@hachej/boring-agent 0.1.111 → 0.2.1

package/dist/model-gateway.d.ts

@@ -0,0 +1,86 @@
+/** An upstream speaking OpenAI chat completions. The gateway gives it a rebuilt body; the upstream adds its own credential. */
+export interface ModelUpstream {
+    readonly id: string;
+    /** The upstream's name for the output ceiling (`max_completion_tokens` for OpenAI, `max_tokens` for most compatible APIs). */
+    readonly maxTokensField?: 'max_completion_tokens' | 'max_tokens';
+    readonly chatCompletions: (body: Readonly<Record<string, unknown>>, signal: AbortSignal) => Promise<Response>;
+}
+export type BudgetDecision = {
+    readonly kind: 'admitted';
+    readonly maxTokens: number;
+} | {
+    readonly kind: 'refused';
+    readonly retryAfterSeconds: number;
+    readonly message: string;
+};
+/** Per-person spending policy. `admit` runs once per completion request, before the upstream is called. */
+export interface ModelBudget {
+    readonly admit: (person: string, request: {
+        readonly model: string;
+        readonly maxTokens: number | undefined;
+    }) => BudgetDecision | Promise<BudgetDecision>;
+}
+export interface GatewayLogEntry {
+    readonly person: string | null;
+    readonly model: string | null;
+    readonly status: number;
+    readonly code?: string;
+    readonly latencyMs: number;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+export interface ModelGatewayOptions {
+    readonly upstream: ModelUpstream;
+    /** Allowed gateway model ids; a record maps each to its upstream model id. */
+    readonly allow: readonly string[] | Readonly<Record<string, string>>;
+    readonly budget: ModelBudget;
+    /** The app session: the person's stable id, or nothing (401). Only this callback ever sees the request headers. */
+    readonly authorize: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    readonly log?: (entry: GatewayLogEntry) => void;
+    /** Where the gateway is mounted, for example `/api/llm`. Default: the root. */
+    readonly basePath?: string;
+    readonly maxBodyBytes?: number;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+}
+export declare const OPENAI_BASE_URL = "https://api.openai.com/v1";
+/** Anthropic's OpenAI-compatible endpoint. */
+export declare const ANTHROPIC_OPENAI_BASE_URL = "https://api.anthropic.com/v1";
+export interface OpenAICompatibleUpstreamOptions {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly id?: string;
+    readonly maxTokensField?: 'max_completion_tokens' | 'max_tokens';
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** An OpenAI-compatible upstream at a fixed base URL with the server's key. */
+export declare function openAICompatibleUpstream(options: OpenAICompatibleUpstreamOptions): ModelUpstream;
+/** Anthropic through its OpenAI-compatible endpoint. */
+export declare const anthropicUpstream: (options: Omit<OpenAICompatibleUpstreamOptions, "baseUrl" | "maxTokensField">) => ModelUpstream;
+/** A scripted turn that calls tools instead of answering in text. */
+export interface ScriptedToolCalls {
+    readonly toolCalls: readonly {
+        readonly name: string;
+        readonly arguments: Readonly<Record<string, unknown>>;
+    }[];
+}
+export interface ScriptedUpstreamOptions {
+    /** The deterministic reply to the conversation (OpenAI-shaped messages): text, or tool calls when the request declared tools. */
+    readonly reply: (messages: readonly Readonly<Record<string, unknown>>[], request: {
+        readonly tools: readonly string[];
+    }) => string | ScriptedToolCalls;
+    readonly id?: string;
+}
+/** A keyless upstream answering every request locally with `reply`, in the OpenAI wire format (JSON or SSE), tool calls included. */
+export declare function scriptedUpstream(options: ScriptedUpstreamOptions): ModelUpstream;
+export interface MemoryBudgetOptions {
+    readonly requestsPerMinute: number;
+    readonly maxTokensPerRequest: number;
+    readonly now?: () => number;
+}
+/** In-memory budget for one process: a sliding one-minute request window per person and a per-request output ceiling
+ * (a larger or missing request is clamped to it). A shared gateway swaps in a durable implementation of `ModelBudget`. */
+export declare function memoryBudget(options: MemoryBudgetOptions): ModelBudget;
+/** The gateway as a Fetch handler: `(request) => Promise<Response>`. */
+export declare function createModelGateway(options: ModelGatewayOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=model-gateway.d.ts.map

package/dist/model-gateway.js

@@ -0,0 +1,241 @@
+// @hachej/boring-agent/model-gateway: the host's model gateway. Browser-side Pi agents (`@hachej/boring-agent/gateway-provider`) call models
+// through it with the person's app session; the provider key never leaves the server. Server-only by role (it holds the key),
+// Fetch-only by construction (no node or Pi imports, ARCHITECTURE.json pathRules), so it runs in Node, Workers or a shared
+// "Boring model gateway" service with the same API: the browser knows only a base URL.
+//
+// API under `basePath`: `POST /v1/chat/completions` (OpenAI-compatible, JSON or SSE streaming, passed through as the upstream
+// sends it) and `GET /v1/models` (the allowed ids). The host owns the policy: who may call (`authorize`, the app session), which
+// models (`allow`, gateway id -> upstream id), how much (`budget`), which upstream and key (`upstream`). The browser cannot choose
+// an upstream, a key or a header: the forwarded body is rebuilt from an allowlist of fields and no request header is forwarded.
+// Errors are `{ error: { code, message } }`: 401 no session, 403 model not allowed, 429 budget, 502 upstream failure (never the
+// upstream's body, which may quote the key), 400/404/405/413 for malformed calls. `log` receives metadata only (person, model,
+// status, tokens, latency), never prompts or completions. The body goes through the shared request guard (JSON content type,
+// byte cap), like every other handler of the packages.
+import { RequestGuardError, readJsonBody } from '@hachej/boring-files/request-guard';
+export const OPENAI_BASE_URL = 'https://api.openai.com/v1';
+/** Anthropic's OpenAI-compatible endpoint. */
+export const ANTHROPIC_OPENAI_BASE_URL = 'https://api.anthropic.com/v1';
+/** Body fields a caller may set; everything else (store, user, metadata, n, provider routing...) is dropped. */
+const FORWARDED = ['messages', 'temperature', 'top_p', 'tools', 'tool_choice', 'parallel_tool_calls', 'response_format', 'stop', 'seed', 'presence_penalty', 'frequency_penalty'];
+const failure = (status, code, message, headers = {}) => Response.json({ error: { code, message } }, { status, headers: { 'cache-control': 'no-store', ...headers } });
+/** An OpenAI-compatible upstream at a fixed base URL with the server's key. */
+export function openAICompatibleUpstream(options) {
+    if (!options.apiKey)
+        throw new TypeError('openAICompatibleUpstream needs the server-side apiKey');
+    const base = (options.baseUrl ?? OPENAI_BASE_URL).replace(/\/+$/, '');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const apiKey = options.apiKey;
+    return Object.freeze({
+        id: options.id ?? 'openai', maxTokensField: options.maxTokensField ?? 'max_completion_tokens',
+        chatCompletions: (body, signal) => fetchImpl(`${base}/chat/completions`, {
+            method: 'POST', signal, body: JSON.stringify(body),
+            headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', accept: body.stream === true ? 'text/event-stream' : 'application/json' },
+        }),
+    });
+}
+/** Anthropic through its OpenAI-compatible endpoint. */
+export const anthropicUpstream = (options) => openAICompatibleUpstream({ id: 'anthropic', ...options, baseUrl: ANTHROPIC_OPENAI_BASE_URL, maxTokensField: 'max_tokens' });
+const tokensOf = (text) => Math.max(1, Math.ceil(text.length / 4));
+/** The function names the request declared (`tools[].function.name`). */
+const declaredTools = (tools) => Array.isArray(tools)
+    ? tools.flatMap(tool => { const name = tool?.function?.name; return typeof name === 'string' ? [name] : []; }) : [];
+/** A keyless upstream answering every request locally with `reply`, in the OpenAI wire format (JSON or SSE), tool calls included. */
+export function scriptedUpstream(options) {
+    const encoder = new TextEncoder();
+    let counter = 0;
+    return Object.freeze({
+        id: options.id ?? 'scripted', maxTokensField: 'max_completion_tokens',
+        chatCompletions: async (body) => {
+            const messages = Array.isArray(body.messages) ? body.messages : [];
+            const tools = declaredTools(body.tools);
+            const replied = options.reply(messages, { tools });
+            const calls = typeof replied === 'string' ? [] : replied.toolCalls.filter(call => tools.includes(call.name))
+                .map((call, index) => ({ index, id: `call_scripted_${counter + 1}_${index}`, type: 'function', function: { name: call.name, arguments: JSON.stringify(call.arguments) } }));
+            const text = typeof replied === 'string' ? replied : calls.length ? '' : '(scripted) no declared tool to call.';
+            const finish = calls.length ? 'tool_calls' : 'stop';
+            const id = `chatcmpl-scripted-${++counter}`, created = 0, model = String(body.model);
+            const usage = { prompt_tokens: tokensOf(JSON.stringify(messages)), completion_tokens: tokensOf(text + JSON.stringify(calls)), total_tokens: 0 };
+            const usageTotal = { ...usage, total_tokens: usage.prompt_tokens + usage.completion_tokens };
+            if (body.stream !== true) {
+                const message = calls.length ? { role: 'assistant', content: null, tool_calls: calls.map(({ index: _index, ...call }) => call) } : { role: 'assistant', content: text };
+                return Response.json({ id, object: 'chat.completion', created, model, choices: [{ index: 0, message, finish_reason: finish }], usage: usageTotal });
+            }
+            const chunk = (choices, extra = {}) => `data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created, model, choices, ...extra })}\n\n`;
+            const frames = [
+                chunk([{ index: 0, delta: { role: 'assistant', content: '' }, finish_reason: null }]),
+                ...(text.match(/\S+\s*/g) ?? []).map(piece => chunk([{ index: 0, delta: { content: piece }, finish_reason: null }])),
+                ...calls.map(call => chunk([{ index: 0, delta: { tool_calls: [call] }, finish_reason: null }])),
+                chunk([{ index: 0, delta: {}, finish_reason: finish }]),
+                chunk([], { usage: usageTotal }),
+                'data: [DONE]\n\n',
+            ];
+            return new Response(new ReadableStream({ start(controller) { for (const frame of frames)
+                    controller.enqueue(encoder.encode(frame)); controller.close(); } }), { headers: { 'content-type': 'text/event-stream; charset=utf-8' } });
+        },
+    });
+}
+/** In-memory budget for one process: a sliding one-minute request window per person and a per-request output ceiling
+ * (a larger or missing request is clamped to it). A shared gateway swaps in a durable implementation of `ModelBudget`. */
+export function memoryBudget(options) {
+    const now = options.now ?? Date.now;
+    const windows = new Map();
+    return Object.freeze({
+        admit: (person, request) => {
+            const at = now();
+            const recent = (windows.get(person) ?? []).filter(time => time > at - 60_000);
+            if (recent.length >= options.requestsPerMinute) {
+                windows.set(person, recent);
+                return { kind: 'refused', retryAfterSeconds: Math.max(1, Math.ceil(((recent[0] ?? at) + 60_000 - at) / 1000)), message: `At most ${options.requestsPerMinute} model requests a minute; try again shortly.` };
+            }
+            recent.push(at);
+            windows.set(person, recent);
+            const asked = request.maxTokens;
+            return { kind: 'admitted', maxTokens: asked !== undefined && asked > 0 ? Math.min(asked, options.maxTokensPerRequest) : options.maxTokensPerRequest };
+        },
+    });
+}
+function usageOf(value, into) {
+    const usage = value?.usage;
+    if (typeof usage?.prompt_tokens === 'number')
+        into.inputTokens = usage.prompt_tokens;
+    if (typeof usage?.completion_tokens === 'number')
+        into.outputTokens = usage.completion_tokens;
+}
+/** The gateway as a Fetch handler: `(request) => Promise<Response>`. */
+export function createModelGateway(options) {
+    if (!options.upstream || typeof options.upstream.chatCompletions !== 'function')
+        throw new TypeError('createModelGateway needs an upstream');
+    if (typeof options.authorize !== 'function')
+        throw new TypeError('createModelGateway needs authorize(request)');
+    if (!options.budget || typeof options.budget.admit !== 'function')
+        throw new TypeError('createModelGateway needs a budget');
+    const allowed = new Map(Array.isArray(options.allow) ? options.allow.map(id => [id, id]) : Object.entries(options.allow));
+    const basePath = (options.basePath ?? '').replace(/\/+$/, '');
+    const maxBodyBytes = options.maxBodyBytes ?? 2 * 1024 * 1024;
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const now = options.now ?? Date.now;
+    const upstream = options.upstream;
+    const report = (entry) => { try {
+        options.log?.(entry);
+    }
+    catch { /* logging never fails a request */ } };
+    async function completions(request, person, started) {
+        const done = (status, model, code, response) => { report({ person, model, status, code, latencyMs: now() - started }); return response; };
+        let body;
+        try {
+            const parsed = await readJsonBody(request, maxBodyBytes, request.signal);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new RequestGuardError(400, 'not an object');
+            body = parsed;
+        }
+        catch (error) {
+            const status = error instanceof RequestGuardError ? error.status : 400;
+            return status === 413 ? done(413, null, 'too-large', failure(413, 'too-large', 'The request is too large.'))
+                : status === 415 ? done(415, null, 'unsupported-media-type', failure(415, 'unsupported-media-type', 'Send the request as application/json.'))
+                    : done(400, null, 'invalid', failure(400, 'invalid', 'The body must be a JSON chat completion request.'));
+        }
+        const model = typeof body.model === 'string' ? body.model : null;
+        if (!model || !Array.isArray(body.messages) || body.messages.length === 0)
+            return done(400, model, 'invalid', failure(400, 'invalid', 'A model and at least one message are required.'));
+        const upstreamModel = allowed.get(model);
+        if (upstreamModel === undefined)
+            return done(403, model, 'model-not-allowed', failure(403, 'model-not-allowed', `The model "${model.slice(0, 80)}" is not available here.`));
+        const asked = [body.max_completion_tokens, body.max_tokens].find((value) => typeof value === 'number' && Number.isFinite(value));
+        const decision = await options.budget.admit(person, { model, maxTokens: asked });
+        if (decision.kind === 'refused')
+            return done(429, model, 'budget', failure(429, 'budget', decision.message, { 'retry-after': String(decision.retryAfterSeconds) }));
+        // Rebuilt, never forwarded: the model is the host's mapping, the ceiling the budget's, and only listed fields pass.
+        const stream = body.stream === true;
+        const forwarded = { model: upstreamModel, stream, [upstream.maxTokensField ?? 'max_completion_tokens']: decision.maxTokens };
+        for (const field of FORWARDED)
+            if (body[field] !== undefined)
+                forwarded[field] = body[field];
+        if (stream)
+            forwarded.stream_options = { include_usage: true };
+        const signal = AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs)]);
+        let answer;
+        try {
+            answer = await upstream.chatCompletions(forwarded, signal);
+        }
+        catch {
+            return done(502, model, 'upstream-unreachable', failure(502, 'upstream-unreachable', 'The model provider could not be reached.'));
+        }
+        if (!answer.ok || !answer.body) {
+            await answer.body?.cancel().catch(() => undefined);
+            return done(502, model, 'upstream-failed', failure(502, 'upstream-failed', `The model provider refused the request (${answer.status}).`));
+        }
+        const usage = {};
+        const finish = (status, code) => report({ person, model, status, ...(code ? { code } : {}), latencyMs: now() - started, ...usage });
+        if (!stream) {
+            let json;
+            try {
+                json = await answer.json();
+            }
+            catch {
+                return done(502, model, 'upstream-failed', failure(502, 'upstream-failed', 'The model provider sent an unreadable answer.'));
+            }
+            usageOf(json, usage);
+            finish(200);
+            return Response.json(json, { headers: { 'cache-control': 'no-store' } });
+        }
+        // SSE passthrough, byte for byte; the `usage` frame is read on the way for the log, nothing else is looked at.
+        const reader = answer.body.getReader();
+        const decoder = new TextDecoder();
+        let pending = '';
+        const scan = (text) => {
+            pending += text;
+            const lines = pending.split('\n');
+            pending = lines.pop() ?? '';
+            for (const line of lines)
+                if (line.startsWith('data:') && line.includes('"usage"')) {
+                    try {
+                        usageOf(JSON.parse(line.slice(5)), usage);
+                    }
+                    catch { /* not JSON */ }
+                }
+        };
+        let ended = false;
+        const end = (status, code) => { if (!ended) {
+            ended = true;
+            finish(status, code);
+        } };
+        return new Response(new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { done: finished, value } = await reader.read();
+                    if (finished) {
+                        scan('\n');
+                        end(200);
+                        controller.close();
+                        return;
+                    }
+                    scan(decoder.decode(value, { stream: true }));
+                    controller.enqueue(value);
+                }
+                catch {
+                    end(502, 'upstream-interrupted');
+                    controller.error(new Error('The model provider stream was interrupted.'));
+                }
+            },
+            async cancel() { end(499, 'client-closed'); await reader.cancel().catch(() => undefined); },
+        }), { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', 'x-accel-buffering': 'no' } });
+    }
+    return async (request) => {
+        const started = now();
+        const path = new URL(request.url).pathname;
+        const route = path.startsWith(`${basePath}/`) ? path.slice(basePath.length) : null;
+        if (route !== '/v1/chat/completions' && route !== '/v1/models')
+            return failure(404, 'not-found', 'Unknown model gateway route.');
+        const method = route === '/v1/models' ? 'GET' : 'POST';
+        if (request.method !== method)
+            return failure(405, 'method-not-allowed', `Use ${method}.`, { allow: method });
+        const person = await options.authorize(request);
+        if (!person) {
+            report({ person: null, model: null, status: 401, code: 'unauthenticated', latencyMs: now() - started });
+            return failure(401, 'unauthenticated', 'Sign in to use models.');
+        }
+        if (route === '/v1/models')
+            return Response.json({ object: 'list', data: [...allowed.keys()].map(id => ({ id, object: 'model', owned_by: 'boring-gateway' })) }, { headers: { 'cache-control': 'no-store' } });
+        return completions(request, person, started);
+    };
+}

package/dist/native-version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Pi Durable release whose public exports Boring records were checked against. Records carry it so a reader can tell which
+ * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
+ * readable, because the native conversation and tool shapes they refer to did not change between them.
+ */
+export declare const NATIVE_VERSION = "pi-durable@1.1.0";
+export type NativeVersion = 'pi-durable@1.0.1' | typeof NATIVE_VERSION;
+export declare const isNativeVersion: (value: unknown) => value is NativeVersion;
+//# sourceMappingURL=native-version.d.ts.map

package/dist/native-version.js

@@ -0,0 +1,7 @@
+/**
+ * The Pi Durable release whose public exports Boring records were checked against. Records carry it so a reader can tell which
+ * native shapes produced them. New records take the current release; records written under an earlier reviewed release stay
+ * readable, because the native conversation and tool shapes they refer to did not change between them.
+ */
+export const NATIVE_VERSION = 'pi-durable@1.1.0';
+export const isNativeVersion = (value) => value === NATIVE_VERSION || value === 'pi-durable@1.0.1';

package/dist/native.d.ts

@@ -0,0 +1,4 @@
+/** Exact native interfaces; use upstream values/functions directly. */
+export type { Harness, HarnessOptions, HarnessSettings, Registry, Extension, ToolRegistration, ToolExecutionApi, ToolExecutionResult, ToolControl, ToolHooks, GenerationHooks, CompactionHooks, EnvTarget, Agent, AgentChange, Conversation, ConversationView, ConversationWatch, WatchEnd, ConversationId, Submission, SubmissionDraft, SubmissionId, TaskId, TaskOutcome, Storage, } from '@earendil-works/pi-durable';
+export type { Context } from '@earendil-works/chord';
+//# sourceMappingURL=native.d.ts.map

package/dist/native.js

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

package/dist/presentation.d.ts

@@ -0,0 +1,17 @@
+import type { PresentationCommand, PresentationResult, ViewerTarget } from '@hachej/boring-ui-kit/contracts';
+import type { Context } from '@earendil-works/chord';
+import type { Static, TSchema } from '@earendil-works/pi-ai';
+import { type ToolExecutionApi, type ToolExecutionResult, type ToolRegistration } from '@earendil-works/pi-durable';
+export interface PresentationToolOptions<P extends TSchema, Input, Output, Subject> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: P;
+    readonly command: PresentationCommand<Input, Output, Subject>;
+    readonly target: ViewerTarget<Subject>;
+    readonly prepareInput: (args: Static<P>) => Input;
+    readonly authorize: (input: Input, target: ViewerTarget<Subject>, api: ToolExecutionApi, context: Context) => boolean | Promise<boolean>;
+    readonly formatResult: (result: PresentationResult<Output, Subject>) => ToolExecutionResult;
+}
+/** Bind one captured viewer target to a native, non-replayable tool. Target and parsed input must be structured-cloneable. */
+export declare function createPresentationTool<P extends TSchema, Input, Output, Subject>(options: PresentationToolOptions<P, Input, Output, Subject>): ToolRegistration<P>;
+//# sourceMappingURL=presentation.d.ts.map

package/dist/presentation.js

@@ -0,0 +1,39 @@
+import { defineTool } from '@earendil-works/pi-durable';
+/** Bind one captured viewer target to a native, non-replayable tool. Target and parsed input must be structured-cloneable. */
+export function createPresentationTool(options) {
+    const target = structuredClone(options.target);
+    const { command, prepareInput, authorize, formatResult } = options;
+    const parse = command.input.parse;
+    const invoke = command.invoke;
+    function format(result) {
+        const refused = result.kind !== 'applied' && result.kind !== 'proposed';
+        const formatted = formatResult(result);
+        return refused ? { ...formatted, isError: true } : formatted;
+    }
+    return defineTool({
+        name: options.name,
+        description: options.description,
+        parameters: options.parameters,
+        replay: 'unsafe',
+        execute: async (args, api, context) => {
+            const signal = context.abortSignal;
+            signal?.throwIfAborted();
+            const prepared = prepareInput(args);
+            let input;
+            try {
+                input = parse(prepared);
+            }
+            catch {
+                return format({ kind: 'denied', reason: 'Invalid presentation command input' });
+            }
+            const retainedInput = structuredClone(input);
+            const allowed = await authorize(structuredClone(retainedInput), structuredClone(target), api, context);
+            signal?.throwIfAborted();
+            if (allowed !== true)
+                return format({ kind: 'denied', reason: 'Presentation command authorization denied' });
+            const result = await invoke(structuredClone(target), retainedInput, signal);
+            signal?.throwIfAborted();
+            return format(result);
+        },
+    });
+}

package/dist/projection-format.d.ts

@@ -0,0 +1,68 @@
+import type { ConversationId, EntryId, TaskId } from '@earendil-works/pi-durable';
+import type { NativeVersion } from './native-version.js';
+export declare const CONVERSATION_PROJECTION_LIMITS: Readonly<{
+    maxMessages: 200;
+    maxMessageBytes: 32768;
+    maxWindowBytes: 196608;
+    maxFrameBytes: 262144;
+}>;
+export interface ProjectionIdentity {
+    readonly runtimeId: string;
+    readonly scopeId: string;
+    readonly principalId: string;
+    readonly conversationId: ConversationId;
+}
+export interface ConversationTextKey {
+    readonly entryId: EntryId;
+    readonly conversationId: ConversationId;
+    readonly messageIndex: number;
+}
+export interface ConversationTextRow extends ConversationTextKey {
+    readonly byTaskId?: TaskId;
+    readonly role: 'user' | 'assistant';
+    readonly content: readonly {
+        readonly blockIndex: number;
+        readonly text: string;
+    }[];
+    readonly clipped: boolean;
+}
+interface ProjectionFrame {
+    readonly schema: 'boring.conversation-text';
+    readonly version: 2;
+    readonly nativeVersion: NativeVersion;
+    readonly source: ProjectionIdentity;
+    /** Ordering within this connection only, never a durable native cursor. */
+    readonly connection: {
+        readonly id: string;
+        readonly frame: number;
+        readonly observedAt: string;
+    };
+    /** Whether older permitted rows were omitted from this window. */
+    readonly window: {
+        readonly truncated: boolean;
+    };
+}
+export interface ConversationTextSnapshot extends ProjectionFrame {
+    readonly kind: 'snapshot';
+    readonly messages: readonly ConversationTextRow[];
+}
+export interface ConversationTextDelta extends ProjectionFrame {
+    readonly kind: 'delta';
+    readonly baseFrame: number;
+    readonly upsert: readonly ConversationTextRow[];
+    /** Complete window order; omitted keys are removed. */
+    readonly order: readonly ConversationTextKey[];
+}
+export type ConversationTextProjection = ConversationTextSnapshot | ConversationTextDelta;
+export declare const projectionEncoder: TextEncoder;
+export declare function projectionBytes(value: unknown): number;
+export declare function projectionKey(key: ConversationTextKey): string;
+export declare function projectionIdentity(value: unknown): value is ProjectionIdentity;
+export interface ConversationTextReceiver {
+    /** Accept one complete JSON frame. A failure clears the cache and requires a fresh initial snapshot. */
+    readonly read: (line: string) => ConversationTextSnapshot;
+    readonly reset: () => void;
+}
+export declare function createConversationTextReceiver(expectedIdentity: ProjectionIdentity): ConversationTextReceiver;
+export {};
+//# sourceMappingURL=projection-format.d.ts.map

package/dist/projection-format.js

@@ -0,0 +1,118 @@
+import { NATIVE_VERSION, isNativeVersion } from './native-version.js';
+export const CONVERSATION_PROJECTION_LIMITS = Object.freeze({
+    maxMessages: 200, maxMessageBytes: 32768, maxWindowBytes: 196608, maxFrameBytes: 262144,
+});
+export const projectionEncoder = new TextEncoder();
+export function projectionBytes(value) {
+    return projectionEncoder.encode(JSON.stringify(value)).byteLength;
+}
+export function projectionKey(key) {
+    return `${key.conversationId}/${key.entryId}/${key.messageIndex}`;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function fields(value, required, optional = []) {
+    return required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+}
+function index(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function id(value) { return index(value) && value > 0; }
+export function projectionIdentity(value) {
+    return record(value) && fields(value, ['runtimeId', 'scopeId', 'principalId', 'conversationId']) && id(value.conversationId)
+        && [value.runtimeId, value.scopeId, value.principalId].every(item => typeof item === 'string' && item.length > 0 && item.length <= 1024);
+}
+function sameSource(a, b) {
+    return a.runtimeId === b.runtimeId && a.scopeId === b.scopeId && a.principalId === b.principalId && a.conversationId === b.conversationId;
+}
+function rowKey(value) {
+    return record(value) && id(value.entryId) && id(value.conversationId) && index(value.messageIndex);
+}
+function row(value) {
+    if (!rowKey(value) || !record(value) || !fields(value, ['entryId', 'conversationId', 'messageIndex', 'role', 'content', 'clipped'], ['byTaskId'])
+        || ('byTaskId' in value && !id(value.byTaskId)) || (value.role !== 'user' && value.role !== 'assistant') || typeof value.clipped !== 'boolean'
+        || !Array.isArray(value.content) || value.content.length === 0 || projectionBytes(value) > CONVERSATION_PROJECTION_LIMITS.maxMessageBytes)
+        return false;
+    let previous = -1;
+    for (const block of value.content) {
+        if (!record(block) || !fields(block, ['blockIndex', 'text']) || !index(block.blockIndex) || block.blockIndex <= previous || typeof block.text !== 'string')
+            return false;
+        previous = block.blockIndex;
+    }
+    return true;
+}
+function rows(value) {
+    return Array.isArray(value) && value.length <= CONVERSATION_PROJECTION_LIMITS.maxMessages && value.every(row)
+        && new Set(value.map(projectionKey)).size === value.length && projectionBytes(value) <= CONVERSATION_PROJECTION_LIMITS.maxWindowBytes;
+}
+function frame(value) {
+    if (!record(value) || value.schema !== 'boring.conversation-text' || value.version !== 2 || !isNativeVersion(value.nativeVersion)
+        || !projectionIdentity(value.source) || !record(value.connection) || !fields(value.connection, ['id', 'frame', 'observedAt'])
+        || typeof value.connection.id !== 'string' || !value.connection.id.length || value.connection.id.length > 128 || !index(value.connection.frame)
+        || typeof value.connection.observedAt !== 'string' || !Number.isFinite(Date.parse(value.connection.observedAt))
+        || !record(value.window) || !fields(value.window, ['truncated']) || typeof value.window.truncated !== 'boolean')
+        return false;
+    const common = ['schema', 'version', 'nativeVersion', 'source', 'connection', 'window', 'kind'];
+    if (value.kind === 'snapshot')
+        return fields(value, [...common, 'messages']) && rows(value.messages);
+    return value.kind === 'delta' && fields(value, [...common, 'baseFrame', 'upsert', 'order']) && index(value.baseFrame) && rows(value.upsert)
+        && Array.isArray(value.order) && value.order.length <= CONVERSATION_PROJECTION_LIMITS.maxMessages
+        && value.order.every(key => rowKey(key) && record(key) && fields(key, ['entryId', 'conversationId', 'messageIndex']))
+        && new Set(value.order.map(projectionKey)).size === value.order.length;
+}
+export function createConversationTextReceiver(expectedIdentity) {
+    if (!projectionIdentity(expectedIdentity))
+        throw new Error('Invalid projection identity');
+    const expected = { ...expectedIdentity };
+    let previous;
+    return {
+        reset: () => { previous = undefined; },
+        read: line => {
+            try {
+                if (typeof line !== 'string' || line.length > CONVERSATION_PROJECTION_LIMITS.maxFrameBytes
+                    || projectionEncoder.encode(line.endsWith('\n') ? line : line + '\n').byteLength > CONVERSATION_PROJECTION_LIMITS.maxFrameBytes)
+                    throw new Error();
+                const value = JSON.parse(line);
+                if (!frame(value) || !sameSource(expected, value.source))
+                    throw new Error();
+                if (previous) {
+                    if (value.connection.id !== previous.connection.id || value.connection.frame !== previous.connection.frame + 1)
+                        throw new Error();
+                }
+                else if (value.kind !== 'snapshot' || value.connection.frame !== 0)
+                    throw new Error();
+                let next;
+                if (value.kind === 'snapshot')
+                    next = value;
+                else {
+                    if (!previous || value.baseFrame !== previous.connection.frame)
+                        throw new Error();
+                    const retained = new Map(previous.messages.map(message => [projectionKey(message), message]));
+                    const ordered = new Set(value.order.map(projectionKey));
+                    for (const message of value.upsert) {
+                        if (!ordered.has(projectionKey(message)))
+                            throw new Error();
+                        retained.set(projectionKey(message), message);
+                    }
+                    const messages = value.order.map(key => {
+                        const message = retained.get(projectionKey(key));
+                        if (!message)
+                            throw new Error();
+                        return message;
+                    });
+                    if (!rows(messages))
+                        throw new Error();
+                    const { baseFrame: _base, upsert: _upsert, order: _order, ...common } = value;
+                    next = { ...common, kind: 'snapshot', messages };
+                }
+                previous = next;
+                return structuredClone(next);
+            }
+            catch {
+                previous = undefined;
+                throw new Error('Invalid conversation projection; reconnect required');
+            }
+        },
+    };
+}

package/dist/projection-window.d.ts

@@ -0,0 +1,9 @@
+import type { EntryRecord } from '@earendil-works/pi-durable';
+import type { ConversationTextRow, ProjectionIdentity } from './projection-format.js';
+export declare function projectConversationWindow(entries: readonly EntryRecord[], identity: ProjectionIdentity, allowEntry: (identity: ProjectionIdentity, entry: EntryRecord) => boolean): {
+    messages: readonly ConversationTextRow[];
+    window: {
+        truncated: boolean;
+    };
+};
+//# sourceMappingURL=projection-window.d.ts.map