@hachej/boring-agent 0.1.111 → 0.2.0

package/dist/approval.d.ts

@@ -0,0 +1,71 @@
+import type { ConversationId, Extension, ToolRegistration } from '@earendil-works/pi-durable';
+import type { JsonValue } from '@earendil-works/chord';
+import type { Static, TSchema } from '@earendil-works/pi-ai';
+/** The two answers an approval question accepts. A chat answers with exactly these strings through `answerUserQuestion`. */
+export declare const APPROVE = "Approve";
+export declare const DENY = "Deny";
+/** A denied call's result text starts with this, so a viewer can tell a denial from a failure. */
+export declare const DENIED_PREFIX = "Denied by the person.";
+/** A call whose question was cancelled (the run was stopped) before the person answered: it did not run. */
+export declare const CANCELLED_PREFIX = "Not run: the approval question was cancelled.";
+/**
+ * Key under a gated call's running details (then, unless the tool returns its own `details`, its result details) that holds
+ * `{ summary, decision? }`: the one-line text `summarize` returned and, once made, `approved`, `denied` or `cancelled`. A chat view carries it, so an approval card can show the summary
+ * without reading the question document. The card in `registry/pi-chat` repeats this key (a contract test keeps them equal).
+ */
+export declare const APPROVAL_DETAILS = "boring.approval";
+/** The call a rule is asked about: which conversation it runs in (a host can name the site or project it maps to) and its ID. */
+export interface ApprovalCall {
+    readonly conversationId: ConversationId;
+    readonly callId: string;
+    readonly toolName: string;
+}
+export interface RequireApprovalOptions<TParameters extends TSchema = TSchema> {
+    /** One line about what the call would change, from its arguments. It is stored with the question; the model never writes it. */
+    readonly summarize: (args: Static<TParameters>, call: ApprovalCall) => string;
+    /** Ask only when this returns true (for example any HTTP method but GET); other calls run at once. Default: always ask. */
+    readonly when?: (args: Static<TParameters>, call: ApprovalCall) => boolean;
+}
+/**
+ * Wrap a native tool so the person must approve each call before it executes. The tool keeps its name, schema and
+ * description. Before `execute`, the call asks "Approve / Deny" through the ask-user mechanism (a conversation document
+ * keyed by the tool call ID, answered with `answerUserQuestion` over the chat transport's `answer` operation, shown by
+ * pi-chat's approval card). The check runs in host code inside the tool's own execution, so the model cannot skip it.
+ *
+ * - While it waits, the summary is published as running details under `APPROVAL_DETAILS` for the card.
+ * - Deny returns an error result starting `DENIED_PREFIX` and `execute` never runs. A question cancelled while the call
+ *   itself keeps running returns one starting `CANCELLED_PREFIX`; when the call is being stopped, Pi records the stop.
+ * - A pending approval survives a restart: the wrapper is replay-safe, and replay re-attaches to the stored question.
+ * - Execution happens at most once per call. The wrapper retains a native memo before running the inner tool; if the
+ *   process dies after that and the inner tool is not itself `replay: 'safe'`, recovery returns an error saying the
+ *   outcome is unknown instead of repeating a change that may have happened.
+ *
+ * Code mode: gated tools are native tools. Do not expose them to a code-mode sandbox (its nested calls cannot reach a
+ * person), and filter with `isApprovalGated`. Give `run_code` the read tools only; changes go through the gated native tool.
+ */
+export declare function requireApproval<TParameters extends TSchema, TDetails extends JsonValue>(tool: ToolRegistration<TParameters, TDetails>, options: RequireApprovalOptions<TParameters>): ToolRegistration<TParameters, JsonValue>;
+/** Whether `tool` came from `requireApproval`. Use it to keep gated tools out of a code-mode sandbox's tool list. */
+export declare function isApprovalGated(tool: object): boolean;
+/** How one tool is gated by `createApprovalExtension`: `true` uses a default summary and always asks. */
+export type ApprovalRule = true | {
+    readonly summarize?: (args: Record<string, unknown>, call: ApprovalCall) => string;
+    readonly when?: (args: Record<string, unknown>, call: ApprovalCall) => boolean;
+};
+export interface ApprovalExtensionOptions {
+    /** Native extension name. Default `boring.approval`; use another name to compose several rule sets. */
+    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>>;
+}
+/**
+ * The approval gate as an opt-in native extension. It brings no tools: it wraps the named tools (native `wraps`, Pi's own
+ * decorator by tool name) with `requireApproval`, so whatever tool of that name wins in a conversation waits for the
+ * person there. Pi applies wraps only in conversations that select the extension, so it is opt-in per conversation:
+ * `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.
+ *
+ * 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`).
+ */
+export declare function createApprovalExtension(options: ApprovalExtensionOptions): Extension;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -0,0 +1,126 @@
+import { defineExtension } 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';
+export const DENY = 'Deny';
+/** A denied call's result text starts with this, so a viewer can tell a denial from a failure. */
+export const DENIED_PREFIX = 'Denied by the person.';
+/** A call whose question was cancelled (the run was stopped) before the person answered: it did not run. */
+export const CANCELLED_PREFIX = 'Not run: the approval question was cancelled.';
+/**
+ * Key under a gated call's running details (then, unless the tool returns its own `details`, its result details) that holds
+ * `{ summary, decision? }`: the one-line text `summarize` returned and, once made, `approved`, `denied` or `cancelled`. A chat view carries it, so an approval card can show the summary
+ * 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 MEMO = 'boring.approval.started';
+const GATED = new WeakSet();
+const text = (value, isError) => ({ isError, content: [{ type: 'text', text: value }] });
+/**
+ * Wrap a native tool so the person must approve each call before it executes. The tool keeps its name, schema and
+ * description. Before `execute`, the call asks "Approve / Deny" through the ask-user mechanism (a conversation document
+ * keyed by the tool call ID, answered with `answerUserQuestion` over the chat transport's `answer` operation, shown by
+ * pi-chat's approval card). The check runs in host code inside the tool's own execution, so the model cannot skip it.
+ *
+ * - While it waits, the summary is published as running details under `APPROVAL_DETAILS` for the card.
+ * - Deny returns an error result starting `DENIED_PREFIX` and `execute` never runs. A question cancelled while the call
+ *   itself keeps running returns one starting `CANCELLED_PREFIX`; when the call is being stopped, Pi records the stop.
+ * - A pending approval survives a restart: the wrapper is replay-safe, and replay re-attaches to the stored question.
+ * - Execution happens at most once per call. The wrapper retains a native memo before running the inner tool; if the
+ *   process dies after that and the inner tool is not itself `replay: 'safe'`, recovery returns an error saying the
+ *   outcome is unknown instead of repeating a change that may have happened.
+ *
+ * Code mode: gated tools are native tools. Do not expose them to a code-mode sandbox (its nested calls cannot reach a
+ * person), and filter with `isApprovalGated`. Give `run_code` the read tools only; changes go through the gated native tool.
+ */
+export function requireApproval(tool, options) {
+    if (GATED.has(tool))
+        return tool; // already gated: never ask twice
+    // The gated tool's details are the inner tool's, with the approval record merged in under APPROVAL_DETAILS, so a view keeps the
+    // summary and decision even when the inner tool publishes details of its own (non-object details are kept as they are).
+    const gated = {
+        ...tool,
+        replay: 'safe',
+        execute: async (args, outerApi, context) => {
+            let record;
+            const withRecord = (value) => !record ? value
+                : value === undefined || (value !== null && typeof value === 'object' && !Array.isArray(value)) ? { ...(value ?? {}), [APPROVAL_DETAILS]: record } : value;
+            const publish = (next) => { record = next; return outerApi.details(withRecord(undefined), context); };
+            const api = { ...outerApi, details: (value, inner) => outerApi.details(withRecord(value), inner) };
+            // The wrapper is replay-safe so a pending question survives a restart; an inner tool that is not keeps its
+            // at-most-once guarantee through a native memo, whether or not this call asked the person.
+            const run = async () => {
+                if (tool.replay !== 'safe') {
+                    if (await outerApi.memo(MEMO, context) !== undefined)
+                        return text(`${tool.name} started, but the process stopped while it ran. Whether the change was applied is unknown; check before retrying.`, true);
+                    await outerApi.memo(MEMO, true, context);
+                }
+                const result = await tool.execute(args, api, context);
+                return result.details === undefined ? result : { ...result, details: withRecord(result.details) };
+            };
+            let ask = true;
+            const call = { conversationId: outerApi.conversationId, callId: outerApi.callId, toolName: tool.name };
+            try {
+                ask = options.when ? options.when(args, call) : true;
+            }
+            catch {
+                ask = true;
+            } // a broken rule asks rather than skipping the person
+            if (!ask)
+                return run();
+            let summary;
+            try {
+                summary = options.summarize(args, call);
+            }
+            catch {
+                summary = JSON.stringify(args);
+            }
+            summary = summary.slice(0, 500);
+            await publish({ summary });
+            const prompt = `Allow ${tool.name}? ${summary}`.slice(0, 1000);
+            // The decision joins the summary in the call's details, so a view tells approved, denied and never-answered apart.
+            const decided = (decision) => publish({ summary, decision });
+            let answer;
+            try {
+                answer = await askPerson(outerApi, context, { prompt, options: [APPROVE, DENY] });
+            }
+            catch (error) {
+                if (context.abortSignal?.aborted)
+                    throw error; // the call itself is being stopped: Pi records that, and no decision was made
+                await decided('cancelled');
+                return text(`${CANCELLED_PREFIX} ${tool.name} was not run and nothing was changed.`, true);
+            }
+            if (answer !== APPROVE) {
+                await decided('denied');
+                return text(`${DENIED_PREFIX} ${tool.name} was not run and nothing was changed.`, true);
+            }
+            await decided('approved');
+            return run();
+        },
+    };
+    GATED.add(gated);
+    return gated;
+}
+/** Whether `tool` came from `requireApproval`. Use it to keep gated tools out of a code-mode sandbox's tool list. */
+export function isApprovalGated(tool) { return GATED.has(tool); }
+const defaultSummary = (name) => (args) => `${name} ${JSON.stringify(args)}`.slice(0, 300);
+/**
+ * The approval gate as an opt-in native extension. It brings no tools: it wraps the named tools (native `wraps`, Pi's own
+ * decorator by tool name) with `requireApproval`, so whatever tool of that name wins in a conversation waits for the
+ * person there. Pi applies wraps only in conversations that select the extension, so it is opt-in per conversation:
+ * `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.
+ *
+ * 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`).
+ */
+export function createApprovalExtension(options) {
+    const wraps = Object.entries(options.tools).map(([name, rule]) => ({
+        tool: name,
+        wrap: (tool) => requireApproval(tool, {
+            summarize: (rule !== true && rule.summarize) || defaultSummary(name),
+            ...(rule !== true && rule.when ? { when: rule.when } : {}),
+        }),
+    }));
+    return defineExtension({ name: options.name ?? 'boring.approval', wraps });
+}

package/dist/artifacts.d.ts

@@ -0,0 +1,53 @@
+import type { ToolExecutionApi } from '@earendil-works/pi-durable';
+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';
+export declare const ARTIFACT_TYPES: readonly ["markdown", "html", "svg", "code", "canvas"];
+export type ArtifactType = typeof ARTIFACT_TYPES[number];
+/**
+ * What a tool result carries under its `artifact` key. The descriptor of `present` points at a workspace file (`target`), names the
+ * revision shown and carries no `id` or `ordinal` (both stay optional for hosts that number their own versions).
+ */
+export interface ArtifactDescriptor {
+    readonly schema: 'boring.artifact';
+    readonly version: 1;
+    readonly id?: string;
+    readonly title: string;
+    readonly type: ArtifactType;
+    readonly mediaType: string;
+    readonly language?: string;
+    readonly target: ResourceLocator;
+    readonly revision: string;
+    readonly ordinal?: number;
+}
+export type ArtifactDescriptorInput = Omit<ArtifactDescriptor, 'schema' | 'version'>;
+/** Build a descriptor, refusing anything `parseArtifact` would refuse. */
+export declare function createArtifactDescriptor(input: ArtifactDescriptorInput): ArtifactDescriptor;
+/**
+ * Strict shape check of an untrusted value (a model-visible tool result, a stored reference). Returns a fresh copy or
+ * undefined. This function has no Pi runtime dependency; `registry/pi-chat/artifact.ts` carries the same validator for
+ * the browser, because a copied registry item cannot import this package.
+ */
+export declare function parseArtifact(value: unknown): ArtifactDescriptor | undefined;
+export interface PresentToolOptions {
+    /**
+     * The workspace of each call, resolved like Pi's environment (`@hachej/boring-agent/workspaces`), or one binding `{ files, root }`; absent: the
+     * workspace attached to the call's env (`withWorkspace`). Its
+     * provider (`@hachej/boring-files/workspace`) reads the file and retains the presented revision in its history; the descriptor names its
+     * provider id.
+     */
+    readonly workspace?: WorkspaceResolver | WorkspaceBinding | undefined;
+    /** The agent's principal for the provider. Default: the binding's `access`. */
+    readonly resolveAccess?: (api: ToolExecutionApi, context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    /** Largest file shown, in bytes. Defaults to 256 KiB. */
+    readonly maxBytes?: number;
+}
+/**
+ * `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.
+ */
+export declare function createPresentTool(options?: PresentToolOptions): import("@earendil-works/pi-durable").ToolRegistration<Type.TObject<{
+    path: Type.TString;
+}>, import("@earendil-works/chord").JsonValue>;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.js

@@ -0,0 +1,129 @@
+import { defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import { asWorkspaceResolver, workspaceFor } from './workspaces.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
+ * file tools and calls `present(path)`, which keeps the shown revision in the workspace provider's history and returns a
+ * descriptor pointing at the file. There is no store of artifacts and no index. Nothing is executed here.
+ */
+export const ARTIFACT_TYPES = ['markdown', 'html', 'svg', 'code', 'canvas'];
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const LANGUAGE = /^[A-Za-z0-9+#._-]{1,32}$/;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasOnly = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+/** Build a descriptor, refusing anything `parseArtifact` would refuse. */
+export function createArtifactDescriptor(input) {
+    const descriptor = { schema: 'boring.artifact', version: 1, ...input };
+    const parsed = parseArtifact(descriptor);
+    if (!parsed)
+        throw new TypeError('Invalid artifact descriptor');
+    return parsed;
+}
+/**
+ * Strict shape check of an untrusted value (a model-visible tool result, a stored reference). Returns a fresh copy or
+ * undefined. This function has no Pi runtime dependency; `registry/pi-chat/artifact.ts` carries the same validator for
+ * the browser, because a copied registry item cannot import this package.
+ */
+export function parseArtifact(value) {
+    if (!isObject(value) || !hasOnly(value, ['schema', 'version', 'id', 'title', 'type', 'mediaType', 'language', 'target', 'revision', 'ordinal']))
+        return undefined;
+    const { id, title, type, mediaType, language, target, revision, ordinal } = value;
+    if (value['schema'] !== 'boring.artifact' || value['version'] !== 1)
+        return undefined;
+    if (id !== undefined && (typeof id !== 'string' || !ID.test(id)))
+        return undefined;
+    if (typeof title !== 'string' || !title.trim() || title.length > 200)
+        return undefined;
+    if (typeof type !== 'string' || !ARTIFACT_TYPES.includes(type))
+        return undefined;
+    if (typeof mediaType !== 'string' || !/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(mediaType))
+        return undefined;
+    if (language !== undefined && (typeof language !== 'string' || !LANGUAGE.test(language)))
+        return undefined;
+    if (typeof revision !== 'string' || !revision || revision.length > 256)
+        return undefined;
+    if (ordinal !== undefined && (typeof ordinal !== 'number' || !Number.isSafeInteger(ordinal) || ordinal < 1))
+        return undefined;
+    if (!isObject(target) || !hasOnly(target, ['resource', 'view']) || !isObject(target['resource']) || !hasOnly(target['resource'], ['providerId', 'path']))
+        return undefined;
+    const { providerId, path } = target['resource'];
+    if (typeof providerId !== 'string' || !providerId || typeof path !== 'string' || !path || path.length > 512)
+        return undefined;
+    const view = target['view'];
+    if (!isObject(view))
+        return undefined;
+    let parsedView;
+    if (view['kind'] === 'published' && hasOnly(view, ['kind']))
+        parsedView = { kind: 'published' };
+    else if (view['kind'] === 'working' && hasOnly(view, ['kind', 'viewId']) && typeof view['viewId'] === 'string' && view['viewId'])
+        parsedView = { kind: 'working', viewId: view['viewId'] };
+    else
+        return undefined;
+    return { schema: 'boring.artifact', version: 1, ...(id === undefined ? {} : { id }), title, type: type, mediaType, ...(language === undefined ? {} : { language: language }),
+        target: { resource: { providerId, path }, view: parsedView }, revision, ...(ordinal === undefined ? {} : { ordinal }) };
+}
+const reply = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+const decode = (bytes) => { try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+catch {
+    return undefined;
+} };
+const PRESENTED = {
+    md: { type: 'markdown', mediaType: 'text/markdown' }, markdown: { type: 'markdown', mediaType: 'text/markdown' },
+    html: { type: 'html', mediaType: 'text/html' }, htm: { type: 'html', mediaType: 'text/html' },
+    svg: { type: 'svg', mediaType: 'image/svg+xml' }, tldraw: { type: 'canvas', mediaType: 'application/vnd.tldraw+json' },
+};
+const LANGUAGE_OF = { 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' };
+/**
+ * `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.
+ */
+export function createPresentTool(options = {}) {
+    const resolver = asWorkspaceResolver(options.workspace);
+    const maxBytes = options.maxBytes ?? 256 * 1024;
+    return defineTool({
+        name: 'present',
+        // 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.',
+            'When the person asks for something substantial and self-contained (a report, document, HTML page, SVG image or program), write it to a file with the write tool, using a short descriptive path with the right extension (.md, .html, .svg with a viewBox, or the language\'s own), then call present with that path; never put that content in your reply. After present, reply with one or two short sentences and never repeat the content.',
+            'Short answers stay in the chat, and so does anything the person asks to have in the chat or without tools or artifacts: then call no tool.',
+            'To change, extend or fix something you presented: read the file again first (the person may have edited it; keep their changes), change it with edit (or write the whole new content) at the same path, never a second file, and call present again. If you do not remember the path, list the files.',
+        ].join(' '),
+        parameters: Type.Object({ path: Type.String({ minLength: 1, maxLength: 512, description: 'The file path, relative to the workspace.' }) }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (args, api, context) => {
+            const path = args.path.replace(/^\.\//, '');
+            const resolved = await workspaceFor(resolver, api, context);
+            if ('refused' in resolved)
+                return reply({ kind: 'denied', reason: resolved.refused });
+            const { files } = resolved.binding;
+            const providerId = files.providerId;
+            const granted = options.resolveAccess ? await options.resolveAccess(api, context) : resolved.binding.access;
+            if (granted === undefined)
+                return reply({ kind: 'denied', reason: 'The host gave no access for this workspace' });
+            const access = { ...granted };
+            const extension = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+            const kind = PRESENTED[extension] ?? { type: 'code', mediaType: 'text/plain', language: LANGUAGE_OF[extension] };
+            const target = { resource: { providerId, path }, view: { kind: 'published' } };
+            const first = await files.read({ target, revision: { kind: 'latest' } }, access);
+            if (first.kind !== 'available')
+                return reply(first);
+            const text = decode(first.snapshot.bytes);
+            if (text === undefined)
+                return reply({ kind: 'denied', reason: 'The file is not valid UTF-8 text' });
+            if (first.snapshot.bytes.byteLength > maxBytes)
+                return reply({ kind: 'denied', reason: `The file is larger than ${maxBytes} bytes` });
+            if (kind.type === 'svg' && !/<svg[\s>]/i.test(text))
+                return reply({ kind: 'denied', reason: 'An SVG file must contain an <svg> element' });
+            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 });
+        },
+    });
+}

package/dist/ask-user.d.ts

@@ -0,0 +1,40 @@
+import type { Conversation, ToolExecutionApi, ToolRegistration } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+export declare const ASK_USER_TOOL = "ask_user";
+export declare const ASK_USER_MAX_ANSWER = 2000;
+export type AskUserAnswer = {
+    kind: 'answered';
+} | {
+    kind: 'denied' | 'conflict' | 'unknown-question';
+    reason?: string;
+};
+/** Bind an answer to the exact assistant entry that asked it. */
+export declare const askUserQuestionId: (assistantEntryId: number, callId: string) => string;
+/**
+ * A native Pi tool that asks the person a question and waits for the answer without holding a model request.
+ * The question is bound to its native assistant entry and tool call, so a pending question survives a restart
+ * (the replay-safe call re-attaches to it) and is cancelled with the call when the conversation is stopped.
+ * The result is the text `{"kind":"answered","answer":"..."}`. Answer it with `answerUserQuestion`.
+ */
+export declare function createAskUserTool(options?: {
+    readonly description?: string;
+}): ToolRegistration;
+/**
+ * Ask the person from inside a running native tool and wait for the answer. The question is a conversation document bound
+ * to the asking assistant entry and tool call (`askUserQuestionId`), so it survives a restart (a replay-safe call
+ * re-attaches to it) and is cancelled with the call. Answer it with `answerUserQuestion(conversation, questionId, answer)`,
+ * which accepts one of `options` (or any text when `allowFreeText`). Resolves with the answer; throws when the question is
+ * cancelled. `createAskUserTool` and `requireApproval` (`@hachej/boring-agent/approval`) both ask through this.
+ */
+export declare function askPerson(api: ToolExecutionApi, context: Context, question: {
+    readonly prompt: string;
+    readonly options?: readonly string[];
+    readonly allowFreeText?: boolean;
+}): Promise<string>;
+/**
+ * Resolve an `ask_user` question using `askUserQuestionId(assistantEntryId, callId)` after authenticating the person.
+ * Unscoped model call IDs are accepted only when exactly one native task used them in this conversation.
+ * Exactly one answer is accepted; repeating it is idempotent.
+ */
+export declare function answerUserQuestion(conversation: Conversation, callId: string, answer: string, context?: Context): Promise<AskUserAnswer>;
+//# sourceMappingURL=ask-user.d.ts.map

package/dist/ask-user.js

@@ -0,0 +1,134 @@
+import { defineDocFamily, defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
+import { AmbiguousCall, UnknownCall, callBinding, callBindingId, ownBindingKey, waitForDocument } from './durable-wait.js';
+export const ASK_USER_TOOL = 'ask_user';
+export const ASK_USER_MAX_ANSWER = 2000;
+/** One member per assistant entry and tool call, in the asking conversation. */
+const documents = defineDocFamily({
+    kind: 'boring.ask-user.question', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
+    initial: () => ({ question: null }),
+});
+/** Bind an answer to the exact assistant entry that asked it. */
+export const askUserQuestionId = callBindingId;
+function refusal(options, allowFreeText) {
+    if (options !== undefined && (options.length < 2 || options.length > 6 || options.some(option => typeof option !== 'string' || !option.trim() || option.length > 200)
+        || new Set(options).size !== options.length))
+        return 'options must be 2 to 6 distinct short strings';
+    if (options === undefined && allowFreeText !== true)
+        return 'give options, or set allowFreeText to true';
+    return undefined;
+}
+/**
+ * A native Pi tool that asks the person a question and waits for the answer without holding a model request.
+ * The question is bound to its native assistant entry and tool call, so a pending question survives a restart
+ * (the replay-safe call re-attaches to it) and is cancelled with the call when the conversation is stopped.
+ * The result is the text `{"kind":"answered","answer":"..."}`. Answer it with `answerUserQuestion`.
+ */
+export function createAskUserTool(options = {}) {
+    return defineTool({
+        name: ASK_USER_TOOL,
+        description: options.description ?? 'Ask the person a question and wait for their answer. Give 2 to 6 short options, or allow free text, or both.',
+        parameters: Type.Object({
+            question: Type.String({ minLength: 1, maxLength: 1000 }),
+            options: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 200 }), { minItems: 2, maxItems: 6 })),
+            allowFreeText: Type.Optional(Type.Boolean()),
+        }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (args, api, context) => {
+            const problem = refusal(args.options, args.allowFreeText);
+            if (problem)
+                return { isError: true, content: [{ type: 'text', text: `Invalid question: ${problem}.` }] };
+            const answer = await askPerson(api, context, { prompt: args.question, ...(args.options === undefined ? {} : { options: args.options }), allowFreeText: args.allowFreeText === true });
+            return { content: [{ type: 'text', text: JSON.stringify({ kind: 'answered', answer }) }] };
+        },
+    });
+}
+/**
+ * Ask the person from inside a running native tool and wait for the answer. The question is a conversation document bound
+ * to the asking assistant entry and tool call (`askUserQuestionId`), so it survives a restart (a replay-safe call
+ * re-attaches to it) and is cancelled with the call. Answer it with `answerUserQuestion(conversation, questionId, answer)`,
+ * which accepts one of `options` (or any text when `allowFreeText`). Resolves with the answer; throws when the question is
+ * cancelled. `createAskUserTool` and `requireApproval` (`@hachej/boring-agent/approval`) both ask through this.
+ */
+export async function askPerson(api, context, question) {
+    const key = await api.commit(async (tx) => {
+        const key = await ownBindingKey(tx, api);
+        const document = await tx.doc(documents, api.conversationId, key, null);
+        if (!document.question) {
+            const legacy = await tx.doc(documents, api.conversationId, api.callId, null);
+            document.question = legacy.question?.taskId === api.taskId ? { ...legacy.question, options: [...legacy.question.options], state: { ...legacy.question.state } }
+                : { prompt: question.prompt, options: [...(question.options ?? [])], allowFreeText: question.allowFreeText === true, taskId: api.taskId, state: { kind: 'pending' } };
+        }
+        if (document.question.taskId !== api.taskId)
+            throw new Error('Question identity belongs to another task');
+        return key;
+    }, context);
+    const final = await waitForDocument(api, documents, key, context, value => value?.question?.state.kind !== 'pending', async (tx) => {
+        const { question: record } = await tx.doc(documents, api.conversationId, key, null);
+        if (record?.state.kind === 'pending')
+            record.state = { kind: 'cancelled' };
+    }, 'Question');
+    const state = final?.question?.state;
+    if (state?.kind !== 'answered')
+        throw new Error('Question cancelled');
+    return state.answer;
+}
+/**
+ * Resolve an `ask_user` question using `askUserQuestionId(assistantEntryId, callId)` after authenticating the person.
+ * Unscoped model call IDs are accepted only when exactly one native task used them in this conversation.
+ * Exactly one answer is accepted; repeating it is idempotent.
+ */
+export async function answerUserQuestion(conversation, callId, answer, context = BACKGROUND_CONTEXT) {
+    if (typeof callId !== 'string' || !callId || callId.length > 1024)
+        return { kind: 'unknown-question' };
+    if (typeof answer !== 'string')
+        return { kind: 'denied', reason: 'The answer must be text' };
+    const text = answer.trim();
+    try {
+        return await conversation.commit(async (tx) => {
+            const binding = await callBinding(tx, conversation, callId);
+            const task = await tx.task(binding.taskId);
+            if (!task)
+                return { kind: 'conflict', reason: 'The question task is unavailable' };
+            const document = await tx.doc(documents, conversation.id, binding.key, null);
+            if (!document.question) {
+                const legacy = await tx.doc(documents, conversation.id, binding.callId, null);
+                // Throwing rolls back the empty drafts created by an unknown question lookup.
+                if (legacy.question?.taskId !== task.id)
+                    throw new UnknownCall();
+                document.question = { ...legacy.question, options: [...legacy.question.options], state: { ...legacy.question.state } };
+            }
+            const question = document.question;
+            if (question.taskId !== task.id)
+                return { kind: 'conflict', reason: 'The question belongs to another task' };
+            if (task.abortRequested) {
+                question.state = { kind: 'cancelled' };
+                return { kind: 'conflict', reason: 'The question was cancelled' };
+            }
+            if (question.state.kind === 'answered')
+                return question.state.answer === text ? { kind: 'answered' } : { kind: 'conflict', reason: 'The question was already answered' };
+            if (question.state.kind === 'cancelled')
+                return { kind: 'conflict', reason: 'The question was cancelled' };
+            if (task.state.status === 'terminal') {
+                question.state = { kind: 'cancelled' };
+                return { kind: 'conflict', reason: 'The question was cancelled' };
+            }
+            if (!text)
+                return { kind: 'denied', reason: 'The answer is empty' };
+            if (text.length > ASK_USER_MAX_ANSWER)
+                return { kind: 'denied', reason: `The answer is longer than ${ASK_USER_MAX_ANSWER} characters` };
+            if (!question.allowFreeText && !question.options.includes(text))
+                return { kind: 'denied', reason: 'The answer is not one of the options' };
+            question.state = { kind: 'answered', answer: text };
+            return { kind: 'answered' };
+        }, context);
+    }
+    catch (error) {
+        if (error instanceof AmbiguousCall)
+            return { kind: 'conflict', reason: 'Use the assistant-entry-bound question ID' };
+        if (error instanceof UnknownCall)
+            return { kind: 'unknown-question' };
+        throw error;
+    }
+}

package/dist/attachment.d.ts

@@ -0,0 +1,5 @@
+import type { Harness } from '@earendil-works/pi-durable';
+import type { AttachmentInput, BorrowedAttachment } from './contracts.js';
+/** Passive borrowing acquires no observer, storage or execution lifetime. */
+export declare function attachHarness<NativeHarness extends Harness>(input: AttachmentInput<NativeHarness>): BorrowedAttachment<NativeHarness>;
+//# sourceMappingURL=attachment.d.ts.map

package/dist/attachment.js

@@ -0,0 +1,4 @@
+/** Passive borrowing acquires no observer, storage or execution lifetime. */
+export function attachHarness(input) {
+    return { harness: input.harness, detach: async () => { } };
+}

package/dist/browser-task.d.ts

@@ -0,0 +1,32 @@
+import type { Conversation, JsonObject, ToolRegistration } from '@earendil-works/pi-durable';
+import type { TSchema } from '@earendil-works/pi-ai';
+import type { Context } from '@earendil-works/chord';
+import type { AskUserAnswer } from './ask-user.js';
+/** Upper bound on an answer's UTF-8 JSON, by default. */
+export declare const BROWSER_TASK_MAX_ANSWER = 16384;
+/** The answer ID of a browser task call: the same `[assistantEntryId, callId]` binding as `askUserQuestionId`. */
+export declare const browserTaskId: (assistantEntryId: number, callId: string) => string;
+export interface BrowserTaskOptions<P extends TSchema> {
+    readonly name: string;
+    readonly description: string;
+    /** The task the page receives, as the tool's parameters (the page reads them from the call). */
+    readonly parameters: P;
+    /** Refuses an answer the page sent: return the reason, or nothing to accept it. Runs before anything is stored. */
+    readonly checkAnswer: (answer: JsonObject) => string | undefined;
+    /** Default `BROWSER_TASK_MAX_ANSWER`. */
+    readonly maxAnswerBytes?: number;
+}
+/**
+ * A native Pi tool that waits for the person's page to answer, without holding a model request. Pending calls survive a restart
+ * (the replay-safe call re-attaches to its record) and are cancelled with the call when the conversation is stopped. The result
+ * text is the page's answer, as JSON. Answer it with `answerBrowserTask`.
+ */
+export declare function createBrowserTaskTool<P extends TSchema>(options: BrowserTaskOptions<P>): ToolRegistration;
+/**
+ * Settles a pending browser task with the page's answer (a JSON object as text) after the host authenticated the person. `id` is
+ * `browserTaskId(assistantEntryId, callId)` (an unscoped call ID only when exactly one native task used it). The answer goes through
+ * the tool's own `checkAnswer` (pass the same options as the tool). Exactly one answer is accepted; repeating it is idempotent.
+ * Returns the `ask_user` outcome kinds, so one chat transport `answer` serves both.
+ */
+export declare function answerBrowserTask(conversation: Conversation, tool: Pick<BrowserTaskOptions<TSchema>, 'name' | 'checkAnswer' | 'maxAnswerBytes'>, id: string, answer: string, context?: Context): Promise<AskUserAnswer>;
+//# sourceMappingURL=browser-task.d.ts.map