@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.
Files changed (54) hide show
  1. package/README.md +1 -1
  2. package/esm/mod.d.ts +3 -2
  3. package/esm/mod.js +1 -1
  4. package/esm/src/guardrails/labels.d.ts +1 -1
  5. package/esm/src/guardrails/labels.js +6 -0
  6. package/esm/src/interface/history.d.ts +2 -2
  7. package/esm/src/interface/history.js +7 -4
  8. package/esm/src/interface/mod.d.ts +1 -1
  9. package/esm/src/interface/mod.js +1 -1
  10. package/esm/src/interface/tool-calls.d.ts +3 -3
  11. package/esm/src/interface/tool-calls.js +5 -8
  12. package/esm/src/interface/tool-invoke.d.ts +11 -1
  13. package/esm/src/interface/tool-invoke.js +13 -1
  14. package/esm/src/interface/types.d.ts +1 -1
  15. package/esm/src/kernel/api-catalog.js +12 -0
  16. package/esm/src/kernel/engine/background.d.ts +7 -0
  17. package/esm/src/kernel/engine/background.js +18 -0
  18. package/esm/src/kernel/engine/runner/gates.js +4 -3
  19. package/esm/src/kernel/engine/runner/mod.js +24 -1
  20. package/esm/src/kernel/engine/runner/state.d.ts +4 -0
  21. package/esm/src/kernel/engine/runner/state.js +1 -0
  22. package/esm/src/kernel/engine/runner/step-order.d.ts +8 -0
  23. package/esm/src/kernel/engine/runner/step-order.js +1 -1
  24. package/esm/src/kernel/engine/runner/steps.js +5 -0
  25. package/esm/src/kernel/engine/session/mod.d.ts +2 -0
  26. package/esm/src/kernel/engine/session/mod.js +19 -2
  27. package/esm/src/kernel/mod.d.ts +3 -2
  28. package/esm/src/kernel/mod.js +1 -1
  29. package/esm/src/kernel/schema.js +12 -0
  30. package/esm/src/kernel/tools/background.d.ts +81 -0
  31. package/esm/src/kernel/tools/background.js +70 -0
  32. package/esm/src/kernel/tools/call-order.d.ts +3 -1
  33. package/esm/src/kernel/tools/call-order.js +10 -6
  34. package/esm/src/kernel/tools/coordinate.d.ts +8 -1
  35. package/esm/src/kernel/tools/coordinate.js +274 -34
  36. package/esm/src/kernel/tools/execute.d.ts +2 -0
  37. package/esm/src/kernel/tools/execute.js +17 -4
  38. package/esm/src/kernel/tools/invoke.js +40 -13
  39. package/esm/src/kernel/tools/memory-execution.js +10 -1
  40. package/esm/src/kernel/tools/operation.d.ts +21 -0
  41. package/esm/src/kernel/tools/operation.js +19 -10
  42. package/esm/src/kernel/tools/registry.js +20 -1
  43. package/esm/src/kernel/tools/resolve.d.ts +4 -2
  44. package/esm/src/kernel/tools/resolve.js +23 -7
  45. package/esm/src/kernel/tools/run.d.ts +2 -2
  46. package/esm/src/kernel/tools/run.js +4 -1
  47. package/esm/src/kernel/tools/stage-run.d.ts +2 -0
  48. package/esm/src/kernel/tools/stage-run.js +1 -0
  49. package/esm/src/kernel/tools/types.d.ts +7 -0
  50. package/esm/src/kernel/turn-events.d.ts +10 -1
  51. package/esm/src/kernel/turn-events.js +3 -0
  52. package/esm/src/kernel/types.d.ts +13 -0
  53. package/esm/src/providers/open-ai/protocol.js +8 -4
  54. 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: args.ctx.operationId ?? crypto.randomUUID(),
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, input, callId, ctx, snapshot, stages } = args;
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
- for await (const event of run.events(tree, canaries)) {
61
- // invariant: A match is the caught text itself; it leaves only when the profile asks for it.
62
- yield projectGuardrailTurnEvent(withPublicLabels(event, labels), policy.include.guardrailMatchPreview);
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: request.operationId ?? crypto.randomUUID(),
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' && record.claimToken === claim.claimToken;
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: z
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 { withCallOrder } from './call-order.js';
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
- for (const id of selected) {
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 failed. */
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' || tool.phase === 'gate' || tool.phase === 'error';
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, which the caller's `done.tokens` includes. */
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(),