@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/util/base64.d.ts

@@ -1,2 +1,4 @@
+/** Decodes a base64 string to bytes. */
 export declare function base64ToBytes(data: string): Uint8Array<ArrayBuffer>;
+/** Encodes bytes as a base64 string. */
 export declare function bytesToBase64(bytes: Uint8Array): string;

package/esm/src/kernel/util/base64.js

@@ -1,3 +1,4 @@
+/** Decodes a base64 string to bytes. */
 export function base64ToBytes(data) {
     const bin = atob(data);
     const out = new Uint8Array(bin.length);
@@ -5,6 +6,7 @@ export function base64ToBytes(data) {
         out[i] = bin.charCodeAt(i);
     return out;
 }
+/** Encodes bytes as a base64 string. */
 export function bytesToBase64(bytes) {
     let bin = '';
     for (let i = 0; i < bytes.length; i++)

package/esm/src/kernel/util/partial-json.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reads JSON text the model is still writing: what is whole so far, and the string it is in the
+ * middle of. For previews only; the text once whole is parsed as JSON.
+ */
+/** A JSON string read from its opening quote: its text so far, and where it closed, if it has. */
+interface StringRead {
+    text: string;
+    /** The index just past the closing quote; none while the string is still open. */
+    end?: number;
+}
+/**
+ * The string whose opening quote is at `at`, unescaped as far as `text` goes. An escape cut off at
+ * the end is left out rather than shown wrong; an escape JSON does not have reads as its letter.
+ */
+declare function readJsonString(text: string, at: number): StringRead;
+/**
+ * The top-level fields of a JSON object the model is still writing: each field whose value is
+ * whole, and the string being written, as far as it goes. A number, object, or array still being
+ * written is left out: it is not its value yet.
+ */
+declare function partialJsonObject(text: string): Record<string, unknown>;
+export type { StringRead };
+export { partialJsonObject, readJsonString };

package/esm/src/kernel/util/partial-json.js

@@ -0,0 +1,128 @@
+/**
+ * Reads JSON text the model is still writing: what is whole so far, and the string it is in the
+ * middle of. For previews only; the text once whole is parsed as JSON.
+ */
+const ESCAPES = {
+    '"': '"',
+    '\\': '\\',
+    '/': '/',
+    b: '\b',
+    f: '\f',
+    n: '\n',
+    r: '\r',
+    t: '\t',
+};
+/**
+ * The string whose opening quote is at `at`, unescaped as far as `text` goes. An escape cut off at
+ * the end is left out rather than shown wrong; an escape JSON does not have reads as its letter.
+ */
+function readJsonString(text, at) {
+    let out = '';
+    let i = at + 1;
+    while (i < text.length) {
+        const ch = text.charAt(i);
+        if (ch === '"')
+            return { text: out, end: i + 1 };
+        if (ch !== '\\') {
+            out += ch;
+            i++;
+            continue;
+        }
+        if (i + 1 >= text.length)
+            break;
+        const code = text.charAt(i + 1);
+        if (code === 'u') {
+            const hex = text.slice(i + 2, i + 6);
+            if (hex.length < 4)
+                break;
+            if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+                out += String.fromCharCode(Number.parseInt(hex, 16));
+                i += 6;
+                continue;
+            }
+        }
+        out += ESCAPES[code] ?? code;
+        i += 2;
+    }
+    return { text: out };
+}
+function skipSpace(text, i) {
+    let at = i;
+    while (/\s/.test(text.charAt(at)))
+        at++;
+    return at;
+}
+/** The JSON value at `at` in `text` and the index past it, or none while `text` ends before it does. */
+function wholeJsonValueAt(text, at) {
+    if (text.charAt(at) === '"') {
+        const read = readJsonString(text, at);
+        return read.end === undefined ? undefined : parsedSlice(text, at, read.end);
+    }
+    let depth = 0;
+    for (let i = at; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (ch === '"') {
+            const end = readJsonString(text, i).end;
+            if (end === undefined)
+                return undefined;
+            i = end - 1;
+        }
+        else if (ch === '{' || ch === '[')
+            depth++;
+        else if (ch === '}' || ch === ']') {
+            if (depth === 0)
+                return parsedSlice(text, at, i);
+            depth--;
+            if (depth === 0)
+                return parsedSlice(text, at, i + 1);
+        }
+        else if (ch === ',' && depth === 0)
+            return parsedSlice(text, at, i);
+    }
+    return undefined;
+}
+function parsedSlice(text, from, to) {
+    try {
+        return { value: JSON.parse(text.slice(from, to)), end: to };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The top-level fields of a JSON object the model is still writing: each field whose value is
+ * whole, and the string being written, as far as it goes. A number, object, or array still being
+ * written is left out: it is not its value yet.
+ */
+function partialJsonObject(text) {
+    const fields = {};
+    let i = skipSpace(text, 0);
+    if (text.charAt(i) !== '{')
+        return fields;
+    i++;
+    for (;;) {
+        i = skipSpace(text, i);
+        if (text.charAt(i) === ',')
+            i = skipSpace(text, i + 1);
+        if (text.charAt(i) !== '"')
+            return fields;
+        const key = readJsonString(text, i);
+        if (key.end === undefined)
+            return fields;
+        i = skipSpace(text, key.end);
+        if (text.charAt(i) !== ':')
+            return fields;
+        i = skipSpace(text, i + 1);
+        if (i >= text.length)
+            return fields;
+        const value = wholeJsonValueAt(text, i);
+        if (!value) {
+            if (text.charAt(i) === '"')
+                fields[key.text] = readJsonString(text, i).text;
+            return fields;
+        }
+        fields[key.text] = value.value;
+        i = value.end;
+    }
+}
+export { partialJsonObject, readJsonString };

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

@@ -1 +1,2 @@
+/** True for a non-null object that is not an array. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;

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

@@ -1,3 +1,4 @@
+/** True for a non-null object that is not an array. */
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/esm/src/observability/destinations.d.ts

@@ -1,8 +1,13 @@
 import type { TraceSink } from './trace-sink.js';
+/** True when the value is a trace sink. */
 declare function isTraceSink(value: unknown): value is TraceSink;
+/** Register a trace sink under an id; throws when the id is empty. */
 declare function registerTraceDestination(id: string, destination: TraceSink): void;
+/** The sink registered under the id, or `undefined`. */
 declare function getTraceDestination(id: string): TraceSink | undefined;
+/** The sink registered under the id; throws when there is none. */
 declare function requireTraceDestination(id: string): TraceSink;
+/** The registered destination ids, sorted. */
 declare function listTraceDestinationIds(): string[];
 /** For tests. */
 declare function clearTraceDestinations(): void;

package/esm/src/observability/destinations.js

@@ -1,26 +1,30 @@
-// THEOREM does not invent filesystem roots: hosts register a named destination once per process.
+// invariant: THEOREM does not invent filesystem roots: hosts register a named destination once per process.
 import { TheoremError } from '../guardrails/error.js';
 const destinations = new Map();
+/** True when the value is a trace sink. */
 function isTraceSink(value) {
     return (typeof value === 'object' &&
         value !== null &&
         'write' in value &&
         typeof value.write === 'function');
 }
+/** Register a trace sink under an id; throws when the id is empty. */
 function registerTraceDestination(id, destination) {
     const key = id.trim();
     if (!key) {
         throw new TheoremError('config', 'registerTraceDestination requires a non-empty id');
     }
-    // Hosts may call from plain JS: the registry holds only writers.
+    // why: Hosts may call from plain JS: the registry holds only writers.
     if (!isTraceSink(destination)) {
         throw new TheoremError('config', `Trace destination '${key}' must be a TraceSink`);
     }
     destinations.set(key, destination);
 }
+/** The sink registered under the id, or `undefined`. */
 function getTraceDestination(id) {
     return destinations.get(id);
 }
+/** The sink registered under the id; throws when there is none. */
 function requireTraceDestination(id) {
     const found = getTraceDestination(id);
     if (!found) {
@@ -28,6 +32,7 @@ function requireTraceDestination(id) {
     }
     return found;
 }
+/** The registered destination ids, sorted. */
 function listTraceDestinationIds() {
     return [...destinations.keys()].sort();
 }

package/esm/src/observability/jsonl.d.ts

@@ -12,7 +12,7 @@ export interface JsonlSinkOptions {
 }
 /**
  * Daily rotating JSONL files under an absolute, host-chosen `dir`. Each write removes day files
- * older than the record's retention (`<= 0` keeps every file) and starts a new file once the
- * day's reaches the profile's `rotateAfterMiB`.
+ * older than the record's retention (`<= 0` keeps every file) and appends to the day's newest file
+ * until it reaches the profile's `rotateAfterMiB`, then starts another.
  */
 export declare function jsonlSink(dir: string, options?: JsonlSinkOptions): TraceSink;

package/esm/src/observability/jsonl.js

@@ -8,7 +8,6 @@ import "../../_dnt.polyfills.js";
 import { appendFile, mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { cwd } from 'node:process';
 import { TheoremError } from '../guardrails/error.js';
-import { isRecord } from '../kernel/util/record.js';
 const HOURS_PER_DAY = 24;
 const MIN_PER_HOUR = 60;
 const SEC_PER_MIN = 60;
@@ -17,12 +16,12 @@ const KIB = 1024;
 const OWNER_ONLY_DIR = 0o700;
 const OWNER_ONLY_FILE = 0o600;
 const MIB = KIB * KIB;
-const FILE_DAY = /^turns-(\d{4}-\d{2}-\d{2})(?:-\d+)?\.jsonl$/;
+const FILE_PART = /^turns-(\d{4}-\d{2}-\d{2})(?:-(\d+))?\.jsonl$/;
 function dayStamp(ms) {
     return new Date(ms).toISOString().slice(0, 10);
 }
 function fileDay(name) {
-    return FILE_DAY.exec(name)?.[1];
+    return FILE_PART.exec(name)?.[1];
 }
 /** Remove day files older than `retainForDays`; `<= 0` keeps every file. */
 async function pruneTraces(dir, now, retainForDays) {
@@ -38,29 +37,23 @@ async function pruneTraces(dir, now, retainForDays) {
         }
     }
 }
-function isMissing(err) {
-    return isRecord(err) && err.code === 'ENOENT';
-}
+/** The day's newest file while it has room, else a new one stamped `now`. */
 async function pickFile(dir, now, rotateBytes) {
     const day = dayStamp(now);
-    const base = `${dir}/turns-${day}.jsonl`;
-    try {
-        if ((await stat(base)).size < rotateBytes) {
-            return base;
-        }
-    }
-    catch (err) {
-        if (isMissing(err)) {
-            return base;
-        }
-        throw err;
-    }
-    return `${dir}/turns-${day}-${now}.jsonl`;
+    const newest = (await readdir(dir))
+        .map((name) => ({ name, part: FILE_PART.exec(name) }))
+        .filter(({ part }) => part?.[1] === day)
+        .map(({ name, part }) => ({ name, stamp: Number(part?.[2] ?? 0) }))
+        .reduce((latest, file) => (latest && latest.stamp >= file.stamp ? latest : file), undefined);
+    if (!newest)
+        return `${dir}/turns-${day}.jsonl`;
+    const path = `${dir}/${newest.name}`;
+    return (await stat(path)).size < rotateBytes ? path : `${dir}/turns-${day}-${now}.jsonl`;
 }
 /**
  * Daily rotating JSONL files under an absolute, host-chosen `dir`. Each write removes day files
- * older than the record's retention (`<= 0` keeps every file) and starts a new file once the
- * day's reaches the profile's `rotateAfterMiB`.
+ * older than the record's retention (`<= 0` keeps every file) and appends to the day's newest file
+ * until it reaches the profile's `rotateAfterMiB`, then starts another.
  */
 export function jsonlSink(dir, options = {}) {
     const safeDir = validateTraceDir(dir);
@@ -68,7 +61,7 @@ export function jsonlSink(dir, options = {}) {
     return {
         write: async (record, context) => {
             const at = now();
-            // Records hold conversation content: readable by the host's user only.
+            // why: Records hold conversation content: readable by the host's user only.
             await mkdir(safeDir, { recursive: true, mode: OWNER_ONLY_DIR });
             await pruneTraces(safeDir, at, context.retainForDays);
             const path = await pickFile(safeDir, at, context.rotateAfterMiB * MIB);

package/esm/src/observability/mod.d.ts

@@ -1,5 +1,5 @@
 /**
- * Trace sinks, the destination registry, observability policy, the span builder and the trace
+ * Trace sinks, the destination registry, observability policy, the span builder, and the trace
  * catalog. THEOREM owns no database: hosts register destinations or pass a sink into `runTurn`.
  *
  * @module
@@ -12,11 +12,11 @@ export { resolveTraceWriter } from './policy.js';
 export { resolveObservabilityPolicy } from './resolve-policy.js';
 export { memorySink, noopSink, writeTrace, } from './trace.js';
 export type { TraceAttributeGroup, TraceAttributeMeta, TraceEventMeta, TraceOptionMeta, TraceSpanMeta, TraceSpanType, TraceValueFormat, } from './trace-catalog.js';
-export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, } from './trace-catalog.js';
+export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceCatalogRows, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, } from './trace-catalog.js';
 export type { TraceRecord } from './trace-record.js';
 export { buildRecord, contentOf, inlineContent } from './trace-record.js';
 export { traceRecordSchema } from './trace-schema.js';
 export type { TraceSink, TraceWriteContext } from './trace-sink.js';
 export type { SpanHandle, SpanLinkInput, SpanOptions, TraceAttributes, TraceAttributeValue, TraceBytes, TraceClock, TraceContent, TraceJson, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus, TraceTree, } from './trace-span.js';
 export { readTraceparent, startTrace, traceBytes, traceContent, traceJson, } from './trace-span.js';
-export type { ProfileObservabilitySpec, ResolvedObservabilityPolicy, ResolvedTraceInclude, ResolvedTraceScrub, TraceIncludeSpec, TraceScrubSpec, } from './types.js';
+export type { ProfileObservabilitySpec, ResolvedObservabilityPolicy, ResolvedScrubSwitch, ResolvedTraceInclude, ResolvedTraceScrub, ScrubSwitch, TraceIncludeSpec, TraceScrubSpec, } from './types.js';

package/esm/src/observability/mod.js

@@ -1,5 +1,5 @@
 /**
- * Trace sinks, the destination registry, observability policy, the span builder and the trace
+ * Trace sinks, the destination registry, observability policy, the span builder, and the trace
  * catalog. THEOREM owns no database: hosts register destinations or pass a sink into `runTurn`.
  *
  * @module
@@ -10,7 +10,7 @@ export { toOtlpJson } from './otlp.js';
 export { resolveTraceWriter } from './policy.js';
 export { resolveObservabilityPolicy } from './resolve-policy.js';
 export { memorySink, noopSink, writeTrace, } from './trace.js';
-export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, } from './trace-catalog.js';
+export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceCatalogRows, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, } from './trace-catalog.js';
 export { buildRecord, contentOf, inlineContent } from './trace-record.js';
 export { traceRecordSchema } from './trace-schema.js';
 export { readTraceparent, startTrace, traceBytes, traceContent, traceJson, } from './trace-span.js';

package/esm/src/observability/openinference.d.ts

@@ -1,5 +1,5 @@
 /**
- * OpenInference attributes for Phoenix, whose message views, reasoning tokens and cost read only
+ * OpenInference attributes for Phoenix, whose message views, reasoning tokens, and cost read only
  * OpenInference names; they are copied beside the semconv names so `toOtlpJson` stays neutral.
  *
  * @module

package/esm/src/observability/openinference.js

@@ -1,5 +1,5 @@
 /**
- * OpenInference attributes for Phoenix, whose message views, reasoning tokens and cost read only
+ * OpenInference attributes for Phoenix, whose message views, reasoning tokens, and cost read only
  * OpenInference names; they are copied beside the semconv names so `toOtlpJson` stays neutral.
  *
  * @module
@@ -24,7 +24,7 @@ function openInferenceUsage(attributes) {
         ...(typeof reasoning === 'number'
             ? { 'llm.token_count.completion_details.reasoning': reasoning }
             : {}),
-        // A partial cost would read as the call's total; it keeps only its theorem.* name.
+        // why: A partial cost would read as the call's total; it keeps only its theorem.* name.
         ...(typeof cost === 'number' && attributes['theorem.usage.cost_partial'] !== true
             ? { 'llm.cost.total': cost }
             : {}),
@@ -142,7 +142,7 @@ function jsonValue(record, side, value) {
 }
 /**
  * Phoenix derives no kind for an operation semconv does not name, and has no price for Jev, so
- * the kind, model, tokens and cost are stated. It has no messages, so Phoenix cannot replay it.
+ * the kind, model, tokens, and cost are stated. It has no messages, so Phoenix cannot replay it.
  */
 function openInferenceDecision(record, span) {
     const { attributes } = span;

package/esm/src/observability/otlp.d.ts

@@ -1,4 +1,5 @@
 import { type TraceRecord } from './trace-record.js';
+/** An OTLP/JSON attribute value. */
 type OtlpAnyValue = {
     stringValue: string;
 } | {
@@ -16,10 +17,12 @@ type OtlpAnyValue = {
         values: OtlpKeyValue[];
     };
 };
+/** An OTLP/JSON attribute: a key and its value. */
 interface OtlpKeyValue {
     key: string;
     value: OtlpAnyValue;
 }
+/** A span as OTLP/JSON carries it. */
 interface OtlpSpan {
     traceId: string;
     spanId: string;

package/esm/src/observability/otlp.js

@@ -1,4 +1,4 @@
-// OTLP has no record-level slot for `TraceRecord.metadata` (the resource is the service's
+// why: OTLP has no record-level slot for `TraceRecord.metadata` (the resource is the service's
 // identity), so each key lands on the record's top spans as `theorem.metadata.<key>`.
 import { inlineContent } from './trace-record.js';
 const SCOPE_NAME = '@theoremjs/agents';
@@ -12,7 +12,7 @@ function anyValue(value) {
         return { boolValue: value };
     }
     if (typeof value === 'number') {
-        // int64 is a decimal string in OTLP/JSON.
+        // why: int64 is a decimal string in OTLP/JSON.
         return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
     }
     if (Array.isArray(value)) {
@@ -21,7 +21,7 @@ function anyValue(value) {
     if (value && typeof value === 'object') {
         return { kvlistValue: { values: keyValues(value) } };
     }
-    // null / undefined: OTLP has no empty value, so the key is left out.
+    // why: null / undefined: OTLP has no empty value, so the key is left out.
     return undefined;
 }
 function keyValues(fields) {

package/esm/src/observability/phoenix.d.ts

@@ -6,6 +6,7 @@
  */
 import "../../_dnt.polyfills.js";
 import { type TraceRecord } from './trace-record.js';
+/** A Phoenix annotation on a judged trial span: its name, whether an LLM judge or a code grader produced it, the result, and metadata. */
 interface PhoenixSpanAnnotation {
     /** The judged root span, as OTLP hex. */
     span_id: string;

package/esm/src/observability/policy.d.ts

@@ -1,3 +1,4 @@
+import type { ProfileGuardrailsSpec } from '../guardrails/types.js';
 import type { TraceSink } from './trace-sink.js';
 import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './types.js';
 /**
@@ -7,6 +8,8 @@ import type { ProfileObservabilitySpec, ResolvedObservabilityPolicy } from './ty
 declare function resolveTraceWriter(args: {
     override?: TraceSink;
     observability?: ProfileObservabilitySpec;
+    /** The profile's guardrails: the patterns a host gave its detectors clean the record too. */
+    guardrails?: ProfileGuardrailsSpec;
 }): {
     sink: TraceSink;
     policy: ResolvedObservabilityPolicy;

package/esm/src/observability/policy.js

@@ -1,3 +1,4 @@
+import { resolveGuardrailPolicy } from '../guardrails/policy.js';
 import { requireTraceDestination } from './destinations.js';
 import { resolveObservabilityPolicy } from './resolve-policy.js';
 import { noopSink } from './trace.js';
@@ -51,7 +52,10 @@ function sinkFromWriteTo(writeTo, policy) {
  * override always records, ignoring `sampleRate`, so tests and one-off capture are deterministic.
  */
 function resolveTraceWriter(args) {
-    const policy = resolveObservabilityPolicy(args.observability);
+    const policy = {
+        ...resolveObservabilityPolicy(args.observability),
+        detect: resolveGuardrailPolicy(args.guardrails).detect,
+    };
     if (args.override) {
         return {
             policy,

package/esm/src/observability/resolve-policy.js

@@ -1,4 +1,4 @@
-// Pure, with no sinks or file system, so kernel type consumers never pull the JSONL sink into their
+// why: Pure, with no sinks or file system, so kernel type consumers never pull the JSONL sink into their
 // graph.
 import { TheoremError } from '../guardrails/error.js';
 /** Default record retention in days; `<= 0` keeps records forever. */
@@ -6,7 +6,7 @@ const DEFAULT_RETAIN_DAYS = 14;
 /** Default JSONL file size, in MiB, before the writer rotates to a new file. */
 const DEFAULT_ROTATE_MIB = 32;
 function resolveInclude(spec) {
-    // No authored block records only through an explicit capture sink (tests,
+    // why: No authored block records only through an explicit capture sink (tests,
     // `runTurn(..., sink)`), which keeps wire and raw evidence. Authored blocks
     // default those two off.
     const authored = spec !== undefined;
@@ -19,11 +19,17 @@ function resolveInclude(spec) {
         guardrailMatchPreview: spec?.include?.guardrailMatchPreview ?? false,
     };
 }
+function resolveSwitch(spec) {
+    if (spec === undefined || typeof spec === 'boolean')
+        return spec ?? true;
+    const sides = { theorem: spec.theorem ?? true, host: spec.host ?? true };
+    return (sides.theorem || sides.host) && sides;
+}
 function resolveScrub(spec) {
     return {
-        sensitive: spec?.scrub?.sensitive ?? true,
-        injection: spec?.scrub?.injection ?? true,
-        canary: spec?.scrub?.canary ?? true,
+        sensitive: resolveSwitch(spec?.scrub?.sensitive),
+        injection: resolveSwitch(spec?.scrub?.injection),
+        canary: resolveSwitch(spec?.scrub?.canary),
     };
 }
 function clampSampleRate(value) {

package/esm/src/observability/spans.d.ts

@@ -1,16 +1,22 @@
 declare const OMIT_INJECTION = "[omitted - injection]";
 declare const OMIT_SENSITIVE = "[omitted -sensitive]";
-type RedactKind = 'injection' | 'sensitive';
+declare const OMIT_CANARY = "[omitted - canary]";
+type RedactKind = 'injection' | 'sensitive' | 'canary' | 'prompt' | 'image' | 'link' | 'tool' | 'directive' | 'host';
 interface RedactSpan {
     start: number;
     end: number;
     kind: RedactKind;
+    /** The name of the host's pattern that matched; unset for a match of Theorem's own. */
+    name?: string;
+    /** What about the match makes it one, for a detector that finds more than one thing. */
+    signal?: string;
 }
 declare function blobAt(match: RegExpMatchArray): {
     blob: string;
     index: number;
 } | undefined;
+declare function mergeSpans(spans: RedactSpan[]): RedactSpan[];
 declare function applySpans(text: string, spans: RedactSpan[]): string;
 declare function spansFromPatterns(text: string, patterns: RegExp[], kind: RedactKind): RedactSpan[];
 export type { RedactKind, RedactSpan };
-export { applySpans, blobAt, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns };
+export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns, };

package/esm/src/observability/spans.js

@@ -1,10 +1,26 @@
 const OMIT_INJECTION = '[omitted - injection]';
 const OMIT_SENSITIVE = '[omitted -sensitive]';
+const OMIT_CANARY = '[omitted - canary]';
+const OMIT_PROMPT = '[omitted - instructions]';
+const OMIT_IMAGE = '[omitted - image]';
+const OMIT_LINK = '[omitted - link]';
+const OMIT_TOOL = '[omitted - tool]';
+const OMIT_DIRECTIVE = '[omitted - directive]';
+/** A match of a detector of the host's own: it says nothing of what was there. */
+const OMIT_HOST = '[omitted]';
+const OMIT = {
+    injection: OMIT_INJECTION,
+    sensitive: OMIT_SENSITIVE,
+    canary: OMIT_CANARY,
+    prompt: OMIT_PROMPT,
+    image: OMIT_IMAGE,
+    link: OMIT_LINK,
+    tool: OMIT_TOOL,
+    directive: OMIT_DIRECTIVE,
+    host: OMIT_HOST,
+};
 function tokenFor(kind) {
-    if (kind === 'injection') {
-        return OMIT_INJECTION;
-    }
-    return OMIT_SENSITIVE;
+    return OMIT[kind];
 }
 function blobAt(match) {
     const [blob] = match;
@@ -53,4 +69,4 @@ function spansFromPatterns(text, patterns, kind) {
     }
     return spans;
 }
-export { applySpans, blobAt, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns };
+export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_SENSITIVE, spansFromPatterns, };

package/esm/src/observability/trace-catalog.d.ts

@@ -15,11 +15,14 @@ type TraceValueFormat = 'text'
  | 'parts'
 /** A unix-nanosecond timestamp string. */
  | 'time';
+/** The groups the attribute catalog sorts attributes into. */
 type TraceAttributeGroup = 'agent' | 'request' | 'response' | 'messages' | 'usage' | 'tool' | 'http' | 'error' | 'record' | 'part' | 'decision' | 'evaluation';
+/** A label and description for one option in a catalog. */
 interface TraceOptionMeta {
     label: string;
     doc: string;
 }
+/** What the catalog says about a span attribute: its label, description, and format. */
 interface TraceAttributeMeta {
     label: string;
     doc: string;
@@ -31,6 +34,7 @@ interface TraceAttributeMeta {
     /** For an `object`: what its keys mean (for a list of objects, each item's keys). */
     fields?: Readonly<Record<string, TraceAttributeMeta>>;
 }
+/** What the catalog says about a span event: its label, description, and keys. */
 interface TraceEventMeta {
     label: string;
     doc: string;
@@ -39,14 +43,16 @@ interface TraceEventMeta {
 }
 /** The kinds of span THEOREM writes, plus `host` for a span the host recorded itself. */
 type TraceSpanType = 'turn' | 'session' | 'call' | 'response' | 'tool' | 'http' | 'cutout' | 'decision' | 'evaluation' | 'host';
-/** `subject` is the thing the span acted on (the model, tool or agent), when it names one. */
+/** `subject` is the thing the span acted on (the model, tool, or agent), when it names one. */
 interface TraceSpanMeta {
     type: TraceSpanType;
     label: string;
     doc: string;
     subject?: string;
 }
+/** Labels and descriptions for each attribute group. */
 declare const TRACE_ATTRIBUTE_GROUPS: Readonly<Record<TraceAttributeGroup, TraceOptionMeta>>;
+/** Labels and descriptions for each span status. */
 declare const TRACE_STATUS: Readonly<Record<TraceSpan['status']['code'], TraceOptionMeta>>;
 /** A record's and a span's own fields, beside their attributes. */
 declare const TRACE_FIELDS: {
@@ -105,7 +111,18 @@ declare function traceAttributeMeta(key: string): TraceAttributeMeta | undefined
 declare function traceEventMeta(name: string): TraceEventMeta | undefined;
 /** The event's own entry, else the span attribute of that key. */
 declare function traceEventAttributeMeta(event: string, key: string): TraceAttributeMeta | undefined;
+/** Labels and descriptions for each span type. */
 declare const TRACE_SPAN_TYPES: Readonly<Record<TraceSpanType, TraceOptionMeta>>;
+/**
+ * Every trace field and span type, named by the record they belong to: `trace.resource`, and a
+ * span type by the field it fills, `trace.type.turn`.
+ */
+declare function traceCatalogRows(): readonly {
+    name: string;
+    label: string;
+    doc: string;
+}[];
+/** The label, subject, and description to show for a span. */
 declare function traceSpanMeta(span: TraceSpan): TraceSpanMeta;
 export type { TraceAttributeGroup, TraceAttributeMeta, TraceEventMeta, TraceOptionMeta, TraceSpanMeta, TraceSpanType, TraceValueFormat, };
-export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, };
+export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceCatalogRows, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, };