@hachej/boring-agent 0.1.111 → 0.2.1

package/dist/memory/optchat.js

@@ -0,0 +1,432 @@
+// OptChat memory as one native pi-durable extension, opt-in per conversation.
+// The Pi transcript is the append-only log and is never rewritten. While the extension is selected, `beforeRequest` shows
+// the model one view of everything before the current turn: a tiling of the log by summary-tree nodes, one `id+n|text`
+// line each. The current turn (the latest user message and the steps after it) stays verbatim, and every positional
+// system message is kept. Summaries are made by native pi-durable tasks (one background task per node, shipped in the
+// extension's `tasks`, so Pi schedules, runs and recovers them) and stored in a conversation document family.
+// Idea, algorithm and prompts: Victor Taelin's OptChat, https://gist.github.com/VictorTaelin/91837951a5ce5b38f341ec1ba1df6449
+import { CompactionTask, GenerationTask, defineDoc, defineDocFamily, defineExtension, defineTask, defineTool, hook, section } from '@earendil-works/pi-durable';
+import { withAbortSignal, withCancel } from '@earendil-works/chord/context';
+import { Type } from '@earendil-works/pi-ai';
+import { DEFAULTS, OptChatLog, OptChatTree, advanceFold, bareLines, byteLength, compactPrompt, cutBytes, dateText, emptyFold, leavesOf, nodeKey, openParts, partStart, renderView, scaleLine, span, viewDoc, zoomText, } from './optchat-core.js';
+export { DEFAULTS as OPTCHAT_DEFAULTS, PLACEHOLDER as OPTCHAT_PLACEHOLDER, compactPrompt, viewDoc } from './optchat-core.js';
+export { OptChatLog, OptChatTree, advanceFold, emptyFold, leavesOf, renderView, zoomText, dateText } from './optchat-core.js';
+/** Summaries of one conversation, in shards of 64 nodes per level (`<level>.<shard>`). A fork starts with the current ones; fingerprints reject any that no longer match. */
+export const OptChatNodes = defineDocFamily({
+    kind: 'boring.memory.optchat.nodes', version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current', initial: () => ({ nodes: {} }),
+});
+/** Compactor bookkeeping of one conversation: the summarizer's calls and spend, and the last failure of each node (the retry spacing reads it; no timer does). */
+export const OptChatState = defineDoc({
+    kind: 'boring.memory.optchat.state', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    initial: () => ({ calls: 0, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }, failures: {} }),
+});
+const SHARD = 64;
+const shardKey = (level, index) => `${level}.${Math.floor(index / SHARD)}`;
+class Session {
+    id;
+    log = new OptChatLog();
+    stored = new Map();
+    tree;
+    fold = emptyFold();
+    /** Summary tasks may be created for leaves below this; the current turn's steps are held back while a request runs. */
+    upTo = 0;
+    lastRequest;
+    constructor(id, nodeBytes) {
+        this.id = id;
+        this.tree = new OptChatTree(this.log, this.stored, nodeBytes);
+    }
+    /** Take the log of a request or a context read; a changed history drops the fold (summaries stay, checked by fingerprint). */
+    sync(leaves) {
+        const before = this.log.leaves.length;
+        if (this.log.set(leaves) < before) {
+            this.tree.reset();
+            this.fold = emptyFold();
+        }
+    }
+}
+const message = (text) => ({ role: 'user', content: text.map(part => ({ type: 'text', text: part })), timestamp: Date.now() });
+const LIVE = ['pending', 'running', 'waiting'];
+const addUsage = (sum, usage) => {
+    if (!sum)
+        return structuredClone(usage);
+    sum.input += usage.input;
+    sum.output += usage.output;
+    sum.cacheRead += usage.cacheRead;
+    sum.cacheWrite += usage.cacheWrite;
+    sum.totalTokens += usage.totalTokens;
+    if (usage.cacheWrite1h !== undefined)
+        sum.cacheWrite1h = (sum.cacheWrite1h ?? 0) + usage.cacheWrite1h;
+    if (usage.reasoning !== undefined)
+        sum.reasoning = (sum.reasoning ?? 0) + usage.reasoning;
+    sum.cost.input += usage.cost.input;
+    sum.cost.output += usage.cost.output;
+    sum.cost.cacheRead += usage.cost.cacheRead;
+    sum.cost.cacheWrite += usage.cost.cacheWrite;
+    sum.cost.total += usage.cost.total;
+    return sum;
+};
+export function createOptChatMemory(options) {
+    const nodeBytes = options.nodeBytes ?? DEFAULTS.nodeBytes, viewBytes = options.viewBytes ?? DEFAULTS.viewBytes, jobs = options.jobs ?? DEFAULTS.jobs;
+    const tries = options.tries ?? DEFAULTS.tries, cap = options.cap ?? DEFAULTS.cap, retryMs = options.retryMs ?? DEFAULTS.retryMs, settleMs = options.settleTimeoutMs ?? DEFAULTS.settleTimeoutMs;
+    const agentName = options.agentName ?? 'OptChat';
+    const extensionName = options.name ?? 'boring.memory.optchat';
+    const taskKind = `${extensionName}.node`;
+    const system = compactPrompt(agentName);
+    const scale = scaleLine(nodeBytes);
+    const sessions = new Map();
+    const aborter = new AbortController();
+    const hostContext = withAbortSignal(aborter.signal, options.context);
+    const session = (id) => {
+        let found = sessions.get(String(id));
+        if (!found)
+            sessions.set(String(id), found = new Session(id, nodeBytes));
+        return found;
+    };
+    /** Read the stored summaries. Tasks write them (in this process or another, before or after a restart), so every read goes to the documents. */
+    async function loadStored(s, reader, context) {
+        const total = s.log.leaves.length;
+        for (let level = 0; span(level) <= total; level++) {
+            const nodes = Math.floor(total / span(level));
+            for (let shard = 0; shard * SHARD < nodes; shard++) {
+                const doc = await reader.snapshot(OptChatNodes, s.id, `${level}.${shard}`, context);
+                for (const [index, node] of Object.entries(doc?.nodes ?? {}))
+                    s.stored.set(nodeKey(level, Number(index)), node);
+            }
+        }
+    }
+    async function conversationOf(id) {
+        const found = await options.harness().conversation(id, options.context);
+        if (!found)
+            throw new Error(`No conversation ${String(id)}`);
+        return found;
+    }
+    /** Bring a session up to date with the committed context and its stored summaries. */
+    async function refresh(id) {
+        const s = session(id);
+        const view = await (await conversationOf(id)).context(options.context);
+        s.sync(leavesOf(view.messages, cap).leaves);
+        await loadStored(s, options.harness(), options.context);
+        return s;
+    }
+    // ---- The summarizer (runs inside the native task) ----------------------------------------------------------------------
+    /** One node by the reference protocol (§4.2, §4.3): context first, then the step; over-long lines are resubmitted cut at the limit; the shortest wins. */
+    async function askModel(job, runtimeModels, signal) {
+        const summarizer = options.summarizer;
+        if ('summarize' in summarizer) {
+            try {
+                return { text: cutBytes((await summarizer.summarize(job, signal)).trim(), nodeBytes), calls: 1 };
+            }
+            catch (error) {
+                if (signal.aborted)
+                    throw error;
+                return { error, calls: 1 };
+            }
+        }
+        const models = summarizer.models ?? runtimeModels;
+        const ref = typeof summarizer.model === 'function' ? await summarizer.model(job.conversationId) : summarizer.model;
+        const model = models.getModel(ref.provider, ref.modelId);
+        if (!model)
+            throw new Error(`Summarizer model ${ref.provider}/${ref.modelId} is not available`);
+        const lines = job.source.map(line => line.replace(/\r?\n/g, ' '));
+        const step = `For scale, this line is exactly ${scale.bytes} bytes:\n${scale.text}\n\n` + (job.level === 0
+            ? `Compress this message into one line, in at most ${nodeBytes} bytes:\n${job.source[0]}`
+            : `Merge these two lines into one, in at most ${nodeBytes} bytes:\n${lines.join('\n')}`);
+        const conversation = [message([`<chat>\n${job.context}\n</chat>`, step])];
+        const attempts = [];
+        let usage, calls = 0, spender;
+        try {
+            for (;;) {
+                const reply = await models.complete(model, { systemPrompt: system, messages: conversation }, { signal });
+                calls++;
+                spender = `${reply.provider}/${reply.model}`;
+                usage = addUsage(usage, reply.usage);
+                if (reply.stopReason === 'error' || reply.stopReason === 'aborted')
+                    throw new Error(reply.errorMessage ?? `Summarizer stopped: ${reply.stopReason}`);
+                const line = reply.content.filter(part => part.type === 'text').map(part => part.text).join('\n').trim();
+                if (!line)
+                    throw new Error('The summarizer returned nothing');
+                attempts.push(line);
+                if (byteLength(line) <= nodeBytes || attempts.length >= tries)
+                    break;
+                conversation.push(reply, message([`That line is ${byteLength(line)} bytes; the limit is ${nodeBytes}. It must end where it is cut here:\n${cutBytes(line, nodeBytes)}| ← LIMIT`]));
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            return { error, ...(usage ? { usage } : {}), calls, ...(spender ? { spender } : {}) };
+        }
+        return { text: attempts.reduce((best, line) => byteLength(line) < byteLength(best) ? line : best), ...(usage ? { usage } : {}), calls, ...(spender ? { spender } : {}) };
+    }
+    /** What one node task adds to the conversation's documents in its single commit: calls, spend and the node or its failure. */
+    async function bookkeeping(tx, id, summary) {
+        const state = await tx.doc(OptChatState, id);
+        state.calls += summary.calls;
+        if (summary.usage && summary.spender) {
+            const u = summary.usage;
+            state.usage.input += u.input;
+            state.usage.output += u.output;
+            state.usage.cacheRead += u.cacheRead;
+            state.usage.cacheWrite += u.cacheWrite;
+            state.usage.cost += u.cost.total;
+        }
+        return state;
+    }
+    const NodeTask = defineTask({
+        name: taskKind, version: 1, initial: () => ({ phase: 'summarize' }),
+        phases: {
+            summarize: async (running, runtime, context) => {
+                const { level, index, of, upTo } = running.input, id = runtime.conversationId;
+                // Nothing to write; a model call that already ran still books its spend.
+                const stale = (summary) => runtime.commit(async (tx) => {
+                    if (summary)
+                        await bookkeeping(tx, id, summary);
+                    return { status: 'terminal', outcome: { status: 'completed', result: { built: false } } };
+                }, context);
+                // A private view of this conversation: a request may be folding and rendering the shared session right now.
+                const s = new Session(id, nodeBytes);
+                const load = async () => {
+                    s.sync(leavesOf((await runtime.context(id, context)).messages, cap).leaves);
+                    await loadStored(s, runtime, context);
+                };
+                await load();
+                const ready = () => s.log.fp(level, index) === of && (level === 0 || (s.tree.text(level - 1, 2 * index) !== undefined && s.tree.text(level - 1, 2 * index + 1) !== undefined));
+                if (!ready() || s.tree.text(level, index) !== undefined)
+                    return stale(); // the history changed, a child is missing, or the node needs no summary
+                const to = Math.min(upTo, s.log.leaves.length);
+                if (s.fold.T > to)
+                    s.fold = emptyFold();
+                advanceFold(s.fold, s.tree, to, viewBytes);
+                const source = level === 0 ? [s.log.leaves[index].line] : [s.tree.text(level - 1, 2 * index), s.tree.text(level - 1, 2 * index + 1)];
+                const job = { conversationId: id, level, index, range: [index * span(level), (index + 1) * span(level) - 1], source, context: bareLines(s.fold, s.tree, level === 0 ? index : (index + 1) * span(level)), nodeBytes };
+                const summary = await askModel(job, runtime.models, runtime.signal);
+                await load();
+                if (!ready())
+                    return stale(summary); // the history changed while the model ran: its line is dropped, its spend is kept
+                let firstFailure = false;
+                await runtime.commit(async (tx) => {
+                    const state = await bookkeeping(tx, id, summary);
+                    if (summary.text === undefined) {
+                        firstFailure = state.failures[`${level}:${index}`]?.of !== of;
+                        state.failures[`${level}:${index}`] = { at: Date.now(), of, error: String(summary.error?.message ?? summary.error) };
+                        return { status: 'terminal', outcome: { status: 'failed', error: { message: state.failures[`${level}:${index}`].error } } };
+                    }
+                    const doc = await tx.doc(OptChatNodes, id, shardKey(level, index), 0);
+                    doc.nodes[String(index)] = { text: summary.text, of };
+                    delete state.failures[`${level}:${index}`];
+                    return { status: 'terminal', outcome: { status: 'completed', result: { built: true } } };
+                }, context);
+                if (firstFailure)
+                    try {
+                        options.onError?.(summary.error, { conversationId: id, level, index });
+                    }
+                    catch { /* a reporter must not stop a task */ }
+            },
+        },
+        abort: async (_running, runtime, context) => { await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'aborted' } }), context); },
+    });
+    // ---- Admission and waiting ---------------------------------------------------------------------------------------------
+    /** Nodes that could be built now: sources exist and the whole preceding view is summarized (§4.1), oldest first. */
+    function candidates(s) {
+        const upTo = Math.min(s.upTo, s.log.leaves.length);
+        advanceFold(s.fold, s.tree, upTo, viewBytes);
+        const open = openParts(s.fold)[0];
+        const first = open ? partStart(open) : s.fold.T;
+        const found = [];
+        for (let level = 0; span(level) <= upTo; level++) {
+            for (let index = 0; (index + 1) * span(level) <= upTo; index++) {
+                const end = level === 0 ? index : (index + 1) * span(level);
+                if (end > first)
+                    break;
+                if (s.tree.text(level, index) !== undefined)
+                    continue;
+                if (level > 0 && (s.tree.text(level - 1, 2 * index) === undefined || s.tree.text(level - 1, 2 * index + 1) === undefined))
+                    continue;
+                found.push({ level, index });
+            }
+        }
+        return found;
+    }
+    /**
+     * Make sure every node that can be built has one live background task, up to `jobs` live tasks of the conversation. Host
+     * admission only: Pi schedules and runs the tasks. One live task per node key (found by scanning native tasks in the same
+     * commit that creates them); a node whose last failure is inside `retryMs` is left for the next trigger.
+     */
+    async function admit(s, skip) {
+        const wanted = candidates(s).map(({ level, index }) => ({ level, index, of: s.log.fp(level, index) }));
+        const failures = (await options.harness().snapshot(OptChatState, s.id, options.context))?.failures ?? {};
+        const now = Date.now(), upTo = Math.min(s.upTo, s.log.leaves.length);
+        const conversation = await conversationOf(s.id);
+        let waiting = 0, created = 0;
+        const live = await conversation.commit(async (tx) => {
+            const found = new Map();
+            for (const status of LIVE) {
+                let cursor;
+                do {
+                    const page = await tx.scanTasks({ conversationId: s.id, kind: taskKind, status }, 200, cursor);
+                    for (const task of page.items)
+                        found.set(task.input.key, task.id);
+                    cursor = page.next;
+                } while (cursor);
+            }
+            for (const node of wanted) {
+                if (found.size >= jobs)
+                    break;
+                const key = `${nodeKey(node.level, node.index)}:${node.of}`;
+                if (found.has(key) || skip.has(key))
+                    continue;
+                const failure = failures[nodeKey(node.level, node.index)];
+                if (failure && failure.of === node.of && now - failure.at < retryMs) {
+                    waiting++;
+                    continue;
+                }
+                found.set(key, await tx.createTask(NodeTask, { key, level: node.level, index: node.index, of: node.of, upTo }, { ownership: { kind: 'conversation' }, background: true }));
+                created++;
+            }
+            return found;
+        }, options.context);
+        return { live, created, waiting };
+    }
+    /** Wait (natively, `waitForTask`) until one of the tasks settles, or `ms` pass or the context ends. Returns what settled, if anything. */
+    async function settleAny(ids, ms, context) {
+        const { context: waiter, cancel } = withCancel(withAbortSignal(aborter.signal, context));
+        const timer = ms === undefined ? undefined : setTimeout(cancel, Math.max(0, ms));
+        try {
+            const done = await Promise.race(ids.map(id => options.harness().waitForTask(id, waiter).then(task => ({ key: task.input.key, built: task.state.outcome.status === 'completed' && task.state.outcome.result?.built === true }), () => undefined)));
+            return done;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            cancel();
+        }
+    }
+    async function nap(id) {
+        const s = await refresh(id);
+        s.upTo = s.log.leaves.length;
+        const skip = new Set();
+        for (;;) {
+            const { live } = await admit(s, skip);
+            if (live.size === 0)
+                return;
+            const done = await settleAny([...live.values()], undefined, hostContext);
+            if (!done)
+                return; // disposed
+            if (!done.built)
+                skip.add(done.key);
+            await loadStored(s, options.harness(), options.context);
+        }
+    }
+    /** Wait until every line of the view is a summary (§6). Never shows cut text: on timeout the rest shows the placeholder. */
+    async function settle(s, covered, context) {
+        const deadline = Date.now() + settleMs, skip = new Set();
+        for (;;) {
+            await loadStored(s, options.harness(), options.context);
+            advanceFold(s.fold, s.tree, covered, viewBytes);
+            const open = openParts(s.fold).length;
+            if (open === 0 && s.fold.size <= viewBytes)
+                return true;
+            const { live } = await admit(s, skip);
+            if (open === 0 && live.size === 0)
+                return true;
+            if (live.size === 0)
+                return false; // nothing to wait for: every missing node is inside its retry window
+            const left = deadline - Date.now();
+            if (left <= 0 || context.abortSignal?.aborted)
+                return false;
+            const done = await settleAny([...live.values()], left, context);
+            if (done && !done.built)
+                skip.add(done.key);
+        }
+    }
+    // ---- The extension -----------------------------------------------------------------------------------------------------
+    const text = (value) => ({ content: [{ type: 'text', text: value }] });
+    const zoomTool = defineTool({
+        name: 'zoom',
+        description: 'Open the line id+n of the view into the two lines of n/2 under it; n = 1 gives the message whole.',
+        parameters: Type.Object({ id: Type.Integer({ minimum: 0 }), n: Type.Integer({ minimum: 1 }) }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async ({ id, n }, api) => text(zoomText((await refresh(api.conversationId)).tree, id, n)),
+    });
+    const dateTool = defineTool({
+        name: 'date',
+        description: 'The date and time of message id.',
+        parameters: Type.Object({ id: Type.Integer({ minimum: 0 }) }, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async ({ id }, api) => text(dateText((await refresh(api.conversationId)).log, id)),
+    });
+    const extension = defineExtension({
+        name: extensionName,
+        tools: [zoomTool, dateTool],
+        sections: [section('optchat-view', () => viewDoc(agentName), { tag: false })],
+        tasks: [NodeTask],
+        hooks: [
+            hook(GenerationTask, {
+                beforeRequest: async (request, api, context) => {
+                    const { leaves, before } = leavesOf(request.messages, cap);
+                    const last = request.messages.findLastIndex(item => item.role === 'user');
+                    const covered = last < 0 ? 0 : before[last];
+                    if (covered === 0)
+                        return undefined; // nothing came before this turn
+                    const s = session(api.conversationId);
+                    s.sync(leaves);
+                    s.upTo = covered;
+                    if (s.fold.T > covered)
+                        s.fold = emptyFold();
+                    const started = Date.now();
+                    const settled = await settle(s, covered, context);
+                    const view = renderView(s.fold, s.tree);
+                    const messages = request.messages.flatMap((item, index) => {
+                        if (index < last)
+                            return item.role === 'system' ? [item] : [];
+                        if (index > last)
+                            return [item];
+                        const user = item;
+                        const body = typeof user.content === 'string' ? [{ type: 'text', text: user.content }] : user.content;
+                        return [{ ...user, content: [{ type: 'text', text: view }, ...body] }];
+                    });
+                    s.lastRequest = { at: new Date().toISOString(), covered, requestMessages: messages.length, logMessages: request.messages.length, viewBytes: byteLength(view), waitedMs: Date.now() - started, settled };
+                    return { messages };
+                },
+                // A finished answer: once the run has committed it, create its summary tasks (background, so they never hold the run) so the next request finds its view ready.
+                onYield: (_answer, api) => {
+                    void (async () => { await (await conversationOf(api.conversationId)).waitForIdle(hostContext); await nap(api.conversationId); })().catch(() => { });
+                    return undefined;
+                },
+            }),
+            // A native compaction summary would cut the transcript this view is built from; the view replaces it while this extension is selected.
+            hook(CompactionTask, { beforeCompact: () => ({ decline: true }) }),
+        ],
+    });
+    return {
+        extension,
+        nap: id => nap(id),
+        async stats(id) {
+            const s = await refresh(id);
+            const fold = { T: s.fold.T, size: s.fold.size, parts: s.fold.parts.map(part => ({ ...part })) };
+            advanceFold(fold, s.tree, s.log.leaves.length, viewBytes);
+            let summaries = 0;
+            for (const [key, node] of s.stored) {
+                const [level, index] = key.split(':').map(Number);
+                if (node.of === s.log.fp(level, index))
+                    summaries++;
+            }
+            const state = await options.harness().snapshot(OptChatState, id, options.context);
+            const failures = Object.entries(state?.failures ?? {}).filter(([key, failure]) => { const [level, index] = key.split(':').map(Number); return failure.of === s.log.fp(level, index); }).map(([, failure]) => failure);
+            const busy = (await options.harness().inspect(options.context)).tasks.filter(task => task.record.kind === taskKind && task.record.conversationId === id).length;
+            const retrying = failures.filter(failure => Date.now() - failure.at < retryMs).length;
+            const latest = failures.reduce((best, failure) => !best || failure.at > best.at ? failure : best, undefined);
+            return {
+                leaves: s.log.leaves.length, summaries,
+                view: { bytes: fold.size, budget: viewBytes, open: openParts(fold).length,
+                    parts: fold.parts.map(part => ({ id: partStart(part), n: span(part.level), level: part.level, text: s.tree.text(part.level, part.index) ?? '', open: part.open })) },
+                compactor: { busy, retrying, failed: failures.length, idle: busy === 0 && retrying === 0, ...(latest ? { error: latest.error } : {}), calls: state?.calls ?? 0, usage: { ...(state?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }) } },
+                ...(s.lastRequest ? { lastRequest: s.lastRequest } : {}),
+            };
+        },
+        async zoom(id, nth, n) { return zoomText((await refresh(id)).tree, nth, n); },
+        async date(id, nth) { return dateText((await refresh(id)).log, nth); },
+        forget(id) { sessions.delete(String(id)); },
+        async dispose() { aborter.abort(); },
+    };
+}

package/dist/mentions.d.ts

@@ -0,0 +1,56 @@
+import type { InputSubmissionDraft } from '@earendil-works/pi-durable';
+import type { ResourceAccess } from '@hachej/boring-files';
+import type { WorkspaceBinding } from './workspaces.js';
+/** The native input content a submission carries: a string, or text and image parts. */
+export type MentionInput = InputSubmissionDraft['content'];
+/** What a host reader returns for one workspace path. `bytes` is absent when the file is too large to read. */
+export interface MentionFile {
+    readonly size: number;
+    readonly bytes?: Uint8Array;
+}
+/** Read one workspace-relative path. Return undefined when it is missing, outside the workspace or unreadable. Never throw to refuse. */
+export type MentionReader = (path: string, options?: {
+    readonly bytes?: boolean;
+}) => Promise<MentionFile | undefined>;
+export interface MentionLimits {
+    /** Largest part of one file given to the model; more is cut and the cut is stated. Default 100 KB. */
+    readonly fileBytes?: number;
+    /** Most bytes of file content in one message. Later files become a note. Default 300 KB. */
+    readonly totalBytes?: number;
+    /** Most distinct mentions resolved in one message. Default 20. */
+    readonly files?: number;
+}
+export interface MentionResolverOptions {
+    readonly read: MentionReader;
+    readonly limits?: MentionLimits;
+    /** `inline` (default) puts the content of each mentioned file in the message. `reference` adds one short `<file path type size />` part per file and never its content: the agent reads the file with its tools when it needs it. */
+    readonly mode?: 'inline' | 'reference';
+}
+export declare const MENTION_LIMITS: Readonly<{
+    fileBytes: 100000;
+    totalBytes: 300000;
+    files: 20;
+}>;
+/** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
+export declare const MENTION_FILE_PREFIX = "<file path=\"";
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
+ * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+export declare function mentionedPaths(text: string): string[];
+/** A workspace-relative path with no absolute prefix, no `..`, no backslash and no control characters. */
+export declare function safeMentionPath(path: string): boolean;
+/**
+ * Turn `@workspace/path` mentions of a submitted input into content the model can read, on the host and at submit
+ * time, so an agent with no file tool still sees what the person attached (in `reference` mode it gets a reference only). The `@path` text stays in the message. A
+ * text file becomes a `<file path="...">` text part, an image a native image part, and a binary, oversized, missing,
+ * unreadable or over-budget file one short note. It never throws: an input it cannot improve is returned unchanged.
+ */
+export declare function createMentionResolver(options: MentionResolverOptions): (content: MentionInput) => Promise<MentionInput>;
+/**
+ * A `MentionReader` over the workspace provider: the person's own view of the workspace, through the same access check and
+ * published view the file viewers use. Paths are workspace-relative and the provider decides what exists, so there is no
+ * containment check of its own. Files above `maxReadBytes` (default 5 MB) are reported by size and not given.
+ */
+export declare function workspaceMentionReader(files: WorkspaceBinding['files'], access: ResourceAccess, options?: {
+    readonly maxReadBytes?: number;
+}): MentionReader;
+//# sourceMappingURL=mentions.d.ts.map

package/dist/mentions.js

@@ -0,0 +1,140 @@
+import { SNIFF_BYTES, extensionOf, fileKind, nativeImageType } from './file-types.js';
+export const MENTION_LIMITS = Object.freeze({ fileBytes: 100_000, totalBytes: 300_000, files: 20 });
+/** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
+export const MENTION_FILE_PREFIX = '<file path="';
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
+ * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+export function mentionedPaths(text) {
+    const found = new Set();
+    for (const match of text.matchAll(/(^|\s)@(?:"((?:[^"\\]|\\.)*)"|([^\s]+))/g)) {
+        const path = match[2] !== undefined ? match[2].replace(/\\(.)/g, '$1') : match[3].replace(/[.,;:!?)\]}'"]+$/, '');
+        if (path)
+            found.add(path);
+    }
+    return [...found];
+}
+/** A workspace-relative path with no absolute prefix, no `..`, no backslash and no control characters. */
+export function safeMentionPath(path) {
+    if (!path || path.startsWith('/') || path.includes('\\') || /[\u0000-\u001f]/.test(path) || /^[A-Za-z]:/.test(path))
+        return false;
+    return !path.split('/').some(segment => segment === '..' || segment === '');
+}
+const attribute = (value) => value.replace(/"/g, '%22').replace(/</g, '%3C');
+const note = (path, reason) => ({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}" unavailable="${attribute(reason)}" />` });
+function utf8(bytes) {
+    if (bytes.includes(0))
+        return undefined;
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Cut at a character boundary: a split multi-byte tail is dropped rather than shown as a replacement character. */
+function utf8Prefix(bytes, limit) {
+    for (let end = Math.min(limit, bytes.length), tries = 0; tries < 4 && end > 0; tries++, end--) {
+        const text = utf8(bytes.subarray(0, end));
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+const base64 = (bytes) => { let binary = ''; for (let at = 0; at < bytes.length; at += 0x8000)
+    binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000)); return btoa(binary); };
+/**
+ * Turn `@workspace/path` mentions of a submitted input into content the model can read, on the host and at submit
+ * time, so an agent with no file tool still sees what the person attached (in `reference` mode it gets a reference only). The `@path` text stays in the message. A
+ * text file becomes a `<file path="...">` text part, an image a native image part, and a binary, oversized, missing,
+ * unreadable or over-budget file one short note. It never throws: an input it cannot improve is returned unchanged.
+ */
+export function createMentionResolver(options) {
+    const limits = { ...MENTION_LIMITS, ...options.limits };
+    return async (content) => {
+        try {
+            const parts = typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+            const paths = mentionedPaths(parts.map(part => part.type === 'text' ? part.text : '').join('\n')).slice(0, limits.files);
+            if (!paths.length)
+                return content;
+            const added = [];
+            const reference = options.mode === 'reference';
+            let used = 0;
+            for (const path of paths) {
+                if (!safeMentionPath(path)) {
+                    added.push(note(path, 'not a path inside the workspace'));
+                    continue;
+                }
+                let file;
+                try {
+                    file = await (reference ? options.read(path, { bytes: false }) : options.read(path));
+                }
+                catch {
+                    file = undefined;
+                }
+                if (!file) {
+                    added.push(note(path, 'not found or not readable'));
+                    continue;
+                }
+                const bytes = file.bytes;
+                const image = nativeImageType(path);
+                if (reference) {
+                    const type = image ?? (extensionOf(path) || undefined);
+                    added.push({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}"${type ? ` type="${attribute(type)}"` : ''} size="${file.size}" />` });
+                    continue;
+                }
+                if (!bytes) {
+                    added.push(note(path, `too large to attach (${file.size} bytes)`));
+                    continue;
+                }
+                if (used >= limits.totalBytes) {
+                    added.push(note(path, `skipped: the ${limits.totalBytes} byte limit for one message was reached`));
+                    continue;
+                }
+                if (image) {
+                    if (bytes.length > limits.fileBytes || used + bytes.length > limits.totalBytes) {
+                        added.push(note(path, `image too large to attach (${bytes.length} bytes)`));
+                        continue;
+                    }
+                    used += bytes.length;
+                    added.push({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}" type="${image}" size="${bytes.length}" />` }, { type: 'image', data: base64(bytes), mimeType: image });
+                    continue;
+                }
+                // Documents are never decoded as text, even when their bytes happen to be valid UTF-8 (an uncompressed PDF is).
+                if (fileKind(path, bytes.subarray(0, SNIFF_BYTES)) !== 'text') {
+                    added.push(note(path, `binary file, ${bytes.length} bytes; content not included`));
+                    continue;
+                }
+                const room = Math.min(limits.fileBytes, limits.totalBytes - used);
+                const text = bytes.length <= room ? utf8(bytes) : utf8Prefix(bytes, room);
+                if (text === undefined) {
+                    added.push(note(path, `binary file, ${bytes.length} bytes; content not included`));
+                    continue;
+                }
+                const cut = bytes.length > room;
+                used += Math.min(bytes.length, room);
+                added.push({ type: 'text', text: `${MENTION_FILE_PREFIX}${attribute(path)}"${cut ? ` truncated="showing the first ${new TextEncoder().encode(text).length} of ${bytes.length} bytes"` : ''}>\n${text.replace(/<\/file>/g, '<\\/file>')}\n</file>` });
+            }
+            return [...parts, ...added];
+        }
+        catch {
+            return content;
+        }
+    };
+}
+/**
+ * A `MentionReader` over the workspace provider: the person's own view of the workspace, through the same access check and
+ * published view the file viewers use. Paths are workspace-relative and the provider decides what exists, so there is no
+ * containment check of its own. Files above `maxReadBytes` (default 5 MB) are reported by size and not given.
+ */
+export function workspaceMentionReader(files, access, options = {}) {
+    const maxRead = options.maxReadBytes ?? 5_000_000;
+    return async (path, readOptions) => {
+        if (!safeMentionPath(path))
+            return undefined;
+        const read = await files.read({ target: { resource: { providerId: files.providerId, path }, view: { kind: 'published' } }, revision: { kind: 'latest' } }, { ...access });
+        if (read.kind !== 'available')
+            return undefined;
+        const bytes = read.snapshot.bytes;
+        return readOptions?.bytes === false || bytes.byteLength > maxRead ? { size: bytes.byteLength } : { size: bytes.byteLength, bytes };
+    };
+}