@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +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

@@ -0,0 +1,15 @@
+/** Decodes a base64 string to bytes. */
+export function base64ToBytes(data) {
+    const bin = atob(data);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        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++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}

package/esm/src/kernel/util/exact-type.d.ts

@@ -0,0 +1,31 @@
+export type Probe<X> = <T>() => T extends X ? 1 : 2;
+export type OptionalKeys<T> = {
+    [K in keyof T]-?: Record<never, never> extends Pick<T, K> ? K : never;
+}[keyof T];
+export type MarkedOnce<T> = T extends object ? {
+    [K in keyof T]-?: K extends OptionalKeys<T> ? {
+        optional: T[K];
+    } : T[K];
+} : T;
+/**
+ * Boxed in `Seen` so a union stays one entry. `T`'s own optional fields are marked first,
+ * or a type would pass for one it merely nests in.
+ */
+export type IsSeen<T, Seen> = true extends (Seen extends [infer S] ? Probe<MarkedOnce<S>> extends Probe<MarkedOnce<T>> ? true : false : never) ? true : false;
+/**
+ * The identity check behind `Probe` ignores optionality, so a field only one side leaves out
+ * would pass unmarked. A recursive type is compared as it is where it recurs.
+ */
+export type Marked<T, Seen = never> = IsSeen<T, Seen> extends true ? T : MarkedEach<T, Seen | [T]>;
+export type MarkedEach<T, Seen> = T extends (...args: never[]) => unknown ? T : T extends readonly unknown[] ? {
+    [I in keyof T]: Marked<T[I], Seen>;
+} : T extends object ? {
+    [K in keyof T]-?: K extends OptionalKeys<T> ? {
+        optional: Marked<T[K], Seen>;
+    } : Marked<T[K], Seen>;
+} : T;
+/**
+ * JSR's `no-slow-types` forbids publishing inferred types, so a hand-written type is checked
+ * against its schema: `true satisfies Equals<z.infer<typeof turnStop>, TurnStop>;`.
+ */
+export type Equals<A, B> = Probe<Marked<A>> extends Probe<Marked<B>> ? true : false;

package/esm/src/kernel/util/exact-type.js

@@ -0,0 +1 @@
+export {};

package/esm/src/kernel/util/find-last.d.ts

@@ -0,0 +1,3 @@
+/** `Array.prototype.findLast` is ES2023; this stays ES2022-safe. */
+export declare function findLast<T, S extends T>(items: readonly T[], predicate: (item: T) => item is S): S | undefined;
+export declare function findLast<T>(items: readonly T[], predicate: (item: T) => boolean): T | undefined;

package/esm/src/kernel/util/find-last.js

@@ -0,0 +1,9 @@
+export function findLast(items, predicate) {
+    for (let i = items.length - 1; i >= 0; i -= 1) {
+        const item = items[i];
+        if (item !== undefined && predicate(item)) {
+            return item;
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,2 @@
+/** Lower-case `type/subtype`, parameters removed. */
+export declare function mimeEssence(mime: string): string;

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

@@ -0,0 +1,4 @@
+/** Lower-case `type/subtype`, parameters removed. */
+export function mimeEssence(mime) {
+    return (mime.split(';')[0] ?? '').trim().toLowerCase();
+}

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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +1,14 @@
+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;
+export { clearTraceDestinations, getTraceDestination, isTraceSink, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, };

package/esm/src/observability/destinations.js

@@ -0,0 +1,43 @@
+// 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');
+    }
+    // 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) {
+        throw new TheoremError('config', `Trace destination '${id}' is not registered`);
+    }
+    return found;
+}
+/** The registered destination ids, sorted. */
+function listTraceDestinationIds() {
+    return [...destinations.keys()].sort();
+}
+/** For tests. */
+function clearTraceDestinations() {
+    destinations.clear();
+}
+export { clearTraceDestinations, getTraceDestination, isTraceSink, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, };

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

@@ -0,0 +1,18 @@
+/**
+ * The file trace sink: daily rotating JSONL under a host-chosen directory. Its own entry point, so
+ * browser bundles and Workers never pull the filesystem into their module graph.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import type { TraceSink } from './trace-sink.js';
+/** Retention and rotation are not here: they arrive with each write (`TraceWriteContext`) from the profile. */
+export interface JsonlSinkOptions {
+    now?: () => number;
+}
+/**
+ * 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 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

@@ -0,0 +1,110 @@
+/**
+ * The file trace sink: daily rotating JSONL under a host-chosen directory. Its own entry point, so
+ * browser bundles and Workers never pull the filesystem into their module graph.
+ *
+ * @module
+ */
+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';
+const HOURS_PER_DAY = 24;
+const MIN_PER_HOUR = 60;
+const SEC_PER_MIN = 60;
+const MS_PER_SEC = 1000;
+const KIB = 1024;
+const OWNER_ONLY_DIR = 0o700;
+const OWNER_ONLY_FILE = 0o600;
+const MIB = KIB * KIB;
+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_PART.exec(name)?.[1];
+}
+/** Remove day files older than `retainForDays`; `<= 0` keeps every file. */
+async function pruneTraces(dir, now, retainForDays) {
+    if (retainForDays <= 0) {
+        return;
+    }
+    const retainMs = retainForDays * HOURS_PER_DAY * MIN_PER_HOUR * SEC_PER_MIN * MS_PER_SEC;
+    const cutoff = now - retainMs;
+    for (const name of await readdir(dir)) {
+        const day = fileDay(name);
+        if (day && Date.parse(`${day}T00:00:00.000Z`) < cutoff) {
+            await rm(`${dir}/${name}`);
+        }
+    }
+}
+/** 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 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 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);
+    const now = options.now ?? Date.now;
+    return {
+        write: async (record, context) => {
+            const at = now();
+            // 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);
+            await appendFile(path, `${JSON.stringify(record)}\n`, { mode: OWNER_ONLY_FILE });
+        },
+    };
+}
+function insideDir(path, root) {
+    let base = root;
+    if (root.endsWith('/')) {
+        base = root.slice(0, -1);
+    }
+    if (path === base) {
+        return true;
+    }
+    return path.startsWith(`${base}/`);
+}
+function normalizeAbsolutePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        throw new TheoremError('config', 'trace directory must be non-empty');
+    }
+    if (!trimmed.startsWith('/')) {
+        throw new TheoremError('config', 'trace directory must be absolute');
+    }
+    const parts = [];
+    for (const part of trimmed.split('/')) {
+        if (!part || part === '.') {
+            continue;
+        }
+        if (part === '..') {
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return `/${parts.join('/')}`;
+}
+/** An absolute directory outside the working directory, normalized; throws `config` otherwise. */
+function validateTraceDir(dir) {
+    const normalized = normalizeAbsolutePath(dir);
+    if (insideDir(normalized, normalizeAbsolutePath(cwd()))) {
+        throw new TheoremError('config', 'trace directory must be outside the project checkout');
+    }
+    return normalized;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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
+ */
+import "../../_dnt.polyfills.js";
+export { clearTraceDestinations, getTraceDestination, isTraceSink, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, } from './destinations.js';
+export type { OtlpAnyValue, OtlpKeyValue, OtlpSpan, OtlpTraceRequest } from './otlp.js';
+export { toOtlpJson } from './otlp.js';
+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, 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, ResolvedScrubSwitch, ResolvedTraceInclude, ResolvedTraceScrub, ScrubSwitch, TraceIncludeSpec, TraceScrubSpec, } from './types.js';

package/esm/src/observability/mod.js

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+import "../../_dnt.polyfills.js";
+export { clearTraceDestinations, getTraceDestination, isTraceSink, listTraceDestinationIds, registerTraceDestination, requireTraceDestination, } from './destinations.js';
+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, 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

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+import "../../_dnt.polyfills.js";
+import { type TraceRecord } from './trace-record.js';
+/** Pure: input records are not changed. Export with `toOtlpJson(withOpenInference(records))`. */
+declare function withOpenInference(records: readonly TraceRecord[]): TraceRecord[];
+export { withOpenInference };