@tangle-network/agent-app 0.6.0 → 0.7.1

package/dist/missions/index.js

@@ -0,0 +1,45 @@
+import {
+  DEFAULT_MISSION_STEP_KINDS,
+  MISSION_CONTROL_CHANNEL_ID,
+  MissionConcurrencyError,
+  RetryableStepError,
+  applyMissionEvent,
+  asMissionStreamEvent,
+  budgetGateProposalId,
+  buildAgentMissionPlan,
+  createInMemoryMissionStore,
+  createMissionEngine,
+  createMissionService,
+  isMissionStopRequested,
+  isMissionTerminal,
+  mergeMissionState,
+  noopEventSink,
+  parseMissionBlocks,
+  parseSessionStreamEnvelope,
+  reduceMissionEvents,
+  stepGateProposalId,
+  volumeGateProposalId
+} from "../chunk-UIWB2F6N.js";
+export {
+  DEFAULT_MISSION_STEP_KINDS,
+  MISSION_CONTROL_CHANNEL_ID,
+  MissionConcurrencyError,
+  RetryableStepError,
+  applyMissionEvent,
+  asMissionStreamEvent,
+  budgetGateProposalId,
+  buildAgentMissionPlan,
+  createInMemoryMissionStore,
+  createMissionEngine,
+  createMissionService,
+  isMissionStopRequested,
+  isMissionTerminal,
+  mergeMissionState,
+  noopEventSink,
+  parseMissionBlocks,
+  parseSessionStreamEnvelope,
+  reduceMissionEvents,
+  stepGateProposalId,
+  volumeGateProposalId
+};
+//# sourceMappingURL=index.js.map

package/dist/missions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/preset-cloudflare/index.d.ts

@@ -1,6 +1,6 @@
 import { KeyProvisioner, KeyCrypto, WorkspaceKeyManager, WorkspaceKeyStore } from '../billing/index.js';
 import { KnowledgeStateAccessor } from '../knowledge/index.js';
-import { c as AppToolHandlers } from '../types-CTOaTNtU.js';
+import { c as AppToolHandlers } from '../types-By4B3K37.js';
 import { KvLike } from '../web/index.js';
 import '@tangle-network/agent-eval';
 

package/dist/runtime/index.d.ts

@@ -1,6 +1,6 @@
 export { C as CatalogModel, M as ModelCatalog, R as RouterModel, _ as __resetCatalogCache, b as buildCatalog, f as fetchModelCatalog, n as normalizeModelId } from '../model-catalog-BEAEVDaa.js';
 export { C as CreateTangleRouterModelConfigOptions, D as DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR, a as DEFAULT_TANGLE_ROUTER_BASE_URL, R as ResolveModelOptions, b as ResolveUserTangleExecutionKeyForUserOptions, c as ResolveUserTangleExecutionKeyOptions, d as ResolvedTangleExecutionKey, T as TangleBillingEnforcementOptions, e as TangleExecutionEnvironment, f as TangleExecutionKeyError, g as TangleExecutionKeyErrorCode, h as TangleExecutionKeyHttpError, i as TangleExecutionKeySource, j as TangleModelConfig, k as createTangleRouterModelConfig, l as isTangleBillingEnforcementDisabled, m as isTangleExecutionKeyError, r as resolveTangleExecutionEnvironment, n as resolveTangleModelConfig, o as resolveUserTangleExecutionKey, p as resolveUserTangleExecutionKeyForUser, t as tangleExecutionKeyHttpError } from '../model-CKzniMMr.js';
-import { b as AppToolContext, e as AppToolProducedEvent, f as AppToolTaxonomy, c as AppToolHandlers, d as AppToolOutcome } from '../types-CTOaTNtU.js';
+import { b as AppToolContext, e as AppToolProducedEvent, f as AppToolTaxonomy, c as AppToolHandlers, d as AppToolOutcome } from '../types-By4B3K37.js';
 
 /**
  * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.
@@ -129,7 +129,8 @@ interface CreateAgentRuntimeOptions {
     handlers: AppToolHandlers;
     /** Default agent identity / system prompt. A turn may override it. */
     systemPrompt: string;
-    /** Max tool-driven re-runs per turn. Default 8. */
+    /** Runaway-backstop cap. Default 200 — set far above any legitimate workflow.
+     *  For per-workflow limits use `deadlineMs` or `maxCostUsd` on the loop options. */
     maxToolTurns?: number;
     /** Extra OpenAI tool definitions advertised ALONGSIDE the four app tools
      *  (e.g. `integration_invoke`). Pair with {@link executeOtherTool}. */
@@ -228,6 +229,12 @@ type LoopEvent = {
     type: 'other';
     event: unknown;
 };
+/** Why the loop stopped. `completed` = model finished naturally; `stuck-loop` =
+ *  ≥3 consecutive identical tool calls (same tool + args); `backstop` = hit the
+ *  runaway-backstop cap (200 by default); `deadline` = wall-clock deadlineMs
+ *  exceeded; `budget` = maxCostUsd exhausted. Non-`completed` stops are infra /
+ *  resource outcomes — eval scoring must distinguish them from capability failure. */
+type ToolLoopStopReason = 'completed' | 'stuck-loop' | 'backstop' | 'deadline' | 'budget';
 interface ToolLoopResult {
     /** The model's final text across the loop. */
     finalText: string;
@@ -239,7 +246,9 @@ interface ToolLoopResult {
     }>;
     /** Number of model turns run (1 + tool-driven re-runs). */
     turns: number;
-    /** True when the loop stopped because it hit `maxToolTurns` with calls still pending. */
+    /** Why the loop stopped. */
+    stopReason: ToolLoopStopReason;
+    /** @deprecated Use `stopReason !== 'completed'` instead. */
     cappedOut: boolean;
 }
 interface AppToolLoopOptions {
@@ -260,8 +269,16 @@ interface AppToolLoopOptions {
     /** Which emitted tool names are executable (others are ignored — e.g. a UI-only
      *  tool the app renders but doesn't run here). */
     isExecutableTool: (toolName: string) => boolean;
-    /** Max tool-driven re-runs. Default 8. */
+    /** Runaway-backstop cap. Default 200 — set far above any legitimate workflow.
+     *  For per-workflow limits use `maxCostUsd` or `deadlineMs` instead. */
     maxToolTurns?: number;
+    /** Wall-clock deadline in ms since epoch (Date.now()-based). When exceeded the
+     *  loop stops with stopReason `deadline`. */
+    deadlineMs?: number;
+    /** Maximum total cost in USD. Requires `costOf` to meter each tool call. */
+    maxCostUsd?: number;
+    /** Return the USD cost of one outcome. Required for `maxCostUsd` to work. */
+    costOf?: (call: LoopToolCall, outcome: AppToolOutcome) => number;
     /** Render one tool outcome as the `content` of its `role: 'tool'` message.
      *  Default is a compact `<label> → ok/failed: …`. */
     renderResult?: (label: string, outcome: AppToolOutcome) => string;
@@ -288,6 +305,7 @@ type StreamLoopYield<Raw> = {
 } | {
     kind: 'capped';
     pending: number;
+    stopReason: Exclude<ToolLoopStopReason, 'completed'>;
 };
 interface StreamAppToolLoopOptions<Raw> {
     systemPrompt: string;
@@ -309,16 +327,23 @@ interface StreamAppToolLoopOptions<Raw> {
     isExecutableTool: (toolName: string) => boolean;
     /** Execute one call — the app routes to its integration / app-tool executor. */
     executeToolCall: (call: LoopToolCall) => Promise<AppToolOutcome>;
+    /** Runaway-backstop cap. Default 200 — set far above any legitimate workflow. */
     maxToolTurns?: number;
+    /** Wall-clock deadline in ms since epoch (Date.now()-based). */
+    deadlineMs?: number;
+    /** Maximum total cost in USD. Requires `costOf` to meter each tool call. */
+    maxCostUsd?: number;
+    /** Return the USD cost of one outcome. Required for `maxCostUsd` to work. */
+    costOf?: (call: LoopToolCall, outcome: AppToolOutcome) => number;
     renderResult?: (label: string, outcome: AppToolOutcome) => string;
     labelFor?: (call: LoopToolCall) => string;
 }
 /**
  * The streaming bounded tool loop. Yields `event` for each raw turn event and
- * `tool_result` for each executed tool; emits a single `capped` when it stops at
- * the turn limit with calls still pending. The app drives telemetry + UI
+ * `tool_result` for each executed tool; emits a single `capped` (with stopReason)
+ * when it stops for any non-completed reason. The app drives telemetry + UI
  * emission off the yielded items.
  */
 declare function streamAppToolLoop<Raw>(opts: StreamAppToolLoopOptions<Raw>): AsyncGenerator<StreamLoopYield<Raw>, void, unknown>;
 
-export { type AgentRuntime, type AgentRuntimeModelConfig, type AgentTurnOptions, type AppToolLoopOptions, type CreateAgentRuntimeOptions, type LoopAssistantToolCall, type LoopEvent, type LoopMessage, type LoopToolCall, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type StreamAppToolLoopOptions, type StreamLoopYield, type ToolLoopResult, createAgentRuntime, createOpenAICompatStreamTurn, runAppToolLoop, streamAppToolLoop, toLoopEvents };
+export { type AgentRuntime, type AgentRuntimeModelConfig, type AgentTurnOptions, type AppToolLoopOptions, type CreateAgentRuntimeOptions, type LoopAssistantToolCall, type LoopEvent, type LoopMessage, type LoopToolCall, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type StreamAppToolLoopOptions, type StreamLoopYield, type ToolLoopResult, type ToolLoopStopReason, createAgentRuntime, createOpenAICompatStreamTurn, runAppToolLoop, streamAppToolLoop, toLoopEvents };

package/dist/runtime/index.js

@@ -8,7 +8,7 @@ import {
   runAppToolLoop,
   streamAppToolLoop,
   toLoopEvents
-} from "../chunk-EO4IGDQD.js";
+} from "../chunk-4YTWB5MG.js";
 import {
   DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR,
   DEFAULT_TANGLE_ROUTER_BASE_URL,
@@ -22,7 +22,7 @@ import {
   resolveUserTangleExecutionKeyForUser,
   tangleExecutionKeyHttpError
 } from "../chunk-EHPK7GKR.js";
-import "../chunk-JANT2G2E.js";
+import "../chunk-QAQBR6KQ.js";
 export {
   DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR,
   DEFAULT_TANGLE_ROUTER_BASE_URL,

package/dist/stream/index.d.ts

@@ -36,4 +36,91 @@ declare function resolveChatTurn(input: {
     turnId?: string;
 }): ResolvedChatTurn;
 
-export { type JsonRecord, type PersistedChatMessageForTurn, type ResolvedChatTurn, type StreamEvent, asRecord, asString, buildUserTextParts, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName };
+/**
+ * Resumable chat turns — the router-path answer to "streams resume on
+ * disconnect" (issue #27). A turn's loop events are teed into a store as they
+ * stream; the turn keeps running under `ctx.waitUntil` when the client drops;
+ * a reconnecting client replays the buffered tail by sequence number and
+ * keeps following until the turn completes.
+ *
+ *   POST /chat/stream            → pumpBufferedTurn(...) + live NDJSON
+ *   GET  /chat/stream/:turnId    → replayTurnEvents({ fromSeq }) → NDJSON
+ *
+ * Storage is a structural seam ({@link TurnEventStore}); a D1 implementation
+ * ships here because that's what Cloudflare products have (KV is unsuitable:
+ * eventually consistent cross-isolate). Per-token deltas would mean hundreds
+ * of rows per turn, so consecutive text/reasoning deltas are coalesced within
+ * a flush window before they are persisted — replay yields slightly chunkier
+ * deltas with identical concatenation.
+ */
+type TurnStatus = 'running' | 'complete' | 'error';
+interface BufferedTurnEvent {
+    seq: number;
+    /** The serialized event line (JSON string, no trailing newline). */
+    event: string;
+}
+interface TurnEventStore {
+    append(turnId: string, events: BufferedTurnEvent[]): Promise<void>;
+    read(turnId: string, fromSeq: number): Promise<BufferedTurnEvent[]>;
+    setStatus(turnId: string, status: TurnStatus): Promise<void>;
+    getStatus(turnId: string): Promise<TurnStatus | null>;
+}
+/** Merge consecutive text/reasoning deltas of the same type into one event.
+ *  Concatenation-preserving: replaying the coalesced stream produces the same
+ *  accumulated text as the original. */
+declare function coalesceDeltas(events: unknown[]): unknown[];
+interface PumpBufferedTurnOptions {
+    source: AsyncIterable<unknown>;
+    store: TurnEventStore;
+    turnId: string;
+    /** Deliver one serialized line (with seq) to the live client. Throwing here
+     *  (client disconnected) does NOT stop the turn — events keep buffering. */
+    write?: (line: string) => Promise<void> | void;
+    /** Flush buffered events to the store at most this often. Default 400ms. */
+    flushIntervalMs?: number;
+}
+/**
+ * Drive a turn to completion regardless of the live client: every source
+ * event is sequence-numbered, delivered to `write` (best-effort), and flushed
+ * to the store in coalesced batches. Returns a promise that resolves when the
+ * turn finishes — hand it to `ctx.waitUntil` so a disconnect can't kill the
+ * turn. Never rejects on client-write failure; a source error marks the turn
+ * status 'error' (after flushing what was produced) and rethrows.
+ */
+declare function pumpBufferedTurn(opts: PumpBufferedTurnOptions): Promise<void>;
+interface ReplayTurnEventsOptions {
+    store: TurnEventStore;
+    turnId: string;
+    /** Replay strictly after this sequence number (0 = from the beginning). */
+    fromSeq?: number;
+    /** Poll cadence while the turn is still running. Default 500ms. */
+    pollMs?: number;
+    /** Give up following a 'running' turn after this long. Default 120s. */
+    timeoutMs?: number;
+}
+/**
+ * Yield buffered events after `fromSeq`, then keep polling while the turn is
+ * still 'running' until it completes, errors, or times out. Terminates with a
+ * final `{seq: -1, event: '{"type":"turn_status",...}'}` marker so clients
+ * know why the replay ended.
+ */
+declare function replayTurnEvents(opts: ReplayTurnEventsOptions): AsyncGenerator<BufferedTurnEvent>;
+/** Minimal structural D1 contract (Cloudflare `D1Database` satisfies it). */
+interface D1LikeForTurns {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            run(): Promise<unknown>;
+            all<T = Record<string, unknown>>(): Promise<{
+                results: T[];
+            }>;
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+        };
+    };
+}
+/** Schema for the D1 store — append to the product's migrations. */
+declare const TURN_EVENTS_MIGRATION_SQL = "\nCREATE TABLE IF NOT EXISTS turn_events (\n  turnId TEXT NOT NULL,\n  seq INTEGER NOT NULL,\n  event TEXT NOT NULL,\n  PRIMARY KEY (turnId, seq)\n);\nCREATE TABLE IF NOT EXISTS turn_status (\n  turnId TEXT PRIMARY KEY,\n  status TEXT NOT NULL,\n  updatedAt TEXT NOT NULL\n);\n";
+declare function createD1TurnEventStore(db: D1LikeForTurns): TurnEventStore;
+/** In-memory store for tests and keyless local dev. */
+declare function createMemoryTurnEventStore(): TurnEventStore;
+
+export { type BufferedTurnEvent, type D1LikeForTurns, type JsonRecord, type PersistedChatMessageForTurn, type PumpBufferedTurnOptions, type ReplayTurnEventsOptions, type ResolvedChatTurn, type StreamEvent, TURN_EVENTS_MIGRATION_SQL, type TurnEventStore, type TurnStatus, asRecord, asString, buildUserTextParts, coalesceDeltas, createD1TurnEventStore, createMemoryTurnEventStore, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, pumpBufferedTurn, replayTurnEvents, resolveChatTurn, resolveToolId, resolveToolName };

package/dist/stream/index.js

@@ -1,7 +1,11 @@
 import {
+  TURN_EVENTS_MIGRATION_SQL,
   asRecord,
   asString,
   buildUserTextParts,
+  coalesceDeltas,
+  createD1TurnEventStore,
+  createMemoryTurnEventStore,
   encodeEvent,
   finalizeAssistantParts,
   getPartKey,
@@ -11,14 +15,20 @@ import {
   normalizePersistedPart,
   normalizeTime,
   normalizeToolEvent,
+  pumpBufferedTurn,
+  replayTurnEvents,
   resolveChatTurn,
   resolveToolId,
   resolveToolName
-} from "../chunk-GMFPCCQZ.js";
+} from "../chunk-SDOT7RNB.js";
 export {
+  TURN_EVENTS_MIGRATION_SQL,
   asRecord,
   asString,
   buildUserTextParts,
+  coalesceDeltas,
+  createD1TurnEventStore,
+  createMemoryTurnEventStore,
   encodeEvent,
   finalizeAssistantParts,
   getPartKey,
@@ -28,6 +38,8 @@ export {
   normalizePersistedPart,
   normalizeTime,
   normalizeToolEvent,
+  pumpBufferedTurn,
+  replayTurnEvents,
   resolveChatTurn,
   resolveToolId,
   resolveToolName

package/dist/tools/index.d.ts

@@ -1,5 +1,5 @@
-import { b as AppToolContext, f as AppToolTaxonomy, c as AppToolHandlers, e as AppToolProducedEvent, d as AppToolOutcome } from '../types-CTOaTNtU.js';
-export { A as AddCitationArgs, a as AddCitationResult, R as RenderUiArgs, g as RenderUiResult, S as ScheduleFollowupArgs, h as ScheduleFollowupResult, i as SubmitProposalArgs, j as SubmitProposalResult } from '../types-CTOaTNtU.js';
+import { b as AppToolContext, f as AppToolTaxonomy, c as AppToolHandlers, e as AppToolProducedEvent, d as AppToolOutcome } from '../types-By4B3K37.js';
+export { A as AddCitationArgs, a as AddCitationResult, R as RenderUiArgs, g as RenderUiResult, S as ScheduleFollowupArgs, h as ScheduleFollowupResult, i as SubmitProposalArgs, j as SubmitProposalResult } from '../types-By4B3K37.js';
 
 /** A correctable bad-input error a tool handler throws; the HTTP layer maps it
  *  to a 4xx with the code, the runtime layer to a failed tool_result. So the
@@ -102,6 +102,14 @@ declare function buildAppToolOpenAITools(taxonomy: AppToolTaxonomy): OpenAIFunct
 interface DispatchOptions {
     handlers: AppToolHandlers;
     taxonomy: AppToolTaxonomy;
+    /** Per-call approval policy. When provided it OVERRIDES the static
+     *  `taxonomy.regulatedTypes` membership check, so products can gate by
+     *  cost threshold, environment, or first-use instead of always/never.
+     *  Fail-closed: a predicate that throws counts as "approval required". */
+    needsApproval?: (type: string, args: {
+        title: string;
+        description: string | null;
+    }, ctx: AppToolContext) => boolean | Promise<boolean>;
     /** Called at the real side-effect site for proposals (proposal_created) and
      *  generated views (artifact) so a consumer's completion oracle credits
      *  persisted state. Omit when produced state isn't tracked. */

package/dist/tools/index.js

@@ -8,7 +8,7 @@ import {
   handleAppToolRequest,
   readToolArgs,
   verifyCapabilityToken
-} from "../chunk-HZZD3ZYD.js";
+} from "../chunk-OLCVUGGI.js";
 import {
   APP_TOOL_NAMES,
   ToolInputError,
@@ -17,7 +17,7 @@ import {
   dispatchAppTool,
   isAppToolName,
   outcomeStatus
-} from "../chunk-JANT2G2E.js";
+} from "../chunk-QAQBR6KQ.js";
 export {
   APP_TOOL_NAMES,
   DEFAULT_APP_TOOL_PATHS,

package/dist/{types-CTOaTNtU.d.ts → types-By4B3K37.d.ts}

@@ -41,6 +41,10 @@ interface SubmitProposalArgs {
     type: string;
     title: string;
     description?: string | null;
+    /** Stamped by dispatch from the approval policy (needsApproval predicate or
+     *  taxonomy.regulatedTypes). Handlers MUST queue (never auto-execute) when
+     *  true. Products don't set this; dispatch owns it — fail-closed. */
+    regulated?: boolean;
 }
 interface SubmitProposalResult {
     proposalId: string;

package/dist/web-react/index.d.ts

@@ -2,6 +2,79 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { C as CatalogModel } from '../model-catalog-BEAEVDaa.js';
 
+/**
+ * Client-side chat-stream consumption — the NDJSON parse loop every agent
+ * app's chat UI hand-rolls (and breaks). Normalizes the three line shapes the
+ * agent-app chat routes emit:
+ *
+ *   {kind:'event', event:{type:'text'|'reasoning'|'tool_call'|'usage', ...}}
+ *   {kind:'tool_result', toolCallId, toolName, label, outcome}
+ *   {type:'turn'|'metadata'|'error'|'turn_status', ...}          (route-level)
+ *
+ * Replayed lines carry an extra `seq` — transparently ignored. Works for
+ * router-backed and sandbox-backed chats alike: anything producing these
+ * lines (live pump, queued follow, resume replay) feeds the same callbacks.
+ */
+interface ChatStreamToolCall {
+    toolCallId?: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+interface ChatStreamToolResult {
+    toolCallId?: string;
+    toolName?: string;
+    label?: string;
+    outcome: {
+        ok: boolean;
+        result?: unknown;
+        code?: string;
+        message?: string;
+    };
+}
+interface ChatStreamCallbacks {
+    onTurnId?: (turnId: string) => void;
+    onText?: (delta: string) => void;
+    onReasoning?: (delta: string) => void;
+    onToolCall?: (call: ChatStreamToolCall) => void;
+    onToolResult?: (result: ChatStreamToolResult) => void;
+    onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+    }) => void;
+    onMetadata?: (data: Record<string, unknown>) => void;
+    /** A loop-level error event (the turn failed server-side). */
+    onErrorEvent?: (message: string) => void;
+}
+interface ConsumeChatStreamResult {
+    turnId: string | null;
+    /** True when any text/reasoning/tool activity was received. */
+    receivedContent: boolean;
+}
+/** Parse one NDJSON line into the callbacks. Exposed for tests. */
+declare function dispatchChatStreamLine(line: string, cb: ChatStreamCallbacks): {
+    turnId?: string;
+    receivedContent: boolean;
+};
+/** Drain one NDJSON body into the callbacks. Throws on transport failure
+ *  (caller decides whether to resume). */
+declare function consumeChatStream(body: ReadableStream<Uint8Array>, cb: ChatStreamCallbacks): Promise<ConsumeChatStreamResult>;
+interface StreamChatOptions {
+    /** Start the turn (POST the chat request); must return a streaming Response. */
+    start: () => Promise<Response>;
+    /** Re-attach to a turn after a transport drop (GET the resume route). */
+    resume?: (turnId: string, fromSeq: number) => Promise<Response>;
+    callbacks: ChatStreamCallbacks;
+    /** Called before a resume replays from 0 so the UI can reset accumulated
+     *  turn state (text, reasoning, tool chips). */
+    onResetForResume?: () => void;
+}
+/**
+ * Run one chat turn with automatic single-shot resume: if the transport drops
+ * mid-turn and the server announced a turnId, reset and replay the buffered
+ * turn. Server-side the turn keeps running either way (queued runner).
+ */
+declare function streamChatTurn(opts: StreamChatOptions): Promise<ConsumeChatStreamResult>;
+
 interface ChatMessageMetrics {
     modelUsed?: string;
     promptTokens?: number;
@@ -37,11 +110,46 @@ interface EffortPickerProps {
 /** Reasoning-effort selector pill, styled to match {@link ModelPicker}. Show
  *  it only when the selected model `supportsReasoning`. */
 declare function EffortPicker({ value, onChange }: EffortPickerProps): react.JSX.Element;
+/** One step of a retained tool run (e.g. a sandbox command + its output). */
+interface ToolRunStep {
+    at: string;
+    label: string;
+    detail?: string;
+    status?: 'ok' | 'error';
+}
+/** A retained tool run keyed by the parent message's toolCallId. The product
+ *  persists these server-side (fail-closed: only ids its own loop created)
+ *  and serves them to the drill-in panel. */
+interface ToolRunRecord {
+    toolCallId: string;
+    toolName: string;
+    title: string;
+    status: 'running' | 'complete' | 'error';
+    steps: ToolRunStep[];
+}
+interface RunDrillInProps {
+    run: ToolRunRecord;
+    onClose: () => void;
+}
+/**
+ * Readonly side panel showing a retained tool run's transcript — the
+ * "drill into what the sandbox actually did" view. Follow-ups happen in the
+ * main chat, never here.
+ */
+declare function RunDrillIn({ run, onClose }: RunDrillInProps): react.JSX.Element;
 interface ChatToolCallInfo {
     id: string;
     name: string;
     status: 'running' | 'done' | 'error';
+    /** The tool outcome (`{ok, result}` shape). When `result.status` is
+     *  'queued_for_approval' the chip renders the approval state. */
+    result?: unknown;
 }
+/** Extract `{proposalId, status}` from a tool outcome when it is a proposal
+ *  awaiting human approval; null otherwise. */
+declare function pendingApprovalOf(call: ChatToolCallInfo): {
+    proposalId: string;
+} | null;
 interface ChatUiMessage extends ChatMessageMetrics {
     id: string;
     role: 'user' | 'assistant' | 'system';
@@ -61,6 +169,15 @@ interface ChatMessagesProps {
     agentLabel?: string;
     /** Render the trailing "agent is thinking" row. */
     loading?: boolean;
+    /** Approve/Reject handlers for proposals awaiting approval. When omitted the
+     *  chip still shows "awaiting approval" but without action buttons. */
+    approval?: ProposalApprovalHandlers;
+    /** Make tool chips clickable (e.g. open a {@link RunDrillIn} panel). */
+    onToolCallClick?: (call: ChatToolCallInfo, message: ChatUiMessage) => void;
+}
+interface ProposalApprovalHandlers {
+    onApprove: (proposalId: string, toolCallId: string) => void | Promise<void>;
+    onReject: (proposalId: string, toolCallId: string) => void | Promise<void>;
 }
 /**
  * The message thread: one centered column; user messages are right-aligned
@@ -68,6 +185,6 @@ interface ChatMessagesProps {
  * model id, tokens/sec, and cost, plus a collapsible thinking section and
  * tool-call chips.
  */
-declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, }: ChatMessagesProps): react.JSX.Element;
+declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, approval, onToolCallClick, }: ChatMessagesProps): react.JSX.Element;
 
-export { type ChatMessageMetrics, ChatMessages, type ChatMessagesProps, type ChatToolCallInfo, type ChatUiMessage, EffortPicker, type EffortPickerProps, ModelPicker, type ModelPickerProps, formatModelCost, formatTokensPerSecond };
+export { type ChatMessageMetrics, ChatMessages, type ChatMessagesProps, type ChatStreamCallbacks, type ChatStreamToolCall, type ChatStreamToolResult, type ChatToolCallInfo, type ChatUiMessage, type ConsumeChatStreamResult, EffortPicker, type EffortPickerProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, RunDrillIn, type RunDrillInProps, type StreamChatOptions, type ToolRunRecord, type ToolRunStep, consumeChatStream, dispatchChatStreamLine, formatModelCost, formatTokensPerSecond, pendingApprovalOf, streamChatTurn };