@earendil-works/pi-durable 1.1.0 → 1.3.0

package/dist/harness/tool.js

@@ -1,35 +1,61 @@
 import { copyJson } from "@earendil-works/chord";
 import { awaitWithContext } from "@earendil-works/chord/context";
 import { overlap } from "@earendil-works/chord/delta";
+import { boundOutput, OutputBuffer, PROGRESS_BYTES_PER_SECOND, Progress, } from "@earendil-works/chord/output";
 import { validateToolArguments } from "@earendil-works/pi-ai/utils/validation";
+import { Compile } from "typebox/compile";
+import { defineDocFamily } from "../documents.js";
 import { AssistantEntry, ToolResultEntry } from "../entries.js";
+import { errorMessage } from "../errors.js";
 import { defineTask } from "../tasks.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, utf8ByteLength } from "../truncate.js";
 import { assignJson } from "./json.js";
-import { clearProgress, finishSlot, LiveDoc, toolSlot } from "./live.js";
-import { boundOutput, OutputBuffer, PROGRESS_BYTES_PER_SECOND, Progress } from "./output.js";
+import { clearProgress, finishSlot, LiveDoc, removeNestedSlots, toolSlot, } from "./live.js";
 import { recordUsage } from "./usage.js";
+/**
+ * Memo of a tool task that made a nested call, in any attempt, committed before the first admission of each attempt:
+ * only then can `pi.live` hold slots below it, which settling removes. A crash between the two only costs a scan.
+ */
+const MADE_NESTED_CALLS = "pi.tool.madeNestedCalls";
+/**
+ * The nested calls of a tool call, a task-scoped family of the calling task keyed by the nested call's key: so a rerun
+ * finds the calls it already made, and the caller reads each result. Created with the nested task; the nested call's
+ * terminal commit adds its result. One document per call, so no commit rewrites the others. Retires with the caller.
+ */
+export const NestedCallDoc = defineDocFamily({
+    kind: "pi.tool.nested-call",
+    version: 1,
+    scope: "task",
+    family: true,
+    initial: () => ({}),
+});
 /**
  * Built-in tool task: resolves the called tool among its phase agent's tools, validates, runs `beforeTool`, records intent,
- * executes, runs `afterTool`, and appends the result, all in one `call` handler so nothing separates resolution from
- * settlement. `execute` is reached only by recovery and applies the replay rule.
+ * executes, runs `afterTool`, and settles the result, all in one `call` handler so nothing separates resolution from
+ * settlement. `execute` is reached only by recovery and applies the replay rule. A model-issued call settles by
+ * appending its result entry; a nested call by writing its result to its caller's `NestedCallDoc`.
  */
 export const ToolTask = defineTask({
     name: "pi.tool",
-    version: 1,
+    version: 2,
     initial: () => ({ phase: "call" }),
+    // Version 1 had only model-issued calls.
+    migrate: (input, checkpoint) => ({
+        input: { kind: "model", ...input },
+        checkpoint: checkpoint,
+    }),
     phases: {
         call: async (task, runtime, context) => {
             const call = await readCall(runtime, task.input, context);
-            const tool = (await runtime.agent(context)).tools.find((each) => each.name === call.name);
+            const tool = await resolveTool(runtime, task.input, call.name, context);
             if (tool === undefined) {
                 const error = harnessError("tool_unavailable", `Tool ${call.name} is not available`);
-                return settle(runtime, call, COMPLETED, () => error, context);
+                return settle(runtime, task.input, call, COMPLETED, () => error, context);
             }
             const prepared = prepare(tool, call.arguments);
             const checked = "error" in prepared ? prepared : validate(tool, call, prepared.args);
             if ("error" in checked)
-                return settle(runtime, call, COMPLETED, () => invalid(checked.error), context);
+                return settle(runtime, task.input, call, COMPLETED, () => invalid(checked.error), context);
             let args = checked.args;
             let block;
             await runtime.hooks.each("beforeTool", async (hook) => {
@@ -45,31 +71,37 @@ export const ToolTask = defineTask({
                 catch (error) {
                     if (runtime.signal.aborted)
                         throw error;
-                    block = errorText(error);
+                    block = errorMessage(error);
                 }
             });
             if (block !== undefined) {
                 const blocked = harnessError("blocked", `Tool call blocked: ${block}`);
-                return settle(runtime, call, COMPLETED, () => blocked, context);
+                return settle(runtime, task.input, call, COMPLETED, () => blocked, context);
             }
             const validated = validate(tool, call, args);
             if ("error" in validated)
-                return settle(runtime, call, COMPLETED, () => invalid(validated.error), context);
-            const final = validated.args;
+                return settle(runtime, task.input, call, COMPLETED, () => invalid(validated.error), context);
+            // Strict JSON: repair may set optional properties to undefined, which the slot and checkpoint cannot hold.
+            const final = copyJson(validated.args, { omitUndefinedProperties: true });
             await runtime.commit(async (tx) => {
                 const slot = toolSlot(await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId);
                 if (slot !== undefined)
                     slot.status = "running";
+                // A nested slot shows the arguments the call runs with, which repair, hooks, and coercion may have changed.
+                // Compared with the input, which the slot got at admission: reading the draft would track every leaf.
+                const changed = task.input.kind === "nested" && !jsonEqual(task.input.call.arguments, final);
+                if (changed && slot !== undefined && "parentTaskId" in slot)
+                    slot.arguments = final;
                 const intent = { phase: "execute", arguments: final, replay: tool.replay ?? "unsafe" };
                 return { status: "running", checkpoint: intent };
             }, context);
-            await run(runtime, call, tool, final, context);
+            await run(runtime, task.input, call, tool, final, context);
         },
         /** Recovery after intent: rerun only when the stored and the current policy both say `safe`. */
         execute: async (task, runtime, context) => {
             const { arguments: args, replay } = task.state.checkpoint;
             const call = await readCall(runtime, task.input, context);
-            const tool = (await runtime.agent(context)).tools.find((each) => each.name === call.name);
+            const tool = await resolveTool(runtime, task.input, call.name, context);
             if (replay === "safe" && tool?.replay === "safe") {
                 // The rerun reports from scratch; clear what the interrupted attempt published.
                 await runtime.commit(async (tx) => {
@@ -78,22 +110,35 @@ export const ToolTask = defineTask({
                         clearProgress(slot);
                     return undefined;
                 }, context);
-                return run(runtime, call, tool, args, context);
+                return run(runtime, task.input, call, tool, args, context);
             }
             const message = `Tool ${call.name} was interrupted and may have partially run`;
             // `failed` records cancellation intent, so the call's owned conversations, left unsupervised, are aborted.
             const ending = { status: "failed", message };
-            await settle(runtime, call, ending, (slot) => fromSlot(slot, "interrupted", message), context);
+            await settle(runtime, task.input, call, ending, (slot) => fromSlot(slot, "interrupted", message), context);
         },
     },
     abort: async (task, runtime, context) => {
         const call = await readCall(runtime, task.input, context);
-        const message = `Tool ${call.name} was aborted`;
-        await settle(runtime, call, { status: "aborted" }, (slot) => fromSlot(slot, "aborted", message), context);
+        // Abandoned after a restart (`TaskOptions.abandonOnRestart`): say whether the call may have run.
+        const [code, message] = task.abortReason !== "restart"
+            ? ["aborted", `Tool ${call.name} was aborted`]
+            : task.state.checkpoint.phase === "execute"
+                ? ["interrupted", `Tool ${call.name} was interrupted by a restart and may have partially run`]
+                : ["abandoned", `Tool ${call.name} was not started: its caller ended with a restart`];
+        const ending = { status: "aborted" };
+        await settle(runtime, task.input, call, ending, (slot) => fromSlot(slot, code, message), context);
     },
 });
-/** The tool call `callId` of the assistant entry. */
+/** The called tool: among the tools the model is offered for a model-issued call, else among those tools may call. */
+async function resolveTool(runtime, input, name, context) {
+    const agent = await runtime.agent(context);
+    return (input.kind === "model" ? agent.tools : agent.callable).find((tool) => tool.name === name);
+}
+/** The call: from the input for a nested call, which hooks see with its parent, else from the assistant entry. */
 async function readCall(runtime, input, context) {
+    if (input.kind === "nested")
+        return { ...input.call, parent: { taskId: input.parent, callId: input.parentCallId } };
     const entry = await runtime.entry(AssistantEntry, input.assistant, context);
     const message = entry?.model?.[0];
     const call = message?.role === "assistant"
@@ -111,7 +156,7 @@ function prepare(tool, args) {
         return { args: tool.prepareArguments(args) };
     }
     catch (error) {
-        return { error: errorText(error) };
+        return { error: errorMessage(error) };
     }
 }
 /** Arguments validated and coerced against the implementation's schema. */
@@ -120,21 +165,31 @@ function validate(tool, call, args) {
         return { args: validateToolArguments(tool, { ...call, arguments: args }) };
     }
     catch (error) {
-        return { error: errorText(error) };
+        return { error: errorMessage(error) };
     }
 }
 function invalid(message) {
     return harnessError("invalid_arguments", message);
 }
 /** Execute with the resolved implementation, then settle its result. */
-async function run(runtime, call, tool, args, context) {
+async function run(runtime, input, call, tool, args, context) {
     const limits = {
         maxBytes: tool.outputLimits?.maxBytes ?? DEFAULT_MAX_BYTES,
         maxLines: tool.outputLimits?.maxLines ?? DEFAULT_MAX_LINES,
         retain: tool.outputLimits?.retain ?? "head",
     };
     const reported = { output: new OutputBuffer(limits), limits, diagnostics: [], details: undefined };
-    const progress = publishProgress(runtime, reported, context);
+    const streams = input.kind === "model" || input.progress !== false;
+    const progress = publishProgress(runtime, reported, streams, context);
+    /** Nested call admissions this invocation started; cleanup waits for them, so it sees every nested call. */
+    const admissions = [];
+    // A caller that can rerun reattaches to its nested calls and child tasks after a restart; any other caller never
+    // resumes, so they are abandoned (`TaskOptions.abandonOnRestart`).
+    const resumes = tool.replay === "safe";
+    /** Default keys: the order of this invocation's calls, so a rerun that calls in the same order reattaches. */
+    let sequence = 0;
+    /** This attempt's commit of the `MADE_NESTED_CALLS` memo. */
+    let madeNestedMemo;
     let ended = false;
     const assertLive = () => {
         if (ended)
@@ -160,6 +215,11 @@ async function run(runtime, call, tool, args, context) {
                 bytesPerSecond: PROGRESS_BYTES_PER_SECOND,
             }
             : undefined,
+        retainedOutput: () => {
+            assertLive();
+            const retained = reported.output.snapshot();
+            return { text: retained.text, truncated: retained.droppedBytes > 0 };
+        },
         diagnostic: (diagnostic) => {
             assertLive();
             reported.diagnostics.push(copyJson(diagnostic, { omitUndefinedProperties: true }));
@@ -184,9 +244,10 @@ async function run(runtime, call, tool, args, context) {
         },
         memo: runtime.memo,
         createTask: async (task, input, options, taskContext) => {
+            const child = options.ownership.kind === "task" && !resumes ? { abandonOnRestart: true, ...options } : options;
             let id;
             await runtime.commit(async (tx) => {
-                id = await tx.createTask(task, input, options);
+                id = await tx.createTask(task, input, child);
                 return undefined;
             }, taskContext);
             return id;
@@ -197,6 +258,27 @@ async function run(runtime, call, tool, args, context) {
         snapshot: runtime.snapshot,
         snapshotAsOf: runtime.snapshotAsOf,
         watchDoc: runtime.watchDoc,
+        executeTool: async (name, toolArgs, callContext, options = {}) => {
+            assertLive();
+            const key = options.key ?? String(++sequence);
+            if (options.key !== undefined)
+                checkKey(options.key);
+            // The memo first, once per attempt; a failed one is tried again by the next call.
+            madeNestedMemo ??= runtime.memo(MADE_NESTED_CALLS, true, callContext).catch((error) => {
+                madeNestedMemo = undefined;
+                throw error;
+            });
+            // Registered now, so cleanup waits for it.
+            const admission = madeNestedMemo.then(() => startNestedCall(runtime, call.id, name, toolArgs, { key, progress: options.progress, abandonOnRestart: !resumes }, callContext));
+            admissions.push(admission);
+            const id = await admission;
+            const settled = await runtime.waitForTask(id, callContext);
+            const stored = (await runtime.snapshot(NestedCallDoc, runtime.taskId, key, callContext))?.result;
+            // A copy the tool may change; a nested call the scheduler faulted or orphaned stored none.
+            return stored === undefined
+                ? fallbackResult(id, name, settled.state.outcome)
+                : copyJson(stored);
+        },
     };
     let result;
     let ending = COMPLETED;
@@ -220,18 +302,20 @@ async function run(runtime, call, tool, args, context) {
                 waiter.reject(error);
             throw error;
         }
-        result = { isError: true, diagnostics: [toolDiagnostic("tool_error", errorText(error))] };
-        // A throw, from `execute()` or from building the environment, ends the task `failed`, which cancels what the call owned; it no longer supervises it. The error text
-        // is already in the result entry.
+        result = { isError: true, diagnostics: [toolDiagnostic("tool_error", errorMessage(error))] };
+        // A throw, from `execute()` or from building the environment, ends the task `failed`, which cancels what the call
+        // owned; it no longer supervises it. The error text is already in the result.
         ending = { status: "failed", message: `Tool ${call.name} threw` };
     }
     ended = true;
+    // No admission starts after `ended`; let those underway commit, so settlement aborts and lists their calls.
+    await Promise.allSettled(admissions);
     reported.output.end();
     // Details still waiting for a progress commit settle with the terminal commit, the final flush.
     const pending = await progress.stop();
     try {
-        const settled = await finalResult(runtime, call, result, reported, context);
-        await settle(runtime, call, ending, () => settled, context, durationMs);
+        const settled = await finalResult(runtime, input, call, tool, result, reported, context);
+        await settle(runtime, input, call, ending, () => settled, context, durationMs);
     }
     catch (error) {
         for (const waiter of pending)
@@ -242,12 +326,14 @@ async function run(runtime, call, tool, args, context) {
         waiter.resolve();
 }
 /**
- * Throttled commits of what the tool reported into its `pi.live.tools` slot, each writing only what changed since the
- * last one.
+ * Throttled commits of what the tool reported into its slot, in `pi.live.tools` or `pi.live.nestedTools`, each writing
+ * only what changed since the last one; none when `enabled` is false.
  */
-function publishProgress(runtime, reported, context) {
+function publishProgress(runtime, reported, enabled, context) {
     let written = { text: "", details: undefined, diagnostics: 0 };
     return new Progress(async () => {
+        if (!enabled)
+            return 0;
         // Capture everything synchronously: the tool keeps reporting while the commit is in flight.
         const snapshot = reported.output.snapshot();
         const current = { text: snapshot.text, details: reported.details, diagnostics: reported.diagnostics.length };
@@ -300,56 +386,247 @@ function publishProgress(runtime, reported, context) {
 }
 /**
  * The settled result: the tool's result with the retained output and last details as fallbacks, its diagnostics after
- * those reported through the api, `afterTool` applied, and explicit text bounded, with the Harness's truncation
- * diagnostic last.
+ * those reported through the api, `afterTool` applied, explicit text bounded, and `structuredOutput` checked against the
+ * tool's schema, with the Harness's diagnostics last. A nested call whose `structuredOutput` breaks the contract gets an
+ * error result without it; a model-issued call only loses it, and the break is reported to the host.
  */
-async function finalResult(runtime, call, result, reported, context) {
+async function finalResult(runtime, input, call, tool, result, reported, context) {
     const harness = [];
-    const retained = result.content === undefined ? reported.output.snapshot() : undefined;
-    const content = retained === undefined ? result.content : retained.text === "" ? [] : [{ type: "text", text: retained.text }];
+    const retained = result.output === undefined ? reported.output.snapshot() : undefined;
+    const output = retained === undefined ? result.output : retained.text === "" ? [] : [{ type: "text", text: retained.text }];
     let final = {
         ...result,
-        content,
+        output,
         details: result.details === undefined ? reported.details : result.details,
         diagnostics: [...reported.diagnostics, ...(result.diagnostics ?? [])],
     };
     await runtime.hooks.each("afterTool", async (hook) => {
         final = (await hook(call, final, runtime, context)) ?? final;
     });
-    // The retained output's truncation applies only while afterTool kept that content.
-    if (retained !== undefined && retained.droppedBytes > 0 && final.content === content) {
+    // The retained output's truncation applies only while afterTool kept that output.
+    if (retained !== undefined && retained.droppedBytes > 0 && final.output === output) {
         harness.push(truncated(retained, reported.limits.retain));
     }
-    const bounded = boundContent(final.content ?? [], reported.limits);
+    const bounded = boundContent(final.output ?? [], reported.limits);
     if (bounded.droppedBytes > 0)
         harness.push(truncated(bounded, reported.limits.retain));
-    return { ...final, content: bounded.content, diagnostics: [...(final.diagnostics ?? []), ...harness] };
+    const broken = structuredOutputError(tool, final);
+    if (broken !== undefined) {
+        const { structuredOutput: _dropped, ...rest } = final;
+        if (input.kind === "nested") {
+            final = { ...rest, isError: true };
+            harness.push(toolDiagnostic("invalid_structured_output", broken));
+        }
+        else {
+            // The model never sees structured output, so its call stands; the host learns of the broken tool.
+            final = rest;
+            runtime.report(new Error(broken));
+        }
+    }
+    // Programs get the tool's own value: without a schema, its output. The model reads only `output`, so model-issued
+    // calls skip both.
+    if (input.kind === "nested" && tool.structuredOutputSchema === undefined) {
+        final = { ...final, structuredOutput: outputValue(bounded.content) };
+    }
+    // A schema tool's error result without structured output has its text only in the output, which programs never
+    // get: it becomes an error diagnostic, as a thrown error's message does, unless one says what went wrong already.
+    if (input.kind === "nested" &&
+        tool.structuredOutputSchema !== undefined &&
+        final.isError === true &&
+        final.structuredOutput === undefined &&
+        ![...(final.diagnostics ?? []), ...harness].some((diagnostic) => diagnostic.severity === "error")) {
+        const text = bounded.content.flatMap((item) => (item.type === "text" ? [item.text] : [])).join("\n");
+        if (text !== "")
+            harness.push(toolDiagnostic("tool_error", text));
+    }
+    return { ...final, output: bounded.content, diagnostics: [...(final.diagnostics ?? []), ...harness] };
+}
+const structuredValidators = new WeakMap();
+/** Why a result's `structuredOutput` breaks the tool's contract, or `undefined` when it keeps it. */
+function structuredOutputError(tool, result) {
+    const schema = tool.structuredOutputSchema;
+    const value = result.structuredOutput;
+    if (schema === undefined) {
+        return value === undefined
+            ? undefined
+            : `Tool ${tool.name} returned structuredOutput but declares no structuredOutputSchema`;
+    }
+    if (value === undefined) {
+        return result.isError === true ? undefined : `Tool ${tool.name} returned no structuredOutput`;
+    }
+    let validator = structuredValidators.get(schema);
+    if (validator === undefined) {
+        validator = Compile(schema);
+        structuredValidators.set(schema, validator);
+    }
+    if (validator.Check(value))
+        return undefined;
+    const [first] = validator.Errors(value);
+    const path = first?.instancePath.replace(/^\//, "").replace(/\//g, ".") || "root";
+    return `Tool ${tool.name} returned structuredOutput that does not match its schema: ${path}: ${first?.message ?? "invalid"}`;
 }
 /**
- * Commit the tool's terminal state: append its result entry, mark its slot done, and complete or end aborted with the
- * entry ID. `build` receives the slot so interruption and abort can report the durable partial output.
+ * Commit the tool's terminal state and mark its slot done. A model-issued call appends its result entry and ends with
+ * the entry ID; a nested call writes its result to the caller's `NestedCallDoc`, records its usage, and ends with a
+ * small receipt. Nested calls this call left running are aborted first, so they report into their slots before the
+ * slots below the call leave `pi.live`. `build` receives the slot so interruption and abort can report the durable
+ * partial output.
  */
-async function settle(runtime, call, ending, build, context, durationMs) {
+async function settle(runtime, input, call, ending, build, context, durationMs) {
+    // A crash in between leaves the call in `execute`: a safe rerun reattaches to the calls, an interruption ends here.
+    // Every live nested call the task owns, also those an earlier attempt made and this one never called again.
+    const nestedIds = (await runtime.ownedTasks(context))
+        .filter((record) => record.kind === ToolTask.definition.name && record.input.kind === "nested")
+        .map((record) => record.id);
+    // Read before the settling commit: no admission starts after `ended`, and those underway were awaited.
+    const madeNested = (await runtime.memo(MADE_NESTED_CALLS, context)) === true;
+    // Mark them all before waiting for any: one may run until a sibling is cancelled.
+    await Promise.all(nestedIds.map((id) => runtime.abortOwned(id, context)));
     await runtime.commit(async (tx) => {
-        const slot = toolSlot(await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId);
+        const conversationId = runtime.conversationId;
+        const live = await tx.doc(LiveDoc, conversationId);
+        const slot = toolSlot(live, runtime.taskId);
         const result = build(slot);
-        const entry = await appendToolResult(tx, runtime.conversationId, call, result, runtime.now(), durationMs);
-        if (slot !== undefined)
-            finishSlot(slot, entry.id);
-        const entryId = entry.id;
+        let settled;
+        if (input.kind === "nested") {
+            const nested = nestedResult(runtime.taskId, result, durationMs);
+            if (nested.usage !== undefined)
+                await recordUsage(tx, conversationId, "tools", call.name, nested.usage);
+            // The caller is never terminal before its owned nested calls, so its document is open; another task in it is a
+            // bug, not a race.
+            const state = await tx.doc(NestedCallDoc, input.parent, input.key, null);
+            if (state.taskId !== runtime.taskId)
+                throw new Error(`Nested call ${call.id} is not in its caller's index`);
+            state.result = nested;
+            if (slot !== undefined && "parentTaskId" in slot) {
+                finishSlot(slot);
+                slot.summary = summaryOf(nested, result.output ?? []);
+            }
+            settled = { kind: "nested" };
+        }
+        else {
+            const timing = { timestamp: runtime.now(), durationMs };
+            const entry = await appendToolResult(tx, conversationId, call, result, timing);
+            if (slot !== undefined && !("parentTaskId" in slot)) {
+                finishSlot(slot);
+                slot.entry = entry.id;
+            }
+            // Tools build control objects freely; drop keys set to undefined so the task result is strict JSON.
+            const control = result.control === undefined || ending.status !== "completed"
+                ? {}
+                : { control: copyJson(result.control, { omitUndefinedProperties: true }) };
+            settled = { kind: "model", entryId: entry.id, ...control };
+        }
+        // A call that made no nested calls, in any attempt, has no slots below it; skipping the scan keeps many leaves
+        // linear. Committed before the read: no nested call is admitted after `ended`.
+        if (madeNested)
+            removeNestedSlots(live, runtime.taskId);
         if (ending.status === "aborted")
-            return { status: "terminal", outcome: { status: "aborted", result: { entryId } } };
+            return { status: "terminal", outcome: { status: "aborted", result: settled } };
         if (ending.status === "failed") {
             const error = { message: ending.message };
-            return { status: "terminal", outcome: { status: "failed", error, result: { entryId } } };
+            return { status: "terminal", outcome: { status: "failed", error, result: settled } };
         }
-        // Tools build control objects freely; drop keys set to undefined so the task result is strict JSON.
-        const control = result.control === undefined
-            ? {}
-            : { control: copyJson(result.control, { omitUndefinedProperties: true }) };
-        return { status: "terminal", outcome: { status: "completed", result: { entryId, ...control } } };
+        return { status: "terminal", outcome: { status: "completed", result: settled } };
     }, context);
 }
+/**
+ * A nested call's result, as stored and returned: strict JSON, without `output`, which only the model reads, and
+ * without `control`, which only model-issued calls apply.
+ */
+function nestedResult(taskId, result, durationMs) {
+    const nested = {
+        taskId,
+        structuredOutput: result.structuredOutput,
+        isError: result.isError ?? false,
+        details: result.details,
+        diagnostics: result.diagnostics ?? [],
+        usage: result.usage,
+        durationMs,
+    };
+    return copyJson(nested, {
+        omitUndefinedProperties: true,
+    });
+}
+/**
+ * Create nested call `key` of the call `parentCallId` in one commit: its tool task, owned by the calling task, its slot,
+ * and its `NestedCallDoc`. A key already made returns that call's task when it names the same tool and arguments.
+ */
+async function startNestedCall(runtime, parentCallId, name, args, options, context) {
+    const key = options.key;
+    const call = {
+        type: "toolCall",
+        id: `${parentCallId}/${key}`,
+        name,
+        arguments: copyJson(args, { omitUndefinedProperties: true }),
+    };
+    let id;
+    await runtime.commit(async (tx) => {
+        // Opened, or created empty for a key not made yet.
+        const state = await tx.doc(NestedCallDoc, runtime.taskId, key, null);
+        const existing = state.taskId;
+        if (existing !== undefined) {
+            const input = (await tx.task(existing))?.input;
+            const same = input?.kind === "nested" &&
+                input.call.name === name &&
+                jsonEqual(input.call.arguments, call.arguments);
+            if (!same)
+                throw new Error(`Nested call ${call.id} was already made with another tool or other arguments`);
+            id = existing;
+            return undefined;
+        }
+        const input = {
+            kind: "nested",
+            parent: runtime.taskId,
+            parentCallId,
+            key,
+            call,
+            ...(options.progress === false ? { progress: false } : {}),
+        };
+        const created = await tx.createTask(ToolTask, input, {
+            ownership: { kind: "task", taskId: runtime.taskId },
+            abandonOnRestart: options.abandonOnRestart,
+        });
+        state.taskId = created;
+        const live = await tx.doc(LiveDoc, runtime.conversationId);
+        live.nestedTools ??= [];
+        const slot = {
+            callId: call.id,
+            parentCallId,
+            parentTaskId: runtime.taskId,
+            name,
+            taskId: created,
+            arguments: call.arguments,
+            status: "pending",
+        };
+        live.nestedTools.push(slot);
+        id = created;
+        return undefined;
+    }, context);
+    return id;
+}
+/**
+ * What programs get of a tool's output when it declares no schema: one text item as its string, one image as itself,
+ * nothing as `""`, and anything else as the content list.
+ */
+function outputValue(output) {
+    if (output.length === 0)
+        return "";
+    if (output.length > 1)
+        return output;
+    const [only] = output;
+    return only.type === "text" ? only.text : only;
+}
+/** What the caller gets for a nested call without a stored result: one the scheduler faulted or orphaned. */
+function fallbackResult(taskId, name, outcome) {
+    const message = outcome.status === "faulted"
+        ? `Tool ${name} failed: ${outcome.error.message}`
+        : outcome.status === "orphaned"
+            ? `Tool ${name} could not resume: ${outcome.reason}`
+            : `Tool ${name} ended without a result`;
+    const error = harnessError(outcome.status, message);
+    return { taskId, isError: true, diagnostics: error.diagnostics ?? [] };
+}
 const COMPLETED = { status: "completed" };
 /** An error result from the slot's durable partial output, details, and diagnostics. */
 function fromSlot(slot, code, message) {
@@ -359,7 +636,7 @@ function fromSlot(slot, code, message) {
         diagnostics.push(truncated({ droppedBytes, droppedLines: slot?.droppedLines ?? 0 }));
     diagnostics.push(toolDiagnostic(code, message));
     return {
-        content: slot?.output === undefined || slot.output === "" ? [] : [{ type: "text", text: slot.output }],
+        output: slot?.output === undefined || slot.output === "" ? [] : [{ type: "text", text: slot.output }],
         isError: true,
         ...(slot?.details === undefined ? {} : { details: slot.details }),
         diagnostics,
@@ -367,7 +644,7 @@ function fromSlot(slot, code, message) {
 }
 /** An error result the Harness writes itself: no content and one `error` diagnostic with `code`. */
 export function harnessError(code, message) {
-    return { content: [], isError: true, diagnostics: [toolDiagnostic(code, message)] };
+    return { output: [], isError: true, diagnostics: [toolDiagnostic(code, message)] };
 }
 function toolDiagnostic(code, message) {
     return { severity: "error", code, message };
@@ -381,13 +658,33 @@ function truncated(dropped, retain) {
         message: `Output truncated${kept}: ${dropped.droppedLines} lines, ${dropped.droppedBytes} bytes dropped`,
     };
 }
+/** Error text a nested call's summary keeps. */
+const MAX_SUMMARY_ERROR_CHARS = 500;
+/** How a nested call ended, for its slot: error text, from its diagnostics or else its `output`, bounded. */
+function summaryOf(result, output) {
+    const error = result.isError ? errorTextOf(result, output).slice(0, MAX_SUMMARY_ERROR_CHARS) : "";
+    return {
+        isError: result.isError,
+        ...(result.durationMs === undefined ? {} : { durationMs: result.durationMs }),
+        ...(result.usage === undefined ? {} : { usage: result.usage }),
+        ...(error === "" ? {} : { error }),
+    };
+}
+/** The error messages of a nested result, else the text items of its output, joined with newlines. */
+function errorTextOf(result, output) {
+    const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0)
+        return errors.map((diagnostic) => diagnostic.message).join("\n");
+    return output.flatMap((item) => (item.type === "text" ? [item.text] : [])).join("\n");
+}
 /**
  * Append a `pi.tool-result` entry. The content ends with the rendered diagnostics, so the stored message is exactly
  * what the model sees; `data` keeps the structured list. A result's usage is added to `pi.usage` in the same commit.
  */
-export async function appendToolResult(tx, conversationId, call, result, timestamp, durationMs) {
+export async function appendToolResult(tx, conversationId, call, result, meta) {
+    const { timestamp, durationMs } = meta;
     const diagnostics = [...(result.diagnostics ?? [])];
-    const content = [...(result.content ?? [])];
+    const content = [...(result.output ?? [])];
     if (diagnostics.length > 0)
         content.push({ type: "text", text: renderDiagnostics(diagnostics) });
     const message = {
@@ -427,7 +724,25 @@ function boundContent(content, limits) {
     }
     return { content: result, droppedBytes: bounded.droppedBytes, droppedLines: bounded.droppedLines };
 }
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
+/**
+ * Explicit nested call keys are path segments of the call ID, so IDs of different nested calls never collide, and are
+ * never plain positive integers, which default keys use. `__proto__` stays reserved, as it was when keys indexed a JSON object.
+ */
+function checkKey(key) {
+    if (key === "" || key.includes("/") || key === "__proto__" || /^[1-9][0-9]*$/.test(key)) {
+        throw new Error(`Nested call key ${JSON.stringify(key)} must be non-empty, without "/", not "__proto__", and not a positive integer`);
+    }
+}
+/** Structural JSON equality; object key order does not matter. */
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => jsonEqual(item, b[i])));
+    }
+    const keys = Object.keys(a);
+    return (keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && jsonEqual(a[key], b[key])));
 }
 //# sourceMappingURL=tool.js.map