@ny4n/durable 0.0.0-stage → 1.0.0

package/dist/harness/tool.js

@@ -0,0 +1,736 @@
+import { validateToolArguments } from "@ny4n/ai/utils/validation";
+import { copyJson } from "@ny4n/chord";
+import { awaitWithContext } from "@ny4n/chord/context";
+import { overlap } from "@ny4n/chord/delta";
+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, removeNestedSlots, toolSlot, } from "./live.js";
+import { boundOutput, OutputBuffer, PROGRESS_BYTES_PER_SECOND, Progress } from "./output.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 `nyan.live` hold slots below it, which settling removes. A crash between the two only costs a scan.
+ */
+const MADE_NESTED_CALLS = "nyan.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: "nyan.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 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: "nyan.tool",
+    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 resolveTool(runtime, task.input, call.name, context);
+            if (tool === undefined) {
+                const error = harnessError("tool_unavailable", `Tool ${call.name} is not available`);
+                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, task.input, call, COMPLETED, () => invalid(checked.error), context);
+            let args = checked.args;
+            let block;
+            await runtime.hooks.each("beforeTool", async (hook) => {
+                if (block !== undefined)
+                    return;
+                try {
+                    const decision = await hook({ ...call, arguments: args }, runtime, context);
+                    if (decision?.block !== undefined)
+                        block = decision.block;
+                    else if (decision?.arguments !== undefined)
+                        args = decision.arguments;
+                }
+                catch (error) {
+                    if (runtime.signal.aborted)
+                        throw error;
+                    block = errorMessage(error);
+                }
+            });
+            if (block !== undefined) {
+                const blocked = harnessError("blocked", `Tool call blocked: ${block}`);
+                return settle(runtime, task.input, call, COMPLETED, () => blocked, context);
+            }
+            const validated = validate(tool, call, args);
+            if ("error" in validated)
+                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, 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 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) => {
+                    const slot = toolSlot(await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId);
+                    if (slot !== undefined)
+                        clearProgress(slot);
+                    return undefined;
+                }, 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, task.input, call, ending, (slot) => fromSlot(slot, "interrupted", message), context);
+        },
+    },
+    abort: async (task, runtime, context) => {
+        const call = await readCall(runtime, task.input, 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 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"
+        ? message.content.find((content) => content.type === "toolCall" && content.id === input.callId)
+        : undefined;
+    if (call === undefined)
+        throw new Error(`Entry ${input.assistant} has no tool call ${input.callId}`);
+    return call;
+}
+/** The call's arguments as repaired by the tool; a throwing repair makes them invalid. */
+function prepare(tool, args) {
+    if (tool.prepareArguments === undefined)
+        return { args };
+    try {
+        return { args: tool.prepareArguments(args) };
+    }
+    catch (error) {
+        return { error: errorMessage(error) };
+    }
+}
+/** Arguments validated and coerced against the implementation's schema. */
+function validate(tool, call, args) {
+    try {
+        return { args: validateToolArguments(tool, { ...call, arguments: args }) };
+    }
+    catch (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, 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 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)
+            throw new Error(`Tool call ${call.id} has settled`);
+    };
+    const api = {
+        taskId: runtime.taskId,
+        conversationId: runtime.conversationId,
+        callId: call.id,
+        registry: runtime.registry,
+        agent: runtime.agent,
+        models: runtime.models,
+        output: (chunk, skipped) => {
+            assertLive();
+            if (reported.output.push(chunk, skipped))
+                progress.mark();
+        },
+        outputWindow: limits.retain === "tail"
+            ? {
+                maxBytes: limits.maxBytes,
+                maxLines: limits.maxLines,
+                minIntervalMs: runtime.settings.progress.outputIntervalMs,
+                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 }));
+            progress.mark();
+        },
+        details: async (value, detailsContext) => {
+            assertLive();
+            detailsContext.abortSignal?.throwIfAborted();
+            reported.details = copyJson(value, { omitUndefinedProperties: true });
+            const committed = progress.markAndWait();
+            // Cancelling the wait leaves the update in place; the commit's own outcome stays observed.
+            committed.catch(() => { });
+            return awaitWithContext(committed, detailsContext);
+        },
+        commit: async (change, commitContext) => {
+            let result;
+            await runtime.commit(async (tx) => {
+                result = await change(tx);
+                return undefined;
+            }, commitContext);
+            return result;
+        },
+        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, child);
+                return undefined;
+            }, taskContext);
+            return id;
+        },
+        getTask: runtime.getTask,
+        waitForTask: runtime.waitForTask,
+        conversation: runtime.conversation,
+        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;
+    // Execution time of this attempt; a rerun after recovery measures only itself.
+    let durationMs;
+    try {
+        // Built for this call, so a rerun after recovery gets the conversation's environment at that time.
+        const env = await runtime.env(context);
+        const startedAt = performance.now();
+        try {
+            result = await tool.execute(args, { ...api, env }, context);
+        }
+        finally {
+            durationMs = Math.round(performance.now() - startedAt);
+        }
+    }
+    catch (error) {
+        if (runtime.signal.aborted) {
+            ended = true;
+            for (const waiter of await progress.stop())
+                waiter.reject(error);
+            throw error;
+        }
+        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, input, call, tool, result, reported, context);
+        await settle(runtime, input, call, ending, () => settled, context, durationMs);
+    }
+    catch (error) {
+        for (const waiter of pending)
+            waiter.reject(error);
+        throw error;
+    }
+    for (const waiter of pending)
+        waiter.resolve();
+}
+/**
+ * Throttled commits of what the tool reported into its slot, in `nyan.live.tools` or `nyan.live.nestedTools`, each writing
+ * only what changed since the last one; none when `enabled` is false.
+ */
+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 };
+        const added = reported.diagnostics.slice(written.diagnostics, current.diagnostics);
+        const detailsChanged = current.details !== written.details;
+        // What the commit writes, as Chord diffs the string: an append, a trim plus an append of what follows the shared
+        // part, or the whole window when its bounded overlap search finds nothing.
+        let bytes = 0;
+        if (snapshot.text !== written.text) {
+            const shared = snapshot.text.startsWith(written.text)
+                ? written.text.length
+                : overlap(written.text, snapshot.text, 65_536);
+            bytes += utf8ByteLength(snapshot.text.slice(shared));
+        }
+        if (detailsChanged)
+            bytes += utf8ByteLength(JSON.stringify(current.details ?? null));
+        if (added.length > 0)
+            bytes += utf8ByteLength(JSON.stringify(added));
+        await runtime.commit(async (tx) => {
+            const slot = toolSlot(await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId);
+            if (slot === undefined)
+                return undefined;
+            // REMINDER: assign `output` as one string field. Chord then diffs it into an append, or a trim plus an
+            // append for a sliding tail; replacing the slot object would record the whole window on every commit.
+            if ((slot.output ?? "") !== snapshot.text)
+                slot.output = snapshot.text;
+            if (snapshot.droppedBytes > 0)
+                slot.droppedBytes = snapshot.droppedBytes;
+            if (snapshot.droppedLines > 0)
+                slot.droppedLines = snapshot.droppedLines;
+            // Diff details leaf by leaf and append new diagnostics, so each commit writes only what changed.
+            if (detailsChanged && current.details !== undefined) {
+                assignJson(slot, "details", current.details);
+            }
+            if (added.length > 0) {
+                if (slot.diagnostics === undefined)
+                    slot.diagnostics = [];
+                for (const diagnostic of added)
+                    slot.diagnostics.push(diagnostic);
+            }
+            return undefined;
+        }, context);
+        written = current;
+        return bytes;
+    }, (error) => {
+        // Rejections after an abort mark or close are expected; the committed state stays consistent.
+        if (!runtime.signal.aborted)
+            runtime.report(error);
+    }, runtime.settings.progress.outputIntervalMs);
+}
+/**
+ * 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, 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, input, call, tool, result, reported, context) {
+    const harness = [];
+    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,
+        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 output.
+    if (retained !== undefined && retained.droppedBytes > 0 && final.output === output) {
+        harness.push(truncated(retained, reported.limits.retain));
+    }
+    const bounded = boundContent(final.output ?? [], reported.limits);
+    if (bounded.droppedBytes > 0)
+        harness.push(truncated(bounded, reported.limits.retain));
+    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));
+        }
+    }
+    // Without a schema, programs get the output itself; the model reads only `output`, so model-issued calls skip it.
+    if (input.kind === "nested" && tool.structuredOutputSchema === undefined) {
+        final = { ...final, structuredOutput: outputValue(bounded.content) };
+    }
+    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 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 `nyan.live`. `build` receives the slot so interruption and abort can report the durable
+ * partial output.
+ */
+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 conversationId = runtime.conversationId;
+        const live = await tx.doc(LiveDoc, conversationId);
+        const slot = toolSlot(live, runtime.taskId);
+        const result = build(slot);
+        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: settled } };
+        if (ending.status === "failed") {
+            const error = { message: ending.message };
+            return { status: "terminal", outcome: { status: "failed", error, result: settled } };
+        }
+        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) {
+    const diagnostics = [...(slot?.diagnostics ?? [])];
+    const droppedBytes = slot?.droppedBytes ?? 0;
+    if (droppedBytes > 0)
+        diagnostics.push(truncated({ droppedBytes, droppedLines: slot?.droppedLines ?? 0 }));
+    diagnostics.push(toolDiagnostic(code, message));
+    return {
+        output: slot?.output === undefined || slot.output === "" ? [] : [{ type: "text", text: slot.output }],
+        isError: true,
+        ...(slot?.details === undefined ? {} : { details: slot.details }),
+        diagnostics,
+    };
+}
+/** An error result the Harness writes itself: no content and one `error` diagnostic with `code`. */
+export function harnessError(code, message) {
+    return { output: [], isError: true, diagnostics: [toolDiagnostic(code, message)] };
+}
+function toolDiagnostic(code, message) {
+    return { severity: "error", code, message };
+}
+/** The Harness's truncation diagnostic; `retain` is unknown when rebuilt from a slot after recovery. */
+function truncated(dropped, retain) {
+    const kept = retain === undefined ? "" : ` to its ${retain === "head" ? "beginning" : "end"}`;
+    return {
+        severity: "warn",
+        code: "truncated",
+        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 `nyan.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 `nyan.usage` in the same commit.
+ */
+export async function appendToolResult(tx, conversationId, call, result, meta) {
+    const { timestamp, durationMs } = meta;
+    const diagnostics = [...(result.diagnostics ?? [])];
+    const content = [...(result.output ?? [])];
+    if (diagnostics.length > 0)
+        content.push({ type: "text", text: renderDiagnostics(diagnostics) });
+    const message = {
+        role: "toolResult",
+        toolCallId: call.id,
+        toolName: call.name,
+        content,
+        ...(result.details === undefined ? {} : { details: result.details }),
+        ...(result.usage === undefined ? {} : { usage: result.usage }),
+        isError: result.isError ?? false,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        timestamp,
+    };
+    if (result.usage !== undefined)
+        await recordUsage(tx, conversationId, "tools", call.name, result.usage);
+    return tx.appendEntry(ToolResultEntry, conversationId, { model: [message], data: { diagnostics } });
+}
+function renderDiagnostics(diagnostics) {
+    return `<harness>\n${diagnostics.map((diagnostic) => `[${diagnostic.severity}] ${diagnostic.message}`).join("\n")}\n</harness>`;
+}
+/**
+ * Bound the text of result content. When the joined text exceeds the limits, the text items are replaced by one bounded
+ * item at the position of the first (head) or last (tail) text item; other content is kept.
+ */
+function boundContent(content, limits) {
+    const texts = content.filter((item) => item.type === "text");
+    const bounded = boundOutput(texts.map((item) => item.text).join(""), limits);
+    if (bounded.droppedBytes === 0)
+        return { content, droppedBytes: 0, droppedLines: 0 };
+    const keep = limits.retain === "head" ? texts[0] : texts.at(-1);
+    const result = [];
+    for (const item of content) {
+        if (item.type !== "text")
+            result.push(item);
+        else if (item === keep)
+            result.push({ ...item, text: bounded.text });
+    }
+    return { content: result, droppedBytes: bounded.droppedBytes, droppedLines: bounded.droppedLines };
+}
+/**
+ * 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