@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/engine/turn-trace.d.ts

@@ -1,7 +1,7 @@
 import type { GuardrailEvent, GuardrailStage, TrustLevel } from '../../guardrails/types.js';
 import { type SpanHandle, type SpanLinkInput, type SpanOptions, type TraceAttributes, type TraceAttributeValue } from '../../observability/trace-span.js';
 import type { ToolFailure } from '../tools/types.js';
-import type { InteractionPart, ModelBinding, ProviderCompleteRequest, ProviderEvent, ProviderTransport, TurnEvent, TurnRequest, TurnStop, TurnTokens, TurnTraceLink } from '../types.js';
+import type { InteractionPart, ModelBinding, ModelEvent, ModelRequest, ProviderTransport, TurnEvent, TurnRequest, TurnStop, TurnTokens, TurnTraceLink } from '../types.js';
 import type { CallUsage } from './runner/usage.js';
 type TracePart = {
     [key: string]: TraceAttributeValue;
@@ -13,7 +13,7 @@ declare class OutputFold {
     private open?;
     /** Each call's `tool_call` part by `callId`, for the failure that follows a malformed one. */
     private readonly calls;
-    add(event: ProviderEvent, nowUnixNano: string): void;
+    add(event: ModelEvent, nowUnixNano: string): void;
     private appendText;
     /**
      * The model's call as a `tool_call` part. A malformed call's failure follows
@@ -43,13 +43,14 @@ declare function guardrailAttributes(guardrail: GuardrailEvent): TraceAttributes
  * each tool boundary, the checks that run on streamed output, and a live
  * session's own gates.
  */
-type GuardrailCheck = 'input' | 'egress' | 'tool_arguments' | 'taint' | 'tool_result' | 'tool_failure' | 'network' | 'network_request' | StreamCheck | 'live_input';
+type GuardrailCheck = 'input' | 'egress' | 'tool_arguments' | 'taint' | 'destination' | 'tool_result' | 'tool_failure' | 'network' | 'network_request' | StreamCheck | 'live_input';
 /**
  * A check that runs many times on one model call's streamed output: the
  * progressive gate on each piece of reply text, the canary scan of every other
- * streamed event, and a live session's gate on each batch it sends.
+ * streamed event, the gate on each piece of a tool call the model is drafting,
+ * and a live session's gate on each batch it sends.
  */
-type StreamCheck = 'output_stream' | 'stream_canary' | 'live_output';
+type StreamCheck = 'output_stream' | 'stream_canary' | 'tool_draft' | 'live_output';
 /**
  * One timed guardrail check as `theorem.guardrail` attributes: its decision,
  * or a pass (`allow`, no hits) when it let the text through. Trace only; the
@@ -77,7 +78,7 @@ interface CallTrace {
     /** Pass as the adapter's `tapUpstream`. */
     tap: (row: Record<string, unknown>) => void;
     /** Every provider event, before guardrails. */
-    observe: (event: ProviderEvent) => void;
+    observe: (event: ModelEvent) => void;
     /** A stream check's decision; it carries the time that check has spent on the call so far. */
     guardrail: (event: GuardrailEvent) => void;
     /** Add one run of a stream check to this call. */
@@ -89,7 +90,7 @@ interface CallTrace {
  * `usage.conversation` is read again at the end, since a Live response sets it only when it closes.
  */
 declare function startCallTrace(open: (name: string, options: SpanOptions) => SpanHandle, args: {
-    req: ProviderCompleteRequest;
+    req: ModelRequest;
     usage: CallUsage;
     binding: ModelBinding | undefined;
     transport: ProviderTransport;

package/esm/src/kernel/engine/turn-trace.js

@@ -1,6 +1,7 @@
 import { errorKind } from '../../guardrails/error.js';
 import { traceBytes, traceContent, traceJson, } from '../../observability/trace-span.js';
 import { historyMessageParts } from '../interaction-parts.js';
+import { isFailedStopKind } from '../stop.js';
 import { findLast } from '../util/find-last.js';
 import { asRecord } from './record.js';
 import { sumEventTokens } from './usage.js';
@@ -33,7 +34,6 @@ function tracePart(part) {
 function traceMessage(msg) {
     const media = historyMessageParts(msg).map(tracePart);
     if (msg.role === 'tool') {
-        // The tool's text is its response; media it returned follows as parts.
         const response = {
             type: 'tool_call_response',
             ...(msg.tool_call_id ? { id: msg.tool_call_id } : {}),
@@ -93,7 +93,7 @@ class OutputFold {
                 return;
             case 'evidence': {
                 const { evidence } = event;
-                // Live transcription: labelled, never taken for the model's own text.
+                // why: Live transcription: labelled, never taken for the model's own text.
                 if (evidence.kind === 'input_transcription' || evidence.kind === 'output_transcription') {
                     this.appendText('text', event.text ?? '', evidence.kind, evidence.interim);
                     return;
@@ -103,6 +103,10 @@ class OutputFold {
                     this.push(part);
                 return;
             }
+            case 'tool_draft':
+            case 'structured_draft':
+                // why: A preview of the call or reply that follows; that one is recorded whole.
+                return;
             default:
                 return;
         }
@@ -287,6 +291,7 @@ function guardrailAttributes(guardrail) {
 const STREAM_CHECK_STAGE = {
     output_stream: 'output_delta',
     stream_canary: 'output_delta',
+    tool_draft: 'tool_call',
     live_output: 'live_outbound',
 };
 /**
@@ -342,22 +347,17 @@ function usageAttributes(tokens) {
     };
 }
 function operationName(transport) {
-    return transport === 'openAiCompat' ? 'chat' : 'generate_content';
+    return transport === 'turn' ? 'chat' : 'generate_content';
 }
-/** `gen_ai.provider.name`: semconv's name where one exists; a local server only when declared. */
+/** `gen_ai.provider.name`: the name the provider's preset states; else the binding's server, when declared. */
 function providerName(binding) {
-    switch (binding?.provider) {
-        case 'google':
-            return 'gcp.gemini';
-        case 'openrouter':
-            return 'openrouter';
-        default:
-            return binding?.server;
-    }
+    if (!binding)
+        return undefined;
+    return binding.provider;
 }
 function outputType(req, transport) {
-    // Live answers in audio: its setup asks for `responseModalities: ['AUDIO']` (live/framing.ts).
-    if (transport === 'geminiLive')
+    // why: Live answers in audio: its setup asks for `responseModalities: ['AUDIO']` (live/framing.ts).
+    if (transport === 'live')
         return 'speech';
     if (req.structured)
         return 'json';
@@ -374,35 +374,30 @@ function requestAttributes(req, binding, transport) {
         ...optional('gen_ai.provider.name', provider),
         'gen_ai.request.model': req.apiId,
         'theorem.model.id': req.model,
+        ...optional('theorem.key_slot', binding?.keySlot),
         ...optional('gen_ai.request.temperature', req.temperature),
         ...optional('gen_ai.request.max_tokens', req.maxOutputTokens),
         ...optional('gen_ai.request.reasoning.level', req.thinking),
-        ...optional('gen_ai.request.previous_response.id', req.previousInteractionId),
         'gen_ai.system_instructions': [{ type: 'text', ...traceContent(req.system) }],
         ...(req.wireTools?.length
             ? { 'gen_ai.tool.definitions': traceContent(JSON.stringify(req.wireTools)) }
             : {}),
         'gen_ai.output.type': outputType(req, transport),
-        ...optional('theorem.key_slot', req.keySlot),
         ...controlAttributes(req),
     };
 }
 /**
- * Request controls semconv has no names for, as requested. The Maps location
- * builtin's coordinates are left to the wire body (`outboundWire`): they locate
- * the user.
+ * Request controls semconv has no names for, as requested. Builtins are named
+ * by id only; their args are left to the wire body (`outboundWire`): the Maps
+ * location locates the user.
  */
 function controlAttributes(req) {
-    const { cache, image, speech, live } = req;
+    const { image, speech, live } = req;
     return {
         'theorem.request.builtins': req.builtins.map((b) => b.id),
-        ...optional('theorem.request.store', req.store),
         ...optional('theorem.request.summaries', req.summaries),
         ...optional('theorem.request.structured', req.structured?.id),
         ...optional('theorem.request.session_id', req.sessionId),
-        ...(cache
-            ? { 'theorem.request.cache': { mode: cache.mode, ...optional('ttl', cache.ttl) } }
-            : {}),
         ...(image
             ? {
                 'theorem.request.image': {
@@ -422,6 +417,7 @@ function controlAttributes(req) {
             ? {
                 'theorem.request.speech': {
                     ...optional('voice', speech.voice),
+                    ...optional('speed', speech.speed),
                     ...optional('format', speech.format),
                 },
             }
@@ -463,7 +459,7 @@ function liveAttributes(live, req) {
                 },
             }
             : {}),
-        resumed: Boolean(req.sessionResumptionHandle),
+        resumed: Boolean(req.providerState),
     };
 }
 function headerAttributes(prefix, headers) {
@@ -475,7 +471,7 @@ function urlAttributes(url) {
     if (typeof url !== 'string')
         return {};
     const parsed = URL.canParse(url) ? new URL(url) : undefined;
-    // The path only: a query can carry credentials.
+    // why: The path only: a query can carry credentials.
     return parsed ? { 'server.address': parsed.hostname, 'url.path': parsed.pathname } : {};
 }
 /** POST spans of one call, opened and closed from the adapter's tap rows. */
@@ -523,7 +519,7 @@ class HttpTries {
             },
         });
         this.tries += 1;
-        // The body sent decides, not the profile: an adapter may stream or buffer regardless.
+        // why: The body sent decides, not the profile: an adapter may stream or buffer regardless.
         this.streamed = asRecord(row.body)?.stream === true;
         if (this.streamed)
             this.call.set({ 'gen_ai.request.stream': true });
@@ -547,7 +543,7 @@ class HttpTries {
             this.current?.set({ 'error.type': String(status) });
         }
         else {
-            // Streamed or buffered, the first data row is the reply's first chunk: a buffered body is its one chunk.
+            // why: Streamed or buffered, the first data row is the reply's first chunk: a buffered body is its one chunk.
             this.awaitingFirstChunk = true;
         }
     }
@@ -653,7 +649,7 @@ function callOutcome(stop, failure) {
 function responseAttributes(response, native, transport) {
     const reported = !native
         ? {}
-        : transport === 'openAiCompat'
+        : transport === 'turn'
             ? { 'gen_ai.response.finish_reasons': [native] }
             : { 'gen_ai.response.status': native };
     return {
@@ -697,7 +693,6 @@ function startCallTrace(open, args) {
         },
         observe: (event) => {
             if (event.type === 'evidence' && event.evidence.kind === 'input_transcription') {
-                // What the provider heard in the input: labelled, beside what the model read.
                 heard.add(event, span.nowUnixNano());
                 return;
             }
@@ -757,7 +752,7 @@ function startCallTrace(open, args) {
                 ...optional('finish_reason', outcome.finish),
             };
             const { input } = inputMessages(usage);
-            // A continuation replays what the model read, not the provider's transcript of it.
+            // why: A continuation replays what the model read, not the provider's transcript of it.
             callMessages.set(usage, { input, output: outputMessage });
             const transcript = heard.parts.length > 0 ? [{ role: 'user', parts: heard.parts }] : [];
             http.close(httpStatus(http.lastStatus, outcome.stopped, end.thrown));
@@ -816,8 +811,6 @@ function turnSpanOptions(req) {
         links: traceLinks(req.links),
     };
 }
-/** Stops where the turn failed; the rest either finished or were stopped on purpose. */
-const FAILED_STOPS = new Set(['provider_error', 'stream_incomplete']);
 const FINISHED_STOPS = new Set(['completed', 'length', 'generation_complete']);
 /**
  * Close a turn's `invoke_agent` span. Usage is the sum of this turn's own
@@ -832,10 +825,9 @@ function endTurnSpan(root, end) {
     const threw = end.thrown !== undefined;
     if (threw)
         recordException(root, end.thrown);
-    const failed = threw || (stop !== undefined && FAILED_STOPS.has(stop));
-    // The builder's name for the failure: the thrown value's kind, else the error event's, else the stop.
+    const failed = threw || (stop !== undefined && isFailedStopKind(stop));
     const failure = threw ? errorKind(end.thrown) : (errorEvent?.errorKind ?? stop);
-    // What the host received, beside each call's `output.messages` (what the model produced).
+    // why: What the host received, beside each call's `output.messages` (what the model produced).
     const delivered = {
         role: 'assistant',
         parts: end.delivered.parts,

package/esm/src/kernel/engine/usage.d.ts

@@ -23,6 +23,12 @@ export declare function usageCount(value: unknown): number | undefined;
 export declare function reportedTokens(usage: ReportedUsage): TurnTokens | undefined;
 /** A turn's usage: the sum of its `tokens` events. `done.tokens` and the turn's span both read it. */
 export declare function sumEventTokens(events: readonly TurnEvent[]): TurnTokens | undefined;
+/**
+ * A turn's usage with its agent tool calls': its own `tokens` events plus each
+ * call's `tokens` on the tool's `complete` or `error`. `done.tokens` reads it;
+ * the turn's span keeps `sumEventTokens`, since each call has its own span.
+ */
+export declare function sumTurnTokens(events: readonly TurnEvent[]): TurnTokens | undefined;
 /**
  * A side is `estimated` when any call estimated it. Cost is `partial` when some call reported none;
  * a missing `upstreamUsd` is not missing data (OpenRouter reports it only for BYOK).

package/esm/src/kernel/engine/usage.js

@@ -92,6 +92,23 @@ function sumGrounding(calls) {
 export function sumEventTokens(events) {
     return sumTokens(events.flatMap((event) => (event.type === 'tokens' ? [event.tokens] : [])));
 }
+/**
+ * A turn's usage with its agent tool calls': its own `tokens` events plus each
+ * call's `tokens` on the tool's `complete` or `error`. `done.tokens` reads it;
+ * the turn's span keeps `sumEventTokens`, since each call has its own span.
+ */
+export function sumTurnTokens(events) {
+    return sumTokens(events.flatMap((event) => {
+        if (event.type === 'tokens')
+            return [event.tokens];
+        if (event.type !== 'tool')
+            return [];
+        const { tool } = event;
+        return (tool.phase === 'complete' || tool.phase === 'error') && tool.tokens
+            ? [tool.tokens]
+            : [];
+    }));
+}
 /**
  * A side is `estimated` when any call estimated it. Cost is `partial` when some call reported none;
  * a missing `upstreamUsd` is not missing data (OpenRouter reports it only for BYOK).

package/esm/src/kernel/interaction-parts.d.ts

@@ -1,6 +1,7 @@
 import type { InteractionMediaRefPart, InteractionPart, TurnHistoryMessage } from './types.js';
 /** `toGoogleValue` snake-cases `mimeType` to the documented Interactions `mime_type`. */
 export declare function wireInteractionPart(part: InteractionPart): Record<string, string>;
+/** True for a part that is media referenced by `uri` rather than carried as data. */
 export declare function isMediaRefPart(part: InteractionPart): part is InteractionMediaRefPart;
 /**
  * Everything a history message says, in the one order every provider adapter
@@ -8,3 +9,5 @@ export declare function isMediaRefPart(part: InteractionPart): part is Interacti
  * Neither field replaces the other.
  */
 export declare function historyMessageParts(msg: TurnHistoryMessage): InteractionPart[];
+/** One step's calls as the assistant message that made them, with the reasoning written before them. */
+export declare function historyToolCalls(calls: readonly Pick<import('./turn-events.js').ToolCallRequest, 'callId' | 'name' | 'arguments' | 'reasoning'>[]): TurnHistoryMessage;

package/esm/src/kernel/interaction-parts.js

@@ -8,6 +8,7 @@ export function wireInteractionPart(part) {
     }
     return { type: part.type, mimeType: part.mimeType, data: part.data };
 }
+/** True for a part that is media referenced by `uri` rather than carried as data. */
 export function isMediaRefPart(part) {
     return part.type !== 'text' && 'uri' in part;
 }
@@ -20,3 +21,20 @@ export function historyMessageParts(msg) {
     const parts = msg.parts ?? [];
     return msg.content ? [{ type: 'text', text: msg.content }, ...parts] : [...parts];
 }
+/** One step's calls as the assistant message that made them, with the reasoning written before them. */
+export function historyToolCalls(calls) {
+    const reasoning = calls.flatMap((call) => call.reasoning ?? []);
+    const tool_calls = [];
+    for (const call of calls) {
+        tool_calls.push({
+            id: call.callId,
+            type: 'function',
+            function: { name: call.name, arguments: JSON.stringify(call.arguments) },
+        });
+    }
+    return {
+        role: 'assistant',
+        tool_calls,
+        ...(reasoning.length ? { reasoning: [...reasoning] } : {}),
+    };
+}

package/esm/src/kernel/json.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/** Any value JSON can hold. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare const jsonValueSchema: z.ZodType<JsonValue>;
+export declare const jsonObjectSchema: z.ZodRecord<z.ZodString, z.ZodType<JsonValue>>;

package/esm/src/kernel/json.js

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export const jsonValueSchema = z.json();
+export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);

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

@@ -5,42 +5,69 @@
  */
 import "../../_dnt.polyfills.js";
 export * from './auth/mod.js';
-export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, } from './default-scope.js';
+export type { ProviderCheckpoint, ProviderContinuationPolicy, ProviderStateRebuilt, ProviderWarning, } from './checkpoint.js';
+export { historyHash, providerCheckpointSchema, providerContinuationSchema, providerWarningSchema, } from './checkpoint.js';
+export { clearProfiles, compactHistory, getProfile, getProvider, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listProtocols, listProviders, listTools, projectProfile, registerProfile, registerProfiles, registerProvider, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTurn, } from './default-scope.js';
 export type { CompactionSplit, CompactionTokens } from './engine/compaction.js';
 export { compactionMeter, compactionNeeded, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export type { RunDecisionOptions } from './engine/decision.js';
 export { DecisionError, validateDecisionRequest } from './engine/decision.js';
+export type { RunEmbeddingOptions } from './engine/embedding.js';
 export type { LiveIngressChannel } from './engine/live-ingress.js';
 export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
 export type { RunSessionOptions, SignInGatePolicy } from './engine/session/mod.js';
-export type { MediaPayload, MediaTokenFamily, TokenCount, TokenEstimator, } from './engine/token-estimate.js';
-export { loadTokenEstimator, mediaTokenFamily, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
+export type { TokenCount, TokenEstimator } from './engine/token-estimate.js';
+export { loadTokenEstimator, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
 export { sumTokens } from './engine/usage.js';
 export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export type { JsonObject, JsonValue } from './json.js';
+export { jsonObjectSchema, jsonValueSchema } from './json.js';
 export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
 export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export { unsetValue } from './profile-presence.js';
+export { outOfScopeFields, profileTypesForField } from './profile-scope.js';
+export type { DecisionModelBinding, ModelBinding, RuntimeAbilities } from './protocols/binding.js';
+export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './protocols/binding.js';
+export type { ProviderLimits } from './protocols/limits.js';
+export { providerLimitsSchema, resolveProviderLimits } from './protocols/limits.js';
+export type { EstimatedCost, ModelPrice, PriceTable, Rates } from './protocols/prices.js';
+export { costFromPrices } from './protocols/prices.js';
+export type { Continuation, DecisionCall, EmbeddingCall, EmbeddingMediaKind, EmbeddingModelLimits, ExtensionBodyAt, ExtensionReader, LiveToolResult, ModelProfileType, Protocol, ProtocolContentEvent, ProtocolContext, ProtocolDefinition, ProtocolEvent, ProtocolExtension, ProtocolOperations, ProtocolRequest, ProtocolSession, ProtocolSocket, SendInit, UpstreamFailure, } from './protocols/protocol.js';
+export { carriesTo, defineProtocol, extendProtocol, modelOptions } from './protocols/protocol.js';
+export type { Authorize, DecisionModelSettings, ModelSettings, Outgoing, Provider, ProviderDefinition, ProviderRegistry, RegisteredProvider, Registration, Serve, Signer, } from './protocols/provider.js';
+export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from './protocols/provider.js';
+export type { CallSetup, OpenWebSocket, ProtocolCall, ProviderHostOptions, } from './protocols/runtime.js';
+export { callProtocol, plainWebSocket } from './protocols/runtime.js';
 export type { MediaInputChannel } from './registry/catalog.js';
 export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
 export type { KernelRegistry } from './registry/kernel-registry.js';
 export { createKernelRegistry } from './registry/kernel-registry.js';
-export type { DecisionProfileDefinition, HostProfileDefinition, ImageProfileDefinition, LiveProfileDefinition, ProfileDefinition, ProfileDefinitionBase, ProfileRegistry, SpeechProfileDefinition, TextProfileDefinition, } from './registry/profiles.js';
+export type { DecisionProfileDefinition, EmbeddingProfileDefinition, HostProfileDefinition, ImageProfileDefinition, LiveProfileDefinition, ProfileDefinition, ProfileDefinitionBase, ProfileRegistry, SpeechProfileDefinition, TextProfileDefinition, } from './registry/profiles.js';
 export { createProfileRegistry, defineProfile } from './registry/profiles.js';
 export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
 export type { SchemaRegistry } from './registry/schemas.js';
 export { createSchemaRegistry } from './registry/schemas.js';
-export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, PlaygroundAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
-export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export type { CredentialContext, CredentialResolver, KeyCredential } from './registry/vault.js';
+export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, StudioAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
+export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
 export type { KernelScope } from './scope.js';
 export { createKernelScope, defaultKernelScope } from './scope.js';
 export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageResult, } from './stages.js';
-export { applyStageResult, isAwaitingUserInput, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
 export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
-export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION_TYPES, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { systemPromptProblem } from './system-parts.js';
+export { activityLabelProblem } from './tools/activity-label.js';
+export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
 export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequest, type GateDecision, gateExpired, type HeldGatedCall, resolveGateTtlMs, sessionPermissionsAfterApproval, type ToolGateAuth, } from './tools/gate-answer.js';
-export type { McpProtocolVersion, McpRpcResponse, ToolRegistry } from './tools/mod.js';
-export { askUserTool, coerceToolResultParts, createToolRegistry, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, } from './tools/mod.js';
+export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './tools/mod.js';
+export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
+export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './tools/operation.js';
+export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
+export { jsonSchemaFromZod } from './tools/schema.js';
 export { CredentialRefusedError } from './tools/signed-in-fetch.js';
-export { awaitingUserInputSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
+export type { ModelToolResult, PageAnswer, ToolAuthConfig, ToolContext, ToolLabels, } from './tools/types.js';
+export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
 export type * from './types.js';
 export { base64ToBytes, bytesToBase64 } from './util/base64.js';
 export type { Equals } from './util/exact-type.js';

package/esm/src/kernel/mod.js

@@ -5,26 +5,41 @@
  */
 import "../../_dnt.polyfills.js";
 export * from './auth/mod.js';
-export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, } from './default-scope.js';
+export { historyHash, providerCheckpointSchema, providerContinuationSchema, providerWarningSchema, } from './checkpoint.js';
+export { clearProfiles, compactHistory, getProfile, getProvider, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listProtocols, listProviders, listTools, projectProfile, registerProfile, registerProfiles, registerProvider, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTurn, } from './default-scope.js';
 export { compactionMeter, compactionNeeded, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export { DecisionError, validateDecisionRequest } from './engine/decision.js';
 export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
-export { loadTokenEstimator, mediaTokenFamily, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
+export { loadTokenEstimator, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
 export { sumTokens } from './engine/usage.js';
 export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export { jsonObjectSchema, jsonValueSchema } from './json.js';
 export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export { unsetValue } from './profile-presence.js';
+export { outOfScopeFields, profileTypesForField } from './profile-scope.js';
+export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './protocols/binding.js';
+export { providerLimitsSchema, resolveProviderLimits } from './protocols/limits.js';
+export { costFromPrices } from './protocols/prices.js';
+export { carriesTo, defineProtocol, extendProtocol, modelOptions } from './protocols/protocol.js';
+export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from './protocols/provider.js';
+export { callProtocol, plainWebSocket } from './protocols/runtime.js';
 export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
 export { createKernelRegistry } from './registry/kernel-registry.js';
 export { createProfileRegistry, defineProfile } from './registry/profiles.js';
 export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
 export { createSchemaRegistry } from './registry/schemas.js';
-export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
 export { createKernelScope, defaultKernelScope } from './scope.js';
-export { applyStageResult, isAwaitingUserInput, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
-export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION_TYPES, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { systemPromptProblem } from './system-parts.js';
+export { activityLabelProblem } from './tools/activity-label.js';
+export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
 export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
-export { askUserTool, coerceToolResultParts, createToolRegistry, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, } from './tools/mod.js';
+export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
+export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
+export { jsonSchemaFromZod } from './tools/schema.js';
 export { CredentialRefusedError } from './tools/signed-in-fetch.js';
-export { awaitingUserInputSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
+export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
 export { base64ToBytes, bytesToBase64 } from './util/base64.js';
 export { isRecord } from './util/record.js';

package/esm/src/kernel/profile-graph.d.ts

@@ -1,5 +1,7 @@
 import type { ProfileType } from './schema.js';
+/** The editor a graph facet is edited with: schema-driven or structural. */
 export type ProfileGraphEditor = 'schema' | 'structural';
+/** Where a facet sits in the graph: root, spine, or branch. */
 export type ProfileGraphRole = 'root' | 'spine' | 'branch';
 /**
  * Adding a profile section? Add it to PROFILE_FIELDS and a row here, never a FacetKind in the
@@ -12,7 +14,7 @@ declare const PROFILE_GRAPH_DEF: readonly [{
     readonly optional: false;
     readonly editor: "structural";
     readonly label: "Identity";
-    readonly ownsFields: readonly ["id", "type"];
+    readonly ownsFields: readonly ["profile.id", "profile.type"];
 }, {
     readonly id: "models";
     readonly profilePath: "models";
@@ -20,7 +22,7 @@ declare const PROFILE_GRAPH_DEF: readonly [{
     readonly optional: false;
     readonly editor: "structural";
     readonly label: "Models";
-    readonly ownsFields: readonly ["defaultModel", "allowModelSelect", "maxSteps", "key", "fallbackKey"];
+    readonly ownsFields: readonly ["profile.defaultModel", "profile.allowModelSelect", "profile.maxSteps", "providerContinuation"];
 }, {
     readonly id: "modelBinding";
     readonly profilePath: "models.*";
@@ -109,13 +111,14 @@ declare const PROFILE_GRAPH_DEF: readonly [{
     readonly editor: "structural";
     readonly label: "Observability";
 }, {
-    readonly id: "wording";
-    readonly profilePath: "lexicon";
+    readonly id: "labels";
+    readonly profilePath: "labels";
     readonly role: "spine";
     readonly optional: true;
     readonly editor: "structural";
-    readonly label: "Wording";
+    readonly label: "Labels";
 }];
+/** The id of a profile graph facet. */
 export type ProfileGraphFacetId = (typeof PROFILE_GRAPH_DEF)[number]['id'];
 /** `profilePath` is a PROFILE_FIELDS key (section root) or a dynamic path (`models.*`). */
 export interface ProfileGraphFacet {
@@ -129,12 +132,14 @@ export interface ProfileGraphFacet {
     label: string;
     /**
      * Extra PROFILE_FIELDS top-level keys owned by this facet (not 1:1 with id).
-     * Used by the drift gate so `defaultModel` / `id` / `type` are not orphaned.
+     * Used by the drift gate so `profile.defaultModel` / `profile.id` / `profile.type` are not orphaned.
      */
     ownsFields?: readonly string[];
 }
+/** The profile graph: each facet, with the profile types it applies to. */
 export declare const PROFILE_GRAPH: readonly ProfileGraphFacet[];
 /** Spine (and root) facets visible for a profile type, in catalog order. */
 declare function spineFacetsForProfileType(type: ProfileType): ProfileGraphFacet[];
+/** The facet with this id, or `undefined`. */
 declare function profileGraphFacet(id: ProfileGraphFacetId): ProfileGraphFacet | undefined;
 export { profileGraphFacet, spineFacetsForProfileType };

package/esm/src/kernel/profile-graph.js

@@ -11,7 +11,7 @@ const PROFILE_GRAPH_DEF = [
         optional: false,
         editor: 'structural',
         label: 'Identity',
-        ownsFields: ['id', 'type'],
+        ownsFields: ['profile.id', 'profile.type'],
     },
     {
         id: 'models',
@@ -20,7 +20,12 @@ const PROFILE_GRAPH_DEF = [
         optional: false,
         editor: 'structural',
         label: 'Models',
-        ownsFields: ['defaultModel', 'allowModelSelect', 'maxSteps', 'key', 'fallbackKey'],
+        ownsFields: [
+            'profile.defaultModel',
+            'profile.allowModelSelect',
+            'profile.maxSteps',
+            'providerContinuation',
+        ],
     },
     {
         id: 'modelBinding',
@@ -122,21 +127,22 @@ const PROFILE_GRAPH_DEF = [
         label: 'Observability',
     },
     {
-        id: 'wording',
-        profilePath: 'lexicon',
+        id: 'labels',
+        profilePath: 'labels',
         role: 'spine',
         optional: true,
         editor: 'structural',
-        label: 'Wording',
+        label: 'Labels',
     },
 ];
 /** The facets whose types differ from their `profilePath`'s scope. */
 const FACET_PROFILE_TYPES = {
-    // The root holds `id` and `type`, which every profile has.
+    // why: The root holds `id` and `type`, which every profile has.
     identity: ALL_PROFILE_TYPES,
-    // A decision's inputs belong to its Decision facet.
+    // why: A decision's inputs belong to its Decision facet.
     inputs: profileTypesForField('inputs').filter((type) => type !== 'decision'),
 };
+/** The profile graph: each facet, with the profile types it applies to. */
 export const PROFILE_GRAPH = PROFILE_GRAPH_DEF.map((facet) => ({
     ...facet,
     profileTypes: FACET_PROFILE_TYPES[facet.id] ?? profileTypesForField(facet.profilePath),
@@ -145,6 +151,7 @@ export const PROFILE_GRAPH = PROFILE_GRAPH_DEF.map((facet) => ({
 function spineFacetsForProfileType(type) {
     return PROFILE_GRAPH.filter((facet) => (facet.role === 'root' || facet.role === 'spine') && facet.profileTypes.includes(type));
 }
+/** The facet with this id, or `undefined`. */
 function profileGraphFacet(id) {
     return PROFILE_GRAPH.find((facet) => facet.id === id);
 }