@intentface/latch-core 0.12.0 → 0.13.1

package/dist/runtime.js

@@ -6,6 +6,58 @@ import { computeCost } from "./pricing.js";
 import { defaultPromptCachingPlan, markLastFunctionTool, mergeProviderOptions, toolsetHash, } from "./prompt-caching.js";
 import { LimitExceededError, exceededPolicy, remainingTokens, windowRef, } from "./limits.js";
 import { compose, fireClientToolResults, insertStepParts, isNewSession, lastUserTextOf, renderTranscript, replaceLastUserText, wrapTools, } from "./extensions/index.js";
+/**
+ * The `data-subagent-progress` writer for one delegation: `now` sends a
+ * snapshot immediately, `throttled` at most every 250ms (each write re-sends
+ * the whole snapshot). Shared by `spawn_agent` and the approval resume so both
+ * write the SAME part id — a resumed delegation updates the one the client is
+ * already showing instead of adding a second.
+ */
+function subagentProgressWriter(writer, ids) {
+    const now = (messages) => {
+        writer.write({
+            type: "data-subagent-progress",
+            id: `subagent_${ids.toolCallId ?? ids.threadId}`,
+            data: { ...ids, messages },
+        });
+    };
+    let lastWrite = 0;
+    const throttled = (messages) => {
+        const t = Date.now();
+        if (t - lastWrite < 250)
+            return;
+        lastWrite = t;
+        now(messages);
+    };
+    return { now, throttled };
+}
+/**
+ * A `buildTurn` `observeStream` that folds the turn's UI chunks into message
+ * snapshots and hands each to `onProgress` as `[...lead, ...assistant]`.
+ * `continuing` is the assistant message a resume extends, so the snapshot keeps
+ * the parts it already had. Observation must never break the run: errors are
+ * swallowed, and the primary stream is drained independently.
+ */
+function progressObserver(lead, onProgress, continuing) {
+    return (observed) => {
+        void (async () => {
+            try {
+                const byId = new Map();
+                for await (const m of readUIMessageStream({
+                    stream: observed,
+                    ...(continuing ? { message: structuredClone(continuing) } : {}),
+                })) {
+                    const msg = m;
+                    byId.set(msg.id, msg);
+                    onProgress([...lead, ...byId.values()]);
+                }
+            }
+            catch {
+                // ignore — live progress is best-effort
+            }
+        })();
+    };
+}
 /** Ids for assistant response messages — `msg_<random>`, matching storage ids. */
 const generateMessageId = createIdGenerator({ prefix: "msg", separator: "_" });
 /** Sub-thread chat ids start with `sub_` so the host can keep them out of the
@@ -191,6 +243,15 @@ function declinePendingApprovals(messages) {
  * Record decisions onto matching `approval-requested` parts (→ `approval-responded`).
  * Mutates in place and returns the messages that changed (to re-persist).
  */
+/**
+ * Whether an approval belongs to the chat's LAST message — the only one a turn
+ * can be paused on. Matches a gated tool part's `approval.id` or a bubbled
+ * subagent approval's `data.approvalId`.
+ */
+function approvalIsLast(messages, approvalId) {
+    const last = messages.at(-1);
+    return (last?.parts ?? []).some((p) => p.approval?.id === approvalId || (p.type === "data-subagent-approval" && p.data?.approvalId === approvalId));
+}
 function applyDecisions(messages, decisions) {
     const byId = new Map(decisions.map((d) => [d.approvalId, d]));
     const changed = [];
@@ -504,6 +565,23 @@ function fireAndForget(fn) {
  */
 /** Keys whose values are masked when a non-`Error` throw is serialized. */
 const SECRETISH_KEY = /token|secret|password|authorization|cookie|api[-_]?key|credential/i;
+/** The last `error` chunk's text in a UI message stream body (SSE `data:` lines), if any. */
+function lastStreamError(body) {
+    let error;
+    for (const line of body.split("\n")) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const chunk = JSON.parse(line.slice(6));
+            if (chunk.type === "error" && chunk.errorText)
+                error = chunk.errorText;
+        }
+        catch {
+            // "[DONE]" and other non-JSON lines
+        }
+    }
+    return error;
+}
 export function clientErrorMessage(error) {
     const message = error instanceof Error ? error.message.trim() : "";
     if (message)
@@ -554,13 +632,15 @@ export function createRuntime(config) {
             "Implement openTurn — see the StorageAdapter contract.");
     }
     /** Resolve an agent's per-request config + a display model id. */
-    async function resolveAgentConfig(agentName, principal, request, turnContext) {
+    async function resolveAgentConfig(agentName, principal, request, turnContext, 
+    /** Passed through to `dynamicAgents.resolve` (see DynamicAgentResolveContext). */
+    resolveCtx) {
         const runtimeCtx = await config.context.build({ principal, request, turnContext });
         // Code-declared agents first; otherwise a dynamic (e.g. DB-stored) agent.
         const factory = config.agents[agentName];
         const cfg = factory
             ? await factory({ context: runtimeCtx, principal, turnContext })
-            : await config.dynamicAgents?.resolve(agentName, principal);
+            : await config.dynamicAgents?.resolve(agentName, principal, resolveCtx);
         if (!cfg)
             throw new Error(`Unknown agent: ${agentName}`);
         const modelId = typeof cfg.model === "string"
@@ -568,15 +648,33 @@ export function createRuntime(config) {
             : (cfg.model.modelId ?? "unknown");
         return { cfg, modelId, runtimeCtx };
     }
+    /** `buildTurnStream` as an SSE `Response` — what every chat-facing path returns. */
+    async function buildTurn(args) {
+        return createUIMessageStreamResponse({
+            stream: (await buildTurnStream(args)),
+            consumeSseStream: consumeStream,
+        });
+    }
     /**
      * Build (and start) one turn's stream — shared by a fresh chat turn and a
      * resume. With durability on, it heartbeats the lease and aborts if it's
      * lost; onFinish writes are fenced by `lease`. The caller decides whether to
      * hand the stream to a client (handleChat) or drive it to completion
-     * server-side (resume).
+     * server-side (resume). Returned as the bare chunk stream (see `buildTurn`
+     * for the `Response`) so `applyApproval`, which may already be streaming a
+     * subagent resume, can merge the continuation into that response.
      */
-    async function buildTurn(args) {
-        const { resolvedChatId, principal, modelId, cfg, run, lease, runtimeCtx } = args;
+    async function buildTurnStream(args) {
+        const { resolvedChatId, principal, run, lease, runtimeCtx } = args;
+        // A per-turn model override replaces the agent's own, and the telemetry id
+        // with it — a run row that says the agent's model while a different one
+        // answered makes every later comparison a lie.
+        const cfg = args.model ? { ...args.cfg, model: args.model } : args.cfg;
+        const modelId = args.model
+            ? typeof args.model === "string"
+                ? args.model
+                : (args.model.modelId ?? "unknown")
+            : args.modelId;
         // Mutable: the start moments below may inject, replace or rewrite history
         // before the model runs. From here on this is the turn's transcript.
         let uiMessages = args.uiMessages;
@@ -777,7 +875,8 @@ export function createRuntime(config) {
         // append the provider's compiled-index block to the instructions. A
         // provider failure degrades to a turn without memory, never a dead turn.
         let instructions = cfg.instructions;
-        if (cfg.memory && config.memory) {
+        const memoryOn = args.memory ?? true;
+        if (memoryOn && cfg.memory && config.memory) {
             const memArgs = { principal, agent: run.agent, memory: cfg.memory };
             try {
                 // Resolve both hooks BEFORE mutating the toolset, so a failure in
@@ -852,30 +951,15 @@ export function createRuntime(config) {
                     const subChatId = threadId?.trim() || generateSubchatId();
                     let onProgress;
                     if (writer) {
-                        const write = (messages) => {
-                            writer.write({
-                                type: "data-subagent-progress",
-                                id: `subagent_${options.toolCallId ?? subChatId}`,
-                                data: {
-                                    toolCallId: options.toolCallId,
-                                    agent,
-                                    threadId: subChatId,
-                                    messages,
-                                },
-                            });
-                        };
-                        write([]);
-                        // Each write re-sends the whole snapshot — throttle the re-sends.
+                        const progress = subagentProgressWriter(writer, {
+                            toolCallId: options.toolCallId,
+                            agent,
+                            threadId: subChatId,
+                        });
+                        progress.now([]);
                         // The trailing tokens are covered by the tool RESULT (the client
                         // switches to the persisted thread once output lands).
-                        let lastWrite = 0;
-                        onProgress = (messages) => {
-                            const now = Date.now();
-                            if (now - lastWrite < 250)
-                                return;
-                            lastWrite = now;
-                            write(messages);
-                        };
+                        onProgress = progress.throttled;
                     }
                     // Propagate the PARENT turn's execution mode AS A SET: interactive →
                     // the subagent gates its tools (a pending write bubbles up here);
@@ -890,7 +974,13 @@ export function createRuntime(config) {
                         depth: depth + 1,
                         autoApprove,
                         blockGated,
+                        // Memory off stays off down the tree: an eval turn's delegate must
+                        // not recall earlier inputs or save new memory either.
+                        ...(memoryOn ? {} : { memory: false }),
                         onProgress,
+                        // Who is delegating — persisted on the sub-thread so every later
+                        // resolve of it can be shaped per parent (DynamicAgentResolveContext).
+                        parentAgent: run.agent,
                         // Telemetry linkage: this turn is the parent; carry the root chat
                         // down so the subagent's trace nests under this conversation.
                         parentRunId: run.id,
@@ -963,18 +1053,36 @@ export function createRuntime(config) {
             // Test runs: stub the approval-gated (mutating) tools so a trial has no
             // real side effects. Gated set = connection defaults + the agent's policy.
             if (blockGated) {
+                /**
+                 * Does this approval value actually gate the tool?
+                 *
+                 * NOT a truthiness check. The SDK spells a waiver as the STRING
+                 * `"not-applicable"` — which is truthy — so `if (v)` treated every
+                 * tool an agent had explicitly waived as gated and stubbed it. On an
+                 * agent whose reads are waived to override a connection default, that
+                 * is every read tool: the agent could not retrieve anything, and an
+                 * eval run measured a model with no access to its own corpus.
+                 *
+                 * Gated: `true`, `"user-approval"`, an object (approval with a
+                 * reason), a function. Waived: `false`, `undefined`,
+                 * `"not-applicable"`.
+                 */
+                const gatedBy = (v) => v === true ||
+                    v === "user-approval" ||
+                    typeof v === "function" ||
+                    (typeof v === "object" && v !== null);
                 const gated = new Set();
                 for (const [k, v] of Object.entries(harnessApproval))
-                    if (v)
+                    if (gatedBy(v))
                         gated.add(k);
                 for (const o of opened) {
                     for (const [k, v] of Object.entries(o.toolApproval ?? {}))
-                        if (v)
+                        if (gatedBy(v))
                             gated.add(k);
                 }
                 if (cfg.toolApproval && typeof cfg.toolApproval !== "function") {
                     for (const [k, v] of Object.entries(cfg.toolApproval)) {
-                        if (v)
+                        if (gatedBy(v))
                             gated.add(k);
                         else
                             gated.delete(k);
@@ -992,12 +1100,19 @@ export function createRuntime(config) {
                     if (t && typeof t.execute === "function") {
                         tools[name] = {
                             ...t,
-                            execute: async (input) => ({
-                                __blocked: true,
-                                tool: name,
-                                input,
-                                reason: "approval-gated tool blocked during test run (no real side effects)",
-                            }),
+                            execute: async (input) => blockGated === "simulate-success"
+                                ? {
+                                    ok: true,
+                                    __stubbed: true,
+                                    tool: name,
+                                    input,
+                                }
+                                : {
+                                    __blocked: true,
+                                    tool: name,
+                                    input,
+                                    reason: "approval-gated tool blocked during test run (no real side effects)",
+                                },
                         };
                     }
                 }
@@ -1056,7 +1171,19 @@ export function createRuntime(config) {
             ? ({ steps }) => steps.reduce((n, st) => n + (st.usage?.inputTokens ?? 0) + (st.usage?.outputTokens ?? 0), 0) >=
                 tokenBudget
             : undefined;
-        const baseStopWhen = budgetStop ? [stepCap ?? stepCountIs(20), budgetStop] : stepCap;
+        // A delegation that paused on the user's approval ends the turn, exactly as
+        // a gated tool of the agent's own does. A gated call has no result, so the
+        // SDK stops there by itself; `spawn_agent` RETURNS one (`awaiting_approval`),
+        // so without this the loop continues and only the result's note stands
+        // between the model and a second delegation — another bubbled card per
+        // step, up to the step cap. Added only when the agent can delegate, so
+        // other agents' stop conditions stay exactly as configured.
+        const subagentPauseStop = tools.spawn_agent
+            ? ({ steps }) => (steps.at(-1)?.toolResults ?? []).some((r) => r.toolName === "spawn_agent" &&
+                r.output?.status === "awaiting_approval")
+            : undefined;
+        const extraStops = [budgetStop, subagentPauseStop].filter((s) => s !== undefined);
+        const baseStopWhen = extraStops.length > 0 ? [stepCap ?? stepCountIs(20), ...extraStops] : stepCap;
         // --- step boundaries for the seam -------------------------------------------
         // A step ends twice from here: on the model side (`agent.stream`'s
         // onStepEnd — usage, finish reason, tool calls) and on the UI side (the
@@ -1130,7 +1257,7 @@ export function createRuntime(config) {
             : config.resolvePromptCaching
                 ? config.resolvePromptCaching(modelId, {
                     agent: run.agent,
-                    memoryScoped: !!(cfg.memory && config.memory),
+                    memoryScoped: !!(memoryOn && cfg.memory && config.memory),
                     principal,
                 })
                 : // No hook → caching is ON by default for first-party Anthropic /
@@ -1704,10 +1831,7 @@ export function createRuntime(config) {
             out = main;
             args.observeStream(observed);
         }
-        return createUIMessageStreamResponse({
-            stream: out,
-            consumeSseStream: consumeStream,
-        });
+        return out;
     }
     async function reapTick(opts) {
         const reaped = await storage.reapExpiredRuns(opts?.now ?? Date.now(), {
@@ -1860,7 +1984,10 @@ export function createRuntime(config) {
             });
         }
         const resolvedChatId = chat.id;
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(agentName, principal, request, turnContext);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(agentName, principal, request, turnContext, 
+        // A host may continue a subagent thread through the chat surface; keep
+        // resolving it the way its spawner would.
+        { parentAgent: chat.parentAgent });
         const prior = await storage.loadMessages(principal, resolvedChatId);
         // A new message while the last turn is parked on an approval is itself the
         // decision: the user declined to answer and wants to steer elsewhere. Close
@@ -2028,7 +2155,12 @@ export function createRuntime(config) {
         // reconcilable even if its (dynamic, DB-stored) agent was since deleted.
         // Before this ordering that throw also aborted `sweep`'s loop, so one such
         // run held up recovery for every other run until its attempts ran out.
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(run.agent, principal);
+        // A recovered subagent run must resolve exactly as its spawner shaped it —
+        // crash recovery and `sweep` both land here.
+        const chat = await storage.getChat(principal, run.chatId);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(run.agent, principal, undefined, undefined, {
+            parentAgent: chat?.parentAgent,
+        });
         // A resume was admitted when the turn first ran — never refuse it (the
         // half-done work would strand), but its tokens still settle against the
         // same counters, and the mid-turn stop still applies.
@@ -2133,57 +2265,115 @@ export function createRuntime(config) {
         // Merge the decisions onto the persisted assistant message, then re-persist
         // only what changed. The agent continues from this updated history.
         const messages = await storage.loadMessages(principal, chatId);
+        // A decision only means something for the message the turn paused on —
+        // the LAST one. An approval from further back (an old tab, an old Slack
+        // card, a late retry after the user moved on) was already settled: the
+        // next message declined it. Continuing anyway would run the agent again
+        // and append an answer nobody asked for. A real retry (a crash or a busy
+        // chat after the decision was saved) still finds its approval last.
+        const live = decisions.filter((d) => approvalIsLast(messages, d.approvalId));
+        if (live.length === 0)
+            return new Response(null, { status: 200 });
+        decisions = live;
         const changed = applyDecisions(messages, decisions);
         if (changed.length > 0)
             await storage.appendMessages(chatId, changed);
+        // Continue this chat from the decided history.
+        const continueTurn = async () => {
+            const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
+            const admitted = await admitContinuation(principal, chat.agent, "decision");
+            const { run, lease } = await openRun(principal, chatId, chat.agent, cfg.configVersion);
+            return buildTurnStream({
+                resolvedChatId: chatId,
+                principal,
+                modelId,
+                cfg,
+                run,
+                lease,
+                // Resume: strip the paused turn's trailing text so the model call ends on
+                // the tool result (a user turn), not an assistant prefill.
+                uiMessages: trimTrailingAssistantPrefill(messages),
+                runtimeCtx,
+                // A human just decided something, so a human is present — even if this
+                // turn parks again on the NEXT gate (see TurnTrigger).
+                trigger: "decision",
+                admitted,
+            });
+        };
         // Route any just-decided SUBAGENT approvals (bubbled up via spawn_agent):
         // resume the sub thread with the decision, then fold its answer back into
         // the parent's spawn_agent result so this turn continues with the digest.
+        //
+        // All of it streams in THIS response, which is the only channel back to a
+        // client already showing the paused message. The resume can run for
+        // minutes, pause on a SECOND gate, or fold an answer the client has never
+        // seen — answered with an empty body instead, the user saw their approval
+        // land and then nothing: no progress, and no card for the next gate, while
+        // the chat sat awaiting a decision it never offered.
         const subApprovals = collectDecidedSubagentApprovals(messages);
         if (subApprovals.length > 0) {
-            for (const sa of subApprovals) {
-                const resumed = await resumeSubagentApproval(principal, sa.subChatId, sa.subApprovalIds.map((id) => ({
-                    approvalId: id,
-                    approved: sa.approved,
-                    reason: sa.reason,
-                })), { parentRunId: sa.parentRunId, rootChatId: sa.rootChatId });
-                if (resumed.pending?.length) {
-                    // The resumed sub paused on ANOTHER gated tool — re-bubble it as a
-                    // fresh data-subagent-approval part on the same parent message. The
-                    // undecided part keeps this chat awaiting_input (hasPendingApproval
-                    // below), and the next decision routes through here again, so
-                    // bubbling recurses per round.
-                    const nextApprovalId = generateSubApprovalId();
-                    appendSubagentApprovalPart(messages, sa.approvalId, {
-                        approvalId: nextApprovalId,
-                        subChatId: sa.subChatId,
-                        subApprovalIds: resumed.pending.map((p) => p.approvalId),
-                        spawnToolCallId: sa.spawnToolCallId,
-                        summaries: resumed.pending.map((p) => p.summary),
-                        // Carry the linkage forward so each further resume stays nested.
-                        parentRunId: sa.parentRunId,
-                        rootChatId: sa.rootChatId,
-                    });
-                    if (sa.spawnToolCallId) {
-                        overwriteToolResult(messages, sa.spawnToolCallId, {
-                            status: "awaiting_approval",
-                            threadId: sa.subChatId,
-                            pending: resumed.pending.map((p) => p.summary),
-                            note: "Awaiting the user's approval — do not retry; stop here, the user will decide and you'll continue automatically.",
-                        });
+            const stream = createUIMessageStream({
+                execute: async ({ writer }) => {
+                    for (const sa of subApprovals) {
+                        const resumed = await resumeSubagentApproval(principal, sa.subChatId, sa.subApprovalIds.map((id) => ({
+                            approvalId: id,
+                            approved: sa.approved,
+                            reason: sa.reason,
+                        })), { parentRunId: sa.parentRunId, rootChatId: sa.rootChatId }, { writer, spawnToolCallId: sa.spawnToolCallId });
+                        let output;
+                        if (resumed.pending?.length) {
+                            // The resumed sub paused on ANOTHER gated tool — re-bubble it as a
+                            // fresh data-subagent-approval part on the same parent message. The
+                            // undecided part keeps this chat awaiting_input (hasPendingApproval
+                            // below), and the next decision routes through here again, so
+                            // bubbling recurses per round.
+                            const data = {
+                                approvalId: generateSubApprovalId(),
+                                subChatId: sa.subChatId,
+                                subApprovalIds: resumed.pending.map((p) => p.approvalId),
+                                spawnToolCallId: sa.spawnToolCallId,
+                                summaries: resumed.pending.map((p) => p.summary),
+                                // Carry the linkage forward so each further resume stays nested.
+                                parentRunId: sa.parentRunId,
+                                rootChatId: sa.rootChatId,
+                            };
+                            appendSubagentApprovalPart(messages, sa.approvalId, data);
+                            // Same id as the stored part, so the client reconciles it into the
+                            // paused message exactly as a reload would show it.
+                            writer.write({ type: "data-subagent-approval", id: data.approvalId, data });
+                            output = {
+                                status: "awaiting_approval",
+                                threadId: sa.subChatId,
+                                pending: resumed.pending.map((p) => p.summary),
+                                note: "Awaiting the user's approval — do not retry; stop here, the user will decide and you'll continue automatically.",
+                            };
+                        }
+                        else {
+                            output = { threadId: sa.subChatId, answer: resumed.answer };
+                        }
+                        if (sa.spawnToolCallId) {
+                            overwriteToolResult(messages, sa.spawnToolCallId, output);
+                            writer.write({ type: "tool-output-available", toolCallId: sa.spawnToolCallId, output });
+                        }
+                        markSubagentApprovalResolved(messages, sa.approvalId);
                     }
-                }
-                else if (sa.spawnToolCallId) {
-                    overwriteToolResult(messages, sa.spawnToolCallId, {
-                        threadId: sa.subChatId,
-                        answer: resumed.answer,
-                    });
-                }
-                markSubagentApprovalResolved(messages, sa.approvalId);
-            }
-            // Persist the folded spawn_agent result (or re-bubbled approval part)
-            // + resolved markers.
-            await storage.appendMessages(chatId, messages);
+                    // Persist the folded spawn_agent result (or re-bubbled approval part)
+                    // + resolved markers.
+                    await storage.appendMessages(chatId, messages);
+                    if (hasPendingApproval(messages)) {
+                        writer.write({ type: "finish" });
+                        return;
+                    }
+                    writer.merge(await continueTurn());
+                },
+                onError: (error) => clientErrorMessage(error),
+            });
+            return createUIMessageStreamResponse({
+                stream: stream,
+                // Drain server-side even if the client leaves: the resume must finish
+                // and persist either way, as every turn does (see buildTurnStream).
+                consumeSseStream: consumeStream,
+            });
         }
         // If the step had several gated calls and some are still undecided, DON'T
         // re-run yet — a tool call without a result makes convertToModelMessages
@@ -2192,24 +2382,9 @@ export function createRuntime(config) {
         if (hasPendingApproval(messages)) {
             return new Response(null, { status: 200 });
         }
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
-        const admitted = await admitContinuation(principal, chat.agent, "decision");
-        const { run, lease } = await openRun(principal, chatId, chat.agent, cfg.configVersion);
-        return buildTurn({
-            resolvedChatId: chatId,
-            principal,
-            modelId,
-            cfg,
-            run,
-            lease,
-            // Resume: strip the paused turn's trailing text so the model call ends on
-            // the tool result (a user turn), not an assistant prefill.
-            uiMessages: trimTrailingAssistantPrefill(messages),
-            runtimeCtx,
-            // A human just decided something, so a human is present — even if this
-            // turn parks again on the NEXT gate (see TurnTrigger).
-            trigger: "decision",
-            admitted,
+        return createUIMessageStreamResponse({
+            stream: (await continueTurn()),
+            consumeSseStream: consumeStream,
         });
     }
     /**
@@ -2240,7 +2415,7 @@ export function createRuntime(config) {
             await storage.appendMessages(chatId, changed);
             return new Response(null, { status: 200 });
         }
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
         const admitted = await admitContinuation(principal, chat.agent, "decision");
         // The result is persisted WITH the run (atomically where the adapter can):
         // a busy chat refuses before anything is recorded, so the retry finds the
@@ -2286,7 +2461,7 @@ export function createRuntime(config) {
         if (hasPendingApproval(live) || hasPendingToolResult([live[live.length - 1]])) {
             throw new PendingApprovalError("This chat is awaiting a decision — resolve the pending request before compacting.");
         }
-        const { cfg, modelId } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
+        const { cfg, modelId } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
         // Tool definitions only affect how a recorded tool RESULT is rendered for the
         // model (`toModelOutput`); an unknown tool falls back to its raw JSON rather
         // than failing. So take every definition available without I/O — the agent's
@@ -2419,11 +2594,14 @@ export function createRuntime(config) {
         return chat ? run : null;
     }
     /** A fresh user message from plain text (for cron-fired turns). */
-    function userMessageOf(text) {
+    function userMessageOf(text, files) {
         return {
             id: generateMessageId(),
             role: "user",
-            parts: [{ type: "text", text }],
+            parts: [
+                ...(files ?? []).map((f) => ({ type: "file", url: f.url, mediaType: f.mediaType, ...(f.filename ? { filename: f.filename } : {}) })),
+                { type: "text", text },
+            ],
             metadata: { visibility: "user", createdAt: Date.now() },
         };
     }
@@ -2485,8 +2663,15 @@ export function createRuntime(config) {
                 // Runtime-created thread: stamp it internal so a host filtering its
                 // chat list on kind never shows it (see ChatRecord.kind).
                 kind: "internal",
+                ...(o.parentAgent ? { parentAgent: o.parentAgent } : {}),
             });
         }
+        // A spawn may only continue a thread its own agent delegated. Otherwise
+        // agent B could pass agent A's sub-thread id and have the child resolved
+        // under A — borrowing whatever a host grants A's subagents.
+        if (o.parentAgent && chat.parentAgent && chat.parentAgent !== o.parentAgent) {
+            throw new Error(`Thread ${chatId} was delegated by another agent; omit threadId to start a new one.`);
+        }
         const prior = await storage.loadMessages(o.principal, chatId);
         // Same rule as handleChat: a new message while the thread is parked on an
         // approval IS the decision — close the stale gate as declined (persisted)
@@ -2503,7 +2688,14 @@ export function createRuntime(config) {
         // the run first, persist the message only once it is ours to run.
         const admitted = await admitTurn(o.principal, o.agent, o.trigger);
         const { cfg, modelId, runtimeCtx, run, lease } = await withReservation(admitted, async () => {
-            const resolved = await resolveAgentConfig(o.agent, o.principal, undefined, o.turnContext);
+            const resolved = await resolveAgentConfig(o.agent, o.principal, undefined, o.turnContext, {
+                // A continued thread keeps the parent it was created under (a mismatch
+                // was refused above). Without a stored one — an adapter that doesn't
+                // persist the column — the spawner of THIS turn is the parent: a host
+                // that restricts a subagent by its parent must never see none.
+                parentAgent: chat.parentAgent ?? o.parentAgent,
+                autoApprove: o.autoApprove,
+            });
             const opened = await openTurn(o.principal, chatId, o.agent, [o.message], resolved.cfg.configVersion);
             return { ...resolved, ...opened };
         });
@@ -2520,35 +2712,20 @@ export function createRuntime(config) {
             admitted,
             autoApprove: o.autoApprove,
             blockGated: o.blockGated,
+            memory: o.memory,
+            model: o.model,
             promptCaching: o.promptCaching,
             depth: o.depth ?? 0,
             parentRunId: o.parentRunId,
             rootChatId: o.rootChatId,
             trigger: o.trigger,
             // Forward progressive UI-message snapshots to the caller (spawn_agent
-            // streams them into the parent turn). Observation must never break the
-            // run — the primary stream is drained independently below.
-            observeStream: onProgress
-                ? (observed) => {
-                    void (async () => {
-                        try {
-                            const byId = new Map();
-                            for await (const m of readUIMessageStream({
-                                stream: observed,
-                            })) {
-                                const msg = m;
-                                byId.set(msg.id, msg);
-                                onProgress([o.message, ...byId.values()]);
-                            }
-                        }
-                        catch {
-                            // ignore — live progress is best-effort
-                        }
-                    })();
-                }
-                : undefined,
+            // streams them into the parent turn).
+            observeStream: onProgress ? progressObserver([o.message], onProgress) : undefined,
         });
-        await res.text();
+        // The turn's own failure travels as an `error` chunk — the stream, not a
+        // throw. Keep its text: without it a failed turn reads as a silent one.
+        const error = lastStreamError(await res.text());
         const after = await storage.loadMessages(o.principal, chatId);
         // The verdict is about THIS turn, so read the FINAL message only (the same
         // rule hasPendingApproval applies): an undecided gate in an older message
@@ -2563,6 +2740,7 @@ export function createRuntime(config) {
             answer: pending.length > 0 ? "" : lastAssistantText(after),
             parked,
             ...(pending.length > 0 ? { pending } : {}),
+            ...(error ? { error } : {}),
         };
     }
     /**
@@ -2577,7 +2755,13 @@ export function createRuntime(config) {
      */
     async function resumeSubagentApproval(principal, subChatId, decisions, 
     /** Telemetry linkage of the original sub-turn, so the trace stays nested. */
-    linkage) {
+    linkage, 
+    /**
+     * Stream the resumed sub-turn into the parent's response as the same
+     * `data-subagent-progress` part `spawn_agent` wrote, so the delegation the
+     * user just approved visibly runs again instead of sitting silent.
+     */
+    live) {
         const subChat = await storage.getChat(principal, subChatId);
         if (!subChat)
             return { answer: "" };
@@ -2588,9 +2772,29 @@ export function createRuntime(config) {
         // Another gated call in the same sub step still undecided → can't finish.
         if (hasPendingApproval(subMessages))
             return { answer: "" };
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(subChat.agent, principal);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(subChat.agent, principal, undefined, undefined, 
+        // Same shaping as the first sub-turn: the parent is read off the persisted
+        // sub-thread, and this path is only ever reached by a human decision.
+        { parentAgent: subChat.parentAgent, autoApprove: false });
         const admitted = await admitContinuation(principal, subChat.agent, "decision");
         const { run, lease } = await openRun(principal, subChatId, subChat.agent, cfg.configVersion);
+        const resumeFrom = trimTrailingAssistantPrefill(subMessages);
+        let observeStream;
+        if (live) {
+            const progress = subagentProgressWriter(live.writer, {
+                toolCallId: live.spawnToolCallId,
+                agent: subChat.agent,
+                threadId: subChatId,
+            });
+            // The exchange being resumed: its prompt and the paused assistant
+            // message, which the resumed turn extends in place.
+            const last = resumeFrom[resumeFrom.length - 1];
+            const continuing = last?.role === "assistant" ? last : undefined;
+            const prompt = resumeFrom.findLast((m) => m.role === "user");
+            const lead = prompt ? [prompt] : [];
+            progress.now(continuing ? [...lead, continuing] : lead);
+            observeStream = progressObserver(lead, progress.throttled, continuing);
+        }
         const res = await buildTurn({
             resolvedChatId: subChatId,
             principal,
@@ -2602,7 +2806,7 @@ export function createRuntime(config) {
             // Resume: same prefill guard as applyApproval — the paused sub turn may
             // have narrated after its gated call, and that text must not reach the
             // model as an assistant prefill.
-            uiMessages: trimTrailingAssistantPrefill(subMessages),
+            uiMessages: resumeFrom,
             runtimeCtx,
             autoApprove: false, // keep gating any further writes in the sub
             depth: 1,
@@ -2611,6 +2815,7 @@ export function createRuntime(config) {
             rootChatId: linkage?.rootChatId,
             // Reached only by a human deciding the bubbled-up approval.
             trigger: "decision",
+            observeStream,
         });
         await res.text();
         const after = await storage.loadMessages(principal, subChatId);
@@ -2825,24 +3030,26 @@ export function createRuntime(config) {
     const self = {
         listAgents: agentInfos,
         handleChat,
-        runAgent: async ({ principal, agent, prompt, threadId, blockGated = true, turnContext, promptCaching, 
+        runAgent: async ({ principal, agent, prompt, files, threadId, blockGated = true, memory, model, turnContext, promptCaching, 
         // No client stream: assume unattended unless the host says otherwise, so
         // a park here can't be silently filtered out as "someone's watching".
         trigger = "programmatic", }) => {
             const r = await runToCompletion({
                 principal,
                 agent,
-                message: userMessageOf(prompt),
+                message: userMessageOf(prompt, files),
                 chatId: threadId,
                 depth: 1,
                 // Autonomous: no human to authorize (blockGated stubs the gated tools).
                 autoApprove: true,
                 blockGated,
+                memory,
+                model,
                 turnContext,
                 promptCaching,
                 trigger,
             });
-            return { threadId: r.chatId, answer: r.answer };
+            return { threadId: r.chatId, answer: r.answer, ...(r.error ? { error: r.error } : {}) };
         },
         compactChat,
         loadHistory,