@rowan-agent/agent 0.4.6 → 0.4.8

package/dist/index.d.cts

@@ -1,13 +1,31 @@
-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 * as _rowan_agent_models from '@rowan-agent/models';
+import { LlmRequest, LlmResponse, LlmModelRef, LlmModelUsage, StreamFn, AgentEventListener, ToolCall, ToolResult, AgentMessage, Outcome, Skill as Skill$1, ContentBlock, ProviderConfig, Protocol, ModelCost, AgentEvent, LlmMessage } from '@rowan-agent/models';
+export { AgentEvent, AgentEventListener, AgentMessage, LlmModelRef, Outcome, Skill, 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 ExecutionTurn = {
+    id: string;
+    sessionId: string;
+    parentSessionId?: string;
+    phase: string;
+    requestedAtMs: number;
+    completedAtMs: number;
+    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;
@@ -30,103 +48,49 @@ type LoopMetrics = {
     /** Total wall-clock duration in ms. */
     durationMs?: number;
 };
-type AgentRunState = {
-    agentState: AgentState;
+type SessionState = {
     currentPhase: string;
     attempt: number;
-    transcript: AgentMessage$1[];
-    /** Loop execution metrics. */
     metrics: LoopMetrics;
+    status: "idle" | "running" | "completed" | "aborted" | "failed";
 };
-
-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;
+type AgentConfig = {
+    context: AgentContext;
+    sessionId?: string;
     model: LlmModelRef;
-    usage?: LlmModelUsage;
-    entries: ExecutionTurnEntry[];
+    stream: StreamFn;
+    signal?: AbortSignal;
+    emit?: AgentEventListener;
+    phases?: PhaseRegistry;
+    runtime?: AgentRuntimePort;
+    beforeToolCall?: BeforeToolCall;
+    afterToolCall?: AfterToolCall;
+    beforePhase?: BeforePhaseHook;
+    afterPhase?: AfterPhaseHook;
+    beforePrompt?: BeforePromptHook;
+    maxAttempts?: number;
+    onModelTranscript?: (transcript: ModelTranscript, meta: {
+        phase: string;
+        model: LlmModelRef;
+    }) => Promise<void>;
+    onMessage?: (message: AgentMessage) => Promise<void>;
+    onOutcome?: (outcome: Outcome) => Promise<void>;
+    sessionState?: SessionState;
+};
+type ToolRunnerInput = {
+    config: AgentConfig;
+    toolCall: ToolCall;
 };
-type StepFilter = {
-    phase?: LoopPhase;
-    afterMs?: number;
+type ToolRunner = (input: ToolRunnerInput) => Promise<ToolResult>;
+type AgentRuntimePort = {
+    tools?: ToolRunner;
 };
 
-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;
+type ToolContext = Pick<AgentContext, "skills"> & {
     toolCallId: string;
 };
-type ToolExecutionMode$1 = "sequential" | "parallel";
-type Tool$1<TArgs = unknown> = {
+type ToolExecutionMode = "sequential" | "parallel";
+type Tool<TArgs = unknown> = {
     name: string;
     description: string;
     parameters: Type.TSchema;
@@ -135,22 +99,22 @@ type Tool$1<TArgs = unknown> = {
     /** 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>;
+    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$1[];
+    messages: AgentMessage[];
     /** Tools available for this run. */
-    tools?: Tool$1[];
+    tools: Tool[];
     /** Skills available for this run. */
-    skills?: Skill$1[];
+    skills: Skill$1[];
 };
 type BeforeToolCall = (input: {
-    tool: Tool$1;
+    tool: Tool;
     args: unknown;
 }) => Promise<{
     allow: true;
@@ -159,188 +123,158 @@ type BeforeToolCall = (input: {
     reason: string;
 }>;
 type AfterToolCall = (input: {
-    tool: Tool$1;
+    tool: Tool;
     result: ToolResult;
 }) => Promise<ToolResult>;
 type RunResult = {
     sessionId: string;
-    messages: AgentMessage$1[];
+    messages: AgentMessage[];
     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 createMessage(role: AgentMessage["role"], content: AgentMessage["content"], metadata?: Record<string, unknown>): AgentMessage;
+declare function messageContentText(content: AgentMessage["content"]): string;
 
-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;
+/** Snapshot of phase-level context for restore */
+type PhaseContextSnapshot = {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    currentPhase: string;
+    availablePhases: string[];
+    turnNumber: number;
+    payload?: unknown;
 };
-/** 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>;
+/** Execution capabilities for a phase — operates on PhaseContext. */
+type PhaseExecution = {
+    snapshot(): PhaseContextSnapshot;
+    restore(snapshot: PhaseContextSnapshot): void;
+    invokeModel(context: PhaseContext): Promise<ModelInvokeOutput>;
+    executeTool(context: AgentContext, toolCall: ToolCall): Promise<ToolResult>;
 };
-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<{
+
+/** 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;
-        description: string;
+        args: unknown;
     }>;
-    /** 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[];
+    /** 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;
 };
-declare function definePhase(definition: PhaseDefinition): PhaseDefinition;
-declare function createPhaseRegistry(input: PhaseRegistryInput): PhaseRegistry;
-declare const DEFAULT_PHASE_ID: 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 */
+    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 if no phases defined) */
+    entryPhaseId: string | null;
+}
 
 /**
- * Source info — tracks where an extension registration came from.
+ * Extension types — simplified for the new hook-based system.
  */
+
 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[];
+/** Phase run function type for extensions */
+type PhaseRun = (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
+/** Phase definition shape used by extensions */
+type PhaseDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    run?: PhaseRun;
+    tools?: string[];
+    skills?: string[];
+    target?: string;
+    input?: Record<string, string>;
+    model?: string;
 };
-type PhaseRegistration = Partial<PhaseManifest> & {
+type PhaseRegistration = Partial<Omit<PhaseDefinition, 'run'>> & {
     /** 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;
     };
@@ -348,7 +282,13 @@ type RegisteredPhase = {
 type ExtensionPackageManifest = {
     rowan?: {
         extensions?: string[];
-        phase?: PhaseManifest;
+        phase?: {
+            id?: string;
+            name?: string;
+            description?: string;
+            tools?: string[];
+            skills?: string[];
+        };
     };
 };
 /**
@@ -434,11 +374,11 @@ type BeforePhaseHookResult = {
         route: string;
         message: string;
     };
-    input?: PhaseInput;
+    input?: PhaseContext;
 };
 type AfterPhaseHookResult = {
     abort?: Outcome;
-    retry?: PhaseInput;
+    retry?: PhaseContext;
     output?: PhaseOutput;
 };
 type HandlerFn = (...args: unknown[]) => Promise<unknown>;
@@ -521,7 +461,7 @@ interface LoadedExtension {
     path: string;
     resolvedPath: string;
     name: string;
-    factory: (api: any) => void | Promise<void>;
+    factory: ExtensionFactory;
     manifest?: ExtensionManifest;
 }
 /** Extension manifest from package.json `rowan` field. */
@@ -656,7 +596,7 @@ interface BeforePhaseEvent {
     /** Phase ID about to execute */
     phaseId: string;
     /** Phase input */
-    input: PhaseInput;
+    input: PhaseContext;
 }
 /**
  * after_phase event - triggered after phase execution
@@ -682,7 +622,7 @@ interface BeforePromptEvent {
     /** Current phase ID */
     phaseId: string;
     /** Phase input (modifiable) */
-    input: PhaseInput;
+    input: PhaseContext;
 }
 /**
  * before_tool_call event - triggered before tool execution
@@ -693,7 +633,7 @@ interface BeforePromptEvent {
 interface BeforeToolCallEvent {
     type: "before_tool_call";
     /** Tool definition */
-    tool: Tool$1;
+    tool: Tool;
     /** Tool arguments */
     args: unknown;
 }
@@ -705,7 +645,7 @@ interface BeforeToolCallEvent {
 interface AfterToolCallEvent {
     type: "after_tool_call";
     /** Tool definition */
-    tool: Tool$1;
+    tool: Tool;
     /** Tool execution result */
     result: ToolResult;
 }
@@ -727,7 +667,7 @@ interface AgentEndEvent {
     /** Execution outcome */
     outcome: Outcome;
     /** All messages */
-    messages: AgentMessage$1[];
+    messages: AgentMessage[];
 }
 /**
  * turn_start event - triggered when conversation turn starts
@@ -735,7 +675,7 @@ interface AgentEndEvent {
 interface TurnStartEvent {
     type: "turn_start";
     /** Current message list */
-    messages: AgentMessage$1[];
+    messages: AgentMessage[];
 }
 /**
  * turn_end event - triggered when conversation turn ends
@@ -743,7 +683,7 @@ interface TurnStartEvent {
 interface TurnEndEvent {
     type: "turn_end";
     /** Message list */
-    messages: AgentMessage$1[];
+    messages: AgentMessage[];
     /** Turn outcome (optional) */
     outcome?: Outcome;
 }
@@ -753,7 +693,7 @@ interface TurnEndEvent {
 interface MessageStartEvent {
     type: "message_start";
     /** Message object */
-    message: AgentMessage$1;
+    message: AgentMessage;
 }
 /**
  * message_update event - triggered on message streaming update
@@ -761,7 +701,7 @@ interface MessageStartEvent {
 interface MessageUpdateEvent {
     type: "message_update";
     /** Message object */
-    message: AgentMessage$1;
+    message: AgentMessage;
     /** Delta text */
     delta: string;
 }
@@ -771,7 +711,7 @@ interface MessageUpdateEvent {
 interface MessageEndEvent {
     type: "message_end";
     /** Message object */
-    message: AgentMessage$1;
+    message: AgentMessage;
 }
 /**
  * tool_execution_start event - triggered when tool execution starts
@@ -855,7 +795,7 @@ interface BeforePhaseResult {
         message: string;
     };
     /** Replace phase input */
-    input?: PhaseInput;
+    input?: PhaseContext;
 }
 /**
  * after_phase hook return value
@@ -868,7 +808,7 @@ interface AfterPhaseResult {
     /** Abort agent */
     abort?: Outcome;
     /** Re-execute phase */
-    retry?: PhaseInput;
+    retry?: PhaseContext;
     /** Replace phase output */
     output?: PhaseOutput;
 }
@@ -879,7 +819,7 @@ interface AfterPhaseResult {
  */
 interface BeforePromptResult {
     /** Replace phase input */
-    input?: PhaseInput;
+    input?: PhaseContext;
 }
 /**
  * before_tool_call hook return value
@@ -1008,16 +948,6 @@ declare class HooksManager {
     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).
      *
@@ -1028,18 +958,6 @@ declare class HooksManager {
     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).
@@ -1053,227 +971,11 @@ 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: [...],
- *   });
+ * Extension context types — runtime state and phase execution context.
  *
- *   // 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 |
+ * For ExtensionAPI and createExtensionAPI, see ./api.ts
  */
 
-/**
- * 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.
  *
@@ -1281,9 +983,6 @@ interface ExtensionAPI {
  * 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) => {
@@ -1316,6 +1015,31 @@ interface ExtensionContext {
     modelId?: string;
     /** Get current system prompt */
     getSystemPrompt?(): string;
+    /** Set/override the system prompt */
+    setSystemPrompt?(prompt: string): void;
+    /** Get the full message history */
+    getMessages?(): Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Append a message to the history */
+    addMessage?(role: "user" | "assistant" | "system", content: string): void;
+    /** Get all available tools */
+    getAvailableTools?(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Get all available skills */
+    getAvailableSkills?(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Get skill content by name */
+    getSkillContent?(skillName: string): string;
+    /** Get all available phase IDs */
+    getAvailablePhases?(): string[];
+    /** Get phase content by ID */
+    getPhaseContent?(phaseId: string): string;
 }
 /**
  * Utility functions available to extensions.
@@ -1333,47 +1057,87 @@ interface ExtensionUtils {
      * @returns JSON string
      */
     formatJson(value: unknown): string;
+}
+
+/**
+ * Extension API object passed to extension factory function.
+ *
+ * @example
+ * ```typescript
+ * export default function(api: ExtensionAPI) {
+ *   // api provides all extension APIs
+ * }
+ * ```
+ */
+interface ExtensionAPI {
     /**
-     * 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",
-     * ]);
+     * Subscribe to a hook event.
      *
-     * // Use in buildPrompt
-     * ctx.registerPhase({
-     *   id: "review",
-     *   buildPrompt: builder,
-     * });
-     * ```
+     * @param eventType - Hook type, e.g. "before_tool_call"
+     * @param handler - Hook handler, can return result to modify behavior
      */
-    createPromptBuilder(instructions: string[]): (input: PhaseInput) => LlmRequest;
+    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. */
+    registerTool(tool: ToolDefinition): void;
+    /** Register a custom phase. */
+    registerPhase(registration: PhaseRegistration): void;
+    /** Register a model provider. */
+    registerProvider(config: _rowan_agent_models.ProviderConfig): void;
+    /** Unregister a model provider. */
+    unregisterProvider(name: string): void;
+    /** Extension manifest from package.json `rowan` field. */
+    manifest?: ExtensionManifest;
+    /** Utility functions. */
+    utils: ExtensionUtils;
+    /** Runtime context — cwd, signal, exec, message access, etc. */
+    context: ExtensionContext;
+    /** Shared event bus for inter-extension communication. */
+    events: EventBus;
+    /** Session context — provides access to the session-level AgentContext. */
+    session: {
+        /** Get the current session AgentContext */
+        getContext(): AgentContext;
+    };
+    /** Phase execution capabilities — rovides Phase In/Out, phase identity, and phase routing. */
+    phase: {
+        /** Phase In: get payload from previous phase */
+        getPayload(): unknown;
+        /** Phase Out: set payload for next phase */
+        setPayload(payload: unknown): void;
+        /** Phase Out: set outcome message */
+        setMessage(message: string): void;
+        /** Get current phase id */
+        getCurrentPhase(): string;
+        /** Set next phase (lower priority than PHASE.md target) */
+        setNextPhase(phaseId: string): void;
+        /** Get the next phase set by setNextPhase */
+        getNextPhase(): string | undefined;
+        /** Get the message set by setMessage */
+        getMessage(): string | undefined;
+    };
 }
 /**
  * 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>;
+/**
+ * @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.
@@ -1387,8 +1151,7 @@ type ExtensionFactory = (api: ExtensionAPI) => void | Promise<void>;
  */
 
 type ExtensionRunnerOptions = {
-    entryPhaseId?: string;
-    validatePhaseOverride?: (phaseId: string, extensionPath: string) => boolean;
+    entryPhaseId?: string | null;
     cwd?: string;
 };
 /**
@@ -1425,7 +1188,6 @@ declare class ExtensionRunner {
     readonly hooks: HooksManager;
     readonly runtime: ExtensionRuntime;
     readonly events: EventBus;
-    private readonly validatePhaseOverride?;
     private readonly cwd;
     private readonly abortController;
     private _idle;
@@ -1436,6 +1198,8 @@ declare class ExtensionRunner {
     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;
@@ -1509,12 +1273,13 @@ declare class ExtensionRunner {
      * 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;
+    getPhase(id: string): Phase | undefined;
+    getPhases(): Phase[];
     createPhaseRegistry(input?: {
-        entryPhaseId?: string;
+        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.
@@ -1528,22 +1293,22 @@ declare class ExtensionRunner {
      * Unified hook emission — returns the first non-undefined result.
      */
     private emitHook;
-    emitBeforePhase(phaseId: string, input: PhaseInput): Promise<{
+    emitBeforePhase(phaseId: string, input: PhaseContext): Promise<{
         abort?: any;
         skip?: any;
-        input?: PhaseInput;
+        input?: PhaseContext;
     }>;
     emitAfterPhase(phaseId: string, output: PhaseOutput): Promise<{
         abort?: any;
-        retry?: PhaseInput;
+        retry?: PhaseContext;
         output?: PhaseOutput;
     }>;
-    emitBeforePrompt(phaseId: string, input: PhaseInput): Promise<PhaseInput>;
-    emitBeforeToolCall(tool: Tool$1, args: unknown): Promise<{
+    emitBeforePrompt(phaseId: string, input: PhaseContext): Promise<PhaseContext>;
+    emitBeforeToolCall(tool: Tool, args: unknown): Promise<{
         allow: boolean;
         reason?: string;
     }>;
-    emitAfterToolCall(tool: Tool$1, result: ToolResult): Promise<ToolResult>;
+    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>;
@@ -1577,21 +1342,6 @@ declare class ExtensionRunner {
 }
 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.
  *
@@ -1602,7 +1352,6 @@ declare function createDefaultPhaseRegistry(options?: CreateDefaultPhaseRegistry
  * 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.
  */
@@ -1632,22 +1381,26 @@ type AgentOptions = {
     model: LlmModelRef;
     stream: StreamFn;
     cwd?: string;
-    phaseConfig?: PhaseRegistry;
+    rowanDir?: string;
+    phases?: PhaseRegistry;
     extensionRunnerRef?: ExtensionRunnerRef;
     sessionId?: string;
     maxAttempts?: number;
-    limits?: AgentRunLimits;
     beforeToolCall?: BeforeToolCall;
     afterToolCall?: AfterToolCall;
-};
-type RunOptions = Partial<Omit<AgentOptions, "context">> & {
-    context: AgentContext;
-};
+    onMessage?: (message: AgentMessage) => Promise<void>;
+    onOutcome?: (outcome: Outcome) => Promise<void>;
+    onModelTranscript?: (transcript: ModelTranscript, meta: {
+        phase: string;
+        model: LlmModelRef;
+    }) => Promise<void>;
+};
+type RunOptions = Partial<AgentConfig> & Pick<AgentConfig, "context">;
 type AgentStatus = {
     sessionId?: string;
     context: AgentContext;
     model: LlmModelRef;
-    tools: Tool$1[];
+    tools: Tool[];
     isRunning: boolean;
     currentResult?: RunResult;
     error?: string;
@@ -1685,67 +1438,58 @@ declare class Agent {
      */
     private handleAfterPhase;
     /**
-     * Hook for before_prompt — called before buildPrompt, allowing extensions to transform PhaseInput.
-     * Extensions can transform the PhaseInput (messages, tools, systemPrompt, etc.).
+     * Hook for before_prompt — called before model request, allowing extensions to transform PhaseContext.
+     * Extensions can transform the PhaseContext (messages, tools, systemPrompt, etc.).
      */
     private handleBeforePrompt;
     private handleRunFailure;
+    /**
+     * Discover and load phases and skills from the workspace.
+     *
+     * - Auto-discovers file-based phases from .rowan/phases/
+     * - Auto-discovers skills from .rowan/skills/
+     * - Merges with CLI-provided phases and skills
+     */
+    private discoverResources;
     private runWithLifecycle;
     private finishRun;
     run(config?: RunOptions): Promise<RunResult>;
     abort(reason?: string): void;
+    /**
+     * Get formatted skill content for LLM consumption.
+     *
+     * Finds the skill by name and returns the formatted content using `formatSkillInvocation`.
+     * This is a programmatic API for developers to invoke skills directly.
+     *
+     * @param name - The skill name to look up
+     * @param additionalInstructions - Optional additional instructions to append
+     * @returns Formatted skill content string
+     */
+    skill(name: string, additionalInstructions?: string): string;
+    /**
+     * Get formatted phase content for LLM consumption.
+     *
+     * Finds the phase by name and returns the formatted content.
+     * This is a programmatic API for developers to invoke phases directly.
+     *
+     * @param name - The phase name to look up
+     * @returns Formatted phase content string, or empty string if not found
+     */
+    phase(name: string): Promise<string>;
     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 function createId(prefix: string): string;
+declare function createTimestamp(date?: Date): string;
 
-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;
+    content: Type.TString;
     disableModelInvocation: Type.TBoolean;
 }>;
 type Skill = Type.Static<typeof SkillSchema>;
@@ -1772,7 +1516,6 @@ declare function createSession<TLogEvent = never>(input: {
 }): 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;
@@ -1822,8 +1565,17 @@ type CustomSessionEntry = SessionEntryBase & {
     customType: string;
     data: unknown;
 };
-type SessionEntry = MessageSessionEntry | OutcomeSessionEntry | ExecutionTurnSessionEntry | CompactionSessionEntry | BranchSummarySessionEntry | SessionInfoSessionEntry | CustomSessionEntry;
-type SessionRecord = SessionHeader | SessionEntry;
+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[];
@@ -1873,48 +1625,17 @@ type SessionManager = {
         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;
+    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[]>;
-    protected appendImportedEntry(entry: SessionEntry): void;
-    private appendEntry;
-    private entriesForLeaf;
-}
-declare function summarizeSessionManagerRecords(records: readonly SessionRecord[]): SessionListItem;
+};
 
 declare class LocalJsonlSessionManager implements SessionManager {
     private readonly sessionsDir;
@@ -1946,6 +1667,12 @@ declare class LocalJsonlSessionManager implements SessionManager {
         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[]>;
@@ -1953,24 +1680,6 @@ declare class LocalJsonlSessionManager implements SessionManager {
     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;
@@ -1992,13 +1701,92 @@ type ResolveWorkspaceOptions = {
     entrypoint?: string;
     homeDir?: string;
     mode?: RuntimeMode;
+    rowanDir?: string;
 };
 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[]>;
+declare function loadSkill(path: string, workspace?: WorkspacePaths): Promise<Skill$1>;
+declare function loadSkills(workspace?: WorkspacePaths, paths?: string[]): Promise<Skill$1[]>;
+
+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();
+}
+
+/**
+ * Load all phases from .rowan/phases directory.
+ *
+ * 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, AgentLoop starts from "none" phase.
+ */
+declare function loadPhases(workspace?: WorkspacePaths, paths?: string[]): Promise<PhaseRegistry>;
 
 interface SystemPromptOptions {
     /** Base system prompt. */
@@ -2019,31 +1807,38 @@ interface SystemPromptOptions {
         name: string;
         description: string;
         filePath: string;
+        disableModelInvocation?: boolean;
     }>;
     /** 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<{
+declare function serializeSkills(skills: Skill$1[]): Array<{
     name: string;
     description: string;
     filePath: string;
+    disableModelInvocation?: boolean;
 }>;
-declare function latestUserInput(input: PhaseInput): string;
-declare function conversationMessages(messages: AgentContextMessage[]): LlmMessage[];
-declare function buildModelRequest(input: PhaseInput, options?: {
+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[];
+    }>;
+    skills: Skill$1[];
+    promptGuidelines?: string[];
+    appendSystemPrompt?: string;
+};
+declare function buildModelRequest(input: ModelRequestInput, 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 };
+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, 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 ExtensionRunnerRef, 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, discoverAndLoadExtensions, getGlobalHooks, interpolateEnvVars, latestUserInput, loadConfigFile, loadExtensionFromFactory, loadExtensions, loadPhases, loadSkill, loadSkills, messageContentText, parseModelRef, registerConfigModels, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, resolveSkillPath, resolveWorkspacePaths, serializeSkills };