@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/host/client-turn.js

@@ -1,4 +1,29 @@
+import { toErrorEvent, withPublicLabels, } from '../guardrails/error.js';
 import { projectGuardrailTurnEvent } from '../guardrails/events.js';
+/**
+ * For the builder, the wording of a failure is its raw reason, wherever a visitor's wording
+ * stands: a failed turn, an ended session, a tool call's failure.
+ */
+function builderWording(event) {
+    if (event.type === 'error' && event.errorInternal !== undefined) {
+        // why: `errorCopy` stays: worded raw or not, its key still names what failed for the page.
+        const { errorInternal, ...rest } = event;
+        return { ...rest, error: errorInternal };
+    }
+    if (event.type === 'session' &&
+        event.session.kind === 'ended' &&
+        event.errorInternal !== undefined) {
+        const { errorInternal, ...rest } = event;
+        return { ...rest, session: { ...event.session, message: errorInternal } };
+    }
+    if (event.type === 'tool' &&
+        event.tool.phase === 'error' &&
+        event.tool.failure.error !== undefined) {
+        const { failure } = event.tool;
+        return { ...event, tool: { ...event.tool, failure: { ...failure, error: failure.message } } };
+    }
+    return event;
+}
 /** Raw diagnostics ride on error events, an ended session's close, and a tool call's failure. */
 function stripErrorInternal(event) {
     if ((event.type !== 'error' && event.type !== 'session' && event.type !== 'tool') ||
@@ -22,17 +47,34 @@ function stripEvidenceRaw(event) {
     const { raw: _raw, ...evidence } = event.evidence;
     return { ...event, evidence };
 }
-/** Strips host-only diagnostics, so the copy is safe to forward to browsers or end-user SSE. */
+/**
+ * The copy of an event its reader may have. For a visitor (the default) host-only diagnostics are
+ * stripped, so the copy is safe to forward to browsers or end-user SSE.
+ */
 function forClient(event, options) {
-    let out = stripGuardrailInternal(stripErrorInternal(event));
+    let out = options?.reader === 'builder'
+        ? builderWording(event)
+        : stripGuardrailInternal(stripErrorInternal(event));
     if (!options?.includeEvidenceRaw) {
         out = stripEvidenceRaw(out);
     }
-    // Clients never receive matched substrings, even if the host opted into guardrailMatchPreview.
+    // invariant: Clients never receive matched substrings, even if the host opted into guardrailMatchPreview.
     out = projectGuardrailTurnEvent(out, false);
     return out;
 }
+/** `forClient` over a list of events. */
 function forClientEvents(events, options) {
     return events.map((event) => forClient(event, options));
 }
-export { forClient, forClientEvents };
+/**
+ * A caught failure as its reader may have it, by the same rule as `forClient`: the profile's
+ * wording (pass its `labels`) for a visitor, the raw diagnostic for a builder.
+ */
+function clientError(err, labels, options) {
+    const event = forClient(withPublicLabels(toErrorEvent(err), labels), options);
+    // why: An error event stays one through `withPublicLabels` and `forClient`, worded by the first.
+    const { error = '', errorKind, errorCopy } = event;
+    // why: The key tells the page what failed (a conversation the host lost), which `errorKind` cannot.
+    return { error, errorKind, ...(errorCopy ? { errorCopy } : {}) };
+}
+export { clientError, forClient, forClientEvents };

package/esm/src/host/mint-trace.d.ts

@@ -1,6 +1,7 @@
 import type { Profile } from '../kernel/types.js';
 import { type TraceRecord } from '../observability/trace-record.js';
 import type { TraceSink } from '../observability/trace-sink.js';
+/** The record of a cutout call kept on the trace: whether it succeeded, how long it took, its URL, the hashes of its input, and output, the upstream exchange and any error. */
 interface CutoutTape {
     ok: boolean;
     /** How long the cutout took; the span ends now and starts this long before. */

package/esm/src/host/mint-trace.js

@@ -30,10 +30,11 @@ async function flushMintTrace(args) {
     const { sink, policy } = resolveTraceWriter({
         override: args.sink,
         observability: args.profile.observability,
+        guardrails: args.profile.guardrails,
     });
     await writeTrace(sink, Promise.resolve(record), policy);
     const { cutout } = args;
-    // One instant: the cutout was reported done now and ran for `ms` before it.
+    // why: One instant: the cutout was reported done now and ran for `ms` before it.
     const now = BigInt(Date.now()) * BigInt(NANOS_PER_MS);
     const tree = startTrace('cutout', {
         clock: { nowUnixNano: () => now },
@@ -45,7 +46,7 @@ async function flushMintTrace(args) {
     if (cutout.http !== undefined) {
         tree.root.event('theorem.upstream.row', { row: traceJson(cutout.http) });
     }
-    // The host's error text is free text: stored by hash under the scrub, like any exception.
+    // why: The host's error text is free text: stored by hash under the scrub, like any exception.
     if (cutout.error) {
         tree.root.event('exception', { 'exception.message': traceContent(cutout.error) });
     }

package/esm/src/host/mod.d.ts

@@ -5,8 +5,8 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export type { ClientTurnOptions } from './client-turn.js';
-export { forClient, forClientEvents } from './client-turn.js';
+export type { ClientError, ClientTurnOptions } from './client-turn.js';
+export { clientError, forClient, forClientEvents } from './client-turn.js';
 export type { CutoutTape } from './mint-trace.js';
 export { flushMintTrace } from './mint-trace.js';
 export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';

package/esm/src/host/mod.js

@@ -5,7 +5,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { forClient, forClientEvents } from './client-turn.js';
+export { clientError, forClient, forClientEvents } from './client-turn.js';
 export { flushMintTrace } from './mint-trace.js';
 export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
 export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/readStreamingJsonStringField.js

@@ -1,21 +1,4 @@
-const JSON_ESCAPES = {
-    n: '\n',
-    t: '\t',
-    r: '\r',
-    '"': '"',
-    '\\': '\\',
-    '/': '/',
-};
-function decodeEscapedChar(ch, jsonText, index) {
-    if (ch === 'u' && index + 4 < jsonText.length) {
-        const hex = jsonText.slice(index + 1, index + 5);
-        if (/^[0-9a-fA-F]{4}$/.test(hex)) {
-            return { text: String.fromCharCode(Number.parseInt(hex, 16)), next: index + 4 };
-        }
-    }
-    const mapped = JSON_ESCAPES[ch];
-    return { text: mapped ?? ch, next: index };
-}
+import { readJsonString } from '../kernel/util/partial-json.js';
 /** The buffer may lack a closing quote; any decoded prefix is returned for live preview. */
 export function readStreamingJsonStringField(jsonText, key) {
     const keyLiteral = JSON.stringify(key);
@@ -40,29 +23,5 @@ export function readStreamingJsonStringField(jsonText, key) {
     if (keyAt < 0 || jsonText[i] !== '"') {
         return null;
     }
-    i += 1;
-    let result = '';
-    let escaped = false;
-    while (i < jsonText.length) {
-        const ch = jsonText[i];
-        if (escaped) {
-            const decoded = decodeEscapedChar(ch, jsonText, i);
-            result += decoded.text;
-            i = decoded.next;
-            escaped = false;
-            i += 1;
-            continue;
-        }
-        if (ch === '\\') {
-            escaped = true;
-        }
-        else if (ch === '"') {
-            return result;
-        }
-        else {
-            result += ch;
-        }
-        i += 1;
-    }
-    return result;
+    return readJsonString(jsonText, i).text;
 }

package/esm/src/host/reply.d.ts

@@ -1,7 +1,13 @@
+/** HTTP status for a success. */
 declare const HTTP_OK = 200;
+/** HTTP status for an unknown route. */
 declare const HTTP_NOT_FOUND = 404;
+/** HTTP status for a method the route does not take. */
 declare const HTTP_METHOD = 405;
+/** HTTP status for a request refused because the host is busy. */
 declare const HTTP_BUSY = 429;
+/** A JSON response with the status and the CORS headers. */
 declare function json(status: number, body: unknown, cors: Record<string, string>): Response;
+/** The HTTP status for a caught error, by its kind. */
 declare function caughtStatus(err: unknown): number;
 export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

package/esm/src/host/reply.js

@@ -1,7 +1,11 @@
 import { errorKind } from '../guardrails/error.js';
+/** HTTP status for a success. */
 const HTTP_OK = 200;
+/** HTTP status for an unknown route. */
 const HTTP_NOT_FOUND = 404;
+/** HTTP status for a method the route does not take. */
 const HTTP_METHOD = 405;
+/** HTTP status for a request refused because the host is busy. */
 const HTTP_BUSY = 429;
 const STATUS_BY_KIND = {
     config: 500,
@@ -19,16 +23,18 @@ const STATUS_BY_KIND = {
     blocked: 403,
     declined: 409,
     failed: 502,
-    // Client closed request (nginx convention): the caller went away.
+    // why: Client closed request (nginx convention): the caller went away.
     cancelled: 499,
     internal: 500,
 };
+/** A JSON response with the status and the CORS headers. */
 function json(status, body, cors) {
     return new Response(JSON.stringify(body), {
         status,
         headers: { ...cors, 'Content-Type': 'application/json' },
     });
 }
+/** The HTTP status for a caught error, by its kind. */
 function caughtStatus(err) {
     return STATUS_BY_KIND[errorKind(err)];
 }

package/esm/src/interface/blocks.d.ts

@@ -1,8 +1,11 @@
 import type { TurnEvent } from '../kernel/types.js';
 import type { FoldTurnEventsOptions, TranscriptBlock, UserTurnDraft } from './types.js';
+/** Restarts block id numbering at zero. */
 declare function resetBlockIds(): void;
+/** Turns a user draft into transcript blocks: a `user-text` block for the trimmed text, then one block per attachment and per voice clip. */
 declare function buildUserTurnBlocks(draft: UserTurnDraft, idPrefix?: string): TranscriptBlock[];
 /** Resets only the turn id sequence, so streaming refolds keep stable `turn-*` keys. */
 declare function foldTurnEvents(events: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+/** One conversation turn as blocks: the user draft's blocks followed by the assistant events folded into blocks. */
 declare function foldConversationTurn(draft: UserTurnDraft, assistantEvents: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
 export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };

package/esm/src/interface/blocks.js

@@ -1,4 +1,6 @@
-import { applyToolEvent } from './tool-calls.js';
+import { keptReply } from '../kernel/turn-events.js';
+import { partialJsonObject } from '../kernel/util/partial-json.js';
+import { applyToolDraft, applyToolEvent } from './tool-calls.js';
 import { collectPromotedMediaFromToolOutput } from './tool-media.js';
 let turnBlockCounter = 0;
 /**
@@ -12,6 +14,7 @@ function nextBlockId(prefix) {
     turnBlockCounter += 1;
     return `${prefix}-${String(turnBlockCounter)}`;
 }
+/** Restarts block id numbering at zero. */
 function resetBlockIds() {
     turnBlockCounter = 0;
 }
@@ -30,17 +33,77 @@ function appendText(blocks, kind, text, idPrefix) {
         text,
     });
 }
-/** One block per call, keyed by `callId`; each event folds into it (`applyToolEvent`). */
+/**
+ * A decision made while text streams goes ahead of that text's block, so the block stays last and
+ * the rest of the text joins it.
+ */
+function addGuardrailBlock(blocks, block) {
+    const last = blocks.at(-1);
+    const streaming = last?.kind === 'text' || last?.kind === 'thought';
+    blocks.splice(streaming ? blocks.length - 1 : blocks.length, 0, block);
+}
+function findToolBlock(blocks, id) {
+    return blocks.find((block) => block.kind === 'tool' && block.id === id);
+}
+/** invariant: Issued operation IDs separate action blocks; historical events use callId. */
 function upsertToolBlock(blocks, tool) {
-    const id = `tool-${tool.callId}`;
-    const existing = blocks.find((block) => block.kind === 'tool' && block.id === id);
+    const id = `tool-${tool.operationId ?? tool.callId}`;
+    const existing = findToolBlock(blocks, id);
     const call = applyToolEvent(existing?.tool, tool);
     if (existing) {
         existing.tool = call;
         return;
     }
+    // why: The call the model was drafting arrives whole where its draft stood.
+    const draft = tool.phase === undefined ? findToolBlock(blocks, `tool-${tool.callId}`) : undefined;
+    if (draft?.tool.draft !== undefined) {
+        draft.id = id;
+        draft.tool = call;
+        return;
+    }
+    blocks.push({ id, kind: 'tool', tool: call });
+}
+/** The call the model is still writing, as far as its draft has come. */
+function upsertToolDraft(blocks, draft) {
+    const id = `tool-${draft.callId}`;
+    const existing = findToolBlock(blocks, id);
+    const call = applyToolDraft(existing?.tool, draft);
+    if (existing) {
+        existing.tool = call;
+        return;
+    }
     blocks.push({ id, kind: 'tool', tool: call });
 }
+/** The structured reply the model is still writing, if one is showing. */
+function openStructuredDraft(blocks) {
+    return blocks.findLast((block) => block.kind === 'structured' && block.draft !== undefined);
+}
+/** The structured reply the model is still writing, as far as its draft has come. */
+function upsertStructuredDraft(blocks, text, idPrefix) {
+    const open = openStructuredDraft(blocks);
+    const draft = (open?.draft ?? '') + text;
+    if (open) {
+        open.draft = draft;
+        open.value = partialJsonObject(draft);
+        return;
+    }
+    blocks.push({
+        id: nextBlockId(idPrefix),
+        kind: 'structured',
+        value: partialJsonObject(draft),
+        draft,
+    });
+}
+/** The structured reply, in its draft's place when one is showing. */
+function settleStructured(blocks, value, idPrefix) {
+    const open = openStructuredDraft(blocks);
+    if (open) {
+        open.value = value;
+        delete open.draft;
+        return;
+    }
+    blocks.push({ id: nextBlockId(idPrefix), kind: 'structured', value });
+}
 /** Same source: one place, or one link. */
 function sameSource(a, b) {
     if (a.type !== b.type)
@@ -89,6 +152,7 @@ function appendPromotedToolMedia(blocks, tool, idPrefix, seenUrls) {
         });
     }
 }
+/** Turns a user draft into transcript blocks: a `user-text` block for the trimmed text, then one block per attachment and per voice clip. */
 function buildUserTurnBlocks(draft, idPrefix = 'user') {
     const blocks = [];
     const text = draft.text?.trim();
@@ -128,7 +192,7 @@ function foldTurnEvents(events, options = {}) {
     turnBlockCounter = 0;
     const blocks = [];
     const promotedMediaUrls = new Set();
-    for (const event of events) {
+    for (const event of keptReply(events)) {
         switch (event.type) {
             case 'thought':
                 if (showThoughts && event.text) {
@@ -140,16 +204,18 @@ function foldTurnEvents(events, options = {}) {
                     appendText(blocks, 'text', event.text, idPrefix);
                 }
                 break;
+            case 'tool_draft':
+                upsertToolDraft(blocks, event);
+                break;
             case 'tool':
                 upsertToolBlock(blocks, event.tool);
                 appendPromotedToolMedia(blocks, event.tool, idPrefix, promotedMediaUrls);
                 break;
+            case 'structured_draft':
+                upsertStructuredDraft(blocks, event.text, idPrefix);
+                break;
             case 'structured':
-                blocks.push({
-                    id: nextBlockId(idPrefix),
-                    kind: 'structured',
-                    value: event.structured,
-                });
+                settleStructured(blocks, event.structured, idPrefix);
                 break;
             case 'media':
                 if (event.media) {
@@ -178,6 +244,13 @@ function foldTurnEvents(events, options = {}) {
                     evidence: event.evidence,
                 });
                 break;
+            case 'guardrail':
+                addGuardrailBlock(blocks, {
+                    id: nextBlockId(idPrefix),
+                    kind: 'guardrail',
+                    guardrail: event.guardrail,
+                });
+                break;
             case 'error':
                 if (event.error) {
                     blocks.push({
@@ -197,16 +270,13 @@ function foldTurnEvents(events, options = {}) {
                     compaction: event.compaction !== undefined,
                 });
                 break;
-            case 'tokens':
-            case 'session':
-            case 'stage':
-                break;
             default:
                 break;
         }
     }
     return blocks;
 }
+/** One conversation turn as blocks: the user draft's blocks followed by the assistant events folded into blocks. */
 function foldConversationTurn(draft, assistantEvents, options = {}) {
     return [...buildUserTurnBlocks(draft, 'user'), ...foldTurnEvents(assistantEvents, options)];
 }

package/esm/src/interface/composer-actions.d.ts

@@ -1,4 +1,5 @@
 import type { ComposerPendingKind } from './pending.js';
+/** Where a run is: idle, streaming, or held at a tool gate. */
 export type ComposerRunPhase = 'idle' | 'streaming' | 'gated';
 /** Primary button / Enter target. */
 export type ComposerPrimaryAction = 'send' | 'stop' | 'queue' | 'none';
@@ -7,6 +8,7 @@ export type ComposerPrimaryAction = 'send' | 'stop' | 'queue' | 'none';
  * abandon the tool gate (no model continue) + send while gated; not a pending kind.
  */
 export type ComposerMenuAction = ComposerPendingKind | 'send_now';
+/** What decides the composer's actions: the run phase, whether there is something to send, and whether steering and stop are allowed. */
 export type ComposerActionContext = {
     phase: ComposerRunPhase;
     hasPayload: boolean;
@@ -15,6 +17,8 @@ export type ComposerActionContext = {
     /** Composer profiles always project `canStop: true`. */
     canStop?: boolean;
 };
+/** The action of the primary button and Enter: `send` when idle with a draft, `queue` mid-run with one, `stop` while streaming with none (when stop is allowed), else `none`. */
 declare function resolveComposerPrimary(ctx: ComposerActionContext): ComposerPrimaryAction;
+/** The split menu's actions: none without a draft; `stash` when idle; mid-run `queue`, `steer` while streaming when steering is allowed, `send_now` and `stash`. */
 declare function resolveComposerMenuActions(ctx: ComposerActionContext): ComposerMenuAction[];
 export { resolveComposerMenuActions, resolveComposerPrimary };

package/esm/src/interface/composer-actions.js

@@ -1,3 +1,4 @@
+/** The action of the primary button and Enter: `send` when idle with a draft, `queue` mid-run with one, `stop` while streaming with none (when stop is allowed), else `none`. */
 function resolveComposerPrimary(ctx) {
     const canStop = ctx.canStop !== false;
     if (ctx.phase === 'idle') {
@@ -8,9 +9,10 @@ function resolveComposerPrimary(ctx) {
             return canStop ? 'stop' : 'none';
         return 'queue';
     }
-    // Gated is still the same run: queue only, no stream to stop.
+    // why: Gated is still the same run: queue only, no stream to stop.
     return ctx.hasPayload ? 'queue' : 'none';
 }
+/** The split menu's actions: none without a draft; `stash` when idle; mid-run `queue`, `steer` while streaming when steering is allowed, `send_now` and `stash`. */
 function resolveComposerMenuActions(ctx) {
     if (!ctx.hasPayload)
         return [];
@@ -24,8 +26,8 @@ function resolveComposerMenuActions(ctx) {
         actions.push('send_now', 'stash');
         return actions;
     }
-    // gated: no steer (not an inject stage); send_now = host ends wait + send
+    // why: gated: no steer (not an inject stage); send_now = host ends wait + send
     return ['queue', 'send_now', 'stash'];
 }
-// Emits semantic action keys only: English labels live in the rendering layer or the host UI.
+// invariant: Emits semantic action keys only: English labels live in the rendering layer or the host UI.
 export { resolveComposerMenuActions, resolveComposerPrimary };

package/esm/src/interface/draft.d.ts

@@ -1,6 +1,12 @@
 import type { AttachmentValidationIssue } from '../kernel/types.js';
 import type { ProfileGuardrailsView, ProfileInputsInterface, TranscriptBlock, UserTurnDraft } from './types.js';
+/**
+ * Reads a draft's text at the `user` boundary with Theorem's patterns, as the kernel will: a
+ * match set to redact shows as its placeholder. A match set to block leaves the draft as typed;
+ * the kernel refuses the turn. A match of the host's own patterns is the kernel's to find.
+ */
 declare function sanitizeUserDraft(draft: UserTurnDraft, guardrails?: ProfileGuardrailsView): UserTurnDraft;
+/** The result of preparing a user turn: the sanitized draft with its transcript blocks, or the attachment issues that rejected it. */
 export type PrepareUserTurnResult = {
     ok: true;
     draft: UserTurnDraft;

package/esm/src/interface/draft.js

@@ -1,20 +1,31 @@
-import { resolveGuardrailPolicy } from '../guardrails/policy.js';
-import { sanitizeText } from '../guardrails/sanitize.js';
-import { anySensitive } from '../guardrails/sensitive.js';
+import { detectAt } from '../guardrails/detect-at.js';
+import { DETECT_DEFAULTS } from '../guardrails/detectors.js';
 import { buildUserTurnBlocks } from './blocks.js';
 import { validateProfileInputs } from './inputs.js';
+/** The view's matrix with Theorem's patterns off where the profile turned them off. The host's own patterns stay with the kernel. */
+function detectOf(guardrails) {
+    if (!guardrails)
+        return DETECT_DEFAULTS;
+    const { detect, patterns } = guardrails;
+    if (!patterns)
+        return detect;
+    const sources = Object.fromEntries(Object.entries(patterns).map(([detector, { theorem }]) => [
+        detector,
+        { theorem, matchers: [] },
+    ]));
+    return { ...detect, sources };
+}
+/**
+ * Reads a draft's text at the `user` boundary with Theorem's patterns, as the kernel will: a
+ * match set to redact shows as its placeholder. A match set to block leaves the draft as typed;
+ * the kernel refuses the turn. A match of the host's own patterns is the kernel's to find.
+ */
 function sanitizeUserDraft(draft, guardrails) {
-    const options = guardrails ?? resolveGuardrailPolicy(undefined);
-    if (!options.sanitizeInput && !anySensitive(options.redactSensitive)) {
-        return draft;
-    }
     if (draft.text === undefined) {
         return draft;
     }
-    return {
-        ...draft,
-        text: sanitizeText(draft.text, options),
-    };
+    const detected = detectAt(draft.text, 'user', detectOf(guardrails));
+    return { ...draft, text: detected.text ?? draft.text };
 }
 /** Call before appending to the thread and before `runTurn` ingress. */
 function prepareUserTurn(inputs, draft, guardrails) {

package/esm/src/interface/from-profile.d.ts

@@ -6,7 +6,19 @@ import type { ComposerProfileInterface, LiveProfileInterface, ProfileInterface }
  * the scope that runs the profile.
  */
 declare function interfaceFromProfile(input: LiveProfile, tools: ToolRegistry): LiveProfileInterface;
+/** The interface for a profile that is not live. */
 declare function interfaceFromProfile(input: Exclude<Profile, LiveProfile>, tools: ToolRegistry): ComposerProfileInterface;
+/** The interface for any profile. */
 declare function interfaceFromProfile(input: Profile, tools: ToolRegistry): ProfileInterface;
+/** The interface for a profile the host has already projected, without resolving its tools again. */
 declare function interfaceFromProjected(projected: ProjectedProfile): ProfileInterface;
-export { interfaceFromProfile, interfaceFromProjected };
+/**
+ * The interface a browser may read: {@linkcode interfaceFromProfile} without `identity.system` and
+ * `systemByRole`, which stay on the server. Labels, turn behaviour, guardrails, and observability are kept.
+ */
+declare function clientProfileInterface(input: LiveProfile, tools: ToolRegistry): LiveProfileInterface;
+/** The client-safe interface for a profile that is not live. */
+declare function clientProfileInterface(input: Exclude<Profile, LiveProfile>, tools: ToolRegistry): ComposerProfileInterface;
+/** The client-safe interface for any profile. */
+declare function clientProfileInterface(input: Profile, tools: ToolRegistry): ProfileInterface;
+export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected };