@theoremjs/agents 0.3.4-next.649.gf83cea1 → 0.3.4-next.673.ga492632

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.
Files changed (43) hide show
  1. package/esm/src/cli/commands/bench.js +2 -0
  2. package/esm/src/cli/commands/run.d.ts +4 -1
  3. package/esm/src/cli/commands/run.js +13 -5
  4. package/esm/src/cli/commands/test.d.ts +3 -1
  5. package/esm/src/cli/commands/test.js +5 -2
  6. package/esm/src/cli/index.d.ts +1 -0
  7. package/esm/src/cli/index.js +36 -3
  8. package/esm/src/cli/setup.d.ts +20 -0
  9. package/esm/src/cli/setup.js +37 -0
  10. package/esm/src/interface/mod.d.ts +1 -1
  11. package/esm/src/interface/mod.js +1 -1
  12. package/esm/src/interface/models.d.ts +3 -1
  13. package/esm/src/interface/models.js +4 -2
  14. package/esm/src/kernel/engine/decision.js +7 -4
  15. package/esm/src/kernel/engine/embedding.js +4 -3
  16. package/esm/src/kernel/engine/runner/steps.js +1 -0
  17. package/esm/src/kernel/engine/session/session-trace.js +1 -0
  18. package/esm/src/kernel/engine/turn-trace.d.ts +2 -0
  19. package/esm/src/kernel/engine/turn-trace.js +5 -8
  20. package/esm/src/kernel/profile-presence.js +1 -1
  21. package/esm/src/kernel/protocols/binding.d.ts +2 -0
  22. package/esm/src/kernel/protocols/binding.js +4 -0
  23. package/esm/src/kernel/protocols/protocol.d.ts +7 -0
  24. package/esm/src/kernel/protocols/protocol.js +19 -2
  25. package/esm/src/kernel/registry/resolve.js +4 -0
  26. package/esm/src/kernel/schema.js +1 -1
  27. package/esm/src/kernel/tools/activity-label.d.ts +3 -2
  28. package/esm/src/kernel/tools/activity-label.js +46 -19
  29. package/esm/src/kernel/types.d.ts +2 -0
  30. package/esm/src/observability/spans.d.ts +1 -1
  31. package/esm/src/observability/spans.js +1 -1
  32. package/esm/src/observability/trace-catalog.js +5 -2
  33. package/esm/src/providers/gemini/embeddings-protocol.js +1 -0
  34. package/esm/src/providers/gemini/interactions-protocol.js +5 -0
  35. package/esm/src/providers/gemini/live-protocol.js +1 -0
  36. package/esm/src/providers/local/embeddings-protocol.js +1 -0
  37. package/esm/src/providers/open-ai/protocol.js +1 -0
  38. package/esm/src/providers/openrouter/decisions-protocol.js +1 -0
  39. package/esm/src/providers/openrouter/embeddings-protocol.js +1 -0
  40. package/esm/src/providers/openrouter/images-protocol.js +1 -0
  41. package/esm/src/providers/system-one/protocol.js +1 -0
  42. package/esm/src/surface/runtime.js +3 -10
  43. package/package.json +1 -1
@@ -73,6 +73,7 @@ function registerBenchProvider(chunks) {
73
73
  name: 'Bench',
74
74
  description: 'Streams the bench chunks without a network.',
75
75
  endpoints: { text: '/bench' },
76
+ operationNames: { text: 'chat' },
76
77
  options: z.strictObject({}),
77
78
  create: () => ({
78
79
  async *complete() {
@@ -385,6 +386,7 @@ async function microTraceRecord(chunks, iterations) {
385
386
  usage: startCallUsage('', { history: [], input: req.input }),
386
387
  binding: undefined,
387
388
  transport: 'turn',
389
+ operation: 'chat',
388
390
  step: 0,
389
391
  attempt: 0,
390
392
  });
@@ -1,4 +1,5 @@
1
1
  import type { ProviderHostOptions } from '../../kernel/protocols/runtime.js';
2
+ import type { TurnWiring } from '../../kernel/types.js';
2
3
  export interface RunOptions {
3
4
  profile: string;
4
5
  prompt?: string;
@@ -6,8 +7,10 @@ export interface RunOptions {
6
7
  search?: boolean;
7
8
  map?: boolean;
8
9
  provider?: ProviderHostOptions;
10
+ prepare?: TurnWiring['prepare'];
9
11
  verbose?: boolean;
10
12
  trace?: boolean;
11
13
  traceDir?: string;
12
14
  }
13
- export declare function runCommand(options: RunOptions): Promise<void>;
15
+ /** Runs one turn and prints it; false when the turn could not run or failed. */
16
+ export declare function runCommand(options: RunOptions): Promise<boolean>;
@@ -1,12 +1,14 @@
1
1
  import { getProfile, runTurn } from '../../kernel/default-scope.js';
2
2
  import { requireModelProfile } from '../../kernel/registry/resolve.js';
3
3
  import { createCliTraceCapture, printRunEvent, printTraceRecord } from '../event-log.js';
4
+ import { preparedRequest } from '../setup.js';
5
+ /** Runs one turn and prints it; false when the turn could not run or failed. */
4
6
  export async function runCommand(options) {
5
7
  requireModelProfile(getProfile(options.profile), 'agents run');
6
8
  const provider = options.provider;
7
9
  if (!provider) {
8
- console.error('\n\x1b[31mExecution Failed\x1b[0m: Theorem CLI does not create providers or read keys. Run turns from a host app with an explicit ProviderHostOptions.\n');
9
- return;
10
+ console.error('\n\x1b[31mExecution Failed\x1b[0m: Theorem CLI does not create providers or read keys. Pass --setup <file> to run on the provider your setup file wires, or run turns from a host app with an explicit ProviderHostOptions.\n');
11
+ return false;
10
12
  }
11
13
  const prompt = options.prompt || 'Hello! Please introduce your capabilities.';
12
14
  if (options.search || options.map) {
@@ -15,11 +17,11 @@ export async function runCommand(options) {
15
17
  const builtins = new Set(profile.models[selected]?.builtInTools ?? []);
16
18
  if (options.search && !builtins.has('googleSearch')) {
17
19
  console.error('\n\x1b[31mExecution Failed\x1b[0m: --search requires googleSearch on models.*.builtInTools for the selected model.\n');
18
- return;
20
+ return false;
19
21
  }
20
22
  if (options.map && !builtins.has('googleMaps')) {
21
23
  console.error('\n\x1b[31mExecution Failed\x1b[0m: --map requires googleMaps on models.*.builtInTools for the selected model.\n');
22
- return;
24
+ return false;
23
25
  }
24
26
  }
25
27
  const req = {
@@ -31,15 +33,21 @@ export async function runCommand(options) {
31
33
  console.log(`Prompt: "${prompt}"\n`);
32
34
  const traceCapture = options.trace ? createCliTraceCapture(options.traceDir) : undefined;
33
35
  try {
34
- for await (const event of runTurn(req, provider, traceCapture?.sink)) {
36
+ const turn = await preparedRequest(options.prepare, req);
37
+ let failed = false;
38
+ for await (const event of runTurn(turn, provider, traceCapture?.sink)) {
39
+ if (event.type === 'error')
40
+ failed = true;
35
41
  printRunEvent(event, { verbose: options.verbose });
36
42
  }
37
43
  console.log('\n');
38
44
  if (options.trace) {
39
45
  printTraceRecord(traceCapture?.records.at(-1), options.verbose === true);
40
46
  }
47
+ return !failed;
41
48
  }
42
49
  catch (err) {
43
50
  console.error(`\n\x1b[31mExecution Failed\x1b[0m: ${err instanceof Error ? err.message : String(err)}\n`);
51
+ return false;
44
52
  }
45
53
  }
@@ -1,5 +1,5 @@
1
1
  import type { ProviderHostOptions } from '../../kernel/protocols/runtime.js';
2
- import type { TurnRequest, TurnTokens } from '../../kernel/types.js';
2
+ import type { TurnRequest, TurnTokens, TurnWiring } from '../../kernel/types.js';
3
3
  import { type MatrixOptions } from '../matrix/synthesizer.js';
4
4
  export interface TestRunResult {
5
5
  passed: boolean;
@@ -10,6 +10,7 @@ export interface TestRunResult {
10
10
  error?: string;
11
11
  }
12
12
  interface CliTestOptions {
13
+ prepare?: TurnWiring['prepare'];
13
14
  verbose?: boolean;
14
15
  trace?: boolean;
15
16
  traceDir?: string;
@@ -19,6 +20,7 @@ export declare function testProfileCommand(profileId?: string, options?: MatrixO
19
20
  all?: boolean;
20
21
  matrix?: boolean;
21
22
  provider?: ProviderHostOptions;
23
+ prepare?: TurnWiring['prepare'];
22
24
  verbose?: boolean;
23
25
  trace?: boolean;
24
26
  traceDir?: string;
@@ -4,6 +4,7 @@ import { isModelProfile, requireModelProfile } from '../../kernel/registry/resol
4
4
  import { profileToolAllow } from '../../kernel/tools/resolve.js';
5
5
  import { createCliTraceCapture, printTestEvent, printTraceRecord } from '../event-log.js';
6
6
  import { buildCustomTurnRequest, synthesizeMatrixCombos, } from '../matrix/synthesizer.js';
7
+ import { preparedRequest } from '../setup.js';
7
8
  function printTestHeader(req, testName) {
8
9
  const profile = requireModelProfile(getProfile(req.profile), 'agents test');
9
10
  const modelId = req.model && profile.models[req.model] ? req.model : (Object.keys(profile.models)[0] ?? '');
@@ -46,10 +47,11 @@ export async function executeSingleTest(req, testName, provider, cliOptions = {}
46
47
  };
47
48
  try {
48
49
  if (!provider) {
49
- throw new Error('Theorem CLI does not create providers or read keys. Pass an explicit ProviderHostOptions from the host app.');
50
+ throw new Error('Theorem CLI does not create providers or read keys. Pass --setup <file> to run on the provider your setup file wires, or an explicit ProviderHostOptions from the host app.');
50
51
  }
51
52
  const traceCapture = cliOptions.trace ? createCliTraceCapture(cliOptions.traceDir) : undefined;
52
- for await (const event of runTurn(req, provider, traceCapture?.sink)) {
53
+ const turn = await preparedRequest(cliOptions.prepare, req);
54
+ for await (const event of runTurn(turn, provider, traceCapture?.sink)) {
53
55
  processTestEvent(event, acc, cliOptions);
54
56
  }
55
57
  if (cliOptions.trace) {
@@ -126,6 +128,7 @@ export async function testProfileCommand(profileId, options = {}) {
126
128
  return false;
127
129
  }
128
130
  const cliOptions = {
131
+ prepare: options.prepare,
129
132
  verbose: options.verbose,
130
133
  trace: options.trace,
131
134
  traceDir: options.traceDir,
@@ -6,5 +6,6 @@
6
6
  * @module
7
7
  */
8
8
  import "../../_dnt.polyfills.js";
9
+ export { type LoadedSetup, loadSetup } from './setup.js';
9
10
  /** Unknown or omitted commands print help; a command that cannot continue exits 1. */
10
11
  export declare function main(cliArgs?: string[]): Promise<void>;
@@ -16,6 +16,8 @@ import { listProfilesCommand, showProfileCommand } from './commands/profile.js';
16
16
  import { runCommand } from './commands/run.js';
17
17
  import { studioCommand } from './commands/studio.js';
18
18
  import { testProfileCommand } from './commands/test.js';
19
+ import { loadSetup } from './setup.js';
20
+ export { loadSetup } from './setup.js';
19
21
  function printHelp() {
20
22
  console.log(`
21
23
  Theorem CLI - Profile Testing and Profile Inspection
@@ -46,6 +48,7 @@ COMMANDS:
46
48
  fuzz-canary Adversarial canary egress fuzzer (stream + Live gates)
47
49
 
48
50
  run Execute a turn with real-time streaming output
51
+ --setup <file> Register, run on and prepare turns with the wiring your setup file names
49
52
  --profile, -p <id> Target profile ID
50
53
  --prompt <text> User prompt string
51
54
  --mode <fast|smart> Reasoning mode
@@ -60,6 +63,7 @@ COMMANDS:
60
63
  errors [setup] What the open studio told the terminal; --follow keeps printing
61
64
 
62
65
  test Run stress matrix or custom profile tests
66
+ --setup <file> Register, run on and prepare turns with the wiring your setup file names
63
67
  --profile, -p <id> Target profile ID registered by your host app
64
68
  --all, -a Test all registered profiles
65
69
  --lite Minimal fast-path connectivity ping
@@ -72,6 +76,7 @@ COMMANDS:
72
76
  --trace-dir <path> Also append trace JSONL under this directory
73
77
 
74
78
  profile Inspect registered profile blueprints
79
+ --setup <file> Register the profiles your setup file's wiring registers first
75
80
  list List all registered profiles
76
81
  show <id> Show detailed JSON profile specification
77
82
 
@@ -136,10 +141,31 @@ function extractProfileId(flags) {
136
141
  return flags.p;
137
142
  return undefined;
138
143
  }
144
+ /** The `--setup` file's wiring, registered; nothing without the flag; exits 1 when it fails. */
145
+ async function setupWiring(flags) {
146
+ if (flags.setup === undefined)
147
+ return {};
148
+ if (typeof flags.setup !== 'string') {
149
+ console.error('Error: --setup needs a path (e.g. `--setup studio.setup.ts`)');
150
+ exit(1);
151
+ }
152
+ try {
153
+ const { theorem } = await loadSetup(flags.setup);
154
+ await theorem.register?.();
155
+ return theorem;
156
+ }
157
+ catch (err) {
158
+ console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
159
+ exit(1);
160
+ }
161
+ }
139
162
  async function handleTest(flags) {
140
163
  const profile = extractProfileId(flags);
141
164
  const diagnostics = cliDiagnostics(flags);
165
+ const wiring = await setupWiring(flags);
142
166
  const success = await testProfileCommand(profile, {
167
+ provider: wiring.provider,
168
+ prepare: wiring.prepare,
143
169
  all: Boolean(flags.all || flags.a),
144
170
  lite: Boolean(flags.lite),
145
171
  matrix: Boolean(flags.matrix),
@@ -162,9 +188,12 @@ async function handleRun(flags) {
162
188
  }
163
189
  const prompt = typeof flags.prompt === 'string' ? flags.prompt : flags._.slice(1).join(' ');
164
190
  const diagnostics = cliDiagnostics(flags);
165
- await runCommand({
191
+ const wiring = await setupWiring(flags);
192
+ const ok = await runCommand({
166
193
  profile,
167
194
  prompt,
195
+ provider: wiring.provider,
196
+ prepare: wiring.prepare,
168
197
  mode: typeof flags.mode === 'string' ? flags.mode : undefined,
169
198
  search: Boolean(flags.search),
170
199
  map: Boolean(flags.map),
@@ -172,6 +201,9 @@ async function handleRun(flags) {
172
201
  trace: diagnostics.trace,
173
202
  traceDir: diagnostics.traceDir,
174
203
  });
204
+ if (!ok) {
205
+ exit(1);
206
+ }
175
207
  }
176
208
  function numberFlag(flags, key) {
177
209
  return typeof flags[key] === 'string' ? Number(flags[key]) : undefined;
@@ -196,7 +228,8 @@ async function handleEval(flags) {
196
228
  exit(1);
197
229
  }
198
230
  }
199
- function handleProfile(flags) {
231
+ async function handleProfile(flags) {
232
+ await setupWiring(flags);
200
233
  const sub = flags._[1] || 'list';
201
234
  if (sub === 'list') {
202
235
  listProfilesCommand();
@@ -268,7 +301,7 @@ export async function main(cliArgs = argv.slice(2)) {
268
301
  await handleEval(flags);
269
302
  }
270
303
  else if (command === 'profile') {
271
- handleProfile(flags);
304
+ await handleProfile(flags);
272
305
  }
273
306
  else {
274
307
  printHelp();
@@ -0,0 +1,20 @@
1
+ /**
2
+ * A project's setup file, as the studio and `agents test` / `agents run` read it: the setup
3
+ * module, and the `theorem` wiring its entry exports.
4
+ *
5
+ * @module
6
+ */
7
+ import type { TurnRequest, TurnWiring } from '../kernel/types.js';
8
+ /** A loaded setup: the module as it is, and its entry's wiring. */
9
+ export interface LoadedSetup {
10
+ setup: Record<string, unknown>;
11
+ theorem: TurnWiring;
12
+ }
13
+ /**
14
+ * Imports the setup at `setupPath`, then its `entry`, relative to the setup, and returns the
15
+ * `theorem` that entry exports. A setup written before the entry existed fails, and says what
16
+ * moved where. Registers nothing: call `theorem.register` for that.
17
+ */
18
+ export declare function loadSetup(setupPath: string): Promise<LoadedSetup>;
19
+ /** `req` through the application's `prepare`, on the profile the command named. */
20
+ export declare function preparedRequest(prepare: TurnWiring['prepare'], req: TurnRequest): Promise<TurnRequest>;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * A project's setup file, as the studio and `agents test` / `agents run` read it: the setup
3
+ * module, and the `theorem` wiring its entry exports.
4
+ *
5
+ * @module
6
+ */
7
+ import { dirname, resolve } from 'node:path';
8
+ import { pathToFileURL } from 'node:url';
9
+ /**
10
+ * Imports the setup at `setupPath`, then its `entry`, relative to the setup, and returns the
11
+ * `theorem` that entry exports. A setup written before the entry existed fails, and says what
12
+ * moved where. Registers nothing: call `theorem.register` for that.
13
+ */
14
+ export async function loadSetup(setupPath) {
15
+ const setup = await import(pathToFileURL(resolve(setupPath)).href);
16
+ const moved = ['default', 'provider'].filter((name) => setup[name] !== undefined);
17
+ if (moved.length > 0) {
18
+ throw new Error(`${setupPath} exports ${moved.map((name) => `\`${name}\``).join(' and ')}. The app's wiring moved to its entry: export \`theorem\` (a TurnWiring) from the entry, with registration in \`theorem.register\` and keys in \`theorem.provider\`, and export \`entry\` from the setup.`);
19
+ }
20
+ if (typeof setup.entry !== 'string' || !setup.entry) {
21
+ throw new Error(`${setupPath} names no entry. Export \`entry\`: the path of your app's entry point, relative to the setup file, which exports \`theorem\` (a TurnWiring).`);
22
+ }
23
+ const entryPath = resolve(dirname(resolve(setupPath)), setup.entry);
24
+ const entry = await import(pathToFileURL(entryPath).href);
25
+ const theorem = entry.theorem;
26
+ if (!theorem || typeof theorem !== 'object') {
27
+ throw new Error(`${setup.entry} exports no \`theorem\`. Export the TurnWiring your app runs its turns with: \`export const theorem: TurnWiring = { register, provider, prepare }\`.`);
28
+ }
29
+ return { setup, theorem: theorem };
30
+ }
31
+ /** `req` through the application's `prepare`, on the profile the command named. */
32
+ export async function preparedRequest(prepare, req) {
33
+ if (!prepare)
34
+ return req;
35
+ const turn = { ...req, input: req.input ?? {} };
36
+ return { ...(await prepare(turn)), profile: req.profile };
37
+ }
@@ -16,7 +16,7 @@ export type { UserTurnHistoryMedia } from './history.js';
16
16
  export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, } from './history.js';
17
17
  export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
18
18
  export type { InterfaceEffortOption, InterfaceModelOption } from './models.js';
19
- export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, } from './models.js';
19
+ export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, MODEL_SELECT_MIN_MODELS, modelSelectEnabled, } from './models.js';
20
20
  export type { ComposerPendingKind, ComposerPendingMessage, CreateComposerPendingMessageArgs, } from './pending.js';
21
21
  export { COMPOSER_PENDING_KINDS, cloneUserTurnDraft, composerPendingMoves, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, } from './pending.js';
22
22
  export { profileInterfaceSchema } from './profile-interface.js';
@@ -11,7 +11,7 @@ export { prepareUserTurn, sanitizeUserDraft } from './draft.js';
11
11
  export { clientProfileInterface, interfaceFromProfile, interfaceFromProjected, } from './from-profile.js';
12
12
  export { answerOpenToolCalls, appendAssistantEventsToHistory, appendPausedTurnToHistory, appendToolDenialToHistory, appendToolExchangeToHistory, appendUserDraftToHistory, assertOpenToolCalls, historyFromTranscriptBlocks, toolReadBack, userDraftToSteerInject, } from './history.js';
13
13
  export { attachmentAcceptAttr, inputsFromSpec, pickMediaRecorderMime, validateProfileInputs, } from './inputs.js';
14
- export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, } from './models.js';
14
+ export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, MODEL_SELECT_MIN_MODELS, modelSelectEnabled, } from './models.js';
15
15
  export { COMPOSER_PENDING_KINDS, cloneUserTurnDraft, composerPendingMoves, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, } from './pending.js';
16
16
  export { profileInterfaceSchema } from './profile-interface.js';
17
17
  export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, } from './session.js';
@@ -11,6 +11,8 @@ export type InterfaceEffortOption = {
11
11
  alias: string;
12
12
  level: string;
13
13
  };
14
+ /** The fewest models a profile needs before people can pick one; below it, `allowModelSelect` shows no picker. */
15
+ declare const MODEL_SELECT_MIN_MODELS = 2;
14
16
  /** True when the profile lets the user pick between two or more models. */
15
17
  declare function modelSelectEnabled(profile: ModelSelectProfile): boolean;
16
18
  /** True when the model lets the user pick between two or more effort levels. */
@@ -23,4 +25,4 @@ declare function defaultInterfaceEffort(profile: ModelSelectProfile, modelId: Mo
23
25
  declare function interfaceModelOptions(profile: ModelSelectProfile): InterfaceModelOption[];
24
26
  /** The effort levels the user can pick from for this model, or none when the choice is off. */
25
27
  declare function interfaceEffortOptions(profile: ModelSelectProfile, modelId: ModelId | undefined): InterfaceEffortOption[];
26
- export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, };
28
+ export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, MODEL_SELECT_MIN_MODELS, modelSelectEnabled, };
@@ -3,9 +3,11 @@ function bindingFor(profile, modelId) {
3
3
  return undefined;
4
4
  return profile.models[modelId];
5
5
  }
6
+ /** The fewest models a profile needs before people can pick one; below it, `allowModelSelect` shows no picker. */
7
+ const MODEL_SELECT_MIN_MODELS = 2;
6
8
  /** True when the profile lets the user pick between two or more models. */
7
9
  function modelSelectEnabled(profile) {
8
- return Boolean(profile.allowModelSelect && Object.keys(profile.models).length >= 2);
10
+ return Boolean(profile.allowModelSelect && Object.keys(profile.models).length >= MODEL_SELECT_MIN_MODELS);
9
11
  }
10
12
  /** True when the model lets the user pick between two or more effort levels. */
11
13
  function effortSelectEnabled(profile, modelId) {
@@ -47,4 +49,4 @@ function interfaceEffortOptions(profile, modelId) {
47
49
  return [];
48
50
  return Object.entries(binding.efforts).map(([alias, level]) => ({ alias, level }));
49
51
  }
50
- export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, modelSelectEnabled, };
52
+ export { defaultInterfaceEffort, effortSelectEnabled, generationSelectEnabled, interfaceEffortOptions, interfaceModelOptions, MODEL_SELECT_MIN_MODELS, modelSelectEnabled, };
@@ -1,6 +1,7 @@
1
1
  import { errorKind, TheoremError, throwIfAborted } from '../../guardrails/error.js';
2
2
  import { labelText } from '../../guardrails/labels.js';
3
3
  import { traceJson } from '../../observability/trace-span.js';
4
+ import { operationNameOf } from '../protocols/binding.js';
4
5
  import { guardedCall } from '../provider-runtime.js';
5
6
  import { soleModelId } from '../registry/sole-model.js';
6
7
  import { isRecord } from '../util/record.js';
@@ -359,9 +360,9 @@ async function enforceDisclosure(profile, model, provider, request, assets) {
359
360
  throw new DecisionError('disclosure_blocked', 'Decision disclosure was blocked'); // labels-exempt: developer contract error
360
361
  }
361
362
  }
362
- function decisionSpanAttributes(profile, modelId, binding, request, assets) {
363
+ function decisionSpanAttributes(profile, modelId, binding, request, assets, operation) {
363
364
  return {
364
- 'gen_ai.operation.name': 'decide',
365
+ ...(operation ? { 'gen_ai.operation.name': operation } : {}),
365
366
  'gen_ai.provider.name': binding.provider,
366
367
  'gen_ai.agent.name': profile.id,
367
368
  'gen_ai.request.model': binding.apiId,
@@ -458,9 +459,11 @@ export async function runDecisionInRegistry(registry, request, options) {
458
459
  const model = decisionModel(profile);
459
460
  const [modelId, binding] = model;
460
461
  const sent = sentCall(request);
462
+ const provider = registry.providers.get(binding.provider);
463
+ const operation = provider && operationNameOf(provider, binding, 'decision');
461
464
  return await tracedCall({
462
- name: `decide ${binding.apiId}`,
463
- attributes: decisionSpanAttributes(profile, modelId, binding, request, sent.assets),
465
+ name: operation ? `${operation} ${binding.apiId}` : binding.apiId,
466
+ attributes: decisionSpanAttributes(profile, modelId, binding, request, sent.assets, operation),
464
467
  traceparent: request.traceparent,
465
468
  metadata: request.metadata,
466
469
  writer: {
@@ -1,5 +1,5 @@
1
1
  import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
2
- import { protocolOf } from '../protocols/binding.js';
2
+ import { operationNameOf, protocolOf } from '../protocols/binding.js';
3
3
  import { guardedCall } from '../provider-runtime.js';
4
4
  import { attachmentsRefused, base64Bytes } from '../registry/attachments.js';
5
5
  import { embeddingMediaIssues, embeddingRules } from '../registry/embedding-rules.js';
@@ -85,10 +85,11 @@ export async function runEmbeddingInRegistry(registry, request, options = {}) {
85
85
  const call = guardedCall(provider, binding, 'embedding', options, {
86
86
  ...(request.signal ? { signal: request.signal } : {}),
87
87
  });
88
+ const operation = operationNameOf(provider, binding, 'embedding');
88
89
  return await tracedCall({
89
- name: `embed ${binding.apiId}`,
90
+ name: operation ? `${operation} ${binding.apiId}` : binding.apiId,
90
91
  attributes: {
91
- 'gen_ai.operation.name': 'embeddings',
92
+ ...(operation ? { 'gen_ai.operation.name': operation } : {}),
92
93
  'gen_ai.provider.name': binding.provider,
93
94
  'gen_ai.agent.name': profile.id,
94
95
  'gen_ai.request.model': binding.apiId,
@@ -80,6 +80,7 @@ function startProviderCall(generation, system, state, answerOnly, labels) {
80
80
  usage,
81
81
  binding: state.trace.binding,
82
82
  transport: genForStep.transport,
83
+ operation: genForStep.operationName,
83
84
  step: state.stepCount,
84
85
  attempt: state.trace.attempt,
85
86
  });
@@ -405,6 +405,7 @@ class LiveTrace {
405
405
  usage,
406
406
  binding: bound.binding,
407
407
  transport: bound.generation.transport,
408
+ operation: bound.generation.operationName,
408
409
  step: this.responses + 1,
409
410
  });
410
411
  if (!tree) {
@@ -94,6 +94,8 @@ declare function startCallTrace(open: (name: string, options: SpanOptions) => Sp
94
94
  usage: CallUsage;
95
95
  binding: ModelBinding | undefined;
96
96
  transport: ProviderTransport;
97
+ /** The protocol's `gen_ai.operation.name`; absent when no provider is registered for the binding. */
98
+ operation: string | undefined;
97
99
  step: number;
98
100
  /** The runner's validation attempt; Live has none. */
99
101
  attempt?: number;
@@ -348,9 +348,6 @@ function usageAttributes(tokens) {
348
348
  ...(tokens.unknownMedia ? { 'theorem.usage.unknown_media': { ...tokens.unknownMedia } } : {}),
349
349
  };
350
350
  }
351
- function operationName(transport) {
352
- return transport === 'turn' ? 'chat' : 'generate_content';
353
- }
354
351
  /** `gen_ai.provider.name`: the name the provider's preset states; else the binding's server, when declared. */
355
352
  function providerName(binding) {
356
353
  if (!binding)
@@ -369,10 +366,10 @@ function outputType(req, transport) {
369
366
  return 'speech';
370
367
  return 'text';
371
368
  }
372
- function requestAttributes(req, binding, transport) {
369
+ function requestAttributes(req, binding, transport, operation) {
373
370
  const provider = providerName(binding);
374
371
  return {
375
- 'gen_ai.operation.name': operationName(transport),
372
+ ...optional('gen_ai.operation.name', operation),
376
373
  ...optional('gen_ai.provider.name', provider),
377
374
  'gen_ai.request.model': req.apiId,
378
375
  'theorem.model.id': req.model,
@@ -665,12 +662,12 @@ function responseAttributes(response, native, transport) {
665
662
  * `usage.conversation` is read again at the end, since a Live response sets it only when it closes.
666
663
  */
667
664
  function startCallTrace(open, args) {
668
- const { req, usage, transport } = args;
665
+ const { req, usage, transport, operation } = args;
669
666
  const opening = inputMessages(usage);
670
- const span = open(`${operationName(transport)} ${req.apiId}`, {
667
+ const span = open(operation ? `${operation} ${req.apiId}` : req.apiId, {
671
668
  kind: 'CLIENT',
672
669
  attributes: {
673
- ...requestAttributes(req, args.binding, transport),
670
+ ...requestAttributes(req, args.binding, transport, operation),
674
671
  'gen_ai.input.messages': opening.input,
675
672
  ...optional('theorem.input.sent_from', opening.sentFrom),
676
673
  'theorem.step': args.step,
@@ -90,7 +90,7 @@ export const PROFILE_FIELD_PRESENCE = {
90
90
  'turnBehaviour.allowSteering': { unset: 'On', value: true },
91
91
  'turnBehaviour.atStepLimit': { unset: 'stop', value: 'stop' },
92
92
  'guardrails.quota': { unset: 'No limit' },
93
- 'guardrails.detect': { unset: 'Redacts what goes to the model' },
93
+ 'guardrails.detect': { unset: 'Flags what goes to the model' },
94
94
  'guardrails.detect.ungiven_images.allow.fromTools': { unset: 'On', value: true },
95
95
  'guardrails.detect.ungiven_links.allow.fromTools': { unset: 'On', value: true },
96
96
  'guardrails.blockedReply': { unset: 'One rewrite' },
@@ -60,6 +60,8 @@ export declare function keySlotsOf(provider: {
60
60
  export declare function bindingServe(provider: RegisteredProvider, binding: ModelBinding | DecisionModelBinding): RegisteredProvider['serves'][number];
61
61
  /** The protocol a binding speaks on its provider. */
62
62
  export declare function protocolOf(provider: RegisteredProvider, binding: ModelBinding | DecisionModelBinding): Protocol;
63
+ /** The `gen_ai.operation.name` of a call the binding makes for `profileType`. */
64
+ export declare function operationNameOf(provider: RegisteredProvider, binding: ModelBinding | DecisionModelBinding, profileType: ModelProfileType): string | undefined;
63
65
  /**
64
66
  * The one place a binding meets its provider, once, at registration, for fit only. Returns the
65
67
  * binding with its options parsed; changes nothing in place.
@@ -109,6 +109,10 @@ export function bindingServe(provider, binding) {
109
109
  export function protocolOf(provider, binding) {
110
110
  return bindingServe(provider, binding).protocol;
111
111
  }
112
+ /** The `gen_ai.operation.name` of a call the binding makes for `profileType`. */
113
+ export function operationNameOf(provider, binding, profileType) {
114
+ return protocolOf(provider, binding).operationNames[profileType];
115
+ }
112
116
  /**
113
117
  * The one place a binding meets its provider, once, at registration, for fit only. Returns the
114
118
  * binding with its options parsed; changes nothing in place.
@@ -170,6 +170,11 @@ export interface ProtocolDefinition<O = unknown, S = unknown> {
170
170
  description: string;
171
171
  /** The path each profile type uses. A type with no entry is not served. */
172
172
  endpoints: Partial<Record<ModelProfileType, string>>;
173
+ /**
174
+ * The `gen_ai.operation.name` a call to each endpoint has, e.g. `'chat'`: one per endpoint. Use a
175
+ * GenAI semconv well-known value where one applies.
176
+ */
177
+ operationNames: Partial<Record<ModelProfileType, string>>;
173
178
  /** Every field a binding may set, each described. */
174
179
  options: z.ZodType<O>;
175
180
  continuation?: Continuation<S>;
@@ -231,6 +236,8 @@ export interface ProtocolExtension<E = unknown, S = unknown> extends Pick<Protoc
231
236
  options?: z.ZodObject & z.ZodType<E>;
232
237
  /** Its own paths, where they differ from the base's. */
233
238
  endpoints?: Partial<Record<ModelProfileType, string>>;
239
+ /** Its own operation names, where they differ from the base's. */
240
+ operationNames?: Partial<Record<ModelProfileType, string>>;
234
241
  /** What it adds to the base's request (or a WebSocket's first frame), and the tools it wrote. */
235
242
  body?(body: JsonObject, at: ExtensionBodyAt<E>): {
236
243
  body: JsonObject;
@@ -15,6 +15,7 @@ const definitionShape = z.object({
15
15
  name: z.string().min(1),
16
16
  description: z.string().min(1),
17
17
  endpoints: z.partialRecord(z.enum(MODEL_PROFILE_TYPES), z.string().min(1)),
18
+ operationNames: z.partialRecord(z.enum(MODEL_PROFILE_TYPES), z.string().regex(/^[a-z][a-z0-9_]*$/)),
18
19
  });
19
20
  function refuse(id, issues) {
20
21
  return new TheoremError('config', labelText('protocol.definition', { id, issues }));
@@ -24,6 +25,13 @@ function checkShape(definition) {
24
25
  if (!parsed.success)
25
26
  throw refuse(String(definition.id), z.prettifyError(parsed.error));
26
27
  }
28
+ function checkOperations(id, endpoints, operationNames) {
29
+ const served = Object.keys(endpoints).toSorted().join(', ');
30
+ const named = Object.keys(operationNames).toSorted().join(', ');
31
+ if (served !== named)
32
+ // labels-exempt: builder diagnostic
33
+ throw refuse(id, `operationNames name [${named}]; endpoints serve [${served}]`);
34
+ }
27
35
  function own(protocol, kind, schema, value) {
28
36
  if (!schema)
29
37
  throw new TheoremError('internal', labelText('protocol.part_schema', { protocol: protocol.id, kind }));
@@ -96,6 +104,7 @@ export function defineProtocol(definition) {
96
104
  typeof definition.options?.safeParse !== 'function')
97
105
  // labels-exempt: builder diagnostic
98
106
  throw refuse(definition.id, 'create and options are required');
107
+ checkOperations(definition.id, definition.endpoints, definition.operationNames);
99
108
  return Object.freeze({
100
109
  ...definition,
101
110
  lineage: Object.freeze([definition.id]),
@@ -227,13 +236,21 @@ function either(key, extension, base) {
227
236
  * typing are the base's unless it gives its own.
228
237
  */
229
238
  export function extendProtocol(base, extension) {
230
- checkShape({ ...extension, endpoints: extension.endpoints ?? {} });
239
+ checkShape({
240
+ ...extension,
241
+ endpoints: extension.endpoints ?? {},
242
+ operationNames: extension.operationNames ?? {},
243
+ });
244
+ const endpoints = { ...base.endpoints, ...extension.endpoints };
245
+ const operationNames = { ...base.operationNames, ...extension.operationNames };
246
+ checkOperations(extension.id, endpoints, operationNames);
231
247
  const keys = mergeOptions(base, extension);
232
248
  return Object.freeze({
233
249
  id: extension.id,
234
250
  name: extension.name,
235
251
  description: extension.description,
236
- endpoints: { ...base.endpoints, ...extension.endpoints },
252
+ endpoints,
253
+ operationNames,
237
254
  options: keys.schema,
238
255
  ...(base.continuation ? { continuation: base.continuation } : {}),
239
256
  ...(extension.reasoning ? { reasoning: extension.reasoning } : {}),
@@ -6,6 +6,7 @@ import { replyIsJudged } from '../../guardrails/progressive-yield.js';
6
6
  import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
7
7
  import { ANSWER_TOOL } from '../answer-tool.js';
8
8
  import { DEFAULT_MAX_STEPS } from '../profile-presence.js';
9
+ import { operationNameOf } from '../protocols/binding.js';
9
10
  import { profileTurnResumption } from '../stop.js';
10
11
  import { projectTools } from '../tools/project.js';
11
12
  import { resolveTurnTools } from '../tools/resolve.js';
@@ -178,12 +179,15 @@ function resolveTurnInRegistry(registry, req, model) {
178
179
  assertSpeechRole(profile, safe);
179
180
  const builtInArgs = resolveBuiltInArgs(profile, picked, binding, safe.builtInArgs);
180
181
  const transport = resolveTransport(profile, binding);
182
+ const provider = registry.providers.get(binding.provider);
183
+ const operationName = provider && operationNameOf(provider, binding, profile.type);
181
184
  return {
182
185
  profile,
183
186
  generation: {
184
187
  model: picked,
185
188
  apiId: binding.apiId,
186
189
  transport,
190
+ ...(operationName ? { operationName } : {}),
187
191
  stream: resolveStreamFlag(profile),
188
192
  thinking: resolveEffort(profile, binding, picked, safe.effort),
189
193
  summaries: resolveSummaries(binding),
@@ -888,7 +888,7 @@ export const EXTRA_FIELDS = {
888
888
  always_confirm: 'Asks every time.',
889
889
  }),
890
890
  'registerTool.category': field('string', 'A label for grouping tools; nothing reads it yet.'),
891
- 'registerTool.labels': field('ToolLabels', "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit."),
891
+ 'registerTool.labels': field('ToolLabels', "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit."),
892
892
  'registerTool.labels.activity': {
893
893
  ...field('string | string[]', "Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the call's input."),
894
894
  unset: 'The tool name, in words',
@@ -3,8 +3,9 @@ export type LabelTemplate = string | readonly string[];
3
3
  /** A tool's name as a label shows it: `manage_alert` reads "manage alert". */
4
4
  export declare function toolNameInWords(name: string): string;
5
5
  /**
6
- * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a line fits
7
- * when every placeholder has a value or a fallback and its `when` holds. A list shows its first
6
+ * Fills each `{path}`, `{path|fallback}` or `{count one|other}` from the call. Only text and numbers
7
+ * fill, and a count fills only from a number; a line fits when every placeholder has a value or a
8
+ * fallback and its `when` holds. A list shows its first
8
9
  * line that fits, and a run of `+` lines shows every member that fits, joined in words. When no
9
10
  * line fits the label is `undefined`, and the transcript names the tool.
10
11
  */
@@ -5,6 +5,8 @@ const UNPRINTABLE = /[\p{Cc}\p{Cf}]/gu;
5
5
  const INDEX = /^-?\d+$/;
6
6
  const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
7
7
  const NUMBER = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
8
+ // why: The forms are the author's English words, so English rules choose between them.
9
+ const PLURAL = new Intl.PluralRules('en');
8
10
  // why: Dates show the wall-clock time as the tool wrote it, not converted to the server's zone.
9
11
  const DAY = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeZone: 'UTC' });
10
12
  const DAY_TIME = new Intl.DateTimeFormat(undefined, {
@@ -17,10 +19,17 @@ const JOINED = /^\+\s+/;
17
19
  const WHEN_ENDS = /:(?:\s|$)/;
18
20
  const CHECK = /^(\S+) is (?:(not) )?(\S.*)$/;
19
21
  function parsePlaceholder(raw) {
20
- const bar = raw.indexOf('|');
21
- if (bar < 0)
22
- return { path: raw.trim() };
23
- return { path: raw.slice(0, bar).trim(), fallback: raw.slice(bar + 1).trim() };
22
+ const text = raw.trim();
23
+ const end = text.search(/[\s|]/);
24
+ if (end < 0)
25
+ return { path: text };
26
+ const path = text.slice(0, end);
27
+ const rest = text.slice(end).trimStart();
28
+ if (rest.startsWith('|'))
29
+ return { path, fallback: rest.slice(1).trim() };
30
+ const [one = '', other = '', ...fallback] = rest.split('|').map((part) => part.trim());
31
+ const forms = one && other ? { one, other } : 'unreadable';
32
+ return fallback.length ? { path, forms, fallback: fallback.join('|') } : { path, forms };
24
33
  }
25
34
  /** `input.x` and `output.x` read one side; a bare path reads the input, then the output. */
26
35
  function routes(path, sides) {
@@ -135,15 +144,22 @@ export function toolNameInWords(name) {
135
144
  .trim()
136
145
  .toLowerCase();
137
146
  }
147
+ function countText(found, forms) {
148
+ if (forms === 'unreadable')
149
+ return undefined;
150
+ const count = found.find((value) => typeof value === 'number' && Number.isFinite(value));
151
+ if (count === undefined)
152
+ return undefined;
153
+ return `${NUMBER.format(count)} ${PLURAL.select(count) === 'one' ? forms.one : forms.other}`;
154
+ }
138
155
  function fillText(template, values, sides) {
139
156
  let missing = false;
140
157
  const filled = template.replace(PLACEHOLDER, (_, raw) => {
141
- const { path, fallback } = parsePlaceholder(raw);
142
- const value = path
143
- ? routes(path, sides)
144
- .map((route) => labelValue(valueAt(values[route.side], route.keys)))
145
- .find((text) => text !== undefined)
146
- : undefined;
158
+ const { path, fallback, forms } = parsePlaceholder(raw);
159
+ const found = path
160
+ ? routes(path, sides).map((route) => valueAt(values[route.side], route.keys))
161
+ : [];
162
+ const value = forms ? countText(found, forms) : found.map(labelValue).find(Boolean);
147
163
  if (value === undefined && fallback === undefined)
148
164
  missing = true;
149
165
  return value ?? fallback ?? '';
@@ -152,8 +168,9 @@ function fillText(template, values, sides) {
152
168
  return missing || !text ? undefined : text;
153
169
  }
154
170
  /**
155
- * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a line fits
156
- * when every placeholder has a value or a fallback and its `when` holds. A list shows its first
171
+ * Fills each `{path}`, `{path|fallback}` or `{count one|other}` from the call. Only text and numbers
172
+ * fill, and a count fills only from a number; a line fits when every placeholder has a value or a
173
+ * fallback and its `when` holds. A list shows its first
157
174
  * line that fits, and a run of `+` lines shows every member that fits, joined in words. When no
158
175
  * line fits the label is `undefined`, and the transcript names the tool.
159
176
  */
@@ -265,11 +282,14 @@ function tryInstead(paths) {
265
282
  }
266
283
  function placeholderProblem(template, schemas, sides) {
267
284
  for (const match of template.matchAll(PLACEHOLDER)) {
268
- const { path } = parsePlaceholder(match[1] ?? '');
285
+ const { path, forms } = parsePlaceholder(match[1] ?? '');
269
286
  if (!path) {
270
287
  const example = placeholdersAt(schemas.input, '')[0] ?? 'name';
271
288
  return `Put a field name between the braces, like {${example}}.`; // labels-exempt: builder diagnostic
272
289
  }
290
+ if (forms === 'unreadable') {
291
+ return `{${match[1]?.trim()}} needs a word for one and a word for any other number, like {${path} item|items}.`; // labels-exempt: builder diagnostic
292
+ }
273
293
  const paths = routes(path, sides);
274
294
  const [route] = paths;
275
295
  if (!route)
@@ -278,8 +298,13 @@ function placeholderProblem(template, schemas, sides) {
278
298
  return `{${path}} is only there once the call is done; use it in the Done label.`; // labels-exempt: builder diagnostic
279
299
  }
280
300
  const found = mergeHolds(paths.map(({ side, keys, prefixed }) => schemaPathHolds(schemas[side], keys, prefixed ? side : '')));
281
- if (found.holds === 'value')
301
+ if (found.holds === 'value') {
302
+ const counts = paths.some(({ side, keys }) => schemaLeavesAt(schemas[side], keys).some((leaf) => leaf.number));
303
+ if (forms && !counts) {
304
+ return `{${path}} is not a number, so it has no plural. Count a list with {${path}.length ${forms.one}|${forms.other}}.`; // labels-exempt: builder diagnostic
305
+ }
282
306
  continue;
307
+ }
283
308
  const all = found.instead ?? [];
284
309
  const depth = route.prefixed ? 1 : 0;
285
310
  const near = all.filter((candidate) => candidate.split('.')[depth] === route.keys[0]);
@@ -292,13 +317,12 @@ function placeholderProblem(template, schemas, sides) {
292
317
  // why: What the builder ended the path with (a length, a name) says which of the fields they meant.
293
318
  const last = route.keys.at(-1);
294
319
  const tail = (candidate) => (candidate.split('.').at(-1) === last ? 0 : 1);
295
- // why: Not `toSorted`: the studio's declaration build targets a lib before ES2023.
296
- const ranked = [...(near.length ? near : all)].sort((a, b) => tail(a) - tail(b));
320
+ const ranked = (near.length ? near : all).toSorted((a, b) => tail(a) - tail(b));
297
321
  return `{${path}} ${reason}${tryInstead(ranked)}`;
298
322
  }
299
323
  return undefined;
300
324
  }
301
- const OPEN_LEAF = { texts: 'any', nullable: true };
325
+ const OPEN_LEAF = { texts: 'any', nullable: true, number: true };
302
326
  function rawTypes(node) {
303
327
  const types = Array.isArray(node.type) ? node.type : [node.type];
304
328
  return types.filter((type) => typeof type === 'string');
@@ -309,6 +333,7 @@ function leafOf(node) {
309
333
  return {
310
334
  texts: listed.filter((value) => value !== null).map((value) => `${value}`),
311
335
  nullable: listed.includes(null),
336
+ number: listed.some((value) => typeof value === 'number'),
312
337
  };
313
338
  }
314
339
  const types = rawTypes(node);
@@ -319,6 +344,7 @@ function leafOf(node) {
319
344
  return {
320
345
  texts: flag ? (shown.length ? ['true', 'false'] : []) : 'any',
321
346
  nullable: types.includes('null'),
347
+ number: shown.some((type) => type === 'number' || type === 'integer'),
322
348
  };
323
349
  }
324
350
  // why: A schema that doesn't say what's there ($ref, no properties, no items) is taken on trust.
@@ -333,8 +359,9 @@ function schemaLeavesAt(node, keys) {
333
359
  return [leafOf(node)];
334
360
  const types = schemaTypes(node);
335
361
  if (types.includes('array')) {
336
- if (key === 'length')
337
- return rest.length ? [] : [{ texts: 'any', nullable: false }];
362
+ if (key === 'length') {
363
+ return rest.length ? [] : [{ texts: 'any', nullable: false, number: true }];
364
+ }
338
365
  if (INDEX.test(key))
339
366
  return schemaLeavesAt(node.items, rest);
340
367
  }
@@ -873,6 +873,8 @@ export interface ResolvedGeneration extends ProviderGenerationConfig {
873
873
  execution?: ToolExecutionCoordinator;
874
874
  pageExecution?: PageToolExecution;
875
875
  transport: ProviderTransport;
876
+ /** The protocol's `gen_ai.operation.name` for this profile type; absent when no provider is registered for the binding. */
877
+ operationName?: string;
876
878
  tools: TurnToolSnapshot;
877
879
  sessionPermissions?: string[];
878
880
  history?: TurnHistoryMessage[];
@@ -1,5 +1,5 @@
1
1
  declare const OMIT_INJECTION = "[omitted - injection]";
2
- declare const OMIT_SENSITIVE = "[omitted -sensitive]";
2
+ declare const OMIT_SENSITIVE = "[omitted - sensitive]";
3
3
  declare const OMIT_CANARY = "[omitted - canary]";
4
4
  declare const OMIT_PROMPT = "[omitted - instructions]";
5
5
  type RedactKind = 'injection' | 'sensitive' | 'canary' | 'prompt' | 'image' | 'link' | 'tool' | 'directive' | 'host';
@@ -1,5 +1,5 @@
1
1
  const OMIT_INJECTION = '[omitted - injection]';
2
- const OMIT_SENSITIVE = '[omitted -sensitive]';
2
+ const OMIT_SENSITIVE = '[omitted - sensitive]';
3
3
  const OMIT_CANARY = '[omitted - canary]';
4
4
  const OMIT_PROMPT = '[omitted - instructions]';
5
5
  const OMIT_IMAGE = '[omitted - image]';
@@ -179,8 +179,11 @@ const CASE_KINDS = {
179
179
  };
180
180
  const OPERATIONS = {
181
181
  invoke_agent: { label: 'Run agent', doc: 'One turn of an agent, or one Live session.' },
182
- chat: { label: 'Chat', doc: 'A model call over a chat-completions API.' },
183
- generate_content: { label: 'Generate content', doc: 'A model call over a Gemini API.' },
182
+ chat: { label: 'Chat', doc: 'A model call to a chat-completions endpoint.' },
183
+ generate_content: {
184
+ label: 'Generate content',
185
+ doc: 'A model call that generates content other than over chat completions: Gemini, speech, or images.',
186
+ },
184
187
  execute_tool: { label: 'Run tool', doc: 'A tool call theorem ran.' },
185
188
  decide: {
186
189
  label: 'Decide',
@@ -81,6 +81,7 @@ export const geminiEmbeddings = defineProtocol({
81
81
  name: 'Gemini Embeddings',
82
82
  description: "Google's embedding API for text and supported media.",
83
83
  endpoints: { embedding: '/models/{apiId}:embedContent' },
84
+ operationNames: { embedding: 'embeddings' },
84
85
  options,
85
86
  embeddingLimits: (apiId) => (TASK_FIELD_MODELS.test(apiId) ? TEXT_ONLY : MULTIMODAL),
86
87
  // why: Gemini Embedding 2 reads the task from the text and refuses the field; the request's `task` says it.
@@ -63,6 +63,11 @@ export const geminiInteractions = defineProtocol({
63
63
  name: 'Gemini Interactions',
64
64
  description: "Google's Interactions API for Gemini: text, images and speech at one endpoint.", // labels-exempt: builder field description, read by the studio and docs
65
65
  endpoints: { text: '/interactions', image: '/interactions', speech: '/interactions' },
66
+ operationNames: {
67
+ text: 'generate_content',
68
+ image: 'generate_content',
69
+ speech: 'generate_content',
70
+ },
66
71
  options,
67
72
  continuation: { version: 1, schema: state, keyOptions: ['store', 'persistViaInteractionId'] },
68
73
  reasoning: thoughtSignature,
@@ -148,6 +148,7 @@ export const geminiLive = defineProtocol({
148
148
  name: 'Gemini Live',
149
149
  description: "Google's Live API for Gemini: a spoken session over one WebSocket.", // labels-exempt: builder field description, read by the studio and docs
150
150
  endpoints: { live: '/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent' },
151
+ operationNames: { live: 'generate_content' },
151
152
  options: z.strictObject({}),
152
153
  continuation: { version: 1, schema: state },
153
154
  create(context) {
@@ -28,6 +28,7 @@ export const ollamaEmbeddings = defineProtocol({
28
28
  name: 'Ollama Embeddings',
29
29
  description: 'Ollama’s local embedding endpoint.',
30
30
  endpoints: { embedding: '/api/embed' },
31
+ operationNames: { embedding: 'embeddings' },
31
32
  options,
32
33
  embeddingLimits: () => ({ media: [] }),
33
34
  create(context) {
@@ -174,6 +174,7 @@ export const openAi = defineProtocol({
174
174
  name: 'OpenAI Chat Completions',
175
175
  description: 'The Chat Completions shape that OpenAI and most compatible servers speak.', // labels-exempt: builder field description, read by the studio and docs
176
176
  endpoints: { text: '/chat/completions', speech: '/audio/speech' },
177
+ operationNames: { text: 'chat', speech: 'generate_content' },
177
178
  options: z.strictObject({}),
178
179
  error: (failure) => httpError(failure, 'Chat Completions'),
179
180
  create(context) {
@@ -12,6 +12,7 @@ export const openRouterDecisions = defineProtocol({
12
12
  name: 'OpenRouter Decisions',
13
13
  description: "OpenRouter's decision API: questions about a state, answered in one call.", // labels-exempt: builder field description, read by the studio and docs
14
14
  endpoints: { decision: '/alpha/decisions' },
15
+ operationNames: { decision: 'decide' },
15
16
  options: z.strictObject({}),
16
17
  create(context) {
17
18
  return {
@@ -43,6 +43,7 @@ export const openRouterEmbeddings = defineProtocol({
43
43
  name: 'OpenRouter Embeddings',
44
44
  description: 'OpenRouter embedding models, including supported multimodal models.',
45
45
  endpoints: { embedding: '/embeddings' },
46
+ operationNames: { embedding: 'embeddings' },
46
47
  options,
47
48
  embeddingLimits: () => LIMITS,
48
49
  create(context) {
@@ -66,6 +66,7 @@ export const openRouterImages = defineProtocol({
66
66
  name: 'OpenRouter Images',
67
67
  description: "OpenRouter's image generation, with or without text beside the picture.", // labels-exempt: builder field description, read by the studio and docs
68
68
  endpoints: { image: '/images' },
69
+ operationNames: { image: 'generate_content' },
69
70
  options: z.strictObject({}),
70
71
  create(context) {
71
72
  return {
@@ -32,6 +32,7 @@ export const systemOne = defineProtocol({
32
32
  name: 'System One',
33
33
  description: "TypeSafe's decision API: questions about a state, answered in one call.", // labels-exempt: builder field description, read by the studio and docs
34
34
  endpoints: { decision: '/systemone' },
35
+ operationNames: { decision: 'decide' },
35
36
  options,
36
37
  create(context) {
37
38
  return {
@@ -1,11 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { jsonSchemaFromZod } from '../kernel/tools/schema.js';
3
3
  import { knownSecrets, maskHeaders, maskUrl, scrubDeep, secretCard } from './formats.js';
4
- const LEDGER_SIZE = 100;
5
4
  const INTENT_WINDOW_MS = 60_000;
6
5
  const MOUNT_WAIT_MS = 5000;
7
6
  const NODE_LIST_CAP = 80;
8
- const RECENT_IN_STATE = 5;
9
7
  /** The tools the runtime answers: `look` and `act`. */
10
8
  export const SURFACE_TOOL_NAMES = ['look', 'act'];
11
9
  const lookArgs = z.object({ at: z.string().optional() });
@@ -57,7 +55,7 @@ export function createSurfaceRuntime(options = {}) {
57
55
  let ledger = [...(options.ledger?.load() ?? [])];
58
56
  const note = (line) => options.onNote?.(line);
59
57
  const remember = (entry) => {
60
- ledger = [...ledger.filter((old) => old.callId !== entry.callId), entry].slice(-LEDGER_SIZE);
58
+ ledger = [...ledger.filter((old) => old.callId !== entry.callId), entry];
61
59
  options.ledger?.save(ledger);
62
60
  };
63
61
  const address = (surface, nodeId) => nodeId ? `${surface.id}/${nodeId}` : surface.id;
@@ -428,14 +426,9 @@ export function createSurfaceRuntime(options = {}) {
428
426
  },
429
427
  stateLine() {
430
428
  const surfaces = [...mounted.values()].map((surface) => `${surface.id} r${String(surface.revision())}: ${surface.summary()}`);
431
- const recent = ledger
432
- .slice(-RECENT_IN_STATE)
433
- .map((entry) => `${entry.at} ${entry.action}`)
434
- .join(', ');
435
- if (!surfaces.length && !recent)
429
+ if (!surfaces.length)
436
430
  return null;
437
- const line = [surfaces.join('; '), recent ? `last calls: ${recent}` : ''].filter(Boolean);
438
- return scrubDeep(`(state) ${line.join('; ')}`, known());
431
+ return scrubDeep(`(state) ${surfaces.join('; ')}`, known());
439
432
  },
440
433
  };
441
434
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.649.gf83cea1",
3
+ "version": "0.3.4-next.673.ga492632",
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",