theorum 0.1.2

package/esm/src/kernel/engine/delta.js

@@ -0,0 +1,362 @@
+import { asRecord } from './record.js';
+function deltaText(delta) {
+    if (typeof delta.text === 'string') {
+        return delta.text;
+    }
+    const { content } = delta;
+    if (typeof content === 'string') {
+        return content;
+    }
+    const nested = asRecord(content);
+    if (nested && typeof nested.text === 'string') {
+        return nested.text;
+    }
+    return '';
+}
+function deltaMedia(delta) {
+    const mimeType = delta.mimeType ?? delta.mime_type;
+    const { data } = delta;
+    if (typeof mimeType === 'string' && typeof data === 'string' && data) {
+        return { type: 'media', media: { mimeType, data } };
+    }
+    return undefined;
+}
+function eventIfText(type, delta) {
+    const text = deltaText(delta);
+    if (!text) {
+        return [];
+    }
+    return [{ type, text }];
+}
+function eventsFromImage(delta) {
+    const media = deltaMedia(delta);
+    if (media) {
+        return [media];
+    }
+    return [];
+}
+function eventsFromDelta(deltaValue) {
+    const delta = asRecord(deltaValue);
+    if (!delta) {
+        return [];
+    }
+    const deltaType = String(delta.type ?? '');
+    if (deltaType === 'thought_summary' || deltaType === 'thought') {
+        return eventIfText('thought', delta);
+    }
+    if (deltaType === 'text') {
+        return eventIfText('text', delta);
+    }
+    if (deltaType === 'image') {
+        return eventsFromImage(delta);
+    }
+    return [];
+}
+function mediaFromRecord(rec) {
+    const mimeType = rec.mimeType ?? rec.mime_type;
+    const { data } = rec;
+    if (typeof mimeType === 'string' && typeof data === 'string' && data) {
+        return { type: 'media', media: { mimeType, data } };
+    }
+    return undefined;
+}
+function mediaFromOutputItem(item) {
+    const rec = asRecord(item);
+    if (!rec) {
+        return undefined;
+    }
+    if (rec.type !== 'image' && rec.type !== 'media') {
+        return undefined;
+    }
+    return mediaFromRecord(rec);
+}
+function mediaFromOutputs(outputs) {
+    if (!Array.isArray(outputs)) {
+        return undefined;
+    }
+    for (const item of outputs) {
+        const media = mediaFromOutputItem(item);
+        if (media) {
+            return media;
+        }
+    }
+    return undefined;
+}
+function mediaFromComplete(event) {
+    const interaction = asRecord(event.interaction) ?? event;
+    const direct = asRecord(interaction.output_image);
+    if (direct) {
+        const media = mediaFromRecord(direct);
+        if (media) {
+            return media;
+        }
+    }
+    return mediaFromOutputs(interaction.outputs);
+}
+function sourceFromMaps(maps) {
+    const uri = maps.uri ?? maps.googleMapsUri ?? maps.google_maps_uri;
+    if (typeof uri !== 'string' || !uri) {
+        return undefined;
+    }
+    const title = maps.title ?? maps.name;
+    return {
+        type: 'maps',
+        uri,
+        title: typeof title === 'string' && title ? title : uri,
+    };
+}
+function sourceFromWeb(web) {
+    const uri = web.uri;
+    if (typeof uri !== 'string' || !uri) {
+        return undefined;
+    }
+    const title = web.title ?? web.domain;
+    return {
+        type: 'web',
+        uri,
+        title: typeof title === 'string' && title ? title : uri,
+    };
+}
+function pushUniqueSource(sources, source) {
+    if (!source) {
+        return;
+    }
+    if (!sources.some((item) => item.uri === source.uri && item.type === source.type)) {
+        sources.push(source);
+    }
+}
+function groundingChunks(metadata) {
+    const chunks = metadata.groundingChunks ?? metadata.grounding_chunks;
+    if (Array.isArray(chunks)) {
+        return chunks;
+    }
+    return [];
+}
+function searchHtml(metadata) {
+    const searchEntryPoint = asRecord(metadata.searchEntryPoint ?? metadata.search_entry_point);
+    const renderedContent = searchEntryPoint?.renderedContent ?? searchEntryPoint?.rendered_content;
+    if (typeof renderedContent === 'string' && renderedContent.trim()) {
+        return renderedContent;
+    }
+    return undefined;
+}
+function sourcesFromChunks(chunks) {
+    const sources = [];
+    for (const chunk of chunks) {
+        const record = asRecord(chunk);
+        if (!record) {
+            continue;
+        }
+        const maps = asRecord(record.maps);
+        if (maps) {
+            pushUniqueSource(sources, sourceFromMaps(maps));
+        }
+        const web = asRecord(record.web);
+        if (web) {
+            pushUniqueSource(sources, sourceFromWeb(web));
+        }
+    }
+    return sources;
+}
+function mergeGrounding(a, b) {
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    const chunks = [...(a.chunks ?? []), ...(b.chunks ?? [])];
+    const sources = [...a.sources];
+    for (const source of b.sources) {
+        pushUniqueSource(sources, source);
+    }
+    return {
+        metadata: b.metadata ?? a.metadata,
+        ...(chunks.length > 0 ? { chunks } : {}),
+        searchHtml: b.searchHtml ?? a.searchHtml,
+        sources,
+    };
+}
+function groundingFromMetadata(metadataValue) {
+    const metadata = asRecord(metadataValue);
+    if (!metadata) {
+        return undefined;
+    }
+    const chunks = groundingChunks(metadata);
+    const sources = sourcesFromChunks(chunks);
+    const html = searchHtml(metadata);
+    if (chunks.length === 0 && sources.length === 0 && !html) {
+        return { metadata, sources };
+    }
+    return {
+        metadata,
+        ...(chunks.length > 0 ? { chunks } : {}),
+        ...(html ? { searchHtml: html } : {}),
+        sources,
+    };
+}
+function groundingMetadataFromRecord(record) {
+    return record.groundingMetadata ?? record.grounding_metadata;
+}
+function groundingFromStep(stepValue) {
+    const step = asRecord(stepValue);
+    if (!step) {
+        return undefined;
+    }
+    let grounding = groundingFromMetadata(groundingMetadataFromRecord(step));
+    const content = step.content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            grounding = mergeGrounding(grounding, groundingFromMetadata(groundingMetadataFromRecord(asRecord(block) ?? {})));
+        }
+    }
+    return grounding;
+}
+function groundingFromEvent(event) {
+    let grounding = groundingFromMetadata(groundingMetadataFromRecord(event));
+    grounding = mergeGrounding(grounding, groundingFromStep(event.step));
+    grounding = mergeGrounding(grounding, groundingFromStep(event.delta));
+    const interaction = asRecord(event.interaction);
+    if (interaction) {
+        grounding = mergeGrounding(grounding, groundingFromMetadata(groundingMetadataFromRecord(interaction)));
+    }
+    const steps = interaction?.steps;
+    if (Array.isArray(steps)) {
+        for (const step of steps) {
+            grounding = mergeGrounding(grounding, groundingFromStep(step));
+        }
+    }
+    if (!grounding) {
+        return undefined;
+    }
+    return { type: 'grounding', grounding };
+}
+const INPUT_KEYS = [
+    'total_input_tokens',
+    'totalInputTokens',
+    'prompt_token_count',
+    'promptTokenCount',
+    'prompt_tokens',
+    'input_tokens',
+    'inputTokens',
+    'input',
+];
+const OUTPUT_KEYS = [
+    'total_output_tokens',
+    'totalOutputTokens',
+    'candidates_token_count',
+    'candidatesTokenCount',
+    'candidates_tokens',
+    'completion_tokens',
+    'output_tokens',
+    'outputTokens',
+    'output',
+];
+const THINKING_KEYS = [
+    'total_thought_tokens',
+    'totalThoughtTokens',
+    'thoughts_token_count',
+    'thoughtsTokenCount',
+    'thoughts_tokens',
+    'thinking_tokens',
+    'thinkingTokens',
+    'thinking',
+];
+const TOOL_KEYS = [
+    'total_tool_use_tokens',
+    'totalToolUseTokens',
+    'tool_use_token_count',
+    'toolUseTokenCount',
+    'tool_tokens',
+    'toolTokens',
+    'toolUse',
+];
+const TOTAL_KEYS = [
+    'total_tokens',
+    'totalTokens',
+    'total_token_count',
+    'totalTokenCount',
+    'total',
+];
+function pickNumericField(record, keys) {
+    for (const key of keys) {
+        const val = record[key];
+        if (val !== undefined && val !== null) {
+            const n = Number(val);
+            if (!Number.isNaN(n)) {
+                return n;
+            }
+        }
+    }
+    return 0;
+}
+function extractUsageTokens(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return undefined;
+    }
+    const r = raw;
+    const input = pickNumericField(r, INPUT_KEYS);
+    const output = pickNumericField(r, OUTPUT_KEYS);
+    const thinking = pickNumericField(r, THINKING_KEYS);
+    const toolUse = pickNumericField(r, TOOL_KEYS);
+    const total = pickNumericField(r, TOTAL_KEYS) || input + output + thinking + toolUse;
+    if (input > 0 || output > 0 || thinking > 0 || toolUse > 0 || total > 0) {
+        return { input, output, thinking, toolUse, total };
+    }
+    return undefined;
+}
+const USAGE_KEYS = ['usage', 'usage_metadata', 'usageMetadata'];
+function findUsageObject(target, event) {
+    for (const key of USAGE_KEYS) {
+        if (target[key])
+            return target[key];
+    }
+    for (const key of USAGE_KEYS) {
+        if (event[key])
+            return event[key];
+    }
+    return undefined;
+}
+function extractTokenEvent(event, interaction) {
+    const target = interaction ?? asRecord(event.interaction) ?? event;
+    const usage = extractUsageTokens(findUsageObject(target, event));
+    const interactionId = typeof target.id === 'string' ? target.id : undefined;
+    if (!usage) {
+        return undefined;
+    }
+    return {
+        type: 'tokens',
+        tokens: usage,
+        ...(interactionId ? { interactionId } : {}),
+    };
+}
+function eventsFromComplete(event, alreadyText) {
+    const interaction = asRecord(event.interaction) ?? event;
+    const outputText = interaction.output_text;
+    const events = [];
+    if (!alreadyText && typeof outputText === 'string' && outputText) {
+        events.push({ type: 'text', text: outputText });
+    }
+    const media = mediaFromComplete(event);
+    if (media) {
+        events.push(media);
+    }
+    const tokenEvent = extractTokenEvent(event, interaction);
+    if (tokenEvent) {
+        events.push(tokenEvent);
+    }
+    const groundingEvent = groundingFromEvent(event);
+    if (groundingEvent) {
+        events.push(groundingEvent);
+    }
+    return events;
+}
+function tryStructured(text) {
+    try {
+        return { type: 'structured', structured: JSON.parse(text) };
+    }
+    catch {
+        return undefined;
+    }
+}
+export { eventsFromComplete, eventsFromDelta, extractTokenEvent, extractUsageTokens, groundingFromEvent, tryStructured, };

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

@@ -0,0 +1 @@
+export declare function sha256(text: string): Promise<string>;

package/esm/src/kernel/engine/hash.js

@@ -0,0 +1,9 @@
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+function hexSha256(bytes) {
+    return [...bytes].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+}
+export async function sha256(text) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hexSha256(new Uint8Array(buf));
+}

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

@@ -0,0 +1,2 @@
+declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export { asRecord };

package/esm/src/kernel/engine/record.js

@@ -0,0 +1,7 @@
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+export { asRecord };

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

@@ -0,0 +1,9 @@
+import type { Profile, TurnHistoryMessage, TurnRepairRequest } from '../types.js';
+declare const MAX_REPAIR_HISTORY_EXCHANGES = 2;
+declare function scopeHistory(history: TurnHistoryMessage[] | undefined): TurnHistoryMessage[];
+declare function synthesizeRepairPrompt(args: {
+    profile: Profile;
+    repair: TurnRepairRequest;
+    history?: TurnHistoryMessage[];
+}): string;
+export { MAX_REPAIR_HISTORY_EXCHANGES, scopeHistory, synthesizeRepairPrompt };

package/esm/src/kernel/engine/repair.js

@@ -0,0 +1,38 @@
+const MAX_REPAIR_HISTORY_EXCHANGES = 2;
+const MAX_REPAIR_HISTORY_MESSAGES = MAX_REPAIR_HISTORY_EXCHANGES * 2;
+function scopeHistory(history) {
+    if (!history || history.length === 0) {
+        return [];
+    }
+    return history.slice(-MAX_REPAIR_HISTORY_MESSAGES);
+}
+function formatHistoryBlock(messages) {
+    if (messages.length === 0) {
+        return '';
+    }
+    const lines = messages.map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`);
+    return `### RECENT CONVERSATION CONTEXT (LAST ${messages.length} TURNS)\n${lines.join('\n')}\n\n`;
+}
+function synthesizeRepairPrompt(args) {
+    const { profile, repair, history } = args;
+    const guidance = repair.guidance ||
+        profile.outputs.validation?.repairGuidance ||
+        'Revise the previous output so it satisfies the validator rejection. Preserve the intended user-facing substance unless the guidance says otherwise.';
+    const historyBlock = formatHistoryBlock(scopeHistory(history));
+    let prompt = `## OUTPUT REPAIR REQUEST\n\n`;
+    prompt += `The previous assistant output was rejected by a host validator and must be revised.\n\n`;
+    prompt += `### PREVIOUS OUTPUT\n\`\`\`\n${repair.previousOutput.trim()}\n\`\`\`\n\n`;
+    prompt += `### VALIDATOR REJECTION\n${repair.rejection.trim()}\n\n`;
+    if (guidance.trim()) {
+        prompt += `### REPAIR GUIDANCE\n${guidance.trim()}\n\n`;
+    }
+    if (historyBlock) {
+        prompt += historyBlock;
+    }
+    prompt += `### INSTRUCTIONS\n`;
+    prompt += `1. Inspect the previous output and validator rejection.\n`;
+    prompt += `2. Apply the repair guidance without inventing unsupported facts.\n`;
+    prompt += `3. Return only the corrected assistant output required by the active profile.`;
+    return prompt;
+}
+export { MAX_REPAIR_HISTORY_EXCHANGES, scopeHistory, synthesizeRepairPrompt };

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

@@ -0,0 +1,14 @@
+/**
+ * Deterministic turn runner for THEORUM.
+ *
+ * `runTurn` resolves a profile, sanitizes input, binds canary boundaries,
+ * streams provider events, executes allowed tools, applies validation and
+ * egress repair loops, writes traces, and emits one terminal `done` event.
+ *
+ * @module
+ */
+import { type TraceSink } from '../../observability/trace.js';
+import type { ModelProvider, TurnEvent, TurnRequest } from '../types.js';
+/** Execute one host turn against a provider adapter. */
+declare function runTurn(req: TurnRequest, provider: ModelProvider, sink?: TraceSink): AsyncGenerator<TurnEvent>;
+export { runTurn };