@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,27 +1,46 @@
-import type { LexiconOverrides } from '../guardrails/lexicon.js';
-import type { SensitiveGroups } from '../guardrails/sensitive.js';
+import type { Boundary } from '../guardrails/boundaries.js';
+import type { DetectAction, DetectMatrix, Detector, UrlDetector } from '../guardrails/detectors.js';
+import type { GuardrailEvent } from '../guardrails/event-schemas.js';
+import type { LabelOverrides } from '../guardrails/labels.js';
 import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
-import type { LiveProfileToolsSpec, ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
-import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
+import type { ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
+import type { ReasoningPart } from '../kernel/turn-events.js';
+import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
 import type { ResolvedObservabilityPolicy } from '../observability/types.js';
-/** A URL check as it runs; `false` when off. */
-export type UrlCheckView = false | {
+/** What a URL detector lets through besides the given URLs, with its defaults applied. */
+export interface UrlAllowView {
     hosts: string[];
     fromTools: boolean;
-};
-/** The bundled egress checks a profile's reply runs through. */
-export interface EgressChecksView {
-    sensitive: SensitiveGroups;
-    boundary: boolean;
-    injection: boolean;
-    images: UrlCheckView;
-    links: UrlCheckView;
-}
-/** Guardrails visible to UI — egress enforcer functions are omitted. */
-export type ProfileGuardrailsView = Pick<ResolvedGuardrailPolicy, 'quota' | 'canary' | 'sanitizeInput' | 'redactSensitive'> & {
-    hasEgress: boolean;
-    /** `null` with no egress check, or a host `enforce` whose checks are its own. */
-    egressChecks: EgressChecksView | null;
+}
+/** Whose patterns one detector reads with: the host's are named, never shown. */
+export interface DetectorPatternsView {
+    /** Whether Theorem's own patterns run. */
+    theorem: boolean;
+    /** The names of the host's patterns. */
+    names: string[];
+}
+/** A detector of the host's own: what it is called and where it applies, never what it matches. */
+export interface HostDetectorView {
+    /** Its key in `guardrails.detect`, as in `acme.record`. Its rule is `detect.<id>`. */
+    id: string;
+    label: string;
+    /** Its action at every boundary. */
+    actions: Record<Boundary, DetectAction>;
+    /** The names of its patterns. */
+    names: string[];
+    /** Whether it also reads with a function of the host's. */
+    find: boolean;
+}
+/** Guardrails visible to UI — a host detector's `find` is told of, not sent. */
+export type ProfileGuardrailsView = Pick<ResolvedGuardrailPolicy, 'quota' | 'blockedReply'> & {
+    /** Every detector's action at every boundary. */
+    detect: DetectMatrix;
+    /** Whose patterns a detector reads with, for each one the profile changed it for. */
+    patterns?: Partial<Record<Detector, DetectorPatternsView>>;
+    /** The host's own detectors, in the order the profile lists them. The kernel reads with them. */
+    host?: HostDetectorView[];
+    /** What `ungiven_images` and `ungiven_links` let through. */
+    allow: Record<UrlDetector, UrlAllowView>;
 };
 /** Observability visible to UI — TraceSink / onWriteError functions are omitted. */
 export type ProfileObservabilityView = Pick<ResolvedObservabilityPolicy, 'record' | 'sampleRate' | 'include' | 'scrub' | 'resource' | 'retainForDays' | 'rotateAfterMiB'> & {
@@ -44,48 +63,62 @@ export interface ProfileInputsInterface {
     maxTurnBytes?: number;
     limitsByMime?: Record<string, number>;
     slots?: Record<string, string[]>;
+    context?: ProfileContextSpec;
 }
-/** A tool's definition (handler, schemas, endpoint, headers) stays on the host; `t1Policy` too. */
-export type ProfileToolsView = Pick<ProfileToolsSpec, 'allow' | 't2Loader'>;
+/**
+ * A tool's definition (handler, schemas, endpoint, headers) stays on the host; `t1Policy` too.
+ * `page` names the tools the page answers (`answeredBy: 'page'`): the page needs a function for each.
+ */
+export type ProfileToolsView = Pick<ProfileToolsSpec, 'allow' | 't2Loader' | 'parallel'> & {
+    page: string[];
+};
 /** A model binding as the interface carries it: a compaction `trigger` is a host function. */
 export type ModelBindingView = Omit<ModelBinding, 'compaction'> & {
     compaction?: Omit<CompactionSpec, 'trigger'>;
 };
 /** `profile.outputs` as the interface carries it: validators are host functions. */
 export type ProfileOutputsView = Omit<ProfileOutputsSpec, 'validation'>;
-/** What the text, image and speech interfaces carry in place of their profile's own fields. */
+/** What the text, image, and speech interfaces carry in place of their profile's own fields. */
 export type ComposerInterfaceFields = {
     models: Record<ModelId, ModelBindingView>;
     outputs?: ProfileOutputsView;
-    /** Client keys' overrides (`CLIENT_LEXICON_KEYS`), resolved on the host; pass to `lexiconText`. */
-    lexicon: LexiconOverrides;
+    /** Client keys' overrides (`CLIENT_LABEL_KEYS`), resolved on the host; pass to `labelText`. */
+    labels: LabelOverrides;
     inputs: ProfileInputsInterface;
     guardrails?: ProfileGuardrailsView;
     observability?: ProfileObservabilityView;
     /** Always true — composer turns cancel via `TurnRequest.signal`. */
     canStop: true;
 };
-export type TextProfileInterface = Omit<TextProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+/** A text profile as a client sees it, without its server-only fields. */
+export type TextProfileInterface = Omit<TextProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields & {
     tools: ProfileToolsView;
     /** From `turnBehaviour.allowSteering` (default true on text). */
     allowSteering: boolean;
 };
-export type ImageProfileInterface = Omit<ImageProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+/** An image profile as a client sees it, without its server-only fields. */
+export type ImageProfileInterface = Omit<ImageProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields & {
     tools: ProfileToolsView;
 };
-export type SpeechProfileInterface = Omit<SpeechProfile, 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields;
-export type LiveProfileInterface = Omit<LiveProfile, 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models'> & {
+/** A speech profile as a client sees it, without its server-only fields. */
+export type SpeechProfileInterface = Omit<SpeechProfile, 'guardrails' | 'observability' | 'labels' | 'models' | 'outputs'> & ComposerInterfaceFields;
+/** A live profile as a client sees it, without its server-only fields. */
+export type LiveProfileInterface = Omit<LiveProfile, 'tools' | 'guardrails' | 'observability' | 'labels' | 'models' | 'live'> & {
+    /** Without `greeting` and `resumed`: the prompts stay on the host. */
+    live: Omit<LiveProfile['live'], 'greeting' | 'resumed'>;
     models: Record<ModelId, ModelBindingView>;
-    /** Client keys' overrides (`CLIENT_LEXICON_KEYS`), resolved on the host; pass to `lexiconText`. */
-    lexicon: LexiconOverrides;
-    tools: LiveProfileToolsSpec;
+    /** Client keys' overrides (`CLIENT_LABEL_KEYS`), resolved on the host; pass to `labelText`. */
+    labels: LabelOverrides;
+    tools: Pick<ProfileToolsView, 'allow' | 'page'>;
     guardrails?: ProfileGuardrailsView;
     observability?: ProfileObservabilityView;
 };
+/** Any profile as a client sees it. */
 export type ProfileInterface = TextProfileInterface | ImageProfileInterface | SpeechProfileInterface | LiveProfileInterface;
 /** Turn/chat composer profiles — excludes live (realtime streams, no turn inputs block). */
 export type ComposerProfileInterface = Exclude<ProfileInterface, LiveProfileInterface>;
-export type TranscriptBlockKind = 'user-text' | 'user-attachment' | 'user-voice' | 'thought' | 'text' | 'tool' | 'structured' | 'media' | 'grounding' | 'citation' | 'evidence' | 'error' | 'turn-done';
+/** The kinds of block a transcript holds. */
+export type TranscriptBlockKind = 'user-text' | 'user-attachment' | 'user-voice' | 'thought' | 'text' | 'tool' | 'structured' | 'media' | 'grounding' | 'citation' | 'evidence' | 'guardrail' | 'error' | 'turn-done';
 export interface TranscriptBlockBase {
     id: string;
     kind: TranscriptBlockKind;
@@ -114,27 +147,38 @@ export interface TextBlock extends TranscriptBlockBase {
 export type ToolCallState = Extract<ToolPhaseEvent, {
     phase: 'running' | 'gate' | 'complete' | 'error' | 'cancel';
 }>;
-/** One tool call: the model's raw call joined with its phase events by `callId` (`toolCallsOf`). */
+/** invariant: An issued operation joins its request and phases; historical calls use callId. */
 export interface ToolCall {
+    operationId?: string;
     name: string;
     callId: string;
-    /** What the model proposed. */
+    /** What the model proposed. `{}` while the model is still writing the call (`draft`). */
     arguments: Record<string, unknown>;
-    /** The call's `ToolCallRequest.thoughtSignature`: history replays the call with it. */
-    thoughtSignature?: string;
+    /**
+     * While the model is still writing the call: its arguments' JSON text so far, from its
+     * `tool_draft` events. Gone once the call arrives whole; `argumentsSoFar` reads it.
+     */
+    draft?: string;
+    /** The call's `ToolCallRequest.reasoning`: history replays the call with it. */
+    reasoning?: ReasoningPart[];
     /** The call's `ToolCallRequest.stepId`: calls sharing it replay as one assistant message. */
     stepId?: string;
     /** The user's edit on approval; `to` is what ran. */
     edited?: ToolCallEdit;
     /** What the call is doing, in the tool's words, from its last `running` phase. */
     activity?: string;
-    /** What the call did, from its `complete` phase. */
+    /** What the call did, from its `complete` phase, or that it failed, from its `error` phase. */
     activityPast?: string;
+    /**
+     * While the call runs: what the tool has written of its output so far, from its `draft` phases
+     * (an agent tool's: its agent's reply). Gone once the call settles; `state` has the output.
+     */
+    outputDraft?: string;
     /** Absent while the call has only been made. */
     state?: ToolCallState;
     /** When it last started running (epoch ms). */
     startedAt?: number;
-    /** When it last settled: complete, failed, cancelled or gated (epoch ms). */
+    /** When it last settled: complete, failed, cancelled, or gated (epoch ms). */
     endedAt?: number;
     artifacts: unknown[];
 }
@@ -144,7 +188,13 @@ export interface ToolBlock extends TranscriptBlockBase {
 }
 export interface StructuredBlock extends TranscriptBlockBase {
     kind: 'structured';
+    /** The reply; while `draft` is set, what of it the model has written so far (`partialJsonObject`). */
     value: unknown;
+    /**
+     * The JSON the model has written so far, from `structured_draft` events. Gone once the
+     * `structured` event arrives, which owns the reply.
+     */
+    draft?: string;
 }
 export interface MediaBlock extends TranscriptBlockBase {
     kind: 'media';
@@ -170,6 +220,15 @@ export interface EvidenceBlock extends TranscriptBlockBase {
     kind: 'evidence';
     evidence: ProviderEvidence;
 }
+/**
+ * A guardrail's decision on the turn: a flag, a redaction, or a block. It names the rule and where
+ * it matched (`hits[].span`), never the matched text. It comes before the text it was read from.
+ * Theorem's own transcript shows nothing for it; a host reads it to show its own notice.
+ */
+export interface GuardrailBlock extends TranscriptBlockBase {
+    kind: 'guardrail';
+    guardrail: GuardrailEvent;
+}
 export interface ErrorBlock extends TranscriptBlockBase {
     kind: 'error';
     message: string;
@@ -188,7 +247,9 @@ export interface TurnDoneBlock extends TranscriptBlockBase {
     /** When the reply last stopped (epoch ms), stamped with `workedMs`. */
     endedAt?: number;
 }
-export type TranscriptBlock = UserTextBlock | UserAttachmentBlock | ThoughtBlock | TextBlock | ToolBlock | StructuredBlock | MediaBlock | GroundingBlock | CitationBlock | EvidenceBlock | ErrorBlock | TurnDoneBlock;
+/** One block of a transcript: a message, an attachment, a thought, a tool call, or a notice. */
+export type TranscriptBlock = UserTextBlock | UserAttachmentBlock | ThoughtBlock | TextBlock | ToolBlock | StructuredBlock | MediaBlock | GroundingBlock | CitationBlock | EvidenceBlock | GuardrailBlock | ErrorBlock | TurnDoneBlock;
+/** A file the user has picked but not yet sent. */
 export interface PendingAttachment {
     name: string;
     mimeType: string;
@@ -196,18 +257,22 @@ export interface PendingAttachment {
     /** Optional base64 payload copied onto the transcript block for UI preview. */
     data?: string;
 }
+/** Whether the pending attachments pass the profile's limits, and the issues if not. */
 export interface AttachmentValidationResult {
     ok: boolean;
     issues: AttachmentValidationIssue[];
 }
+/** What the user has composed and not yet sent. */
 export interface UserTurnDraft {
     text?: string;
     attachments?: PendingAttachment[];
     voice?: PendingAttachment[];
 }
+/** Options for folding turn events into transcript blocks. */
 export interface FoldTurnEventsOptions {
     showThoughts?: boolean;
     idPrefix?: string;
 }
+/** True unless the profile turns thought streaming off. */
 declare function streamThoughtsEnabled(outputs?: ProfileOutputsSpec): boolean;
 export { streamThoughtsEnabled };

package/esm/src/interface/types.js

@@ -1,3 +1,4 @@
+/** True unless the profile turns thought streaming off. */
 function streamThoughtsEnabled(outputs) {
     return outputs?.streaming?.streamThoughts !== false;
 }

package/esm/src/kernel/api-catalog.d.ts

@@ -0,0 +1,85 @@
+/** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
+import type { FieldMeta } from './schema.js';
+import type { TurnInput, TurnRequest } from './types.js';
+/** The catalog of the fields a `runTurn` request takes, keyed `runTurn.<field>`. */
+export declare const REQUEST_FIELDS: Record<`runTurn.${keyof TurnRequest | `input.${keyof TurnInput}`}`, FieldMeta>;
+/** What the catalog records about one export: what it is and what it does. */
+export type ApiExportMeta = {
+    kind: 'function' | 'class';
+    doc: string;
+};
+/** The catalog of the exports a builder calls by name, keyed by that name. */
+export declare const API_EXPORTS: {
+    readonly defineProfile: {
+        readonly kind: "function";
+        readonly doc: "Checks a profile and returns it; a field the profile type cannot take is a config error.";
+    };
+    readonly registerProfile: {
+        readonly kind: "function";
+        readonly doc: "Stores a profile under its id, so that a request can name it.";
+    };
+    readonly registerTool: {
+        readonly kind: "function";
+        readonly doc: "Stores a tool under its name, so that a profile can list it in tools.allow.";
+    };
+    readonly registerStructured: {
+        readonly kind: "function";
+        readonly doc: "Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.";
+    };
+    readonly registerTraceDestination: {
+        readonly kind: "function";
+        readonly doc: "Stores a place to write traces under an id, so that a profile can name it in observability.";
+    };
+    readonly defineProvider: {
+        readonly kind: "function";
+        readonly doc: "Validates a provider definition and supplies its typed model helper.";
+    };
+    readonly registerProvider: {
+        readonly kind: "function";
+        readonly doc: "Registers a provider instance before profiles reference its ID.";
+    };
+    readonly runTurn: {
+        readonly kind: "function";
+        readonly doc: "Runs one turn of a text, image, or speech profile and yields its events.";
+    };
+    readonly runSession: {
+        readonly kind: "function";
+        readonly doc: "Runs a realtime voice or video session of a live profile.";
+    };
+    readonly runDecision: {
+        readonly kind: "function";
+        readonly doc: "Asks a decision profile its questions about your JSON state and returns checked answers.";
+    };
+    readonly invokeTool: {
+        readonly kind: "function";
+        readonly doc: "Runs one registered tool through a profile, with no model.";
+    };
+    readonly runTool: {
+        readonly kind: "function";
+        readonly doc: "Runs one registered tool through a profile, with no model, and returns how the call settled.";
+    };
+    readonly compactHistory: {
+        readonly kind: "function";
+        readonly doc: "Shortens a conversation history with the compaction the profile sets.";
+    };
+    readonly takeSlot: {
+        readonly kind: "function";
+        readonly doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.";
+    };
+    readonly releaseSlot: {
+        readonly kind: "function";
+        readonly doc: "Frees the turn slot that takeSlot gave.";
+    };
+    readonly overrideLabels: {
+        readonly kind: "function";
+        readonly doc: "Replaces status lines for every profile in the process; a profile's own labels wins.";
+    };
+    readonly resetLabels: {
+        readonly kind: "function";
+        readonly doc: "Removes every replacement that overrideLabels made.";
+    };
+    readonly TheoremError: {
+        readonly kind: "class";
+        readonly doc: "The error Theorem throws; its kind tells your host which status and wording to use.";
+    };
+};

package/esm/src/kernel/api-catalog.js

@@ -0,0 +1,229 @@
+/** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
+/** The catalog of the fields a `runTurn` request takes, keyed `runTurn.<field>`. */
+export const REQUEST_FIELDS = {
+    'runTurn.pageExecution': {
+        type: 'PageToolExecution',
+        doc: 'Host-issued browser dispatch with a claimed operation and correlated result.',
+    },
+    'runTurn.execution': {
+        type: 'ToolExecutionCoordinator',
+        doc: 'Host-owned atomic tool claims and outcomes. Never sent to providers.',
+    },
+    'runTurn.providerState': {
+        type: 'ProviderCheckpoint',
+        doc: 'Native provider state saved alongside portable history.',
+    },
+    'runTurn.profile': {
+        type: 'string',
+        doc: 'The id of the registered profile the turn runs.',
+        required: true,
+    },
+    'runTurn.input': { type: 'TurnInput', doc: 'What the user sent for the turn.' },
+    'runTurn.input.text': { type: 'string', doc: "The user's message." },
+    'runTurn.input.role': {
+        type: 'string',
+        doc: 'Picks the instruction of that name from identity.systemByRole.',
+        unset: 'The profile instruction',
+    },
+    'runTurn.input.slots': {
+        type: 'Record<string, string>',
+        doc: 'The choice the turn makes for each slot the profile declares in inputs.slots; a slot or a value the profile does not declare is refused.',
+    },
+    'runTurn.input.context': {
+        type: "Partial<Record<'client' | 'server', unknown>>",
+        doc: "What the page (client) or the host (server) wants the model to know, as any JSON or text; a sender the profile's inputs.context does not list, or a package over its maxChars, is refused.",
+        unset: 'No context',
+    },
+    'runTurn.input.attachments': {
+        type: 'Array<TurnBlob | TurnMediaRef>',
+        doc: "Files sent with the turn, as bytes or as a provider file reference; each must pass the profile's inputs.attachments.",
+    },
+    'runTurn.input.voice': {
+        type: 'TurnBlob[]',
+        doc: "Recorded speech sent with the turn; each must pass the profile's inputs.voice.",
+    },
+    'runTurn.input.history': {
+        type: 'TurnHistoryMessage[]',
+        doc: 'The earlier messages of the conversation, when the host keeps them.',
+        unset: 'The turn starts a new conversation',
+    },
+    'runTurn.input.repair': {
+        type: 'TurnRepairRequest',
+        doc: 'A reply your host rejected and why, so that the model writes it again.',
+    },
+    'runTurn.input.historyTokens': {
+        type: 'number',
+        doc: "Your count of the history's tokens, used by compaction that meters history.",
+        unset: "Theorem's own estimate",
+    },
+    'runTurn.input.inputTokens': {
+        type: 'number',
+        doc: "Your count of the whole prompt's tokens, used by compaction that meters input before the call.",
+    },
+    'runTurn.model': {
+        type: 'string',
+        doc: "The model id the turn picks from the profile's models; refused unless the profile sets allowModelSelect.",
+        unset: "The profile's defaultModel",
+    },
+    'runTurn.effort': {
+        type: 'string',
+        doc: "The effort the turn picks from the model's efforts; refused unless the model sets allowEffortSelect.",
+        unset: "The model's default effort",
+    },
+    'runTurn.builtInArgs': {
+        type: 'Record<BuiltinToolId, JsonObject>',
+        doc: "Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is checked by the schema the provider declares for that tool.",
+        unset: 'Each built-in runs with no args',
+    },
+    'runTurn.system': {
+        type: 'SystemPrompt',
+        doc: "An instruction for this request only, added to the profile's own.",
+    },
+    'runTurn.path': {
+        type: 'string',
+        doc: 'The channel the turn comes from; only tools whose paths name it, or *, are offered.',
+        unset: 'Only tools on every path',
+    },
+    'runTurn.sessionPermissions': {
+        type: 'string[]',
+        doc: 'The tools the user has already approved for this session.',
+    },
+    'runTurn.credentials': {
+        type: 'ToolCredentialSource',
+        doc: 'Where an HTTP or MCP tool gets the credential for its auth slot.',
+    },
+    'runTurn.host': {
+        type: 'unknown',
+        doc: 'Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.',
+    },
+    'runTurn.signal': {
+        type: 'AbortSignal',
+        doc: 'Stops the turn when it aborts, and cancels the provider call where the provider can.',
+    },
+    'runTurn.sessionId': {
+        type: 'string',
+        doc: 'A session key that OpenRouter uses for routing and caching.',
+    },
+    'runTurn.projectId': {
+        type: 'string',
+        doc: 'Your project id, recorded on the trace.',
+    },
+    'runTurn.conversationId': {
+        type: 'string',
+        doc: 'Your conversation id, recorded on the trace.',
+    },
+    'runTurn.metadata': {
+        type: 'Record<string, unknown>',
+        doc: 'Your own values, kept on the trace; Theorem does not read them.',
+    },
+    'runTurn.traceparent': {
+        type: 'string',
+        doc: "The W3C traceparent of your span; the turn's trace joins it as a child.",
+        unset: 'The turn starts a new trace',
+    },
+    'runTurn.links': {
+        type: 'TurnTraceLink[]',
+        doc: 'Earlier traces this turn follows: a resume, a continue, or a retry.',
+    },
+    'runTurn.continueFrom': {
+        type: 'TurnContinueFrom',
+        doc: 'Continues a turn that stopped in a way the profile lets a turn continue.',
+    },
+    'runTurn.continuation': {
+        type: 'number',
+        doc: 'Which continue attempt this is, from 1; checked against the maxContinues of the profile.',
+    },
+    'runTurn.speech': {
+        type: 'TurnSpeech',
+        doc: "This turn's voice, style, and speed; each one given replaces the profile's speech field of that name. Refused on a profile that is not speech.",
+        unset: "The profile's speech settings",
+    },
+    'runTurn.resolveHost': {
+        type: 'ResolveHost',
+        doc: 'Resolves the host name of a remote tool before each request; a name that resolves to a private address is refused.',
+    },
+    'runTurn.onStage': {
+        type: 'StageHandler',
+        doc: 'Your function that sees each stage of a text turn and can answer with what the stage allows.',
+    },
+    'runTurn.onAgentCall': {
+        type: 'AgentCallHook',
+        doc: 'Runs before each agent tool call, to shape the request to the called agent or to refuse the call.',
+        unset: 'The agent runs on what the model sent',
+    },
+};
+/** The catalog of the exports a builder calls by name, keyed by that name. */
+export const API_EXPORTS = {
+    defineProfile: {
+        kind: 'function',
+        doc: 'Checks a profile and returns it; a field the profile type cannot take is a config error.',
+    },
+    registerProfile: {
+        kind: 'function',
+        doc: 'Stores a profile under its id, so that a request can name it.',
+    },
+    registerTool: {
+        kind: 'function',
+        doc: 'Stores a tool under its name, so that a profile can list it in tools.allow.',
+    },
+    registerStructured: {
+        kind: 'function',
+        doc: 'Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.',
+    },
+    registerTraceDestination: {
+        kind: 'function',
+        doc: 'Stores a place to write traces under an id, so that a profile can name it in observability.',
+    },
+    defineProvider: {
+        kind: 'function',
+        doc: 'Validates a provider definition and supplies its typed model helper.',
+    },
+    registerProvider: {
+        kind: 'function',
+        doc: 'Registers a provider instance before profiles reference its ID.',
+    },
+    runTurn: {
+        kind: 'function',
+        doc: 'Runs one turn of a text, image, or speech profile and yields its events.',
+    },
+    runSession: {
+        kind: 'function',
+        doc: 'Runs a realtime voice or video session of a live profile.',
+    },
+    runDecision: {
+        kind: 'function',
+        doc: 'Asks a decision profile its questions about your JSON state and returns checked answers.',
+    },
+    invokeTool: {
+        kind: 'function',
+        doc: 'Runs one registered tool through a profile, with no model.',
+    },
+    runTool: {
+        kind: 'function',
+        doc: 'Runs one registered tool through a profile, with no model, and returns how the call settled.',
+    },
+    compactHistory: {
+        kind: 'function',
+        doc: 'Shortens a conversation history with the compaction the profile sets.',
+    },
+    takeSlot: {
+        kind: 'function',
+        doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.",
+    },
+    releaseSlot: {
+        kind: 'function',
+        doc: 'Frees the turn slot that takeSlot gave.',
+    },
+    overrideLabels: {
+        kind: 'function',
+        doc: "Replaces status lines for every profile in the process; a profile's own labels wins.",
+    },
+    resetLabels: {
+        kind: 'function',
+        doc: 'Removes every replacement that overrideLabels made.',
+    },
+    TheoremError: {
+        kind: 'class',
+        doc: 'The error Theorem throws; its kind tells your host which status and wording to use.',
+    },
+};

package/esm/src/kernel/auth/crypto.d.ts

@@ -1,10 +1,12 @@
 /** RFC 4648 base64url, without padding. */
 export declare function toBase64Url(bytes: Uint8Array): string;
+/** Decodes base64url text into bytes. */
 export declare function fromBase64Url(base64url: string): Uint8Array<ArrayBuffer>;
 /** RFC 7636 §4.1: 43 to 128 characters, drawn without modulo bias. */
 export declare function generateCodeVerifier(length?: number): string;
 /** RFC 7636 §4.2 S256. */
 export declare function computeCodeChallenge(verifier: string): Promise<string>;
+/** What a sealed PKCE state carries between starting and finishing a sign-in. */
 export interface SealedStatePayload {
     codeVerifier: string;
     expectedIssuer: string;
@@ -24,12 +26,14 @@ export interface SealedStatePayload {
 }
 /** Encrypted, not only signed: the state crosses the browser and the server, and the PKCE verifier must stay secret. */
 export declare function sealStatePayload(payload: SealedStatePayload, secret: string): Promise<string>;
+/** Opens a sealed PKCE state; throws when the secret or the seal is wrong. */
 export declare function unsealStatePayload(sealed: string, secret: string): Promise<SealedStatePayload>;
+/** What `sealSecret` takes: the plaintext and the sealing key. */
 export interface SealSecretInput {
     plaintext: string;
     /** The host's sealing key: at least 32 bytes, kept apart from where sealed values are stored. */
     key: string;
-    /** What the sealed value belongs to, such as owner, slot and row. Opening needs the same list. */
+    /** What the sealed value belongs to, such as owner, slot, and row. Opening needs the same list. */
     binding: readonly string[];
     /** Names `key`, so a rotated key still opens what an older one sealed. */
     keyVersion: number;
@@ -40,6 +44,7 @@ export interface SealSecretInput {
  * slot or row does not open.
  */
 export declare function sealSecret(input: SealSecretInput): Promise<string>;
+/** What `openSecret` takes: the sealed value and the keys still in use. */
 export interface OpenSecretInput {
     sealed: string;
     /** Every key still in use, by version. */
@@ -47,5 +52,5 @@ export interface OpenSecretInput {
     /** The binding the value was sealed with. */
     binding: readonly string[];
 }
-/** Opens what `sealSecret` sealed; throws when the envelope, key version or binding does not match. */
+/** Opens what `sealSecret` sealed; throws when the envelope, key version, or binding does not match. */
 export declare function openSecret(input: OpenSecretInput): Promise<string>;