@hachej/boring-agent 0.1.110 → 0.2.0

package/dist/delivery-input.d.ts

@@ -0,0 +1,35 @@
+import type { TaskId } from '@earendil-works/pi-durable';
+import type { ResourceAccess, ResourceExpectation } from '@hachej/boring-files';
+type Identity = Pick<ResourceAccess, 'principalId' | 'scopeId' | 'initiatorId'> & {
+    authorizationRef: string | null;
+};
+export type DocumentDeliveryTarget = ResourceExpectation & {
+    readonly preconditions?: readonly ResourceExpectation[];
+};
+export type DeliveryInput = {
+    producer: TaskId<string>;
+    target: ResourceExpectation;
+    preconditions: readonly ResourceExpectation[];
+    identity: Identity;
+    namespace: string;
+    validationVersion: string;
+};
+export type DeliveryPhase = {
+    phase: 'wait';
+} | {
+    phase: 'validate';
+} | {
+    phase: 'publish';
+    text: string;
+};
+export declare function captureDeliveryTarget(value: DocumentDeliveryTarget): {
+    target: ResourceExpectation;
+    preconditions: ResourceExpectation[];
+};
+export declare function identity(access: ResourceAccess): Identity;
+export declare function migrateDelivery(input: unknown, checkpoint: unknown, fromVersion: number): {
+    input: DeliveryInput;
+    checkpoint: DeliveryPhase;
+};
+export {};
+//# sourceMappingURL=delivery-input.d.ts.map

package/dist/delivery-input.js

@@ -0,0 +1,56 @@
+import { locator, reference } from '@hachej/boring-files/publication';
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Invalid delivery binding');
+    return Object.fromEntries(Object.entries(value));
+}
+function expectation(value) {
+    const input = object(value);
+    if (input.kind === 'absent')
+        return { kind: 'absent', target: locator(input.target) };
+    if (input.kind === 'revision')
+        return { kind: 'revision', target: reference(input.target) };
+    throw new TypeError('Invalid delivery expectation');
+}
+export function captureDeliveryTarget(value) {
+    const input = object(value);
+    if (input.preconditions !== undefined && !Array.isArray(input.preconditions))
+        throw new TypeError('Invalid delivery preconditions');
+    return { target: expectation(input), preconditions: input.preconditions === undefined ? [] : Array.from(input.preconditions, expectation) };
+}
+export function identity(access) {
+    const result = { principalId: access.principalId, scopeId: access.scopeId, initiatorId: access.initiatorId, authorizationRef: access.authorizationRef ?? null };
+    if ([result.principalId, result.scopeId, result.initiatorId].some(value => typeof value !== 'string' || !value))
+        throw new TypeError('Delivery requires an authenticated identity');
+    return result;
+}
+function nonempty(value) {
+    if (typeof value !== 'string' || !value)
+        throw new TypeError('Invalid v1 delivery binding');
+    return value;
+}
+function producerId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+export function migrateDelivery(input, checkpoint, fromVersion) {
+    if (fromVersion !== 1)
+        throw new TypeError('Unsupported delivery version');
+    const old = object(input), phase = object(checkpoint), actor = object(old.identity);
+    if (!producerId(old.producer) || 'preconditions' in old)
+        throw new TypeError('Invalid v1 delivery input');
+    if (actor.authorizationRef !== null && typeof actor.authorizationRef !== 'string')
+        throw new TypeError('Invalid v1 delivery identity');
+    const migrated = {
+        producer: old.producer, target: expectation(old.target), preconditions: [],
+        identity: {
+            principalId: nonempty(actor.principalId), scopeId: nonempty(actor.scopeId), initiatorId: nonempty(actor.initiatorId),
+            authorizationRef: actor.authorizationRef,
+        },
+        namespace: nonempty(old.namespace), validationVersion: nonempty(old.validationVersion),
+    };
+    if (phase.phase === 'wait' || phase.phase === 'validate')
+        return { input: migrated, checkpoint: { phase: phase.phase } };
+    if (phase.phase === 'publish' && typeof phase.text === 'string')
+        return { input: migrated, checkpoint: { phase: 'publish', text: phase.text } };
+    throw new TypeError('Invalid v1 delivery checkpoint');
+}

package/dist/delivery.d.ts

@@ -0,0 +1,33 @@
+import type { TaskId, TaskOptions, Tx } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+import type { PublicationLookup, PublicationResult, ResourceAccess, ResourceExpectation, ResourcePublisher } from '@hachej/boring-files';
+import type { DeliveryInput, DeliveryPhase, DocumentDeliveryTarget } from './delivery-input.js';
+export type { DocumentDeliveryTarget } from './delivery-input.js';
+export type DocumentDeliveryResult = PublicationResult | {
+    kind: 'invalid';
+    errors: readonly string[];
+} | {
+    kind: 'producer-failed';
+    status: string;
+};
+export interface DocumentDeliveryOptions {
+    readonly operationNamespace: string;
+    readonly validationVersion: string;
+    readonly publisher: ResourcePublisher;
+    readonly lookup: PublicationLookup;
+    /** This callback checks real producer output. It does not generate or repair output. */
+    readonly validate: (text: string, producer: TaskId<string>, context: Context) => readonly string[];
+    readonly resolveAccess: (target: ResourceExpectation, producer: TaskId<string>, context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    /** Safe replay requires host qualification of atomic receipts and durable duplicate suppression. */
+    readonly replay?: 'safe' | 'reconcile-only';
+}
+export declare function createDocumentDelivery(options: DocumentDeliveryOptions): {
+    task: import("@earendil-works/pi-durable").Task<DeliveryInput, DeliveryPhase, DocumentDeliveryResult, object>;
+    extension: import("@earendil-works/pi-durable").Extension<import("@earendil-works/pi-durable").ToolRegistration>;
+    admit: (tx: Tx, createProducer: (tx: Tx) => Promise<TaskId<string>>, target: DocumentDeliveryTarget, taskOptions: TaskOptions, context: Context, access?: ResourceAccess) => Promise<{
+        producer: TaskId<string>;
+        delivery: TaskId<DocumentDeliveryResult>;
+        operationId: string;
+    }>;
+};
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.js

@@ -0,0 +1,154 @@
+import { defineExtension, defineTask } from '@earendil-works/pi-durable';
+import { parsePublicationResult, publicationDigest } from '@hachej/boring-files/publication';
+import { captureDeliveryTarget, identity, migrateDelivery } from './delivery-input.js';
+export function createDocumentDelivery(options) {
+    const namespace = options.operationNamespace;
+    const validationVersion = options.validationVersion;
+    if (!namespace || !validationVersion)
+        throw new TypeError('Stable delivery namespace and validation version are required');
+    const operationId = (taskId) => JSON.stringify([namespace, taskId]);
+    const task = defineTask({
+        name: 'boring.documents.deliver', version: 2, initial: () => ({ phase: 'wait' }), migrate: migrateDelivery,
+        phases: {
+            wait: async (running, runtime, context) => {
+                await runtime.commit(() => ({ status: 'waiting', on: [running.input.producer], policy: 'allSettled', checkpoint: { phase: 'validate' } }), context);
+            },
+            validate: async (running, runtime, context) => {
+                const [outcome] = await runtime.outcomes([running.input.producer], context);
+                if (!outcome)
+                    throw new Error('Native producer outcome is missing');
+                if (outcome.status !== 'completed') {
+                    await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'completed', result: { kind: 'producer-failed', status: outcome.status } } }), context);
+                    return;
+                }
+                const text = outcome.result;
+                const validation = typeof text !== 'string' ? ['Producer did not return text']
+                    : new TextDecoder('utf-8', { ignoreBOM: true }).decode(new TextEncoder().encode(text)) !== text ? ['Producer text contains invalid Unicode']
+                        : options.validate(text, running.input.producer, context);
+                const errors = Array.isArray(validation) && validation.every(item => typeof item === 'string')
+                    ? [...validation] : ['Validator must return an array of errors'];
+                await runtime.commit(() => errors.length
+                    ? { status: 'terminal', outcome: { status: 'completed', result: { kind: 'invalid', errors } } }
+                    : { status: 'running', checkpoint: { phase: 'publish', text } }, context);
+            },
+            publish: async (running, runtime, context) => {
+                const input = running.input;
+                const id = JSON.stringify([input.namespace, runtime.taskId]);
+                const unknown = (reason) => ({ kind: 'unknown', operationId: id, reason });
+                const settle = async (result) => {
+                    await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'completed', result } }), context);
+                };
+                if (input.namespace !== namespace || input.validationVersion !== validationVersion) {
+                    await settle(unknown('Delivery binding changed; reconcile using the original binding'));
+                    return;
+                }
+                const attempted = await runtime.memo('boring.delivery.attempted.v1', context);
+                let access;
+                let activeIdentity;
+                try {
+                    access = { ...await options.resolveAccess(structuredClone(input.target), input.producer, context) };
+                    activeIdentity = identity(access);
+                }
+                catch (error) {
+                    if (!attempted)
+                        throw error;
+                    await settle(unknown('Access could not be resolved after a publication attempt; reconcile using the original identity'));
+                    return;
+                }
+                if (activeIdentity.principalId !== input.identity.principalId || activeIdentity.scopeId !== input.identity.scopeId
+                    || activeIdentity.initiatorId !== input.identity.initiatorId || activeIdentity.authorizationRef !== input.identity.authorizationRef) {
+                    await settle(unknown('Delivery identity changed; reconcile using the original authenticated identity'));
+                    return;
+                }
+                const request = deliveryRequest(input, id, running.state.checkpoint.text);
+                let result;
+                try {
+                    if (attempted) {
+                        const found = await options.lookup.lookup(id, { ...access, signal: runtime.signal });
+                        if (found.kind !== 'not-found')
+                            result = parsePublicationResult(found);
+                        else if (options.replay !== 'safe')
+                            result = unknown('No retained receipt; replay has not been qualified');
+                        else
+                            result = parsePublicationResult(await options.publisher.publish(structuredClone(request), { ...access, signal: runtime.signal }));
+                    }
+                    else {
+                        await runtime.memo('boring.delivery.attempted.v1', true, context);
+                        result = parsePublicationResult(await options.publisher.publish(structuredClone(request), { ...access, signal: runtime.signal }));
+                    }
+                }
+                catch {
+                    result = unknown('Delivery acknowledgement was lost');
+                }
+                result = await deliveryEvidence(input, request, result);
+                await settle(result);
+            },
+        },
+        abort: async (running, runtime, context) => {
+            const id = JSON.stringify([running.input.namespace, runtime.taskId]);
+            // An abort after a publication attempt must not hide a document that may be published.
+            let result;
+            if (await runtime.memo('boring.delivery.attempted.v1', context)) {
+                try {
+                    const access = { ...await options.resolveAccess(structuredClone(running.input.target), running.input.producer, context) };
+                    const input = running.input;
+                    const activeIdentity = identity(access);
+                    if (input.namespace !== namespace || input.validationVersion !== validationVersion
+                        || activeIdentity.principalId !== input.identity.principalId || activeIdentity.scopeId !== input.identity.scopeId
+                        || activeIdentity.initiatorId !== input.identity.initiatorId || activeIdentity.authorizationRef !== input.identity.authorizationRef) {
+                        throw new Error('Delivery binding changed');
+                    }
+                    const found = await options.lookup.lookup(id, access);
+                    result = found.kind !== 'not-found' && running.state.checkpoint.phase === 'publish'
+                        ? await deliveryEvidence(input, deliveryRequest(input, id, running.state.checkpoint.text), parsePublicationResult(found))
+                        : { kind: 'unknown', operationId: id, reason: 'Aborted after a publication attempt; no matching receipt was retained' };
+                }
+                catch {
+                    result = { kind: 'unknown', operationId: id, reason: 'Aborted after a publication attempt; the outcome could not be looked up' };
+                }
+            }
+            await runtime.commit(() => result ? { status: 'terminal', outcome: { status: 'completed', result } } : { status: 'terminal', outcome: { status: 'aborted' } }, context);
+        },
+    });
+    /** Producer creation and its delivery obligation use one native transaction. */
+    async function admit(tx, createProducer, target, taskOptions, context, access) {
+        const captured = captureDeliveryTarget(target);
+        const admittedIdentity = access === undefined ? undefined : identity({ ...access });
+        const producer = await createProducer(tx);
+        const boundIdentity = admittedIdentity ?? identity({ ...await options.resolveAccess(structuredClone(captured.target), producer, context) });
+        const delivery = await tx.createTask(task, { producer, ...captured, identity: boundIdentity, namespace, validationVersion }, taskOptions);
+        return { producer, delivery, operationId: operationId(delivery) };
+    }
+    return { task, extension: defineExtension({ name: 'boring.documents.delivery', tasks: [task] }), admit };
+}
+function deliveryRequest(input, id, text) {
+    const bytes = new TextEncoder().encode(text);
+    const request = { operationId: id, atomicity: 'all-or-nothing', preconditions: input.preconditions, changes: [input.target.kind === 'absent'
+                ? { kind: 'create', target: input.target.target, expected: { kind: 'absent' }, bytes, mediaType: 'text/markdown' }
+                : { kind: 'replace', target: input.target.target, bytes, mediaType: 'text/markdown' }] };
+    return request;
+}
+async function deliveryEvidence(input, request, result) {
+    const id = request.operationId;
+    const digest = await publicationDigest(request);
+    const unknown = (reason) => ({ kind: 'unknown', operationId: id, reason });
+    if (result.kind === 'committed') {
+        const receipt = result.receipt;
+        const change = receipt.changes[0];
+        const expected = request.changes[0];
+        const after = change?.after;
+        const targetMatches = after && after.resource.providerId === input.target.target.resource.providerId
+            && after.resource.path === input.target.target.resource.path && JSON.stringify(after.view) === JSON.stringify(input.target.target.view);
+        const beforeMatches = input.target.kind === 'absent' ? change?.before === null
+            : change?.before?.revision === input.target.target.revision && change.before.resource.providerId === input.target.target.resource.providerId
+                && change.before.resource.path === input.target.target.resource.path && JSON.stringify(change.before.view) === JSON.stringify(input.target.target.view);
+        if (receipt.operationId !== id || receipt.argumentDigest !== digest || receipt.principalId !== input.identity.principalId
+            || receipt.scopeId !== input.identity.scopeId || receipt.initiatorId !== input.identity.initiatorId || receipt.changes.length !== 1
+            || change?.kind !== expected.kind || !targetMatches || !beforeMatches)
+            result = unknown('Receipt does not match the admitted delivery');
+    }
+    else if (result.kind === 'partial' || (result.kind === 'unknown' && result.operationId !== id)) {
+        result = unknown('Provider returned incompatible delivery evidence');
+    }
+    return result;
+}

package/dist/durable-wait.d.ts

@@ -0,0 +1,23 @@
+import type { Conversation, ConversationDocFamilyToken, JsonObject, TaskId, ToolExecutionApi, Tx } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+export declare class UnknownCall extends Error {
+}
+export declare class AmbiguousCall extends Error {
+}
+/** Bind an answer to the exact assistant entry that made the call. */
+export declare const callBindingId: (assistantEntryId: number, callId: string) => string;
+export interface CallBinding {
+    readonly key: string;
+    readonly callId: string;
+    readonly taskId: TaskId;
+}
+/** The native tool task an answer ID names: `callBindingId(entry, call)`, or a raw call ID used by exactly one task. */
+export declare function callBinding(tx: Tx, conversation: Conversation, id: string): Promise<CallBinding>;
+/** The binding key of the calling tool task (its assistant entry and call id). */
+export declare function ownBindingKey(tx: Tx, api: Pick<ToolExecutionApi, 'taskId' | 'callId'>): Promise<string>;
+/**
+ * Waits until `settled(value)` holds for the document `key` of `family`, without holding a model request. When the call is aborted,
+ * `cancel` runs in a background commit (`label` names the waiting thing in errors) (the answer path also refuses a call whose task has ended) and the abort is rethrown.
+ */
+export declare function waitForDocument<T extends JsonObject>(api: ToolExecutionApi, family: ConversationDocFamilyToken<T, null>, key: string, context: Context, settled: (value: Readonly<T> | null | undefined) => boolean, cancel: (tx: Tx) => Promise<void>, label: string): Promise<Readonly<T> | null | undefined>;
+//# sourceMappingURL=durable-wait.d.ts.map

package/dist/durable-wait.js

@@ -0,0 +1,79 @@
+// The durable wait shared by `ask_user` (./ask-user.ts) and browser tasks (./browser-task.ts): a native tool call parks on a
+// conversation document keyed by its assistant entry and call id, and an authenticated answer later settles that document. No model
+// request is held while waiting; a restart re-attaches the replay-safe call to the same document; stopping the conversation
+// cancels it. Internal module: not a package export.
+import { ToolTask } from '@earendil-works/pi-durable';
+import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
+export class UnknownCall extends Error {
+}
+export class AmbiguousCall extends Error {
+}
+/** Bind an answer to the exact assistant entry that made the call. */
+export const callBindingId = (assistantEntryId, callId) => JSON.stringify([assistantEntryId, callId]);
+/** The native tool task an answer ID names: `callBindingId(entry, call)`, or a raw call ID used by exactly one task. */
+export async function callBinding(tx, conversation, id) {
+    let cursor;
+    let match;
+    do {
+        const page = await tx.scanTasks({ conversationId: conversation.id, kind: ToolTask.definition.name }, 100, cursor);
+        for (const task of page.items) {
+            const input = task.input;
+            if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input['callId'] !== 'string' || typeof input['assistant'] !== 'number')
+                continue;
+            const key = callBindingId(input['assistant'], input['callId']);
+            if (key !== id && input['callId'] !== id)
+                continue;
+            if (match !== undefined)
+                throw new AmbiguousCall();
+            match = { key, callId: input['callId'], taskId: task.id };
+        }
+        cursor = page.next;
+    } while (cursor !== undefined);
+    if (match === undefined)
+        throw new UnknownCall();
+    return match;
+}
+/** The binding key of the calling tool task (its assistant entry and call id). */
+export async function ownBindingKey(tx, api) {
+    const task = await tx.task(api.taskId);
+    const input = task?.input;
+    if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input['assistant'] !== 'number')
+        throw new Error('Tool task has no assistant entry');
+    return callBindingId(input['assistant'], api.callId);
+}
+/**
+ * Waits until `settled(value)` holds for the document `key` of `family`, without holding a model request. When the call is aborted,
+ * `cancel` runs in a background commit (`label` names the waiting thing in errors) (the answer path also refuses a call whose task has ended) and the abort is rethrown.
+ */
+export async function waitForDocument(api, family, key, context, settled, cancel, label) {
+    const watch = await api.watchDoc(family, api.conversationId, key, context);
+    if (!watch)
+        throw new Error(`${label} record is missing`);
+    const signal = context.abortSignal;
+    let final = watch.value;
+    try {
+        if (!settled(final)) {
+            final = await new Promise((resolve, reject) => {
+                if (signal?.aborted)
+                    return reject(signal.reason ?? new Error(`${label} cancelled`));
+                signal?.addEventListener('abort', () => reject(signal.reason ?? new Error(`${label} cancelled`)), { once: true });
+                void watch.closed.then(() => reject(new Error(`${label} observation closed`)));
+                watch.start(async (value) => { if (settled(value))
+                    resolve(value); });
+            });
+        }
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            try {
+                await api.commit(cancel, BACKGROUND_CONTEXT);
+            }
+            catch { /* the answer path also refuses a call whose task has ended */ }
+        }
+        throw error;
+    }
+    finally {
+        await watch.stop();
+    }
+    return final;
+}

package/dist/file-convert.d.ts

@@ -0,0 +1,46 @@
+import type { ToolExecutionApi, ToolRegistration } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+import type { ResourceAccess } from '@hachej/boring-files';
+import type { WorkspaceBinding, WorkspaceResolver } from './workspaces.js';
+/** The converter: bytes to text, or `{ error }`. A failure is not cached. */
+export type FileConverter = (file: {
+    readonly name: string;
+    readonly mediaType: string;
+    readonly bytes: Uint8Array;
+}) => Promise<{
+    readonly text: string;
+} | {
+    readonly error: string;
+}>;
+/** Converted text per `<path>@<revision>`. A `Map<string, string>` satisfies it. */
+export interface ConvertedTextCache {
+    get(key: string): string | undefined | Promise<string | undefined>;
+    set(key: string, text: string): unknown;
+}
+export interface ConvertingReadOptions {
+    /** The workspace of each call, resolved like the file guard's (`@hachej/boring-agent/workspaces`); absent: the env's workspace. */
+    readonly workspace?: WorkspaceResolver | WorkspaceBinding | undefined;
+    /** The agent's principal for the provider. Default: the binding's `access`. */
+    readonly resolveAccess?: (api: ToolExecutionApi, context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    /** Converts a file to text. Without it, images use Pi's native read and other binary files answer `unsupported`. */
+    readonly convert?: FileConverter;
+    /** Stores converted text per revision. Without it, each read converts again. */
+    readonly cache?: ConvertedTextCache;
+    /** Largest file converted, in bytes. Default 20 MiB. */
+    readonly maxBytes?: number;
+    /** The extension name (default `boring.files.read`). */
+    readonly name?: string;
+}
+/** Pi's `read`, extended to convert PDF, office and image files through the host's converter. An extension to select (after the extension that registers `read`, before the file guard). */
+export declare function createConvertingRead(options?: ConvertingReadOptions): import("@earendil-works/pi-durable").Extension<ToolRegistration>;
+/**
+ * Adapts a Workers AI binding (`env.AI`, whose `toMarkdown` converts a file to Markdown) to a `FileConverter`. Typed loosely, so the
+ * package needs no Cloudflare types.
+ */
+export declare function workersAiMarkdown(ai: {
+    toMarkdown(input: {
+        name: string;
+        blob: Blob;
+    }): Promise<unknown>;
+}): FileConverter;
+//# sourceMappingURL=file-convert.d.ts.map

package/dist/file-convert.js

@@ -0,0 +1,159 @@
+import { defineExtension, wrapTool } from '@earendil-works/pi-durable';
+import { createReadTool } from '@earendil-works/pi-durable/tools';
+import { workspaceRelative } from './file-guard.js';
+import { SNIFF_BYTES, fileKind, mediaTypeFor } from './file-types.js';
+import { asWorkspaceResolver, workspaceFor } from './workspaces.js';
+/*
+ * One `read`. This wraps Pi's native `read` (public `wrapTool`, the supported way to override a native tool) and adds no tool:
+ *
+ *  - Text goes to Pi's native read untouched.
+ *  - A PDF, an office document or an image goes to the host's `convert` hook (`workersAiMarkdown` adapts Workers AI). The converted
+ *    text is cached per path and saved revision and paged exactly as Pi pages a text file: `offset` is the 1-based line to start at,
+ *    `limit` a count of lines, a page ends at 2000 lines or 50 KB, and the info diagnostic names the `offset` to continue from.
+ *  - An archive or other binary file (a NUL byte) answers `unsupported` and is never converted. Without `convert`, an image goes to
+ *    Pi's native behaviour and a PDF or office file answers `unsupported`.
+ *
+ * What is a text file and what is not comes from the single table in file-types.ts: the extension and the leading bytes (Pi's read
+ * returns garbled text for a PDF, so the magic number decides, not only the name). The converted file is read through the workspace
+ * provider, which checks access; a path this wrapper cannot place inside the workspace is left to the native read, and the file guard
+ * (`createFileGuard`) refuses it. Install this extension before the guard, so the guard stays outermost. Nothing is written.
+ */
+const MAX_LINES = 2000; // Pi's read page: DEFAULT_MAX_LINES
+const MAX_BYTES = 50 * 1024; // Pi's read page: DEFAULT_MAX_BYTES
+const DEFAULT_MAX_FILE = 20 * 1024 * 1024;
+const failure = (text, code) => ({ content: [{ type: 'text', text }], isError: true, diagnostics: [{ severity: 'error', code, message: text }] });
+const utf8Length = (text) => new TextEncoder().encode(text).length;
+/**
+ * The converted text as pageable lines. A line longer than MAX_BYTES is split, on character boundaries, into segments of at most
+ * MAX_BYTES; each segment counts as one line for `offset` and `limit`, so every byte stays reachable with an honest offset (Pi's own
+ * read can only point at `sed` for the rest of such a line, and converted text has no file for `sed`). `split` maps the 0-based
+ * index of each segment to the 1-based number of the original line.
+ */
+function linesOf(text) {
+    const lines = [], split = new Map();
+    const encoder = new TextEncoder(), decoder = new TextDecoder('utf-8', { ignoreBOM: true }); // keep a U+FEFF that starts a segment
+    text.split('\n').forEach((line, index) => {
+        if (utf8Length(line) <= MAX_BYTES) {
+            lines.push(line);
+            return;
+        }
+        const bytes = encoder.encode(line);
+        for (let start = 0; start < bytes.length;) {
+            let end = Math.min(bytes.length, start + MAX_BYTES);
+            while (end < bytes.length && end > start && (bytes[end] & 0xc0) === 0x80)
+                end--; // never cut inside a character
+            split.set(lines.length, index + 1);
+            lines.push(decoder.decode(bytes.subarray(start, end)));
+            start = end;
+        }
+    });
+    return { lines, split };
+}
+/** The lines from the 0-based `start`, cut like Pi's `truncateHead`: whole lines up to MAX_LINES / MAX_BYTES (no line exceeds MAX_BYTES). */
+function page(lines, start, count) {
+    const out = [];
+    let bytes = 0, byBytes = false;
+    for (let index = start; index < start + count && out.length < MAX_LINES; index++) {
+        const line = lines[index];
+        const size = utf8Length(line) + (out.length > 0 ? 1 : 0);
+        if (bytes + size > MAX_BYTES) {
+            byBytes = true;
+            break;
+        }
+        bytes += size;
+        out.push(line);
+    }
+    return { text: out.join('\n'), shown: out.length, byBytes };
+}
+/** Pi's read result for already converted text. */
+function convertedPage(text, offset, limit) {
+    const { lines, split } = linesOf(text);
+    const total = lines.length;
+    const start = offset ? Math.max(0, Math.trunc(offset) - 1) : 0;
+    if (start >= total)
+        throw new Error(`Offset ${offset} is beyond end of file (${total} lines total)`);
+    const wanted = limit === undefined ? total - start : Math.max(1, Math.min(Math.trunc(limit), total - start));
+    const { text: shownText, shown, byBytes } = page(lines, start, wanted);
+    const end = start + shown;
+    const diagnostics = [];
+    const cut = [...new Set([...split].filter(([index]) => index >= start && index < end).map(([, original]) => original))];
+    if (cut.length)
+        diagnostics.push({ severity: 'warn', code: 'truncated', message: `The converted text has ${cut.length === 1 ? 'a line' : 'lines'} longer than ${MAX_BYTES / 1024}KB (original line ${cut.join(', ')}); each is split into segments of at most ${MAX_BYTES / 1024}KB and every segment counts as one line for offset and limit.` });
+    if (shown < wanted)
+        diagnostics.push({ severity: 'info', code: 'truncated', message: `Showing lines ${start + 1}-${end} of ${total}${byBytes ? ` (${MAX_BYTES / 1024}KB limit)` : ''}. Use offset=${end + 1} to continue.` });
+    else if (end < total)
+        diagnostics.push({ severity: 'info', message: `${total - end} more lines in file. Use offset=${end + 1} to continue.` });
+    return { content: shownText === '' ? [] : [{ type: 'text', text: shownText }], diagnostics };
+}
+/** Pi's `read`, extended to convert PDF, office and image files through the host's converter. An extension to select (after the extension that registers `read`, before the file guard). */
+export function createConvertingRead(options = {}) {
+    const resolver = asWorkspaceResolver(options.workspace);
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_FILE;
+    function converting(tool) {
+        const native = tool.execute;
+        const execute = async (args, api, context) => {
+            const resolved = await workspaceFor(resolver, api, context);
+            if ('refused' in resolved)
+                return native(args, api, context);
+            const root = resolved.binding.root.replace(/\/+$/, '');
+            const located = await workspaceRelative(api, root, args.path, context);
+            if (located === undefined)
+                return native(args, api, context);
+            // The access check comes first, and the type is sniffed on the bytes the provider returned: nothing is read around it.
+            const { files } = resolved.binding;
+            const access = options.resolveAccess ? await options.resolveAccess(api, context) : resolved.binding.access;
+            if (access === undefined)
+                return failure('Refused: the host gave no access for this workspace.', 'denied');
+            const read = await files.read({ target: { resource: { providerId: files.providerId, path: located.path }, view: { kind: 'published' } }, revision: { kind: 'latest' } }, { ...access });
+            // Never delegate a missing path: Pi's read would try other spellings the provider and the containment check never saw.
+            if (read.kind === 'missing')
+                return failure(`Refused: ${args.path} does not exist in the workspace.`, 'denied');
+            if (read.kind !== 'available')
+                return failure(`Refused: ${args.path} cannot be read here (${read.reason}).`, 'denied');
+            const { snapshot } = read;
+            const head = snapshot.bytes.subarray(0, SNIFF_BYTES);
+            let kind = fileKind(located.path, head);
+            // The leading bytes are only a sniff: a NUL anywhere in the loaded snapshot makes a text file binary.
+            if (kind === 'text' && snapshot.bytes.includes(0))
+                kind = 'binary';
+            if (kind === 'text')
+                return native(args, api, context);
+            if (kind === 'archive' || kind === 'binary')
+                return failure(`${args.path} is ${kind === 'archive' ? 'an archive' : 'a binary file'}; it cannot be read as text here (unsupported).`, 'unsupported');
+            if (!options.convert) {
+                if (kind === 'image')
+                    return native(args, api, context);
+                return failure(`${args.path} is a ${kind} file; this agent has no converter, so it cannot be read as text here (unsupported).`, 'unsupported');
+            }
+            if (snapshot.bytes.byteLength > maxBytes)
+                return failure(`${args.path} is larger than ${maxBytes} bytes and is not converted.`, 'too_large');
+            const key = `${located.path}@${snapshot.ref.revision}`;
+            let text = await options.cache?.get(key);
+            if (text === undefined) {
+                const result = await options.convert({ name: located.path.slice(located.path.lastIndexOf('/') + 1), mediaType: mediaTypeFor(located.path, kind, snapshot.mediaType, head), bytes: snapshot.bytes });
+                if ('error' in result)
+                    return failure(`${args.path} could not be converted to text: ${result.error}`, 'unavailable');
+                text = result.text;
+                await options.cache?.set(key, text);
+            }
+            return convertedPage(text, args.offset, args.limit);
+        };
+        return { ...tool, execute };
+    }
+    return defineExtension({
+        name: options.name ?? 'boring.files.read',
+        wraps: [wrapTool(createReadTool(), converting)],
+    });
+}
+/**
+ * Adapts a Workers AI binding (`env.AI`, whose `toMarkdown` converts a file to Markdown) to a `FileConverter`. Typed loosely, so the
+ * package needs no Cloudflare types.
+ */
+export function workersAiMarkdown(ai) {
+    return async ({ name, mediaType, bytes }) => {
+        const result = await ai.toMarkdown({ name, blob: new Blob([bytes], { type: mediaType }) });
+        if (result?.format === 'markdown' && typeof result.data === 'string')
+            return { text: result.data };
+        return { error: typeof result?.error === 'string' ? result.error : 'The file could not be converted to text.' };
+    };
+}

package/dist/file-guard.d.ts

@@ -0,0 +1,50 @@
+import type { ToolExecutionApi, ToolRegistration } from '@earendil-works/pi-durable';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Context } from '@earendil-works/chord';
+import type { ResourceAccess } from '@hachej/boring-files';
+import type { WorkspaceBinding, WorkspaceResolver } from './workspaces.js';
+type Baselines = {
+    revisions: Record<string, string>;
+};
+/** Conversation document: workspace and path (relative to the workspace root; see `baselineKey`) to the revision this conversation last read or wrote. */
+export declare const lastReadRevisions: import("@earendil-works/pi-durable").ConversationDocToken<Baselines>;
+/** The baseline key of `path` in `workspace` (its `id`, or its provider id): `<workspace>:<path>`. */
+export declare const baselineKey: (workspace: Pick<WorkspaceBinding, "id" | "files">, path: string) => string;
+/** The revision this conversation last read or wrote under `key` (see `baselineKey`), or undefined. Also what host tools over workspace files (such as the canvas tools) check. */
+export declare const lastReadRevision: (api: ToolExecutionApi, key: string, context: Context) => Promise<string | undefined>;
+/** Record `revision` as the conversation's baseline under `key` (see `baselineKey`), durably. */
+export declare const recordRevision: (api: ToolExecutionApi, key: string, revision: string, context: Context) => Promise<void>;
+export interface FileGuardOptions {
+    /**
+     * The workspace of each call: a resolver shaped like `HarnessOptions.env` (`@hachej/boring-agent/workspaces`), or one binding
+     * `{ files, root }` for a host with a single workspace; absent: the workspace attached to the call's env (`withWorkspace`). `files` is the provider the viewers use (its queue serialises the calls,
+     * its reads name the revisions); `root` is the workspace root as the call's ExecutionEnv names it. Paths outside it are refused.
+     */
+    readonly workspace?: WorkspaceResolver | WorkspaceBinding | undefined;
+    /** The agent's principal for the provider. Default: the binding's `access`. */
+    readonly resolveAccess?: (api: ToolExecutionApi, context: Context) => ResourceAccess | Promise<ResourceAccess>;
+    /**
+     * The extension name (default `boring.files.guard`). A registry keeps one extension per name, so two agents with different
+     * workspace resolvers in one registry need two names; otherwise the last installed guard wraps every agent's tools.
+     */
+    readonly name?: string;
+}
+/** `path` as the call's env names it, and relative to `root`, or undefined when it is not lexically inside `root` (or the call has no env). Pi's path normalisation applies. */
+export declare function workspaceRelative(api: ToolExecutionApi, root: string, path: string, context: Context): Promise<{
+    readonly path: string;
+    readonly absolute: string;
+} | undefined>;
+export declare const ONE_PATH: Set<string>;
+/**
+ * `env` as the native `read`, `write` and `edit` must see it: every operation that opens, changes or lists a path first re-checks the
+ * path it is ABOUT to touch (links resolved, like `contained`) and refuses outside `root` with a typed `permission_denied`. The check
+ * is on the path Pi actually opens, so a fallback spelling Pi picks after the provider's check (NFD, curly apostrophe) is judged as
+ * itself. `exists` answers false for a path outside, so Pi's fallback loop moves on instead of revealing it. A Pi extension point
+ * (`ExecutionEnv` decorator), public API only. Residual: a symlink swapped between this check and the OS `open` is not closable from
+ * here; that boundary is the host's isolation (an isolated worker env), not this guard.
+ */
+export declare function confinedEnv(env: ExecutionEnv, root: string): ExecutionEnv;
+/** The guard as a native extension. Select it after the extension(s) that register `read`, `write` and `edit`. */
+export declare function createFileGuard(options?: FileGuardOptions): import("@earendil-works/pi-durable").Extension<ToolRegistration>;
+export {};
+//# sourceMappingURL=file-guard.d.ts.map