@theoremjs/react 0.3.0 → 0.3.1

package/client/run-session.js

@@ -1,75 +1,91 @@
-import { applyTurnEventsToSession, gatedToolFromEvents, } from '@theoremjs/agents/interface';
 import { attachmentsRefused, TheoremError } from '@theoremjs/agents';
+import { gatedToolsFromEvents, settlesToolCall, } from '@theoremjs/agents/interface';
 import { attachPreviewData, encodeFiles } from "./encode-files.js";
 import { turnFailure } from "./failure.js";
-import { continueAfterTool, failGateAnswer, failTurnStream, finalizeTurnStream, stampWorked, streamFoldedTurn, toTurnMedia, } from "./run-commit.js";
+import { streamFoldedTurn } from "./run-commit.js";
 import { continueGatedToolInvocation } from "./tool-resume.js";
-import { walkAwayFrom } from "./walk-away.js";
-import { buildInvokeRequest, buildTurnRequest, foldAssistantTurn, prepareComposerTurn, projectUserTurn, turnInputFromSession, } from "./turn-client.js";
+import { isUnknownConversation, } from "./transport.js";
+import { buildInvokeRequest, buildTurnRequest, foldAssistantTurn, issuedOperationId, prepareComposerTurn, projectUserTurn, } from "./turn-client.js";
+/**
+ * Whether the host keeps this chat's conversation. A stateless profile keeps
+ * none: the page holds its transcript, and nothing goes on from a ref.
+ */
+export function keepsConversation(iface) {
+    return iface.providerContinuation?.history !== 'stateless';
+}
 /**
  * A session state the user can't act from (no gate waiting, a gate without a
- * call id): the lexicon's line for it, as a turn failure.
+ * call id): the labels' line for it, as a turn failure.
  */
 function sessionFailure(key, iface) {
-    return turnFailure(new TheoremError('request', `session state: ${key}`, { copy: { key } }), iface.lexicon);
+    return turnFailure(new TheoremError('request', `session state: ${key}`, { copy: { key } }), iface.labels);
 }
-function sessionHasGatedTool(session) {
-    return session.gatedTool !== null;
+/** A run that never went out: nothing streamed, and the message did not post. */
+function unsent(session, failure) {
+    return { session, events: [], posted: false, failure };
 }
-async function streamPreparedInterfaceTurn(args) {
-    const media = toTurnMedia(args.encodedAttachments, args.encodedVoice);
+async function streamPreparedTurn(args) {
+    const keeps = keepsConversation(args.iface);
     const userBlocks = attachPreviewData(args.prepared.blocks, args.encodedAttachments, args.encodedVoice);
-    const { walking } = args;
-    const sent = walking ? { ...args.session, history: walking.history } : args.session;
-    const input = turnInputFromSession(sent, {
+    const paused = args.session.assistantEvents;
+    const walking = args.session.gatedTool !== null;
+    const request = buildTurnRequest(args.iface, args.session, {
         ...(args.prepared.draft.text ? { text: args.prepared.draft.text } : {}),
         ...(args.encodedAttachments?.length ? { attachments: args.encodedAttachments } : {}),
         ...(args.encodedVoice?.length ? { voice: args.encodedVoice } : {}),
+    }, {
+        ...args.scope,
+        ...(walking ? { walkAway: { calls: gatedToolsFromEvents(paused) } } : {}),
     });
-    const request = buildTurnRequest(args.iface, args.session, input, {
-        turnId: args.turnId,
-        ...(walking ? { walkAway: walking.request } : {}),
-    });
-    // The message's reply starts from the conversation as it stands when the message posts.
-    const posted = (base) => ({
-        ...base,
-        pendingUserDraft: args.prepared.draft,
-        assistantEvents: [],
-    });
-    let session = posted(args.session);
-    // Walking away, the message posts once the paused reply has settled, after it.
-    let posts = walking ? [] : userBlocks;
+    // why: Walking away, the stream settles the paused reply first; once the message posts, the events are the new reply's.
+    const events = walking ? [...paused] : [];
+    let posted = !keeps;
     if (!walking)
-        args.onUserBlocks?.(userBlocks);
-    const events = [];
+        args.onUserBlocks(userBlocks);
+    const onConversation = (line) => {
+        if (!line.posted)
+            return;
+        posted = true;
+        if (walking) {
+            args.onUserBlocks([...foldAssistantTurn(args.iface, events), ...userBlocks]);
+            events.length = 0;
+        }
+    };
+    const send = (body) => streamFoldedTurn({
+        iface: args.iface,
+        view: args.view,
+        events,
+        onConversation,
+        stream: (onLine) => args.transport.turn(body, onLine, args.signal),
+    });
     try {
-        await streamFoldedTurn({
-            iface: args.iface,
-            view: args.view,
-            events,
-            stream: (onEvent) => args.transport.turn(request, walking
-                ? walking.sink(onEvent, (walked) => {
-                    session = posted(walked.session);
-                    posts = [...walked.blocks, ...userBlocks];
-                    args.onUserBlocks?.(posts);
-                })
-                : onEvent, args.signal),
-        });
+        try {
+            await send(request);
+        }
+        catch (err) {
+            if (!args.transcript || request.conversation === undefined || !isUnknownConversation(err))
+                throw err;
+            // why: The host lost the conversation before the message posted; it goes on from the page's copy, once. The lost reply's waiting calls went with it.
+            const { abandon: _lost, ...rest } = request;
+            await send({ ...rest, transcript: [...args.transcript] });
+        }
     }
     catch (err) {
-        const failure = turnFailure(err, args.iface.lexicon, args.signal);
-        // A message that never posted leaves the paused reply waiting as it was.
-        if (walking && !walking.settled())
-            return failure;
-        return failTurnStream({ session, events, media, failure });
+        return {
+            session: args.session,
+            // why: A walk that failed before the message posted leaves no reply of its own; the host's view is the truth.
+            events: posted ? events : [],
+            posted,
+            failure: turnFailure(err, args.iface.labels, args.signal),
+        };
     }
-    session = finalizeTurnStream({ session, events, media });
-    return {
-        ok: true,
-        session,
-        userBlocks: posts,
-        assistantBlocks: foldAssistantTurn(args.iface, events),
-    };
+    if (!posted) {
+        // why: A host that keeps the conversation posts the message or fails; a stream that ends without either is the host's fault.
+        return unsent(args.session, turnFailure(
+        // labels-exempt: internal diagnostic; the user reads error.internal
+        new TheoremError('internal', 'the reply ended without posting the message'), args.iface.labels));
+    }
+    return { session: args.session, events, posted };
 }
 function extractInlineEncodedAttachments(attachments) {
     const filtered = attachments
@@ -78,31 +94,26 @@ function extractInlineEncodedAttachments(attachments) {
     return filtered && filtered.length > 0 ? filtered : undefined;
 }
 async function runPreparedTurnStream(args) {
-    const gated = sessionHasGatedTool(args.session);
-    if (gated && !args.walkAway)
-        return sessionFailure('session.gate_pending', args.iface);
-    const walking = gated && args.walkAway ? walkAwayFrom(args.iface, args.session, args.walkAway.workedMs) : undefined;
+    if (args.session.gatedTool !== null && (!args.walkAway || !keepsConversation(args.iface))) {
+        return unsent(args.session, sessionFailure('session.gate_pending', args.iface));
+    }
     try {
         const outcome = await args.prepare();
         if (!outcome.ok) {
-            return { ...turnFailure(attachmentsRefused(outcome.issues), args.iface.lexicon), issues: outcome.issues };
+            return unsent(args.session, {
+                ...turnFailure(attachmentsRefused(outcome.issues), args.iface.labels),
+                issues: outcome.issues,
+            });
         }
-        return await streamPreparedInterfaceTurn({
-            iface: args.iface,
-            transport: args.transport,
-            session: args.session,
+        return await streamPreparedTurn({
+            ...args,
             prepared: outcome.prepared,
-            encodedAttachments: outcome.encodedAttachments,
-            encodedVoice: outcome.encodedVoice,
-            view: args.view,
-            onUserBlocks: args.onUserBlocks,
-            signal: args.signal,
-            turnId: args.turnId,
-            ...(walking ? { walking } : {}),
+            ...(outcome.encodedAttachments ? { encodedAttachments: outcome.encodedAttachments } : {}),
+            ...(outcome.encodedVoice ? { encodedVoice: outcome.encodedVoice } : {}),
         });
     }
     catch (err) {
-        return turnFailure(err, args.iface.lexicon, args.signal);
+        return unsent(args.session, turnFailure(err, args.iface.labels, args.signal));
     }
 }
 export async function streamInterfaceTurn(args) {
@@ -140,76 +151,57 @@ export async function streamInterfaceDraftTurn(args) {
         },
     });
 }
-/**
- * After one gate settles: wait on the step's next gate if one is left, else
- * send the whole step back to the model.
- */
-async function continueOnceSettled(args) {
-    const gatedTool = gatedToolFromEvents(args.events);
-    const session = { ...args.session, gatedTool, assistantEvents: args.events };
-    if (gatedTool) {
-        return { ok: true, session, assistantBlocks: foldAssistantTurn(args.iface, args.events) };
-    }
-    return await continueAfterTool({ ...args, session, seedEvents: args.events });
-}
 /**
  * Send the user's answer to the gate the session waits on. The host settles
- * the call either way (an approval runs it; a refusal records it declined),
- * so the model and the trace read what the user chose.
+ * the call either way (an approval runs it; a refusal records it declined), so
+ * the model and the trace read what the user chose. A host that keeps the
+ * conversation goes on with the reply in the same stream once no call waits.
  */
 export async function resumeInterfaceTool(args) {
     const gated = args.session.gatedTool;
     if (!gated?.callId)
-        return sessionFailure('session.gate_expired', args.iface);
+        return unsent(args.session, sessionFailure('session.gate_expired', args.iface));
     const reply = continueGatedToolInvocation({
         toolName: gated.name,
         gate: gated,
         sessionPermissions: args.session.sessionPermissions,
         resolution: args.resolution,
     });
-    const sessionPermissions = reply.decision === 'approve' ? reply.sessionPermissions : args.session.sessionPermissions;
-    // Seeded with the paused reply, and filled as the answer streams, so a failed answer keeps what it delivered.
+    const session = {
+        ...args.session,
+        sessionPermissions: reply.decision === 'approve' ? reply.sessionPermissions : args.session.sessionPermissions,
+    };
+    // why: Seeded with the paused reply, and filled as the answer streams, so a failed answer keeps what it delivered.
     const events = [...args.session.assistantEvents];
     try {
         await streamFoldedTurn({
             iface: args.iface,
             view: args.view,
             events,
-            stream: (onEvent) => args.transport.invoke(buildInvokeRequest(args.iface, args.session, {
+            stream: (onLine) => args.transport.invoke(buildInvokeRequest(args.iface, args.session, {
                 gateId: gated.callId,
+                operationId: issuedOperationId(gated),
                 decision: reply.decision,
                 name: gated.name,
                 input: gated.arguments,
-                sessionPermissions,
-                ...(reply.decision === 'approve' && reply.secret !== undefined ? { secret: reply.secret } : {}),
-            }), onEvent),
+                sessionPermissions: session.sessionPermissions,
+                ...(reply.decision === 'approve' && reply.secret !== undefined
+                    ? { secret: reply.secret }
+                    : {}),
+                ...(reply.decision === 'approve' && reply.page ? { page: reply.page } : {}),
+            }, args.scope), onLine),
         });
-        const session = { ...applyTurnEventsToSession(args.session, events), sessionPermissions };
-        return await continueOnceSettled({ ...args, session, events });
     }
     catch (err) {
-        return failGateAnswer({
-            session: { ...args.session, sessionPermissions },
-            callId: gated.callId,
-            events,
-            failure: turnFailure(err, args.iface.lexicon),
-        });
-    }
-}
-export function applyTurnResultToTranscript(args) {
-    const session = args.session;
-    const prefix = args.userBlocks?.length ? [...args.blocks, ...args.userBlocks] : args.blocks;
-    const assistantBlocks = args.worked ? stampWorked(args.assistantBlocks, args.worked) : args.assistantBlocks;
-    if (sessionHasGatedTool(session)) {
+        // why: An answer that failed before its call settled leaves the reply waiting as it was; the answer can go again.
+        const answered = events.slice(args.session.assistantEvents.length);
+        const settled = answered.some((event) => settlesToolCall(event, gated.callId));
         return {
-            blocks: prefix,
-            streamBlocks: assistantBlocks,
             session,
+            events: settled ? events : [...args.session.assistantEvents],
+            posted: true,
+            failure: turnFailure(err, args.iface.labels),
         };
     }
-    return {
-        blocks: [...prefix, ...assistantBlocks],
-        streamBlocks: [],
-        session,
-    };
+    return { session, events, posted: true };
 }

package/client/schema-fields.js

@@ -14,7 +14,11 @@ const MAX_SLIDER_STEPS = 100;
 const LONG_TEXT = 120;
 function kindOf(prop) {
     const declared = Array.isArray(prop.type) ? prop.type.find((type) => type !== 'null') : prop.type;
-    if (declared === 'string' || declared === 'number' || declared === 'integer' || declared === 'boolean' || declared === 'array')
+    if (declared === 'string' ||
+        declared === 'number' ||
+        declared === 'integer' ||
+        declared === 'boolean' ||
+        declared === 'array')
         return declared;
     if (declared === 'object' || isRow(prop.properties))
         return 'object';
@@ -27,7 +31,11 @@ function itemsOf(prop) {
 }
 function enumOf(prop) {
     const options = prop?.enum;
-    return Array.isArray(options) && options.length > 0 && options.every((option) => typeof option === 'string') ? options : undefined;
+    return Array.isArray(options) &&
+        options.length > 0 &&
+        options.every((option) => typeof option === 'string')
+        ? options
+        : undefined;
 }
 function numberAt(prop, key) {
     const value = prop[key];
@@ -36,9 +44,18 @@ function numberAt(prop, key) {
 function numberControl(prop, isInteger) {
     const min = numberAt(prop, 'minimum');
     const max = numberAt(prop, 'maximum');
-    if (isInteger && min !== undefined && max !== undefined && max > min && max - min <= MAX_SLIDER_STEPS)
+    if (isInteger &&
+        min !== undefined &&
+        max !== undefined &&
+        max > min &&
+        max - min <= MAX_SLIDER_STEPS)
         return { kind: 'range', min, max };
-    return { kind: 'number', isInteger, ...(min === undefined ? {} : { min }), ...(max === undefined ? {} : { max }) };
+    return {
+        kind: 'number',
+        isInteger,
+        ...(min === undefined ? {} : { min }),
+        ...(max === undefined ? {} : { max }),
+    };
 }
 function textControl(prop) {
     if (prop.format === 'date')
@@ -85,7 +102,9 @@ export function schemaControl(prop) {
     }
 }
 function requiredOf(schema) {
-    return new Set(Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === 'string') : []);
+    return new Set(Array.isArray(schema.required)
+        ? schema.required.filter((key) => typeof key === 'string')
+        : []);
 }
 /** An object schema's fields in the order it declares them, each with its input. */
 export function schemaFields(schema) {
@@ -98,7 +117,9 @@ export function schemaFields(schema) {
             {
                 key,
                 label: typeof prop.title === 'string' && prop.title ? prop.title : humanize(key),
-                ...(typeof prop.description === 'string' && prop.description ? { description: prop.description } : {}),
+                ...(typeof prop.description === 'string' && prop.description
+                    ? { description: prop.description }
+                    : {}),
                 isRequired: required.has(key),
                 control: schemaControl(prop),
             },

package/client/shaped-data.js

@@ -6,14 +6,33 @@
 /** Fields that name a row, in the order they're tried. */
 const TITLE_KEYS = ['name', 'title', 'label', 'headline', 'subject', 'id'];
 /** Fields that place or sort a row, shown as tokens beside its title. */
-const TAG_KEYS = ['country', 'region', 'state', 'admin1', 'city', 'category', 'type', 'kind', 'status'];
+const TAG_KEYS = [
+    'country',
+    'region',
+    'state',
+    'admin1',
+    'city',
+    'category',
+    'type',
+    'kind',
+    'status',
+];
 const MAX_TAGS = 2;
 const MAX_TAG_LENGTH = 24;
 /** Fields that say, in a line, what a row is. */
-const DESCRIPTION_KEYS = ['description', 'summary', 'snippet', 'extract', 'subtitle', 'address', 'display_name', 'text'];
+const DESCRIPTION_KEYS = [
+    'description',
+    'summary',
+    'snippet',
+    'extract',
+    'subtitle',
+    'address',
+    'display_name',
+    'text',
+];
 /** Fields that link a row to its page. */
 const LINK_KEYS = ['url', 'link', 'href'];
-/** Fields a list row shows beyond its name, line, link and tags, at its end. */
+/** Fields a list row shows beyond its name, line, link, and tags, at its end. */
 const MAX_LIST_EXTRAS = 2;
 /** A list of flat objects with at most this many fields reads as a table. */
 const MAX_TABLE_COLUMNS = 6;
@@ -188,7 +207,10 @@ export function titleKey(row) {
 function tags(row, skip) {
     return TAG_KEYS.filter((key) => {
         const value = row[key];
-        return key !== skip && typeof value === 'string' && value.length > 0 && value.length <= MAX_TAG_LENGTH;
+        return (key !== skip &&
+            typeof value === 'string' &&
+            value.length > 0 &&
+            value.length <= MAX_TAG_LENGTH);
     })
         .slice(0, MAX_TAGS)
         .map((key) => row[key]);
@@ -242,7 +264,9 @@ export function columnStore(row) {
         return undefined;
     const lengths = new Set(entries.map(([, value]) => (Array.isArray(value) && value.every(isPlain) ? value.length : -1)));
     const [length] = lengths;
-    return lengths.size === 1 && length !== undefined && length >= 2 ? entries.map(([key]) => key) : undefined;
+    return lengths.size === 1 && length !== undefined && length >= 2
+        ? entries.map(([key]) => key)
+        : undefined;
 }
 /** A column store's lists, turned into rows. */
 export function storeRows(row, columns) {
@@ -264,7 +288,9 @@ function rowShape(row) {
     if (Object.keys(row).length === 0)
         return { kind: 'none' };
     const store = columnStore(row);
-    return store ? { kind: 'table', columns: store, rows: storeRows(row, store) } : { kind: 'fields', row };
+    return store
+        ? { kind: 'table', columns: store, rows: storeRows(row, store) }
+        : { kind: 'fields', row };
 }
 /** How a value (already unpacked) at `depth` is drawn. */
 export function shapeOf(value, depth) {
@@ -286,14 +312,17 @@ function isInline(value) {
         return false;
     if (isPlain(inner))
         return true;
-    return Array.isArray(inner) && inner.length > 0 && inner.length <= MAX_INLINE_TOKENS && inner.every(isPlain);
+    return (Array.isArray(inner) &&
+        inner.length > 0 &&
+        inner.length <= MAX_INLINE_TOKENS &&
+        inner.every(isPlain));
 }
 function section(row, key) {
     const path = [key];
     let inner = unpacked(row[key]);
     let units = unitsOf(row, key);
     while (isRow(inner)) {
-        // A units object beside the one field doesn't count: `{ hourly, hourly_units }` is still a wrapper.
+        // why: A units object beside the one field doesn't count: `{ hourly, hourly_units }` is still a wrapper.
         const entries = shownEntries(inner);
         const only = entries.length === 1 ? entries[0] : undefined;
         if (!only || isPlain(unpacked(only[1])))

package/client/source-citations.js

@@ -19,7 +19,7 @@ function citationFromSource(source, key) {
 }
 /**
  * A source is linked only at an http(s) URL. Sources come from the model and
- * from tool output, so a `javascript:`, `data:` or other scheme never becomes
+ * from tool output, so a `javascript:`, `data:`, or other scheme never becomes
  * a clickable link.
  */
 function webUrl(uri) {

package/client/space-geometry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What the embedding space draws, as flat arrays a GPU takes as they are:
+ * the axes' three circles, each document's dot, a line for each link, heavier
+ * the further its cosine similarity passes the threshold, and a query's white
+ * dot with a line to each match that passes its own.
+ * Every other line joins two real points and stands for their cosine
+ * similarity; nothing is drawn for show.
+ *
+ * @module
+ */
+import type { EmbeddingSpace, SpacePoint } from './embedding-space.ts';
+/**
+ * Floats per line segment: from (3), to (3), colour (3), alpha, width in CSS
+ * pixels, the two slots it reads its state from, where it sits along its line
+ * (0 at the start, 1 at the end), and the gap in CSS pixels it leaves before
+ * its start and after its end, where a dot sits.
+ */
+export declare const SEGMENT_FLOATS = 16;
+/** Floats per dot: position (3), colour (3), alpha, radius in CSS pixels, its slot, and where it sits along the line that reaches it. */
+export declare const DOT_FLOATS = 10;
+/** Stands for the query where a slot would go. */
+export declare const QUERY_SLOT = -1;
+/** Stands for the axes' circles, which no document's state reaches. */
+export declare const FRAME_SLOT = -2;
+/** Line segments and dots, packed as {@link SEGMENT_FLOATS} and {@link DOT_FLOATS} describe. */
+export type SpaceGeometry = {
+    segments: Float32Array;
+    dots: Float32Array;
+};
+/** Everything a space draws before any query: the axes' circles, a line for each link, then every document's dot. */
+export declare function spaceGeometry(space: EmbeddingSpace): SpaceGeometry;
+/** A match the query is joined to. */
+export type QueryMatch = {
+    index: number;
+    /** How far its similarity passes the threshold it stood out against, from 0 at it to 1 at identical. */
+    closeness: number;
+};
+/** A query's white dot where it landed, and a line from it to each match, weighted as a link is. */
+export declare function queryGeometry(space: EmbeddingSpace, at: SpacePoint, matches: readonly QueryMatch[]): SpaceGeometry;