@hachej/boring-agent 0.3.2 → 0.4.1

package/README.md

@@ -134,7 +134,29 @@ Choose the seam by how the text changes and who should see it:
 
 Failure is fail-open and Pi's: a throwing `context` is reported through `HarnessOptions.onReport` and the request goes out without the context (Pi's `hooks.each`, scheduler.js). An aborted turn rethrows. This is advisory text, not policy or authorization; do not use it to enforce a decision. The text is sent to the model provider and gateways or telemetry that log request bodies may see it; the model can quote it into a stored assistant message. Compaction summarizes the stored transcript only, so the context is not folded into summaries. After a crash the hook runs again at recovery, so the value is fresh per attempt, not replayed. Placement: before the round's question when that is the last message; after tool results or an assistant continuation, at the tail. Tests: `test/packages/agent-prompt-context.test.mjs`.
 
-Screen context: a browser can send what the person is looking at with each submit. `createRemoteChat({ requestContext })` adds the returned plain object to the submit body as `context`. In `ChatTransportAccess`, `requestContext(value)` receives it after validation and before `conversation.submit`; a value that is not a plain JSON object of at most 4 KB is `400 invalid-request`, and a host without `requestContext` ignores the field. The host stores `context` by conversation id in `requestContext` and renders it in `createPromptContext({ context })`; the transport keeps nothing. Tests: `test/packages/agent-chat-transport-context.test.mjs`, `test/packages/ui-remote-chat-context.test.mjs`.
+Screen context: a browser can send what the person is looking at with each submit. `createRemoteChat({ requestContext })` adds the returned plain object to the submit body as `context`. In `ChatTransportAccess`, `requestContext(value)` receives it after validation and before `conversation.submit`; a value that is not a plain JSON object of at most 4 KB is `400 invalid-request`, and a host without `requestContext` ignores the field. The host stores `context` by conversation id in `requestContext` and renders it in `createPromptContext({ context })`; the transport keeps nothing. With `useRemoteChat` the context is the `requestContext` value as it is (`name`, `params`: a host written before placement keeps working) plus `placement` (`docked` or `floating`), reported by `PiChat` / `AmbientChat`; `PiChat` takes a `placement` prop for a host that floats it, as the `AgentLayer` does. `renderRequestContext(value)` (from `@hachej/boring-agent/prompt-context`) turns it into the agent's role and the screen for `createPromptContext`; placement changes behaviour, never authority (see [PAGE-TOOLS.md](../../docs/architecture/PAGE-TOOLS.md)). Tests: `test/packages/agent-chat-transport-context.test.mjs`, `test/packages/ui-remote-chat-context.test.mjs`, `test/packages/agent-prompt-context.test.mjs`, `test/contracts/chat-placement.test.mjs`, `test/contracts/chat-placement-registry.test.mjs`.
+
+## Chat over a hibernatable WebSocket
+
+`createConversationSocketHandler` (from `@hachej/boring-agent/chat-transport`) serves the chat transport over WebSockets accepted with the Durable Object Hibernation API, so an idle open page does not keep the object in memory (or billed). One socket carries the watch (the same `view` then `ops` frames as the NDJSON stream) and every call: `{"kind":"call","id","op","params","body"}` is answered by `{"kind":"reply","id","status","body"}` and runs through `createChatTransportHandler` unchanged (validation, `allow`, `project`, `submission-refused`, request-id deduplication). A submit without `whenBusy` is a follow-up when the conversation is busy. `ping` is answered `pong` (on Cloudflare by `setWebSocketAutoResponse`, without waking the object).
+
+Mount it in a Durable Object (any host with the same `acceptWebSocket`/`getWebSockets` and attachment methods works the same):
+
+```js
+sockets = createConversationSocketHandler({ state: this.ctx,
+  // Upgrade only: who and which conversation, kept in the socket's attachment (`serializeAttachment`). Null answers 401.
+  authenticate: async request => ({ owner: personOf(request), conversationId: selectedIn(request) }),
+  // From the attachment alone, at accept and after every wake: the same access the HTTP handler gets.
+  access: async ({ owner, conversationId }) => ({ conversation: await open(owner, conversationId), context }) });
+fetch(request) { if (request.headers.get('upgrade') === 'websocket') return this.sockets.fetch(request); /* ... */ }
+webSocketMessage(socket, message) { return this.sockets.webSocketMessage(socket, message); }
+webSocketClose(socket, code, reason) { return this.sockets.webSocketClose(socket, code, reason); }
+alarm() { void this.sockets.resume(); /* ... */ } // or Lifecycle's host `onStart`
+```
+
+After a wake the in-memory watches are gone; `resume()` (also run by every message and upgrade) reopens each socket's watch from its attachment and sends a complete view first. `broadcast(event, { owner?, conversationId? })` sends host events (`{"kind":"event","event"}`: presence, the conversation list) on the same sockets, and `connections({ owner?, conversationId? })` lists the open sockets' attachments. A browser cannot set headers on a WebSocket: a client offers `boring.chat` as subprotocol (the handler selects it) and a bearer host reads its credential from another offered value, as the Cloudflare recipe does. Pi keeps idle documents and contexts in memory on ten-minute timers by default, and a pending timer keeps a Durable Object from hibernating: open the harness with `settings: { documentRetentionMs: 0, contextRetentionMs: 0 }`.
+
+The client is `createRemoteChat({ transport: 'websocket' })` (or `useRemoteChat({ transport: 'websocket' })`): the controller API is unchanged; unanswered calls are sent again unchanged (same request ID) on the next socket, each socket starts from a complete view, and if the first socket cannot open it uses HTTP. Reused from Cloudflare: the platform Hibernation API itself; the agents SDK `WebSockets` capability (`agents/websockets`) was not used because it is a Lifecycle catch-all that claims every upgrade and speaks the Agent protocol, while this handler must mount in a plain Durable Object too. `PiHarness` leaves "how a session reaches a client" to the host. Tests: `test/packages/agent-chat-socket.test.mjs`; the recipe journey `examples/hosts/cloudflare/journey.mjs` (`CF_HIBERNATION=1` proves hibernation with the socket open).
 
 ## Native questions
 
@@ -160,9 +182,9 @@ The native delivery task is version 2. Existing version 1 records migrate with e
 
 `resolveAccess` may return a Promise. When recovery reads the original actor from native producer input, pass that already-authenticated access as the sixth admission argument: `admit(tx, createProducer, target, taskOptions, context, access)`. Admission captures its identity before awaiting producer creation. Publication still resolves current access and compares the original identity. Omitting the sixth argument preserves resolution during admission; such a resolver must not read the same Harness or call `tx.task` after producer writes. Native transactions reject table reads after their first write. Explicit access is trusted host input, not authentication or a grant. Resolved credential fields are copied before digest, memo and provider awaits.
 
-Run `node examples/background-document.mjs` after building for fictional question, native producer and document delivery without a model, browser or shell. The example resolves a fixed fictional answer in trusted host code; it is not an authenticated remote human journey.
+Run `node fixtures/background-document.mjs` after building for fictional question, native producer and document delivery without a model, browser or shell. The example resolves a fixed fictional answer in trusted host code; it is not an authenticated remote human journey.
 
-Import interfaces with `import type`. See [scaffold guide](../../docs/contracts/SCAFFOLD.md), [native examples](../../examples/native-compositions.ts) and [implementation evidence](../../docs/implementation/PARTIAL.md).
+Import interfaces with `import type`. See [scaffold guide](../../docs/contracts/SCAFFOLD.md), [native examples](../../fixtures/native-compositions.ts) and [implementation evidence](../../docs/implementation/PARTIAL.md).
 
 ## Authorized conversation text
 
@@ -182,7 +204,7 @@ The adapter keeps the last bounded delivered window and no update queue. A slow
 
 TLS, cookies, CORS, socket/proxy lifecycle, browser presentation and deployment authentication remain host qualifications. Public projection tests exercise actual native watches through in-process Fetch/Web Streams. `npm run test:projection-consumer` installs the agent archive without files/UI/execution packages, checks strict declarations, repeats the tests and builds the receiver for a browser. It requires the pinned registry archives in a writable npm cache.
 
-Run `node examples/conversation-projection.mjs` after building for a fictional authenticated stream and idle revocation demonstration.
+Run `node fixtures/conversation-projection.mjs` after building for a fictional authenticated stream and idle revocation demonstration.
 
 ## Authenticated question responses
 
@@ -194,7 +216,7 @@ Responses expose the narrow native decision, with `no-store` headers. An observe
 
 `test/packages/agent-question-response.test.mjs` exercises real native transactions through Fetch requests, including duplicate answers, identity/policy refusal, streamed byte limits, unacknowledged source cancellation and lost response recovery. `npm run test:question-consumer` repeats these scenarios from the installed agent and files tarballs without UI/execution packages; the handler reads bodies through `@hachej/boring-files/request-guard`, so install `@hachej/boring-files` (an optional peer) with this subpath. Set `npm_config_cache` to a writable cache of the pinned dependencies. Socket/browser authentication, remote inbox presentation and human identity-provider integration remain unqualified.
 
-The strict TypeScript consumer recipe additionally installs `@modelcontextprotocol/sdk@1.32.0`. Pinned Pi model declarations transitively load `@google/genai`, whose declarations reference that optional SDK. This dependency is needed for this `skipLibCheck: false` recipe even though the question runtime does not call MCP. The consumer does not establish strict checking with only the agent's declared peers installed.
+The strict TypeScript consumer recipe additionally installs `@modelcontextprotocol/sdk@1.32.1`. Pinned Pi model declarations transitively load `@google/genai`, whose declarations reference that optional SDK. This dependency is needed for this `skipLibCheck: false` recipe even though the question runtime does not call MCP. The consumer does not establish strict checking with only the agent's declared peers installed.
 
 `@hachej/boring-agent/git` exports `createGitTool(repository?)`. Register this ordinary native tool with the same host-created `@hachej/boring-files/git` repository used by Bash or direct callers, or without one: each call then uses the `repository` of its own workspace binding (the one attached to the call's env, see [Workspace per call](#workspace-per-call)), so one tool serves a repository per person. It exposes the local service operations and preserves native ToolTask execution. The tool is always unsafe to replay because working Git has no publication receipts. The repository's host-bound authorization applies on every call. No environment or shell is mandatory for a file-only repository binding.
 
@@ -222,7 +244,7 @@ Native configuration retains tool names. A later registry replacement or native
 
 The resource must be UTF-8 `application/json`, optionally with `charset=utf-8`. The default accepted size is 65,536 bytes; `maxBytes` accepts integers from 1 to 1,048,576. This limits accepted bytes after the reader returns, not provider allocation. The loader preserves borrowed tool/provider ownership and checks an optional abort signal after awaited operations; it cannot interrupt a noncooperative reader or resolver.
 
-Run `node examples/agent-definitions.mjs` after building for a fictional definition, explicit native configuration and real document publication. `npm run test:definitions-consumer` installs files/agent archives with pinned registry dependencies, checks strict declarations and repeats exact-read, native publication, reopen and registry-replacement tests. Like the question consumer, this strict fixture explicitly installs the pinned optional model SDK declaration dependencies.
+Run `node fixtures/agent-definitions.mjs` after building for a fictional definition, explicit native configuration and real document publication. `npm run test:definitions-consumer` installs files/agent archives with pinned registry dependencies, checks strict declarations and repeats exact-read, native publication, reopen and registry-replacement tests. Like the question consumer, this strict fixture explicitly installs the pinned optional model SDK declaration dependencies.
 
 ## Structured output and native tool evidence
 
@@ -238,7 +260,7 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 ## Asking the person
 
-`@hachej/boring-agent/ask-user` exports `createAskUserTool()`, a replay-safe native tool named `ask_user` with arguments `{ question, options?: string[2..6], allowFreeText? }`. The call waits on a conversation document keyed by its assistant entry and tool call ID, so no model request is held, a pending question survives a restart and stopping the conversation cancels it. A trusted host resolves it with `answerUserQuestion(conversation, askUserQuestionId(assistantEntryId, callId), answer)` (pass the scoped ID through `ChatTransportAccess.answer` after authenticating the person): the answer must be an option unless free text is allowed, at most 2000 characters; one answer wins, repeating it is idempotent. The tool result is `{"kind":"answered","answer":"..."}`. The chat transport also serves `?op=answer` and `?op=withdraw` (a queued message, by submission ID), both gated by `allow`. Like browser tasks and `requireApproval`-gated tools, it is `callers: ['model']`: the wait binds to the calling model entry, so Pi refuses a nested `api.executeTool` call (`tool_unavailable`) until nested bindings are supported.
+`@hachej/boring-agent/ask-user` exports `createAskUserTool()`, a replay-safe native tool named `ask_user` with arguments `{ question, options?: string[2..6], allowFreeText?, questions?: { question, options? }[1..8] }`. Free text is accepted unless `allowFreeText` is `false`; `questions` makes one form answered as one free text that lists each question and its answer (the `pi-chat` question card renders it). The call waits on a conversation document keyed by its assistant entry and tool call ID, so no model request is held, a pending question survives a restart and stopping the conversation cancels it. A trusted host resolves it with `answerUserQuestion(conversation, askUserQuestionId(assistantEntryId, callId), answer)` (pass the scoped ID through `ChatTransportAccess.answer` after authenticating the person): the answer must be an option when `allowFreeText` is `false`, at most 2000 characters; one answer wins, repeating it is idempotent. The tool result is `{"kind":"answered","answer":"..."}`. The chat transport also serves `?op=answer` and `?op=withdraw` (a queued message, by submission ID), both gated by `allow`. Like browser tasks and `requireApproval`-gated tools, it is `callers: ['model']`: the wait binds to the calling model entry, so Pi refuses a nested `api.executeTool` call (`tool_unavailable`) until nested bindings are supported.
 
 ## Browser tasks
 
@@ -248,6 +270,16 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 `createSkillsExtension` tells the model that a user message starting with `/<skill-name>` is an explicit request to load that skill first, which is what the chat's `/` menu inserts. `defineAgent(...).skills` lists each skill's name and description for such a menu.
 
+## Sub-agents and schedules
+
+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.
+
+**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.
+
+**Storage conformance.** Boring ships no Pi `Storage` implementation. `test/packages/pi-storage-conformance.test.mjs` runs Pi's own suite (`createStorageConformance`, what `registerStorageConformance` registers with Vitest) on every storage the repository configures: `openPiStorage` (shared/pi-storage.mjs) on the local-disk and network-file-system presets, Pi's `SqliteStorage` over `openBrowserSqlite`, and Pi's `openDurableObjectSqliteStorage` on a SQLite-backed Durable Object in workerd through miniflare (the version the pinned wrangler resolves).
+
 ## Tools from a JSON Schema
 
 `jsonSchemaTool({ name, description, parameters, execute, ... })` from `@hachej/boring-agent/agents` makes a native tool registration from a raw JSON Schema (an MCP server's `inputSchema`, an agent-written `.agent/tools/*.json`) with typebox's `Type.Unsafe`, so no `as unknown as TSchema` cast is needed. It refuses a schema that is not `"type": "object"` and adds an empty `properties` when there is none. It validates nothing itself: the Harness already validates every call's arguments against `parameters` before `execute` (Pi's `validateToolArguments`, which compiles plain JSON Schema with typebox) and answers a mismatch with an `invalid_arguments` error result naming the fields, before an approval gate is asked. The studio's MCP recipe and self-evolution use it; their journeys send one call with a missing required argument each.

package/dist/agents.d.ts

@@ -2,12 +2,15 @@ import type { AgentChange, Conversation, ConversationCreateOptions, Extension, H
 import type { Context } from '@earendil-works/chord';
 import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
 import type { SelfEvolutionReport } from './self-evolving.js';
+import type { DelegateOptions } from './delegate.js';
 import type { Skill } from './skills.js';
 export type { SelfEvolutionError, SelfEvolutionReport } from './self-evolving.js';
 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';
 /** 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>`. */
@@ -20,6 +23,13 @@ export interface AgentSpec {
     /** Additional native extensions this agent selects, for example Pi's `CodingTools`. */
     readonly extensions?: readonly Extension[];
     readonly skills?: readonly Skill[];
+    /**
+     * Sub-agents this agent may hand a task to: each becomes a `delegate` tool (`createDelegateTool`) among this agent's tools, and
+     * `install` installs the child agent's extensions too. The child runs in a conversation owned by the tool call, with only its own tools.
+     */
+    readonly delegates?: readonly (DelegateOptions & {
+        readonly agent: DefinedAgent;
+    })[];
     /** Directory within the harness environment. */
     readonly cwd?: string;
     /**

package/dist/agents.js

@@ -2,8 +2,10 @@ import { createHash } from 'node:crypto';
 import { 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';
 /** Turn an agent described as data into native extensions and a native agent configuration. */
 export function defineAgent(spec) {
     if (!NAME.test(spec.id))
@@ -13,16 +15,17 @@ export function defineAgent(spec) {
     // Self-evolving (SELF-3): Pi renders native `instructions` after every extension section, so the host's instructions become the first
     // section of the agent's own (first) extension instead, and the agent-written section, in the last extension, comes after them.
     const base = spec.selfEvolving && spec.instructions !== undefined ? spec.instructions : undefined;
+    const tools = [...spec.tools ?? [], ...(spec.delegates ?? []).map(createDelegateTool)];
     const own = [];
-    if (spec.tools?.length || base !== undefined) {
-        own.push(defineExtension({ name: `agent.${spec.id}`, tools: [...spec.tools ?? []], sections: base === undefined ? [] : [{ key: 'host-instructions', render: () => base }] }));
+    if (tools.length || base !== undefined) {
+        own.push(defineExtension({ name: `agent.${spec.id}`, tools, sections: base === undefined ? [] : [{ key: 'host-instructions', render: () => base }] }));
     }
     // The skills of a self-evolving agent live in its per-workspace extension, so agent-written skills join them on reload. Without a
     // workspace (a self-evolving agent whose workspace is chosen per conversation, before `inWorkspace`) they stay the host's alone.
     const evolving = spec.selfEvolving === true && spec.workspace !== undefined;
     const hostSkills = spec.skills?.length && !evolving ? [createSkillsExtension(`agent.${spec.id}.skills`, spec.skills)] : [];
     const listed = (skills) => Object.freeze(skills.map(skill => Object.freeze({ name: skill.name, description: skill.description.trim() })));
-    const reserved = [...(spec.tools ?? []), ...(spec.extensions ?? []).flatMap(extension => extension.tools ?? [])].map(tool => tool.name);
+    const reserved = [...tools, ...(spec.extensions ?? []).flatMap(extension => extension.tools ?? [])].map(tool => tool.name);
     /** The agent as one native configuration: its own extensions, the host's, and with `evolution` the per-workspace one last. */
     function assemble(selected, evolution, inWorkspace) {
         const initial = evolution?.current();
@@ -39,12 +42,16 @@ export function defineAgent(spec) {
         return Object.freeze({
             id: spec.id, extensions, agent,
             get skills() { return evolution ? listed(evolution.skills()) : fixedSkills; },
-            install: (registry) => { for (const extension of extensions) {
-                if (extension === initial)
-                    evolution.install(registry);
-                else
-                    registry.install(extension);
-            } },
+            install: (registry) => {
+                for (const delegate of spec.delegates ?? [])
+                    delegate.agent.install(registry);
+                for (const extension of extensions) {
+                    if (extension === initial)
+                        evolution.install(registry);
+                    else
+                        registry.install(extension);
+                }
+            },
             ...(evolution ? { reload: evolution.reload } : {}),
             createConversation: (harness, context, options = {}) => harness.createConversation({ ownership: options.ownership ?? { kind: 'ownerless' }, agent, ...(options.init ? { init: options.init } : {}) }, context),
             ...(inWorkspace ? { inWorkspace } : {}),

package/dist/ask-user.js

@@ -15,8 +15,8 @@ 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';
+    if (options === undefined && allowFreeText === false)
+        return 'give options, or allow free text';
     return undefined;
 }
 /**
@@ -28,20 +28,27 @@ function refusal(options, allowFreeText) {
 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.',
+        description: options.description ?? 'Ask the person a question and wait for their answer. Give 2 to 6 short options when the answer is a choice; the person may also answer in their own words unless allowFreeText is false. To ask several related questions at once, give them as `questions` (up to 8, each with its own options): the person answers them in one form, may skip some, and the answer lists each question with its answer.',
         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()),
+            questions: Type.Optional(Type.Array(Type.Object({
+                question: Type.String({ minLength: 1, maxLength: 1000 }),
+                options: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 200 }), { minItems: 2, maxItems: 6 })),
+            }, { additionalProperties: false }), { minItems: 1, maxItems: 8 })),
         }, { additionalProperties: false }),
         replay: 'safe',
         // The wait binds to the calling model entry and call id; a nested `api.executeTool` caller has neither (see durable-wait.ts).
         callers: ['model'],
         execute: async (args, api, context) => {
-            const problem = refusal(args.options, args.allowFreeText);
+            // A form (`questions`) is answered as one free text that lists each question and its answer.
+            const form = args.questions?.length ? args.questions : undefined;
+            const problem = form ? form.map(item => refusal(item.options, true)).find(Boolean) : refusal(args.options, args.allowFreeText);
             if (problem)
                 return { isError: true, output: [{ type: 'text', text: `Invalid question: ${problem}.` }] };
-            const answer = await askPerson(api, context, { prompt: args.question, ...(args.options === undefined ? {} : { options: args.options }), allowFreeText: args.allowFreeText === true });
+            const prompt = form ? [args.question, ...form.map((item, i) => `${i + 1}. ${item.question}`)].join('\n') : args.question;
+            const answer = await askPerson(api, context, { prompt, ...(form || args.options === undefined ? {} : { options: args.options }), allowFreeText: form ? true : args.allowFreeText !== false });
             return { output: [{ type: 'text', text: JSON.stringify({ kind: 'answered', answer }) }] };
         },
     });

package/dist/chat-transport.d.ts

@@ -85,4 +85,81 @@ export declare function createChatTransportHandler(options: ChatTransportOptions
  * idempotent on `requestId`, as native submission is.
  */
 export declare function routeSubmissions(conversation: Conversation, admit: (draft: InputSubmissionDraft, context: Context) => Promise<unknown>): Conversation;
+/**
+ * A WebSocket accepted with the Durable Object Hibernation API (`ctx.acceptWebSocket`): the members this handler uses. Any host
+ * with the same shape can mount it (tests use an in-memory one).
+ */
+export interface HibernatableSocket {
+    send(message: string): void;
+    close(code?: number, reason?: string): void;
+    serializeAttachment(value: unknown): void;
+    deserializeAttachment(): unknown;
+}
+/** The Hibernation API of a Durable Object's `ctx` (`DurableObjectState`) that the handler uses. */
+export interface HibernationState {
+    acceptWebSocket(socket: HibernatableSocket, tags?: string[]): void;
+    getWebSockets(tag?: string): HibernatableSocket[];
+    setWebSocketAutoResponse?(pair?: unknown): void;
+}
+/**
+ * Per-socket state, kept in the socket's attachment so it survives hibernation. `owner` and `conversationId` are the host's
+ * (who the socket acts for, which conversation it watches); further JSON fields are the host's to add. `socketId` is the handler's.
+ */
+export interface ConversationSocketAttachment {
+    readonly owner: string;
+    readonly conversationId: string;
+    readonly [key: string]: unknown;
+}
+export interface ConversationSocketOptions {
+    /** The Durable Object's `ctx`, or any object with the same Hibernation API. */
+    readonly state: HibernationState;
+    /**
+     * Authenticate the upgrade request and select the conversation, in trusted host code (also the Origin policy: a browser sends
+     * cookies with a cross-site upgrade). Null refuses with 401 before any socket is accepted. The result becomes the attachment.
+     */
+    readonly authenticate: (request: Request) => Promise<ConversationSocketAttachment | null>;
+    /**
+     * The conversation access for a socket, from its attachment alone: called when the socket is accepted and again after every
+     * 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>;
+}
+/** 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";
+export interface ConversationSocketHandler {
+    /** Cloudflare upgrade: authenticate, create the `WebSocketPair`, accept the server end and answer 101 (401 when refused). */
+    readonly fetch: (request: Request) => Promise<Response>;
+    /** Accept a socket the host created: tag it with its owner and conversation, store the attachment and send the first view. False when refused. */
+    readonly accept: (socket: HibernatableSocket, request: Request) => Promise<boolean>;
+    /** The Durable Object's `webSocketMessage`. */
+    readonly webSocketMessage: (socket: HibernatableSocket, message: string | ArrayBuffer) => Promise<void>;
+    /** The Durable Object's `webSocketClose` (and `webSocketError`): stops the socket's watch. */
+    readonly webSocketClose: (socket: HibernatableSocket, code?: number, reason?: string) => Promise<void>;
+    /**
+     * Reopen the watch of every accepted socket that has none in memory: after a wake from hibernation each socket receives a
+     * complete view again, then deltas. Messages and upgrades call it; a host also calls it when the object wakes for another
+     * reason (an alarm), so a resumed run reaches open pages. Idempotent.
+     */
+    readonly resume: () => Promise<void>;
+    /** Send a host event (`{"kind":"event","event":...}`, for example presence or the conversation list) to the sockets of an owner or conversation, or all. */
+    readonly broadcast: (event: unknown, to?: {
+        readonly owner?: string;
+        readonly conversationId?: string;
+    }) => void;
+    /** The attachments of the open sockets, optionally by owner or conversation: presence is these. */
+    readonly connections: (to?: {
+        readonly owner?: string;
+        readonly conversationId?: string;
+    }) => ConversationSocketAttachment[];
+}
+/**
+ * The chat transport over hibernatable WebSockets, for a Durable Object (`ctx.acceptWebSocket`). One socket carries the watch (the
+ * same `view` then `ops` frames as the NDJSON stream) and every call (`{"kind":"call","id","op","params","body"}`, answered by
+ * `{"kind":"reply","id","status","body"}`), which runs through `createChatTransportHandler` unchanged: the same validation,
+ * `allow`, `project` and request-id deduplication. A submit without `whenBusy` is a follow-up when the conversation is busy.
+ * Nothing in memory is needed between messages: the attachment holds the socket's owner and conversation, so an idle page lets
+ * the object hibernate, and a wake reopens the watches with a complete view. `ping` is answered `pong` (on Cloudflare by the
+ * platform's auto-response, without waking the object).
+ */
+export declare function createConversationSocketHandler(options: ConversationSocketOptions): ConversationSocketHandler;
 //# sourceMappingURL=chat-transport.d.ts.map

package/dist/chat-transport.js

@@ -33,8 +33,8 @@ async function body(request) {
  */
 function reads(conversation, context, project) {
     return {
-        async entries(limit, cursor) {
-            const page = await conversation.entries({}, limit, cursor, context);
+        async entries(query, limit, cursor) {
+            const page = await conversation.entries(query, limit, cursor, context);
             if (!project)
                 return page;
             const record = await conversation.commit(tx => tx.conversation(conversation.id), context);
@@ -60,6 +60,19 @@ function reads(conversation, context, project) {
         },
     };
 }
+/** Serialize one watch frame; with `project` a view is projected first (a throw means `projection_failed`). */
+function encodeFrame(frame, project) {
+    return JSON.stringify(frame.kind === 'view' && project ? { kind: 'view', view: project(frame.view) } : frame);
+}
+/** Open the conversation watch for an authenticated access, refusing a revoked one. Shared by the HTTP watch and the socket. */
+async function openWatch(access, signal) {
+    const watch = await access.conversation.watch(access.context);
+    if (signal?.aborted || access.revoked?.aborted) {
+        await watch.stop();
+        return null;
+    }
+    return watch;
+}
 /**
  * Stream newline-delimited JSON. A trusted viewer receives one view and then the exact native operation batches,
  * replayed in the browser with `@earendil-works/chord/delta`. With `project`, raw operations never leave the host:
@@ -107,7 +120,7 @@ function stream(watch, project, signal, heartbeatMs) {
             if (frame) {
                 let line;
                 try {
-                    line = JSON.stringify(frame.kind === 'view' && project ? { kind: 'view', view: project(frame.view) } : frame);
+                    line = encodeFrame(frame, project);
                 }
                 catch {
                     finished = true;
@@ -177,11 +190,9 @@ export function createChatTransportHandler(options) {
         try {
             if (request.method === 'GET' && operation === 'watch') {
                 const signal = access.revoked ? AbortSignal.any([request.signal, access.revoked]) : request.signal;
-                const watch = await conversation.watch(context);
-                if (signal.aborted) {
-                    await watch.stop();
+                const watch = await openWatch(access, signal);
+                if (!watch)
                     return failure(403, 'not-authorized');
-                }
                 return stream(watch, access.project, signal, options.heartbeatMs ?? CHAT_TRANSPORT.heartbeatMs);
             }
             if (request.method === 'GET' && operation === 'submission') {
@@ -207,7 +218,19 @@ export function createChatTransportHandler(options) {
                         return failure(400, 'invalid-request');
                     }
                 }
-                const page = await read.entries(limit, cursor);
+                const entryId = (encoded) => {
+                    if (encoded === null)
+                        return undefined;
+                    const value = Number(encoded);
+                    if (!Number.isSafeInteger(value) || value < 1)
+                        throw new RequestGuardError(400, 'Invalid native entry bound');
+                    return value;
+                };
+                const maxEntryId = entryId(params.get('maxEntryId')), minEntryId = entryId(params.get('minEntryId'));
+                const order = params.get('order');
+                if (order !== null && order !== 'ascending' && order !== 'descending')
+                    return failure(400, 'invalid-request');
+                const page = await read.entries({ ...(maxEntryId === undefined ? {} : { maxEntryId }), ...(minEntryId === undefined ? {} : { minEntryId }), ...(order === null ? {} : { order }) }, limit, cursor);
                 if (access.revoked?.aborted)
                     return failure(403, 'not-authorized');
                 return json({ page });
@@ -317,3 +340,177 @@ export function routeSubmissions(conversation, admit) {
             return typeof value === 'function' ? value.bind(target) : value;
         } });
 }
+/** 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';
+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;
+/**
+ * The chat transport over hibernatable WebSockets, for a Durable Object (`ctx.acceptWebSocket`). One socket carries the watch (the
+ * same `view` then `ops` frames as the NDJSON stream) and every call (`{"kind":"call","id","op","params","body"}`, answered by
+ * `{"kind":"reply","id","status","body"}`), which runs through `createChatTransportHandler` unchanged: the same validation,
+ * `allow`, `project` and request-id deduplication. A submit without `whenBusy` is a follow-up when the conversation is busy.
+ * Nothing in memory is needed between messages: the attachment holds the socket's owner and conversation, so an idle page lets
+ * the object hibernate, and a wake reopens the watches with a complete view. `ping` is answered `pong` (on Cloudflare by the
+ * platform's auto-response, without waking the object).
+ */
+export function createConversationSocketHandler(options) {
+    const { state } = options;
+    const Pair = globalThis.WebSocketRequestResponsePair;
+    if (Pair && state.setWebSocketAutoResponse)
+        state.setWebSocketAutoResponse(new Pair('ping', 'pong'));
+    /** Live watches by socket id, in memory only: empty after a wake, refilled by `attach`. */
+    const live = new Map();
+    const attachment = (socket) => socket.deserializeAttachment();
+    const send = (socket, value) => { try {
+        socket.send(value);
+    }
+    catch { /* the socket closed meanwhile */ } };
+    const end = (socket, reason, code = 1000) => {
+        send(socket, JSON.stringify({ kind: 'end', reason }));
+        try {
+            socket.close(code, reason);
+        }
+        catch { /* already closed */ }
+    };
+    function attach(socket) {
+        const found = attachment(socket);
+        if (!found)
+            return Promise.resolve(null);
+        let entry = live.get(found.socketId);
+        if (entry)
+            return entry;
+        entry = (async () => {
+            let access;
+            try {
+                access = await options.access(found);
+            }
+            catch {
+                access = null;
+            }
+            if (!access) {
+                live.delete(found.socketId);
+                end(socket, 'revoked', 1008);
+                return null;
+            }
+            const watch = await openWatch(access).catch(() => null);
+            if (!watch) {
+                live.delete(found.socketId);
+                end(socket, 'revoked', 1008);
+                return null;
+            }
+            const { project } = access;
+            const frame = (value) => {
+                try {
+                    send(socket, encodeFrame(value, project));
+                }
+                catch {
+                    void watch.stop();
+                    end(socket, 'projection_failed', 1011);
+                }
+            };
+            frame({ kind: 'view', view: watch.value });
+            access.revoked?.addEventListener('abort', () => { void watch.stop(); }, { once: true });
+            watch.start(async (view, ops) => frame(project ? { kind: 'view', view } : { kind: 'ops', ops }));
+            void watch.closed.then(result => {
+                if (live.get(found.socketId) !== entry)
+                    return;
+                live.delete(found.socketId);
+                // A host restart (`session_closed`) asks the client to reconnect; the other reasons are final.
+                end(socket, access.revoked?.aborted ? 'revoked' : result.reason, result.reason === 'session_closed' ? 1012 : 1000);
+            });
+            return { access, watch };
+        })();
+        live.set(found.socketId, entry);
+        return entry;
+    }
+    async function resume() { await Promise.all(state.getWebSockets().map(socket => attach(socket))); }
+    async function accept(socket, request) {
+        const found = await options.authenticate(request);
+        if (!found)
+            return false;
+        state.acceptWebSocket(socket, [ownerTag(found.owner), conversationTag(found.conversationId)]);
+        socket.serializeAttachment({ ...found, socketId: crypto.randomUUID() });
+        void resume();
+        return true;
+    }
+    async function call(socket, frame) {
+        const entry = await attach(socket);
+        if (!entry)
+            return;
+        const url = new URL('https://socket.invalid/');
+        for (const [key, value] of Object.entries(frame.params ?? {}))
+            if (typeof value === 'string')
+                url.searchParams.set(key, value);
+        url.searchParams.set('op', frame.op);
+        let body = frame.body;
+        if (frame.op === 'submit' && body !== null && typeof body === 'object' && !Array.isArray(body) && body['whenBusy'] === undefined)
+            body = { ...body, whenBusy: 'followUp' };
+        let response;
+        if (frame.op === 'watch')
+            response = failure(400, 'invalid-request');
+        else {
+            // The HTTP handler, unchanged, with this socket's access: the same checks, `allow`, `project` and request-id deduplication.
+            const handler = createChatTransportHandler({ authenticate: async () => entry.access });
+            response = await handler(new Request(url, body === undefined ? {} : { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }));
+        }
+        const reply = await response.json().catch(() => null);
+        send(socket, JSON.stringify({ kind: 'reply', id: frame.id, status: response.status, body: reply }));
+    }
+    return {
+        accept,
+        resume,
+        async fetch(request) {
+            if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket')
+                return failure(426, 'upgrade-required');
+            const Socket = globalThis.WebSocketPair;
+            if (!Socket)
+                return failure(501, 'not-supported');
+            const pair = new Socket();
+            let accepted;
+            try {
+                accepted = await accept(pair[1], request);
+            }
+            catch {
+                return failure(503, 'authentication-unavailable');
+            }
+            if (!accepted)
+                return failure(401, 'authentication-required');
+            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 } } : {}) });
+        },
+        async webSocketMessage(socket, message) {
+            if (message === 'ping')
+                return send(socket, 'pong');
+            let frame;
+            try {
+                frame = JSON.parse(typeof message === 'string' ? message : new TextDecoder().decode(message));
+            }
+            catch {
+                return;
+            }
+            if (frame?.kind !== 'call' || typeof frame.id !== 'string' || typeof frame.op !== 'string')
+                return;
+            void resume();
+            await call(socket, frame);
+        },
+        async webSocketClose(socket, code, reason) {
+            const found = attachment(socket);
+            const entry = found ? live.get(found.socketId) : undefined;
+            if (found)
+                live.delete(found.socketId);
+            const opened = await entry?.catch(() => null);
+            await opened?.watch?.stop();
+            try {
+                socket.close(code === undefined || code === 1005 || code === 1006 || code === 1015 ? 1000 : code, reason);
+            }
+            catch { /* already closed */ }
+        },
+        broadcast(event, to) {
+            const text = JSON.stringify({ kind: 'event', event });
+            for (const socket of state.getWebSockets(tagFor(to)))
+                send(socket, text);
+        },
+        connections: to => state.getWebSockets(tagFor(to)).flatMap(socket => { const found = attachment(socket); return found ? [found] : []; }),
+    };
+}

package/dist/delegate.d.ts

@@ -0,0 +1,24 @@
+import type { AgentChange, ToolRegistration } from '@earendil-works/pi-durable';
+export declare const DELEGATE_TOOL = "delegate";
+export interface DelegateOptions {
+    /**
+     * The child agent, usually a `defineAgent` result (its `id` and native `agent` change). The child conversation selects exactly its
+     * extensions, model and instructions: its tools are the whole toolset. Its extensions must be installed in the registry.
+     */
+    readonly agent: {
+        readonly id: string;
+        readonly agent: AgentChange;
+    };
+    /** Tool name; default `delegate`. Give each delegate of one agent its own name. */
+    readonly name?: string;
+    readonly description?: string;
+}
+/**
+ * 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.
+ */
+export declare function createDelegateTool(options: DelegateOptions): ToolRegistration;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.js

@@ -0,0 +1,44 @@
+import { AssistantEntry, configure, defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+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.
+ */
+export function createDelegateTool(options) {
+    const name = options.name ?? DELEGATE_TOOL;
+    // A task-owned conversation starts as a copy of its owner's agent; reset the inherited filters so the child's own extensions are
+    // its whole toolset, then apply the child agent. `cwd` stays inherited unless the child agent sets one.
+    const child = { tools: null, modelTools: null, instructions: null, thinkingLevel: null, ...options.agent.agent };
+    return defineTool({
+        name,
+        description: options.description ?? `Delegate a self-contained task to the ${options.agent.id} agent and get its final answer back.`,
+        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 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);
+                return created.id;
+            }, context);
+            await api.details({ conversationId: childId }, 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 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 } };
+        },
+    });
+}

package/dist/prompt-context.d.ts

@@ -22,4 +22,13 @@ export interface PromptContextOptions {
  */
 export declare function withRequestContext(messages: readonly Message[], text: string, tag?: string): Message[];
 export declare function createPromptContext(options: PromptContextOptions): Extension;
+/**
+ * The text for the browser's request context: the screen's `{ name, params }` with `placement` beside them, as `useRemoteChat` sends it
+ * (an older client sends only `{ name, params }`, which still renders; a `{ screen }` wrapper is read too). The host calls this in
+ * `createPromptContext({ context })` on the value it stored by conversation id. `placement` is `docked` or `floating` and picks the
+ * agent's role. Both are advisory text from the browser: placement changes behaviour and never authority (a docked agent writes no
+ * more than a floating one), and anything else in the value is ignored.
+ * See docs/architecture/PAGE-TOOLS.md (PLACE-1..3).
+ */
+export declare function renderRequestContext(value: unknown): string | undefined;
 //# sourceMappingURL=prompt-context.d.ts.map

package/dist/prompt-context.js

@@ -36,3 +36,29 @@ export function createPromptContext(options) {
             })],
     });
 }
+const ROLES = {
+    docked: 'The chat is docked beside the page: you lead. Open the pages, records and files that answer the question in the viewer, and say what you opened.',
+    floating: 'The chat floats over the page: the person leads. Do not move the page unless asked; answer briefly about what is on screen and suggest where to go.',
+};
+/**
+ * The text for the browser's request context: the screen's `{ name, params }` with `placement` beside them, as `useRemoteChat` sends it
+ * (an older client sends only `{ name, params }`, which still renders; a `{ screen }` wrapper is read too). The host calls this in
+ * `createPromptContext({ context })` on the value it stored by conversation id. `placement` is `docked` or `floating` and picks the
+ * agent's role. Both are advisory text from the browser: placement changes behaviour and never authority (a docked agent writes no
+ * more than a floating one), and anything else in the value is ignored.
+ * See docs/architecture/PAGE-TOOLS.md (PLACE-1..3).
+ */
+export function renderRequestContext(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { placement, screen } = value;
+    const lines = [];
+    if (placement === 'docked' || placement === 'floating')
+        lines.push(`Placement: ${placement}. ${ROLES[placement]}`);
+    const shown = typeof screen === 'object' && screen !== null ? screen : value;
+    if (typeof shown.name === 'string') {
+        const { name, params } = shown;
+        lines.push(`The person is looking at: ${name}${params && typeof params === 'object' && Object.keys(params).length ? ` ${JSON.stringify(params)}` : ''}`);
+    }
+    return lines.length ? lines.join('\n') : undefined;
+}

package/dist/schedule.d.ts

@@ -0,0 +1,77 @@
+import type { ConversationId, DocumentReader, Extension, TaskId, TaskInspection, Tx } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+export declare const SCHEDULE_TOOL = "schedule";
+export declare const LIST_SCHEDULES_TOOL = "list_schedules";
+export declare const CANCEL_SCHEDULE_TOOL = "cancel_schedule";
+/** Entry kind of a delivered instruction: typed provenance, so a viewer can tell it from a person's message. */
+export declare const SCHEDULED_INPUT_KIND = "boring.schedule.delivery";
+export type ScheduleRecord = {
+    /** Stable id the model lists and cancels by. */
+    readonly id: string;
+    /** Idempotency key: scheduling again with it returns this schedule instead of creating another. */
+    readonly operationId: string;
+    readonly instruction: string;
+    /** Unix milliseconds. */
+    readonly runAt: number;
+    readonly taskId: TaskId;
+    readonly cancelled?: boolean;
+};
+type DeliveryInput = {
+    id: string;
+    conversationId: ConversationId;
+    instruction: string;
+    runAt: number;
+};
+type DeliveryState = {
+    phase: 'wait';
+} | {
+    phase: 'deliver';
+};
+/** Pending schedules of one conversation. Forks start empty: a schedule belongs to the conversation that made it. */
+export declare const ConversationSchedules: import("@earendil-works/pi-durable").ConversationDocToken<{
+    items: ScheduleRecord[];
+    next: number;
+}>;
+/**
+ * The native durable task behind one schedule: it sleeps on the Harness clock (`runtime.sleep`), then delivers the instruction to
+ * its conversation as a follow-up input whose request id is the schedule id, so a replayed delivery never submits twice. Owned by
+ * the conversation as background work: a person stopping the current turn does not cancel it. No second scheduler: Pi's own
+ * scheduler runs it, and a restart resumes it.
+ */
+export declare const ScheduledDelivery: import("@earendil-works/pi-durable").Task<DeliveryInput, DeliveryState, {
+    delivered: boolean;
+}, object>;
+/**
+ * Create a schedule in a commit, or return the one `operationId` already made in this conversation. For hosts that schedule
+ * outside a tool (an API route); the `schedule` tool calls it too.
+ */
+export declare function addSchedule(tx: Tx, conversationId: ConversationId, request: {
+    readonly operationId: string;
+    readonly instruction: string;
+    readonly runAt: number;
+}): Promise<ScheduleRecord>;
+/** Mark a pending schedule of this conversation cancelled; its task wakes and ends without delivering. False when there is none. */
+export declare function cancelSchedule(tx: Tx, conversationId: ConversationId, id: string): Promise<boolean>;
+/** Pending, uncancelled schedules of one conversation, soonest first. */
+export declare function listSchedules(reader: DocumentReader, conversationId: ConversationId, context: Context): Promise<ScheduleRecord[]>;
+/**
+ * The deadline of a schedule task that is still sleeping, from `harness.inspect()`; `undefined` for every other task. A host with
+ * one wake-up timer (a Durable Object alarm) sets it to the earliest deadline, and wakes Pi then; the deadlines stay Pi's tasks.
+ */
+export declare function scheduledDeadline(task: TaskInspection): number | undefined;
+export interface ScheduleExtensionOptions {
+    /** The clock deadlines are computed on; give the Harness's own `now`. Default `Date.now`. */
+    readonly now?: () => number;
+    /** Called with each new (or returned) deadline, so a host with one wake-up timer can move it earlier. */
+    readonly onDeadline?: (runAt: number, context: Context) => void | Promise<void>;
+    /** Longest delay accepted; default 366 days. */
+    readonly maxDelaySeconds?: number;
+}
+/**
+ * `schedule`, `list_schedules` and `cancel_schedule` plus the delivery task, as one native extension. A conversation lists and
+ * cancels only its own schedules. `schedule` is idempotent on `operationId` (default: the tool task, so a replayed call returns
+ * the schedule it made).
+ */
+export declare function createScheduleExtension(options?: ScheduleExtensionOptions): Extension;
+export {};
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.js

@@ -0,0 +1,191 @@
+import { defineDoc, defineExtension, defineTask, defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import { withAbortSignal } from '@earendil-works/chord/context';
+export const SCHEDULE_TOOL = 'schedule';
+export const LIST_SCHEDULES_TOOL = 'list_schedules';
+export const CANCEL_SCHEDULE_TOOL = 'cancel_schedule';
+/** Entry kind of a delivered instruction: typed provenance, so a viewer can tell it from a person's message. */
+export const SCHEDULED_INPUT_KIND = 'boring.schedule.delivery';
+const MAX_DELAY_SECONDS = 366 * 24 * 60 * 60;
+const MAX_INSTRUCTION = 4000;
+const TIMEZONE_SUFFIX = /(?:Z|[+-]\d{2}:\d{2})$/i;
+/** Pending schedules of one conversation. Forks start empty: a schedule belongs to the conversation that made it. */
+export const ConversationSchedules = defineDoc({
+    kind: 'boring.schedules', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', initial: () => ({ items: [], next: 1 }),
+});
+const remove = (items, id) => { const index = items.findIndex(item => item.id === id); if (index !== -1)
+    items.splice(index, 1); };
+/** Sleep on the Harness clock until `runAt`; true when the schedule was cancelled first. */
+async function sleepUnlessCancelled(runtime, input, context) {
+    const cancelledIn = (value) => value?.items.find(item => item.id === input.id)?.cancelled === true;
+    const watch = await runtime.watchDoc(ConversationSchedules, input.conversationId, context);
+    if (watch === undefined)
+        return false;
+    const cancel = new AbortController();
+    try {
+        if (cancelledIn(watch.value))
+            return true;
+        watch.start(async (value) => { if (cancelledIn(value))
+            cancel.abort(); });
+        await runtime.sleep(input.runAt, withAbortSignal(cancel.signal, context));
+        return false;
+    }
+    catch (error) {
+        if (cancel.signal.aborted)
+            return true;
+        throw error;
+    }
+    finally {
+        await watch.stop();
+    }
+}
+/**
+ * The native durable task behind one schedule: it sleeps on the Harness clock (`runtime.sleep`), then delivers the instruction to
+ * its conversation as a follow-up input whose request id is the schedule id, so a replayed delivery never submits twice. Owned by
+ * the conversation as background work: a person stopping the current turn does not cancel it. No second scheduler: Pi's own
+ * scheduler runs it, and a restart resumes it.
+ */
+export const ScheduledDelivery = defineTask({
+    name: 'boring.schedule.deliver',
+    version: 1,
+    initial: () => ({ phase: 'wait' }),
+    phases: {
+        wait: async (task, runtime, context) => {
+            if (await sleepUnlessCancelled(runtime, task.input, context)) {
+                await runtime.commit(async (tx) => {
+                    remove((await tx.doc(ConversationSchedules, task.input.conversationId)).items, task.input.id);
+                    return { status: 'terminal', outcome: { status: 'completed', result: { delivered: false } } };
+                }, context);
+                return;
+            }
+            await runtime.commit(() => ({ status: 'running', checkpoint: { phase: 'deliver' } }), context);
+        },
+        deliver: async (task, runtime, context) => {
+            const conversation = await runtime.conversation(task.input.conversationId, context);
+            if (conversation === undefined)
+                runtime.report(new Error(`Schedule ${task.input.id}: conversation ${task.input.conversationId} is missing`));
+            else {
+                await conversation.submit({
+                    type: 'input', requestId: task.input.id, whenBusy: 'followUp', content: `Scheduled instruction ${task.input.id} is due now: ${task.input.instruction}`,
+                    entry: { kind: SCHEDULED_INPUT_KIND, data: { scheduleId: task.input.id, instruction: task.input.instruction, runAt: task.input.runAt } },
+                }, context);
+            }
+            await runtime.commit(async (tx) => {
+                remove((await tx.doc(ConversationSchedules, task.input.conversationId)).items, task.input.id);
+                return { status: 'terminal', outcome: { status: 'completed', result: { delivered: conversation !== undefined } } };
+            }, context);
+        },
+    },
+    abort: async (task, runtime, context) => {
+        await runtime.commit(async (tx) => {
+            remove((await tx.doc(ConversationSchedules, task.input.conversationId)).items, task.input.id);
+            return { status: 'terminal', outcome: { status: 'aborted' } };
+        }, context);
+    },
+});
+/**
+ * Create a schedule in a commit, or return the one `operationId` already made in this conversation. For hosts that schedule
+ * outside a tool (an API route); the `schedule` tool calls it too.
+ */
+export async function addSchedule(tx, conversationId, request) {
+    const schedules = await tx.doc(ConversationSchedules, conversationId);
+    const existing = schedules.items.find(item => item.operationId === request.operationId);
+    if (existing !== undefined)
+        return { ...existing };
+    const id = `schedule-${schedules.next++}`;
+    const taskId = await tx.createTask(ScheduledDelivery, { id, conversationId, instruction: request.instruction, runAt: request.runAt }, { ownership: { kind: 'conversation' }, conversationId, background: true });
+    const record = { id, operationId: request.operationId, instruction: request.instruction, runAt: request.runAt, taskId };
+    schedules.items.push(record);
+    return { ...record };
+}
+/** Mark a pending schedule of this conversation cancelled; its task wakes and ends without delivering. False when there is none. */
+export async function cancelSchedule(tx, conversationId, id) {
+    const item = (await tx.doc(ConversationSchedules, conversationId)).items.find(candidate => candidate.id === id);
+    if (item === undefined || item.cancelled)
+        return false;
+    item.cancelled = true;
+    return true;
+}
+/** Pending, uncancelled schedules of one conversation, soonest first. */
+export async function listSchedules(reader, conversationId, context) {
+    const value = await reader.snapshot(ConversationSchedules, conversationId, context);
+    return (value?.items ?? []).filter(item => !item.cancelled).map(item => ({ ...item })).sort((a, b) => a.runAt - b.runAt);
+}
+/**
+ * The deadline of a schedule task that is still sleeping, from `harness.inspect()`; `undefined` for every other task. A host with
+ * one wake-up timer (a Durable Object alarm) sets it to the earliest deadline, and wakes Pi then; the deadlines stay Pi's tasks.
+ */
+export function scheduledDeadline(task) {
+    const { record } = task;
+    if (record.kind !== ScheduledDelivery.definition.name || record.abortRequested)
+        return undefined;
+    if (record.state.status === 'completing' || record.state.status === 'terminal')
+        return undefined;
+    const checkpoint = record.state.checkpoint;
+    const runAt = record.input?.runAt;
+    return checkpoint?.phase === 'wait' && typeof runAt === 'number' ? runAt : undefined;
+}
+/**
+ * `schedule`, `list_schedules` and `cancel_schedule` plus the delivery task, as one native extension. A conversation lists and
+ * cancels only its own schedules. `schedule` is idempotent on `operationId` (default: the tool task, so a replayed call returns
+ * the schedule it made).
+ */
+export function createScheduleExtension(options = {}) {
+    const now = options.now ?? Date.now;
+    const maxDelay = options.maxDelaySeconds ?? MAX_DELAY_SECONDS;
+    const describe = (record) => ({ id: record.id, instruction: record.instruction, runAt: new Date(record.runAt).toISOString() });
+    const schedule = defineTool({
+        name: SCHEDULE_TOOL,
+        description: 'Schedule an instruction for this conversation at a later time. When it is due, the conversation receives the instruction and carries it out. Give exactly one of delaySeconds or at.',
+        parameters: Type.Object({
+            instruction: Type.String({ minLength: 1, maxLength: MAX_INSTRUCTION, description: 'What to do when it is due, as a self-contained request without timing words.' }),
+            delaySeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: maxDelay })),
+            at: Type.Optional(Type.String({ description: 'ISO 8601 date-time with a timezone offset, for example 2026-11-01T09:00:00+01:00.' })),
+            operationId: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: 'Idempotency key: the same key returns the existing schedule.' })),
+        }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (args, api, context) => {
+            const time = now();
+            if ((args.delaySeconds === undefined) === (args.at === undefined))
+                return refused('give exactly one of delaySeconds or at');
+            let runAt;
+            if (args.delaySeconds !== undefined)
+                runAt = time + args.delaySeconds * 1000;
+            else {
+                runAt = TIMEZONE_SUFFIX.test(args.at) ? Date.parse(args.at) : Number.NaN;
+                if (!Number.isFinite(runAt))
+                    return refused('at must be an ISO 8601 date-time with a timezone offset');
+                if (runAt <= time)
+                    return refused('at must be in the future');
+                if (runAt > time + maxDelay * 1000)
+                    return refused('at is too far in the future');
+            }
+            const operationId = args.operationId ?? `tool:${api.taskId}`;
+            const record = await api.commit(tx => addSchedule(tx, api.conversationId, { operationId, instruction: args.instruction, runAt }), context);
+            await options.onDeadline?.(record.runAt, context);
+            return { output: [{ type: 'text', text: `Scheduled ${record.id} for ${describe(record).runAt}: ${JSON.stringify(record.instruction)}. Nothing more is needed now.` }], details: describe(record) };
+        },
+    });
+    const list = defineTool({
+        name: LIST_SCHEDULES_TOOL,
+        description: 'List the pending schedules of this conversation.',
+        parameters: Type.Object({}, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (_args, api, context) => {
+            const items = (await listSchedules(api, api.conversationId, context)).map(describe);
+            return { output: [{ type: 'text', text: JSON.stringify(items) }], details: { items } };
+        },
+    });
+    const cancel = defineTool({
+        name: CANCEL_SCHEDULE_TOOL,
+        description: 'Cancel a pending schedule of this conversation by its id.',
+        parameters: Type.Object({ id: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (args, api, context) => {
+            const cancelled = await api.commit(tx => cancelSchedule(tx, api.conversationId, args.id), context);
+            return cancelled ? { output: [{ type: 'text', text: `Cancelled ${args.id}.` }] } : { isError: true, output: [{ type: 'text', text: `No pending schedule ${args.id} in this conversation.` }] };
+        },
+    });
+    return defineExtension({ name: 'boring.schedule', tools: [schedule, list, cancel], tasks: [ScheduledDelivery] });
+}
+const refused = (reason) => ({ isError: true, output: [{ type: 'text', text: `Not scheduled: ${reason}.` }] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -90,6 +90,10 @@
       "types": "./dist/agents.d.ts",
       "import": "./dist/agents.js"
     },
+    "./schedule": {
+      "types": "./dist/schedule.d.ts",
+      "import": "./dist/schedule.js"
+    },
     "./chat-transport": {
       "types": "./dist/chat-transport.d.ts",
       "import": "./dist/chat-transport.js"
@@ -139,8 +143,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.3.2",
-    "@hachej/boring-ui-kit": "^0.3.2"
+    "@hachej/boring-files": "^0.4.1",
+    "@hachej/boring-ui-kit": "^0.4.1"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {