@hachej/boring-agent 0.4.8 → 0.4.10

package/README.md

@@ -58,6 +58,25 @@ Limits: a run is admitted against its hold, not stopped mid-run (no per-call fen
 
 `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.
 
+### A view that is not a document (a dashboard)
+
+A view the agent opens, such as a dashboard, is presented the same way: it is a small workspace file that names what to show (for example `sales.dashboard.json`), and the app registers an artifact kind that draws it. There is no second channel: the same `ack` answers for it. Mark the kind `waitsForReady: true` when its renderer loads asynchronously: the panel then reports the mount (and the page confirms the `present` call) only after the renderer calls `onReady` for the revision shown. `onFailed(reason)`, or a renderer that throws, refuses the call with that reason, and a renderer that never becomes ready leaves it `unconfirmed` at the deadline. A kind without `waitsForReady` is confirmed as soon as its file is read.
+
+```tsx
+// Server: the agent writes sales.dashboard.json, then calls present('sales.dashboard.json').
+createPresentTool({ workspace, ack: { timeoutMs: 15_000 } });
+// -> { kind: 'presented', artifact, opened: true, viewer } | { opened: false, refused: 'the sales query failed' } | { opened: 'unconfirmed', timeoutMs }
+
+// Page (pi-app block): the kind confirms the view only once its data has loaded.
+const dashboard: ArtifactKind = {
+  match: target => target.resource.path.endsWith('.dashboard.json'),
+  label: 'Dashboard',
+  waitsForReady: true,
+  renderer: ({ text, onReady, onFailed }) => <SalesDashboard spec={JSON.parse(text)} onLoaded={onReady} onError={error => onFailed?.(error.message)} />,
+};
+<AgentWorkspace {...workspace} artifactKinds={[dashboard]} />;
+```
+
 `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.
 
 The descriptor's `id` and `ordinal` are optional and `present` sets neither; `parseArtifact` validates a descriptor and has no Pi runtime dependency (the copied `pi-chat` registry item carries the same validator for the browser).
@@ -66,6 +85,20 @@ The descriptor's `id` and `ordinal` are optional and `present` sets neither; `pa
 
 `refreshAgentState({ conversations, agent, read, write, context })` from `@hachej/boring-agent/agents` brings existing conversations up to a changed deployment. A conversation keeps the agent it was created with, so when the agent's `instructions` or default `thinkingLevel` change, the helper calls `configure` on each conversation. The host stores a hash of `[instructions, thinkingLevel]` (`read()` returns the stored hash, `write(hash)` stores the new one); it configures nothing when the hash is unchanged and writes the new hash last, so a failed run is retried. It returns how many conversations were configured.
 
+### Add an extension to an existing conversation
+
+`addExtension(conversation, extension, context)` from `@hachej/boring-agent/agents` adds one Pi extension (for example `createApprovalExtension(...)` or one that registers a tool) to a conversation that already exists; its next turn runs with it. It edits the conversation's stored `pi.agent` selection in one native `Conversation.commit` (Pi's public `AgentDoc`): the name is appended to the conversation's own list, so it keeps its other extensions and picks up no other agent's, and the extension's tools are enabled and offered even when the conversation lists its tools. Adding it twice changes nothing; remove it with native `conversation.configure({ extensions: { remove: [extension] } }, context)`. Native `configure({ extensions: { add } })` is not the same: on a `defineAgent` conversation it replaces the stored list with an edit of the host default selection.
+
+```ts
+const registry = createRegistry();
+agent.install(registry);
+registry.install(approval); // at every Harness open: the conversation stores the name only
+const conversation = await harness.conversation(id, context);
+await addExtension(conversation, approval, context);
+```
+
+The selection is durable (it is in the conversation's Pi state and survives a reopen), but an extension is host code and is not stored: install it in the registry every time the Harness opens, or its name selects nothing. Installing it does not add it to other `defineAgent` conversations, whose lists are explicit; a conversation with no stored list (such as `harness.root()` without `agent`) follows the host default selection, which is every installed extension unless `HarnessSettings.extensions` names them.
+
 `createConvertingRead({ workspace?, resolveAccess?, convert?, cache?, maxBytes?, name? })` from `@hachej/boring-agent/file-convert` returns an extension that wraps Pi's native `read` (`wrapTool`); there is one `read`, and no second tool. Text goes to Pi's read untouched. A PDF, an office document or an image goes to the host's `convert({ name, mediaType, bytes })`, once per saved revision (cached by path and revision), and the converted text is paged the way Pi pages a text file: `offset` is the 1-based line to start at, `limit` a number of lines, a page ends at 2000 lines or 50 KB, and the note names the `offset` to continue from. What is text and what is not comes from one table, `fileKind` in `@hachej/boring-agent/file-types`, which looks at the extension and the leading bytes (Pi's read returns garbled text for a PDF, so a PDF is recognised by `%PDF-` even under another name); the mention resolver uses the same table. An archive or other binary file answers `unsupported` and is never converted; without `convert`, an image uses Pi's native behaviour and a PDF or office file answers `unsupported`. A line of converted text above 50 KB is split into 50 KB segments, each counted as one line, with a warning, so nothing is cut. The type is sniffed on the bytes the provider returns after its access check, and the converter is told the media type the file's signature names (a PDF named `.txt` arrives as `application/pdf`). The file is read through the workspace provider, so its access policy applies; a path the wrapper cannot place inside the workspace is left to the native read. Install it before `createFileGuard`, so the guard stays outermost and refuses anything outside the workspace first. `workersAiMarkdown(env.AI)` adapts a Workers AI `toMarkdown` binding to `convert` without a Cloudflare types dependency.
 
 ## Shared document readers
@@ -312,7 +345,18 @@ With self-evolution, workspace skills may be flat `.agent/skills/<name>.md` file
 
 These follow [Pi Durable on Cloudflare](https://earendil.com/posts/pi-durable-on-cloudflare/) and stay host-agnostic: a Node process and a Durable Object mount the same tools.
 
-**Delegate.** `createDelegateTool({ agent, name?, description? })` from `@hachej/boring-agent/agents` is Pi's documented subagent pattern (pi-durable README, "Abort and Subagents"; pi-durable ships it as an example, not an export) as a tool factory. `delegate({ task })` creates a child conversation owned by the calling tool task (`ownership: { kind: 'task', taskId }`), configured as the child agent alone (its extensions, model and instructions; the inherited tool filters reset), submits the task with request id `<name>:<taskId>` and returns only the child's final text, with `details.conversationId` naming the child. It is replay-safe: a rerun after a crash or eviction finds its child through Pi's ownership index (`scanConversations({ ownerTaskId })`) and its submission through the request id, so it never starts a second child or turn. Aborting the call aborts the child. With `defineAgent`, declare `delegates: [{ agent: researcher }]`: each becomes a tool of the agent and `install(registry)` installs the child's extensions as well. A raw-Pi host installs the child agent's extensions itself.
+**Delegate.** `createDelegateTool({ agent, name?, description? })` from `@hachej/boring-agent/agents` is Pi's documented subagent pattern (pi-durable README, "Abort and Subagents"; pi-durable ships it as an example, not an export) as a tool factory. `delegate({ task })` creates a child conversation owned by the calling tool task (`ownership: { kind: 'task', taskId }`), configured as the child agent alone (its extensions, model and instructions; the inherited tool filters reset), submits the task with request id `<name>:<taskId>` and returns only the child's final text, with `details` (`DelegateDetails`, below) naming the child. It is replay-safe: a rerun after a crash or eviction finds its child through Pi's ownership index (`scanConversations({ ownerTaskId })`) and its submission through the request id, so it never starts a second child or turn. Aborting the call aborts the child. With `defineAgent`, declare `delegates: [{ agent: researcher }]`: each becomes a tool of the agent and `install(registry)` installs the child's extensions as well. A raw-Pi host installs the child agent's extensions itself.
+
+**Child identity.** The kit copies no identity onto a child; the host decides what a child carries. Pass `onChild(parent, child, tx)` in `DelegateOptions` (or a `delegates` entry): it runs inside the same native commit (`ToolExecutionApi.commit`, Pi's `Tx`) that creates and configures the child, so the child never exists without what it writes, and a throw aborts the commit and leaves no child (the delegate call returns an error). It runs once per child, not on a replay that finds the existing child. Read and write only through `tx`:
+
+```ts
+const delegates = [{ agent: researcher, onChild: async (parent, child, tx) => {
+  const from = await tx.doc(HostIdentity, parent), to = await tx.doc(HostIdentity, child); // HostIdentity: the host's conversation doc
+  to.user = from.user; to.workspace = from.workspace; to.permissions = [...from.permissions];
+} }];
+```
+
+**Sub-agent card data.** Every delegate call's `details` is a stable `DelegateDetails` (exported from `@hachej/boring-agent/agents`, with `DELEGATE_DETAILS_KIND` and `DelegateStatus`): `{ kind: 'boring.delegate', version: 1, agent, conversationId, status, startedAt, durationMs, toolCalls, tokens: { input, output }, error? }`. `status` is `running`, `done`, `failed` (with `error`, the same text as the result) or `cancelled`; `conversationId` is the child conversation, `toolCalls` counts the tool calls in the child's assistant messages and `tokens` sums the child's `UsageDoc` (input includes cache reads and writes). While the child runs, the tool publishes `running` values through Pi's `api.details`, so they appear in the call's `LiveDoc` tool slot: it watches the child's `LiveDoc` (`api.watchDoc`) and, when a step of the child's run changes, recounts (`tx.scanEntries` from the last counted entry, `api.snapshot(UsageDoc)`) and publishes only when the counts change; Pi paces the commits. The final result carries `done`, `failed` or `cancelled`. When the delegate call itself is stopped, Pi writes its aborted result from the slot, so its details keep the last `running` value: read `running` on a settled error result as `cancelled`. The `pi-chat` block's `SubagentCard` and `parseDelegateDetails(details, result?)` do this and render any call carrying these details.
 
 **Schedule.** `@hachej/boring-agent/schedule` exports `createScheduleExtension({ now?, onDeadline?, maxDelaySeconds? })`, one native extension with `schedule({ instruction, delaySeconds | at, operationId? })`, `list_schedules()` and `cancel_schedule({ id })`, plus the delivery task `ScheduledDelivery`. A schedule is a native Pi task owned by the conversation as background work: it sleeps on the Harness clock (`runtime.sleep`) and then submits the instruction to its conversation as a follow-up input (entry kind `boring.schedule.delivery`, request id = schedule id, so a replayed delivery never submits twice). Pi's scheduler runs it and a restart resumes it; there is no second scheduler. Pending schedules live in the conversation document `ConversationSchedules`, so a conversation lists and cancels only its own; a cancelled schedule's task wakes and ends without delivering. `schedule` is idempotent on `operationId` (default: the tool task, so a replayed call returns the schedule it made). Hosts schedule outside a tool with `addSchedule(tx, conversationId, { operationId, instruction, runAt })`, `cancelSchedule(tx, conversationId, id)` and `listSchedules(harness, conversationId, context)`. Pass the Harness's own clock as `now`. A host with one wake-up timer (a Durable Object alarm) computes the earliest deadline from `harness.inspect()` with `scheduledDeadline(task)` and moves the timer earlier from `onDeadline`; its alarm handler only reopens or resumes the Harness, and Pi delivers what is due.
 

package/dist/agents.d.ts

@@ -9,8 +9,8 @@ export { createSkillsExtension, parseSkill } from './skills.js';
 export type { Skill } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
 export type { JsonObjectSchema, JsonSchemaToolOptions } from './json-schema-tool.js';
-export { createDelegateTool, DELEGATE_TOOL } from './delegate.js';
-export type { DelegateOptions } from './delegate.js';
+export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';
+export type { DelegateDetails, DelegateOptions, DelegateStatus } from './delegate.js';
 /** One agent as plain data over native Pi pieces. It is a convenience, not another registry or lifecycle. */
 export interface AgentSpec {
     /** Stable name; it becomes the native extension name `agent.<id>`. */
@@ -82,4 +82,13 @@ export declare function refreshAgentState(options: {
     readonly write: (hash: string) => void | Promise<void>;
     readonly context: Context;
 }): Promise<number>;
+/**
+ * Add one extension to an existing conversation, so its next turn runs with it (native `Conversation.commit` over the public
+ * `pi.agent` document, `AgentDoc`). The conversation stores extension names only: the host installs `extension` in the Harness
+ * registry, now and every time it opens the Harness, or the name selects nothing. Unlike `configure({ extensions: { add } })`,
+ * which replaces a stored list (a `defineAgent` conversation's) with an edit of the host default selection, this appends to the
+ * conversation's own list, so it keeps its other extensions and gains no one else's. Its tools are enabled and offered even when
+ * the conversation lists its tools explicitly. Adding an extension twice changes nothing. Remove it with native `configure`.
+ */
+export declare function addExtension(conversation: Conversation, extension: Extension, context: Context): Promise<void>;
 //# sourceMappingURL=agents.d.ts.map

package/dist/agents.js

@@ -1,11 +1,11 @@
 import { createHash } from 'node:crypto';
-import { defineExtension } from '@earendil-works/pi-durable';
+import { AgentDoc, defineExtension } from '@earendil-works/pi-durable';
 import { createSelfEvolution } from './self-evolving.js';
 import { NAME, createSkillsExtension, parseSkill, validSkill } from './skills.js';
 import { createDelegateTool } from './delegate.js';
 export { createSkillsExtension, parseSkill } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
-export { createDelegateTool, DELEGATE_TOOL } from './delegate.js';
+export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';
 /** Turn an agent described as data into native extensions and a native agent configuration. */
 export function defineAgent(spec) {
     if (!NAME.test(spec.id))
@@ -96,3 +96,35 @@ export async function refreshAgentState(options) {
     await options.write(hash);
     return configured;
 }
+/**
+ * Add one extension to an existing conversation, so its next turn runs with it (native `Conversation.commit` over the public
+ * `pi.agent` document, `AgentDoc`). The conversation stores extension names only: the host installs `extension` in the Harness
+ * registry, now and every time it opens the Harness, or the name selects nothing. Unlike `configure({ extensions: { add } })`,
+ * which replaces a stored list (a `defineAgent` conversation's) with an edit of the host default selection, this appends to the
+ * conversation's own list, so it keeps its other extensions and gains no one else's. Its tools are enabled and offered even when
+ * the conversation lists its tools explicitly. Adding an extension twice changes nothing. Remove it with native `configure`.
+ */
+export async function addExtension(conversation, extension, context) {
+    const tools = (extension.tools ?? []).map(tool => tool.name);
+    await conversation.commit(async (tx) => {
+        const state = await tx.doc(AgentDoc, conversation.id);
+        const append = (list, names) => { for (const name of names)
+            if (!list.includes(name))
+                list.push(name); };
+        const selected = state.extensions;
+        if (Array.isArray(selected))
+            append(selected, [extension.name]);
+        else {
+            const add = [...selected?.add ?? []];
+            append(add, [extension.name]);
+            const remove = (selected?.remove ?? []).filter(name => name !== extension.name);
+            state.extensions = { add, ...(remove.length ? { remove } : {}) };
+        }
+        if (Array.isArray(state.tools))
+            append(state.tools, tools);
+        else if (state.tools)
+            state.tools = { remove: state.tools.remove.filter(name => !tools.includes(name)) };
+        if (Array.isArray(state.modelTools))
+            append(state.modelTools, tools);
+    }, context);
+}

package/dist/approval.d.ts

@@ -56,6 +56,14 @@ export interface ApprovalExtensionOptions {
     readonly name?: string;
     /** Tool names to gate, with their rule. Any native tool works, including Pi's stock `bash`, `write` and `edit`. */
     readonly tools: Readonly<Record<string, ApprovalRule>>;
+    /**
+     * What happens to a tool call whose tool is NOT named in `tools`. `'allow'` (default) runs it ungated. `'deny'` blocks it before it runs
+     * (the model is told it was not run), except the tools listed in `allow`. Approval is not asked for unlisted tools: a native hook can
+     * block a call but cannot ask the person, so name a tool in `tools` to have it asked.
+     */
+    readonly unlisted?: 'allow' | 'deny';
+    /** With `unlisted: 'deny'`: tool names that still run without approval (for example the read tools). Ignored otherwise. */
+    readonly allow?: readonly string[];
 }
 /**
  * The approval gate as an opt-in native extension. It brings no tools: it wraps the named tools (native `wraps`, Pi's own
@@ -64,6 +72,13 @@ export interface ApprovalExtensionOptions {
  * `conversation.configure({ extensions: { add: [approvals] } })` turns it on and `remove` turns it off from the next call.
  * Several approval extensions (different `name`s) compose; a tool already gated is never asked twice.
  *
+ * Gating only `bash` is bypassable when self-evolving tools or write+reload are enabled: the agent writes a tool with the ungated
+ * `write` tool, reloads it, and the new tool runs through the same `env.exec`. Gate `write`/`edit` and the reload path too, or set
+ * `unlisted: 'deny'` (with `allow` for the tools that may run freely) so a tool nobody listed cannot run. The default `'allow'` gates only
+ * what `tools` names.
+ *
+ * A delegated child (`createDelegateTool`) inherits the parent's approval extensions, so a delegate cannot escape the gate.
+ *
  * It gates native tool calls only. A code-mode sandbox or any host code that offers the same capability another way is
  * not covered: keep such capabilities out of the sandbox (see `isApprovalGated`).
  */

package/dist/approval.js

@@ -1,4 +1,4 @@
-import { defineExtension } from '@earendil-works/pi-durable';
+import { ToolTask, defineExtension, hook } from '@earendil-works/pi-durable';
 import { askPerson } from './ask-user.js';
 /** The two answers an approval question accepts. A chat answers with exactly these strings through `answerUserQuestion`. */
 export const APPROVE = 'Approve';
@@ -13,6 +13,8 @@ export const CANCELLED_PREFIX = 'Not run: the approval question was cancelled.';
  * without reading the question document. The card in `registry/pi-chat` repeats this key (a contract test keeps them equal).
  */
 export const APPROVAL_DETAILS = 'boring.approval';
+const GUARDS = (globalThis[Symbol.for('boring.agent.guards')] ??= new WeakSet()); // approval + sandbox extensions: a delegated child inherits them
+const markGuard = (extension) => { GUARDS.add(extension); return extension; };
 const MEMO = 'boring.approval.started';
 const GATED = new WeakSet();
 const text = (value, isError) => ({ isError, output: [{ type: 'text', text: value }] });
@@ -112,6 +114,13 @@ const defaultSummary = (name) => (args) => `${name} ${JSON.stringify(args)}`.sli
  * `conversation.configure({ extensions: { add: [approvals] } })` turns it on and `remove` turns it off from the next call.
  * Several approval extensions (different `name`s) compose; a tool already gated is never asked twice.
  *
+ * Gating only `bash` is bypassable when self-evolving tools or write+reload are enabled: the agent writes a tool with the ungated
+ * `write` tool, reloads it, and the new tool runs through the same `env.exec`. Gate `write`/`edit` and the reload path too, or set
+ * `unlisted: 'deny'` (with `allow` for the tools that may run freely) so a tool nobody listed cannot run. The default `'allow'` gates only
+ * what `tools` names.
+ *
+ * A delegated child (`createDelegateTool`) inherits the parent's approval extensions, so a delegate cannot escape the gate.
+ *
  * It gates native tool calls only. A code-mode sandbox or any host code that offers the same capability another way is
  * not covered: keep such capabilities out of the sandbox (see `isApprovalGated`).
  */
@@ -123,5 +132,9 @@ export function createApprovalExtension(options) {
             ...(rule !== true && rule.when ? { when: rule.when } : {}),
         }),
     }));
-    return defineExtension({ name: options.name ?? 'boring.approval', wraps });
+    const allowed = new Set([...Object.keys(options.tools), ...options.allow ?? []]);
+    const hooks = options.unlisted === 'deny'
+        ? [hook(ToolTask, { beforeTool: call => allowed.has(call.name) ? undefined : { block: `Not run: ${call.name} is not allowed in this conversation.` } })]
+        : [];
+    return markGuard(defineExtension({ name: options.name ?? 'boring.approval', wraps, hooks }));
 }

package/dist/chat-transport.d.ts

@@ -55,7 +55,10 @@ export interface ChatTransportAccess {
      * 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`. */
+    /**
+     * Refuse an effect call. Reading stays governed by `authenticate` and `project`. Without it EVERY effect (submit, abort, answer,
+     * withdraw, configure) is allowed to whoever `authenticate` accepted: a host with read-only viewers must pass it.
+     */
     readonly allow?: (operation: 'submit' | 'abort' | 'answer' | 'withdraw' | 'configure') => boolean | Promise<boolean>;
 }
 export interface ChatTransportOptions {
@@ -123,6 +126,12 @@ export interface ConversationSocketOptions {
      * hibernation (the original request is gone by then). The same access the HTTP handler gets from `authenticate`. Null closes the socket.
      */
     readonly access: (attachment: ConversationSocketAttachment) => Promise<ChatTransportAccess | null>;
+    /**
+     * Origins (`https://app.example`) besides the request's own host that may open the socket. A browser upgrade whose `Origin` is
+     * neither the request's host nor listed here is refused (a cross-site page would otherwise ride the visitor's cookies); a request with
+     * no `Origin` (not a browser) is not subject to this check, so `authenticate` still decides who it is.
+     */
+    readonly allowedOrigins?: readonly string[];
 }
 /** The subprotocol a browser client offers and the handler selects. Other offered values (for example a credential) are the host's. */
 export declare const CHAT_SOCKET_PROTOCOL = "boring.chat";

package/dist/chat-transport.js

@@ -241,6 +241,8 @@ export function createChatTransportHandler(options) {
                     || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string')
                     || (access.requestContext && !contextValue(input['context'])))
                     return failure(400, 'invalid-request');
+                if (!await allowed('submit'))
+                    return failure(403, 'not-authorized'); // before `prepareInput`: a denied submitter reads nothing
                 let prepared = input['content'];
                 if (access.prepareInput) {
                     try {
@@ -248,7 +250,7 @@ export function createChatTransportHandler(options) {
                     }
                     catch { /* submit what the person typed */ }
                 }
-                if (!await allowed('submit') || access.revoked?.aborted)
+                if (access.revoked?.aborted)
                     return failure(403, 'not-authorized');
                 if (access.requestContext && input['context'] !== undefined)
                     await access.requestContext(input['context']);
@@ -311,7 +313,7 @@ export function createChatTransportHandler(options) {
             if (error instanceof Error && error.code === 'submission-refused') {
                 return Response.json({ schema: CHAT_TRANSPORT.schema, version: CHAT_TRANSPORT.version, reason: 'submission-refused', message: error.message.slice(0, 500) }, { status: 402, headers });
             }
-            return failure(503, error instanceof Error && error.message ? `source-unavailable: ${error.message.slice(0, 200)}` : 'source-unavailable');
+            return failure(503, 'source-unavailable'); // the detail stays on the host: a message can carry paths, hosts or credentials
         }
         return failure(404, 'unknown-operation');
     };
@@ -342,6 +344,20 @@ export function routeSubmissions(conversation, admit) {
 }
 /** The subprotocol a browser client offers and the handler selects. Other offered values (for example a credential) are the host's. */
 export const CHAT_SOCKET_PROTOCOL = 'boring.chat';
+/** Whether a WebSocket upgrade comes from the page's own host or a listed origin. No `Origin` header: not a browser, so not subject. */
+function sameOrigin(request, allowed = []) {
+    const origin = request.headers.get('origin');
+    if (origin === null)
+        return true;
+    if (allowed.includes(origin))
+        return true;
+    try {
+        return new URL(origin).host === (request.headers.get('host') ?? new URL(request.url).host);
+    }
+    catch {
+        return false;
+    }
+}
 const ownerTag = (owner) => `owner:${owner}`;
 const conversationTag = (id) => `conversation:${id}`;
 const tagFor = (to) => to?.conversationId !== undefined ? conversationTag(to.conversationId) : to?.owner !== undefined ? ownerTag(to.owner) : undefined;
@@ -426,6 +442,8 @@ export function createConversationSocketHandler(options) {
     }
     async function resume() { await Promise.all(state.getWebSockets().map(socket => attach(socket))); }
     async function accept(socket, request) {
+        if (!sameOrigin(request, options.allowedOrigins))
+            return false;
         const found = await options.authenticate(request);
         if (!found)
             return false;
@@ -475,7 +493,7 @@ export function createConversationSocketHandler(options) {
                 return failure(503, 'authentication-unavailable');
             }
             if (!accepted)
-                return failure(401, 'authentication-required');
+                return failure(sameOrigin(request, options.allowedOrigins) ? 401 : 403, sameOrigin(request, options.allowedOrigins) ? 'authentication-required' : 'origin-not-allowed');
             const offered = (request.headers.get('sec-websocket-protocol') ?? '').split(',').map(value => value.trim());
             return new Response(null, { status: 101, webSocket: pair[0], ...(offered.includes(CHAT_SOCKET_PROTOCOL) ? { headers: { 'sec-websocket-protocol': CHAT_SOCKET_PROTOCOL } } : {}) });
         },

package/dist/conversations.js

@@ -359,7 +359,7 @@ export function createConversationsHandler(options) {
                 return failure(error.status, error.status === 413 ? 'request-too-large' : 'invalid-request');
             if (error instanceof TypeError)
                 return failure(400, 'invalid-request');
-            return failure(503, error instanceof Error && error.message ? `source-unavailable: ${error.message.slice(0, 200)}` : 'source-unavailable');
+            return failure(503, 'source-unavailable');
         }
         return failure(404, 'unknown-operation');
     };

package/dist/delegate.d.ts

@@ -1,5 +1,36 @@
-import type { AgentChange, ToolRegistration } from '@earendil-works/pi-durable';
+import type { AgentChange, ConversationId, ToolRegistration, Tx } from '@earendil-works/pi-durable';
 export declare const DELEGATE_TOOL = "delegate";
+/** `DelegateDetails.kind`: how a UI recognises a sub-agent call's details, whatever the tool is named. */
+export declare const DELEGATE_DETAILS_KIND = "boring.delegate";
+export type DelegateStatus = 'running' | 'done' | 'failed' | 'cancelled';
+/**
+ * What a delegate call publishes for a UI (a sub-agent card), version 1. While the child runs, the call's running details
+ * (Pi's `ToolExecutionApi.details`, `pi.live` tool slot) carry it with `status: 'running'`, replaced each time the child's tool
+ * calls or tokens change; the tool result's details carry the finished value (`done`, `failed` with `error`, or `cancelled`).
+ * Fields are only added under version 1; a change of meaning bumps `version`.
+ */
+export type DelegateDetails = {
+    readonly kind: typeof DELEGATE_DETAILS_KIND;
+    readonly version: 1;
+    /** The child agent's id (`DelegateOptions.agent.id`). */
+    readonly agent: string;
+    /** The child conversation, owned by the delegate call's tool task. */
+    readonly conversationId: ConversationId;
+    readonly status: DelegateStatus;
+    /** Epoch milliseconds the call first started (kept across a replay). */
+    readonly startedAt: number;
+    /** Milliseconds from `startedAt` to this update (to the end, once finished). */
+    readonly durationMs: number;
+    /** Tool calls the child's model has made so far (from its committed assistant entries). */
+    readonly toolCalls: number;
+    /** The child's spend so far, from its `pi.usage`: prompt tokens (cache reads and writes included) and output tokens. */
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /** Why the child failed (`failed` only). */
+    readonly error?: string;
+};
 export interface DelegateOptions {
     /**
      * The child agent, usually a `defineAgent` result (its `id` and native `agent` change). The child conversation selects exactly its
@@ -12,13 +43,21 @@ export interface DelegateOptions {
     /** Tool name; default `delegate`. Give each delegate of one agent its own name. */
     readonly name?: string;
     readonly description?: string;
+    /**
+     * Runs inside the native commit (`ToolExecutionApi.commit`, Pi's `Tx`) that creates the child, after the child agent is
+     * configured: the host copies what the child must carry from the parent (user, workspace binding, permissions) with `tx`.
+     * It runs once per child (never on a replay that finds the existing child); a throw aborts the commit, so no child exists.
+     */
+    readonly onChild?: (parent: ConversationId, child: ConversationId, tx: Tx) => void | Promise<void>;
 }
 /**
  * Pi's subagent pattern (pi-durable README "Abort and Subagents") as a tool factory: the child is a conversation owned by the
  * calling tool task (`ownership: { kind: 'task', taskId }`), so aborting the call aborts the child and the parent is idle only
  * once the child is. Replay-safe: a rerun of the same tool task (after a crash or eviction) finds its child through the native
  * ownership index and its submission through the request id, so it never starts a second child or a second turn. Returns only the
- * child's final text; `details.conversationId` names the child for a UI that shows it.
+ * child's final text. The child inherits the parent's approval and sandbox extensions (appended after its own, in the parent's order, so a
+ * sandbox stays last), so a delegate cannot escape the parent's gate; `details` is a `DelegateDetails` (live while the child runs) for a UI that shows it.
+ * `onChild` lets the host write the parent's identity onto the child in the same commit that creates it.
  */
 export declare function createDelegateTool(options: DelegateOptions): ToolRegistration;
 //# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.js

@@ -1,12 +1,18 @@
-import { AssistantEntry, configure, defineTool } from '@earendil-works/pi-durable';
+import { AssistantEntry, LiveDoc, UsageDoc, configure, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
+const GUARDS = (globalThis[Symbol.for('boring.agent.guards')] ??= new WeakSet()); // approval + sandbox extensions: a delegated child inherits them
+const isGuard = (extension) => GUARDS.has(extension);
 export const DELEGATE_TOOL = 'delegate';
+/** `DelegateDetails.kind`: how a UI recognises a sub-agent call's details, whatever the tool is named. */
+export const DELEGATE_DETAILS_KIND = 'boring.delegate';
 /**
  * Pi's subagent pattern (pi-durable README "Abort and Subagents") as a tool factory: the child is a conversation owned by the
  * calling tool task (`ownership: { kind: 'task', taskId }`), so aborting the call aborts the child and the parent is idle only
  * once the child is. Replay-safe: a rerun of the same tool task (after a crash or eviction) finds its child through the native
  * ownership index and its submission through the request id, so it never starts a second child or a second turn. Returns only the
- * child's final text; `details.conversationId` names the child for a UI that shows it.
+ * child's final text. The child inherits the parent's approval and sandbox extensions (appended after its own, in the parent's order, so a
+ * sandbox stays last), so a delegate cannot escape the parent's gate; `details` is a `DelegateDetails` (live while the child runs) for a UI that shows it.
+ * `onChild` lets the host write the parent's identity onto the child in the same commit that creates it.
  */
 export function createDelegateTool(options) {
     const name = options.name ?? DELEGATE_TOOL;
@@ -19,26 +25,125 @@ export function createDelegateTool(options) {
         parameters: Type.Object({ task: Type.String({ minLength: 1, description: 'The complete task; the agent sees nothing else of this conversation.' }) }, { additionalProperties: false }),
         replay: 'safe',
         execute: async (args, api, context) => {
+            const inherited = (await api.agent(context)).extensions.filter(isGuard);
+            const agent = withGuards(child, inherited);
             const childId = await api.commit(async (tx) => {
                 const existing = (await tx.scanConversations({ ownerTaskId: api.taskId }, 1)).items[0];
                 if (existing !== undefined)
                     return existing.id;
                 const created = await tx.createConversation({ ownership: { kind: 'task', taskId: api.taskId } });
-                await configure(tx, created.id, child);
+                await configure(tx, created.id, agent);
+                await options.onChild?.(api.conversationId, created.id, tx);
                 return created.id;
             }, context);
-            await api.details({ conversationId: childId }, context);
+            const startedAt = await api.memo('delegate.startedAt', Date.now(), context);
+            const progress = childProgress(api, childId);
+            const details = (status, counts, error) => ({
+                kind: DELEGATE_DETAILS_KIND, version: 1, agent: options.agent.id, conversationId: childId, status, startedAt,
+                durationMs: Math.max(1, Date.now() - startedAt), ...counts, ...(error === undefined ? {} : { error })
+            });
+            const initial = await progress.read(context);
+            await api.details(details('running', initial), context);
             const conversation = await api.conversation(childId, context);
             if (conversation === undefined)
                 throw new Error(`Delegate conversation ${childId} is missing`);
             const submission = await conversation.submit({ type: 'input', content: args.task, requestId: `${name}:${api.taskId}` }, context);
-            const settled = await submission.wait(context);
-            if (settled.status !== 'done' || settled.type !== 'input')
-                throw new Error(`The ${options.agent.id} agent did not answer: ${settled.status}`);
+            const live = await publishLive(api, childId, progress, initial, counts => api.details(details('running', counts), context), context);
+            // A stopped call ends here: Pi writes its aborted result from the slot, so its details stay the last `running` value.
+            const settled = await submission.wait(context).finally(() => live.stop());
+            const counts = await progress.read(context);
+            if (settled.status !== 'done' || settled.type !== 'input') {
+                const reason = settled.status === 'unanswered' ? settled.reason : settled.status;
+                const detail = settled.status === 'unanswered' && typeof settled.detail === 'string' && settled.detail ? settled.detail : undefined;
+                const error = `The ${options.agent.id} agent did not answer: ${reason}${detail ? ` (${detail})` : ''}`;
+                return { output: [{ type: 'text', text: error }], isError: true, details: reason === 'aborted' ? details('cancelled', counts) : details('failed', counts, error) };
+            }
             const answer = await api.commit(tx => tx.entry(AssistantEntry, settled.answer), context);
             const message = answer?.model?.find(part => part.role === 'assistant');
             const text = message?.role === 'assistant' ? message.content.flatMap(part => part.type === 'text' ? [part.text] : []).join('\n') : '';
-            return { output: [{ type: 'text', text }], details: { conversationId: childId } };
+            return { output: [{ type: 'text', text }], details: details('done', counts) };
         },
     });
 }
+/**
+ * The child's counts from its native records: tool calls from its committed assistant entries (scanned once, incrementally,
+ * through the invocation's commit), tokens from its `pi.usage` (Pi's `UsageDoc`, both buckets).
+ */
+function childProgress(api, childId) {
+    let toolCalls = 0, after;
+    return {
+        async read(context) {
+            const scanned = await api.commit(async (tx) => {
+                let found = 0, last = after, cursor;
+                do {
+                    const page = await tx.scanEntries({ conversationId: childId, order: 'ascending', ...(last === undefined ? {} : { minEntryId: (last + 1) }) }, 100, cursor);
+                    for (const entry of page.items) {
+                        last = entry.id;
+                        for (const message of entry.model ?? [])
+                            if (message.role === 'assistant')
+                                found += message.content.filter(part => part.type === 'toolCall').length;
+                    }
+                    cursor = page.next;
+                } while (cursor !== undefined);
+                return { found, last };
+            }, context);
+            toolCalls += scanned.found;
+            after = scanned.last;
+            const usage = await api.snapshot(UsageDoc, childId, context);
+            const tokens = { input: 0, output: 0 };
+            for (const bucket of [usage?.models, usage?.tools])
+                for (const spend of Object.values(bucket ?? {})) {
+                    tokens.input += (spend.input ?? 0) + (spend.cacheRead ?? 0) + (spend.cacheWrite ?? 0);
+                    tokens.output += spend.output ?? 0;
+                }
+            return { toolCalls, tokens };
+        },
+    };
+}
+/**
+ * Publish the child's counts while it runs. Pi's `watchDoc(LiveDoc)` on the child is the trigger: a frame whose run shape changed
+ * (a response committed, a tool round started or ended; never a streamed partial) schedules one read of the counts, outside the
+ * listener so the watch never waits on it, coalescing the frames that arrive meanwhile. The details are replaced only when the
+ * counts changed. `stop()` ends the watch and waits for a publish in flight.
+ */
+async function publishLive(api, childId, progress, initial, publish, context) {
+    const watch = await api.watchDoc(LiveDoc, childId, context);
+    if (watch === undefined)
+        return { stop: async () => undefined };
+    let shape = '', published = JSON.stringify(initial), stopped = false, dirty = false;
+    let reading, committing = Promise.resolve();
+    const drain = async () => {
+        while (dirty && !stopped) {
+            dirty = false;
+            const counts = await progress.read(context);
+            const key = JSON.stringify(counts);
+            if (stopped || key === published)
+                continue;
+            published = key;
+            // Not awaited: Pi paces running-details commits (`progress.outputIntervalMs`) and a newer value replaces a pending one.
+            committing = publish(counts).catch(() => undefined);
+        }
+    };
+    watch.start(async (value) => {
+        const next = runShape(value);
+        if (stopped || next === shape)
+            return;
+        shape = next;
+        dirty = true;
+        reading ??= drain().catch(() => undefined).finally(() => { reading = undefined; });
+    });
+    return { async stop() { stopped = true; await watch.stop(); await reading; await committing; } };
+}
+const runShape = (live) => JSON.stringify([live?.run?.taskId ?? null, live?.generation?.attempt ?? null, live?.generation?.message === undefined,
+    (live?.tools ?? []).map(slot => `${slot.callId}:${slot.status}`)]);
+/** `change` with the parent's guard extensions appended to its extension selection (an array or `add`; an unset selection already inherits the parent's). */
+function withGuards(change, guards) {
+    const { extensions } = change;
+    if (!guards.length || extensions === undefined || extensions === null)
+        return change;
+    if (Array.isArray(extensions))
+        return { ...change, extensions: [...extensions, ...guards.filter(guard => !extensions.some(own => own.name === guard.name))] };
+    const selection = extensions;
+    const present = selection.add ?? [];
+    return { ...change, extensions: { ...selection, add: [...present, ...guards.filter(guard => !present.some(own => own.name === guard.name))] } };
+}

package/dist/mentions.js

@@ -113,7 +113,7 @@ export function createMentionResolver(options) {
                 }
                 const cut = bytes.length > room;
                 used += Math.min(bytes.length, room);
-                added.push({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}"${cut ? ` truncated="showing the first ${new TextEncoder().encode(text).length} of ${bytes.length} bytes"` : ''}>\n${text.replace(/<\/file>/g, '<\\/file>')}\n</file>` });
+                added.push({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}"${cut ? ` truncated="showing the first ${new TextEncoder().encode(text).length} of ${bytes.length} bytes"` : ''}>\n${text.replace(/<(\s*\/?\s*file)\b/gi, '<\\$1')}\n</file>` });
             }
             return [...parts, ...added];
         }

package/dist/prompt-context.js

@@ -14,7 +14,9 @@ const produced = new WeakSet();
  * assistant continuation) at the tail. Pure: the input array is not changed.
  */
 export function withRequestContext(messages, text, tag = 'request-context') {
-    const message = { role: 'user', content: [{ type: 'text', text: `<${tag}>\n${text}\n</${tag}>` }], timestamp: Date.now() };
+    // The text may be browser-supplied: neutralise every opening or closing `tag` in it (any case, spaces allowed) so it cannot end the wrapper.
+    const inner = text.replace(new RegExp(`<(\\s*/?\\s*${tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})(?![\\w-])`, 'gi'), '<\\$1');
+    const message = { role: 'user', content: [{ type: 'text', text: `<${tag}>\n${inner}\n</${tag}>` }], timestamp: Date.now() };
     produced.add(message);
     let end = messages.length;
     while (end > 0 && produced.has(messages[end - 1]))

package/dist/sandbox.d.ts

@@ -1,6 +1,5 @@
 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 {

package/dist/sandbox.js

@@ -1,5 +1,7 @@
 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`. */
+const GUARDS = (globalThis[Symbol.for('boring.agent.guards')] ??= new WeakSet()); // approval + sandbox extensions: a delegated child inherits them
+const markGuard = (extension) => { GUARDS.add(extension); return extension; };
 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.`;
@@ -45,13 +47,13 @@ export function createSandboxExtension(options) {
     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({
+    return markGuard(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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -156,8 +156,8 @@
     "@earendil-works/pi-durable": "~1.2.0",
     "@earendil-works/pi-ai": "~1.2.0",
     "@earendil-works/chord": "~1.2.0",
-    "@hachej/boring-files": "^0.4.8",
-    "@hachej/boring-ui-kit": "^0.4.8",
+    "@hachej/boring-files": "^0.4.10",
+    "@hachej/boring-ui-kit": "^0.4.10",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {