@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.
- package/README.md +5 -4
- package/esm/mod.d.ts +6 -3
- package/esm/mod.js +3 -1
- package/esm/src/cli/commands/bench.js +4 -10
- package/esm/src/cli/commands/profile.js +4 -1
- package/esm/src/guardrails/labels.d.ts +1 -1
- package/esm/src/guardrails/labels.js +9 -0
- package/esm/src/interface/blocks.js +19 -0
- package/esm/src/interface/from-profile.d.ts +2 -2
- package/esm/src/interface/from-profile.js +7 -0
- package/esm/src/interface/history.d.ts +2 -2
- package/esm/src/interface/history.js +7 -4
- package/esm/src/interface/mod.d.ts +2 -2
- package/esm/src/interface/mod.js +1 -1
- package/esm/src/interface/profile-interface.js +14 -4
- package/esm/src/interface/tool-calls.d.ts +3 -3
- package/esm/src/interface/tool-calls.js +5 -8
- package/esm/src/interface/tool-invoke.d.ts +3 -1
- package/esm/src/interface/tool-invoke.js +6 -1
- package/esm/src/interface/types.d.ts +7 -5
- package/esm/src/kernel/api-catalog.js +13 -5
- package/esm/src/kernel/auth/oauth.js +3 -1
- package/esm/src/kernel/engine/background.d.ts +7 -0
- package/esm/src/kernel/engine/background.js +18 -0
- package/esm/src/kernel/engine/runner/mod.js +24 -1
- package/esm/src/kernel/engine/runner/state.d.ts +4 -0
- package/esm/src/kernel/engine/runner/state.js +1 -0
- package/esm/src/kernel/engine/runner/step-order.d.ts +8 -0
- package/esm/src/kernel/engine/runner/step-order.js +1 -1
- package/esm/src/kernel/engine/runner/steps.js +1 -0
- package/esm/src/kernel/engine/session/mod.d.ts +2 -0
- package/esm/src/kernel/engine/session/mod.js +20 -2
- package/esm/src/kernel/engine/session/session-trace.js +1 -0
- package/esm/src/kernel/mod.d.ts +6 -3
- package/esm/src/kernel/mod.js +3 -1
- package/esm/src/kernel/profile-presence.js +1 -0
- package/esm/src/kernel/profile-scope.js +23 -21
- package/esm/src/kernel/protocols/protocol.d.ts +1 -1
- package/esm/src/kernel/protocols/protocol.js +1 -0
- package/esm/src/kernel/registry/catalog.js +4 -1
- package/esm/src/kernel/registry/ingress.d.ts +3 -1
- package/esm/src/kernel/registry/ingress.js +12 -1
- package/esm/src/kernel/registry/profile-outputs.js +2 -1
- package/esm/src/kernel/registry/profiles.d.ts +12 -2
- package/esm/src/kernel/registry/profiles.js +37 -7
- package/esm/src/kernel/registry/resolve.js +9 -5
- package/esm/src/kernel/registry/system-prompt.d.ts +6 -1
- package/esm/src/kernel/registry/system-prompt.js +20 -13
- package/esm/src/kernel/schema.d.ts +1 -1
- package/esm/src/kernel/schema.js +24 -8
- package/esm/src/kernel/system-lines.d.ts +22 -0
- package/esm/src/kernel/system-lines.js +162 -0
- package/esm/src/kernel/tools/activity-label.d.ts +15 -0
- package/esm/src/kernel/tools/activity-label.js +12 -7
- package/esm/src/kernel/tools/agent.js +1 -1
- package/esm/src/kernel/tools/background.d.ts +81 -0
- package/esm/src/kernel/tools/background.js +70 -0
- package/esm/src/kernel/tools/call-order.d.ts +18 -0
- package/esm/src/kernel/tools/call-order.js +52 -0
- package/esm/src/kernel/tools/coordinate.d.ts +8 -1
- package/esm/src/kernel/tools/coordinate.js +274 -34
- package/esm/src/kernel/tools/execute.d.ts +2 -0
- package/esm/src/kernel/tools/execute.js +17 -4
- package/esm/src/kernel/tools/invoke.js +40 -13
- package/esm/src/kernel/tools/memory-execution.js +10 -1
- package/esm/src/kernel/tools/operation.d.ts +21 -0
- package/esm/src/kernel/tools/operation.js +19 -10
- package/esm/src/kernel/tools/registry.js +28 -6
- package/esm/src/kernel/tools/resolve.d.ts +4 -2
- package/esm/src/kernel/tools/resolve.js +34 -7
- package/esm/src/kernel/tools/run.d.ts +2 -2
- package/esm/src/kernel/tools/run.js +4 -1
- package/esm/src/kernel/tools/stage-run.d.ts +3 -1
- package/esm/src/kernel/tools/stage-run.js +58 -55
- package/esm/src/kernel/tools/types.d.ts +10 -0
- package/esm/src/kernel/turn-events.d.ts +8 -1
- package/esm/src/kernel/turn-events.js +2 -0
- package/esm/src/kernel/types.d.ts +39 -4
- package/esm/src/observability/trace-catalog.js +3 -0
- package/esm/src/providers/google/interactions/steps.js +14 -3
- package/esm/src/providers/mod.d.ts +2 -0
- package/esm/src/providers/mod.js +1 -0
- package/esm/src/providers/open-ai/protocol.js +8 -4
- package/esm/src/providers/openrouter/protocol.d.ts +26 -0
- package/esm/src/providers/openrouter/protocol.js +58 -2
- package/esm/src/providers/openrouter/provider.d.ts +1 -1
- package/esm/src/providers/openrouter/provider.js +3 -1
- package/esm/src/providers/openrouter/transcriptions-protocol.d.ts +10 -0
- package/esm/src/providers/openrouter/transcriptions-protocol.js +87 -0
- package/package.json +1 -1
- package/esm/src/kernel/registry/system-role.d.ts +0 -3
- 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
|
-
|
|
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
|
-
|
|
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,
|
|
161
|
+
await this.coordinator.settle(this.claim, outcome);
|
|
88
162
|
else
|
|
89
|
-
await this.coordinator.settleNotStarted(this.operation,
|
|
163
|
+
await this.coordinator.settleNotStarted(this.operation, outcome);
|
|
90
164
|
this.committed = true;
|
|
91
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
|
860
|
+
operationId,
|
|
852
861
|
callId: args.callId,
|
|
853
862
|
profileId: args.profile.id,
|
|
854
863
|
toolId: args.name,
|
|
@@ -857,8 +866,11 @@ export async function* executeRegisteredTool(args) {
|
|
|
857
866
|
resume: args.ctx.resume,
|
|
858
867
|
snapshot: args.snapshot,
|
|
859
868
|
context: args.invocation,
|
|
860
|
-
}, args.ctx.signal, (beginBody) => executeTracedTool({
|
|
869
|
+
}, args.ctx.signal, (beginBody, hooks) => executeTracedTool({
|
|
861
870
|
...args,
|
|
871
|
+
...(detach ? { openSpan: detach.trace.open } : {}),
|
|
872
|
+
ctx: { ...args.ctx, signal: hooks.signal },
|
|
873
|
+
...(args.stages ? { stages: { ...args.stages, ...hooks } } : {}),
|
|
862
874
|
beginBody: async (input) => {
|
|
863
875
|
const claim = (await beginBody?.(input)) ?? (await args.beginBody?.(input));
|
|
864
876
|
args.onDispatch?.();
|
|
@@ -871,7 +883,7 @@ export async function* executeRegisteredTool(args) {
|
|
|
871
883
|
name: args.name,
|
|
872
884
|
resume: args.ctx.resume,
|
|
873
885
|
snapshot: args.snapshot,
|
|
874
|
-
}));
|
|
886
|
+
}), detach);
|
|
875
887
|
}
|
|
876
888
|
async function* executeTracedTool(args) {
|
|
877
889
|
const tool = args.tools.get(args.name);
|
|
@@ -916,7 +928,8 @@ async function* executeTracedTool(args) {
|
|
|
916
928
|
}
|
|
917
929
|
}
|
|
918
930
|
async function* runRegisteredTool(args, tool) {
|
|
919
|
-
const { profile, name,
|
|
931
|
+
const { profile, name, callId, ctx, snapshot, stages } = args;
|
|
932
|
+
const { input } = splitBackground(tool?.type === 'builtin' ? undefined : tool, args.input);
|
|
920
933
|
const safeInput = plainToolInput(input);
|
|
921
934
|
const operationId = ctx.operationId ?? crypto.randomUUID();
|
|
922
935
|
const base = {
|