@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/evals/trial.js

@@ -1,16 +1,3 @@
-/**
- * Records → `Trial`. A live run hands the runner what its memory sink caught;
- * a recorded run hands it what a file held. Both build the same trial, so the
- * same graders give the same results.
- *
- * The root is the `invoke_agent` span with no agent above it in the set; a host
- * span above it (the host's request, when the host nests the turn under its own
- * span) does not hide it, and the topmost span above it is the trial's `top`. It
- * is never assumed to be the first record: a compaction turn's record can be
- * written before its parent's (P9).
- *
- * @module
- */
 import { TheoremError } from '../guardrails/error.js';
 import { contentOf, inlineContent } from '../observability/trace-record.js';
 function byStart(a, b) {
@@ -22,11 +9,9 @@ function operationOf(span) {
     const value = span.attributes['gen_ai.operation.name'];
     return typeof value === 'string' ? value : undefined;
 }
-/** Every span of every record, in start order. */
 function allSpans(records) {
     return records.flatMap((record) => record.spans).sort(byStart);
 }
-/** The spans above `span` in the set, nearest first; a parent outside the set ends the walk. */
 function ancestorsOf(span, byId) {
     const above = [];
     const seen = new Set([span.spanId]);
@@ -38,16 +23,13 @@ function ancestorsOf(span, byId) {
     }
     return above;
 }
-/**
- * The `invoke_agent` span with no `invoke_agent` above it in the set; the
- * earliest when several qualify (a session root before its responses).
- */
+/** 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'); // lexicon-exempt: developer contract error
+        throw new TheoremError('config', 'trial records hold no invoke_agent root span'); // labels-exempt: developer contract error
     }
     return root;
 }
@@ -55,7 +37,7 @@ function rootOf(spans, byId) {
 function mergedRecord(records) {
     const [first] = records;
     if (!first) {
-        throw new TheoremError('config', 'a trial needs at least one trace record'); // lexicon-exempt: developer contract error
+        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)) };
 }
@@ -69,7 +51,6 @@ function isObject(value) {
 function isMessageList(value) {
     return Array.isArray(value) && value.every(isObject);
 }
-/** The root's usage attributes as `TurnTokens`; zero when the root recorded none. */
 function usageOf(root) {
     const input = numberAttribute(root, 'gen_ai.usage.input_tokens') ?? 0;
     const output = numberAttribute(root, 'gen_ai.usage.output_tokens') ?? 0;
@@ -99,11 +80,7 @@ function usageOf(root) {
     };
     return costUsd === undefined ? { tokens } : { tokens, costUsd };
 }
-/**
- * What the host received. 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`, taken in start order.
- */
+/** 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))
@@ -115,7 +92,7 @@ function deliveredOf(root, spans) {
         return isMessageList(delivered) ? delivered : [];
     });
 }
-/** Build the trial every grader receives from the records that share one trace. */
+/** 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);
@@ -136,7 +113,7 @@ function buildTrial(args) {
         usage: () => usageOf(root),
     };
 }
-/** Group records by trace id, in first-seen order. */
+/** 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) {
@@ -151,7 +128,7 @@ function groupByTrace(records) {
     }
     return groups;
 }
-/** Whether these records hold a turn at all: an `invoke_agent` span. An eval run record does not. */
+/** 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'));
 }

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

@@ -1,96 +1,66 @@
-/**
- * Eval shapes: the suite a host writes, the cases it keeps in JSONL,
- * and the result every grader returns. Each is a documented type and a zod
- * schema checked against it (`Equals`): the type is what graders read; the
- * schema is what the runner runs on a file.
- *
- * Vocabulary follows Anthropic's evals guide so a host can read both: a
- * **suite** of **cases**, each run as k **trials**; a **grader** reads a
- * trial's transcript (its trace) and returns a **result**; the suite's pass
- * rule turns k results into one **verdict**.
- *
- * @module
- */
 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 { ModelProvider } from '../kernel/types.js';
 import type { TraceRecord } from '../observability/trace-record.js';
 import type { TraceAttributeValue, TraceSpan } from '../observability/trace-span.js';
-/** Anthropic's split: does the agent *do* the thing (capability), or *still* do it (regression)? */
+/** Whether a case probes what the profile can do (`capability`) or guards what it already did (`regression`). */
 export type EvalCaseKind = 'capability' | 'regression';
-/** A file the case attaches to its turn, inline, as `TurnBlob` takes it. */
+/** An attachment carried in the case file as base64. */
 export interface EvalInlineAttachment {
     mimeType: string;
     /** Base64 bytes. */
     data: string;
     name?: string;
 }
-/**
- * A file the case attaches to its turn, kept beside the cases file and pinned
- * by the hex SHA-256 of its bytes; a file whose bytes hash otherwise is refused.
- */
+/** 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;
-    /** Relative to the cases file, or absolute; the loaded case holds it absolute. */
     path: string;
     sha256: string;
     name?: string;
 }
-/** A file the case attaches to its turn: its bytes inline, or a file beside the cases. */
+/** An attachment a case sends: inline bytes or a file on disk. */
 export type EvalAttachment = EvalInlineAttachment | EvalFileAttachment;
-/** One turn's input (`mode: 'turn'`). */
+/** A single-turn case input. */
 export interface EvalTurnInput {
     text?: string;
     attachments?: EvalAttachment[];
 }
-/** One scripted step of a Live session: send text, wait for the boundary it names. */
+/** One message of a session case, sent once the previous step's turn completes. */
 export interface EvalSessionStep {
     text: string;
     until: 'turn_complete';
 }
-/** A scripted Live session (`mode: 'session'`): text steps in order. Audio steps are not in this slice. */
+/** A multi-step session case input. */
 export interface EvalSessionInput {
     session: {
         steps: EvalSessionStep[];
     };
 }
-/** What the case sends: a turn's input or a session script. */
+/** A case input: one turn or a session. */
 export type EvalCaseInput = EvalTurnInput | EvalSessionInput;
-/**
- * A dataset case's right answer. Only an `accepted` name passes; a `partial`
- * one is close but not enough (the genus, the broader condition); a `rejected`
- * one is a wrong answer the dataset records for the case (a confuser, an
- * identification it superseded).
- */
+/** 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 {
-    /** Every name that counts: scientific name, synonyms, common names. */
     accepted: string[];
     partial?: string[];
-    /** A reply that names one beside an accepted name hedged: `partial`, not a pass. */
     rejected?: string[];
-    /** Grounding notes for the person reading a miss; no grader reads them. */
     reference?: string;
 }
-/** What the transcript should contain; graders that need it are skipped when it is absent. */
+/** What a case expects: tools, JSON fields, a transcription, or an answer. */
 export interface EvalExpect {
-    /** Tools the agent should call, in order (`toolTrajectory` reads it). Empty = no tool. */
     tools?: string[];
-    /** Fields the delivered JSON should carry, each compared whole (`delivered.json` reads it). */
     json?: Record<string, unknown>;
-    /** What the Live reply's transcript should say (`transcription.*` read it). */
     transcription?: {
         includes?: string;
         regex?: string;
     };
-    /** The right answer to a dataset question (`answer` reads it). */
     answer?: EvalAnswer;
-    /** For the human reading the case; no grader reads it. */
     notes?: string;
 }
-/** Perplexity's 1–5 difficulty; results are reported per bucket when set. */
+/** How hard a case is, from 1 to 5. */
 export type EvalDifficulty = 1 | 2 | 3 | 4 | 5;
-/** One line of `cases.jsonl`. */
+/** One eval case: its input and what the reply is expected to be. */
 export interface EvalCase {
     id: string;
     kind: EvalCaseKind;
@@ -99,113 +69,70 @@ export interface EvalCase {
     expect?: EvalExpect;
     tags?: string[];
 }
-/** What the runner runs on each line of a cases file. */
+/** The schema an eval case parses against. */
 export declare const evalCaseSchema: z.ZodType<EvalCase>;
-/** The `gen_ai.operation.name` values a trial's spans carry. */
+/** 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>;
-/** What the root span reports the trial cost, as the kernel's `TurnTokens`. */
+/** Tokens and cost a trial used. */
 export interface TrialUsage {
     tokens: TurnTokens;
     costUsd?: number;
 }
-/**
- * One run of one case, as every grader receives it: the trace records that
- * share the trial's trace id and nothing else. If a grader needs a fact the
- * trace does not hold, the trace is wrong, not the grader.
- */
+/** 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;
-    /** Absent in caseless recorded mode (a production trace with no `metadata.eval`). */
     case?: EvalCase;
-    /** 0..k-1. */
     index: number;
     records: TraceRecord[];
-    /** The `invoke_agent` span with no agent above it in the set; never assumed to be first. */
     root: TraceSpan;
-    /**
-     * The topmost span above `root` in the set: the host's own span when the host
-     * nested the turn under it, else `root`. Its length is the trial's time.
-     */
+    /** 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 by operation, in start order, across every record. */
     spans: (operation: TraceOperation) => TraceSpan[];
-    /** The spans one span parents, in start order (a model call's HTTP tries, a response's tool calls). */
     children: (span: TraceSpan) => TraceSpan[];
-    /** A value with every `{ content_sha256 }` / `{ json_sha256 }` reference replaced by its stored content. */
     content: (value: unknown) => unknown;
-    /** The stored text one reference names; `undefined` for any other value. */
     text: (value: unknown) => string | undefined;
-    /** What the host received: the root's output messages, or each Live response's, as stored. */
     delivered: () => TrialMessage[];
-    /** Tokens and cost from the root's usage attributes. */
     usage: () => TrialUsage;
 }
-/** Who produced a result: a code grader, or a judge model. */
+/** Whether a result came from code or from a model. */
 export type EvalResultSource = 'code' | 'model';
-/**
- * One grader's reading of one trial: the semconv `gen_ai.evaluation.result`
- * event, before it is written. `passed` is the grader's yes/no when it has one;
- * absent means the result informs but does not decide the verdict.
- */
+/** One grader's verdict on a trial: a score, a label, and why. */
 export interface EvalResult {
-    /** The grader's name, e.g. `tool_trajectory`, `faithfulness`. */
     name: string;
     source: EvalResultSource;
-    /** `value` is 0–1 unless the grader says otherwise; `label` is one of the grader's labels. */
     score?: {
         value?: number;
         label?: string;
     };
-    /** Why, in the grader's words. */
     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;
-    /** Judge turns this result was drawn from (`traceparent` each); model graders only. */
     judgeTraceparents?: string[];
 }
-/** A result as a reader validates it, e.g. one rebuilt from a written event. */
+/** The schema an eval result parses against. */
 export declare const evalResultSchema: z.ZodType<EvalResult>;
-/** How k trials become one verdict: every trial (pass^k), any trial (pass@k), or at least n. */
+/** How many trials of a case must pass for the case to pass. */
 export type EvalPassRule = 'all' | 'any' | {
     atLeast: number;
 };
-/** How many times each case runs, and what counts as passing. */
+/** 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;
-    /** Default `all`. */
     pass?: EvalPassRule;
 }
-/**
- * What the runner hands every grader beside the trial. Code graders ignore it;
- * a model grader runs its judge through it and reports each judge call's
- * records through `traced`, so the runner can count their cost and write them
- * to the sink.
- */
+/** What a grader gets besides the trial: the judge model and its trace parent. */
 export interface EvalGradeContext {
-    /** The suite's judge profile, when it names one; a grader may name its own. */
     judge?: string;
-    /** The host's provider for text judge profiles. */
-    judgeProvider?: ModelProvider;
-    /** The host's vault for decision judge profiles. */
+    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.
-     */
+    /** 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;
-    /**
-     * The host's store for media a trace names only by hash. A judge that must
-     * see media the case did not attach asks here; absent, only the case's own
-     * attachments can be shown.
-     */
     media?: EvalMediaResolver;
-    /** Every record a grader's own judge call produced. */
     traced: (records: TraceRecord[]) => void | Promise<void>;
     signal?: AbortSignal;
 }
@@ -216,45 +143,27 @@ export interface EvalMediaRef {
 }
 /** 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>;
-/** Code or model logic that reads a trial and returns a result. */
+/** Grades one trial of a case, from its trace. */
 export interface EvalGrader {
-    /** The result's `gen_ai.evaluation.name`. */
     name: string;
-    /**
-     * Stable text naming exactly what this grader checks (its options, its
-     * rubric). Its sha256 is written as `theorem.evaluation.grader.version`, so
-     * a later reader can tell which rubric produced which score.
-     */
+    /** 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;
-    /** Reads the case's `expect`; skipped when a trial has no case (caseless recorded mode). */
     needsExpect: boolean;
-    /**
-     * Model graders: every judge profile this grader may run, given the suite's
-     * `judge.profile`: its judge first, then any it escalates to. Throws when
-     * there is none, or a profile cannot run this grader, so a suite fails
-     * before its first trial.
-     */
     judgeProfiles?: (suiteJudge: string | undefined) => string[];
     grade: (trial: Trial, context: EvalGradeContext) => EvalResult | Promise<EvalResult>;
 }
-/** A named set of cases against one profile, with graders and a pass rule. */
+/** A suite: a profile, a mode, a cases file, and the graders to run. */
 export interface EvalSuite {
     id: string;
-    /** The profile under test; any type but `host`. */
     profile: string;
     mode: 'turn' | 'session';
-    /** Path to `cases.jsonl`, relative to the suite module. */
     cases: string;
     trials: EvalTrials;
     graders: EvalGrader[];
-    /**
-     * The judge profile model graders run unless they name their own: a text
-     * profile that answers through `evalJudgment`, or a decision profile (Jev).
-     */
     judge?: {
         profile: string;
     };
 }
-/** What the runner runs on a suite module's default export. */
+/** The schema an eval suite parses against. */
 export declare const evalSuiteSchema: z.ZodType<EvalSuite>;

package/esm/src/evals/types.js

@@ -1,16 +1,3 @@
-/**
- * Eval shapes: the suite a host writes, the cases it keeps in JSONL,
- * and the result every grader returns. Each is a documented type and a zod
- * schema checked against it (`Equals`): the type is what graders read; the
- * schema is what the runner runs on a file.
- *
- * Vocabulary follows Anthropic's evals guide so a host can read both: a
- * **suite** of **cases**, each run as k **trials**; a **grader** reads a
- * trial's transcript (its trace) and returns a **result**; the suite's pass
- * rule turns k results into one **verdict**.
- *
- * @module
- */
 import { z } from 'zod';
 import { isRecord } from '../kernel/util/record.js';
 const evalCaseKind = z.enum(['capability', 'regression']);
@@ -75,7 +62,7 @@ const evalCase = z.object({
     tags: z.array(z.string()).optional(),
 });
 true;
-/** What the runner runs on each line of a cases file. */
+/** The schema an eval case parses against. */
 export const evalCaseSchema = evalCase;
 const evalResultSource = z.enum(['code', 'model']);
 true;
@@ -89,7 +76,7 @@ const evalResult = z.object({
     judgeTraceparents: z.array(z.string()).optional(),
 });
 true;
-/** A result as a reader validates it, e.g. one rebuilt from a written event. */
+/** The schema an eval result parses against. */
 export const evalResultSchema = evalResult;
 const evalPassRule = z.union([
     z.literal('all'),
@@ -122,5 +109,5 @@ const evalSuite = z.object({
     judge: z.object({ profile: z.string().min(1) }).optional(),
 });
 true;
-/** What the runner runs on a suite module's default export. */
+/** The schema an eval suite parses against. */
 export const evalSuiteSchema = evalSuite;

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

@@ -1,6 +1,9 @@
 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'];
@@ -12,7 +15,9 @@ interface CaseVerdict {
     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

@@ -1,3 +1,4 @@
+/** The outcome of a trial from its results. */
 function trialOutcome(results) {
     if (results.some((result) => result.errorType !== undefined))
         return 'errored';
@@ -18,10 +19,12 @@ function ruleMet(rule, passed, trials) {
 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';
 }
-// 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.
+// 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;

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

@@ -1,5 +1,6 @@
 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. */