@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,376 @@
+import { isStreamedCanaryEvent } from '../../../guardrails/canary.js';
+import { detectEvent, leakScopeOf } from '../../../guardrails/detect-at.js';
+import { eventLeak, isPromptLeakHit, promptLeakReason, WITHHELD_REASON, } from '../../../guardrails/egress.js';
+import { TheoremError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
+import { guardrailFromHits, guardrailTurnEvent } from '../../../guardrails/events.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { createDraftGate, createOutboundProgressiveGate, DraftReader, } from '../../../guardrails/progressive-yield.js';
+import { EGRESS_RULES } from '../../../guardrails/rules.js';
+import { thoughtGuardFor, } from '../../../guardrails/thought-guard.js';
+import { profileTurnOutputs } from '../../registry/profile-outputs.js';
+import { toolArgumentsBoundary } from '../../tools/execute.js';
+function shouldSkipStreamEvent(event, profile) {
+    return (event.type === 'thought' && profileTurnOutputs(profile)?.streaming?.streamThoughts === false);
+}
+/**
+ * A leak in an event that is not the reply's text ends the turn there: the
+ * event never reaches the host, and it has no text to replace.
+ */
+function* yieldLeakStop(hits) {
+    if (hits.some((hit) => hit.rule === EGRESS_RULES.providerToolLeak)) {
+        yield* yieldDeltaBlock(hits);
+    }
+    else {
+        yield* yieldDetected('reply', { action: 'block', hits });
+    }
+    const reason = promptLeakReason(hits);
+    yield toErrorEvent(new TheoremError('safety', reason));
+    // why: 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 `guardrails.detect` found at `boundary` in text released as it streamed. */
+function* yieldDetected(boundary, found) {
+    const event = found && detectEvent(boundary, found, undefined, STREAMED_STAGE[boundary]);
+    if (event)
+        yield guardrailTurnEvent(event);
+}
+/** The stage a boundary reports under while its text streams, where that is not its own. */
+const STREAMED_STAGE = { reply: 'output_delta' };
+/** What the guard released, after the events saying what was found in it and omitted from it. */
+function* yieldThought({ text, hits, found }, event) {
+    yield* yieldDetected('thought', found);
+    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';
+}
+/**
+ * An event as the host gets it, or nothing. The text of a call that asked for structured output is
+ * that output's JSON: under `sse` it goes out as `structured_draft`, and under `buffered` not at all,
+ * since the `structured` event is the reply whole. The turn keeps it as text, which its checks,
+ * repairs and history read.
+ */
+function shownToHost(event, generation) {
+    if (!generation.structured || event.type !== 'text')
+        return event;
+    return generation.stream === false ? undefined : { type: 'structured_draft', text: event.text };
+}
+/**
+ * A step's events as the host gets them (`shownToHost`), with a structured reply's drafts read
+ * first at `reply_structured`, where the whole is read. The reply's text has already passed the
+ * `reply` gate; a match at `reply_structured` stops the drafts, and the `structured` event still
+ * arrives as that check leaves it. The held tail is read and released when the step's stream ends.
+ */
+class StructuredDrafts {
+    drafts;
+    generation;
+    /** Reads the stream's own checks off what the step knows of the turn. */
+    constructor(seen) {
+        const policy = resolveGuardrailPolicy(seen.profile.guardrails);
+        const context = streamContext(seen, policy);
+        this.drafts = new DraftReader(() => createDraftGate(policy, context, 'reply_structured'));
+        this.generation = seen.generation;
+    }
+    async *show(event) {
+        const shown = shownToHost(event, this.generation);
+        if (shown?.type !== 'structured_draft') {
+            if (shown)
+                yield shown;
+            return;
+        }
+        const text = await this.drafts.read(shown.text);
+        if (text)
+            yield { ...shown, text };
+    }
+    /** The drafts' tail the gate still holds, once the step's stream has ended. */
+    *end() {
+        const text = this.drafts.end();
+        if (text)
+            yield { type: 'structured_draft', text };
+    }
+}
+/**
+ * Events read at a boundary of their own, not with the reply's text: the
+ * model's tool call at its `tool_arguments` boundary, and the structured
+ * output at `reply_structured`.
+ */
+function isReadElsewhere(event) {
+    return event.type === 'structured' || event.type === 'tool';
+}
+/**
+ * The tool calls the model is drafting, each through a gate of its own at the boundary its call is
+ * read at (`createDraftGate`). A draft is a preview: one its gate stops, or whose tool's name
+ * changes, shows nothing more, and the call itself is still read whole. A draft's gate closes when
+ * its call arrives; its held tail is not released, because the call shows all of it.
+ */
+class ToolDrafts {
+    policy;
+    context;
+    tools;
+    drafts = new Map();
+    constructor(policy, context, tools) {
+        this.policy = policy;
+        this.context = context;
+        this.tools = tools;
+    }
+    /**
+     * Shows `event` when it is a draft and says whether it was; any other event closes its call's
+     * draft. Nothing shows while the reply is `withheld`.
+     */
+    async *take(event, withheld, timed) {
+        if (event.type !== 'tool_draft') {
+            this.close(event);
+            return false;
+        }
+        // why: A withheld reply is judged whole when its attempt ends; nothing more of it previews before then.
+        if (!withheld)
+            yield* this.release(event, timed);
+        return true;
+    }
+    async *release(event, timed) {
+        const draft = this.drafts.get(event.callId) ?? (await this.open(event));
+        if (draft === 'stopped')
+            return;
+        if (draft.name !== event.name) {
+            this.drafts.set(event.callId, 'stopped');
+            return;
+        }
+        if (!draft.gate) {
+            yield event;
+            return;
+        }
+        const { gate } = draft;
+        // why: What the gate finds is reported once, by the check on the whole call.
+        const result = await timed('tool_draft', () => gate.process(event.text));
+        if (result.blocked) {
+            this.drafts.set(event.callId, 'stopped');
+            return;
+        }
+        if (result.emit)
+            yield { ...event, text: result.emit };
+    }
+    close(event) {
+        if (event.type === 'tool')
+            this.drafts.delete(event.tool.callId);
+    }
+    async open(event) {
+        const boundary = toolArgumentsBoundary(this.tools, event.name);
+        const gate = boundary ? await createDraftGate(this.policy, this.context, boundary) : null;
+        const draft = { name: event.name, gate };
+        this.drafts.set(event.callId, draft);
+        return draft;
+    }
+}
+/** What the stream's checks know of the turn. */
+function streamContext(args, policy) {
+    const { profile, privateSystem, canaryGiven } = args;
+    const { canary } = args.generation;
+    return {
+        stage: 'output_final',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(profile.labels ? { labels: profile.labels } : {}),
+        ...leakScopeOf(policy.detect, { canary, canaryGiven, privateSystem }),
+        givenUrls: args.givenUrls,
+        ...(args.ownTools ? { ownTools: args.ownTools } : {}),
+    };
+}
+async function* yieldProviderEvents(args) {
+    const { profile, request, provider, call, signal, control } = 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 policy = resolveGuardrailPolicy(profile.guardrails);
+    const context = streamContext(args, policy);
+    const { canaryCarry, thoughtCarry } = control ?? {};
+    const gate = await createOutboundProgressiveGate(policy, context, 'reply', canaryCarry);
+    const thoughts = await thoughtGuardFor(policy, context, thoughtCarry);
+    const drafts = new ToolDrafts(policy, context, args.tools);
+    /** The streamed event whose reply sits in the gate's lookback; released tails keep its shape. */
+    let pendingStream = null;
+    let withholdVisible = false;
+    /**
+     * A leak the gate stopped on goes to the end-of-attempt verdict, which reads
+     * the whole reply for it: one that reading misses still blocks.
+     */
+    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);
+        // why: 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 withhold the rest of the
+     * reply for the verdict on the whole of it.
+     */
+    async function* releaseOrBlock(result, template) {
+        if (result.blocked) {
+            recordPromptLeak(result.hits);
+            // why: A detector's stop is reported once, by the verdict on the whole reply. The trace
+            // still records that this check is the one that stopped it.
+            const stopped = result.boundary &&
+                detectEvent(result.boundary, { action: 'block', hits: result.hits }, undefined, 'output_delta');
+            if (stopped)
+                call.guardrail?.(stopped);
+            yield* drainBlockedDelta(result.boundary ? [] : result.hits, template);
+            return 'go';
+        }
+        yield* yieldDetected('reply', result.found);
+        if (result.emit) {
+            yield { ...template, text: result.emit };
+        }
+        return 'go';
+    }
+    async function* gateStreamEvent(event) {
+        if (!gate) {
+            yield event;
+            return 'continue';
+        }
+        if (withholding()) {
+            // why: 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') {
+            // why: Identity is the trace's alone; the call span already recorded it.
+            continue;
+        }
+        if (event.type === 'reasoning') {
+            // why: Signed reasoning goes back to the model as it came; no one reads it in between.
+            yield event;
+            continue;
+        }
+        if (yield* guardThought(event))
+            continue;
+        if (isStreamedCanaryEvent(event)) {
+            yield* endThought();
+            const status = yield* gateStreamEvent(event);
+            if (status === 'stop') {
+                return;
+            }
+            continue;
+        }
+        // why: Release held reply text first so the host sees events in order.
+        const flushed = yield* flushGate();
+        if (flushed === 'stop') {
+            return;
+        }
+        if (yield* drafts.take(event, withholding(), timed))
+            continue;
+        const leak = isReadElsewhere(event)
+            ? undefined
+            : await timed('stream_canary', () => eventLeak(event, context, policy.detect, 'reply'));
+        if (leak?.stop) {
+            yield* yieldLeakStop(leak.hits);
+            return;
+        }
+        if (leak)
+            yield* yieldDetected('reply', { action: 'flag', hits: leak.hits });
+        if (withholding() && isWithheldOnBlock(event)) {
+            // why: 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) {
+        // why: 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, StructuredDrafts, shouldSkipStreamEvent, shownToHost, yieldProviderEvents, };

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

@@ -0,0 +1,45 @@
+import type { ToolCallRequest } from '../../tools/types.js';
+import type { InteractionPart, ModelEvent, ResolvedGeneration, TurnEventOf, TurnHistoryMessage, TurnTokens } from '../../types.js';
+import { 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: ModelEvent): 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): 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): Promise<TurnEventOf<'tokens'> | undefined>;
+export type { CallConversation, CallUsage };
+export { callTokensEvent, heldAfter, observeCallEvent, startCallUsage };

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

@@ -0,0 +1,148 @@
+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':
+            // why: 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) {
+    const estimator = await loadTokenEstimator();
+    const { conversation } = usage;
+    if ('previous' in conversation) {
+        const earlier = await countConversation(conversation.previous);
+        const replayed = await countOutput(conversation.previous, false);
+        const continuation = estimator.messages(conversation.continuation);
+        return addCounts(addCounts(earlier, replayed), continuation);
+    }
+    const history = estimator.messages(conversation.history);
+    const sent = addCounts(history, estimator.parts(conversation.input));
+    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) {
+    return addCounts(await countConversation(usage), await countOutput(usage, false));
+}
+async function countPrompt(usage, generation) {
+    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);
+    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) {
+    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) : 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,33 @@
+import type { TraceSink } from '../../../observability/trace-sink.js';
+import type { ProviderHostOptions } from '../../protocols/runtime.js';
+import type { KernelRegistry } from '../../registry/kernel-registry.js';
+import type { PageToolExecution, ToolExecutionCoordinator } from '../../tools/operation.js';
+import type { KeyVault, LiveSession, SessionRequest } from '../../types.js';
+export type { LiveSession, SessionRequest };
+/** Options for opening a live session: the key vault, a provider's own settings, a WebSocket opener, how long a gated call waits for its decision, and the sign-in gate policy. */
+export interface RunSessionOptions extends ProviderHostOptions {
+    execution?: ToolExecutionCoordinator;
+    pageExecution?: PageToolExecution;
+    /** The host's keys by slot; the session uses the slots its profile names. */
+    vault?: KeyVault;
+    /**
+     * 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;
+}
+/** How a sign-in gate behaves in a live session: `hold` waits for the decision, `answer` tells the model the sign-in is pending and releases the call. */
+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>;