@adonis-agora/agent 0.31.0 → 0.33.1

package/dist/src/agent-loop.js

@@ -1,5 +1,12 @@
 import { publishAgentDelegated, publishAgentMessage, publishAgentRetrieved, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, spannedAgent, } from './diagnostics.js';
+import { ASK_TOOL_NAME, askInputSchema, askToolDefinition, DEFAULT_INTAKE_PREAMBLE, isHumanDecision, normalizeElicitationReply, settleElicitation, } from './elicitation.js';
+import { buildMemoryBlock, offerMemories, REMEMBER_TOOL_NAME, rememberInputSchema, rememberToolDefinition, writeMemory, } from './memory.js';
+import { createFrameBuffer, createIncrementalGate, gateTail, releaseGatedFrames, resolveGateLookback, resolveOutputGateMode, runInputProcessors, runOutputProcessors, } from './processors.js';
+import { isReplayIntegrityError } from './replay-integrity.js';
+import { buildSkillsBlock, loadSkill, offerSkills, SKILL_TOOL_NAME, skillInputSchema, skillToolDefinition, } from './skills.js';
 import { estimateCost, resolveModelPrice, } from './spi/pricing-store.js';
+import { OutputRejectedError, } from './spi/processors.js';
+import { DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, repairInstruction, StructuredOutputError, validateStructured, } from './structured-output.js';
 import { ToolForbiddenError, ToolInputInvalidError } from './tool-registry.js';
 import { invokeWithTransientRetry } from './tool-retry.js';
 /** Renders retrieved passages as a numbered, citable context block appended to the system prompt. */
@@ -23,6 +30,17 @@ function intersectAllow(a, b) {
     const second = new Set(b);
     return a.filter((name) => second.has(name));
 }
+/**
+ * The {@link AgentLoopHooks.parallel} implementation for a runner whose checkpoint positions are
+ * handed out on the CALL — `@adonis-agora/durable`'s `ctx.localStep` is: it takes `pos.next()`
+ * before its first `await`. Every task is invoked here, synchronously and in list order, before any
+ * of them is awaited, which is what fixes the block of positions they occupy whatever order they
+ * then settle in. Nothing rejects: the caller decides what an individual failure means.
+ */
+export function settleAll(tasks) {
+    const started = tasks.map((task) => task());
+    return Promise.all(started.map((work) => work.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }))));
+}
 export class QuotaExceededError extends Error {
     constructor() {
         super('Daily token quota exceeded');
@@ -60,6 +78,112 @@ function extractTask(input) {
     }
     return JSON.stringify(input);
 }
+/**
+ * How many agent→agent delegations deep a chain may go when the host names no ceiling.
+ *
+ * A backstop for a chain that is merely LONG. The cycle it would otherwise stand in for is detected
+ * directly — see {@link DEFAULT_MAX_AGENT_APPEARANCES}.
+ *
+ * WHEN IT ACTUALLY BINDS. At one appearance per agent a chain cannot be longer than the number of
+ * registered agents, so a deployment with fewer agents than this number never reaches it: the cycle
+ * guard always fires first. It starts mattering with a larger fleet than the ceiling, or once a host
+ * raises {@link AgentLoopDeps.maxAgentAppearances}, which is what lets a chain revisit an agent and
+ * therefore grow past the fleet's size.
+ */
+export const MAX_DELEGATION_DEPTH = 5;
+/**
+ * How many times one agent may appear on a single delegation chain, when the host names no other
+ * number. Once: a chain that reaches an agent it has already passed through is going in circles.
+ *
+ * Override with {@link AgentLoopDeps.maxAgentAppearances} — a supervisor that genuinely hands work
+ * back to an earlier agent needs a larger number, and it is the count of APPEARANCES, so 2 admits
+ * exactly one return.
+ */
+export const DEFAULT_MAX_AGENT_APPEARANCES = 1;
+/**
+ * Why this delegation must not happen, or `null` to let it through.
+ *
+ * Two different refusals, and the order matters: a CYCLE is named before a depth, because they
+ * describe different faults and the depth is the vaguer of the two. `alpha → beta → alpha` points at
+ * the wiring; "depth limit of 5 reached" leaves a reader to work out whether the chain was looping or
+ * merely long, which is exactly the question a count cannot answer.
+ *
+ * Decided from the run's own input and the agent's configured ceilings, inside the checkpoint that
+ * settles the call's kind — so the verdict is what a replay reads back rather than something each
+ * process re-derives.
+ */
+function delegationRefusal(args) {
+    const { deps, input, targetAgent } = args;
+    // `delegationPath` is the chain that REACHED this run, so this run's own agent is the last link of
+    // the chain a delegation from here would extend. Naming it is what makes the refusal describe the
+    // wiring: a mutual handoff reads `alpha → beta → alpha` rather than an `alpha → alpha` that no
+    // edge in the deployment declares. It also makes an agent delegating to ITSELF a cycle on the spot
+    // rather than one hop later.
+    const ancestry = [
+        ...(input.delegationPath ?? []),
+        ...(input.agentName !== undefined ? [input.agentName] : []),
+    ];
+    const appearances = ancestry.filter((name) => name === targetAgent).length;
+    const maxAppearances = deps.maxAgentAppearances ?? DEFAULT_MAX_AGENT_APPEARANCES;
+    if (appearances >= maxAppearances) {
+        const chain = [...ancestry, targetAgent].join(' → ');
+        const times = appearances + 1;
+        return `delegation cycle: ${chain} — ${targetAgent} ${times} times on one chain`;
+    }
+    const maxDepth = deps.maxDelegationDepth ?? MAX_DELEGATION_DEPTH;
+    if ((input.delegationDepth ?? 0) >= maxDepth) {
+        return `delegation depth limit of ${maxDepth} reached`;
+    }
+    return null;
+}
+/**
+ * The gates a delegation must clear. Delegation bypasses `ToolRegistry.invoke` (it is a ctx-level
+ * suspend point), so the three checks `invoke` applies have to be re-applied here in the same order
+ * — authorization first, then shape:
+ *  - the offered-tools (persona/agent allow-list) filter: a tool the model was not offered must not
+ *    run, even if the model names it anyway;
+ *  - the role/ability re-check. A synthesized delegate spec (`registerDelegateTools` in
+ *    agent-deps-factory.ts) carries whatever `roles`/`ability` its `delegatesTo` edge declared, and
+ *    nothing at all when the edge is a bare string — under `DefaultRolesPolicy` that is ADMIN-only,
+ *    and under an authz posture a tool with no `ability` is always denied;
+ *  - input validation, so a malformed input is rejected rather than silently coerced.
+ *
+ * Then the two nesting guards, once the target is known: {@link delegationRefusal} refuses a chain
+ * that is going in circles, or one that is merely too deep.
+ *
+ * Returns the verdict rather than throwing it: this runs inside the call's checkpoint, whose output
+ * is what a replay reads back, and it has to run BEFORE any event publication so a refusal never
+ * emits `agent.delegated`.
+ */
+async function resolveDelegation(deps, input, call, spec) {
+    try {
+        if (spec === undefined) {
+            // Unreachable while the kind is read off this same spec, but an `agent`-kind call with no
+            // resolvable spec must fail closed rather than fall through.
+            throw new ToolForbiddenError(call.name);
+        }
+        const offeredAllow = intersectAllow(input.persona?.allowedTools, deps.toolAllowList);
+        if (offeredAllow !== undefined && !offeredAllow.includes(call.name)) {
+            throw new ToolForbiddenError(call.name);
+        }
+        if (!(await deps.rolesPolicy.can(input.actor, spec))) {
+            throw new ToolForbiddenError(call.name);
+        }
+        const validation = await spec.inputSchema['~standard'].validate(call.input);
+        if (validation.issues !== undefined) {
+            throw new ToolInputInvalidError(call.name, validation.issues);
+        }
+        const targetAgent = spec.targetAgent ?? call.name;
+        const refusal = delegationRefusal({ deps, input, targetAgent });
+        if (refusal !== null) {
+            return { error: refusal };
+        }
+        return { targetAgent, task: extractTask(validation.value) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
 function deriveTitle(userText) {
     const trimmed = userText.trim().replace(/\s+/g, ' ');
     return trimmed.length > 60 ? `${trimmed.slice(0, 57)}...` : trimmed || 'New chat';
@@ -75,6 +199,925 @@ function resolveCostUsd(usage, reportedCostUsd, price) {
     }
     return price === undefined ? null : estimateCost(usage, price);
 }
+/** Renders a folded-history summary as the leading `system` message of a windowed turn. */
+function buildSummaryBlock(summary) {
+    return `<conversation_summary>\n${summary}\n</conversation_summary>\nEarlier messages in this thread are no longer included verbatim. Treat the summary above as an accurate record of them.`;
+}
+/**
+ * Identifies the split shape to {@link AgentLoopHooks.patched}: a run whose journal holds one
+ * `history:window` checkpoint has to keep replaying against that, not against a pure selection that
+ * spends no position at all. Reached only when a window is configured, so a deployment with none
+ * never spends the marker's position and records byte-identical checkpoints.
+ */
+const HISTORY_SELECT_PATCH = 'agent:history-select';
+/** The three answers, normalized out of whatever shape `load:thread` recorded them in. */
+function threadForTurn(recorded) {
+    const messages = (recorded?.messages ?? []).map(toModelMessage);
+    return {
+        messages,
+        title: recorded?.title ?? null,
+        hasAssistantMessage: recorded?.hasAssistantMessage ?? messages.some((message) => message.role === 'assistant'),
+    };
+}
+/**
+ * A message as the model sees it — the store's own bookkeeping (`id`, `createdAt`, `usage`,
+ * `followUps`, `runId`, `persona`) left behind, so what `load:thread` records is the prompt's rows
+ * rather than the table's.
+ */
+function toModelMessage(message) {
+    return {
+        role: message.role,
+        content: message.content,
+        ...(message.toolCalls !== undefined ? { toolCalls: message.toolCalls } : {}),
+        ...(message.toolResults !== undefined ? { toolResults: message.toolResults } : {}),
+        ...(message.attachments !== undefined ? { attachments: message.attachments } : {}),
+    };
+}
+/**
+ * How many of the thread's newest rows to ask for — the window's own row ceiling, or nothing at all,
+ * which asks for the transcript.
+ *
+ * A window that SUMMARIZES gets no limit. `summarize` is handed what `select` dropped, and a read
+ * bounded to what `select` keeps drops nothing: the turn would fold an empty summary into a prompt
+ * that is missing the messages it stands in for, with no error anywhere.
+ *
+ * A ceiling expressed only in TOKENS gets no limit either, and none can be derived from it: one
+ * message can be four tokens or forty thousand, so no row count follows from a token budget. Naming
+ * one too low reads fewer rows than `select` would have kept, which changes the prompt itself;
+ * leaving it out only costs the read.
+ */
+function turnMessageLimit(window) {
+    if (window === undefined || window.summarize !== undefined) {
+        return undefined;
+    }
+    return window.maxMessages;
+}
+/**
+ * Read the thread: the store's bounded WINDOW where it offers one, else its whole transcript cut to
+ * the same bound in process.
+ *
+ * The probe is structural — the window is an optimization a store either offers or does not, and one
+ * that offers none still answers correctly. Which branch ran is invisible to the journal on purpose:
+ * both produce the same three answers over the same rows, so the payload `load:thread` records is
+ * identical either way and a deployment's choice of store can never decide a run's checkpoints. That
+ * is also why the probe lives INSIDE `load:thread` — it adds no position, and a replaying process
+ * reads the recorded payload back without calling the store at all.
+ *
+ * `hasAssistantMessage` is answered over the whole thread, never over the window. It decides a
+ * `thread-start` intake, and a window that happens to hold only the user's last questions belongs to
+ * a conversation that has still been answered — scanned off the window, such a thread re-introduces
+ * itself every turn.
+ */
+async function readThreadForTurn(deps, threadId, messageLimit) {
+    const windowing = deps.store;
+    if (typeof windowing.loadThreadForTurn === 'function') {
+        const page = await windowing.loadThreadForTurn({
+            threadId,
+            ...(messageLimit !== undefined ? { messageLimit } : {}),
+        });
+        return page === null
+            ? { messages: [], title: null, hasAssistantMessage: false }
+            : {
+                messages: page.messages.map(toModelMessage),
+                title: page.title,
+                hasAssistantMessage: page.hasAssistantMessage,
+            };
+    }
+    const thread = await deps.store.getThread(threadId);
+    const stored = thread?.messages ?? [];
+    const window = messageLimit === undefined
+        ? stored
+        : stored.slice(Math.max(0, stored.length - Math.max(0, messageLimit)));
+    return {
+        messages: window.map(toModelMessage),
+        title: thread?.title ?? null,
+        hasAssistantMessage: stored.some((message) => message.role === 'assistant'),
+    };
+}
+/**
+ * Apply the configured ceiling to the thread's messages. `select` runs OUTSIDE any checkpoint — it
+ * is contractually pure and its input is already `load:thread`'s cached result, so a replay reaches
+ * the same split without a checkpoint of its own.
+ *
+ * Summarizing is the opposite: it calls a model. Journaled under `history:summarize`, so a resumed
+ * run reads back the summary the suspended attempt produced (and does not pay for it twice) instead
+ * of prompting with a different one. Both that checkpoint and the usage row below are reachable
+ * only through a window that actually summarizes.
+ */
+async function applyHistoryWindow(window, deps, input, hooks, messages, step) {
+    const ctx = { actor: input.actor, threadId: input.threadId };
+    const { keep, drop } = window.select(messages, ctx);
+    const summarize = window.summarize?.bind(window);
+    if (drop.length === 0 || summarize === undefined) {
+        return keep;
+    }
+    const summary = await step('history:summarize', () => summarize(drop, ctx));
+    if (summary.usage !== undefined) {
+        const usage = summary.usage;
+        await step('persist:usage:history', () => deps.store.recordUsage({
+            threadId: input.threadId,
+            actorRef: input.actor.id,
+            runId: hooks.runId,
+            modelId: summary.modelId ?? deps.modelId ?? 'unknown',
+            purpose: 'summary',
+            usage,
+        }));
+    }
+    return [{ role: 'system', content: buildSummaryBlock(summary.text) }, ...keep];
+}
+/**
+ * The turn's tool list plus the built-ins the module offers — `ask`, `skill`. Appended from CONFIG
+ * rather than the registry, because neither is ever registered: see {@link AgentLoopDeps.ask} and
+ * {@link AgentLoopDeps.skills}.
+ */
+export function withBuiltInTools(args) {
+    return [
+        ...args.tools,
+        ...(args.ask === true ? [askToolDefinition()] : []),
+        ...(args.skills ? [skillToolDefinition()] : []),
+        ...(args.memory ? [rememberToolDefinition()] : []),
+    ];
+}
+/**
+ * Does this deployment offer `remember` at all? A provider that serves memory read-only omits
+ * `write`, and then the tool is never offered — so a turn's tool list is the same on every process,
+ * decided by module config rather than by what a given pod happens to hold.
+ */
+function memoryIsWritable(deps) {
+    return deps.memory?.provider.write !== undefined;
+}
+/**
+ * Park on a question set, through whichever wait the host implemented, and read back whatever that
+ * wait delivered as answers.
+ *
+ * The reduction of a yes/no channel — approve is "confirmed the pre-picked answers", reject is
+ * "skipped" — applies to BOTH branches, because the shape of the reply is decided by whoever settled
+ * the tool call, not by which hook the host wired. The question set sits in the approvals inbox as a
+ * `pending_approval` action, so an operator pressing Approve there sends a `Decision` into a run
+ * whose host implements `awaitAnswers` perfectly well.
+ *
+ * Neither branch moves a checkpoint: the wait sits at the same position either way, so the choice of
+ * hook cannot change the sequence a replay lines up with.
+ */
+async function awaitElicitation(args) {
+    const { hooks, request, ctx } = args;
+    if (hooks.awaitAnswers !== undefined) {
+        return normalizeElicitationReply(await hooks.awaitAnswers(request, ctx));
+    }
+    return normalizeElicitationReply(await hooks.awaitApproval({ id: request.id, name: ASK_TOOL_NAME, input: request }, ctx));
+}
+/** How many wrong-shaped replies one approval wait absorbs before {@link awaitDecision} gives up. */
+const MAX_DISCARDED_APPROVAL_REPLIES = 100;
+/**
+ * Park on an `action`'s approval until a human's yes/no actually arrives.
+ *
+ * The wait carries both reply shapes, because a question set parks as a `pending_approval` action
+ * too — so a client can address `POST /agent/tool-call/answer` at a call that is in fact waiting on
+ * an approve/reject. A set of answers is not a verdict on proposed work; reading its absent
+ * `approved` as `false` would persist a rejection nobody made, against a tool whose operator only
+ * ever submitted a form. The reply is discarded and the approval stays pending, which is what it is.
+ *
+ * Waiting again spends another position, and a replay lines up with it: the reply that was discarded
+ * is itself journaled at the position it arrived on, so every process replaying the turn discards
+ * the same replies in the same order and reaches the same wait.
+ */
+async function awaitDecision(args) {
+    const { hooks, call, ctx } = args;
+    for (let discarded = 0; discarded < MAX_DISCARDED_APPROVAL_REPLIES; discarded += 1) {
+        const reply = await hooks.awaitApproval(call, ctx);
+        if (isHumanDecision(reply)) {
+            return reply;
+        }
+    }
+    // Both shipped runners wait here, so the ceiling is out of reach: a person would have to misdirect
+    // the whole budget at one tool call. What it rules out is a HOST whose `awaitApproval` resolves
+    // WITHOUT waiting — which would otherwise spin this loop on the only thread the process has.
+    throw new Error(`Tool call "${call.id}" was sent ${MAX_DISCARDED_APPROVAL_REPLIES} replies that carried no approve/reject`);
+}
+/**
+ * Does the configured intake run this turn? Both inputs are facts the journal already holds — the
+ * config, and `load:thread`'s record of whether the thread had an assistant message when the turn
+ * began. Neither is re-read from the store here, and that is the point: by the time a replay reaches
+ * this line the first attempt has already appended the intake's own assistant message to the thread,
+ * so a fresh read would answer differently on the resume than it did on the way in — and the answer
+ * decides how many checkpoints follow it.
+ */
+function intakeApplies(args) {
+    return args.intake.when === 'every-turn' || !args.threadHasAssistant;
+}
+/**
+ * The configured intake: post the authored question set, park until a human settles it, and leave
+ * the exchange on the transcript as an ordinary tool round-trip so the model reads the answers the
+ * same way it reads its own `ask`'s.
+ *
+ * COSTS NO MODEL CALL. The questions, their options and their pre-picked defaults are all authored
+ * on the agent, so nothing here is generated and nothing here is billed — which is also why the
+ * total is knowable before the first question is shown.
+ *
+ * One checkpoint whenever an `intake` is configured, plus two more on the turns it actually asks —
+ * all reachable only through that config, so a run that predates the option cannot land on any of
+ * them and no {@link AgentLoopHooks.patched} marker is spent keeping the sequence stable for it.
+ */
+async function runIntake(args) {
+    const { intake, deps, input, hooks, writer, threadHasAssistant } = args;
+    const preamble = intake.preamble ?? DEFAULT_INTAKE_PREAMBLE;
+    // Derived from the run, so a replay rebuilds the same id without minting one — the id is a
+    // checkpoint name's suffix and the signal's own key, so it cannot come from a random source.
+    const request = {
+        id: `intake-${hooks.runId}`,
+        source: 'intake',
+        preamble,
+        questions: intake.questions,
+    };
+    const call = {
+        id: request.id,
+        name: ASK_TOOL_NAME,
+        input: { preamble, questions: intake.questions },
+    };
+    const asked = (await hooks.step('intake:ask', async () => {
+        if (!intakeApplies({ intake, threadHasAssistant })) {
+            return null;
+        }
+        const message = await deps.store.appendMessage({
+            threadId: input.threadId,
+            role: 'assistant',
+            content: preamble,
+            runId: hooks.runId,
+            toolCalls: [call],
+            ...(input.persona !== undefined ? { persona: input.persona.id } : {}),
+        });
+        await deps.store.recordToolCall({
+            toolCallId: request.id,
+            messageId: message.id,
+            toolName: ASK_TOOL_NAME,
+            // The store knows read/action only. An unanswered question is work waiting on a human, which
+            // is what `action` + `pending_approval` already mean — so it surfaces in an approvals inbox
+            // rather than needing one of its own.
+            toolType: 'action',
+            input: call.input,
+            status: 'pending_approval',
+            runId: hooks.runId,
+        });
+        await writer.write({ t: 'elicitation', runId: hooks.runId, id: request.id, request });
+        return message.id;
+    }));
+    if (asked === null || asked === false) {
+        return null;
+    }
+    // A checkpoint that recorded only WHETHER the intake ran carries no message id, so such a run
+    // settles the tool-call row alone.
+    const messageId = typeof asked === 'string' ? asked : null;
+    const reply = await awaitElicitation({
+        hooks,
+        request,
+        ctx: elicitationContext(deps, input, hooks),
+    });
+    const result = settleElicitation({ request, reply });
+    await hooks.step('intake:answers', async () => {
+        await deps.store.updateToolCall({
+            toolCallId: request.id,
+            // A skip is not an answer. Both leave the agent holding the same values, but only one of them
+            // is evidence the user chose them, and a reader auditing what the agent was told has to be
+            // able to tell those apart.
+            status: result.skipped ? 'rejected' : 'executed',
+            output: result,
+            ...(result.skipped ? { error: 'skipped by the user' } : {}),
+            ...(reply.answeredByRef !== undefined ? { executedByRef: reply.answeredByRef } : {}),
+        });
+        if (messageId !== null) {
+            await deps.store.setMessageToolResults(messageId, [
+                { id: request.id, name: ASK_TOOL_NAME, output: result },
+            ]);
+        }
+    });
+    return {
+        role: 'assistant',
+        content: preamble,
+        toolCalls: [call],
+        toolResults: [{ id: request.id, name: ASK_TOOL_NAME, output: result }],
+    };
+}
+/** The context a wait is handed. The intake has no tool ctx of its own — it is not a tool call. */
+function elicitationContext(deps, input, hooks) {
+    return {
+        actor: input.actor,
+        threadId: input.threadId,
+        runId: hooks.runId,
+        requestId: hooks.runId,
+        ...(input.persona !== undefined ? { persona: input.persona } : {}),
+        ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+        ...(deps.host !== undefined ? { host: deps.host } : {}),
+    };
+}
+/**
+ * Identifies the batched tool-call shape to {@link AgentLoopHooks.patched}: batching hoists a turn's
+ * `persist:toolcall` checkpoints ahead of its first tool execution, so a run whose journal
+ * interleaves them one call at a time has to keep replaying against THAT.
+ */
+const PARALLEL_TOOLS_PATCH = 'agent:parallel-tools';
+/**
+ * Identifies the message-borne tool results to {@link AgentLoopHooks.patched}: attaching them adds a
+ * checkpoint after a turn's last tool, a position a run recorded under the shape without it cannot
+ * supply.
+ */
+const MESSAGE_TOOL_RESULTS_PATCH = 'agent:message-tool-results';
+/**
+ * Record the call and settle its KIND, which decides this call's control flow: an `action` suspends
+ * the run on an approval signal (`tool:<runId>:<callId>`), an `agent` delegates to a child run,
+ * anything else records a plain step. Resolving it from `deps.registry` in the loop body would tie
+ * that branch to the registry of WHICHEVER PROCESS runs the body — and a process whose registry
+ * lacks the tool reads `undefined`, falls back to 'read', and then asks for a `tool:` checkpoint
+ * where the history holds the approval signal. That is a non-determinism refusal on resume, and it
+ * is an approval-gated action about to run with nobody's approval.
+ *
+ * So the lookup — and the delegation gates that hang off it — happen INSIDE the `persist:toolcall`
+ * step, and the verdict is RETURNED from it. The first process to reach this call writes the kind
+ * into the journal; every later replay reads it back instead of asking its own registry.
+ */
+async function claimToolCall(turn, call) {
+    const { deps, input, hooks, messageId, writer } = turn;
+    const persona = input.persona;
+    const persisted = (await hooks.step(`persist:toolcall:${call.id}`, async () => {
+        // The kind the llm checkpoint stamped WINS: it came from the process that offered the tool,
+        // whereas this one is only the process claiming the call — and the two disagree exactly when
+        // that matters. The fallback is for a journal written before kinds travelled.
+        const kind = call.kind ?? declaredKind(deps, call.name);
+        if (kind === 'agent') {
+            const delegation = await resolveDelegation(deps, input, call, deps.registry.spec(call.name));
+            await deps.store.recordToolCall({
+                toolCallId: call.id,
+                messageId,
+                toolName: call.name,
+                // The store knows read/action only; a delegation is neither approved nor rejected by a
+                // human, so it persists as a read. A refused one is recorded `failed` directly — never
+                // `auto_executed` even transiently.
+                toolType: 'read',
+                input: call.input,
+                status: delegation.error !== undefined ? 'failed' : 'auto_executed',
+                runId: hooks.runId,
+            });
+            return { kind, delegation };
+        }
+        // An `ask` persists exactly as an `action` does: the store knows read/action only, and an
+        // unanswered question is work waiting on a human — which is what `pending_approval` already
+        // means, so it lands in the approvals inbox a deployment already has.
+        const parks = kind === 'action' || kind === 'ask';
+        await deps.store.recordToolCall({
+            toolCallId: call.id,
+            messageId,
+            toolName: call.name,
+            toolType: parks ? 'action' : 'read',
+            input: call.input,
+            status: parks ? 'pending_approval' : 'auto_executed',
+            runId: hooks.runId,
+        });
+        // Written from INSIDE this checkpoint, so the frame is streamed once and a replay — which
+        // returns the memoized result without re-running the body — never re-posts a form for a
+        // decision already made. That is also why it spends no position of its own.
+        //
+        // An `ask` is left out: `elicitToolCall` posts its `elicitation` frame, which carries the
+        // whole question set. Two frames for one parked call would be two forms.
+        if (kind === 'action') {
+            await writer.write({
+                t: 'approval',
+                runId: hooks.runId,
+                id: call.id,
+                toolName: call.name,
+                input: call.input,
+            });
+        }
+        return { kind };
+    }));
+    // A checkpoint written before the kind was journaled carries no output. Such a run is already
+    // committed to whatever its first process resolved, so the local registry is the only thing left
+    // to consult — reached by those runs alone.
+    const toolType = persisted?.kind ?? declaredKind(deps, call.name);
+    return {
+        call,
+        toolType,
+        ...(persisted?.delegation !== undefined ? { delegation: persisted.delegation } : {}),
+        ctx: {
+            actor: input.actor,
+            threadId: input.threadId,
+            runId: hooks.runId,
+            requestId: hooks.runId,
+            emitComponent: (name, data) => writer.write({ t: 'component', name, data }),
+            ...(persona !== undefined ? { persona } : {}),
+            ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+            ...(deps.host !== undefined ? { host: deps.host } : {}),
+        },
+    };
+}
+/**
+ * Execute one claimed call. Asks for its checkpoint SYNCHRONOUSLY — nothing is awaited before
+ * `hooks.step` — which is what lets a batch of these be launched together and still occupy
+ * positions in call order (see {@link AgentLoopHooks.parallel}).
+ *
+ * A tool's own failure is an OUTCOME, not a throw: the model is handed it as a result and adapts.
+ * Only the runner's control flow (a suspend / continue-as-new) and a replay-integrity refusal
+ * escape — answering either of those with a `persist:toolfail` checkpoint would ask for a position
+ * a diverged history has no room for, so the operator reads that second refusal instead of the
+ * disagreement that caused it.
+ *
+ * The retry loop runs INSIDE the `tool:<call.id>` step so it stays replay-safe: a durable step
+ * memoizes only its successful result, so on replay the whole step returns cached and the retries
+ * never re-run (side effects happen exactly once). The span sits inside the step body for the same
+ * reason, and covers all in-place attempts; the tool's output never rides it.
+ */
+/**
+ * The span's narrower tool vocabulary. An `ask` is settled against a human and a `skill` is read out
+ * of the journal, so neither reaches a registry invocation; each maps to the kind whose control flow
+ * it shares, for a reader of a trace who only ever sees the three.
+ */
+function spanToolType(kind) {
+    if (kind === 'ask') {
+        return 'action';
+    }
+    return kind === 'skill' || kind === 'memory' ? 'read' : kind;
+}
+async function invokeClaimedTool(turn, claimed) {
+    const { deps, hooks } = turn;
+    const { call, ctx, toolType } = claimed;
+    try {
+        const output = await hooks.step(`tool:${call.id}`, () => spannedAgent('tool.execution', hooks.runId, {
+            runId: hooks.runId,
+            toolCallId: call.id,
+            toolName: call.name,
+            toolType: spanToolType(toolType),
+        }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
+            ...(hooks.isControlFlowError !== undefined
+                ? { isControlFlowError: hooks.isControlFlowError }
+                : {}),
+            onRetry: (attempt, retryError) => {
+                publishAgentToolRetry({
+                    runId: hooks.runId,
+                    toolName: call.name,
+                    toolCallId: call.id,
+                    attempt,
+                    message: retryError instanceof Error ? retryError.message : String(retryError),
+                });
+            },
+        }), () => ({})));
+        return { status: 'executed', output };
+    }
+    catch (error) {
+        if (isReplayIntegrityError(error) || hooks.isControlFlowError?.(error) === true) {
+            throw error;
+        }
+        return { status: 'failed', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Persist one settled invocation and shape the result the model is fed. */
+async function recordToolOutcome(turn, claimed, outcome) {
+    const { deps, input, hooks } = turn;
+    const { call } = claimed;
+    // An `agent` call branches to delegation before reaching here, so anything that isn't an `action`
+    // is a read — the same posture the kind fallback itself takes.
+    const toolType = claimed.toolType === 'action' ? 'action' : 'read';
+    if (outcome.status === 'failed') {
+        await hooks.step(`persist:toolfail:${call.id}`, () => deps.store.updateToolCall({ toolCallId: call.id, status: 'failed', error: outcome.error }));
+        publishAgentToolCall({ runId: hooks.runId, toolName: call.name, toolType, status: 'failed' });
+        return { id: call.id, name: call.name, output: null, error: outcome.error };
+    }
+    await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({
+        toolCallId: call.id,
+        status: 'executed',
+        output: outcome.output,
+        ...(toolType === 'action' ? { executedByRef: input.actor.id } : {}),
+    }));
+    publishAgentToolCall({ runId: hooks.runId, toolName: call.name, toolType, status: 'executed' });
+    return { id: call.id, name: call.name, output: outcome.output };
+}
+/**
+ * Delegate to another agent (an `agent`-kind call). Dispatched at the LOOP level (not in a step)
+ * because the durable runner maps it to `ctx.child`, a ctx-level suspend point.
+ */
+async function delegateToolCall(turn, claimed) {
+    const { deps, input, hooks } = turn;
+    const { call } = claimed;
+    const delegation = claimed.delegation ??
+        (await resolveDelegation(deps, input, call, deps.registry.spec(call.name)));
+    if (delegation.error !== undefined) {
+        return { id: call.id, name: call.name, output: null, error: delegation.error };
+    }
+    const { targetAgent, task } = delegation;
+    publishAgentDelegated({
+        runId: hooks.runId,
+        toAgent: targetAgent,
+        ...(input.agentName !== undefined ? { fromAgent: input.agentName } : {}),
+    });
+    const sub = hooks.runAgent
+        ? await hooks.runAgent(targetAgent, task)
+        : { text: `(no multi-agent support wired; cannot reach "${targetAgent}")` };
+    await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({ toolCallId: call.id, status: 'executed', output: sub }));
+    return { id: call.id, name: call.name, output: sub };
+}
+/**
+ * Stamp each of a model turn's calls with the kind declared WHERE THE TOOL WAS OFFERED.
+ *
+ * A call exists only because some process put that tool's definition in front of the model, so that
+ * process is the one that certainly knows the tool. Another process might not: a deployment that
+ * splits its pods by role has one that serves HTTP and replays run bodies without registering the
+ * tool classes, and its registry answers `undefined`. Stamping here, INSIDE the llm checkpoint, is
+ * what puts the kind in the journal — so the branch a call takes is a fact about the turn rather
+ * than about whichever process happened to replay it (see {@link claimToolCall}).
+ *
+ * Only unstamped calls are touched: a kind already on a call was settled upstream, and a process
+ * further down never second-guesses it.
+ */
+function stampToolKinds(result, deps) {
+    return {
+        ...result,
+        toolCalls: result.toolCalls.map((call) => call.kind === undefined ? { ...call, kind: declaredKind(deps, call.name) } : call),
+    };
+}
+/**
+ * A call's declared kind, resolved from this process's own configuration and registry.
+ *
+ * Read by {@link stampToolKinds} where the tools were offered, which is the answer that then rides
+ * the journal; a claim falls back to it only for a call that arrives unstamped.
+ *
+ * The reserved `ask` name resolves from module CONFIG, never from the registry: `ask` has no handler
+ * to register, and grounding its branch in config is what keeps a process with a partial registry
+ * from disagreeing about it. Every other name is the registry's `ToolSpec`, as before.
+ */
+function declaredKind(deps, name) {
+    if (deps.ask === true && name === ASK_TOOL_NAME) {
+        return 'ask';
+    }
+    if (deps.skills !== undefined && name === SKILL_TOOL_NAME) {
+        return 'skill';
+    }
+    if (memoryIsWritable(deps) && name === REMEMBER_TOOL_NAME) {
+        return 'memory';
+    }
+    return deps.registry.spec(name)?.kind ?? 'read';
+}
+/**
+ * Settle an `ask` call against a human. The model authored the questions, so unlike the configured
+ * intake there is nothing to persist first — `persist:toolcall` already wrote the row, under the same
+ * name and at the same position any other kind would have used.
+ *
+ * Costs nothing beyond the step that produced it: the question set arrived as the ARGUMENTS of a tool
+ * call the model was already making, in a step already billed as `chat`. There is no second model
+ * call and therefore no usage row of its own — the opposite of the structured-output pass.
+ *
+ * The two new positions here (`stream:elicitation:<id>`, and the wait) are reachable only when this
+ * call's journaled kind is `ask`, which no run recorded before the kind existed. Every replay reads
+ * that kind back rather than re-deciding it, so no run can disagree about whether they are there.
+ */
+async function elicitToolCall(turn, claimed) {
+    const { deps, hooks } = turn;
+    const { call, ctx } = claimed;
+    // Validated HERE rather than by the registry, which never sees this tool. Deterministic on the
+    // same footing as `validateStructured`: a module-constant schema over an input the `llm:<i>`
+    // checkpoint already holds, so every replay reaches the same verdict — and the same branch.
+    const parsed = await askInputSchema['~standard'].validate(call.input);
+    if (parsed.issues !== undefined) {
+        const error = `invalid ask input: ${parsed.issues
+            .map((each) => `${(each.path ?? []).join('.') || '(root)'}: ${each.message}`)
+            .join('; ')}`;
+        await hooks.step(`persist:toolfail:${call.id}`, () => deps.store.updateToolCall({ toolCallId: call.id, status: 'failed', error }));
+        // A malformed question set is the model's mistake to fix, so it comes back as a tool failure —
+        // the vocabulary the model already knows how to answer — rather than failing the run.
+        return { id: call.id, name: call.name, output: null, error };
+    }
+    const request = {
+        id: call.id,
+        source: 'ask',
+        questions: parsed.value.questions,
+        ...(parsed.value.preamble !== undefined ? { preamble: parsed.value.preamble } : {}),
+    };
+    await hooks.step(`stream:elicitation:${call.id}`, () => Promise.resolve(turn.writer.write({ t: 'elicitation', runId: hooks.runId, id: call.id, request })));
+    const reply = await awaitElicitation({ hooks, request, ctx });
+    const result = settleElicitation({ request, reply });
+    await hooks.step(result.skipped ? `persist:toolreject:${call.id}` : `persist:toolexec:${call.id}`, () => deps.store.updateToolCall({
+        toolCallId: call.id,
+        status: result.skipped ? 'rejected' : 'executed',
+        output: result,
+        ...(result.skipped ? { error: 'skipped by the user' } : {}),
+        ...(reply.answeredByRef !== undefined ? { executedByRef: reply.answeredByRef } : {}),
+    }));
+    publishAgentToolCall({
+        runId: hooks.runId,
+        toolName: call.name,
+        toolType: 'action',
+        status: result.skipped ? 'rejected' : 'executed',
+    });
+    return { id: call.id, name: call.name, output: result };
+}
+/** The turn's identity as the skills seam sees it — the same inputs the prompt is resolved from. */
+function skillContext(input) {
+    return {
+        actor: input.actor,
+        threadId: input.threadId,
+        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+        ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+    };
+}
+/**
+ * Serve one `skill` call: read the body and hand it to the model as an ordinary tool result.
+ *
+ * WHY THE BODY IS RETURNED FROM THE CHECKPOINT. Which instructions entered a turn's prompt is a
+ * decision about the turn, and a decision about a turn has to be readable from its journal — the
+ * same property `persist:toolcall` gives the read/action branch. A replay that re-read the provider
+ * would compose a DIFFERENT prompt from a skill edited in between, at a transcript position the
+ * history already holds: the model would then be answering something nobody can reconstruct from the
+ * record. Inside `tool:<callId>` the first attempt's text is the only text there ever was.
+ *
+ * The positions are a read tool's, exactly (`persist:toolcall` before, `tool:<id>` here,
+ * `persist:toolexec:<id>` / `persist:toolfail:<id>` after), so nothing about the shape of a turn
+ * depends on whether a call was a skill — only on the kind the journal recorded.
+ */
+async function loadSkillIntoTurn(turn, claimed) {
+    const { deps, input, hooks } = turn;
+    const { call } = claimed;
+    const config = deps.skills;
+    const offer = turn.skills;
+    const outcome = await hooks.step(`tool:${call.id}`, async () => {
+        if (config === undefined || offer === undefined) {
+            // Reachable where a call's journaled kind is `skill` but this process has no skills
+            // configured. A tool failure, because it is the one vocabulary the model can act on, and
+            // because failing the run would strand a turn over a lookup.
+            return { ok: false, error: 'Skills are not available in this deployment.' };
+        }
+        const parsed = await skillInputSchema['~standard'].validate(call.input);
+        if (parsed.issues !== undefined) {
+            return {
+                ok: false,
+                error: `invalid skill input: ${parsed.issues
+                    .map((each) => `${(each.path ?? []).join('.') || '(root)'}: ${each.message}`)
+                    .join('; ')}`,
+            };
+        }
+        const loaded = await loadSkill({
+            config,
+            offer,
+            name: parsed.value.name,
+            ctx: skillContext(input),
+        });
+        if (!loaded.ok) {
+            return { ok: false, error: loaded.error };
+        }
+        return {
+            ok: true,
+            output: {
+                name: loaded.skill.name,
+                scope: loaded.skill.scope,
+                body: loaded.skill.body,
+                ...(loaded.shadows !== undefined ? { shadows: loaded.shadows } : {}),
+            },
+        };
+    });
+    return outcome.ok
+        ? { status: 'executed', output: outcome.output }
+        : { status: 'failed', error: outcome.error };
+}
+/**
+ * Serve one `remember` call: write the fact and hand the stored record back as an ordinary tool
+ * result.
+ *
+ * WHY THE WRITE HAPPENS INSIDE THE CHECKPOINT. Two reasons, and the second is the one that is easy
+ * to miss. It makes the write idempotent under replay — a resumed run reads the record back from
+ * `tool:<callId>` instead of storing a second copy of a fact the model only decided once. And it
+ * makes what the model was TOLD about the write part of the journal, so the transcript a later step
+ * reads is the one the first attempt built rather than whatever a second write would have returned.
+ *
+ * The positions are a read tool's, exactly, so nothing about the shape of a turn depends on whether
+ * a call wrote a memory — only on the kind the journal recorded.
+ */
+async function rememberIntoTurn(turn, claimed) {
+    const { deps, input, hooks } = turn;
+    const { call } = claimed;
+    const config = deps.memory;
+    const digest = turn.memory;
+    const outcome = await hooks.step(`tool:${call.id}`, async () => {
+        if (config === undefined || digest === undefined) {
+            // Reachable where a call's journaled kind is `memory` but this process has none configured.
+            // A tool failure, because it is the one vocabulary the model can act on, and because failing
+            // the run would strand a turn over a lookup.
+            return { ok: false, error: 'Memory is not available in this deployment.' };
+        }
+        const parsed = await rememberInputSchema['~standard'].validate(call.input);
+        if (parsed.issues !== undefined) {
+            return {
+                ok: false,
+                error: `invalid remember input: ${parsed.issues
+                    .map((each) => `${(each.path ?? []).join('.') || '(root)'}: ${each.message}`)
+                    .join('; ')}`,
+            };
+        }
+        return writeMemory({
+            config,
+            digest,
+            call: parsed.value,
+            ctx: skillContext(input),
+            runId: hooks.runId,
+        });
+    });
+    return outcome.ok
+        ? { status: 'executed', output: outcome.record }
+        : { status: 'failed', error: outcome.error };
+}
+/**
+ * Run one claimed call's INVOCATION, whatever kind it is. A `skill` reads the catalog the journal
+ * holds instead of the registry; everything that reaches here spends the same `tool:<id>` position
+ * either way, which is what lets the two be batched together.
+ */
+function invokeClaimed(turn, claimed) {
+    if (claimed.toolType === 'skill') {
+        return loadSkillIntoTurn(turn, claimed);
+    }
+    return claimed.toolType === 'memory'
+        ? rememberIntoTurn(turn, claimed)
+        : invokeClaimedTool(turn, claimed);
+}
+/** Everything a claimed call still needs, on its own: delegation or approval, then execute. */
+async function runClaimedToolCall(turn, claimed) {
+    const { deps, hooks } = turn;
+    const { call, toolType, ctx } = claimed;
+    if (toolType === 'agent') {
+        return delegateToolCall(turn, claimed);
+    }
+    if (toolType === 'ask') {
+        return elicitToolCall(turn, claimed);
+    }
+    if (toolType === 'action') {
+        const decision = await awaitDecision({ hooks, call, ctx });
+        if (!decision.approved) {
+            await hooks.step(`persist:toolreject:${call.id}`, () => deps.store.updateToolCall({
+                toolCallId: call.id,
+                status: 'rejected',
+                ...(decision.reason !== undefined ? { error: decision.reason } : {}),
+            }));
+            publishAgentToolCall({
+                runId: hooks.runId,
+                toolName: call.name,
+                toolType,
+                status: 'rejected',
+            });
+            return {
+                id: call.id,
+                name: call.name,
+                output: { rejected: true, reason: decision.reason ?? DEFAULT_REFUSAL_REASON },
+                denied: true,
+                // What the MODEL is told. The bare word `rejected` names no actor and reads exactly like a
+                // tool that blew up, so the answer that follows speculates about causes ("the key may not
+                // exist", "there may be permission restrictions") and offers to run it again. A person's
+                // decision is not a fault to diagnose, so this says who decided, that nothing ran, and what
+                // not to do next.
+                error: refusalNarrative(decision.reason),
+            };
+        }
+    }
+    return recordToolOutcome(turn, claimed, await invokeClaimed(turn, claimed));
+}
+/** Stored as the reason when someone declines without giving one — a placeholder, not a quote. */
+export const DEFAULT_REFUSAL_REASON = 'rejected by user';
+/**
+ * How a refusal is put to the model. Written as instructions rather than as a status because the
+ * model's next move is the whole problem: told only that something was "rejected", it treats the
+ * refusal as a fault, lists possible causes it cannot check, and offers to retry the same action —
+ * which asks the person to say no twice.
+ */
+function refusalNarrative(reason) {
+    const base = 'The person was asked to approve this action and declined it. Nothing ran and nothing changed. ' +
+        'This is their decision, not an error, a missing record or a permissions problem — do not ' +
+        'explain it as one, do not guess at causes, and do not run this action again or reach for ' +
+        'another way to do the same thing. Acknowledge the decision and ask what they would like instead.';
+    return reason === undefined ? base : `${base} They said: ${reason}`;
+}
+/**
+ * Overlap the INVOCATIONS of a batch of claimed calls, and only those. The persist checkpoints on
+ * either side stay strictly sequential, in call order — they are asked for after their neighbours'
+ * positions are already spent, so nothing about them depends on which tool finished first.
+ *
+ * A rejection here is the runner unwinding the turn, never a tool's own failure
+ * ({@link invokeClaimedTool} reports those). Rethrow the first one in call order and persist
+ * NOTHING: the resume replays this whole block, and a `persist:toolexec` written now would sit at
+ * the position the replay computes for an earlier call's.
+ */
+async function invokeClaimedToolsTogether(turn, parallel, claimed) {
+    const settled = await parallel(claimed.map((entry) => () => invokeClaimed(turn, entry)));
+    for (const outcome of settled) {
+        if (!outcome.ok) {
+            throw outcome.error;
+        }
+    }
+    const results = [];
+    for (const [index, entry] of claimed.entries()) {
+        const outcome = settled[index];
+        if (outcome?.ok === true) {
+            results.push(await recordToolOutcome(turn, entry, outcome.value));
+        }
+    }
+    return results;
+}
+/**
+ * What the formatting pass is shown. By default the QUESTION and the ANSWER — the pass is a
+ * translation of the answer, and its own instruction tells the model to use only what the
+ * conversation already contains, so handing it the whole transcript again would roughly double what
+ * a turn with an `outputSchema` costs for nothing. See {@link AgentLoopDeps.outputFromTranscript}
+ * for the agent that genuinely needs more, and why it is off by default.
+ *
+ * The question comes off the PROCESSED prompt rather than `AgentRunInput.userText`: this pass is a
+ * second route out of the model and has to stand behind the same input chain the streamed turn did,
+ * so a question a processor masked cannot reappear in the clear here.
+ */
+function restatementPrompt(args) {
+    const restated = { role: 'assistant', content: args.answer };
+    if (args.fromTranscript) {
+        return [...args.messages, restated];
+    }
+    // The last user message that actually SAYS something. The loop feeds a step's tool results back
+    // as an empty `user` message carrying `toolResults`, so scanning for the last `user` role alone
+    // would hand the pass a blank question on every turn that called a tool.
+    for (let index = args.messages.length - 1; index >= 0; index -= 1) {
+        const message = args.messages[index];
+        if (message?.role === 'user' && message.content.length > 0) {
+            return [message, restated];
+        }
+    }
+    return [restated];
+}
+/**
+ * Restate a finished answer as `deps.outputSchema`, repairing a rejected reply up to
+ * `outputRepairAttempts` times. Every model call is its own checkpoint (`structured:<step>:<n>`)
+ * with its own usage row, so a suspend between two attempts resumes on the reply the first one got
+ * rather than paying for a third.
+ *
+ * Validation itself sits OUTSIDE the checkpoints, on the same footing as `HistoryWindow.select`: its
+ * inputs are the schema (module config, identical on every process of a deployment) and a reply a
+ * checkpoint already holds, so every replay reaches the same verdict — and therefore the same number
+ * of attempts — without a checkpoint of its own.
+ *
+ * THE OUTPUT CHAIN RULES ON EACH ATTEMPT, before the schema does. This pass is a second route out of
+ * the model, so anything the chain held back from the prose must not be able to leave through here.
+ * It is gated on the WHOLE reply regardless of what the chain declared, because nothing here is
+ * streamed — there is no prefix for an `incremental` processor to release.
+ */
+async function structureAnswer(args) {
+    const { schema, deps, input, hooks, messages, step, ctx } = args;
+    const instruction = deps.outputInstruction ?? DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION;
+    const maxAttempts = 1 + (deps.outputRepairAttempts ?? 1);
+    const outputProcessors = deps.outputProcessors ?? [];
+    let issues = [];
+    let text = '';
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const system = attempt === 0 ? instruction : repairInstruction({ instruction, issues });
+        const reply = await hooks.step(`structured:${step}:${attempt}`, async () => {
+            // A sink that drops every frame: this call is not the turn's answer, so its tokens must never
+            // reach the reader's stream alongside the prose they are restating.
+            const discard = { write: () => { }, end: () => { } };
+            const turn = await deps.model.runTurn({
+                system,
+                messages,
+                tools: [],
+                sink: discard,
+                outputSchema: schema,
+            });
+            return {
+                text: turn.text,
+                usage: turn.usage,
+                ...(turn.object !== undefined ? { object: turn.object } : {}),
+                ...(turn.modelId !== undefined ? { modelId: turn.modelId } : {}),
+            };
+        });
+        await hooks.step(`persist:usage:structured:${step}:${attempt}`, () => deps.store.recordUsage({
+            threadId: input.threadId,
+            actorRef: input.actor.id,
+            runId: hooks.runId,
+            modelId: reply.modelId ?? deps.modelId ?? 'unknown',
+            purpose: 'structured_output',
+            usage: reply.usage,
+        }));
+        text = reply.text;
+        if (outputProcessors.length > 0) {
+            // Its own checkpoint, after the usage row: the tokens were spent either way, and a refusal
+            // that also hid its own cost would let a mis-tuned gate burn a budget invisibly — the same
+            // ordering the streamed answer's gate takes.
+            const gate = await hooks.step(`process:output:structured:${step}:${attempt}`, () => runOutputProcessors({
+                processors: outputProcessors,
+                answer: { text: reply.text, toolCalls: [] },
+                ctx,
+            }));
+            if (gate.rejection !== undefined) {
+                throw new OutputRejectedError(gate.rejection.processor, gate.rejection.reason);
+            }
+            text = gate.text;
+        }
+        // A provider that constrained its own generation reports a parsed `object`, but that object
+        // describes the reply the chain has just rewritten. Once the two disagree, the gated text is the
+        // only version anything downstream may see, so it is re-parsed rather than trusted.
+        const reported = text === reply.text ? reply.object : undefined;
+        const outcome = await validateStructured({ schema, text, reported });
+        if (outcome.ok) {
+            return outcome.value;
+        }
+        issues = outcome.issues;
+    }
+    throw new StructuredOutputError(issues, text, maxAttempts);
+}
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
@@ -84,6 +1127,17 @@ export async function runAgentLoop(deps, input, hooks) {
     const maxSteps = deps.maxSteps ?? 8;
     const persona = input.persona;
     let system = await resolveSystemPrompt(deps, input);
+    const inputProcessors = deps.inputProcessors ?? [];
+    const outputProcessors = deps.outputProcessors ?? [];
+    const gateMode = resolveOutputGateMode(outputProcessors);
+    const gateLookback = resolveGateLookback(outputProcessors);
+    const processorContext = (step) => ({
+        threadId: input.threadId,
+        actor: input.actor,
+        step,
+        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+        ...(persona !== undefined ? { persona: persona.id } : {}),
+    });
     // Open the run (turn) row FIRST — before the quota gate — so even a quota-rejected run is tracked
     // (the runner settles it `failed`). A checkpointed step so a durable replay reuses the ONE row (no
     // duplicate on resume); `run_id` is then stamped onto every message / tool call / usage row below.
@@ -93,6 +1147,7 @@ export async function runAgentLoop(deps, input, hooks) {
         actor: input.actor,
         durable: hooks.durable ?? false,
         ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+        ...(input.parentRunId !== undefined ? { parentRunId: input.parentRunId } : {}),
     }));
     if (deps.quota !== undefined) {
         const quota = deps.quota;
@@ -112,23 +1167,21 @@ export async function runAgentLoop(deps, input, hooks) {
         ...(persona !== undefined ? { persona: persona.id } : {}),
         ...(input.attachments !== undefined ? { attachments: input.attachments } : {}),
     }));
-    const thread = await hooks.step('load:thread', () => deps.store.getThread(input.threadId));
-    const fullHistory = (thread?.messages ?? []).map((message) => ({
-        role: message.role,
-        content: message.content,
-        ...(message.toolCalls !== undefined ? { toolCalls: message.toolCalls } : {}),
-        ...(message.toolResults !== undefined ? { toolResults: message.toolResults } : {}),
-        ...(message.attachments !== undefined ? { attachments: message.attachments } : {}),
-    }));
-    // Compaction runs INSIDE the step body (replay-safe): a summarizing impl spends its own tokens,
-    // which a durable replay must never pay twice. With no window configured this is the identity
-    // function, so an existing deployment sends byte-identical history.
-    const modelMessages = deps.historyWindow !== undefined
-        ? await hooks.step('history:window', async () => deps.historyWindow.apply(fullHistory, {
-            actor: input.actor,
-            threadId: input.threadId,
-        }))
-        : fullHistory;
+    const thread = threadForTurn(await hooks.step('load:thread', () => readThreadForTurn(deps, input.threadId, turnMessageLimit(deps.historyWindow))));
+    // With no window configured this whole block is skipped, so an existing deployment sends the
+    // messages `load:thread` returned and records byte-identical checkpoints.
+    let modelMessages = thread.messages;
+    if (deps.historyWindow !== undefined) {
+        const window = deps.historyWindow;
+        modelMessages = (await (hooks.patched?.(HISTORY_SELECT_PATCH) ?? Promise.resolve(true)))
+            ? await applyHistoryWindow(window, deps, input, hooks, thread.messages, hooks.step)
+            : // A run whose history holds the single `history:window` checkpoint replays against it: a
+                // completed one returns its recorded messages without re-running anything, and one that has
+                // yet to reach it runs the whole fold INSIDE that one checkpoint — nested checkpoints would
+                // take positions the recorded shape never had, and go missing the moment the outer one
+                // replays from cache.
+                await hooks.step('history:window', () => applyHistoryWindow(window, deps, input, hooks, thread.messages, (_name, fn) => fn()));
+    }
     const writer = await hooks.openSink();
     let lastText = '';
     let steps = 0;
@@ -138,12 +1191,45 @@ export async function runAgentLoop(deps, input, hooks) {
     // priced). If NO step had a cost, the run's `cost_usd` stays `null` — never a fabricated `0`.
     let totalCost = 0;
     let hasCost = false;
+    let structured;
     publishAgentRunStarted({
         runId: hooks.runId,
         threadId: input.threadId,
         actorId: input.actor.id,
         ...(persona !== undefined ? { persona: persona.id } : {}),
     });
+    // What the assistant already believes about this person, folded in ABOVE the retrieved passages
+    // and the skills catalog — most durable first, so a reader meets the standing facts before the
+    // passages this one question pulled.
+    //
+    // One checkpoint, holding the WHOLE digest: the scopes the resolver returned and the entries that
+    // survived selection, precedence and the ceiling. That payload is what the block is rendered from
+    // AND what a later `remember` call is authorized against — so which memories entered this prompt,
+    // and which scopes this turn could write, are facts the journal holds rather than answers a
+    // replaying process's provider would give afresh. Where the host runs an index, the SEARCH happens
+    // in here too: a ranking is the most re-derivable decision in this library, so a replay has to
+    // read its result back rather than ask an index that has since moved.
+    //
+    // THE QUERY IS THE USER'S OWN MESSAGE, and nothing else. It is the only thing available before the
+    // first model call — which is where memory has to be, since a memory is worthless unless it is in
+    // front of the model on the turn nobody thought to look — and it is already a journaled input to
+    // this run, so it needs no determinism machinery of its own. What it fails at is a turn with no
+    // topic ("and the other thing?"): `pinned` is the answer to those, not a cleverer query.
+    let memoryDigest;
+    if (deps.memory !== undefined) {
+        const config = deps.memory;
+        memoryDigest = await hooks.step('memory:digest', () => offerMemories({ config, ctx: skillContext(input), query: input.userText }));
+        // No entries, no block: an actor the assistant has concluded nothing about pays nothing, rather
+        // than reading a heading over an empty list and inferring something from its presence.
+        const digest = memoryDigest;
+        if (digest.entries.length > 0) {
+            system = `${system}\n\n${buildMemoryBlock({
+                entries: digest.entries,
+                writable: memoryIsWritable(deps),
+                partial: digest.omitted > 0 || digest.recalled === true,
+            })}`;
+        }
+    }
     // Inject-mode RAG: retrieve once for the user message and fold the passages into the system prompt.
     // Wrapped in `hooks.step` so a durable replay reuses the SAME passages (no re-query, deterministic
     // prompt). Recorded below as a synthetic auto-executed `retrieve` tool call on the first assistant
@@ -206,6 +1292,25 @@ export async function runAgentLoop(deps, input, hooks) {
             count: passages.length,
         });
     }
+    // The skills catalog, LAST of the things that write the system block (base prompt, persona,
+    // retrieved context, this) — so a reader of the assembled prompt meets the agent's own
+    // instructions before the menu of ones it could go and fetch.
+    //
+    // One checkpoint, holding the WHOLE offer: the scopes the resolver returned and the entries that
+    // survived precedence. That payload is what the block is rendered from and what a later `skill`
+    // call is served against, so the two things a turn's prompt depends on — which scopes applied, and
+    // which skills they yielded — are facts the journal holds rather than answers a replaying
+    // process's provider would give afresh.
+    let skillOffer;
+    if (deps.skills !== undefined) {
+        const config = deps.skills;
+        skillOffer = await hooks.step('skills:catalog', () => offerSkills(config, skillContext(input)));
+        // No entries, no block: an actor whose scopes yield nothing pays nothing, rather than reading a
+        // heading over an empty list and wondering what it was for.
+        if (skillOffer.entries.length > 0) {
+            system = `${system}\n\n${buildSkillsBlock(skillOffer.entries)}`;
+        }
+    }
     // Fetched ONCE per run (not per step) and reused for every step's cost estimate below. Returned as
     // a plain array (not the Map built from it) so a durable runner can JSON-cache the step's result.
     let prices = [];
@@ -214,21 +1319,126 @@ export async function runAgentLoop(deps, input, hooks) {
         prices = await hooks.step('pricing:list', () => pricingStore.listCurrentPrices());
     }
     const priceByModel = new Map(prices.map((price) => [price.modelId, price]));
+    // The configured intake, LAST before the first model call: everything the run records about itself
+    // (the run row, retrieval, prices) is settled before the turn parks on a person, who may take a
+    // day. The whole block is reachable only through `deps.intake`.
+    if (deps.intake !== undefined) {
+        const asked = await runIntake({
+            intake: deps.intake,
+            deps,
+            input,
+            hooks,
+            writer,
+            // Whether this thread had already been answered when the turn began — taken off
+            // `load:thread`'s CACHED result so a replay decides the intake the way the first attempt did.
+            threadHasAssistant: thread.hasAssistantMessage,
+        });
+        if (asked !== null) {
+            modelMessages.push(asked);
+        }
+    }
     // NOTE: no try/finally around this loop. A durable runner suspends by THROWING through the stack
     // at `awaitApproval` (ctx.waitForSignal); a finally would then call writer.end() on every suspend
     // and prematurely close the live stream. We only end on normal completion — the throw propagates
     // to the engine, and the resumed replay reaches the writer.end() below.
     for (let i = 0; i < maxSteps; i += 1) {
-        const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, intersectAllow(persona?.allowedTools, deps.toolAllowList));
+        const tools = withBuiltInTools({
+            tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, intersectAllow(persona?.allowedTools, deps.toolAllowList)),
+            ask: deps.ask,
+            skills: skillOffer !== undefined,
+            memory: memoryDigest !== undefined && memoryIsWritable(deps),
+        });
+        // Every step, not once per run: the transcript grows between steps, so a processor that only saw
+        // the opening prompt would wave through whatever a tool result carried back. The result is a
+        // per-step DERIVED prompt — `modelMessages` stays the loop's canonical transcript, so a redaction
+        // never becomes the thread's own memory of what was said.
+        let prompt = { system, messages: modelMessages };
+        if (inputProcessors.length > 0) {
+            prompt = await hooks.step(`process:input:${i}`, () => runInputProcessors({ processors: inputProcessors, prompt, ctx: processorContext(i) }));
+        }
         // Span the model call INSIDE the step body (replay-safe). The turn's raw text/output never rides
         // the span — only token counts + name/length metadata (the point events' redaction posture).
-        const turn = await hooks.step(`llm:${i}`, () => spannedAgent('llm.turn', hooks.runId, { runId: hooks.runId, step: i }, () => deps.model.runTurn({ system, messages: modelMessages, tools, sink: writer }), (result) => ({
+        // Stamped from THIS process's registry, which is the one that built `tools` for the call above —
+        // and stamped INSIDE the checkpoint, so the kinds are journaled with the calls they describe
+        // rather than re-derived by whatever process replays this turn.
+        let turn = await hooks.step(`llm:${i}`, async () => stampToolKinds(await spannedAgent('llm.turn', hooks.runId, { runId: hooks.runId, step: i }, async () => {
+            const incremental = gateMode === 'incremental'
+                ? createIncrementalGate({
+                    processors: outputProcessors,
+                    ctx: processorContext(i),
+                    lookbackChars: gateLookback,
+                    writer,
+                })
+                : undefined;
+            const buffer = gateMode === 'whole' ? createFrameBuffer() : undefined;
+            const result = await deps.model.runTurn({
+                system: prompt.system,
+                messages: prompt.messages,
+                tools,
+                sink: incremental?.writer ?? buffer?.writer ?? writer,
+            });
+            if (incremental !== undefined) {
+                await incremental.settled();
+                const refusal = incremental.rejection();
+                return {
+                    ...result,
+                    releasedText: incremental.released(),
+                    ...(refusal !== undefined ? { gateRejection: refusal } : {}),
+                };
+            }
+            return buffer === undefined ? result : { ...result, bufferedFrames: buffer.frames() };
+        }, (result) => ({
             ...(result.modelId !== undefined ? { modelId: result.modelId } : {}),
             inputTokens: result.usage.inputTokens,
             outputTokens: result.usage.outputTokens,
             textLength: result.text.length,
             toolCalls: result.toolCalls.length,
-        })));
+        })), deps));
+        // The gate runs before ANYTHING downstream: before the held frames reach the subscriber, before
+        // the assistant message is persisted, before this text becomes the next step's context.
+        let rejection;
+        if (gateMode !== 'off') {
+            const gate = await hooks.step(`process:output:${i}`, async () => {
+                // Which release this turn still owes is read from the JOURNALED model result, never from the
+                // chain configured on whichever process is running now: `releasedText` is the record that a
+                // prefix already reached the reader, so a run that resumes under a re-declared chain cannot
+                // flush the same answer a second time.
+                const released = turn.releasedText;
+                // A refusal an incremental gate already reached. Re-running the chain would bill the same
+                // verdict twice.
+                if (turn.gateRejection !== undefined) {
+                    return { text: turn.text, rejection: turn.gateRejection };
+                }
+                const settled = await runOutputProcessors({
+                    processors: outputProcessors,
+                    answer: { text: turn.text, toolCalls: turn.toolCalls },
+                    ctx: processorContext(i),
+                });
+                // Releasing inside the same checkpoint as the verdict is what makes "refused" and "nothing
+                // was streamed" one fact rather than two that a suspend could separate. For an incremental
+                // turn the second half of that is weaker by construction — a prefix is already out — and the
+                // whole-answer pass stays authoritative for both the stream and the store.
+                if (settled.rejection === undefined) {
+                    if (released === undefined) {
+                        for (const frame of releaseGatedFrames({
+                            frames: turn.bufferedFrames ?? [],
+                            text: settled.text,
+                        })) {
+                            await writer.write(frame);
+                        }
+                    }
+                    else {
+                        const tail = gateTail({ processors: outputProcessors, released, text: settled.text });
+                        if (tail.length > 0) {
+                            await writer.write({ t: 'text', v: tail });
+                        }
+                    }
+                }
+                return settled;
+            });
+            rejection = gate.rejection;
+            turn = { ...turn, text: gate.text };
+        }
         // provider-reported model wins over the configured fallback, so cost can't misattribute
         const resolvedModelId = turn.modelId ?? deps.modelId ?? 'unknown';
         // Provider-reported spend wins; else an estimate from the (once-per-run cached) price list; else
@@ -254,16 +1464,72 @@ export async function runAgentLoop(deps, input, hooks) {
             const quota = deps.quota;
             await hooks.step(`quota:bump:${i}`, () => quota.bump(input.actor.id, deps.day, turn.usage.inputTokens + turn.usage.outputTokens));
         }
+        // Thrown only AFTER the two accounting checkpoints above: those tokens were genuinely spent, and
+        // a refusal that also hid its own cost would let a mis-tuned gate burn a budget invisibly.
+        if (rejection !== undefined) {
+            throw new OutputRejectedError(rejection.processor, rejection.reason);
+        }
         steps += 1;
         totalInput += turn.usage.inputTokens;
         totalOutput += turn.usage.outputTokens;
         lastText = turn.text;
+        // Restating the GATED text, never the model's raw reply: the formatting pass is a translation of
+        // the answer that survived the output chain, not a second route out of the model.
+        if (turn.toolCalls.length === 0 && deps.outputSchema !== undefined) {
+            structured = await structureAnswer({
+                schema: deps.outputSchema,
+                deps,
+                input,
+                hooks,
+                messages: restatementPrompt({
+                    messages: prompt.messages,
+                    answer: turn.text,
+                    fromTranscript: deps.outputFromTranscript === true,
+                }),
+                step: i,
+                ctx: processorContext(i),
+            });
+        }
         publishAgentMessage({
             runId: hooks.runId,
             threadId: input.threadId,
             role: 'assistant',
             textLength: turn.text.length,
         });
+        // Inject-mode retrieval and the structured answer both reach a reader as ordinary tool calls.
+        // Their ids come off the RUN rather than the message they hang from, because the message does
+        // not exist yet and both have to be on the append below: a reader pairs a call with its result
+        // off the message, so a call added afterwards renders as a tool still running. Every value here
+        // is already settled by a checkpoint this turn ran (`retrieve`, `structured:<step>:<n>`), so a
+        // replay rebuilds the same pair rather than minting one.
+        const synthetic = [];
+        if (i === 0 && injectedPassages !== undefined) {
+            const call = {
+                id: `retrieve-${hooks.runId}`,
+                name: 'retrieve',
+                input: { query: input.userText },
+            };
+            const output = { passages: injectedPassages };
+            synthetic.push({
+                step: 'persist:retrieval',
+                call,
+                result: { id: call.id, name: call.name, output },
+            });
+        }
+        if (structured !== undefined) {
+            const call = {
+                id: `structured-${hooks.runId}`,
+                name: 'structured_output',
+                input: {},
+            };
+            synthetic.push({
+                step: 'persist:structured',
+                call,
+                result: { id: call.id, name: call.name, output: structured },
+            });
+        }
+        const messageCalls = [...turn.toolCalls, ...synthetic.map((entry) => entry.call)];
+        const syntheticResults = synthetic.map((entry) => entry.result);
         const assistant = await hooks.step(`persist:assistant:${i}`, () => deps.store.appendMessage({
             threadId: input.threadId,
             role: 'assistant',
@@ -271,219 +1537,104 @@ export async function runAgentLoop(deps, input, hooks) {
             runId: hooks.runId,
             usage: { ...turn.usage, costUsd },
             ...(persona !== undefined ? { persona: persona.id } : {}),
-            ...(turn.toolCalls.length > 0 ? { toolCalls: turn.toolCalls } : {}),
+            ...(messageCalls.length > 0 ? { toolCalls: messageCalls } : {}),
+            ...(syntheticResults.length > 0 ? { toolResults: syntheticResults } : {}),
         }));
         modelMessages.push({
             role: 'assistant',
             content: turn.text,
-            ...(turn.toolCalls.length > 0 ? { toolCalls: turn.toolCalls } : {}),
+            ...(messageCalls.length > 0 ? { toolCalls: messageCalls } : {}),
+            ...(syntheticResults.length > 0 ? { toolResults: syntheticResults } : {}),
         });
-        // Record inject-mode retrieval as a synthetic auto-executed `retrieve` tool call on the assistant
-        // message it informed — so its passages persist and render as citations exactly like an agentic
-        // search would, without a new message field. One durable step keeps replay from re-writing it.
-        if (i === 0 && injectedPassages !== undefined) {
-            const passages = injectedPassages;
-            const toolCallId = `retrieve-${assistant.id}`;
-            await hooks.step(`persist:retrieval:${assistant.id}`, async () => {
+        for (const entry of synthetic) {
+            const { call, result } = entry;
+            await hooks.step(`${entry.step}:${assistant.id}`, async () => {
                 await deps.store.recordToolCall({
-                    toolCallId,
+                    toolCallId: call.id,
                     messageId: assistant.id,
-                    toolName: 'retrieve',
+                    toolName: call.name,
                     toolType: 'read',
-                    input: { query: input.userText },
+                    input: call.input,
                     status: 'auto_executed',
                     runId: hooks.runId,
                 });
-                await deps.store.updateToolCall({ toolCallId, status: 'executed', output: { passages } });
+                await deps.store.updateToolCall({
+                    toolCallId: call.id,
+                    status: 'executed',
+                    output: result.output,
+                });
             });
         }
         if (turn.toolCalls.length === 0) {
             break;
         }
         const results = [];
-        for (const call of turn.toolCalls) {
-            const spec = deps.registry.spec(call.name);
-            const toolType = spec?.kind ?? 'read';
-            const ctx = {
-                actor: input.actor,
-                threadId: input.threadId,
-                runId: hooks.runId,
-                requestId: hooks.runId,
-                emitComponent: (name, data) => writer.write({ t: 'component', name, data }),
-                ...(persona !== undefined ? { persona } : {}),
-                ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
-                ...(deps.host !== undefined ? { host: deps.host } : {}),
-            };
-            // Delegation: an `agent`-kind tool runs another agent. Handled at the LOOP level (not in a
-            // step) because the durable runner maps it to `ctx.child`, a ctx-level suspend point.
-            //
-            // This bypasses `ToolRegistry.invoke`, so it must apply the same two gates `invoke` applies
-            // itself — the role/ability re-check AND the offered-tools (persona/agent allow-list) filter
-            // — BEFORE any persistence or event publication. A synthesized delegate spec
-            // (`registerDelegateTools` in agent-deps-factory.ts) carries whatever `roles`/`ability` its
-            // `delegatesTo` edge declared, and nothing when the edge is a bare string — under
-            // `DefaultRolesPolicy` that is ADMIN-only, under an authz posture a tool with no `ability` is
-            // always denied — so an unauthorized delegate call must fail closed here exactly like
-            // `ToolRegistry.invoke` fails closed for every other tool kind.
-            if (toolType === 'agent') {
-                const targetAgent = spec?.targetAgent ?? call.name;
-                let task;
-                try {
-                    if (spec === undefined) {
-                        // Never actually reachable today (an unresolved name defaults `toolType` to 'read'
-                        // above), but an `agent`-kind call with no resolvable spec must fail closed rather than
-                        // fall through — and this narrows `spec` to `ToolSpec` for the `rolesPolicy.can` call
-                        // below.
-                        throw new ToolForbiddenError(call.name);
-                    }
-                    const offeredAllow = intersectAllow(persona?.allowedTools, deps.toolAllowList);
-                    if (offeredAllow !== undefined && !offeredAllow.includes(call.name)) {
-                        // A tool the model was not offered must not run, even if the model names it anyway.
-                        throw new ToolForbiddenError(call.name);
-                    }
-                    if (!(await deps.rolesPolicy.can(input.actor, spec))) {
-                        throw new ToolForbiddenError(call.name);
-                    }
-                    // The third gate `ToolRegistry.invoke` applies, in the same order: authorization first,
-                    // then shape. Delegation bypasses `invoke` (it is a ctx-level suspend point), so the gate
-                    // has to be re-applied here or a malformed input is silently coerced instead of rejected.
-                    const validation = await spec.inputSchema['~standard'].validate(call.input);
-                    if (validation.issues !== undefined) {
-                        throw new ToolInputInvalidError(call.name, validation.issues);
-                    }
-                    task = extractTask(validation.value);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    // A denied delegation is recorded `failed` directly — never `auto_executed` even
-                    // transiently — and never emits `agent.delegated`.
-                    await hooks.step(`persist:toolcall:${call.id}`, () => deps.store.recordToolCall({
-                        toolCallId: call.id,
-                        messageId: assistant.id,
-                        toolName: call.name,
-                        toolType: 'read',
-                        input: call.input,
-                        status: 'failed',
-                        runId: hooks.runId,
-                    }));
-                    results.push({ id: call.id, name: call.name, output: null, error: message });
-                    continue;
-                }
-                await hooks.step(`persist:toolcall:${call.id}`, () => deps.store.recordToolCall({
-                    toolCallId: call.id,
-                    messageId: assistant.id,
-                    toolName: call.name,
-                    toolType: 'read',
-                    input: call.input,
-                    status: 'auto_executed',
-                    runId: hooks.runId,
-                }));
-                publishAgentDelegated({
-                    runId: hooks.runId,
-                    toAgent: targetAgent,
-                    ...(input.agentName !== undefined ? { fromAgent: input.agentName } : {}),
-                });
-                const sub = hooks.runAgent
-                    ? await hooks.runAgent(targetAgent, task)
-                    : { text: `(no multi-agent support wired; cannot reach "${targetAgent}")` };
-                await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({ toolCallId: call.id, status: 'executed', output: sub }));
-                results.push({ id: call.id, name: call.name, output: sub });
-                continue;
+        const turnCalls = {
+            deps,
+            input,
+            hooks,
+            messageId: assistant.id,
+            writer,
+            ...(skillOffer !== undefined ? { skills: skillOffer } : {}),
+            ...(memoryDigest !== undefined ? { memory: memoryDigest } : {}),
+        };
+        // A model routinely asks for several tools at once, and running them back to back makes the
+        // turn cost their sum. Overlapping them is safe here because a checkpoint position is handed
+        // out on the CALL, not when the work settles: launching every invocation in one tick — what
+        // `hooks.parallel` promises — pins the `tool:` block in call order however the tools then
+        // finish. The claim and persist checkpoints stay sequential around it.
+        //
+        // Only a turn whose every call is a plain `read` qualifies:
+        //   - an `action` suspends on an approval signal, which is human time rather than I/O, so
+        //     overlapping what follows it buys nothing — and reserving an invocation position for a
+        //     call that may yet be REJECTED spends a position the rejected branch never fills.
+        //   - an `agent` delegation is `ctx.child`, whose parallel form is the runtime's own `ctx.all`:
+        //     one workflow ref over a reserved block, carrying the `parallelGroup` bookkeeping that
+        //     makes a fan render as a fan. That is not N independent task closures, so it cannot ride
+        //     this hook.
+        // The kinds come from the `persist:toolcall` checkpoints, never from a local registry lookup,
+        // so every process replaying this turn reaches the same verdict.
+        const parallel = hooks.parallel;
+        if (parallel !== undefined &&
+            turn.toolCalls.length > 1 &&
+            (await (hooks.patched?.(PARALLEL_TOOLS_PATCH) ?? Promise.resolve(true)))) {
+            // Claiming the whole turn first is what makes the kinds knowable before the first execution —
+            // and it is also what moves the checkpoints, hence the `patched` gate above.
+            const claimed = [];
+            for (const call of turn.toolCalls) {
+                claimed.push(await claimToolCall(turnCalls, call));
             }
-            if (toolType === 'action') {
-                await hooks.step(`persist:toolcall:${call.id}`, () => deps.store.recordToolCall({
-                    toolCallId: call.id,
-                    messageId: assistant.id,
-                    toolName: call.name,
-                    toolType: 'action',
-                    input: call.input,
-                    status: 'pending_approval',
-                    runId: hooks.runId,
-                }));
-                const decision = await hooks.awaitApproval(call, ctx);
-                if (!decision.approved) {
-                    await hooks.step(`persist:toolreject:${call.id}`, () => deps.store.updateToolCall({
-                        toolCallId: call.id,
-                        status: 'rejected',
-                        ...(decision.reason !== undefined ? { error: decision.reason } : {}),
-                    }));
-                    results.push({
-                        id: call.id,
-                        name: call.name,
-                        output: { rejected: true, reason: decision.reason ?? 'rejected by user' },
-                        error: 'rejected',
-                    });
-                    publishAgentToolCall({
-                        runId: hooks.runId,
-                        toolName: call.name,
-                        toolType,
-                        status: 'rejected',
-                    });
-                    continue;
-                }
+            // A `skill` load and a `remember` write qualify alongside a `read`: each takes its position on
+            // the call exactly as a read does, and each spends a read's `tool:`/`persist:` names. What
+            // disqualifies the other kinds is not that they have effects — it is that an `action` suspends
+            // on human time and an `agent` delegation is the runtime's own child-workflow fan.
+            if (claimed.every((entry) => entry.toolType === 'read' || entry.toolType === 'skill' || entry.toolType === 'memory')) {
+                results.push(...(await invokeClaimedToolsTogether(turnCalls, parallel, claimed)));
             }
             else {
-                await hooks.step(`persist:toolcall:${call.id}`, () => deps.store.recordToolCall({
-                    toolCallId: call.id,
-                    messageId: assistant.id,
-                    toolName: call.name,
-                    toolType: 'read',
-                    input: call.input,
-                    status: 'auto_executed',
-                    runId: hooks.runId,
-                }));
-            }
-            try {
-                // The retry loop runs INSIDE the `tool:<call.id>` step so it stays replay-safe: a durable
-                // step memoizes only its successful result, so on replay the whole step returns cached and
-                // the retries never re-run (side effects happen exactly once). A classified-transient error
-                // (DB deadlock / lock-wait timeout / serialization failure) is retried in place; any other
-                // failure surfaces immediately as before. `false` disables retry entirely.
-                // Span the tool execution INSIDE the step body (replay-safe). The transient-retry loop runs
-                // within the span, so the span covers all in-place attempts; the tool's output never rides it.
-                const output = await hooks.step(`tool:${call.id}`, () => spannedAgent('tool.execution', hooks.runId, { runId: hooks.runId, toolCallId: call.id, toolName: call.name, toolType }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
-                    ...(hooks.isControlFlowError !== undefined
-                        ? { isControlFlowError: hooks.isControlFlowError }
-                        : {}),
-                    onRetry: (attempt, retryError) => {
-                        publishAgentToolRetry({
-                            runId: hooks.runId,
-                            toolName: call.name,
-                            toolCallId: call.id,
-                            attempt,
-                            message: retryError instanceof Error ? retryError.message : String(retryError),
-                        });
-                    },
-                }), () => ({})));
-                await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({
-                    toolCallId: call.id,
-                    status: 'executed',
-                    output,
-                    ...(toolType === 'action' ? { executedByRef: input.actor.id } : {}),
-                }));
-                results.push({ id: call.id, name: call.name, output });
-                publishAgentToolCall({
-                    runId: hooks.runId,
-                    toolName: call.name,
-                    toolType,
-                    status: 'executed',
-                });
+                for (const entry of claimed) {
+                    results.push(await runClaimedToolCall(turnCalls, entry));
+                }
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                await hooks.step(`persist:toolfail:${call.id}`, () => deps.store.updateToolCall({ toolCallId: call.id, status: 'failed', error: message }));
-                results.push({ id: call.id, name: call.name, output: null, error: message });
-                publishAgentToolCall({
-                    runId: hooks.runId,
-                    toolName: call.name,
-                    toolType,
-                    status: 'failed',
-                });
+        }
+        else {
+            for (const call of turn.toolCalls) {
+                results.push(await runClaimedToolCall(turnCalls, await claimToolCall(turnCalls, call)));
             }
         }
+        // The outputs land on the assistant message that made the calls. A reader reopening the thread
+        // pairs a call with its result off THAT message, so results that only reached the tool-call
+        // table leave every tool in the turn rendering as one still running.
+        //
+        // A position of its own, hence the marker: a run that suspended mid-turn under the shape
+        // without it has no room for a checkpoint between the last tool's persist and the next `llm:`.
+        // Every value written here comes from a checkpoint above, so a replay writes the same list.
+        if (await (hooks.patched?.(MESSAGE_TOOL_RESULTS_PATCH) ?? Promise.resolve(true))) {
+            await hooks.step(`persist:toolresults:${i}`, () => deps.store.setMessageToolResults(assistant.id, [...results, ...syntheticResults]));
+        }
         modelMessages.push({ role: 'user', content: '', toolResults: results });
     }
-    if (thread !== null && (thread.title === '' || thread.title === 'New chat')) {
+    if (thread.title === '' || thread.title === 'New chat') {
         await hooks.step('persist:title', () => deps.store.setTitle(input.threadId, deriveTitle(input.userText)));
     }
     // Settle the run `completed` with its rollup. Normal completion only — the loop never records a
@@ -507,6 +1658,6 @@ export async function runAgentLoop(deps, input, hooks) {
         inputTokens: totalInput,
         outputTokens: totalOutput,
     });
-    return { text: lastText };
+    return { text: lastText, ...(structured !== undefined ? { object: structured } : {}) };
 }
 //# sourceMappingURL=agent-loop.js.map