@theoremjs/agents 0.3.4-next.476.g46e6627 → 0.3.4-next.480.ge8c8d47

package/README.md

@@ -136,7 +136,7 @@ const support = defineProfile({
     system: "You help customers with their account. Cite the docs you used.",
   },
   models: {
-    main: router.model("openRouter", "openrouter/free"),
+    main: router.model("openRouterOpenAi", "openrouter/free"),
   },
   defaultModel: "main",
   tools: { allow: ["search_tickets"] },
@@ -173,9 +173,9 @@ Use the `type` field to choose what the agent does. The type sets the shape of t
 
 | Type | Runner | Takes | Returns | First-party protocols |
 | :--- | :--- | :--- | :--- | :--- |
-| `text` | `runTurn` | text, attachments, voice notes, slots, history | text, thoughts, validated JSON, tool calls | `geminiInteractions`, `openRouter`, `openAi` |
+| `text` | `runTurn` | text, attachments, voice notes, slots, history | text, thoughts, validated JSON, tool calls | `geminiInteractions`, `openRouterOpenAi`, `openAi` |
 | `image` | `runTurn` | prompt + reference images | images, optionally with interleaved text | `geminiInteractions`, `openRouterImages` |
-| `speech` | `runTurn` | text | audio (WAV, or MP3 on OpenRouter) | `geminiInteractions`, `openRouter`, `openAi` |
+| `speech` | `runTurn` | text | audio (WAV, or MP3 on OpenRouter) | `geminiInteractions`, `openRouterOpenAi`, `openAi` |
 | `live` | `runSession` | realtime mic audio, camera frames, typed text | streamed audio, transcripts, tool calls | `geminiLive` |
 | `host` | `invokeTool`, `invokeToolStep`, `runTool`, `runToolStep` | tool calls from your own code, one at a time or as a step; the `run` pair gives how each call ended | guarded tool results | none; it never calls a model |
 | `decision` | `runDecision` | non-null JSON state plus declared questions | typed choices, probabilities, scores, or `noul` | `systemOne` |
@@ -294,7 +294,7 @@ The binding under `models` names the protocol, the registered provider ID, and t
 | Provider | ID | Protocols |
 | :--- | :--- | :--- |
 | `geminiProvider` | `gemini` | `geminiInteractions` (text, image, speech), `geminiLive` (live) |
-| `openRouterProvider` | `openrouter` | `openRouter` (text, speech), `openRouterImages` (image), `systemOne` (decision) |
+| `openRouterProvider` | `openrouter` | `openRouterOpenAi` (text, speech), `openRouterImages` (image), `openRouterDecisions` (decision) |
 | `typesafeProvider` | `typesafe` | `systemOne` (decision) |
 | `localProvider` | `local` | `openAi` (text, speech), for a server such as Ollama |
 
@@ -468,7 +468,7 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
 | Observability | `memorySink`, `noopSink`, `readTraceparent`, `writeTrace`, `buildRecord`, `traceRecordSchema`, `contentOf`, `inlineContent`, `toOtlpJson`, `startTrace`, `traceContent`, `traceBytes`, `traceJson`, `registerTraceDestination`, `requireTraceDestination`, `getTraceDestination`, `listTraceDestinationIds`, `clearTraceDestinations`, `isTraceSink`, `resolveTraceWriter`, `resolveObservabilityPolicy`, `traceSpanMeta`, `traceAttributeMeta`, `traceEventMeta`, `traceEventAttributeMeta`, `TRACE_ATTRIBUTE_GROUPS`, `TRACE_STATUS`, `TRACE_FIELDS`, `TRACE_SPAN_TYPES`, `TraceSpanMeta`, `TraceSpanType`, `TraceAttributeMeta`, `TraceEventMeta`, `TraceOptionMeta`, `TraceAttributeGroup`, `TraceValueFormat`, `TraceRecord`, `TraceSink`, `TraceWriteContext`, `TraceSpan`, `TraceSpanEvent`, `TraceSpanKind`, `TraceSpanLink`, `TraceSpanStatus`, `TraceAttributes`, `TraceAttributeValue`, `TraceContent`, `TraceBytes`, `TraceJson`, `TraceTree`, `SpanHandle`, `SpanOptions`, `SpanLinkInput`, `TraceClock`, `ProfileObservabilitySpec`, `ResolvedObservabilityPolicy`, `ResolvedTraceInclude`, `ResolvedTraceScrub`, `TraceIncludeSpec`, `TraceScrubSpec`, `ScrubSwitch`, `ResolvedScrubSwitch`, `OtlpTraceRequest`, `OtlpSpan`, `OtlpKeyValue`, `OtlpAnyValue` (file sink: `@theoremjs/agents/observability/jsonl` → `jsonlSink`, `JsonlSinkOptions`) |
 | Providers | `registerProvider`, `getProvider`, `listProviders`, `listProtocols`, `createProviderRegistry`, `defineProvider`, `Provider`, `ProviderDefinition`, `Registration`, `RegisteredProvider`, `ProviderRegistry`, `geminiProvider`, `openRouterProvider`, `typesafeProvider`, `localProvider` |
 | Provider sign-in | `bearer`, `header`, `query`, `Authorize`, `Signer`, `Outgoing`, `Serve`, `endpointUrlSchema` |
-| Protocols | `defineProtocol`, `extendProtocol`, `carriesTo`, `modelOptions`, `geminiInteractions`, `geminiLive`, `geminiEmbedding`, `openAi`, `openRouter`, `openRouterImages`, `openRouterEmbedding`, `ollamaEmbedding`, `systemOne`, `Protocol`, `ProtocolDefinition`, `ProtocolExtension`, `ExtensionBodyAt`, `ExtensionReader`, `ModelProfileType` |
+| Protocols | `defineProtocol`, `extendProtocol`, `carriesTo`, `modelOptions`, `geminiInteractions`, `geminiLive`, `geminiEmbedding`, `openAi`, `openRouterOpenAi`, `openRouterImages`, `openRouterDecisions`, `openRouterEmbedding`, `ollamaEmbedding`, `systemOne`, `Protocol`, `ProtocolDefinition`, `ProtocolExtension`, `ExtensionBodyAt`, `ExtensionReader`, `ModelProfileType` |
 | Protocol operations | `ProtocolContext`, `ProtocolOperations`, `ProtocolRequest`, `ProtocolSession`, `ProtocolSocket`, `ProtocolEvent`, `ProtocolContentEvent`, `SendInit`, `UpstreamFailure`, `Continuation`, `DecisionCall`, `EmbeddingCall`, `LiveToolResult`, `callProtocol`, `ProtocolCall`, `CallSetup` |
 | Model bindings | `ModelBinding`, `DecisionModelBinding`, `modelBindingSchema`, `decisionModelBindingSchema`, `commonModelSettingsSchema`, `keySlotSchema`, `checkBinding`, `keySlotsOf`, `RuntimeAbilities` |
 | Provider data | `JsonValue`, `JsonObject`, `jsonValueSchema`, `jsonObjectSchema`, `PriceTable`, `ModelPrice`, `Rates` |
@@ -512,7 +512,7 @@ Four properties are invariant. Where a test or a lint checks one, the table name
 | P3 | No buried policy — behavioral defaults are declared profile-schema fields | `PROFILE_FIELDS` / schema |
 | P4 | Inert extras — optional entrypoints removable without behavior change | publish-bundle gate excludes `studio/` |
 
-Provider definition and registration validate without opening transport (`src/kernel/protocols/provider.ts`). A protocol never holds a key, a key slot, or a base URL. The kernel signs each request with the registered provider's sign-in.
+Provider definition and registration validate without opening transport (`src/kernel/protocols/provider.ts`). A protocol never holds a key, a key slot, or a base URL. The kernel signs each request with the registered provider's sign-in. A protocol that extends another, as `openRouterDecisions` extends `systemOne`, has its own id, and a binding names the one its provider serves.
 
 Domain rules, delivery policy, product copy, database access, and session memory belong in your application, not in Theorem.
 

package/esm/src/cli/commands/fuzz-canary.js

@@ -23,7 +23,7 @@ function registerFuzzCanaryProfile() {
         identity: { handle: 'fuzz-canary', system: 'Canary fuzz profile.' },
         models: {
             'fuzz-model': {
-                protocol: 'openRouter',
+                protocol: 'openRouterOpenAi',
                 provider: 'openrouter',
                 apiId: 'fuzz-model',
                 keySlot: 'fuzz',

package/esm/src/evals/graders/judge.js

@@ -3,7 +3,7 @@ import { getProfile, registerStructured, runDecision, runTurn, } from '../../ker
 import { mimeAllowed, profileAccept } from '../../kernel/registry/catalog.js';
 import { isRecord } from '../../kernel/util/record.js';
 import { memorySink } from '../../observability/trace.js';
-import { formatTraceparent } from '../../observability/trace-span.js';
+import { formatTraceparent, recordRoot } from '../../observability/trace-span.js';
 import { fillRubric } from '../rubrics/types.js';
 import { buildTrial } from '../trial.js';
 import { resolveMedia, trialMedia } from './media.js';
@@ -70,9 +70,7 @@ function judgeKind(grader, rubric, profileId) {
     return 'text';
 }
 function traceparentsOf(records) {
-    const spans = records[0]?.spans ?? [];
-    const ids = new Set(spans.map((span) => span.spanId));
-    const root = spans.find((span) => span.parentSpanId === undefined || !ids.has(span.parentSpanId));
+    const root = records[0] && recordRoot(records[0]);
     return root ? [formatTraceparent(root.traceId, root.spanId)] : [];
 }
 function judgeStamp(trial, grader) {

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

@@ -2,7 +2,7 @@ import type { RunDecisionOptions } from '../kernel/engine/decision.js';
 import type { ProviderHostOptions } from '../kernel/protocols/runtime.js';
 import type { TraceRecord } from '../observability/trace-record.js';
 import type { TraceSink } from '../observability/trace-sink.js';
-import type { TraceClock } from '../observability/trace-span.js';
+import { type TraceClock } from '../observability/trace-span.js';
 import type { LoadedSuite } from './suite.js';
 import type { EvalCase, EvalMediaResolver, EvalPassRule, EvalResult } from './types.js';
 import { type CaseVerdict, type TrialOutcome } from './verdict.js';

package/esm/src/evals/run.js

@@ -4,6 +4,7 @@ import { isModelProfile } from '../kernel/registry/resolve.js';
 import { isRecord } from '../kernel/util/record.js';
 import { resolveObservabilityPolicy } from '../observability/resolve-policy.js';
 import { memorySink, writeTrace } from '../observability/trace.js';
+import { recordRoot } from '../observability/trace-span.js';
 import { attachmentData } from './attachments.js';
 import { modelCalls, spanDurationMs } from './graders/shared.js';
 import { buildRunRecord, startTrialRecord } from './record.js';
@@ -63,11 +64,6 @@ function erroredResults(graders, evalCase, error) {
         errorType: error,
     }));
 }
-/** The record's root: the span no other span in it parents (a judge call's root has the trial span above it). */
-function recordRoot(record) {
-    const ids = new Set(record.spans.map((span) => span.spanId));
-    return record.spans.find((span) => span.parentSpanId === undefined || !ids.has(span.parentSpanId));
-}
 function recordCost(record) {
     const attributes = recordRoot(record)?.attributes;
     const cost = attributes?.['theorem.usage.cost_usd'];

package/esm/src/guardrails/corpus/fuzz-inbound.js

@@ -17,7 +17,7 @@ function registerFuzzProfile() {
         identity: { handle: 'fuzz', system: 'Fuzz profile.' },
         models: {
             'fuzz-model': {
-                protocol: 'openRouter',
+                protocol: 'openRouterOpenAi',
                 provider: 'openrouter',
                 apiId: 'fuzz-model',
                 keySlot: 'fuzz',

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

@@ -18,5 +18,5 @@ 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 { readTraceparent, recordRoot, 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

@@ -13,4 +13,4 @@ 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';
+export { readTraceparent, recordRoot, startTrace, traceBytes, traceContent, traceJson, } from './trace-span.js';

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

@@ -1,4 +1,4 @@
-import type { TraceAttributes, TraceAttributeValue, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus } from './trace-schema.js';
+import type { TraceAttributes, TraceAttributeValue, TraceRecord, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus } from './trace-schema.js';
 /** In-memory text awaiting scrub + hash at record build. */
 interface TraceContent {
     [key: string]: TraceAttributeValue;
@@ -94,5 +94,10 @@ declare function startTrace(name: string, options?: SpanOptions & {
     traceparent?: string;
     clock?: TraceClock;
 }): TraceTree;
+/**
+ * The record's root: the span no other span in it parents. It may hang under a span that lives
+ * elsewhere: a host's own span over the turn, or an eval's trial span over a judge call.
+ */
+declare function recordRoot(record: TraceRecord): TraceSpan | undefined;
 export type { SpanHandle, SpanLinkInput, SpanOptions, TraceAttributes, TraceAttributeValue, TraceBytes, TraceClock, TraceContent, TraceJson, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanStatus, TraceTree, };
-export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, startTrace, traceBytes, traceContent, traceJson, };
+export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, recordRoot, startTrace, traceBytes, traceContent, traceJson, };

package/esm/src/observability/trace-span.js

@@ -198,4 +198,12 @@ function startTrace(name, options = {}) {
         },
     };
 }
-export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, startTrace, traceBytes, traceContent, traceJson, };
+/**
+ * The record's root: the span no other span in it parents. It may hang under a span that lives
+ * elsewhere: a host's own span over the turn, or an eval's trial span over a judge call.
+ */
+function recordRoot(record) {
+    const ids = new Set(record.spans.map((span) => span.spanId));
+    return record.spans.find((span) => span.parentSpanId === undefined || !ids.has(span.parentSpanId));
+}
+export { formatTraceparent, isTraceBytes, isTraceContent, isTraceJson, parseTraceparent, readTraceparent, recordRoot, startTrace, traceBytes, traceContent, traceJson, };

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

@@ -24,9 +24,10 @@ export { geminiProvider } from './gemini/provider.js';
 export { ollamaEmbedding } from './local/embedding-protocol.js';
 export { localProvider } from './local/provider.js';
 export { openAi } from './open-ai/protocol.js';
+export { openRouterDecisions } from './openrouter/decisions-protocol.js';
 export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
 export { openRouterImages } from './openrouter/images-protocol.js';
-export { openRouter } from './openrouter/protocol.js';
+export { openRouterOpenAi } from './openrouter/protocol.js';
 export { openRouterProvider } from './openrouter/provider.js';
 export { systemOne } from './system-one/protocol.js';
 export { typesafeProvider } from './typesafe/provider.js';

package/esm/src/providers/mod.js

@@ -15,9 +15,10 @@ export { geminiProvider } from './gemini/provider.js';
 export { ollamaEmbedding } from './local/embedding-protocol.js';
 export { localProvider } from './local/provider.js';
 export { openAi } from './open-ai/protocol.js';
+export { openRouterDecisions } from './openrouter/decisions-protocol.js';
 export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
 export { openRouterImages } from './openrouter/images-protocol.js';
-export { openRouter } from './openrouter/protocol.js';
+export { openRouterOpenAi } from './openrouter/protocol.js';
 export { openRouterProvider } from './openrouter/provider.js';
 export { systemOne } from './system-one/protocol.js';
 export { typesafeProvider } from './typesafe/provider.js';

package/esm/src/providers/openrouter/decisions-protocol.d.ts

@@ -0,0 +1,4 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+import { type SystemOneOptions } from '../system-one/protocol.js';
+/** OpenRouter's decision API: System One's questions and answers, at OpenRouter's own endpoint. */
+export declare const openRouterDecisions: Protocol<SystemOneOptions>;

package/esm/src/providers/openrouter/decisions-protocol.js

@@ -0,0 +1,9 @@
+import { extendProtocol } from '../../kernel/protocols/mod.js';
+import { systemOne } from '../system-one/protocol.js';
+/** OpenRouter's decision API: System One's questions and answers, at OpenRouter's own endpoint. */
+export const openRouterDecisions = extendProtocol(systemOne, {
+    id: 'openRouterDecisions',
+    name: 'OpenRouter Decisions',
+    description: "OpenRouter's decision API: questions about a state, answered in one call.", // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { decision: '/alpha/decisions' },
+});

package/esm/src/providers/openrouter/protocol.d.ts

@@ -1,8 +1,8 @@
 import { type Protocol } from '../../kernel/protocols/mod.js';
 import type { CacheSpec } from '../../kernel/types.js';
-/** What an `openRouter` binding sets in `options`. */
+/** What an `openRouterOpenAi` binding sets in `options`. */
 export interface OpenRouterOptions {
     cache?: CacheSpec;
 }
 /** Chat Completions with OpenRouter's caching, routing, web search, citations, and reasoning. */
-export declare const openRouter: Protocol<OpenRouterOptions>;
+export declare const openRouterOpenAi: Protocol<OpenRouterOptions>;

package/esm/src/providers/openrouter/protocol.js

@@ -93,8 +93,8 @@ function thinking(row) {
         .join('');
 }
 /** Chat Completions with OpenRouter's caching, routing, web search, citations, and reasoning. */
-export const openRouter = extendProtocol(openAi, {
-    id: 'openRouter',
+export const openRouterOpenAi = extendProtocol(openAi, {
+    id: 'openRouterOpenAi',
     name: 'OpenRouter Chat Completions',
     description: "Chat Completions with OpenRouter's caching, routing, web search, citations and reasoning.", // labels-exempt: builder field description, read by the studio and docs
     options: z.strictObject({ cache: cache.optional() }),

package/esm/src/providers/openrouter/provider.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
-import { systemOne } from '../system-one/protocol.js';
+import { openRouterDecisions } from './decisions-protocol.js';
 import { openRouterEmbedding } from './embedding-protocol.js';
 import { openRouterImages } from './images-protocol.js';
-import { openRouter } from './protocol.js';
+import { openRouterOpenAi } from './protocol.js';
 const connection = z.strictObject({
     baseUrl: endpointUrlSchema
         .optional()
@@ -41,10 +41,10 @@ export const openRouterProvider = defineProvider({
             headers['X-Title'] = at.siteName;
         const decisionUrl = at.decisionUrl ?? 'https://openrouter.ai/api/alpha/decisions';
         return [
-            { protocol: openRouter, baseUrl, headers },
+            { protocol: openRouterOpenAi, baseUrl, headers },
             { protocol: openRouterEmbedding, baseUrl, headers },
             { protocol: openRouterImages, baseUrl, headers },
-            { protocol: systemOne, baseUrl: decisionUrl, url: () => decisionUrl, headers },
+            { protocol: openRouterDecisions, baseUrl: decisionUrl, url: () => decisionUrl, headers },
         ];
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.476.g46e6627",
+  "version": "0.3.4-next.480.ge8c8d47",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",