@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.
- package/README.md +4 -3
- package/esm/mod.d.ts +3 -1
- package/esm/mod.js +2 -0
- package/esm/src/cli/commands/bench.js +4 -10
- package/esm/src/cli/commands/profile.js +4 -1
- package/esm/src/guardrails/labels.d.ts +1 -1
- package/esm/src/guardrails/labels.js +3 -0
- package/esm/src/interface/blocks.js +19 -0
- package/esm/src/interface/from-profile.d.ts +2 -2
- package/esm/src/interface/from-profile.js +7 -0
- package/esm/src/interface/mod.d.ts +1 -1
- package/esm/src/interface/profile-interface.js +14 -4
- package/esm/src/interface/types.d.ts +6 -4
- package/esm/src/kernel/api-catalog.js +5 -5
- package/esm/src/kernel/auth/oauth.js +3 -1
- package/esm/src/kernel/engine/runner/mod.js +1 -0
- package/esm/src/kernel/engine/session/mod.js +1 -0
- package/esm/src/kernel/engine/session/session-trace.js +1 -0
- package/esm/src/kernel/mod.d.ts +3 -1
- package/esm/src/kernel/mod.js +2 -0
- package/esm/src/kernel/profile-presence.js +1 -0
- package/esm/src/kernel/profile-scope.js +23 -21
- package/esm/src/kernel/protocols/protocol.d.ts +1 -1
- package/esm/src/kernel/protocols/protocol.js +1 -0
- package/esm/src/kernel/registry/catalog.js +4 -1
- package/esm/src/kernel/registry/ingress.d.ts +3 -1
- package/esm/src/kernel/registry/ingress.js +12 -1
- package/esm/src/kernel/registry/profile-outputs.js +2 -1
- package/esm/src/kernel/registry/profiles.d.ts +12 -2
- package/esm/src/kernel/registry/profiles.js +37 -7
- package/esm/src/kernel/registry/resolve.js +9 -5
- package/esm/src/kernel/registry/system-prompt.d.ts +6 -1
- package/esm/src/kernel/registry/system-prompt.js +20 -13
- package/esm/src/kernel/schema.d.ts +1 -1
- package/esm/src/kernel/schema.js +12 -8
- package/esm/src/kernel/system-lines.d.ts +22 -0
- package/esm/src/kernel/system-lines.js +162 -0
- package/esm/src/kernel/tools/activity-label.d.ts +15 -0
- package/esm/src/kernel/tools/activity-label.js +12 -7
- package/esm/src/kernel/tools/agent.js +1 -1
- package/esm/src/kernel/tools/call-order.d.ts +16 -0
- package/esm/src/kernel/tools/call-order.js +48 -0
- package/esm/src/kernel/tools/registry.js +9 -6
- package/esm/src/kernel/tools/resolve.js +11 -0
- package/esm/src/kernel/tools/stage-run.d.ts +1 -1
- package/esm/src/kernel/tools/stage-run.js +57 -55
- package/esm/src/kernel/tools/types.d.ts +3 -0
- package/esm/src/kernel/types.d.ts +31 -4
- package/esm/src/observability/trace-catalog.js +3 -0
- package/esm/src/providers/google/interactions/steps.js +14 -3
- package/esm/src/providers/mod.d.ts +2 -0
- package/esm/src/providers/mod.js +1 -0
- package/esm/src/providers/openrouter/protocol.d.ts +26 -0
- package/esm/src/providers/openrouter/protocol.js +58 -2
- package/esm/src/providers/openrouter/provider.d.ts +1 -1
- package/esm/src/providers/openrouter/provider.js +3 -1
- package/esm/src/providers/openrouter/transcriptions-protocol.d.ts +10 -0
- package/esm/src/providers/openrouter/transcriptions-protocol.js +87 -0
- package/package.json +1 -1
- package/esm/src/kernel/registry/system-role.d.ts +0 -3
- 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
|
-
/**
|
|
95
|
-
function
|
|
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, '').
|
|
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).
|
|
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
|
|
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
|
|
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
|
-
|
|
142
|
-
|
|
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 (
|
|
145
|
-
return normalizeMcp(
|
|
147
|
+
if (ordered.type === 'mcp') {
|
|
148
|
+
return normalizeMcp(ordered);
|
|
146
149
|
}
|
|
147
|
-
return normalizeFunction(
|
|
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
|
-
|
|
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(
|
|
53
|
+
toolPreTool = (await tool.preTool(input, ctx)) ?? undefined;
|
|
32
54
|
}
|
|
33
|
-
if (!stages && toolPreTool === undefined) {
|
|
34
|
-
return { ok: true, 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
|
|
62
|
+
input,
|
|
41
63
|
toolPreTool,
|
|
42
|
-
details: gateDetails(tool,
|
|
64
|
+
details: gateDetails(tool, input),
|
|
43
65
|
confirmed,
|
|
44
66
|
approved,
|
|
45
67
|
});
|
|
46
68
|
if (!pre.ok) {
|
|
47
|
-
if (pre.kind
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
387
|
-
|
|
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`. */
|