@hachej/boring-agent 0.2.2 → 0.2.4

package/README.md

@@ -56,7 +56,7 @@ Limits: a run is admitted against its hold, not stopped mid-run (no per-call fen
 
 ## Artifacts
 
-`createPresentTool({ workspace, resolveAccess?, maxBytes? })` from `@hachej/boring-agent/artifacts` returns the native `present(path)` tool (its workspace resolved per call like the guard's): the agent writes a workspace file with its ordinary file tools and presents it, and the chat shows a card that points at that file (`target`, the revision shown, no `id` or `ordinal`). The file's versions are the history of the workspace provider (`@hachej/boring-files/workspace`, whose `keep` retains the presented revision); a card of an older revision pins it and a card of the newest follows the file as it changes. The tool writes nothing and refuses files that are missing, not UTF-8 text or larger than 256 KiB. How to use it is in the tool's own description, so a host does not repeat it in its prompt: substantial output goes to a file that is then presented, short answers (and anything asked for in the chat) stay in the chat, and a revision re-reads the file, changes it at the same path and presents it again. A host adds only what is its own, such as what its HTML preview allows.
+`createPresentTool({ workspace, resolveAccess?, maxBytes? })` from `@hachej/boring-agent/artifacts` returns the native `present(path)` tool (its workspace resolved per call like the guard's): the agent writes a workspace file with its ordinary file tools and presents it, and the chat shows a card that points at that file (`target`, the revision shown, no `id` or `ordinal`). The file's versions are the history of the workspace provider (`@hachej/boring-files/workspace`, whose `keep` retains the presented revision); a card of an older revision pins it and a card of the newest follows the file as it changes. The tool writes nothing and refuses files that are missing, not UTF-8 text or larger than 256 KiB. An opt-in `ack: { timeoutMs?, viewers? }` makes `present` wait until a page has mounted the presented revision: the page answers `{ kind: 'opened', instanceId, path, revision }` or `{ kind: 'refused', reason }` through the chat's `answer` (the transport's `?op=answer`), and the result carries `opened: true` with `viewer`, `opened: false` with `refused` (for example `closed by user`), `opened: 'unconfirmed'` after `timeoutMs` (default 15 s) or `opened: false, viewer: 'none'` at once when `viewers()` says no page watches the conversation. The wait is the durable wait of `ask_user` (`packages/agent/src/view-open.ts`, a conversation document keyed by the call); the deadline is stored, so a restart cannot extend it, and the first valid answer wins. Without `ack` the result is unchanged. `answerViewOpen` settles an answer; the host chains it with `answerUserQuestion` and `answerBrowserTask` in its `answer` handler. How to use it is in the tool's own description, so a host does not repeat it in its prompt: substantial output goes to a file that is then presented, short answers (and anything asked for in the chat) stay in the chat, and a revision re-reads the file, changes it at the same path and presents it again. A host adds only what is its own, such as what its HTML preview allows.
 
 `workspaceMentionReader(files, access, { maxReadBytes? })` is the reader for a host with a workspace provider: it reads the person's own published view through the provider (the access check the file viewers use) and has no containment check of its own. A host that has no provider has no reader here; it writes a `MentionReader` over whatever it does have.
 
@@ -72,6 +72,8 @@ 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.
+
 `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.
 
 Code mode: gated tools are native tools and must not be exposed to a code-mode sandbox, whose nested calls cannot reach a person. Give `run_code` the read tools only and send changes through the gated native tool. `isApprovalGated(tool)` lets a host filter automatically.
@@ -132,6 +134,8 @@ Choose the seam by how the text changes and who should see it:
 
 Failure is fail-open and Pi's: a throwing `context` is reported through `HarnessOptions.onReport` and the request goes out without the context (Pi's `hooks.each`, scheduler.js). An aborted turn rethrows. This is advisory text, not policy or authorization; do not use it to enforce a decision. The text is sent to the model provider and gateways or telemetry that log request bodies may see it; the model can quote it into a stored assistant message. Compaction summarizes the stored transcript only, so the context is not folded into summaries. After a crash the hook runs again at recovery, so the value is fresh per attempt, not replayed. Placement: before the round's question when that is the last message; after tool results or an assistant continuation, at the tail. Tests: `test/packages/agent-prompt-context.test.mjs`.
 
+Screen context: a browser can send what the person is looking at with each submit. `createRemoteChat({ requestContext })` adds the returned plain object to the submit body as `context`. In `ChatTransportAccess`, `requestContext(value)` receives it after validation and before `conversation.submit`; a value that is not a plain JSON object of at most 4 KB is `400 invalid-request`, and a host without `requestContext` ignores the field. The host stores `context` by conversation id in `requestContext` and renders it in `createPromptContext({ context })`; the transport keeps nothing. Tests: `test/packages/agent-chat-transport-context.test.mjs`, `test/packages/ui-remote-chat-context.test.mjs`.
+
 ## Native questions
 
 `createQuestions` from `@hachej/boring-agent/questions` exposes a native task, session document family and extension. Install the extension explicitly. Call `admit(tx, question, ownership, context)` in a native commit to persist a single-choice question and its task together. `resolve` and `consume` take the caller's native transaction so host writes can share that atomic commit. Call them before host table writes: native task reads after a table write are unavailable and the operation returns conflict. Host authentication and current subject/policy checks run at both boundaries. A resolved answer is clarification, never publication permission.

package/dist/artifacts.d.ts

@@ -3,6 +3,9 @@ import { Type } from '@earendil-works/pi-ai';
 import type { Context } from '@earendil-works/chord';
 import type { ResourceAccess, ResourceLocator } from '@hachej/boring-files';
 import type { WorkspaceBinding, WorkspaceResolver } from './workspaces.js';
+import type { ViewOpenOptions } from './view-open.js';
+export { answerViewOpen, parseViewOpenAnswer, VIEW_OPEN_TIMEOUT_MS } from './view-open.js';
+export type { ViewOpenAnswer, ViewOpenOptions, ViewOpenOutcome } from './view-open.js';
 export declare const ARTIFACT_TYPES: readonly ["markdown", "html", "svg", "code", "canvas"];
 export type ArtifactType = typeof ARTIFACT_TYPES[number];
 /**
@@ -42,6 +45,12 @@ export interface PresentToolOptions {
     readonly resolveAccess?: (api: ToolExecutionApi, context: Context) => ResourceAccess | Promise<ResourceAccess>;
     /** Largest file shown, in bytes. Defaults to 256 KiB. */
     readonly maxBytes?: number;
+    /**
+     * Opt-in: wait until a page has mounted the presented revision (`answerViewOpen`, the chat transport's `?op=answer`) and report
+     * `opened`, `refused`, `unconfirmed` (no answer in time) or `viewer: 'none'` (no page watches the conversation). Absent: the result
+     * is the file kept, as before, with no wait.
+     */
+    readonly ack?: ViewOpenOptions;
 }
 /**
  * `present(path)`: show a workspace file to the person as a card and a side panel. The agent writes the file with its ordinary file

package/dist/artifacts.js

@@ -2,6 +2,8 @@ import { defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
 import { workspacePath } from '@hachej/boring-files/file-types';
 import { asWorkspaceResolver, workspaceFor } from './workspaces.js';
+import { PRESENT_TOOL, awaitViewOpen } from './view-open.js';
+export { answerViewOpen, parseViewOpenAnswer, VIEW_OPEN_TIMEOUT_MS } from './view-open.js';
 /*
  * Artifacts: substantial, self-contained content (a document, an HTML page, an SVG, code) that a chat shows as a card
  * and a side panel instead of a wall of text. An artifact is a file of the workspace: the agent writes it with its ordinary
@@ -78,6 +80,15 @@ const PRESENTED = Object.assign(Object.create(null), {
     svg: { type: 'svg', mediaType: 'image/svg+xml' }, tldraw: { type: 'canvas', mediaType: 'application/vnd.tldraw+json' },
 });
 const LANGUAGE_OF = Object.assign(Object.create(null), { js: 'javascript', mjs: 'javascript', ts: 'typescript', py: 'python', json: 'json', css: 'css', sql: 'sql', yaml: 'yaml', yml: 'yaml', sh: 'shell', rs: 'rust', go: 'go', java: 'java', csv: 'csv' });
+/** The `present` result fields for a view outcome (see ./view-open.ts): `opened` true, false (refused or no viewer) or 'unconfirmed'. */
+function viewFields(outcome) {
+    switch (outcome.kind) {
+        case 'opened': return { opened: true, viewer: outcome.viewer };
+        case 'refused': return { opened: false, refused: outcome.reason };
+        case 'unconfirmed': return { opened: 'unconfirmed', timeoutMs: outcome.timeoutMs };
+        case 'none': return { opened: false, viewer: 'none' };
+    }
+}
 /**
  * `present(path)`: show a workspace file to the person as a card and a side panel. The agent writes the file with its ordinary file
  * tools first. The card points at the file; the file's history (the provider's) is its list of versions. Nothing is written here.
@@ -86,7 +97,7 @@ export function createPresentTool(options = {}) {
     const resolver = asWorkspaceResolver(options.workspace);
     const maxBytes = options.maxBytes ?? 256 * 1024;
     return defineTool({
-        name: 'present',
+        name: PRESENT_TOOL,
         // How to use it travels with the tool, so every host that offers `present` gets the same rules without repeating them in its prompt.
         description: [
             'Show a file of the workspace to the person in a side panel instead of pasting it in your reply.',
@@ -126,9 +137,13 @@ export function createPresentTool(options = {}) {
             const kept = await files.keep(path, access);
             if (kept.kind !== 'available')
                 return reply(kept);
-            const artifact = createArtifactDescriptor({ title: path.slice(path.lastIndexOf('/') + 1), type: kind.type, mediaType: kind.mediaType, ...(kind.language ? { language: kind.language } : {}),
-                target, revision: kept.snapshot.ref.revision });
-            return reply({ kind: 'presented', artifact });
+            const describe = (revision) => createArtifactDescriptor({ title: path.slice(path.lastIndexOf('/') + 1), type: kind.type, mediaType: kind.mediaType,
+                ...(kind.language ? { language: kind.language } : {}), target, revision });
+            if (!options.ack)
+                return reply({ kind: 'presented', artifact: describe(kept.snapshot.ref.revision) });
+            // A replay reports the revision the call recorded (and the page acknowledged), even if the file has changed since.
+            const { outcome, revision } = await awaitViewOpen(api, context, { tool: PRESENT_TOOL, path, revision: kept.snapshot.ref.revision }, options.ack);
+            return reply({ kind: 'presented', artifact: describe(revision), ...viewFields(outcome) });
         },
     });
 }

package/dist/chat-transport.d.ts

@@ -5,6 +5,7 @@ export declare const CHAT_TRANSPORT: Readonly<{
     schema: "boring.chat-transport";
     version: 1;
     maxRequestBytes: 8388608;
+    maxContextBytes: 4096;
     maxHistoryPage: 200;
     maxPendingFrames: 100;
     heartbeatMs: 15000;
@@ -47,6 +48,13 @@ export interface ChatTransportAccess {
      * scopes the id to this conversation. Without it `?op=withdraw` is not supported. This handler never edits the inbox.
      */
     readonly abortSubmission?: (id: SubmissionId) => Promise<'aborted' | 'already_placed' | 'settled' | 'not_found'>;
+    /**
+     * Receive the screen context a browser sent with a submit (`context`, from `createRemoteChat({ requestContext })`), called after
+     * the request is validated and admitted and before `conversation.submit`. The value is a plain JSON object of at most
+     * `CHAT_TRANSPORT.maxContextBytes`; anything else is `400 invalid-request`. The host stores it by conversation id and renders
+     * it in `createPromptContext({ context })`; this handler keeps nothing. Without it the `context` field is ignored.
+     */
+    readonly requestContext?: (value: Readonly<Record<string, unknown>>) => void | Promise<void>;
     /** Refuse an effect call. Reading stays governed by `authenticate` and `project`. */
     readonly allow?: (operation: 'submit' | 'abort' | 'answer' | 'withdraw' | 'configure') => boolean | Promise<boolean>;
 }

package/dist/chat-transport.js

@@ -1,6 +1,6 @@
 import { RequestGuardError, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
 /** Wire protocol shared with the browser client in `@hachej/boring-ui-kit/remote-chat`. */
-export const CHAT_TRANSPORT = Object.freeze({ schema: 'boring.chat-transport', version: 1, maxRequestBytes: 8_388_608, maxHistoryPage: 200, maxPendingFrames: 100, heartbeatMs: 15_000 });
+export const CHAT_TRANSPORT = Object.freeze({ schema: 'boring.chat-transport', version: 1, maxRequestBytes: 8_388_608, maxContextBytes: 4096, maxHistoryPage: 200, maxPendingFrames: 100, heartbeatMs: 15_000 });
 /** `no-transform` keeps proxies from compressing or rewriting responses; the watch stream adds `x-accel-buffering: no` so nginx does not buffer it. */
 const headers = { 'cache-control': 'no-store, no-transform', 'x-content-type-options': 'nosniff' };
 const failure = (status, reason) => Response.json({ schema: CHAT_TRANSPORT.schema, version: CHAT_TRANSPORT.version, reason }, { status, headers });
@@ -12,6 +12,14 @@ function content(value) {
     return Array.isArray(value) && value.length > 0 && value.every(part => part !== null && typeof part === 'object'
         && ((part.type === 'text' && typeof part.text === 'string') || (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string')));
 }
+/** The submit `context` field: absent, or a plain JSON object of at most `maxContextBytes` once serialized. */
+function contextValue(value) {
+    if (value === undefined)
+        return true;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return encoder.encode(JSON.stringify(value)).length <= CHAT_TRANSPORT.maxContextBytes;
+}
 async function body(request) {
     const value = await readJsonBody(request, CHAT_TRANSPORT.maxRequestBytes, request.signal);
     if (value === null || typeof value !== 'object' || Array.isArray(value))
@@ -207,7 +215,8 @@ export function createChatTransportHandler(options) {
             if (request.method === 'POST' && operation === 'submit') {
                 const input = await body(request);
                 if (typeof input['requestId'] !== 'string' || !input['requestId'] || !content(input['content'])
-                    || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string'))
+                    || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string')
+                    || (access.requestContext && !contextValue(input['context'])))
                     return failure(400, 'invalid-request');
                 let prepared = input['content'];
                 if (access.prepareInput) {
@@ -218,6 +227,10 @@ export function createChatTransportHandler(options) {
                 }
                 if (!await allowed('submit') || access.revoked?.aborted)
                     return failure(403, 'not-authorized');
+                if (access.requestContext && input['context'] !== undefined)
+                    await access.requestContext(input['context']);
+                if (access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
                 const submission = await conversation.submit({ type: 'input', requestId: input['requestId'], content: prepared,
                     ...(input['whenBusy'] === undefined ? {} : { whenBusy: input['whenBusy'] }) }, context);
                 return json({ submissionId: submission.id });

package/dist/durable-wait.d.ts

@@ -15,9 +15,18 @@ export interface CallBinding {
 export declare function callBinding(tx: Tx, conversation: Conversation, id: string): Promise<CallBinding>;
 /** The binding key of the calling tool task (its assistant entry and call id). */
 export declare function ownBindingKey(tx: Tx, api: Pick<ToolExecutionApi, 'taskId' | 'callId'>): Promise<string>;
+/**
+ * A deadline on the wait (ms since the epoch): at `at`, `expire` settles the document in a background commit and returns its value.
+ * It is stored state, so a re-attached wait keeps the same `at`.
+ */
+export interface WaitDeadline<T> {
+    readonly at: number;
+    readonly expire: (tx: Tx) => Promise<Readonly<T> | null | undefined>;
+}
 /**
  * Waits until `settled(value)` holds for the document `key` of `family`, without holding a model request. When the call is aborted,
  * `cancel` runs in a background commit (`label` names the waiting thing in errors) (the answer path also refuses a call whose task has ended) and the abort is rethrown.
+ * With a `deadline`, the wait ends when `expire` has settled the document (the value it returns is the result).
  */
-export declare function waitForDocument<T extends JsonObject>(api: ToolExecutionApi, family: ConversationDocFamilyToken<T, null>, key: string, context: Context, settled: (value: Readonly<T> | null | undefined) => boolean, cancel: (tx: Tx) => Promise<void>, label: string): Promise<Readonly<T> | null | undefined>;
+export declare function waitForDocument<T extends JsonObject>(api: ToolExecutionApi, family: ConversationDocFamilyToken<T, null>, key: string, context: Context, settled: (value: Readonly<T> | null | undefined) => boolean, cancel: (tx: Tx) => Promise<void>, label: string, deadline?: WaitDeadline<T>): Promise<Readonly<T> | null | undefined>;
 //# sourceMappingURL=durable-wait.d.ts.map

package/dist/durable-wait.js

@@ -44,13 +44,15 @@ export async function ownBindingKey(tx, api) {
 /**
  * Waits until `settled(value)` holds for the document `key` of `family`, without holding a model request. When the call is aborted,
  * `cancel` runs in a background commit (`label` names the waiting thing in errors) (the answer path also refuses a call whose task has ended) and the abort is rethrown.
+ * With a `deadline`, the wait ends when `expire` has settled the document (the value it returns is the result).
  */
-export async function waitForDocument(api, family, key, context, settled, cancel, label) {
+export async function waitForDocument(api, family, key, context, settled, cancel, label, deadline) {
     const watch = await api.watchDoc(family, api.conversationId, key, context);
     if (!watch)
         throw new Error(`${label} record is missing`);
     const signal = context.abortSignal;
     let final = watch.value;
+    let timer;
     try {
         if (!settled(final)) {
             final = await new Promise((resolve, reject) => {
@@ -58,6 +60,8 @@ export async function waitForDocument(api, family, key, context, settled, cancel
                     return reject(signal.reason ?? new Error(`${label} cancelled`));
                 signal?.addEventListener('abort', () => reject(signal.reason ?? new Error(`${label} cancelled`)), { once: true });
                 void watch.closed.then(() => reject(new Error(`${label} observation closed`)));
+                if (deadline)
+                    timer = setTimeout(() => { void api.commit(deadline.expire, BACKGROUND_CONTEXT).then(value => resolve(value), reject); }, Math.max(0, deadline.at - Date.now()));
                 watch.start(async (value) => { if (settled(value))
                     resolve(value); });
             });
@@ -73,6 +77,7 @@ export async function waitForDocument(api, family, key, context, settled, cancel
         throw error;
     }
     finally {
+        clearTimeout(timer);
         await watch.stop();
     }
     return final;

package/dist/sandbox.d.ts

@@ -0,0 +1,61 @@
+import type { Extension } from '@earendil-works/pi-durable';
+import type { JsonValue } from '@earendil-works/chord';
+/** Key under a recorded call's result details: `{ simulated: true, tool, arguments }`. A caller reads it back with `simulatedCalls`. */
+export declare const SANDBOX_DETAILS = "boring.sandbox";
+/** What the host declares about one tool. An unset field is not declared: a call is recorded unless the host declares it safe. */
+export interface SandboxFlags {
+    readonly mutates?: boolean;
+    readonly writes?: boolean;
+    readonly sandboxSafe?: boolean;
+}
+export interface SandboxOptions {
+    /** Native extension name. Default `boring.sandbox`. */
+    readonly name?: string;
+    /** Every tool this sandbox covers. A call to any other name is blocked, including a tool added to the run later. */
+    readonly tools: readonly string[];
+    /** Host flags per tool name (for example the app's tools.json). */
+    readonly flags?: Readonly<Record<string, SandboxFlags>>;
+    /** The text the model receives for a recorded call. Default: `defaultAck`. */
+    readonly simulate?: (toolName: string, args: JsonValue) => string;
+}
+/** The acknowledgement a recorded call returns when the host does not supply its own. */
+export declare const defaultAck: (toolName: string) => string;
+/** `run` only when the host declares the tool safe (`sandboxSafe`, or `mutates: false` / `writes: false`). Any mutating flag records. */
+export declare function sandboxDecision(flags: SandboxFlags | undefined): 'run' | 'record';
+/** One call the sandbox recorded instead of running. */
+export interface SimulatedCall {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly arguments: JsonValue;
+}
+/** The recorded calls among a conversation's tool results, in order (the results' `details` carry the record). */
+export declare function simulatedCalls(results: readonly {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly details?: unknown;
+}[]): SimulatedCall[];
+/**
+ * A native extension that makes the named tools fail closed in a sandbox. Its wraps replace each tool the host flags as
+ * mutating (or does not declare safe) with a recorder, so the call is never executed and the model gets an acknowledgement.
+ * Its `beforeTool` hook blocks every call whose name is not in `tools`, so a tool added mid-run (or another extension's)
+ * cannot run unnamed. It brings no tools and changes nothing unless a conversation selects it: include it in the full
+ * selected list and apply that list with `configure({ extensions: selected })`. (`add` keeps the defaults' positions, so it
+ * does not give the effective order.)
+ *
+ * Composition limit (owned by the host): the sandbox must be the last wrap of each recorded tool. A wrap selected after it
+ * replaces the recorder's `execute`, and the replaced call runs for real. Pi 1.1 exposes no public seam that tells the
+ * executing phase which composed tool it runs, so this module cannot verify the order at call time. Use
+ * `assertSandboxLast` at setup, over the COMPLETE selected list (the array passed to `configure({ extensions: selected })`, or
+ * the effective list of a `defineAgent`), not over an `add` list. The upstream request is in
+ * docs/upstream/pi-hookapi-composed-tool.md.
+ */
+export declare function createSandboxExtension(options: SandboxOptions): Extension;
+/**
+ * Setup-time check over the public `Extension.wraps` shape. Throws when an extension selected after `sandbox` wraps a tool the
+ * sandbox records, because that wrap would replace the recorder. `selected` must be the COMPLETE effective list, in the order
+ * the conversation applies it (the same array passed to `configure({ extensions: selected })`). A partial `add` list
+ * does not show the effective order, because defaults keep their positions. It is a host check, not a Harness guard:
+ * nothing in Pi calls it, so the host must call it wherever it composes that list.
+ */
+export declare function assertSandboxLast(selected: readonly Extension[], sandbox: Extension): void;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -0,0 +1,75 @@
+import { defineExtension, hook, ToolTask } from '@earendil-works/pi-durable';
+/** Key under a recorded call's result details: `{ simulated: true, tool, arguments }`. A caller reads it back with `simulatedCalls`. */
+export const SANDBOX_DETAILS = 'boring.sandbox';
+/** The acknowledgement a recorded call returns when the host does not supply its own. */
+export const defaultAck = (toolName) => `Simulated: ${toolName} was recorded and not run. Nothing was changed.`;
+/** `run` only when the host declares the tool safe (`sandboxSafe`, or `mutates: false` / `writes: false`). Any mutating flag records. */
+export function sandboxDecision(flags) {
+    if (flags?.mutates === true || flags?.writes === true)
+        return 'record';
+    return flags?.sandboxSafe === true || flags?.mutates === false || flags?.writes === false ? 'run' : 'record';
+}
+/** The recorded calls among a conversation's tool results, in order (the results' `details` carry the record). */
+export function simulatedCalls(results) {
+    return results.flatMap(result => {
+        const record = result.details?.[SANDBOX_DETAILS];
+        return record?.simulated === true ? [{ toolCallId: result.toolCallId, toolName: result.toolName, arguments: record.arguments ?? null }] : [];
+    });
+}
+/** A tool that never runs: it returns the acknowledgement and records the call in its result details. Replay-safe, as nothing executes. */
+const recorded = (tool, simulate) => ({
+    ...tool,
+    replay: 'safe',
+    execute: async (args) => ({
+        content: [{ type: 'text', text: simulate(tool.name, args) }],
+        details: { [SANDBOX_DETAILS]: { simulated: true, tool: tool.name, arguments: args } },
+    }),
+});
+/**
+ * A native extension that makes the named tools fail closed in a sandbox. Its wraps replace each tool the host flags as
+ * mutating (or does not declare safe) with a recorder, so the call is never executed and the model gets an acknowledgement.
+ * Its `beforeTool` hook blocks every call whose name is not in `tools`, so a tool added mid-run (or another extension's)
+ * cannot run unnamed. It brings no tools and changes nothing unless a conversation selects it: include it in the full
+ * selected list and apply that list with `configure({ extensions: selected })`. (`add` keeps the defaults' positions, so it
+ * does not give the effective order.)
+ *
+ * Composition limit (owned by the host): the sandbox must be the last wrap of each recorded tool. A wrap selected after it
+ * replaces the recorder's `execute`, and the replaced call runs for real. Pi 1.1 exposes no public seam that tells the
+ * executing phase which composed tool it runs, so this module cannot verify the order at call time. Use
+ * `assertSandboxLast` at setup, over the COMPLETE selected list (the array passed to `configure({ extensions: selected })`, or
+ * the effective list of a `defineAgent`), not over an `add` list. The upstream request is in
+ * docs/upstream/pi-hookapi-composed-tool.md.
+ */
+export function createSandboxExtension(options) {
+    const covered = new Set(options.tools);
+    const recordOnly = new Set(options.tools.filter(name => sandboxDecision(options.flags?.[name]) === 'record'));
+    const simulate = options.simulate ?? ((toolName) => defaultAck(toolName));
+    const wraps = [...recordOnly].map(name => ({ tool: name, wrap: (tool) => recorded(tool, simulate) }));
+    return defineExtension({
+        name: options.name ?? 'boring.sandbox',
+        wraps,
+        hooks: [hook(ToolTask, {
+                beforeTool: call => covered.has(call.name) ? undefined : { block: `Not run: ${call.name} is not covered by the sandbox.` },
+            })],
+    });
+}
+/**
+ * Setup-time check over the public `Extension.wraps` shape. Throws when an extension selected after `sandbox` wraps a tool the
+ * sandbox records, because that wrap would replace the recorder. `selected` must be the COMPLETE effective list, in the order
+ * the conversation applies it (the same array passed to `configure({ extensions: selected })`). A partial `add` list
+ * does not show the effective order, because defaults keep their positions. It is a host check, not a Harness guard:
+ * nothing in Pi calls it, so the host must call it wherever it composes that list.
+ */
+export function assertSandboxLast(selected, sandbox) {
+    const at = selected.indexOf(sandbox);
+    if (at < 0)
+        return;
+    const recorded = new Set((sandbox.wraps ?? []).flatMap(wrap => 'tool' in wrap ? [wrap.tool] : []));
+    for (const later of selected.slice(at + 1)) {
+        for (const wrap of later.wraps ?? []) {
+            if ('tool' in wrap && recorded.has(wrap.tool)) {
+                throw new Error(`${later.name} wraps ${wrap.tool} after ${sandbox.name}; the sandbox must be the last wrap of each recorded tool.`);
+            }
+        }
+    }
+}

package/dist/view-open.d.ts

@@ -0,0 +1,63 @@
+import type { Conversation, ToolExecutionApi } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+import type { AskUserAnswer } from './ask-user.js';
+/** How long a view may take to be confirmed by a page before the result says `unconfirmed` (a UI ack, not a person's decision). */
+export declare const VIEW_OPEN_TIMEOUT_MS = 15000;
+/** The tool whose calls the view-open record belongs to, unless a host renamed `present`. */
+export declare const PRESENT_TOOL = "present";
+/** What the page reports after its panel mounted the revision, or that it refused to open it. */
+export type ViewOpenAnswer = {
+    readonly kind: 'opened';
+    readonly instanceId: string;
+    readonly path: string;
+    readonly revision: string;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+/** What `present` reports for the view: the result's `opened`, `refused` or `viewer` fields (see ./artifacts.ts). */
+export type ViewOpenOutcome = {
+    readonly kind: 'opened';
+    readonly viewer: string;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'unconfirmed';
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'none';
+};
+export interface ViewOpenOptions {
+    /** Default `VIEW_OPEN_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /** Whether a page watches this conversation. False: `none` at once, nothing is waited for. Absent: the timeout bounds the wait. */
+    readonly viewers?: (api: ToolExecutionApi, context: Context) => boolean | Promise<boolean>;
+}
+/** Strict shape of the page's answer. Returns undefined for anything else. */
+export declare function parseViewOpenAnswer(value: unknown): ViewOpenAnswer | undefined;
+/**
+ * Records the pending view of a `present` call, then waits for the page's acknowledgement or the deadline. The deadline is stored
+ * with the record, so a re-attached call (after a restart) keeps the time it started with. Abort cancels the record.
+ * Returns the revision the record holds: on a replay after the file changed, that is the revision that was acknowledged, not the
+ * current one, so the result never pairs a new file revision with an old acknowledgement.
+ */
+export declare function awaitViewOpen(api: ToolExecutionApi, context: Context, view: {
+    readonly tool: string;
+    readonly path: string;
+    readonly revision: string;
+}, options?: ViewOpenOptions): Promise<{
+    readonly outcome: ViewOpenOutcome;
+    readonly revision: string;
+}>;
+/**
+ * Settles a pending view with the page's answer (JSON text) after the host authenticated the person. `id` is the answer ID of the
+ * call (`[assistantEntryId, callId]`, or a raw call ID used by one task). An `opened` answer must name the path and revision the
+ * call recorded; the first valid answer wins, an identical repeat is idempotent, any other answer after that is `conflict`.
+ * Returns the `ask_user` outcome kinds, so one chat transport `answer` can serve questions, browser tasks and views.
+ */
+export declare function answerViewOpen(conversation: Conversation, id: string, answer: string, options?: {
+    readonly tool?: string;
+    readonly context?: Context;
+}): Promise<AskUserAnswer>;
+//# sourceMappingURL=view-open.d.ts.map

package/dist/view-open.js

@@ -0,0 +1,146 @@
+// The acknowledgement that a `present` call's file is on screen (the opt-in `ack` of `createPresentTool`, ./artifacts.ts). It is the
+// same durable wait as `ask_user` and browser tasks (./durable-wait.ts): a conversation document keyed by the call's
+// `[assistantEntryId, callId]` holds the pending view, the page answers after its panel has mounted the revision, and a stored
+// deadline ends the wait. It is a sibling of ./browser-task.ts, not a second channel: the page answers through the chat transport's
+// `?op=answer`. Presentation outcomes (`createPresentationTool`, ./presentation.ts) are a different contract and stay separate.
+import { defineDocFamily } from '@earendil-works/pi-durable';
+import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
+import { AmbiguousCall, UnknownCall, callBinding, ownBindingKey, waitForDocument } from './durable-wait.js';
+/** How long a view may take to be confirmed by a page before the result says `unconfirmed` (a UI ack, not a person's decision). */
+export const VIEW_OPEN_TIMEOUT_MS = 15_000;
+/** The tool whose calls the view-open record belongs to, unless a host renamed `present`. */
+export const PRESENT_TOOL = 'present';
+/** One member per assistant entry and tool call, in the calling conversation. */
+const documents = defineDocFamily({
+    kind: 'boring.view-open', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
+    initial: () => ({ view: null }),
+});
+const MAX_REASON = 200;
+const MAX_ID = 128;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Strict shape of the page's answer. Returns undefined for anything else. */
+export function parseViewOpenAnswer(value) {
+    if (!isObject(value))
+        return undefined;
+    if (value['kind'] === 'opened' && Object.keys(value).every(key => ['kind', 'instanceId', 'path', 'revision'].includes(key))) {
+        const { instanceId, path, revision } = value;
+        if (typeof instanceId !== 'string' || !instanceId || instanceId.length > MAX_ID)
+            return undefined;
+        if (typeof path !== 'string' || !path || path.length > 512)
+            return undefined;
+        if (typeof revision !== 'string' || !revision || revision.length > 256)
+            return undefined;
+        return { kind: 'opened', instanceId, path, revision };
+    }
+    if (value['kind'] === 'refused' && Object.keys(value).every(key => ['kind', 'reason'].includes(key))) {
+        const { reason } = value;
+        if (typeof reason !== 'string' || !reason || reason.length > MAX_REASON)
+            return undefined;
+        return { kind: 'refused', reason };
+    }
+    return undefined;
+}
+/**
+ * Records the pending view of a `present` call, then waits for the page's acknowledgement or the deadline. The deadline is stored
+ * with the record, so a re-attached call (after a restart) keeps the time it started with. Abort cancels the record.
+ * Returns the revision the record holds: on a replay after the file changed, that is the revision that was acknowledged, not the
+ * current one, so the result never pairs a new file revision with an old acknowledgement.
+ */
+export async function awaitViewOpen(api, context, view, options = {}) {
+    const timeoutMs = options.timeoutMs ?? VIEW_OPEN_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw new TypeError('The view-open timeout must be a positive integer of milliseconds');
+    if (options.viewers && !(await options.viewers(api, context)))
+        return { outcome: { kind: 'none' }, revision: view.revision };
+    const { key, startedAt, duration } = await api.commit(async (tx) => {
+        const key = await ownBindingKey(tx, api);
+        const document = await tx.doc(documents, api.conversationId, key, null);
+        if (!document.view)
+            document.view = { tool: view.tool, taskId: api.taskId, path: view.path, revision: view.revision, startedAt: Date.now(), timeoutMs, state: { kind: 'pending' } };
+        if (document.view.taskId !== api.taskId)
+            throw new Error('View-open identity belongs to another task');
+        return { key, startedAt: document.view.startedAt, duration: document.view.timeoutMs };
+    }, context);
+    const expire = async (tx) => {
+        const document = await tx.doc(documents, api.conversationId, key, null);
+        if (document.view?.state.kind === 'pending')
+            document.view.state = { kind: 'unconfirmed' };
+        return { view: document.view ? { ...document.view, state: { ...document.view.state } } : null };
+    };
+    const final = await waitForDocument(api, documents, key, context, value => value?.view?.state.kind !== 'pending', async (tx) => {
+        const document = await tx.doc(documents, api.conversationId, key, null);
+        if (document.view?.state.kind === 'pending')
+            document.view.state = { kind: 'cancelled' };
+    }, 'View open', { at: startedAt + duration, expire });
+    const state = final?.view?.state;
+    const revision = final?.view?.revision ?? view.revision;
+    if (state?.kind === 'opened')
+        return { outcome: { kind: 'opened', viewer: state.viewer }, revision };
+    if (state?.kind === 'refused')
+        return { outcome: { kind: 'refused', reason: state.reason }, revision };
+    if (state?.kind === 'unconfirmed')
+        return { outcome: { kind: 'unconfirmed', timeoutMs: duration }, revision };
+    throw new Error('View open cancelled');
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * Settles a pending view with the page's answer (JSON text) after the host authenticated the person. `id` is the answer ID of the
+ * call (`[assistantEntryId, callId]`, or a raw call ID used by one task). An `opened` answer must name the path and revision the
+ * call recorded; the first valid answer wins, an identical repeat is idempotent, any other answer after that is `conflict`.
+ * Returns the `ask_user` outcome kinds, so one chat transport `answer` can serve questions, browser tasks and views.
+ */
+export async function answerViewOpen(conversation, id, answer, options = {}) {
+    const tool = options.tool ?? PRESENT_TOOL;
+    if (typeof id !== 'string' || !id || id.length > 1024)
+        return { kind: 'unknown-question' };
+    if (typeof answer !== 'string' || answer.length > 4096)
+        return { kind: 'denied', reason: 'The answer must be JSON text of at most 4096 characters' };
+    let value;
+    try {
+        value = JSON.parse(answer);
+    }
+    catch {
+        return { kind: 'denied', reason: 'The answer is not JSON' };
+    }
+    const parsed = parseViewOpenAnswer(value);
+    if (!parsed)
+        return { kind: 'denied', reason: 'The answer must be { kind: "opened", instanceId, path, revision } or { kind: "refused", reason }' };
+    const next = parsed.kind === 'opened' ? { kind: 'opened', viewer: parsed.instanceId } : { kind: 'refused', reason: parsed.reason };
+    try {
+        return await conversation.commit(async (tx) => {
+            const binding = await callBinding(tx, conversation, id);
+            const task = await tx.task(binding.taskId);
+            if (!task)
+                return { kind: 'conflict', reason: 'The view is unavailable' };
+            const document = await tx.doc(documents, conversation.id, binding.key, null);
+            // Throwing rolls back the empty draft an unknown or foreign call would leave behind.
+            if (!document.view || document.view.tool !== tool)
+                throw new UnknownCall();
+            const record = document.view;
+            if (record.taskId !== task.id)
+                return { kind: 'conflict', reason: 'The view belongs to another task' };
+            if (record.state.kind !== 'pending')
+                return same(record.state, next) ? { kind: 'answered' } : { kind: 'conflict', reason: 'The view was already decided' };
+            if (task.abortRequested || task.state.status === 'terminal') {
+                record.state = { kind: 'cancelled' };
+                return { kind: 'conflict', reason: 'The view was cancelled' };
+            }
+            if (Date.now() >= record.startedAt + record.timeoutMs) {
+                record.state = { kind: 'unconfirmed' };
+                return { kind: 'conflict', reason: 'The view was not confirmed in time' };
+            }
+            if (parsed.kind === 'opened' && (parsed.path.replace(/^\.\//, '') !== record.path || parsed.revision !== record.revision)) {
+                return { kind: 'denied', reason: 'The acknowledgement names another file or revision than the one presented' };
+            }
+            record.state = next;
+            return { kind: 'answered' };
+        }, options.context ?? BACKGROUND_CONTEXT);
+    }
+    catch (error) {
+        if (error instanceof AmbiguousCall)
+            return { kind: 'conflict', reason: 'Use the assistant-entry-bound call ID' };
+        if (error instanceof UnknownCall)
+            return { kind: 'unknown-question' };
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -54,6 +54,10 @@
       "types": "./dist/file-convert.d.ts",
       "import": "./dist/file-convert.js"
     },
+    "./sandbox": {
+      "types": "./dist/sandbox.d.ts",
+      "import": "./dist/sandbox.js"
+    },
     "./file-types": {
       "types": "./dist/file-types.d.ts",
       "import": "./dist/file-types.js"
@@ -132,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.2",
-    "@hachej/boring-ui-kit": "^0.2.2"
+    "@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.4",
+    "@hachej/boring-ui-kit": "^0.2.4"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {