@mikode13/harness 9.3.1 → 11.0.0

package/dist/engines/domain/model/backgroundAgents.js

@@ -0,0 +1,165 @@
+import { describeFailure } from '#src/shared/domain/providerFailure';
+import { RunEndingToolError } from '#src/tools/domain/preparedCall';
+// How much of a task the answer repeats, so the model can tell which one it is.
+const shownTaskCharacters = 200;
+/** How the model that sent an agent is told which one it is, such as `explorer 2`. */
+function labelOf({ name, subagent }) {
+    return `${name} ${String(subagent)}`;
+}
+/** What the model is told of the agents a call sent, as that call's result. */
+export function sentNote(agents) {
+    const names = agents.map(labelOf).join(', ');
+    return `Sent to work in the background: ${names}. Each one's answer reaches you in a message of its own once it finishes. Keep working meanwhile. When you have nothing else to do until they answer, say briefly that you are waiting, without calling a tool: the run waits for them, and you go on with their answers.`;
+}
+// What a model is told of an agent the end of its run stopped, in a conversation kept for the next.
+const stoppedAnswer = 'None: it was stopped when the run ended, before it answered. Anything it changed stays as it left it.';
+function shownTask(task) {
+    return task.length > shownTaskCharacters ? `${task.slice(0, shownTaskCharacters)}…` : task;
+}
+/**
+ * The agents a run's calls sent to work in the background. Each one's answer waits here, in the
+ * order they finished, until the model's next step takes it. A failure that ends the run stops
+ * every agent still working at once, and the run at its next boundary.
+ */
+export class BackgroundAgents {
+    stopping = new AbortController();
+    /** What the agents work under: the run's own signal, or the stop of the run's end. */
+    signal;
+    agents = new Set();
+    arrived = [];
+    ended;
+    unrecordedWorking = 0;
+    // Such an agent ended since `mayHaveChangedUnseen` was last asked.
+    unrecordedEnded = false;
+    woken;
+    /**
+     * What some agent spent is unknown: it was stopped while it worked, or failed in a way that
+     * carries no usage.
+     */
+    unknownUsage = false;
+    narrate;
+    /** `narrate` tells the person watching when each agent ended; it must never throw. */
+    constructor(runSignal, narrate) {
+        this.signal = AbortSignal.any([runSignal, this.stopping.signal]);
+        this.narrate = narrate;
+    }
+    /** Some agent is still working. */
+    get working() {
+        return this.agents.size > 0;
+    }
+    /**
+     * Whether an agent that may change files the history does not record worked since the last
+     * time this was asked: one is working now, or one ended meanwhile.
+     */
+    mayHaveChangedUnseen() {
+        const worked = this.unrecordedWorking > 0 || this.unrecordedEnded;
+        this.unrecordedEnded = false;
+        return worked;
+    }
+    get usageUnknown() {
+        return this.unknownUsage;
+    }
+    /** Watches the agents call `callId` sent, until each one answers. */
+    add(callId, agents, unrecorded) {
+        for (const agent of agents) {
+            if (unrecorded)
+                this.unrecordedWorking++;
+            const ended = (outcome) => {
+                const { name, subagent } = agent;
+                this.narrate({ type: 'subagentEnded', callId, subagent, name, outcome });
+            };
+            const watched = agent.answer
+                .then(({ text, failed }) => {
+                ended(failed ? 'failed' : 'answered');
+                this.arrive(agent, callId, text);
+            }, (error) => {
+                if (this.signal.aborted) {
+                    ended('stopped');
+                    this.unknownUsage = true;
+                    this.arrive(agent, callId, stoppedAnswer);
+                }
+                else if (error instanceof RunEndingToolError) {
+                    ended('failed');
+                    this.end(error.failure);
+                }
+                else {
+                    // It broke the promise of answering, so what it spent is unknown.
+                    ended('failed');
+                    this.unknownUsage = true;
+                    this.arrive(agent, callId, `It failed: ${describeFailure(error)}`);
+                }
+            })
+                .finally(() => {
+                if (unrecorded) {
+                    this.unrecordedWorking--;
+                    this.unrecordedEnded = true;
+                }
+                this.agents.delete(watched);
+                this.wake();
+            });
+            this.agents.add(watched);
+        }
+    }
+    /**
+     * The message holding every answer that arrived since the last one, if any did, and what
+     * became of each agent a stop interrupted.
+     */
+    takeAnswers() {
+        if (this.arrived.length === 0)
+            return undefined;
+        const answers = this.arrived.splice(0);
+        const text = [
+            'This message is from the harness, not the user: agents you sent finished.',
+            ...answers,
+        ].join('\n\n');
+        return { role: 'user', content: [{ type: 'text', text }] };
+    }
+    /**
+     * Waits until an answer arrives, while agents are working. Rejects as cancelled when the run
+     * is cancelled meanwhile, and with the failure that ended it.
+     */
+    async nextAnswer() {
+        while (this.arrived.length === 0 && this.agents.size > 0) {
+            this.throwIfEnded();
+            this.signal.throwIfAborted();
+            await new Promise(resolve => {
+                const done = () => {
+                    this.signal.removeEventListener('abort', done);
+                    resolve();
+                };
+                this.woken = done;
+                this.signal.addEventListener('abort', done, { once: true });
+            });
+        }
+        this.throwIfEnded();
+        this.signal.throwIfAborted();
+    }
+    /** Throws the failure of an agent that ended the run, if one did. */
+    throwIfEnded() {
+        if (this.ended)
+            throw this.ended.failure;
+    }
+    /**
+     * Stops every agent still working, and waits until each one has: what they changed and spent
+     * belongs to the run, which ends only after them.
+     */
+    async stop() {
+        if (this.agents.size > 0)
+            this.stopping.abort();
+        await Promise.all(this.agents);
+    }
+    arrive(agent, callId, answer) {
+        this.arrived.push(`${labelOf(agent)}, sent by your call ${callId} with the task: ${shownTask(agent.task)}\nIts answer:\n${answer}`);
+    }
+    /** A failure ends the run: every agent is stopped for it. */
+    end(failure) {
+        this.ended ??= { failure };
+        this.stopping.abort();
+    }
+    wake() {
+        const woken = this.woken;
+        this.woken = undefined;
+        woken?.();
+    }
+}
+//# sourceMappingURL=backgroundAgents.js.map

package/dist/engines/domain/model/backgroundAgents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundAgents.js","sourceRoot":"","sources":["../../../../src/engines/domain/model/backgroundAgents.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProgressEvent } from '#src/agent/domain/agent';\nimport type { Message } from '#src/llm/domain/message';\nimport { describeFailure } from '#src/shared/domain/providerFailure';\nimport { type Delegated, RunEndingToolError } from '#src/tools/domain/preparedCall';\n\n// How much of a task the answer repeats, so the model can tell which one it is.\nconst shownTaskCharacters = 200;\n\n/** How the model that sent an agent is told which one it is, such as `explorer 2`. */\nfunction labelOf({ name, subagent }: Delegated): string {\n\treturn `${name} ${String(subagent)}`;\n}\n\n/** What the model is told of the agents a call sent, as that call's result. */\nexport function sentNote(agents: readonly Delegated[]): string {\n\tconst names = agents.map(labelOf).join(', ');\n\treturn `Sent to work in the background: ${names}. Each one's answer reaches you in a message of its own once it finishes. Keep working meanwhile. When you have nothing else to do until they answer, say briefly that you are waiting, without calling a tool: the run waits for them, and you go on with their answers.`;\n}\n\n// What a model is told of an agent the end of its run stopped, in a conversation kept for the next.\nconst stoppedAnswer =\n\t'None: it was stopped when the run ended, before it answered. Anything it changed stays as it left it.';\n\nfunction shownTask(task: string): string {\n\treturn task.length > shownTaskCharacters ? `${task.slice(0, shownTaskCharacters)}…` : task;\n}\n\n/**\n * The agents a run's calls sent to work in the background. Each one's answer waits here, in the\n * order they finished, until the model's next step takes it. A failure that ends the run stops\n * every agent still working at once, and the run at its next boundary.\n */\nexport class BackgroundAgents {\n\tprivate readonly stopping = new AbortController();\n\t/** What the agents work under: the run's own signal, or the stop of the run's end. */\n\treadonly signal: AbortSignal;\n\tprivate readonly agents = new Set<Promise<void>>();\n\tprivate readonly arrived: string[] = [];\n\tprivate ended: { failure: unknown } | undefined;\n\tprivate unrecordedWorking = 0;\n\t// Such an agent ended since `mayHaveChangedUnseen` was last asked.\n\tprivate unrecordedEnded = false;\n\tprivate woken: (() => void) | undefined;\n\t/**\n\t * What some agent spent is unknown: it was stopped while it worked, or failed in a way that\n\t * carries no usage.\n\t */\n\tprivate unknownUsage = false;\n\n\tprivate readonly narrate: (event: ProgressEvent) => void;\n\n\t/** `narrate` tells the person watching when each agent ended; it must never throw. */\n\tconstructor(runSignal: AbortSignal, narrate: (event: ProgressEvent) => void) {\n\t\tthis.signal = AbortSignal.any([runSignal, this.stopping.signal]);\n\t\tthis.narrate = narrate;\n\t}\n\n\t/** Some agent is still working. */\n\tget working(): boolean {\n\t\treturn this.agents.size > 0;\n\t}\n\n\t/**\n\t * Whether an agent that may change files the history does not record worked since the last\n\t * time this was asked: one is working now, or one ended meanwhile.\n\t */\n\tmayHaveChangedUnseen(): boolean {\n\t\tconst worked = this.unrecordedWorking > 0 || this.unrecordedEnded;\n\t\tthis.unrecordedEnded = false;\n\t\treturn worked;\n\t}\n\n\tget usageUnknown(): boolean {\n\t\treturn this.unknownUsage;\n\t}\n\n\t/** Watches the agents call `callId` sent, until each one answers. */\n\tadd(callId: string, agents: readonly Delegated[], unrecorded: boolean): void {\n\t\tfor (const agent of agents) {\n\t\t\tif (unrecorded) this.unrecordedWorking++;\n\t\t\tconst ended = (outcome: 'answered' | 'failed' | 'stopped') => {\n\t\t\t\tconst { name, subagent } = agent;\n\t\t\t\tthis.narrate({ type: 'subagentEnded', callId, subagent, name, outcome });\n\t\t\t};\n\t\t\tconst watched = agent.answer\n\t\t\t\t.then(\n\t\t\t\t\t({ text, failed }) => {\n\t\t\t\t\t\tended(failed ? 'failed' : 'answered');\n\t\t\t\t\t\tthis.arrive(agent, callId, text);\n\t\t\t\t\t},\n\t\t\t\t\t(error: unknown) => {\n\t\t\t\t\t\tif (this.signal.aborted) {\n\t\t\t\t\t\t\tended('stopped');\n\t\t\t\t\t\t\tthis.unknownUsage = true;\n\t\t\t\t\t\t\tthis.arrive(agent, callId, stoppedAnswer);\n\t\t\t\t\t\t} else if (error instanceof RunEndingToolError) {\n\t\t\t\t\t\t\tended('failed');\n\t\t\t\t\t\t\tthis.end(error.failure);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t// It broke the promise of answering, so what it spent is unknown.\n\t\t\t\t\t\t\tended('failed');\n\t\t\t\t\t\t\tthis.unknownUsage = true;\n\t\t\t\t\t\t\tthis.arrive(agent, callId, `It failed: ${describeFailure(error)}`);\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t)\n\t\t\t\t.finally(() => {\n\t\t\t\t\tif (unrecorded) {\n\t\t\t\t\t\tthis.unrecordedWorking--;\n\t\t\t\t\t\tthis.unrecordedEnded = true;\n\t\t\t\t\t}\n\t\t\t\t\tthis.agents.delete(watched);\n\t\t\t\t\tthis.wake();\n\t\t\t\t});\n\t\t\tthis.agents.add(watched);\n\t\t}\n\t}\n\n\t/**\n\t * The message holding every answer that arrived since the last one, if any did, and what\n\t * became of each agent a stop interrupted.\n\t */\n\ttakeAnswers(): Message | undefined {\n\t\tif (this.arrived.length === 0) return undefined;\n\t\tconst answers = this.arrived.splice(0);\n\t\tconst text = [\n\t\t\t'This message is from the harness, not the user: agents you sent finished.',\n\t\t\t...answers,\n\t\t].join('\\n\\n');\n\t\treturn { role: 'user', content: [{ type: 'text', text }] };\n\t}\n\n\t/**\n\t * Waits until an answer arrives, while agents are working. Rejects as cancelled when the run\n\t * is cancelled meanwhile, and with the failure that ended it.\n\t */\n\tasync nextAnswer(): Promise<void> {\n\t\twhile (this.arrived.length === 0 && this.agents.size > 0) {\n\t\t\tthis.throwIfEnded();\n\t\t\tthis.signal.throwIfAborted();\n\t\t\tawait new Promise<void>(resolve => {\n\t\t\t\tconst done = () => {\n\t\t\t\t\tthis.signal.removeEventListener('abort', done);\n\t\t\t\t\tresolve();\n\t\t\t\t};\n\t\t\t\tthis.woken = done;\n\t\t\t\tthis.signal.addEventListener('abort', done, { once: true });\n\t\t\t});\n\t\t}\n\t\tthis.throwIfEnded();\n\t\tthis.signal.throwIfAborted();\n\t}\n\n\t/** Throws the failure of an agent that ended the run, if one did. */\n\tthrowIfEnded(): void {\n\t\tif (this.ended) throw this.ended.failure;\n\t}\n\n\t/**\n\t * Stops every agent still working, and waits until each one has: what they changed and spent\n\t * belongs to the run, which ends only after them.\n\t */\n\tasync stop(): Promise<void> {\n\t\tif (this.agents.size > 0) this.stopping.abort();\n\t\tawait Promise.all(this.agents);\n\t}\n\n\tprivate arrive(agent: Delegated, callId: string, answer: string): void {\n\t\tthis.arrived.push(\n\t\t\t`${labelOf(agent)}, sent by your call ${callId} with the task: ${shownTask(agent.task)}\\nIts answer:\\n${answer}`,\n\t\t);\n\t}\n\n\t/** A failure ends the run: every agent is stopped for it. */\n\tprivate end(failure: unknown): void {\n\t\tthis.ended ??= { failure };\n\t\tthis.stopping.abort();\n\t}\n\n\tprivate wake(): void {\n\t\tconst woken = this.woken;\n\t\tthis.woken = undefined;\n\t\twoken?.();\n\t}\n}\n"]}

package/dist/engines/domain/model/llmAgent.d.ts

@@ -67,8 +67,9 @@ export declare class LLMAgent implements Agent {
     private denial;
     /**
      * Always answers the call: a missing tool, a denied call or a failing one becomes an error
-     * result, so the model can correct itself. Only a cancellation, or a failing approver,
-     * escapes, whatever error the tool turned it into.
+     * result, so the model can correct itself. Only a cancellation, a failing approver, or host
+     * code that failed inside the call escapes. A call that hands tasks to agents answers once
+     * it sent them, and `background` watches them from then on.
      */
     private runTool;
     /**
@@ -76,8 +77,16 @@ export declare class LLMAgent implements Agent {
      * correct; an asker that fails or answers wrongly is host code, and ends the run.
      */
     private askUser;
-    /** One at a time and in order, so their effects and their narration never interleave. */
+    /**
+     * One at a time and in order, so their effects and their narration never interleave. Agents a
+     * call hands tasks to keep working in the background once it answered.
+     */
     private runTools;
+    /**
+     * Narrates how a call ended and notes its command's ending, with the warning for the model
+     * when that ending keeps coming back alike.
+     */
+    private settle;
     /**
      * On a loop found, the fifth ending alike of a command or the fifth answer in a row asking for
      * the same calls: the note for the model if the user lets the run go on, or the failure that

package/dist/engines/domain/model/llmAgent.js

@@ -1,18 +1,20 @@
 import { readDecision, } from '#src/agent/domain/approval';
 import { ignoreProgress, } from '#src/agent/domain/agent';
-import { RunContext, runContextOf, withRunContext, } from '#src/agent/domain/runContext';
+import { delegationOf, RunContext, runContextOf, withRunContext, } from '#src/agent/domain/runContext';
 import { InvalidAgentConfigError, RecoverableError, UnrecoverableError, withSpentTokens, } from '#src/shared/domain/errors';
 import { classifyHostFailure, classifyLocalFailure, classifyProviderFailure, describeFailure, treatErrors, } from '#src/shared/domain/providerFailure';
 import { Conversation } from '#src/llm/domain/conversation';
 import { asNative, nativeOf } from '#src/llm/domain/tool';
-import { prepareCall, ToolExecutionError, } from '#src/tools/domain/preparedCall';
+import { readAnswers } from '#src/agent/domain/question';
+import { isDelegating, prepareCall, RunEndingToolError, ToolExecutionError, } from '#src/tools/domain/preparedCall';
 import { ReadRegistry } from '#src/tools/domain/readRegistry';
 import { InvalidToolInputError } from '#src/tools/domain/tool';
 import { isAbortError } from '#src/shared/domain/isAbortError';
 import { addTokens } from '#src/shared/domain/tokens';
 import { anotherAttempt, askAt, CommandLoops, extensionNote, loopQuestion, loopStop, loopWarning, repeatedAnswersAt, repeatNote, repeatQuestion, repeatStop, stop, warnAt, } from "./commandLoops.js";
+import { BackgroundAgents, sentNote } from "./backgroundAgents.js";
 import { measureContext } from "./stepContext.js";
-import { askUserDefinition, askUserName, describeAnswers, readAnswers, readQuestions, summarizeQuestions, } from "./askUser.js";
+import { askUserDefinition, askUserName, describeAnswers, readQuestions, summarizeQuestions, } from "./askUser.js";
 import { followHistory, transcriptOf, undoNote, } from "./historyFollower.js";
 function describePart(part) {
     switch (part.type) {
@@ -269,9 +271,11 @@ export class LLMAgent {
      * place. Only a `destructive` call is asked about: git can undo a `mutating` one. A throwing
      * approver ends the run, as any host callback does.
      */
-    async denial(call, { risk, command }, signal, approve) {
+    async denial(call, prepared, signal, approve) {
+        const { risk } = prepared;
         if (this.autoApprove || risk !== 'destructive')
             return undefined;
+        const command = 'command' in prepared ? prepared.command : undefined;
         const retry = 'Do not retry the same call; choose another way, or ask the user.';
         if (!approve) {
             return `The call to "${call.name}" was denied: it is destructive, and no one was asked to allow it. ${retry}`;
@@ -305,10 +309,11 @@ export class LLMAgent {
     }
     /**
      * Always answers the call: a missing tool, a denied call or a failing one becomes an error
-     * result, so the model can correct itself. Only a cancellation, or a failing approver,
-     * escapes, whatever error the tool turned it into.
+     * result, so the model can correct itself. Only a cancellation, a failing approver, or host
+     * code that failed inside the call escapes. A call that hands tasks to agents answers once
+     * it sent them, and `background` watches them from then on.
      */
-    async runTool(call, { signal, onProgress: callback = ignoreProgress, approve, ask }, effects, toolCall) {
+    async runTool(call, { signal, onProgress: callback = ignoreProgress, approve, ask }, effects, toolCall, background) {
         const result = { type: 'toolResult', callId: call.id, name: call.name };
         signal.throwIfAborted();
         if (call.name === askUserName && ask && !this.tools.has(askUserName)) {
@@ -346,7 +351,10 @@ export class LLMAgent {
         }
         let prepared;
         try {
-            prepared = await prepareCall(tool, call.input, signal, { ...toolCall, callId: call.id });
+            const context = { ...toolCall, callId: call.id };
+            prepared = isDelegating(tool)
+                ? await tool.delegate(call.input, signal, context)
+                : await prepareCall(tool, call.input, signal, context);
         }
         catch (error) {
             signal.throwIfAborted();
@@ -384,6 +392,25 @@ export class LLMAgent {
         // Set before `execute`, so a tool that fails halfway still counts: it may have had effects.
         effects.toolRan = true;
         const unrecorded = prepared.unrecorded === true && prepared.risk !== 'safe';
+        if ('start' in prepared) {
+            // Before its agents start, so the person watching reads it before anything they narrate.
+            emit({
+                type: 'tool',
+                id: call.id,
+                name: call.name,
+                status: 'sent',
+                ...(summary === undefined ? {} : { summary }),
+            }, callback);
+            const agents = prepared.start(background.signal);
+            background.add(call.id, agents, unrecorded);
+            return {
+                result: { ...result, output: sentNote(agents), isError: false },
+                denied: false,
+                sent: true,
+                unrecorded,
+                ...(summary === undefined ? {} : { summary }),
+            };
+        }
         try {
             const output = await prepared.run(signal);
             const ending = prepared.ending?.();
@@ -398,6 +425,8 @@ export class LLMAgent {
         }
         catch (error) {
             signal.throwIfAborted();
+            if (error instanceof RunEndingToolError)
+                throw error.failure;
             const ending = prepared.ending?.();
             return {
                 result: { ...result, output: describeFailure(error), isError: true },
@@ -447,11 +476,14 @@ export class LLMAgent {
             summary,
         };
     }
-    /** One at a time and in order, so their effects and their narration never interleave. */
+    /**
+     * One at a time and in order, so their effects and their narration never interleave. Agents a
+     * call hands tasks to keep working in the background once it answered.
+     */
     async runTools(calls, options, effects, toolCall, 
     // Throws the failure of a progress callback a call narrated through.
-    throwIfProgressFailed, loops) {
-        const { signal, onProgress: callback = ignoreProgress } = options;
+    throwIfProgressFailed, loops, background) {
+        const { signal } = options;
         const results = [];
         for (const [index, call] of calls.entries()) {
             // A call before this one may have ignored the cancellation; this one must not start,
@@ -459,48 +491,15 @@ export class LLMAgent {
             signal.throwIfAborted();
             // `runTool` announces the call only once it is allowed to run, so a consumer never
             // shows a call as running early, nor while the user is still being asked.
-            const ran = await this.runTool(call, options, effects, toolCall);
-            const { denied, diff, summary, exitCode, ending } = ran;
-            let { result } = ran;
+            const ran = await this.runTool(call, options, effects, toolCall, background);
             // A call that failed to narrate ends the run before the next one can start.
             throwIfProgressFailed();
-            if (ran.unrecorded)
+            // An agent at work since the last call may have changed what the history cannot copy.
+            if (background.mayHaveChangedUnseen())
                 loops.unrecordedCallRan();
-            const key = callKey(call);
-            const label = summary ?? call.name;
-            const alike = ending === undefined ? undefined : loops.observe(key, ending);
-            // A command that changed what the history cannot copy hides that change from the next.
-            if (ending !== undefined && ending.state === undefined)
-                loops.unrecordedCallRan();
-            // Narrated with it, so the person watching reads what the model is told.
-            if (alike?.times === warnAt) {
-                result = {
-                    ...result,
-                    output: `${result.output}\n\n${loopWarning(label, alike, options.ask !== undefined && !loops.wentOn)}`,
-                };
-            }
-            if (denied) {
-                emit({
-                    type: 'tool',
-                    id: call.id,
-                    name: call.name,
-                    status: 'denied',
-                    ...(summary === undefined ? {} : { summary }),
-                }, callback);
-            }
-            // The diff of a change it made, for the person watching; only once it was made.
-            else if (diff !== undefined) {
-                emit({
-                    type: 'tool',
-                    id: call.id,
-                    name: call.name,
-                    status: 'completed',
-                    diff,
-                    ...(summary === undefined ? {} : { summary }),
-                }, callback);
-            }
-            else
-                narrate(result, callback, summary, exitCode);
+            const settled = this.settle(call, ran, loops, options);
+            let { result } = settled;
+            const { alike, key, label } = settled;
             // After its result is narrated, so the user is asked about the ending they have seen.
             if (alike !== undefined && alike.times >= askAt) {
                 const decision = await this.decideOnLoop({
@@ -526,6 +525,55 @@ export class LLMAgent {
         }
         return { message: { role: 'tool', content: results } };
     }
+    /**
+     * Narrates how a call ended and notes its command's ending, with the warning for the model
+     * when that ending keeps coming back alike.
+     */
+    settle(call, ran, loops, { onProgress: callback = ignoreProgress, ask }) {
+        const { denied, diff, summary, exitCode, ending, sent } = ran;
+        let { result } = ran;
+        if (ran.unrecorded)
+            loops.unrecordedCallRan();
+        const key = callKey(call);
+        const label = summary ?? call.name;
+        const alike = ending === undefined ? undefined : loops.observe(key, ending);
+        // A command that changed what the history cannot copy hides that change from the next.
+        if (ending !== undefined && ending.state === undefined)
+            loops.unrecordedCallRan();
+        // Narrated with it, so the person watching reads what the model is told.
+        if (alike?.times === warnAt) {
+            result = {
+                ...result,
+                output: `${result.output}\n\n${loopWarning(label, alike, ask !== undefined && !loops.wentOn)}`,
+            };
+        }
+        if (denied) {
+            emit({
+                type: 'tool',
+                id: call.id,
+                name: call.name,
+                status: 'denied',
+                ...(summary === undefined ? {} : { summary }),
+            }, callback);
+        }
+        else if (sent === true) {
+            // Narrated as it sent its agents, which go on after it until each one ends.
+        }
+        // The diff of a change it made, for the person watching; only once it was made.
+        else if (diff !== undefined) {
+            emit({
+                type: 'tool',
+                id: call.id,
+                name: call.name,
+                status: 'completed',
+                diff,
+                ...(summary === undefined ? {} : { summary }),
+            }, callback);
+        }
+        else
+            narrate(result, callback, summary, exitCode);
+        return { result, alike, key, label };
+    }
     /**
      * On a loop found, the fifth ending alike of a command or the fifth answer in a row asking for
      * the same calls: the note for the model if the user lets the run go on, or the failure that
@@ -607,16 +655,17 @@ export class LLMAgent {
             response = await this.takeSteps(prompt, options, context, seen);
         }
         catch (error) {
-            await this.transcribe(seen, isAbortError(error) ? 'cancelled' : 'failed', error);
+            await this.transcribe(seen, options, isAbortError(error) ? 'cancelled' : 'failed', error);
             throw error;
         }
-        await this.transcribe(seen, 'completed');
+        await this.transcribe(seen, options, 'completed');
         return response;
     }
     /** Hands the run's transcript to the consumer, whose failure is logged, not the run's. */
-    async transcribe(seen, outcome, error) {
+    async transcribe(seen, options, outcome, error) {
         if (!this.onTranscript)
             return;
+        const delegation = delegationOf(options);
         try {
             // A copy, so a consumer that changes it cannot change the agent's tools or conversation.
             const content = structuredClone({
@@ -629,7 +678,19 @@ export class LLMAgent {
                 messages: seen.messages(),
                 ...(outcome === 'completed' ? {} : { error: describeFailure(error) }),
             });
-            await this.onTranscript({ outcome, content });
+            await this.onTranscript({
+                ...(delegation
+                    ? {
+                        delegation: {
+                            tool: delegation.tool,
+                            callId: delegation.callId,
+                            subagent: delegation.subagent,
+                        },
+                    }
+                    : {}),
+                outcome,
+                content,
+            });
         }
         catch (failure) {
             treatErrors(() => {
@@ -639,6 +700,22 @@ export class LLMAgent {
     }
     async takeSteps(prompt, options, context, seen) {
         const { signal, onProgress: callback = ignoreProgress } = options;
+        // A tool narrates through this without ever failing: a failing callback would reach
+        // only the tool, which turns any failure into a result for the model. The run ends on
+        // it once that tool returns.
+        let progressFailure;
+        const onProgress = (event) => {
+            if (progressFailure)
+                return;
+            try {
+                emit(event, callback);
+            }
+            catch (error) {
+                progressFailure = { error };
+            }
+        };
+        // The agents the run's calls send to work in the background.
+        const background = new BackgroundAgents(signal, onProgress);
         const start = Date.now();
         const runMessages = [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
         let tokens;
@@ -682,23 +759,11 @@ export class LLMAgent {
                 tokens = addTokens(tokens, spent);
                 unreported ||= unreportedCall;
             };
-            // A tool narrates through this without ever failing: a failing callback would reach
-            // only the tool, which turns any failure into a result for the model. The run ends on
-            // it once that tool returns.
-            let progressFailure;
-            const onProgress = (event) => {
-                if (progressFailure)
-                    return;
-                try {
-                    emit(event, callback);
-                }
-                catch (error) {
-                    progressFailure = { error };
-                }
-            };
+            // Also ends the run at its next boundary when an agent at work failed in a way that ends it.
             const throwIfProgressFailed = () => {
                 if (progressFailure)
                     throw progressFailure.error;
+                background.throwIfEnded();
             };
             // The agent's own `askUser` exists only for a run someone can answer, and never beside
             // a consumer's tool of that name, which the consumer gave first and which stays theirs.
@@ -714,7 +779,18 @@ export class LLMAgent {
                 if (followed)
                     this.seenRevision = followed.latestRevision;
             };
+            // A run kept although it failed stops its agents first, and tells the next run what
+            // became of each one, which would otherwise wait for answers that never come.
+            const keepFailed = async () => {
+                await background.stop();
+                const ended = background.takeAnswers();
+                if (ended)
+                    runMessages.push(ended);
+                remember();
+            };
             for (let step = 1; step <= this.maxSteps; step++) {
+                // An agent at work may have narrated through a callback that failed.
+                throwIfProgressFailed();
                 const { response, context: sent } = await this.llmCall(runMessages, after, {
                     signal,
                     step,
@@ -726,6 +802,7 @@ export class LLMAgent {
                 // After the tokens are counted, so a throwing callback still reports them, and for an
                 // unusable answer too: the call was sent, and billed.
                 this.narrateStep(step, response.usage, { context: sent, tools }, callback);
+                throwIfProgressFailed();
                 if (response.stopReason === 'truncated') {
                     // What it wrote before the output limit, kept with the run so the next run can
                     // take it up. Not its calls, whose input may be cut, nor what only the provider
@@ -735,7 +812,7 @@ export class LLMAgent {
                         narrate(part, callback);
                     if (written.length > 0)
                         runMessages.push({ role: 'assistant', content: written });
-                    remember();
+                    await keepFailed();
                     throw new UnrecoverableError('The LLM stopped before completing its answer', {
                         cause: 'The model stopped with "truncated". The run, and what the answer held before the limit, are kept in the conversation.',
                     });
@@ -755,6 +832,24 @@ export class LLMAgent {
                 }
                 const calls = response.message.content.filter(part => part.type === 'toolCall');
                 if (calls.length === 0) {
+                    // An answer given while agents work, or before the model read what they answered,
+                    // is a wait: the model goes on with their answers.
+                    let answers = background.takeAnswers();
+                    if (!answers && background.working && step < this.maxSteps) {
+                        await background.nextAnswer();
+                        throwIfProgressFailed();
+                        answers = background.takeAnswers();
+                    }
+                    if (answers || background.working) {
+                        if (step === this.maxSteps) {
+                            throw new UnrecoverableError('The LLM did not finish within its step limit', {
+                                cause: `The model was still waiting for the agents it sent after ${String(this.maxSteps)} steps.`,
+                            });
+                        }
+                        if (answers)
+                            runMessages.push(answers);
+                        continue;
+                    }
                     remember();
                     return {
                         // Only the final answer: text from earlier steps was narrated as it came.
@@ -762,7 +857,7 @@ export class LLMAgent {
                             .filter(part => part.type === 'text')
                             .map(part => part.text)
                             .join('\n'),
-                        tokens: unreported ? undefined : tokens,
+                        tokens: unreported || background.usageUnknown ? undefined : tokens,
                         duration: (Date.now() - start) / 1000,
                     };
                 }
@@ -793,7 +888,7 @@ export class LLMAgent {
                                 ...rest,
                             ],
                         });
-                        remember();
+                        await keepFailed();
                         throw decision;
                     }
                     repeats.reset();
@@ -801,13 +896,25 @@ export class LLMAgent {
                 }
                 // On the last step no call is left to send the results to, so the tools do not run.
                 if (step < this.maxSteps) {
-                    const { message, stopped } = await this.runTools(calls, options, effects, { run: context, reads, onProgress, spend }, throwIfProgressFailed, loops);
+                    const { message, stopped } = await this.runTools(calls, options, effects, {
+                        run: context,
+                        reads,
+                        onProgress,
+                        spend,
+                        depth: delegationOf(options)?.depth ?? 0,
+                        ...(options.approve ? { approve: options.approve } : {}),
+                        ...(options.ask ? { ask: options.ask } : {}),
+                    }, throwIfProgressFailed, loops, background);
                     runMessages.push(repeatedNote === undefined ? message : withNote(message, repeatedNote));
                     // Kept like a run cut by the output limit: the user may take it up.
                     if (stopped) {
-                        remember();
+                        await keepFailed();
                         throw stopped;
                     }
+                    // What agents answered meanwhile, after the results the model is waiting for.
+                    const answers = background.takeAnswers();
+                    if (answers)
+                        runMessages.push(answers);
                 }
             }
             throw new UnrecoverableError('The LLM did not finish within its step limit', {
@@ -815,6 +922,9 @@ export class LLMAgent {
             });
         }
         catch (error) {
+            // The run ends only after the agents still working, which stop with it: what they
+            // changed and spent is the run's.
+            await background.stop();
             let failure = error;
             if (effects.toolRan && error instanceof RecoverableError) {
                 // RetryingAgent would run the whole prompt again, and with it every tool this run
@@ -828,7 +938,7 @@ export class LLMAgent {
                 failure = unrecoverable;
             }
             // The run spent the tokens of every step before the one that failed.
-            throw withSpentTokens(failure, tokens, unreported);
+            throw withSpentTokens(failure, tokens, unreported || background.usageUnknown);
         }
     }
 }