From 2be8b5987d3e3d92385e1926300974dd136c9bd5 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Tue, 16 Dec 2025 21:50:19 -0600 Subject: [PATCH] MAESTRO: Implement Phase 8.2 - Update documentation for multi-provider architecture - CLAUDE.md: Added agent capabilities section, updated architecture diagram with parsers/ and storage/ directories, added agentSessions and agentError APIs, updated key files table, added error fields to Session interface - AGENT_SUPPORT.md: Added multi-provider architecture status section showing all 7 completed components, updated supported agents reference with implementation status and detailed checklist for planned agents - CONTRIBUTING.md: Updated supported agents reference table with status column and link to detailed guide --- AGENT_SUPPORT.md | 75 ++++++++++++++++++++++++++++++++++++++++++------ CLAUDE.md | 51 ++++++++++++++++++++++++++++---- CONTRIBUTING.md | 14 +++++---- 3 files changed, 121 insertions(+), 19 deletions(-) diff --git a/AGENT_SUPPORT.md b/AGENT_SUPPORT.md index c4cb68f8..f9270f33 100644 --- a/AGENT_SUPPORT.md +++ b/AGENT_SUPPORT.md @@ -2,6 +2,35 @@ This guide explains how to add support for a new AI coding agent (provider) in Maestro. It covers the architecture, required implementations, and step-by-step instructions. +## Multi-Provider Architecture Status + +**Status:** ✅ Foundation Complete (2025-12-16) + +The multi-provider refactoring has established the pluggable architecture for supporting multiple AI agents: + +| Component | Status | Description | +|-----------|--------|-------------| +| Capability System | ✅ Complete | `AgentCapabilities` interface, capability gating in UI | +| Generic Identifiers | ✅ Complete | `claudeSessionId` → `agentSessionId` across 47+ files | +| Session Storage | ✅ Complete | `AgentSessionStorage` interface, Claude + OpenCode implementations | +| Output Parsers | ✅ Complete | `AgentOutputParser` interface, Claude + OpenCode parsers | +| Error Handling | ✅ Complete | `AgentError` types, detection patterns, recovery UI | +| IPC API | ✅ Complete | `window.maestro.agentSessions.*` replaces `claude.*` | +| UI Capability Gates | ✅ Complete | Features hidden/shown based on agent capabilities | + +### Adding a New Agent + +To add support for a new agent (e.g., Gemini CLI, Codex), follow these steps: + +1. Add agent definition to `src/main/agent-detector.ts` +2. Define capabilities in `src/main/agent-capabilities.ts` +3. Create output parser in `src/main/parsers/{agent}-output-parser.ts` +4. Register parser in `src/main/parsers/index.ts` +5. (Optional) Create session storage in `src/main/storage/{agent}-session-storage.ts` +6. (Optional) Add error patterns to `src/main/parsers/error-patterns.ts` + +See detailed instructions below. + ## Table of Contents - [Vernacular](#vernacular) @@ -511,7 +540,7 @@ describe('YourAgentOutputParser', () => { ## Supported Agents Reference -### Claude Code +### Claude Code ✅ Fully Implemented | Aspect | Value | |--------|-------| @@ -522,6 +551,12 @@ describe('YourAgentOutputParser', () => { | Session ID Field | `session_id` (snake_case) | | Session Storage | `~/.claude/projects//` | +**Implementation Status:** +- ✅ Output Parser: `src/main/parsers/claude-output-parser.ts` +- ✅ Session Storage: `src/main/storage/claude-session-storage.ts` +- ✅ Error Patterns: `src/main/parsers/error-patterns.ts` +- ✅ All capabilities enabled + **JSON Event Types:** - `system` (init) → session_id, slash_commands - `assistant` → streaming content @@ -529,7 +564,7 @@ describe('YourAgentOutputParser', () => { --- -### OpenCode +### OpenCode 🔄 Stub Ready | Aspect | Value | |--------|-------| @@ -540,6 +575,12 @@ describe('YourAgentOutputParser', () => { | Session ID Field | `sessionID` (camelCase) | | Session Storage | Server-managed | +**Implementation Status:** +- ✅ Output Parser: `src/main/parsers/opencode-output-parser.ts` (based on expected format) +- ✅ Session Storage: `src/main/storage/opencode-session-storage.ts` (stub, returns empty results) +- ⏳ Error Patterns: Placeholder, needs real-world testing +- ⏳ Capabilities: Set to minimal defaults + **JSON Event Types:** - `step_start` → session start - `text` → streaming content @@ -548,18 +589,36 @@ describe('YourAgentOutputParser', () => { --- -### Gemini CLI (Planned) +### Gemini CLI 📋 Planned -Status: Not yet implemented +**Status:** Not yet implemented + +**To Add:** +1. Agent definition in `agent-detector.ts` +2. Capabilities in `agent-capabilities.ts` +3. Output parser for Gemini JSON format +4. Error patterns for Google API errors --- -### Codex (Planned) +### Codex 📋 Planned -Status: Not yet implemented +**Status:** Not yet implemented + +**To Add:** +1. Agent definition in `agent-detector.ts` +2. Capabilities in `agent-capabilities.ts` +3. Output parser for Codex JSON format +4. Error patterns for OpenAI API errors --- -### Qwen3 Coder (Planned) +### Qwen3 Coder 📋 Planned -Status: Not yet implemented +**Status:** Not yet implemented + +**To Add:** +1. Agent definition in `agent-detector.ts` +2. Capabilities in `agent-capabilities.ts` (likely local model, no cost tracking) +3. Output parser for Qwen JSON format +4. Error patterns (likely minimal for local models) diff --git a/CLAUDE.md b/CLAUDE.md index 073c7c66..293c9f74 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,16 @@ src/ │ ├── process-manager.ts # Process spawning (PTY + child_process) │ ├── preload.ts # Secure IPC bridge │ ├── agent-detector.ts # Agent detection and configuration +│ ├── agent-capabilities.ts # Agent capability definitions +│ ├── agent-session-storage.ts # Session storage interface +│ ├── parsers/ # Agent output parsers +│ │ ├── agent-output-parser.ts # Parser interface +│ │ ├── claude-output-parser.ts # Claude Code parser +│ │ ├── opencode-output-parser.ts # OpenCode parser +│ │ └── error-patterns.ts # Error detection patterns +│ ├── storage/ # Session storage implementations +│ │ ├── claude-session-storage.ts +│ │ └── opencode-session-storage.ts │ ├── tunnel-manager.ts # Cloudflare tunnel support │ ├── web-server.ts # Fastify server for web/mobile interface │ └── utils/execFile.ts # Safe command execution @@ -91,7 +101,10 @@ src/ | Add template variable | `src/shared/templateVariables.ts`, `src/renderer/utils/templateVariables.ts` | | Modify system prompts | `src/prompts/*.md` (wizard, Auto Run, etc.) | | Add CLI command | `src/cli/commands/`, `src/cli/index.ts` | -| Configure agent | `src/main/agent-detector.ts` | +| Configure agent | `src/main/agent-detector.ts`, `src/main/agent-capabilities.ts` | +| Add agent output parser | `src/main/parsers/`, `src/main/parsers/index.ts` | +| Add agent session storage | `src/main/storage/`, `src/main/agent-session-storage.ts` | +| Add agent error patterns | `src/main/parsers/error-patterns.ts` | | Add playbook feature | `src/cli/services/playbooks.ts` | | Modify wizard flow | `src/renderer/components/Wizard/` (see Onboarding Wizard section) | | Add tour step | `src/renderer/components/Wizard/tour/tourSteps.ts` | @@ -309,6 +322,10 @@ interface Session { // Command History aiCommandHistory?: string[]; // AI input history shellCommandHistory?: string[]; // Terminal input history + + // Error Handling (NEW) + agentError?: AgentError; // Current agent error (auth, tokens, rate limit, etc.) + agentErrorPaused?: boolean; // Input blocked while error modal shown } interface AITab { @@ -334,9 +351,11 @@ The `window.maestro` API exposes: - `shells` - Detect available shells - `logger` - System logging -### Agent & Claude -- `agents` - Detect, get, config, refresh, custom paths -- `claude` - List/read/search Claude Code sessions, global stats +### Agent & Agent Sessions +- `agents` - Detect, get, config, refresh, custom paths, getCapabilities +- `agentSessions` - Generic agent session storage API (list, read, search, delete) +- `agentError` - Agent error handling (clearError, retryAfterError) +- `claude` - (Deprecated) Claude Code sessions - use `agentSessions` instead ### Git Integration - `git` - Status, diff, isRepo, numstat, branches, tags, info @@ -389,12 +408,34 @@ window.maestro.history = { | ID | Name | Status | Notes | |----|------|--------|-------| | `claude-code` | Claude Code | Active | Primary agent, uses `--print --verbose --output-format stream-json` | +| `opencode` | OpenCode | Stub | Output parser implemented, session storage stub ready | | `terminal` | Terminal | Internal | Hidden from UI, used for shell sessions | | `openai-codex` | OpenAI Codex | Planned | Coming soon | | `gemini-cli` | Gemini CLI | Planned | Coming soon | | `qwen3-coder` | Qwen3 Coder | Planned | Coming soon | -Additional `ToolType` values (`aider`, `opencode`, `claude`) are defined in types but not yet implemented in `agent-detector.ts`. +Additional `ToolType` values (`aider`, `claude`) are defined in types but not yet implemented in `agent-detector.ts`. + +### Agent Capabilities + +Each agent declares capabilities that control UI feature availability. See `src/main/agent-capabilities.ts` for the full interface. + +| Capability | Description | UI Feature Controlled | +|------------|-------------|----------------------| +| `supportsResume` | Can resume previous sessions | Resume button | +| `supportsReadOnlyMode` | Has plan/read-only mode | Read-only toggle | +| `supportsJsonOutput` | Emits structured JSON | Output parsing | +| `supportsSessionId` | Emits session ID | Session ID pill | +| `supportsImageInput` | Accepts image attachments | Attach image button | +| `supportsSlashCommands` | Has discoverable commands | Slash autocomplete | +| `supportsSessionStorage` | Persists browsable sessions | Sessions browser | +| `supportsCostTracking` | Reports token costs | Cost widget | +| `supportsUsageStats` | Reports token counts | Context window widget | +| `supportsBatchMode` | Runs per-message | Batch processing | +| `supportsStreaming` | Streams output | Real-time display | +| `supportsResultMessages` | Distinguishes final result | Message classification | + +For detailed agent integration guide, see [AGENT_SUPPORT.md](AGENT_SUPPORT.md). ## Onboarding Wizard diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32a004a9..2deb3e0d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -425,12 +425,14 @@ Based on capabilities, these UI features are automatically enabled/disabled: ### Supported Agents Reference -| Agent | Resume | Read-Only | JSON | Images | Sessions | Cost | -|-------|--------|-----------|------|--------|----------|------| -| Claude Code | ✅ `--resume` | ✅ `--permission-mode plan` | ✅ | ✅ | ✅ `~/.claude/` | ✅ | -| OpenCode | ✅ `--session` | ✅ `--agent plan` | ✅ | ✅ | TBD | ❌ (local) | -| Gemini CLI | TBD | TBD | TBD | TBD | TBD | ✅ | -| Codex | TBD | TBD | TBD | TBD | TBD | ✅ | +| Agent | Resume | Read-Only | JSON | Images | Sessions | Cost | Status | +|-------|--------|-----------|------|--------|----------|------|--------| +| Claude Code | ✅ `--resume` | ✅ `--permission-mode plan` | ✅ | ✅ | ✅ `~/.claude/` | ✅ | ✅ Complete | +| OpenCode | ✅ `--session` | ✅ `--agent plan` | ✅ | ✅ | Stub | ❌ (local) | 🔄 Stub Ready | +| Gemini CLI | TBD | TBD | TBD | TBD | TBD | ✅ | 📋 Planned | +| Codex | TBD | TBD | TBD | TBD | TBD | ✅ | 📋 Planned | + +For detailed implementation guide, see [AGENT_SUPPORT.md](AGENT_SUPPORT.md). ## Code Style