@theoremjs/react 0.0.0-stage → 0.3.1

package/client/embedding-space.js

@@ -0,0 +1,389 @@
+/**
+ * The index as a space: each document a point in a ball, placed by the
+ * three directions its vectors differ most along, each measured in its own
+ * spread so the space is as deep as it is wide. Its direction from the
+ * centre is its direction along those three; its distance is how far it sits
+ * from the index's mean along them, as `r / (r + median)`, scaled so the
+ * farthest document is on the rim: the order of distances is kept, and no
+ * one far document squeezes the rest into the centre. A pair is alike when
+ * its cosine similarity stands out against every other pair in the index:
+ * more than {@link OUTLIER} robust deviations above the median pair. Most
+ * pairs in an index are unrelated, so the median and its deviation say what
+ * unrelated looks like for this model and these documents. Each document is
+ * linked to its nearest neighbour, the one its cosine similarity is highest
+ * with, when that pair is alike. A cluster is documents alike pairs connect,
+ * directly or through each other. Positions are a projection and only
+ * approximate; links and clusters are the vectors' own cosine similarity.
+ *
+ * @module
+ */
+/** Power-iteration rounds per axis; the Gram matrix is small, so this converges well inside it. */
+const ROUNDS = 200;
+/** Where a point lands when the projection says nothing about it. */
+const CENTRE = [0, 0, 0];
+/** How many robust deviations above the median pair a pair must be to count as alike: the usual cut for an outlier. */
+const OUTLIER = 3;
+/** Scales the median absolute deviation to a standard deviation, for normally spread values. */
+const MAD_SCALE = 1.4826;
+function dot(a, b, length) {
+    let sum = 0;
+    for (let i = 0; i < length; i += 1)
+        sum += a[i] * b[i];
+    return sum;
+}
+/** A point's offset from the mean along each axis, in that axis's own spread; 0 along an axis with none. */
+function along(axes, mean, spreads, vector) {
+    const offset = Array.from(vector, (v, d) => v - mean[d]);
+    return [0, 1, 2].map((k) => axes[k] && spreads[k] > 1e-12 ? dot(axes[k], offset, offset.length) / spreads[k] : 0);
+}
+/** Each axis's spread: the root mean square of the documents' offsets along it. */
+function spreadsOf(axes, mean, vectors) {
+    return [0, 1, 2].map((k) => {
+        const axis = axes[k];
+        if (!axis || vectors.length === 0)
+            return 0;
+        const squares = vectors.reduce((sum, v) => {
+            const at = dot(axis, Array.from(v, (x, d) => x - mean[d]), v.length);
+            return sum + at * at;
+        }, 0);
+        return Math.sqrt(squares / vectors.length);
+    });
+}
+/** Coordinates in the axes, drawn into the ball: same direction, distance `r / (r + scale) / reach`. */
+function inBall(point, scale, reach) {
+    const length = Math.hypot(point[0], point[1], point[2]);
+    if (length < 1e-9 || scale <= 0 || reach <= 0)
+        return CENTRE;
+    const radius = length / (length + scale) / reach / length;
+    return [point[0] * radius, point[1] * radius, point[2] * radius];
+}
+/** The documents packed row after row, so the loops over them stay on one typed array. */
+function packed(vectors, dimensions) {
+    const rows = new Float64Array(vectors.length * dimensions);
+    vectors.forEach((vector, i) => {
+        rows.set(vector, i * dimensions);
+    });
+    return rows;
+}
+/** Every document against every other: the raw dot products, once. Yields after each row, so a large index can share the thread. */
+function* gramOf(rows, n, dimensions) {
+    const gram = new Float64Array(n * n);
+    const tail = dimensions - (dimensions % 4);
+    for (let i = 0; i < n; i += 1) {
+        const a = i * dimensions;
+        for (let j = i; j < n; j += 1) {
+            const b = j * dimensions;
+            let s0 = 0;
+            let s1 = 0;
+            let s2 = 0;
+            let s3 = 0;
+            // why: four running sums let the engine pipeline the multiplies; this loop is most of the layout's time.
+            for (let d = 0; d < tail; d += 4) {
+                s0 += rows[a + d] * rows[b + d];
+                s1 += rows[a + d + 1] * rows[b + d + 1];
+                s2 += rows[a + d + 2] * rows[b + d + 2];
+                s3 += rows[a + d + 3] * rows[b + d + 3];
+            }
+            for (let d = tail; d < dimensions; d += 1)
+                s0 += rows[a + d] * rows[b + d];
+            const sum = s0 + s1 + s2 + s3;
+            gram[i * n + j] = sum;
+            gram[j * n + i] = sum;
+        }
+        yield;
+    }
+    return gram;
+}
+/** The same products about the documents' mean, from the raw ones. */
+function centred(gram, n) {
+    const rows = new Float64Array(n);
+    let all = 0;
+    for (let i = 0; i < n; i += 1) {
+        for (let j = 0; j < n; j += 1)
+            rows[i] += gram[i * n + j];
+        rows[i] /= n;
+        all += rows[i];
+    }
+    all /= n;
+    const out = new Float64Array(n * n);
+    for (let i = 0; i < n; i += 1)
+        for (let j = 0; j < n; j += 1)
+            out[i * n + j] = gram[i * n + j] - rows[i] - rows[j] + all;
+    return out;
+}
+/** One power-iteration round: `matrix · vector`, normalised, with its length and how far it moved. */
+function powerRound(matrix, n, vector) {
+    const next = new Float64Array(n);
+    let length = 0;
+    for (let i = 0; i < n; i += 1) {
+        let sum = 0;
+        for (let j = 0; j < n; j += 1)
+            sum += matrix[i * n + j] * vector[j];
+        next[i] = sum;
+        length += sum * sum;
+    }
+    length = Math.sqrt(length);
+    if (length < 1e-12)
+        return { next: vector, length: 0, moved: 0 };
+    let moved = 0;
+    for (let i = 0; i < n; i += 1) {
+        next[i] /= length;
+        moved = Math.max(moved, Math.abs(next[i] - vector[i]));
+    }
+    return { next, length, moved };
+}
+/** Flips a vector so its largest entry is positive. */
+function signed(vector) {
+    let lead = 0;
+    for (let i = 1; i < vector.length; i += 1)
+        if (Math.abs(vector[i]) > Math.abs(vector[lead]))
+            lead = i;
+    return vector[lead] < 0 ? vector.map((v) => -v) : vector;
+}
+/** The largest eigenvector left in a matrix, by power iteration. */
+function* largestEigen(matrix, n, k) {
+    // invariant: a fixed start, so the same documents always draw the same space.
+    let vector = Float64Array.from({ length: n }, (_, i) => 1 + ((i * 7919 + k * 104729) % 97) / 97);
+    let value = 0;
+    for (let round = 0; round < ROUNDS; round += 1) {
+        const step = powerRound(matrix, n, vector);
+        if (step.length === 0)
+            break;
+        value = step.length;
+        vector = step.next;
+        if (step.moved < 1e-12)
+            break;
+        yield;
+    }
+    return { vector: signed(vector), value };
+}
+/** The largest eigenvectors of a symmetric matrix, by power iteration with deflation, each signed so its largest entry is positive. */
+function* topEigen(matrix, n, count) {
+    const work = Float64Array.from(matrix);
+    const found = [];
+    const scale = Math.max(...Array.from({ length: n }, (_, i) => Math.abs(work[i * n + i])), 0);
+    for (let k = 0; k < Math.min(count, n); k += 1) {
+        const { vector, value } = yield* largestEigen(work, n, k);
+        if (value <= scale * 1e-9)
+            break;
+        found.push({ vector, value });
+        for (let i = 0; i < n; i += 1)
+            for (let j = 0; j < n; j += 1)
+                work[i * n + j] -= value * vector[i] * vector[j];
+    }
+    return found;
+}
+function meanOf(rows, n, dimensions) {
+    const mean = new Float64Array(dimensions);
+    for (let i = 0; i < n; i += 1)
+        for (let d = 0; d < dimensions; d += 1)
+            mean[d] += rows[i * dimensions + d];
+    for (let d = 0; d < dimensions; d += 1)
+        mean[d] /= Math.max(n, 1);
+    return mean;
+}
+/** One axis in the vectors' own space: the documents weighted by an eigenvector of their Gram matrix. */
+function axisOf(rows, mean, weights) {
+    const dimensions = mean.length;
+    const axis = new Float64Array(dimensions);
+    for (let i = 0; i < weights.length; i += 1)
+        for (let d = 0; d < dimensions; d += 1)
+            axis[d] += weights[i] * (rows[i * dimensions + d] - mean[d]);
+    let length = 0;
+    for (let d = 0; d < dimensions; d += 1)
+        length += axis[d] * axis[d];
+    length = Math.sqrt(length);
+    if (length > 0)
+        for (let d = 0; d < dimensions; d += 1)
+            axis[d] /= length;
+    return axis;
+}
+/** Every pair's cosine similarity, from the raw products. */
+function cosineOf(gram, n) {
+    const norms = Array.from({ length: n }, (_, i) => Math.sqrt(Math.max(gram[i * n + i], 0)));
+    const cosine = new Float64Array(n * n);
+    for (let i = 0; i < n; i += 1)
+        for (let j = 0; j < n; j += 1)
+            cosine[i * n + j] =
+                norms[i] === 0 || norms[j] === 0 ? 0 : gram[i * n + j] / (norms[i] * norms[j]);
+    return cosine;
+}
+/** The median of some values; it sorts them. */
+function medianOf(values) {
+    values.sort();
+    const middle = values.length >> 1;
+    return values.length % 2 ? values[middle] : (values[middle - 1] + values[middle]) / 2;
+}
+/**
+ * The similarity one must pass to stand out among `similarities`: their
+ * median plus {@link OUTLIER} robust deviations. `Infinity` when they have no
+ * spread, since then nothing stands out.
+ */
+export function outlierThreshold(similarities) {
+    const values = Float64Array.from(similarities);
+    if (values.length === 0)
+        return Infinity;
+    const median = medianOf(values.slice());
+    const deviation = MAD_SCALE * medianOf(values.map((v) => Math.abs(v - median)));
+    return deviation > 0 ? median + OUTLIER * deviation : Infinity;
+}
+/** Every pair's similarity, once each. */
+function pairsOf(cosine, n) {
+    const pairs = new Float64Array((n * (n - 1)) / 2);
+    let at = 0;
+    for (let i = 0; i < n; i += 1)
+        for (let j = i + 1; j < n; j += 1)
+            pairs[at++] = cosine[i * n + j];
+    return pairs;
+}
+/** Every pair above the threshold, a row at a time: what clusters are made of. */
+function* linksOf(cosine, n, threshold) {
+    const links = [];
+    for (let i = 0; i < n; i += 1) {
+        for (let j = i + 1; j < n; j += 1)
+            if (cosine[i * n + j] > threshold)
+                links.push({ a: i, b: j, similarity: cosine[i * n + j] });
+        yield;
+    }
+    return links;
+}
+/** The document whose cosine similarity with `i` is highest, the first on a tie; -1 when there is no other. */
+function nearestTo(cosine, n, i) {
+    let best = -1;
+    for (let j = 0; j < n; j += 1)
+        if (j !== i && (best < 0 || cosine[i * n + j] > cosine[i * n + best]))
+            best = j;
+    return best;
+}
+/** Each document's nearest neighbour where that pair passes the threshold, each pair once, a row at a time. */
+function* nearestOf(cosine, n, threshold) {
+    const seen = new Set();
+    const links = [];
+    for (let i = 0; i < n; i += 1) {
+        const best = nearestTo(cosine, n, i);
+        const [a, b] = i < best ? [i, best] : [best, i];
+        if (best >= 0 && cosine[i * n + best] > threshold && !seen.has(a * n + b)) {
+            seen.add(a * n + b);
+            links.push({ a, b, similarity: cosine[i * n + best] });
+        }
+        yield;
+    }
+    return links.sort((x, y) => x.a - y.a || x.b - y.b);
+}
+/** The groups the links connect, each in document order. */
+function groupsOf(n, links) {
+    const root = Array.from({ length: n }, (_, i) => i);
+    const find = (i) => {
+        while (root[i] !== i) {
+            root[i] = root[root[i]];
+            i = root[i];
+        }
+        return i;
+    };
+    for (const link of links)
+        root[find(link.a)] = find(link.b);
+    const groups = new Map();
+    for (let i = 0; i < n; i += 1) {
+        const top = find(i);
+        const group = groups.get(top);
+        if (group)
+            group.push(i);
+        else
+            groups.set(top, [i]);
+    }
+    return [...groups.values()];
+}
+/** The mean of some rows. */
+function meanOfRows(rows, members, dimensions) {
+    const mean = new Array(dimensions).fill(0);
+    for (const i of members)
+        for (let d = 0; d < dimensions; d += 1)
+            mean[d] += rows[i * dimensions + d];
+    return mean.map((v) => v / Math.max(members.length, 1));
+}
+/** A position's hue: its angle around the space's two widest directions, from 0 to 1. */
+function toneOf(position) {
+    return (Math.atan2(position[1], position[0]) / (2 * Math.PI) + 1) % 1;
+}
+/**
+ * The layout, a slice at a time. Vectors whose width differs from the first
+ * are placed at the centre, each a cluster of its own.
+ */
+function* layoutSteps(vectors) {
+    const dimensions = vectors[0]?.length ?? 0;
+    const original = vectors.flatMap((vector, i) => (vector.length === dimensions ? [i] : []));
+    const n = original.length;
+    const rows = packed(original.map((i) => vectors[i]), dimensions);
+    const mean = meanOf(rows, n, dimensions);
+    const gram = yield* gramOf(rows, n, dimensions);
+    const axes = (yield* topEigen(centred(gram, n), n, 3)).map(({ vector }) => axisOf(rows, mean, vector));
+    const kept = original.map((i) => vectors[i]);
+    const spreads = spreadsOf(axes, mean, kept);
+    const coordinates = kept.map((vector) => along(axes, mean, spreads, vector));
+    const lengths = Float64Array.from(coordinates, (p) => Math.hypot(p[0], p[1], p[2]));
+    // why: when more than half sit at the mean, the farthest sets the scale, so the rest still spread out.
+    const median = n > 0 ? medianOf(lengths.slice()) : 0;
+    const scale = median > 1e-9 ? median : lengths.reduce((most, v) => Math.max(most, v), 0);
+    const reach = lengths.reduce((most, r) => Math.max(most, scale > 0 ? r / (r + scale) : 0), 0);
+    const basis = { mean, axes, spreads, scale, reach };
+    const cosine = cosineOf(gram, n);
+    const threshold = outlierThreshold(pairsOf(cosine, n));
+    const found = yield* linksOf(cosine, n, threshold);
+    const groups = groupsOf(n, found);
+    const nearest = yield* nearestOf(cosine, n, threshold);
+    const clusters = groups.map((group) => ({
+        members: group.map((i) => original[i]),
+        tone: toneOf(project(basis, meanOfRows(rows, group, dimensions))),
+    }));
+    for (const [i, vector] of vectors.entries())
+        if (vector.length !== dimensions)
+            clusters.push({ members: [i], tone: toneOf(CENTRE) });
+    const clusterOf = new Map(clusters.flatMap((c, k) => c.members.map((i) => [i, k])));
+    const documents = vectors.map((vector, index) => ({
+        index,
+        // invariant: documents and queries go through the one projection, so a query lands on its own document.
+        position: vector.length === dimensions ? project(basis, vector) : CENTRE,
+        cluster: clusterOf.get(index) ?? 0,
+    }));
+    const links = nearest.map((link) => ({ ...link, a: original[link.a], b: original[link.b] }));
+    return { documents, clusters, links, threshold, basis, dimensions };
+}
+/** The space for a set of document vectors, all at once. */
+export function layoutSpace(vectors) {
+    const steps = layoutSteps(vectors);
+    for (;;) {
+        const step = steps.next();
+        if (step.done)
+            return step.value;
+    }
+}
+/** Time the layout works before it lets the page go on, in milliseconds. */
+const SLICE_MS = 8;
+/**
+ * The same space, laid out in slices between which the page goes on, so a
+ * large index never freezes it. Rejects with the signal's reason once aborted.
+ */
+export async function layoutSpaceSoon(vectors, signal) {
+    const steps = layoutSteps(vectors);
+    for (;;) {
+        const until = performance.now() + SLICE_MS;
+        for (;;) {
+            const step = steps.next();
+            if (step.done)
+                return step.value;
+            if (performance.now() >= until)
+                break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        signal?.throwIfAborted();
+    }
+}
+/** Where a query lands in the space: projected along the same directions as the documents. `null` when its width differs. */
+export function placeQuery(space, query) {
+    if (query.length !== space.dimensions || space.dimensions === 0)
+        return null;
+    return project(space.basis, query);
+}
+function project(basis, vector) {
+    return inBall(along(basis.axes, basis.mean, basis.spreads, vector), basis.scale, basis.reach);
+}

package/client/embedding-transport.d.ts

@@ -0,0 +1,40 @@
+import { type EmbeddingInput, type EmbeddingProfile, type EmbeddingResult, type EmbeddingRules, type EmbeddingTask, type Protocol, type TraceRecord } from '@theoremjs/agents';
+import type { TraceFeed } from './trace-feed.ts';
+import { type HttpOptions } from './transport.ts';
+export type EmbeddingInterface = {
+    type: 'embedding';
+    identity: {
+        handle: string;
+    };
+    /** The profile's inputs held to what its default model takes. */
+    inputs: EmbeddingRules;
+    observability?: {
+        record: boolean;
+    };
+};
+/**
+ * The interface a client reads: the profile's inputs held to its default model's limits. Pass
+ * `protocols` when a model speaks a protocol of your own.
+ */
+export declare function embeddingInterface(profile: Pick<EmbeddingProfile, 'identity' | 'inputs' | 'observability' | 'models' | 'defaultModel'>, protocols?: readonly Protocol[]): EmbeddingInterface;
+export type EmbeddingReply = {
+    result: EmbeddingResult;
+    traces?: TraceRecord[];
+};
+/** What an embedding asks beyond its inputs: a named model, and what the inputs are for. */
+export type EmbedOptions = {
+    model?: string;
+    task?: EmbeddingTask;
+};
+export interface EmbeddingTransport {
+    describe(signal?: AbortSignal): Promise<EmbeddingInterface>;
+    embed(input: EmbeddingInput | readonly EmbeddingInput[], options?: EmbedOptions, signal?: AbortSignal): Promise<EmbeddingReply>;
+    traces?: TraceFeed;
+}
+export declare function readEmbeddingReply(raw: unknown): EmbeddingReply;
+/** POSTs an embedding and reads its reply; a failure keeps the trace records its body carried. */
+export declare function postEmbedding(url: string, body: unknown, signal: AbortSignal | undefined, options?: HttpOptions): Promise<EmbeddingReply>;
+/** Transport for a host mounted with `createTheoremEmbeddingHandler`. Default endpoint `/api/embedding`. */
+export declare function createEmbeddingTransport(options?: HttpOptions & {
+    endpoint?: string;
+}): EmbeddingTransport;

package/client/embedding-transport.js

@@ -0,0 +1,71 @@
+import { embeddingModelLimits, embeddingRules, resolveObservabilityPolicy, traceRecordSchema, z, } from '@theoremjs/agents';
+import { postWithTraces } from "./decision-transport.js";
+import { fetchJson } from "./transport.js";
+import { checkWire } from "./wire-line.js";
+/**
+ * The interface a client reads: the profile's inputs held to its default model's limits. Pass
+ * `protocols` when a model speaks a protocol of your own.
+ */
+export function embeddingInterface(profile, protocols = []) {
+    const binding = profile.models[profile.defaultModel];
+    return {
+        type: 'embedding',
+        identity: { handle: profile.identity.handle },
+        inputs: embeddingRules(profile.inputs, binding ? embeddingModelLimits(binding, protocols) : undefined),
+        ...(profile.observability
+            ? { observability: { record: resolveObservabilityPolicy(profile.observability).record } }
+            : {}),
+    };
+}
+const embeddingReplySchema = z.object({
+    result: z.object({
+        model: z.string().min(1),
+        embeddings: z.array(z
+            .object({
+            index: z.number().int().nonnegative(),
+            values: z.array(z.number()),
+            dimensions: z.number().int().positive(),
+        })
+            .refine((embedding) => embedding.values.length === embedding.dimensions, 'vector length must match dimensions')),
+        usage: z
+            .object({
+            inputTokens: z.number().int().nonnegative().optional(),
+            costUsd: z.number().nonnegative().optional(),
+            estimated: z.literal(true).optional(),
+        })
+            .optional(),
+    }),
+    traces: z.array(traceRecordSchema).optional(),
+});
+const describedSchema = z.object({
+    interface: z.object({
+        type: z.literal('embedding'),
+        identity: z.object({ handle: z.string() }),
+        inputs: z.object({
+            text: z.boolean(),
+            attachments: z.object({ accept: z.array(z.string()) }).optional(),
+            maxFiles: z.number().optional(),
+            maxBytes: z.number().optional(),
+            maxTurnBytes: z.number().optional(),
+            limitsByMime: z.record(z.string(), z.number()).optional(),
+        }),
+        observability: z.object({ record: z.boolean() }).optional(),
+    }),
+});
+export function readEmbeddingReply(raw) {
+    return checkWire(embeddingReplySchema, raw, 'the embedding');
+}
+/** POSTs an embedding and reads its reply; a failure keeps the trace records its body carried. */
+export function postEmbedding(url, body, signal, options = {}) {
+    return postWithTraces(url, body, signal, options, readEmbeddingReply);
+}
+/** Transport for a host mounted with `createTheoremEmbeddingHandler`. Default endpoint `/api/embedding`. */
+export function createEmbeddingTransport(options = {}) {
+    const base = (options.endpoint ?? '/api/embedding').replace(/\/$/, '');
+    return {
+        async describe(signal) {
+            return checkWire(describedSchema, await fetchJson(base, { signal }, options), 'the embedding description').interface;
+        },
+        embed: (input, embed, signal) => postEmbedding(`${base}/embed`, { input, ...embed }, signal, options),
+    };
+}

package/client/encode-composer-draft.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Encode composer fields into a serializable `UserTurnDraft` for pending intents.
+ */
+import type { UserTurnDraft } from '@theoremjs/agents/interface';
+export declare function encodeComposerDraft(args: {
+    text: string;
+    pendingFiles?: readonly File[];
+    pendingVoice?: readonly File[];
+}): Promise<UserTurnDraft>;

package/client/encode-composer-draft.js

@@ -0,0 +1,34 @@
+/**
+ * Encode composer fields into a serializable `UserTurnDraft` for pending intents.
+ */
+import { encodeFiles } from "./encode-files.js";
+export async function encodeComposerDraft(args) {
+    const text = args.text.trim();
+    const files = args.pendingFiles ?? [];
+    const voice = args.pendingVoice ?? [];
+    const encodedFiles = files.length ? await encodeFiles(files) : [];
+    const encodedVoice = voice.length ? await encodeFiles(voice) : [];
+    return {
+        ...(text ? { text } : {}),
+        ...(encodedFiles.length
+            ? {
+                attachments: encodedFiles.map((blob, index) => ({
+                    name: blob.name,
+                    mimeType: blob.mimeType,
+                    sizeBytes: files[index]?.size ?? 0,
+                    data: blob.data,
+                })),
+            }
+            : {}),
+        ...(encodedVoice.length
+            ? {
+                voice: encodedVoice.map((blob, index) => ({
+                    name: blob.name,
+                    mimeType: blob.mimeType,
+                    sizeBytes: voice[index]?.size ?? 0,
+                    data: blob.data,
+                })),
+            }
+            : {}),
+    };
+}

package/client/encode-files.d.ts

@@ -0,0 +1,18 @@
+import type { PendingAttachment, TranscriptBlock } from '@theoremjs/agents/interface';
+export declare function filesToPending(files: readonly File[]): PendingAttachment[];
+/**
+ * Rebuild `File`s from encoded pending attachments (stash / queue restore).
+ * Attachments without `data` cannot be restored and are skipped.
+ */
+export declare function pendingAttachmentsToFiles(attachments: readonly PendingAttachment[]): File[];
+export declare function encodeFiles(files: readonly File[]): Promise<Array<{
+    name: string;
+    mimeType: string;
+    data: string;
+}>>;
+/** Copy encoded base64 onto matching user attachment/voice transcript blocks for UI preview. */
+export declare function attachPreviewData(blocks: readonly TranscriptBlock[], attachments?: ReadonlyArray<{
+    data: string;
+}>, voice?: ReadonlyArray<{
+    data: string;
+}>): TranscriptBlock[];

package/client/encode-files.js

@@ -0,0 +1,54 @@
+import { base64ToBytes, bytesToBase64 } from '@theoremjs/agents/kernel';
+export function filesToPending(files) {
+    return files.map((file) => ({
+        name: file.name,
+        mimeType: file.type || 'application/octet-stream',
+        sizeBytes: file.size,
+    }));
+}
+/**
+ * Rebuild `File`s from encoded pending attachments (stash / queue restore).
+ * Attachments without `data` cannot be restored and are skipped.
+ */
+export function pendingAttachmentsToFiles(attachments) {
+    const files = [];
+    for (const attachment of attachments) {
+        if (typeof attachment.data !== 'string' || attachment.data.length === 0)
+            continue;
+        const bytes = base64ToBytes(attachment.data);
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        files.push(new File([buffer], attachment.name, {
+            type: attachment.mimeType || 'application/octet-stream',
+        }));
+    }
+    return files;
+}
+export async function encodeFiles(files) {
+    const out = [];
+    for (const file of files) {
+        out.push({
+            name: file.name,
+            mimeType: file.type || 'application/octet-stream',
+            data: bytesToBase64(new Uint8Array(await file.arrayBuffer())),
+        });
+    }
+    return out;
+}
+/** Copy encoded base64 onto matching user attachment/voice transcript blocks for UI preview. */
+export function attachPreviewData(blocks, attachments, voice) {
+    let attachmentIndex = 0;
+    let voiceIndex = 0;
+    return blocks.map((block) => {
+        if (block.kind === 'user-attachment') {
+            const data = attachments?.[attachmentIndex]?.data;
+            attachmentIndex += 1;
+            return data !== undefined ? { ...block, data } : block;
+        }
+        if (block.kind === 'user-voice') {
+            const data = voice?.[voiceIndex]?.data;
+            voiceIndex += 1;
+            return data !== undefined ? { ...block, data } : block;
+        }
+        return block;
+    });
+}

package/client/failure.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One failure, two worlds, in the browser: the builder reads `errorKind` and
+ * `errorInternal`; the user reads `error`, the profile's wording for it.
+ *
+ * @module
+ */
+import { type ErrorKind, type LabelOverrides } from '@theoremjs/agents';
+import type { AttachmentValidationIssue } from '@theoremjs/agents/interface';
+export type ClientFailure = {
+    /** What the user reads: the host's wording, else the profile labels' for the failure. */
+    error: string;
+    errorKind: ErrorKind;
+    /** Raw detail for the builder; never shown to the user. */
+    errorInternal?: string;
+};
+/**
+ * Word a caught value for the user with the profile's `labels` (the interface's
+ * `labels`). A host-reported failure keeps the host's wording.
+ */
+export declare function clientFailure(err: unknown, labels?: LabelOverrides): ClientFailure;
+/** A turn that did not run or did not finish. */
+export type TurnFailure = ClientFailure & {
+    /** The files the profile refused, one entry per reason (the kernel's check). */
+    issues?: AttachmentValidationIssue[];
+    /** The user stopped it; nothing to show. */
+    aborted?: boolean;
+};
+/** A caught value as a turn failure; an aborted `signal` marks it the user's stop. */
+export declare function turnFailure(err: unknown, labels?: LabelOverrides, signal?: AbortSignal): TurnFailure;

package/client/failure.js

@@ -0,0 +1,34 @@
+/**
+ * One failure, two worlds, in the browser: the builder reads `errorKind` and
+ * `errorInternal`; the user reads `error`, the profile's wording for it.
+ *
+ * @module
+ */
+import { describeError, errorKind, labelText, publicError, } from '@theoremjs/agents';
+import { isTheoremStreamError } from "./transport.js";
+/**
+ * Word a caught value for the user with the profile's `labels` (the interface's
+ * `labels`). A host-reported failure keeps the host's wording.
+ */
+export function clientFailure(err, labels) {
+    if (isTheoremStreamError(err)) {
+        return {
+            error: err.publicMessage ?? labelText(`error.${err.kind}`, {}, labels),
+            errorKind: err.kind,
+            ...(err.internalMessage ? { errorInternal: err.internalMessage } : {}),
+        };
+    }
+    const error = publicError(err, labels);
+    const internal = describeError(err);
+    return {
+        error,
+        errorKind: errorKind(err),
+        ...(internal && internal !== error ? { errorInternal: internal } : {}),
+    };
+}
+/** A caught value as a turn failure; an aborted `signal` marks it the user's stop. */
+export function turnFailure(err, labels, signal) {
+    const failure = clientFailure(err, labels);
+    const aborted = failure.errorKind === 'cancelled' || signal?.aborted === true;
+    return { ...failure, ...(aborted ? { aborted: true } : {}) };
+}