@theoremjs/agents 0.3.4-next.693.g4ab1526 → 0.3.4-next.715.geef22fd
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 +1 -1
- package/esm/mod.d.ts +3 -2
- package/esm/mod.js +1 -1
- package/esm/src/guardrails/labels.d.ts +1 -1
- package/esm/src/guardrails/labels.js +6 -0
- package/esm/src/interface/history.d.ts +2 -2
- package/esm/src/interface/history.js +7 -4
- package/esm/src/interface/mod.d.ts +1 -1
- package/esm/src/interface/mod.js +1 -1
- package/esm/src/interface/tool-calls.d.ts +3 -3
- package/esm/src/interface/tool-calls.js +5 -8
- package/esm/src/interface/tool-invoke.d.ts +11 -1
- package/esm/src/interface/tool-invoke.js +13 -1
- package/esm/src/interface/types.d.ts +1 -1
- package/esm/src/kernel/api-catalog.js +12 -0
- package/esm/src/kernel/engine/background.d.ts +7 -0
- package/esm/src/kernel/engine/background.js +18 -0
- package/esm/src/kernel/engine/runner/gates.js +4 -3
- package/esm/src/kernel/engine/runner/mod.js +24 -1
- package/esm/src/kernel/engine/runner/state.d.ts +4 -0
- package/esm/src/kernel/engine/runner/state.js +1 -0
- package/esm/src/kernel/engine/runner/step-order.d.ts +8 -0
- package/esm/src/kernel/engine/runner/step-order.js +1 -1
- package/esm/src/kernel/engine/runner/steps.js +5 -0
- package/esm/src/kernel/engine/session/mod.d.ts +2 -0
- package/esm/src/kernel/engine/session/mod.js +19 -2
- package/esm/src/kernel/mod.d.ts +3 -2
- package/esm/src/kernel/mod.js +1 -1
- package/esm/src/kernel/schema.js +12 -0
- package/esm/src/kernel/tools/background.d.ts +81 -0
- package/esm/src/kernel/tools/background.js +70 -0
- package/esm/src/kernel/tools/call-order.d.ts +3 -1
- package/esm/src/kernel/tools/call-order.js +10 -6
- package/esm/src/kernel/tools/coordinate.d.ts +8 -1
- package/esm/src/kernel/tools/coordinate.js +274 -34
- package/esm/src/kernel/tools/execute.d.ts +2 -0
- package/esm/src/kernel/tools/execute.js +17 -4
- package/esm/src/kernel/tools/invoke.js +40 -13
- package/esm/src/kernel/tools/memory-execution.js +10 -1
- package/esm/src/kernel/tools/operation.d.ts +21 -0
- package/esm/src/kernel/tools/operation.js +19 -10
- package/esm/src/kernel/tools/registry.js +20 -1
- package/esm/src/kernel/tools/resolve.d.ts +4 -2
- package/esm/src/kernel/tools/resolve.js +23 -7
- package/esm/src/kernel/tools/run.d.ts +2 -2
- package/esm/src/kernel/tools/run.js +4 -1
- package/esm/src/kernel/tools/stage-run.d.ts +2 -0
- package/esm/src/kernel/tools/stage-run.js +1 -0
- package/esm/src/kernel/tools/types.d.ts +7 -0
- package/esm/src/kernel/turn-events.d.ts +10 -1
- package/esm/src/kernel/turn-events.js +3 -0
- package/esm/src/kernel/types.d.ts +13 -0
- package/esm/src/providers/open-ai/protocol.js +8 -4
- package/package.json +1 -1
|
@@ -6,6 +6,7 @@ import { type ToolCallEnd } from '../engine/tool-trace.js';
|
|
|
6
6
|
import type { InjectUnit } from '../stages.js';
|
|
7
7
|
import type { InteractionPart, Profile, TurnEvent } from '../types.js';
|
|
8
8
|
import { type AgentCaller } from './agent.js';
|
|
9
|
+
import { type ToolBackgroundSupport } from './background.js';
|
|
9
10
|
import { startToolExecution, type ToolCallBase } from './events.js';
|
|
10
11
|
import type { ToolExecutionCoordinator, ToolOperationClaim, ToolOperationOutcome } from './operation.js';
|
|
11
12
|
import type { ToolRegistry } from './registry.js';
|
|
@@ -61,6 +62,7 @@ export declare function authorizeToolReplay(args: {
|
|
|
61
62
|
}): void;
|
|
62
63
|
interface RegisteredToolCall {
|
|
63
64
|
execution?: ToolExecutionCoordinator;
|
|
65
|
+
background?: ToolBackgroundSupport;
|
|
64
66
|
invocation?: unknown;
|
|
65
67
|
onDispatch?: () => void;
|
|
66
68
|
beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>;
|
|
@@ -11,6 +11,7 @@ import { isAwaitingUserInput } from '../turn-events.js';
|
|
|
11
11
|
import { isRecord } from '../util/record.js';
|
|
12
12
|
import { fillActivityLabel } from './activity-label.js';
|
|
13
13
|
import { AgentCallFailed, agentToolOrigin } from './agent.js';
|
|
14
|
+
import { planDetach, splitBackground } from './background.js';
|
|
14
15
|
import { coordinateTool } from './coordinate.js';
|
|
15
16
|
import { dispatchToolBody, failedActivity, failedActivityOf, failureEvent, messageOf, networkBlocked, networkBlockedEvent, requestChecks, sourceEvents, startToolExecution, toolCallArguments, toolEvent, } from './events.js';
|
|
16
17
|
import { HandlerEvents } from './handler-events.js';
|
|
@@ -847,8 +848,16 @@ export async function* executeRegisteredTool(args) {
|
|
|
847
848
|
...args,
|
|
848
849
|
ctx: { ...args.ctx, operationId: args.ctx.operationId ?? crypto.randomUUID() },
|
|
849
850
|
};
|
|
851
|
+
const operationId = args.ctx.operationId ?? crypto.randomUUID();
|
|
852
|
+
const detach = planDetach({
|
|
853
|
+
tool: args.tools.get(args.name),
|
|
854
|
+
input: args.input,
|
|
855
|
+
support: args.background,
|
|
856
|
+
base: { name: args.name, callId: args.callId, operationId },
|
|
857
|
+
labels: args.profile.labels,
|
|
858
|
+
});
|
|
850
859
|
return yield* coordinateTool(args.execution, {
|
|
851
|
-
operationId
|
|
860
|
+
operationId,
|
|
852
861
|
callId: args.callId,
|
|
853
862
|
profileId: args.profile.id,
|
|
854
863
|
toolId: args.name,
|
|
@@ -857,8 +866,11 @@ export async function* executeRegisteredTool(args) {
|
|
|
857
866
|
resume: args.ctx.resume,
|
|
858
867
|
snapshot: args.snapshot,
|
|
859
868
|
context: args.invocation,
|
|
860
|
-
}, args.ctx.signal, (beginBody) => executeTracedTool({
|
|
869
|
+
}, args.ctx.signal, (beginBody, hooks) => executeTracedTool({
|
|
861
870
|
...args,
|
|
871
|
+
...(detach ? { openSpan: detach.trace.open } : {}),
|
|
872
|
+
ctx: { ...args.ctx, signal: hooks.signal },
|
|
873
|
+
...(args.stages ? { stages: { ...args.stages, ...hooks } } : {}),
|
|
862
874
|
beginBody: async (input) => {
|
|
863
875
|
const claim = (await beginBody?.(input)) ?? (await args.beginBody?.(input));
|
|
864
876
|
args.onDispatch?.();
|
|
@@ -871,7 +883,7 @@ export async function* executeRegisteredTool(args) {
|
|
|
871
883
|
name: args.name,
|
|
872
884
|
resume: args.ctx.resume,
|
|
873
885
|
snapshot: args.snapshot,
|
|
874
|
-
}));
|
|
886
|
+
}), detach);
|
|
875
887
|
}
|
|
876
888
|
async function* executeTracedTool(args) {
|
|
877
889
|
const tool = args.tools.get(args.name);
|
|
@@ -916,7 +928,8 @@ async function* executeTracedTool(args) {
|
|
|
916
928
|
}
|
|
917
929
|
}
|
|
918
930
|
async function* runRegisteredTool(args, tool) {
|
|
919
|
-
const { profile, name,
|
|
931
|
+
const { profile, name, callId, ctx, snapshot, stages } = args;
|
|
932
|
+
const { input } = splitBackground(tool?.type === 'builtin' ? undefined : tool, args.input);
|
|
920
933
|
const safeInput = plainToolInput(input);
|
|
921
934
|
const operationId = ctx.operationId ?? crypto.randomUUID();
|
|
922
935
|
const base = {
|
|
@@ -4,12 +4,14 @@ import { resolveTraceWriter } from '../../observability/policy.js';
|
|
|
4
4
|
import { writeTrace } from '../../observability/trace.js';
|
|
5
5
|
import { buildRecord } from '../../observability/trace-record.js';
|
|
6
6
|
import { startTrace, } from '../../observability/trace-span.js';
|
|
7
|
+
import { detachedTrace } from '../engine/background.js';
|
|
7
8
|
import { invokeAgentCaller } from '../engine/runner/mod.js';
|
|
8
9
|
import { inStep, runSideBySide, stepOrder } from '../engine/runner/step-order.js';
|
|
9
10
|
import { startToolTrace, toolSpanName } from '../engine/tool-trace.js';
|
|
10
11
|
import { endThrownSpan, optional, traceLinks } from '../engine/turn-trace.js';
|
|
11
12
|
import { pickModel } from '../registry/resolve.js';
|
|
12
13
|
import { turnDoneOf } from '../turn-events.js';
|
|
14
|
+
import { assertBackgroundCoordinator, planDetach, } from './background.js';
|
|
13
15
|
import { coordinateTool } from './coordinate.js';
|
|
14
16
|
import { failedActivity, failureEvent, newCallId, toolCallArguments, toolCallRequestEvent, } from './events.js';
|
|
15
17
|
import { authorizeToolReplay, executeRegisteredTool, } from './execute.js';
|
|
@@ -57,9 +59,24 @@ async function* invokeInTrace(registry, request, spanName, sinkOverride, run) {
|
|
|
57
59
|
const canaries = [];
|
|
58
60
|
try {
|
|
59
61
|
const labels = known?.labels;
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
62
|
+
// invariant: A match is the caught text itself; it leaves only when the profile asks for it.
|
|
63
|
+
const project = (event) => projectGuardrailTurnEvent(withPublicLabels(event, labels), policy.include.guardrailMatchPreview);
|
|
64
|
+
const { background: service } = request;
|
|
65
|
+
const background = service && {
|
|
66
|
+
service,
|
|
67
|
+
project,
|
|
68
|
+
openTrace: () => detachedTrace({
|
|
69
|
+
traceparent: tree.root.traceparent(),
|
|
70
|
+
write: (spans) => writeTrace(sink, buildRecord({
|
|
71
|
+
spans,
|
|
72
|
+
policy,
|
|
73
|
+
canaries,
|
|
74
|
+
...(request.metadata ? { metadata: request.metadata } : {}),
|
|
75
|
+
}), policy),
|
|
76
|
+
}),
|
|
77
|
+
};
|
|
78
|
+
for await (const event of run.events(tree, canaries, background)) {
|
|
79
|
+
yield project(event);
|
|
63
80
|
}
|
|
64
81
|
run.ended?.(tree);
|
|
65
82
|
}
|
|
@@ -86,6 +103,7 @@ function failCallBeforeTool(openSpan, invoke, callId) {
|
|
|
86
103
|
}
|
|
87
104
|
/** The profile an invoke runs under, and its own copy of the tool snapshot. */
|
|
88
105
|
async function invokeSnapshot(registry, request) {
|
|
106
|
+
assertBackgroundCoordinator(request.background, request.execution);
|
|
89
107
|
const profile = registry.profiles.get(request.profile);
|
|
90
108
|
const snapshot = request.snapshot
|
|
91
109
|
? cloneTurnToolSnapshot(request.snapshot)
|
|
@@ -106,7 +124,7 @@ function startInvoke(registry, request, sinkOverride) {
|
|
|
106
124
|
return tree.root;
|
|
107
125
|
};
|
|
108
126
|
const events = invokeInTrace(registry, invoke, toolSpanName(invoke.name), sinkOverride, {
|
|
109
|
-
events: (tree, canaries) => invokeTraced(registry, invoke, callId, openSpan(tree), failCallBeforeTool(openSpan(tree), invoke, callId), tree.root.traceparent(), canaries),
|
|
127
|
+
events: (tree, canaries, background) => invokeTraced(registry, invoke, callId, openSpan(tree), failCallBeforeTool(openSpan(tree), invoke, callId), tree.root.traceparent(), canaries, background),
|
|
110
128
|
failed: (tree, err) => failCallBeforeTool(openSpan(tree), invoke, callId)(isAbortError(err) ? { outcome: 'cancelled' } : { outcome: 'error', thrown: err }),
|
|
111
129
|
});
|
|
112
130
|
return { name: invoke.name, callId, events };
|
|
@@ -141,7 +159,7 @@ function startInvokeStep(registry, request, sinkOverride) {
|
|
|
141
159
|
};
|
|
142
160
|
});
|
|
143
161
|
const events = invokeInTrace(registry, request, `tool_step ${request.profile}`, sinkOverride, {
|
|
144
|
-
events: (tree, canaries) => invokeStepTraced(registry, request, calls, (name, attributes) => tree.root.child(name, { attributes }), tree.root.traceparent(), canaries),
|
|
162
|
+
events: (tree, canaries, background) => invokeStepTraced(registry, request, calls, (name, attributes) => tree.root.child(name, { attributes }), tree.root.traceparent(), canaries, background),
|
|
145
163
|
ended: (tree) => tree.root.end({ code: 'OK' }),
|
|
146
164
|
failed: (tree, err) => {
|
|
147
165
|
if (isAbortError(err))
|
|
@@ -155,7 +173,7 @@ function startInvokeStep(registry, request, sinkOverride) {
|
|
|
155
173
|
events,
|
|
156
174
|
};
|
|
157
175
|
}
|
|
158
|
-
async function* invokeStepTraced(registry, request, calls, openSpan, traceparent, canaries) {
|
|
176
|
+
async function* invokeStepTraced(registry, request, calls, openSpan, traceparent, canaries, background) {
|
|
159
177
|
const { profile, snapshot } = await invokeSnapshot(registry, request);
|
|
160
178
|
const stepId = crypto.randomUUID();
|
|
161
179
|
for (const { callId, invoke, announce } of calls) {
|
|
@@ -175,7 +193,7 @@ async function* invokeStepTraced(registry, request, calls, openSpan, traceparent
|
|
|
175
193
|
let gated = false;
|
|
176
194
|
try {
|
|
177
195
|
// why: As in a turn's step, one call that throws ends the step; the others are closed.
|
|
178
|
-
const settlements = yield* runSideBySide(calls.map(({ callId, invoke }) => inStep(order, callId, () => runCall(registry, invoke, profile, snapshot, callId, openSpan, failCallBeforeTool(openSpan, invoke, callId), canaries, step))));
|
|
196
|
+
const settlements = yield* runSideBySide(calls.map(({ callId, invoke }) => inStep(order, callId, () => runCall(registry, invoke, profile, snapshot, callId, openSpan, failCallBeforeTool(openSpan, invoke, callId), canaries, background, step))));
|
|
179
197
|
gated = settlements.some((settlement) => settlement?.gated !== undefined);
|
|
180
198
|
}
|
|
181
199
|
catch (err) {
|
|
@@ -186,7 +204,7 @@ async function* invokeStepTraced(registry, request, calls, openSpan, traceparent
|
|
|
186
204
|
traceparent,
|
|
187
205
|
}, snapshot);
|
|
188
206
|
}
|
|
189
|
-
async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent, canaries) {
|
|
207
|
+
async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent, canaries, background) {
|
|
190
208
|
const { profile, snapshot } = await invokeSnapshot(registry, request);
|
|
191
209
|
// why: A model's call was already announced by its turn.
|
|
192
210
|
if (request.callId === undefined) {
|
|
@@ -194,7 +212,7 @@ async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool
|
|
|
194
212
|
}
|
|
195
213
|
let gated = false;
|
|
196
214
|
try {
|
|
197
|
-
const settlement = yield* runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries);
|
|
215
|
+
const settlement = yield* runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, background);
|
|
198
216
|
gated = settlement.gated !== undefined;
|
|
199
217
|
}
|
|
200
218
|
catch (err) {
|
|
@@ -206,9 +224,18 @@ async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool
|
|
|
206
224
|
}, snapshot);
|
|
207
225
|
}
|
|
208
226
|
/** One call, coordinated: replayed when its operation already ran, else executed. */
|
|
209
|
-
function runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, step) {
|
|
227
|
+
function runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, background, step) {
|
|
228
|
+
const operationId = request.operationId ?? crypto.randomUUID();
|
|
229
|
+
const tool = registry.tools.get(request.name);
|
|
230
|
+
const detach = planDetach({
|
|
231
|
+
tool: tool?.type === 'builtin' ? undefined : tool,
|
|
232
|
+
input: request.input,
|
|
233
|
+
support: background,
|
|
234
|
+
base: { name: request.name, callId, operationId },
|
|
235
|
+
labels: profile.labels,
|
|
236
|
+
});
|
|
210
237
|
return coordinateTool(request.execution, {
|
|
211
|
-
operationId
|
|
238
|
+
operationId,
|
|
212
239
|
callId,
|
|
213
240
|
profileId: profile.id,
|
|
214
241
|
toolId: request.name,
|
|
@@ -221,14 +248,14 @@ function runCall(registry, request, profile, snapshot, callId, openSpan, failBef
|
|
|
221
248
|
turnInput: request.turnInput,
|
|
222
249
|
promoted: request.promoted,
|
|
223
250
|
},
|
|
224
|
-
}, request.signal, (beginBody) => invokePrepared(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, beginBody, step), (outcome) => authorizeToolReplay({
|
|
251
|
+
}, request.signal, (beginBody, hooks) => invokePrepared(registry, { ...request, ...(hooks.signal ? { signal: hooks.signal } : {}) }, profile, snapshot, callId, detach?.trace.open ?? openSpan, failBeforeTool, canaries, beginBody, { ...step, ...(hooks.bodyEnded ? { bodyEnded: hooks.bodyEnded } : {}) }), (outcome) => authorizeToolReplay({
|
|
225
252
|
outcome,
|
|
226
253
|
tools: registry.tools,
|
|
227
254
|
profile,
|
|
228
255
|
name: request.name,
|
|
229
256
|
resume: request.resume,
|
|
230
257
|
snapshot,
|
|
231
|
-
}));
|
|
258
|
+
}), detach);
|
|
232
259
|
}
|
|
233
260
|
async function* invokePrepared(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, beginBody, step) {
|
|
234
261
|
if (request.promoted?.length) {
|
|
@@ -16,11 +16,14 @@ export function createMemoryToolExecution(options = {}) {
|
|
|
16
16
|
return undefined;
|
|
17
17
|
if (record.state === 'settled')
|
|
18
18
|
return { kind: 'settled', outcome: record.outcome };
|
|
19
|
+
if (record.state === 'background')
|
|
20
|
+
return { kind: 'background', reply: record.reply };
|
|
19
21
|
return { kind: record.state };
|
|
20
22
|
};
|
|
21
23
|
const holds = (claim) => {
|
|
22
24
|
const record = records.get(keyOf(claim));
|
|
23
|
-
return record?.state === 'running'
|
|
25
|
+
return ((record?.state === 'running' || record?.state === 'background') &&
|
|
26
|
+
record.claimToken === claim.claimToken);
|
|
24
27
|
};
|
|
25
28
|
const full = () => new TheoremError('config', `The memory tool coordinator holds its maxOperations of ${limit}`);
|
|
26
29
|
const notHeld = () => operationBroken('The memory tool coordinator holds no running claim for this token'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
|
|
@@ -37,6 +40,12 @@ export function createMemoryToolExecution(options = {}) {
|
|
|
37
40
|
records.set(keyOf(operation), { state: 'running', claimToken });
|
|
38
41
|
return Promise.resolve({ kind: 'acquired', claimToken });
|
|
39
42
|
},
|
|
43
|
+
detach: (claim, reply) => {
|
|
44
|
+
if (!holds(claim))
|
|
45
|
+
return Promise.reject(notHeld());
|
|
46
|
+
records.set(keyOf(claim), { state: 'background', claimToken: claim.claimToken, reply });
|
|
47
|
+
return Promise.resolve();
|
|
48
|
+
},
|
|
40
49
|
settle: (claim, outcome) => {
|
|
41
50
|
if (!holds(claim))
|
|
42
51
|
return Promise.reject(notHeld());
|
|
@@ -30,6 +30,18 @@ export interface PageToolDispatch {
|
|
|
30
30
|
export interface PageToolExecution {
|
|
31
31
|
dispatch(claim: ToolOperationClaim, signal?: AbortSignal): Promise<PageToolDispatch>;
|
|
32
32
|
}
|
|
33
|
+
export type BackgroundToolEvent = TurnEventOf<'tool'> & {
|
|
34
|
+
tool: Extract<TurnEventOf<'tool'>['tool'], {
|
|
35
|
+
phase: 'background';
|
|
36
|
+
}>;
|
|
37
|
+
};
|
|
38
|
+
/** What the model reads when a call goes on after its turn. */
|
|
39
|
+
export interface ToolOperationReply {
|
|
40
|
+
event: BackgroundToolEvent;
|
|
41
|
+
replay: {
|
|
42
|
+
modelResult: ModelToolResult;
|
|
43
|
+
};
|
|
44
|
+
}
|
|
33
45
|
export interface ToolOperationOutcome {
|
|
34
46
|
event: TerminalToolEvent;
|
|
35
47
|
effects: 'not_started' | 'completed' | 'unknown';
|
|
@@ -53,6 +65,9 @@ export type BeginToolOperationResult = {
|
|
|
53
65
|
} | {
|
|
54
66
|
kind: 'settled';
|
|
55
67
|
outcome: ToolOperationOutcome;
|
|
68
|
+
} | {
|
|
69
|
+
kind: 'background';
|
|
70
|
+
reply: ToolOperationReply;
|
|
56
71
|
} | {
|
|
57
72
|
kind: 'running';
|
|
58
73
|
} | {
|
|
@@ -69,6 +84,11 @@ export interface ToolExecutionCoordinator {
|
|
|
69
84
|
kind: 'acquired';
|
|
70
85
|
}> | undefined>;
|
|
71
86
|
begin(operation: ToolOperationIdentity): Promise<BeginToolOperationResult>;
|
|
87
|
+
/**
|
|
88
|
+
* Keeps the reply the model reads for a call that goes on after its turn. The claim stays held
|
|
89
|
+
* for `settle` or `markUncertain`. A coordinator without it cannot take a background service.
|
|
90
|
+
*/
|
|
91
|
+
detach?(claim: ToolOperationClaim, reply: ToolOperationReply): Promise<void>;
|
|
72
92
|
settle(claim: ToolOperationClaim, outcome: ToolOperationOutcome): Promise<void>;
|
|
73
93
|
settleNotStarted(operation: ToolOperationIdentity, outcome: ToolOperationOutcome): Promise<void>;
|
|
74
94
|
markUncertain(claim: ToolOperationClaim, reason: ToolOperationUncertainty): Promise<void>;
|
|
@@ -80,5 +100,6 @@ export declare function unresolvedOperation(kind: ErrorKind, reason: string, cau
|
|
|
80
100
|
/** The host asked to run an operation that is still running or uncertain, so the host settles it first. */
|
|
81
101
|
export declare function heldOperation(state: 'running' | 'uncertain'): TheoremError;
|
|
82
102
|
export declare function toolInvocationHash(value: unknown): Promise<string>;
|
|
103
|
+
export declare const toolOperationReplySchema: z.ZodType<ToolOperationReply>;
|
|
83
104
|
export declare const toolOperationOutcomeSchema: z.ZodType<ToolOperationOutcome>;
|
|
84
105
|
export declare function operationWireValue(value: unknown): JsonValue;
|
|
@@ -42,20 +42,29 @@ const terminalSchema = TURN_EVENT_SCHEMAS.tool.transform((event, ctx) => {
|
|
|
42
42
|
ctx.addIssue({ code: 'custom' });
|
|
43
43
|
return z.NEVER;
|
|
44
44
|
});
|
|
45
|
+
const modelResultSchema = z.strictObject({
|
|
46
|
+
finding: z.string(),
|
|
47
|
+
data: jsonValueSchema.optional(),
|
|
48
|
+
parts: z.array(interactionPartSchema).optional(),
|
|
49
|
+
modelText: z.string().optional(),
|
|
50
|
+
provenance: provenance.optional(),
|
|
51
|
+
suspicious: z.array(guardrailHit).optional(),
|
|
52
|
+
});
|
|
53
|
+
const backgroundSchema = TURN_EVENT_SCHEMAS.tool.transform((event, ctx) => {
|
|
54
|
+
if (event.tool.phase === 'background')
|
|
55
|
+
return { ...event, tool: event.tool };
|
|
56
|
+
ctx.addIssue({ code: 'custom' });
|
|
57
|
+
return z.NEVER;
|
|
58
|
+
});
|
|
59
|
+
export const toolOperationReplySchema = z.strictObject({
|
|
60
|
+
event: backgroundSchema,
|
|
61
|
+
replay: z.strictObject({ modelResult: modelResultSchema }),
|
|
62
|
+
});
|
|
45
63
|
export const toolOperationOutcomeSchema = z.strictObject({
|
|
46
64
|
event: terminalSchema,
|
|
47
65
|
effects: z.enum(['not_started', 'completed', 'unknown']),
|
|
48
66
|
replay: z.strictObject({
|
|
49
|
-
modelResult:
|
|
50
|
-
.strictObject({
|
|
51
|
-
finding: z.string(),
|
|
52
|
-
data: jsonValueSchema.optional(),
|
|
53
|
-
parts: z.array(interactionPartSchema).optional(),
|
|
54
|
-
modelText: z.string().optional(),
|
|
55
|
-
provenance: provenance.optional(),
|
|
56
|
-
suspicious: z.array(guardrailHit).optional(),
|
|
57
|
-
})
|
|
58
|
-
.optional(),
|
|
67
|
+
modelResult: modelResultSchema.optional(),
|
|
59
68
|
outputRaw: jsonValueSchema.optional(),
|
|
60
69
|
failure: z
|
|
61
70
|
.strictObject({
|
|
@@ -2,7 +2,8 @@ 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 {
|
|
5
|
+
import { assertBackgroundSetting, backgroundField } from './background.js';
|
|
6
|
+
import { withCallOrder, withModelField } from './call-order.js';
|
|
6
7
|
import { createMcpSessionCache } from './mcp-sessions.js';
|
|
7
8
|
import { pageAnswerHandler } from './page-answer.js';
|
|
8
9
|
import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolSchema, } from './schema.js';
|
|
@@ -128,7 +129,25 @@ function normalizeFunction(def) {
|
|
|
128
129
|
}
|
|
129
130
|
return { ...def, handler, type: 'function', ...schemasFromZod(def) };
|
|
130
131
|
}
|
|
132
|
+
/** Checks the tool's `background`, and gives an `ask` tool the schema a turn with the service sends. */
|
|
133
|
+
function withBackground(tool) {
|
|
134
|
+
if (tool.type === 'builtin')
|
|
135
|
+
return tool;
|
|
136
|
+
assertBackgroundSetting({
|
|
137
|
+
name: tool.name,
|
|
138
|
+
...(tool.background !== undefined ? { background: tool.background } : {}),
|
|
139
|
+
...(tool.type === 'function' && tool.answeredBy ? { answeredBy: tool.answeredBy } : {}),
|
|
140
|
+
});
|
|
141
|
+
if (tool.background !== 'ask')
|
|
142
|
+
return tool;
|
|
143
|
+
const input = tool.input;
|
|
144
|
+
const asked = withModelField(tool.name, input, 'background', backgroundField);
|
|
145
|
+
return { ...tool, askInputSchema: checkedSchemas(asked, tool.output).inputSchema };
|
|
146
|
+
}
|
|
131
147
|
function normalizeToolDefinition(def, findProfile, findTool) {
|
|
148
|
+
return withBackground(normalizeDefinition(def, findProfile, findTool));
|
|
149
|
+
}
|
|
150
|
+
function normalizeDefinition(def, findProfile, findTool) {
|
|
132
151
|
if (def.type === 'builtin') {
|
|
133
152
|
return def;
|
|
134
153
|
}
|
|
@@ -9,8 +9,8 @@ export declare function profileToolsSpec(profile: Profile): ProfileToolsSpec | u
|
|
|
9
9
|
export declare function profileToolsParallel(profile: Profile): boolean | undefined;
|
|
10
10
|
export declare function resolveAllowedCustomToolIds(tools: ToolRegistry, profile: Profile, req: TurnRequest): ToolId[];
|
|
11
11
|
export declare function resolveModelBuiltinIds(tools: ToolRegistry, profile: ModelProfile, req: TurnRequest, modelId: ModelId): ToolId[];
|
|
12
|
-
export declare function wireForTool(tools: ToolRegistry, name: string): WireFunctionTool | undefined;
|
|
13
|
-
export declare function buildWire(tools: ToolRegistry, visible: ToolId[]): WireFunctionTool[];
|
|
12
|
+
export declare function wireForTool(tools: ToolRegistry, name: string, modelBackground?: boolean): WireFunctionTool | undefined;
|
|
13
|
+
export declare function buildWire(tools: ToolRegistry, visible: ToolId[], modelBackground?: boolean): WireFunctionTool[];
|
|
14
14
|
export declare function promoteTool(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
|
|
15
15
|
export declare function promoteBuiltin(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
|
|
16
16
|
/** Live declarations are fixed at session setup, so every allowed tool there is effectively T0. */
|
|
@@ -22,6 +22,8 @@ export declare function prepareTurnToolSnapshot(tools: ToolRegistry, profile: Pr
|
|
|
22
22
|
/** So concurrent host invokes do not share mutable state. */
|
|
23
23
|
export declare function cloneTurnToolSnapshot(state: TurnToolSnapshot): TurnToolSnapshot;
|
|
24
24
|
export declare function expandT1Policy(tools: ToolRegistry, state: TurnToolSnapshot, profile: Profile, req: TurnRequest): Promise<void>;
|
|
25
|
+
/** Puts the T2 tools among `ids` that the turn may call on its list; any other id is left out. */
|
|
26
|
+
export declare function promoteTurnTools(tools: ToolRegistry, state: TurnToolSnapshot, ids?: readonly ToolId[]): void;
|
|
25
27
|
export declare function extractLoadedIds(output: unknown): string[] | undefined;
|
|
26
28
|
export declare function promoteLoadedTools(tools: ToolRegistry, state: TurnToolSnapshot, loaded: string[], profile: Profile): PromoteLoadedResult;
|
|
27
29
|
export declare function promotionTarget(tools: ToolRegistry, id: string, profile: Profile): {
|
|
@@ -57,7 +57,7 @@ export function resolveModelBuiltinIds(tools, profile, req, modelId) {
|
|
|
57
57
|
return pathMatches(tool.paths, req.path);
|
|
58
58
|
});
|
|
59
59
|
}
|
|
60
|
-
export function wireForTool(tools, name) {
|
|
60
|
+
export function wireForTool(tools, name, modelBackground) {
|
|
61
61
|
const tool = tools.get(name);
|
|
62
62
|
if (!tool || tool.type === 'builtin') {
|
|
63
63
|
return undefined;
|
|
@@ -66,13 +66,13 @@ export function wireForTool(tools, name) {
|
|
|
66
66
|
type: 'function',
|
|
67
67
|
name: tool.name,
|
|
68
68
|
description: tool.description,
|
|
69
|
-
parameters: tool.inputSchema,
|
|
69
|
+
parameters: (modelBackground && tool.askInputSchema) || tool.inputSchema,
|
|
70
70
|
};
|
|
71
71
|
}
|
|
72
|
-
export function buildWire(tools, visible) {
|
|
72
|
+
export function buildWire(tools, visible, modelBackground) {
|
|
73
73
|
const out = [];
|
|
74
74
|
for (const id of visible) {
|
|
75
|
-
const wire = wireForTool(tools, id);
|
|
75
|
+
const wire = wireForTool(tools, id, modelBackground);
|
|
76
76
|
if (wire) {
|
|
77
77
|
out.push(wire);
|
|
78
78
|
}
|
|
@@ -84,7 +84,7 @@ export function promoteTool(tools, state, id) {
|
|
|
84
84
|
return;
|
|
85
85
|
}
|
|
86
86
|
state.visible.push(id);
|
|
87
|
-
const wire = wireForTool(tools, id);
|
|
87
|
+
const wire = wireForTool(tools, id, state.modelBackground);
|
|
88
88
|
if (wire && !state.wire.some((w) => w.name === id)) {
|
|
89
89
|
state.wire.push(wire);
|
|
90
90
|
}
|
|
@@ -129,8 +129,17 @@ function assertToolPathsDeclared(tools, profile) {
|
|
|
129
129
|
if (problem)
|
|
130
130
|
throw new TheoremError('config', `Profile ${profile.id}: ${problem}`); // labels-exempt: developer contract error
|
|
131
131
|
}
|
|
132
|
+
/** A T2 loader changes the turn that called it, so it must finish in that turn. */
|
|
133
|
+
function assertLoaderAnswersInTurn(tools, profile) {
|
|
134
|
+
const loader = profileToolsSpec(profile)?.t2Loader;
|
|
135
|
+
const tool = loader === undefined ? undefined : tools.get(loader);
|
|
136
|
+
if (!tool || tool.type === 'builtin' || (tool.background ?? 'never') === 'never')
|
|
137
|
+
return;
|
|
138
|
+
throw new TheoremError('config', `Profile ${profile.id}: tools.t2Loader '${tool.name}' sets background, and a loader cannot detach`);
|
|
139
|
+
}
|
|
132
140
|
export function resolveTurnTools(tools, profile, req, modelId) {
|
|
133
141
|
assertToolPathsDeclared(tools, profile);
|
|
142
|
+
assertLoaderAnswersInTurn(tools, profile);
|
|
134
143
|
const customAllowed = resolveAllowedCustomToolIds(tools, profile, req);
|
|
135
144
|
const modelBuiltins = profile.type === 'host' ||
|
|
136
145
|
profile.type === 'decision' ||
|
|
@@ -142,6 +151,7 @@ export function resolveTurnTools(tools, profile, req, modelId) {
|
|
|
142
151
|
const builtins = initialBuiltins(tools, profile, gated);
|
|
143
152
|
const visible = initialVisible(tools, profile, gated);
|
|
144
153
|
const executable = visible.filter((id) => isExecutable(tools, id));
|
|
154
|
+
const modelBackground = req.background !== undefined;
|
|
145
155
|
return {
|
|
146
156
|
builtins,
|
|
147
157
|
gated,
|
|
@@ -149,7 +159,8 @@ export function resolveTurnTools(tools, profile, req, modelId) {
|
|
|
149
159
|
executable,
|
|
150
160
|
path: req.path,
|
|
151
161
|
sessionPermissions: req.sessionPermissions,
|
|
152
|
-
wire: buildWire(tools, visible),
|
|
162
|
+
wire: buildWire(tools, visible, modelBackground),
|
|
163
|
+
...(modelBackground ? { modelBackground } : {}),
|
|
153
164
|
};
|
|
154
165
|
}
|
|
155
166
|
/** Resolves the tools a turn may call into a snapshot, then applies the profile's `t1Policy` to it. */
|
|
@@ -168,6 +179,7 @@ export function cloneTurnToolSnapshot(state) {
|
|
|
168
179
|
path: state.path,
|
|
169
180
|
sessionPermissions: state.sessionPermissions ? [...state.sessionPermissions] : undefined,
|
|
170
181
|
wire: state.wire.map((w) => ({ ...w, parameters: structuredClone(w.parameters) })),
|
|
182
|
+
...(state.modelBackground ? { modelBackground: state.modelBackground } : {}),
|
|
171
183
|
};
|
|
172
184
|
}
|
|
173
185
|
export async function expandT1Policy(tools, state, profile, req) {
|
|
@@ -195,7 +207,11 @@ export async function expandT1Policy(tools, state, profile, req) {
|
|
|
195
207
|
if (!Array.isArray(selected)) {
|
|
196
208
|
throw new TheoremError('config', `Profile '${profile.id}' tools.t1Policy must return ToolId[]`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
|
|
197
209
|
}
|
|
198
|
-
|
|
210
|
+
promoteTurnTools(tools, state, selected);
|
|
211
|
+
}
|
|
212
|
+
/** Puts the T2 tools among `ids` that the turn may call on its list; any other id is left out. */
|
|
213
|
+
export function promoteTurnTools(tools, state, ids = []) {
|
|
214
|
+
for (const id of ids) {
|
|
199
215
|
if (!state.gated.includes(id)) {
|
|
200
216
|
continue;
|
|
201
217
|
}
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import type { ToolPhaseEvent, TurnEvent } from '../turn-events.js';
|
|
7
7
|
import type { StartedInvoke, StartedStep } from './invoke.js';
|
|
8
|
-
/** The phase a call ends on: it completed, a gate held it, or it
|
|
8
|
+
/** The phase a call ends on: it completed, a gate held it, it failed, or it went on in the background. */
|
|
9
9
|
export type SettledToolCall = Extract<ToolPhaseEvent, {
|
|
10
|
-
phase: 'complete' | 'gate' | 'error';
|
|
10
|
+
phase: 'complete' | 'gate' | 'error' | 'background';
|
|
11
11
|
}> & {
|
|
12
12
|
/** Kernel-issued identity; a gate's resume carries it. */
|
|
13
13
|
operationId?: string;
|
|
@@ -5,7 +5,10 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import { labelText } from '../../guardrails/labels.js';
|
|
7
7
|
function isSettled(tool) {
|
|
8
|
-
return tool.phase === 'complete' ||
|
|
8
|
+
return (tool.phase === 'complete' ||
|
|
9
|
+
tool.phase === 'gate' ||
|
|
10
|
+
tool.phase === 'error' ||
|
|
11
|
+
tool.phase === 'background');
|
|
9
12
|
}
|
|
10
13
|
function foldTool(fold, tool) {
|
|
11
14
|
if (tool.phase === 'running')
|
|
@@ -34,6 +34,8 @@ export interface ToolStageSupport {
|
|
|
34
34
|
wait?: StepWait;
|
|
35
35
|
/** The host sees a handler's drafts: `outputs.streaming.mode` `sse`. Unset outside a turn's step. */
|
|
36
36
|
drafts?: boolean;
|
|
37
|
+
/** Told when the body has ended, before `post_tool` reads it. */
|
|
38
|
+
bodyEnded?: () => void;
|
|
37
39
|
}
|
|
38
40
|
export type PreBodyOutcome = {
|
|
39
41
|
ok: true;
|
|
@@ -162,6 +162,7 @@ async function waitForStepCalls(stages, callId, toolName, waitFor, labels) {
|
|
|
162
162
|
}
|
|
163
163
|
export async function* runPostToolStages(args) {
|
|
164
164
|
const { stages, toolName, callId, mutable, ...call } = args;
|
|
165
|
+
stages.bodyEnded?.();
|
|
165
166
|
const applied = yield* runStage({
|
|
166
167
|
...call,
|
|
167
168
|
stage: 'post_tool',
|
|
@@ -8,6 +8,7 @@ import type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, T
|
|
|
8
8
|
import type { RemovedItem, Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
|
|
9
9
|
import type { InteractionPart, ModelId, Profile, ProfileId, ToolId, TurnInput, TurnRequest, TurnSpeech, TurnTraceLink } from '../types.js';
|
|
10
10
|
import type { LabelTemplate } from './activity-label.js';
|
|
11
|
+
import type { ToolBackground, ToolBackgroundService } from './background.js';
|
|
11
12
|
import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js';
|
|
12
13
|
import type { UncheckedOutput } from './unchecked-output.js';
|
|
13
14
|
export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
|
|
@@ -157,6 +158,10 @@ export interface ToolHostHooks<TIn = unknown> {
|
|
|
157
158
|
exposeToModel?: boolean;
|
|
158
159
|
/** The model gets an `after` field: the tools in the same step that must settle before this call starts. */
|
|
159
160
|
after?: boolean;
|
|
161
|
+
/** When the model gets its reply. Unset is `never`: when the body ends. A turn without a background service runs inline. */
|
|
162
|
+
background?: ToolBackground;
|
|
163
|
+
/** `inputSchema` with the `background` argument. The registry sets it on an `ask` tool. */
|
|
164
|
+
askInputSchema?: Record<string, unknown>;
|
|
160
165
|
}
|
|
161
166
|
export interface ToolOutputHooks<TOut = unknown> {
|
|
162
167
|
/** A source that fails `sourceSchema`, or a throw, is a `sources_invalid` warning and is not cited. */
|
|
@@ -319,6 +324,7 @@ export interface AgentToolDef extends ToolBase {
|
|
|
319
324
|
hostOnly?: AgentToolChannel[];
|
|
320
325
|
preTool?: ToolHostHooks<AgentToolInput>['preTool'];
|
|
321
326
|
after?: ToolHostHooks<AgentToolInput>['after'];
|
|
327
|
+
background?: ToolHostHooks<AgentToolInput>['background'];
|
|
322
328
|
exposeToModel?: boolean;
|
|
323
329
|
}
|
|
324
330
|
export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
|
|
@@ -400,6 +406,7 @@ export type ToolPolicy = (ctx: ToolLoadContext) => ToolId[] | Promise<ToolId[]>;
|
|
|
400
406
|
/** A request to run a held tool call outside a turn. */
|
|
401
407
|
export interface InvokeToolRequest {
|
|
402
408
|
execution?: ToolExecutionCoordinator;
|
|
409
|
+
background?: ToolBackgroundService;
|
|
403
410
|
/** invariant: Only the trusted host restores the kernel-issued identity from saved authority. */
|
|
404
411
|
operationId?: string;
|
|
405
412
|
profile: string;
|
|
@@ -368,6 +368,8 @@ export interface TurnToolSnapshot {
|
|
|
368
368
|
path?: string;
|
|
369
369
|
sessionPermissions?: string[];
|
|
370
370
|
wire: WireFunctionTool[];
|
|
371
|
+
/** The request has a background service, so `ask` tools offer the `background` argument. */
|
|
372
|
+
modelBackground?: boolean;
|
|
371
373
|
}
|
|
372
374
|
/** The schema a tool snapshot parses against. */
|
|
373
375
|
export declare const turnToolSnapshotSchema: z.ZodType<TurnToolSnapshot>;
|
|
@@ -473,12 +475,17 @@ export type ToolPhaseEvent = ToolPhaseBase & ({
|
|
|
473
475
|
readBack?: string;
|
|
474
476
|
parts?: InteractionPart[];
|
|
475
477
|
activityPast?: string;
|
|
476
|
-
/** An agent tool's call: the called agent's own usage
|
|
478
|
+
/** An agent tool's call: the called agent's own usage. The caller's `done.tokens` includes it, unless the call settled after `done`. */
|
|
477
479
|
tokens?: TurnTokens;
|
|
478
480
|
} | {
|
|
479
481
|
phase: 'gate';
|
|
480
482
|
gate: ToolGate;
|
|
481
483
|
readBack?: string;
|
|
484
|
+
}
|
|
485
|
+
/** The model reads `readBack` now and the call goes on; its real end reaches the host alone. */
|
|
486
|
+
| {
|
|
487
|
+
phase: 'background';
|
|
488
|
+
readBack: string;
|
|
482
489
|
} | {
|
|
483
490
|
phase: 'error';
|
|
484
491
|
failure: ToolFailure;
|
|
@@ -562,6 +569,8 @@ export interface DoneBase {
|
|
|
562
569
|
tokens?: TurnTokens;
|
|
563
570
|
/** The turn's root span as a W3C `traceparent`, for a later request's `links`. */
|
|
564
571
|
traceparent?: string;
|
|
572
|
+
/** The model calls that count against `maxSteps` so far, those of `stepsTaken` included. */
|
|
573
|
+
steps?: number;
|
|
565
574
|
compaction?: CompactionSignal;
|
|
566
575
|
/** A user utterance interrupted an in-flight live response (barge-in). */
|
|
567
576
|
interrupted?: boolean;
|
|
@@ -246,6 +246,7 @@ const turnToolSnapshot = z.object({
|
|
|
246
246
|
path: z.string().optional(),
|
|
247
247
|
sessionPermissions: z.array(z.string()).optional(),
|
|
248
248
|
wire: z.array(wireFunctionTool),
|
|
249
|
+
modelBackground: z.boolean().optional(),
|
|
249
250
|
});
|
|
250
251
|
true;
|
|
251
252
|
/** The schema a tool snapshot parses against. */
|
|
@@ -299,6 +300,7 @@ const toolPhaseEvent = z.discriminatedUnion('phase', [
|
|
|
299
300
|
gate: toolGate,
|
|
300
301
|
readBack: z.string().optional(),
|
|
301
302
|
}),
|
|
303
|
+
z.object({ ...toolPhaseBase, phase: z.literal('background'), readBack: z.string() }),
|
|
302
304
|
z.object({
|
|
303
305
|
...toolPhaseBase,
|
|
304
306
|
phase: z.literal('error'),
|
|
@@ -358,6 +360,7 @@ const doneBase = {
|
|
|
358
360
|
type: z.literal('done'),
|
|
359
361
|
tokens: turnTokens.optional(),
|
|
360
362
|
traceparent: z.string().optional(),
|
|
363
|
+
steps: z.number().int().nonnegative().optional(),
|
|
361
364
|
compaction: compactionSignal.optional(),
|
|
362
365
|
interrupted: z.boolean().optional(),
|
|
363
366
|
interactionId: z.string().optional(),
|