@theoremjs/agents 0.3.4-next.548.gbb156b2 → 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 +18 -2
- package/esm/mod.d.ts +2 -2
- package/esm/mod.js +1 -1
- package/esm/src/cli/commands/studio.d.ts +15 -0
- package/esm/src/cli/commands/studio.js +44 -0
- package/esm/src/cli/index.js +10 -1
- package/esm/src/kernel/mod.d.ts +2 -2
- package/esm/src/kernel/mod.js +1 -1
- package/esm/src/kernel/protocols/provider.d.ts +14 -0
- package/esm/src/kernel/protocols/provider.js +2 -1
- package/esm/src/kernel/protocols/runtime.d.ts +29 -1
- package/esm/src/kernel/protocols/runtime.js +106 -17
- package/esm/src/kernel/registry/vault.d.ts +2 -1
- package/esm/src/kernel/types.d.ts +19 -0
- package/esm/src/providers/gemini/provider.js +2 -0
- package/esm/src/providers/openrouter/provider.js +2 -0
- package/esm/src/providers/typesafe/provider.js +2 -0
- package/package.json +1 -1
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
|
+
}
|
package/esm/src/cli/index.js
CHANGED
|
@@ -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') {
|
package/esm/src/kernel/mod.d.ts
CHANGED
|
@@ -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';
|
package/esm/src/kernel/mod.js
CHANGED
|
@@ -22,7 +22,7 @@ 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';
|
|
@@ -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
|
-
|
|
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
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
const
|
|
46
|
-
|
|
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:
|
|
52
|
-
apiId:
|
|
49
|
+
providerId: provider.id,
|
|
50
|
+
...(at.apiId === undefined ? {} : { apiId: at.apiId }),
|
|
53
51
|
keySlot: slot,
|
|
54
|
-
...(
|
|
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 =
|
|
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:
|
|
64
|
-
|
|
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.
|
|
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(
|
|
88
|
+
if (held && JSON.stringify(held.key) === JSON.stringify(key))
|
|
72
89
|
return held.signer;
|
|
73
|
-
const signer = authorize(
|
|
74
|
-
cache.set(cacheKey, { key
|
|
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 }));
|
|
@@ -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
|
-
|
|
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
|
}
|
|
@@ -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`).
|
|
@@ -813,6 +814,24 @@ export interface TurnRequest {
|
|
|
813
814
|
*/
|
|
814
815
|
onAgentCall?: AgentCallHook;
|
|
815
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
|
+
}
|
|
816
835
|
/** A profile projected for a client, with its secrets and server-only fields removed. */
|
|
817
836
|
export interface ProjectedProfile extends ProfileModelFields {
|
|
818
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.
|
|
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",
|