@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/evals/trial.js

@@ -0,0 +1,135 @@
+import { TheoremError } from '../guardrails/error.js';
+import { contentOf, inlineContent } from '../observability/trace-record.js';
+function byStart(a, b) {
+    const left = BigInt(a.startTimeUnixNano);
+    const right = BigInt(b.startTimeUnixNano);
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function operationOf(span) {
+    const value = span.attributes['gen_ai.operation.name'];
+    return typeof value === 'string' ? value : undefined;
+}
+function allSpans(records) {
+    return records.flatMap((record) => record.spans).sort(byStart);
+}
+function ancestorsOf(span, byId) {
+    const above = [];
+    const seen = new Set([span.spanId]);
+    let parent = span.parentSpanId === undefined ? undefined : byId.get(span.parentSpanId);
+    while (parent && !seen.has(parent.spanId)) {
+        above.push(parent);
+        seen.add(parent.spanId);
+        parent = parent.parentSpanId === undefined ? undefined : byId.get(parent.parentSpanId);
+    }
+    return above;
+}
+/** The earliest `invoke_agent` span with no `invoke_agent` above it; never assumed to be the first record, since a compaction turn's record can be written before its parent's (P9). */
+function rootOf(spans, byId) {
+    const roots = spans.filter((span) => operationOf(span) === 'invoke_agent' &&
+        !ancestorsOf(span, byId).some((above) => operationOf(above) === 'invoke_agent'));
+    const [root] = roots;
+    if (!root) {
+        throw new TheoremError('config', 'trial records hold no invoke_agent root span'); // labels-exempt: developer contract error
+    }
+    return root;
+}
+/** One record whose `content` is every record's, so a reference from any span resolves. */
+function mergedRecord(records) {
+    const [first] = records;
+    if (!first) {
+        throw new TheoremError('config', 'a trial needs at least one trace record'); // labels-exempt: developer contract error
+    }
+    return { ...first, content: Object.assign({}, ...records.map((record) => record.content)) };
+}
+function numberAttribute(span, key) {
+    const value = span.attributes[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isMessageList(value) {
+    return Array.isArray(value) && value.every(isObject);
+}
+function usageOf(root) {
+    const input = numberAttribute(root, 'gen_ai.usage.input_tokens') ?? 0;
+    const output = numberAttribute(root, 'gen_ai.usage.output_tokens') ?? 0;
+    const thinking = numberAttribute(root, 'gen_ai.usage.reasoning.output_tokens');
+    const cached = numberAttribute(root, 'gen_ai.usage.cache_read.input_tokens');
+    const cacheWrite = numberAttribute(root, 'gen_ai.usage.cache_write.input_tokens');
+    const toolUse = numberAttribute(root, 'theorem.usage.tool_use.input_tokens');
+    const costUsd = numberAttribute(root, 'theorem.usage.cost_usd');
+    const partial = root.attributes['theorem.usage.cost_partial'] === true;
+    const estimated = root.attributes['theorem.usage.estimated'];
+    const tokens = {
+        input,
+        output,
+        total: input + output,
+        ...(thinking === undefined ? {} : { thinking }),
+        ...(cached === undefined ? {} : { cached }),
+        ...(cacheWrite === undefined ? {} : { cacheWrite }),
+        ...(toolUse === undefined ? {} : { toolUse }),
+        ...(costUsd === undefined
+            ? {}
+            : { cost: { usd: costUsd, ...(partial ? { partial: true } : {}) } }),
+        ...(Array.isArray(estimated)
+            ? {
+                estimated: estimated.flatMap((side) => side === 'input' || side === 'output' ? [side] : []),
+            }
+            : {}),
+    };
+    return costUsd === undefined ? { tokens } : { tokens, costUsd };
+}
+/** A turn's root carries `gen_ai.output.messages`; a Live session's root carries none, and each response span carries its own `theorem.output.delivered`. */
+function deliveredOf(root, spans) {
+    const own = root.attributes['gen_ai.output.messages'];
+    if (isMessageList(own))
+        return own;
+    return spans
+        .filter((span) => 'theorem.request.live' in span.attributes)
+        .flatMap((span) => {
+        const delivered = span.attributes['theorem.output.delivered'];
+        return isMessageList(delivered) ? delivered : [];
+    });
+}
+/** Builds the `Trial` a grader reads from one trial's trace records: its root and top spans and accessors for spans, children, content, delivered output, and usage. */
+function buildTrial(args) {
+    const merged = mergedRecord(args.records);
+    const spans = allSpans(args.records);
+    const byId = new Map(spans.map((span) => [span.spanId, span]));
+    const root = rootOf(spans, byId);
+    return {
+        suite: args.suite,
+        ...(args.case ? { case: args.case } : {}),
+        index: args.index,
+        records: args.records,
+        root,
+        top: ancestorsOf(root, byId).at(-1) ?? root,
+        spans: (operation) => spans.filter((span) => operationOf(span) === operation),
+        children: (parent) => spans.filter((span) => span.parentSpanId === parent.spanId),
+        content: (value) => inlineContent(merged, value),
+        text: (value) => (isObject(value) ? contentOf(merged, value) : undefined),
+        delivered: () => deliveredOf(root, spans),
+        usage: () => usageOf(root),
+    };
+}
+/** Groups trace records by the trace id of their first span; records with no spans are dropped. */
+function groupByTrace(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const traceId = record.spans[0]?.traceId;
+        if (traceId === undefined)
+            continue;
+        const group = groups.get(traceId);
+        if (group)
+            group.push(record);
+        else
+            groups.set(traceId, [record]);
+    }
+    return groups;
+}
+/** True when any record holds an `invoke_agent` span, meaning an agent turn ran. */
+function hasTurn(records) {
+    return records.some((record) => record.spans.some((span) => operationOf(span) === 'invoke_agent'));
+}
+export { buildTrial, groupByTrace, hasTurn };

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

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import type { RunDecisionOptions } from '../kernel/engine/decision.js';
+import type { ProviderHostOptions } from '../kernel/protocols/runtime.js';
+import type { TurnTokens } from '../kernel/turn-events.js';
+import type { TraceRecord } from '../observability/trace-record.js';
+import type { TraceAttributeValue, TraceSpan } from '../observability/trace-span.js';
+/** Whether a case probes what the profile can do (`capability`) or guards what it already did (`regression`). */
+export type EvalCaseKind = 'capability' | 'regression';
+/** An attachment carried in the case file as base64. */
+export interface EvalInlineAttachment {
+    mimeType: string;
+    /** Base64 bytes. */
+    data: string;
+    name?: string;
+}
+/** A file attachment is pinned by the hex SHA-256 of its bytes; a file whose bytes hash otherwise is refused. */
+export interface EvalFileAttachment {
+    mimeType: string;
+    path: string;
+    sha256: string;
+    name?: string;
+}
+/** An attachment a case sends: inline bytes or a file on disk. */
+export type EvalAttachment = EvalInlineAttachment | EvalFileAttachment;
+/** A single-turn case input. */
+export interface EvalTurnInput {
+    text?: string;
+    attachments?: EvalAttachment[];
+}
+/** One message of a session case, sent once the previous step's turn completes. */
+export interface EvalSessionStep {
+    text: string;
+    until: 'turn_complete';
+}
+/** A multi-step session case input. */
+export interface EvalSessionInput {
+    session: {
+        steps: EvalSessionStep[];
+    };
+}
+/** A case input: one turn or a session. */
+export type EvalCaseInput = EvalTurnInput | EvalSessionInput;
+/** Only an `accepted` name passes; a `partial` one is close but not enough; a `rejected` one named beside an accepted name makes the reply `partial`, not a pass. */
+export interface EvalAnswer {
+    accepted: string[];
+    partial?: string[];
+    rejected?: string[];
+    reference?: string;
+}
+/** What a case expects: tools, JSON fields, a transcription, or an answer. */
+export interface EvalExpect {
+    tools?: string[];
+    json?: Record<string, unknown>;
+    transcription?: {
+        includes?: string;
+        regex?: string;
+    };
+    answer?: EvalAnswer;
+    notes?: string;
+}
+/** How hard a case is, from 1 to 5. */
+export type EvalDifficulty = 1 | 2 | 3 | 4 | 5;
+/** One eval case: its input and what the reply is expected to be. */
+export interface EvalCase {
+    id: string;
+    kind: EvalCaseKind;
+    difficulty?: EvalDifficulty;
+    input: EvalCaseInput;
+    expect?: EvalExpect;
+    tags?: string[];
+}
+/** The schema an eval case parses against. */
+export declare const evalCaseSchema: z.ZodType<EvalCase>;
+/** The operation a trace span records. */
+export type TraceOperation = 'invoke_agent' | 'chat' | 'generate_content' | 'execute_tool';
+/** A message as the trace stores it: `{ role, parts: [...] }`, parts by hash; resolve them with `text` / `content`. */
+export type TrialMessage = Record<string, TraceAttributeValue>;
+/** Tokens and cost a trial used. */
+export interface TrialUsage {
+    tokens: TurnTokens;
+    costUsd?: number;
+}
+/** A grader receives the trace records that share the trial's trace id and nothing else; if it needs a fact the trace does not hold, the trace is wrong, not the grader. */
+export interface Trial {
+    suite: string;
+    case?: EvalCase;
+    index: number;
+    records: TraceRecord[];
+    root: TraceSpan;
+    /** The topmost span above `root`: the host's own span when the host nested the turn under it, else `root`. Its length is the trial's time. */
+    top: TraceSpan;
+    spans: (operation: TraceOperation) => TraceSpan[];
+    children: (span: TraceSpan) => TraceSpan[];
+    content: (value: unknown) => unknown;
+    text: (value: unknown) => string | undefined;
+    delivered: () => TrialMessage[];
+    usage: () => TrialUsage;
+}
+/** Whether a result came from code or from a model. */
+export type EvalResultSource = 'code' | 'model';
+/** One grader's verdict on a trial: a score, a label, and why. */
+export interface EvalResult {
+    name: string;
+    source: EvalResultSource;
+    score?: {
+        value?: number;
+        label?: string;
+    };
+    explanation?: string;
+    /** Whether this result counts as a pass. Absent: informational only. */
+    passed?: boolean;
+    /** Why no score could be produced; the result is then a failed one. */
+    errorType?: string;
+    judgeTraceparents?: string[];
+}
+/** The schema an eval result parses against. */
+export declare const evalResultSchema: z.ZodType<EvalResult>;
+/** How many trials of a case must pass for the case to pass. */
+export type EvalPassRule = 'all' | 'any' | {
+    atLeast: number;
+};
+/** How often a case runs, and the rule across those runs. */
+export interface EvalTrials {
+    /** Trials per case. No default: it is a cost decision, so the suite states it. `1` cannot tell noise from change. */
+    repeat: number;
+    pass?: EvalPassRule;
+}
+/** What a grader gets besides the trial: the judge model and its trace parent. */
+export interface EvalGradeContext {
+    judge?: string;
+    judgeProvider?: ProviderHostOptions;
+    judgeDecision?: Omit<RunDecisionOptions, 'sink'>;
+    /** The trial span as a W3C `traceparent`: a judge call runs under it, so it lands in the judged trace beneath the trial. Absent, each judge call starts a trace of its own. */
+    traceparent?: string;
+    media?: EvalMediaResolver;
+    traced: (records: TraceRecord[]) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+/** Media a trace names by the sha256 (hex) of its raw bytes. */
+export interface EvalMediaRef {
+    sha256: string;
+    mimeType: string;
+}
+/** The media's bytes as base64, or `undefined` when the host does not have them. */
+export type EvalMediaResolver = (ref: EvalMediaRef) => string | undefined | Promise<string | undefined>;
+/** Grades one trial of a case, from its trace. */
+export interface EvalGrader {
+    name: string;
+    /** Stable text naming exactly what this grader checks; its sha256 is written as `theorem.evaluation.grader.version`, so a later reader can tell which rubric produced which score. */
+    identity: string;
+    source: EvalResultSource;
+    needsExpect: boolean;
+    judgeProfiles?: (suiteJudge: string | undefined) => string[];
+    grade: (trial: Trial, context: EvalGradeContext) => EvalResult | Promise<EvalResult>;
+}
+/** A suite: a profile, a mode, a cases file, and the graders to run. */
+export interface EvalSuite {
+    id: string;
+    profile: string;
+    mode: 'turn' | 'session';
+    cases: string;
+    trials: EvalTrials;
+    graders: EvalGrader[];
+    judge?: {
+        profile: string;
+    };
+}
+/** The schema an eval suite parses against. */
+export declare const evalSuiteSchema: z.ZodType<EvalSuite>;

package/esm/src/evals/types.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { isRecord } from '../kernel/util/record.js';
+const evalCaseKind = z.enum(['capability', 'regression']);
+true;
+const evalInlineAttachment = z.object({
+    mimeType: z.string(),
+    data: z.string(),
+    name: z.string().optional(),
+});
+true;
+const evalFileAttachment = z.object({
+    mimeType: z.string(),
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/, 'must be a lowercase hex SHA-256'),
+    name: z.string().optional(),
+});
+true;
+const evalAttachment = z.union([evalInlineAttachment, evalFileAttachment]);
+true;
+const evalTurnInput = z.object({
+    text: z.string().optional(),
+    attachments: z.array(evalAttachment).optional(),
+});
+true;
+const evalSessionStep = z.object({ text: z.string(), until: z.literal('turn_complete') });
+true;
+const evalSessionInput = z.object({ session: z.object({ steps: z.array(evalSessionStep) }) });
+true;
+const evalCaseInput = z.union([evalSessionInput, evalTurnInput]);
+true;
+const evalAnswer = z.object({
+    accepted: z.array(z.string().min(1)).min(1),
+    partial: z.array(z.string().min(1)).optional(),
+    rejected: z.array(z.string().min(1)).optional(),
+    reference: z.string().optional(),
+});
+true;
+const evalExpect = z.object({
+    tools: z.array(z.string()).optional(),
+    json: z.record(z.string(), z.unknown()).optional(),
+    transcription: z
+        .object({ includes: z.string().optional(), regex: z.string().optional() })
+        .optional(),
+    answer: evalAnswer.optional(),
+    notes: z.string().optional(),
+});
+true;
+const evalDifficulty = z.union([
+    z.literal(1),
+    z.literal(2),
+    z.literal(3),
+    z.literal(4),
+    z.literal(5),
+]);
+true;
+const evalCase = z.object({
+    id: z.string().min(1),
+    kind: evalCaseKind,
+    difficulty: evalDifficulty.optional(),
+    input: evalCaseInput,
+    expect: evalExpect.optional(),
+    tags: z.array(z.string()).optional(),
+});
+true;
+/** The schema an eval case parses against. */
+export const evalCaseSchema = evalCase;
+const evalResultSource = z.enum(['code', 'model']);
+true;
+const evalResult = z.object({
+    name: z.string().min(1),
+    source: evalResultSource,
+    score: z.object({ value: z.number().optional(), label: z.string().optional() }).optional(),
+    explanation: z.string().optional(),
+    passed: z.boolean().optional(),
+    errorType: z.string().optional(),
+    judgeTraceparents: z.array(z.string()).optional(),
+});
+true;
+/** The schema an eval result parses against. */
+export const evalResultSchema = evalResult;
+const evalPassRule = z.union([
+    z.literal('all'),
+    z.literal('any'),
+    z.object({ atLeast: z.number().int().min(1) }),
+]);
+true;
+const evalTrials = z.object({
+    repeat: z.number().int().min(1),
+    pass: evalPassRule.optional(),
+});
+true;
+function isGrader(value) {
+    return (isRecord(value) &&
+        typeof value.name === 'string' &&
+        typeof value.identity === 'string' &&
+        (value.source === 'code' || value.source === 'model') &&
+        typeof value.needsExpect === 'boolean' &&
+        (value.judgeProfiles === undefined || typeof value.judgeProfiles === 'function') &&
+        typeof value.grade === 'function');
+}
+const evalGrader = z.custom(isGrader);
+const evalSuite = z.object({
+    id: z.string().min(1),
+    profile: z.string().min(1),
+    mode: z.enum(['turn', 'session']),
+    cases: z.string().min(1),
+    trials: evalTrials,
+    graders: z.array(evalGrader),
+    judge: z.object({ profile: z.string().min(1) }).optional(),
+});
+true;
+/** The schema an eval suite parses against. */
+export const evalSuiteSchema = evalSuite;

package/esm/src/evals/verdict.d.ts

@@ -0,0 +1,23 @@
+import type { EvalCase, EvalPassRule, EvalResult } from './types.js';
+/** How a trial ended: passed, failed, errored, or ungraded. */
+type TrialOutcome = 'passed' | 'failed' | 'errored' | 'ungraded';
+/** The outcome of a trial from its results. */
+declare function trialOutcome(results: readonly EvalResult[]): TrialOutcome;
+/** A case's verdict across its trials, under the pass rule. */
+interface CaseVerdict {
+    case: string;
+    kind: EvalCase['kind'];
+    difficulty?: EvalCase['difficulty'];
+    passed: boolean;
+    decided: boolean;
+    trials: number;
+    trialsPassed: number;
+    trialsErrored: number;
+    trialsUngraded: number;
+}
+/** The name of a pass rule, as the trace records it. */
+declare function passRuleName(rule: EvalPassRule): 'all' | 'any' | 'at_least';
+/** The verdict of a case from its trials' results. */
+declare function caseVerdict(evalCase: EvalCase, trials: readonly (readonly EvalResult[])[], rule?: EvalPassRule): CaseVerdict;
+export type { CaseVerdict, TrialOutcome };
+export { caseVerdict, passRuleName, trialOutcome };

package/esm/src/evals/verdict.js

@@ -0,0 +1,48 @@
+/** The outcome of a trial from its results. */
+function trialOutcome(results) {
+    if (results.some((result) => result.errorType !== undefined))
+        return 'errored';
+    const decided = results.filter((result) => result.passed !== undefined);
+    if (decided.length === 0)
+        return 'ungraded';
+    return decided.every((result) => result.passed) ? 'passed' : 'failed';
+}
+function ruleMet(rule, passed, trials) {
+    if (trials === 0)
+        return false;
+    if (rule === 'all')
+        return passed === trials;
+    if (rule === 'any')
+        return passed >= 1;
+    return passed >= rule.atLeast;
+}
+function trialsNeeded(rule) {
+    return typeof rule === 'object' ? rule.atLeast : 1;
+}
+/** The name of a pass rule, as the trace records it. */
+function passRuleName(rule) {
+    return typeof rule === 'string' ? rule : 'at_least';
+}
+// why: An errored trial is one that could not be graded (a provider error, a judge that failed), so the rule reads it as a trial that never ran: a rate limit never counts against the agent.
+/** The verdict of a case from its trials' results. */
+function caseVerdict(evalCase, trials, rule = 'all') {
+    const outcomes = trials.map(trialOutcome);
+    const count = (outcome) => outcomes.filter((o) => o === outcome).length;
+    const trialsPassed = count('passed');
+    const trialsErrored = count('errored');
+    const trialsUngraded = count('ungraded');
+    const ran = outcomes.length - trialsErrored;
+    const passed = trialsUngraded < ran && ruleMet(rule, trialsPassed, ran);
+    return {
+        case: evalCase.id,
+        kind: evalCase.kind,
+        ...(evalCase.difficulty === undefined ? {} : { difficulty: evalCase.difficulty }),
+        passed,
+        decided: passed || trialsErrored === 0 || ran >= trialsNeeded(rule),
+        trials: outcomes.length,
+        trialsPassed,
+        trialsErrored,
+        trialsUngraded,
+    };
+}
+export { caseVerdict, passRuleName, trialOutcome };

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

@@ -0,0 +1,41 @@
+/** labels-exempt-file: authoring labels and descriptions for boundaries — not runtime user or model copy (P2) */
+/** A record with one entry per key, typed by the keys it was built from. */
+declare function recordOf<K extends string, V>(keys: readonly K[], value: (key: K) => V): Record<K, V>;
+/**
+ * The kinds of tool whose text the kernel reads, in the words a builder writes as a tool's
+ * `type`. A provider builtin has none: the provider runs it and the kernel never reads its text.
+ */
+declare const TOOL_KINDS: readonly ["function", "http", "mcp", "agent"];
+/** One of {@linkcode TOOL_KINDS}. */
+type ToolKind = (typeof TOOL_KINDS)[number];
+/**
+ * The places a tool's text crosses: what the model sends, what comes back to it, its error text,
+ * and what the call shows the person (its output, error, artifacts, and trace on the turn's events).
+ */
+declare const TOOL_CROSSINGS: readonly ["tool_arguments", "tool_output", "tool_failure", "tool_shown"];
+/** One of {@linkcode TOOL_CROSSINGS}. */
+type ToolCrossing = (typeof TOOL_CROSSINGS)[number];
+/** A tool crossing for one kind of tool, such as `tool_output_mcp`. */
+type ToolBoundary = `${ToolCrossing}_${ToolKind}`;
+/** The boundary where `crossing` happens for a `kind` tool. */
+declare function toolBoundary<C extends ToolCrossing, K extends ToolKind>(crossing: C, kind: K): `${C}_${K}`;
+/** Every tool boundary, each crossing in turn for every kind of tool. */
+declare const TOOL_BOUNDARIES: readonly ToolBoundary[];
+/** Where text reaches the model from the person or the host. */
+declare const INBOUND_BOUNDARIES: readonly ["user", "attachment", "voice", "slots", "context", "history", "injected", "system", "repair", "live_user"];
+/** Where the model's own text reaches the person. */
+declare const OUTBOUND_BOUNDARIES: readonly ["reply", "reply_structured", "live_reply", "thought"];
+/** Every place the kernel reads text as it crosses, in the order a turn meets them. */
+declare const BOUNDARIES: readonly ["user", "attachment", "voice", "slots", "context", "history", "injected", "system", "repair", "live_user", ...("tool_arguments_function" | "tool_arguments_http" | "tool_arguments_mcp" | "tool_arguments_agent" | "tool_output_function" | "tool_output_http" | "tool_output_mcp" | "tool_output_agent" | "tool_failure_function" | "tool_failure_http" | "tool_failure_mcp" | "tool_failure_agent" | "tool_shown_function" | "tool_shown_http" | "tool_shown_mcp" | "tool_shown_agent")[], "reply", "reply_structured", "live_reply", "thought"];
+/** One of {@linkcode BOUNDARIES}. */
+type Boundary = (typeof BOUNDARIES)[number];
+/** How a boundary is named and described to a builder. */
+interface BoundaryMeta {
+    label: string;
+    /** What is read there. */
+    doc: string;
+}
+/** The label and description of every boundary. */
+declare const BOUNDARY_META: Readonly<Record<Boundary, BoundaryMeta>>;
+export type { Boundary, BoundaryMeta, ToolBoundary, ToolCrossing, ToolKind };
+export { BOUNDARIES, BOUNDARY_META, INBOUND_BOUNDARIES, OUTBOUND_BOUNDARIES, recordOf, TOOL_BOUNDARIES, TOOL_KINDS, toolBoundary, };

package/esm/src/guardrails/boundaries.js

@@ -0,0 +1,103 @@
+// invariant: Leaf module. Imports nothing from `src/guardrails/types.ts` or `src/kernel/`, so the
+// vocabulary can be read by every layer without a cycle.
+/** labels-exempt-file: authoring labels and descriptions for boundaries — not runtime user or model copy (P2) */
+/** A record with one entry per key, typed by the keys it was built from. */
+function recordOf(keys, value) {
+    return Object.fromEntries(keys.map((key) => [key, value(key)]));
+}
+/**
+ * The kinds of tool whose text the kernel reads, in the words a builder writes as a tool's
+ * `type`. A provider builtin has none: the provider runs it and the kernel never reads its text.
+ */
+const TOOL_KINDS = ['function', 'http', 'mcp', 'agent'];
+/**
+ * The places a tool's text crosses: what the model sends, what comes back to it, its error text,
+ * and what the call shows the person (its output, error, artifacts, and trace on the turn's events).
+ */
+const TOOL_CROSSINGS = ['tool_arguments', 'tool_output', 'tool_failure', 'tool_shown'];
+/** The boundary where `crossing` happens for a `kind` tool. */
+function toolBoundary(crossing, kind) {
+    return `${crossing}_${kind}`;
+}
+/** Every tool boundary, each crossing in turn for every kind of tool. */
+const TOOL_BOUNDARIES = TOOL_CROSSINGS.flatMap((crossing) => TOOL_KINDS.map((kind) => toolBoundary(crossing, kind)));
+/** Where text reaches the model from the person or the host. */
+const INBOUND_BOUNDARIES = [
+    'user',
+    'attachment',
+    'voice',
+    'slots',
+    'context',
+    'history',
+    'injected',
+    'system',
+    'repair',
+    'live_user',
+];
+/** Where the model's own text reaches the person. */
+const OUTBOUND_BOUNDARIES = ['reply', 'reply_structured', 'live_reply', 'thought'];
+/** Every place the kernel reads text as it crosses, in the order a turn meets them. */
+const BOUNDARIES = [
+    ...INBOUND_BOUNDARIES,
+    ...TOOL_BOUNDARIES,
+    ...OUTBOUND_BOUNDARIES,
+];
+const TOOL_KIND_LABELS = {
+    function: 'function',
+    http: 'HTTP',
+    mcp: 'MCP',
+    agent: 'agent',
+};
+const TOOL_CROSSING_META = {
+    tool_arguments: (kind) => ({
+        label: `Arguments to ${kind} tools`,
+        doc: `What the model sends to a tool of type ${kind}.`,
+    }),
+    tool_output: (kind) => ({
+        label: `Output of ${kind} tools`,
+        doc: `What a tool of type ${kind} returns.`,
+    }),
+    tool_failure: (kind) => ({
+        label: `Errors from ${kind} tools`,
+        doc: `The error text of a tool of type ${kind} that failed.`,
+    }),
+    tool_shown: (kind) => ({
+        label: `Shown from ${kind} tools`,
+        doc: `What a call to a tool of type ${kind} shows the person: its output, error, artifacts, and trace.`,
+    }),
+};
+function toolBoundaryMeta() {
+    const entries = TOOL_CROSSINGS.flatMap((crossing) => TOOL_KINDS.map((kind) => [
+        toolBoundary(crossing, kind),
+        TOOL_CROSSING_META[crossing](TOOL_KIND_LABELS[kind]),
+    ]));
+    return Object.fromEntries(entries);
+}
+/** The label and description of every boundary. */
+const BOUNDARY_META = {
+    user: { label: 'User message', doc: 'The message the person typed.' },
+    attachment: { label: 'Attachments', doc: 'The text of a file the person attached.' },
+    voice: { label: 'Voice', doc: 'The transcript of what the person said.' },
+    slots: { label: 'Slots', doc: 'The values the host fills into the prompt.' },
+    context: { label: 'Context', doc: 'What the page or the host tells the model to know.' },
+    history: { label: 'History', doc: 'Earlier messages the host replays.' },
+    injected: { label: 'Stage messages', doc: 'Messages a host stage adds during the turn.' },
+    system: {
+        label: 'Turn system text',
+        doc: 'Text the host adds to the system instruction for one turn.',
+    },
+    repair: {
+        label: 'Repair',
+        doc: 'A stopped reply and the reason, handed back to the model to try again.',
+    },
+    live_user: { label: 'Live message', doc: 'Text the person sends in a Live session.' },
+    ...toolBoundaryMeta(),
+    reply: { label: 'Reply', doc: 'The text the model says to the person.' },
+    reply_structured: {
+        label: 'Structured reply',
+        doc: 'The structured output the model returns.',
+    },
+    live_reply: { label: 'Live reply', doc: 'What the model says in a Live session.' },
+    thought: { label: 'Thoughts', doc: "The model's reasoning, where the host shows it." },
+};
+export { BOUNDARIES, BOUNDARY_META, INBOUND_BOUNDARIES, OUTBOUND_BOUNDARIES, recordOf, TOOL_BOUNDARIES, TOOL_KINDS, toolBoundary, };

package/esm/src/guardrails/canary-gate.d.ts

@@ -0,0 +1,22 @@
+import type { TurnEvent } from '../kernel/types.js';
+import { type CanaryStreamGate } from './canary.js';
+/** A canary leak gate for one reply: the turn canary, the system prompt to catch echoes of, and the stream gate that holds text back. */
+export interface CanaryGateSession {
+    canary: string;
+    /** The system prompt as sent, when replies echoing it are leaks too. */
+    privateSystem?: readonly string[];
+    gate: CanaryStreamGate;
+}
+/** Pass the system prompt as sent to catch replies that echo it, as `runTurn` and Live do. */
+declare function createCanaryGateSession(canary: string, privateSystem?: readonly string[]): CanaryGateSession;
+/**
+ * Canary-only batch filter for hosts that need stream lookback without full egress. Stops at the
+ * first leak, so no unsafe event is returned; thoughts are unguarded (`isGuardedOutput`).
+ */
+declare function filterCanaryGatedEvents(session: CanaryGateSession, events: TurnEvent[]): {
+    leaked: true;
+} | {
+    leaked: false;
+    events: TurnEvent[];
+};
+export { createCanaryGateSession, filterCanaryGatedEvents };