maestro-flow 0.1.0

package/dashboard/dist-server/shared/agent-types.d.ts

@@ -0,0 +1,143 @@
+/** Supported agent CLI types */
+export type AgentType = 'claude-code' | 'codex' | 'codex-server' | 'gemini' | 'qwen' | 'opencode' | 'agent-sdk';
+/** Agent process lifecycle status */
+export type AgentProcessStatus = 'spawning' | 'running' | 'paused' | 'stopping' | 'stopped' | 'error';
+/** 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;
+}
+/** 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;
+}
+/** 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';
+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;
+/** 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;
+}
+/** 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/dashboard/dist-server/shared/agent-types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// Agent type system — protocol abstraction for CLI agent processes
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=agent-types.js.map

package/dashboard/dist-server/shared/agent-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../../src/shared/agent-types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E"}

package/dashboard/dist-server/shared/commander-types.d.ts

@@ -0,0 +1,86 @@
+import type { AgentType } from './agent-types.js';
+import type { WorkspacePolicy } from './execution-types.js';
+export interface CommanderSafetyConfig {
+    /** Event debounce interval (ms) */
+    eventDebounceMs: number;
+    /** Auto-pause after N consecutive failures */
+    circuitBreakerThreshold: number;
+    /** Max ticks per hour (prevent runaway loops) */
+    maxTicksPerHour: number;
+    /** Max token budget per hour */
+    maxTokensPerHour: number;
+    /** File globs that Commander must not operate on */
+    protectedPaths: string[];
+}
+export interface CommanderConfig {
+    /** Tick interval (ms). Lower = more aggressive */
+    pollIntervalMs: number;
+    /** Maximum concurrent worker agents */
+    maxConcurrentWorkers: number;
+    /** Worker timeout (ms), marks stalled after this */
+    stallTimeoutMs: number;
+    /** Max retries per issue */
+    maxRetries: number;
+    /** Retry backoff interval (ms) */
+    retryBackoffMs: number;
+    /** Model used for assessment queries */
+    decisionModel: 'haiku' | 'sonnet' | 'opus';
+    /** Max exploration turns for assessment */
+    assessMaxTurns: number;
+    /** Auto-approve risk threshold: low=only low risk, medium=incl medium, high=fully auto */
+    autoApproveThreshold: 'low' | 'medium' | 'high';
+    /** Default executor agent type */
+    defaultExecutor: AgentType;
+    safety: CommanderSafetyConfig;
+    workspace: WorkspacePolicy;
+    /** Preset environment profile, overrides specific fields */
+    profile: 'development' | 'staging' | 'production' | 'custom';
+}
+export interface CommanderState {
+    status: 'idle' | 'thinking' | 'dispatching' | 'paused';
+    lastTickAt: string;
+    lastDecision: Decision | null;
+    activeWorkers: number;
+    sessionId: string;
+    tickCount: number;
+}
+export interface PriorityAction {
+    type: 'execute_issue' | 'analyze_issue' | 'plan_issue' | 'create_issue' | 'advance_phase' | 'flag_blocker';
+    /** Target identifier (ISS-xxx or phase-slug) */
+    target: string;
+    reason: string;
+    risk: 'low' | 'medium' | 'high';
+    /** Executor agent type identifier */
+    executor: string;
+}
+export interface Assessment {
+    priority_actions: PriorityAction[];
+    observations: string[];
+    risks: string[];
+}
+export interface DecisionMetrics {
+    assessDurationMs: number;
+    decideDurationMs: number;
+    totalDurationMs: number;
+}
+export interface AssessMetrics {
+    input_tokens: number;
+    output_tokens: number;
+    latency_ms: number;
+}
+export interface Decision {
+    id: string;
+    timestamp: string;
+    /** What triggered this decision (scheduled_tick, issue:created, etc.) */
+    trigger: string;
+    assessment: Assessment;
+    /** Actions approved by threshold + capacity filter */
+    actions: PriorityAction[];
+    /** Actions blocked by capacity or threshold */
+    deferred: PriorityAction[];
+    /** Timing metrics for observability */
+    metrics?: DecisionMetrics;
+    /** Agent SDK token/latency metrics from the assess() call */
+    assessMetrics?: AssessMetrics;
+}
+export declare const DEFAULT_COMMANDER_CONFIG: CommanderConfig;

package/dashboard/dist-server/shared/commander-types.js

@@ -0,0 +1,37 @@
+// ---------------------------------------------------------------------------
+// Commander Agent types — config, state, assessment, and decision interfaces
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Default configuration
+// ---------------------------------------------------------------------------
+export const DEFAULT_COMMANDER_CONFIG = {
+    // Core Loop
+    pollIntervalMs: 30_000,
+    maxConcurrentWorkers: 3,
+    stallTimeoutMs: 300_000,
+    maxRetries: 2,
+    retryBackoffMs: 60_000,
+    // Decision
+    decisionModel: 'sonnet',
+    assessMaxTurns: 5,
+    autoApproveThreshold: 'low',
+    defaultExecutor: 'claude-code',
+    // Safety
+    safety: {
+        eventDebounceMs: 5_000,
+        circuitBreakerThreshold: 3,
+        maxTicksPerHour: 120,
+        maxTokensPerHour: 500_000,
+        protectedPaths: ['.env', '.env.*', '*.key', '*.pem', 'credentials.*'],
+    },
+    // Workspace
+    workspace: {
+        enabled: false,
+        useWorktree: true,
+        autoCleanup: true,
+        strict: false,
+    },
+    // Profile
+    profile: 'development',
+};
+//# sourceMappingURL=commander-types.js.map

package/dashboard/dist-server/shared/commander-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commander-types.js","sourceRoot":"","sources":["../../src/shared/commander-types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAyH9E,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,YAAY;IACZ,cAAc,EAAE,MAAM;IACtB,oBAAoB,EAAE,CAAC;IACvB,cAAc,EAAE,OAAO;IACvB,UAAU,EAAE,CAAC;IACb,cAAc,EAAE,MAAM;IAEtB,WAAW;IACX,aAAa,EAAE,QAAQ;IACvB,cAAc,EAAE,CAAC;IACjB,oBAAoB,EAAE,KAAK;IAC3B,eAAe,EAAE,aAAa;IAE9B,SAAS;IACT,MAAM,EAAE;QACN,eAAe,EAAE,KAAK;QACtB,uBAAuB,EAAE,CAAC;QAC1B,eAAe,EAAE,GAAG;QACpB,gBAAgB,EAAE,OAAO;QACzB,cAAc,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC;KACtE;IAED,YAAY;IACZ,SAAS,EAAE;QACT,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,IAAI;QACjB,WAAW,EAAE,IAAI;QACjB,MAAM,EAAE,KAAK;KACd;IAED,UAAU;IACV,OAAO,EAAE,aAAa;CACvB,CAAC"}

package/dashboard/dist-server/shared/constants.d.ts

@@ -0,0 +1,110 @@
+import type { PhaseStatus, TaskStatus, SSEEventType } from './types.js';
+import type { WsEventType } from './ws-protocol.js';
+import type { AgentType } from './agent-types.js';
+import type { Issue } from './issue-types.js';
+export declare const PHASE_STATUSES: readonly PhaseStatus[];
+export declare const TASK_STATUSES: readonly TaskStatus[];
+export interface ColumnDefinition {
+    id: string;
+    label: string;
+    statuses: readonly PhaseStatus[];
+}
+export declare const COLLAPSED_COLUMNS: readonly ColumnDefinition[];
+export declare const SSE_EVENT_TYPES: Record<string, SSEEventType>;
+export declare const API_ENDPOINTS: {
+    readonly HEALTH: "/api/health";
+    readonly BOARD: "/api/board";
+    readonly PROJECT: "/api/project";
+    readonly PHASES: "/api/phases";
+    readonly PHASE: "/api/phases/:n";
+    readonly PHASE_TASKS: "/api/phases/:n/tasks";
+    readonly ARTIFACTS: "/api/artifacts";
+    readonly SCRATCH: "/api/scratch";
+    readonly SETTINGS: "/api/settings";
+    readonly SETTINGS_GENERAL: "/api/settings/general";
+    readonly SETTINGS_AGENTS: "/api/settings/agents";
+    readonly SETTINGS_CLI_TOOLS: "/api/settings/cli-tools";
+    readonly SETTINGS_SPECS: "/api/settings/specs";
+};
+export declare const SPECS_API_ENDPOINTS: {
+    readonly SPECS: "/api/specs";
+    readonly SPECS_FILES: "/api/specs/files";
+    readonly SPECS_FILE: "/api/specs/file/:name";
+};
+export declare const MCP_API_ENDPOINTS: {
+    readonly CONFIG: "/api/mcp-config";
+    readonly TOGGLE: "/api/mcp-toggle";
+    readonly COPY_SERVER: "/api/mcp-copy-server";
+    readonly REMOVE_SERVER: "/api/mcp-remove-server";
+    readonly ADD_GLOBAL: "/api/mcp-add-global-server";
+    readonly REMOVE_GLOBAL: "/api/mcp-remove-global-server";
+    readonly INSTALL_MAESTRO: "/api/mcp-install-maestro";
+    readonly CODEX_CONFIG: "/api/codex-mcp-config";
+    readonly CODEX_ADD: "/api/codex-mcp-add";
+    readonly CODEX_REMOVE: "/api/codex-mcp-remove";
+    readonly CODEX_TOGGLE: "/api/codex-mcp-toggle";
+    readonly TEMPLATES: "/api/mcp-templates";
+    readonly TEMPLATES_SEARCH: "/api/mcp-templates/search";
+    readonly TEMPLATES_CATEGORIES: "/api/mcp-templates/categories";
+    readonly TEMPLATES_INSTALL: "/api/mcp-templates/install";
+    readonly DETECT_COMMANDS: "/api/mcp/detect-commands";
+};
+export declare const SSE_ENDPOINT = "/events";
+export declare const WS_EVENT_TYPES: Record<string, WsEventType>;
+export declare const AGENT_API_ENDPOINTS: {
+    readonly SPAWN: "/api/agent/spawn";
+    readonly STOP: "/api/agent/stop";
+    readonly MESSAGE: "/api/agent/message";
+    readonly APPROVE: "/api/agent/approve";
+    readonly LIST: "/api/agent/list";
+    readonly ENTRIES: "/api/agent/entries";
+};
+export declare const ISSUE_API_ENDPOINTS: {
+    readonly ISSUES: "/api/issues";
+    readonly ISSUE: "/api/issues/:id";
+};
+export declare const EXECUTION_API_ENDPOINTS: {
+    readonly DISPATCH: "/api/execution/dispatch";
+    readonly BATCH: "/api/execution/batch";
+    readonly CANCEL: "/api/execution/cancel";
+    readonly STATUS: "/api/execution/status";
+    readonly SUPERVISOR: "/api/execution/supervisor";
+};
+export declare const LINEAR_API_ENDPOINTS: {
+    readonly STATUS: "/api/linear/status";
+    readonly TEAMS: "/api/linear/teams";
+    readonly BOARD: "/api/linear/board";
+    readonly IMPORT: "/api/linear/import";
+    readonly EXPORT: "/api/linear/export";
+};
+export declare const TEAM_API_ENDPOINTS: {
+    readonly SESSIONS: "/api/teams/sessions";
+    readonly SESSION: "/api/teams/sessions/:sessionId";
+    readonly SESSION_MESSAGES: "/api/teams/sessions/:sessionId/messages";
+    readonly SESSION_FILE: "/api/teams/sessions/:sessionId/files";
+};
+export declare const WS_ENDPOINT = "/ws";
+export declare const DEFAULT_CONFIG: {
+    readonly serverPort: 3001;
+    readonly serverHost: "127.0.0.1";
+    readonly watchDebounceMs: 150;
+    readonly sseHeartbeatMs: 30000;
+    readonly sseMaxConnections: 10;
+};
+export declare const CLI_HISTORY_DIR_NAME = "cli-history";
+export declare const INSTALL_API_ENDPOINTS: {
+    readonly DETECT: "/api/install/detect";
+    readonly EXECUTE: "/api/install/execute";
+    readonly MANIFESTS: "/api/install/manifests";
+};
+export declare const STATUS_COLORS: Record<PhaseStatus, string>;
+export declare const AGENT_DOT_COLORS: Record<AgentType, string>;
+export declare const AGENT_LABELS: Record<AgentType, string>;
+/** UI-derived status that includes metadata-based states */
+export type DisplayStatus = 'open' | 'registered' | 'analyzing' | 'planned' | 'in_progress' | 'resolved' | 'closed' | 'deferred';
+export declare const ISSUE_DISPLAY_STATUS_COLORS: Record<DisplayStatus, string>;
+/**
+ * Derive display status from issue.status + metadata (analysis/solution presence).
+ * Maps the raw IssueStatus to a richer UI state based on attached data.
+ */
+export declare function getDisplayStatus(issue: Issue): DisplayStatus;