theorum 0.1.15 → 1.0.0

package/esm/src/guardrails/sanitize.js

@@ -1,13 +1,8 @@
 /**
  * Request sanitization utilities for THEORUM.
  *
- * Sanitization removes inbound prompt-injection spans and sensitive-data spans
- * according to the active profile guardrail flags. The host remains responsible
- * for domain policy.
- *
  * @module
  */
-import { mapStrings } from '../kernel/engine/tree.js';
 import { sanitizeTurnBlobsForProfile } from '../kernel/registry/attachments.js';
 import { getProfile } from '../kernel/registry/profiles.js';
 import { applySpans } from '../observability/spans.js';
@@ -26,8 +21,7 @@ function sanitizeText(text, options) {
     ];
     return applySpans(text, spans);
 }
-/** Redact only sensitive data (credentials, PII) — skip injection patterns.
- *  Use for model output text that never contained user-authored injection attempts. */
+/** Redact only sensitive data (credentials, PII) — skip injection patterns. */
 function redactSensitiveOnly(text) {
     const spans = sensitiveSpans(text);
     if (spans.length === 0)
@@ -44,17 +38,8 @@ function sanitizeSlots(slots, options) {
     }
     return out;
 }
-function sanitizeArgs(args, options) {
-    const next = mapStrings(args, (t) => sanitizeText(t, options));
-    if (next && typeof next === 'object' && !Array.isArray(next)) {
-        return next;
-    }
-    return args;
-}
-/** Maximum retained length for trace-safe host project ids. */
 const PROJECT_ID_MAX = 128;
 const PROJECT_ID_OK = /^[A-Za-z0-9._-]+$/;
-/** Return a trace-safe project id or `undefined` when the input is unsafe. */
 function sanitizeProjectId(id) {
     if (!id) {
         return undefined;
@@ -93,43 +78,23 @@ function sanitizeHistory(history, options) {
         ...(m.metadata ? { metadata: m.metadata } : {}),
     }));
 }
-function sanitizeDynamicTool(decl, options) {
-    const clean = { ...decl };
-    if (clean.description !== undefined) {
-        clean.description = sanitizeText(clean.description, options);
-    }
-    if (clean.parameters !== undefined) {
-        clean.parameters = sanitizeArgs(clean.parameters, options);
-    }
-    return clean;
-}
-/** Sanitize description and parameter schema text in dynamic tool declarations. */
-function sanitizeDynamicTools(tools, options) {
-    if (!tools || tools.length === 0) {
-        return tools;
-    }
-    return tools.map((decl) => sanitizeDynamicTool(decl, options));
-}
-/** Sanitize all user-controlled text and blobs in a turn request. */
-function sanitizeTurnRequest(req) {
+function guardrailTextOptions(profileId) {
     let profileGuardrails;
     try {
-        profileGuardrails = getProfile(req.profile)?.guardrails;
+        profileGuardrails = getProfile(profileId)?.guardrails;
     }
     catch {
-        // If profile not registered yet, default to full guardrails
+        // If profile not registered yet, default to full guardrails.
     }
-    const options = {
+    return {
         sanitizeInput: profileGuardrails?.sanitizeInput ?? true,
         redactSensitive: profileGuardrails?.redactSensitive ?? true,
     };
+}
+/** Sanitize user-controlled text fields; leave attachments/voice untouched. */
+function sanitizeTurnRequestText(req, options) {
     const input = req.input ?? {};
-    const { toolInvoke } = req;
     const { text: rawText } = input;
-    let invoke = toolInvoke;
-    if (toolInvoke) {
-        invoke = { ...toolInvoke, arguments: sanitizeArgs(toolInvoke.arguments, options) };
-    }
     let text = rawText;
     if (rawText !== undefined) {
         text = sanitizeText(rawText, options);
@@ -138,22 +103,48 @@ function sanitizeTurnRequest(req) {
     if (system !== undefined) {
         system = sanitizeText(system, options);
     }
-    const { attachments, voice } = sanitizeTurnBlobsForProfile(req.profile, input.attachments, input.voice);
     return {
         ...req,
         system,
         projectId: sanitizeProjectId(req.projectId),
-        dynamicTools: sanitizeDynamicTools(req.dynamicTools, options),
         input: {
             ...input,
             text,
             slots: sanitizeSlots(input.slots, options),
-            attachments,
-            voice,
             repair: sanitizeRepair(input.repair, options),
             history: sanitizeHistory(input.history, options),
         },
-        toolInvoke: invoke,
     };
 }
-export { PROJECT_ID_MAX, redactSensitiveOnly, sanitizeDynamicTools, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, };
+/** Sanitize all user-controlled text and blobs in a turn request. */
+function sanitizeTurnRequest(req) {
+    const options = guardrailTextOptions(req.profile);
+    const textSafe = sanitizeTurnRequestText(req, options);
+    const input = textSafe.input ?? {};
+    const { attachments, voice } = sanitizeTurnBlobsForProfile(req.profile, input.attachments, input.voice);
+    return {
+        ...textSafe,
+        input: {
+            ...input,
+            attachments,
+            voice,
+        },
+    };
+}
+/**
+ * Trace-safe request sanitize. Prefers full `sanitizeTurnRequest`; if blob/policy
+ * checks throw, still redacts text and keeps attachments for hashing — never invents empty input.
+ */
+function sanitizeTurnRequestForTrace(req) {
+    try {
+        return { request: sanitizeTurnRequest(req) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            request: sanitizeTurnRequestText(req, guardrailTextOptions(req.profile)),
+            sanitizeError: message,
+        };
+    }
+}
+export { PROJECT_ID_MAX, redactSensitiveOnly, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestForTrace, };

package/esm/src/guardrails/sensitive.js

@@ -23,7 +23,8 @@ const GITHUB_PAT = /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g;
 const GITHUB_TOKEN = /\bghp_[A-Za-z0-9]{36}\b/g;
 const SLACK_TOKEN = /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g;
 const BEARER = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
-const PEM_KEY = /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA )?PRIVATE KEY-----/g;
+/** Bounded payload so PEM redaction cannot ReDoS on repeated BEGIN markers. */
+const PEM_KEY = /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]{0,16384}?-----END (?:RSA )?PRIVATE KEY-----/g;
 const CARD_CANDIDATE = /\b(?:\d[\s.-]*?){13,19}\b/g;
 const KEY_PATTERNS = [
     SSN,

package/esm/src/guardrails/testing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Guardrails testing surface — adversarial corpus, fuzz runners, live attack builders.
+ *
+ * Import via `theorum/guardrails/testing` (not published on the production guardrails entry).
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { CanaryEgressAttack, CanaryEgressCatalogEntry, InboundFuzzPayload, InboundFuzzResult, LiveAttack, } from './corpus/mod.js';
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';

package/esm/src/guardrails/testing.js

@@ -0,0 +1,9 @@
+/**
+ * Guardrails testing surface — adversarial corpus, fuzz runners, live attack builders.
+ *
+ * Import via `theorum/guardrails/testing` (not published on the production guardrails entry).
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';

package/esm/src/host/client-turn.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Strip host-only diagnostics from turn events before client-facing transports.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../kernel/types.js';
+/** Options for {@link forClient} / {@link forClientEvents}. */
+export interface ClientTurnOptions {
+    /**
+     * Keep provider-native step payloads on `evidence` events.
+     * Default `false` — parsed fields (`kind`, `code`, `result`, citations) remain.
+     */
+    includeEvidenceRaw?: boolean;
+}
+/** Return a copy of one turn event safe to forward to browsers or end-user SSE. */
+declare function forClient(event: TurnEvent, options?: ClientTurnOptions): TurnEvent;
+/** Map {@link forClient} over a batch (e.g. Live relay or HTTP stream flush). */
+declare function forClientEvents(events: TurnEvent[], options?: ClientTurnOptions): TurnEvent[];
+export { forClient, forClientEvents };

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

@@ -0,0 +1,32 @@
+/**
+ * Strip host-only diagnostics from turn events before client-facing transports.
+ *
+ * @module
+ */
+function stripErrorInternal(event) {
+    if (event.type !== 'error' || !event.errorInternal) {
+        return event;
+    }
+    const { errorInternal: _internal, ...rest } = event;
+    return rest;
+}
+function stripEvidenceRaw(event) {
+    if (event.type !== 'evidence' || !event.evidence?.raw) {
+        return event;
+    }
+    const { raw: _raw, ...evidence } = event.evidence;
+    return { ...event, evidence };
+}
+/** Return a copy of one turn event safe to forward to browsers or end-user SSE. */
+function forClient(event, options) {
+    let out = stripErrorInternal(event);
+    if (!options?.includeEvidenceRaw) {
+        out = stripEvidenceRaw(out);
+    }
+    return out;
+}
+/** Map {@link forClient} over a batch (e.g. Live relay or HTTP stream flush). */
+function forClientEvents(events, options) {
+    return events.map((event) => forClient(event, options));
+}
+export { forClient, forClientEvents };

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

@@ -1,13 +1,15 @@
 /**
  * Optional host-application helpers.
  *
- * These are not part of the turn kernel. They exist for Deno HTTP hosts that
- * want shared reply status mapping and cutout-trace flushing without re-
- * implementing the same glue in every app route.
+ * Not part of the turn kernel. Shared glue for Deno HTTP hosts (reply status,
+ * cutout-trace flush) and live structured-output preview while tokens stream.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export type { ClientTurnOptions } from './client-turn.js';
+export { forClient, forClientEvents } from './client-turn.js';
 export type { CutoutTape } from './mint-trace.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/mod.js

@@ -1,12 +1,13 @@
 /**
  * Optional host-application helpers.
  *
- * These are not part of the turn kernel. They exist for Deno HTTP hosts that
- * want shared reply status mapping and cutout-trace flushing without re-
- * implementing the same glue in every app route.
+ * Not part of the turn kernel. Shared glue for Deno HTTP hosts (reply status,
+ * cutout-trace flush) and live structured-output preview while tokens stream.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export { 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/interface/blocks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Turn event folding — map kernel `TurnEvent` streams to transcript blocks.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../kernel/types.js';
+import type { FoldTurnEventsOptions, TranscriptBlock, UserTurnDraft } from './types.js';
+declare function resetBlockIds(): void;
+/** Build transcript blocks for a user-authored turn. */
+declare function buildUserTurnBlocks(draft: UserTurnDraft, idPrefix?: string): TranscriptBlock[];
+/**
+ * Fold a single assistant turn's `TurnEvent` stream into ordered transcript blocks.
+ *
+ * Merges consecutive `text` and `thought` deltas, upserts tool calls by id, and
+ * skips kernel bookkeeping events (`tokens`, `session`) unless folded into `turn-done`.
+ */
+declare function foldTurnEvents(events: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+/** User draft blocks followed by folded assistant turn events. */
+declare function foldConversationTurn(draft: UserTurnDraft, assistantEvents: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };

package/esm/src/interface/blocks.js

@@ -0,0 +1,180 @@
+/**
+ * Turn event folding — map kernel `TurnEvent` streams to transcript blocks.
+ *
+ * @module
+ */
+let blockCounter = 0;
+function nextBlockId(prefix) {
+    blockCounter += 1;
+    return `${prefix}-${String(blockCounter)}`;
+}
+function resetBlockIds() {
+    blockCounter = 0;
+}
+function isAppendableTextBlock(block, kind) {
+    return block?.kind === kind;
+}
+function toolKey(event, index) {
+    const tool = event.tool;
+    if (!tool)
+        return `tool-${String(index)}`;
+    return tool.callId ?? tool.id ?? `${tool.name}-${String(index)}`;
+}
+function appendText(blocks, kind, text, idPrefix) {
+    const last = blocks.at(-1);
+    if (isAppendableTextBlock(last, kind)) {
+        last.text += text;
+        return;
+    }
+    blocks.push({
+        id: nextBlockId(idPrefix),
+        kind,
+        text,
+    });
+}
+function upsertToolBlock(blocks, event, key) {
+    const tool = event.tool;
+    if (!tool)
+        return;
+    const existing = blocks.find((block) => block.kind === 'tool' && block.id === `tool-${key}`);
+    const payload = { ...tool, id: tool.id ?? tool.callId };
+    if (existing && existing.kind === 'tool') {
+        existing.tool = { ...existing.tool, ...payload };
+        return;
+    }
+    blocks.push({
+        id: `tool-${key}`,
+        kind: 'tool',
+        tool: payload,
+    });
+}
+/** Build transcript blocks for a user-authored turn. */
+function buildUserTurnBlocks(draft, idPrefix = 'user') {
+    resetBlockIds();
+    const blocks = [];
+    const text = draft.text?.trim();
+    if (text) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-text',
+            text,
+        });
+    }
+    for (const file of draft.attachments ?? []) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-attachment',
+            name: file.name,
+            mimeType: file.mimeType,
+            sizeBytes: file.sizeBytes,
+        });
+    }
+    for (const file of draft.voice ?? []) {
+        blocks.push({
+            id: nextBlockId(idPrefix),
+            kind: 'user-voice',
+            name: file.name,
+            mimeType: file.mimeType,
+            sizeBytes: file.sizeBytes,
+        });
+    }
+    return blocks;
+}
+/**
+ * Fold a single assistant turn's `TurnEvent` stream into ordered transcript blocks.
+ *
+ * Merges consecutive `text` and `thought` deltas, upserts tool calls by id, and
+ * skips kernel bookkeeping events (`tokens`, `session`) unless folded into `turn-done`.
+ */
+function foldTurnEvents(events, options = {}) {
+    const idPrefix = options.idPrefix ?? 'turn';
+    const showThoughts = options.showThoughts ?? true;
+    resetBlockIds();
+    const blocks = [];
+    let toolIndex = 0;
+    for (const event of events) {
+        switch (event.type) {
+            case 'thought':
+                if (showThoughts && event.text) {
+                    appendText(blocks, 'thought', event.text, idPrefix);
+                }
+                break;
+            case 'text':
+                if (event.text) {
+                    appendText(blocks, 'text', event.text, idPrefix);
+                }
+                break;
+            case 'tool': {
+                const key = toolKey(event, toolIndex);
+                toolIndex += 1;
+                upsertToolBlock(blocks, event, key);
+                break;
+            }
+            case 'structured':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'structured',
+                    value: event.structured,
+                });
+                break;
+            case 'media':
+                if (event.media) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'media',
+                        mimeType: event.media.mimeType,
+                        data: event.media.data,
+                    });
+                }
+                break;
+            case 'grounding':
+                if (event.grounding) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'grounding',
+                        grounding: event.grounding,
+                    });
+                }
+                break;
+            case 'evidence':
+                if (event.evidence) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'evidence',
+                        evidence: event.evidence,
+                    });
+                }
+                break;
+            case 'error':
+                if (event.error) {
+                    blocks.push({
+                        id: nextBlockId(idPrefix),
+                        kind: 'error',
+                        message: event.error,
+                    });
+                }
+                break;
+            case 'done':
+                blocks.push({
+                    id: nextBlockId(idPrefix),
+                    kind: 'turn-done',
+                    stop: event.stop,
+                    tokens: event.tokens,
+                    interactionId: event.interactionId,
+                    compaction: event.compaction !== undefined,
+                });
+                break;
+            case 'tokens':
+            case 'session':
+                break;
+            default:
+                break;
+        }
+    }
+    return blocks;
+}
+/** User draft blocks followed by folded assistant turn events. */
+function foldConversationTurn(draft, assistantEvents, options = {}) {
+    return [...buildUserTurnBlocks(draft, 'user'), ...foldTurnEvents(assistantEvents, options)];
+}
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };

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

@@ -0,0 +1,14 @@
+/**
+ * Profile → `ProfileInterface` projection.
+ *
+ * Kernel `projectProfileObject` is the single inspection projection; this module
+ * only enriches `inputs` (acceptAttr) and attaches serializable guardrails.
+ *
+ * @module
+ */
+import type { Profile, ProjectedProfile } from '../kernel/types.js';
+import type { ProfileInterface, ProfileInterfaceSource } from './types.js';
+declare function interfaceFrom(source: ProfileInterfaceSource): ProfileInterface;
+declare function interfaceFromProfile(profile: Profile): ProfileInterface;
+declare function interfaceFromProjected(projected: ProjectedProfile): ProfileInterface;
+export { interfaceFrom, interfaceFromProfile, interfaceFromProjected };

package/esm/src/interface/from-profile.js

@@ -0,0 +1,104 @@
+/**
+ * Profile → `ProfileInterface` projection.
+ *
+ * Kernel `projectProfileObject` is the single inspection projection; this module
+ * only enriches `inputs` (acceptAttr) and attaches serializable guardrails.
+ *
+ * @module
+ */
+import { projectProfileObject } from '../kernel/registry/resolve.js';
+import { inputsFromSpec } from './inputs.js';
+function guardrailsView(guardrails) {
+    if (!guardrails)
+        return undefined;
+    return {
+        quota: guardrails.quota,
+        canary: guardrails.canary,
+        sanitizeInput: guardrails.sanitizeInput,
+        redactSensitive: guardrails.redactSensitive,
+        hasEgress: Boolean(guardrails.egress),
+    };
+}
+function normalizeModel(model) {
+    return {
+        ...model,
+        select: model.select ?? null,
+        controls: model.controls ?? [],
+    };
+}
+function toolsResolved(projected, profile) {
+    if (projected.type === 'speech') {
+        return { allow: [], resolved: [] };
+    }
+    if (profile && profile.type !== 'speech') {
+        return {
+            allow: profile.tools.allow,
+            t2Loader: profile.tools.t2Loader,
+            resolved: projected.tools,
+        };
+    }
+    const allow = projected.tools
+        .filter((tool) => !('type' in tool && tool.type === 'builtin'))
+        .map((tool) => tool.name);
+    return { allow, resolved: projected.tools };
+}
+function enrich(projected, profile) {
+    const inputs = inputsFromSpec(projected.type, projected.inputs);
+    const identity = profile?.identity ?? { handle: projected.handle };
+    const model = normalizeModel(projected.model);
+    const guardrails = profile ? guardrailsView(profile.guardrails) : undefined;
+    const outputs = projected.outputs ?? undefined;
+    const shared = { id: projected.id, identity, model, outputs, guardrails };
+    switch (projected.type) {
+        case 'text':
+            return {
+                ...shared,
+                type: 'text',
+                inputs,
+                tools: toolsResolved(projected, profile),
+                turnResumption: profile?.type === 'text' ? profile.turnResumption : undefined,
+            };
+        case 'image':
+            return {
+                ...shared,
+                type: 'image',
+                image: projected.image ?? {},
+                inputs,
+                tools: toolsResolved(projected, profile),
+                turnResumption: profile?.type === 'image' ? profile.turnResumption : undefined,
+            };
+        case 'speech':
+            return {
+                ...shared,
+                type: 'speech',
+                speech: projected.speech ?? {},
+                inputs,
+                turnResumption: profile?.type === 'speech' ? profile.turnResumption : undefined,
+            };
+        case 'live':
+            return {
+                ...shared,
+                type: 'live',
+                live: projected.live ?? {},
+                inputs,
+                tools: toolsResolved(projected, profile),
+            };
+        default: {
+            const exhaustive = projected.type;
+            return exhaustive;
+        }
+    }
+}
+function interfaceFrom(source) {
+    if ('identity' in source) {
+        return enrich(projectProfileObject(source), source);
+    }
+    return enrich(source);
+}
+function interfaceFromProfile(profile) {
+    return interfaceFrom(profile);
+}
+function interfaceFromProjected(projected) {
+    return interfaceFrom(projected);
+}
+export { interfaceFrom, interfaceFromProfile, interfaceFromProjected };

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

@@ -0,0 +1,8 @@
+import type { ProfileInputsSpec, ProfileType } from '../kernel/types.js';
+import type { AttachmentValidationResult, ProfileInputsInterface, UserTurnDraft } from './types.js';
+declare function attachmentAcceptAttr(accept: string[]): string;
+declare function inputsFromSpec(type: ProfileType, inputs: ProfileInputsSpec | null | undefined): ProfileInputsInterface;
+/** Validate staged files against resolved profile `inputs`. */
+declare function validateProfileInputs(inputs: ProfileInputsInterface, draft: Pick<UserTurnDraft, 'attachments' | 'voice'>): AttachmentValidationResult;
+declare function pickMediaRecorderMime(accept?: string[]): string | undefined;
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs };