@hachej/boring-agent 0.2.5 → 0.3.1

package/README.md

@@ -72,7 +72,7 @@ The descriptor's `id` and `ordinal` are optional and `present` sets neither; `pa
 
 `requireApproval(tool, { summarize })` from `@hachej/boring-agent/approval` wraps a native tool so each call waits for the person's Approve or Deny before `execute`. It reuses the ask-user mechanism (`askPerson` from `@hachej/boring-agent/ask-user`): a conversation document keyed by the tool call ID, answered with `answerUserQuestion` through the chat transport's `answer` operation, and shown by the `pi-chat` approval card. The check runs inside the tool's own execution in host code, so the model cannot skip it. While the call waits, the one-line `summarize` text is also published as the call's running details under `APPROVAL_DETAILS` (it stays as the result's details unless the tool returns its own). That is also how `pi-chat` recognizes a gated call: no list of tool names is needed. The card shows the summary as the headline with the raw arguments collapsed. Deny (or a stopped conversation) returns an error result starting `DENIED_PREFIX` and `execute` never runs. The wrapper is replay-safe: a pending approval survives a restart, and a retained native memo makes execution at most once (after a crash during execution the model gets an "outcome unknown" error instead of a repeat of the change). Reads are simply not wrapped.
 
-`createSandboxExtension({ tools, flags?, simulate? })` from `@hachej/boring-agent/sandbox` is a fail-closed sandbox as a native extension (`boring.sandbox`, or `name`). Its wraps replace each listed tool that the host flags `mutates` or `writes`, or does not declare `sandboxSafe` or `mutates: false`/`writes: false` (in `flags`), with a recorder: the call is never executed, the model gets `simulate(name, args)` (default `defaultAck`), and the result's details carry `{ simulated: true, tool, arguments }` under `SANDBOX_DETAILS`, which `simulatedCalls(results)` reads back. Its `beforeTool` hook blocks any call whose name is not in `tools`, so a tool added mid-run cannot run unnamed. Select it per conversation by including it in the complete selected list and applying that list with `configure({ extensions: selected })` (not `add`: defaults keep their positions, so an `add` list does not show the effective order), after any approval extension, so no question is asked inside a sandbox. **Composition limit (host-owned ordering):** the sandbox must be the last wrap of each recorded tool. A wrap selected after it (for example `createConvertingRead` on `read`) replaces the recorder's `execute`, and that call runs for real. Pi 1.1 has no public seam that tells the executing phase which composed tool it runs, so the sandbox cannot refuse this at call time. The host checks the order at setup with `assertSandboxLast(selected, sandbox)` over the COMPLETE selected list, the same array it applies with `configure({ extensions: selected })` (`@hachej/boring-agent/sandbox`); it throws on a later wrap of a recorded tool. Nothing in Pi calls it, so a host that composes extensions without it has no protection against that ordering. The gap is recorded in [docs/upstream/pi-hookapi-composed-tool.md](../../docs/upstream/pi-hookapi-composed-tool.md). The name gate in `beforeTool` is public and holds at call time: a call to a tool the sandbox does not name is refused.
+`createSandboxExtension({ tools, flags?, simulate? })` from `@hachej/boring-agent/sandbox` is a fail-closed sandbox as a native extension (`boring.sandbox`, or `name`). Its wraps replace each listed tool that the host flags `mutates` or `writes`, or does not declare `sandboxSafe` or `mutates: false`/`writes: false` (in `flags`), with a recorder: the call is never executed, the model gets `simulate(name, args)` (default `defaultAck`), and the result's details carry `{ simulated: true, tool, arguments }` under `SANDBOX_DETAILS`, which `simulatedCalls(results)` reads back. Its `beforeTool` hook blocks any call whose name is not in `tools`, so a tool added mid-run cannot run unnamed. Select it per conversation by including it in the complete selected list and applying that list with `configure({ extensions: selected })` (not `add`: defaults keep their positions, so an `add` list does not show the effective order), after any approval extension, so no question is asked inside a sandbox. **Composition limit (host-owned ordering):** the sandbox must be the last wrap of each recorded tool. A wrap selected after it (for example `createConvertingRead` on `read`) replaces the recorder's `execute`, and that call runs for real. Pi 1.2 has no public seam that tells the executing phase which composed tool it runs, so the sandbox cannot refuse this at call time. The host checks the order at setup with `assertSandboxLast(selected, sandbox)` over the COMPLETE selected list, the same array it applies with `configure({ extensions: selected })` (`@hachej/boring-agent/sandbox`); it throws on a later wrap of a recorded tool. Nothing in Pi calls it, so a host that composes extensions without it has no protection against that ordering. The gap is recorded in [docs/upstream/pi-hookapi-composed-tool.md](../../docs/upstream/pi-hookapi-composed-tool.md). The name gate in `beforeTool` is public and holds at call time: a call to a tool the sandbox does not name is refused.
 
 `createApprovalExtension({ name?, tools: { bash: true, write_note: { summarize, when } } })` is the same gate as an opt-in native extension: it brings no tools, only native `wraps` that decorate whichever tool of each name wins in a conversation, including Pi's stock `bash`, `write` and `edit`. Pi applies wraps only where the extension is selected, so the gate is per conversation: `conversation.configure({ extensions: { add: [approvals] } })` turns it on and `remove` turns it off from the next call. `when(args, call)` lets a rule ask only for some calls (for example any method but GET); `summarize(args, call)` writes the card's headline (default: the tool name and its arguments). `call` is `{ conversationId, callId, toolName }`, so a host with one conversation per site or project can name it in the headline. Approval extensions compose: a tool already gated is not gated again, so the first selected rule for a tool decides. `requireApproval(tool, { summarize, when? })` remains the building block for a tool you define yourself.
 
@@ -238,7 +238,7 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 ## Asking the person
 
-`@hachej/boring-agent/ask-user` exports `createAskUserTool()`, a replay-safe native tool named `ask_user` with arguments `{ question, options?: string[2..6], allowFreeText? }`. The call waits on a conversation document keyed by its assistant entry and tool call ID, so no model request is held, a pending question survives a restart and stopping the conversation cancels it. A trusted host resolves it with `answerUserQuestion(conversation, askUserQuestionId(assistantEntryId, callId), answer)` (pass the scoped ID through `ChatTransportAccess.answer` after authenticating the person): the answer must be an option unless free text is allowed, at most 2000 characters; one answer wins, repeating it is idempotent. The tool result is `{"kind":"answered","answer":"..."}`. The chat transport also serves `?op=answer` and `?op=withdraw` (a queued message, by submission ID), both gated by `allow`.
+`@hachej/boring-agent/ask-user` exports `createAskUserTool()`, a replay-safe native tool named `ask_user` with arguments `{ question, options?: string[2..6], allowFreeText? }`. The call waits on a conversation document keyed by its assistant entry and tool call ID, so no model request is held, a pending question survives a restart and stopping the conversation cancels it. A trusted host resolves it with `answerUserQuestion(conversation, askUserQuestionId(assistantEntryId, callId), answer)` (pass the scoped ID through `ChatTransportAccess.answer` after authenticating the person): the answer must be an option unless free text is allowed, at most 2000 characters; one answer wins, repeating it is idempotent. The tool result is `{"kind":"answered","answer":"..."}`. The chat transport also serves `?op=answer` and `?op=withdraw` (a queued message, by submission ID), both gated by `allow`. Like browser tasks and `requireApproval`-gated tools, it is `callers: ['model']`: the wait binds to the calling model entry, so Pi refuses a nested `api.executeTool` call (`tool_unavailable`) until nested bindings are supported.
 
 ## Browser tasks
 
@@ -298,7 +298,7 @@ const navigate = createPresentationTool({
   target: capturedTarget,
   prepareInput: ({ index }) => ({ index, expiresAt: Date.now() + 5000 }),
   authorize: (_input, _target, api, context) => canNavigate(api.conversationId, context),
-  formatResult: result => ({ content: [{ type: 'text', text: JSON.stringify({ kind: result.kind }) }] }),
+  formatResult: result => ({ output: [{ type: 'text', text: JSON.stringify({ kind: result.kind }) }] }),
 });
 ```
 

package/dist/approval.js

@@ -15,7 +15,7 @@ export const CANCELLED_PREFIX = 'Not run: the approval question was cancelled.';
 export const APPROVAL_DETAILS = 'boring.approval';
 const MEMO = 'boring.approval.started';
 const GATED = new WeakSet();
-const text = (value, isError) => ({ isError, content: [{ type: 'text', text: value }] });
+const text = (value, isError) => ({ isError, output: [{ type: 'text', text: value }] });
 /**
  * Wrap a native tool so the person must approve each call before it executes. The tool keeps its name, schema and
  * description. Before `execute`, the call asks "Approve / Deny" through the ask-user mechanism (a conversation document
@@ -41,6 +41,7 @@ export function requireApproval(tool, options) {
     const gated = {
         ...tool,
         replay: 'safe',
+        callers: ['model'], // the question binds to the calling model entry; a nested executeTool caller has none (durable-wait.ts)
         execute: async (args, outerApi, context) => {
             let record;
             const withRecord = (value) => !record ? value

package/dist/artifacts.js

@@ -66,7 +66,7 @@ export function parseArtifact(value) {
     return { schema: 'boring.artifact', version: 1, ...(id === undefined ? {} : { id }), title, type: type, mediaType, ...(language === undefined ? {} : { language: language }),
         target: { resource: { providerId, path }, view: parsedView }, revision, ...(ordinal === undefined ? {} : { ordinal }) };
 }
-const reply = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+const reply = (value) => ({ output: [{ type: 'text', text: JSON.stringify(value) }] });
 const decode = (bytes) => { try {
     return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
 }

package/dist/ask-user.js

@@ -35,12 +35,14 @@ export function createAskUserTool(options = {}) {
             allowFreeText: Type.Optional(Type.Boolean()),
         }, { additionalProperties: false }),
         replay: 'safe',
+        // The wait binds to the calling model entry and call id; a nested `api.executeTool` caller has neither (see durable-wait.ts).
+        callers: ['model'],
         execute: async (args, api, context) => {
             const problem = refusal(args.options, args.allowFreeText);
             if (problem)
-                return { isError: true, content: [{ type: 'text', text: `Invalid question: ${problem}.` }] };
+                return { isError: true, output: [{ type: 'text', text: `Invalid question: ${problem}.` }] };
             const answer = await askPerson(api, context, { prompt: args.question, ...(args.options === undefined ? {} : { options: args.options }), allowFreeText: args.allowFreeText === true });
-            return { content: [{ type: 'text', text: JSON.stringify({ kind: 'answered', answer }) }] };
+            return { output: [{ type: 'text', text: JSON.stringify({ kind: 'answered', answer }) }] };
         },
     });
 }

package/dist/browser-task.js

@@ -31,6 +31,8 @@ export function createBrowserTaskTool(options) {
         description: options.description,
         parameters: options.parameters,
         replay: 'safe',
+        // The wait binds to the calling model entry and call id; a nested `api.executeTool` caller has neither (see durable-wait.ts).
+        callers: ['model'],
         execute: async (_args, api, context) => {
             const key = await api.commit(async (tx) => {
                 const key = await ownBindingKey(tx, api);
@@ -49,7 +51,7 @@ export function createBrowserTaskTool(options) {
             const state = final?.task?.state;
             if (state?.kind !== 'answered')
                 throw new Error('Browser task cancelled');
-            return { content: [{ type: 'text', text: JSON.stringify(state.answer) }] };
+            return { output: [{ type: 'text', text: JSON.stringify(state.answer) }] };
         },
     });
 }

package/dist/file-convert.js

@@ -21,7 +21,7 @@ import { asWorkspaceResolver, workspaceFor } from './workspaces.js';
 const MAX_LINES = 2000; // Pi's read page: DEFAULT_MAX_LINES
 const MAX_BYTES = 50 * 1024; // Pi's read page: DEFAULT_MAX_BYTES
 const DEFAULT_MAX_FILE = 20 * 1024 * 1024;
-const failure = (text, code) => ({ content: [{ type: 'text', text }], isError: true, diagnostics: [{ severity: 'error', code, message: text }] });
+const failure = (text, code) => ({ output: [{ type: 'text', text }], isError: true, diagnostics: [{ severity: 'error', code, message: text }] });
 const utf8Length = (text) => new TextEncoder().encode(text).length;
 /**
  * The converted text as pageable lines. A line longer than MAX_BYTES is split, on character boundaries, into segments of at most
@@ -83,7 +83,7 @@ function convertedPage(text, offset, limit) {
         diagnostics.push({ severity: 'info', code: 'truncated', message: `Showing lines ${start + 1}-${end} of ${total}${byBytes ? ` (${MAX_BYTES / 1024}KB limit)` : ''}. Use offset=${end + 1} to continue.` });
     else if (end < total)
         diagnostics.push({ severity: 'info', message: `${total - end} more lines in file. Use offset=${end + 1} to continue.` });
-    return { content: shownText === '' ? [] : [{ type: 'text', text: shownText }], diagnostics };
+    return { output: shownText === '' ? [] : [{ type: 'text', text: shownText }], diagnostics };
 }
 /** Pi's `read`, extended to convert PDF, office and image files through the host's converter. An extension to select (after the extension that registers `read`, before the file guard). */
 export function createConvertingRead(options = {}) {

package/dist/file-guard.js

@@ -16,7 +16,7 @@ export const recordRevision = (api, key, revision, context) => api.commit(async
     const doc = await tx.doc(lastReadRevisions, api.conversationId);
     doc.revisions[key] = revision;
 }, context);
-const refusal = (text) => ({ content: [{ type: 'text', text }], isError: true });
+const refusal = (text) => ({ output: [{ type: 'text', text }], isError: true });
 // The same normalisation as Pi's tool paths: a leading "@" and special spaces.
 const normalised = (path) => { const spaced = path.replace(/[  -   　]/g, ' '); return spaced.startsWith('@') ? spaced.slice(1) : spaced; };
 /** `path` as the call's env names it, and relative to `root`, or undefined when it is not lexically inside `root` (or the call has no env). Pi's path normalisation applies. */

package/dist/git.js

@@ -38,7 +38,7 @@ export function createGitTool(repository) {
             const resolved = repository === undefined ? await workspaceFor(undefined, api, context) : undefined;
             const selected = repository ?? (resolved && 'binding' in resolved ? resolved.binding.repository : undefined);
             if (selected === undefined)
-                return { content: [{ type: 'text', text: 'This conversation has no working repository.' }], isError: true };
+                return { output: [{ type: 'text', text: 'This conversation has no working repository.' }], isError: true };
             const signal = context.abortSignal;
             let value;
             switch (args.operation) {
@@ -73,7 +73,7 @@ export function createGitTool(repository) {
                     value = (await selected.diff(args.before, args.after, signal)).map(change => ({ path: change.path, before: readable(change.before), after: readable(change.after) }));
                     break;
             }
-            return { content: [{ type: 'text', text: JSON.stringify({ operation: args.operation, value: value ?? null }) }] };
+            return { output: [{ type: 'text', text: JSON.stringify({ operation: args.operation, value: value ?? null }) }] };
         },
     });
 }

package/dist/memory/optchat.js

@@ -340,7 +340,7 @@ export function createOptChatMemory(options) {
         }
     }
     // ---- The extension -----------------------------------------------------------------------------------------------------
-    const text = (value) => ({ content: [{ type: 'text', text: value }] });
+    const text = (value) => ({ output: [{ type: 'text', text: value }] });
     const zoomTool = defineTool({
         name: 'zoom',
         description: 'Open the line id+n of the view into the two lines of n/2 under it; n = 1 gives the message whole.',

package/dist/native-version.d.ts

@@ -3,7 +3,7 @@
  * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
  * readable, because the native conversation and tool shapes they refer to did not change between them.
  */
-export declare const NATIVE_VERSION = "pi-durable@1.1.0";
-export type NativeVersion = 'pi-durable@1.0.1' | typeof NATIVE_VERSION;
+export declare const NATIVE_VERSION = "pi-durable@1.2.0";
+export type NativeVersion = 'pi-durable@1.0.1' | 'pi-durable@1.1.0' | typeof NATIVE_VERSION;
 export declare const isNativeVersion: (value: unknown) => value is NativeVersion;
 //# sourceMappingURL=native-version.d.ts.map

package/dist/native-version.js

@@ -3,5 +3,5 @@
  * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
  * readable, because the native conversation and tool shapes they refer to did not change between them.
  */
-export const NATIVE_VERSION = 'pi-durable@1.1.0';
-export const isNativeVersion = (value) => value === NATIVE_VERSION || value === 'pi-durable@1.0.1';
+export const NATIVE_VERSION = 'pi-durable@1.2.0';
+export const isNativeVersion = (value) => value === NATIVE_VERSION || value === 'pi-durable@1.1.0' || value === 'pi-durable@1.0.1';

package/dist/sandbox.js

@@ -21,7 +21,7 @@ const recorded = (tool, simulate) => ({
     ...tool,
     replay: 'safe',
     execute: async (args) => ({
-        content: [{ type: 'text', text: simulate(tool.name, args) }],
+        output: [{ type: 'text', text: simulate(tool.name, args) }],
         details: { [SANDBOX_DETAILS]: { simulated: true, tool: tool.name, arguments: args } },
     }),
 });

package/dist/self-evolving.js

@@ -40,14 +40,14 @@ export function agentInstructionsSection() {
 /** Runs `run` through the conversation's environment with the arguments as one line of JSON on stdin; the output is the result. */
 async function runTool(description, env, args, context) {
     if (env === undefined || typeof env.exec !== 'function')
-        return { content: [{ type: 'text', text: `${description.name} cannot run: this conversation has no execution environment.` }], isError: true };
+        return { output: [{ type: 'text', text: `${description.name} cannot run: this conversation has no execution environment.` }], isError: true };
     let output = '';
     const command = `{ ${description.run}\n} <<'${ARGS_END}'\n${JSON.stringify(args ?? {})}\n${ARGS_END}`;
     const result = await env.exec(command, { onOutput: text => { output += text; } }, context);
     if (!result.ok)
-        return { content: [{ type: 'text', text: `${description.name} failed: ${result.error.message}${output ? `\n${output}` : ''}` }], isError: true };
+        return { output: [{ type: 'text', text: `${description.name} failed: ${result.error.message}${output ? `\n${output}` : ''}` }], isError: true };
     const failed = result.value.exitCode !== 0;
-    return { content: [{ type: 'text', text: output || '(no output)' }], ...(failed ? { isError: true, diagnostics: [{ severity: 'error', message: `${description.run} exited with code ${result.value.exitCode}` }] } : {}) };
+    return { output: [{ type: 'text', text: output || '(no output)' }], ...(failed ? { isError: true, diagnostics: [{ severity: 'error', message: `${description.run} exited with code ${result.value.exitCode}` }] } : {}) };
 }
 /** The Harness validates each call's arguments against the agent-written schema before `run` starts (see `jsonSchemaTool`). */
 function toolOf(description) {
@@ -121,7 +121,7 @@ export function createSelfEvolution(options) {
         executionMode: 'sequential',
         execute: async (_args, api, context) => {
             const report = await reload(api.env, context);
-            return { content: [{ type: 'text', text: report.text }], details: JSON.parse(JSON.stringify(report)) };
+            return { output: [{ type: 'text', text: report.text }], details: JSON.parse(JSON.stringify(report)) };
         },
     });
     const section = agentInstructionsSection();

package/dist/skills.js

@@ -44,7 +44,7 @@ export function createSkillsExtension(name, skills) {
                 replay: 'safe',
                 execute: async (args) => {
                     const skill = known.get(args.name);
-                    return { content: [{ type: 'text', text: skill ? skill.body : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
+                    return { output: [{ type: 'text', text: skill ? skill.body : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
                 },
             })],
     });

package/dist/tool-evidence.js

@@ -19,6 +19,8 @@ async function ownedBy(tx, id, owner) {
     }
     return false;
 }
+// A completed v1 tool task keeps version 1 and its untagged `{ assistant, callId }` input after the upgrade; v2 model tasks are tagged.
+const modelTaskShape = (version, input) => version === 1 || (version === ToolTask.definition.version && object(input) && input.kind === 'model');
 export async function readToolEvidence(harness, owner, ids, context) {
     return harness.commit(async (tx) => {
         const evidence = [];
@@ -27,7 +29,7 @@ export async function readToolEvidence(harness, owner, ids, context) {
             if (!entry?.byTaskId || entry.model?.length !== 1)
                 throw new Error('Missing native tool result');
             const task = await tx.task(entry.byTaskId);
-            if (!task || task.kind !== ToolTask.definition.name || task.version !== ToolTask.definition.version
+            if (!task || task.kind !== ToolTask.definition.name || !modelTaskShape(task.version, task.input)
                 || task.conversationId !== entry.conversationId || task.state.status !== 'terminal'
                 || task.state.outcome.status !== 'completed' || !object(task.state.outcome.result)
                 || task.state.outcome.result.entryId !== id || !object(task.input)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -136,11 +136,11 @@
     }
   },
   "peerDependencies": {
-    "@earendil-works/pi-durable": "~1.1.0",
-    "@earendil-works/pi-ai": "~1.1.0",
-    "@earendil-works/chord": "~1.1.0",
-    "@hachej/boring-files": "^0.2.5",
-    "@hachej/boring-ui-kit": "^0.2.5"
+    "@earendil-works/pi-durable": "~1.2.0",
+    "@earendil-works/pi-ai": "~1.2.0",
+    "@earendil-works/chord": "~1.2.0",
+    "@hachej/boring-files": "^0.3.1",
+    "@hachej/boring-ui-kit": "^0.3.1"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {