@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/engine/runner/stream.js

@@ -0,0 +1,225 @@
+import { isStreamedCanaryEvent } from '../../../guardrails/canary.js';
+import { CANARY_HIT, eventPromptLeakHits, isPromptLeakHit, promptLeakReason, WITHHELD_REASON, } from '../../../guardrails/egress.js';
+import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromHits } from '../../../guardrails/events.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { createOutboundProgressiveGate, } from '../../../guardrails/progressive-yield.js';
+import { thoughtGuardFor, } from '../../../guardrails/thought-guard.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
+function shouldSkipStreamEvent(event, profile) {
+    return (event.type === 'thought' && profileTurnOutputs(profile)?.streaming?.streamThoughts === false);
+}
+/** The offending text never reaches the host: redaction cannot cover a partial or encoded token. */
+function* yieldCanaryLeak(hits = [CANARY_HIT]) {
+    yield* yieldDeltaBlock(hits);
+    const reason = promptLeakReason(hits);
+    yield toErrorEvent(new TheoremError('safety', reason));
+    // The turn ends because our guardrail blocked the output, not because the model finished.
+    const native = reason === WITHHELD_REASON.canary
+        ? 'canary'
+        : reason === WITHHELD_REASON.promptEcho
+            ? 'prompt_echo'
+            : 'provider_tool_leak';
+    yield { type: 'done', stop: { kind: 'filtered', native } };
+}
+function* yieldDeltaBlock(hits) {
+    const guardrail = guardrailFromHits('output_delta', 'untrusted', hits, 'block');
+    if (guardrail) {
+        yield guardrail;
+    }
+}
+/** What the guard released, after the event saying what it omitted from it. */
+function* yieldThought({ text, hits }, event) {
+    const guardrail = guardrailFromHits('thought', 'untrusted', hits, 'redact');
+    if (guardrail)
+        yield guardrail;
+    if (text)
+        yield { ...event, text };
+}
+/** The thought held at the end of a call, and what the next call's thoughts read on from. */
+function* flushThoughts(thoughts, control) {
+    if (!thoughts)
+        return;
+    yield* yieldThought(thoughts.flush(), { type: 'thought', text: '' });
+    if (control)
+        control.thoughtCarry = thoughts.carryOut();
+}
+/** Host-visible output a mid-stream block withholds. A thought is never withheld, only omitted from. */
+function isWithheldOnBlock(event) {
+    return event.type === 'text' || event.type === 'media';
+}
+function canaryOnlyImmediateStop(policy) {
+    return !policy.egress?.enforce;
+}
+async function* yieldProviderEvents(args) {
+    const { profile, generation, request, privateSystem, provider, call, signal, control, givenUrls, } = args;
+    /** Runs one stream check and adds the run to the call's record of that check. */
+    async function timed(check, run) {
+        const start = performance.now();
+        try {
+            return await run();
+        }
+        finally {
+            call.guardTime?.(check, performance.now() - start);
+        }
+    }
+    const { canary } = generation;
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const context = {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(profile.lexicon ? { lexicon: profile.lexicon } : {}),
+        ...(canary ? { canary } : {}),
+        // The system prompt is guarded against echo alongside the canary that binds it.
+        ...(canary && policy.promptEcho && privateSystem.length > 0 ? { privateSystem } : {}),
+        givenUrls,
+    };
+    const { canaryCarry, thoughtCarry } = control ?? {};
+    const gate = createOutboundProgressiveGate(policy, context, canaryCarry);
+    const thoughts = thoughtGuardFor(policy.egress?.enforce, context, thoughtCarry);
+    /** The streamed event whose reply sits in the gate's lookback; released tails keep its shape. */
+    let pendingStream = null;
+    let withholdVisible = false;
+    /**
+     * Under a host policy a withheld system-prompt leak goes to the
+     * end-of-attempt verdict, which it pins to block: no verdict may release it.
+     */
+    function recordPromptLeak(hits) {
+        const leaks = hits.filter(isPromptLeakHit);
+        if (control && leaks.length > 0)
+            control.promptLeaks = leaks;
+    }
+    function armWithhold() {
+        withholdVisible = true;
+        if (control)
+            control.withholdVisible = true;
+    }
+    function withholding() {
+        return withholdVisible;
+    }
+    async function* drainBlockedDelta(hits, template) {
+        yield* yieldDeltaBlock(hits);
+        // Arm withhold before recording the unreleased tail so the step runner
+        // does not forward that text to the host.
+        armWithhold();
+        const tail = gate?.drainUnreleased();
+        if (tail)
+            yield { ...template, text: tail };
+    }
+    async function* flushGate() {
+        if (!(gate && pendingStream)) {
+            return 'pass';
+        }
+        const template = pendingStream;
+        const result = await timed('output_stream', () => gate.flush());
+        pendingStream = null;
+        return (yield* releaseOrBlock(result, template)) === 'stop' ? 'stop' : 'pass';
+    }
+    /**
+     * Act on one gate step: release what it cleared, or block — stopping the turn
+     * when no host policy decides later, otherwise withholding for its verdict.
+     */
+    async function* releaseOrBlock(result, template) {
+        if (result.blocked) {
+            if (canary && canaryOnlyImmediateStop(policy)) {
+                yield* yieldCanaryLeak(result.hits);
+                return 'stop';
+            }
+            recordPromptLeak(result.hits);
+            yield* drainBlockedDelta(result.hits, template);
+            return 'go';
+        }
+        if (result.emit) {
+            yield { ...template, text: result.emit };
+        }
+        return 'go';
+    }
+    async function* gateStreamEvent(event) {
+        if (!gate) {
+            yield event;
+            return 'continue';
+        }
+        if (withholding()) {
+            // Keep recording ungated fragments for egress context; host will not see them.
+            yield { ...event, text: event.text ?? '' };
+            return 'continue';
+        }
+        pendingStream = event;
+        const result = await timed('output_stream', () => gate.process(event.text ?? ''));
+        return (yield* releaseOrBlock(result, event)) === 'stop' ? 'stop' : 'continue';
+    }
+    /** Whether a thought has streamed since the guard last flushed. */
+    let thinking = false;
+    /** A thought, through the guard when there is one; false for any other event. */
+    function* guardThought(event) {
+        if (event.type !== 'thought' || !thoughts)
+            return false;
+        thinking = true;
+        yield* yieldThought(thoughts.push(event.text), event);
+        return true;
+    }
+    /** The reply ends the thought: release its hold, as a call's end does, reading on from the carry. */
+    function* endThought() {
+        if (!thinking)
+            return;
+        thinking = false;
+        yield* flushThoughts(thoughts, control);
+    }
+    throwIfAborted(signal);
+    let providerFailed = false;
+    for await (const event of provider.complete({ ...request, signal, tapUpstream: call.tap })) {
+        call.observe(event);
+        throwIfAborted(signal);
+        if (event.type === 'response') {
+            // Identity is the trace's alone; the call span already recorded it.
+            continue;
+        }
+        if (yield* guardThought(event))
+            continue;
+        if (isStreamedCanaryEvent(event)) {
+            yield* endThought();
+            const status = yield* gateStreamEvent(event);
+            if (status === 'stop') {
+                return;
+            }
+            continue;
+        }
+        // Release held reply text first so the host sees events in order.
+        const flushed = yield* flushGate();
+        if (flushed === 'stop') {
+            return;
+        }
+        const leaks = canary
+            ? await timed('stream_canary', () => eventPromptLeakHits(event, canary, context.privateSystem))
+            : [];
+        if (leaks.length > 0) {
+            yield* yieldCanaryLeak(leaks);
+            return;
+        }
+        if (withholding() && isWithheldOnBlock(event)) {
+            // Record for attempt egress / repair; step runner withholds from host.
+            yield event;
+            continue;
+        }
+        if (event.type === 'error') {
+            providerFailed = true;
+        }
+        if (event.type === 'done')
+            yield* flushThoughts(thoughts, control);
+        yield event;
+    }
+    yield* flushThoughts(thoughts, control);
+    const flushed = yield* flushGate();
+    if (flushed === 'stop') {
+        return;
+    }
+    if (control && gate) {
+        control.canaryCarry = gate.carryOut();
+    }
+    if (providerFailed) {
+        // An error from the provider outranks any `done` it sent: the call's output is not whole.
+        yield { type: 'done', stop: { kind: 'provider_error' } };
+    }
+}
+export { isWithheldOnBlock, shouldSkipStreamEvent, yieldProviderEvents };

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

@@ -0,0 +1,45 @@
+import type { ToolCallRequest } from '../../tools/types.js';
+import type { InteractionPart, ProviderEvent, ResolvedGeneration, TurnEventOf, TurnHistoryMessage, TurnTokens } from '../../types.js';
+import { type MediaTokenFamily, type TokenCount } from '../token-estimate.js';
+type CallConversation = {
+    history: TurnHistoryMessage[];
+    input: InteractionPart[];
+} | {
+    previous: CallUsage;
+    continuation: TurnHistoryMessage[];
+};
+/** What a call wrote that the output estimate counts: text, thoughts, media, and its tool calls. */
+export type CallOutput = TurnEventOf<'text' | 'thought' | 'media'> | {
+    type: 'tool';
+    tool: ToolCallRequest;
+};
+interface CallUsage {
+    system: string;
+    /** Copied before the stream: the runner mutates history as tools run. */
+    conversation: CallConversation;
+    /** Context the provider already holds from earlier calls (a Live session). */
+    held?: TokenCount;
+    /** Last usage the provider reported for this call. */
+    reported?: TurnTokens;
+    output: CallOutput[];
+    failed: boolean;
+}
+declare function startCallUsage(system: string, conversation: CallConversation, held?: TokenCount): CallUsage;
+/**
+ * Record one provider event. Returns true for a `tokens` event, which the
+ * runner holds instead of streaming; `callTokensEvent` emits it at call end.
+ */
+declare function observeCallEvent(usage: CallUsage, event: ProviderEvent): boolean;
+/**
+ * What the provider holds once `usage`'s call has ended: what it held before,
+ * what was sent for the call, and the call's output (not thoughts), counted
+ * as a continuation replays it.
+ */
+declare function heldAfter(usage: CallUsage, family: MediaTokenFamily | undefined): Promise<TokenCount>;
+/**
+ * `undefined` when the call failed with no usage: what was billed is unknown, and an estimate would
+ * claim a completed read.
+ */
+declare function callTokensEvent(usage: CallUsage, generation: ResolvedGeneration, family: MediaTokenFamily | undefined): Promise<TurnEventOf<'tokens'> | undefined>;
+export type { CallConversation, CallUsage };
+export { callTokensEvent, heldAfter, observeCallEvent, startCallUsage };

package/esm/src/kernel/engine/runner/usage.js

@@ -0,0 +1,150 @@
+import { loadTokenEstimator } from '../token-estimate.js';
+function startCallUsage(system, conversation, held) {
+    return {
+        system,
+        ...(held ? { held } : {}),
+        conversation: 'previous' in conversation
+            ? { previous: conversation.previous, continuation: [...conversation.continuation] }
+            : { history: [...conversation.history], input: [...conversation.input] },
+        output: [],
+        failed: false,
+    };
+}
+/**
+ * Record one provider event. Returns true for a `tokens` event, which the
+ * runner holds instead of streaming; `callTokensEvent` emits it at call end.
+ */
+function observeCallEvent(usage, event) {
+    switch (event.type) {
+        case 'tokens':
+            usage.reported = event.tokens;
+            return true;
+        case 'error':
+            usage.failed = true;
+            return false;
+        case 'tool':
+            // The model wrote its call; a provider's phase event about it (a malformed call's failure) it did not.
+            if (event.tool.phase === undefined)
+                usage.output.push({ type: 'tool', tool: event.tool });
+            return false;
+        case 'text':
+        case 'thought':
+        case 'media':
+            usage.output.push(event);
+            return false;
+        default:
+            return false;
+    }
+}
+function addCounts(a, b) {
+    return { tokens: a.tokens + b.tokens, unknownMedia: a.unknownMedia + b.unknownMedia };
+}
+/**
+ * The output's streamed text as the model wrote it: consecutive chunks of one
+ * kind joined, so the estimate does not depend on how the stream was split.
+ */
+function textRuns(output, thoughts) {
+    const runs = [];
+    let kind;
+    for (const event of output) {
+        if (event.type === 'tool' || event.type === 'media') {
+            kind = undefined;
+        }
+        else if (event.text && (thoughts || event.type !== 'thought')) {
+            if (event.type === kind) {
+                runs.push(`${runs.pop() ?? ''}${event.text}`);
+            }
+            else {
+                runs.push(event.text);
+                kind = event.type;
+            }
+        }
+    }
+    return runs;
+}
+/** Output events counted; thoughts only when counting what the model wrote. */
+async function countOutput(usage, thoughts) {
+    const estimator = await loadTokenEstimator();
+    const count = { tokens: 0, unknownMedia: 0 };
+    for (const event of usage.output) {
+        if (event.type === 'media') {
+            count.unknownMedia += 1;
+        }
+        else if (event.type === 'tool') {
+            count.tokens +=
+                estimator.text(event.tool.name) + estimator.text(JSON.stringify(event.tool.arguments));
+        }
+    }
+    for (const run of textRuns(usage.output, thoughts)) {
+        count.tokens += estimator.text(run);
+    }
+    return count;
+}
+async function countConversation(usage, family) {
+    const estimator = await loadTokenEstimator();
+    const { conversation } = usage;
+    if ('previous' in conversation) {
+        const earlier = await countConversation(conversation.previous, family);
+        const replayed = await countOutput(conversation.previous, false);
+        const continuation = await estimator.messages(conversation.continuation, family);
+        return addCounts(addCounts(earlier, replayed), continuation);
+    }
+    const history = await estimator.messages(conversation.history, family);
+    const sent = addCounts(history, await estimator.parts(conversation.input, family));
+    return usage.held ? addCounts(usage.held, sent) : sent;
+}
+/**
+ * What the provider holds once `usage`'s call has ended: what it held before,
+ * what was sent for the call, and the call's output (not thoughts), counted
+ * as a continuation replays it.
+ */
+async function heldAfter(usage, family) {
+    return addCounts(await countConversation(usage, family), await countOutput(usage, false));
+}
+async function countPrompt(usage, generation, family) {
+    const estimator = await loadTokenEstimator();
+    const wire = generation.tools.wire;
+    const tools = wire.length > 0 ? estimator.text(JSON.stringify(wire)) : 0;
+    const schema = generation.structured
+        ? estimator.text(JSON.stringify(generation.structured.jsonSchema))
+        : 0;
+    const conversation = await countConversation(usage, family);
+    return {
+        tokens: estimator.text(usage.system) + tools + schema + conversation.tokens,
+        unknownMedia: conversation.unknownMedia,
+    };
+}
+/**
+ * `undefined` when the call failed with no usage: what was billed is unknown, and an estimate would
+ * claim a completed read.
+ */
+async function callTokensEvent(usage, generation, family) {
+    const reported = usage.reported;
+    if (!reported && usage.failed)
+        return undefined;
+    const estimated = reported ? (reported.estimated ?? []) : ['input', 'output'];
+    if (reported && estimated.length === 0)
+        return { type: 'tokens', tokens: reported };
+    const prompt = estimated.includes('input')
+        ? await countPrompt(usage, generation, family)
+        : undefined;
+    const written = estimated.includes('output') ? await countOutput(usage, true) : undefined;
+    const input = prompt?.tokens ?? reported?.input ?? 0;
+    const output = written?.tokens ?? reported?.output ?? 0;
+    const unknownMedia = {
+        ...(prompt?.unknownMedia ? { input: prompt.unknownMedia } : {}),
+        ...(written?.unknownMedia ? { output: written.unknownMedia } : {}),
+    };
+    return {
+        type: 'tokens',
+        tokens: {
+            ...reported,
+            input,
+            output,
+            total: input + output,
+            estimated: [...estimated],
+            ...(Object.keys(unknownMedia).length > 0 ? { unknownMedia } : {}),
+        },
+    };
+}
+export { callTokensEvent, heldAfter, observeCallEvent, startCallUsage };

package/esm/src/kernel/engine/session/mod.d.ts

@@ -0,0 +1,31 @@
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { GeminiOptions } from '../../../providers/google/keys.js';
+import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import type { KeyVault, LiveSession, SessionRequest } from '../../types.js';
+export type { LiveSession, SessionRequest };
+export interface RunSessionOptions {
+    /** The host's keys by slot; the session uses the slots its profile names. */
+    vault: KeyVault;
+    gemini?: GeminiOptions;
+    /** Override socket open (Cloudflare fetch-upgrade, tests). Default: `new WebSocket(url)`. */
+    openWebSocket?: (url: string) => Promise<WebSocket>;
+    /**
+     * Milliseconds a gated call waits for its decision (default 30 minutes). A later decision is
+     * refused (`session.gate_expired`), and the model reads the call as abandoned.
+     */
+    gateTtlMs?: number;
+    /**
+     * `hold` (default): a sign-in gate waits for its decision, as any gate does. `answer`: the
+     * model reads the gate's pending note at once and the call is released, for a host whose
+     * sign-in finishes outside the session. A released call still takes its outcome for
+     * `gateTtlMs` (`executeTool` with a decision, or `answerToolCall`), which the model reads as
+     * the call's next result; unanswered by then, the model reads that the sign-in expired.
+     */
+    signInGate?: SignInGatePolicy;
+}
+export type SignInGatePolicy = 'hold' | 'answer';
+/**
+ * The session record is written however the session ends, including when opening fails. An unknown
+ * profile fails to open and is recorded under the standard observability policy.
+ */
+export declare function runSessionInRegistry(registry: KernelRegistry, req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;