@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/runtime/drivers/persistent-cli-process.d.ts

@@ -0,0 +1,425 @@
+/**
+ * Persistent Claude CLI Process - Keeps Claude alive for multi-turn conversations
+ *
+ * WHY THIS EXISTS:
+ * - Previous approach spawned new Claude CLI process for each message
+ * - Each spawn required ~20K system prompt to be sent every time
+ * - Result: Slow responses (16-30 seconds per message)
+ *
+ * NEW ARCHITECTURE:
+ * - Keep Claude process alive using stream-json input/output
+ * - Send messages via stdin, receive responses via stdout
+ * - Session memory preserved in Claude's context
+ * - System prompt sent only once at process start
+ *
+ * STREAM-JSON PROTOCOL:
+ * Input (stdin):
+ *   User message: {"type":"user","message":{"role":"user","content":"..."}}
+ *   Tool result:  {"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"xxx","content":"...","is_error":false}]}}
+ *
+ * Output (stdout):
+ *   Init:      {"type":"system","subtype":"init",...}
+ *   Assistant: {"type":"assistant","message":{...}}
+ *   Tool use:  Content block with type="tool_use" in assistant message
+ *   Result:    {"type":"result","subtype":"success",...}
+ */
+import { EventEmitter } from 'events';
+import { type SessionPolicyStatus } from './types.js';
+import { type PromptCallbacks, type PromptResult, type TokenUsageRecord } from './types.js';
+import { type ThinkingEffort } from './claude-effort.js';
+export interface PersistentProcessOptions {
+    sessionId: string;
+    /**
+     * Timeouts the product states. A driver does not read a config file: the
+     * numbers arrive with the options, and the defaults below are what a caller
+     * that states nothing gets.
+     */
+    /**
+     * The isolated workspace this process runs in, and the empty plugin
+     * directory that keeps the host's global plugins out of every turn. The
+     * product states both; the driver only creates and uses them. The values
+     * are a product decision recorded in its CLAUDE.md — a driver that invented
+     * them would be deciding where another system keeps its files.
+     */
+    /**
+     * Where this run keeps its files. Required: a driver does not know a product's
+     * directory name, and the default it used to compute spelled one out.
+     */
+    workspaceDir: string;
+    timeouts?: {
+        requestMs?: number;
+        idleMs?: number;
+        sessionMs?: number;
+        cleanupMs?: number;
+        pendingToolMs?: number;
+    };
+    /** Host-computed authority fingerprint bound to this process generation. */
+    policyFingerprint?: string;
+    model?: string;
+    systemPrompt?: string;
+    mcpConfigPath?: string;
+    /**
+     * Skip permission prompts for tool execution
+     *
+     * @warning SECURITY RISK: Bypasses all permission checks.
+     * Only enable in trusted environments where agent actions are pre-approved.
+     */
+    dangerouslySkipPermissions?: boolean;
+    /** Noninteractive consumers use dontAsk with explicit permission rules. */
+    permissionMode?: 'default' | 'acceptEdits' | 'dontAsk' | 'plan';
+    useGatewayTools?: boolean;
+    /** Timeout for each request in ms (default: 120000) */
+    requestTimeout?: number;
+    /** Idle timeout for pooled persistent processes in ms (default: session_ms) */
+    idleTimeoutMs?: number;
+    /** Cleanup interval for pooled persistent processes in ms (default: session_cleanup_ms) */
+    cleanupIntervalMs?: number;
+    /** Maximum time to keep a process waiting for host-side tool results (default: max(4 * idleTimeoutMs, 30m)) */
+    pendingToolUseTimeoutMs?: number;
+    /** Environment variables to pass to the Claude CLI process */
+    env?: Record<string, string>;
+    /** Complete inherited environment supplied by the consumer; env is applied afterward. */
+    processEnv?: NodeJS.ProcessEnv;
+    /** Structurally allowed tools (--allowedTools CLI flag) */
+    allowedTools?: string[];
+    /** Structurally disallowed tools (--disallowedTools CLI flag) */
+    disallowedTools?: string[];
+    /** Override built-in tool set (--tools CLI flag). Use "" to disable all tools. */
+    tools?: string;
+    /** Override plugin directory (--plugin-dir CLI flag). Use empty dir to disable plugins. */
+    pluginDir?: string;
+    /** Optional callback for recording token usage */
+    onTokenUsage?: (record: TokenUsageRecord) => void;
+    /** Channel key for token usage tracking */
+    channelKey?: string;
+    /** Agent ID for token usage tracking */
+    agentId?: string;
+    /** Thinking effort passed as --effort on models that accept it. */
+    effort?: ThinkingEffort;
+}
+export interface PersistentProcessAcquireResult {
+    process: PersistentClaudeProcess;
+    created: boolean;
+}
+export type { ToolUseBlock } from './types.js';
+export interface ContentBlock {
+    type: 'text' | 'tool_use' | 'tool_result';
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    tool_use_id?: string;
+    content?: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+    is_error?: boolean;
+}
+export interface StreamMessage {
+    type: 'system' | 'assistant' | 'result' | 'error' | 'user';
+    subtype?: string;
+    uuid?: string;
+    origin?: {
+        kind: string;
+    };
+    /**
+     * Set by the CLI on events produced INSIDE a subagent (the Agent tool_use id that
+     * started it). It is the only non-heuristic way to tell a child's tool calls from the
+     * parent's on one stream; absent/null means "this stream position", not "parent".
+     */
+    parent_tool_use_id?: string | null;
+    /** Background-task identity on `system` task_* events; field name varies by CLI build. */
+    task_id?: string;
+    taskId?: string;
+    task?: {
+        id?: string;
+        status?: string;
+        description?: string;
+        agentId?: string;
+    };
+    agent_id?: string;
+    agentId?: string;
+    message?: {
+        role: string;
+        content: ContentBlock[] | string;
+        model?: string;
+        id?: string;
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+    result?: string;
+    session_id?: string;
+    total_cost_usd?: number;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    };
+    duration_ms?: number;
+    num_turns?: number;
+    is_error?: boolean;
+    error?: string;
+}
+export type { PromptCallbacks, PromptResult };
+type ProcessState = 'idle' | 'busy' | 'starting' | 'dead';
+/** Host-visible spawn/finish of a native background Agent on the Claude stream. */
+export interface ClaudeSubagentStreamEvent {
+    kind: 'started' | 'completed';
+    agentThreadId: string;
+    agentPath: string;
+    itemId: string;
+    status?: 'completed' | 'unknown';
+    finalText?: string;
+    /**
+     * False when the CLI opened its own follow-up turn for the notification: that turn IS
+     * the owner reacting, so the host must not enqueue a second one.
+     */
+    wakeRequired: boolean;
+}
+/** A turn the CLI begins on its own after a background task notification (no stdin). */
+export interface ClaudeAutonomousTurnEvent {
+    agentThreadId: string;
+    agentPath: string;
+    itemId: string;
+}
+export interface ClaudeAutonomousTurnResultEvent extends ClaudeAutonomousTurnEvent {
+    text: string;
+    isError: boolean;
+}
+/**
+ * PersistentClaudeProcess - Manages a single long-lived Claude CLI process
+ *
+ * Features:
+ * - Keeps Claude process alive for multiple messages
+ * - Uses stream-json for bidirectional communication
+ * - Handles tool execution via Gateway Tools
+ * - Auto-restarts on process death
+ */
+export declare class PersistentClaudeProcess extends EventEmitter {
+    private process;
+    private options;
+    private state;
+    private outputBuffer;
+    private currentCallbacks;
+    /**
+     * The most recent request that offered a follow-up sink. A CLI turn that no stdin request
+     * and no tracked child explains (a grandchild's task notification, measured 2026-09-10)
+     * still answers SOMEONE: the last request that asked.
+     */
+    private lastFollowUp;
+    private currentResolve;
+    private currentReject;
+    private currentInputUuid;
+    private inputAcknowledged;
+    private requestTimeoutHandle;
+    private toolUseBlocks;
+    private readonly promptToolExchanges;
+    private completedToolExchanges;
+    private awaitingToolResults;
+    private pendingToolUseStartedAt;
+    private accumulatedText;
+    private startPromise;
+    private onTokenUsage?;
+    /** Live + just-finished native background Agents, keyed by their `Agent` tool_use id. */
+    private readonly backgroundAgents;
+    /**
+     * True once a turn's `result` resolved while a background child was still running. From
+     * then until the next stdin request, unattributed assistant/user events on the stream
+     * belong to that child, not to a parent turn that no longer exists.
+     */
+    private parentTurnEnded;
+    /** Set between a `task_notification` and the CLI's own follow-up turn. */
+    private pendingNotification;
+    /** The CLI-initiated turn currently running with no stdin request behind it. */
+    private autonomousTurn;
+    /**
+     * Resolve the effective request timeout in ms.
+     * 0 = unlimited (no timeout). Returns the configured or default value.
+     */
+    private _getRequestTimeoutMs;
+    constructor(options: PersistentProcessOptions);
+    /**
+     * Start the Claude CLI process
+     *
+     * Note: The CLI only emits the 'init' event after receiving the first user message.
+     * So we don't wait for init here - we just start the process and let it run.
+     * The first sendMessage() call will handle init as part of its response flow.
+     */
+    start(): Promise<void>;
+    private doStart;
+    /**
+     * Build CLI arguments for stream-json mode
+     */
+    private buildArgs;
+    /**
+     * Send a user message to Claude
+     */
+    sendMessage(content: string, callbacks?: PromptCallbacks, nativeInputId?: string): Promise<PromptResult>;
+    /**
+     * Send a tool result back to Claude
+     */
+    sendToolResult(toolUseId: string, result: string, isError?: boolean, callbacks?: PromptCallbacks): Promise<PromptResult>;
+    /**
+     * Send multiple tool results back to Claude in a single message.
+     * Required when Claude requests multiple tools in one turn.
+     */
+    sendToolResults(results: Array<{
+        tool_use_id: string;
+        content: string;
+        is_error: boolean;
+    }>, callbacks?: PromptCallbacks): Promise<PromptResult>;
+    /**
+     * Handle stdout data
+     */
+    private handleStdout;
+    /**
+     * Process a parsed event from stdout
+     */
+    private processEvent;
+    private recordToolUse;
+    private trackBackgroundAgent;
+    private pruneBackgroundAgents;
+    /** The newest tracked agent matching a predicate; `system` task events carry no item id. */
+    private latestBackgroundAgent;
+    private taskIdentityOf;
+    private recordBackgroundTaskStarted;
+    /** Lift the child's id out of the "Async agent launched" tool_result text. */
+    private recordBackgroundLaunchResult;
+    private fireSubagentStart;
+    /**
+     * Which background child an assistant/user event belongs to, or null for the parent.
+     *
+     * `parent_tool_use_id` is authoritative when the CLI stamps it. Without it the only
+     * honest signal is position: the parent turn already ended and exactly one child is
+     * live. Two live children and no stamp is ambiguous, so the event stays with the parent
+     * and says so rather than being silently attributed.
+     */
+    private childAgentFor;
+    private absorbChildAssistant;
+    private recordBackgroundTaskNotification;
+    private beginAutonomousTurn;
+    private finishAutonomousTurn;
+    private completeBackgroundAgent;
+    /** Whether a spawned background child has not been reported finished yet. */
+    hasLiveBackgroundAgents(): boolean;
+    private recordToolResult;
+    private failToolStreamProtocol;
+    /**
+     * Handle process close
+     */
+    private handleClose;
+    /**
+     * Handle process error
+     */
+    private handleError;
+    /**
+     * Handle request timeout
+     */
+    private handleTimeout;
+    /**
+     * Clear request timeout
+     */
+    private clearRequestTimeout;
+    /**
+     * Reset request state
+     */
+    private resetRequestState;
+    /**
+     * Stop the process
+     */
+    stop(): void;
+    /**
+     * Check if process is alive
+     */
+    isAlive(): boolean;
+    /**
+     * Check if process is ready for new messages
+     */
+    isReady(): boolean;
+    /**
+     * True while Claude has requested tools and the host has not sent tool_result yet.
+     * The process is technically idle during host-side tool execution, but it must not
+     * be reclaimed because the next prompt depends on this live Claude context.
+     */
+    hasPendingToolUse(): boolean;
+    getPendingToolUseStartedAt(): number | null;
+    /**
+     * Get current state
+     */
+    getState(): ProcessState;
+    /**
+     * Get session ID
+     */
+    getSessionId(): string;
+}
+export declare function formatClaudeArgsForLog(args: readonly string[]): string[];
+/**
+ * PersistentProcessPool - Manages multiple persistent Claude processes
+ *
+ * Features:
+ * - One process per channel/session
+ * - Automatic process lifecycle management
+ * - Process reuse for multi-turn conversations
+ */
+export declare class PersistentProcessPool {
+    private processes;
+    private defaultOptions;
+    private idleTimeoutMs;
+    private cleanupIntervalMs;
+    private pendingToolUseTimeoutMs;
+    private cleanupTimer;
+    constructor(defaultOptions: Partial<PersistentProcessOptions> & {
+        workspaceDir: string;
+    });
+    private resolveIdleTimeoutMs;
+    private resolveCleanupIntervalMs;
+    private resolvePendingToolUseTimeoutMs;
+    private startCleanupTimer;
+    /**
+     * Get or create a process for a channel
+     */
+    getProcess(channelKey: string, options?: Partial<PersistentProcessOptions>): Promise<PersistentClaudeProcess>;
+    /**
+     * Get or create a process for a channel and report whether this call created it.
+     */
+    getProcessWithStatus(channelKey: string, options?: Partial<PersistentProcessOptions>): Promise<PersistentProcessAcquireResult>;
+    /**
+     * Stop idle ready processes that have outlived the configured idle timeout.
+     */
+    cleanupIdleProcesses(now?: number): number;
+    /**
+     * Stop a specific process
+     */
+    stopProcess(channelKey: string): void;
+    getSessionPolicyStatus(channelKey: string, policyFingerprint: string | undefined): SessionPolicyStatus;
+    /**
+     * Stop the exact process generation acquired by the caller. Only remove the pool entry when it
+     * still points at that generation, so stale cleanup cannot stop or evict a replacement. The
+     * expected process may already be absent after its error listener ran; it still must be stopped
+     * or the child would remain alive outside pool lifecycle management.
+     */
+    retireProcess(channelKey: string, expectedProcess: PersistentClaudeProcess): boolean;
+    /**
+     * Stop all processes
+     */
+    stopAll(): void;
+    /**
+     * Get number of active processes
+     */
+    getActiveCount(): number;
+    /**
+     * Get all channel keys with active processes
+     */
+    getActiveChannels(): string[];
+    /**
+     * Get states of all active processes
+     * @returns Map of channelKey → ProcessState
+     */
+    getProcessStates(): Map<string, string>;
+}
+//# sourceMappingURL=persistent-cli-process.d.ts.map