maestro-flow 0.4.7 → 0.4.9

package/shared/agent-types.ts

@@ -1,231 +1,237 @@
-// ---------------------------------------------------------------------------
-// Agent type system — protocol abstraction for CLI agent processes
-//
-// CANONICAL source of truth for all agent types. Both the maestro CLI (src/)
-// and dashboard (dashboard/src/) import from this file.
-// ---------------------------------------------------------------------------
-
-/** Supported agent CLI types */
-export type AgentType = 'claude-code' | 'codex' | 'codex-server' | 'gemini' | 'gemini-a2a' | 'qwen' | 'opencode' | 'agent-sdk';
-
-/** Agent process lifecycle status */
-export type AgentProcessStatus =
-  | 'spawning'
-  | 'running'
-  | 'paused'
-  | 'stopping'
-  | 'stopped'
-  | 'error';
-
-// ---------------------------------------------------------------------------
-// Agent configuration & process
-// ---------------------------------------------------------------------------
-
-/** Configuration for spawning an agent process */
-export interface AgentConfig {
-  type: AgentType;
-  prompt: string;
-  workDir: string;
-  env?: Record<string, string>;
-  model?: string;
-  approvalMode?: 'suggest' | 'auto';
-  baseUrl?: string;
-  apiKey?: string;
-  settingsFile?: string;
-  /** Path to .env file for loading environment variables before spawn */
-  envFile?: string;
-  /** When true, spawn in interactive mode (stdin kept open for follow-up messages) */
-  interactive?: boolean;
-  /** Path to MCP config JSON file for CLI agents (claude-code --mcp-config) */
-  mcpConfigPath?: string;
-  /** Opaque metadata bag — used to pass team session context through the spawn pipeline */
-  metadata?: Record<string, unknown>;
-  /** Reasoning effort level (undefined = tool default) */
-  reasoningEffort?: 'low' | 'medium' | 'high' | 'max';
-}
-
-/** Runtime state of a spawned agent process */
-export interface AgentProcess {
-  id: string;
-  type: AgentType;
-  status: AgentProcessStatus;
-  config: AgentConfig;
-  startedAt: string;
-  pid?: number;
-  /** Whether the agent supports interactive follow-up messages */
-  interactive?: boolean;
-  /** Opaque metadata from config — carries team session context etc. */
-  metadata?: Record<string, unknown>;
-}
-
-// ---------------------------------------------------------------------------
-// NormalizedEntry — 11-type discriminated union for unified agent output
-// ---------------------------------------------------------------------------
-
-/** Base fields shared by all normalized entries */
-export interface NormalizedEntryBase {
-  id: string;
-  processId: string;
-  timestamp: string;
-}
-
-/** All possible entry type discriminators */
-export type EntryType =
-  | 'user_message'
-  | 'assistant_message'
-  | 'thinking'
-  | 'tool_use'
-  | 'file_change'
-  | 'command_exec'
-  | 'approval_request'
-  | 'approval_response'
-  | 'error'
-  | 'status_change'
-  | 'token_usage';
-
-// --- Individual entry types ------------------------------------------------
-
-export interface UserMessageEntry extends NormalizedEntryBase {
-  type: 'user_message';
-  content: string;
-}
-
-export interface AssistantMessageEntry extends NormalizedEntryBase {
-  type: 'assistant_message';
-  content: string;
-  partial: boolean;
-}
-
-export interface ThinkingEntry extends NormalizedEntryBase {
-  type: 'thinking';
-  content: string;
-}
-
-export interface ToolUseEntry extends NormalizedEntryBase {
-  type: 'tool_use';
-  name: string;
-  input: Record<string, unknown>;
-  status: 'pending' | 'running' | 'completed' | 'failed';
-  result?: string;
-}
-
-export interface FileChangeEntry extends NormalizedEntryBase {
-  type: 'file_change';
-  path: string;
-  action: 'create' | 'modify' | 'delete';
-  diff?: string;
-}
-
-export interface CommandExecEntry extends NormalizedEntryBase {
-  type: 'command_exec';
-  command: string;
-  exitCode?: number;
-  output?: string;
-}
-
-export interface ApprovalRequestEntry extends NormalizedEntryBase {
-  type: 'approval_request';
-  toolName: string;
-  toolInput: Record<string, unknown>;
-  requestId: string;
-}
-
-export interface ApprovalResponseEntry extends NormalizedEntryBase {
-  type: 'approval_response';
-  requestId: string;
-  allowed: boolean;
-}
-
-export interface ErrorEntry extends NormalizedEntryBase {
-  type: 'error';
-  message: string;
-  code?: string;
-}
-
-export interface StatusChangeEntry extends NormalizedEntryBase {
-  type: 'status_change';
-  status: AgentProcessStatus;
-  reason?: string;
-}
-
-export interface TokenUsageEntry extends NormalizedEntryBase {
-  type: 'token_usage';
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadTokens?: number;
-  cacheWriteTokens?: number;
-}
-
-/** Discriminated union of all 11 normalized entry types */
-export type NormalizedEntry =
-  | UserMessageEntry
-  | AssistantMessageEntry
-  | ThinkingEntry
-  | ToolUseEntry
-  | FileChangeEntry
-  | CommandExecEntry
-  | ApprovalRequestEntry
-  | ApprovalResponseEntry
-  | ErrorEntry
-  | StatusChangeEntry
-  | TokenUsageEntry;
-
-// ---------------------------------------------------------------------------
-// Agent event payload types (used in WS/SSE event envelopes)
-// ---------------------------------------------------------------------------
-
-/** Thought data from agent reasoning */
-export interface ThoughtData {
-  subject: string;
-  description: string;
-}
-
-/** Payload for agent:thought events */
-export interface AgentThoughtPayload {
-  processId: string;
-  thought: ThoughtData;
-}
-
-/** Payload for agent:streaming events */
-export interface AgentStreamingPayload {
-  processId: string;
-  streaming: boolean;
-}
-
-/** Payload for agent:status events */
-export interface AgentStatusPayload {
-  processId: string;
-  status: AgentProcessStatus;
-  reason?: string;
-}
-
-/** Payload for agent:stopped events */
-export interface AgentStoppedPayload {
-  processId: string;
-  reason?: string;
-}
-
-/** Payload for agent:turnCompleted events (codex-server multi-turn) */
-export interface AgentTurnCompletedPayload {
-  processId: string;
-}
-
-// ---------------------------------------------------------------------------
-// Approval workflow types
-// ---------------------------------------------------------------------------
-
-/** Server-side approval request (sent to client for user decision) */
-export interface ApprovalRequest {
-  id: string;
-  processId: string;
-  toolName: string;
-  toolInput: Record<string, unknown>;
-  timestamp: string;
-}
-
-/** Client-side approval decision (sent back to server) */
-export interface ApprovalDecision {
-  id: string;
-  allow: boolean;
-  processId: string;
-}
+// ---------------------------------------------------------------------------
+// Agent type system — protocol abstraction for CLI agent processes
+//
+// CANONICAL source of truth for all agent types. Both the maestro CLI (src/)
+// and dashboard (dashboard/src/) import from this file.
+// ---------------------------------------------------------------------------
+
+/** Supported agent CLI types */
+export type AgentType = 'claude-code' | 'codex' | 'codex-server' | 'gemini' | 'gemini-a2a' | 'qwen' | 'opencode' | 'agy' | 'agent-sdk';
+
+/** Agent process lifecycle status */
+export type AgentProcessStatus =
+  | 'spawning'
+  | 'running'
+  | 'paused'
+  | 'stopping'
+  | 'stopped'
+  | 'error';
+
+// ---------------------------------------------------------------------------
+// Agent configuration & process
+// ---------------------------------------------------------------------------
+
+/** Configuration for spawning an agent process */
+export interface AgentConfig {
+  type: AgentType;
+  prompt: string;
+  workDir: string;
+  env?: Record<string, string>;
+  model?: string;
+  approvalMode?: 'suggest' | 'auto';
+  baseUrl?: string;
+  apiKey?: string;
+  settingsFile?: string;
+  /** Path to .env file for loading environment variables before spawn */
+  envFile?: string;
+  /** When true, spawn in interactive mode (stdin kept open for follow-up messages) */
+  interactive?: boolean;
+  /** Path to MCP config JSON file for CLI agents (claude-code --mcp-config) */
+  mcpConfigPath?: string;
+  /** Opaque metadata bag — used to pass team session context through the spawn pipeline */
+  metadata?: Record<string, unknown>;
+  /** Reasoning effort level (undefined = tool default) */
+  reasoningEffort?: 'low' | 'medium' | 'high' | 'max';
+  /**
+   * Stale-stream silence window in ms before the adapter force-terminates a
+   * silent CLI. Undefined = StreamMonitor default (10 min). Threaded from
+   * `maestro delegate --timeout` / cli-tools.json `streamTimeoutMs`.
+   */
+  streamTimeoutMs?: number;
+}
+
+/** Runtime state of a spawned agent process */
+export interface AgentProcess {
+  id: string;
+  type: AgentType;
+  status: AgentProcessStatus;
+  config: AgentConfig;
+  startedAt: string;
+  pid?: number;
+  /** Whether the agent supports interactive follow-up messages */
+  interactive?: boolean;
+  /** Opaque metadata from config — carries team session context etc. */
+  metadata?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// NormalizedEntry — 11-type discriminated union for unified agent output
+// ---------------------------------------------------------------------------
+
+/** Base fields shared by all normalized entries */
+export interface NormalizedEntryBase {
+  id: string;
+  processId: string;
+  timestamp: string;
+}
+
+/** All possible entry type discriminators */
+export type EntryType =
+  | 'user_message'
+  | 'assistant_message'
+  | 'thinking'
+  | 'tool_use'
+  | 'file_change'
+  | 'command_exec'
+  | 'approval_request'
+  | 'approval_response'
+  | 'error'
+  | 'status_change'
+  | 'token_usage';
+
+// --- Individual entry types ------------------------------------------------
+
+export interface UserMessageEntry extends NormalizedEntryBase {
+  type: 'user_message';
+  content: string;
+}
+
+export interface AssistantMessageEntry extends NormalizedEntryBase {
+  type: 'assistant_message';
+  content: string;
+  partial: boolean;
+}
+
+export interface ThinkingEntry extends NormalizedEntryBase {
+  type: 'thinking';
+  content: string;
+}
+
+export interface ToolUseEntry extends NormalizedEntryBase {
+  type: 'tool_use';
+  name: string;
+  input: Record<string, unknown>;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  result?: string;
+}
+
+export interface FileChangeEntry extends NormalizedEntryBase {
+  type: 'file_change';
+  path: string;
+  action: 'create' | 'modify' | 'delete';
+  diff?: string;
+}
+
+export interface CommandExecEntry extends NormalizedEntryBase {
+  type: 'command_exec';
+  command: string;
+  exitCode?: number;
+  output?: string;
+}
+
+export interface ApprovalRequestEntry extends NormalizedEntryBase {
+  type: 'approval_request';
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  requestId: string;
+}
+
+export interface ApprovalResponseEntry extends NormalizedEntryBase {
+  type: 'approval_response';
+  requestId: string;
+  allowed: boolean;
+}
+
+export interface ErrorEntry extends NormalizedEntryBase {
+  type: 'error';
+  message: string;
+  code?: string;
+}
+
+export interface StatusChangeEntry extends NormalizedEntryBase {
+  type: 'status_change';
+  status: AgentProcessStatus;
+  reason?: string;
+}
+
+export interface TokenUsageEntry extends NormalizedEntryBase {
+  type: 'token_usage';
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+/** Discriminated union of all 11 normalized entry types */
+export type NormalizedEntry =
+  | UserMessageEntry
+  | AssistantMessageEntry
+  | ThinkingEntry
+  | ToolUseEntry
+  | FileChangeEntry
+  | CommandExecEntry
+  | ApprovalRequestEntry
+  | ApprovalResponseEntry
+  | ErrorEntry
+  | StatusChangeEntry
+  | TokenUsageEntry;
+
+// ---------------------------------------------------------------------------
+// Agent event payload types (used in WS/SSE event envelopes)
+// ---------------------------------------------------------------------------
+
+/** Thought data from agent reasoning */
+export interface ThoughtData {
+  subject: string;
+  description: string;
+}
+
+/** Payload for agent:thought events */
+export interface AgentThoughtPayload {
+  processId: string;
+  thought: ThoughtData;
+}
+
+/** Payload for agent:streaming events */
+export interface AgentStreamingPayload {
+  processId: string;
+  streaming: boolean;
+}
+
+/** Payload for agent:status events */
+export interface AgentStatusPayload {
+  processId: string;
+  status: AgentProcessStatus;
+  reason?: string;
+}
+
+/** Payload for agent:stopped events */
+export interface AgentStoppedPayload {
+  processId: string;
+  reason?: string;
+}
+
+/** Payload for agent:turnCompleted events (codex-server multi-turn) */
+export interface AgentTurnCompletedPayload {
+  processId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Approval workflow types
+// ---------------------------------------------------------------------------
+
+/** Server-side approval request (sent to client for user decision) */
+export interface ApprovalRequest {
+  id: string;
+  processId: string;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  timestamp: string;
+}
+
+/** Client-side approval decision (sent back to server) */
+export interface ApprovalDecision {
+  id: string;
+  allow: boolean;
+  processId: string;
+}

package/workflows/agy-instructions.md

@@ -0,0 +1,124 @@
+# Maestro for Antigravity CLI
+
+Workflow orchestration CLI with MCP endpoint support and extensible architecture, adapted for Antigravity CLI tooling.
+
+- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
+
+## Delegate & CLI
+
+- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+**Strictly follow the cli-tools.json configuration**
+
+Available CLI endpoints are dynamically defined by the config file. Use `maestro delegate --to agy` to dispatch tasks to the Antigravity CLI.
+
+## Antigravity Tool Priority
+
+When choosing between equivalent tools, prefer the agy native primitives over shell fallbacks:
+
+| Need | Prefer | Fallback |
+|------|--------|----------|
+| Read a file | `view_file(AbsolutePath, StartLine, EndLine)` | `run_command("Get-Content ...")` |
+| Read external URL | `read_url_content(Url)` | `run_command("curl ...")` |
+| Create / overwrite file | `write_to_file(TargetFile, CodeContent, Overwrite)` | n/a |
+| Single-block edit | `replace_file_content(TargetFile, StartLine, EndLine, TargetContent, ReplacementContent)` | n/a |
+| Multi-block edit on same file | `multi_replace_file_content(TargetFile, ReplacementChunks=[...])` | repeated `replace_file_content` |
+| Search text | `grep_search(SearchPath, Query, IsRegex, Includes)` | `run_command("rg ...")` |
+| List directory | `list_dir(DirectoryPath)` | `run_command("ls ...")` |
+| Execute shell | `run_command(CommandLine, Cwd, WaitMsBeforeAsync)` | n/a |
+| Web search | `search_web(query, domain)` | n/a |
+| Ask user | `ask_question(questions=[{question, options, is_multi_select}])` | n/a |
+
+Always pass `Cwd` to `run_command`; do not rely on inherited shell cwd. On Windows, set UTF-8 in PowerShell before chained commands:
+
+```powershell
+[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+chcp 65001 > $null
+```
+
+## Sub-Agent Orchestration (Two Phases)
+
+Antigravity uses an explicit two-phase model for sub-agents — unlike Claude's single `Agent(...)` call:
+
+1. **Define**: declare the sub-agent type once per session (idempotent within a session)
+   ```
+   define_subagent(
+     name="team-worker",
+     description="Generic role-spec worker",
+     system_prompt="<contents of antigravity-cli/agents/team-worker.md>",
+     enable_write_tools=true,
+     enable_mcp_tools=true,
+     enable_subagent_tools=false
+   )
+   ```
+
+2. **Invoke**: spawn one or more instances; capture the returned ConversationId for later messaging
+   ```
+   invoke_subagent([
+     { TypeName: "team-worker",
+       Role:     "<concrete role label>",
+       Prompt:   "<task-specific instructions>",
+       Workspace: "inherit"            # inherit | branch | share
+     }
+   ])
+   ```
+
+**Workspace modes**:
+- `inherit` — share the parent's working directory (default; matches Claude semantics)
+- `branch` — independent filesystem branch (useful for parallel waves that must not collide)
+- `share` — explicit cross-worker sharing (rare; use only when workers must atomically see each other's writes)
+
+**Inter-agent messaging**: `send_message(Recipient=<ConversationId>, Message=<text>)`. The Recipient must be a ConversationId returned by `invoke_subagent`, never a role name.
+
+**Background OS tasks vs sub-agents**: `manage_task` handles `run_command` async instances (list / kill / status / send_input). Do **not** repurpose it for named task tracking — use `.workflow/tasks/<id>.json` files instead.
+
+## Cross-Skill Invocation
+
+Agent-internal chaining uses the **inline-execute** pattern:
+
+```
+view_file(AbsolutePath="<agy-skills-dir>/<target-skill>/SKILL.md") + execute inline (args: "...")
+```
+
+`<agy-skills-dir>` resolves to:
+- global install: `~/.gemini/antigravity-cli/skills/`
+- workspace install: `<project>/.agents/skills/`
+
+The agent reads the target SKILL.md, treats its body as additional instructions, and executes them in the same conversation context. Args are passed conceptually as input variables — substitute them when running the loaded instructions.
+
+User-initiated invocation uses `/skills`.
+
+## Cross-Worker Coordination
+
+Antigravity has no built-in message bus. For shared logs across workers, write JSONL lines to `.workflow/.team/<session>/.msg/messages.jsonl`:
+
+- Log:   `write_to_file(TargetFile=".workflow/.team/<session>/.msg/messages.jsonl", CodeContent="<json line>\n", Overwrite=false)`
+- Read:  `view_file(AbsolutePath=".workflow/.team/<session>/.msg/messages.jsonl")` then filter client-side
+- Status snapshot: write `<session>/.msg/state.json` and read with `view_file`
+
+For point-to-point delivery, use `send_message` directly.
+
+## Code Diagnostics
+
+- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation when the MCP channel is available.
+
+## Knowledge System
+
+### Search — Query Before Acting
+
+When tackling unfamiliar domains or cross-cutting concerns, search existing knowledge first:
+- `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
+- `maestro spec load --keyword <kw>` — cross-category keyword match
+- `maestro wiki search "<query>"` — full-text search across all knowhow
+- `maestro wiki list --category <cat>` → `maestro wiki load <id>` — browse then load full detail
+
+### Record — Capture Knowledge
+
+When execution surfaces non-obvious knowledge (decisions, root causes, pitfalls, patterns), persist it:
+
+- **Spec entry** (short rule/constraint) → `/spec-add <category> "title" "content" --keywords kw1,kw2`
+- **Knowhow document** (detailed recipe/template/decision/reference) → `/manage-knowhow-capture`
+
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, test strategy→`test`.