@rowan-agent/agent 0.4.4

package/dist/index.d.cts

@@ -0,0 +1,2049 @@
+import { AgentContextMessage, AgentContextSkill, LlmModelRef, LlmModelUsage, ToolCall, ToolResult, Outcome, LlmToolChoice, ContentBlock, LlmRequest, ProviderConfig, StreamFn, AgentEventListener, AgentEvent, LlmMessage } from '@rowan-agent/models';
+export { AgentEvent, AgentEventListener, LlmModelRef, Outcome, StreamFn, ToolResult } from '@rowan-agent/models';
+import Type from 'typebox';
+
+type AgentRunLimits = {
+    /** Maximum number of phase iterations before forcing stop. Default: 50. */
+    maxIterations?: number;
+    /** Maximum consecutive "continue" rounds within a single phase before forcing transition. Default: 10. */
+    maxPhaseRounds?: number;
+};
+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 AgentRunState = {
+    agentState: AgentState;
+    currentPhase: string;
+    attempt: number;
+    transcript: AgentMessage$1[];
+    /** Loop execution metrics. */
+    metrics: LoopMetrics;
+};
+
+type AgentContextState = {
+    version: string;
+    id: string;
+    parentSessionId?: string;
+    systemPrompt: string;
+    input: string;
+    messages: AgentContextMessage[];
+    skills: AgentContextSkill[];
+    createdAt: string;
+    updatedAt: string;
+    title?: 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;
+    /** 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;
+};
+
+type LoopPhase = "chat" | "plan" | "execute" | "verify";
+
+type ExecutionTurnEntry = {
+    kind: "prompt";
+    message: Pick<AgentContextMessage, "role" | "content">;
+} | {
+    kind: "assistant_text";
+    text: string;
+} | {
+    kind: "tool_call";
+    toolCall: ToolCall;
+} | {
+    kind: "tool_result";
+    result: ToolResult;
+};
+type ExecutionTurn = {
+    id: string;
+    sessionId: string;
+    parentSessionId?: string;
+    phase: LoopPhase;
+    requestedAtMs: number;
+    completedAtMs: number;
+    model: LlmModelRef;
+    usage?: LlmModelUsage;
+    entries: ExecutionTurnEntry[];
+};
+type StepFilter = {
+    phase?: LoopPhase;
+    afterMs?: number;
+};
+
+declare const AGENT_STATE_SCHEMA_VERSION = "0.4.4";
+type AgentMessage$1 = AgentContextMessage;
+type Skill$1 = AgentContextSkill;
+type AgentState = {
+    version: string;
+    id: string;
+    parentSessionId?: string;
+    systemPrompt: string;
+    input: string;
+    messages: AgentMessage$1[];
+    skills: Skill$1[];
+    createdAt: string;
+    updatedAt: string;
+    title?: string;
+};
+type CreateAgentStateInput = {
+    id?: string;
+    systemPrompt: string;
+    input: string;
+    skills?: Skill$1[];
+    parentSessionId?: string;
+    title?: string;
+    messages?: AgentMessage$1[];
+};
+type ToolContext$1 = {
+    state: AgentState;
+    toolCallId: string;
+};
+type ToolExecutionMode$1 = "sequential" | "parallel";
+type Tool$1<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$1;
+    execute(args: TArgs, context: ToolContext$1, 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$1[];
+    /** Tools available for this run. */
+    tools?: Tool$1[];
+    /** Skills available for this run. */
+    skills?: Skill$1[];
+};
+type BeforeToolCall = (input: {
+    tool: Tool$1;
+    args: unknown;
+}) => Promise<{
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+}>;
+type AfterToolCall = (input: {
+    tool: Tool$1;
+    result: ToolResult;
+}) => Promise<ToolResult>;
+type RunResult = {
+    sessionId: string;
+    messages: AgentMessage$1[];
+    outcome: Outcome;
+    metrics: LoopMetrics;
+};
+type Unsubscribe = () => void;
+declare function createMessage(role: AgentMessage$1["role"], content: string, metadata?: Record<string, unknown>): AgentMessage$1;
+declare function createAgentState(input: CreateAgentStateInput): AgentState;
+
+declare function createId(prefix: string): string;
+declare function createTimestamp(date?: Date): string;
+declare const createJson: {
+    "new"<T>(value: T): T;
+    stringify(value: unknown): string;
+};
+
+/** Unified phase input — contains everything the model needs. */
+type PhaseInput = {
+    phase: string;
+    systemPrompt: string;
+    messages: AgentMessage$1[];
+    /** All tools (for systemPrompt display, cache-friendly) */
+    tools: Tool$1[];
+    /** All skills (for systemPrompt display) */
+    skills: Skill$1[];
+    /** Phase-specific filtered tools (for LlmRequest.tools) */
+    phaseTools?: Tool$1[];
+    /** Phase-specific filtered skills */
+    phaseSkills?: Skill$1[];
+    /** Additional guideline bullets appended to the system prompt. */
+    promptGuidelines?: string[];
+    /** Text to append after the system prompt. */
+    appendSystemPrompt?: string;
+    /** Tool choice configuration from phase definition */
+    toolChoice?: LlmToolChoice;
+};
+type PhaseManifest = {
+    id: string;
+    name: string;
+    description: string;
+    /** Tools available in this phase. If omitted, all tools are available. */
+    tools?: string[];
+    /** Skills available in this phase. If omitted, all skills are available. */
+    skills?: string[];
+};
+type PhaseRun = (context: PhaseContext, input: PhaseInput) => Promise<PhaseOutput | void>;
+type PhaseDefinition = PhaseManifest & {
+    run?: PhaseRun;
+    buildPrompt?(input: PhaseInput): LlmRequest;
+};
+type ModelInvokeOutput = {
+    text: string;
+    contentBlocks: ContentBlock[];
+    toolCalls: ToolCall[];
+    stopReason?: string;
+};
+type ModelInvokeInput = {
+    input: PhaseInput;
+    /** Auto-execute tools and record results to message history */
+    autoExecuteTools?: boolean;
+    /** Max tool execution rounds (default: 10) */
+    maxToolRounds?: number;
+    /** Tool names to exclude from auto-execution (e.g. ["route"]) */
+    excludeTools?: string[];
+};
+/** Message lifecycle manager for streaming updates */
+/** Snapshot of message state, used for restore */
+type MessageSnapshot = {
+    transcriptLength: number;
+    stateMessagesLength: number;
+};
+type PhaseMessageManager = {
+    /** Get all visible messages in the transcript */
+    visible(): AgentMessage$1[];
+    /** Start a new message stream, returns message id */
+    start(role: "assistant" | "tool", content: string, metadata?: Record<string, unknown>): string;
+    /** Stream a text delta */
+    update(messageId: string, delta: string): Promise<void>;
+    /** End the message stream, appends to transcript */
+    end(messageId: string): Promise<void>;
+    /** Delete a single message by id or index */
+    delete(target: string | number): void;
+    /** Insert a message before a target (by id or index) */
+    insert(target: string | number, message: AgentMessage$1): void;
+    /** Clear all messages from transcript and state */
+    clear(): void;
+    /** Capture current message state for later restore */
+    snapshot(): MessageSnapshot;
+    /** Restore message state to a previous snapshot, discarding messages added after it */
+    restore(snap: MessageSnapshot): void;
+};
+/** Tool execution lifecycle manager */
+type PhaseToolExecutionManager = {
+    /** Start tool execution */
+    start(toolCallId: string, toolName: string, args: unknown): Promise<void>;
+    /** Update tool execution progress */
+    update(toolCallId: string, partialResult: unknown): Promise<void>;
+    /** End tool execution */
+    end(toolCallId: string, toolName: string, result: ToolResult, isError: boolean): Promise<void>;
+};
+type PhaseContext = {
+    phaseId: string;
+    state: AgentRunState;
+    messages: PhaseMessageManager;
+    toolExecution: PhaseToolExecutionManager;
+    model: {
+        invoke(input: ModelInvokeInput): Promise<ModelInvokeOutput>;
+    };
+    tools: {
+        execute(input: {
+            toolCall: ToolCall;
+        }): Promise<ToolResult>;
+    };
+    skills: AgentState["skills"];
+    turn<T>(fn: () => Promise<T>): Promise<T>;
+    maxAttempts?: number;
+    incrementAttempt(): void;
+    availablePhases: Array<{
+        id: string;
+        name: string;
+        description: string;
+    }>;
+    /** Extract route decision from tool calls. Returns undefined if no route tool call found. */
+    routeDecision(toolCalls: ToolCall[]): {
+        route: string;
+        reason?: string;
+    } | undefined;
+};
+type PhaseRegistry = {
+    entryPhaseId: string;
+    phases: PhaseDefinition[];
+};
+type PhaseRegistryInput = {
+    entryPhaseId?: string;
+    phases?: PhaseDefinition[];
+};
+declare function definePhase(definition: PhaseDefinition): PhaseDefinition;
+declare function createPhaseRegistry(input: PhaseRegistryInput): PhaseRegistry;
+declare const DEFAULT_PHASE_ID: string;
+
+/**
+ * Source info — tracks where an extension registration came from.
+ */
+interface SourceInfo {
+    /** Source type: "local" for filesystem, "builtin" for built-in, etc. */
+    source: string;
+    /** Base directory for resolving relative paths. */
+    baseDir?: string;
+    /** Display name for error messages. */
+    displayName?: string;
+}
+declare function createSourceInfo(extensionPath: string, options?: {
+    source?: string;
+    baseDir?: string;
+}): SourceInfo;
+
+/**
+ * Extension types — simplified for the new hook-based system.
+ */
+
+/** Declarative prompt configuration — alternative to implementing buildPrompt. */
+type PhasePromptConfig = {
+    /** Lines to append as a user message with phase instructions. */
+    instructions?: string[];
+};
+type PhaseRegistration = Partial<PhaseManifest> & {
+    /** Optional execution override — takes over model invocation */
+    run?: PhaseRun;
+    /** Declarative prompt config — framework generates buildPrompt from this */
+    prompt?: PhasePromptConfig;
+    /** Custom prompt builder — overrides prompt config if provided */
+    buildPrompt?: (input: PhaseInput) => LlmRequest;
+};
+type RegisteredPhase = {
+    definition: PhaseDefinition;
+    handler: {
+        buildPrompt?: (input: PhaseInput) => LlmRequest;
+    };
+    source: {
+        extensionPath: string;
+    };
+};
+type ExtensionPackageManifest = {
+    rowan?: {
+        extensions?: string[];
+        phase?: PhaseManifest;
+    };
+};
+/**
+ * Tool definition for registering LLM-callable tools via `api.registerTool()`.
+ *
+ * @example
+ * ```typescript
+ * api.registerTool({
+ *   name: "search_docs",
+ *   description: "Search documentation",
+ *   parameters: { type: "object", properties: { query: { type: "string" } } },
+ *   execute: async (args, ctx) => {
+ *     return { content: [{ type: "text", text: "result" }] };
+ *   },
+ * });
+ * ```
+ */
+interface ToolDefinition {
+    /** Tool name (used in LLM tool calls) */
+    name: string;
+    /** Description for LLM */
+    description: string;
+    /** Parameter schema (JSON Schema) */
+    parameters: Record<string, unknown>;
+    /** Execute the tool */
+    execute: (args: unknown, signal?: AbortSignal) => Promise<ToolExecutionResult>;
+    /** Optional: per-tool execution mode override */
+    executionMode?: "sequential" | "parallel";
+}
+/**
+ * Result from tool execution.
+ */
+interface ToolExecutionResult {
+    /** Content blocks to return to the LLM */
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    /** 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;
+    /** Environment variables to add/override. */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds. */
+    timeout?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+};
+type ExecResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+type BeforePhaseHookResult = {
+    abort?: Outcome;
+    skip?: {
+        route: string;
+        message: string;
+    };
+    input?: PhaseInput;
+};
+type AfterPhaseHookResult = {
+    abort?: Outcome;
+    retry?: PhaseInput;
+    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 `<builtin:phase:chat>`) */
+    path: string;
+    /** Resolved absolute path */
+    resolvedPath: 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, resolvedPath: 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.
+ */
+type LoadExtensionsResult = {
+    extensions: LoadedExtension[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+};
+/**
+ * Pre-initialization extension form — factory + metadata.
+ * Runner.loadExtensions() calls the factory and creates the full Extension object.
+ */
+interface LoadedExtension {
+    path: string;
+    resolvedPath: string;
+    name: string;
+    factory: (api: any) => void | Promise<void>;
+    manifest?: ExtensionManifest;
+}
+/** Extension manifest from package.json `rowan` field. */
+interface ExtensionManifest {
+    entry?: string;
+    name?: string;
+    phase?: {
+        id?: string;
+        name?: string;
+        description?: string;
+        tools?: string[];
+        skills?: string[];
+    };
+}
+
+/**
+ * EventBus — simple pub/sub for inter-extension communication.
+ *
+ * Extensions can emit and subscribe to arbitrary events via `api.events`.
+ * This allows extensions to coordinate without direct coupling.
+ *
+ * @example
+ * ```typescript
+ * // Extension A
+ * api.events.on("my-plugin:ready", (data) => {
+ *   console.log("Plugin ready:", data);
+ * });
+ *
+ * // Extension B
+ * api.events.emit("my-plugin:ready", { version: "1.0" });
+ * ```
+ */
+type Listener = (...args: unknown[]) => void;
+interface EventBus {
+    /** Subscribe to an event. Returns unsubscribe function. */
+    on(event: string, listener: Listener): () => void;
+    /** Emit an event to all subscribers. */
+    emit(event: string, ...args: unknown[]): void;
+    /** Remove all listeners for an event, or all listeners if no event specified. */
+    off(event?: string): void;
+    /** Check if there are listeners for an event. */
+    has(event: string): boolean;
+    /** Get listener count for an event. */
+    count(event: string): number;
+}
+declare function createEventBus(): EventBus;
+
+/**
+ * @module extensions/hooks
+ *
+ * Type-safe hook system
+ *
+ * ## Overview
+ *
+ * The hook system allows extensions to intercept and modify Agent behavior at specific points.
+ *
+ * ## Hook Categories
+ *
+ * ### Modifiable (return result to change behavior)
+ *
+ * | Hook | Return | Effect |
+ * |------|--------|--------|
+ * | `before_phase` | `{ abort?, skip?, input? }` | Abort, skip, or modify phase input |
+ * | `after_phase` | `{ abort?, retry?, output? }` | Abort, retry, or replace phase output |
+ * | `before_prompt` | `{ input? }` | Modify input sent to LLM |
+ * | `before_tool_call` | `{ allow, reason? }` | Allow/block tool execution |
+ * | `after_tool_call` | `{ result? }` | Modify tool execution result |
+ *
+ * ### Listen-only (return void)
+ *
+ * | Hook | Trigger |
+ * |------|---------|
+ * | `agent_start` | Agent starts |
+ * | `agent_end` | Agent ends |
+ * | `turn_start` | Conversation turn starts |
+ * | `turn_end` | Conversation turn ends |
+ * | `message_start` | Message streaming starts |
+ * | `message_update` | Message streaming update |
+ * | `message_end` | Message completes |
+ * | `tool_execution_start` | Tool execution starts |
+ * | `tool_execution_update` | Tool execution progress update |
+ * | `tool_execution_end` | Tool execution completes |
+ * | `queue_update` | Queue state update |
+ * | `save_point` | Session save point |
+ * | `abort` | Agent aborted |
+ * | `settled` | Agent idle |
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * import type { ExtensionAPI } from "@rowan-agent/agent";
+ *
+ * export default function(api: ExtensionAPI) {
+ *   // Block dangerous tools
+ *   api.on("before_tool_call", (event) => {
+ *     if (event.tool.name === "bash") {
+ *       const cmd = (event.args as any).command;
+ *       if (cmd.includes("rm -rf")) {
+ *         return { allow: false, reason: "Dangerous command" };
+ *       }
+ *     }
+ *     return { allow: true };
+ *   });
+ *
+ *   // Inject context
+ *   api.on("before_prompt", (event) => {
+ *     return {
+ *       input: {
+ *         ...event.input,
+ *         systemPrompt: event.input.systemPrompt + "\n\nExtra context",
+ *       },
+ *     };
+ *   });
+ *
+ *   // Log tool calls
+ *   api.on("tool_execution_end", (event) => {
+ *     console.log(`Tool ${event.toolName}: ${event.result.ok ? "success" : "failed"}`);
+ *   });
+ * }
+ * ```
+ */
+
+/**
+ * before_phase event - triggered before phase execution
+ *
+ * Return `{ abort }` to abort the agent.
+ * Return `{ skip: { route, message } }` to skip the phase.
+ * Return `{ input }` to replace the phase input.
+ */
+interface BeforePhaseEvent {
+    type: "before_phase";
+    /** Phase ID about to execute */
+    phaseId: string;
+    /** Phase input */
+    input: PhaseInput;
+}
+/**
+ * after_phase event - triggered after phase execution
+ *
+ * Return `{ abort }` to abort the agent.
+ * Return `{ retry }` to re-execute the phase with new input.
+ * Return `{ output }` to replace the phase output.
+ */
+interface AfterPhaseEvent {
+    type: "after_phase";
+    /** Phase ID that completed */
+    phaseId: string;
+    /** Phase output */
+    output: PhaseOutput;
+}
+/**
+ * before_prompt event - triggered before building LLM request
+ *
+ * Return `{ input }` to replace the input sent to LLM.
+ */
+interface BeforePromptEvent {
+    type: "before_prompt";
+    /** Current phase ID */
+    phaseId: string;
+    /** Phase input (modifiable) */
+    input: PhaseInput;
+}
+/**
+ * before_tool_call event - triggered before tool execution
+ *
+ * Return `{ allow: false, reason }` to block execution.
+ * Return `{ allow: true }` to allow execution.
+ */
+interface BeforeToolCallEvent {
+    type: "before_tool_call";
+    /** Tool definition */
+    tool: Tool$1;
+    /** Tool arguments */
+    args: unknown;
+}
+/**
+ * after_tool_call event - triggered after tool execution
+ *
+ * Return `{ result }` to replace the tool execution result.
+ */
+interface AfterToolCallEvent {
+    type: "after_tool_call";
+    /** Tool definition */
+    tool: Tool$1;
+    /** Tool execution result */
+    result: ToolResult;
+}
+/**
+ * agent_start event - triggered when agent starts
+ */
+interface AgentStartEvent {
+    type: "agent_start";
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * agent_end event - triggered when agent ends
+ */
+interface AgentEndEvent {
+    type: "agent_end";
+    /** Session ID */
+    sessionId: string;
+    /** Execution outcome */
+    outcome: Outcome;
+    /** All messages */
+    messages: AgentMessage$1[];
+}
+/**
+ * turn_start event - triggered when conversation turn starts
+ */
+interface TurnStartEvent {
+    type: "turn_start";
+    /** Current message list */
+    messages: AgentMessage$1[];
+}
+/**
+ * turn_end event - triggered when conversation turn ends
+ */
+interface TurnEndEvent {
+    type: "turn_end";
+    /** Message list */
+    messages: AgentMessage$1[];
+    /** Turn outcome (optional) */
+    outcome?: Outcome;
+}
+/**
+ * message_start event - triggered when message streaming starts
+ */
+interface MessageStartEvent {
+    type: "message_start";
+    /** Message object */
+    message: AgentMessage$1;
+}
+/**
+ * message_update event - triggered on message streaming update
+ */
+interface MessageUpdateEvent {
+    type: "message_update";
+    /** Message object */
+    message: AgentMessage$1;
+    /** Delta text */
+    delta: string;
+}
+/**
+ * message_end event - triggered when message completes
+ */
+interface MessageEndEvent {
+    type: "message_end";
+    /** Message object */
+    message: AgentMessage$1;
+}
+/**
+ * tool_execution_start event - triggered when tool execution starts
+ */
+interface ToolExecutionStartEvent {
+    type: "tool_execution_start";
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name */
+    toolName: string;
+    /** Tool arguments */
+    args: unknown;
+}
+/**
+ * tool_execution_update event - triggered on tool execution progress
+ */
+interface ToolExecutionUpdateEvent {
+    type: "tool_execution_update";
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name */
+    toolName: string;
+}
+/**
+ * tool_execution_end event - triggered when tool execution completes
+ */
+interface ToolExecutionEndEvent {
+    type: "tool_execution_end";
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name */
+    toolName: string;
+    /** Tool execution result */
+    result: ToolResult;
+}
+/**
+ * queue_update event - triggered on queue state update
+ */
+interface QueueUpdateEvent {
+    type: "queue_update";
+    /** Pending message count */
+    pendingCount: number;
+}
+/**
+ * save_point event - triggered at session save point
+ */
+interface SavePointEvent {
+    type: "save_point";
+    /** Whether there are pending mutations */
+    hadPendingMutations: boolean;
+}
+/**
+ * abort event - triggered when agent is aborted
+ */
+interface AbortEvent {
+    type: "abort";
+    /** Abort reason */
+    reason?: string;
+}
+/**
+ * settled event - triggered when agent is idle
+ */
+interface SettledEvent {
+    type: "settled";
+}
+/** Union type of all hook events */
+type HookEvent = BeforePhaseEvent | AfterPhaseEvent | BeforePromptEvent | BeforeToolCallEvent | AfterToolCallEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | QueueUpdateEvent | SavePointEvent | AbortEvent | SettledEvent;
+/**
+ * before_phase hook return value
+ *
+ * - `abort`: Abort the entire agent
+ * - `skip`: Skip current phase, route to specified phase
+ * - `input`: Replace phase input
+ */
+interface BeforePhaseResult {
+    /** Abort agent */
+    abort?: Outcome;
+    /** Skip current phase */
+    skip?: {
+        route: string;
+        message: string;
+    };
+    /** Replace phase input */
+    input?: PhaseInput;
+}
+/**
+ * after_phase hook return value
+ *
+ * - `abort`: Abort the entire agent
+ * - `retry`: Re-execute phase with new input
+ * - `output`: Replace phase output
+ */
+interface AfterPhaseResult {
+    /** Abort agent */
+    abort?: Outcome;
+    /** Re-execute phase */
+    retry?: PhaseInput;
+    /** Replace phase output */
+    output?: PhaseOutput;
+}
+/**
+ * before_prompt hook return value
+ *
+ * - `input`: Replace input sent to LLM
+ */
+interface BeforePromptResult {
+    /** Replace phase input */
+    input?: PhaseInput;
+}
+/**
+ * before_tool_call hook return value
+ *
+ * - `allow`: Whether to allow execution
+ * - `reason`: Rejection reason (when allow=false)
+ */
+interface BeforeToolCallResult {
+    /** Whether to allow execution */
+    allow: boolean;
+    /** Rejection reason */
+    reason?: string;
+}
+/**
+ * after_tool_call hook return value
+ *
+ * - `result`: Replace tool execution result
+ */
+interface AfterToolCallResult {
+    /** Replace tool execution result */
+    result?: ToolResult;
+}
+/**
+ * Hook result mapping table.
+ *
+ * Defines the return type for each hook event:
+ * - Modifiable hooks return specific objects
+ * - Listen-only hooks return undefined
+ */
+interface HookResultMap {
+    before_phase: BeforePhaseResult | undefined;
+    after_phase: AfterPhaseResult | undefined;
+    before_prompt: BeforePromptResult | undefined;
+    before_tool_call: BeforeToolCallResult | undefined;
+    after_tool_call: AfterToolCallResult | undefined;
+    agent_start: undefined;
+    agent_end: undefined;
+    turn_start: undefined;
+    turn_end: undefined;
+    message_start: undefined;
+    message_update: undefined;
+    message_end: undefined;
+    tool_execution_start: undefined;
+    tool_execution_update: undefined;
+    tool_execution_end: undefined;
+    queue_update: undefined;
+    save_point: undefined;
+    abort: undefined;
+    settled: undefined;
+}
+/** Hook event type string */
+type HookEventType = HookEvent["type"];
+/**
+ * Hook handler type.
+ *
+ * @typeParam K - Hook event type
+ * @param event - Event object
+ * @returns Result object or void
+ */
+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 collect all non-undefined results.
+     *
+     * @param eventType - Event type
+     * @param event - Event object
+     * @returns Array of non-undefined results
+     */
+    emitCollect<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
+        type: K;
+    }>): Promise<Array<NonNullable<HookResultMap[K]>>>;
+    /**
+     * 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>;
+    /**
+     * Emit event and aggregate results with reducer.
+     *
+     * @param eventType - Event type
+     * @param event - Event object
+     * @param reducer - Aggregation function
+     * @param initial - Initial value
+     * @returns Aggregated result
+     */
+    emitReduce<K extends HookEventType, T>(eventType: K, event: Extract<HookEvent, {
+        type: K;
+    }>, reducer: (acc: T, result: NonNullable<HookResultMap[K]>) => T, initial: T): Promise<T>;
+}
+/**
+ * Get global hooks manager instance (singleton).
+ */
+declare function getGlobalHooks(): HooksManager;
+/**
+ * Reset global hooks manager (mainly for testing).
+ */
+declare function resetGlobalHooks(): void;
+
+/**
+ * @module extensions/context
+ *
+ * ExtensionAPI - Main API for extension developers
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import type { ExtensionAPI } from "@rowan-agent/agent";
+ *
+ * export default function(api: ExtensionAPI) {
+ *   // 1. Subscribe to hooks
+ *   api.on("before_tool_call", (event) => {
+ *     console.log(`Tool: ${event.tool.name}`);
+ *     return { allow: true };
+ *   });
+ *
+ *   // 2. Register custom tool
+ *   api.registerTool({
+ *     name: "search_docs",
+ *     description: "Search documentation",
+ *     parameters: { type: "object", properties: { query: { type: "string" } } },
+ *     execute: async (args) => {
+ *       return { content: [{ type: "text", text: "result" }] };
+ *     },
+ *   });
+ *
+ *   // 3. Register custom phase
+ *   api.registerPhase({
+ *     ...api.manifest?.phase,  // Read metadata from package.json
+ *     id: "my-phase",
+ *     run: async (context, input) => {
+ *       return { message: "Done", route: "stop" };
+ *     },
+ *   });
+ *
+ *   // 4. Register model provider
+ *   api.registerProvider({
+ *     name: "custom",
+ *     baseUrl: "https://api.example.com",
+ *     api: "openai-completions",
+ *     models: [...],
+ *   });
+ *
+ *   // 5. Inter-extension communication
+ *   api.events.on("other-plugin:ready", (data) => {
+ *     console.log("Plugin ready:", data);
+ *   });
+ * }
+ * ```
+ *
+ * ## Available Hooks
+ *
+ * | Hook | Trigger | Return |
+ * |------|---------|--------|
+ * | `before_phase` | Before phase execution | `{ abort?, skip?, input? }` |
+ * | `after_phase` | After phase execution | `{ abort?, retry?, output? }` |
+ * | `before_prompt` | Before building LLM request | `{ input? }` |
+ * | `before_tool_call` | Before tool execution | `{ allow, reason? }` |
+ * | `after_tool_call` | After tool execution | `{ result? }` |
+ * | `agent_start` | Agent starts | Listen only |
+ * | `agent_end` | Agent ends | Listen only |
+ * | `message_*` | Message lifecycle | Listen only |
+ * | `tool_execution_*` | Tool execution lifecycle | Listen only |
+ */
+
+/**
+ * Extension API object passed to extension factory function.
+ *
+ * @example
+ * ```typescript
+ * export default function(api: ExtensionAPI) {
+ *   // api provides all extension APIs
+ * }
+ * ```
+ */
+interface ExtensionAPI {
+    /**
+     * Subscribe to a hook event.
+     *
+     * @param eventType - Hook type, e.g. "before_tool_call"
+     * @param handler - Hook handler, can return result to modify behavior
+     *
+     * @example
+     * ```typescript
+     * ctx.on("before_tool_call", (event) => {
+     *   // event contains { tool, args }
+     *   if (event.tool.name === "bash") {
+     *     return { allow: false, reason: "Blocked" };
+     *   }
+     *   return { allow: true };
+     * });
+     * ```
+     */
+    on<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
+    /**
+     * Unsubscribe from a hook event.
+     */
+    off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
+    /**
+     * Register a custom LLM-callable tool.
+     *
+     * @param tool - Tool definition with name, description, parameters, and execute function
+     *
+     * @example
+     * ```typescript
+     * api.registerTool({
+     *   name: "search_docs",
+     *   description: "Search project documentation",
+     *   parameters: {
+     *     type: "object",
+     *     properties: { query: { type: "string" } },
+     *     required: ["query"],
+     *   },
+     *   execute: async (args, signal) => {
+     *     const query = (args as any).query;
+     *     return { content: [{ type: "text", text: `Results for: ${query}` }] };
+     *   },
+     * });
+     * ```
+     */
+    registerTool(tool: ToolDefinition): void;
+    /**
+     * Register a custom phase.
+     *
+     * Phases are state machine nodes that can be referenced by the routing system.
+     *
+     * @param registration - Phase registration info
+     *
+     * @example
+     * ```typescript
+     * ctx.registerPhase({
+     *   id: "review",
+     *   name: "Code Review",
+     *   description: "Review code changes",
+     *
+     *   // Optional: declarative prompt config
+     *   prompt: {
+     *     instructions: [
+     *       "Phase: review",
+     *       "Review code changes, call route tool if looks good",
+     *     ],
+     *   },
+     *
+     *   // Optional: custom execution logic
+     *   async run(context, input) {
+     *     const result = await context.model.invoke({ input });
+     *     return { message: result.text, route: "stop" };
+     *   },
+     * });
+     * ```
+     */
+    registerPhase(registration: PhaseRegistration): void;
+    /**
+     * Register a model provider.
+     *
+     * @param config - Provider configuration
+     *
+     * @example
+     * ```typescript
+     * ctx.registerProvider({
+     *   name: "custom-llm",
+     *   baseUrl: "https://api.custom.com/v1",
+     *   api: "openai-completions",
+     *   models: [{
+     *     id: "custom-7b",
+     *     name: "Custom 7B",
+     *     api: "openai-completions",
+     *     reasoning: false,
+     *     input: ["text"],
+     *     cost: { input: 0.1, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+     *     contextWindow: 8192,
+     *     maxTokens: 4096,
+     *   }],
+     * });
+     * ```
+     */
+    registerProvider(config: ProviderConfig): void;
+    /**
+     * Unregister a model provider.
+     */
+    unregisterProvider(name: string): void;
+    /**
+     * Extension manifest from package.json `rowan` field.
+     *
+     * Can be used to auto-fill phase metadata:
+     * ```typescript
+     * ctx.registerPhase({
+     *   ...ctx.manifest?.phase,  // Auto-fill id, name, description
+     *   run: async (context, input) => { ... },
+     * });
+     * ```
+     */
+    manifest?: ExtensionManifest;
+    /**
+     * Utility functions.
+     */
+    utils: ExtensionUtils;
+    /**
+     * Runtime context — provides access to agent state, cwd, and utilities.
+     *
+     * Available after extension loading completes. Use for runtime operations
+     * like executing shell commands or checking agent state.
+     */
+    context: ExtensionContext;
+    /**
+     * Shared event bus for inter-extension communication.
+     *
+     * Extensions can emit and subscribe to arbitrary events to coordinate
+     * without direct coupling.
+     *
+     * @example
+     * ```typescript
+     * // Extension A
+     * api.events.on("my-plugin:ready", (data) => {
+     *   console.log("Plugin ready:", data);
+     * });
+     *
+     * // Extension B
+     * api.events.emit("my-plugin:ready", { version: "1.0" });
+     * ```
+     */
+    events: EventBus;
+}
+/**
+ * Runtime context available to extensions during event handler execution.
+ *
+ * Provides access to agent state, working directory, and utility methods.
+ * Values are resolved lazily via getters, so changes via `runner.bind()` are
+ * reflected immediately without recreating the context.
+ *
+ * This is distinct from ExtensionAPI (which is for registration) —
+ * ExtensionContext gives runtime state during hook execution.
+ *
+ * @example
+ * ```typescript
+ * api.on("before_tool_call", (event, ctx) => {
+ *   console.log(`cwd: ${ctx.cwd}`);
+ *   if (ctx.isIdle()) { ... }
+ * });
+ * ```
+ */
+interface ExtensionContext {
+    /** Current working directory */
+    cwd: string;
+    /** Abort signal — fires when the agent operation is cancelled */
+    signal: AbortSignal | undefined;
+    /** Whether the agent is currently idle (not streaming) */
+    isIdle(): boolean;
+    /** Abort the current agent operation */
+    abort(): void;
+    /**
+     * Execute a shell command.
+     *
+     * @param command - The command to run
+     * @param args - Command arguments
+     * @param options - Execution options (cwd, env, timeout, signal)
+     * @returns Execution result with exitCode, stdout, stderr
+     */
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+    /** Extension manifest from package.json `rowan` field */
+    manifest?: ExtensionManifest;
+    /** Current model ID, if available */
+    modelId?: string;
+    /** Get current system prompt */
+    getSystemPrompt?(): string;
+}
+/**
+ * Utility functions available to extensions.
+ */
+interface ExtensionUtils {
+    /**
+     * Generate unique ID.
+     * @param prefix - ID prefix
+     * @returns Format: `{prefix}_{timestamp}_{counter}`
+     */
+    createId(prefix: string): string;
+    /**
+     * JSON serialization (with indentation).
+     * @param value - Value to serialize
+     * @returns JSON string
+     */
+    formatJson(value: unknown): string;
+    /**
+     * Build LlmRequest from PhaseInput.
+     * @param input - Phase input
+     * @returns LLM request object
+     */
+    buildModelRequest(input: PhaseInput): LlmRequest;
+    /**
+     * Create a prompt builder.
+     * @param instructions - Instruction list
+     * @returns Builder function
+     *
+     * @example
+     * ```typescript
+     * const builder = ctx.utils.createPromptBuilder([
+     *   "Phase: review",
+     *   "Review code changes",
+     * ]);
+     *
+     * // Use in buildPrompt
+     * ctx.registerPhase({
+     *   id: "review",
+     *   buildPrompt: builder,
+     * });
+     * ```
+     */
+    createPromptBuilder(instructions: string[]): (input: PhaseInput) => LlmRequest;
+}
+/**
+ * Extension factory function.
+ * Receives ExtensionAPI for registering hooks, phases, and providers.
+ *
+ * @param api - Extension API
+ *
+ * @example
+ * ```typescript
+ * const factory: ExtensionFactory = (api) => {
+ *   api.on("before_tool_call", handler);
+ * };
+ * ```
+ */
+type ExtensionFactory = (api: ExtensionAPI) => void | Promise<void>;
+
+/**
+ * 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;
+    validatePhaseOverride?: (phaseId: string, extensionPath: string) => boolean;
+    cwd?: string;
+};
+/**
+ * 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 validatePhaseOverride?;
+    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;
+    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): PhaseDefinition | undefined;
+    getPhases(): PhaseDefinition[];
+    getPhaseHandler(id: string): RegisteredPhase["handler"] | undefined;
+    createPhaseRegistry(input?: {
+        entryPhaseId?: string;
+    }): PhaseRegistry;
+    /**
+     * 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: PhaseInput): Promise<{
+        abort?: any;
+        skip?: any;
+        input?: PhaseInput;
+    }>;
+    emitAfterPhase(phaseId: string, output: PhaseOutput): Promise<{
+        abort?: any;
+        retry?: PhaseInput;
+        output?: PhaseOutput;
+    }>;
+    emitBeforePrompt(phaseId: string, input: PhaseInput): Promise<PhaseInput>;
+    emitBeforeToolCall(tool: Tool$1, args: unknown): Promise<{
+        allow: boolean;
+        reason?: string;
+    }>;
+    emitAfterToolCall(tool: Tool$1, 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;
+
+/** Check if a path is a built-in extension source (synthetic path). */
+declare function isBuiltinSource(path: string): boolean;
+/** Check if an external extension is attempting to override a built-in phase. */
+declare function isBuiltinPhaseOverride(phaseId: string, extensionPath: string): boolean;
+type CreateDefaultPhaseRegistryOptions = {
+    cwd?: string;
+    entryPhaseId?: string;
+};
+declare function getBuiltinExtensions(): Promise<LoadedExtension[]>;
+declare function getBuiltinRunner(): ExtensionRunner;
+declare function createBuiltinPhaseRegistry(input?: {
+    entryPhaseId?: string;
+}): Promise<PhaseRegistry>;
+declare function createDefaultPhaseRegistry(options?: CreateDefaultPhaseRegistryOptions): Promise<PhaseRegistry>;
+
+/**
+ * Extension loader — discovers and loads extensions from the filesystem.
+ *
+ * Uses the new LoadedExtension type that works with ExtensionRunner.
+ */
+
+/**
+ * Load a single extension from a factory function.
+ */
+declare function loadExtensionFromFactory(factory: ExtensionFactory, cwd: string, extensionPath?: string): LoadedExtension;
+declare const loadExtensionFromFactorySync: typeof loadExtensionFromFactory;
+/**
+ * Load extensions from file paths.
+ */
+declare function loadExtensions(paths: string[], cwd: string): Promise<{
+    extensions: LoadedExtension[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Discover and load extensions from .rowan/extensions directory.
+ */
+declare function discoverAndLoadExtensions(cwd: string): Promise<{
+    extensions: LoadedExtension[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+
+type ExtensionRunnerRef = {
+    current?: ExtensionRunner;
+};
+type AgentOptions = {
+    context: AgentContext;
+    model: LlmModelRef;
+    stream: StreamFn;
+    cwd?: string;
+    phaseConfig?: PhaseRegistry;
+    extensionRunnerRef?: ExtensionRunnerRef;
+    sessionId?: string;
+    maxAttempts?: number;
+    limits?: AgentRunLimits;
+    beforeToolCall?: BeforeToolCall;
+    afterToolCall?: AfterToolCall;
+};
+type RunOptions = Partial<Omit<AgentOptions, "context">> & {
+    context: AgentContext;
+};
+type AgentStatus = {
+    sessionId?: string;
+    context: AgentContext;
+    model: LlmModelRef;
+    tools: Tool$1[];
+    isRunning: boolean;
+    currentResult?: RunResult;
+    error?: string;
+};
+declare class Agent {
+    readonly state: AgentStatus;
+    private options;
+    private readonly listeners;
+    private readonly pendingListenerTasks;
+    private readonly listenerErrors;
+    private activeRun?;
+    constructor(options: AgentOptions);
+    subscribe(listener: AgentEventListener): Unsubscribe;
+    private emitToListeners;
+    flushEvents(): Promise<void>;
+    private processEvents;
+    /**
+     * Hook for before_tool_call — called before a tool executes.
+     * Extensions can block execution by setting allow=false.
+     */
+    private handleBeforeToolCall;
+    /**
+     * Hook for after_tool_call — called after a tool executes.
+     * Extensions can mutate the result.
+     */
+    private handleAfterToolCall;
+    /**
+     * Hook for before_phase — called before a phase executes.
+     * Extensions can abort, skip, or replace the phase input.
+     */
+    private handleBeforePhase;
+    /**
+     * Hook for after_phase — called after a phase executes.
+     * Extensions can abort, retry, or replace the output.
+     */
+    private handleAfterPhase;
+    /**
+     * Hook for before_prompt — called before buildPrompt, allowing extensions to transform PhaseInput.
+     * Extensions can transform the PhaseInput (messages, tools, systemPrompt, etc.).
+     */
+    private handleBeforePrompt;
+    private handleRunFailure;
+    private runWithLifecycle;
+    private finishRun;
+    run(config?: RunOptions): Promise<RunResult>;
+    abort(reason?: string): void;
+    waitForIdle(): Promise<void>;
+    private resolveRunConfig;
+    private createContextSnapshot;
+}
+
+/**
+ * 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$1[]> {
+    constructor();
+}
+
+declare const SESSION_SCHEMA_VERSION = "0.4.4";
+type AgentMessageMetadata = Record<string, unknown> & {
+    phase?: string;
+};
+declare const AgentMessageSchema: Type.TObject<{
+    id: Type.TString;
+    role: Type.TUnion<[Type.TLiteral<"system">, Type.TLiteral<"user">, Type.TLiteral<"assistant">, Type.TLiteral<"tool">]>;
+    content: Type.TString;
+    createdAt: Type.TString;
+    metadata: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+}>;
+type AgentMessage = Type.Static<typeof AgentMessageSchema>;
+declare const SkillSchema: Type.TObject<{
+    name: Type.TString;
+    description: Type.TString;
+    filePath: Type.TString;
+    baseDir: Type.TString;
+    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>;
+
+declare const SESSION_MANAGER_SCHEMA_VERSION = "0.4.4";
+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 SessionEntry = MessageSessionEntry | OutcomeSessionEntry | ExecutionTurnSessionEntry | CompactionSessionEntry | BranchSummarySessionEntry | SessionInfoSessionEntry | CustomSessionEntry;
+type SessionRecord = SessionHeader | SessionEntry;
+type SessionAgentContext<TTool = unknown> = {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    tools: TTool[];
+    skills: Skill[];
+};
+type BuildAgentContextInput<TTool = unknown> = {
+    leafId?: string | null;
+    tools?: TTool[];
+    skills?: Skill[];
+};
+type CreateSessionManagerInput = {
+    id?: string;
+    systemPrompt: string;
+    input: string;
+    parentSessionId?: string;
+    skills?: Skill[];
+    title?: string;
+};
+type SessionListItem = {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    latestMessage?: string;
+};
+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>;
+    branch(entryId: string | null): Promise<void>;
+    buildAgentContext<TTool = unknown>(input?: BuildAgentContextInput<TTool>): Promise<SessionAgentContext<TTool>>;
+    listEntries(): Promise<SessionEntry[]>;
+    loadExecutionTurns(filter?: StepFilter): Promise<ExecutionTurn[]>;
+};
+declare function createSessionHeader(input: CreateSessionManagerInput): SessionHeader;
+declare class InMemorySessionManager implements SessionManager {
+    private header;
+    private readonly entries;
+    private constructor();
+    static create(input: CreateSessionManagerInput): InMemorySessionManager;
+    static fromRecords(records: SessionRecord[]): InMemorySessionManager;
+    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>;
+    branch(entryId: string | null): Promise<void>;
+    buildAgentContext<TTool = unknown>(input?: BuildAgentContextInput<TTool>): Promise<SessionAgentContext<TTool>>;
+    listEntries(): Promise<SessionEntry[]>;
+    loadExecutionTurns(filter?: StepFilter): Promise<ExecutionTurn[]>;
+    protected appendImportedEntry(entry: SessionEntry): void;
+    private appendEntry;
+    private entriesForLeaf;
+}
+declare function summarizeSessionManagerRecords(records: readonly SessionRecord[]): SessionListItem;
+
+declare class LocalJsonlSessionManager implements SessionManager {
+    private readonly sessionsDir;
+    private readonly filePath;
+    private readonly inner;
+    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>;
+    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;
+}
+
+type ToolContext = {
+    state: AgentContextState;
+    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>;
+};
+
+type CoreToolContext = {
+    root?: string;
+    maxReadBytes?: number;
+    bashTimeoutMs?: number;
+    maxBashOutputBytes?: number;
+};
+declare function createCoreTools(input?: CoreToolContext): Tool[];
+
+type RuntimeMode = "source" | "binary";
+type WorkspacePaths = {
+    mode: RuntimeMode;
+    cwd: string;
+    rowanDir: string;
+};
+type ResolveWorkspaceOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    entrypoint?: string;
+    homeDir?: string;
+    mode?: RuntimeMode;
+};
+declare function resolveWorkspacePaths(options?: ResolveWorkspaceOptions): WorkspacePaths;
+declare function resolveInWorkspace(path: string, rootOrPaths: string | Pick<WorkspacePaths, "cwd">): string;
+
+declare function resolveSkillPath(input: string, workspace?: WorkspacePaths): string;
+declare function loadSkill(path: string, workspace?: WorkspacePaths): Promise<AgentContextSkill>;
+declare function loadSkills(paths?: string[], workspace?: WorkspacePaths): Promise<AgentContextSkill[]>;
+
+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[];
+    }>;
+    /** Loaded skills — serialized into the prompt. */
+    skills?: Array<{
+        name: string;
+        description: string;
+        filePath: string;
+    }>;
+    /** Working directory. */
+    cwd?: string;
+}
+declare function buildSystemPrompt(options: SystemPromptOptions): string;
+
+type PromptTool = {
+    name: string;
+    description: string;
+    parameters: unknown;
+};
+type SerializableTool = {
+    name: string;
+    description: string;
+    parameters: unknown;
+};
+declare function serializeSkills(skills: AgentContextSkill[]): Array<{
+    name: string;
+    description: string;
+    filePath: string;
+}>;
+declare function latestUserInput(input: PhaseInput): string;
+declare function conversationMessages(messages: AgentContextMessage[]): LlmMessage[];
+declare function buildModelRequest(input: PhaseInput, options?: {
+    model?: LlmModelRef;
+}): LlmRequest;
+
+export { AGENT_STATE_SCHEMA_VERSION, type AbortEvent, type AfterPhaseEvent, type AfterPhaseHookResult, type AfterPhaseResult, type AfterToolCall, type AfterToolCallEvent, type AfterToolCallResult, Agent, type AgentContext, type AgentEndEvent, AgentEventStream, type AgentMessage$1 as AgentMessage, type AgentMessageMetadata, AgentMessageSchema, type AgentOptions, type AgentRunLimits, type AgentStartEvent, type AgentState, type AgentStatus, type BeforePhaseEvent, type BeforePhaseHookResult, type BeforePhaseResult, type BeforePromptEvent, type BeforePromptResult, type BeforeToolCall, type BeforeToolCallEvent, type BeforeToolCallResult, type BranchSummarySessionEntry, type BuildAgentContextInput, type CompactionSessionEntry, type CoreToolContext, type CreateAgentStateInput, type CreateDefaultPhaseRegistryOptions, type CreateSessionManagerInput, type CustomSessionEntry, DEFAULT_PHASE_ID, type EventBus, EventStream, type ExecOptions, type ExecResult, type ExecutionTurn, type ExecutionTurnEntry, type ExecutionTurnSessionEntry, type Extension, type ExtensionAPI, type ExtensionContext, type ExtensionError, type ExtensionErrorListener, type ExtensionFactory, type ExtensionManifest, type ExtensionPackageManifest, ExtensionRunner, type ExtensionRunnerOptions, type ExtensionRunnerRef, type ExtensionRuntime, type ExtensionUtils, HookError, type HookEvent, type HookEventType, type HookHandler, type HookResultMap, HooksManager, InMemorySessionManager, type LoadExtensionsResult, type LoadedExtension, LocalJsonlSessionManager, type LoopMetrics, type MessageEndEvent, type MessageSessionEntry, type MessageSnapshot, type MessageStartEvent, type MessageUpdateEvent, type ModelInvokeInput, type ModelInvokeOutput, type OutcomeSessionEntry, type PhaseContext, type PhaseDefinition, type PhaseInput, type PhaseManifest, type PhaseMessageManager, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseRegistryInput, type PhaseRun, type PhaseToolExecutionManager, type PromptTool, type QueueUpdateEvent, type RegisteredPhase, type RegisteredTool, type RunOptions, type RunResult, SESSION_MANAGER_SCHEMA_VERSION, SESSION_SCHEMA_VERSION, type SavePointEvent, type SerializableTool, type Session, type SessionAgentContext, type SessionEntry, type SessionHeader, type SessionInfoSessionEntry, type SessionListItem, type SessionManager, type SessionRecord, type SettledEvent, type Skill$1 as Skill, SkillSchema, type SourceInfo, type StepFilter, type SystemPromptOptions, type Tool$1 as Tool, type ToolDefinition, type ToolExecutionEndEvent, type ToolExecutionMode$1 as ToolExecutionMode, type ToolExecutionResult, type ToolExecutionStartEvent, type ToolExecutionUpdateEvent, type TurnEndEvent, type TurnStartEvent, type Unsubscribe, type WorkspacePaths, appendUserTurn, buildModelRequest, buildSystemPrompt, conversationMessages, createAgentState, createBuiltinPhaseRegistry, createCoreTools, createDefaultPhaseRegistry, createEventBus, createExtension, createExtensionRunner, createExtensionRuntime, createId, createJson, createMessage, createPhaseRegistry, createSession, createSessionHeader, createSourceInfo, createTimestamp, definePhase, discoverAndLoadExtensions, getBuiltinExtensions, getBuiltinRunner, getGlobalHooks, isBuiltinPhaseOverride, isBuiltinSource, latestUserInput, loadExtensionFromFactory, loadExtensionFromFactorySync, loadExtensions, loadSkill, loadSkills, resetGlobalHooks, resolveInWorkspace, resolveSkillPath, resolveWorkspacePaths, serializeSkills, summarizeSessionManagerRecords };