@earendil-works/pi-durable 1.4.0 → 1.5.0

package/dist/harness/tool.js

@@ -1,9 +1,10 @@
 import { copyJson } from "@earendil-works/chord";
 import { awaitWithContext } from "@earendil-works/chord/context";
-import { overlap } from "@earendil-works/chord/delta";
+import { overlap, ownedSlice } 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 { compile } from "@earendil-works/pi-schema";
+import { formats } from "@earendil-works/pi-schema/formats";
 import { defineDocFamily } from "../documents.js";
 import { AssistantEntry, ToolResultEntry } from "../entries.js";
 import { errorMessage } from "../errors.js";
@@ -11,7 +12,7 @@ import { defineTask } from "../tasks.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, utf8ByteLength } from "../truncate.js";
 import { toolExtension } from "./agent.js";
 import { assignJson } from "./json.js";
-import { clearProgress, finishSlot, LiveDoc, removeNestedSlots, toolSlot, } from "./live.js";
+import { clearProgress, cutOffCount, cutOffTooOften, finishSlot, LiveDoc, PROGRESS_COMMIT, removeNestedSlots, salvageable, toolSlot, } from "./live.js";
 import { recordUsage } from "./usage.js";
 import { optionalExtension } from "./util.js";
 /**
@@ -41,25 +42,29 @@ export const NestedCallDoc = defineDocFamily({
  */
 export const ToolTask = defineTask({
     name: "pi.tool",
-    version: 2,
+    version: 3,
     initial: () => ({ phase: "call" }),
-    // Version 1 had only model-issued calls.
-    migrate: (input, checkpoint) => ({
-        input: { kind: "model", ...input },
+    // Version 1 had only model-issued calls, without `kind`; version 3 added `unoffered`, absent in version 2 inputs.
+    migrate: (input, checkpoint, fromVersion) => ({
+        input: fromVersion === 1
+            ? { kind: "model", ...input }
+            : 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 (cutOffTooOften(task, runtime))
+                return endCutOff(runtime, task, call, context);
+            const tool = isUnoffered(task.input) ? undefined : 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);
+                return reject(runtime, task.input, call, undefined, 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);
+                return reject(runtime, task.input, call, tool, invalid(checked.error), context);
             let args = checked.args;
             let block;
             await runtime.hooks.each("beforeTool", async (hook) => {
@@ -80,22 +85,26 @@ export const ToolTask = defineTask({
             });
             if (block !== undefined) {
                 const blocked = harnessError("blocked", `Tool call blocked: ${block}`);
-                return settle(runtime, task.input, call, COMPLETED, () => blocked, context);
+                return reject(runtime, task.input, call, tool, blocked, context);
             }
             const validated = validate(tool, call, args);
             if ("error" in validated)
-                return settle(runtime, task.input, call, COMPLETED, () => invalid(validated.error), context);
+                return reject(runtime, task.input, call, tool, 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 });
+            // The slot's status and arguments are presentation, stored like progress (`PROGRESS_COMMIT`); the intent is
+            // durable before the tool runs. Parallel calls of one round then share no immediate write to `pi.live`.
             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)
+                // Assigned whole: an equal value records no change, and a rerun corrects what an earlier attempt showed.
+                if (slot !== undefined && "parentTaskId" in slot)
                     slot.arguments = final;
+                return undefined;
+            }, context, PROGRESS_COMMIT);
+            await runtime.commit(() => {
                 const intent = { phase: "execute", arguments: final, replay: tool.replay ?? "unsafe" };
                 return { status: "running", checkpoint: intent };
             }, context);
@@ -105,13 +114,21 @@ export const ToolTask = defineTask({
         execute: async (task, runtime, context) => {
             const { arguments: args, replay } = task.state.checkpoint;
             const call = await readCall(runtime, task.input, context);
+            // Also before an interruption result: its `afterTool` hooks may be what cut the task off.
+            if (cutOffTooOften(task, runtime))
+                return endCutOff(runtime, task, call, 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.
+                // The rerun reports from scratch: clear what the interrupted attempt published, and show the slot running with
+                // the arguments it runs with again, as the deferred commit that showed them may have been lost with the crash.
                 await runtime.commit(async (tx) => {
                     const slot = toolSlot(await tx.doc(LiveDoc, runtime.conversationId), runtime.taskId);
-                    if (slot !== undefined)
+                    if (slot !== undefined) {
                         clearProgress(slot);
+                        slot.status = "running";
+                        if ("parentTaskId" in slot)
+                            slot.arguments = args;
+                    }
                     return undefined;
                 }, context);
                 return run(runtime, task.input, call, tool, args, context);
@@ -119,26 +136,92 @@ export const ToolTask = defineTask({
             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);
+            // Not cut off too often (checked above), so the hooks run.
+            await settleFromSlot(runtime, task.input, call, { tool }, ending, "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);
+        // Abandoned after a restart (`TaskOptions.abandonOnRestart`): say whether the call may have run. An unoffered call
+        // could not run in any case, and its result says so.
+        const [code, message] = isUnoffered(task.input)
+            ? ["tool_unavailable", `Tool ${call.name} is not available`]
+            : 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`];
+        // The scheduler runs an abort handler only while its restarts are below the limit, and faults the task without a
+        // result when the last attempt is cut off. That attempt skips the hooks, which may be what cuts it off.
+        const hooks = (task.restarts ?? 0) < runtime.settings.restartLimit - 1
+            ? { tool: await toolForLimits(runtime, task.input, call.name, context) }
+            : undefined;
+        await settleFromSlot(runtime, task.input, call, hooks, { status: "aborted" }, code, message, context);
     },
 });
+/**
+ * End a call cut off `settings.restartLimit` times in a row (spec §5.4) with an error result, built from the slot like
+ * an interrupted call's, instead of running it again. `failed`, like an interruption, so its owned work is aborted.
+ */
+async function endCutOff(runtime, task, call, context) {
+    const message = `Tool ${call.name} was interrupted ${cutOffCount(task)}; it is not run again`;
+    const ending = { status: "failed", message, reason: "restart_limit" };
+    // Past the limit the hooks may be what keeps cutting the task off (`salvageable`).
+    const hooks = salvageable(task, runtime)
+        ? { tool: await toolForLimits(runtime, task.input, call.name, context) }
+        : undefined;
+    await settleFromSlot(runtime, task.input, call, hooks, ending, "restart_limit", message, context);
+}
+/**
+ * Settle a result the Harness decided in the `call` phase, without running the tool: the tool did not resolve, the
+ * arguments are invalid, or `beforeTool` blocked the call. `afterTool` applies as to an executed call's result.
+ */
+async function reject(runtime, input, call, tool, result, context) {
+    const settled = await afterHarnessResult(runtime, input, call, tool, result, undefined, context);
+    await settle(runtime, input, call, COMPLETED, settled, context);
+}
+/**
+ * Settle an error result built from the call's slot (`fromSlot`): an interruption, the restart limit, or an abort.
+ * The tool is not running, so the slot read before the commit is still current when it commits. With `hooks`, the
+ * result passes `afterTool` and is bounded with the limits of `hooks.tool` (the defaults when it is `undefined`);
+ * without, it is settled as built, when the hooks may be what cuts the task off.
+ */
+async function settleFromSlot(runtime, input, call, hooks, ending, code, message, context) {
+    const live = await runtime.snapshot(LiveDoc, runtime.conversationId, context);
+    const { result, truncation } = fromSlot(live === undefined ? undefined : toolSlot(live, runtime.taskId), code, message);
+    const settled = hooks !== undefined
+        ? await afterHarnessResult(runtime, input, call, hooks.tool, result, truncation, context)
+        : truncation === undefined
+            ? result
+            : { ...result, diagnostics: [...(result.diagnostics ?? []), truncation] };
+    await settle(runtime, input, call, ending, settled, context);
+}
+/**
+ * The tool whose output limits bound a hooks' result: the called tool, or none when it, or the agent, fails to resolve,
+ * and for an unoffered call, which never resolves its name.
+ */
+async function toolForLimits(runtime, input, name, context) {
+    if (isUnoffered(input))
+        return undefined;
+    return resolveTool(runtime, input, name, context).catch(() => undefined);
+}
+/** A model-issued call to a tool its request did not offer (spec §8.3). */
+function isUnoffered(input) {
+    return input.kind === "model" && input.unoffered === true;
+}
 /** 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 tool's output limits, the defaults filled in; all defaults when the tool did not resolve. */
+function outputLimits(tool) {
+    return {
+        maxBytes: tool?.outputLimits?.maxBytes ?? DEFAULT_MAX_BYTES,
+        maxLines: tool?.outputLimits?.maxLines ?? DEFAULT_MAX_LINES,
+        retain: tool?.outputLimits?.retain ?? "head",
+    };
+}
 /** 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") {
@@ -186,11 +269,7 @@ function invalid(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 limits = outputLimits(tool);
     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);
@@ -255,12 +334,12 @@ async function run(runtime, input, call, tool, args, context) {
             committed.catch(() => { });
             return awaitWithContext(committed, detailsContext);
         },
-        commit: async (change, commitContext) => {
+        commit: async (change, commitContext, options) => {
             let result;
             await runtime.commit(async (tx) => {
                 result = await change(tx);
                 return undefined;
-            }, commitContext);
+            }, commitContext, options);
             return result;
         },
         memo: runtime.memo,
@@ -335,7 +414,7 @@ async function run(runtime, input, call, tool, args, context) {
     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);
+        await settle(runtime, input, call, ending, settled, context, durationMs);
     }
     catch (error) {
         for (const waiter of pending)
@@ -366,7 +445,7 @@ function progressClock(runtime) {
 }
 /**
  * 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.
+ * only what changed since the last one, deferred (`PROGRESS_COMMIT`); none when `enabled` is false.
  */
 function publishProgress(runtime, reported, enabled, context) {
     let written = { text: "", details: undefined, diagnostics: 0 };
@@ -414,7 +493,7 @@ function publishProgress(runtime, reported, enabled, context) {
                     slot.diagnostics.push(diagnostic);
             }
             return undefined;
-        }, context);
+        }, context, PROGRESS_COMMIT);
         written = current;
         return bytes;
     }, (error) => {
@@ -461,7 +540,7 @@ async function finalResult(runtime, input, call, tool, result, reported, context
             final = rest;
             // Only names the extension: a failed resolution leaves the report without the name.
             const extension = await runtime.agent(context).then((agent) => toolExtension(agent, tool.name), () => undefined);
-            runtime.report(new Error(broken), { type: "extension", ...optionalExtension(extension) });
+            runtime.report(new Error(broken), { kind: "extension", ...optionalExtension(extension) });
         }
     }
     // Programs get the tool's own value: without a schema, its output. The model reads only `output`, so model-issued
@@ -482,6 +561,33 @@ async function finalResult(runtime, input, call, tool, result, reported, context
     }
     return { ...final, output: bounded.content, diagnostics: [...(final.diagnostics ?? []), ...harness] };
 }
+/**
+ * A result the Harness wrote itself, without executing the tool, after the `afterTool` chain, normalized like an
+ * executed call's: the output bounded with the tool's limits (the defaults when it did not resolve), a truncation
+ * diagnostic when that dropped something, and the hooks' `structuredOutput` dropped, since the tool never produced
+ * one. A nested call that the hooks turned into a success gets the bounded output as its value, as a schema-less
+ * tool's success does, unless the tool declares a schema. `usage` is kept and recorded; `control` applies only when
+ * the task completes. `truncation` describes what the result's own output lost before (a slot's retained output); it
+ * is kept only while the hooks keep that output.
+ */
+async function afterHarnessResult(runtime, input, call, tool, result, truncation, context) {
+    let final = result;
+    await runtime.hooks.each("afterTool", async (hook) => {
+        final = (await hook(call, final, runtime, context)) ?? final;
+    });
+    const harness = [];
+    if (truncation !== undefined && final.output === result.output)
+        harness.push(truncation);
+    const limits = outputLimits(tool);
+    const bounded = boundContent(final.output ?? [], limits);
+    if (bounded.droppedBytes > 0)
+        harness.push(truncated(bounded, limits.retain));
+    const { structuredOutput: _dropped, ...rest } = final;
+    const value = input.kind === "nested" && final.isError !== true && tool?.structuredOutputSchema === undefined
+        ? { structuredOutput: outputValue(bounded.content) }
+        : {};
+    return { ...rest, ...value, output: bounded.content, diagnostics: [...(rest.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) {
@@ -497,23 +603,26 @@ function structuredOutputError(tool, result) {
     }
     let validator = structuredValidators.get(schema);
     if (validator === undefined) {
-        validator = Compile(schema);
+        validator = compile(schema, { formats, unresolvedRefs: "reject" });
         structuredValidators.set(schema, validator);
     }
-    if (validator.Check(value))
+    if (validator.check(value))
         return undefined;
-    const [first] = validator.Errors(value);
-    const path = first?.instancePath.replace(/^\//, "").replace(/\//g, ".") || "root";
+    const [first] = validator.errors(value);
+    const path = first?.path
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"))
+        .join(".") || "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 `pi.live`. `build` receives the slot so interruption and abort can report the durable
- * partial output.
+ * slots below the call leave `pi.live`. `control` applies only when the task completes.
  */
-async function settle(runtime, input, call, ending, build, context, durationMs) {
+async function settle(runtime, input, call, ending, result, 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))
@@ -527,7 +636,6 @@ async function settle(runtime, input, call, ending, build, context, durationMs)
         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);
@@ -565,7 +673,10 @@ async function settle(runtime, input, call, ending, build, context, durationMs)
         if (ending.status === "aborted")
             return { status: "terminal", outcome: { status: "aborted", result: settled } };
         if (ending.status === "failed") {
-            const error = { message: ending.message };
+            const error = {
+                message: ending.message,
+                ...(ending.reason === undefined ? {} : { detail: { reason: ending.reason } }),
+            };
             return { status: "terminal", outcome: { status: "failed", error, result: settled } };
         }
         return { status: "terminal", outcome: { status: "completed", result: settled } };
@@ -674,19 +785,21 @@ function fallbackResult(taskId, name, outcome) {
     return { taskId, isError: true, diagnostics: error.diagnostics ?? [] };
 }
 const COMPLETED = { status: "completed" };
-/** An error result from the slot's durable partial output, details, and diagnostics. */
+/**
+ * An error result from the slot's durable partial output, details, and diagnostics, ending with `code`; and the
+ * truncation diagnostic of that output, when its bounds dropped some, which the caller adds after `afterTool`.
+ */
 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 {
+    const result = {
         output: slot?.output === undefined || slot.output === "" ? [] : [{ type: "text", text: slot.output }],
         isError: true,
         ...(slot?.details === undefined ? {} : { details: slot.details }),
-        diagnostics,
+        diagnostics: [...(slot?.diagnostics ?? []), toolDiagnostic(code, message)],
     };
+    if (droppedBytes === 0)
+        return { result };
+    return { result, truncation: truncated({ droppedBytes, droppedLines: slot?.droppedLines ?? 0 }) };
 }
 /** An error result the Harness writes itself: no content and one `error` diagnostic with `code`. */
 export function harnessError(code, message) {
@@ -706,9 +819,12 @@ function truncated(dropped, retain) {
 }
 /** 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. */
+/**
+ * How a nested call ended, for its slot: error text, from its diagnostics or else its `output`, bounded. The bound is a
+ * copy, so the slot never keeps a large output alive through a slice of it.
+ */
 function summaryOf(result, output) {
-    const error = result.isError ? errorTextOf(result, output).slice(0, MAX_SUMMARY_ERROR_CHARS) : "";
+    const error = result.isError ? ownedSlice(errorTextOf(result, output), 0, MAX_SUMMARY_ERROR_CHARS) : "";
     return {
         isError: result.isError,
         ...(result.durationMs === undefined ? {} : { durationMs: result.durationMs }),