feat: add GitHub Copilot CLI as first-class agent

[dwizzzle]

Summary

Adds \copilot-cli\ as a first-class agent in Maestro, on par with Claude Code, Codex, OpenCode, and Factory Droid.

What's included

Core integration (8 modified files, 2 new files):

• Agent ID, definition, capabilities, display name, beta badge, context window
• CLI args: -p\ (batch), --output-format json, --resume, --allow-all, --model\
• Config options for model selection and context window size

Output parser — verified against actual Copilot CLI JSONL output:

• 11 event types: \session.*, \�ssistant.message_delta, \�ssistant.message, \ ool.execution_start/complete,
  esult\
• Streaming text display, tool use tracking, session ID extraction, output token accumulation

Session storage browser — reads ~/.copilot/session-state//:

• Parses \workspace.yaml\ for metadata (summary, cwd, timestamps)
• Reads \�vents.jsonl\ for message history
• Supports pagination, search, and project path filtering

Error patterns — auth failures, rate limiting, network errors, token exhaustion

UI — Added to \SUPPORTED_AGENTS\ and wizard agent tiles (no more 'Coming Soon')

Testing

• TypeScript compiles cleanly across all 3 configs
• Maestro launches, detects \copilot\ binary, registers parser
• Ran \copilot -p ... --output-format json\ to verify JSONL schema matches parser

Follow-up (Phase 2)

\docs/Copilot-CLI-Phase2-Plan.md\ covers remaining parity items: read-only mode, wizard, group chat moderation.

[greptile-apps]

Greptile Summary

This PR integrates GitHub Copilot CLI (copilot) as a first-class agent in Maestro, following the established patterns used by Claude Code, Codex, OpenCode, and Factory Droid. The integration spans all required layers: agent ID/definition/capabilities, a JSONL output parser, a session storage browser, error-pattern matching, and UI registration (wizard tile + SUPPORTED_AGENTS). A Phase 2 roadmap document is included for future parity work.

Key changes:

• src/main/parsers/copilot-cli-output-parser.ts — New parser handling 11 Copilot CLI JSONL event types; contains two bugs around accumulatedOutputTokens never resetting between sessions and tokens being silently dropped when the result event lacks a usage field.
• src/main/storage/copilot-cli-session-storage.ts — New session storage reading ~/.copilot/session-state/<uuid>/; unvalidated sessionId in public methods creates a path traversal risk.
• src/main/agents/capabilities.ts — Capability flags for Copilot CLI; supportsSessionStorage and supportsResultMessages are set true but the Phase 2 plan parity matrix marks both as Phase 1 unsupported.
• All shared/registry wiring (agent IDs, metadata, constants, parser index, storage index) is clean and consistent with existing agent patterns.

Confidence Score: 4/5

Safe to merge after fixing the two P1 token-accumulation bugs in the output parser.

Two P1 issues exist in the new output parser: accumulatedOutputTokens is never reset between sessions (singleton parser instance), and the accumulated token count is silently discarded when the result event has no usage field. Both produce incorrect usage stats from the second session onward. The session storage and UI changes are clean. Fixing the two accumulator issues is straightforward and does not require architectural changes.

src/main/parsers/copilot-cli-output-parser.ts — token accumulator reset and unconditional usage reporting; src/main/storage/copilot-cli-session-storage.ts — sessionId validation before path join.

Important Files Changed

Filename	Overview
src/main/parsers/copilot-cli-output-parser.ts	New JSONL parser for Copilot CLI; two bugs: accumulatedOutputTokens never resets between sessions (singleton parser), and accumulated tokens are silently discarded when the result event lacks a usage field.
src/main/storage/copilot-cli-session-storage.ts	New session storage reading ~/.copilot/session-state/; logic is solid but readSessionMessages/getSessionPath accept an unvalidated sessionId that is directly concatenated into a file path, enabling potential path traversal.
src/main/agents/capabilities.ts	Copilot CLI capability block added; supportsSessionStorage and supportsResultMessages are both set true but the Phase 2 plan parity matrix marks both as Phase 1 unsupported, requiring clarification.
src/main/agents/definitions.ts	Copilot CLI agent definition added with correct CLI flags (-p, --output-format json, --resume, --allow-all, --model) and UI config options for model and context window.
src/main/parsers/error-patterns.ts	Copilot CLI error patterns added covering auth failures, rate limiting, network errors, and token exhaustion; patterns are reasonable and registered correctly.
src/renderer/components/Wizard/screens/AgentSelectionScreen.tsx	Copilot CLI tile added to the wizard; GRID_ROWS bumped to 3 for 7 items (correct), but the constant is hardcoded rather than derived from tile count.
docs/Copilot-CLI-Phase2-Plan.md	Phase 2 roadmap doc; useful, but the parity matrix is already stale — session storage shipped in this PR but is still shown as Phase 1 unsupported.

Sequence Diagram

sequenceDiagram
    participant UI as Renderer (UI)
    participant Main as Main Process
    participant Parser as CopilotCliOutputParser
    participant Storage as CopilotCliSessionStorage
    participant CLI as copilot binary

    UI->>Main: Launch agent (copilot -p "..." --output-format json --allow-all)
    Main->>CLI: spawn()

    CLI-->>Parser: session.tools_updated (JSONL)
    Parser-->>Main: ParsedEvent { type: 'init' }

    CLI-->>Parser: assistant.message_delta (streaming)
    Parser-->>Main: ParsedEvent { type: 'text', isPartial: true }

    CLI-->>Parser: assistant.message (with toolRequests)
    Parser-->>Main: ParsedEvent { type: 'tool_use' }

    CLI-->>Parser: tool.execution_start / tool.execution_complete
    Parser-->>Main: ParsedEvent { type: 'tool_use', toolState }

    CLI-->>Parser: assistant.message (text only)
    Parser-->>Main: ParsedEvent { type: 'result', text }
    Note over Parser: accumulatedOutputTokens += outputTokens

    CLI-->>Parser: result (sessionId, usage)
    Parser-->>Main: ParsedEvent { type: 'usage', sessionId, usage }
    Note over Parser: ⚠ tokens not reset after this point

    Main->>UI: Session complete, sessionId stored

    UI->>Main: Browse past sessions
    Main->>Storage: listSessions(projectPath)
    Storage->>Storage: readdir ~/.copilot/session-state/
    Storage->>Storage: parseWorkspaceYaml per UUID dir
    Storage-->>Main: AgentSessionInfo[]
    Main-->>UI: Session list

    UI->>Main: Resume session (--resume SESSION-ID)
    Main->>CLI: spawn with resumeArgs

Loading

Comments Outside Diff (2)

1. src/main/storage/copilot-cli-session-storage.ts, line 1304-1311 (link)

   sessionId not validated before path construction

   readSessionMessages (and getSessionPath, getSearchableMessages) construct a file path by directly concatenating the caller-supplied sessionId into the session base directory:

   const sessionDir = path.join(getCopilotSessionDir(), sessionId);

   If sessionId contains path traversal sequences (e.g. ../../../etc/passwd), path.join will resolve them and the code will attempt to read files outside ~/.copilot/session-state/. listSessions generates clean UUIDs from directory reads, but readSessionMessages is a public interface that accepts arbitrary strings. Adding a UUID-format guard before path construction would eliminate this risk:

   if (!/^[0-9a-f-]{36}$/i.test(sessionId)) {
       return { messages: [], total: 0, hasMore: false };
   }

2. src/renderer/components/Wizard/screens/AgentSelectionScreen.tsx, line 1476-1478 (link)

   Hardcoded GRID_ROWS will need manual bumping for future agents

   The change from GRID_ROWS = 2 to GRID_ROWS = 3 is correct for 7 items, but this constant will need to be bumped again when a future tile is added. Consider deriving it programmatically:

   const GRID_ROWS = Math.ceil(AGENT_TILES.length / GRID_COLS);

_{Reviews (1): Last reviewed commit: "feat: add GitHub Copilot CLI as first-cl..." | Re-trigger Greptile}

[greptile-apps]

accumulatedOutputTokens never resets between sessions

CopilotCliOutputParser is registered as a singleton (one instance for the lifetime of the process). The accumulatedOutputTokens field is never reset, so after the first Copilot CLI session ends and a second session starts, the token count from session 1 will be added to session 2's tally. Every subsequent session will report an inflated (and incorrect) output-token count.

Other parsers avoid this by reading token values directly from each event rather than accumulating across sessions. The fix is to reset the counter when the top-level result event is emitted:

case 'result': {
    const event: ParsedEvent = {
        type: 'usage',
        sessionId: msg.sessionId,
        raw: msg,
    };

    event.usage = {
        inputTokens: 0,
        outputTokens: this.accumulatedOutputTokens,
    };

    // Reset for next session
    this.accumulatedOutputTokens = 0;

    return event;
}

[greptile-apps]

Accumulated tokens silently dropped when result event has no usage field

accumulatedOutputTokens is only written into event.usage when msg.usage is truthy. If the result event is missing the top-level usage object (network truncation, CLI version difference, empty session, etc.), the entire per-turn accumulation is discarded and the caller receives a ParsedEvent with type: 'usage' but no event.usage set.

Because extractUsage returns event.usage || null, the caller will receive null, meaning all output-token data for the session is silently lost. Report the accumulated tokens unconditionally:

case 'result': {
    const event: ParsedEvent = {
        type: 'usage',
        sessionId: msg.sessionId,
        raw: msg,
    };

    // Report accumulated output tokens regardless of whether msg.usage exists
    event.usage = {
        inputTokens: 0,
        outputTokens: this.accumulatedOutputTokens,
    };

    this.accumulatedOutputTokens = 0;
    return event;
}

[greptile-apps]

Capabilities contradict the Phase 2 parity matrix

supportsSessionStorage: true and supportsResultMessages: true are set here, but the parity matrix in docs/Copilot-CLI-Phase2-Plan.md explicitly marks both as ❌ for "Copilot CLI (Phase 1)".

supportsSessionStorage is fine because CopilotCliSessionStorage is actually implemented in this PR — the plan doc is simply stale on that point. However supportsResultMessages needs a second look: the plan doc marks it as unsupported in Phase 1 and lists it as a Phase 2 TODO. If it truly is unsupported, the flag should remain false to avoid enabling Auto Run prematurely. If it is supported as implemented, the plan doc should be updated to reflect that.

[nolanmclark]

Had a similar PR if you wanted to build on it or take anything from it. :) #566

[dwizzzle]

Review Feedback Addressed (commit 05ae36d)

Thanks for the thorough review. All 5 issues fixed:

P1 - Token accumulator bugs (both fixed)

1. accumulatedOutputTokens never resets - Now resets to 0 after the result event. The parser is a singleton so this was carrying tokens across sessions.

2. Tokens silently dropped when result has no usage field - Usage stats are now reported unconditionally on result, regardless of whether msg.usage exists.

P2 - Session storage, docs, UI (all fixed)

3. Path traversal in session storage - Added UUID format validation to readSessionMessages, getSessionPath, and getSearchableMessages before path construction.

4. Capabilities vs Phase 2 parity matrix - Updated docs/Copilot-CLI-Phase2-Plan.md to mark session storage, result messages, and usage stats as shipped.

5. Hardcoded GRID_ROWS - Changed to Math.ceil(AGENT_TILES.length / GRID_COLS) so it auto-adjusts when future agents are added.

Tests updated to cover token reset behavior and unconditional usage reporting. All 41 tests pass.

[pedramamini]

@coderabbitai analyze this PR