@rowan-agent/agent 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _rowan_agent_models from '@rowan-agent/models';
-import { LlmContentPart, ModelRef, ContentBlock, ModelConfig, StreamFn } from '@rowan-agent/models';
-export { ModelConfig, ModelRef, StreamFn, ThinkingLevel } from '@rowan-agent/models';
+import { LlmContentPart, ModelRef, ContentBlock, ScopeRef, ToolKind, ToolAnnotations, ToolCallStatus, ToolProgress, ToolCallContent, ToolCallLocation, JsonValue as JsonValue$1, JsonObject as JsonObject$1, ModelConfig, StreamFn, ThinkingLevel, ToolCall as ToolCall$1, ToolCallUpdate } from '@rowan-agent/models';
+export { ModelConfig, ModelRef, ProviderCallContext, ProviderConfig, ProviderModelConfig, ProviderStreamFn, ScopeRef, StreamFn, ThinkingLevel, ToolAnnotations, ToolCall, ToolCallContent, ToolCallLocation, ToolCallOptions, ToolCallOutcome, ToolCallStatus, ToolCallUpdate, ToolDefinitionSummary, ToolKind, ToolProgress } from '@rowan-agent/models';
 import Type from 'typebox';
 
 type AgentMessage = {
@@ -53,6 +53,8 @@ type ToolResult = {
     ok: boolean;
     content: unknown;
     error?: string;
+    structuredContent?: unknown;
+    isError?: boolean;
 };
 
 type PhaseRegistrySelection = Readonly<{
@@ -206,15 +208,25 @@ type PhaseMessageManager = {
     discard(messageId: string): void;
 };
 
-type ScopeRef = {
-    kind: "global";
-} | {
-    kind: "team";
-    teamId: string;
+type UiSlot = "settings" | "model-picker";
+type UiContribution = {
+    slot: "settings";
+    id: string;
+    title: string;
+    description?: string;
+    settings: SettingsDefinition;
 } | {
-    kind: "project";
-    teamId: string;
-    projectId: string;
+    slot: "model-picker";
+    id: string;
+    provider: string;
+    status?: {
+        kind: "ready" | "needs-setup" | "error";
+        message?: string;
+    };
+    actions?: {
+        id: string;
+        label: string;
+    }[];
 };
 interface ExtensionStateStore {
     get(key: string): Promise<JsonValue | undefined>;
@@ -227,6 +239,9 @@ interface ExtensionHost {
     getAgentState(extensionId: string, agentId: string, key: string): Promise<JsonValue | undefined> | JsonValue | undefined;
     setAgentState(extensionId: string, agentId: string, key: string, value: JsonValue): Promise<void> | void;
     deleteAgentState(extensionId: string, agentId: string, key: string): Promise<void> | void;
+    getGlobalState(extensionId: string, key: string): Promise<JsonValue | undefined> | JsonValue | undefined;
+    setGlobalState(extensionId: string, key: string, value: JsonValue): Promise<void> | void;
+    deleteGlobalState(extensionId: string, key: string): Promise<void> | void;
 }
 type ExtensionToolContribution = {
     kind: "tool";
@@ -248,11 +263,11 @@ interface SourceInfo {
 /** Register a Phase by directory path or Phase object; PHASE.md and direct child Skills are loaded atomically when a path is supplied. */
 type PhaseRegistration = string | Phase;
 /**
- * Tool definition for registering LLM-callable tools via `api.tool.register()`.
+ * Tool definition for registering LLM-callable tools via `api.tools.register()`.
  *
  * @example
  * ```typescript
- * api.tool.register({
+ * api.tools.register({
  *   name: "search_docs",
  *   description: "Search documentation",
  *   parameters: { type: "object", properties: { query: { type: "string" } } },
@@ -273,24 +288,31 @@ interface ToolDefinition {
     promptSnippet?: string;
     /** Optional: additional guidelines appended to system prompt */
     promptGuidelines?: string[];
+    kind?: ToolKind;
+    annotations?: ToolAnnotations;
+    _meta?: JsonObject;
+    present?: (call: {
+        status: ToolCallStatus;
+        args: JsonValue;
+        progress?: ToolProgress;
+        result?: ToolExecutionResult;
+    }) => {
+        title?: string;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        _meta?: JsonObject;
+    } | undefined | void | Promise<{
+        title?: string;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        _meta?: JsonObject;
+    } | undefined | void>;
     /** Execute the tool */
-    execute: (args: unknown, context: ToolInvocationContext, signal?: AbortSignal) => Promise<ToolExecutionResult$1>;
+    execute: (args: unknown, context: ToolInvocationContext, signal?: AbortSignal) => Promise<ToolExecutionResult>;
     /** Optional: per-tool execution mode override */
     executionMode?: "sequential" | "parallel";
 }
-/**
- * Result from tool execution.
- */
-interface ToolExecutionResult$1 {
-    /** 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.
  */
@@ -417,7 +439,7 @@ interface EventBus {
  *
  * @example
  * ```typescript
- * api.on("before_tool_call", (event, ctx) => {
+ * api.hooks.on("before_tool_call", (event, ctx) => {
  *   console.log(`cwd: ${ctx.cwd}`);
  *   if (ctx.isIdle()) { ... }
  * });
@@ -502,15 +524,18 @@ interface ExtensionUtils {
  * ```
  */
 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
-     */
-    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;
+    /** Hook events — subscribe or unsubscribe. */
+    hooks: {
+        /**
+         * Subscribe to a hook event.
+         *
+         * @param eventType - Hook type, e.g. "before_tool_call"
+         * @param handler - Hook handler, can return result to modify behavior
+         */
+        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;
+    };
     /** Extension configuration — read own layered config or listen for changes. */
     config: {
         /** Get the extension's own effective configuration block. */
@@ -518,15 +543,17 @@ interface ExtensionAPI {
         /** Listen for configuration changes for a scope. */
         changed(handler: (scope: ScopeRef) => void): void;
     };
-    /** Extension state — scoped to run (in-memory) or agent (durable). */
+    /** Extension state — scoped to run (in-memory) or agent (durable) or global (durable). */
     state: {
         /** Run-scoped in-memory state; dropped when the Run ends. */
         run(runId: string): ExtensionStateStore;
         /** Agent-scoped durable state; persisted with the Agent record. */
         agent(agentId: string): ExtensionStateStore;
+        /** Extension-scoped durable state; survives process restarts. */
+        global(): ExtensionStateStore;
     };
     /** Tool capabilities — register and unregister custom tools. */
-    tool: {
+    tools: {
         /** Register a custom LLM-callable tool. */
         register(tool: ToolDefinition): void;
         /** Unregister a previously registered tool by name. */
@@ -537,20 +564,15 @@ interface ExtensionAPI {
         /** Contribute a capability to the host. Returns a disposer to remove the contribution. */
         contribute(contribution: ExtensionCapabilityContribution): () => 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;
+    /** Model provider registration. */
+    providers: {
+        /** Register a model provider. Registering with an existing id replaces it. */
+        register(config: _rowan_agent_models.ProviderConfig): void;
+        /** Unregister a model provider by id. */
+        unregister(id: string): void;
+    };
     /** Phase execution capabilities — provides Phase In/Out, phase identity, phase routing, and registration. */
-    phase: {
+    phases: {
         /** Register a Phase directory bundle or Phase object. */
         register(phase: PhaseRegistration): Promise<void>;
         /** Unregister a previously registered phase by name. */
@@ -569,11 +591,20 @@ interface ExtensionAPI {
         getNextPhase(): string | undefined;
         /** Get the message set by setMessage */
         getMessage(): string | undefined;
-        /** Phase Settings contributions registered by the Phase extension. */
-        settings: {
-            register(provider: PhaseSettingsProvider): void;
-        };
     };
+    /** Declarative UI contributions — settings or model picker decorations. */
+    ui: {
+        /** Contribute declarative UI to a host slot. Returns a disposer to remove the contribution. */
+        contribute(contribution: UiContribution): () => 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;
 }
 /**
  * Extension factory function.
@@ -586,10 +617,12 @@ type ExtensionFactory = (api: ExtensionAPI) => ExtensionFactoryResult | Promise<
 declare class InMemoryExtensionHost implements ExtensionHost {
     private readonly configs;
     private readonly agentState;
+    private readonly globalState;
     private readonly listeners;
     constructor(options?: {
         configs?: Record<string, Record<string, JsonObject>>;
         agentState?: Record<string, Record<string, Record<string, JsonValue>>>;
+        globalState?: Record<string, Record<string, JsonValue>>;
     });
     setConfig(extensionId: string, config: JsonObject | null, scope?: ScopeRef): void;
     getConfig(extensionId: string, scope?: ScopeRef): JsonObject | null;
@@ -598,6 +631,9 @@ declare class InMemoryExtensionHost implements ExtensionHost {
     getAgentState(extensionId: string, agentId: string, key: string): JsonValue | undefined;
     setAgentState(extensionId: string, agentId: string, key: string, value: JsonValue): void;
     deleteAgentState(extensionId: string, agentId: string, key: string): void;
+    getGlobalState(extensionId: string, key: string): JsonValue | undefined;
+    setGlobalState(extensionId: string, key: string, value: JsonValue): void;
+    deleteGlobalState(extensionId: string, key: string): void;
 }
 
 /**
@@ -664,6 +700,7 @@ declare class ExtensionRunner {
     private bound;
     private readonly errorListeners;
     private readonly capabilityListeners;
+    private readonly uiContributionListeners;
     /** Current agent context — set by the agent before each phase */
     currentContext?: AgentContext;
     constructor(options?: ExtensionRunnerOptions);
@@ -729,6 +766,18 @@ declare class ExtensionRunner {
      * Returns an unsubscribe function.
      */
     onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
+    /** Get all contributed UI elements across all extensions. */
+    getUiContributions(): readonly UiContribution[];
+    /**
+     * Subscribe to UI contribution changes (contributions added, removed, or extensions disposed).
+     * Returns an unsubscribe function.
+     */
+    onUiContributionsChanged(listener: (contributions: readonly UiContribution[]) => void): () => void;
+    triggerUiAction(event: {
+        contributionId: string;
+        actionId: string;
+        scope?: ScopeRef;
+    }): void;
     getPhase(name: string): Phase | undefined;
     getPhases(): Phase[];
     createPhaseRegistry(input?: {
@@ -798,6 +847,8 @@ declare class ExtensionRunner {
     private unregisterTool;
     private contributeCapability;
     private notifyCapabilitiesChanged;
+    private contributeUi;
+    private notifyUiContributionsChanged;
     private registerPhase;
     private registerPhaseDefinition;
     private unregisterPhase;
@@ -811,6 +862,40 @@ declare class ExtensionRunner {
     private disposeExtension;
 }
 
+type ToolCallPresentationInput = Readonly<{
+    status: ToolCallStatus;
+    args: JsonValue$1;
+    progress?: ToolProgress;
+    result?: ToolExecutionResult;
+}>;
+type ToolCallPresentationOutput = {
+    title?: string;
+    content?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+    _meta?: JsonObject$1;
+};
+type ToolCallMergeTarget = {
+    title?: string;
+    kind?: ToolKind;
+    status?: ToolCallStatus;
+    locations?: ToolCallLocation[];
+    content?: ToolCallContent[];
+    rawInput?: JsonValue$1;
+    rawOutput?: JsonValue$1;
+    _meta?: JsonObject$1;
+};
+type ToolCallMergePatch = {
+    title?: string;
+    kind?: ToolKind;
+    status?: ToolCallStatus;
+    locations?: ToolCallLocation[];
+    content?: ToolCallContent[];
+    rawInput?: JsonValue$1;
+    rawOutput?: JsonValue$1;
+    _meta?: JsonObject$1;
+};
+declare function mergeToolCall<T extends ToolCallMergeTarget>(target: T, patch: ToolCallMergePatch): T;
+
 type ExtensionContribution = LoadedExtension;
 type ExtensionLoadInput = LoadInput<ExtensionContribution>;
 type ExtensionActivationError = Readonly<{
@@ -911,6 +996,7 @@ declare function isConfigurationSnapshot(config: AgentConfiguration | Configurat
 type UserInput = string | Readonly<{
     content: UserContent;
     metadata?: Metadata;
+    thinkingLevel?: ThinkingLevel;
 }>;
 type HistorySeed = readonly Message[];
 type ContextStatus = Readonly<{
@@ -950,11 +1036,12 @@ type ToolCallContext = Readonly<{
     providerToolCallId?: string;
     scope?: ScopeRef;
     turn?: JsonObject;
-    reportProgress(progress: JsonValue): void;
+    reportProgress(progress: ToolProgress): void;
 }>;
 type ToolInvocationContext = ToolCallContext & Readonly<{
     interaction: RunInteractionDriver;
 }>;
+
 type Tool$1 = Readonly<{
     name: string;
     /** Rowan-owned Core Tool; Core Tools bypass Definition/Phase filtering. */
@@ -963,6 +1050,20 @@ type Tool$1 = Readonly<{
     parameters: Type.TSchema;
     promptSnippet?: string;
     promptGuidelines?: readonly string[];
+    kind?: ToolKind;
+    annotations?: ToolAnnotations;
+    _meta?: JsonObject;
+    present?(call: ToolCallPresentationInput): {
+        title?: string;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        _meta?: JsonObject;
+    } | undefined | void | Promise<{
+        title?: string;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        _meta?: JsonObject;
+    } | undefined | void>;
     execute(args: JsonValue, context: ToolInvocationContext, signal: AbortSignal): Promise<ToolExecutionResult>;
 }>;
 type ContextCandidate = Readonly<{
@@ -1041,6 +1142,11 @@ type ToolCallReservation = Readonly<{
     name: string;
     args: JsonValue;
     toolCallId?: ToolCallId;
+    title?: string;
+    kind?: ToolKind;
+    locations?: ToolCallLocation[];
+    content?: ToolCallContent[];
+    _meta?: JsonObject;
 }>;
 type ToolCommit = Readonly<{
     run: RunRecord;
@@ -1062,6 +1168,8 @@ type RunRecord = Readonly<{
     revision: number;
     state: RunState;
     input: UserInput;
+    scope?: ScopeRef;
+    cwd?: string;
     initialMessageId?: MessageId;
     invalidatedBy?: Readonly<{
         messageId: MessageId;
@@ -1125,6 +1233,8 @@ type RunSnapshotBase = Readonly<{
     agentSequence: number;
     revision: number;
     input: UserInput;
+    scope?: ScopeRef;
+    cwd?: string;
     metadata?: Metadata;
     /** Effective entry Phase payload the Run started with (defaults filled). */
     phasePayload?: JsonValue;
@@ -1139,6 +1249,7 @@ type RunSnapshotBase = Readonly<{
 type RunSnapshot = RunSnapshotBase & (Readonly<{
     state: "queued" | "running";
     currentPhaseId?: string;
+    interactions?: readonly RunInteraction[];
 }> | Readonly<{
     state: "input_required";
     interactions: readonly RunInteraction[];
@@ -1235,6 +1346,8 @@ interface OwnedStore {
         agentId: AgentId;
         input: UserInput;
         metadata?: Metadata;
+        scope?: ScopeRef;
+        cwd?: string;
         phasePayload?: JsonValue;
         entryPhases?: readonly EntryPhaseSpec[];
         pinnedConfigToken?: ConfigToken;
@@ -1300,6 +1413,11 @@ interface OwnedStore {
         args: JsonValue;
         toolCallId?: ToolCallId;
         providerToolCallId?: string;
+        title?: string;
+        kind?: ToolKind;
+        locations?: ToolCallLocation[];
+        content?: ToolCallContent[];
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     reserveToolCalls(input: {
         runId: RunId;
@@ -1315,6 +1433,11 @@ interface OwnedStore {
         execution: ExecutionToken;
         expectedRevision: number;
         toolCallId: ToolCallId;
+        title?: string;
+        kind?: ToolKind;
+        locations?: ToolCallLocation[];
+        content?: ToolCallContent[];
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     suspendToolCall(input: {
         runId: RunId;
@@ -1330,6 +1453,12 @@ interface OwnedStore {
         result: ToolExecutionResult;
         state: "completed" | "failed" | "indeterminate";
         reason?: string;
+        title?: string;
+        kind?: ToolKind;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        rawOutput?: JsonValue;
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     cancelRun(input: {
         runId: RunId;
@@ -1337,6 +1466,12 @@ interface OwnedStore {
         reason?: string;
         output?: AssistantMessage;
     }): Promise<RunRecord>;
+    recordToolCall(input: {
+        runId: RunId;
+        execution?: ExecutionToken;
+        update: ToolCall$1 | ToolCallUpdate;
+        external?: boolean;
+    }): Promise<DurableRunEvent>;
     snapshotRun(runId: RunId): Promise<RunSnapshot>;
     history(agentId: AgentId): Promise<readonly Message[]>;
     listAgents(): Promise<readonly AgentRecord[]>;
@@ -1428,6 +1563,8 @@ interface AgentRuntime$1 {
     start(agentId: AgentId, input: UserInput, options: {
         idempotencyKey: string;
         metadata?: Metadata;
+        scope?: ScopeRef;
+        cwd?: string;
         phasePayload?: JsonValue;
         entryPhases?: ReadonlyArray<EntryPhaseSpec>;
     }): Promise<AgentRun>;
@@ -1463,6 +1600,13 @@ interface AgentRuntime$1 {
     }): Promise<DurableConsumer>;
     listCapabilities(): readonly ExtensionCapability[];
     onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
+    listUiContributions(): readonly UiContribution[];
+    onUiContributionsChanged(listener: (contributions: readonly UiContribution[]) => void): () => void;
+    triggerUiAction(event: {
+        contributionId: string;
+        actionId: string;
+        scope?: ScopeRef;
+    }): void;
     close(): Promise<void>;
 }
 type ConsumerRegistration = Readonly<{
@@ -1565,7 +1709,7 @@ type RunInteractionDriver = Readonly<{
 }>;
 declare class RunInteractionCancelledError extends Error {
     readonly code: "run_interaction_cancelled";
-    constructor();
+    constructor(message?: string);
 }
 declare class RunInteractionBoundary extends Error {
     readonly state: ExecutionState;
@@ -1620,10 +1764,20 @@ type ToolUseContent = Readonly<{
 type ToolExecutionResult = Readonly<{
     ok: true;
     content: JsonValue;
+    structuredContent?: JsonValue;
+    isError?: boolean;
 }> | Readonly<{
     ok: false;
     content: JsonValue;
     error: string;
+    structuredContent?: JsonValue;
+    isError?: boolean;
+}> | Readonly<{
+    content: readonly ContentBlock[];
+    structuredContent?: JsonValue;
+    isError?: boolean;
+    ok?: boolean;
+    error?: string;
 }>;
 type DurableToolResult = Readonly<{
     toolCallId: ToolCallId;
@@ -1729,43 +1883,24 @@ type QueuedRunFailure = Extract<RunFailure, {
 type RunningRunFailure = Extract<RunFailure, {
     code: "runtime_interrupted" | "tool_indeterminate" | "execution_failed";
 }>;
-type ToolCallState = "pending" | "running" | "completed" | "failed" | "indeterminate";
-type ToolCallSnapshotBase = Readonly<{
+type ToolCallState = ToolCallStatus;
+type ToolCallSnapshot = ToolCall$1 & Readonly<{
     id: ToolCallId;
-    providerToolCallId: string;
-    agentId: AgentId;
-    runId: RunId;
-    executionId: ExecutionId;
-    requestMessageId: MessageId;
-    name: string;
-    args: JsonValue;
-    createdAt: string;
-    updatedAt: string;
+    providerToolCallId?: string;
+    agentId?: AgentId;
+    runId?: RunId;
+    executionId?: ExecutionId;
+    requestMessageId?: MessageId;
+    name?: string;
+    args?: JsonValue;
+    state?: ToolCallStatus;
+    result?: DurableToolResult;
+    resultMessageId?: MessageId;
+    reason?: string;
+    external?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
 }>;
-type ToolCallSnapshot = ToolCallSnapshotBase & (Readonly<{
-    state: "pending";
-}> | Readonly<{
-    state: "running";
-}> | Readonly<{
-    state: "completed";
-    result: DurableToolResult & Readonly<{
-        ok: true;
-    }>;
-    resultMessageId: MessageId;
-}> | Readonly<{
-    state: "failed";
-    result: DurableToolResult & Readonly<{
-        ok: false;
-    }>;
-    resultMessageId: MessageId;
-}> | Readonly<{
-    state: "indeterminate";
-    result: DurableToolResult & Readonly<{
-        ok: false;
-    }>;
-    resultMessageId: MessageId;
-    reason: string;
-}>);
 type DurableEventBase = Readonly<{
     id: EventId;
     schemaVersion: 1;
@@ -1837,80 +1972,29 @@ type RunStateChanged = DurableEventBase & (Readonly<{
     to: "cancelled";
     reason?: string;
 }>);
-type ToolStateChanged = DurableEventBase & (Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: null;
-        to: "pending";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "pending";
-    }>;
-}> | Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: "pending";
-        to: "running";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "running";
-    }>;
-}> | Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: "pending";
-        to: "failed";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "failed";
-    }>;
-}> | Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: "running";
-        to: "pending";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "pending";
-    }>;
-}> | Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: "running";
-        to: "pending";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "pending";
-    }>;
-}> | Readonly<{
-    kind: "tool_state_changed";
-    transition: Readonly<{
-        from: "running";
-        to: "completed";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "completed";
-    }>;
-}> | Readonly<{
+type ToolStateChanged = (DurableEventBase & Readonly<{
     kind: "tool_state_changed";
     transition: Readonly<{
-        from: "running";
-        to: "failed";
+        from: ToolCallStatus | null;
+        to: ToolCallStatus;
     }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "failed";
-    }>;
-}> | Readonly<{
+    toolCall: ToolCall$1;
+    external?: boolean;
+}>) | Readonly<{
     kind: "tool_state_changed";
+    durability: "transient";
+    runId: RunId;
+    executionId?: ExecutionId;
     transition: Readonly<{
-        from: "running";
-        to: "indeterminate";
-    }>;
-    toolCall: Extract<ToolCallSnapshot, {
-        state: "indeterminate";
+        from: ToolCallStatus | null;
+        to: ToolCallStatus;
     }>;
-}>);
-type DurableRunEvent = PhaseEntered | MessageCommitted | MessageRevised | RunStateChanged | ToolStateChanged;
+    toolCall: ToolCall$1 | ToolCallUpdate;
+    external?: boolean;
+}>;
+type DurableRunEvent = PhaseEntered | MessageCommitted | MessageRevised | RunStateChanged | Extract<ToolStateChanged, {
+    durability: "durable";
+}>;
 type MessageDelta = Readonly<{
     kind: "message_delta";
     durability: "transient";
@@ -1941,14 +2025,6 @@ type ToolCallDelta = Readonly<{
     arguments: string;
     args: JsonValue | undefined;
 }>;
-type ToolProgress = Readonly<{
-    kind: "tool_progress";
-    durability: "transient";
-    runId: RunId;
-    executionId: ExecutionId;
-    toolCallId: ToolCallId;
-    progress: JsonValue;
-}>;
 type PhaseStatusEvent = Readonly<{
     kind: "phase_status";
     durability: "transient";
@@ -1967,7 +2043,9 @@ type ModelRetry = Readonly<{
     delayMs: number;
     error: string;
 }>;
-type RunEvent = DurableRunEvent | MessageDelta | ThinkingDelta | ToolCallDelta | ToolProgress | PhaseStatusEvent | ModelRetry;
+type RunEvent = DurableRunEvent | MessageDelta | ThinkingDelta | ToolCallDelta | PhaseStatusEvent | ModelRetry | Extract<ToolStateChanged, {
+    durability: "transient";
+}>;
 
 type PhaseStatusState = "running" | "completed";
 /** Normalized status event exposed to Runtime consumers. */
@@ -2029,6 +2107,8 @@ type PhaseExecutionIdentity = Readonly<{
     /** Opaque metadata captured at the durable boundary; Rowan does not decode it. */
     agentMetadata?: Readonly<Record<string, unknown>>;
     runMetadata?: Readonly<Record<string, unknown>>;
+    scope?: _rowan_agent_models.ScopeRef;
+    cwd?: string;
 }>;
 /** Everything a phase needs to execute */
 interface PhaseContext {
@@ -2051,24 +2131,24 @@ interface PhaseContext {
 }
 /** JSON-safe structural defaults declared by a Phase's `input` mapping. */
 type PhaseInput = Readonly<Record<string, JsonValue>>;
-/** JSON-safe option metadata exposed by a Phase to a host Settings surface. */
-interface PhaseSettingsOption {
+/** JSON-safe option metadata exposed to a host Settings surface. */
+interface SettingsOption {
     value: string;
     label: string;
     description?: string;
     disabled?: boolean;
 }
-interface PhaseSettingsBadge {
+interface SettingsBadge {
     label: string;
     tone?: "neutral" | "success" | "review" | "danger";
 }
-interface PhaseSettingsItem {
+interface SettingsItem {
     id: string;
     title: string;
     description?: string;
-    badges?: readonly PhaseSettingsBadge[];
+    badges?: readonly SettingsBadge[];
 }
-type PhaseSettingsControl = {
+type SettingsControl = {
     type: "boolean";
     path: string;
     label: string;
@@ -2088,7 +2168,7 @@ type PhaseSettingsControl = {
     path: string;
     label: string;
     description?: string;
-    options: readonly PhaseSettingsOption[];
+    options: readonly SettingsOption[];
 } | {
     type: "text";
     path: string;
@@ -2102,32 +2182,26 @@ type PhaseSettingsControl = {
     path: string;
     label: string;
     description?: string;
-    items: readonly PhaseSettingsItem[];
-    fields: readonly PhaseSettingsControl[];
+    items: readonly SettingsItem[];
+    fields: readonly SettingsControl[];
     add?: {
         label: string;
         idLabel?: string;
-        fields: readonly PhaseSettingsControl[];
+        fields: readonly SettingsControl[];
     };
     removeLabel?: string;
 };
-interface PhaseSettingsSection {
+interface SettingsSection {
     id: string;
     title: string;
     description?: string;
-    controls: readonly PhaseSettingsControl[];
+    controls: readonly SettingsControl[];
 }
-/** Declarative, host-neutral Settings surface contributed by a Phase. */
-interface PhaseSettingsDefinition {
+/** Declarative, host-neutral Settings surface. */
+interface SettingsDefinition {
     description?: string;
-    sections: readonly PhaseSettingsSection[];
-}
-/** Host context is intentionally opaque beyond the effective configuration. */
-interface PhaseSettingsContext {
-    configuration: Readonly<Record<string, unknown>>;
-    metadata?: Readonly<Record<string, unknown>>;
+    sections: readonly SettingsSection[];
 }
-type PhaseSettingsProvider = (context: PhaseSettingsContext) => PhaseSettingsDefinition | Promise<PhaseSettingsDefinition>;
 /**
  * Loaded Phase object
  */
@@ -2293,6 +2367,7 @@ type Tool<TArgs = unknown> = {
     promptGuidelines?: string[];
     /** Whether this tool can run concurrently with others. Default: "parallel". */
     executionMode?: ToolExecutionMode;
+    _meta?: JsonObject$1;
     execute(args: TArgs, context: ToolContext, signal?: AbortSignal): Promise<ToolResult>;
 };
 /** Context snapshot passed into the low-level agent loop. */
@@ -2307,6 +2382,7 @@ type AgentContext = {
     skills: Skill[];
     /** Custom phases for this run. Agent normalizes this with the built-in default phase. */
     phases?: PhaseRegistry;
+    cwd?: string;
 };
 
 /**
@@ -2339,6 +2415,7 @@ declare class AgentRuntime implements AgentRuntime$1 {
     readonly host: ExtensionHost;
     private readonly resources;
     private readonly startedRuns;
+    private readonly liveInteractions;
     private heartbeat?;
     private pumping;
     private closed;
@@ -2394,6 +2471,8 @@ declare class AgentRuntime implements AgentRuntime$1 {
     start(agentId: AgentId, input: UserInput, options: {
         idempotencyKey: string;
         metadata?: Metadata;
+        scope?: ScopeRef;
+        cwd?: string;
         phasePayload?: JsonValue;
         entryPhases?: ReadonlyArray<EntryPhaseSpec>;
     }): Promise<AgentRun>;
@@ -2420,6 +2499,14 @@ declare class AgentRuntime implements AgentRuntime$1 {
     }): Promise<DurableConsumer>;
     listCapabilities(): readonly ExtensionCapability[];
     onCapabilitiesChanged(listener: (capabilities: readonly ExtensionCapability[]) => void): () => void;
+    listUiContributions(): readonly UiContribution[];
+    onUiContributionsChanged(listener: (contributions: readonly UiContribution[]) => void): () => void;
+    triggerUiAction(event: {
+        contributionId: string;
+        actionId: string;
+        scope?: ScopeRef;
+    }): void;
+    private liveInteract;
     close(): Promise<void>;
     snapshot(runId: RunId): Promise<RunSnapshot>;
     history(agentId: AgentId): Promise<readonly Message[]>;
@@ -2435,6 +2522,7 @@ declare class AgentRuntime implements AgentRuntime$1 {
     private resolveContextWindow;
     private executeTool;
     private executeToolBatch;
+    private executeAndCommitTool;
     private foldToolInteractionRecords;
     private requireAgent;
     private archiveDirFor;
@@ -2460,14 +2548,24 @@ type StoredAgent = Mutable<AgentRecord>;
 type StoredRun = Mutable<RunRecord>;
 type StoredToolCall = {
     id: ToolCallId;
-    providerToolCallId: string;
+    providerToolCallId?: string;
     agentId: AgentId;
     runId: RunId;
-    executionId: ExecutionId;
-    requestMessageId: MessageId;
-    name: string;
-    args: JsonValue;
-    state: ToolCallState;
+    executionId?: ExecutionId;
+    requestMessageId?: MessageId;
+    name?: string;
+    args?: JsonValue;
+    state?: ToolCallState;
+    toolCallId: string;
+    title: string;
+    kind: ToolKind;
+    status: ToolCallStatus;
+    content?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+    rawInput?: JsonValue;
+    rawOutput?: JsonValue;
+    _meta?: JsonObject;
+    external?: boolean;
     result?: DurableToolResult;
     resultMessageId?: MessageId;
     reason?: string;
@@ -2586,6 +2684,8 @@ declare class InMemoryStore implements DurableStore {
         agentId: AgentId;
         input: UserInput;
         metadata?: Metadata;
+        scope?: ScopeRef;
+        cwd?: string;
         phasePayload?: JsonValue;
         entryPhases?: readonly EntryPhaseSpec[];
         pinnedConfigToken?: ConfigToken;
@@ -2661,6 +2761,11 @@ declare class InMemoryStore implements DurableStore {
         execution: ExecutionToken;
         expectedRevision: number;
         toolCallId: ToolCallId;
+        title?: string;
+        kind?: ToolKind;
+        locations?: ToolCallLocation[];
+        content?: ToolCallContent[];
+        _meta?: JsonObject;
     }): ToolCommit;
     suspendToolCall(lease: OwnerLease, input: {
         runId: RunId;
@@ -2676,6 +2781,12 @@ declare class InMemoryStore implements DurableStore {
         result: ToolExecutionResult;
         state: "completed" | "failed" | "indeterminate";
         reason?: string;
+        title?: string;
+        kind?: ToolKind;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        rawOutput?: JsonValue;
+        _meta?: JsonObject;
     }): ToolCommit;
     commitOutcome(lease: OwnerLease, input: {
         runId: RunId;
@@ -2691,6 +2802,12 @@ declare class InMemoryStore implements DurableStore {
         reason?: string;
         output?: AssistantMessage;
     }): RunRecord;
+    recordToolCall(lease: OwnerLease, input: {
+        runId: RunId;
+        execution?: ExecutionToken;
+        update: ToolCall$1 | ToolCallUpdate;
+        external?: boolean;
+    }): DurableRunEvent;
     snapshotRun(lease: OwnerLease, runId: RunId): RunSnapshot;
     listAgents(lease: OwnerLease): readonly AgentRecord[];
     listRuns(lease: OwnerLease, input?: {
@@ -2817,6 +2934,8 @@ declare class SqliteStore implements DurableStore {
         agentId: AgentId;
         input: UserInput;
         metadata?: Metadata;
+        scope?: ScopeRef;
+        cwd?: string;
         phasePayload?: JsonValue;
         entryPhases?: readonly EntryPhaseSpec[];
         pinnedConfigToken?: ConfigToken;
@@ -2884,18 +3003,18 @@ declare class SqliteStore implements DurableStore {
         args: JsonValue;
         toolCallId?: ToolCallId;
         providerToolCallId?: string;
+        title?: string;
+        kind?: ToolKind;
+        locations?: ToolCallLocation[];
+        content?: ToolCallContent[];
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     reserveToolCalls(lease: OwnerLease, input: {
         runId: RunId;
         execution: ExecutionToken;
         expectedRevision: number;
         requestMessageId: MessageId;
-        calls: readonly Readonly<{
-            providerToolCallId: string;
-            name: string;
-            args: JsonValue;
-            toolCallId?: ToolCallId;
-        }>[];
+        calls: readonly ToolCallReservation[];
         contentBlocks?: readonly ContentBlock[];
     }): Promise<ToolBatchCommit>;
     startToolCall(lease: OwnerLease, input: {
@@ -2903,6 +3022,11 @@ declare class SqliteStore implements DurableStore {
         execution: ExecutionToken;
         expectedRevision: number;
         toolCallId: ToolCallId;
+        title?: string;
+        kind?: ToolKind;
+        locations?: ToolCallLocation[];
+        content?: ToolCallContent[];
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     suspendToolCall(lease: OwnerLease, input: {
         runId: RunId;
@@ -2918,6 +3042,12 @@ declare class SqliteStore implements DurableStore {
         result: ToolExecutionResult;
         state: "completed" | "failed" | "indeterminate";
         reason?: string;
+        title?: string;
+        kind?: ToolKind;
+        content?: ToolCallContent[];
+        locations?: ToolCallLocation[];
+        rawOutput?: JsonValue;
+        _meta?: JsonObject;
     }): Promise<ToolCommit>;
     cancelRun(lease: OwnerLease, input: {
         runId: RunId;
@@ -2925,6 +3055,12 @@ declare class SqliteStore implements DurableStore {
         reason?: string;
         output?: AssistantMessage;
     }): Promise<RunRecord>;
+    recordToolCall(lease: OwnerLease, input: {
+        runId: RunId;
+        execution?: ExecutionToken;
+        update: ToolCall$1 | ToolCallUpdate;
+        external?: boolean;
+    }): Promise<DurableRunEvent>;
     snapshotRun(lease: OwnerLease, runId: RunId): Promise<RunSnapshot>;
     history(lease: OwnerLease, agentId: AgentId): Promise<readonly Message[]>;
     listAgents(lease: OwnerLease): Promise<readonly AgentRecord[]>;
@@ -3117,12 +3253,6 @@ declare function loadSkills(targetPath: string): Promise<Skill[]>;
  * If a directory is provided, the loader reads its PHASE.md.
  */
 declare function loadPhase(targetPath: string): Promise<Phase>;
-/**
- * Collect and evaluate the Settings provider registered through the Phase's
- * ExtensionAPI namespace. Settings discovery never reads a direct module
- * export; the Phase contributes through `api.phase.settings.register()`.
- */
-declare function loadPhaseSettings(phase: Phase, context: PhaseSettingsContext): Promise<PhaseSettingsDefinition | undefined>;
 /**
  * Load all phases from the target directory.
  *
@@ -3176,4 +3306,4 @@ declare function parseFrontmatter<T = Record<string, unknown>>(raw: string): Fro
 
 declare function createCoreTools(input?: CoreToolContext): Tool$1[];
 
-export { type AfterToolCall, type AgentConfiguration, type AgentDefinition, type AgentId, type AgentListCursor, type AgentRecord, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, COMPACT_PHASE_ID, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type ContextCompactionRecord, type ContextStatus, type CoreToolContext, DEFAULT_PHASE_ID, type DefinitionLayer, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EntryPhaseSpec, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionActivationError, type ExtensionActivationResult, type ExtensionCapability, type ExtensionCapabilityContribution, type ExtensionContribution, type ExtensionDisposer, type ExtensionFactory, type ExtensionFactoryResult, type ExtensionHost, ExtensionLifetimeError, type ExtensionLifetimeErrorCode, type ExtensionLoadInput, type ExtensionStateStore, type ExtensionToolContribution, type FrontmatterResult, type HistorySeed, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryExtensionHost, InMemoryStore, type InteractionRecord, type InvocationCatalogEntry, type InvocationSource, type JsonObject, type JsonPrimitive, type JsonValue, type LoadExtensionsResult, type LoadInput, type LoadResult, type LoadedExtension, type Message, type MessageBase, type MessageCommitted, type MessageContent, type MessageDelta, type MessageId, type MessageRevised, type MessageRevisionResult, type Metadata, type ModelRetry, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecution, type PhaseExecutionIdentity, type PhaseInput, type PhaseInvocation, type PhaseMessageManager, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseSettingsBadge, type PhaseSettingsContext, type PhaseSettingsControl, type PhaseSettingsDefinition, type PhaseSettingsItem, type PhaseSettingsOption, type PhaseSettingsProvider, type PhaseSettingsSection, type PhaseState, type PhaseStatus, type PhaseStatusState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RetentionResult, type RunBoundary, type RunClaim, type RunEndEvent, type RunEvent, type RunFailure, type RunId, type RunInteraction, RunInteractionBoundary, RunInteractionCancelledError, type RunInteractionDriver, type RunInteractionKind, type RunInteractionRequest, type RunInteractionState, type RunInteractionStatus, type RunListCursor, type RunRecord, type RunSnapshot, type RunStartEvent, type RunState, type RunStateChanged, type RunSummary, RuntimeBootstrapRegistry, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, RuntimeExtensionLifetime, STOP_PHASE_ID, type ScopeRef, type Skill, SqliteStore, type TextContent, type ThinkingContent, type ThinkingDelta, type Tool$1 as Tool, type ToolCallContext, type ToolCallDelta, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, type WithdrawnUserInput, brandConfigToken, createCompactPhase, createCorePhases, createCoreTools, createDefaultPhase, createStopPhase, isConfigurationSnapshot, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhaseSettings, loadPhases, loadSkill, loadSkills, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };
+export { type AfterToolCall, type AgentConfiguration, type AgentDefinition, type AgentId, type AgentListCursor, type AgentRecord, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, COMPACT_PHASE_ID, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type ContextCompactionRecord, type ContextStatus, type CoreToolContext, DEFAULT_PHASE_ID, type DefinitionLayer, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EntryPhaseSpec, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionActivationError, type ExtensionActivationResult, type ExtensionCapability, type ExtensionCapabilityContribution, type ExtensionContribution, type ExtensionDisposer, type ExtensionFactory, type ExtensionFactoryResult, type ExtensionHost, ExtensionLifetimeError, type ExtensionLifetimeErrorCode, type ExtensionLoadInput, type ExtensionStateStore, type ExtensionToolContribution, type FrontmatterResult, type HistorySeed, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryExtensionHost, InMemoryStore, type InteractionRecord, type InvocationCatalogEntry, type InvocationSource, type JsonObject, type JsonPrimitive, type JsonValue, type LoadExtensionsResult, type LoadInput, type LoadResult, type LoadedExtension, type Message, type MessageBase, type MessageCommitted, type MessageContent, type MessageDelta, type MessageId, type MessageRevised, type MessageRevisionResult, type Metadata, type ModelRetry, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecution, type PhaseExecutionIdentity, type PhaseInput, type PhaseInvocation, type PhaseMessageManager, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type PhaseStatus, type PhaseStatusState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RetentionResult, type RunBoundary, type RunClaim, type RunEndEvent, type RunEvent, type RunFailure, type RunId, type RunInteraction, RunInteractionBoundary, RunInteractionCancelledError, type RunInteractionDriver, type RunInteractionKind, type RunInteractionRequest, type RunInteractionState, type RunInteractionStatus, type RunListCursor, type RunRecord, type RunSnapshot, type RunStartEvent, type RunState, type RunStateChanged, type RunSummary, RuntimeBootstrapRegistry, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, RuntimeExtensionLifetime, STOP_PHASE_ID, type SettingsBadge, type SettingsControl, type SettingsDefinition, type SettingsItem, type SettingsOption, type SettingsSection, type Skill, SqliteStore, type TextContent, type ThinkingContent, type ThinkingDelta, type Tool$1 as Tool, type ToolCallContext, type ToolCallDelta, type ToolCallId, type ToolCallPresentationInput, type ToolCallPresentationOutput, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UiContribution, type UiSlot, type UserContent, type UserInput, type UserMessage, type WithdrawnUserInput, brandConfigToken, createCompactPhase, createCorePhases, createCoreTools, createDefaultPhase, createStopPhase, isConfigurationSnapshot, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhases, loadSkill, loadSkills, mergeToolCall, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };