@hachej/boring-agent 0.1.110 → 0.2.0

package/dist/conversations.d.ts

@@ -0,0 +1,136 @@
+import type { Conversation, ConversationId, ConversationInit, EntryId, Harness } from '@earendil-works/pi-durable';
+import type { Message } from '@earendil-works/pi-ai';
+import type { Context } from '@earendil-works/chord';
+/**
+ * What a host's conversation list needs that Pi does not keep: a title, when it was created and last active, a preview of the
+ * last message, whether it is archived or deleted, and which host owner it belongs to. One native conversation document per
+ * conversation, written through the public document API; there is no second store. A conversation without this document (or
+ * with an empty owner, such as a native fork made outside this module) is not managed and never listed.
+ */
+export type ConversationMetadata = {
+    /** The host's owner key (a person, a team, an agent). Empty: not managed by this module. */
+    owner: string;
+    /** Set explicitly, or derived once from the first user message; durable afterwards. */
+    title: string | null;
+    createdAt: number;
+    /** Last activity: the last user or assistant message (or creation, rename is not activity). */
+    updatedAt: number;
+    /** A bounded preview of the last user or assistant message. */
+    lastMessage: string | null;
+    archived: boolean;
+    /** Pi cannot delete a conversation: a deleted one is hidden by this durable mark; its records stay in the session storage. */
+    deletedAt: number | null;
+};
+/** The native document. `fork: 'initial'`: a fork made by `fork()` gets its own metadata in the creating commit; any other fork starts unmanaged. */
+export declare const conversationMetadata: import("@earendil-works/pi-durable").ConversationDocToken<ConversationMetadata>;
+/** One row of a conversation list. */
+export interface ConversationSummary {
+    readonly id: ConversationId;
+    readonly title: string | null;
+    readonly lastMessage: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly archived: boolean;
+}
+export interface ConversationListQuery {
+    readonly owner: string;
+    /** `false` (default): active ones; `true`: archived ones; `'all'`: both. Deleted ones never. */
+    readonly archived?: boolean | 'all';
+    /** Case-insensitive substring of the title or the last message. */
+    readonly query?: string;
+    /** Default 50, at most 200. */
+    readonly limit?: number;
+    /** The `next` of the previous page. */
+    readonly cursor?: string;
+}
+export interface ConversationsOptions {
+    readonly harness: Harness;
+    /** Long-lived context for the metadata writes that follow turns. */
+    readonly context: Context;
+    readonly now?: () => number;
+    /** Longest derived title (default 80 characters). */
+    readonly titleLength?: number;
+    /** Longest last-message preview (default 160 characters). */
+    readonly previewLength?: number;
+    /** A metadata write after a turn failed (the turn itself is unaffected). */
+    readonly onError?: (error: unknown) => void;
+}
+export interface Conversations {
+    /**
+     * Create a managed conversation; its metadata is written in the creating commit. `start` creates the native conversation with
+     * the host's agent (pass `init` on, for example `definition.createConversation(harness, context, { init })`); the default is
+     * an ownerless `harness.createConversation`.
+     */
+    readonly create: (owner: string, options?: {
+        readonly title?: string;
+        readonly start?: (init: ConversationInit) => Promise<Conversation>;
+    }) => Promise<Conversation>;
+    /**
+     * Manage an existing conversation (migration). Title and preview are derived once from its history (bounded scan) unless
+     * given. Returns `undefined` when the conversation does not exist or another owner already manages it.
+     */
+    readonly adopt: (id: ConversationId, owner: string, options?: {
+        readonly title?: string;
+        readonly createdAt?: number;
+        readonly updatedAt?: number;
+    }) => Promise<ConversationSummary | undefined>;
+    /** The summary when `owner` manages the conversation and it is not deleted. */
+    readonly get: (owner: string, id: ConversationId) => Promise<ConversationSummary | undefined>;
+    /** The native handle under the same condition as `get`. */
+    readonly open: (owner: string, id: ConversationId) => Promise<Conversation | undefined>;
+    /** Newest activity first. One `scanConversations` pass plus one metadata read per conversation; no transcript is read. */
+    readonly list: (query: ConversationListQuery) => Promise<{
+        readonly items: readonly ConversationSummary[];
+        readonly next?: string;
+    }>;
+    readonly rename: (owner: string, id: ConversationId, title: string) => Promise<ConversationSummary | undefined>;
+    readonly archive: (owner: string, id: ConversationId, archived?: boolean) => Promise<ConversationSummary | undefined>;
+    /** Stops the conversation's ordinary work, then marks it deleted (Pi has no delete). `false` when not found. */
+    readonly delete: (owner: string, id: ConversationId) => Promise<boolean>;
+    /** Native `Conversation.fork(at)`: a new managed conversation with the history up to and including entry `at`, titled "<title> (fork)". */
+    readonly fork: (owner: string, id: ConversationId, at: EntryId, options?: {
+        readonly title?: string;
+    }) => Promise<Conversation | undefined>;
+    /** Wait for the metadata writes of turns already committed. */
+    readonly flush: () => Promise<void>;
+    /** Stop observing commits (after `flush`). Never closes the Harness. */
+    readonly dispose: () => Promise<void>;
+}
+/** The visible text of a user or assistant message: text parts only, never the `<file>` blocks mentions add. */
+export declare function messageText(message: Message): string | undefined;
+/** A conversation's title as the list shows it: the first user message, clipped to `maxLength` characters. Undefined: no user message yet. */
+export type ConversationTitleCache = {
+    get(key: string): string | undefined;
+    set(key: string, title: string): unknown;
+};
+/**
+ * The title of a conversation that has no stored one: its first user message, clipped to 80 characters. The first message of a
+ * conversation never changes, so a non-null title is cached (`cache`, keyed by the conversation id) and the history is read once;
+ * `null` (no user message yet) is not cached. A `Map<string, string>` is a valid cache.
+ */
+export declare function conversationTitle(conversation: Conversation, context: Context, cache?: ConversationTitleCache): Promise<string | null>;
+export declare function createConversations(options: ConversationsOptions): Conversations;
+/** What the host's authentication decides for one request: whose conversations, and how to start one. */
+export interface ConversationsAccess {
+    readonly owner: string;
+    /** How `create` starts the native conversation (the host's agent). Default: an ownerless conversation. */
+    readonly start?: (init: ConversationInit) => Promise<Conversation>;
+    /** Called with a conversation this request created or forked (for example to register its environment). */
+    readonly opened?: (conversation: Conversation) => void | Promise<void>;
+    /** Called after this request deleted a conversation. */
+    readonly deleted?: (id: ConversationId) => void | Promise<void>;
+    /** Refuse an operation; listing included. */
+    readonly allow?: (operation: 'list' | 'create' | 'rename' | 'archive' | 'delete' | 'fork') => boolean | Promise<boolean>;
+}
+export interface ConversationsHandlerOptions {
+    readonly conversations: Conversations;
+    /** Authenticate in trusted host code and name the owner. Null refuses. The host also enforces its Origin/CSRF policy here. */
+    readonly authenticate: (request: Request) => Promise<ConversationsAccess | null>;
+}
+/**
+ * Fetch handler for a conversation list: `GET` (`?archived=1|all&q=&limit=&cursor=`) lists, `POST` with `?op=create` (the
+ * default), `rename` `{ conversationId, title }`, `archive` `{ conversationId, archived? }`, `delete` `{ conversationId }` or
+ * `fork` `{ conversationId, at, title? }`. Every POST needs a JSON body.
+ */
+export declare function createConversationsHandler(options: ConversationsHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=conversations.d.ts.map

package/dist/conversations.js

@@ -0,0 +1,366 @@
+import { defineDoc } from '@earendil-works/pi-durable';
+import { RequestGuardError, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
+import { MENTION_FILE_PREFIX } from './mentions.js';
+/** The native document. `fork: 'initial'`: a fork made by `fork()` gets its own metadata in the creating commit; any other fork starts unmanaged. */
+export const conversationMetadata = defineDoc({
+    kind: 'boring.conversation.metadata', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    initial: () => ({ owner: '', title: null, createdAt: 0, updatedAt: 0, lastMessage: null, archived: false, deletedAt: null }),
+});
+const managed = (meta, owner) => meta !== undefined && meta.owner !== '' && meta.deletedAt === null && (owner === undefined || meta.owner === owner);
+const clip = (text, max) => { const flat = text.replace(/\s+/g, ' ').trim(); return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat; };
+/** The visible text of a user or assistant message: text parts only, never the `<file>` blocks mentions add. */
+export function messageText(message) {
+    if (message.role === 'user') {
+        const text = typeof message.content === 'string' ? message.content
+            : message.content.map(part => part.type === 'text' && !part.text.startsWith(MENTION_FILE_PREFIX) ? part.text : '').join(' ');
+        return text.trim() ? text : undefined;
+    }
+    if (message.role === 'assistant') {
+        const text = message.content.map(part => part.type === 'text' ? part.text : '').join(' ');
+        return text.trim() ? text : undefined;
+    }
+    return undefined;
+}
+function summary(id, meta) {
+    return { id, title: meta.title, lastMessage: meta.lastMessage, createdAt: meta.createdAt, updatedAt: meta.updatedAt, archived: meta.archived };
+}
+/**
+ * The first user message of a conversation, as `messageText` shows it. Pi's ascending entry scan (`order: 'ascending'`) stops at
+ * the first user message, so a long transcript is never read. `maxPages` (100 entries each) bounds the scan.
+ */
+async function firstUserText(conversation, context, maxPages) {
+    let cursor;
+    for (let pages = 0; pages < maxPages; pages++) {
+        const page = await conversation.entries({ order: 'ascending' }, 100, cursor, context);
+        for (const entry of page.items)
+            for (const message of entry.model ?? []) {
+                if (message.role !== 'user')
+                    continue;
+                const text = messageText(message);
+                if (text !== undefined)
+                    return text;
+            }
+        if (!page.next)
+            break;
+        cursor = page.next;
+    }
+    return undefined;
+}
+/** The last visible message of a conversation: a newest-first scan that stops at the first one found. */
+async function lastVisibleText(conversation, context, maxPages) {
+    let cursor;
+    for (let pages = 0; pages < maxPages; pages++) {
+        const page = await conversation.entries({}, 100, cursor, context);
+        for (const entry of page.items)
+            for (const message of [...(entry.model ?? [])].reverse()) {
+                const text = messageText(message);
+                if (text !== undefined)
+                    return text;
+            }
+        if (!page.next)
+            break;
+        cursor = page.next;
+    }
+    return undefined;
+}
+/**
+ * The title of a conversation that has no stored one: its first user message, clipped to 80 characters. The first message of a
+ * conversation never changes, so a non-null title is cached (`cache`, keyed by the conversation id) and the history is read once;
+ * `null` (no user message yet) is not cached. A `Map<string, string>` is a valid cache.
+ */
+export async function conversationTitle(conversation, context, cache) {
+    const key = String(conversation.id);
+    const known = cache?.get(key);
+    if (known !== undefined)
+        return known;
+    const title = await firstUserText(conversation, context, Infinity);
+    if (title === undefined)
+        return null;
+    const clipped = clip(title, 80);
+    cache?.set(key, clipped);
+    return clipped;
+}
+export function createConversations(options) {
+    const { harness, context } = options;
+    const now = options.now ?? Date.now;
+    const titleLength = options.titleLength ?? 80, previewLength = options.previewLength ?? 160;
+    const read = (id) => harness.snapshot(conversationMetadata, id, context);
+    // Checked before the commit (so no document is created for a conversation this module does not manage) and again inside it.
+    const write = async (id, owner, change) => {
+        if (!managed(await read(id), owner))
+            return undefined;
+        return harness.commit(async (tx) => {
+            const meta = await tx.doc(conversationMetadata, id);
+            return managed(meta, owner) ? change(meta) : undefined;
+        }, context);
+    };
+    const pending = new Map();
+    let chain = Promise.resolve(), scheduled = false;
+    const apply = async (id, item) => {
+        const meta = await read(id);
+        if (!managed(meta))
+            return;
+        await harness.commit(async (tx) => {
+            const draft = await tx.doc(conversationMetadata, id);
+            if (!managed(draft))
+                return;
+            draft.updatedAt = Math.max(draft.updatedAt, item.at);
+            if (item.last !== undefined)
+                draft.lastMessage = clip(item.last, previewLength);
+            if (draft.title === null && item.firstUser !== undefined)
+                draft.title = clip(item.firstUser, titleLength);
+        }, context);
+    };
+    const drain = async () => {
+        scheduled = false;
+        const batch = [...pending];
+        pending.clear();
+        for (const [id, item] of batch) {
+            try {
+                await apply(id, item);
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+        }
+    };
+    const observe = (publication) => {
+        let found = false;
+        for (const change of publication.changes) {
+            if (change.type !== 'entry')
+                continue;
+            const entry = change.value;
+            for (const message of entry.model ?? []) {
+                const text = messageText(message);
+                if (text === undefined)
+                    continue;
+                const item = pending.get(entry.conversationId) ?? { at: now() };
+                if (message.role === 'user' && item.firstUser === undefined)
+                    item.firstUser = text;
+                item.last = text;
+                item.at = now();
+                pending.set(entry.conversationId, item);
+                found = true;
+            }
+        }
+        if (found && !scheduled) {
+            scheduled = true;
+            chain = chain.then(drain);
+        }
+    };
+    const unsubscribe = harness.subscribeCommits(observe);
+    const unsubscribeClose = harness.subscribeClose(() => { unsubscribe(); });
+    async function derive(conversation) {
+        const [title, last] = await Promise.all([firstUserText(conversation, context, 20), lastVisibleText(conversation, context, 20)]);
+        return { ...(title === undefined ? {} : { title }), ...(last === undefined ? {} : { last }) };
+    }
+    const initial = (owner, fields) => async (tx, id) => {
+        const meta = await tx.doc(conversationMetadata, id);
+        const at = now();
+        Object.assign(meta, { owner, title: null, createdAt: at, updatedAt: at, lastMessage: null, archived: false, deletedAt: null }, fields);
+    };
+    const ownerKey = (owner) => { if (typeof owner !== 'string' || owner === '')
+        throw new TypeError('An owner is required'); return owner; };
+    const titleOf = (title) => { const value = clip(String(title), 200); if (!value)
+        throw new TypeError('A title is required'); return value; };
+    return {
+        async create(owner, createOptions = {}) {
+            const init = initial(ownerKey(owner), createOptions.title === undefined ? {} : { title: titleOf(createOptions.title) });
+            return createOptions.start ? createOptions.start(init) : harness.createConversation({ ownership: { kind: 'ownerless' }, init }, context);
+        },
+        async adopt(id, owner, adoptOptions = {}) {
+            ownerKey(owner);
+            const conversation = await harness.conversation(id, context);
+            if (!conversation)
+                return undefined;
+            const existing = await read(id);
+            if (managed(existing))
+                return existing.owner === owner ? summary(id, existing) : undefined;
+            const derived = await derive(conversation);
+            const at = now();
+            const meta = await harness.commit(async (tx) => {
+                const draft = await tx.doc(conversationMetadata, id);
+                Object.assign(draft, { owner, createdAt: adoptOptions.createdAt ?? adoptOptions.updatedAt ?? at, updatedAt: adoptOptions.updatedAt ?? adoptOptions.createdAt ?? at,
+                    title: adoptOptions.title !== undefined ? titleOf(adoptOptions.title) : derived.title !== undefined ? clip(derived.title, titleLength) : null,
+                    lastMessage: derived.last === undefined ? null : clip(derived.last, previewLength), archived: false, deletedAt: null });
+                return { ...draft };
+            }, context);
+            return summary(id, meta);
+        },
+        async get(owner, id) { const meta = await read(id); return managed(meta, owner) ? summary(id, meta) : undefined; },
+        async open(owner, id) { return managed(await read(id), owner) ? harness.conversation(id, context) : undefined; },
+        async list(query) {
+            const owner = ownerKey(query.owner);
+            const archived = query.archived ?? false;
+            const needle = query.query?.trim().toLowerCase() ?? '';
+            const limit = Math.min(Math.max(1, Math.floor(query.limit ?? 50)), 200);
+            const found = [];
+            let cursor;
+            do {
+                const page = await harness.commit(tx => tx.scanConversations({}, 500, cursor), context);
+                for (const record of page.items) {
+                    if (record.owner)
+                        continue; // conversations owned by a task (subagents) are never listed
+                    const meta = await read(record.id);
+                    if (!managed(meta, owner) || (archived !== 'all' && meta.archived !== archived))
+                        continue;
+                    if (needle && !(meta.title ?? '').toLowerCase().includes(needle) && !(meta.lastMessage ?? '').toLowerCase().includes(needle))
+                        continue;
+                    found.push(summary(record.id, meta));
+                }
+                cursor = page.next;
+            } while (cursor);
+            found.sort((a, b) => b.updatedAt - a.updatedAt || Number(b.id) - Number(a.id));
+            let start = 0;
+            if (query.cursor) {
+                const [at, id] = query.cursor.split(':').map(Number);
+                start = found.findIndex(item => item.updatedAt < at || (item.updatedAt === at && Number(item.id) < id));
+                if (start < 0)
+                    start = found.length;
+            }
+            const items = found.slice(start, start + limit);
+            const tail = items.at(-1);
+            return start + limit < found.length && tail ? { items, next: `${tail.updatedAt}:${Number(tail.id)}` } : { items };
+        },
+        async rename(owner, id, title) {
+            const value = titleOf(title);
+            const meta = await write(id, ownerKey(owner), meta => { meta.title = value; return { ...meta }; });
+            return meta && summary(id, meta);
+        },
+        async archive(owner, id, archived = true) {
+            const meta = await write(id, ownerKey(owner), meta => { meta.archived = archived; return { ...meta }; });
+            return meta && summary(id, meta);
+        },
+        async delete(owner, id) {
+            if (!managed(await read(id), ownerKey(owner)))
+                return false;
+            await (await harness.conversation(id, context))?.abort(context);
+            return (await write(id, owner, meta => { meta.deletedAt = now(); return true; })) === true;
+        },
+        async fork(owner, id, at, forkOptions = {}) {
+            const source = await read(id);
+            if (!managed(source, ownerKey(owner)))
+                return undefined;
+            const conversation = await harness.conversation(id, context);
+            if (!conversation)
+                return undefined;
+            // The preview of the fork is the last message it inherits: one bounded page of its history up to `at`.
+            let last;
+            const page = await conversation.entries({ maxEntryId: at }, 50, undefined, context);
+            for (const entry of page.items) {
+                for (const message of [...entry.model ?? []].reverse()) {
+                    last = messageText(message);
+                    if (last !== undefined)
+                        break;
+                }
+                if (last !== undefined)
+                    break;
+            }
+            const title = forkOptions.title !== undefined ? titleOf(forkOptions.title) : clip(`${source.title ?? 'New conversation'} (fork)`, 200);
+            return conversation.fork(at, { ownership: { kind: 'ownerless' }, init: initial(owner, { title, lastMessage: last === undefined ? null : clip(last, previewLength) }) }, context);
+        },
+        async flush() { while (scheduled || pending.size)
+            await chain; await chain; },
+        async dispose() { unsubscribe(); unsubscribeClose(); await chain; },
+    };
+}
+const headers = { 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' };
+const failure = (status, reason) => Response.json({ reason }, { status, headers });
+const idOf = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value
+    : typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : undefined;
+/**
+ * Fetch handler for a conversation list: `GET` (`?archived=1|all&q=&limit=&cursor=`) lists, `POST` with `?op=create` (the
+ * default), `rename` `{ conversationId, title }`, `archive` `{ conversationId, archived? }`, `delete` `{ conversationId }` or
+ * `fork` `{ conversationId, at, title? }`. Every POST needs a JSON body.
+ */
+export function createConversationsHandler(options) {
+    const { conversations } = options;
+    return async (request) => {
+        const params = new URL(request.url).searchParams;
+        const operation = params.get('op') ?? (request.method === 'GET' ? 'list' : 'create');
+        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 { owner } = access;
+        const allowed = async (name) => access.allow === undefined || await access.allow(name) === true;
+        try {
+            if (request.method === 'GET' && operation === 'list') {
+                if (!await allowed('list'))
+                    return failure(403, 'not-authorized');
+                const archived = params.get('archived');
+                const limit = params.get('limit');
+                const page = await conversations.list({ owner, archived: archived === 'all' ? 'all' : archived === '1' || archived === 'true',
+                    ...(params.get('q') ? { query: params.get('q') } : {}), ...(limit ? { limit: Number(limit) || 50 } : {}), ...(params.get('cursor') ? { cursor: params.get('cursor') } : {}) });
+                return Response.json({ conversations: page.items, ...(page.next ? { next: page.next } : {}) }, { headers });
+            }
+            if (request.method !== 'POST')
+                return failure(404, 'unknown-operation');
+            const input = await readJsonBody(request, 65_536, request.signal).catch(error => { if (error instanceof RequestGuardError && error.status !== 400)
+                throw error; return {}; });
+            const body = (input !== null && typeof input === 'object' && !Array.isArray(input) ? input : {});
+            const title = typeof body['title'] === 'string' ? body['title'] : undefined;
+            if (operation === 'create') {
+                if (!await allowed('create'))
+                    return failure(403, 'not-authorized');
+                const created = await conversations.create(owner, { ...(title === undefined ? {} : { title }), ...(access.start ? { start: access.start } : {}) });
+                await access.opened?.(created);
+                return Response.json({ conversationId: created.id }, { headers });
+            }
+            const id = idOf(body['conversationId']);
+            if (id === undefined)
+                return failure(400, 'invalid-request');
+            if (operation === 'rename') {
+                if (title === undefined || !title.trim())
+                    return failure(400, 'invalid-request');
+                if (!await allowed('rename'))
+                    return failure(403, 'not-authorized');
+                const renamed = await conversations.rename(owner, id, title);
+                return renamed ? Response.json({ conversation: renamed }, { headers }) : failure(404, 'unknown-conversation');
+            }
+            if (operation === 'archive') {
+                if (body['archived'] !== undefined && typeof body['archived'] !== 'boolean')
+                    return failure(400, 'invalid-request');
+                if (!await allowed('archive'))
+                    return failure(403, 'not-authorized');
+                const changed = await conversations.archive(owner, id, body['archived'] !== false);
+                return changed ? Response.json({ conversation: changed }, { headers }) : failure(404, 'unknown-conversation');
+            }
+            if (operation === 'delete') {
+                if (!await allowed('delete'))
+                    return failure(403, 'not-authorized');
+                if (!await conversations.delete(owner, id))
+                    return failure(404, 'unknown-conversation');
+                await access.deleted?.(id);
+                return Response.json({ deleted: true }, { headers });
+            }
+            if (operation === 'fork') {
+                const at = idOf(body['at']);
+                if (at === undefined)
+                    return failure(400, 'invalid-request');
+                if (!await allowed('fork'))
+                    return failure(403, 'not-authorized');
+                const forked = await conversations.fork(owner, id, at, title === undefined ? {} : { title });
+                if (!forked)
+                    return failure(404, 'unknown-conversation');
+                await access.opened?.(forked);
+                return Response.json({ conversationId: forked.id }, { headers });
+            }
+        }
+        catch (error) {
+            if (error instanceof RequestGuardError)
+                return failure(error.status, error.status === 413 ? 'request-too-large' : 'invalid-request');
+            if (error instanceof TypeError)
+                return failure(400, 'invalid-request');
+            return failure(503, error instanceof Error && error.message ? `source-unavailable: ${error.message.slice(0, 200)}` : 'source-unavailable');
+        }
+        return failure(404, 'unknown-operation');
+    };
+}

package/dist/definitions.d.ts

@@ -0,0 +1,37 @@
+import type { ResourceAccess, ResourceReader, ResourceRef } from '@hachej/boring-files';
+import type { AgentChange, ToolRegistration } from '@earendil-works/pi-durable';
+import type { NativeVersion } from './native-version.js';
+export interface ResolvedDefinitionTool {
+    readonly tool: ToolRegistration;
+    /** Host identity for the effective implementation, including native wrappers. */
+    readonly implementationVersion: string;
+}
+export interface AgentDefinitionBinding {
+    readonly ref: ResourceRef;
+    readonly scopeId: string;
+    readonly digest: string;
+    readonly formatVersion: 1;
+    readonly nativeVersion: NativeVersion;
+    readonly implementationVersion: string;
+    readonly tools: readonly {
+        readonly name: string;
+        readonly implementationVersion: string;
+    }[];
+}
+export interface AgentDefinitionOptions {
+    readonly reader: ResourceReader;
+    readonly ref: ResourceRef;
+    readonly access: ResourceAccess;
+    readonly implementationVersion: string;
+    /** Resolve currently installed and permitted tools; this does not grant later execution. */
+    readonly resolveTool: (name: string) => ResolvedDefinitionTool | undefined | Promise<ResolvedDefinitionTool | undefined>;
+    readonly expectedBinding?: AgentDefinitionBinding;
+    readonly maxBytes?: number;
+}
+export interface LoadedAgentDefinition {
+    readonly change: AgentChange;
+    readonly binding: AgentDefinitionBinding;
+}
+/** Load data only. Native configuration stores tool names, so the host must recheck implementations at admission. */
+export declare function loadAgentDefinition(options: AgentDefinitionOptions): Promise<LoadedAgentDefinition>;
+//# sourceMappingURL=definitions.d.ts.map

package/dist/definitions.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { accessSnapshot, identifier, reference } from '@hachej/boring-files/publication';
+import { NATIVE_VERSION, isNativeVersion } from './native-version.js';
+function object(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key)))
+        throw new TypeError('Invalid definition object');
+    return Object.fromEntries(Object.entries(value));
+}
+function names(value) {
+    if (!Array.isArray(value) || value.length > 64)
+        throw new TypeError('Invalid definition tool list');
+    const result = value.map(item => identifier(item));
+    if (new Set(result).size !== result.length)
+        throw new TypeError('Duplicate definition tool');
+    return result;
+}
+function binding(value) {
+    const input = object(value, ['ref', 'scopeId', 'digest', 'formatVersion', 'nativeVersion', 'implementationVersion', 'tools']);
+    if (input.formatVersion !== 1 || !isNativeVersion(input.nativeVersion)
+        || typeof input.digest !== 'string' || !/^[a-f0-9]{64}$/.test(input.digest)
+        || !Array.isArray(input.tools) || input.tools.length > 64)
+        throw new TypeError('Invalid definition binding');
+    const tools = input.tools.map(value => {
+        const tool = object(value, ['name', 'implementationVersion']);
+        return { name: identifier(tool.name), implementationVersion: identifier(tool.implementationVersion) };
+    });
+    if (new Set(tools.map(tool => tool.name)).size !== tools.length)
+        throw new TypeError('Duplicate bound tool');
+    return { ref: reference(input.ref), scopeId: identifier(input.scopeId), digest: input.digest, formatVersion: 1,
+        nativeVersion: input.nativeVersion, implementationVersion: identifier(input.implementationVersion), tools };
+}
+/** Load data only. Native configuration stores tool names, so the host must recheck implementations at admission. */
+export async function loadAgentDefinition(options) {
+    const ref = reference(options.ref), access = accessSnapshot(options.access);
+    const implementationVersion = identifier(options.implementationVersion), maxBytes = options.maxBytes === undefined ? 65536 : options.maxBytes;
+    const expected = options.expectedBinding === undefined ? undefined : binding(options.expectedBinding);
+    const read = options.reader.read.bind(options.reader), resolveTool = options.resolveTool;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 1048576 || typeof resolveTool !== 'function') {
+        throw new TypeError('Invalid definition loader options');
+    }
+    const resolve = resolveTool.bind(options);
+    access.signal?.throwIfAborted();
+    let result;
+    try {
+        result = await read({ target: { resource: { ...ref.resource }, view: { ...ref.view } }, revision: { kind: 'exact', value: ref.revision } }, { ...access });
+    }
+    catch {
+        access.signal?.throwIfAborted();
+        throw new Error('Definition read failed');
+    }
+    access.signal?.throwIfAborted();
+    if (result?.kind !== 'available')
+        throw new Error('Definition is not available');
+    const snapshot = result.snapshot;
+    if (!snapshot || JSON.stringify(reference(snapshot.ref)) !== JSON.stringify(ref)
+        || !(snapshot.bytes instanceof Uint8Array) || snapshot.bytes.byteLength > maxBytes
+        || typeof snapshot.mediaType !== 'string' || !/^application\/json\s*(?:;\s*charset\s*=\s*utf-8\s*)?$/i.test(snapshot.mediaType.trim())) {
+        throw new TypeError('Definition snapshot does not match the selected JSON resource');
+    }
+    const bytes = Uint8Array.from(snapshot.bytes), digest = createHash('sha256').update(bytes).digest('hex');
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new TypeError('Definition must contain UTF-8 JSON');
+    }
+    const data = object(parsed, ['format', 'version', 'instructions', 'tools']);
+    if (data.format !== 'boring.agent' || data.version !== 1 || typeof data.instructions !== 'string'
+        || new TextDecoder('utf-8', { ignoreBOM: true }).decode(new TextEncoder().encode(data.instructions)) !== data.instructions)
+        throw new TypeError('Unsupported agent definition');
+    const selected = names(data.tools), tools = [], versions = [];
+    for (const name of selected) {
+        access.signal?.throwIfAborted();
+        let resolved;
+        try {
+            resolved = await resolve(name);
+        }
+        catch {
+            throw new Error('Definition tool resolution failed');
+        }
+        access.signal?.throwIfAborted();
+        if (!resolved || !resolved.tool || resolved.tool.name !== name || typeof resolved.tool.execute !== 'function'
+            || typeof resolved.tool.description !== 'string' || !resolved.tool.parameters || typeof resolved.tool.parameters !== 'object') {
+            throw new TypeError('Definition tool is not installed and permitted');
+        }
+        versions.push({ name, implementationVersion: identifier(resolved.implementationVersion) });
+        tools.push(resolved.tool);
+    }
+    access.signal?.throwIfAborted();
+    if (tools.some((tool, index) => tool.name !== selected[index]))
+        throw new TypeError('Definition tool changed while loading');
+    const loaded = { ref, scopeId: access.scopeId, digest, formatVersion: 1,
+        nativeVersion: NATIVE_VERSION, implementationVersion, tools: versions };
+    if (expected && JSON.stringify(expected) !== JSON.stringify(loaded))
+        throw new TypeError('Definition compatibility binding changed');
+    return { change: { instructions: data.instructions, tools }, binding: loaded };
+}