@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
@@ -0,0 +1,70 @@
1
+ import { z } from 'zod';
2
+ import { TheoremError } from '../../guardrails/error.js';
3
+ import { labelText } from '../../guardrails/labels.js';
4
+ import { toolEvent } from './events.js';
5
+ import { formatToolResult } from './model-text.js';
6
+ import { operationWireValue, toolOperationReplySchema, } from './operation.js';
7
+ const FIELD = 'background';
8
+ /** The `ask` argument, as the model reads it. */
9
+ export function backgroundField() {
10
+ return z.boolean().optional().describe(labelText('tool.background_field'));
11
+ }
12
+ /** The call's input without `background`, and whether the model asked for it. */
13
+ export function splitBackground(tool, input) {
14
+ if (tool?.background !== 'ask' || typeof input !== 'object' || input === null) {
15
+ return { input, asked: false };
16
+ }
17
+ const { [FIELD]: asked, ...rest } = input;
18
+ return { input: rest, asked: asked === true };
19
+ }
20
+ function detachAt(tool, input) {
21
+ const { background } = tool;
22
+ if (background === undefined || background === 'never')
23
+ return undefined;
24
+ if (background === 'always')
25
+ return 'claim';
26
+ if (background === 'ask')
27
+ return splitBackground(tool, input).asked ? 'claim' : undefined;
28
+ return background;
29
+ }
30
+ /** How this call detaches, or `undefined` when it runs inline. */
31
+ export function planDetach(args) {
32
+ const { tool, support, base, labels } = args;
33
+ if (!tool || !support)
34
+ return undefined;
35
+ const at = detachAt(tool, args.input);
36
+ if (at === undefined)
37
+ return undefined;
38
+ return {
39
+ at,
40
+ support,
41
+ trace: support.openTrace(base.callId),
42
+ reply: () => {
43
+ const modelResult = {
44
+ finding: labelText('tool.background_started', { tool: tool.name }, labels),
45
+ };
46
+ const readBack = formatToolResult(modelResult);
47
+ const event = toolEvent(base, { phase: 'background', readBack });
48
+ return toolOperationReplySchema.parse(operationWireValue({ event, replay: { modelResult } }));
49
+ },
50
+ };
51
+ }
52
+ /** A late result needs a coordinator to keep it. */
53
+ export function assertBackgroundCoordinator(service, execution) {
54
+ if (service && !execution?.detach) {
55
+ throw new TheoremError('config', 'A request with a background service needs a coordinator with detach');
56
+ }
57
+ }
58
+ /** A tool that must answer in an open turn cannot detach; only an object input takes `background`. */
59
+ export function assertBackgroundSetting(tool) {
60
+ const { name, background } = tool;
61
+ if (background === undefined || background === 'never')
62
+ return;
63
+ if (tool.answeredBy === 'page') {
64
+ throw new TheoremError('config', `Tool '${name}' sets background, which a tool answered by the page cannot`);
65
+ }
66
+ if (typeof background === 'object' &&
67
+ !(Number.isFinite(background.afterMs) && background.afterMs >= 0)) {
68
+ throw new TheoremError('config', `Tool '${name}' sets background.afterMs, which must be a time in milliseconds`);
69
+ }
70
+ }
@@ -0,0 +1,18 @@
1
+ import { z } from 'zod';
2
+ import type { StepCall } from '../stages.js';
3
+ /** `input` with a field the kernel adds for the model. A tool's own field of that name is refused, never replaced. */
4
+ export declare function withModelField<TIn>(name: string, input: z.ZodType<TIn>, field: string, shape: () => z.ZodType): z.ZodType<TIn>;
5
+ /** `input` with the model's `after` field. */
6
+ export declare function withCallOrder<TIn>(name: string, input: z.ZodType<TIn>): z.ZodType<TIn>;
7
+ /** The call's input without `after`, and the tool names `after` held. */
8
+ export declare function splitCallOrder(tool: {
9
+ after?: boolean;
10
+ }, input: unknown): {
11
+ input: unknown;
12
+ names: readonly string[];
13
+ };
14
+ /**
15
+ * The ids of each named tool's other calls in the step; a name with none stays, to be refused. A
16
+ * call outside a step, as in a live session, has nothing to wait on.
17
+ */
18
+ export declare function stepCallIds(names: readonly string[], callId: string, stepCalls: readonly StepCall[] | undefined): string[];
@@ -0,0 +1,52 @@
1
+ import { z } from 'zod';
2
+ import { TheoremError } from '../../guardrails/error.js';
3
+ import { labelText } from '../../guardrails/labels.js';
4
+ const FIELD = 'after';
5
+ function orderField() {
6
+ return z.array(z.string()).optional().describe(labelText('tool.after_field'));
7
+ }
8
+ /** `input` with a field the kernel adds for the model. A tool's own field of that name is refused, never replaced. */
9
+ export function withModelField(name, input, field, shape) {
10
+ const ordered = (schema) => {
11
+ if (schema instanceof z.ZodObject) {
12
+ if (field in schema.shape) {
13
+ throw new TheoremError('config', `Tool '${name}' sets ${field}, and its input already has a field of that name`);
14
+ }
15
+ return schema.safeExtend({ [field]: shape() });
16
+ }
17
+ if (schema instanceof z.ZodDiscriminatedUnion) {
18
+ const options = schema.options.map(ordered);
19
+ return z.discriminatedUnion(schema.def.discriminator, options);
20
+ }
21
+ if (schema instanceof z.ZodUnion) {
22
+ return z.union(schema.options.map(ordered));
23
+ }
24
+ throw new TheoremError('config', `Tool '${name}' sets ${field}, which needs an object input or a union of objects`);
25
+ };
26
+ return ordered(input);
27
+ }
28
+ /** `input` with the model's `after` field. */
29
+ export function withCallOrder(name, input) {
30
+ return withModelField(name, input, FIELD, orderField);
31
+ }
32
+ /** The call's input without `after`, and the tool names `after` held. */
33
+ export function splitCallOrder(tool, input) {
34
+ if (!tool.after || typeof input !== 'object' || input === null)
35
+ return { input, names: [] };
36
+ const { [FIELD]: names, ...rest } = input;
37
+ return { input: rest, names: names ?? [] };
38
+ }
39
+ /**
40
+ * The ids of each named tool's other calls in the step; a name with none stays, to be refused. A
41
+ * call outside a step, as in a live session, has nothing to wait on.
42
+ */
43
+ export function stepCallIds(names, callId, stepCalls) {
44
+ if (!stepCalls)
45
+ return [];
46
+ return names.flatMap((name) => {
47
+ const ids = stepCalls
48
+ .filter((call) => call.tool === name && call.callId !== callId)
49
+ .map((call) => call.callId);
50
+ return ids.length > 0 ? ids : [name];
51
+ });
52
+ }
@@ -1,4 +1,11 @@
1
1
  import type { TurnEvent } from '../types.js';
2
+ import type { ToolDetach } from './background.js';
2
3
  import type { ToolExecuteSettlement } from './execute.js';
3
4
  import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperationIdentity, type ToolOperationOutcome } from './operation.js';
4
- export declare function coordinateTool(coordinator: ToolExecutionCoordinator | undefined, identity: Omit<ToolOperationIdentity, 'invocationHash'>, invocation: unknown, signal: AbortSignal | undefined, run: (beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>, authorizeReplay?: (outcome: ToolOperationOutcome) => void | Promise<void>): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
5
+ /** What the run gives a body: its stop signal, and how it tells that the body has ended. */
6
+ export interface ToolCallHooks {
7
+ signal: AbortSignal | undefined;
8
+ bodyEnded?: () => void;
9
+ }
10
+ export type ToolRun = (beginBody: ((preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) | undefined, hooks: ToolCallHooks) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
11
+ export declare function coordinateTool(coordinator: ToolExecutionCoordinator | undefined, identity: Omit<ToolOperationIdentity, 'invocationHash'>, invocation: unknown, signal: AbortSignal | undefined, run: ToolRun, authorizeReplay?: (outcome?: ToolOperationOutcome) => void | Promise<void>, detach?: ToolDetach): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
@@ -1,14 +1,75 @@
1
1
  import { errorKind, throwIfAborted } from '../../guardrails/error.js';
2
+ import { settleable } from '../engine/runner/step-order.js';
2
3
  import { jsonObjectSchema } from '../json.js';
3
4
  import { failureEvent } from './events.js';
4
5
  import { formatToolFailureForModel } from './model-text.js';
5
- import { heldOperation, operationBroken, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, unresolvedOperation, } from './operation.js';
6
+ import { heldOperation, operationBroken, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, unresolvedOperation, } from './operation.js';
6
7
  class ReplayedOperation {
7
8
  outcome;
8
9
  constructor(outcome) {
9
10
  this.outcome = outcome;
10
11
  }
11
12
  }
13
+ class ReplayedReply {
14
+ reply;
15
+ constructor(reply) {
16
+ this.reply = reply;
17
+ }
18
+ }
19
+ const FIRED = Symbol('fired');
20
+ const CUT = Symbol('cut');
21
+ /**
22
+ * invariant: A detachable call owns its stop signal. The turn's signal reaches it only until the
23
+ * reply, so a turn that ends leaves the call to the host's `stop`.
24
+ */
25
+ class DetachTrigger {
26
+ at;
27
+ turnSignal;
28
+ controller = new AbortController();
29
+ firing = settleable();
30
+ timer;
31
+ ended = false;
32
+ forward = () => this.controller.abort();
33
+ constructor(at, turnSignal) {
34
+ this.at = at;
35
+ this.turnSignal = turnSignal;
36
+ if (turnSignal?.aborted)
37
+ this.forward();
38
+ turnSignal?.addEventListener('abort', this.forward, { once: true });
39
+ }
40
+ get signal() {
41
+ return this.controller.signal;
42
+ }
43
+ get fired() {
44
+ return this.firing.promise;
45
+ }
46
+ claimed() {
47
+ if (this.ended)
48
+ return;
49
+ if (this.at === 'claim')
50
+ this.firing.resolve(FIRED);
51
+ else
52
+ this.timer = setTimeout(() => this.firing.resolve(FIRED), this.at.afterMs);
53
+ }
54
+ bodyEnded = () => {
55
+ this.ended = true;
56
+ clearTimeout(this.timer);
57
+ };
58
+ abort() {
59
+ this.controller.abort();
60
+ }
61
+ release() {
62
+ this.bodyEnded();
63
+ this.turnSignal?.removeEventListener('abort', this.forward);
64
+ }
65
+ }
66
+ /** A settled failure in place of what the run gave. */
67
+ function failedOutcome(base, effects, failure) {
68
+ const { name, callId, operationId } = base;
69
+ const modelResult = formatToolFailureForModel(failure);
70
+ const event = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
71
+ return toolOperationOutcomeSchema.parse(operationWireValue({ event, effects, replay: { modelResult, failure } }));
72
+ }
12
73
  /** A gate after the claim cannot pause a call that was already sent; only a sign-in can ask for one there. */
13
74
  function gateAfterClaim(gate) {
14
75
  return unresolvedOperation(gate.kind === 'auth' ? 'auth' : 'internal', `The tool asked for a ${gate.kind} gate after it was sent, so its effects are unknown`);
@@ -18,15 +79,20 @@ class CoordinatedExecution {
18
79
  operation;
19
80
  accepted;
20
81
  signal;
82
+ trigger;
21
83
  claim;
22
84
  committed = false;
23
85
  writeFailed = false;
24
86
  terminal;
25
- constructor(coordinator, operation, accepted, signal) {
87
+ stopped;
88
+ cut = settleable();
89
+ graceTimer;
90
+ constructor(coordinator, operation, accepted, signal, trigger) {
26
91
  this.coordinator = coordinator;
27
92
  this.operation = operation;
28
93
  this.accepted = accepted;
29
94
  this.signal = signal;
95
+ this.trigger = trigger;
30
96
  }
31
97
  async beginBody(preparedInput) {
32
98
  throwIfAborted(this.signal);
@@ -37,12 +103,15 @@ class CoordinatedExecution {
37
103
  const result = await this.coordinator.begin(operation);
38
104
  if (result.kind === 'settled')
39
105
  throw new ReplayedOperation(result.outcome);
106
+ if (result.kind === 'background')
107
+ throw new ReplayedReply(result.reply);
40
108
  if (result.kind === 'running' || result.kind === 'uncertain')
41
109
  throw heldOperation(result.kind);
42
110
  if (result.kind !== 'acquired' || typeof result.claimToken !== 'string' || !result.claimToken)
43
111
  throw operationBroken("The tool coordinator's begin returned no claim"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
44
112
  this.claim = { ...operation, claimToken: result.claimToken };
45
113
  throwIfAborted(this.signal);
114
+ this.trigger?.claimed();
46
115
  return this.claim;
47
116
  }
48
117
  observe(event) {
@@ -50,6 +119,7 @@ class CoordinatedExecution {
50
119
  return true;
51
120
  if (event.tool.phase === 'complete' || event.tool.phase === 'error') {
52
121
  this.terminal = { ...event, tool: event.tool };
122
+ this.trigger?.bodyEnded();
53
123
  return false;
54
124
  }
55
125
  if (this.claim && event.tool.phase === 'gate')
@@ -82,13 +152,142 @@ class CoordinatedExecution {
82
152
  };
83
153
  const whole = toolOperationOutcomeSchema.parse(operationWireValue(outcome));
84
154
  const saved = this.withinLimit(whole);
155
+ await this.save(saved);
156
+ return { terminal: saved.event, settlement: saved === whole ? settlement : saved.replay };
157
+ }
158
+ async save(outcome) {
85
159
  this.writeFailed = true;
86
160
  if (this.claim)
87
- await this.coordinator.settle(this.claim, saved);
161
+ await this.coordinator.settle(this.claim, outcome);
88
162
  else
89
- await this.coordinator.settleNotStarted(this.operation, saved);
163
+ await this.coordinator.settleNotStarted(this.operation, outcome);
90
164
  this.committed = true;
91
- return { terminal: saved.event, settlement: saved === whole ? settlement : saved.replay };
165
+ }
166
+ base() {
167
+ const { toolId: name, callId, operationId } = this.operation;
168
+ return { name, callId, operationId };
169
+ }
170
+ /**
171
+ * Saves the reply, and only then gives the turn its answer. A failed save stops the body: the
172
+ * model never read a reply, so the work must not go on.
173
+ */
174
+ async detach(detach, iterator, pending) {
175
+ const { claim, coordinator, trigger } = this;
176
+ if (!claim || !coordinator.detach || !trigger) {
177
+ throw operationBroken('The tool detached with no claim'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
178
+ }
179
+ const reply = detach.reply();
180
+ const done = settleable();
181
+ const handle = {
182
+ ...this.call(),
183
+ stop: (reason, options) => this.stop(reason, options),
184
+ done: done.promise,
185
+ };
186
+ try {
187
+ await coordinator.detach(claim, reply);
188
+ throwIfAborted(this.signal);
189
+ detach.support.service.detached(handle);
190
+ }
191
+ catch (error) {
192
+ this.writeFailed = !this.signal?.aborted;
193
+ trigger.abort();
194
+ throw error;
195
+ }
196
+ trigger.release();
197
+ this.goOn(detach, iterator, pending).finally(() => done.resolve());
198
+ return reply;
199
+ }
200
+ call() {
201
+ const { operationId, callId, toolId } = this.operation;
202
+ return { operationId, callId, toolId };
203
+ }
204
+ stop(reason, options) {
205
+ if (this.committed)
206
+ return;
207
+ this.stopped ??= reason === undefined ? {} : { reason };
208
+ this.trigger?.abort();
209
+ if (options?.graceMs !== undefined && this.graceTimer === undefined) {
210
+ this.graceTimer = setTimeout(() => this.cut.resolve(CUT), options.graceMs);
211
+ }
212
+ }
213
+ /** Reads the run past the reply, passing its events to the host, until the call settles. */
214
+ async goOn(detach, iterator, pending) {
215
+ const { service, project } = detach.support;
216
+ const emit = async (event) => {
217
+ try {
218
+ await service.event(project(event), this.call());
219
+ }
220
+ catch {
221
+ // why: The host's sink failing does not change how the call ends.
222
+ }
223
+ };
224
+ try {
225
+ await this.drain(iterator, pending, emit);
226
+ }
227
+ catch {
228
+ // why: Nothing reads this run; `close` marks a call that did not settle.
229
+ }
230
+ finally {
231
+ clearTimeout(this.graceTimer);
232
+ await this.close().catch(() => { });
233
+ await Promise.resolve(detach.trace.end()).catch(() => { });
234
+ }
235
+ }
236
+ async drain(iterator, first, emit) {
237
+ let pending = first;
238
+ try {
239
+ for (;;) {
240
+ const next = await Promise.race([pending, this.cut.promise]);
241
+ if (next === CUT) {
242
+ // why: The body ignored its stop. It cannot be killed, so nothing reads it again.
243
+ iterator.return({}).catch(() => { });
244
+ return await this.settleStopped(emit);
245
+ }
246
+ if (next.done)
247
+ return await this.settleAfterReply(next.value, emit);
248
+ if (this.observe(next.value))
249
+ await emit(next.value);
250
+ pending = iterator.next();
251
+ }
252
+ }
253
+ catch (error) {
254
+ if (this.writeFailed)
255
+ throw error;
256
+ await this.settleStopped(emit);
257
+ throw error;
258
+ }
259
+ }
260
+ async settleAfterReply(settlement, emit) {
261
+ if (this.stopped)
262
+ return this.settleStopped(emit);
263
+ if (settlement.awaiting) {
264
+ return this.settleFailed({
265
+ code: 'awaiting_after_reply',
266
+ kind: 'internal',
267
+ message: 'The tool asked to wait for a result after its turn ended', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
268
+ }, emit);
269
+ }
270
+ // why: No turn is open, so a post_tool inject or abort has nothing to reach.
271
+ const { pendingInject: _inject, aborted: _aborted, ...kept } = settlement;
272
+ const { terminal } = await this.finish(kept);
273
+ if (terminal)
274
+ await emit(terminal);
275
+ }
276
+ /** A stop with a reason settles the call; a shutdown leaves it for `close` to mark. */
277
+ async settleStopped(emit) {
278
+ const reason = this.stopped?.reason;
279
+ if (reason === undefined)
280
+ return;
281
+ await this.settleFailed({
282
+ code: reason,
283
+ kind: 'cancelled',
284
+ message: `The tool call was stopped: ${reason}`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
285
+ }, emit);
286
+ }
287
+ async settleFailed(failure, emit) {
288
+ const saved = failedOutcome(this.base(), 'unknown', failure);
289
+ await this.save(saved);
290
+ await emit(saved.event);
92
291
  }
93
292
  /**
94
293
  * why: A result the coordinator cannot keep would leave a call that ran unresolved. It settles as
@@ -101,27 +300,33 @@ class CoordinatedExecution {
101
300
  const bytes = new TextEncoder().encode(JSON.stringify(outcome)).byteLength;
102
301
  if (bytes <= limit)
103
302
  return outcome;
104
- const { name, callId, operationId } = outcome.event.tool;
303
+ const { name } = outcome.event.tool;
105
304
  const failure = {
106
305
  code: 'result_too_large',
107
306
  kind: 'bad_response',
108
307
  message: `The result of ${name} is ${bytes} bytes, more than the ${limit} bytes kept for one tool result`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
109
308
  details: { bytes, maxOutcomeBytes: limit },
110
309
  };
111
- const modelResult = formatToolFailureForModel(failure);
112
- const event = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
113
- return toolOperationOutcomeSchema.parse(operationWireValue({ event, effects: outcome.effects, replay: { modelResult, failure } }));
310
+ return failedOutcome(outcome.event.tool, outcome.effects, failure);
114
311
  }
115
312
  replay(error) {
116
313
  const saved = toolOperationOutcomeSchema.parse(operationWireValue(error.outcome));
117
- const { operationId, callId, toolId } = this.operation;
118
- if (saved.event.tool.operationId !== operationId ||
119
- saved.event.tool.callId !== callId ||
120
- saved.event.tool.name !== toolId)
121
- throw operationBroken("The tool coordinator's saved outcome is another operation's"); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
314
+ this.assertOwn(saved, 'outcome');
315
+ this.committed = true;
316
+ return saved;
317
+ }
318
+ replayReply(reply) {
319
+ const saved = toolOperationReplySchema.parse(operationWireValue(reply));
320
+ this.assertOwn(saved, 'reply');
122
321
  this.committed = true;
123
322
  return saved;
124
323
  }
324
+ assertOwn(saved, what) {
325
+ const { operationId, callId, toolId } = this.operation;
326
+ const { tool } = saved.event;
327
+ if (tool.operationId !== operationId || tool.callId !== callId || tool.name !== toolId)
328
+ throw operationBroken(`The tool coordinator's saved ${what} is another operation's`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
329
+ }
125
330
  failure(error) {
126
331
  if (!this.claim || this.committed)
127
332
  return error;
@@ -134,30 +339,63 @@ class CoordinatedExecution {
134
339
  }
135
340
  }
136
341
  }
137
- export async function* coordinateTool(coordinator, identity, invocation, signal, run, authorizeReplay) {
342
+ /** What a saved operation gives the turn, once the replay check has passed. */
343
+ async function replayed(execution, saved, authorizeReplay) {
344
+ if (!authorizeReplay)
345
+ throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
346
+ if (saved instanceof ReplayedReply) {
347
+ const reply = execution.replayReply(saved.reply);
348
+ await authorizeReplay();
349
+ return reply;
350
+ }
351
+ const outcome = execution.replay(saved);
352
+ await authorizeReplay(outcome);
353
+ return outcome;
354
+ }
355
+ function savedResult(known) {
356
+ if (known?.kind === 'background')
357
+ return new ReplayedReply(known.reply);
358
+ if (known?.kind === 'settled')
359
+ return new ReplayedOperation(known.outcome);
360
+ return undefined;
361
+ }
362
+ export async function* coordinateTool(coordinator, identity, invocation, signal, run, authorizeReplay, detach) {
138
363
  if (!coordinator)
139
- return yield* run();
364
+ return yield* run(undefined, { signal });
140
365
  const accepted = jsonObjectSchema.parse(operationWireValue(invocation));
141
366
  const operation = { ...identity, invocationHash: await toolInvocationHash(accepted) };
142
- const execution = new CoordinatedExecution(coordinator, operation, accepted, signal);
367
+ const trigger = detach ? new DetachTrigger(detach.at, signal) : undefined;
368
+ const callSignal = trigger ? trigger.signal : signal;
369
+ const execution = new CoordinatedExecution(coordinator, operation, accepted, callSignal, trigger);
143
370
  throwIfAborted(signal);
144
371
  const existing = await coordinator.lookup(operation);
145
372
  throwIfAborted(signal);
146
373
  if (existing?.kind === 'running' || existing?.kind === 'uncertain')
147
374
  throw heldOperation(existing.kind);
148
- if (existing?.kind === 'settled') {
149
- if (!authorizeReplay)
150
- throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
151
- const saved = execution.replay(new ReplayedOperation(existing.outcome));
152
- await authorizeReplay(saved);
375
+ const known = savedResult(existing);
376
+ if (known) {
377
+ const saved = await replayed(execution, known, authorizeReplay);
153
378
  throwIfAborted(signal);
154
379
  yield saved.event;
155
380
  return saved.replay;
156
381
  }
157
- const iterator = run((input) => execution.beginBody(input));
382
+ const iterator = run((input) => execution.beginBody(input), {
383
+ signal: callSignal,
384
+ ...(trigger ? { bodyEnded: trigger.bodyEnded } : {}),
385
+ });
386
+ let handedOff = false;
158
387
  try {
388
+ let pending = iterator.next();
159
389
  for (;;) {
160
- const next = await iterator.next();
390
+ const next = await (trigger ? Promise.race([pending, trigger.fired]) : pending);
391
+ if (next === FIRED) {
392
+ if (!detach)
393
+ throw operationBroken('The tool detached with no plan'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
394
+ const reply = await execution.detach(detach, iterator, pending);
395
+ handedOff = true;
396
+ yield reply.event;
397
+ return { ...reply.replay };
398
+ }
161
399
  if (next.done) {
162
400
  const { terminal, settlement } = await execution.finish(next.value);
163
401
  if (terminal)
@@ -166,25 +404,27 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
166
404
  }
167
405
  if (execution.observe(next.value))
168
406
  yield next.value;
407
+ pending = iterator.next();
169
408
  }
170
409
  }
171
410
  catch (error) {
172
- if (error instanceof ReplayedOperation) {
173
- if (!authorizeReplay)
174
- throw operationBroken('A settled tool operation has no replay check'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
175
- const saved = execution.replay(error);
176
- await authorizeReplay(saved);
411
+ if (error instanceof ReplayedOperation || error instanceof ReplayedReply) {
412
+ const saved = await replayed(execution, error, authorizeReplay);
177
413
  yield saved.event;
178
414
  return saved.replay;
179
415
  }
180
416
  throw execution.failure(error);
181
417
  }
182
418
  finally {
183
- try {
184
- await execution.close();
185
- }
186
- finally {
187
- await iterator.return({});
419
+ if (!handedOff) {
420
+ trigger?.release();
421
+ try {
422
+ await execution.close();
423
+ }
424
+ finally {
425
+ await iterator.return({});
426
+ await detach?.trace.end();
427
+ }
188
428
  }
189
429
  }
190
430
  }
@@ -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 = {