@theoremjs/agents 0.3.4-next.544.gb5ef325 → 0.3.4-next.550.gf20b9cd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -163,6 +163,20 @@ for await (const event of runTurn(
163
163
 
164
164
  Every event is typed. A `structured` event arrives only after validation and the egress checks pass. The `done` event carries a normalized `stop`: `completed`, `length`, `gate`, `cancelled`, or another kind. Read `stop` to decide whether to continue, resume, or stop.
165
165
 
166
+ When your app adds to each turn (a system prompt, credentials, a stage handler), write it once as a `TurnWiring` and use it at every call site. A web handler takes the same `prepare`, and Theorem Studio runs your turns with it:
167
+
168
+ ```ts
169
+ import { runTurn, type TurnWiring } from "@theoremjs/agents";
170
+
171
+ export const theorem = {
172
+ provider: { vault: { openrouter: apiKey } },
173
+ prepare: (turn) => ({ ...turn, system: "Answer in the customer's language." }),
174
+ } satisfies TurnWiring;
175
+
176
+ const turn = { profile: "support.agent", input: { text: "Why did the export fail?" } };
177
+ for await (const event of runTurn(await theorem.prepare(turn), theorem.provider)) send(event);
178
+ ```
179
+
166
180
  ---
167
181
 
168
182
  ## Profile types
@@ -324,12 +338,14 @@ const gateway = defineProvider({
324
338
  connection: z.strictObject({ baseUrl: z.string() }),
325
339
  key: z.string().trim().min(1),
326
340
  authorize: bearer(),
341
+ check: { protocol: openAi, path: "/models" },
327
342
  serves: (at) => [{ protocol: openAi, baseUrl: at.baseUrl }],
328
343
  });
329
344
  registerProvider(gateway, { connection: { baseUrl: "https://gateway.example/v1" }, keySlot: "gateway" });
330
345
  ```
331
346
 
332
347
  Use `defineProvider` for a server that speaks a protocol that Theorem has. `bearer`, `header`, and `query` put the key on each request.
348
+ `check` names a GET that answers 2xx for a key that works and 400, 401 or 403 for one that does not. `checkKey(provider, { vault })` sends it once and returns a `KeyCheck`: `accepted`, `refused`, `unreachable`, `empty`, or `unchecked` for a provider with no `check`. The Gemini, OpenRouter and TypeSafe providers have one.
333
349
  Use `extendProtocol` for an API that nearly matches a protocol. Use `defineProtocol` for a new API shape.
334
350
  A protocol never holds a key or an address. The kernel signs and sends each request.
335
351
 
@@ -406,7 +422,7 @@ Import from the narrowest entrypoint that has what you need. Each row gives the
406
422
  | `jsr:@theoremjs/agents/host` / `@theoremjs/agents/host` | Optional Deno HTTP helpers (`json`, status mapping, cutout mint flush). |
407
423
  | `jsr:@theoremjs/agents/interface` / `@theoremjs/agents/interface` | Headless interface projection of a profile (transcript, composer, gates) that UI packages such as `@theoremjs/react` render. |
408
424
  | `jsr:@theoremjs/agents/surface` / `@theoremjs/agents/surface` | Surfaces: the agent sees and works in a client's screen through two tools, `look` and `act`. Secrets reach the agent only as cards. |
409
- | `jsr:@theoremjs/agents/cli` / `@theoremjs/agents/cli` | Profile inspection and stress-test CLI (`agents` binary on npm). |
425
+ | `jsr:@theoremjs/agents/cli` / `@theoremjs/agents/cli` | Profile inspection and stress-test CLI (`agents` binary on npm). `agents studio …` runs the studio the project installed. |
410
426
  | `jsr:@theoremjs/agents/schema` / `@theoremjs/agents/schema` | Profile vocabulary and field catalog (closed unions, field metadata) for host UIs and docs; no Deno APIs. |
411
427
  | `jsr:@theoremjs/agents/evals` / `@theoremjs/agents/evals` | Graders that read trace records and write their results as trace records through the same sink. |
412
428
 
@@ -459,7 +475,7 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
459
475
  | Protocol operations | `ProtocolContext`, `ProtocolOperations`, `ProtocolRequest`, `ProtocolSession`, `ProtocolSocket`, `ProtocolEvent`, `ProtocolContentEvent`, `SendInit`, `UpstreamFailure`, `Continuation`, `DecisionCall`, `EmbeddingCall`, `LiveToolResult`, `callProtocol`, `ProtocolCall`, `CallSetup` |
460
476
  | Model bindings | `ModelBinding`, `DecisionModelBinding`, `modelBindingSchema`, `decisionModelBindingSchema`, `commonModelSettingsSchema`, `keySlotSchema`, `checkBinding`, `keySlotsOf`, `RuntimeAbilities` |
461
477
  | Provider data | `JsonValue`, `JsonObject`, `jsonValueSchema`, `jsonObjectSchema`, `PriceTable`, `ModelPrice`, `Rates` |
462
- | Provider vault | `ProviderHostOptions`, `KeyVault`, `KeyCredential`, `CredentialContext`, `CredentialResolver`, `OpenWebSocket`, `plainWebSocket` |
478
+ | Provider vault | `ProviderHostOptions`, `KeyVault`, `KeyCredential`, `CredentialContext`, `CredentialResolver`, `OpenWebSocket`, `plainWebSocket`, `checkKey`, `KeyCheck` |
463
479
  | Provider output | `ProviderCheckpoint`, `ProviderWarning`, `ProviderStateRebuilt`, `ProviderContinuationPolicy`, `providerCheckpointSchema`, `providerWarningSchema`, `providerContinuationSchema` |
464
480
  | Provider limits | `ProviderLimits`, `providerLimitsSchema` |
465
481
  | Re-exported whole | Everything that `@theoremjs/agents/providers` exports. Its contract lists each name. |
package/esm/mod.d.ts CHANGED
@@ -40,8 +40,8 @@ export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './
40
40
  export type { RuntimeAbilities } from './src/kernel/protocols/binding.js';
41
41
  export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './src/kernel/protocols/binding.js';
42
42
  export { providerLimitsSchema } from './src/kernel/protocols/limits.js';
43
- export type { CallSetup, ProtocolCall } from './src/kernel/protocols/runtime.js';
44
- export { callProtocol, plainWebSocket } from './src/kernel/protocols/runtime.js';
43
+ export type { CallSetup, KeyCheck, ProtocolCall } from './src/kernel/protocols/runtime.js';
44
+ export { callProtocol, checkKey, plainWebSocket } from './src/kernel/protocols/runtime.js';
45
45
  export type { AttachmentFacts, AttachmentRules } from './src/kernel/registry/attachments.js';
46
46
  export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, } from './src/kernel/registry/attachments.js';
47
47
  export type { MediaInputChannel } from './src/kernel/registry/catalog.js';
package/esm/mod.js CHANGED
@@ -27,7 +27,7 @@ export { sumTokens } from './src/kernel/engine/usage.js';
27
27
  export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './src/kernel/profile-graph.js';
28
28
  export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './src/kernel/protocols/binding.js';
29
29
  export { providerLimitsSchema } from './src/kernel/protocols/limits.js';
30
- export { callProtocol, plainWebSocket } from './src/kernel/protocols/runtime.js';
30
+ export { callProtocol, checkKey, plainWebSocket } from './src/kernel/protocols/runtime.js';
31
31
  export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, } from './src/kernel/registry/attachments.js';
32
32
  export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './src/kernel/registry/catalog.js';
33
33
  export { embeddingMediaIssues, embeddingRules } from './src/kernel/registry/embedding-rules.js';
@@ -0,0 +1,15 @@
1
+ /**
2
+ * `agents studio`: runs the studio the project installed, with the arguments it was given. The
3
+ * studio is its own package, so this only finds its command; it never installs it.
4
+ *
5
+ * @module
6
+ */
7
+ /** What the builder runs when the project has no studio. */
8
+ export declare const STUDIO_MISSING = "The studio is not installed in this project. Install it: npm install -D @theoremjs/studio";
9
+ /**
10
+ * The studio's command, from the nearest `node_modules/@theoremjs/studio` at or above `from`.
11
+ * Undefined when the project installed none.
12
+ */
13
+ export declare function installedStudio(from: string): string | undefined;
14
+ /** Runs the installed studio's command with `args`, and answers with its exit code. */
15
+ export declare function studioCommand(args: readonly string[], from: string): Promise<number>;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * `agents studio`: runs the studio the project installed, with the arguments it was given. The
3
+ * studio is its own package, so this only finds its command; it never installs it.
4
+ *
5
+ * @module
6
+ */
7
+ import { spawn } from 'node:child_process';
8
+ import { existsSync, readFileSync } from 'node:fs';
9
+ import { dirname, join } from 'node:path';
10
+ /** What the builder runs when the project has no studio. */
11
+ export const STUDIO_MISSING = 'The studio is not installed in this project. Install it: npm install -D @theoremjs/studio';
12
+ /**
13
+ * The studio's command, from the nearest `node_modules/@theoremjs/studio` at or above `from`.
14
+ * Undefined when the project installed none.
15
+ */
16
+ export function installedStudio(from) {
17
+ for (let at = from;; at = dirname(at)) {
18
+ const folder = join(at, 'node_modules', '@theoremjs', 'studio');
19
+ const manifest = join(folder, 'package.json');
20
+ if (existsSync(manifest)) {
21
+ const bin = JSON.parse(readFileSync(manifest, 'utf8'))
22
+ .bin?.['theorem-studio'];
23
+ return bin ? join(folder, bin) : undefined;
24
+ }
25
+ if (dirname(at) === at)
26
+ return undefined;
27
+ }
28
+ }
29
+ /** Runs the installed studio's command with `args`, and answers with its exit code. */
30
+ export function studioCommand(args, from) {
31
+ const command = installedStudio(from);
32
+ if (!command) {
33
+ console.error(STUDIO_MISSING);
34
+ return Promise.resolve(1);
35
+ }
36
+ return new Promise((resolve) => {
37
+ const studio = spawn('node', [command, ...args], { cwd: from, stdio: 'inherit' });
38
+ studio.on('error', (error) => {
39
+ console.error(`agents studio: ${error.message}`);
40
+ resolve(1);
41
+ });
42
+ studio.on('exit', (code, signal) => resolve(code ?? (signal ? 0 : 1)));
43
+ });
44
+ }
@@ -6,7 +6,7 @@
6
6
  * @module
7
7
  */
8
8
  import "../../_dnt.polyfills.js";
9
- import { argv, exit } from 'node:process';
9
+ import { argv, cwd, exit } from 'node:process';
10
10
  import { benchCommand } from './commands/bench.js';
11
11
  import { detectCompileCommand } from './commands/detect-compile.js';
12
12
  import { evalCommand } from './commands/eval.js';
@@ -14,6 +14,7 @@ import { fuzzCanaryCommand } from './commands/fuzz-canary.js';
14
14
  import { fuzzGuardrailsCommand } from './commands/fuzz-guardrails.js';
15
15
  import { listProfilesCommand, showProfileCommand } from './commands/profile.js';
16
16
  import { runCommand } from './commands/run.js';
17
+ import { studioCommand } from './commands/studio.js';
17
18
  import { testProfileCommand } from './commands/test.js';
18
19
  function printHelp() {
19
20
  console.log(`
@@ -54,6 +55,10 @@ COMMANDS:
54
55
  --trace Capture a TraceRecord and print it after the turn
55
56
  --trace-dir <path> Also append trace JSONL under this directory
56
57
 
58
+ studio [args] Run the studio this project installed (@theoremjs/studio), with its arguments
59
+ status [setup] What the open studio loaded, what its keys said, what to look at
60
+ errors [setup] What the open studio told the terminal; --follow keeps printing
61
+
57
62
  test Run stress matrix or custom profile tests
58
63
  --profile, -p <id> Target profile ID registered by your host app
59
64
  --all, -a Test all registered profiles
@@ -225,6 +230,10 @@ async function handleDetectCompile(flags) {
225
230
  }
226
231
  /** Unknown or omitted commands print help; a command that cannot continue exits 1. */
227
232
  export async function main(cliArgs = argv.slice(2)) {
233
+ // why: the studio parses its own arguments, so they go to it as they were given.
234
+ if (cliArgs[0] === 'studio') {
235
+ exit(await studioCommand(cliArgs.slice(1), cwd()));
236
+ }
228
237
  const flags = parseFlags(cliArgs);
229
238
  const command = flags._[0] || (flags.help ? 'help' : 'help');
230
239
  if (command === 'fuzz') {
@@ -1,5 +1,6 @@
1
1
  import { attachmentIssues, resolveMediaLimits } from '../kernel/registry/attachments.js';
2
2
  import { mimeAllowed } from '../kernel/registry/catalog.js';
3
+ import { normalizeSlots } from '../kernel/registry/slots.js';
3
4
  const RECORDER_CANDIDATES = [
4
5
  'audio/webm;codecs=opus',
5
6
  'audio/webm',
@@ -23,7 +24,7 @@ function inputsFromSpec(inputs) {
23
24
  maxBytes: inputs?.maxBytes,
24
25
  maxTurnBytes: inputs?.maxTurnBytes,
25
26
  limitsByMime: inputs?.limitsByMime,
26
- slots: inputs?.slots,
27
+ slots: normalizeSlots(inputs?.slots),
27
28
  context: inputs?.context,
28
29
  };
29
30
  }
@@ -105,7 +105,15 @@ const inputs = z.object({
105
105
  maxBytes: z.number().optional(),
106
106
  maxTurnBytes: z.number().optional(),
107
107
  limitsByMime: z.record(z.string(), z.number()).optional(),
108
- slots: z.record(z.string(), z.array(z.string())).optional(),
108
+ slots: z
109
+ .record(z.string(), z.object({
110
+ label: z.string().optional(),
111
+ choices: z.array(z.object({
112
+ value: z.string(),
113
+ description: z.string().optional(),
114
+ })),
115
+ }))
116
+ .optional(),
109
117
  context: z.object({ from: z.array(z.enum(CONTEXT_SENDERS)), maxChars: z.number() }).optional(),
110
118
  });
111
119
  const resumption = z.object({
@@ -5,7 +5,7 @@ import type { LabelOverrides } from '../guardrails/labels.js';
5
5
  import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
6
6
  import type { ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
7
7
  import type { ReasoningPart } from '../kernel/turn-events.js';
8
- import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
8
+ import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, SlotDecl, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
9
9
  import type { ResolvedObservabilityPolicy } from '../observability/types.js';
10
10
  /** What a URL detector lets through besides the given URLs, with its defaults applied. */
11
11
  export interface UrlAllowView {
@@ -62,7 +62,8 @@ export interface ProfileInputsInterface {
62
62
  maxBytes?: number;
63
63
  maxTurnBytes?: number;
64
64
  limitsByMime?: Record<string, number>;
65
- slots?: Record<string, string[]>;
65
+ /** Normalized slot decls (`label?` + `choices`); legacy string lists are expanded upstream. */
66
+ slots?: Record<string, SlotDecl>;
66
67
  context?: ProfileContextSpec;
67
68
  }
68
69
  /**
@@ -36,8 +36,8 @@ export type { Continuation, DecisionCall, EmbeddingCall, EmbeddingMediaKind, Emb
36
36
  export { carriesTo, defineProtocol, extendProtocol, modelOptions } from './protocols/protocol.js';
37
37
  export type { Authorize, DecisionModelSettings, ModelSettings, Outgoing, Provider, ProviderDefinition, ProviderRegistry, RegisteredProvider, Registration, Serve, Signer, } from './protocols/provider.js';
38
38
  export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from './protocols/provider.js';
39
- export type { CallSetup, OpenWebSocket, ProtocolCall, ProviderHostOptions, } from './protocols/runtime.js';
40
- export { callProtocol, plainWebSocket } from './protocols/runtime.js';
39
+ export type { CallSetup, KeyCheck, OpenWebSocket, ProtocolCall, ProviderHostOptions, } from './protocols/runtime.js';
40
+ export { callProtocol, checkKey, plainWebSocket } from './protocols/runtime.js';
41
41
  export type { MediaInputChannel } from './registry/catalog.js';
42
42
  export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
43
43
  export type { KernelRegistry } from './registry/kernel-registry.js';
@@ -47,6 +47,7 @@ export { createProfileRegistry, defineProfile } from './registry/profiles.js';
47
47
  export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
48
48
  export type { SchemaRegistry } from './registry/schemas.js';
49
49
  export { createSchemaRegistry } from './registry/schemas.js';
50
+ export { normalizeProfileInputsSlots, normalizeSlotDecl, normalizeSlots, slotValues, } from './registry/slots.js';
50
51
  export type { CredentialContext, CredentialResolver, KeyCredential } from './registry/vault.js';
51
52
  export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, StudioAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
52
53
  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';
@@ -22,12 +22,13 @@ export { providerLimitsSchema } from './protocols/limits.js';
22
22
  export { costFromPrices } from './protocols/prices.js';
23
23
  export { carriesTo, defineProtocol, extendProtocol, modelOptions } from './protocols/protocol.js';
24
24
  export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from './protocols/provider.js';
25
- export { callProtocol, plainWebSocket } from './protocols/runtime.js';
25
+ export { callProtocol, checkKey, plainWebSocket } from './protocols/runtime.js';
26
26
  export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
27
27
  export { createKernelRegistry } from './registry/kernel-registry.js';
28
28
  export { createProfileRegistry, defineProfile } from './registry/profiles.js';
29
29
  export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
30
30
  export { createSchemaRegistry } from './registry/schemas.js';
31
+ export { normalizeProfileInputsSlots, normalizeSlotDecl, normalizeSlots, slotValues, } from './registry/slots.js';
31
32
  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';
32
33
  export { createKernelScope, defaultKernelScope } from './scope.js';
33
34
  export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
@@ -63,6 +63,15 @@ export interface ProviderDefinition<C = unknown, K = unknown> {
63
63
  /** Only where the API reports no cost. */
64
64
  prices?: PriceTable;
65
65
  serves(connection: C): Serve<K>[];
66
+ /**
67
+ * How to ask the provider whether it takes a key: a GET to `path` on where it serves `protocol`,
68
+ * signed as a call is. It must answer 2xx for a key that works and 400, 401 or 403 for one
69
+ * that does not. `checkKey` sends it.
70
+ */
71
+ check?: {
72
+ protocol: Protocol;
73
+ path: string;
74
+ };
66
75
  }
67
76
  /** A provider as defined; register it to use it. */
68
77
  export type Provider<C = unknown, K = unknown> = Readonly<ProviderDefinition<C, K>>;
@@ -105,4 +114,9 @@ export interface ProviderRegistry {
105
114
  /** Every protocol the registered providers serve, with the protocols they extend. */
106
115
  protocols(): Protocol[];
107
116
  }
117
+ /** Where a provider serves a protocol; a config error when it does not. */
118
+ export declare function served(provider: {
119
+ id: string;
120
+ serves: readonly Serve[];
121
+ }, protocol: string): Serve;
108
122
  export declare function createProviderRegistry(): ProviderRegistry;
@@ -52,7 +52,8 @@ export function defineProvider(definition) {
52
52
  }));
53
53
  return Object.freeze({ ...definition });
54
54
  }
55
- function served(provider, protocol) {
55
+ /** Where a provider serves a protocol; a config error when it does not. */
56
+ export function served(provider, protocol) {
56
57
  const serve = provider.serves.find((entry) => entry.protocol.id === protocol);
57
58
  if (!serve)
58
59
  throw new TheoremError('config', labelText('protocol.not_served', { provider: provider.id, protocol }));
@@ -5,7 +5,7 @@ import type { DecisionResult, KeySlot } from '../types.js';
5
5
  import { type DecisionModelBinding, type ModelBinding } from './binding.js';
6
6
  import type { ProviderLimits } from './limits.js';
7
7
  import type { DecisionCall, EmbeddingCall, EmbeddingResult, ModelProfileType, ProtocolOperations } from './protocol.js';
8
- import type { RegisteredProvider } from './provider.js';
8
+ import { type RegisteredProvider } from './provider.js';
9
9
  /** Opens a WebSocket with the headers and subprotocols a sign-in put on it. */
10
10
  export type OpenWebSocket = (url: string, init: {
11
11
  headers: Headers;
@@ -44,6 +44,34 @@ export interface CallSetup {
44
44
  /** Told the slot and key each attempt signs with, so the caller can redact it and key its state. */
45
45
  onKey?(slot: KeySlot | undefined, key: unknown): void;
46
46
  }
47
+ /** What a provider said about a key when asked with its `check`. */
48
+ export interface KeyCheck {
49
+ provider: string;
50
+ slot?: KeySlot;
51
+ /**
52
+ * `accepted`: the provider answered 2xx. `refused`: it answered 400, 401 or 403, or the key is
53
+ * not one the provider takes. `unreachable`: no answer in time, or another status. `empty`: the
54
+ * slot holds no key. `unchecked`: the provider declares no `check`.
55
+ */
56
+ state: 'accepted' | 'refused' | 'unreachable' | 'empty' | 'unchecked';
57
+ status?: number;
58
+ /** The provider's own words on a refusal, with the key taken out. */
59
+ said?: string;
60
+ }
61
+ /**
62
+ * Asks a registered provider whether it takes a key, with the GET its definition's `check`
63
+ * names: `key` when given, else `slot` (by default its key slot) in `vault`. One request, never retried; the key is
64
+ * not kept or logged.
65
+ */
66
+ export declare function checkKey(provider: RegisteredProvider, options?: {
67
+ key?: unknown;
68
+ vault?: KeyVault;
69
+ /** The slot to read, when a model names its own. Default: the provider's `keySlot`. */
70
+ slot?: string;
71
+ fetch?: typeof fetch;
72
+ signal?: AbortSignal;
73
+ timeoutMs?: number;
74
+ }): Promise<KeyCheck>;
47
75
  /**
48
76
  * One binding's call, as the kernel runs it: the protocol's operations with the kernel's retries,
49
77
  * ids, origins, and prices around them.
@@ -8,6 +8,7 @@ import { jsonValueSchema } from '../json.js';
8
8
  import { bytesToBase64 } from '../util/base64.js';
9
9
  import { bindingServe, keySlotsOf, } from './binding.js';
10
10
  import { costFromPrices } from './prices.js';
11
+ import { served, } from './provider.js';
11
12
  /**
12
13
  * The runtime's own WebSocket. It takes no headers, so a sign-in that needs them is refused; a host
13
14
  * that can send them passes `openWebSocket`.
@@ -40,40 +41,128 @@ const signers = new WeakMap();
40
41
  function vaultEntry(vault, slot) {
41
42
  return vault && Object.hasOwn(vault, slot) ? vault[slot] : undefined;
42
43
  }
43
- async function signerFor(setup, serve, slot) {
44
- const { definition } = setup.provider;
45
- const authorize = serve.authorize ?? definition.authorize;
46
- if (!definition.key || !authorize)
47
- return undefined;
48
- const entry = slot ? vaultEntry(setup.vault, slot) : undefined;
49
- const raw = typeof entry === 'function'
44
+ /** A slot's entry as a call reads it: the vault's own entry, or what its resolver returns. */
45
+ async function rawKeyIn(provider, vault, slot, at) {
46
+ const entry = slot ? vaultEntry(vault, slot) : undefined;
47
+ return typeof entry === 'function'
50
48
  ? await entry({
51
- providerId: setup.provider.id,
52
- apiId: setup.binding.apiId,
49
+ providerId: provider.id,
50
+ ...(at.apiId === undefined ? {} : { apiId: at.apiId }),
53
51
  keySlot: slot,
54
- ...(setup.signal ? { signal: setup.signal } : {}),
52
+ ...(at.signal ? { signal: at.signal } : {}),
55
53
  })
56
54
  : entry;
55
+ }
56
+ /** A key checked against the provider's key schema; an `auth` error names the slot when it is not one. */
57
+ function parsedKey(provider, slot, raw) {
58
+ const key = provider.definition.key;
59
+ if (!key)
60
+ return undefined;
57
61
  const value = typeof raw === 'string' ? raw.trim() || undefined : raw;
58
- const parsed = definition.key.safeParse(value);
62
+ const parsed = key.safeParse(value);
59
63
  // invariant: a named slot promises a key, even where the provider's key is optional.
60
64
  if (!parsed.success || (slot && value === undefined))
61
65
  throw new TheoremError('auth', value === undefined
62
66
  ? labelText('provider.credential_missing', { slot: slot ?? '' })
63
- : labelText('protocol.key_invalid', { slot: slot ?? '', provider: setup.provider.id }));
64
- if (parsed.data === undefined)
67
+ : labelText('protocol.key_invalid', { slot: slot ?? '', provider: provider.id }));
68
+ return parsed.data;
69
+ }
70
+ async function signerFor(setup, serve, slot) {
71
+ const authorize = serve.authorize ?? setup.provider.definition.authorize;
72
+ if (!authorize)
65
73
  return undefined;
66
- setup.onKey?.(slot, parsed.data);
74
+ const raw = setup.provider.definition.key
75
+ ? await rawKeyIn(setup.provider, setup.vault, slot, {
76
+ apiId: setup.binding.apiId,
77
+ ...(setup.signal ? { signal: setup.signal } : {}),
78
+ })
79
+ : undefined;
80
+ const key = parsedKey(setup.provider, slot, raw);
81
+ if (key === undefined)
82
+ return undefined;
83
+ setup.onKey?.(slot, key);
67
84
  const cacheKey = `${serve.protocol.id}\u0000${slot ?? ''}`;
68
85
  const cache = signers.get(setup.provider) ?? new Map();
69
86
  signers.set(setup.provider, cache);
70
87
  const held = cache.get(cacheKey);
71
- if (held && JSON.stringify(held.key) === JSON.stringify(parsed.data))
88
+ if (held && JSON.stringify(held.key) === JSON.stringify(key))
72
89
  return held.signer;
73
- const signer = authorize(parsed.data);
74
- cache.set(cacheKey, { key: parsed.data, signer });
90
+ const signer = authorize(key);
91
+ cache.set(cacheKey, { key, signer });
75
92
  return signer;
76
93
  }
94
+ /** Characters of a provider's refusal a key check keeps. */
95
+ const SAID_CAP = 300;
96
+ const CHECK_TIMEOUT_MS = 8000;
97
+ /** The provider's message from a refusal's body, with the key taken out. */
98
+ async function refusalSaid(response, key) {
99
+ const text = await response.text().catch(() => '');
100
+ const body = failureBody(text);
101
+ const message = body && typeof body === 'object' && !Array.isArray(body)
102
+ ? (body.error?.message ?? body.message ?? body.detail)
103
+ : body;
104
+ const said = typeof message === 'string' ? message : message == null ? '' : JSON.stringify(message);
105
+ const secret = typeof key === 'string' ? key : '';
106
+ return (secret ? said.replaceAll(secret, '…') : said).slice(0, SAID_CAP) || undefined;
107
+ }
108
+ /**
109
+ * Asks a registered provider whether it takes a key, with the GET its definition's `check`
110
+ * names: `key` when given, else `slot` (by default its key slot) in `vault`. One request, never retried; the key is
111
+ * not kept or logged.
112
+ */
113
+ export async function checkKey(provider, options = {}) {
114
+ const slot = options.slot ?? provider.keySlot;
115
+ const base = { provider: provider.id, ...(slot ? { slot } : {}) };
116
+ const { check, authorize } = provider.definition;
117
+ const signal = AbortSignal.any([
118
+ AbortSignal.timeout(options.timeoutMs ?? CHECK_TIMEOUT_MS),
119
+ ...(options.signal ? [options.signal] : []),
120
+ ]);
121
+ const raw = options.key !== undefined
122
+ ? options.key
123
+ : provider.definition.key
124
+ ? await rawKeyIn(provider, options.vault, slot, { signal })
125
+ : undefined;
126
+ if (raw === undefined || (typeof raw === 'string' && !raw.trim()))
127
+ return { ...base, state: 'empty' };
128
+ if (!check)
129
+ return { ...base, state: 'unchecked' };
130
+ const serve = served(provider, check.protocol.id);
131
+ let key;
132
+ try {
133
+ key = parsedKey(provider, slot, raw);
134
+ }
135
+ catch (error) {
136
+ if (error instanceof TheoremError && error.kind === 'auth')
137
+ return { ...base, state: 'refused' };
138
+ throw error;
139
+ }
140
+ const outgoing = {
141
+ transport: 'http',
142
+ url: urlFor({ ...serve, url: undefined }, check.path, '', false),
143
+ headers: new Headers(serve.headers),
144
+ protocols: [],
145
+ };
146
+ await (serve.authorize ?? authorize)?.(key).sign(outgoing);
147
+ let response;
148
+ try {
149
+ response = await (options.fetch ?? fetch)(outgoing.url, { headers: outgoing.headers, signal });
150
+ }
151
+ catch {
152
+ return { ...base, state: 'unreachable' };
153
+ }
154
+ if (response.ok) {
155
+ await response.body?.cancel();
156
+ return { ...base, state: 'accepted', status: response.status };
157
+ }
158
+ const said = await refusalSaid(response, key);
159
+ return {
160
+ ...base,
161
+ state: [400, 401, 403].includes(response.status) ? 'refused' : 'unreachable',
162
+ status: response.status,
163
+ ...(said ? { said } : {}),
164
+ };
165
+ }
77
166
  function urlFor(serve, path, apiId, stream) {
78
167
  if (serve.url)
79
168
  return new URL(serve.url({ path, apiId, stream }));
@@ -7,6 +7,7 @@ import { CONTEXT_SENDERS } from '../schema.js';
7
7
  import { CONTINUE_INSTRUCTION_TYPES } from '../stop.js';
8
8
  import { isTurnMediaRef } from './attachments.js';
9
9
  import { mediaKindForMime, mimeEssence, profileInputs } from './catalog.js';
10
+ import { slotValues } from './slots.js';
10
11
  function activePrimaryOutputModes(profile, structuredId) {
11
12
  const modes = [];
12
13
  if (structuredId) {
@@ -149,10 +150,11 @@ function assertTurnSlots(profile, req) {
149
150
  return;
150
151
  const declared = profileInputs(profile)?.slots ?? {};
151
152
  for (const [key, value] of Object.entries(slots)) {
152
- const choices = Object.hasOwn(declared, key) ? declared[key] : undefined;
153
- if (!choices) {
153
+ const decl = Object.hasOwn(declared, key) ? declared[key] : undefined;
154
+ if (!decl) {
154
155
  throw new TheoremError('request', `Profile ${profile.id} has no slot '${key}'`);
155
156
  }
157
+ const choices = slotValues(decl);
156
158
  if (!choices.includes(value)) {
157
159
  throw new TheoremError('request', `Profile ${profile.id}: slot '${key}' takes ${choices.join(', ')}, not '${value}'`);
158
160
  }
@@ -15,6 +15,7 @@ import { assertSystemPrompt } from '../system-parts.js';
15
15
  import { profileToolAllow, profileToolsSpec } from '../tools/resolve.js';
16
16
  import { isTurnMediaRef } from './attachments.js';
17
17
  import { mediaKindForMime, mimeAllowed, profileInputs } from './catalog.js';
18
+ import { normalizeProfileInputsSlots, slotValues } from './slots.js';
18
19
  import { soleModelId } from './sole-model.js';
19
20
  function assertModelRoute(_profileId, _modelId, binding, _type) {
20
21
  if (!binding.provider?.trim() || !binding.apiId?.trim())
@@ -400,7 +401,7 @@ function defineProfile(input) {
400
401
  identity,
401
402
  ...modelFields,
402
403
  tools: input.tools,
403
- inputs: input.inputs,
404
+ inputs: normalizeProfileInputsSlots(input.inputs),
404
405
  outputs: input.outputs,
405
406
  turnBehaviour: input.turnBehaviour,
406
407
  guardrails,
@@ -416,7 +417,7 @@ function defineProfile(input) {
416
417
  ...modelFields,
417
418
  image: input.image,
418
419
  tools: input.tools,
419
- inputs: input.inputs,
420
+ inputs: normalizeProfileInputsSlots(input.inputs),
420
421
  outputs: input.outputs,
421
422
  turnBehaviour: input.turnBehaviour,
422
423
  guardrails,
@@ -447,7 +448,7 @@ function defineProfile(input) {
447
448
  identity,
448
449
  ...modelFields,
449
450
  live: input.live,
450
- inputs: input.inputs,
451
+ inputs: input.inputs ? normalizeProfileInputsSlots(input.inputs) : input.inputs,
451
452
  tools: { allow: input.tools.allow, ...optionalParallel(input.tools.parallel) },
452
453
  turnBehaviour: input.turnBehaviour,
453
454
  guardrails,
@@ -491,10 +492,11 @@ function assertStructuredSlot(profile) {
491
492
  const structured = profile.outputs?.structured;
492
493
  if (!structured || typeof structured === 'string')
493
494
  return;
494
- const choices = profileInputs(profile)?.slots?.[structured.by];
495
- if (!choices) {
495
+ const decl = profileInputs(profile)?.slots?.[structured.by];
496
+ if (!decl) {
496
497
  throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.by '${structured.by}' is not a slot in inputs.slots`);
497
498
  }
499
+ const choices = slotValues(decl);
498
500
  const unknown = Object.keys(structured.map).filter((value) => !choices.includes(value));
499
501
  if (unknown.length) {
500
502
  throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.map maps ${unknown.join(', ')}, not a choice of slot '${structured.by}'`);
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Slot declaration helpers: normalize authoring forms and read choice values for
3
+ * validation and fillSlots. Descriptions and labels are UI-only.
4
+ */
5
+ import type { ProfileInputsSpec, SlotDecl, SlotDeclInput } from '../types.js';
6
+ /** The allowed values of one slot declaration (legacy list or labeled form). */
7
+ export declare function slotValues(decl: SlotDeclInput): string[];
8
+ /** Canonical slot declaration: always `{ choices }`, optional `label`. */
9
+ export declare function normalizeSlotDecl(decl: SlotDeclInput): SlotDecl;
10
+ /** Canonical `inputs.slots`, or undefined when none. */
11
+ export declare function normalizeSlots(slots: Record<string, SlotDeclInput> | undefined): Record<string, SlotDecl> | undefined;
12
+ /** Profile inputs with every slot normalized (labels/descriptions preserved). */
13
+ export declare function normalizeProfileInputsSlots<T extends ProfileInputsSpec | undefined>(inputs: T): T;
@@ -0,0 +1,31 @@
1
+ /** The allowed values of one slot declaration (legacy list or labeled form). */
2
+ export function slotValues(decl) {
3
+ return Array.isArray(decl) ? [...decl] : decl.choices.map((choice) => choice.value);
4
+ }
5
+ /** Canonical slot declaration: always `{ choices }`, optional `label`. */
6
+ export function normalizeSlotDecl(decl) {
7
+ if (Array.isArray(decl)) {
8
+ return { choices: decl.map((value) => ({ value })) };
9
+ }
10
+ return {
11
+ ...(decl.label !== undefined && decl.label !== '' ? { label: decl.label } : {}),
12
+ choices: decl.choices.map((choice) => ({
13
+ value: choice.value,
14
+ ...(choice.description !== undefined && choice.description !== ''
15
+ ? { description: choice.description }
16
+ : {}),
17
+ })),
18
+ };
19
+ }
20
+ /** Canonical `inputs.slots`, or undefined when none. */
21
+ export function normalizeSlots(slots) {
22
+ if (!slots)
23
+ return undefined;
24
+ return Object.fromEntries(Object.entries(slots).map(([name, decl]) => [name, normalizeSlotDecl(decl)]));
25
+ }
26
+ /** Profile inputs with every slot normalized (labels/descriptions preserved). */
27
+ export function normalizeProfileInputsSlots(inputs) {
28
+ if (!inputs?.slots)
29
+ return inputs;
30
+ return { ...inputs, slots: normalizeSlots(inputs.slots) };
31
+ }
@@ -4,7 +4,8 @@ import type { KeySlot } from '../types.js';
4
4
  export type KeyCredential = string | JsonObject;
5
5
  export interface CredentialContext {
6
6
  providerId: string;
7
- apiId: string;
7
+ /** The model the call is for. Absent for a key check, which calls no model. */
8
+ apiId?: string;
8
9
  keySlot: KeySlot;
9
10
  signal?: AbortSignal;
10
11
  }
@@ -585,8 +585,12 @@ export const PROFILE_FIELDS = withScopeAndPresence({
585
585
  'inputs.maxTurnBytes': field('number', 'The most bytes one turn or embedding request may send inline across all its files and clips.'),
586
586
  'inputs.limitsByMime': field('Record<string, number>', 'Size limits by file type that replace maxBytes for those types.'),
587
587
  'inputs.limitsByMime.*': field('number', 'The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.'),
588
- 'inputs.slots': field('Record<string, string[]>', 'Named choices a turn or a call can make, such as language, each with its allowed values. {name} in a prompt becomes the chosen value.'),
589
- 'inputs.slots.*': field('string[]', 'The values a turn may choose for this slot; any other is refused.'),
588
+ 'inputs.slots': field('Record<string, string[] | SlotDecl>', 'Named choices a turn or a call can make. A bare string list is the allowed values; an object may add a UI label and per-choice descriptions. {name} in a prompt becomes the chosen value string.'),
589
+ 'inputs.slots.*': field('string[] | SlotDecl', 'Either the allowed value strings, or { label?, choices: { value, description? }[] }. Descriptions are UI-only; value is what the turn sends and what {name} fills.'),
590
+ 'inputs.slots.*.label': field('string', 'Visitor-facing group title for this slot in the composer (for example Source Bias). Omit to show the slot name.'),
591
+ 'inputs.slots.*.choices': field('SlotChoice[]', 'The allowed values for this slot, each with an optional UI description.'),
592
+ 'inputs.slots.*.choices.*.value': field('string', 'The string the turn sends for this choice and that {name} substitutes into prompts.'),
593
+ 'inputs.slots.*.choices.*.description': field('string', 'Visitor-facing blurb for this choice in the composer. Never substituted into prompts.'),
590
594
  'inputs.context': field('{ from: ContextSender[]; maxChars: number }', 'Lets the page or the host send the agent one package of things to know, read at the context boundary.'),
591
595
  'inputs.context.from': field("Array<'client' | 'server'>", 'Who may send context; context from anyone else is refused.', CONTEXT_SENDERS, {
592
596
  client: 'The browser. A visitor can change it, so it is untrusted.',
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
+ import { slotValues } from '../registry/slots.js';
3
4
  import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
4
5
  import { findLast } from '../util/find-last.js';
5
6
  import { profileToolAllow } from './resolve.js';
@@ -32,7 +33,10 @@ const speechInput = z.strictObject({
32
33
  });
33
34
  /** One choice per declared slot; a slot or a value the profile does not declare is refused. */
34
35
  function slotsInput(slots) {
35
- return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, choices]) => [slot, z.enum(choices).optional()])));
36
+ return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, decl]) => {
37
+ const choices = slotValues(decl);
38
+ return [slot, z.enum(choices).optional()];
39
+ })));
36
40
  }
37
41
  /** The fields an agent tool's input can carry to the called agent; a host field takes none of these names. */
38
42
  const AGENT_INPUT_FIELDS = new Set([
@@ -46,6 +46,7 @@ export interface ProfileImageSpec {
46
46
  includeText?: boolean;
47
47
  }
48
48
  import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
49
+ import type { ProviderHostOptions } from './protocols/runtime.js';
49
50
  export type { DecisionModelBinding, ModelBinding };
50
51
  /**
51
52
  * OpenRouter prompt-cache policy (`models.*.options.cache`).
@@ -313,6 +314,24 @@ export interface ProfileModelFields {
313
314
  /** Tool-loop ceiling. Omit = `DEFAULT_MAX_STEPS`; `1` = one-shot; `> 1` = hard cap. */
314
315
  maxSteps?: number;
315
316
  }
317
+ /**
318
+ * One allowed value for an `inputs.slots` entry. `value` is what the turn sends and what
319
+ * `{name}` fills; optional `description` is visitor-facing UI copy only.
320
+ */
321
+ export interface SlotChoice {
322
+ value: string;
323
+ description?: string;
324
+ }
325
+ /**
326
+ * One named slot: optional group `label` for the UI, and its choices. A bare `string[]` is
327
+ * still accepted on define and normalized to `{ choices: [{ value }] }`.
328
+ */
329
+ export interface SlotDecl {
330
+ label?: string;
331
+ choices: SlotChoice[];
332
+ }
333
+ /** Authoring form for one slot: legacy value list, or a labeled declaration. */
334
+ export type SlotDeclInput = string[] | SlotDecl;
316
335
  /** What a profile accepts as input. */
317
336
  export interface ProfileInputsSpec {
318
337
  text?: boolean;
@@ -326,7 +345,7 @@ export interface ProfileInputsSpec {
326
345
  maxBytes?: number;
327
346
  maxTurnBytes?: number;
328
347
  limitsByMime?: Record<string, number>;
329
- slots?: Record<string, string[]>;
348
+ slots?: Record<string, SlotDeclInput>;
330
349
  context?: ProfileContextSpec;
331
350
  }
332
351
  /** What a live profile declares beside its ingress channels. */
@@ -795,6 +814,24 @@ export interface TurnRequest {
795
814
  */
796
815
  onAgentCall?: AgentCallHook;
797
816
  }
817
+ /**
818
+ * How an application runs its turns: the one value its own call sites, its web handler and the
819
+ * studio all use, so they cannot run a turn differently. An app that calls `runTurn` itself
820
+ * writes `runTurn(await wiring.prepare(turn), wiring.provider)`.
821
+ */
822
+ export interface TurnWiring {
823
+ /** Registers the application's profiles and tools. Called once, before the first turn. */
824
+ register?: () => void | Promise<void>;
825
+ /** The keys, network and limits each model call runs on. */
826
+ provider?: ProviderHostOptions;
827
+ /**
828
+ * The turn the application runs, from the one it is given: the profile, the input with the
829
+ * conversation's history, and the application's context as `host`. Set what the application
830
+ * sets per turn, such as `system`, `credentials`, `onStage`, `onAgentCall`, `path` and
831
+ * `metadata`. Text, image and speech turns run through it.
832
+ */
833
+ prepare?: (turn: NormalizedTurnRequest) => TurnRequest | Promise<TurnRequest>;
834
+ }
798
835
  /** A profile projected for a client, with its secrets and server-only fields removed. */
799
836
  export interface ProjectedProfile extends ProfileModelFields {
800
837
  id: string;
@@ -25,6 +25,8 @@ export const geminiProvider = defineProvider({
25
25
  key: z.string().trim().min(1),
26
26
  authorize: header('x-goog-api-key'),
27
27
  prices: geminiPrices,
28
+ // probed 2026-10-27: a working key answers 200; a wrong one 400 (`API_KEY_INVALID`), none 403.
29
+ check: { protocol: geminiInteractions, path: '/models?pageSize=1' },
28
30
  serves(at) {
29
31
  const host = new URL(at.host ?? 'https://generativelanguage.googleapis.com');
30
32
  const origin = host.origin;
@@ -32,6 +32,8 @@ export const openRouterProvider = defineProvider({
32
32
  connection: connection.default({}),
33
33
  key: z.string().trim().min(1),
34
34
  authorize: bearer(),
35
+ // probed 2026-10-27: a working key answers 200; a wrong one or none 401.
36
+ check: { protocol: openRouterOpenAi, path: '/key' },
35
37
  serves(at) {
36
38
  const baseUrl = at.baseUrl ?? 'https://openrouter.ai/api/v1';
37
39
  const headers = {};
@@ -20,5 +20,7 @@ export const typesafeProvider = defineProvider({
20
20
  checked: '2026-10-19',
21
21
  models: { 'jev-*': { input: 0.042, output: 0 } },
22
22
  },
23
+ // probed 2026-10-27: a working key answers 200; a wrong one 401, none 403.
24
+ check: { protocol: systemOne, path: '/models' },
23
25
  serves: (at) => [{ protocol: systemOne, baseUrl: at.baseUrl ?? 'https://api.typesafe.ai/v1' }],
24
26
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.544.gb5ef325",
3
+ "version": "0.3.4-next.550.gf20b9cd",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",