theorum 0.1.14 → 1.0.0

package/esm/src/interface/inputs.js

@@ -0,0 +1,127 @@
+/**
+ * Profile `inputs` → UI affordances and validation.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+import { fileTooLargeMessage, maxBytesForMime, resolveMediaLimits, tooManyFilesMessage, turnTooLargeMessage, } from '../kernel/registry/attachments.js';
+import { mimeAllowed } from '../kernel/registry/catalog.js';
+const RECORDER_CANDIDATES = [
+    'audio/webm;codecs=opus',
+    'audio/webm',
+    'audio/mp4',
+    'audio/wav',
+    'audio/mpeg',
+];
+function attachmentAcceptAttr(accept) {
+    return accept.join(',');
+}
+function inputsFromSpec(type, inputs) {
+    if (type === 'speech') {
+        return { text: true, attachments: null, voice: null };
+    }
+    const accept = inputs?.attachments?.accept;
+    const voiceAccept = inputs?.voice?.accept;
+    return {
+        text: inputs?.text !== false,
+        attachments: accept?.length ? { accept, acceptAttr: attachmentAcceptAttr(accept) } : null,
+        voice: voiceAccept?.length ? { accept: voiceAccept } : null,
+        maxFiles: inputs?.maxFiles,
+        maxBytes: inputs?.maxBytes,
+        maxTurnBytes: inputs?.maxTurnBytes,
+        limitsByMime: inputs?.limitsByMime,
+        slots: inputs?.slots,
+    };
+}
+function toProfileInputsSpec(inputs) {
+    return {
+        text: inputs.text,
+        attachments: inputs.attachments ? { accept: inputs.attachments.accept } : undefined,
+        voice: inputs.voice ? { accept: inputs.voice.accept } : undefined,
+        maxFiles: inputs.maxFiles,
+        maxBytes: inputs.maxBytes,
+        maxTurnBytes: inputs.maxTurnBytes,
+        limitsByMime: inputs.limitsByMime,
+        slots: inputs.slots,
+    };
+}
+function issue(code, message, fileName) {
+    return { code, message, fileName };
+}
+function validateMime(accept, files, channelLabel) {
+    const issues = [];
+    for (const file of files) {
+        if (!mimeAllowed(accept, file.mimeType)) {
+            issues.push(issue('mime_not_allowed', `${file.name}: MIME '${file.mimeType}' is not accepted for ${channelLabel} input.`, file.name));
+        }
+    }
+    return issues;
+}
+function validateLimits(files, limits) {
+    const issues = [];
+    if (files.length > limits.maxFiles) {
+        issues.push(issue('too_many_files', tooManyFilesMessage(limits.maxFiles)));
+        return issues;
+    }
+    let total = 0;
+    for (const file of files) {
+        const maxAllowed = maxBytesForMime(file.mimeType, limits);
+        if (file.sizeBytes > maxAllowed) {
+            issues.push(issue('file_too_large', fileTooLargeMessage(maxAllowed), file.name));
+        }
+        total += file.sizeBytes;
+    }
+    if (total > limits.maxTurnBytes) {
+        issues.push(issue('turn_too_large', turnTooLargeMessage(limits.maxTurnBytes)));
+    }
+    return issues;
+}
+/** Validate staged files against resolved profile `inputs`. */
+function validateProfileInputs(inputs, draft) {
+    const attachments = draft.attachments ?? [];
+    const voice = draft.voice ?? [];
+    if (attachments.length === 0 && voice.length === 0) {
+        return { ok: true, issues: [] };
+    }
+    if (attachments.length > 0 && !inputs.attachments) {
+        return {
+            ok: false,
+            issues: [issue('mime_not_allowed', 'This profile does not accept file attachments.')],
+        };
+    }
+    if (voice.length > 0 && !inputs.voice) {
+        return {
+            ok: false,
+            issues: [issue('mime_not_allowed', 'This profile does not accept voice input.')],
+        };
+    }
+    const spec = toProfileInputsSpec(inputs);
+    const issues = [];
+    if (attachments.length > 0 && inputs.attachments) {
+        issues.push(...validateMime(inputs.attachments.accept, attachments, 'attachment'));
+    }
+    if (voice.length > 0 && inputs.voice) {
+        issues.push(...validateMime(inputs.voice.accept, voice, 'voice'));
+    }
+    const limits = resolveMediaLimits(spec);
+    if (!limits) {
+        issues.push(issue('limits_unconfigured', 'This profile accepts media but does not define maxFiles, maxBytes, and maxTurnBytes.'));
+        return { ok: false, issues };
+    }
+    issues.push(...validateLimits([...attachments, ...voice], limits));
+    return { ok: issues.length === 0, issues };
+}
+function pickMediaRecorderMime(accept) {
+    const supported = (mime) => {
+        const recorder = dntShim.dntGlobalThis
+            .MediaRecorder;
+        return recorder === undefined || recorder.isTypeSupported(mime);
+    };
+    const fromCandidates = (pool) => pool.find(supported);
+    if (accept?.length) {
+        return (fromCandidates(RECORDER_CANDIDATES.filter((mime) => mimeAllowed(accept, mime))) ??
+            accept.find(supported));
+    }
+    return fromCandidates(RECORDER_CANDIDATES);
+}
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs };

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

@@ -0,0 +1,10 @@
+/**
+ * Headless profile-driven interface — spec, inputs, transcript folding.
+ *
+ * @module
+ */
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds, } from './blocks.js';
+export { interfaceFrom, interfaceFromProfile, interfaceFromProjected } from './from-profile.js';
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
+export type { AttachmentValidationCode, AttachmentValidationIssue, AttachmentValidationResult, FoldTurnEventsOptions, ImageProfileInterface, LiveProfileInterface, NormalizedModel, NormalizeModel, PendingAttachment, ProfileGuardrailsView, ProfileInputsInterface, ProfileInterface, ProfileInterfaceSource, ResolvedTools, SpeechProfileInterface, TextProfileInterface, TranscriptBlock, TranscriptBlockKind, UserTurnDraft, } from './types.js';
+export { streamThoughtsEnabled } from './types.js';

package/esm/src/interface/mod.js

@@ -0,0 +1,9 @@
+/**
+ * Headless profile-driven interface — spec, inputs, transcript folding.
+ *
+ * @module
+ */
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds, } from './blocks.js';
+export { interfaceFrom, interfaceFromProfile, interfaceFromProjected } from './from-profile.js';
+export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
+export { streamThoughtsEnabled } from './types.js';

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

@@ -0,0 +1,153 @@
+/**
+ * Headless interface contracts — profile-driven UI spec and transcript blocks.
+ *
+ * `ProfileInterface` is `Profile` with resolved `inputs`/`tools` and a serializable
+ * `guardrails` view. No parallel schema.
+ *
+ * @module
+ */
+import type { ProfileToolsSpec } from '../kernel/tools/types.js';
+import type { ControlId, GroundingEvent, ImageProfile, LiveProfile, ModelId, Profile, ProfileGuardrailsSpec, ProfileModelSpec, ProfileOutputsSpec, ProjectedProfile, ProviderEvidenceEvent, RegisteredTool, SpeechProfile, TextProfile, ToolCallEvent, ToolId, TurnStop, TurnTokens } from '../kernel/types.js';
+/** Guardrails visible to UI — egress enforcer functions are omitted. */
+export type ProfileGuardrailsView = Pick<ProfileGuardrailsSpec, 'quota' | 'canary' | 'sanitizeInput' | 'redactSensitive'> & {
+    hasEgress: boolean;
+};
+/** `profile.model` with normalized `select` / `controls`. */
+export type NormalizeModel<M extends ProfileModelSpec = ProfileModelSpec> = M & {
+    select: Record<string, ModelId> | null;
+    controls: ControlId[];
+};
+/** Resolved `inputs` — `ProfileInputsSpec` plus `acceptAttr` for file pickers. */
+export interface ProfileInputsInterface {
+    text: boolean;
+    attachments: {
+        accept: string[];
+        acceptAttr: string;
+    } | null;
+    voice: {
+        accept: string[];
+    } | null;
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+    slots?: Record<string, string[]>;
+}
+/** `profile.tools` plus resolved registry entries. */
+export type ResolvedTools = ProfileToolsSpec & {
+    resolved: Array<RegisteredTool | {
+        name: ToolId;
+        missing: true;
+    }>;
+};
+export type NormalizedModel = NormalizeModel;
+export type TextProfileInterface = Omit<TextProfile, 'inputs' | 'tools' | 'guardrails' | 'model'> & {
+    model: NormalizeModel<TextProfile['model']>;
+    inputs: ProfileInputsInterface;
+    tools: ResolvedTools;
+    guardrails?: ProfileGuardrailsView;
+};
+export type ImageProfileInterface = Omit<ImageProfile, 'inputs' | 'tools' | 'guardrails' | 'model'> & {
+    model: NormalizeModel<ImageProfile['model']>;
+    inputs: ProfileInputsInterface;
+    tools: ResolvedTools;
+    guardrails?: ProfileGuardrailsView;
+};
+export type SpeechProfileInterface = Omit<SpeechProfile, 'guardrails' | 'model'> & {
+    model: NormalizeModel<SpeechProfile['model']>;
+    inputs: ProfileInputsInterface;
+    guardrails?: ProfileGuardrailsView;
+};
+export type LiveProfileInterface = Omit<LiveProfile, 'inputs' | 'tools' | 'model' | 'guardrails'> & {
+    model: NormalizeModel<LiveProfile['model']>;
+    inputs: ProfileInputsInterface;
+    tools: ResolvedTools;
+    guardrails?: ProfileGuardrailsView;
+};
+export type ProfileInterface = TextProfileInterface | ImageProfileInterface | SpeechProfileInterface | LiveProfileInterface;
+export type ProfileInterfaceSource = Profile | ProjectedProfile;
+export type TranscriptBlockKind = 'user-text' | 'user-attachment' | 'user-voice' | 'thought' | 'text' | 'tool' | 'structured' | 'media' | 'grounding' | 'evidence' | 'error' | 'turn-done';
+export interface TranscriptBlockBase {
+    id: string;
+    kind: TranscriptBlockKind;
+}
+export interface UserTextBlock extends TranscriptBlockBase {
+    kind: 'user-text';
+    text: string;
+}
+export interface UserAttachmentBlock extends TranscriptBlockBase {
+    kind: 'user-attachment' | 'user-voice';
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+export interface ThoughtBlock extends TranscriptBlockBase {
+    kind: 'thought';
+    text: string;
+}
+export interface TextBlock extends TranscriptBlockBase {
+    kind: 'text';
+    text: string;
+}
+export interface ToolBlock extends TranscriptBlockBase {
+    kind: 'tool';
+    tool: ToolCallEvent & {
+        id?: string;
+    };
+}
+export interface StructuredBlock extends TranscriptBlockBase {
+    kind: 'structured';
+    value: unknown;
+}
+export interface MediaBlock extends TranscriptBlockBase {
+    kind: 'media';
+    mimeType: string;
+    data: string;
+}
+export interface GroundingBlock extends TranscriptBlockBase {
+    kind: 'grounding';
+    grounding: GroundingEvent;
+}
+export interface EvidenceBlock extends TranscriptBlockBase {
+    kind: 'evidence';
+    evidence: ProviderEvidenceEvent;
+}
+export interface ErrorBlock extends TranscriptBlockBase {
+    kind: 'error';
+    message: string;
+}
+export interface TurnDoneBlock extends TranscriptBlockBase {
+    kind: 'turn-done';
+    stop?: TurnStop;
+    tokens?: TurnTokens;
+    interactionId?: string;
+    compaction?: boolean;
+}
+export type TranscriptBlock = UserTextBlock | UserAttachmentBlock | ThoughtBlock | TextBlock | ToolBlock | StructuredBlock | MediaBlock | GroundingBlock | EvidenceBlock | ErrorBlock | TurnDoneBlock;
+export interface PendingAttachment {
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+export type AttachmentValidationCode = 'mime_not_allowed' | 'too_many_files' | 'file_too_large' | 'turn_too_large' | 'limits_unconfigured';
+export interface AttachmentValidationIssue {
+    code: AttachmentValidationCode;
+    message: string;
+    fileName?: string;
+}
+export interface AttachmentValidationResult {
+    ok: boolean;
+    issues: AttachmentValidationIssue[];
+}
+export interface UserTurnDraft {
+    text?: string;
+    attachments?: PendingAttachment[];
+    voice?: PendingAttachment[];
+}
+export interface FoldTurnEventsOptions {
+    showThoughts?: boolean;
+    idPrefix?: string;
+}
+/** Whether `foldTurnEvents` should emit thought blocks for this profile. */
+declare function streamThoughtsEnabled(outputs?: ProfileOutputsSpec): boolean;
+export { streamThoughtsEnabled };

package/esm/src/interface/types.js

@@ -0,0 +1,13 @@
+/**
+ * Headless interface contracts — profile-driven UI spec and transcript blocks.
+ *
+ * `ProfileInterface` is `Profile` with resolved `inputs`/`tools` and a serializable
+ * `guardrails` view. No parallel schema.
+ *
+ * @module
+ */
+/** Whether `foldTurnEvents` should emit thought blocks for this profile. */
+function streamThoughtsEnabled(outputs) {
+    return outputs?.streaming?.streamThoughts !== false;
+}
+export { streamThoughtsEnabled };

package/esm/src/kernel/engine/delta.d.ts

@@ -1,8 +1,30 @@
 import type { TurnEvent, TurnTokens } from '../types.js';
+declare function isCodeExecutionType(type: string): boolean;
+declare function isGoogleBuiltinStepType(type: string): boolean;
+declare function googleBuiltinEvidence(raw: Record<string, unknown>): TurnEvent;
+/** Merge a later code-exec delta/step onto an earlier snapshot (partial code/stdout). */
+declare function mergeCodeExecutionPayload(existing: Record<string, unknown> | undefined, incoming: Record<string, unknown>): Record<string, unknown>;
+/** Normalize a Google `code_execution_*` step/delta into an `evidence` event. */
+declare function codeExecutionEvidence(raw: Record<string, unknown>): TurnEvent;
+/** Stable key so streamed deltas and batched `steps[]` do not double-emit. */
+declare function codeExecutionStepKey(raw: Record<string, unknown>, index?: number): string;
 declare function eventsFromDelta(deltaValue: unknown): TurnEvent[];
+/**
+ * Replay a completed Interactions `steps[]` array (non-SSE or stream tail).
+ * Emits typed code-execution evidence plus model_output text/media.
+ */
+declare function eventsFromInteractionSteps(steps: unknown[], alreadyText: boolean): TurnEvent[];
 declare function groundingFromEvent(event: Record<string, unknown>): TurnEvent | undefined;
 declare function extractUsageTokens(raw: unknown): TurnTokens | undefined;
 declare function extractTokenEvent(event: Record<string, unknown>, interaction?: Record<string, unknown>): TurnEvent | undefined;
 declare function eventsFromComplete(event: Record<string, unknown>, alreadyText: boolean): TurnEvent[];
-declare function tryStructured(text: string): TurnEvent | undefined;
-export { eventsFromComplete, eventsFromDelta, extractTokenEvent, extractUsageTokens, groundingFromEvent, tryStructured, };
+export type ParsedStructuredOutput = {
+    ok: true;
+    structured: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parse model text as structured JSON. Invalid JSON is a hard failure — never silent skip. */
+declare function parseStructuredOutput(text: string): ParsedStructuredOutput;
+export { codeExecutionEvidence, codeExecutionStepKey, eventsFromComplete, eventsFromDelta, eventsFromInteractionSteps, extractTokenEvent, extractUsageTokens, googleBuiltinEvidence, groundingFromEvent, isCodeExecutionType, isGoogleBuiltinStepType, mergeCodeExecutionPayload, parseStructuredOutput, };