@rowan-agent/agent 0.5.5 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _rowan_agent_models from '@rowan-agent/models';
-import { LlmRequest, LlmResponse, LlmModelRef, LlmModelUsage, AgentMessage, ContentBlock, ToolCall, ToolResult, Outcome, ProviderConfig, Skill as Skill$1, StreamFn, AgentEventListener, Protocol, ModelCost, AgentEvent, LlmMessage } from '@rowan-agent/models';
-export { AgentEvent, AgentEventListener, AgentMessage, LlmModelRef, Outcome, Skill, StreamFn, ToolResult, createDispatchStream, registerBuiltInApiProviders } from '@rowan-agent/models';
+import { LlmRequest, LlmResponse, LlmModelRef, LlmModelUsage, StreamFn, AgentEventListener, AgentMessage, Outcome, ToolCall, ToolResult, Skill as Skill$1, ContentBlock } from '@rowan-agent/models';
+export { AgentEvent, AgentEventListener, AgentMessage, LlmModelRef, Outcome, Skill, StreamFn, ToolResult } from '@rowan-agent/models';
 import Type from 'typebox';
 
 type ExecutionTurn = {
@@ -13,16 +13,127 @@ type ExecutionTurn = {
     model: LlmModelRef;
     usage?: LlmModelUsage;
 };
-type StepFilter = {
-    phase?: string;
-    afterMs?: number;
-};
 /** Raw model input/output for session persistence. */
 type ModelTranscript = {
     request: LlmRequest;
     response: LlmResponse;
 };
 
+type BeforePhaseHook = (phaseId: string, input: PhaseContext) => Promise<BeforePhaseHookResult>;
+type AfterPhaseHook = (phaseId: string, output: PhaseOutput) => Promise<AfterPhaseHookResult>;
+type BeforePromptHook = (phaseId: string, input: PhaseContext) => Promise<PhaseContext>;
+type LoopMetrics = {
+    /** Number of phase iterations executed. */
+    iterations: number;
+    /** Phase transition history. */
+    phaseTransitions: Array<{
+        from: string;
+        to: string;
+        ts: string;
+    }>;
+    /** Number of times compaction was triggered. */
+    compactionCount: number;
+    /** Number of retry attempts due to transient errors. */
+    retryCount: number;
+    /** Loop start timestamp. */
+    startedAt: string;
+    /** Loop start time as epoch ms (for duration calculation). */
+    startedAtMs: number;
+    /** Loop end timestamp (set on completion). */
+    endedAt?: string;
+    /** Total wall-clock duration in ms. */
+    durationMs?: number;
+};
+type SessionState = {
+    currentPhase: string;
+    attempt: number;
+    metrics: LoopMetrics;
+    status: "idle" | "running" | "completed" | "aborted" | "failed";
+};
+type AgentConfig = {
+    model: LlmModelRef;
+    stream: StreamFn;
+    context: AgentContext;
+    sessionId?: string;
+    sessionState?: SessionState;
+    maxAttempts?: number;
+    runtime?: AgentRuntimePort;
+    emit?: AgentEventListener;
+    signal?: AbortSignal;
+    beforeToolCall?: BeforeToolCall;
+    afterToolCall?: AfterToolCall;
+    beforePhase?: BeforePhaseHook;
+    afterPhase?: AfterPhaseHook;
+    beforePrompt?: BeforePromptHook;
+    onModelTranscript?: (transcript: ModelTranscript, meta: {
+        phase: string;
+        model: LlmModelRef;
+    }) => Promise<void>;
+    onMessage?: (message: AgentMessage) => Promise<void>;
+    onOutcome?: (outcome: Outcome) => Promise<void>;
+    /** Internal: await next user messages before retrying the same phase. */
+    waitForInput?: () => Promise<AgentMessage[]>;
+};
+type ToolRunnerInput = {
+    config: AgentConfig;
+    toolCall: ToolCall;
+};
+type ToolRunner = (input: ToolRunnerInput) => Promise<ToolResult>;
+type AgentRuntimePort = {
+    tools?: ToolRunner;
+};
+
+type ToolContext = Pick<AgentContext, "skills"> & {
+    toolCallId: string;
+};
+type ToolExecutionMode = "sequential" | "parallel";
+type Tool<TArgs = unknown> = {
+    name: string;
+    description: string;
+    parameters: Type.TSchema;
+    /** One-line snippet shown in the system prompt tool list. */
+    promptSnippet?: string;
+    /** Additional guidelines appended to the system prompt when this tool is active. */
+    promptGuidelines?: string[];
+    /** Whether this tool can run concurrently with others. Default: "parallel". */
+    executionMode?: ToolExecutionMode;
+    execute(args: TArgs, context: ToolContext, signal?: AbortSignal): Promise<ToolResult>;
+};
+/** Context snapshot passed into the low-level agent loop. */
+type AgentContext = {
+    /** System prompt included with the request. */
+    systemPrompt: string;
+    /** Transcript visible to the model. */
+    messages: AgentMessage[];
+    /** Tools available for this run. */
+    tools: Tool[];
+    /** Skills available for this run. */
+    skills: Skill$1[];
+    /** Custom phases for this run. Agent normalizes this with the built-in default phase. */
+    phases?: PhaseRegistry;
+};
+type BeforeToolCall = (input: {
+    tool: Tool;
+    args: unknown;
+}) => Promise<{
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+}>;
+type AfterToolCall = (input: {
+    tool: Tool;
+    result: ToolResult;
+}) => Promise<ToolResult>;
+type RunResult = {
+    sessionId: string;
+    messages: AgentMessage[];
+    outcome: Outcome;
+    metrics: LoopMetrics;
+};
+type Unsubscribe = () => void;
+declare function createMessage(role: AgentMessage["role"], content: AgentMessage["content"], metadata?: Record<string, unknown>): AgentMessage;
+
 type ModelInvokeOutput = {
     text: string;
     contentBlocks: ContentBlock[];
@@ -46,19 +157,93 @@ type PhaseExecution = {
     executeTool(context: AgentContext, toolCall: ToolCall): Promise<ToolResult>;
 };
 
+/** Unified phase output — model decides routing via route. */
+type PhaseOutput = {
+    message: string;
+    /** Route to next phase, or "continue" to re-execute current phase, or "stop" to end */
+    route: string;
+    /** Phase name that produced this output */
+    phase?: string;
+    /** Tool calls from the model invocation (used by framework for route extraction) */
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        args: unknown;
+    }>;
+    /** Route reason extracted from route tool call (for hooks to inspect) */
+    routeReason?: string;
+    /** Structured data from this phase, passed to the next phase */
+    payload?: unknown;
+};
+/** Phase machine state — tracks position and inter-phase data */
+interface PhaseState {
+    current: string;
+    available: string[];
+    iterations: number;
+    payload?: unknown;
+}
+/** Everything a phase needs to execute */
+interface PhaseContext {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    /** Phase-filtered tools */
+    tools: Tool[];
+    /** Phase-filtered skills */
+    skills: Skill$1[];
+    /** Phase machine state */
+    state: PhaseState;
+    /** Additional guideline bullets appended to the system prompt */
+    promptGuidelines?: string[];
+    /** Text to append after the system prompt */
+    appendSystemPrompt?: string;
+}
+/**
+ * Loaded Phase object
+ */
+interface Phase {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Restricted tools (undefined = all tools available) */
+    tools?: string[];
+    /** Restricted skills (undefined = all skills available) */
+    skills?: string[];
+    /** Forced next phase */
+    target?: string;
+    /** Expected input fields (key → description) */
+    input?: Record<string, string>;
+    /** If true, phase gets a fresh context when executed in parallel */
+    isolated?: boolean;
+    /** Path to PHASE.md file */
+    filePath: string;
+    /** Phase directory path */
+    baseDir: string;
+    /** PHASE.md body content */
+    content: string;
+    /** Model override for this phase (resolved from frontmatter) */
+    model?: LlmModelRef;
+    /** ExtensionAPI factory function (default export pattern) */
+    factory?: (api: ExtensionAPI) => Promise<void>;
+    /** Legacy run function */
+    run?: (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
+}
+/**
+ * Phase registry containing all loaded phases
+ */
+interface PhaseRegistry {
+    /** Map of phase id to Phase object */
+    phases: Map<string, Phase>;
+    /** Entry phase id (null until Agent applies its default phase) */
+    entryPhaseId: string | null;
+}
+
 /**
  * Extension types — simplified for the new hook-based system.
  */
 
-interface SourceInfo {
-    source: string;
-    baseDir?: string;
-    displayName?: string;
-}
-declare function createSourceInfo(extensionPath: string, options?: {
-    source?: string;
-    baseDir?: string;
-}): SourceInfo;
 /** Phase run function type for extensions */
 type PhaseRun = (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
 /** Phase definition shape used by extensions */
@@ -77,24 +262,6 @@ type PhaseRegistration = Partial<Omit<PhaseDefinition, 'run'>> & {
     /** Optional execution override — takes over model invocation */
     run?: PhaseRun;
 };
-type RegisteredPhase = {
-    definition: PhaseDefinition;
-    source: {
-        extensionPath: string;
-    };
-};
-type ExtensionPackageManifest = {
-    rowan?: {
-        extensions?: string[];
-        phase?: {
-            id?: string;
-            name?: string;
-            description?: string;
-            tools?: string[];
-            skills?: string[];
-        };
-    };
-};
 /**
  * Tool definition for registering LLM-callable tools via `api.registerTool()`.
  *
@@ -135,28 +302,6 @@ interface ToolExecutionResult {
     /** Whether this is an error result */
     isError?: boolean;
 }
-/**
- * Registered tool with source metadata.
- */
-interface RegisteredTool {
-    definition: ToolDefinition;
-    sourceInfo: SourceInfo;
-}
-/**
- * Structured extension error with attribution.
- */
-interface ExtensionError {
-    /** Path of the extension that caused the error */
-    extensionPath: string;
-    /** Event or operation that caused the error */
-    event: string;
-    /** Error message */
-    error: string;
-    /** Optional stack trace */
-    stack?: string;
-}
-/** Error listener callback type. */
-type ExtensionErrorListener = (error: ExtensionError) => void;
 type ExecOptions = {
     /** Working directory for the command. Defaults to cwd passed to runtime. */
     cwd?: string;
@@ -185,65 +330,6 @@ type AfterPhaseHookResult = {
     retry?: PhaseContext;
     output?: PhaseOutput;
 };
-type HandlerFn = (...args: unknown[]) => Promise<unknown>;
-/**
- * Loaded extension with all registered items.
- * Tracks what each extension registered for attribution and cleanup.
- */
-interface Extension {
-    /** Extension path (may be synthetic like `<inline>`) */
-    path: string;
-    /** Source info for error messages */
-    sourceInfo: SourceInfo;
-    /** Event handlers registered by this extension */
-    handlers: Map<string, HandlerFn[]>;
-    /** Tools registered by this extension */
-    tools: Map<string, RegisteredTool>;
-    /** Phases registered by this extension */
-    phases: Map<string, RegisteredPhase>;
-}
-/**
- * Create an Extension object with empty collections.
- */
-declare function createExtension(extensionPath: string, sourceInfo: SourceInfo): Extension;
-/**
- * Shared runtime state created by loader, used during registration and runtime.
- * All ExtensionAPI instances reference this shared state.
- *
- * Key features:
- * - `invalidate()` / `assertActive()` — prevents stale context usage
- * - Pending provider registration queue
- * - Shared action implementations replaceable post-bind
- */
-interface ExtensionRuntime {
-    /** Throws when this extension instance is stale after runtime replacement. */
-    assertActive: () => void;
-    /** Marks this extension instance as stale after runtime replacement or reload. */
-    invalidate: (message?: string) => void;
-    /** Provider registrations queued during extension loading, processed when runner binds */
-    pendingProviderRegistrations: Array<{
-        name: string;
-        config: ProviderConfig;
-        extensionPath: string;
-    }>;
-    /**
-     * Register a provider.
-     * Before bind(): queues registrations.
-     * After bind(): calls provider registration directly.
-     */
-    registerProvider: (name: string, config: ProviderConfig, extensionPath?: string) => void;
-    /**
-     * Unregister a provider.
-     * Before bind(): removes from queue.
-     * After bind(): calls provider unregistration directly.
-     */
-    unregisterProvider: (name: string, extensionPath?: string) => void;
-}
-/**
- * Create an ExtensionRuntime with throwing stubs.
- * Runner.bind() replaces these with real implementations.
- */
-declare function createExtensionRuntime(): ExtensionRuntime;
 /**
  * Result of loading extensions from filesystem.
  * The runner takes these and creates Extension tracking objects.
@@ -308,7 +394,6 @@ interface EventBus {
     /** Get listener count for an event. */
     count(event: string): number;
 }
-declare function createEventBus(): EventBus;
 
 /**
  * @module extensions/hooks
@@ -683,91 +768,6 @@ type HookEventType = HookEvent["type"];
 type HookHandler<K extends HookEventType> = (event: Extract<HookEvent, {
     type: K;
 }>) => HookResultMap[K] | Promise<HookResultMap[K]> | void | Promise<void>;
-/**
- * Hook execution error
- */
-declare class HookError extends Error {
-    /** Event type that caused the error */
-    readonly eventType: string;
-    constructor(
-    /** Event type that caused the error */
-    eventType: string, message: string, cause?: Error);
-}
-/**
- * Type-safe hook manager.
- *
- * ## Usage
- *
- * ```typescript
- * const hooks = new HooksManager();
- *
- * // Register hook
- * hooks.on("before_tool_call", (event) => {
- *   return { allow: false, reason: "Blocked" };
- * });
- *
- * // Emit event (listen-only)
- * await hooks.emit("agent_start", { type: "agent_start", sessionId: "123" });
- *
- * // Emit event and collect result
- * const result = await hooks.emitFirst("before_tool_call", { type: "before_tool_call", tool, args });
- * ```
- */
-declare class HooksManager {
-    private handlers;
-    /**
-     * Register a hook handler.
-     * Handlers execute in registration order.
-     *
-     * @param eventType - Event type
-     * @param handler - Handler function
-     */
-    on<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
-    /**
-     * Unregister a hook handler.
-     */
-    off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
-    /**
-     * Clear all handlers, or clear handlers for specified event type.
-     */
-    clear(eventType?: HookEventType): void;
-    /**
-     * Check if there are handlers registered for specified event type.
-     */
-    has(eventType: HookEventType): boolean;
-    /**
-     * Get handler count for specified event type.
-     */
-    count(eventType: HookEventType): number;
-    /**
-     * Emit event (listen-only, ignore return values).
-     * Errors are collected and thrown.
-     *
-     * @param eventType - Event type
-     * @param event - Event object
-     */
-    emit<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
-        type: K;
-    }>): Promise<void>;
-    /**
-     * Emit event and return first non-undefined result (short-circuit).
-     *
-     * @param eventType - Event type
-     * @param event - Event object
-     * @returns First non-undefined result, or undefined
-     */
-    emitFirst<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
-        type: K;
-    }>): Promise<HookResultMap[K] | undefined>;
-}
-/**
- * Get global hooks manager instance (singleton).
- */
-declare function getGlobalHooks(): HooksManager;
-/**
- * Reset global hooks manager (mainly for testing).
- */
-declare function resetGlobalHooks(): void;
 
 /**
  * @module extensions/context
@@ -924,435 +924,120 @@ interface ExtensionAPI {
  * Receives ExtensionAPI for registering hooks, phases, and providers.
  */
 type ExtensionFactory = (api: ExtensionAPI) => void | Promise<void>;
-/**
- * @internal
- * Create ExtensionAPI instance.
- * Works for both extension context (with hooks/runtime/eventBus) and phase context (without).
- */
-declare function createExtensionAPI(hooks?: HooksManager, _extensionPath?: string, options?: {
-    registerPhase?: (registration: PhaseRegistration) => void;
-    registerProvider?: (config: _rowan_agent_models.ProviderConfig) => void;
-    unregisterProvider?: (name: string) => void;
-    registerTool?: (tool: ToolDefinition) => void;
-    context?: ExtensionContext;
-    manifest?: ExtensionManifest;
-    phase?: PhaseContext;
-    session?: AgentContext;
-}, runtime?: ExtensionRuntime, eventBus?: EventBus): ExtensionAPI;
-
-/**
- * Extension runner — manages extension loading and hook execution.
- *
- * Architecture reference: PI's ExtensionRunner
- * - Per-extension tracking via Extension objects
- * - Shared ExtensionRuntime with invalidate/assertActive
- * - Direct `on()` API for hook registration
- * - Error listener pattern for structured error handling
- * - Tool registration support
- */
 
-type ExtensionRunnerOptions = {
-    entryPhaseId?: string | null;
-    cwd?: string;
+declare const opaqueIdBrand: unique symbol;
+type OpaqueId<Kind extends string> = string & {
+    readonly [opaqueIdBrand]: Kind;
 };
-/**
- * Manages extensions and provides hooks for the agent loop.
- *
- * Features:
- * - Per-extension tracking (handlers, tools, phases)
- * - Shared runtime with lifecycle protection (invalidate/assertActive)
- * - Error listener pattern for structured error handling
- * - Direct hook API and extension-loaded hook API
- * - Tool registration for LLM-callable tools
- * - EventBus for inter-extension communication
- *
- * @example
- * ```ts
- * const runner = createExtensionRunner();
- *
- * // Direct hook registration
- * const unsub = runner.on("before_tool_call", (event) => {
- *   return { allow: false, reason: "Blocked" };
- * });
- *
- * // Error handling
- * runner.onError((error) => {
- *   console.error(`Extension error in ${error.extensionPath}:`, error.error);
- * });
- *
- * // Load extensions
- * await runner.loadExtensions(extensions);
- * runner.bind();
- * ```
- */
-declare class ExtensionRunner {
-    readonly hooks: HooksManager;
-    readonly runtime: ExtensionRuntime;
-    readonly events: EventBus;
-    private readonly cwd;
-    private readonly abortController;
-    private _idle;
-    private readonly extensions;
-    private readonly phases;
-    private _phaseCache;
-    private readonly pendingProviders;
-    private bound;
-    private readonly errorListeners;
-    private readonly loadedExtensions;
-    /** Current agent context — set by the agent before each phase */
-    currentContext?: AgentContext;
-    constructor(options?: ExtensionRunnerOptions);
-    /** Whether the agent is currently idle (not streaming). */
-    get isIdle(): boolean;
-    /** Set idle state — called by the agent loop. */
-    setIdle(idle: boolean): void;
-    /** Abort signal for the current runner instance. */
-    get signal(): AbortSignal;
-    /** Abort the current runner operation. */
-    abort(): void;
-    /**
-     * Register an error listener.
-     * Returns an unsubscribe function.
-     */
-    onError(listener: ExtensionErrorListener): () => void;
-    /**
-     * Emit a structured extension error to all listeners.
-     */
-    emitError(error: ExtensionError): void;
-    /**
-     * Mark all extension contexts as stale.
-     * After calling this, any captured ExtensionAPI or ExtensionContext will throw
-     * on use. Used during session replacement or reload.
-     */
-    invalidate(message?: string): void;
-    /**
-     * Subscribe to a specific hook event type.
-     * Returns an unsubscribe function.
-     *
-     * @example
-     * ```ts
-     * const unsub = runner.on("before_tool_call", (event) => {
-     *   return { allow: false, reason: "Blocked" };
-     * });
-     * unsub(); // Cancel subscription
-     * ```
-     */
-    on<K extends HookEventType>(type: K, handler: HookHandler<K>): () => void;
-    /**
-     * Subscribe to all events (read-only).
-     * Returns an unsubscribe function.
-     *
-     * @example
-     * ```ts
-     * const unsub = runner.subscribe((event) => {
-     *   console.log(event.type);
-     * });
-     * ```
-     */
-    subscribe(listener: (event: {
-        type: HookEventType;
-    }) => void): () => void;
-    private getAllEventTypes;
-    /**
-     * Load and initialize extensions.
-     * Creates Extension tracking objects and calls each factory with an ExtensionAPI.
-     */
-    loadExtensions(extensions: LoadedExtension[]): Promise<void>;
-    /**
-     * Get all registered tools from all extensions (first registration per name wins).
-     */
-    getAllRegisteredTools(): RegisteredTool[];
-    /**
-     * Get a tool definition by name. Returns undefined if not found.
-     */
-    getToolDefinition(toolName: string): RegisteredTool["definition"] | undefined;
-    /**
-     * Check if there are handlers registered for specified event type.
-     */
-    hasHandlers(eventType: HookEventType): boolean;
-    /**
-     * Get the number of handlers for specified event type.
-     */
-    handlerCount(eventType: HookEventType): number;
-    getPhase(id: string): Phase | undefined;
-    getPhases(): Phase[];
-    createPhaseRegistry(input?: {
-        entryPhaseId?: string | null;
-    }): PhaseRegistry;
-    /** Adapt an extension RegisteredPhase to the core Phase type. */
-    private adaptToPhase;
-    /**
-     * Bind the runner — flushes pending provider registrations and
-     * replaces runtime stubs with real implementations.
-     */
-    bind(): void;
-    /**
-     * Generic emit — fire-and-forget for any event type.
-     */
-    emit<K extends HookEventType>(eventType: K, event: Parameters<HookHandler<K>>[0]): Promise<void>;
-    /**
-     * Unified hook emission — returns the first non-undefined result.
-     */
-    private emitHook;
-    emitBeforePhase(phaseId: string, input: PhaseContext): Promise<{
-        abort?: any;
-        skip?: any;
-        input?: PhaseContext;
-    }>;
-    emitAfterPhase(phaseId: string, output: PhaseOutput): Promise<{
-        abort?: any;
-        retry?: PhaseContext;
-        output?: PhaseOutput;
-    }>;
-    emitBeforePrompt(phaseId: string, input: PhaseContext): Promise<PhaseContext>;
-    emitBeforeToolCall(tool: Tool, args: unknown): Promise<{
-        allow: boolean;
-        reason?: string;
-    }>;
-    emitAfterToolCall(tool: Tool, result: ToolResult): Promise<ToolResult>;
-    emitAgentStart(sessionId: string): Promise<void>;
-    emitAgentEnd(sessionId: string, outcome: any, messages: any[]): Promise<void>;
-    emitTurnStart(messages: any[]): Promise<void>;
-    emitTurnEnd(messages: any[], outcome?: any): Promise<void>;
-    emitMessageStart(message: any): Promise<void>;
-    emitMessageUpdate(message: any, delta: string): Promise<void>;
-    emitMessageEnd(message: any): Promise<void>;
-    emitToolExecutionStart(toolCallId: string, toolName: string, args: unknown): Promise<void>;
-    emitToolExecutionUpdate(toolCallId: string, toolName: string, _progress?: string): Promise<void>;
-    emitToolExecutionEnd(toolCallId: string, toolName: string, result: ToolResult): Promise<void>;
-    emitSavePoint(hadPendingMutations: boolean): Promise<void>;
-    emitAbort(reason?: string): Promise<void>;
-    emitSettled(): Promise<void>;
-    /**
-     * Emit an AgentEvent by routing to the appropriate typed hook.
-     */
-    emitAgentEvent(event: any): Promise<void>;
-    /**
-     * Create an ExtensionAPI for a specific extension.
-     * Registration methods write to the extension tracking object.
-     * Action methods delegate to the shared runtime.
-     */
-    private createExtensionAPI;
-    private registerTool;
-    private registerPhase;
-    private registerProvider;
-    private unregisterProvider;
-    private flushPendingProviders;
-    private getRegisteredPhase;
-    private collectRegisteredPhases;
-}
-declare function createExtensionRunner(options?: ExtensionRunnerOptions): ExtensionRunner;
-
-type LoopMetrics = {
-    /** Number of phase iterations executed. */
-    iterations: number;
-    /** Phase transition history. */
-    phaseTransitions: Array<{
-        from: string;
-        to: string;
-        ts: string;
-    }>;
-    /** Number of times compaction was triggered. */
-    compactionCount: number;
-    /** Number of retry attempts due to transient errors. */
-    retryCount: number;
-    /** Loop start timestamp. */
-    startedAt: string;
-    /** Loop start time as epoch ms (for duration calculation). */
-    startedAtMs: number;
-    /** Loop end timestamp (set on completion). */
-    endedAt?: string;
-    /** Total wall-clock duration in ms. */
-    durationMs?: number;
+type AgentId = OpaqueId<"AgentId">;
+type AgentRunId = OpaqueId<"AgentRunId">;
+type RuntimeMessageId = OpaqueId<"RuntimeMessageId">;
+type RuntimeEventId = OpaqueId<"RuntimeEventId">;
+type LeaseId = OpaqueId<"LeaseId">;
+type RuntimeToolCallId = OpaqueId<"RuntimeToolCallId">;
+type AgentLifecycleState = "active" | "paused";
+type RuntimeMessageState = "queued" | "leased" | "acknowledged" | "dead_lettered";
+type AgentRunState = "queued" | "running" | "suspended" | "completed" | "failed" | "cancelled";
+type RuntimeToolCallState = "queued" | "running" | "completed" | "failed" | "indeterminate";
+type AgentRecord = {
+    id: AgentId;
+    sessionId: string;
+    factoryId?: string;
+    state: AgentLifecycleState;
+    createdAt: string;
+    updatedAt: string;
 };
-type SessionState = {
-    currentPhase: string;
-    attempt: number;
-    metrics: LoopMetrics;
-    status: "idle" | "running" | "completed" | "aborted" | "failed";
+type RuntimeLease = {
+    id: LeaseId;
+    runId: AgentRunId;
+    workerId: string;
+    leasedAt: string;
+    expiresAt: string;
 };
-
-type ToolContext = Pick<AgentContext, "skills"> & {
-    toolCallId: string;
+type RuntimeMessage = {
+    id: RuntimeMessageId;
+    agentId: AgentId;
+    kind: "agent_input";
+    input: AgentMessage;
+    state: RuntimeMessageState;
+    attempts: number;
+    runId?: AgentRunId;
+    lease?: RuntimeLease;
+    deadLetterReason?: string;
+    createdAt: string;
+    updatedAt: string;
 };
-type ToolExecutionMode = "sequential" | "parallel";
-type Tool<TArgs = unknown> = {
-    name: string;
-    description: string;
-    parameters: Type.TSchema;
-    /** One-line snippet shown in the system prompt tool list. */
-    promptSnippet?: string;
-    /** Additional guidelines appended to the system prompt when this tool is active. */
-    promptGuidelines?: string[];
-    /** Whether this tool can run concurrently with others. Default: "parallel". */
-    executionMode?: ToolExecutionMode;
-    execute(args: TArgs, context: ToolContext, signal?: AbortSignal): Promise<ToolResult>;
+type AgentRunRecord = {
+    id: AgentRunId;
+    agentId: AgentId;
+    messageId: RuntimeMessageId;
+    state: AgentRunState;
+    attempt: number;
+    leaseId?: LeaseId;
+    outcome?: Outcome;
+    suspensionReason?: string;
+    createdAt: string;
+    updatedAt: string;
 };
-/** Context snapshot passed into the low-level agent loop. */
-type AgentContext = {
-    /** System prompt included with the request. */
-    systemPrompt: string;
-    /** Transcript visible to the model. */
-    messages: AgentMessage[];
-    /** Tools available for this run. */
-    tools: Tool[];
-    /** Skills available for this run. */
-    skills: Skill$1[];
-    /** Custom phases for this run. Agent normalizes this with the built-in default phase. */
-    phases?: PhaseRegistry;
+type RuntimeEventKind = "agent_created" | "agent_paused" | "agent_resumed" | "agent_recovered" | "agent_recovery_failed" | "factory_missing" | "message_enqueued" | "run_enqueued" | "run_leased" | "lease_expired" | "lease_recovered" | "run_suspended" | "run_retry_scheduled" | "run_completed" | "run_aborted" | "message_acknowledged" | "message_dead_lettered" | "tool_call_created" | "tool_call_started" | "tool_call_failed" | "tool_call_completed" | "tool_call_indeterminate";
+type RuntimeEvent = {
+    id: RuntimeEventId;
+    sequence: number;
+    kind: RuntimeEventKind;
+    agentId?: AgentId;
+    messageId?: RuntimeMessageId;
+    runId?: AgentRunId;
+    toolCallId?: RuntimeToolCallId;
+    payload?: unknown;
+    createdAt: string;
 };
-type BeforeToolCall = (input: {
-    tool: Tool;
-    args: unknown;
-}) => Promise<{
-    allow: true;
-} | {
-    allow: false;
-    reason: string;
-}>;
-type AfterToolCall = (input: {
-    tool: Tool;
-    result: ToolResult;
-}) => Promise<ToolResult>;
-type RunResult = {
-    sessionId: string;
-    messages: AgentMessage[];
-    outcome: Outcome;
-    metrics: LoopMetrics;
+type RuntimeEventCursor = {
+    after?: RuntimeEventId;
+    limit?: number;
 };
-type Unsubscribe = () => void;
-declare function createMessage(role: AgentMessage["role"], content: AgentMessage["content"], metadata?: Record<string, unknown>): AgentMessage;
-declare function messageContentText(content: AgentMessage["content"]): string;
-
-/** Unified phase output — model decides routing via route. */
-type PhaseOutput = {
-    message: string;
-    /** Route to next phase, or "continue" to re-execute current phase, or "stop" to end */
-    route: string;
-    /** Phase name that produced this output */
-    phase?: string;
-    /** Tool calls from the model invocation (used by framework for route extraction) */
-    toolCalls?: Array<{
-        id: string;
-        name: string;
-        args: unknown;
-    }>;
-    /** Route reason extracted from route tool call (for hooks to inspect) */
-    routeReason?: string;
-    /** Structured data from this phase, passed to the next phase */
-    payload?: unknown;
+type RuntimeEventCheckpoint = {
+    consumerId: string;
+    sequence: number;
+    eventId?: RuntimeEventId;
+    updatedAt: string;
 };
-/** Phase machine state — tracks position and inter-phase data */
-interface PhaseState {
-    current: string;
-    available: string[];
-    iterations: number;
-    payload?: unknown;
-}
-/** Everything a phase needs to execute */
-interface PhaseContext {
-    systemPrompt: string;
-    messages: AgentMessage[];
-    /** Phase-filtered tools */
-    tools: Tool[];
-    /** Phase-filtered skills */
-    skills: Skill$1[];
-    /** Phase machine state */
-    state: PhaseState;
-    /** Additional guideline bullets appended to the system prompt */
-    promptGuidelines?: string[];
-    /** Text to append after the system prompt */
-    appendSystemPrompt?: string;
-}
-/**
- * Loaded Phase object
- */
-interface Phase {
-    /** Unique identifier */
-    id: string;
-    /** Display name */
+type RuntimeToolCall = {
+    id: RuntimeToolCallId;
+    agentId: AgentId;
+    runId: AgentRunId;
     name: string;
-    /** Description */
-    description: string;
-    /** Restricted tools (undefined = all tools available) */
-    tools?: string[];
-    /** Restricted skills (undefined = all skills available) */
-    skills?: string[];
-    /** Forced next phase */
-    target?: string;
-    /** Expected input fields (key → description) */
-    input?: Record<string, string>;
-    /** If true, phase gets a fresh context when executed in parallel */
-    isolated?: boolean;
-    /** Path to PHASE.md file */
-    filePath: string;
-    /** Phase directory path */
-    baseDir: string;
-    /** PHASE.md body content */
-    content: string;
-    /** Model override for this phase (resolved from frontmatter) */
-    model?: LlmModelRef;
-    /** ExtensionAPI factory function (default export pattern) */
-    factory?: (api: ExtensionAPI) => Promise<void>;
-    /** Legacy run function */
-    run?: (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
-}
-/**
- * Phase registry containing all loaded phases
- */
-interface PhaseRegistry {
-    /** Map of phase id to Phase object */
-    phases: Map<string, Phase>;
-    /** Entry phase id (null until Agent applies its default phase) */
-    entryPhaseId: string | null;
-}
-
-type WorkspacePaths = {
-    cwd: string;
-    rowanDir: string;
-};
-type ResolveWorkspaceOptions = {
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    homeDir?: string;
-    rowanDir?: string;
+    args: unknown;
+    state: RuntimeToolCallState;
+    result?: ToolResult;
+    indeterminateReason?: string;
+    createdAt: string;
+    updatedAt: string;
 };
-declare function resolveWorkspacePaths(options?: ResolveWorkspaceOptions): WorkspacePaths;
-declare function resolveInWorkspace(path: string, rootOrPaths: string | Pick<WorkspacePaths, "cwd">): string;
 
-type PhaseLoadTarget = string | Pick<WorkspacePaths, "rowanDir">;
 /**
- * Load a single phase from a PHASE.md file or phase directory.
+ * Load all phases from the target directory.
  *
- * If a directory is provided, the loader reads its PHASE.md.
- */
-declare function loadPhase(targetPath: string): Promise<Phase>;
-declare function loadPhases(targetPath: PhaseLoadTarget): Promise<PhaseRegistry>;
-/**
- * Re-read all file-based phases from disk and update the registry in place.
- * Extension-registered phases (with empty filePath) are preserved as-is.
+ * Scans for subdirectories containing PHASE.md files.
+ * Returns PhaseRegistry with entryPhaseId:
+ * - null by default (caller must explicitly set to start from a specific phase)
+ * - Set to a specific phase id to start from that phase
+ *
+ * When entryPhaseId is null, Agent normalizes the registry to start from its default phase.
  */
-declare function reloadPhases(registry: PhaseRegistry): Promise<void>;
+declare function loadPhases(targetPath: string): Promise<PhaseRegistry>;
 
-type AgentOptions = {
-    context: AgentContext;
-    model: LlmModelRef;
-    stream: StreamFn;
-    cwd?: string;
-    extensions?: LoadedExtension[];
+type AgentExecutionOptions = AgentOptions & {
     sessionId?: string;
-    maxAttempts?: number;
-    beforeToolCall?: BeforeToolCall;
-    afterToolCall?: AfterToolCall;
-    onMessage?: (message: AgentMessage) => Promise<void>;
-    onOutcome?: (outcome: Outcome) => Promise<void>;
-    onModelTranscript?: (transcript: ModelTranscript, meta: {
-        phase: string;
-        model: LlmModelRef;
-    }) => Promise<void>;
+    agentId?: AgentId;
+    onInput?: (message: AgentMessage) => Promise<void>;
+    runtime?: AgentRuntimePort;
+};
+type RunOptions = Partial<AgentExecutionOptions>;
+type RuntimeRunHooks = {
+    onSuspend?: (reason?: string) => Promise<void> | void;
 };
-type RunOptions = Partial<AgentOptions>;
 type AgentStatus = {
+    agentId?: AgentId;
     sessionId?: string;
     context: AgentContext;
     model: LlmModelRef;
@@ -1362,7 +1047,7 @@ type AgentStatus = {
     currentResult?: RunResult;
     error?: string;
 };
-declare class Agent {
+declare class AgentExecution {
     readonly state: AgentStatus;
     private options;
     private readonly listeners;
@@ -1372,16 +1057,21 @@ declare class Agent {
     private extensionRunner?;
     private loadedExtensions?;
     private loadedExtensionsCwd?;
+    private runtimeRunId?;
+    get id(): AgentId;
+    get sessionId(): string;
     static loadSkills(targetPath: string): Promise<AgentContext["skills"]>;
     static loadPhases(targetPath: Parameters<typeof loadPhases>[0]): Promise<PhaseRegistry>;
     static loadExtensions(targetPath: string): Promise<LoadExtensionsResult>;
-    constructor(options: AgentOptions);
+    constructor(options: AgentExecutionOptions);
     subscribe(listener: AgentEventListener): Unsubscribe;
     appendUserMessage(input: string): void;
     appendMessage(message: AgentMessage): void;
     appendMessages(messages: AgentMessage[]): void;
     runWithUserInput(input: string, options?: RunOptions): Promise<RunResult>;
-    runWithMessage(message: AgentMessage, options?: RunOptions): Promise<RunResult>;
+    runWithMessage(message: AgentMessage, options?: RunOptions, internalHooks?: RuntimeRunHooks): Promise<RunResult>;
+    /** Internal Runtime seam: executes one leased Agent Input. */
+    executeAgentInput(input: AgentMessage, runId: AgentRunId, control: AgentRunControl): Promise<Outcome>;
     resetInitialization(): void;
     getContext(): AgentContext;
     setContext(context: AgentContext): void;
@@ -1392,11 +1082,14 @@ declare class Agent {
     clearMessages(): void;
     getTranscript(): AgentMessage[];
     replaceTranscript(messages: AgentMessage[]): void;
-    getConfig(): AgentOptions;
-    setConfig(config: AgentOptions): void;
-    updateConfig(updater: (config: AgentOptions) => AgentOptions): void;
+    getConfig(): AgentExecutionOptions;
+    setConfig(config: AgentExecutionOptions): void;
+    updateConfig(updater: (config: AgentExecutionOptions) => AgentExecutionOptions): void;
     setSessionId(sessionId: string): void;
     getSessionId(): string | undefined;
+    getAgentId(): AgentId | undefined;
+    /** Internal Runtime hook for associating Tool Calls with the leased Run. */
+    getRuntimeRunId(): AgentRunId | undefined;
     setModel(model: LlmModelRef): void;
     setTools(tools: Tool[]): void;
     setSkills(skills: Skill$1[]): void;
@@ -1440,8 +1133,11 @@ declare class Agent {
     private runWithLifecycle;
     private finishRun;
     private loadExtensions;
-    run(config?: RunOptions): Promise<RunResult>;
+    run(config?: RunOptions, internalHooks?: RuntimeRunHooks): Promise<RunResult>;
     abort(reason?: string): void;
+    private abortLocal;
+    /** Internal Runtime hook; public callers abort a precise AgentRun. */
+    abortFromRuntime(reason?: string): void;
     /**
      * Get formatted skill content for LLM consumption.
      *
@@ -1469,9 +1165,6 @@ declare class Agent {
     private cloneOptions;
 }
 
-declare function createId(prefix: string): string;
-declare function createTimestamp(date?: Date): string;
-
 declare const SkillSchema: Type.TObject<{
     name: Type.TString;
     description: Type.TString;
@@ -1481,89 +1174,7 @@ declare const SkillSchema: Type.TObject<{
     disableModelInvocation: Type.TBoolean;
 }>;
 type Skill = Type.Static<typeof SkillSchema>;
-type Session<TLogEvent = never> = {
-    version: string;
-    id: string;
-    parentSessionId?: string;
-    systemPrompt: string;
-    input: string;
-    messages: AgentMessage[];
-    log: TLogEvent[];
-    skills: Skill[];
-    createdAt: string;
-    updatedAt: string;
-    title?: string;
-};
-declare function createSession<TLogEvent = never>(input: {
-    id?: string;
-    systemPrompt: string;
-    input: string;
-    skills?: Skill[];
-    parentSessionId?: string;
-    title?: string;
-}): Session<TLogEvent>;
-declare function appendUserTurn<TLogEvent>(session: Session<TLogEvent>, input: string): Session<TLogEvent>;
 
-type SessionHeader = {
-    type: "header";
-    id: string;
-    version: string;
-    createdAt: string;
-    updatedAt: string;
-    systemPrompt: string;
-    input: string;
-    parentSessionId?: string;
-    skills: Skill[];
-    title?: string;
-    currentLeafId?: string | null;
-};
-type SessionEntryBase = {
-    id: string;
-    parentId: string | null;
-    timestamp: string;
-};
-type MessageSessionEntry = SessionEntryBase & {
-    type: "message";
-    message: AgentMessage;
-};
-type OutcomeSessionEntry = SessionEntryBase & {
-    type: "outcome";
-    outcome: Outcome;
-};
-type ExecutionTurnSessionEntry = SessionEntryBase & {
-    type: "execution_turn";
-    turn: ExecutionTurn;
-};
-type CompactionSessionEntry = SessionEntryBase & {
-    type: "compaction";
-    summary: string;
-    firstKeptEntryId: string;
-};
-type BranchSummarySessionEntry = SessionEntryBase & {
-    type: "branch_summary";
-    fromId: string;
-    summary: string;
-};
-type SessionInfoSessionEntry = SessionEntryBase & {
-    type: "session_info";
-    title: string;
-};
-type CustomSessionEntry = SessionEntryBase & {
-    type: "custom";
-    customType: string;
-    data: unknown;
-};
-type SessionStateSessionEntry = SessionEntryBase & {
-    type: "session_state";
-    state: SessionState;
-};
-type ModelTranscriptSessionEntry = SessionEntryBase & {
-    type: "model_transcript";
-    transcript: ModelTranscript;
-    phase?: string;
-    model?: LlmModelRef;
-};
-type SessionEntry = MessageSessionEntry | OutcomeSessionEntry | ExecutionTurnSessionEntry | CompactionSessionEntry | BranchSummarySessionEntry | SessionInfoSessionEntry | CustomSessionEntry | SessionStateSessionEntry | ModelTranscriptSessionEntry;
 type SessionAgentContext<TTool = unknown> = {
     systemPrompt: string;
     messages: AgentMessage[];
@@ -1593,79 +1204,278 @@ type SessionListItem = {
 };
 type SessionManager = {
     getSessionId(): string;
-    getSessionFile(): string | undefined;
-    getHeader(): Promise<SessionHeader>;
     appendMessage(message: AgentMessage): Promise<string>;
     appendOutcome(outcome: Outcome): Promise<string>;
-    appendExecutionTurn(turn: ExecutionTurn): Promise<string>;
-    appendCompaction(input: {
-        summary: string;
-        firstKeptEntryId: string;
-    }): Promise<string>;
-    appendBranchSummary(input: {
-        fromId: string;
-        summary: string;
-    }): Promise<string>;
-    appendSessionInfo(input: {
-        title: string;
-    }): Promise<string>;
-    appendCustom(input: {
-        customType: string;
-        data: unknown;
-    }): Promise<string>;
-    appendSessionState(state: SessionState): Promise<string>;
     appendModelTranscript(transcript: ModelTranscript, meta?: {
         phase?: string;
         model?: LlmModelRef;
     }): Promise<string>;
-    getSessionState(): Promise<SessionState | undefined>;
-    branch(entryId: string | null): Promise<void>;
     buildAgentContext<TTool = unknown>(input?: BuildAgentContextInput<TTool>): Promise<SessionAgentContext<TTool>>;
-    listEntries(): Promise<SessionEntry[]>;
-    loadExecutionTurns(filter?: StepFilter): Promise<ExecutionTurn[]>;
+};
+type SessionManagerProvider = {
+    create(input: CreateSessionManagerInput): Promise<SessionManager>;
+    open(sessionId: string): Promise<SessionManager | undefined>;
 };
 
-declare class LocalJsonlSessionManager implements SessionManager {
-    private readonly sessionsDir;
-    private readonly filePath;
-    private readonly inner;
+type CreateAgentInput = {
+    sessionId: string;
+    factoryId?: string;
+};
+type EnqueueAgentInput = {
+    agentId: AgentId;
+    input: AgentMessage;
+};
+type ListRunsInput = {
+    agentId?: AgentId;
+    states?: AgentRunRecord["state"][];
+};
+type RecordRuntimeEventInput = {
+    kind: RuntimeEventKind;
+    related?: Pick<RuntimeEvent, "agentId" | "messageId" | "runId" | "toolCallId">;
+    payload?: unknown;
+};
+type LeaseRunInput = {
+    runId: AgentRunId;
+    workerId: string;
+    leaseDurationMs: number;
+    now?: Date;
+};
+type LeasedRun = {
+    run: AgentRunRecord;
+    message: RuntimeMessage;
+    lease: RuntimeLease;
+};
+type RenewLeaseInput = {
+    runId: AgentRunId;
+    leaseId: LeaseId;
+    leaseDurationMs: number;
+    now?: Date;
+};
+type SuspendRunInput = {
+    runId: AgentRunId;
+    reason?: string;
+};
+type CompleteRunInput = {
+    runId: AgentRunId;
+    outcome: Outcome;
+    state?: Extract<AgentRunRecord["state"], "completed" | "failed" | "cancelled">;
+};
+type RetryRunInput = {
+    runId: AgentRunId;
+    reason: string;
+};
+type ExhaustRunInput = {
+    runId: AgentRunId;
+    outcome: Outcome;
+    reason: string;
+};
+type AbortRunInput = {
+    runId: AgentRunId;
+    outcome: Outcome;
+};
+type CreateToolCallInput = {
+    agentId: AgentId;
+    runId: AgentRunId;
+    name: string;
+    args: unknown;
+};
+type CompleteToolCallInput = {
+    toolCallId: RuntimeToolCallId;
+    result: ToolResult;
+    state?: Extract<RuntimeToolCall["state"], "completed" | "failed">;
+};
+type IndeterminateToolCallInput = {
+    toolCallId: RuntimeToolCallId;
+    reason: string;
+};
+interface RuntimeStateStore {
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
+    listAgents(): Promise<AgentRecord[]>;
+    setAgentState(agentId: AgentId, state: AgentLifecycleState): Promise<AgentRecord>;
+    enqueueAgentInput(input: EnqueueAgentInput): Promise<{
+        message: RuntimeMessage;
+        run: AgentRunRecord;
+        resumed: boolean;
+    }>;
+    getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
+    getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
+    listRuns(input?: ListRunsInput): Promise<AgentRunRecord[]>;
+    leaseRun(input: LeaseRunInput): Promise<LeasedRun>;
+    renewLease(input: RenewLeaseInput): Promise<RuntimeLease>;
+    suspendRun(input: SuspendRunInput): Promise<AgentRunRecord>;
+    completeRun(input: CompleteRunInput): Promise<AgentRunRecord>;
+    retryRun(input: RetryRunInput): Promise<AgentRunRecord>;
+    exhaustRun(input: ExhaustRunInput): Promise<AgentRunRecord>;
+    abortRun(input: AbortRunInput): Promise<AgentRunRecord>;
+    recoverExpiredLeases(now?: Date): Promise<AgentRunRecord[]>;
+    recoverLeases(): Promise<AgentRunRecord[]>;
+    createToolCall(input: CreateToolCallInput): Promise<RuntimeToolCall>;
+    startToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall>;
+    completeToolCall(input: CompleteToolCallInput): Promise<RuntimeToolCall>;
+    markToolCallIndeterminate(input: IndeterminateToolCallInput): Promise<RuntimeToolCall>;
+    getToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall | undefined>;
+    listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
+    recordEvent(input: RecordRuntimeEventInput): Promise<RuntimeEvent>;
+    getEventCheckpoint(consumerId: string): Promise<RuntimeEventCheckpoint>;
+    acknowledgeEvent(consumerId: string, eventId: RuntimeEventId): Promise<RuntimeEventCheckpoint>;
+}
+
+type ToolRuntimePolicy = {
+    /** A narrowing allow-list. It can never add a Tool to an Agent. */
+    allowedTools?: readonly string[];
+    maxConcurrent?: number;
+    perToolMaxConcurrent?: Readonly<Record<string, number>>;
+};
+
+type AgentFactoryIdentity = {
+    agentId: AgentId;
+    sessionId: string;
+    factoryId: string;
+};
+type AgentFactory = (identity: AgentFactoryIdentity) => Promise<AgentOptions | undefined> | AgentOptions | undefined;
+type AgentRuntimeOptions = {
+    stateStore: RuntimeStateStore;
+    sessionProvider?: SessionManagerProvider;
+    factories?: ReadonlyMap<string, AgentFactory> | Readonly<Record<string, AgentFactory>>;
+    toolPolicy?: ToolRuntimePolicy;
+    maxConcurrentRuns?: number;
+    maxInfrastructureAttempts?: number;
+    leaseDurationMs?: number;
+    leaseRenewalIntervalMs?: number;
+};
+type RuntimeRunHandle = {
+    notify(run: AgentRunRecord): void;
+};
+type RuntimeEventListener = (event: RuntimeEvent) => void | Promise<void>;
+declare class AgentRuntime {
+    private readonly stateStore;
+    private readonly sessionProvider?;
+    private readonly maxConcurrentRuns;
+    private readonly maxInfrastructureAttempts;
+    private readonly leaseDurationMs;
+    private readonly leaseRenewalIntervalMs;
+    private readonly toolRuntime;
+    private readonly factories;
+    private readonly bindings;
+    private readonly runHandles;
+    private readonly runWaiters;
+    private readonly pendingRuns;
+    private readonly scheduledRunIds;
+    private readonly runningAgents;
+    private readonly pausedAgents;
+    private readonly eventSubscriptions;
+    private readonly activeDispatches;
+    private runningRuns;
+    private pumping;
+    private nextWorkerId;
+    private stopped;
     private constructor();
-    static create(sessionsDir: string, input: CreateSessionManagerInput): Promise<LocalJsonlSessionManager>;
-    static open(sessionsDir: string, id: string): Promise<LocalJsonlSessionManager | undefined>;
-    static list(sessionsDir: string): Promise<SessionListItem[]>;
-    static delete(sessionsDir: string, id: string): Promise<boolean>;
-    getSessionId(): string;
-    getSessionFile(): string | undefined;
-    getHeader(): Promise<SessionHeader>;
-    appendMessage(message: AgentMessage): Promise<string>;
-    appendOutcome(outcome: Outcome): Promise<string>;
-    appendExecutionTurn(turn: ExecutionTurn): Promise<string>;
-    appendCompaction(input: {
-        summary: string;
-        firstKeptEntryId: string;
-    }): Promise<string>;
-    appendBranchSummary(input: {
-        fromId: string;
-        summary: string;
-    }): Promise<string>;
-    appendSessionInfo(input: {
-        title: string;
-    }): Promise<string>;
-    appendCustom(input: {
-        customType: string;
-        data: unknown;
-    }): Promise<string>;
-    appendSessionState(state: SessionState): Promise<string>;
-    appendModelTranscript(transcript: ModelTranscript, meta?: {
-        phase?: string;
-        model?: LlmModelRef;
-    }): Promise<string>;
-    getSessionState(): Promise<SessionState | undefined>;
-    branch(entryId: string | null): Promise<void>;
-    buildAgentContext<TTool = unknown>(input?: BuildAgentContextInput<TTool>): Promise<SessionAgentContext<TTool>>;
-    listEntries(): Promise<SessionEntry[]>;
-    loadExecutionTurns(filter?: StepFilter): Promise<ExecutionTurn[]>;
-    private appendThroughInner;
+    static start(options: AgentRuntimeOptions): Promise<AgentRuntime>;
+    createAgent(options: AgentCreateOptions): Promise<Agent>;
+    reconstructAgent(agentId: AgentId, options: AgentOptions): Promise<Agent>;
+    stop(): Promise<void>;
+    private bindAgent;
+    private registerRunHandle;
+    private waitForRunChange;
+    private scheduleRun;
+    pauseAgent(agentId: AgentId): Promise<void>;
+    resumeAgent(agentId: AgentId): Promise<void>;
+    abortRun(runId: AgentRunId, reason?: string): Promise<void>;
+    consumeEvents(consumerId: string, listener: RuntimeEventListener): () => void;
+    listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
+    private recover;
+    private scheduleQueuedRuns;
+    private attachAgent;
+    private submitAgentInput;
+    private pump;
+    private dispatchRun;
+    private finishRun;
+    private finishFailedRun;
+    private notifyRun;
+    private publishEvents;
+    private deliverEvents;
+    private assertRunning;
+}
+
+type AgentRunListener = (state: AgentRunState) => void | Promise<void>;
+type AgentRunHost = {
+    register(handle: RuntimeRunHandle): void;
+    getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
+    waitForRunChange(runId: AgentRunId, state: AgentRunState, updatedAt: string): Promise<void>;
+    abortRun(runId: AgentRunId, reason: string): Promise<void>;
+    consumeEvents(consumerId: string, listener: RuntimeEventListener): () => void;
+};
+declare const CREATE_AGENT_RUN: unique symbol;
+declare class AgentRun implements RuntimeRunHandle {
+    private readonly host;
+    private readonly publicMessageId;
+    private current;
+    private readonly listeners;
+    private constructor();
+    static [CREATE_AGENT_RUN](host: AgentRunHost, initial: AgentRunRecord, publicMessageId: string): AgentRun;
+    get id(): AgentRunId;
+    get messageId(): string;
+    get status(): AgentRunState;
+    get state(): AgentRunState;
+    getStatus(): Promise<AgentRunState>;
+    subscribe(listener: AgentRunListener): () => void;
+    consumeRuntimeEvents(consumerId: string, listener: RuntimeEventListener): () => void;
+    result(): Promise<Outcome>;
+    abort(reason?: string): Promise<void>;
+    notify(run: AgentRunRecord): void;
+}
+
+type AgentOptions = {
+    context: AgentContext;
+    model: LlmModelRef;
+    stream: StreamFn;
+    cwd?: string;
+    extensions?: LoadedExtension[];
+    maxAttempts?: number;
+    beforeToolCall?: BeforeToolCall;
+    afterToolCall?: AfterToolCall;
+    onMessage?: (message: AgentMessage) => Promise<void>;
+    onOutcome?: (outcome: Outcome) => Promise<void>;
+    onModelTranscript?: (transcript: ModelTranscript, meta: {
+        phase: string;
+        model: LlmModelRef;
+    }) => Promise<void>;
+};
+type AgentCreateOptions = AgentOptions & {
+    input?: string;
+    factoryId?: string;
+};
+type AgentRunControl = {
+    suspend(reason?: string): Promise<void>;
+};
+declare const ATTACH_AGENT: unique symbol;
+declare class Agent {
+    readonly id: AgentId;
+    readonly sessionId: string;
+    private readonly execution;
+    private readonly submitInput;
+    private constructor();
+    static [ATTACH_AGENT](id: AgentId, sessionId: string, execution: AgentExecution, submitInput: (input: AgentMessage) => Promise<AgentRun>): Agent;
+    static loadSkills(targetPath: string): Promise<AgentContext["skills"]>;
+    static loadPhases(targetPath: Parameters<typeof AgentExecution.loadPhases>[0]): Promise<PhaseRegistry>;
+    static loadExtensions(targetPath: string): Promise<LoadExtensionsResult>;
+    subscribe(listener: AgentEventListener): Unsubscribe;
+    flushEvents(): Promise<void>;
+    send(input: string | AgentMessage): Promise<AgentRun>;
+}
+
+declare class InMemorySessionProvider implements SessionManagerProvider {
+    private readonly sessions;
+    create(input: CreateSessionManagerInput): Promise<SessionManager>;
+    open(sessionId: string): Promise<SessionManager | undefined>;
+}
+declare class LocalJsonlSessionProvider implements SessionManagerProvider {
+    private readonly sessionsDir;
+    constructor(sessionsDir: string);
+    create(input: CreateSessionManagerInput): Promise<SessionManager>;
+    open(sessionId: string): Promise<SessionManager | undefined>;
+    list(): Promise<SessionListItem[]>;
 }
 
 type CoreToolContext = {
@@ -1676,129 +1486,99 @@ type CoreToolContext = {
 };
 declare function createCoreTools(input?: CoreToolContext): Tool[];
 
-type ModelConfigFromFile = {
-    id: string;
-    name?: string;
-    primary?: boolean;
-    reasoning?: boolean;
-    input?: ("text" | "image")[];
-    contextWindow?: number;
-    maxTokens?: number;
-    cost?: Partial<ModelCost>;
-};
-type ProviderConfigFromFile = {
-    id: string;
-    name?: string;
-    baseUrl: string;
-    apiKey: string;
-    protocol: Protocol;
-    timeoutMs?: number;
-    maxRetries?: number;
-    retryDelayMs?: number;
-    headers?: Record<string, string>;
-    models: ModelConfigFromFile[];
-};
-type AgentConfigFile = {
-    model?: {
-        provider: string;
-        id: string;
-    };
-    logLevel?: "debug" | "info" | "warn" | "error" | "silent";
-    providers: ProviderConfigFromFile[];
-};
-declare function interpolateEnvVars(value: string): string;
-declare function loadConfigFile(workspace: WorkspacePaths): Promise<AgentConfigFile | undefined>;
-declare function resolveDefaultModel(config: AgentConfigFile): LlmModelRef | undefined;
-declare function registerConfigModels(config: AgentConfigFile): void;
-declare function parseModelRef(input?: string): LlmModelRef | undefined;
-
-/**
- * Push-based async iterable with a final result.
- *
- * Producers call `push(event)` to deliver events. Consumers iterate with
- * `for await (const event of stream)`. The stream terminates when an event
- * matches the `isComplete` predicate; `result()` resolves with the extracted
- * final value.
- */
-declare class EventStream<T, R = T> implements AsyncIterable<T> {
-    private queue;
-    private waiting;
-    private done;
-    private finalResultPromise;
-    private resolveFinalResult;
-    private isComplete;
-    private extractResult;
-    constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R);
-    push(event: T): void;
-    end(result?: R): void;
-    [Symbol.asyncIterator](): AsyncIterator<T>;
-    result(): Promise<R>;
-}
-/**
- * Agent-level event stream that terminates on `agent_end`.
- * `result()` resolves with the final messages array.
- */
-declare class AgentEventStream extends EventStream<AgentEvent, AgentMessage[]> {
-    constructor();
-}
-
-/** Error thrown when the model returns an empty response (no text, no tool calls). */
-declare class EmptyResponseError extends Error {
-    readonly code = "empty_response";
-    constructor(message?: string);
-}
-
-interface SystemPromptOptions {
-    /** Base system prompt. */
-    systemPrompt: string;
-    /** Additional guideline bullets appended to the default runtime instructions. */
-    promptGuidelines?: string[];
-    /** Text to append after the default runtime instructions. */
-    appendSystemPrompt?: string;
-    /** Active tools — snippets and guidelines are included in the prompt. */
-    tools?: Array<{
-        name: string;
-        description?: string;
-        promptSnippet?: string;
-        promptGuidelines?: string[];
+declare class InMemoryRuntimeStateStore implements RuntimeStateStore {
+    private readonly agents;
+    private readonly messages;
+    private readonly runs;
+    private readonly toolCalls;
+    private readonly events;
+    private readonly eventCheckpoints;
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
+    listAgents(): Promise<AgentRecord[]>;
+    setAgentState(agentId: AgentId, state: AgentRecord["state"]): Promise<AgentRecord>;
+    enqueueAgentInput(input: EnqueueAgentInput): Promise<{
+        message: RuntimeMessage;
+        run: AgentRunRecord;
+        resumed: boolean;
     }>;
-    /** Loaded skills — serialized into the prompt. */
-    skills?: Array<{
-        name: string;
-        description: string;
-        filePath: string;
-        disableModelInvocation?: boolean;
-    }>;
-    /** Working directory. */
-    cwd?: string;
+    getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
+    getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
+    listRuns(input?: ListRunsInput): Promise<AgentRunRecord[]>;
+    leaseRun(input: LeaseRunInput): Promise<LeasedRun>;
+    renewLease(input: RenewLeaseInput): Promise<RuntimeLease>;
+    suspendRun(input: SuspendRunInput): Promise<AgentRunRecord>;
+    completeRun(input: CompleteRunInput): Promise<AgentRunRecord>;
+    retryRun(input: RetryRunInput): Promise<AgentRunRecord>;
+    exhaustRun(input: ExhaustRunInput): Promise<AgentRunRecord>;
+    abortRun(input: AbortRunInput): Promise<AgentRunRecord>;
+    recoverExpiredLeases(input?: Date): Promise<AgentRunRecord[]>;
+    recoverLeases(): Promise<AgentRunRecord[]>;
+    createToolCall(input: CreateToolCallInput): Promise<RuntimeToolCall>;
+    startToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall>;
+    completeToolCall(input: CompleteToolCallInput): Promise<RuntimeToolCall>;
+    markToolCallIndeterminate(input: IndeterminateToolCallInput): Promise<RuntimeToolCall>;
+    getToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall | undefined>;
+    listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
+    recordEvent(input: RecordRuntimeEventInput | RuntimeEventKind, related?: Pick<RuntimeEvent, "agentId" | "messageId" | "runId" | "toolCallId">, payload?: unknown): Promise<RuntimeEvent>;
+    getEventCheckpoint(consumerId: string): Promise<RuntimeEventCheckpoint>;
+    acknowledgeEvent(consumerId: string, eventId: RuntimeEventId): Promise<RuntimeEventCheckpoint>;
+    private requireAgent;
+    private requireMessage;
+    private requireRun;
+    private requireToolCall;
+    private recordEventInternal;
 }
-declare function buildSystemPrompt(options: SystemPromptOptions): string;
 
-declare function serializeSkills(skills: Skill$1[]): Array<{
-    name: string;
-    description: string;
-    filePath: string;
-    disableModelInvocation?: boolean;
-}>;
-declare function latestUserInput(messages: AgentMessage[]): string;
-declare function conversationMessages(messages: AgentMessage[]): LlmMessage[];
-/** Input for building an LLM request — generic, not phase-specific. */
-type ModelRequestInput = {
-    systemPrompt: string;
-    messages: AgentMessage[];
-    tools: Array<{
-        name: string;
-        description: string;
-        parameters: unknown;
-        promptSnippet?: string;
-        promptGuidelines?: string[];
+declare class SqliteRuntimeStateStore implements RuntimeStateStore {
+    private readonly database;
+    constructor(filename?: string);
+    close(): void;
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    getAgent(agentId: AgentId): Promise<AgentRecord | undefined>;
+    listAgents(): Promise<AgentRecord[]>;
+    setAgentState(agentId: AgentId, state: AgentRecord["state"]): Promise<AgentRecord>;
+    enqueueAgentInput(input: EnqueueAgentInput): Promise<{
+        message: RuntimeMessage;
+        run: AgentRunRecord;
+        resumed: boolean;
     }>;
-    skills: Skill$1[];
-    promptGuidelines?: string[];
-    appendSystemPrompt?: string;
-};
-declare function buildModelRequest(input: ModelRequestInput, options?: {
-    model?: LlmModelRef;
-}): LlmRequest;
+    getMessage(messageId: RuntimeMessageId): Promise<RuntimeMessage | undefined>;
+    getRun(runId: AgentRunId): Promise<AgentRunRecord | undefined>;
+    listRuns(input?: ListRunsInput): Promise<AgentRunRecord[]>;
+    leaseRun(input: LeaseRunInput): Promise<LeasedRun>;
+    renewLease(input: RenewLeaseInput): Promise<RuntimeLease>;
+    suspendRun(input: SuspendRunInput): Promise<AgentRunRecord>;
+    completeRun(input: CompleteRunInput): Promise<AgentRunRecord>;
+    retryRun(input: RetryRunInput): Promise<AgentRunRecord>;
+    exhaustRun(input: ExhaustRunInput): Promise<AgentRunRecord>;
+    abortRun(input: AbortRunInput): Promise<AgentRunRecord>;
+    recoverExpiredLeases(input?: Date): Promise<AgentRunRecord[]>;
+    recoverLeases(): Promise<AgentRunRecord[]>;
+    createToolCall(input: CreateToolCallInput): Promise<RuntimeToolCall>;
+    startToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall>;
+    completeToolCall(input: CompleteToolCallInput): Promise<RuntimeToolCall>;
+    markToolCallIndeterminate(input: IndeterminateToolCallInput): Promise<RuntimeToolCall>;
+    getToolCall(toolCallId: RuntimeToolCallId): Promise<RuntimeToolCall | undefined>;
+    listEvents(cursor?: RuntimeEventCursor): Promise<RuntimeEvent[]>;
+    recordEvent(input: RecordRuntimeEventInput | RuntimeEventKind, related?: Pick<RuntimeEvent, "agentId" | "messageId" | "runId" | "toolCallId">, payload?: unknown): Promise<RuntimeEvent>;
+    getEventCheckpoint(consumerId: string): Promise<RuntimeEventCheckpoint>;
+    acknowledgeEvent(consumerId: string, eventId: RuntimeEventId): Promise<RuntimeEventCheckpoint>;
+    private insertMessage;
+    private agentFromRow;
+    private messageFromRow;
+    private runFromRow;
+    private eventFromRow;
+    private toolCallFromRow;
+    private messageRow;
+    private runRow;
+    private requireAgent;
+    private requireMessage;
+    private requireRun;
+    private requireToolCall;
+    private requireEvent;
+    private eventCheckpoint;
+    private recordEventInternal;
+}
 
-export { type AbortEvent, type AfterPhaseEvent, type AfterPhaseHookResult, type AfterPhaseResult, type AfterToolCallEvent, type AfterToolCallResult, Agent, type AgentConfigFile, type AgentContext, type AgentEndEvent, AgentEventStream, type AgentOptions, type AgentStartEvent, type AgentStatus, type BeforePhaseEvent, type BeforePhaseHookResult, type BeforePhaseResult, type BeforePromptEvent, type BeforePromptResult, type BeforeToolCallEvent, type BeforeToolCallResult, EmptyResponseError, type EventBus, EventStream, type ExecOptions, type ExecResult, type ExecutionTurn, type Extension, type ExtensionAPI, type ExtensionContext, type ExtensionError, type ExtensionErrorListener, type ExtensionFactory, type ExtensionManifest, type ExtensionPackageManifest, ExtensionRunner, type ExtensionRunnerOptions, type ExtensionRuntime, type ExtensionUtils, HookError, type HookEvent, type HookEventType, type HookHandler, type HookResultMap, HooksManager, type LoadExtensionsResult, type LoadedExtension, LocalJsonlSessionManager, type LoopMetrics, type MessageEndEvent, type MessageStartEvent, type MessageUpdateEvent, type ModelConfigFromFile, type ModelTranscript, type Phase, type PhaseContext, type PhaseDefinition, type PhaseExecution, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseRun, type PhaseState, type ProviderConfigFromFile, type QueueUpdateEvent, type RegisteredPhase, type RegisteredTool, type RunOptions, type RunResult, type SavePointEvent, type Session, type SessionListItem, type SettledEvent, type SourceInfo, type Tool, type ToolDefinition, type ToolExecutionEndEvent, type ToolExecutionResult, type ToolExecutionStartEvent, type ToolExecutionUpdateEvent, type TurnEndEvent, type TurnStartEvent, type WorkspacePaths, appendUserTurn, buildModelRequest, buildSystemPrompt, conversationMessages, createCoreTools, createEventBus, createExtension, createExtensionAPI, createExtensionRunner, createExtensionRuntime, createId, createMessage, createSession, createSourceInfo, createTimestamp, getGlobalHooks, interpolateEnvVars, latestUserInput, loadConfigFile, loadPhase, loadPhases, messageContentText, parseModelRef, registerConfigModels, reloadPhases, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, resolveWorkspacePaths, serializeSkills };
+export { type AfterToolCall, Agent, type AgentContext, type AgentCreateOptions, type AgentFactory, type AgentFactoryIdentity, type AgentId, type AgentOptions, AgentRun, type AgentRunId, type AgentRunListener, type AgentRunState, AgentRuntime, type AgentRuntimeOptions, type BeforeToolCall, type CoreToolContext, type ExecutionTurn, type ExtensionAPI, type ExtensionFactory, type HookEvent, type HookEventType, type HookHandler, InMemoryRuntimeStateStore, InMemorySessionProvider, type LoadExtensionsResult, type LoadedExtension, LocalJsonlSessionProvider, type LoopMetrics, type ModelTranscript, type Phase, type PhaseContext, type PhaseExecution, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseState, type RuntimeEvent, type RuntimeEventCursor, type RuntimeEventKind, type RuntimeEventListener, type SessionManagerProvider, SqliteRuntimeStateStore, type Tool, type ToolContext, type ToolDefinition, type ToolExecutionMode, type ToolExecutionResult, type ToolRuntimePolicy, type Unsubscribe, createCoreTools, createMessage };