@theoremjs/react 0.0.0-stage → 0.3.1

package/client/run-session.js

@@ -0,0 +1,207 @@
+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 { streamFoldedTurn } from "./run-commit.js";
+import { continueGatedToolInvocation } from "./tool-resume.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 labels' line for it, as a turn failure.
+ */
+function sessionFailure(key, iface) {
+    return turnFailure(new TheoremError('request', `session state: ${key}`, { copy: { key } }), iface.labels);
+}
+/** 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 streamPreparedTurn(args) {
+    const keeps = keepsConversation(args.iface);
+    const userBlocks = attachPreviewData(args.prepared.blocks, args.encodedAttachments, args.encodedVoice);
+    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) } } : {}),
+    });
+    // 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 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 {
+        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) {
+        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),
+        };
+    }
+    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
+        ?.filter((a) => typeof a.data === 'string')
+        .map((a) => ({ name: a.name, mimeType: a.mimeType, data: a.data }));
+    return filtered && filtered.length > 0 ? filtered : undefined;
+}
+async function runPreparedTurnStream(args) {
+    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 unsent(args.session, {
+                ...turnFailure(attachmentsRefused(outcome.issues), args.iface.labels),
+                issues: outcome.issues,
+            });
+        }
+        return await streamPreparedTurn({
+            ...args,
+            prepared: outcome.prepared,
+            ...(outcome.encodedAttachments ? { encodedAttachments: outcome.encodedAttachments } : {}),
+            ...(outcome.encodedVoice ? { encodedVoice: outcome.encodedVoice } : {}),
+        });
+    }
+    catch (err) {
+        return unsent(args.session, turnFailure(err, args.iface.labels, args.signal));
+    }
+}
+export async function streamInterfaceTurn(args) {
+    return await runPreparedTurnStream({
+        ...args,
+        prepare: async () => {
+            const prepared = prepareComposerTurn(args.iface, args.text, args.pendingFiles, args.pendingVoice);
+            if (!prepared.ok)
+                return prepared;
+            return {
+                ok: true,
+                prepared,
+                encodedAttachments: args.pendingFiles.length
+                    ? await encodeFiles(args.pendingFiles)
+                    : undefined,
+                encodedVoice: args.pendingVoice.length ? await encodeFiles(args.pendingVoice) : undefined,
+            };
+        },
+    });
+}
+/** Send a turn from an already-encoded pending draft (queue drain / send now). */
+export async function streamInterfaceDraftTurn(args) {
+    return await runPreparedTurnStream({
+        ...args,
+        prepare: () => {
+            const prepared = projectUserTurn(args.iface, args.draft);
+            if (!prepared.ok)
+                return prepared;
+            return {
+                ok: true,
+                prepared,
+                encodedAttachments: extractInlineEncodedAttachments(prepared.draft.attachments),
+                encodedVoice: extractInlineEncodedAttachments(prepared.draft.voice),
+            };
+        },
+    });
+}
+/**
+ * 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. 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 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 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: (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: session.sessionPermissions,
+                ...(reply.decision === 'approve' && reply.secret !== undefined
+                    ? { secret: reply.secret }
+                    : {}),
+                ...(reply.decision === 'approve' && reply.page ? { page: reply.page } : {}),
+            }, args.scope), onLine),
+        });
+    }
+    catch (err) {
+        // 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 {
+            session,
+            events: settled ? events : [...args.session.assistantEvents],
+            posted: true,
+            failure: turnFailure(err, args.iface.labels),
+        };
+    }
+    return { session, events, posted: true };
+}

package/client/schema-fields.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The rules behind a tool's request form: which input each JSON Schema field
+ * gets, what the form starts filled with, and what a request still lacks.
+ * The component only maps each decision to its Astryx input.
+ *
+ * @module
+ */
+export type JsonSchema = Record<string, unknown>;
+/** The input a field gets. */
+export type SchemaControl = {
+    kind: 'choice';
+    options: string[];
+    isMenu: boolean;
+} | {
+    kind: 'range';
+    min: number;
+    max: number;
+} | {
+    kind: 'number';
+    isInteger: boolean;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'switch';
+} | {
+    kind: 'date';
+} | {
+    kind: 'text';
+    isLong: boolean;
+    type: 'text' | 'email';
+} | {
+    kind: 'choices';
+    options: string[];
+} | {
+    kind: 'words';
+} | {
+    kind: 'rows';
+    item: JsonSchema;
+} | {
+    kind: 'group';
+    schema: JsonSchema;
+} | {
+    kind: 'json';
+};
+export type SchemaField = {
+    key: string;
+    label: string;
+    description?: string;
+    isRequired: boolean;
+    control: SchemaControl;
+};
+/** The input a field's schema asks for. */
+export declare function schemaControl(prop: JsonSchema): SchemaControl;
+/** An object schema's fields in the order it declares them, each with its input. */
+export declare function schemaFields(schema: JsonSchema): SchemaField[];
+/** Required fields, and optional ones the schema gives an example for; a plain value of the field's type when the schema declares no sample. */
+export declare function sampleFromSchema(schema: JsonSchema): Record<string, unknown>;
+/** A new row for a list of objects: its required fields, each at its sample. */
+export declare function blankRow(item: JsonSchema): Record<string, unknown>;
+/** The object with `key` set, or dropped when the value is empty. An optional field left empty isn't sent. */
+export declare function withField(row: Record<string, unknown>, key: string, value: unknown): Record<string, unknown>;
+/** The labels of required fields the request is still missing, nested ones by their path. */
+export declare function missingFields(schema: JsonSchema, value: unknown, prefix?: string): string[];

package/client/schema-fields.js

@@ -0,0 +1,199 @@
+/**
+ * The rules behind a tool's request form: which input each JSON Schema field
+ * gets, what the form starts filled with, and what a request still lacks.
+ * The component only maps each decision to its Astryx input.
+ *
+ * @module
+ */
+import { humanize, isRow } from "./shaped-data.js";
+/** Choices this few sit side by side; more open a menu. */
+const MAX_SEGMENTS = 5;
+/** Whole numbers bounded this closely slide; wider ranges are typed. */
+const MAX_SLIDER_STEPS = 100;
+/** Text allowed this long gets a text area. */
+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')
+        return declared;
+    if (declared === 'object' || isRow(prop.properties))
+        return 'object';
+    if (Array.isArray(prop.enum))
+        return 'string';
+    return 'unknown';
+}
+function itemsOf(prop) {
+    return isRow(prop.items) ? prop.items : undefined;
+}
+function enumOf(prop) {
+    const options = prop?.enum;
+    return Array.isArray(options) &&
+        options.length > 0 &&
+        options.every((option) => typeof option === 'string')
+        ? options
+        : undefined;
+}
+function numberAt(prop, key) {
+    const value = prop[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+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)
+        return { kind: 'range', min, max };
+    return {
+        kind: 'number',
+        isInteger,
+        ...(min === undefined ? {} : { min }),
+        ...(max === undefined ? {} : { max }),
+    };
+}
+function textControl(prop) {
+    if (prop.format === 'date')
+        return { kind: 'date' };
+    const maxLength = numberAt(prop, 'maxLength');
+    return {
+        kind: 'text',
+        isLong: maxLength === undefined ? false : maxLength > LONG_TEXT,
+        type: prop.format === 'email' ? 'email' : 'text',
+    };
+}
+function listControl(prop) {
+    const item = itemsOf(prop);
+    const choices = enumOf(item);
+    if (choices)
+        return { kind: 'choices', options: choices };
+    const itemKind = item ? kindOf(item) : 'unknown';
+    if (itemKind === 'string' || itemKind === 'number' || itemKind === 'integer')
+        return { kind: 'words' };
+    if (item && itemKind === 'object')
+        return { kind: 'rows', item };
+    return { kind: 'json' };
+}
+/** The input a field's schema asks for. */
+export function schemaControl(prop) {
+    const options = enumOf(prop);
+    if (options)
+        return { kind: 'choice', options, isMenu: options.length > MAX_SEGMENTS };
+    switch (kindOf(prop)) {
+        case 'boolean':
+            return { kind: 'switch' };
+        case 'number':
+            return numberControl(prop, false);
+        case 'integer':
+            return numberControl(prop, true);
+        case 'string':
+            return textControl(prop);
+        case 'array':
+            return listControl(prop);
+        case 'object':
+            return isRow(prop.properties) ? { kind: 'group', schema: prop } : { kind: 'json' };
+        default:
+            return { kind: 'json' };
+    }
+}
+function requiredOf(schema) {
+    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) {
+    const props = isRow(schema.properties) ? schema.properties : {};
+    const required = requiredOf(schema);
+    return Object.entries(props).flatMap(([key, prop]) => {
+        if (!isRow(prop))
+            return [];
+        return [
+            {
+                key,
+                label: typeof prop.title === 'string' && prop.title ? prop.title : humanize(key),
+                ...(typeof prop.description === 'string' && prop.description
+                    ? { description: prop.description }
+                    : {}),
+                isRequired: required.has(key),
+                control: schemaControl(prop),
+            },
+        ];
+    });
+}
+/** The schema's own example for a value: `examples[0]`, then `default`, `const`, `enum[0]`. */
+function declaredSample(prop) {
+    if (Array.isArray(prop.examples) && prop.examples.length)
+        return { value: prop.examples[0] };
+    if ('default' in prop)
+        return { value: prop.default };
+    if ('const' in prop)
+        return { value: prop.const };
+    if (Array.isArray(prop.enum) && prop.enum.length)
+        return { value: prop.enum[0] };
+    return undefined;
+}
+function sampleValue(prop) {
+    const declared = declaredSample(prop);
+    if (declared)
+        return declared.value;
+    switch (kindOf(prop)) {
+        case 'number':
+        case 'integer':
+            return numberAt(prop, 'minimum') ?? 1;
+        case 'boolean':
+            return true;
+        case 'array':
+            return [];
+        case 'object':
+            return sampleFromSchema(prop);
+        case 'string':
+        case 'unknown':
+            return 'example';
+    }
+}
+/** Required fields, and optional ones the schema gives an example for; a plain value of the field's type when the schema declares no sample. */
+export function sampleFromSchema(schema) {
+    const props = isRow(schema.properties) ? schema.properties : {};
+    const required = new Set(requiredOf(schema));
+    const sample = {};
+    for (const [key, prop] of Object.entries(props)) {
+        if (!isRow(prop))
+            continue;
+        if (required.has(key))
+            sample[key] = sampleValue(prop);
+        else if (Array.isArray(prop.examples) && prop.examples.length)
+            sample[key] = prop.examples[0];
+    }
+    return sample;
+}
+/** A new row for a list of objects: its required fields, each at its sample. */
+export function blankRow(item) {
+    return sampleFromSchema(item);
+}
+/** The object with `key` set, or dropped when the value is empty. An optional field left empty isn't sent. */
+export function withField(row, key, value) {
+    const next = { ...row };
+    if (value === undefined || value === '')
+        delete next[key];
+    else
+        next[key] = value;
+    return next;
+}
+/** The labels of required fields the request is still missing, nested ones by their path. */
+export function missingFields(schema, value, prefix = '') {
+    if (!isRow(value))
+        return [];
+    return schemaFields(schema).flatMap((field) => {
+        const entry = value[field.key];
+        const label = prefix ? `${prefix} › ${field.label}` : field.label;
+        if (entry === undefined || entry === null || entry === '')
+            return field.isRequired ? [label] : [];
+        return field.control.kind === 'group' ? missingFields(field.control.schema, entry, label) : [];
+    });
+}

package/client/shaped-data.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The rules `ShapedData` draws a payload by, as plain decisions: which shape a
+ * value takes, what a row is called, what a field's label and unit are. The
+ * component only maps each decision to its Astryx part.
+ */
+export type Row = Record<string, unknown>;
+/** Rows shown before the rest are left to the JSON view. */
+export declare const MAX_ROWS = 50;
+export declare const ISO_DATE: RegExp;
+export declare function isRow(value: unknown): value is Row;
+export declare function isPlain(value: unknown): boolean;
+/** The value as indented JSON, whatever it holds. */
+export declare function json(value: unknown): string;
+/** A string that holds a JSON object or list, parsed; anything else as it came. */
+export declare function unpacked(value: unknown): unknown;
+/** `country_code`, `countryCode` → "Country code". */
+export declare function humanize(key: string): string;
+/** A unit worth printing: a symbol or abbreviation, not a format name like `iso8601` or `wmo code`. */
+export declare function printableUnit(unit: unknown): string | undefined;
+/** A column's label and unit: from its `<key>_units` entry, else its key's suffix. */
+export declare function fieldLabel(key: string, units?: Row): {
+    label: string;
+    unit?: string;
+};
+/** A field's label and the unit its value reads with. A unit only reads onto a number: `country_code` stays "Country code". */
+export declare function fieldReading(key: string, value: unknown, units?: Row): {
+    label: string;
+    unit?: string;
+};
+/** The `<key>_units` object beside `key`, if there is one. */
+export declare function unitsOf(row: Row, key: string): Row | undefined;
+/** A row's fields, less the units objects its other fields read. */
+export declare function shownEntries(row: Row): [string, unknown][];
+/** How a plain value reads. */
+export type PlainReading = {
+    kind: 'none';
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'number';
+    value: number;
+    unit?: string;
+} | {
+    kind: 'link';
+    href: string;
+} | {
+    kind: 'date';
+    date: Date;
+} | {
+    kind: 'date-time';
+    date: Date;
+} | {
+    kind: 'text';
+    text: string;
+};
+export declare function plainReading(value: unknown, unit?: string): PlainReading;
+/** A formatted number with its unit: symbols sit close (21°C, 35%), words stand apart (320 m). */
+export declare function withUnit(number: string, unit?: string): string;
+/** The field that names a row, if it has one. */
+export declare function titleKey(row: Row): string | undefined;
+/** A row of a list as a ListItem shows it. */
+export type ListRow = {
+    title: string;
+    description: string;
+    href?: string;
+    tags: string[];
+    extras: [string, unknown][];
+};
+/** A collapsible row's heading and what it opens to: a titled row loses its title field; else it's named by its place. */
+export declare function rowHeading(item: unknown): {
+    title?: string;
+    tags: string[];
+    rest: unknown;
+};
+/** An object of equal-length lists of plain values (a column store): a table's columns. */
+export declare function columnStore(row: Row): string[] | undefined;
+/** A column store's lists, turned into rows. */
+export declare function storeRows(row: Row, columns: readonly string[]): Row[];
+/** The shape a value is drawn as. */
+export type Shape = {
+    kind: 'json';
+} | {
+    kind: 'none';
+} | {
+    kind: 'plain';
+} | {
+    kind: 'tokens';
+    items: unknown[];
+} | {
+    kind: 'list';
+    rows: ListRow[];
+} | {
+    kind: 'table';
+    columns: string[];
+    rows: Row[];
+} | {
+    kind: 'rows';
+    items: unknown[];
+} | {
+    kind: 'fields';
+    row: Row;
+};
+/** How a value (already unpacked) at `depth` is drawn. */
+export declare function shapeOf(value: unknown, depth: number): Shape;
+export declare function isProse(value: unknown): value is string;
+/** A nested field, through any chain of one-key wrappers: `{ data: { items: [] } }` → "Data › Items". */
+export type Section = {
+    key: string;
+    title: string;
+    value: unknown;
+    units?: Row;
+};
+/** An object's fields split: plain ones for the field list, nested ones as sections. */
+export declare function splitFields(row: Row): {
+    plain: [string, unknown][];
+    sections: Section[];
+};