@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,226 @@
+/**
+ * Closed unions and the profile field catalog. No Deno APIs, so host UIs and docs can import it.
+ *
+ * @module
+ */
+/** labels-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+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];
+/** 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. */
+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;
+/** 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.
+ * - `deferred`: the compactor failed and the history still fits `maxTokens`, so it is kept whole.
+ * - `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];
+/** 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`. `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];
+/** 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", "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", "fail"];
+/** One of {@linkcode AUTH_UNAUTHENTICATED_POLICIES}. */
+export type AuthUnauthenticatedPolicy = (typeof AUTH_UNAUTHENTICATED_POLICIES)[number];
+/** 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 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
+ * here, so hosts keep no second table. Rows follow Google Interactions / Live's documented
+ * lists (verified 2026-09-12), the widest provider; TypeScript, `application/xml` and
+ * `application/rtf` are not on Google's list. OpenAI-compat adapters forward the MIME
+ * verbatim and add no rows. Provider alias essences (`image/jpg`, `video/mov`, …) are rows;
+ * `resolveInputParts` canonicalizes `image/jpg` to `image/jpeg` on the wire.
+ */
+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
+ * PDF, the inputs image models document reading. Also the allowlist each of its
+ * `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[];
+/** What the catalog records about one profile field: its type, description, options, and when it applies. */
+export type FieldMeta = {
+    type: string;
+    doc: string;
+    options?: readonly string[];
+    optionDescriptions?: Record<string, string>;
+    optionNote?: string;
+    /** Types the field may be set on, when not every type; `defineProfile` rejects it elsewhere. */
+    profileTypes?: readonly ProfileType[];
+    /** Why the other types can't take it. */
+    profileTypesReason?: string;
+    /** The profile must set the field: always (`true`), or only in the case named. */
+    required?: true | string;
+    /** What leaving the field out does, as a short phrase a blank control can show. */
+    unset?: string;
+};
+/**
+ * Parents whose next key is a host-owned map key (model id, slot name, …).
+ * 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>;
+/** `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';