@theoremjs/agents 0.3.4-next.677.g14b70fe → 0.3.4-next.693.g4ab1526

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 (61) hide show
  1. package/README.md +4 -3
  2. package/esm/mod.d.ts +3 -1
  3. package/esm/mod.js +2 -0
  4. package/esm/src/cli/commands/bench.js +4 -10
  5. package/esm/src/cli/commands/profile.js +4 -1
  6. package/esm/src/guardrails/labels.d.ts +1 -1
  7. package/esm/src/guardrails/labels.js +3 -0
  8. package/esm/src/interface/blocks.js +19 -0
  9. package/esm/src/interface/from-profile.d.ts +2 -2
  10. package/esm/src/interface/from-profile.js +7 -0
  11. package/esm/src/interface/mod.d.ts +1 -1
  12. package/esm/src/interface/profile-interface.js +14 -4
  13. package/esm/src/interface/types.d.ts +6 -4
  14. package/esm/src/kernel/api-catalog.js +5 -5
  15. package/esm/src/kernel/auth/oauth.js +3 -1
  16. package/esm/src/kernel/engine/runner/mod.js +1 -0
  17. package/esm/src/kernel/engine/session/mod.js +1 -0
  18. package/esm/src/kernel/engine/session/session-trace.js +1 -0
  19. package/esm/src/kernel/mod.d.ts +3 -1
  20. package/esm/src/kernel/mod.js +2 -0
  21. package/esm/src/kernel/profile-presence.js +1 -0
  22. package/esm/src/kernel/profile-scope.js +23 -21
  23. package/esm/src/kernel/protocols/protocol.d.ts +1 -1
  24. package/esm/src/kernel/protocols/protocol.js +1 -0
  25. package/esm/src/kernel/registry/catalog.js +4 -1
  26. package/esm/src/kernel/registry/ingress.d.ts +3 -1
  27. package/esm/src/kernel/registry/ingress.js +12 -1
  28. package/esm/src/kernel/registry/profile-outputs.js +2 -1
  29. package/esm/src/kernel/registry/profiles.d.ts +12 -2
  30. package/esm/src/kernel/registry/profiles.js +37 -7
  31. package/esm/src/kernel/registry/resolve.js +9 -5
  32. package/esm/src/kernel/registry/system-prompt.d.ts +6 -1
  33. package/esm/src/kernel/registry/system-prompt.js +20 -13
  34. package/esm/src/kernel/schema.d.ts +1 -1
  35. package/esm/src/kernel/schema.js +12 -8
  36. package/esm/src/kernel/system-lines.d.ts +22 -0
  37. package/esm/src/kernel/system-lines.js +162 -0
  38. package/esm/src/kernel/tools/activity-label.d.ts +15 -0
  39. package/esm/src/kernel/tools/activity-label.js +12 -7
  40. package/esm/src/kernel/tools/agent.js +1 -1
  41. package/esm/src/kernel/tools/call-order.d.ts +16 -0
  42. package/esm/src/kernel/tools/call-order.js +48 -0
  43. package/esm/src/kernel/tools/registry.js +9 -6
  44. package/esm/src/kernel/tools/resolve.js +11 -0
  45. package/esm/src/kernel/tools/stage-run.d.ts +1 -1
  46. package/esm/src/kernel/tools/stage-run.js +57 -55
  47. package/esm/src/kernel/tools/types.d.ts +3 -0
  48. package/esm/src/kernel/types.d.ts +31 -4
  49. package/esm/src/observability/trace-catalog.js +3 -0
  50. package/esm/src/providers/google/interactions/steps.js +14 -3
  51. package/esm/src/providers/mod.d.ts +2 -0
  52. package/esm/src/providers/mod.js +1 -0
  53. package/esm/src/providers/openrouter/protocol.d.ts +26 -0
  54. package/esm/src/providers/openrouter/protocol.js +58 -2
  55. package/esm/src/providers/openrouter/provider.d.ts +1 -1
  56. package/esm/src/providers/openrouter/provider.js +3 -1
  57. package/esm/src/providers/openrouter/transcriptions-protocol.d.ts +10 -0
  58. package/esm/src/providers/openrouter/transcriptions-protocol.js +87 -0
  59. package/package.json +1 -1
  60. package/esm/src/kernel/registry/system-role.d.ts +0 -3
  61. package/esm/src/kernel/registry/system-role.js +0 -9
@@ -0,0 +1,162 @@
1
+ import { TheoremError } from '../guardrails/error.js';
2
+ import { assertSystemPrompt } from './system-parts.js';
3
+ import { checkHolds, checkProblem, splitWhen } from './tools/activity-label.js';
4
+ const CONDITION_NAME = /^[A-Za-z_][\w-]*$/;
5
+ const CONDITION_VALUE = /^\S+$/;
6
+ function linesOf(prompt) {
7
+ if (typeof prompt === 'string')
8
+ return [[prompt]];
9
+ return prompt.map((line) => (typeof line === 'string' ? [line] : line));
10
+ }
11
+ function textOf(part) {
12
+ return typeof part === 'string' ? part : part.private;
13
+ }
14
+ function headOf(parts) {
15
+ return splitWhen(parts[0] === undefined ? '' : textOf(parts[0]));
16
+ }
17
+ function factsSchema(conditions, slots) {
18
+ const properties = {};
19
+ for (const [name, values] of Object.entries({ ...conditions, ...slots })) {
20
+ properties[name] = { type: 'string', enum: [...values] };
21
+ }
22
+ return { type: 'object', properties };
23
+ }
24
+ function conditionsProblem(conditions, slots) {
25
+ for (const [name, values] of Object.entries(conditions ?? {})) {
26
+ if (!CONDITION_NAME.test(name))
27
+ return `Condition "${name}" needs a plain name.`; // labels-exempt: developer contract error
28
+ if (name === 'input' || name === 'output')
29
+ return `Condition "${name}" is a reserved name.`; // labels-exempt: developer contract error
30
+ if (Object.hasOwn(slots, name))
31
+ return `"${name}" is both a condition and a slot.`; // labels-exempt: developer contract error
32
+ if (values.length === 0)
33
+ return `Condition "${name}" lists no values.`; // labels-exempt: developer contract error
34
+ const bad = values.find((value) => !CONDITION_VALUE.test(value) || value === 'null');
35
+ if (bad !== undefined)
36
+ return `Condition "${name}" can't take the value "${bad}".`; // labels-exempt: developer contract error
37
+ }
38
+ return undefined;
39
+ }
40
+ function lineProblem(parts, schema) {
41
+ if (parts.length === 0)
42
+ return 'It has no wording to send.'; // labels-exempt: developer contract error
43
+ const line = headOf(parts);
44
+ if (line.joined)
45
+ return 'A prompt line can\'t start with "+"; every line that fits is sent.'; // labels-exempt: developer contract error
46
+ if (line.when === 'unreadable') {
47
+ return 'A line that opens with "when" needs a condition and a colon, like "when path is web: …".'; // labels-exempt: developer contract error
48
+ }
49
+ for (const check of line.when) {
50
+ if (check.path.includes('.'))
51
+ return `"${check.path}" isn't one condition or slot.`; // labels-exempt: developer contract error
52
+ if (check.expected === null)
53
+ return 'A condition always has a value, so "is null" never fits.'; // labels-exempt: developer contract error
54
+ const problem = checkProblem(check, schema, 'this profile’s conditions or slots');
55
+ if (problem)
56
+ return problem;
57
+ }
58
+ if (line.when.length > 0 && !line.text && parts.length === 1) {
59
+ return 'It has no wording to send.'; // labels-exempt: developer contract error
60
+ }
61
+ return undefined;
62
+ }
63
+ /** What is wrong with a prompt's conditions and lines, or undefined. */
64
+ export function systemLinesProblem(prompt, conditions, slots) {
65
+ const declared = conditionsProblem(conditions, slots);
66
+ if (declared)
67
+ return declared;
68
+ const schema = factsSchema(conditions, slots);
69
+ for (const [at, parts] of linesOf(prompt).entries()) {
70
+ const problem = lineProblem(parts, schema);
71
+ if (problem)
72
+ return `Line ${at + 1}: ${problem}`;
73
+ }
74
+ return undefined;
75
+ }
76
+ /** The facts a turn's `when` reads, once the turn has stated every condition with a listed value. */
77
+ export function turnFacts(id, conditions, req, slots) {
78
+ const stated = req.conditions ?? {};
79
+ if (conditions === undefined) {
80
+ if (req.conditions)
81
+ throw new TheoremError('request', `Profile ${id} declares no conditions`); // labels-exempt: developer contract error
82
+ return { ...slots };
83
+ }
84
+ if (Object.hasOwn(stated, 'path')) {
85
+ throw new TheoremError('request', `Profile ${id}: the turn's own path states path`); // labels-exempt: developer contract error
86
+ }
87
+ for (const name of Object.keys(stated)) {
88
+ if (!Object.hasOwn(conditions, name)) {
89
+ throw new TheoremError('request', `Profile ${id} has no condition '${name}'`); // labels-exempt: developer contract error
90
+ }
91
+ }
92
+ const facts = { ...slots };
93
+ for (const [name, values] of Object.entries(conditions)) {
94
+ const value = name === 'path' ? req.path : stated[name];
95
+ if (value === undefined) {
96
+ throw new TheoremError('request', `Profile ${id}: the turn left condition '${name}' unset`); // labels-exempt: developer contract error
97
+ }
98
+ if (!values.includes(value)) {
99
+ throw new TheoremError('request', `Profile ${id}: '${value}' is no value of condition '${name}'`);
100
+ }
101
+ facts[name] = value;
102
+ }
103
+ return facts;
104
+ }
105
+ function lineFits(line, facts) {
106
+ if (line.when === 'unreadable')
107
+ return false;
108
+ return line.when.every((check) => checkHolds(check, facts));
109
+ }
110
+ /**
111
+ * Every line that fits. Whether plain text is shareable is settled on the prompt as written, so a
112
+ * line dropped on this turn never changes the marks of one that stayed.
113
+ */
114
+ export function pickSystemLines(prompt, facts, fill) {
115
+ const lines = linesOf(prompt);
116
+ const marked = lines.flat().some((part) => typeof part !== 'string');
117
+ const kept = [];
118
+ for (const [at, parts] of lines.entries()) {
119
+ const line = headOf(parts);
120
+ if (!lineFits(line, facts))
121
+ continue;
122
+ const pieces = [];
123
+ for (const [partAt, part] of parts.entries()) {
124
+ const text = fill(partAt === 0 ? line.text : textOf(part));
125
+ if (text)
126
+ pieces.push({ text, private: typeof part === 'string' ? !marked : true });
127
+ }
128
+ kept.push({ line: at + 1, pieces });
129
+ }
130
+ return kept;
131
+ }
132
+ /** `where` names the prompt in the error. A bare `{ private }` must sit inside a line's own list. */
133
+ export function assertSystemLines(prompt, where) {
134
+ if (typeof prompt === 'string')
135
+ return;
136
+ if (!Array.isArray(prompt)) {
137
+ throw new TheoremError('config', `${where} must be a string or an array of lines`); // labels-exempt: developer contract error
138
+ }
139
+ if (prompt.length === 0)
140
+ throw new TheoremError('config', `${where} must not be an empty array`); // labels-exempt: developer contract error
141
+ for (const [at, line] of prompt.entries()) {
142
+ if (typeof line === 'string')
143
+ continue;
144
+ if (!Array.isArray(line)) {
145
+ throw new TheoremError('config', `${where}[${at}] must be a string or a list of parts; put { private } inside the list`);
146
+ }
147
+ assertSystemPrompt(line, `${where}[${at}]`);
148
+ }
149
+ }
150
+ /** The first tool in `tools` with a path `conditions.path` does not list, as a sentence. */
151
+ export function toolPathProblem(conditions, tools) {
152
+ const known = conditions?.path;
153
+ if (!known)
154
+ return undefined;
155
+ for (const tool of tools) {
156
+ const bad = tool.paths?.find((path) => path !== '*' && !known.includes(path));
157
+ if (bad !== undefined) {
158
+ return `Tool ${tool.name} lists path "${bad}", which is not one of ${known.join(', ')}.`; // labels-exempt: developer contract error
159
+ }
160
+ }
161
+ return undefined;
162
+ }
@@ -1,5 +1,19 @@
1
1
  /** One line of wording, or a list of lines read top to bottom: the first that fits is shown. */
2
2
  export type LabelTemplate = string | readonly string[];
3
+ /** `expected: null` is the check "is null". */
4
+ export type Check = {
5
+ path: string;
6
+ negated: boolean;
7
+ expected: string | null;
8
+ };
9
+ export type Line = {
10
+ joined: boolean;
11
+ when: Check[] | 'unreadable';
12
+ text: string;
13
+ };
14
+ /** A line's head, with its text exactly as written after the condition. */
15
+ export declare function splitWhen(raw: string): Line;
16
+ export declare function checkHolds(check: Check, input: unknown): boolean;
3
17
  /** A tool's name as a label shows it: `manage_alert` reads "manage alert". */
4
18
  export declare function toolNameInWords(name: string): string;
5
19
  /**
@@ -13,6 +27,7 @@ export declare function fillActivityLabel(template: LabelTemplate | undefined, v
13
27
  input: unknown;
14
28
  output?: unknown;
15
29
  }): string | undefined;
30
+ export declare function checkProblem(check: Check, input: unknown, reads?: string): string | undefined;
16
31
  export declare function activityLabelProblem(template: LabelTemplate, schemas: {
17
32
  input: unknown;
18
33
  output?: unknown;
@@ -91,16 +91,21 @@ function parseChecks(raw) {
91
91
  }
92
92
  return checks;
93
93
  }
94
- /** `+ when status is archived: archiving {name}` is a joined line, with one check, then its text. */
95
- function parseLine(raw) {
94
+ /** A line's head, with its text exactly as written after the condition. */
95
+ export function splitWhen(raw) {
96
96
  const joined = JOINED.test(raw);
97
- const rest = raw.replace(JOINED, '').trim();
97
+ const rest = raw.replace(JOINED, '').trimStart();
98
98
  if (!/^when(\s|$)/.test(rest))
99
99
  return { joined, when: [], text: rest };
100
100
  const end = rest.search(WHEN_ENDS);
101
101
  if (end < 0)
102
102
  return { joined, when: 'unreadable', text: '' };
103
- return { joined, when: parseChecks(rest.slice(4, end)), text: rest.slice(end + 1).trim() };
103
+ return { joined, when: parseChecks(rest.slice(4, end)), text: rest.slice(end + 1).trimStart() };
104
+ }
105
+ /** `+ when status is archived: archiving {name}` is a joined line, with one check, then its text. */
106
+ function parseLine(raw) {
107
+ const line = splitWhen(raw);
108
+ return { ...line, text: line.text.trim() };
104
109
  }
105
110
  function entriesOf(template) {
106
111
  const raw = typeof template === 'string' ? [template] : template;
@@ -121,7 +126,7 @@ function checkKeys(path) {
121
126
  return route?.side === 'input' ? route.keys : undefined;
122
127
  }
123
128
  // why: "is not" is the plain opposite of "is", so a field the model left out is not any value.
124
- function checkHolds(check, input) {
129
+ export function checkHolds(check, input) {
125
130
  const keys = checkKeys(check.path);
126
131
  if (!keys)
127
132
  return false;
@@ -384,7 +389,7 @@ function oneOf(values) {
384
389
  ? (shown[0] ?? '')
385
390
  : `${shown.slice(0, -1).join(', ')}${shown.length > 2 ? ',' : ''} or ${shown.at(-1)}`;
386
391
  }
387
- function checkProblem(check, input) {
392
+ export function checkProblem(check, input, reads = "this tool's input") {
388
393
  const keys = checkKeys(check.path);
389
394
  if (!keys) {
390
395
  return `A "when" reads what the model sent; "${check.path}" is only there once the call is done.`; // labels-exempt: builder diagnostic
@@ -393,7 +398,7 @@ function checkProblem(check, input) {
393
398
  if (found.holds === 'missing') {
394
399
  const fields = inputFields(input).slice(0, 4);
395
400
  const tryThese = fields.length ? ` Try ${oneOf(fields)}.` : ''; // labels-exempt: builder diagnostic
396
- return `"${check.path}" in the "when" is not a field of this tool's input.${tryThese}`; // labels-exempt: builder diagnostic
401
+ return `"${check.path}" in the "when" is not a field of ${reads}.${tryThese}`; // labels-exempt: builder diagnostic
397
402
  }
398
403
  if (found.holds === 'group') {
399
404
  return `"${check.path}" in the "when" is a list or group; a "when" compares text, a number, or true or false.`; // labels-exempt: builder diagnostic
@@ -12,7 +12,7 @@ class AgentCallFailed extends Error {
12
12
  this.failure = failure;
13
13
  }
14
14
  }
15
- /** The agents an agent tool can run: each has a turn that takes text. */
15
+ /** The agents an agent tool can run: each has a turn that takes text, which a transcription turn does not. */
16
16
  const AGENT_TOOL_TYPES = new Set(['text', 'image', 'speech']);
17
17
  // why: Bytes that are not base64, or a text of only spaces, would be refused inside the called turn as the host's error and end the caller's turn; checked here, the model reads a failed call.
18
18
  const textInput = z.string().regex(/\S/);
@@ -0,0 +1,16 @@
1
+ import { z } from 'zod';
2
+ import type { StepCall } from '../stages.js';
3
+ /** `input` with the model's `after` field. A tool's own `after` is refused, never replaced. */
4
+ export declare function withCallOrder<TIn>(name: string, input: z.ZodType<TIn>): z.ZodType<TIn>;
5
+ /** The call's input without `after`, and the tool names `after` held. */
6
+ export declare function splitCallOrder(tool: {
7
+ after?: boolean;
8
+ }, input: unknown): {
9
+ input: unknown;
10
+ names: readonly string[];
11
+ };
12
+ /**
13
+ * The ids of each named tool's other calls in the step; a name with none stays, to be refused. A
14
+ * call outside a step, as in a live session, has nothing to wait on.
15
+ */
16
+ export declare function stepCallIds(names: readonly string[], callId: string, stepCalls: readonly StepCall[] | undefined): string[];
@@ -0,0 +1,48 @@
1
+ import { z } from 'zod';
2
+ import { TheoremError } from '../../guardrails/error.js';
3
+ import { labelText } from '../../guardrails/labels.js';
4
+ const FIELD = 'after';
5
+ function orderField() {
6
+ return z.array(z.string()).optional().describe(labelText('tool.after_field'));
7
+ }
8
+ /** `input` with the model's `after` field. A tool's own `after` is refused, never replaced. */
9
+ export function withCallOrder(name, input) {
10
+ const ordered = (schema) => {
11
+ if (schema instanceof z.ZodObject) {
12
+ if (FIELD in schema.shape) {
13
+ throw new TheoremError('config', `Tool '${name}' sets after, and its input already has a field of that name`);
14
+ }
15
+ return schema.safeExtend({ [FIELD]: orderField() });
16
+ }
17
+ if (schema instanceof z.ZodDiscriminatedUnion) {
18
+ const options = schema.options.map(ordered);
19
+ return z.discriminatedUnion(schema.def.discriminator, options);
20
+ }
21
+ if (schema instanceof z.ZodUnion) {
22
+ return z.union(schema.options.map(ordered));
23
+ }
24
+ throw new TheoremError('config', `Tool '${name}' sets after, which needs an object input or a union of objects`);
25
+ };
26
+ return ordered(input);
27
+ }
28
+ /** The call's input without `after`, and the tool names `after` held. */
29
+ export function splitCallOrder(tool, input) {
30
+ if (!tool.after || typeof input !== 'object' || input === null)
31
+ return { input, names: [] };
32
+ const { [FIELD]: names, ...rest } = input;
33
+ return { input: rest, names: names ?? [] };
34
+ }
35
+ /**
36
+ * The ids of each named tool's other calls in the step; a name with none stays, to be refused. A
37
+ * call outside a step, as in a live session, has nothing to wait on.
38
+ */
39
+ export function stepCallIds(names, callId, stepCalls) {
40
+ if (!stepCalls)
41
+ return [];
42
+ return names.flatMap((name) => {
43
+ const ids = stepCalls
44
+ .filter((call) => call.tool === name && call.callId !== callId)
45
+ .map((call) => call.callId);
46
+ return ids.length > 0 ? ids : [name];
47
+ });
48
+ }
@@ -2,6 +2,7 @@ import { TheoremError } from '../../guardrails/error.js';
2
2
  import { profileInputs } from '../registry/catalog.js';
3
3
  import { activityLabelProblem } from './activity-label.js';
4
4
  import { agentToolInputFor, agentToolOutput, agentToolProfile, normalizeAgent } from './agent.js';
5
+ import { withCallOrder } from './call-order.js';
5
6
  import { createMcpSessionCache } from './mcp-sessions.js';
6
7
  import { pageAnswerHandler } from './page-answer.js';
7
8
  import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolSchema, } from './schema.js';
@@ -134,17 +135,19 @@ function normalizeToolDefinition(def, findProfile, findTool) {
134
135
  if (def.type === 'agent') {
135
136
  const profile = agentToolProfile(def, findProfile, findTool);
136
137
  const inputs = profileInputs(profile);
137
- const input = agentToolInputFor({ type: profile.type, ...(inputs ? { inputs } : {}) }, def);
138
+ const taken = agentToolInputFor({ type: profile.type, ...(inputs ? { inputs } : {}) }, def);
139
+ const input = def.after ? withCallOrder(def.name, taken) : taken;
138
140
  const schemas = schemasFromZod({ ...def, input, output: agentToolOutput });
139
141
  return normalizeAgent(def, input, schemas);
140
142
  }
141
- if (def.type === 'http') {
142
- return normalizeHttp(def);
143
+ const ordered = def.after ? { ...def, input: withCallOrder(def.name, def.input) } : def;
144
+ if (ordered.type === 'http') {
145
+ return normalizeHttp(ordered);
143
146
  }
144
- if (def.type === 'mcp') {
145
- return normalizeMcp(def);
147
+ if (ordered.type === 'mcp') {
148
+ return normalizeMcp(ordered);
146
149
  }
147
- return normalizeFunction(def);
150
+ return normalizeFunction(ordered);
148
151
  }
149
152
  /**
150
153
  * Registration is not synchronized: register a scope's tools before its turns or invokes run.
@@ -1,4 +1,5 @@
1
1
  import { TheoremError } from '../../guardrails/error.js';
2
+ import { toolPathProblem } from '../system-lines.js';
2
3
  import { isRecord } from '../util/record.js';
3
4
  /** Callable by the host: registered, and not a provider-run builtin. */
4
5
  function isExecutable(tools, id) {
@@ -119,7 +120,17 @@ export function initialBuiltins(tools, profile, gated) {
119
120
  return tool?.type === 'builtin' && (profile.type === 'live' || tool.loadTier === 'T0');
120
121
  }));
121
122
  }
123
+ // why: a tool can register after its profile, so the two lists of paths can only be compared here.
124
+ function assertToolPathsDeclared(tools, profile) {
125
+ if (profile.type !== 'text' && profile.type !== 'image' && profile.type !== 'live')
126
+ return;
127
+ const allowed = profileToolAllow(profile).flatMap((id) => tools.get(id) ?? []);
128
+ const problem = toolPathProblem(profile.identity.conditions, allowed);
129
+ if (problem)
130
+ throw new TheoremError('config', `Profile ${profile.id}: ${problem}`); // labels-exempt: developer contract error
131
+ }
122
132
  export function resolveTurnTools(tools, profile, req, modelId) {
133
+ assertToolPathsDeclared(tools, profile);
123
134
  const customAllowed = resolveAllowedCustomToolIds(tools, profile, req);
124
135
  const modelBuiltins = profile.type === 'host' ||
125
136
  profile.type === 'decision' ||
@@ -72,7 +72,6 @@ export type PostToolStageOutcome = {
72
72
  };
73
73
  labelFailed?: true;
74
74
  };
75
- /** Tool `preTool` → host `pre_tool` → mutate re-parse. */
76
75
  export declare function runPreToolPipeline(args: {
77
76
  tool: {
78
77
  name: string;
@@ -81,6 +80,7 @@ export declare function runPreToolPipeline(args: {
81
80
  };
82
81
  access: ToolAccess;
83
82
  labels?: ToolLabels;
83
+ after?: boolean;
84
84
  preTool?: (input: never, ctx: ToolContext) => StageResult | undefined | Promise<StageResult | undefined>;
85
85
  };
86
86
  input: unknown;
@@ -1,6 +1,7 @@
1
1
  import { labelText } from '../../guardrails/labels.js';
2
2
  import { jsonObjectSchema } from '../json.js';
3
3
  import { runStage, stageEventFields, } from '../stages.js';
4
+ import { splitCallOrder, stepCallIds } from './call-order.js';
4
5
  import { toolEvent } from './events.js';
5
6
  import { operationWireValue } from './operation.js';
6
7
  import { gateDetails, isGateResumeGranted } from './permission.js';
@@ -17,79 +18,80 @@ function defaultToolStageSupport(ctx) {
17
18
  };
18
19
  }
19
20
  /** Tool `preTool` → host `pre_tool` → mutate re-parse. */
21
+ /** What a resume already granted, so `pre_tool` asks it no second time. */
22
+ function resumeApproval(resume) {
23
+ const granted = isGateResumeGranted(resume);
24
+ // why: Permission and sign-in gates come before `pre_tool`, so granting one answers nothing it asked.
25
+ const confirmed = granted && resume?.gateKind !== 'permission' && resume?.gateKind !== 'auth';
26
+ return {
27
+ confirmed,
28
+ // why: An approval skips the tool's own check it already passed — unless the user edited the arguments.
29
+ approvedAsIs: confirmed && resume?.edited === undefined,
30
+ approved: granted && resume?.gateKind !== 'auth',
31
+ };
32
+ }
33
+ function invalidAfterMutate(error, ctx) {
34
+ return {
35
+ ok: false,
36
+ kind: 'failed',
37
+ failure: {
38
+ code: 'invalid_input',
39
+ kind: 'bad_response',
40
+ message: labelText('tool.input_invalid_after_mutate', {}, ctx.profile.labels),
41
+ details: error.flatten(),
42
+ },
43
+ };
44
+ }
20
45
  export async function* runPreToolPipeline(args) {
21
46
  const { tool, ctx, base, stages } = args;
47
+ const { input, names } = splitCallOrder(tool, args.input);
48
+ // why: A resumed call's step has ended, so every call it waited for has settled.
49
+ const after = ctx.resume ? [] : stepCallIds(names, base.callId, stages?.stepCalls);
22
50
  let toolPreTool;
23
- // why: Permission and sign-in gates come before `pre_tool`, so granting one answers nothing it asked.
24
- const confirmed = isGateResumeGranted(ctx.resume) &&
25
- ctx.resume?.gateKind !== 'permission' &&
26
- ctx.resume?.gateKind !== 'auth';
27
- // why: An approval skips the tool's own check it already passed — unless the user edited the arguments.
28
- const approvedAsIs = confirmed && ctx.resume?.edited === undefined;
29
- const approved = isGateResumeGranted(ctx.resume) && ctx.resume?.gateKind !== 'auth';
51
+ const { confirmed, approved, approvedAsIs } = resumeApproval(ctx.resume);
30
52
  if (tool.preTool && !approvedAsIs) {
31
- toolPreTool = (await tool.preTool(args.input, ctx)) ?? undefined;
53
+ toolPreTool = (await tool.preTool(input, ctx)) ?? undefined;
32
54
  }
33
- if (!stages && toolPreTool === undefined) {
34
- return { ok: true, input: args.input };
55
+ if (!stages && toolPreTool === undefined && after.length === 0) {
56
+ return { ok: true, input };
35
57
  }
36
58
  const pre = yield* runPreToolStages({
37
59
  stages: stages ?? defaultToolStageSupport(ctx),
38
60
  toolName: tool.name,
39
61
  callId: base.callId,
40
- input: args.input,
62
+ input,
41
63
  toolPreTool,
42
- details: gateDetails(tool, args.input),
64
+ details: gateDetails(tool, input),
43
65
  confirmed,
44
66
  approved,
45
67
  });
46
68
  if (!pre.ok) {
47
- if (pre.kind === 'gated') {
48
- if ('input' in pre) {
49
- const candidate = pre.input;
50
- const parsed = tool.input.safeParse(plainToolInput(candidate));
51
- if (!parsed.success) {
52
- return {
53
- ok: false,
54
- kind: 'failed',
55
- failure: {
56
- code: 'invalid_input',
57
- kind: 'bad_response',
58
- message: labelText('tool.input_invalid_after_mutate', {}, ctx.profile.labels),
59
- details: parsed.error.flatten(),
60
- },
61
- };
62
- }
63
- pre.gate = {
64
- ...pre.gate,
65
- ...gateDetails(tool, parsed.data),
66
- preparedArguments: jsonObjectSchema.parse(operationWireValue(plainToolInput(candidate))),
67
- };
68
- }
69
- yield stageEventFields('pre_tool', {
70
- callId: base.callId,
71
- toolName: tool.name,
72
- callNotStarted: true,
73
- gate: pre.gate,
74
- });
75
- yield toolEvent(base, { phase: 'gate', gate: pre.gate });
69
+ if (pre.kind !== 'gated')
70
+ return pre;
71
+ if ('input' in pre) {
72
+ const candidate = pre.input;
73
+ const parsed = tool.input.safeParse(plainToolInput(candidate));
74
+ if (!parsed.success)
75
+ return invalidAfterMutate(parsed.error, ctx);
76
+ pre.gate = {
77
+ ...pre.gate,
78
+ ...gateDetails(tool, parsed.data),
79
+ preparedArguments: jsonObjectSchema.parse(operationWireValue(plainToolInput(candidate))),
80
+ };
76
81
  }
82
+ yield stageEventFields('pre_tool', {
83
+ callId: base.callId,
84
+ toolName: tool.name,
85
+ callNotStarted: true,
86
+ gate: pre.gate,
87
+ });
88
+ yield toolEvent(base, { phase: 'gate', gate: pre.gate });
77
89
  return pre;
78
90
  }
79
91
  const reparsed = pre.mutated ? tool.input.safeParse(plainToolInput(pre.input)) : undefined;
80
- if (reparsed && !reparsed.success) {
81
- return {
82
- ok: false,
83
- kind: 'failed',
84
- failure: {
85
- code: 'invalid_input',
86
- kind: 'bad_response',
87
- message: labelText('tool.input_invalid_after_mutate', {}, args.ctx.profile.labels),
88
- details: reparsed.error.flatten(),
89
- },
90
- };
91
- }
92
- const waitFailure = await waitForStepCalls(stages, base.callId, tool.name, pre.waitFor, ctx.profile.labels);
92
+ if (reparsed && !reparsed.success)
93
+ return invalidAfterMutate(reparsed.error, ctx);
94
+ const waitFailure = await waitForStepCalls(stages, base.callId, tool.name, [...(pre.waitFor ?? []), ...after], ctx.profile.labels);
93
95
  if (waitFailure)
94
96
  return { ok: false, kind: 'failed', failure: waitFailure };
95
97
  return { ok: true, input: reparsed ? reparsed.data : pre.input };
@@ -145,7 +147,7 @@ async function* runPreToolStages(args) {
145
147
  }
146
148
  /** Holds the call for the calls its `pre_tool` named; a wait that cannot end fails the call. */
147
149
  async function waitForStepCalls(stages, callId, toolName, waitFor, labels) {
148
- if (!waitFor)
150
+ if (waitFor.length === 0)
149
151
  return undefined;
150
152
  const outcome = stages?.wait
151
153
  ? await stages.wait(callId, waitFor)
@@ -155,6 +155,8 @@ export interface ToolHostHooks<TIn = unknown> {
155
155
  /** Runs before the host's `pre_tool` `onStage`. */
156
156
  preTool?: (input: TIn, ctx: ToolContext) => import('../stages.js').StageResult | undefined | Promise<import('../stages.js').StageResult | undefined>;
157
157
  exposeToModel?: boolean;
158
+ /** The model gets an `after` field: the tools in the same step that must settle before this call starts. */
159
+ after?: boolean;
158
160
  }
159
161
  export interface ToolOutputHooks<TOut = unknown> {
160
162
  /** A source that fails `sourceSchema`, or a throw, is a `sources_invalid` warning and is not cited. */
@@ -316,6 +318,7 @@ export interface AgentToolDef extends ToolBase {
316
318
  /** Channels the profile takes that the calling model can't fill; only `onAgentCall` sends them. */
317
319
  hostOnly?: AgentToolChannel[];
318
320
  preTool?: ToolHostHooks<AgentToolInput>['preTool'];
321
+ after?: ToolHostHooks<AgentToolInput>['after'];
319
322
  exposeToModel?: boolean;
320
323
  }
321
324
  export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
@@ -375,6 +375,12 @@ export type SystemPart = string | PrivateSystemPart;
375
375
  * part is `{ private }`, the plain strings beside it are shareable.
376
376
  */
377
377
  export type SystemPrompt = string | readonly SystemPart[];
378
+ /** One line of a profile's prompt: text, or parts kept together. A leading `when` decides it. */
379
+ export type SystemLine = string | readonly SystemPart[];
380
+ /** A profile's prompt: a string, or lines. Every line that fits is sent, a blank line apart. */
381
+ export type ProfileSystem = string | readonly SystemLine[];
382
+ /** The facts a host states on each turn, by name, each with the values it can take. */
383
+ export type ProfileConditions = Readonly<Record<string, readonly string[]>>;
378
384
  /** A stretch of the system prompt as sent, and whether a reply may repeat it. */
379
385
  export interface SystemPiece {
380
386
  text: string;
@@ -383,8 +389,9 @@ export interface SystemPiece {
383
389
  /** A profile's handle and system prompt. */
384
390
  export interface ProfileIdentity {
385
391
  handle: string;
386
- system?: SystemPrompt;
387
- systemByRole?: Record<string, SystemPrompt>;
392
+ /** The facts this agent's turns state, by name, with the values each can take. */
393
+ conditions?: ProfileConditions;
394
+ system?: ProfileSystem;
388
395
  }
389
396
  /** The fields every profile type shares. */
390
397
  export interface ProfileCommon {
@@ -631,6 +638,21 @@ export interface SpeechProfile extends Omit<ProfileCommon, 'identity'> {
631
638
  speech: ProfileSpeechSpec;
632
639
  turnBehaviour?: MediaTurnBehaviourSpec;
633
640
  }
641
+ /** A transcription profile's inputs: voice clips within byte limits, and no text. */
642
+ export type TranscriptionInputsSpec = Required<Pick<ProfileInputsSpec, 'voice'>> & Pick<ProfileInputsSpec, 'maxFiles' | 'maxBytes' | 'maxTurnBytes' | 'limitsByMime'>;
643
+ /**
644
+ * Speech to text: a voice clip in, what was said out as the turn's text. No tools, no system
645
+ * prompt, and no canary, because the model follows no instruction and has nothing of the profile's to leak.
646
+ */
647
+ export interface TranscriptionProfile extends Omit<ProfileCommon, 'identity' | 'outputs' | 'maxSteps'> {
648
+ type: 'transcription';
649
+ identity: Pick<ProfileIdentity, 'handle'>;
650
+ inputs: TranscriptionInputsSpec & {
651
+ text: false;
652
+ };
653
+ outputs?: undefined;
654
+ maxSteps?: undefined;
655
+ }
634
656
  /** A profile that holds a live audio session. */
635
657
  export interface LiveProfile extends Omit<ProfileCommon, 'outputs'> {
636
658
  type: 'live';
@@ -656,7 +678,7 @@ export interface HostProfile {
656
678
  labels?: LabelOverrides;
657
679
  }
658
680
  /** The contract that defines an agent’s capabilities and the rules for its interactions. Its type determines which settings it accepts. */
659
- export type Profile = TextProfile | ImageProfile | SpeechProfile | LiveProfile | DecisionProfile | EmbeddingProfile | HostProfile;
681
+ export type Profile = TextProfile | ImageProfile | SpeechProfile | TranscriptionProfile | LiveProfile | DecisionProfile | EmbeddingProfile | HostProfile;
660
682
  /** Profiles that run a model turn — every type except `host` and `decision` (which runs through `runDecision`). */
661
683
  export type ModelProfile = Exclude<Profile, HostProfile | DecisionProfile | EmbeddingProfile>;
662
684
  /** The image a profile asks the model to return. */
@@ -699,7 +721,6 @@ export interface TurnRepairRequest {
699
721
  /** What the user sent for a turn: text, slots, attachments, voice, and history. */
700
722
  export interface TurnInput {
701
723
  text?: string;
702
- role?: string;
703
724
  slots?: Record<string, string>;
704
725
  /** What the page or the host wants the model to know, by sender; the profile's `inputs.context` allows it. */
705
726
  context?: TurnContext;
@@ -763,6 +784,8 @@ export interface TurnRequest {
763
784
  sessionPermissions?: string[];
764
785
  /** Host channel/path for catalog `paths` filtering. */
765
786
  path?: string;
787
+ /** This turn's facts, one value for each of `profile.identity.conditions` but `path`. */
788
+ conditions?: Readonly<Record<string, string>>;
766
789
  /** Host-owned metadata preserved for traces; the kernel does not interpret it. */
767
790
  metadata?: Record<string, unknown>;
768
791
  /**
@@ -893,6 +916,8 @@ export interface ResolvedGeneration extends ProviderGenerationConfig {
893
916
  canary: string;
894
917
  /** Snapshotted synchronously before any async work; the runner binds the canary on top. */
895
918
  resolvedSystem: readonly SystemPiece[];
919
+ /** Which of the profile's prompt lines fit this turn, by number from 1. */
920
+ systemLines: readonly number[];
896
921
  /** `TurnRequest.host`, carried to tool contexts only. Never sent to providers or traces. */
897
922
  host?: unknown;
898
923
  }
@@ -935,6 +960,8 @@ export interface SessionRequest {
935
960
  /** As `TurnRequest.builtInArgs`. */
936
961
  builtInArgs?: BuiltInArgs;
937
962
  path?: string;
963
+ /** As `TurnRequest.conditions`. */
964
+ conditions?: Readonly<Record<string, string>>;
938
965
  sessionPermissions?: string[];
939
966
  history?: TurnHistoryMessage[];
940
967
  /** The value chosen for each of the profile's `inputs.slots`. */