maestro-flow 0.1.3 → 0.2.0

package/package.json

@@ -1,58 +1,78 @@
-{
-  "name": "maestro-flow",
-  "version": "0.1.3",
-  "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
-  "type": "module",
-  "bin": {
-    "maestro": "bin/maestro.js",
-    "maestro-statusline": "bin/maestro-statusline.js",
-    "maestro-context-monitor": "bin/maestro-context-monitor.js"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "bin",
-    "dist",
-    "templates",
-    "workflows",
-    "chains",
-    ".claude/commands",
-    ".claude/agents",
-    ".claude/skills",
-    ".claude/CLAUDE.md",
-    ".codex/skills",
-    "dashboard/dist",
-    "dashboard/dist-server",
-    "dashboard/package.json"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node bin/maestro.js",
-    "mcp": "node bin/maestro-mcp.js",
-    "lint": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.77",
-    "@hono/node-server": "^1.14.0",
-    "@inquirer/prompts": "^8.3.2",
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "chokidar": "^4.0.0",
-    "commander": "^13.1.0",
-    "hono": "^4.7.0",
-    "node-cron": "^4.2.1",
-    "ws": "^8.19.0",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.7.0"
-  },
-  "license": "MIT"
-}
+{
+  "name": "maestro-flow",
+  "version": "0.2.0",
+  "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
+  "type": "module",
+  "imports": {
+    "#maestro-dashboard/agents/*": "./dashboard/dist-server/dashboard/src/server/agents/*",
+    "#maestro-dashboard/shared/*": "./dashboard/dist-server/dashboard/src/shared/*",
+    "#maestro-dashboard/wiki/*": "./dashboard/dist-server/dashboard/src/server/wiki/*"
+  },
+  "bin": {
+    "maestro": "bin/maestro.js",
+    "maestro-statusline": "bin/maestro-statusline.js",
+    "maestro-context-monitor": "bin/maestro-context-monitor.js"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "bin",
+    "dist",
+    "shared",
+    "templates",
+    "workflows",
+    "chains",
+    ".claude/commands",
+    ".claude/agents",
+    ".claude/skills",
+    ".claude/CLAUDE.md",
+    ".codex/skills",
+    "dashboard/dist",
+    "dashboard/dist-server",
+    "dashboard/tui/dist",
+    "dashboard/package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node bin/maestro.js",
+    "mcp": "node bin/maestro-mcp.js",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.77",
+    "@hono/node-server": "^1.14.0",
+    "@inkjs/ui": "^2.0.0",
+    "@inquirer/prompts": "^8.3.2",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "argon2": "^0.44.0",
+    "chokidar": "^4.0.0",
+    "commander": "^13.1.0",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.7.0",
+    "ink": "^6.0.0",
+    "ink-big-text": "^2.0.0",
+    "ink-gradient": "^4.0.0",
+    "ink-spinner": "^5.0.0",
+    "marked": "^15.0.0",
+    "node-cron": "^4.2.1",
+    "pg": "^8.20.0",
+    "react": "^19.0.0",
+    "ws": "^8.19.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.20.0",
+    "@types/react": "^19.2.14",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.4"
+  },
+  "license": "MIT"
+}

package/shared/agent-types.ts

@@ -0,0 +1,223 @@
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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/templates/cli/prompts/coordinate-step-v2.md

@@ -1,38 +1,57 @@
-# Coordinate Step {{STEP_N}} — {{GRAPH_NAME}}
-
-## Command
-{{COMMAND}}
-
-{{#AUTO_DIRECTIVE}}
-**Mode:** {{AUTO_DIRECTIVE}}
-{{/AUTO_DIRECTIVE}}
-
-{{#PREVIOUS_CONTEXT}}
-## Context from Previous Step
-{{PREVIOUS_CONTEXT}}
-{{/PREVIOUS_CONTEXT}}
-
-{{#STATE_SNAPSHOT}}
-## Current State
-{{STATE_SNAPSHOT}}
-{{/STATE_SNAPSHOT}}
-
-{{#INTENT}}
-## Original Intent
-{{INTENT}}
-{{/INTENT}}
-
-## Return Format
-
-Output MUST end with this exact block:
-
-```
---- COORDINATE RESULT ---
-STATUS: <SUCCESS or FAILURE>
-PHASE: <number, or "none">
-VERIFICATION_STATUS: <passed or failed or pending, if applicable>
-REVIEW_VERDICT: <PASS or WARN or BLOCK, if applicable>
-UAT_STATUS: <passed or failed or pending, if applicable>
-ARTIFACTS: <comma-separated file paths, or "none">
-SUMMARY: <one-line what was accomplished>
-```
+# Coordinate Step {{STEP_N}} — {{GRAPH_NAME}}
+
+## Command
+{{COMMAND}}
+
+{{#AUTO_DIRECTIVE}}
+**Mode:** {{AUTO_DIRECTIVE}}
+{{/AUTO_DIRECTIVE}}
+
+{{#PREVIOUS_CONTEXT}}
+## Context from Previous Step
+{{PREVIOUS_CONTEXT}}
+{{/PREVIOUS_CONTEXT}}
+
+{{#STATE_SNAPSHOT}}
+## Current State
+{{STATE_SNAPSHOT}}
+{{/STATE_SNAPSHOT}}
+
+{{#INTENT}}
+## Original Intent
+{{INTENT}}
+{{/INTENT}}
+
+## Report Status (Required)
+
+Before finishing, run exactly this command (substitute values based on what
+you accomplished). This is the ONLY way the coordinator learns your result —
+text output alone is not read.
+
+```
+maestro coordinate report \
+  --session {{SESSION_ID}} \
+  --node {{NODE_ID}} \
+  --status <SUCCESS|FAILURE> \
+  [--verification <passed|failed|pending>] \
+  [--review <PASS|WARN|BLOCK>] \
+  [--uat <passed|failed|pending>] \
+  [--phase <number>] \
+  [--artifact <path>] [--artifact <path>] \
+  [--summary "<one-line what was accomplished>"]
+```
+
+Legacy fallback (only if the report command is unavailable): append this
+block at the end of your output. The coordinator will parse it as a
+last-resort contract.
+
+```
+--- COORDINATE RESULT ---
+STATUS: <SUCCESS or FAILURE>
+PHASE: <number, or "none">
+VERIFICATION_STATUS: <passed or failed or pending, if applicable>
+REVIEW_VERDICT: <PASS or WARN or BLOCK, if applicable>
+UAT_STATUS: <passed or failed or pending, if applicable>
+ARTIFACTS: <comma-separated file paths, or "none">
+SUMMARY: <one-line what was accomplished>
+```

package/templates/state.json

@@ -23,6 +23,7 @@
       }
     ]
   },
+  "transition_history": [],
   "milestone_history": [
     {
       "name": "{{MILESTONE_NAME}}",