@hachej/boring-agent 0.4.7 → 0.4.9

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

@@ -18,7 +18,8 @@ export interface DelegateOptions {
  * 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.conversationId` names the child for a UI that shows it.
  */
 export declare function createDelegateTool(options: DelegateOptions): ToolRegistration;
 //# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.js

@@ -1,12 +1,15 @@
 import { AssistantEntry, 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';
 /**
  * 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.conversationId` names the child for a UI that shows it.
  */
 export function createDelegateTool(options) {
     const name = options.name ?? DELEGATE_TOOL;
@@ -19,12 +22,14 @@ 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);
                 return created.id;
             }, context);
             await api.details({ conversationId: childId }, context);
@@ -42,3 +47,14 @@ export function createDelegateTool(options) {
         },
     });
 }
+/** `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.7",
+  "version": "0.4.9",
   "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.7",
-    "@hachej/boring-ui-kit": "^0.4.7",
+    "@hachej/boring-files": "^0.4.9",
+    "@hachej/boring-ui-kit": "^0.4.9",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {