@theoremjs/agents 0.3.4-next.679.gcdf1a3a → 0.3.4-next.711.g78e504a

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 (92) hide show
  1. package/README.md +5 -4
  2. package/esm/mod.d.ts +6 -3
  3. package/esm/mod.js +3 -1
  4. package/esm/src/cli/commands/bench.js +4 -10
  5. package/esm/src/cli/commands/profile.js +4 -1
  6. package/esm/src/guardrails/labels.d.ts +1 -1
  7. package/esm/src/guardrails/labels.js +9 -0
  8. package/esm/src/interface/blocks.js +19 -0
  9. package/esm/src/interface/from-profile.d.ts +2 -2
  10. package/esm/src/interface/from-profile.js +7 -0
  11. package/esm/src/interface/history.d.ts +2 -2
  12. package/esm/src/interface/history.js +7 -4
  13. package/esm/src/interface/mod.d.ts +2 -2
  14. package/esm/src/interface/mod.js +1 -1
  15. package/esm/src/interface/profile-interface.js +14 -4
  16. package/esm/src/interface/tool-calls.d.ts +3 -3
  17. package/esm/src/interface/tool-calls.js +5 -8
  18. package/esm/src/interface/tool-invoke.d.ts +3 -1
  19. package/esm/src/interface/tool-invoke.js +6 -1
  20. package/esm/src/interface/types.d.ts +7 -5
  21. package/esm/src/kernel/api-catalog.js +13 -5
  22. package/esm/src/kernel/auth/oauth.js +3 -1
  23. package/esm/src/kernel/engine/background.d.ts +7 -0
  24. package/esm/src/kernel/engine/background.js +18 -0
  25. package/esm/src/kernel/engine/runner/mod.js +24 -1
  26. package/esm/src/kernel/engine/runner/state.d.ts +4 -0
  27. package/esm/src/kernel/engine/runner/state.js +1 -0
  28. package/esm/src/kernel/engine/runner/step-order.d.ts +8 -0
  29. package/esm/src/kernel/engine/runner/step-order.js +1 -1
  30. package/esm/src/kernel/engine/runner/steps.js +1 -0
  31. package/esm/src/kernel/engine/session/mod.d.ts +2 -0
  32. package/esm/src/kernel/engine/session/mod.js +20 -2
  33. package/esm/src/kernel/engine/session/session-trace.js +1 -0
  34. package/esm/src/kernel/mod.d.ts +6 -3
  35. package/esm/src/kernel/mod.js +3 -1
  36. package/esm/src/kernel/profile-presence.js +1 -0
  37. package/esm/src/kernel/profile-scope.js +23 -21
  38. package/esm/src/kernel/protocols/protocol.d.ts +1 -1
  39. package/esm/src/kernel/protocols/protocol.js +1 -0
  40. package/esm/src/kernel/registry/catalog.js +4 -1
  41. package/esm/src/kernel/registry/ingress.d.ts +3 -1
  42. package/esm/src/kernel/registry/ingress.js +12 -1
  43. package/esm/src/kernel/registry/profile-outputs.js +2 -1
  44. package/esm/src/kernel/registry/profiles.d.ts +12 -2
  45. package/esm/src/kernel/registry/profiles.js +37 -7
  46. package/esm/src/kernel/registry/resolve.js +9 -5
  47. package/esm/src/kernel/registry/system-prompt.d.ts +6 -1
  48. package/esm/src/kernel/registry/system-prompt.js +20 -13
  49. package/esm/src/kernel/schema.d.ts +1 -1
  50. package/esm/src/kernel/schema.js +24 -8
  51. package/esm/src/kernel/system-lines.d.ts +22 -0
  52. package/esm/src/kernel/system-lines.js +162 -0
  53. package/esm/src/kernel/tools/activity-label.d.ts +15 -0
  54. package/esm/src/kernel/tools/activity-label.js +12 -7
  55. package/esm/src/kernel/tools/agent.js +1 -1
  56. package/esm/src/kernel/tools/background.d.ts +81 -0
  57. package/esm/src/kernel/tools/background.js +70 -0
  58. package/esm/src/kernel/tools/call-order.d.ts +18 -0
  59. package/esm/src/kernel/tools/call-order.js +52 -0
  60. package/esm/src/kernel/tools/coordinate.d.ts +8 -1
  61. package/esm/src/kernel/tools/coordinate.js +274 -34
  62. package/esm/src/kernel/tools/execute.d.ts +2 -0
  63. package/esm/src/kernel/tools/execute.js +17 -4
  64. package/esm/src/kernel/tools/invoke.js +40 -13
  65. package/esm/src/kernel/tools/memory-execution.js +10 -1
  66. package/esm/src/kernel/tools/operation.d.ts +21 -0
  67. package/esm/src/kernel/tools/operation.js +19 -10
  68. package/esm/src/kernel/tools/registry.js +28 -6
  69. package/esm/src/kernel/tools/resolve.d.ts +4 -2
  70. package/esm/src/kernel/tools/resolve.js +34 -7
  71. package/esm/src/kernel/tools/run.d.ts +2 -2
  72. package/esm/src/kernel/tools/run.js +4 -1
  73. package/esm/src/kernel/tools/stage-run.d.ts +3 -1
  74. package/esm/src/kernel/tools/stage-run.js +58 -55
  75. package/esm/src/kernel/tools/types.d.ts +10 -0
  76. package/esm/src/kernel/turn-events.d.ts +8 -1
  77. package/esm/src/kernel/turn-events.js +2 -0
  78. package/esm/src/kernel/types.d.ts +39 -4
  79. package/esm/src/observability/trace-catalog.js +3 -0
  80. package/esm/src/providers/google/interactions/steps.js +14 -3
  81. package/esm/src/providers/mod.d.ts +2 -0
  82. package/esm/src/providers/mod.js +1 -0
  83. package/esm/src/providers/open-ai/protocol.js +8 -4
  84. package/esm/src/providers/openrouter/protocol.d.ts +26 -0
  85. package/esm/src/providers/openrouter/protocol.js +58 -2
  86. package/esm/src/providers/openrouter/provider.d.ts +1 -1
  87. package/esm/src/providers/openrouter/provider.js +3 -1
  88. package/esm/src/providers/openrouter/transcriptions-protocol.d.ts +10 -0
  89. package/esm/src/providers/openrouter/transcriptions-protocol.js +87 -0
  90. package/package.json +1 -1
  91. package/esm/src/kernel/registry/system-role.d.ts +0 -3
  92. package/esm/src/kernel/registry/system-role.js +0 -9
@@ -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,6 +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 { assertBackgroundSetting, backgroundField } from './background.js';
6
+ import { withCallOrder, withModelField } from './call-order.js';
5
7
  import { createMcpSessionCache } from './mcp-sessions.js';
6
8
  import { pageAnswerHandler } from './page-answer.js';
7
9
  import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolSchema, } from './schema.js';
@@ -127,24 +129,44 @@ function normalizeFunction(def) {
127
129
  }
128
130
  return { ...def, handler, type: 'function', ...schemasFromZod(def) };
129
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
+ }
130
147
  function normalizeToolDefinition(def, findProfile, findTool) {
148
+ return withBackground(normalizeDefinition(def, findProfile, findTool));
149
+ }
150
+ function normalizeDefinition(def, findProfile, findTool) {
131
151
  if (def.type === 'builtin') {
132
152
  return def;
133
153
  }
134
154
  if (def.type === 'agent') {
135
155
  const profile = agentToolProfile(def, findProfile, findTool);
136
156
  const inputs = profileInputs(profile);
137
- const input = agentToolInputFor({ type: profile.type, ...(inputs ? { inputs } : {}) }, def);
157
+ const taken = agentToolInputFor({ type: profile.type, ...(inputs ? { inputs } : {}) }, def);
158
+ const input = def.after ? withCallOrder(def.name, taken) : taken;
138
159
  const schemas = schemasFromZod({ ...def, input, output: agentToolOutput });
139
160
  return normalizeAgent(def, input, schemas);
140
161
  }
141
- if (def.type === 'http') {
142
- return normalizeHttp(def);
162
+ const ordered = def.after ? { ...def, input: withCallOrder(def.name, def.input) } : def;
163
+ if (ordered.type === 'http') {
164
+ return normalizeHttp(ordered);
143
165
  }
144
- if (def.type === 'mcp') {
145
- return normalizeMcp(def);
166
+ if (ordered.type === 'mcp') {
167
+ return normalizeMcp(ordered);
146
168
  }
147
- return normalizeFunction(def);
169
+ return normalizeFunction(ordered);
148
170
  }
149
171
  /**
150
172
  * Registration is not synchronized: register a scope's tools before its turns or invokes run.
@@ -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): {
@@ -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) {
@@ -56,7 +57,7 @@ export function resolveModelBuiltinIds(tools, profile, req, modelId) {
56
57
  return pathMatches(tool.paths, req.path);
57
58
  });
58
59
  }
59
- export function wireForTool(tools, name) {
60
+ export function wireForTool(tools, name, modelBackground) {
60
61
  const tool = tools.get(name);
61
62
  if (!tool || tool.type === 'builtin') {
62
63
  return undefined;
@@ -65,13 +66,13 @@ export function wireForTool(tools, name) {
65
66
  type: 'function',
66
67
  name: tool.name,
67
68
  description: tool.description,
68
- parameters: tool.inputSchema,
69
+ parameters: (modelBackground && tool.askInputSchema) || tool.inputSchema,
69
70
  };
70
71
  }
71
- export function buildWire(tools, visible) {
72
+ export function buildWire(tools, visible, modelBackground) {
72
73
  const out = [];
73
74
  for (const id of visible) {
74
- const wire = wireForTool(tools, id);
75
+ const wire = wireForTool(tools, id, modelBackground);
75
76
  if (wire) {
76
77
  out.push(wire);
77
78
  }
@@ -83,7 +84,7 @@ export function promoteTool(tools, state, id) {
83
84
  return;
84
85
  }
85
86
  state.visible.push(id);
86
- const wire = wireForTool(tools, id);
87
+ const wire = wireForTool(tools, id, state.modelBackground);
87
88
  if (wire && !state.wire.some((w) => w.name === id)) {
88
89
  state.wire.push(wire);
89
90
  }
@@ -119,7 +120,26 @@ 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
+ }
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
+ }
122
140
  export function resolveTurnTools(tools, profile, req, modelId) {
141
+ assertToolPathsDeclared(tools, profile);
142
+ assertLoaderAnswersInTurn(tools, profile);
123
143
  const customAllowed = resolveAllowedCustomToolIds(tools, profile, req);
124
144
  const modelBuiltins = profile.type === 'host' ||
125
145
  profile.type === 'decision' ||
@@ -131,6 +151,7 @@ export function resolveTurnTools(tools, profile, req, modelId) {
131
151
  const builtins = initialBuiltins(tools, profile, gated);
132
152
  const visible = initialVisible(tools, profile, gated);
133
153
  const executable = visible.filter((id) => isExecutable(tools, id));
154
+ const modelBackground = req.background !== undefined;
134
155
  return {
135
156
  builtins,
136
157
  gated,
@@ -138,7 +159,8 @@ export function resolveTurnTools(tools, profile, req, modelId) {
138
159
  executable,
139
160
  path: req.path,
140
161
  sessionPermissions: req.sessionPermissions,
141
- wire: buildWire(tools, visible),
162
+ wire: buildWire(tools, visible, modelBackground),
163
+ ...(modelBackground ? { modelBackground } : {}),
142
164
  };
143
165
  }
144
166
  /** Resolves the tools a turn may call into a snapshot, then applies the profile's `t1Policy` to it. */
@@ -157,6 +179,7 @@ export function cloneTurnToolSnapshot(state) {
157
179
  path: state.path,
158
180
  sessionPermissions: state.sessionPermissions ? [...state.sessionPermissions] : undefined,
159
181
  wire: state.wire.map((w) => ({ ...w, parameters: structuredClone(w.parameters) })),
182
+ ...(state.modelBackground ? { modelBackground: state.modelBackground } : {}),
160
183
  };
161
184
  }
162
185
  export async function expandT1Policy(tools, state, profile, req) {
@@ -184,7 +207,11 @@ export async function expandT1Policy(tools, state, profile, req) {
184
207
  if (!Array.isArray(selected)) {
185
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)
186
209
  }
187
- 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) {
188
215
  if (!state.gated.includes(id)) {
189
216
  continue;
190
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;
@@ -72,7 +74,6 @@ export type PostToolStageOutcome = {
72
74
  };
73
75
  labelFailed?: true;
74
76
  };
75
- /** Tool `preTool` → host `pre_tool` → mutate re-parse. */
76
77
  export declare function runPreToolPipeline(args: {
77
78
  tool: {
78
79
  name: string;
@@ -81,6 +82,7 @@ export declare function runPreToolPipeline(args: {
81
82
  };
82
83
  access: ToolAccess;
83
84
  labels?: ToolLabels;
85
+ after?: boolean;
84
86
  preTool?: (input: never, ctx: ToolContext) => StageResult | undefined | Promise<StageResult | undefined>;
85
87
  };
86
88
  input: unknown;
@@ -1,6 +1,7 @@
1
1
  import { labelText } from '../../guardrails/labels.js';
2
2
  import { jsonObjectSchema } from '../json.js';
3
3
  import { runStage, stageEventFields, } from '../stages.js';
4
+ import { splitCallOrder, stepCallIds } from './call-order.js';
4
5
  import { toolEvent } from './events.js';
5
6
  import { operationWireValue } from './operation.js';
6
7
  import { gateDetails, isGateResumeGranted } from './permission.js';
@@ -17,79 +18,80 @@ function defaultToolStageSupport(ctx) {
17
18
  };
18
19
  }
19
20
  /** Tool `preTool` → host `pre_tool` → mutate re-parse. */
21
+ /** What a resume already granted, so `pre_tool` asks it no second time. */
22
+ function resumeApproval(resume) {
23
+ const granted = isGateResumeGranted(resume);
24
+ // why: Permission and sign-in gates come before `pre_tool`, so granting one answers nothing it asked.
25
+ const confirmed = granted && resume?.gateKind !== 'permission' && resume?.gateKind !== 'auth';
26
+ return {
27
+ confirmed,
28
+ // why: An approval skips the tool's own check it already passed — unless the user edited the arguments.
29
+ approvedAsIs: confirmed && resume?.edited === undefined,
30
+ approved: granted && resume?.gateKind !== 'auth',
31
+ };
32
+ }
33
+ function invalidAfterMutate(error, ctx) {
34
+ return {
35
+ ok: false,
36
+ kind: 'failed',
37
+ failure: {
38
+ code: 'invalid_input',
39
+ kind: 'bad_response',
40
+ message: labelText('tool.input_invalid_after_mutate', {}, ctx.profile.labels),
41
+ details: error.flatten(),
42
+ },
43
+ };
44
+ }
20
45
  export async function* runPreToolPipeline(args) {
21
46
  const { tool, ctx, base, stages } = args;
47
+ const { input, names } = splitCallOrder(tool, args.input);
48
+ // why: A resumed call's step has ended, so every call it waited for has settled.
49
+ const after = ctx.resume ? [] : stepCallIds(names, base.callId, stages?.stepCalls);
22
50
  let toolPreTool;
23
- // why: Permission and sign-in gates come before `pre_tool`, so granting one answers nothing it asked.
24
- const confirmed = isGateResumeGranted(ctx.resume) &&
25
- ctx.resume?.gateKind !== 'permission' &&
26
- ctx.resume?.gateKind !== 'auth';
27
- // why: An approval skips the tool's own check it already passed — unless the user edited the arguments.
28
- const approvedAsIs = confirmed && ctx.resume?.edited === undefined;
29
- const approved = isGateResumeGranted(ctx.resume) && ctx.resume?.gateKind !== 'auth';
51
+ const { confirmed, approved, approvedAsIs } = resumeApproval(ctx.resume);
30
52
  if (tool.preTool && !approvedAsIs) {
31
- toolPreTool = (await tool.preTool(args.input, ctx)) ?? undefined;
53
+ toolPreTool = (await tool.preTool(input, ctx)) ?? undefined;
32
54
  }
33
- if (!stages && toolPreTool === undefined) {
34
- return { ok: true, input: args.input };
55
+ if (!stages && toolPreTool === undefined && after.length === 0) {
56
+ return { ok: true, input };
35
57
  }
36
58
  const pre = yield* runPreToolStages({
37
59
  stages: stages ?? defaultToolStageSupport(ctx),
38
60
  toolName: tool.name,
39
61
  callId: base.callId,
40
- input: args.input,
62
+ input,
41
63
  toolPreTool,
42
- details: gateDetails(tool, args.input),
64
+ details: gateDetails(tool, input),
43
65
  confirmed,
44
66
  approved,
45
67
  });
46
68
  if (!pre.ok) {
47
- if (pre.kind === 'gated') {
48
- if ('input' in pre) {
49
- const candidate = pre.input;
50
- const parsed = tool.input.safeParse(plainToolInput(candidate));
51
- if (!parsed.success) {
52
- return {
53
- ok: false,
54
- kind: 'failed',
55
- failure: {
56
- code: 'invalid_input',
57
- kind: 'bad_response',
58
- message: labelText('tool.input_invalid_after_mutate', {}, ctx.profile.labels),
59
- details: parsed.error.flatten(),
60
- },
61
- };
62
- }
63
- pre.gate = {
64
- ...pre.gate,
65
- ...gateDetails(tool, parsed.data),
66
- preparedArguments: jsonObjectSchema.parse(operationWireValue(plainToolInput(candidate))),
67
- };
68
- }
69
- yield stageEventFields('pre_tool', {
70
- callId: base.callId,
71
- toolName: tool.name,
72
- callNotStarted: true,
73
- gate: pre.gate,
74
- });
75
- yield toolEvent(base, { phase: 'gate', gate: pre.gate });
69
+ if (pre.kind !== 'gated')
70
+ return pre;
71
+ if ('input' in pre) {
72
+ const candidate = pre.input;
73
+ const parsed = tool.input.safeParse(plainToolInput(candidate));
74
+ if (!parsed.success)
75
+ return invalidAfterMutate(parsed.error, ctx);
76
+ pre.gate = {
77
+ ...pre.gate,
78
+ ...gateDetails(tool, parsed.data),
79
+ preparedArguments: jsonObjectSchema.parse(operationWireValue(plainToolInput(candidate))),
80
+ };
76
81
  }
82
+ yield stageEventFields('pre_tool', {
83
+ callId: base.callId,
84
+ toolName: tool.name,
85
+ callNotStarted: true,
86
+ gate: pre.gate,
87
+ });
88
+ yield toolEvent(base, { phase: 'gate', gate: pre.gate });
77
89
  return pre;
78
90
  }
79
91
  const reparsed = pre.mutated ? tool.input.safeParse(plainToolInput(pre.input)) : undefined;
80
- if (reparsed && !reparsed.success) {
81
- return {
82
- ok: false,
83
- kind: 'failed',
84
- failure: {
85
- code: 'invalid_input',
86
- kind: 'bad_response',
87
- message: labelText('tool.input_invalid_after_mutate', {}, args.ctx.profile.labels),
88
- details: reparsed.error.flatten(),
89
- },
90
- };
91
- }
92
- const waitFailure = await waitForStepCalls(stages, base.callId, tool.name, pre.waitFor, ctx.profile.labels);
92
+ if (reparsed && !reparsed.success)
93
+ return invalidAfterMutate(reparsed.error, ctx);
94
+ const waitFailure = await waitForStepCalls(stages, base.callId, tool.name, [...(pre.waitFor ?? []), ...after], ctx.profile.labels);
93
95
  if (waitFailure)
94
96
  return { ok: false, kind: 'failed', failure: waitFailure };
95
97
  return { ok: true, input: reparsed ? reparsed.data : pre.input };
@@ -145,7 +147,7 @@ async function* runPreToolStages(args) {
145
147
  }
146
148
  /** Holds the call for the calls its `pre_tool` named; a wait that cannot end fails the call. */
147
149
  async function waitForStepCalls(stages, callId, toolName, waitFor, labels) {
148
- if (!waitFor)
150
+ if (waitFor.length === 0)
149
151
  return undefined;
150
152
  const outcome = stages?.wait
151
153
  ? await stages.wait(callId, waitFor)
@@ -160,6 +162,7 @@ async function waitForStepCalls(stages, callId, toolName, waitFor, labels) {
160
162
  }
161
163
  export async function* runPostToolStages(args) {
162
164
  const { stages, toolName, callId, mutable, ...call } = args;
165
+ stages.bodyEnded?.();
163
166
  const applied = yield* runStage({
164
167
  ...call,
165
168
  stage: 'post_tool',