@hachej/boring-agent 0.4.26 → 0.4.28

package/README.md

@@ -327,6 +327,17 @@ The resource must be UTF-8 `application/json`, optionally with `charset=utf-8`.
 
 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.
 
+## One-call runs
+
+A run is one agent asked once, in its own native conversation, for a result: the host starts it by a key, the agent answers by calling a result tool (or in text), the host checks the answer, asks for a corrected one while the repair budget lasts, and hands the end to the operation that started the run. Every home needs the same parts, so they are here once. Pi still owns the turns, the transcript and recovery; these read the transcript and submit native follow-up inputs, and the host keeps its data and its budgets.
+
+- `@hachej/boring-agent/run-result` (optional peer `typebox`): `resultConfig` (the card's `result: { schema?, validate?, repairs? }`), `resultParameters`, `resultExecutor` (the result tool's `execute`: checks the call against the schema and the card's validator operation, spends the budget), `settleResult` (wait for the answer, read it, repair it in the run's own conversation with `repair:<conversation>:<n>` inputs, check it once more with `phase: "delivery"`), `runMessage`, `runResult`, `resultState`, `evidenceOf`, `withEvidence`. The validator is an operation the host calls through `invoke(operation, input, key)` as the person whose run it is. `ResultBudget` keeps the stored document shape of the homes that ran this first.
+- `@hachej/boring-agent/runs`: the run ends (`completed`, `invalid_output`, `cancelled`, `interrupted`, `revoked`, `error`), `RunView`, `sumUsage`, `OVER_BUDGET` and `isOverBudget`, and `deliverRunEnd`: bounded attempts under one `deliver:<key>` receipt key, a completed end checked again first and delivered as `invalid_output` when it no longer passes. A delivery that fails is reported, not dropped.
+- `@hachej/boring-agent/run-ledger`: `createRunLedger(sql)` keeps `_host_agent_runs` in the person's own SQLite file; an end happens once (`UPDATE ... RETURNING`), so a cancel and the run's own end can race. `createRunner({ ledger, person, context, has, prepare, invoke, admit?, usage? })` gives `start(agent, input, key, deliverTo)` (the same key is the same run), `status`, `cancel` and `recover`: a run a stopped process left ends `interrupted`, and one that ended without being delivered is delivered. `admit` is the host's spend meter: a refused run is never started and ends `error: over_budget`. The cap, the spend ledger and the prices stay the host's.
+- `@hachej/boring-agent/run-outbox`: `stageStarts(sql, ...)` in the app operation's own transaction, `drainStarts` after the commit. A row is removed only when the run is acknowledged, retried with backoff when it may pass, dropped when it never will.
+
+Stores are a synchronous `SyncSql` function (`node:sqlite` `prepare(sql).all(...params)`, a Durable Object's `sql.exec`); nothing here opens a connection or a transaction. Not here, by design: the card parser and its front matter, the app operations a run calls, the schedule and alarm of a Durable Object home, and anything clinical or app specific.
+
 ## Structured output and native tool evidence
 
 `@hachej/boring-agent/validation` exports `createOutputValidation`. Install its native extension explicitly. A producer returns `{ text, evidence }`, where `evidence` contains retained native tool-result entry IDs. Create the returned validation task with `{ producer }` through ordinary `tx.createTask`; it waits for the producer and returns `valid`, `invalid` or `producer-failed`. Only a `valid` result may feed application delivery. The host supplies a stable task name and definition version; incompatible stored versions require native migration or refusal.
@@ -449,7 +460,7 @@ const delegates = [
 ];
 ```
 
-**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.
+**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 waits on the Harness clock (`runtime.setTimer`; Pi 1.4 removed `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).
 
@@ -510,3 +521,33 @@ const navigate = createPresentationTool({
 Here `Type` is Pi AI's native schema builder, and `mounted`, `capturedTarget` and `canNavigate` belong to the host. The adapter passes native cancellation to the command and fixes replay to `unsafe`: an interrupted presentation call cannot safely be redirected or repeated. It acquires no controller, provider or Harness and owns none of their cleanup.
 
 This is direct in-process binding. A server cannot manipulate a remote browser through this adapter alone. The optional [canvas host recipe](../../docs/architecture/CANVAS.md#authenticated-remote-presentation-recipe) supplies authenticated selection/proposal delivery to a mounted canvas. Other viewer transports and deployment identity remain separate work. Presentation/proposal results are not publication receipts or human approval.
+
+## Structured actions
+
+`@hachej/boring-agent/actions` provides `withActionModels(models, { resolve })`, an optional adapter at the public `HarnessOptions.models` seam. A host decision admits one structured extraction; its single validated tool call is executed by Pi. The next native generation renders a template from the actual tool result, without contacting an LLM. Ambiguous requests return to the full model. No extra harness, tool dispatcher or durable journal is created.
+
+```ts
+import { ACTION_PROVIDER, withActionModels } from '@hachej/boring-agent/actions';
+
+const actionModels = withActionModels(admittedModels, {
+  resolve: id => id === 'notes' ? {
+    model: fullModel,
+    extraction: { model: extractionModel, instructions: 'Extract one new note.', tool: noteTool },
+    decide: async ({ message, history, signal }) => decideNote({ message, history, signal }),
+    reply: 'Saved {note.title}.',
+    uncertainReply: 'The outcome is uncertain. Check before retrying.',
+  } : undefined,
+});
+// Pass actionModels as the models option when the host opens its native Harness.
+await conversation.configure({ model: { provider: ACTION_PROVIDER, modelId: 'notes' } }, context);
+```
+
+`admittedModels` is the host's existing native Models, including its provider authentication and budget wrappers. `noteTool` is a native tool declaration, already installed and allowed in the conversation. The extraction schema may be stricter than that tool's schema; both are checked without coercion before returning a call. No commercial provider, API key, subscription or Jev client is embedded in the package. The host's `decide` adapts its chosen decision service; only literal `true` admits extraction. The callback gets native prior messages so the host can choose and bound the authorized decision context. Extraction receives only the current text input.
+
+The default decision deadline is 400 ms and the input cap is 1,500 characters; `decisionTimeoutMs` and `maxInputCharacters` override them. Decision failure/timeout, non-text input, missing current tool, malformed/multiple extraction calls or extraction refusal return to the full model. The decision receives an abort signal; an uncooperative service may finish later, but its result cannot start extraction. Native compaction uses `completeSimple` with a tool-free summarization context, which delegates to the full model. Explicit deferred requests also use the full model; polling and cancellation retain the underlying provider. Missing action definitions or full models return the native unavailable-model result. Unselected models and native registry capabilities remain available.
+
+Reply placeholders such as `{note.title}` accept actual strings, finite numbers and string arrays (joined by newline). Missing output, a failed tool or unreadable result produces `uncertainReply`, never a blind replay of a possible mutation. `rejectedWithoutEffect(result)` may opt into full-model handling only when the host can prove an atomic rejection; a throwing predicate leaves the outcome uncertain. Tools still own permission checks and durable idempotent receipts; the adapter cannot make external writes transactional. Install the adapter outside the metered Models so real extraction and fallback requests retain admission. Synthetic replies have zero usage; failed extraction usage needs host request metering because only the final fallback message enters Pi's transcript.
+
+Hosts must explicitly configure existing conversations when adopting this virtual model; deployment alone does not change their persisted selection. Keep the action's tool and result contract compatible while native work is pending. Changing definitions during an outstanding action is not a version-pinning guarantee.
+
+Evidence: `node --test test/packages/agent-actions.test.mjs` runs the public package through a native Harness, SQLite reopen, native tool gates and scripted models. `npm run test:definitions-consumer -- --actions` repeats these tests and checks strict installed declarations. Real-model speed and decision accuracy remain consumer evals, not claims of these scripted tests.

package/dist/actions.d.ts

@@ -0,0 +1,38 @@
+import type { Message, Models, Tool, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { ModelRef } from '@earendil-works/pi-durable';
+/** Virtual model identity persisted by Pi; real requests use the host's Models. */
+export declare const ACTION_PROVIDER = "boring-action";
+export interface StructuredAction {
+    readonly model: ModelRef;
+    readonly extraction: {
+        readonly model: ModelRef;
+        readonly instructions: string;
+        readonly tool: Tool;
+    };
+    /** Host decision policy (Jev, another classifier, or deterministic rules). Literal true admits extraction. */
+    readonly decide: (input: {
+        readonly message: string;
+        readonly history: readonly Message[];
+        readonly signal: AbortSignal;
+    }) => Promise<boolean>;
+    readonly reply: string;
+    /** Host-localized text for an outcome that must not be retried automatically. */
+    readonly uncertainReply: string;
+    /** Only return true for a known atomic rejection with no effect. */
+    readonly rejectedWithoutEffect?: (result: ToolResultMessage) => boolean;
+    readonly decisionTimeoutMs?: number;
+    readonly maxInputCharacters?: number;
+}
+export interface ActionModelsOptions {
+    /** Resolve trusted configuration; this never registers tools or grants permissions. */
+    readonly resolve: (id: string) => StructuredAction | undefined;
+    readonly now?: () => number;
+}
+/** Substitute actual scalar results only. Missing values cannot become invented confirmations. */
+export declare function actionReply(template: string, result: unknown): string;
+/** Compose at HarnessOptions.models, outside the host's admitted/metered real Models.
+ * Pi still owns generation, tool execution, hooks, history and recovery. Tool-free requests
+ * (including native compaction) delegate to the full model. No tool is executed here.
+ */
+export declare function withActionModels<T extends Models>(models: T, options: ActionModelsOptions): T;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,158 @@
+import { createAssistantMessageEventStream, getCurrentTools, normalizeContext } from '@earendil-works/pi-ai';
+import { Check } from 'typebox/schema';
+/** Virtual model identity persisted by Pi; real requests use the host's Models. */
+export const ACTION_PROVIDER = 'boring-action';
+const PREFIX = 'boring_action_';
+const zeroUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
+const inputText = (content) => typeof content === 'string' ? content : content.filter(p => p.type === 'text').map(p => p.text).join('');
+/** Substitute actual scalar results only. Missing values cannot become invented confirmations. */
+export function actionReply(template, result) {
+    return template.replace(/\{([\w.]+)\}/g, (_match, path) => {
+        let value = result;
+        for (const key of path.split('.')) {
+            value = value !== null && typeof value === 'object' && Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined;
+        }
+        if (Array.isArray(value) && value.every(v => typeof v === 'string'))
+            value = value.join('\n');
+        if (typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value)))
+            throw new Error(`Missing action result: ${path}`);
+        return String(value);
+    });
+}
+async function admitted(action, message, history, parent) {
+    const controller = new AbortController();
+    const signal = parent ? AbortSignal.any([parent, controller.signal]) : controller.signal;
+    if (signal.aborted)
+        return false;
+    let timer;
+    let onAbort = () => { };
+    const cancelled = new Promise(resolve => {
+        onAbort = () => resolve(false);
+        signal.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => controller.abort(), action.decisionTimeoutMs ?? 400);
+    });
+    try {
+        return await Promise.race([Promise.resolve().then(() => action.decide({ message, history, signal })).then(value => value === true, () => false), cancelled]);
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+        controller.abort();
+    }
+}
+/** Compose at HarnessOptions.models, outside the host's admitted/metered real Models.
+ * Pi still owns generation, tool execution, hooks, history and recovery. Tool-free requests
+ * (including native compaction) delegate to the full model. No tool is executed here.
+ */
+export function withActionModels(models, options) {
+    const now = options.now ?? Date.now;
+    const required = (ref) => {
+        const model = models.getModel(ref.provider, ref.modelId);
+        if (!model || model.provider === ACTION_PROVIDER)
+            throw new Error(`Unavailable action model: ${ref.provider}/${ref.modelId}`);
+        return model;
+    };
+    const resolve = (id) => {
+        const action = options.resolve(id);
+        if (!action)
+            throw new Error(`No action agent ${id}`);
+        return action;
+    };
+    const wrapped = {
+        getModel(provider, id) {
+            if (provider !== ACTION_PROVIDER)
+                return models.getModel(provider, id);
+            const action = options.resolve(id);
+            const model = action && models.getModel(action.model.provider, action.model.modelId);
+            return model && model.provider !== ACTION_PROVIDER ? { ...model, provider, id } : undefined;
+        },
+        streamSimple(model, context, requestOptions) {
+            if (model.provider !== ACTION_PROVIDER)
+                return models.streamSimple(model, context, requestOptions);
+            const action = resolve(model.id);
+            const original = required(action.model);
+            const out = createAssistantMessageEventStream();
+            const full = async () => { for await (const event of models.streamSimple(original, context, requestOptions))
+                out.push(event); };
+            const emit = (message) => {
+                if (message.stopReason === 'error' || message.stopReason === 'aborted')
+                    out.push({ type: 'error', reason: message.stopReason, error: message });
+                else if (message.stopReason !== 'pending')
+                    out.push({ type: 'done', reason: message.stopReason, message });
+                else
+                    throw new Error('An action cannot emit a pending completion');
+            };
+            void (async () => {
+                const messages = context.messages.filter(message => message.role !== 'system');
+                const last = messages.at(-1), previous = messages.at(-2);
+                const calls = previous?.role === 'assistant' ? previous.content.filter(p => p.type === 'toolCall') : [];
+                const call = calls.length === 1 ? calls[0] : undefined;
+                if (last?.role === 'toolResult' && call?.id === last.toolCallId && call.name === action.extraction.tool.name && call.id.startsWith(PREFIX)) {
+                    if (last.isError) {
+                        let rejected = false;
+                        try {
+                            rejected = action.rejectedWithoutEffect?.(last) === true;
+                        }
+                        catch { /* Unknown outcomes remain uncertain. */ }
+                        if (rejected)
+                            return full();
+                    }
+                    let text = action.uncertainReply;
+                    if (!last.isError) {
+                        try {
+                            text = actionReply(action.reply, JSON.parse(inputText(last.content)));
+                        }
+                        catch { /* A possible effect must not be repeated. */ }
+                    }
+                    emit({ role: 'assistant', content: [{ type: 'text', text }], api: original.api, provider: ACTION_PROVIDER, model: model.id, usage: zeroUsage(), stopReason: 'stop', timestamp: now() });
+                    return;
+                }
+                const tool = getCurrentTools(normalizeContext(context).messages).find(tool => tool.name === action.extraction.tool.name);
+                if (!tool || last?.role !== 'user' || requestOptions?.signal?.aborted || requestOptions?.deferred)
+                    return full();
+                const raw = inputText(last.content);
+                if (!raw.trim() || raw.length > (action.maxInputCharacters ?? 1500) || (Array.isArray(last.content) && last.content.some(p => p.type !== 'text')))
+                    return full();
+                if (!await admitted(action, raw, messages.slice(0, -1), requestOptions?.signal) || requestOptions?.signal?.aborted)
+                    return full();
+                let extracted;
+                try {
+                    extracted = await models.streamSimple(required(action.extraction.model), {
+                        systemPrompt: action.extraction.instructions, messages: [last], tools: [action.extraction.tool],
+                    }, requestOptions).result();
+                    const extractedCalls = extracted.content.filter(p => p.type === 'toolCall');
+                    const extractedCall = extractedCalls.length === 1 ? extractedCalls[0] : undefined;
+                    if (extracted.stopReason !== 'toolUse' || !extractedCall || extractedCall.name !== tool.name ||
+                        !Check(action.extraction.tool.parameters, extractedCall.arguments) || !Check(tool.parameters, extractedCall.arguments))
+                        return full();
+                    // Native ToolTask owns the write, permission checks and host receipt; keep this ID in its transcript.
+                    const bytes = crypto.getRandomValues(new Uint8Array(16));
+                    const id = PREFIX + Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+                    emit({ ...extracted, content: [{ ...extractedCall, id }] });
+                }
+                catch {
+                    return full();
+                }
+            })().catch(error => emit({ role: 'assistant', content: [], api: original.api, provider: original.provider, model: original.id, usage: zeroUsage(), stopReason: 'error', errorMessage: String(error instanceof Error ? error.message : error), timestamp: now() })).finally(() => out.end());
+            return out;
+        },
+        stream(model, context, requestOptions) {
+            return models.stream(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, context, requestOptions);
+        },
+        completeSimple: (model, context, requestOptions) => wrapped.streamSimple(model, context, requestOptions).result(),
+        complete: (model, context, requestOptions) => wrapped.stream(model, context, requestOptions).result(),
+        streamDeferred(model, handle, requestOptions) {
+            return models.streamDeferred(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, handle, requestOptions);
+        },
+        fetchDeferred: (model, handle, requestOptions) => wrapped.streamDeferred(model, handle, requestOptions).result(),
+        cancelDeferred(model, handle, requestOptions) {
+            return models.cancelDeferred(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, handle, requestOptions);
+        },
+    };
+    return new Proxy(models, { get(target, key) {
+            if (Object.hasOwn(wrapped, key))
+                return Reflect.get(wrapped, key);
+            const value = Reflect.get(target, key);
+            return typeof value === 'function' ? value.bind(target) : value;
+        } });
+}

package/dist/ask-user.js

@@ -6,7 +6,7 @@ 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,
+    kind: 'boring.ask-user.question', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
     initial: () => ({ question: null }),
 });
 /** Bind an answer to the exact assistant entry that asked it. */

package/dist/browser-task.js

@@ -11,7 +11,7 @@ import { AmbiguousCall, UnknownCall, callBinding, callBindingId, ownBindingKey,
 export const BROWSER_TASK_MAX_ANSWER = 16_384;
 /** One member per assistant entry and tool call, in the calling conversation. */
 const documents = defineDocFamily({
-    kind: 'boring.browser-task', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
+    kind: 'boring.browser-task', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
     initial: () => ({ task: null }),
 });
 /** The answer ID of a browser task call: the same `[assistantEntryId, callId]` binding as `askUserQuestionId`. */

package/dist/conversations.js

@@ -3,7 +3,7 @@ import { RequestGuardError, hasJsonContentType, readJsonBody } from '@hachej/bor
 import { MENTION_FILE_PREFIX } from './mentions.js';
 /** The native document. `fork: 'initial'`: a fork made by `fork()` gets its own metadata in the creating commit; any other fork starts unmanaged. */
 export const conversationMetadata = defineDoc({
-    kind: 'boring.conversation.metadata', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    kind: 'boring.conversation.metadata', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
     initial: () => ({ owner: '', title: null, createdAt: 0, updatedAt: 0, lastMessage: null, archived: false, deletedAt: null }),
 });
 const managed = (meta, owner) => meta !== undefined && meta.owner !== '' && meta.deletedAt === null && (owner === undefined || meta.owner === owner);

package/dist/file-guard.js

@@ -4,7 +4,7 @@ import { createEditTool, createReadTool, createWriteTool } from '@earendil-works
 import { asWorkspaceResolver, decorate, workspaceFor } from './workspaces.js';
 /** Conversation document: workspace and path (relative to the workspace root; see `baselineKey`) to the revision this conversation last read or wrote. */
 export const lastReadRevisions = defineDoc({
-    kind: 'boring.files.last-read', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    kind: 'boring.files.last-read', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
     initial: () => ({ revisions: {} }),
 });
 /** The baseline key of `path` in `workspace` (its `id`, or its provider id): `<workspace>:<path>`. */

package/dist/memory/optchat.js

@@ -15,26 +15,26 @@ export { DEFAULTS as OPTCHAT_DEFAULTS, PLACEHOLDER as OPTCHAT_PLACEHOLDER, compa
 export { OptChatLog, OptChatTree, advanceFold, emptyFold, leavesOf, renderView, zoomText, dateText } from './optchat-core.js';
 /** Summaries of one conversation, in shards of 64 nodes per level (`<level>.<shard>`). A fork starts with the current ones; fingerprints reject any that no longer match. */
 export const OptChatNodes = defineDocFamily({
-    kind: 'boring.memory.optchat.nodes', version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current', initial: () => ({ nodes: {} }),
+    kind: 'boring.memory.optchat.nodes', checkpointWhen: () => false, version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current', initial: () => ({ nodes: {} }),
 });
 /** Seed memories, stored once per conversation and inherited by forks. They precede the Pi transcript in the memory only. */
 export const OptChatNotes = defineDoc({
-    kind: 'boring.memory.optchat.notes', version: 1, scope: 'conversation', history: 'latest', fork: 'current',
+    kind: 'boring.memory.optchat.notes', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'current',
     initial: () => ({ seeded: false, notes: [] }),
 });
 /** Memory-only tombstones. Values are leaf counts, never the forgotten content. Pi's transcript is unchanged. */
 export const OptChatEdits = defineDoc({
-    kind: 'boring.memory.optchat.edits', version: 1, scope: 'conversation', history: 'latest', fork: 'current',
+    kind: 'boring.memory.optchat.edits', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'current',
     initial: () => ({ revision: 0, forgotten: {} }),
 });
 /** Only the emitted tiling and fingerprints are retained, never another copy of message or summary text. */
 const OptChatFold = defineDocFamily({
-    kind: 'boring.memory.optchat.fold', version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current',
+    kind: 'boring.memory.optchat.fold', checkpointWhen: () => false, version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current',
     initial: () => ({ configuration: '', revision: -1, fingerprints: [], fold: null }),
 });
 /** Compactor bookkeeping of one conversation: calls, spend and the last failure of each node, including its retry streak. */
 export const OptChatState = defineDoc({
-    kind: 'boring.memory.optchat.state', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    kind: 'boring.memory.optchat.state', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
     initial: () => ({ calls: 0, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }, failures: {} }),
 });
 const SHARD = 64;

package/dist/native-version.d.ts

@@ -3,7 +3,7 @@
  * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
  * readable, because the native conversation and tool shapes they refer to did not change between them.
  */
-export declare const NATIVE_VERSION = "pi-durable@1.2.0";
+export declare const NATIVE_VERSION = "pi-durable@1.4.0";
 export type NativeVersion = 'pi-durable@1.0.1' | 'pi-durable@1.1.0' | typeof NATIVE_VERSION;
 export declare const isNativeVersion: (value: unknown) => value is NativeVersion;
 //# sourceMappingURL=native-version.d.ts.map

package/dist/native-version.js

@@ -3,5 +3,5 @@
  * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
  * readable, because the native conversation and tool shapes they refer to did not change between them.
  */
-export const NATIVE_VERSION = 'pi-durable@1.2.0';
+export const NATIVE_VERSION = 'pi-durable@1.4.0';
 export const isNativeVersion = (value) => value === NATIVE_VERSION || value === 'pi-durable@1.1.0' || value === 'pi-durable@1.0.1';

package/dist/questions.js

@@ -1,4 +1,5 @@
 import { ReadAfterWrite, defineDocFamily, defineExtension, defineTask } from '@earendil-works/pi-durable';
+import { waitUntil } from './wait-until.js';
 function sameRef(left, right) {
     return left.runtimeId === right.runtimeId && left.conversationId === right.conversationId
         && left.taskId === right.taskId && left.questionId === right.questionId && left.scopeId === right.scopeId
@@ -11,7 +12,7 @@ export function createQuestions(options) {
         throw new TypeError('A stable runtime identity is required');
     const now = options.now ?? Date.now;
     const documents = defineDocFamily({
-        kind: 'boring.questions.record', version: 1, scope: 'session', family: true,
+        kind: 'boring.questions.record', checkpointWhen: () => false, version: 1, scope: 'session', family: true,
         initial: () => ({ question: null }),
     });
     const key = (ref) => JSON.stringify([runtimeId, ref.scopeId, ref.questionId]);
@@ -40,11 +41,17 @@ export function createQuestions(options) {
                             watch.start(async (value) => { if (value?.question?.state.kind !== 'pending')
                                 resolve(); });
                         });
-                        await Promise.race([
-                            changed,
-                            runtime.sleep(Date.parse(watch.value.question.ref.expiresAt), context),
-                            watch.closed.then(() => { throw new Error('Question observation closed'); }),
-                        ]);
+                        const expiry = waitUntil(runtime, Date.parse(watch.value.question.ref.expiresAt), context);
+                        try {
+                            await Promise.race([
+                                changed,
+                                expiry.done,
+                                watch.closed.then(() => { throw new Error('Question observation closed'); }),
+                            ]);
+                        }
+                        finally {
+                            expiry.disarm();
+                        }
                     }
                     await runtime.commit(async (tx) => {
                         const doc = await tx.doc(documents, running.input.key, null);

package/dist/room.js

@@ -118,8 +118,8 @@ export function wakeFor(entry, room) {
     return room.people.length === 1 && room.people[0] === author && room.agents.includes('agent:pm') ? [wake('agent:pm')] : [];
 }
 /** Conversation names to native ids, and each card's first entry (an action's target). */
-const RoomIndex = defineDoc({ kind: 'boring.room.index', version: 1, scope: 'session', initial: () => ({ conversations: {}, cards: {} }) });
-const RoomWakes = defineDoc({ kind: 'boring.room.wakes', version: 1, scope: 'session', initial: () => ({ open: [] }) });
+const RoomIndex = defineDoc({ kind: 'boring.room.index', checkpointWhen: () => false, version: 1, scope: 'session', initial: () => ({ conversations: {}, cards: {} }) });
+const RoomWakes = defineDoc({ kind: 'boring.room.wakes', checkpointWhen: () => false, version: 1, scope: 'session', initial: () => ({ open: [] }) });
 const REFUSED = Object.freeze({ refused: 'no-open-wake' });
 const copyWake = (wake) => ({ ...wake });
 /** The room over one Harness that never runs a model. Membership, roles and rates are the host's, before it calls. */
@@ -264,7 +264,7 @@ const framesOf = (entries) => entries.flatMap(entry => (entry.model ?? []).flatM
         return [];
     return message.content.flatMap((part) => part.type === 'text' && part.text ? [{ type: 'text', text: part.text }] : part.type === 'toolCall' ? [{ type: 'step', label: part.name, status: 'running' }] : []);
 }));
-const Turns = defineDoc({ kind: 'boring.room.turns', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', initial: () => ({ owed: [] }) });
+const Turns = defineDoc({ kind: 'boring.room.turns', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial', initial: () => ({ owed: [] }) });
 /** The agent's side of a room, over its own conversation in its own home. Delivery to the port is at least once. */
 export function createRoomTurn(options) {
     const { conversation, port } = options;

package/dist/run-ledger.d.ts

@@ -0,0 +1,98 @@
+import type { Context } from '@earendil-works/chord';
+import type { SyncSql } from './run-outbox.js';
+import type { ResultCard, ResultConversation, ResultInvoke, ResultSubmission, ResultValidationRecord } from './run-result.js';
+import type { RunEnd, RunUsage, RunView } from './runs.js';
+/**
+ * The runs a home keeps in a person's own store, and the runner over them: start a run by its key (the same key is the same run),
+ * end it exactly once, deliver its end to the operation that started it, cancel it, and find again what a stopped process left.
+ * The store is the host's data (a table in its SQLite file); the model turns stay Pi's (the run is a native conversation).
+ */
+export declare const RUNS_TABLE = "CREATE TABLE IF NOT EXISTS _host_agent_runs (key TEXT PRIMARY KEY, agent TEXT NOT NULL, status TEXT NOT NULL, output TEXT, error TEXT, deliver TEXT, validation TEXT, delivered INTEGER NOT NULL DEFAULT 0, person TEXT NOT NULL, usage TEXT, started_at TEXT)";
+export interface RunRow {
+    readonly key: string;
+    readonly agent: string;
+    readonly status: string;
+    readonly output: string | null;
+    readonly error: string | null;
+    readonly deliver: string | null;
+    readonly validation: string | null;
+    readonly delivered: number;
+    readonly person: string;
+    readonly usage: string | null;
+    readonly started_at: string | null;
+}
+/** A refusal with an HTTP-like `status` (404: no such agent; 409: the key belongs to another agent). */
+export declare class RunRefused extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface EndOptions {
+    readonly output?: unknown;
+    readonly error?: string | null;
+    readonly validation?: ResultValidationRecord;
+    readonly usage?: RunUsage | null;
+}
+/** The ledger over a store's synchronous SQL (`SyncSql`: `UPDATE ... RETURNING` is what makes an end happen once). */
+export declare function createRunLedger(sql: SyncSql): {
+    ensure: () => void;
+    get: (key: string) => RunRow | undefined;
+    /** Record a new running run. The caller has checked `get(key)` first. */
+    begin(run: {
+        key: string;
+        agent: string;
+        deliver: string | null;
+        person: unknown;
+        startedAt: string;
+    }): void;
+    /** End a run still running, once (a cancel and the run's own end race): false when something else ended it first. */
+    end(key: string, status: RunEnd, options?: EndOptions): boolean;
+    /** A completed run whose delivery-time check failed: its end becomes the failure (never after it was delivered). */
+    fail(key: string, status: RunEnd, error: string): void;
+    markDelivered(key: string): void;
+    /** Runs a stopped process left: still running (they end `interrupted`), or ended and not delivered. */
+    left(): RunRow[];
+    view(row: RunRow): RunView;
+};
+export type RunLedger = ReturnType<typeof createRunLedger>;
+/** A started run's live handle: its conversation and first submission, and the card it answers. */
+export interface RunExecution {
+    readonly conversation: ResultConversation & {
+        abort(context: Context): Promise<unknown>;
+    };
+    readonly submission: ResultSubmission;
+    readonly card: ResultCard;
+}
+export interface RunnerOptions {
+    readonly ledger: RunLedger;
+    /** The person whose store this is: written on each row so another process can deliver it as them. */
+    readonly person: unknown;
+    readonly context: Context;
+    /** Whether the home has this agent (a start of an unknown agent is refused 404 before any row is written). */
+    readonly has: (agent: string) => boolean | Promise<boolean>;
+    /** Open the run's conversation and submit its input: null when the agent is gone. */
+    readonly prepare: (agent: string, input: unknown) => Promise<RunExecution | null>;
+    /** Call an operation as the person: the result validators and the delivery (which may reach an `internal` operation). */
+    readonly invoke: ResultInvoke;
+    /** The run's model answers summed, from its conversation; null when none answered. */
+    readonly usage?: (conversation: RunExecution['conversation']) => Promise<RunUsage | null>;
+    /** The host's spend meter: throws `over_budget` when the app may not spend now. A refused run is never started and ends `error: over_budget`. */
+    readonly admit?: () => void;
+    readonly now?: () => string;
+    readonly deliverAttempts?: number;
+    readonly deliverBackoffMs?: number;
+}
+/**
+ * The runner of one person's store. A run lives in this process: one a restart cut short is found by `recover` and ends
+ * `interrupted`; one that ended and was not delivered is delivered then. Delivery is once (the host's receipt `deliver:<key>`).
+ */
+export declare function createRunner(options: RunnerOptions): {
+    /** Starts the run of this key (a key already started is the same run, whatever else is asked): launched and returned at once. */
+    start(agent: string, input: unknown, key: string, deliverTo: string | null): Promise<RunView>;
+    /** The run of this key as recorded, or null. Never waits on a delivery in flight: safe to call from inside one. */
+    status(key: string): Promise<RunView | null>;
+    /** Cancels it (its delivery gets `cancelled`); a run that has ended stays as it is; null: no such run. */
+    cancel(key: string): Promise<RunView | null>;
+    recover: () => Promise<void>;
+};
+export type Runner = ReturnType<typeof createRunner>;
+//# sourceMappingURL=run-ledger.d.ts.map