@hachej/boring-agent 0.4.26 → 0.4.28

package/dist/run-result.js

@@ -0,0 +1,195 @@
+import { defineDoc } from '@earendil-works/pi-durable';
+import { Check, Errors } from 'typebox/schema';
+const MAX_HINT = 1000;
+const OPERATION = /^[A-Za-z][\w.-]{0,80}$/;
+/** A settled submission that was cut short (aborted, reset, superseded) is `interrupted`; any other non-answer is an `error`. */
+const INTERRUPTED = new Set(['aborted', 'reset', 'stale']);
+/**
+ * The per-conversation count of repair attempts that left no result call (a model that answered in text instead of the tool).
+ * Defined without `history` and `fork`, exactly as the homes that ran this protocol before persisted it: pi-durable refuses a token
+ * whose semantics differ from the stored record, so adding them here would break every existing run store.
+ */
+export const ResultBudget = defineDoc({ kind: 'boring.result-budget', checkpointWhen: () => false, version: 1, scope: 'conversation', initial: () => ({ misses: 0 }) });
+/** Parse `result:` of a card. `legacy` is the card's `tool.json`, whose input is the default schema. Throws a plain Error naming the agent. */
+export function resultConfig(value, legacy, name) {
+    if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value)))
+        throw new Error(`agents/${name}: result is { schema?, validate?, repairs? }`);
+    const result = (value ?? {});
+    if (result.validate !== undefined && (typeof result.validate !== 'string' || !OPERATION.test(result.validate)))
+        throw new Error(`agents/${name}: result.validate names an operation`);
+    const repairs = result.repairs === undefined ? 2 : result.repairs;
+    if (typeof repairs !== 'number' || !Number.isSafeInteger(repairs) || repairs < 0 || repairs > 10)
+        throw new Error(`agents/${name}: result.repairs is an integer from 0 to 10`);
+    const schema = result.schema === undefined ? legacy?.input : result.schema;
+    if (schema !== undefined && (!schema || typeof schema !== 'object' || Array.isArray(schema) || schema.type !== 'object'))
+        throw new Error(`agents/${name}: result.schema is an object JSON Schema`);
+    return { ...(schema ? { schema: schema } : {}), ...(typeof result.validate === 'string' ? { validate: result.validate } : {}), repairs };
+}
+export const callsOf = (messages) => messages.flatMap(m => m.role === 'assistant' && Array.isArray(m.content) ? m.content.filter(p => p.type === 'toolCall') : []);
+/** The state of a run's result from its transcript. Only a host tool result can accept a call; a later rejected call cannot replace an accepted one. */
+export function resultState(card, messages, misses = 0) {
+    if (!card.result)
+        return { accepted: null, attempts: 0, exhausted: false };
+    const all = callsOf(messages), calls = all.filter(c => c.name === card.output?.name);
+    const acceptedIds = new Set();
+    let accepted = null, error, end;
+    for (const message of messages) {
+        if (message.role !== 'toolResult' || message.toolName !== card.output?.name)
+            continue;
+        const checked = message.details?.resultValidation;
+        if (checked?.error) {
+            error = checked.error;
+            end = checked.end ?? 'error';
+        }
+        if (!message.isError && checked?.valid === true && message.toolCallId !== undefined)
+            acceptedIds.add(message.toolCallId);
+    }
+    for (const call of calls) {
+        if (acceptedIds.has(call.id) && all.filter(c => c.id === call.id).length === 1 && card.output && Check(card.output.input, call.arguments))
+            accepted = call.arguments;
+    }
+    const attempts = calls.length + misses;
+    return { accepted, ...(error !== undefined ? { error } : {}), ...(end !== undefined ? { end } : {}), attempts, exhausted: attempts > card.result.repairs + 1 || (attempts === card.result.repairs + 1 && !accepted) };
+}
+/** The message of a one-call run: the input as JSON, and how to answer. */
+export function runMessage(card, input) {
+    const data = typeof input === 'string' ? input : `Input:\n${JSON.stringify(input ?? {}, null, 2)}`;
+    return card.output ? `${data}\n\nReturn the result by calling the tool ${card.output.name} exactly once. No text outside that call.` : data;
+}
+/** A run's answer: only the last host-accepted result call, else the last markdown reply. */
+export function runResult(card, messages) {
+    if (card.output) {
+        const state = resultState(card, messages ?? []);
+        return state.accepted && !state.error && !state.exhausted ? { output: state.accepted } : null;
+    }
+    let text = '';
+    for (const message of messages ?? []) {
+        if (message?.role !== 'assistant')
+            continue;
+        const parts = typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : Array.isArray(message.content) ? message.content : [];
+        const said = parts.filter(p => p.type === 'text' && p.text).map(p => p.text).join('');
+        if (said)
+            text = said;
+    }
+    return text ? { text } : null;
+}
+/** The model sees the complete result schema as the tool's parameters (nested items, descriptions, required), like a production tool. */
+export function resultParameters(card) {
+    return { ...card.output.input, type: 'object', properties: card.output.input.properties ?? {} };
+}
+export const resultDescription = (card) => card.output.description ?? '';
+/** Read the host's whole transcript, not a compacted model context or model-provided evidence. */
+export async function resultMessages(reader, conversationId) {
+    const entries = [];
+    let cursor;
+    do {
+        const page = await reader.scanEntries({ conversationId, order: 'ascending' }, 500, cursor);
+        entries.push(...page.items);
+        cursor = page.next;
+    } while (cursor);
+    return entries.flatMap(e => (e.model ?? []));
+}
+/** The tool results a run obtained (every call but the result tool's own), with the arguments that actually executed. */
+export function evidenceOf(card, messages) {
+    const all = callsOf(messages), calls = all.filter(c => c.name !== card.output?.name);
+    return messages.filter(m => m.role === 'toolResult' && calls.some(c => c.id === m.toolCallId && c.name === m.toolName) && all.filter(c => c.id === m.toolCallId).length === 1).map(m => {
+        const call = calls.find(c => c.id === m.toolCallId);
+        return { name: call.name, arguments: m.details?.hostArguments ?? call.arguments, results: { content: m.content, isError: Boolean(m.isError) } };
+    });
+}
+/**
+ * Check a result: the schema first (no coercion), then the card's `result.validate` operation, called through `invoke` with the
+ * evidence. `phase` is `attempt` while the agent answers and `delivery` for the check made again just before the run is delivered;
+ * `key` must be fresh for a delivery check. Throws when the validator answers something else than `{ valid, hint? }`.
+ */
+export async function validateResult(card, output, evidence, invoke, phase, key) {
+    if (card.output && !Check(card.output.input, output)) {
+        const [, errors] = Errors(card.output.input, output);
+        return { valid: false, hint: errors.map(e => `${e.instancePath || '/'}: ${e.message}`).join('; ').slice(0, MAX_HINT) };
+    }
+    if (!card.result?.validate)
+        return { valid: true };
+    const checked = await invoke(card.result.validate, { output, evidence, ...(phase === 'delivery' ? { phase } : {}) }, key);
+    if (!checked || typeof checked.valid !== 'boolean' || (checked.hint !== undefined && typeof checked.hint !== 'string'))
+        throw new Error(`result.validate ${card.result.validate}: expected { valid: boolean, hint?: string }`);
+    return { valid: checked.valid, hint: checked.hint?.slice(0, MAX_HINT) ?? 'Return a supported result.' };
+}
+/** `end` of a run from an error thrown while validating: a refusal by the host's authority is `revoked`, anything else `error`. */
+export function validationError(error) {
+    const e = error;
+    return { error: String(e?.message ?? error).slice(0, 500), end: e?.status === 401 || e?.status === 403 ? 'revoked' : 'error' };
+}
+/** Record the arguments that actually executed (after guards and coercion), never ones invented in the final answer. */
+export function withEvidence(tool) {
+    const execute = tool.execute;
+    return { ...tool, async execute(args, api, context) {
+            const result = await execute.call(tool, args, api, context);
+            return { ...result, details: { ...result.details, hostArguments: args } };
+        } };
+}
+/**
+ * Settle a one-call run in its own conversation: wait for the answer, read the result, check it, and while it is wrong and the card's
+ * repair budget lasts, ask for a corrected result with a native follow-up input (`repair:<conversation>:<n>`, so a replay finds the
+ * same submission). A result that passes is checked once more with phase `delivery` before it is returned. Not durable by itself:
+ * the caller records the end; a process that dies in the middle ends the run `interrupted`.
+ */
+export async function settleResult(options) {
+    const { card, conversation, invoke, context, readResult = runResult } = options;
+    let submission = options.submission, previousAttempts = 0;
+    for (let attempt = 0;; attempt++) {
+        const settled = await submission.wait(context);
+        const messages = await conversation.commit(tx => resultMessages(tx, conversation.id), context);
+        const budget = await conversation.commit(async (tx) => ({ misses: (await tx.doc(ResultBudget, conversation.id)).misses }), context);
+        const state = resultState(card, messages, budget.misses);
+        if (state.error)
+            return { error: state.error, end: state.end ?? 'error' };
+        if (card.output && state.exhausted)
+            return { error: `${card.name} returned no result matching tool.json: repair budget exhausted`, end: 'invalid_output' };
+        if (settled.status !== 'done')
+            return { error: `${card.name} did not answer (${settled.reason ?? settled.status})`, end: INTERRUPTED.has(settled.reason ?? '') ? 'interrupted' : 'error' };
+        const result = readResult(card, messages);
+        // A card without `result:` keeps its own result reader: no host validation, no repairs.
+        if (!card.result)
+            return result ? { result } : {};
+        const checked = result
+            ? (card.output ? { valid: true } : await validateResult(card, result.text, evidenceOf(card, messages), invoke, 'attempt', `result:${conversation.id}:markdown:${attempt}`))
+            : { valid: false, hint: card.output ? `Return the result using ${card.output.name}.` : 'Return a non-empty answer.' };
+        if (checked.valid && result) {
+            const validation = { card, evidence: evidenceOf(card, messages) };
+            const fresh = await validateResult(card, 'output' in result ? result.output : result.text, validation.evidence, invoke, 'delivery', `result-delivery:${conversation.id}:${crypto.randomUUID()}`);
+            return fresh.valid ? { result, validation } : { error: fresh.hint ?? 'Return a supported result.', end: 'invalid_output' };
+        }
+        const hint = checked.hint ?? 'Return a supported result.';
+        const attempts = card.output ? state.attempts + (state.attempts === previousAttempts ? 1 : 0) : attempt + 1;
+        if (attempts >= card.result.repairs + 1)
+            return { error: hint, end: 'invalid_output' };
+        if (card.output && state.attempts === previousAttempts)
+            await conversation.commit(async (tx) => { (await tx.doc(ResultBudget, conversation.id)).misses++; }, context);
+        previousAttempts = attempts;
+        submission = await conversation.submit({ type: 'input', content: `Invalid result: ${hint}\nReturn a corrected result.`, requestId: `repair:${conversation.id}:${attempt + 1}` }, context);
+    }
+}
+/** The `execute` of the result tool: validates the call the model made, spends the repair budget, and ends the turn when the budget is gone. */
+export function resultExecutor(card, invoke) {
+    return async (args, api, context) => {
+        const messages = await api.commit(tx => resultMessages(tx, api.conversationId), context);
+        const budget = await api.snapshot(ResultBudget, api.conversationId, context);
+        const state = resultState(card, messages, budget?.misses ?? 0);
+        const calls = callsOf(messages).filter(c => c.id === api.callId);
+        const output = calls[0]?.arguments ?? args;
+        let checked;
+        try {
+            checked = calls.length > 1 ? { valid: false, hint: 'Use a unique result call id.' }
+                : state.attempts > card.result.repairs + 1 ? { valid: false, hint: 'Result repair budget exhausted' }
+                    : await validateResult(card, output, evidenceOf(card, messages), invoke, 'attempt', `result:${api.conversationId}:${api.taskId}`);
+        }
+        catch (error) {
+            return { output: [{ type: 'text', text: 'Result validation failed.' }], isError: true, details: { resultValidation: validationError(error) }, control: { terminate: true } };
+        }
+        return {
+            output: [{ type: 'text', text: checked.valid ? 'Saved.' : `Invalid result: ${checked.hint}` }],
+            isError: !checked.valid, details: { resultValidation: { valid: checked.valid } },
+            ...(!checked.valid && state.attempts >= card.result.repairs + 1 ? { control: { terminate: true } } : {}),
+        };
+    };
+}

package/dist/runs.d.ts

@@ -0,0 +1,83 @@
+import type { ResultFailure } from './run-result.js';
+/**
+ * What a run is, in every home: the ways it ends, the view an operation reads, the usage it reports, and the delivery of its end
+ * to the operation that started it. The home keeps the run (a durable task on a Durable Object, a row in a person's SQLite file);
+ * these are the parts that must not differ between homes.
+ */
+/** How a run ends. `revoked`: the host's authority was withdrawn (a delivery or validation refused with 401/403). */
+export declare const RUN_ENDS: readonly ["completed", "invalid_output", "cancelled", "interrupted", "revoked", "error"];
+export type RunEnd = typeof RUN_ENDS[number];
+export type RunStatus = 'queued' | 'running' | RunEnd;
+/** The end code of a run that the host's spend cap refused (`error: "over_budget"`), and of a request it refused. */
+export declare const OVER_BUDGET = "over_budget";
+/** What a run used, summed over its model answers: tokens, cost in USD as pi-ai prices it, and the models that answered. */
+export interface RunUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly cost: number;
+    readonly models: readonly string[];
+}
+/** A run by its key, as the operation that started it reads it. `usage` is null for a run that never answered. */
+export interface RunView {
+    readonly run: string;
+    readonly status: RunStatus;
+    readonly startedAt?: string;
+    readonly output?: unknown;
+    readonly usage: RunUsage | null;
+    readonly error?: string;
+}
+/** What the delivery operation is called with: the run's end. */
+export interface RunPayload {
+    readonly run: string;
+    readonly status: RunEnd;
+    readonly output?: unknown;
+    readonly usage: RunUsage | null;
+    readonly error?: string;
+}
+/** Statuses a run can still be in, and ends the view carries an `error` text for. */
+export declare const isEnd: (status: string) => status is RunEnd;
+export declare const endsWithError: (status: string) => boolean;
+/** True when `error` is the spend meter's refusal (`over_budget`, 429), by its `code` or its `extra.code`. */
+export declare function isOverBudget(error: unknown): boolean;
+/**
+ * A run's model answers summed from its transcript messages (pi-ai's `usage` on each assistant message); null when none answered.
+ * `modelRef` names the model of a message (default: its `model`), for hosts that report `provider:model`; return undefined to skip one.
+ */
+export declare function sumUsage(messages: readonly unknown[], modelRef?: (message: {
+    provider?: string;
+    model?: string;
+}) => string | undefined): RunUsage | null;
+export interface DeliveryOptions {
+    /** The operation that receives the end (`deliver:` of the start). */
+    readonly operation: string;
+    /** The run's key: the delivery's receipt key is `deliver:<key>`, so the host's receipt makes the delivery once. */
+    readonly key: string;
+    readonly end: Omit<RunPayload, 'run'>;
+    /** Calls the operation as the person whose run it is. Resolve = delivered; throw = refused (the next attempt may pass). */
+    readonly invoke: (operation: string, input: unknown, key: string) => Promise<unknown>;
+    /** A completed run is checked again just before it is delivered (a `phase: "delivery"` check): its failure becomes the end delivered instead. */
+    readonly recheck?: () => Promise<ResultFailure | undefined>;
+    /** Told once when the re-check fails, before the delivery, so the home can record the failed end. */
+    readonly onFailure?: (failure: ResultFailure) => Promise<void> | void;
+    /** Attempts (default 3) and the first wait between two (default 20 ms, doubling). */
+    readonly attempts?: number;
+    readonly backoffMs?: number;
+}
+export interface DeliveryResult {
+    /** False when no attempt was accepted: the run's end stays undelivered and is delivered again later. */
+    readonly delivered: boolean;
+    /** The end as delivered or last tried: the re-check's failure replaces a completed end. */
+    readonly end: Omit<RunPayload, 'run'>;
+    readonly failure?: ResultFailure;
+    /** The last refusal, when not delivered. */
+    readonly error?: string;
+}
+/**
+ * Hand a run's end to the operation that started it, once however often it is tried: attempts are bounded, every one carries the same
+ * `deliver:<key>` receipt key, and a completed run is first checked again so a result that stopped being valid is delivered as
+ * `invalid_output` (or `revoked`), never as a success. A failed delivery is reported, not dropped: the home retries it later.
+ */
+export declare function deliverRunEnd(options: DeliveryOptions): Promise<DeliveryResult>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/runs.js

@@ -0,0 +1,83 @@
+/**
+ * What a run is, in every home: the ways it ends, the view an operation reads, the usage it reports, and the delivery of its end
+ * to the operation that started it. The home keeps the run (a durable task on a Durable Object, a row in a person's SQLite file);
+ * these are the parts that must not differ between homes.
+ */
+/** How a run ends. `revoked`: the host's authority was withdrawn (a delivery or validation refused with 401/403). */
+export const RUN_ENDS = Object.freeze(['completed', 'invalid_output', 'cancelled', 'interrupted', 'revoked', 'error']);
+/** The end code of a run that the host's spend cap refused (`error: "over_budget"`), and of a request it refused. */
+export const OVER_BUDGET = 'over_budget';
+/** Statuses a run can still be in, and ends the view carries an `error` text for. */
+export const isEnd = (status) => RUN_ENDS.includes(status);
+const WITH_ERROR = new Set(['error', 'interrupted', 'invalid_output', 'revoked']);
+export const endsWithError = (status) => WITH_ERROR.has(status);
+/** True when `error` is the spend meter's refusal (`over_budget`, 429), by its `code` or its `extra.code`. */
+export function isOverBudget(error) {
+    const e = error;
+    return (e?.code ?? e?.extra?.code) === OVER_BUDGET;
+}
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+/**
+ * A run's model answers summed from its transcript messages (pi-ai's `usage` on each assistant message); null when none answered.
+ * `modelRef` names the model of a message (default: its `model`), for hosts that report `provider:model`; return undefined to skip one.
+ */
+export function sumUsage(messages, modelRef = (m) => m.model) {
+    let answered = false, input = 0, output = 0, cacheRead = 0, cacheWrite = 0, cost = 0;
+    const models = [];
+    for (const raw of messages) {
+        const message = raw;
+        if (message?.role !== 'assistant' || !message.usage)
+            continue;
+        const u = message.usage;
+        answered = true;
+        input += count(u.input);
+        output += count(u.output);
+        cacheRead += count(u.cacheRead);
+        cacheWrite += count(u.cacheWrite);
+        cost += count(u.cost?.total);
+        const ref = typeof message.model === 'string' ? modelRef(message) : undefined;
+        if (ref && !models.includes(ref))
+            models.push(ref);
+    }
+    return answered ? { input, output, cacheRead, cacheWrite, cost, models } : null;
+}
+/**
+ * Hand a run's end to the operation that started it, once however often it is tried: attempts are bounded, every one carries the same
+ * `deliver:<key>` receipt key, and a completed run is first checked again so a result that stopped being valid is delivered as
+ * `invalid_output` (or `revoked`), never as a success. A failed delivery is reported, not dropped: the home retries it later.
+ */
+export async function deliverRunEnd(options) {
+    const { operation, key, invoke, recheck, onFailure, attempts = 3, backoffMs = 20 } = options;
+    let end = options.end, failure, last;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt)
+            await new Promise(resolve => setTimeout(resolve, backoffMs * 2 ** (attempt - 1)));
+        if (end.status === 'completed' && recheck) {
+            let found;
+            try {
+                found = await recheck();
+            }
+            catch (error) {
+                // Only a refusal by authority changes the end; any other throw (an outage) leaves it completed, tried again.
+                const status = error?.status;
+                last = error?.message ?? error;
+                if (status !== 401 && status !== 403)
+                    continue;
+                found = { error: String(last).slice(0, 500), end: 'revoked' };
+            }
+            if (found) {
+                failure = found;
+                end = { status: found.end, usage: end.usage, error: found.error };
+                await onFailure?.(found);
+            }
+        }
+        try {
+            await invoke(operation, { run: key, ...end }, `deliver:${key}`);
+            return { delivered: true, end, ...(failure ? { failure } : {}) };
+        }
+        catch (error) {
+            last = error?.message ?? error;
+        }
+    }
+    return { delivered: false, end, ...(failure ? { failure } : {}), error: `deliver ${operation}: ${String(last).slice(0, 200)}` };
+}

package/dist/schedule.d.ts

@@ -33,7 +33,7 @@ export declare const ConversationSchedules: import("@earendil-works/pi-durable")
     next: number;
 }>;
 /**
- * The native durable task behind one schedule: it sleeps on the Harness clock (`runtime.sleep`), then delivers the instruction to
+ * The native durable task behind one schedule: it waits on the Harness clock (`runtime.setTimer`), 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.

package/dist/schedule.js

@@ -1,6 +1,7 @@
 import { defineDoc, defineExtension, defineTask, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
 import { withAbortSignal } from '@earendil-works/chord/context';
+import { waitUntil } from './wait-until.js';
 export const SCHEDULE_TOOL = 'schedule';
 export const LIST_SCHEDULES_TOOL = 'list_schedules';
 export const CANCEL_SCHEDULE_TOOL = 'cancel_schedule';
@@ -11,7 +12,7 @@ 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 }),
+    kind: 'boring.schedules', checkpointWhen: () => false, 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); };
@@ -27,7 +28,13 @@ async function sleepUnlessCancelled(runtime, input, context) {
             return true;
         watch.start(async (value) => { if (cancelledIn(value))
             cancel.abort(); });
-        await runtime.sleep(input.runAt, withAbortSignal(cancel.signal, context));
+        const wait = waitUntil(runtime, input.runAt, withAbortSignal(cancel.signal, context));
+        try {
+            await wait.done;
+        }
+        finally {
+            wait.disarm();
+        }
         return false;
     }
     catch (error) {
@@ -40,7 +47,7 @@ async function sleepUnlessCancelled(runtime, input, context) {
     }
 }
 /**
- * The native durable task behind one schedule: it sleeps on the Harness clock (`runtime.sleep`), then delivers the instruction to
+ * The native durable task behind one schedule: it waits on the Harness clock (`runtime.setTimer`), 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.

package/dist/view-open.js

@@ -12,7 +12,7 @@ export const VIEW_OPEN_TIMEOUT_MS = 15_000;
 export const PRESENT_TOOL = 'present';
 /** One member per assistant entry and tool call, in the calling conversation. */
 const documents = defineDocFamily({
-    kind: 'boring.view-open', version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
+    kind: 'boring.view-open', checkpointWhen: () => false, version: 1, scope: 'conversation', history: 'latest', fork: 'initial', family: true,
     initial: () => ({ view: null }),
 });
 const MAX_REASON = 200;

package/dist/wait-until.d.ts

@@ -0,0 +1,12 @@
+import type { TaskRuntime } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+/**
+ * Wait inside the running phase until the Harness clock reaches `at`, on the Harness's own timer (`TaskRuntime.setTimer`, the
+ * 1.4 replacement for the removed `TaskRuntime.sleep`). It rejects when `context` is cancelled first. `disarm` frees the timer
+ * when something else ends the wait. It is not durable: a restart reruns the phase, which reads its absolute deadline again.
+ */
+export declare function waitUntil(runtime: Pick<TaskRuntime<never, never, never, never>, 'now' | 'setTimer'>, at: number, context: Context): {
+    readonly done: Promise<void>;
+    readonly disarm: () => void;
+};
+//# sourceMappingURL=wait-until.d.ts.map

package/dist/wait-until.js

@@ -0,0 +1,20 @@
+/**
+ * Wait inside the running phase until the Harness clock reaches `at`, on the Harness's own timer (`TaskRuntime.setTimer`, the
+ * 1.4 replacement for the removed `TaskRuntime.sleep`). It rejects when `context` is cancelled first. `disarm` frees the timer
+ * when something else ends the wait. It is not durable: a restart reruns the phase, which reads its absolute deadline again.
+ */
+export function waitUntil(runtime, at, context) {
+    let disarm = () => { };
+    const done = new Promise((resolve, reject) => {
+        const signal = context.abortSignal;
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Wait cancelled'));
+            return;
+        }
+        const onAbort = () => { disarm(); reject(signal.reason ?? new Error('Wait cancelled')); };
+        const disarmTimer = runtime.setTimer(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, Math.max(0, at - runtime.now()));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        disarm = () => { signal?.removeEventListener('abort', onAbort); disarmTimer(); };
+    });
+    return { done, disarm: () => disarm() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -148,6 +148,26 @@
     "./room": {
       "types": "./dist/room.d.ts",
       "import": "./dist/room.js"
+    },
+    "./run-result": {
+      "types": "./dist/run-result.d.ts",
+      "import": "./dist/run-result.js"
+    },
+    "./runs": {
+      "types": "./dist/runs.d.ts",
+      "import": "./dist/runs.js"
+    },
+    "./run-ledger": {
+      "types": "./dist/run-ledger.d.ts",
+      "import": "./dist/run-ledger.js"
+    },
+    "./run-outbox": {
+      "types": "./dist/run-outbox.d.ts",
+      "import": "./dist/run-outbox.js"
+    },
+    "./actions": {
+      "types": "./dist/actions.d.ts",
+      "import": "./dist/actions.js"
     }
   },
   "dependencies": {
@@ -157,11 +177,12 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
-    "@earendil-works/pi-durable": "~1.2.0",
-    "@earendil-works/pi-ai": "~1.2.0",
-    "@earendil-works/chord": "~1.2.0",
-    "@hachej/boring-files": "^0.4.26",
-    "@hachej/boring-ui-kit": "^0.4.26",
+    "@earendil-works/pi-durable": "~1.4.0",
+    "@earendil-works/pi-ai": "~1.4.0",
+    "@earendil-works/chord": "~1.4.0",
+    "@hachej/boring-files": "^0.4.28",
+    "@hachej/boring-ui-kit": "^0.4.28",
+    "typebox": "1.3.27",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {