@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
@@ -42,7 +42,7 @@ export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
42
42
  export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
43
43
  export { createMemoryToolExecution } from './tools/memory-execution.js';
44
44
  export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
45
- export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
45
+ export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './tools/operation.js';
46
46
  export { jsonSchemaFromZod } from './tools/schema.js';
47
47
  export { CredentialRefusedError } from './tools/signed-in-fetch.js';
48
48
  export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
@@ -891,6 +891,18 @@ export const EXTRA_FIELDS = {
891
891
  ...field('boolean', 'Gives the model an after field on this tool: the tools called in the same step that must settle before this call starts. The kernel removes the field before the tool, the stages or a gate read the input. A name with no other call in the step fails the call wait_unknown.'),
892
892
  unset: 'The model sets no order',
893
893
  },
894
+ 'registerTool.background': {
895
+ ...field("'always' | { afterMs: number } | 'ask' | 'never'", "When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }: once the body has run past this time. 'ask': at the hand-off if the model sets the background argument. A turn with no background service runs the tool inline."),
896
+ options: ['never', 'ask', 'always', 'afterMs'],
897
+ optionDescriptions: {
898
+ never: 'The model gets its reply when the body ends.',
899
+ ask: 'The model chooses, call by call, whether to go on without the result.',
900
+ always: 'The model gets its reply at once, and the body goes on after the turn.',
901
+ afterMs: 'The model gets its reply once the body has run past this time.',
902
+ },
903
+ unset: "'never': the model gets its reply when the body ends",
904
+ },
905
+ 'registerTool.background.afterMs': field('number', 'Milliseconds the body runs before the model gets its reply. A body that ends sooner answers in the turn.'),
894
906
  'registerTool.category': field('string', 'A label for grouping tools; nothing reads it yet.'),
895
907
  'registerTool.labels': field('ToolLabels', "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit."),
896
908
  'registerTool.labels.activity': {
@@ -0,0 +1,81 @@
1
+ import { z } from 'zod';
2
+ import { labelText } from '../../guardrails/labels.js';
3
+ import type { SpanHandle, TraceAttributes } from '../../observability/trace-span.js';
4
+ import type { TurnEvent } from '../types.js';
5
+ import { type ToolCallBase } from './events.js';
6
+ import { type ToolExecutionCoordinator, type ToolOperationReply } from './operation.js';
7
+ /** When the model gets its reply: at the hand-off, past a time, if it asks, or when the body ends. */
8
+ export type ToolBackground = 'always' | {
9
+ afterMs: number;
10
+ } | 'ask' | 'never';
11
+ /** The call a detached event belongs to. */
12
+ export interface ToolBackgroundCall {
13
+ operationId: string;
14
+ callId: string;
15
+ toolId: string;
16
+ }
17
+ /** The host's hold on one detached call. */
18
+ export interface ToolBackgroundHandle extends ToolBackgroundCall {
19
+ /**
20
+ * Stops the call. It settles as a `cancelled` failure with `reason` as its code, whatever the
21
+ * body does. With no reason this is a shutdown: the call ends `execution_interrupted`. With
22
+ * `graceMs`, a body that ignores its signal past that time settles anyway.
23
+ */
24
+ stop(reason?: string, options?: {
25
+ graceMs?: number;
26
+ }): void;
27
+ /** Resolves when the call has settled or been marked. */
28
+ done: Promise<void>;
29
+ }
30
+ /** The host's service for detached calls. Without it every tool runs inline. */
31
+ export interface ToolBackgroundService {
32
+ detached(call: ToolBackgroundHandle): void;
33
+ event(event: TurnEvent, call: ToolBackgroundCall): void | Promise<void>;
34
+ }
35
+ /** A detached call's own trace record, joined to its turn through `traceparent`. */
36
+ export interface DetachedToolTrace {
37
+ open: (name: string, attributes: TraceAttributes) => SpanHandle;
38
+ end: () => void | Promise<void>;
39
+ }
40
+ /** The service with what a request adds: its event projection and where a detached trace goes. */
41
+ export interface ToolBackgroundSupport {
42
+ service: ToolBackgroundService;
43
+ project: (event: TurnEvent) => TurnEvent;
44
+ openTrace: (callId: string) => DetachedToolTrace;
45
+ }
46
+ export interface ToolDetach {
47
+ at: 'claim' | {
48
+ afterMs: number;
49
+ };
50
+ support: ToolBackgroundSupport;
51
+ trace: DetachedToolTrace;
52
+ reply: () => ToolOperationReply;
53
+ }
54
+ /** The `ask` argument, as the model reads it. */
55
+ export declare function backgroundField(): z.ZodOptional<z.ZodBoolean>;
56
+ /** The call's input without `background`, and whether the model asked for it. */
57
+ export declare function splitBackground(tool: {
58
+ background?: ToolBackground;
59
+ } | undefined, input: unknown): {
60
+ input: unknown;
61
+ asked: boolean;
62
+ };
63
+ /** How this call detaches, or `undefined` when it runs inline. */
64
+ export declare function planDetach(args: {
65
+ tool: {
66
+ background?: ToolBackground;
67
+ name: string;
68
+ } | undefined;
69
+ input: unknown;
70
+ support: ToolBackgroundSupport | undefined;
71
+ base: ToolCallBase;
72
+ labels: Parameters<typeof labelText>[2];
73
+ }): ToolDetach | undefined;
74
+ /** A late result needs a coordinator to keep it. */
75
+ export declare function assertBackgroundCoordinator(service: ToolBackgroundService | undefined, execution: ToolExecutionCoordinator | undefined): void;
76
+ /** A tool that must answer in an open turn cannot detach; only an object input takes `background`. */
77
+ export declare function assertBackgroundSetting(tool: {
78
+ name: string;
79
+ background?: ToolBackground;
80
+ answeredBy?: string;
81
+ }): void;
@@ -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
+ }
@@ -1,6 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import type { StepCall } from '../stages.js';
3
- /** `input` with the model's `after` field. A tool's own `after` is refused, never replaced. */
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. */
4
6
  export declare function withCallOrder<TIn>(name: string, input: z.ZodType<TIn>): z.ZodType<TIn>;
5
7
  /** The call's input without `after`, and the tool names `after` held. */
6
8
  export declare function splitCallOrder(tool: {
@@ -5,14 +5,14 @@ const FIELD = 'after';
5
5
  function orderField() {
6
6
  return z.array(z.string()).optional().describe(labelText('tool.after_field'));
7
7
  }
8
- /** `input` with the model's `after` field. A tool's own `after` is refused, never replaced. */
9
- export function withCallOrder(name, input) {
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
10
  const ordered = (schema) => {
11
11
  if (schema instanceof z.ZodObject) {
12
- if (FIELD in schema.shape) {
13
- throw new TheoremError('config', `Tool '${name}' sets after, and its input already has a field of that name`);
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
14
  }
15
- return schema.safeExtend({ [FIELD]: orderField() });
15
+ return schema.safeExtend({ [field]: shape() });
16
16
  }
17
17
  if (schema instanceof z.ZodDiscriminatedUnion) {
18
18
  const options = schema.options.map(ordered);
@@ -21,10 +21,14 @@ export function withCallOrder(name, input) {
21
21
  if (schema instanceof z.ZodUnion) {
22
22
  return z.union(schema.options.map(ordered));
23
23
  }
24
- throw new TheoremError('config', `Tool '${name}' sets after, which needs an object input or a union of objects`);
24
+ throw new TheoremError('config', `Tool '${name}' sets ${field}, which needs an object input or a union of objects`);
25
25
  };
26
26
  return ordered(input);
27
27
  }
28
+ /** `input` with the model's `after` field. */
29
+ export function withCallOrder(name, input) {
30
+ return withModelField(name, input, FIELD, orderField);
31
+ }
28
32
  /** The call's input without `after`, and the tool names `after` held. */
29
33
  export function splitCallOrder(tool, input) {
30
34
  if (!tool.after || typeof input !== 'object' || input === null)
@@ -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
  }