@tomsun28/pizza 0.1.0 → 0.1.1

package/dist/core/runtime/reactor.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Reactor — Event-Driven Agent Core
+ *
+ * Replaces the AgentLoop while-loop with a set of typed handlers that react
+ * to events appended to the EventStore. Each handler is a pure async function
+ * that may emit new events. The reactor itself is stateless — all mutable
+ * state lives in the EventStore.
+ *
+ * Event flow:
+ *
+ *   USER_MESSAGE / USER_INTERRUPT / TOOL_RESULTS_AGGREGATED / RETRY_SCHEDULED
+ *         ↓
+ *   [onUserMessage]  ──→ emit AGENT_TURN_REQUESTED
+ *         ↓
+ *   [onAgentTurnRequested]  ──→ emit LLM_CALL_REQUESTED
+ *         ↓
+ *   [onLlmCallRequested]  ──→ call LLM → emit AGENT_MESSAGE_START/CHUNK/END
+ *         ↓
+ *   [onAgentMessageEnd]
+ *       ├── if no tool_calls → emit AGENT_TURN_COMPLETED
+ *       └── if tool_calls → emit INTENT_TOOL_CALL (one per call)
+ *         ↓
+ *   [onIntentToolCall]  ──→ (approval gate) → emit TOOL_EXECUTION_START/END
+ *         ↓
+ *   [onToolExecutionEnd]  ──→ track count → if all done → emit TOOL_RESULTS_AGGREGATED
+ *         ↓
+ *   [onToolResultsAggregated]  ──→ emit AGENT_TURN_REQUESTED  ← loop back
+ *
+ * Other handlers (run in parallel, do not gate the main flow):
+ *   onAgentTurnCompleted  — UI notification
+ *   onLlmCallFailed        — retry scheduling
+ *   onUserInterrupt        — abort signal + turn completion
+ *   onCompactionRequested  — compaction orchestration
+ */
+import type { EventBase, EventType } from "../event-store/types.js";
+import type { EventStore } from "../event-store/store.js";
+import type { ApprovalHandler, ToolRegistry } from "../intent/types.js";
+import type { IntentClassifier } from "../intent/classifier.js";
+import type { LLMClient, ToolDefinition } from "./llm-types.js";
+import type { RuntimeAdapter } from "./types.js";
+import type { SessionProjection } from "../projection/session-projection.js";
+import type { SessionManager } from "../projection/session-manager.js";
+import type { CompactionPolicy, RetryPolicy } from "./policies.js";
+/** Reactor configuration */
+export interface ReactorConfig {
+    store: EventStore;
+    projection: SessionProjection;
+    llmClient: LLMClient;
+    classifier: IntentClassifier;
+    toolRegistry: ToolRegistry;
+    approvalHandler?: ApprovalHandler;
+    runtimeAdapter: RuntimeAdapter;
+    systemPrompt: string;
+    model: {
+        provider: string;
+        model_id: string;
+        thinking_level?: string;
+    };
+    contextBudget: number;
+    /** Tool definitions exposed to the LLM */
+    tools: ToolDefinition[];
+    /** Retry policy (default: DefaultRetryPolicy). */
+    retryPolicy?: RetryPolicy;
+    /** Whether assistant messages that complete with stop_reason=error should be retried by the reactor. */
+    retryAssistantErrorCompletions?: boolean;
+    /** Compaction policy (default: NoopCompactionPolicy). */
+    compactionPolicy?: CompactionPolicy;
+    /** SessionManager for refreshing projection after session splits. */
+    sessionManager?: SessionManager;
+}
+/** A single event handler. Returns void or void Promise. */
+export type EventHandler = (event: EventBase) => void | Promise<void>;
+/** Mapping from event type to handler */
+export type EventHandlerMap = Partial<Record<EventType, EventHandler>>;
+export declare class Reactor {
+    private config;
+    private abortController;
+    private turnTrackers;
+    private handlers;
+    private unsubscribers;
+    private _isRunning;
+    /** Context built in onAgentTurnRequested, consumed by onLlmCallRequested. */
+    private _pendingContext;
+    /** Active retry policy. */
+    private retryPolicy;
+    /** Active compaction policy. */
+    private compactionPolicy;
+    /** Pending follow-up messages (delivered after current turn completes without interrupt). */
+    private followUpQueue;
+    /** Aborter for the current compaction run (if any). */
+    private compactionAbort;
+    /** Retry timers waiting to re-enter the turn loop. */
+    private retryTimers;
+    /** Set when abort() is called with no new content — next turn completion should discard queued follow-ups. */
+    private _abortedByUser;
+    /** Tool names called in each consecutive tool-use round within the current prompt cycle. */
+    private _toolRoundSignatures;
+    constructor(config: ReactorConfig);
+    /** Subscribe to all events and start the reactor. */
+    start(): Promise<void>;
+    /**
+     * Replay USER_FOLLOWUP_QUEUED events that were appended while the reactor was idle.
+     * Skips events that have already been consumed (i.e. an AGENT_TURN_COMPLETED with a
+     * caused_by chain that includes them).
+     *
+     * For now we use a simple heuristic: count followups vs followup-driven user messages.
+     * If followups outnumber the consumed ones, replay the difference into the in-memory queue.
+     */
+    private _replayPendingFollowUps;
+    /** Stop the reactor. Clears all subscriptions. */
+    stop(): void;
+    /** Check if the reactor is running. */
+    get isRunning(): boolean;
+    /** Abort signal for the currently active reactor run. */
+    get signal(): AbortSignal | undefined;
+    private _dispatch;
+    private _emit;
+    /** Check if the reactor has been asked to stop. */
+    private _shouldInterrupt;
+    /** Interrupt the reactor. */
+    interrupt(): void;
+    private _registerAllHandlers;
+    /**
+     * Send a user message to the agent (idle path).
+     * For interrupt-while-streaming use steer(). For after-turn-completion use followUp().
+     */
+    prompt(content: string | Array<{
+        type: string;
+        [key: string]: unknown;
+    }>, images?: Array<{
+        type: "image";
+        data: string;
+        mime_type: string;
+    }>): void;
+    /**
+     * Steer: interrupt current turn with a new user message.
+     * The reactor aborts the current LLM call (if any) and treats the steer message
+     * as a fresh USER_MESSAGE once the turn settles.
+     */
+    steer(content: string | Array<{
+        type: string;
+        [key: string]: unknown;
+    }>, images?: Array<{
+        type: "image";
+        data: string;
+        mime_type: string;
+    }>): void;
+    /**
+     * Follow-up: queue a message to be delivered after the current turn naturally completes.
+     * Does not interrupt. If the reactor is idle, behaves like prompt().
+     */
+    followUp(content: string | Array<{
+        type: string;
+        [key: string]: unknown;
+    }>, images?: Array<{
+        type: "image";
+        data: string;
+        mime_type: string;
+    }>): void;
+    /** Number of pending follow-up messages. */
+    get pendingFollowUpCount(): number;
+    /** Number of scheduled retries waiting to re-enter the turn loop. */
+    get pendingRetryCount(): number;
+    /** Clear pending follow-ups (e.g. on user-explicit cancel). */
+    clearFollowUpQueue(): void;
+    private _onUserMessage;
+    private _onUserInterrupt;
+    private _onUserFollowupQueued;
+    private _onAgentTurnRequested;
+    private _onLlmCallRequested;
+    private _handleLlmResponse;
+    private _onAgentMessageEnd;
+    private readonly _pendingApprovals;
+    private _onIntentToolCall;
+    private _executeTool;
+    private _emitToolExecutionUpdate;
+    private _emitToolExecutionEnd;
+    private _onToolExecutionEnd;
+    private _onToolResultsAggregated;
+    /**
+     * When a session split occurs, refresh the projection to point to the new
+     * session. The new session's start_event_id is set to the current USER_MESSAGE,
+     * so buildContext() will include the user's request + tool results but exclude
+     * old conversation history. This lets the model continue working in the same
+     * turn with a clean context.
+     */
+    private _onSessionBoundaryInferred;
+    /**
+     * Check whether the model is stuck in a loop — calling the exact same set
+     * of tool names in too many consecutive rounds.
+     */
+    private _isInToolLoop;
+    private _onAgentTurnCompleted;
+    private _onLlmCallFailed;
+    private _scheduleRetryForCompletedError;
+    private _errorAlreadyHandledByLlmFailure;
+    private _scheduleRetry;
+    /** Walk causal chain back to find the highest retry_attempt seen. */
+    private _attemptCount;
+    private _onUserApproval;
+    private _onUserRejection;
+    private _onCompactionRequested;
+    /**
+     * Check compaction policy after a non-error turn. Emits COMPACTION_REQUESTED if
+     * threshold or overflow conditions are met.
+     */
+    private _checkCompaction;
+    /**
+     * Walk causal chain back from the given event to find the most recent AGENT_MESSAGE_END.
+     * Replaces the mutable _lastAssistantMessageEvent field which races with synchronous dispatch.
+     */
+    private _findLastAssistantMessage;
+}