@hachej/boring-agent 0.1.111 → 0.2.1

package/dist/browser-task.js

@@ -0,0 +1,119 @@
+// @hachej/boring-agent/browser-task: a native Pi tool that hands a task to the person's open page and waits, durably, for the page's
+// structured answer: the same wait as `ask_user` (./durable-wait.ts) with a JSON object for an answer instead of a short text.
+// The page finds the pending call in the conversation it already watches (the tool call with no result yet), does the task with
+// the person (for example a live preview of a change, `browser_preview` in `@hachej/boring-feedback/agent`) and answers through the same
+// authenticated path as a question: the chat transport's `?op=answer`, with the call's `[assistantEntryId, callId]` binding.
+// Nothing runs in the page because of this tool alone; the host decides which page code picks the task up.
+import { defineDocFamily, defineTool } from '@earendil-works/pi-durable';
+import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
+import { AmbiguousCall, UnknownCall, callBinding, callBindingId, ownBindingKey, waitForDocument } from './durable-wait.js';
+/** Upper bound on an answer's UTF-8 JSON, by default. */
+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,
+    initial: () => ({ task: null }),
+});
+/** The answer ID of a browser task call: the same `[assistantEntryId, callId]` binding as `askUserQuestionId`. */
+export const browserTaskId = callBindingId;
+const encoder = new TextEncoder();
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/**
+ * A native Pi tool that waits for the person's page to answer, without holding a model request. Pending calls survive a restart
+ * (the replay-safe call re-attaches to its record) and are cancelled with the call when the conversation is stopped. The result
+ * text is the page's answer, as JSON. Answer it with `answerBrowserTask`.
+ */
+export function createBrowserTaskTool(options) {
+    if (!/^[a-z][a-z0-9_]{0,63}$/.test(options.name))
+        throw new TypeError('A browser task needs a snake_case tool name');
+    return defineTool({
+        name: options.name,
+        description: options.description,
+        parameters: options.parameters,
+        replay: 'safe',
+        execute: async (_args, api, context) => {
+            const key = await api.commit(async (tx) => {
+                const key = await ownBindingKey(tx, api);
+                const document = await tx.doc(documents, api.conversationId, key, null);
+                if (!document.task)
+                    document.task = { tool: options.name, taskId: api.taskId, state: { kind: 'pending' } };
+                if (document.task.taskId !== api.taskId)
+                    throw new Error('Browser task identity belongs to another task');
+                return key;
+            }, context);
+            const final = await waitForDocument(api, documents, key, context, value => value?.task?.state.kind !== 'pending', async (tx) => {
+                const { task } = await tx.doc(documents, api.conversationId, key, null);
+                if (task?.state.kind === 'pending')
+                    task.state = { kind: 'cancelled' };
+            }, 'Browser task');
+            const state = final?.task?.state;
+            if (state?.kind !== 'answered')
+                throw new Error('Browser task cancelled');
+            return { content: [{ type: 'text', text: JSON.stringify(state.answer) }] };
+        },
+    });
+}
+/**
+ * Settles a pending browser task with the page's answer (a JSON object as text) after the host authenticated the person. `id` is
+ * `browserTaskId(assistantEntryId, callId)` (an unscoped call ID only when exactly one native task used it). The answer goes through
+ * the tool's own `checkAnswer` (pass the same options as the tool). Exactly one answer is accepted; repeating it is idempotent.
+ * Returns the `ask_user` outcome kinds, so one chat transport `answer` serves both.
+ */
+export async function answerBrowserTask(conversation, tool, id, answer, context = BACKGROUND_CONTEXT) {
+    if (typeof id !== 'string' || !id || id.length > 1024)
+        return { kind: 'unknown-question' };
+    if (typeof answer !== 'string')
+        return { kind: 'denied', reason: 'The answer must be JSON text' };
+    const max = tool.maxAnswerBytes ?? BROWSER_TASK_MAX_ANSWER;
+    if (encoder.encode(answer).length > max)
+        return { kind: 'denied', reason: `The answer is larger than ${max} bytes` };
+    let value;
+    try {
+        value = JSON.parse(answer);
+    }
+    catch {
+        return { kind: 'denied', reason: 'The answer is not JSON' };
+    }
+    if (!isObject(value))
+        return { kind: 'denied', reason: 'The answer must be a JSON object' };
+    const parsed = value;
+    try {
+        return await conversation.commit(async (tx) => {
+            const binding = await callBinding(tx, conversation, id);
+            const task = await tx.task(binding.taskId);
+            if (!task)
+                return { kind: 'conflict', reason: 'The browser task is unavailable' };
+            const document = await tx.doc(documents, conversation.id, binding.key, null);
+            // Throwing rolls back the empty draft an unknown or foreign call would leave behind.
+            if (!document.task || document.task.tool !== tool.name)
+                throw new UnknownCall();
+            const record = document.task;
+            if (record.taskId !== task.id)
+                return { kind: 'conflict', reason: 'The browser task belongs to another task' };
+            if (task.abortRequested) {
+                record.state = { kind: 'cancelled' };
+                return { kind: 'conflict', reason: 'The browser task was cancelled' };
+            }
+            if (record.state.kind === 'answered')
+                return JSON.stringify(record.state.answer) === JSON.stringify(parsed) ? { kind: 'answered' } : { kind: 'conflict', reason: 'The browser task was already answered' };
+            if (record.state.kind === 'cancelled')
+                return { kind: 'conflict', reason: 'The browser task was cancelled' };
+            if (task.state.status === 'terminal') {
+                record.state = { kind: 'cancelled' };
+                return { kind: 'conflict', reason: 'The browser task was cancelled' };
+            }
+            const problem = tool.checkAnswer(parsed);
+            if (problem)
+                return { kind: 'denied', reason: problem };
+            record.state = { kind: 'answered', answer: parsed };
+            return { kind: 'answered' };
+        }, context);
+    }
+    catch (error) {
+        if (error instanceof AmbiguousCall)
+            return { kind: 'conflict', reason: 'Use the assistant-entry-bound call ID' };
+        if (error instanceof UnknownCall)
+            return { kind: 'unknown-question' };
+        throw error;
+    }
+}

package/dist/chat-transport.d.ts

@@ -0,0 +1,80 @@
+import type { Context } from '@earendil-works/chord';
+import type { Conversation, ConversationView, InputSubmissionDraft, SubmissionId } from '@earendil-works/pi-durable';
+/** Wire protocol shared with the browser client in `@hachej/boring-ui-kit/remote-chat`. */
+export declare const CHAT_TRANSPORT: Readonly<{
+    schema: "boring.chat-transport";
+    version: 1;
+    maxRequestBytes: 8388608;
+    maxHistoryPage: 200;
+    maxPendingFrames: 100;
+    heartbeatMs: 15000;
+}>;
+/** The agent change a browser may ask for. Names only: the host maps it to a native `AgentChange`. */
+export interface ChatConfigureChange {
+    readonly model?: {
+        readonly provider: string;
+        readonly modelId: string;
+    };
+    readonly thinkingLevel?: string;
+}
+export interface ChatTransportAccess {
+    readonly conversation: Conversation;
+    readonly context: Context;
+    /** The host aborts on revocation or identity change; open watches then end. */
+    readonly revoked?: AbortSignal;
+    /**
+     * Remove fields the caller may not see. Without it the raw native view is sent to a trusted viewer. With it, raw
+     * conversation data never leaves the host: every read (the watch, `?op=entries` history pages, `?op=submission`) goes
+     * through it. History pages are projected as a view holding just the page's entries and no documents.
+     */
+    readonly project?: (view: ConversationView) => ConversationView;
+    /** Resolve a pending `ask_user` call. The host authenticates the person; without it `?op=answer` is not supported. */
+    readonly answer?: (questionId: string, answer: string) => Promise<unknown>;
+    /**
+     * Change the conversation's native agent (`conversation.configure`). The host validates the change against its own
+     * allow-list and returns a refusal (for example `{ kind: 'refused', reason }`) instead of applying it; this handler
+     * never decides which models or levels are allowed. Without it `?op=configure` is not supported.
+     */
+    readonly configure?: (change: ChatConfigureChange) => Promise<unknown>;
+    /**
+     * Improve a submitted input on the host before it reaches the native conversation, for example resolve `@path`
+     * mentions into file content with `createMentionResolver` from `@hachej/boring-agent/mentions`. It must return the
+     * input to submit; if it throws, the original input is submitted unchanged so a message is never lost.
+     */
+    readonly prepareInput?: (content: InputSubmissionDraft['content']) => Promise<InputSubmissionDraft['content']>;
+    /**
+     * Withdraw one queued input: the host binds the native `Harness.abortSubmission(id, context, conversation.id)`, which
+     * scopes the id to this conversation. Without it `?op=withdraw` is not supported. This handler never edits the inbox.
+     */
+    readonly abortSubmission?: (id: SubmissionId) => Promise<'aborted' | 'already_placed' | 'settled' | 'not_found'>;
+    /** Refuse an effect call. Reading stays governed by `authenticate` and `project`. */
+    readonly allow?: (operation: 'submit' | 'abort' | 'answer' | 'withdraw' | 'configure') => boolean | Promise<boolean>;
+}
+export interface ChatTransportOptions {
+    /**
+     * Authenticate and select the native conversation in trusted host code. Null refuses. The host also enforces its
+     * Origin/CSRF policy here; this handler only requires `application/json` on every POST, which a cross-site form
+     * cannot send without a preflight.
+     */
+    readonly authenticate: (request: Request) => Promise<ChatTransportAccess | null>;
+    /**
+     * While the watch stream has nothing to send, write `{"kind":"heartbeat","intervalMs":N}` every N milliseconds (default
+     * `CHAT_TRANSPORT.heartbeatMs`, 15 s; 0 turns it off). Proxies and load balancers close a response that stays silent past
+     * their idle timeout (an AWS ALB after 60 s by default); the browser client ignores the frame for the transcript and treats a
+     * stream silent for 2.5 intervals as lost, then reopens it. The first heartbeat follows the first view, announcing the interval.
+     */
+    readonly heartbeatMs?: number;
+}
+/**
+ * Authenticated Fetch adapter over one native conversation: watch, submit, abort, configure, submission lookup and history.
+ * It adds no execution lifecycle. A closed connection says nothing about the native task.
+ */
+export declare function createChatTransportHandler(options: ChatTransportOptions): (request: Request) => Promise<Response>;
+/**
+ * A view of a native conversation whose `submit` first hands the input to a host admission function (for example Cloudflare's
+ * `PiHarness.submit`, which schedules the wake job that restarts an evicted Durable Object) and then answers with the native
+ * submission, found by its request ID. Every other member is the native conversation, bound to it. The admission must be
+ * idempotent on `requestId`, as native submission is.
+ */
+export declare function routeSubmissions(conversation: Conversation, admit: (draft: InputSubmissionDraft, context: Context) => Promise<unknown>): Conversation;
+//# sourceMappingURL=chat-transport.d.ts.map

package/dist/chat-transport.js

@@ -0,0 +1,306 @@
+import { RequestGuardError, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
+/** Wire protocol shared with the browser client in `@hachej/boring-ui-kit/remote-chat`. */
+export const CHAT_TRANSPORT = Object.freeze({ schema: 'boring.chat-transport', version: 1, maxRequestBytes: 8_388_608, maxHistoryPage: 200, maxPendingFrames: 100, heartbeatMs: 15_000 });
+/** `no-transform` keeps proxies from compressing or rewriting responses; the watch stream adds `x-accel-buffering: no` so nginx does not buffer it. */
+const headers = { 'cache-control': 'no-store, no-transform', 'x-content-type-options': 'nosniff' };
+const failure = (status, reason) => Response.json({ schema: CHAT_TRANSPORT.schema, version: CHAT_TRANSPORT.version, reason }, { status, headers });
+const json = (value) => Response.json(value, { headers });
+const encoder = new TextEncoder();
+function content(value) {
+    if (typeof value === 'string')
+        return value.length > 0;
+    return Array.isArray(value) && value.length > 0 && value.every(part => part !== null && typeof part === 'object'
+        && ((part.type === 'text' && typeof part.text === 'string') || (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string')));
+}
+async function body(request) {
+    const value = await readJsonBody(request, CHAT_TRANSPORT.maxRequestBytes, request.signal);
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new RequestGuardError(400, 'Expected a JSON object');
+    return value;
+}
+/**
+ * The only way conversation data other than the watch leaves this handler. With `project` set, history entries are
+ * projected and a submission record loses its free-form `detail`; `npm run check` fails if the native history read or
+ * submission lookup is called anywhere else in this file.
+ */
+function reads(conversation, context, project) {
+    return {
+        async entries(limit, cursor) {
+            const page = await conversation.entries({}, limit, cursor, context);
+            if (!project)
+                return page;
+            const record = await conversation.commit(tx => tx.conversation(conversation.id), context);
+            if (!record)
+                throw new Error('The conversation is not available');
+            let items;
+            try {
+                items = project({ conversation: record, entries: page.items, docs: {} }).entries;
+            }
+            catch {
+                throw new Error('projection_failed');
+            }
+            return { ...page, items };
+        },
+        async submission(requestId) {
+            const record = await conversation.commit(tx => tx.submissionByRequest(conversation.id, requestId), context);
+            if (!record)
+                return null;
+            if (!project || record.detail === undefined)
+                return record;
+            const { detail: _detail, ...rest } = record;
+            return rest;
+        },
+    };
+}
+/**
+ * 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:
+ * the viewer receives complete projected views, and a slow reader gets the latest one rather than a backlog.
+ */
+function stream(watch, project, signal, heartbeatMs) {
+    let pending = [{ kind: 'view', view: watch.value }], wake, end, finished = false;
+    // `beat` asks the next pull for a heartbeat. The timer restarts after every frame, so it fires only on an idle stream, and it is
+    // cleared when the stream finishes or is cancelled: nothing outlives the response.
+    let beat = false, timer;
+    const notify = () => { const resume = wake; wake = undefined; resume?.(); };
+    const idle = () => { clearTimeout(timer); timer = undefined; if (heartbeatMs > 0 && !finished)
+        timer = setTimeout(() => { beat = true; notify(); }, heartbeatMs); };
+    const heartbeat = () => encoder.encode(JSON.stringify({ kind: 'heartbeat', intervalMs: heartbeatMs }) + '\n');
+    const stop = () => { pending = []; clearTimeout(timer); notify(); void watch.stop(); };
+    signal.addEventListener('abort', stop, { once: true });
+    watch.start(async (view, ops) => {
+        if (signal.aborted)
+            return;
+        if (project || pending.length >= CHAT_TRANSPORT.maxPendingFrames)
+            pending = [{ kind: 'view', view }];
+        else
+            pending.push({ kind: 'ops', ops });
+        notify();
+    });
+    void watch.closed.then(result => { end = result; signal.removeEventListener('abort', stop); notify(); });
+    let started = false;
+    const frames = new ReadableStream({
+        async pull(controller) {
+            while (pending.length === 0 && !beat && end === undefined && !signal.aborted)
+                await new Promise(resolve => { wake = resolve; });
+            if (finished)
+                return;
+            const close = (reason) => {
+                finished = true;
+                clearTimeout(timer);
+                controller.enqueue(encoder.encode(JSON.stringify({ kind: 'end', reason }) + '\n'));
+                controller.close();
+            };
+            if (signal.aborted) {
+                close('revoked');
+                return;
+            }
+            const frame = pending.shift();
+            if (frame) {
+                let line;
+                try {
+                    line = JSON.stringify(frame.kind === 'view' && project ? { kind: 'view', view: project(frame.view) } : frame);
+                }
+                catch {
+                    finished = true;
+                    stop();
+                    controller.enqueue(encoder.encode(JSON.stringify({ kind: 'end', reason: 'projection_failed' }) + '\n'));
+                    controller.close();
+                    return;
+                }
+                if (signal.aborted) {
+                    close('revoked');
+                    return;
+                }
+                controller.enqueue(encoder.encode(line + '\n'));
+                // The first frame is followed by a heartbeat at once, so the client learns the interval before any idle period.
+                if (!started && heartbeatMs > 0) {
+                    started = true;
+                    controller.enqueue(heartbeat());
+                }
+                beat = false;
+                idle();
+                return;
+            }
+            if (beat && end === undefined) {
+                beat = false;
+                controller.enqueue(heartbeat());
+                idle();
+                return;
+            }
+            finished = true;
+            clearTimeout(timer);
+            controller.enqueue(encoder.encode(JSON.stringify({ kind: 'end', reason: end.reason }) + '\n'));
+            controller.close();
+        },
+        cancel() { finished = true; stop(); },
+    });
+    return new Response(frames, { headers: { ...headers, 'content-type': 'application/x-ndjson; charset=utf-8', 'x-accel-buffering': 'no' } });
+}
+/**
+ * Authenticated Fetch adapter over one native conversation: watch, submit, abort, configure, submission lookup and history.
+ * It adds no execution lifecycle. A closed connection says nothing about the native task.
+ */
+export function createChatTransportHandler(options) {
+    return async (request) => {
+        const operation = new URL(request.url).searchParams.get('op');
+        if (request.method === 'POST' && !hasJsonContentType(request.headers))
+            return failure(415, 'unsupported-media-type');
+        let access;
+        try {
+            access = await options.authenticate(request);
+        }
+        catch {
+            return failure(503, 'authentication-unavailable');
+        }
+        if (!access)
+            return failure(401, 'authentication-required');
+        const { conversation, context } = access;
+        if (access.revoked?.aborted)
+            return failure(403, 'not-authorized');
+        const read = reads(conversation, context, access.project);
+        const allowed = async (effect) => {
+            if (access.revoked?.aborted)
+                return false;
+            const granted = access.allow === undefined || await access.allow(effect) === true;
+            return granted && !access.revoked?.aborted;
+        };
+        const params = new URL(request.url).searchParams;
+        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();
+                    return failure(403, 'not-authorized');
+                }
+                return stream(watch, access.project, signal, options.heartbeatMs ?? CHAT_TRANSPORT.heartbeatMs);
+            }
+            if (request.method === 'GET' && operation === 'submission') {
+                const requestId = params.get('requestId');
+                if (!requestId)
+                    return failure(400, 'invalid-request');
+                const record = await read.submission(requestId);
+                if (access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
+                return json({ record });
+            }
+            if (request.method === 'GET' && operation === 'entries') {
+                const limit = Number(params.get('limit'));
+                if (!Number.isInteger(limit) || limit < 1 || limit > CHAT_TRANSPORT.maxHistoryPage)
+                    return failure(400, 'invalid-request');
+                let cursor;
+                const encoded = params.get('cursor');
+                if (encoded !== null) {
+                    try {
+                        cursor = JSON.parse(encoded);
+                    }
+                    catch {
+                        return failure(400, 'invalid-request');
+                    }
+                }
+                const page = await read.entries(limit, cursor);
+                if (access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
+                return json({ page });
+            }
+            if (request.method === 'POST' && operation === 'submit') {
+                const input = await body(request);
+                if (typeof input['requestId'] !== 'string' || !input['requestId'] || !content(input['content'])
+                    || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string'))
+                    return failure(400, 'invalid-request');
+                let prepared = input['content'];
+                if (access.prepareInput) {
+                    try {
+                        prepared = await access.prepareInput(prepared);
+                    }
+                    catch { /* submit what the person typed */ }
+                }
+                if (!await allowed('submit') || access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
+                const submission = await conversation.submit({ type: 'input', requestId: input['requestId'], content: prepared,
+                    ...(input['whenBusy'] === undefined ? {} : { whenBusy: input['whenBusy'] }) }, context);
+                return json({ submissionId: submission.id });
+            }
+            if (request.method === 'POST' && operation === 'abort') {
+                if (!await allowed('abort') || access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
+                // The body carries nothing, but it is read under the shared guard before answering: on Workers a body still unread
+                // when the response is sent makes the runtime throw "Can't read from request stream after response has been sent".
+                await body(request).catch(() => undefined);
+                await conversation.abort(context);
+                return json({ aborted: true });
+            }
+            if (request.method === 'POST' && operation === 'answer') {
+                if (!access.answer)
+                    return failure(404, 'not-supported');
+                const input = await body(request);
+                if (typeof input['callId'] !== 'string' || !input['callId'] || typeof input['answer'] !== 'string')
+                    return failure(400, 'invalid-request');
+                if (!await allowed('answer'))
+                    return failure(403, 'not-authorized');
+                return json(await access.answer(input['callId'], input['answer']));
+            }
+            if (request.method === 'POST' && operation === 'configure') {
+                if (!access.configure)
+                    return failure(404, 'not-supported');
+                const input = await body(request);
+                const model = input['model'], level = input['thinkingLevel'];
+                const validModel = model === undefined || (model !== null && typeof model === 'object' && !Array.isArray(model)
+                    && typeof model['provider'] === 'string' && typeof model['modelId'] === 'string');
+                if (!validModel || (level !== undefined && typeof level !== 'string') || (model === undefined && level === undefined))
+                    return failure(400, 'invalid-request');
+                const { provider, modelId } = (model ?? {});
+                if (!await allowed('configure') || access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
+                return json(await access.configure({ ...(model === undefined ? {} : { model: { provider: provider, modelId: modelId } }), ...(level === undefined ? {} : { thinkingLevel: level }) }));
+            }
+            if (request.method === 'POST' && operation === 'withdraw') {
+                if (!access.abortSubmission)
+                    return failure(404, 'not-supported');
+                const id = (await body(request))['submissionId'];
+                if (typeof id !== 'number' && typeof id !== 'string')
+                    return failure(400, 'invalid-request');
+                if (!await allowed('withdraw'))
+                    return failure(403, 'not-authorized');
+                // The native operation scopes the id to this conversation; an unknown or foreign id is "too late" to the caller.
+                const result = await access.abortSubmission(id);
+                return json({ result: result === 'not_found' ? 'settled' : result });
+            }
+        }
+        catch (error) {
+            if (error instanceof RequestGuardError)
+                return failure(error.status, error.status === 413 ? 'request-too-large' : error.status === 415 ? 'unsupported-media-type' : 'invalid-request');
+            // A host admission refused the input before it reached the conversation (for example `MeteringRefused` from `@hachej/boring-agent/metering`).
+            if (error instanceof Error && error.code === 'submission-refused') {
+                return Response.json({ schema: CHAT_TRANSPORT.schema, version: CHAT_TRANSPORT.version, reason: 'submission-refused', message: error.message.slice(0, 500) }, { status: 402, headers });
+            }
+            return failure(503, error instanceof Error && error.message ? `source-unavailable: ${error.message.slice(0, 200)}` : 'source-unavailable');
+        }
+        return failure(404, 'unknown-operation');
+    };
+}
+/**
+ * A view of a native conversation whose `submit` first hands the input to a host admission function (for example Cloudflare's
+ * `PiHarness.submit`, which schedules the wake job that restarts an evicted Durable Object) and then answers with the native
+ * submission, found by its request ID. Every other member is the native conversation, bound to it. The admission must be
+ * idempotent on `requestId`, as native submission is.
+ */
+export function routeSubmissions(conversation, admit) {
+    return new Proxy(conversation, { get: (target, key) => {
+            if (key === 'submit') {
+                return async (draft, context) => {
+                    const requestId = draft.requestId;
+                    if (!requestId)
+                        throw new TypeError('A request ID is required');
+                    await admit(draft, context);
+                    const record = await target.commit(tx => tx.submissionByRequest(target.id, requestId), context);
+                    if (!record)
+                        throw new Error('The submission was not recorded');
+                    return { id: record.id };
+                };
+            }
+            const value = Reflect.get(target, key, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        } });
+}

package/dist/contracts.d.ts

@@ -0,0 +1,40 @@
+import type { Harness, ConversationId, TaskId } from '@earendil-works/pi-durable';
+/** Borrow only the native handle. A second independently supplied Registry
+ * cannot prove it belongs to this Harness. The host installs native features
+ * explicitly through its own registry; passive attachment needs no registry.
+ */
+export interface AttachmentInput<NativeHarness extends Harness = Harness> {
+    readonly harness: NativeHarness;
+}
+export interface BorrowedAttachment<NativeHarness extends Harness = Harness> {
+    readonly harness: NativeHarness;
+    readonly detach: () => Promise<void>;
+}
+/** Host services keep their own APIs. Native defineTool/ToolRegistration,
+ * ToolExecutionApi and ToolExecutionResult are the tool contract; no parallel
+ * Boring HostOperation, RuntimeSchema or reduced execution-result envelope.
+ */
+export interface RuntimeQuestionRef {
+    readonly runtimeId: string;
+    readonly conversationId: ConversationId;
+    readonly taskId: TaskId;
+    readonly questionId: string;
+    readonly scopeId: string;
+    readonly subjectDigest: string;
+    readonly policyVersion: string;
+    readonly expiresAt: string;
+}
+export interface QuestionResolution<Answer> {
+    readonly question: RuntimeQuestionRef;
+    readonly resolutionId: string;
+    readonly answer: Answer;
+}
+/** References to native tasks, never a second job model. Preserve result type. */
+export interface DeliveryBinding<Result = unknown> {
+    readonly producer: TaskId<Result>;
+    readonly delivery: TaskId;
+    readonly operationId: string;
+    readonly inputDigest: string;
+    readonly recoverableInputRef: string;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};