@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -3,59 +3,71 @@
  *
  * @module
  */
-/** lexicon-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+/** labels-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
 import "../../_dnt.polyfills.js";
-import { EGRESS_ON_BLOCK, type EgressOnBlock } from '../guardrails/types.js';
-export { EGRESS_ON_BLOCK, type EgressOnBlock };
-export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live", "decision", "host"];
+import { BLOCKED_REPLY_ON_BLOCK, type BlockedReplyOnBlock } from '../guardrails/types.js';
+export { BLOCKED_REPLY_ON_BLOCK, type BlockedReplyOnBlock };
+/** The kinds of profile: each fixes which fields and models a profile may use. */
+export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live", "decision", "embedding", "host"];
+/** One of {@linkcode PROFILE_TYPES}. */
 export type ProfileType = (typeof PROFILE_TYPES)[number];
+/** Reasoning effort levels, lowest to highest; a model accepts only the levels its catalog row lists. */
 export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** One of {@linkcode THINKING_LEVELS}. */
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
-export declare const PROTOCOLS: readonly ["geminiInteractions", "geminiLive", "openAi", "decision"];
-export type Protocol = (typeof PROTOCOLS)[number];
-export declare const PROVIDERS: readonly ["google", "openrouter", "local", "typesafe"];
-export type Provider = (typeof PROVIDERS)[number];
-/** Turn pairs are handled by `createProvider`; decision pairs by `runDecision`. */
-export declare const PROTOCOL_PROVIDERS: {
-    readonly geminiInteractions: readonly ["google"];
-    readonly geminiLive: readonly ["google"];
-    readonly openAi: readonly ["openrouter", "local"];
-    readonly decision: readonly ["typesafe", "openrouter"];
-};
-export declare const PROFILE_TYPE_PROTOCOLS: {
-    readonly text: readonly ["geminiInteractions", "openAi"];
-    readonly image: readonly ["geminiInteractions", "openAi"];
-    readonly speech: readonly ["geminiInteractions", "openAi"];
-    readonly live: readonly ["geminiLive"];
-    readonly decision: readonly ["decision"];
-    readonly host: readonly [];
-};
-export type ProfileTypeProtocol<T extends ProfileType> = (typeof PROFILE_TYPE_PROTOCOLS)[T][number];
-export declare function protocolsForProfileType(type: ProfileType): readonly Protocol[];
-export declare function isValidProfileProtocol(type: ProfileType, protocol: Protocol): boolean;
+/** The longest a profile's `id` may be, in characters: room for a dotted or generated one. */
+export declare const PROFILE_ID_MAX_CHARS = 64;
+/** The longest a profile's `identity.handle` may be, in characters: it is a name people read. */
+export declare const PROFILE_HANDLE_MAX_CHARS = 32;
 /** A vault slot's name, chosen by the host. The profile names slots; the host fills them with keys. */
 export type KeySlot = string;
-/** Letters, digits, `-` and `_`, up to 32 characters, starting with a letter or digit. */
+/** Letters, digits, `-`, and `_`, up to 32 characters, starting with a letter or digit. */
 export declare const KEY_SLOT_NAME: RegExp;
+/** True when the value is a legal key slot name. */
 export declare function isKeySlotName(value: unknown): value is KeySlot;
-export type KeyVault = Readonly<Record<KeySlot, string | undefined>>;
+/** The host-filled keys by slot name; a slot with no key is `undefined`. */
+export type { KeyVault } from './registry/vault.js';
+/** The kinds of media a model can take as input. */
 export declare const MEDIA_INPUT_KIND_VALUES: readonly ["image", "audio", "video", "document"];
+/** One of {@linkcode MEDIA_INPUT_KIND_VALUES}. */
 export type MediaInputKind = (typeof MEDIA_INPUT_KIND_VALUES)[number];
+/** Whether thought summaries are asked for (`auto`) or not (`none`). */
 export declare const SUMMARY_MODES: readonly ["auto", "none"];
+/** One of {@linkcode SUMMARY_MODES}. */
 export type SummaryMode = (typeof SUMMARY_MODES)[number];
+/** Whether the provider call streams (`sse`) or is one buffered call. */
 export declare const STREAM_MODES: readonly ["sse", "buffered"];
+/** One of {@linkcode STREAM_MODES}. */
 export type StreamMode = (typeof STREAM_MODES)[number];
+/** Audio encodings a speech profile can return. */
 export declare const SPEECH_AUDIO_FORMATS: readonly ["pcm", "mp3"];
+/** One of {@linkcode SPEECH_AUDIO_FORMATS}. */
 export type SpeechAudioFormat = (typeof SPEECH_AUDIO_FORMATS)[number];
+/** Who can send a turn its context: the browser, or the host's own code. */
+/** How long a caller is away, in milliseconds, before `live.resumed.prompt` is sent, when the profile sets no `afterMs`. */
+export declare const DEFAULT_RESUMED_AFTER_MS = 3000;
+export declare const CONTEXT_SENDERS: readonly ["client", "server"];
+/** One of {@linkcode CONTEXT_SENDERS}. */
+export type ContextSender = (typeof CONTEXT_SENDERS)[number];
+/** What the user starting to speak does to a live model that is mid-reply. */
 export declare const LIVE_ACTIVITY_HANDLINGS: readonly ["START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION"];
+/** One of {@linkcode LIVE_ACTIVITY_HANDLINGS}. */
 export type LiveActivityHandling = (typeof LIVE_ACTIVITY_HANDLINGS)[number];
+/** How readily live voice detection decides the user has started speaking. */
 export declare const LIVE_START_SENSITIVITIES: readonly ["START_SENSITIVITY_LOW", "START_SENSITIVITY_HIGH"];
+/** One of {@linkcode LIVE_START_SENSITIVITIES}. */
 export type LiveStartSensitivity = (typeof LIVE_START_SENSITIVITIES)[number];
+/** How readily live voice detection decides the user has stopped speaking. */
 export declare const LIVE_END_SENSITIVITIES: readonly ["END_SENSITIVITY_LOW", "END_SENSITIVITY_HIGH"];
+/** One of {@linkcode LIVE_END_SENSITIVITIES}. */
 export type LiveEndSensitivity = (typeof LIVE_END_SENSITIVITIES)[number];
+/** What compaction counts against its token limit: the stored history or the next request's input. */
 export declare const COMPACTION_METERS: readonly ["history", "input"];
+/** One of {@linkcode COMPACTION_METERS}. */
 export type CompactionMeter = (typeof COMPACTION_METERS)[number];
+/** Whether compaction runs before or after a turn. */
 export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
+/** One of {@linkcode COMPACTION_TIMINGS}. */
 export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
 /**
  * - `compacted`: a summary replaced the compacted messages.
@@ -63,54 +75,95 @@ export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
  * - `dropped`: the compactor failed over `maxTokens`, so the compacted messages were dropped.
  */
 export declare const COMPACTION_OUTCOMES: readonly ["compacted", "deferred", "dropped"];
+/** One of {@linkcode COMPACTION_OUTCOMES}. */
 export type CompactionOutcome = (typeof COMPACTION_OUTCOMES)[number];
+/** Which part of the prompt is cached: the whole request (`automatic`) or the system instruction only (`system`). */
 export declare const CACHE_MODES: readonly ["automatic", "system"];
+/** One of {@linkcode CACHE_MODES}. */
 export type CacheMode = (typeof CACHE_MODES)[number];
+/** How long a provider keeps a cached prompt. */
 export declare const CACHE_TTLS: readonly ["5m", "1h"];
+/** One of {@linkcode CACHE_TTLS}. */
 export type CacheTtl = (typeof CACHE_TTLS)[number];
-export declare const TURN_STOP_KINDS: readonly ["completed", "length", "tool", "gate", "filtered", "provider_error", "cancelled", "stream_incomplete", "interrupted", "generation_complete"];
+/** Why a turn stopped, as `done.stop.kind` reports it. */
+export declare const TURN_STOP_KINDS: readonly ["completed", "length", "tool", "gate", "filtered", "provider_error", "cancelled", "stream_incomplete", "step_limit", "interrupted", "generation_complete"];
+/** One of {@linkcode TURN_STOP_KINDS}. */
 export type TurnStopKind = (typeof TURN_STOP_KINDS)[number];
+/** What a text turn's last allowed model call may do, as `turnBehaviour.atStepLimit` sets it. */
+export declare const STEP_LIMIT_MODES: readonly ["stop", "answer"];
+/** What happens to a list item its check refuses, as `outputs.validation.items.*.onFail` sets it. */
+export declare const ITEM_FAIL_ACTIONS: readonly ["drop", "fix"];
+/** One of {@linkcode STEP_LIMIT_MODES}. */
+export type StepLimitMode = (typeof STEP_LIMIT_MODES)[number];
 /** Every other stop resumes by another host path, or not at all. */
 export declare const CONTINUE_STOP_KINDS: readonly ["length", "stream_incomplete", "provider_error"];
+/** One of {@linkcode CONTINUE_STOP_KINDS}. */
 export type ContinueStopKind = (typeof CONTINUE_STOP_KINDS)[number];
+/** The points in a turn where a stage handler runs. */
 export declare const TURN_STAGES: readonly ["pre_turn", "pre_tool", "post_tool", "before_end", "post_turn"];
+/** One of {@linkcode TURN_STAGES}. */
 export type TurnStage = (typeof TURN_STAGES)[number];
+/** True when the value names a turn stage. */
 export declare function isTurnStage(value: unknown): value is TurnStage;
 /** Stages where an inject can land; the inject gate still applies. */
 export declare const TURN_INJECT_STAGES: readonly ["pre_turn", "post_tool", "before_end"];
+/** One of {@linkcode TURN_INJECT_STAGES}. */
 export type TurnInjectStage = (typeof TURN_INJECT_STAGES)[number];
+/** True when the value names a stage an inject can land in. */
 export declare function isTurnInjectStage(value: unknown): value is TurnInjectStage;
-/** `pre_tool` gates; not `awaiting_user_input`. */
-export declare const TOOL_GATE_KINDS: readonly ["confirmation", "permission", "auth"];
+/** `pre_tool` gates; not `awaiting_user_input`. `page` holds a call for the page that answers it. */
+export declare const TOOL_GATE_KINDS: readonly ["confirmation", "permission", "auth", "page"];
+/** One of {@linkcode TOOL_GATE_KINDS}. */
 export type ToolGateKind = (typeof TOOL_GATE_KINDS)[number];
 /** Why a refused gate settles: the user said no, walked away, or let it run out. */
 export declare const TOOL_RESUME_CAUSES: readonly ["declined", "abandoned", "expired"];
+/** One of {@linkcode TOOL_RESUME_CAUSES}. */
 export type ToolResumeCause = (typeof TOOL_RESUME_CAUSES)[number];
+/** True when the value names a tool gate kind. */
 export declare function isToolGateKind(value: unknown): value is ToolGateKind;
+/** The questions a turn can pause to ask the user. */
 export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "text"];
+/** One of {@linkcode AWAITING_USER_INPUT_KINDS}. */
 export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
-export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "abort_invalid", "unknown_field", "result_invalid"];
+/** Why a stage handler's result was partly or wholly ignored. */
+export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "label_failed_invalid", "abort_invalid", "wait_for_invalid", "unknown_field", "result_invalid"];
+/** One of {@linkcode STAGE_APPLY_WARNING_CODES}. */
 export type StageApplyWarningCode = (typeof STAGE_APPLY_WARNING_CODES)[number];
+/** The `status` of a tool output that asks the user a question. */
 export declare const AWAITING_USER_INPUT_STATUS: "awaiting_user_input";
 /** Enforced by the kernel at resolve time. */
-export declare const TOOL_LOAD_TIERS: readonly ["T0", "T1", "T2"];
+export declare const TOOL_LOAD_TIERS: readonly ["T0", "T2"];
+/** One of {@linkcode TOOL_LOAD_TIERS}. */
 export type ToolLoadTier = (typeof TOOL_LOAD_TIERS)[number];
+/** The HTTP methods an `http` tool may use. */
 export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+/** One of {@linkcode HTTP_METHODS}. */
 export type HttpMethod = (typeof HTTP_METHODS)[number];
 /** When remote tool auth is missing or expired. */
-export declare const AUTH_UNAUTHENTICATED_POLICIES: readonly ["gate", "report_to_model"];
+export declare const AUTH_UNAUTHENTICATED_POLICIES: readonly ["gate", "report_to_model", "fail"];
+/** One of {@linkcode AUTH_UNAUTHENTICATED_POLICIES}. */
 export type AuthUnauthenticatedPolicy = (typeof AUTH_UNAUTHENTICATED_POLICIES)[number];
-export declare const TOOL_TYPES: readonly ["builtin", "function", "http", "mcp"];
+/** The kinds of tool a profile can list. */
+export declare const TOOL_TYPES: readonly ["builtin", "function", "http", "mcp", "agent"];
+/** How much a tool can change: nothing, data, or irreversibly. */
 export declare const TOOL_ACCESS: readonly ["read-only", "read-write", "destructive"];
+/** One of {@linkcode TOOL_ACCESS}. */
 export type ToolAccess = (typeof TOOL_ACCESS)[number];
+/** When the user must approve a tool call: never, once per session, or every call. */
 export declare const TOOL_PERMISSION: readonly ["auto", "session_consent", "always_confirm"];
+/** One of {@linkcode TOOL_PERMISSION}. */
 export type ToolPermission = (typeof TOOL_PERMISSION)[number];
+/** The credential shapes a remote tool can authenticate with. */
 export declare const TOOL_AUTH_TYPES: readonly ["bearer", "api_key", "oauth2"];
+/** One of {@linkcode TOOL_AUTH_TYPES}. */
 export type ToolAuthType = (typeof TOOL_AUTH_TYPES)[number];
 /** Adds UI-only `none`, which omits auth at compile time. */
-export declare const PLAYGROUND_AUTH_TYPES: readonly ["none", "bearer", "api_key", "oauth2"];
-export type PlaygroundAuthType = (typeof PLAYGROUND_AUTH_TYPES)[number];
+export declare const STUDIO_AUTH_TYPES: readonly ["none", "bearer", "api_key", "oauth2"];
+/** One of {@linkcode STUDIO_AUTH_TYPES}. */
+export type StudioAuthType = (typeof STUDIO_AUTH_TYPES)[number];
+/** One of {@linkcode TOOL_TYPES}. */
 export type ToolType = (typeof TOOL_TYPES)[number];
+/** A tool type the host defines, which is every type but `builtin`. */
 export type CustomToolType = Exclude<ToolType, 'builtin'>;
 /**
  * The package's complete media-input vocabulary: `assertMediaMime` refuses any MIME not
@@ -123,6 +176,7 @@ export type CustomToolType = Exclude<ToolType, 'builtin'>;
 export declare const MEDIA_INPUT_KINDS: Record<string, MediaInputKind>;
 /** Type-prefix wildcards accepted by `mimeAllowed`. */
 export declare const MEDIA_WILDCARDS: readonly ["image/*", "audio/*", "video/*"];
+/** The MIME types a text profile's `accept` entries may list. */
 export declare const ATTACHMENT_ACCEPT_MIMES: readonly string[];
 /**
  * The attachment `accept` values an image profile may list: images, video and
@@ -130,15 +184,9 @@ export declare const ATTACHMENT_ACCEPT_MIMES: readonly string[];
  * `accept` entries must fall within.
  */
 export declare const IMAGE_ATTACHMENT_ACCEPT_MIMES: readonly string[];
+/** The MIME types a voice profile's `accept` entries may list. */
 export declare const VOICE_ACCEPT_MIMES: readonly string[];
-export declare function providersFor(protocol: Protocol): readonly Provider[];
-export declare function protocolsFor(provider: Provider): readonly Protocol[];
-/** True when `createProvider` will accept this pair. */
-export declare function isValidPair(protocol: Protocol, provider: Provider): boolean;
-/** When protocol changes, snap provider to a valid partner. */
-export declare function coerceProvider(protocol: Protocol, provider: Provider): Provider;
-/** When provider changes, snap protocol to a valid partner. */
-export declare function coerceProtocol(protocol: Protocol, provider: Provider): Protocol;
+/** What the catalog records about one profile field: its type, description, options, and when it applies. */
 export type FieldMeta = {
     type: string;
     doc: string;
@@ -159,14 +207,20 @@ export type FieldMeta = {
  * The annotator substitutes `*` so `models.flash.apiId` → `models.*.apiId`.
  */
 export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
+/** Turns a key path into its catalog path, replacing host-chosen map keys with `*`. */
 export declare function catalogPathFor(keys: readonly string[]): string;
 /**
  * Adding a profile field? Add it here; scope it in `PROFILE_FIELD_SCOPE` if only some types
  * take it, and record it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters.
  */
 export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
+/**
+ * The catalog of the fields `registerTool` takes, keyed `registerTool.<field>`. The `studio.` and
+ * `local.` rows are the studio's own; a builder never sets them.
+ */
 export declare const EXTRA_FIELDS: Record<string, FieldMeta>;
-/** `lexicon.<key>` resolves to `lexicon.*` with that key's own note. */
+/** `labels.<key>` resolves to `labels.*` with that key's own note. */
 export declare function fieldMeta(path: string): FieldMeta | undefined;
+export { API_EXPORTS, type ApiExportMeta, REQUEST_FIELDS } from './api-catalog.js';
 export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
 export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType } from './profile-graph.js';