@theoremjs/agents 0.3.4-next.715.geef22fd → 0.3.4-next.721.g7ff150a
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/esm/src/kernel/engine/call-trace.d.ts +3 -1
- package/esm/src/kernel/engine/call-trace.js +3 -2
- package/esm/src/kernel/engine/decision.js +3 -0
- package/esm/src/kernel/engine/embedding.js +3 -0
- package/esm/src/kernel/engine/runner/mod.js +3 -1
- package/esm/src/kernel/engine/session/mod.d.ts +0 -5
- package/esm/src/kernel/engine/session/mod.js +6 -22
- package/esm/src/kernel/engine/session/session-trace.js +3 -3
- package/esm/src/kernel/engine/turn-trace.d.ts +6 -2
- package/esm/src/kernel/engine/turn-trace.js +17 -5
- package/esm/src/kernel/profile-scope.js +2 -2
- package/esm/src/kernel/registry/profiles.d.ts +1 -1
- package/esm/src/kernel/tools/coordinate.d.ts +2 -1
- package/esm/src/kernel/tools/coordinate.js +9 -3
- package/esm/src/kernel/tools/execute.js +9 -0
- package/esm/src/kernel/tools/invoke.js +5 -1
- package/esm/src/kernel/tools/stage-run.d.ts +3 -1
- package/esm/src/kernel/types.d.ts +55 -106
- package/package.json +1 -1
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
import { resolveTraceWriter } from '../../observability/policy.js';
|
|
2
2
|
import { type SpanHandle, type SpanOptions } from '../../observability/trace-span.js';
|
|
3
|
+
import type { TurnTraceLink } from '../types.js';
|
|
3
4
|
interface TracedCall {
|
|
4
5
|
/** The root span's name, such as `decide <apiId>`. */
|
|
5
6
|
name: string;
|
|
6
7
|
attributes: SpanOptions['attributes'];
|
|
7
8
|
traceparent?: string;
|
|
9
|
+
links?: readonly TurnTraceLink[];
|
|
8
10
|
/** Host metadata kept on the record. */
|
|
9
11
|
metadata?: Record<string, unknown>;
|
|
10
12
|
/** Where the record goes and how it is cleaned: the profile's settings, or the caller's sink. */
|
|
@@ -14,6 +16,6 @@ interface TracedCall {
|
|
|
14
16
|
* One request that isn't a turn, under a root span: ended OK when `run` returns, with the
|
|
15
17
|
* exception when it throws, and written either way. A failed write never changes the outcome.
|
|
16
18
|
*/
|
|
17
|
-
declare function tracedCall<T>({ name, attributes, traceparent, metadata, writer }: TracedCall, run: (root: SpanHandle) => Promise<T>): Promise<T>;
|
|
19
|
+
declare function tracedCall<T>({ name, attributes, traceparent, links, metadata, writer }: TracedCall, run: (root: SpanHandle) => Promise<T>): Promise<T>;
|
|
18
20
|
export type { TracedCall };
|
|
19
21
|
export { tracedCall };
|
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
import { resolveTraceWriter } from '../../observability/policy.js';
|
|
2
2
|
import { writeSpans } from '../../observability/trace.js';
|
|
3
3
|
import { startTrace } from '../../observability/trace-span.js';
|
|
4
|
-
import { endThrownSpan } from './turn-trace.js';
|
|
4
|
+
import { endThrownSpan, traceLinks } from './turn-trace.js';
|
|
5
5
|
/**
|
|
6
6
|
* One request that isn't a turn, under a root span: ended OK when `run` returns, with the
|
|
7
7
|
* exception when it throws, and written either way. A failed write never changes the outcome.
|
|
8
8
|
*/
|
|
9
|
-
async function tracedCall({ name, attributes, traceparent, metadata, writer }, run) {
|
|
9
|
+
async function tracedCall({ name, attributes, traceparent, links, metadata, writer }, run) {
|
|
10
10
|
const tree = startTrace(name, {
|
|
11
11
|
kind: 'CLIENT',
|
|
12
12
|
attributes,
|
|
13
|
+
links: traceLinks(links),
|
|
13
14
|
...(traceparent ? { traceparent } : {}),
|
|
14
15
|
});
|
|
15
16
|
const { sink, policy } = resolveTraceWriter(writer);
|
|
@@ -7,6 +7,7 @@ import { soleModelId } from '../registry/sole-model.js';
|
|
|
7
7
|
import { isRecord } from '../util/record.js';
|
|
8
8
|
import { tracedCall } from './call-trace.js';
|
|
9
9
|
import { referencedAssets } from './decision-references.js';
|
|
10
|
+
import { runIdentity } from './turn-trace.js';
|
|
10
11
|
/** Each decision failure code, and the error kind it reads as. */
|
|
11
12
|
const DECISION_ERROR_KINDS = {
|
|
12
13
|
invalid_config: 'config',
|
|
@@ -365,6 +366,7 @@ function decisionSpanAttributes(profile, modelId, binding, request, assets, oper
|
|
|
365
366
|
...(operation ? { 'gen_ai.operation.name': operation } : {}),
|
|
366
367
|
'gen_ai.provider.name': binding.provider,
|
|
367
368
|
'gen_ai.agent.name': profile.id,
|
|
369
|
+
...runIdentity(request),
|
|
368
370
|
'gen_ai.request.model': binding.apiId,
|
|
369
371
|
'theorem.model.id': modelId,
|
|
370
372
|
'theorem.decision.contract': profile.decision.contract,
|
|
@@ -465,6 +467,7 @@ export async function runDecisionInRegistry(registry, request, options) {
|
|
|
465
467
|
name: operation ? `${operation} ${binding.apiId}` : binding.apiId,
|
|
466
468
|
attributes: decisionSpanAttributes(profile, modelId, binding, request, sent.assets, operation),
|
|
467
469
|
traceparent: request.traceparent,
|
|
470
|
+
links: request.links,
|
|
468
471
|
metadata: request.metadata,
|
|
469
472
|
writer: {
|
|
470
473
|
override: options.sink,
|
|
@@ -4,6 +4,7 @@ import { guardedCall } from '../provider-runtime.js';
|
|
|
4
4
|
import { attachmentsRefused, base64Bytes } from '../registry/attachments.js';
|
|
5
5
|
import { embeddingMediaIssues, embeddingRules } from '../registry/embedding-rules.js';
|
|
6
6
|
import { tracedCall } from './call-trace.js';
|
|
7
|
+
import { runIdentity } from './turn-trace.js';
|
|
7
8
|
function requireEmbeddingProfile(registry, id) {
|
|
8
9
|
const profile = registry.profiles.get(id);
|
|
9
10
|
if (profile.type !== 'embedding')
|
|
@@ -92,12 +93,14 @@ export async function runEmbeddingInRegistry(registry, request, options = {}) {
|
|
|
92
93
|
...(operation ? { 'gen_ai.operation.name': operation } : {}),
|
|
93
94
|
'gen_ai.provider.name': binding.provider,
|
|
94
95
|
'gen_ai.agent.name': profile.id,
|
|
96
|
+
...runIdentity(request),
|
|
95
97
|
'gen_ai.request.model': binding.apiId,
|
|
96
98
|
'theorem.model.id': modelId,
|
|
97
99
|
'theorem.embedding.inputs': inputs.length,
|
|
98
100
|
...(request.task ? { 'theorem.embedding.task': request.task } : {}),
|
|
99
101
|
},
|
|
100
102
|
traceparent: request.traceparent,
|
|
103
|
+
links: request.links,
|
|
101
104
|
metadata: request.metadata,
|
|
102
105
|
writer: {
|
|
103
106
|
override: options.sink,
|
|
@@ -605,7 +605,9 @@ async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
|
|
|
605
605
|
const turnReq = {
|
|
606
606
|
profile: req.profile,
|
|
607
607
|
input: {},
|
|
608
|
-
|
|
608
|
+
conversationId: req.conversationId,
|
|
609
|
+
projectId: req.projectId,
|
|
610
|
+
links: req.links,
|
|
609
611
|
};
|
|
610
612
|
const tree = startTrace(`invoke_agent ${req.profile}`, {
|
|
611
613
|
...turnSpanOptions(turnReq),
|
|
@@ -1,15 +1,10 @@
|
|
|
1
1
|
import type { TraceSink } from '../../../observability/trace-sink.js';
|
|
2
2
|
import type { ProviderHostOptions } from '../../protocols/runtime.js';
|
|
3
3
|
import type { KernelRegistry } from '../../registry/kernel-registry.js';
|
|
4
|
-
import { type ToolBackgroundService } from '../../tools/background.js';
|
|
5
|
-
import { type PageToolExecution, type ToolExecutionCoordinator } from '../../tools/operation.js';
|
|
6
4
|
import type { KeyVault, LiveSession, SessionRequest } from '../../types.js';
|
|
7
5
|
export type { LiveSession, SessionRequest };
|
|
8
6
|
/** Options for opening a live session: the key vault, a provider's own settings, a WebSocket opener, how long a gated call waits for its decision, and the sign-in gate policy. */
|
|
9
7
|
export interface RunSessionOptions extends ProviderHostOptions {
|
|
10
|
-
execution?: ToolExecutionCoordinator;
|
|
11
|
-
background?: ToolBackgroundService;
|
|
12
|
-
pageExecution?: PageToolExecution;
|
|
13
8
|
/** The host's keys by slot; the session uses the slots its profile names. */
|
|
14
9
|
vault?: KeyVault;
|
|
15
10
|
/**
|
|
@@ -114,23 +114,7 @@ function sessionSnapshotWithinAllow(profile, snapshot) {
|
|
|
114
114
|
return cloneTurnToolSnapshot(snapshot);
|
|
115
115
|
}
|
|
116
116
|
function toTurnRequest(req) {
|
|
117
|
-
return {
|
|
118
|
-
profile: req.profile,
|
|
119
|
-
providerState: req.providerState,
|
|
120
|
-
system: req.system,
|
|
121
|
-
builtInArgs: req.builtInArgs,
|
|
122
|
-
path: req.path,
|
|
123
|
-
conditions: req.conditions,
|
|
124
|
-
sessionPermissions: req.sessionPermissions,
|
|
125
|
-
signal: req.signal,
|
|
126
|
-
metadata: req.metadata,
|
|
127
|
-
host: req.host,
|
|
128
|
-
input: {
|
|
129
|
-
text: '',
|
|
130
|
-
history: req.history,
|
|
131
|
-
slots: req.slots,
|
|
132
|
-
},
|
|
133
|
-
};
|
|
117
|
+
return { ...req, input: { text: '', history: req.history, slots: req.slots } };
|
|
134
118
|
}
|
|
135
119
|
/**
|
|
136
120
|
* The prompt the session opens with: the greeting on a new call, the resume prompt when the
|
|
@@ -1139,8 +1123,8 @@ async function openTracedSession(registry, req, options, trace) {
|
|
|
1139
1123
|
if (refusal)
|
|
1140
1124
|
throw refusal;
|
|
1141
1125
|
throwIfAborted(safe.signal);
|
|
1142
|
-
assertBackgroundCoordinator(
|
|
1143
|
-
const { profile, generation: gen0 } = resolveTurnInRegistry(registry,
|
|
1126
|
+
assertBackgroundCoordinator(req.background, req.execution);
|
|
1127
|
+
const { profile, generation: gen0 } = resolveTurnInRegistry(registry, safe);
|
|
1144
1128
|
assertLiveProfile(profile);
|
|
1145
1129
|
const openingContext = req.context ? readSessionContext(profile, req.context) : undefined;
|
|
1146
1130
|
if (req.snapshot) {
|
|
@@ -1181,9 +1165,9 @@ async function openTracedSession(registry, req, options, trace) {
|
|
|
1181
1165
|
const connection = await openRegisteredLiveSession(definition, { ...binding }, completeReq, options, req.providerState, profile.providerContinuation);
|
|
1182
1166
|
trace.setup(connection.setup);
|
|
1183
1167
|
return buildLiveSession({
|
|
1184
|
-
execution:
|
|
1185
|
-
...(
|
|
1186
|
-
pageExecution:
|
|
1168
|
+
execution: req.execution,
|
|
1169
|
+
...(req.background ? { background: req.background } : {}),
|
|
1170
|
+
pageExecution: req.pageExecution,
|
|
1187
1171
|
tools: registry.tools,
|
|
1188
1172
|
profile,
|
|
1189
1173
|
canary: generation.canary,
|
|
@@ -8,7 +8,7 @@ import { KEY_FALLBACK_ROW } from '../../../providers/types.js';
|
|
|
8
8
|
import { base64ToBytes, bytesToBase64 } from '../../util/base64.js';
|
|
9
9
|
import { asRecord } from '../record.js';
|
|
10
10
|
import { callTokensEvent, heldAfter, observeCallEvent, startCallUsage, } from '../runner/usage.js';
|
|
11
|
-
import { endThrownSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, startCallTrace, traceLinks, usageAttributes, } from '../turn-trace.js';
|
|
11
|
+
import { endThrownSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, runChoice, runIdentity, startCallTrace, traceLinks, usageAttributes, } from '../turn-trace.js';
|
|
12
12
|
import { sumTokens } from '../usage.js';
|
|
13
13
|
/** Events that are the model's output: they mark a response as answering. */
|
|
14
14
|
const OUTPUT_EVENTS = new Set(['text', 'thought', 'media', 'tool']);
|
|
@@ -489,11 +489,11 @@ function startLiveTrace(req, profile, sinkOverride) {
|
|
|
489
489
|
});
|
|
490
490
|
const identity = {
|
|
491
491
|
'gen_ai.agent.name': req.profile,
|
|
492
|
-
...
|
|
492
|
+
...runIdentity(req),
|
|
493
493
|
};
|
|
494
494
|
const tree = startTrace(`invoke_agent ${req.profile}`, {
|
|
495
495
|
kind: 'INTERNAL',
|
|
496
|
-
attributes: { 'gen_ai.operation.name': 'invoke_agent', ...identity },
|
|
496
|
+
attributes: { 'gen_ai.operation.name': 'invoke_agent', ...identity, ...runChoice(req) },
|
|
497
497
|
links: traceLinks(req.links),
|
|
498
498
|
...(req.traceparent ? { traceparent: req.traceparent } : {}),
|
|
499
499
|
});
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { GuardrailEvent, GuardrailStage, TrustLevel } from '../../guardrails/types.js';
|
|
2
2
|
import { type SpanHandle, type SpanLinkInput, type SpanOptions, type TraceAttributes, type TraceAttributeValue } from '../../observability/trace-span.js';
|
|
3
3
|
import type { ToolFailure } from '../tools/types.js';
|
|
4
|
-
import type { InteractionPart, ModelBinding, ModelEvent, ModelRequest, ProviderTransport, TurnEvent, TurnRequest, TurnStop, TurnTokens, TurnTraceLink } from '../types.js';
|
|
4
|
+
import type { InteractionPart, ModelBinding, ModelChoice, ModelEvent, ModelRequest, ProviderTransport, RunControls, TurnEvent, TurnRequest, TurnStop, TurnTokens, TurnTraceLink } from '../types.js';
|
|
5
5
|
import type { CallUsage } from './runner/usage.js';
|
|
6
6
|
type TracePart = {
|
|
7
7
|
[key: string]: TraceAttributeValue;
|
|
@@ -101,6 +101,10 @@ declare function startCallTrace(open: (name: string, options: SpanOptions) => Sp
|
|
|
101
101
|
attempt?: number;
|
|
102
102
|
}): CallTrace;
|
|
103
103
|
declare function traceLinks(links: readonly TurnTraceLink[] | undefined): SpanLinkInput[];
|
|
104
|
+
/** What a run's request says about the run, on its root span. */
|
|
105
|
+
declare function runIdentity(req: Pick<RunControls, 'conversationId' | 'projectId'>): TraceAttributes;
|
|
106
|
+
/** The pick a run's request made; absent when it took the defaults. */
|
|
107
|
+
declare function runChoice(req: ModelChoice): TraceAttributes;
|
|
104
108
|
declare function turnSpanOptions(req: TurnRequest): SpanOptions;
|
|
105
109
|
interface TurnEnd {
|
|
106
110
|
seen: readonly TurnEvent[];
|
|
@@ -118,4 +122,4 @@ interface TurnEnd {
|
|
|
118
122
|
*/
|
|
119
123
|
declare function endTurnSpan(root: SpanHandle, end: TurnEnd): void;
|
|
120
124
|
export type { CallEnd, CallTrace, GuardrailCheck, SentToolCall, StreamCheck, TracePart, TurnEnd };
|
|
121
|
-
export { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, recordException, startCallTrace, toolArgumentsText, traceLinks, tracePart, turnSpanOptions, urlAttributes, usageAttributes, };
|
|
125
|
+
export { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, recordException, runChoice, runIdentity, startCallTrace, toolArgumentsText, traceLinks, tracePart, turnSpanOptions, urlAttributes, usageAttributes, };
|
|
@@ -795,17 +795,29 @@ function traceLinks(links) {
|
|
|
795
795
|
},
|
|
796
796
|
}));
|
|
797
797
|
}
|
|
798
|
+
/** What a run's request says about the run, on its root span. */
|
|
799
|
+
function runIdentity(req) {
|
|
800
|
+
return {
|
|
801
|
+
...optional('gen_ai.conversation.id', req.conversationId),
|
|
802
|
+
...optional('theorem.project.id', req.projectId),
|
|
803
|
+
};
|
|
804
|
+
}
|
|
805
|
+
/** The pick a run's request made; absent when it took the defaults. */
|
|
806
|
+
function runChoice(req) {
|
|
807
|
+
return {
|
|
808
|
+
...optional('theorem.request.effort', req.effort),
|
|
809
|
+
...optional('theorem.request.model_select', req.model),
|
|
810
|
+
};
|
|
811
|
+
}
|
|
798
812
|
function turnSpanOptions(req) {
|
|
799
813
|
return {
|
|
800
814
|
kind: 'INTERNAL',
|
|
801
815
|
attributes: {
|
|
802
816
|
'gen_ai.operation.name': 'invoke_agent',
|
|
803
817
|
'gen_ai.agent.name': req.profile,
|
|
804
|
-
...
|
|
818
|
+
...runIdentity(req),
|
|
805
819
|
'gen_ai.input.messages': turnInputMessages(req.input),
|
|
806
|
-
...
|
|
807
|
-
...optional('theorem.request.model_select', req.model),
|
|
808
|
-
...optional('theorem.project.id', req.projectId),
|
|
820
|
+
...runChoice(req),
|
|
809
821
|
},
|
|
810
822
|
links: traceLinks(req.links),
|
|
811
823
|
};
|
|
@@ -851,4 +863,4 @@ function endTurnSpan(root, end) {
|
|
|
851
863
|
root.end(stop && !FINISHED_STOPS.has(stop) ? { code: 'UNSET' } : { code: 'OK' });
|
|
852
864
|
}
|
|
853
865
|
}
|
|
854
|
-
export { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, recordException, startCallTrace, toolArgumentsText, traceLinks, tracePart, turnSpanOptions, urlAttributes, usageAttributes, };
|
|
866
|
+
export { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, optional, recordException, runChoice, runIdentity, startCallTrace, toolArgumentsText, traceLinks, tracePart, turnSpanOptions, urlAttributes, usageAttributes, };
|
|
@@ -109,8 +109,8 @@ export const PROFILE_FIELD_SCOPE = {
|
|
|
109
109
|
reason: 'a host profile runs no model and a decision declares exactly one',
|
|
110
110
|
},
|
|
111
111
|
'profile.maxSteps': {
|
|
112
|
-
profileTypes:
|
|
113
|
-
reason: 'only
|
|
112
|
+
profileTypes: ['text', 'image', 'speech'],
|
|
113
|
+
reason: 'only turns take tool-loop steps; a live call has no one reply to count them against',
|
|
114
114
|
},
|
|
115
115
|
decision: { profileTypes: ['decision'], reason: 'only decision profiles carry a contract' },
|
|
116
116
|
image: { profileTypes: ['image'], reason: 'only image profiles generate images' },
|
|
@@ -56,7 +56,7 @@ export type TranscriptionProfileDefinition = Omit<ProfileDefinitionBase, 'identi
|
|
|
56
56
|
};
|
|
57
57
|
};
|
|
58
58
|
/** What a host writes to define a live profile. */
|
|
59
|
-
export type LiveProfileDefinition = ProfileDefinitionBase & {
|
|
59
|
+
export type LiveProfileDefinition = Omit<ProfileDefinitionBase, 'maxSteps'> & {
|
|
60
60
|
type: 'live';
|
|
61
61
|
live: NonNullable<LiveProfile['live']>;
|
|
62
62
|
inputs?: LiveProfile['inputs'];
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { TurnEvent } from '../types.js';
|
|
1
|
+
import type { TurnEvent, TurnTokens } from '../types.js';
|
|
2
2
|
import type { ToolDetach } from './background.js';
|
|
3
3
|
import type { ToolExecuteSettlement } from './execute.js';
|
|
4
4
|
import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperationIdentity, type ToolOperationOutcome } from './operation.js';
|
|
@@ -6,6 +6,7 @@ import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperat
|
|
|
6
6
|
export interface ToolCallHooks {
|
|
7
7
|
signal: AbortSignal | undefined;
|
|
8
8
|
bodyEnded?: () => void;
|
|
9
|
+
spent?: (tokens: TurnTokens) => void;
|
|
9
10
|
}
|
|
10
11
|
export type ToolRun = (beginBody: ((preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) | undefined, hooks: ToolCallHooks) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
|
|
11
12
|
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>;
|
|
@@ -64,10 +64,11 @@ class DetachTrigger {
|
|
|
64
64
|
}
|
|
65
65
|
}
|
|
66
66
|
/** A settled failure in place of what the run gave. */
|
|
67
|
-
function failedOutcome(base, effects, failure) {
|
|
67
|
+
function failedOutcome(base, effects, failure, tokens) {
|
|
68
68
|
const { name, callId, operationId } = base;
|
|
69
69
|
const modelResult = formatToolFailureForModel(failure);
|
|
70
|
-
const
|
|
70
|
+
const failed = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
|
|
71
|
+
const event = tokens ? { ...failed, tool: { ...failed.tool, tokens } } : failed;
|
|
71
72
|
return toolOperationOutcomeSchema.parse(operationWireValue({ event, effects, replay: { modelResult, failure } }));
|
|
72
73
|
}
|
|
73
74
|
/** A gate after the claim cannot pause a call that was already sent; only a sign-in can ask for one there. */
|
|
@@ -85,6 +86,7 @@ class CoordinatedExecution {
|
|
|
85
86
|
writeFailed = false;
|
|
86
87
|
terminal;
|
|
87
88
|
stopped;
|
|
89
|
+
spent;
|
|
88
90
|
cut = settleable();
|
|
89
91
|
graceTimer;
|
|
90
92
|
constructor(coordinator, operation, accepted, signal, trigger) {
|
|
@@ -114,6 +116,9 @@ class CoordinatedExecution {
|
|
|
114
116
|
this.trigger?.claimed();
|
|
115
117
|
return this.claim;
|
|
116
118
|
}
|
|
119
|
+
spend(tokens) {
|
|
120
|
+
this.spent = tokens;
|
|
121
|
+
}
|
|
117
122
|
observe(event) {
|
|
118
123
|
if (event.type !== 'tool')
|
|
119
124
|
return true;
|
|
@@ -285,7 +290,7 @@ class CoordinatedExecution {
|
|
|
285
290
|
}, emit);
|
|
286
291
|
}
|
|
287
292
|
async settleFailed(failure, emit) {
|
|
288
|
-
const saved = failedOutcome(this.base(), 'unknown', failure);
|
|
293
|
+
const saved = failedOutcome(this.base(), 'unknown', failure, this.spent);
|
|
289
294
|
await this.save(saved);
|
|
290
295
|
await emit(saved.event);
|
|
291
296
|
}
|
|
@@ -381,6 +386,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
|
|
|
381
386
|
}
|
|
382
387
|
const iterator = run((input) => execution.beginBody(input), {
|
|
383
388
|
signal: callSignal,
|
|
389
|
+
spent: (tokens) => execution.spend(tokens),
|
|
384
390
|
...(trigger ? { bodyEnded: trigger.bodyEnded } : {}),
|
|
385
391
|
});
|
|
386
392
|
let handedOff = false;
|
|
@@ -6,6 +6,7 @@ import { labelText } from '../../guardrails/labels.js';
|
|
|
6
6
|
import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
|
|
7
7
|
import { checkTaintGate, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
|
|
8
8
|
import { recordToolCheck, startToolTrace, } from '../engine/tool-trace.js';
|
|
9
|
+
import { sumTurnTokens } from '../engine/usage.js';
|
|
9
10
|
import { jsonObjectSchema } from '../json.js';
|
|
10
11
|
import { isAwaitingUserInput } from '../turn-events.js';
|
|
11
12
|
import { isRecord } from '../util/record.js';
|
|
@@ -1091,6 +1092,7 @@ async function* executeAgentTool(args) {
|
|
|
1091
1092
|
});
|
|
1092
1093
|
// why: A retry throws away the reply drafted so far; the drafts stop there, and the output arrives whole.
|
|
1093
1094
|
let retried = false;
|
|
1095
|
+
const seen = [];
|
|
1094
1096
|
for (;;) {
|
|
1095
1097
|
const next = await run.next();
|
|
1096
1098
|
if (next.done) {
|
|
@@ -1101,6 +1103,13 @@ async function* executeAgentTool(args) {
|
|
|
1101
1103
|
return;
|
|
1102
1104
|
}
|
|
1103
1105
|
const event = next.value;
|
|
1106
|
+
seen.push(event);
|
|
1107
|
+
if (event.type === 'tokens' || event.type === 'tool') {
|
|
1108
|
+
const spent = sumTurnTokens(seen);
|
|
1109
|
+
// why: A stopped agent throws before it returns its usage.
|
|
1110
|
+
if (spent)
|
|
1111
|
+
args.stages?.spent?.(spent);
|
|
1112
|
+
}
|
|
1104
1113
|
if (event.type === 'attempt')
|
|
1105
1114
|
retried = true;
|
|
1106
1115
|
if (event.type === 'text' || event.type === 'structured_draft') {
|
|
@@ -248,7 +248,11 @@ function runCall(registry, request, profile, snapshot, callId, openSpan, failBef
|
|
|
248
248
|
turnInput: request.turnInput,
|
|
249
249
|
promoted: request.promoted,
|
|
250
250
|
},
|
|
251
|
-
}, request.signal, (beginBody, hooks) => invokePrepared(registry, { ...request, ...(hooks.signal ? { signal: hooks.signal } : {}) }, profile, snapshot, callId, detach?.trace.open ?? openSpan, failBeforeTool, canaries, beginBody, {
|
|
251
|
+
}, request.signal, (beginBody, hooks) => invokePrepared(registry, { ...request, ...(hooks.signal ? { signal: hooks.signal } : {}) }, profile, snapshot, callId, detach?.trace.open ?? openSpan, failBeforeTool, canaries, beginBody, {
|
|
252
|
+
...step,
|
|
253
|
+
...(hooks.bodyEnded ? { bodyEnded: hooks.bodyEnded } : {}),
|
|
254
|
+
...(hooks.spent ? { spent: hooks.spent } : {}),
|
|
255
|
+
}), (outcome) => authorizeToolReplay({
|
|
252
256
|
outcome,
|
|
253
257
|
tools: registry.tools,
|
|
254
258
|
profile,
|
|
@@ -3,7 +3,7 @@ import { type LabelOverrides } from '../../guardrails/labels.js';
|
|
|
3
3
|
import type { SpanHandle } from '../../observability/trace-span.js';
|
|
4
4
|
import type { ToolAccess } from '../schema.js';
|
|
5
5
|
import { type InjectUnit, type StageHandler, type StageResult, type StepCall } from '../stages.js';
|
|
6
|
-
import type { Profile, TurnEvent, TurnHistoryMessage } from '../types.js';
|
|
6
|
+
import type { Profile, TurnEvent, TurnHistoryMessage, TurnTokens } from '../types.js';
|
|
7
7
|
import { type ToolCallBase } from './events.js';
|
|
8
8
|
import type { ModelToolResult, ToolContext, ToolFailure, ToolGate, ToolLabels } from './types.js';
|
|
9
9
|
/** How a call's wait for other calls in its step ended: they settled, or the wait cannot end. */
|
|
@@ -36,6 +36,8 @@ export interface ToolStageSupport {
|
|
|
36
36
|
drafts?: boolean;
|
|
37
37
|
/** Told when the body has ended, before `post_tool` reads it. */
|
|
38
38
|
bodyEnded?: () => void;
|
|
39
|
+
/** Told what an agent tool's turn has spent so far. */
|
|
40
|
+
spent?: (tokens: TurnTokens) => void;
|
|
39
41
|
}
|
|
40
42
|
export type PreBodyOutcome = {
|
|
41
43
|
ok: true;
|
|
@@ -103,8 +103,33 @@ export interface CompactionSpec {
|
|
|
103
103
|
/** Replaces the default `tokens > compactAt * maxTokens` check. */
|
|
104
104
|
trigger?: (ctx: CompactionTriggerContext) => boolean | Promise<boolean>;
|
|
105
105
|
}
|
|
106
|
+
/** What every request that runs a model takes: how to stop it, and where its trace goes. */
|
|
107
|
+
export interface RunControls {
|
|
108
|
+
/** Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter supports it. */
|
|
109
|
+
signal?: AbortSignal;
|
|
110
|
+
/** Host-owned metadata preserved on the run's trace records; the kernel does not interpret it. */
|
|
111
|
+
metadata?: Record<string, unknown>;
|
|
112
|
+
/**
|
|
113
|
+
* W3C `traceparent` of the host span this run goes under. The run's root span joins that trace
|
|
114
|
+
* as its child; without it the run starts a new trace. A malformed value throws.
|
|
115
|
+
*/
|
|
116
|
+
traceparent?: string;
|
|
117
|
+
/** Your project id, recorded on the trace. */
|
|
118
|
+
projectId?: string;
|
|
119
|
+
/** Host conversation id, recorded as `gen_ai.conversation.id`. */
|
|
120
|
+
conversationId?: string;
|
|
121
|
+
/** Earlier traces this run follows. */
|
|
122
|
+
links?: TurnTraceLink[];
|
|
123
|
+
}
|
|
124
|
+
/** Which of the profile's models a run uses, and how hard it thinks. */
|
|
125
|
+
export interface ModelChoice {
|
|
126
|
+
/** Selected model id when `profile.allowModelSelect` is true. */
|
|
127
|
+
model?: ModelId;
|
|
128
|
+
/** Selected effort alias when the binding has `allowEffortSelect`. */
|
|
129
|
+
effort?: string;
|
|
130
|
+
}
|
|
106
131
|
/** `compactHistory` input, for `timing: 'after'`: the host passes back what `done.compaction` carried. */
|
|
107
|
-
export interface CompactHistoryRequest {
|
|
132
|
+
export interface CompactHistoryRequest extends RunControls {
|
|
108
133
|
/** The profile whose model binding carries the `compaction` spec. */
|
|
109
134
|
profile: ProfileId;
|
|
110
135
|
/** That binding; defaults to the profile's `defaultModel`. */
|
|
@@ -112,10 +137,6 @@ export interface CompactHistoryRequest {
|
|
|
112
137
|
history: TurnHistoryMessage[];
|
|
113
138
|
/** `done.compaction.tokens`: a failed compactor drops `toCompact` only when this is over `maxTokens`. */
|
|
114
139
|
tokens: number;
|
|
115
|
-
signal?: AbortSignal;
|
|
116
|
-
traceparent?: string;
|
|
117
|
-
conversationId?: string;
|
|
118
|
-
metadata?: Record<string, unknown>;
|
|
119
140
|
}
|
|
120
141
|
/** A structured-output schema given inline. */
|
|
121
142
|
export interface StructuredSpec {
|
|
@@ -480,7 +501,7 @@ export interface DecisionAsset {
|
|
|
480
501
|
data: string;
|
|
481
502
|
}
|
|
482
503
|
/** A request to `runDecision`: the profile, the state to judge, and the questions to answer. */
|
|
483
|
-
export interface DecisionRequest {
|
|
504
|
+
export interface DecisionRequest extends RunControls {
|
|
484
505
|
profile: ProfileId;
|
|
485
506
|
state: Exclude<DecisionJson, null>;
|
|
486
507
|
questions: Record<string, DecisionQuestion>;
|
|
@@ -491,15 +512,6 @@ export interface DecisionRequest {
|
|
|
491
512
|
* references are sent, so pick references that cannot occur in your text by accident.
|
|
492
513
|
*/
|
|
493
514
|
assets?: Record<string, DecisionAsset>;
|
|
494
|
-
signal?: AbortSignal;
|
|
495
|
-
/** Host-owned metadata preserved on the decision's trace record; the kernel does not interpret it. */
|
|
496
|
-
metadata?: Record<string, unknown>;
|
|
497
|
-
/**
|
|
498
|
-
* W3C `traceparent` of the host span this decision runs under. The `decide`
|
|
499
|
-
* root joins that trace as its child; without it the decision starts a new
|
|
500
|
-
* trace. A malformed value throws.
|
|
501
|
-
*/
|
|
502
|
-
traceparent?: string;
|
|
503
515
|
}
|
|
504
516
|
/** The model's answer to one decision question. */
|
|
505
517
|
export type DecisionAnswer = {
|
|
@@ -581,14 +593,11 @@ export interface EmbeddingProfile extends Omit<ProfileCommon, 'identity' | 'outp
|
|
|
581
593
|
*/
|
|
582
594
|
export type EmbeddingTask = 'query' | 'document';
|
|
583
595
|
/** A request to `runEmbedding`. */
|
|
584
|
-
export interface EmbeddingRequest {
|
|
596
|
+
export interface EmbeddingRequest extends RunControls {
|
|
585
597
|
profile: ProfileId;
|
|
586
598
|
model?: ModelId;
|
|
587
599
|
input: EmbeddingInput | readonly EmbeddingInput[];
|
|
588
600
|
task?: EmbeddingTask;
|
|
589
|
-
signal?: AbortSignal;
|
|
590
|
-
metadata?: Record<string, unknown>;
|
|
591
|
-
traceparent?: string;
|
|
592
601
|
}
|
|
593
602
|
/** One vector returned for one ordered embedding input. */
|
|
594
603
|
export interface EmbeddingVector {
|
|
@@ -757,23 +766,13 @@ export interface TurnTraceLink {
|
|
|
757
766
|
/** How the earlier turn stopped, when the host knows. */
|
|
758
767
|
stop?: TurnStopKind;
|
|
759
768
|
}
|
|
760
|
-
/**
|
|
761
|
-
export interface
|
|
769
|
+
/** What `runTurn` and `runSession` both take: an agent's profile, its model, and the host's hooks and keys. */
|
|
770
|
+
export interface AgentRunRequest extends RunControls, ModelChoice {
|
|
762
771
|
execution?: ToolExecutionCoordinator;
|
|
763
772
|
background?: ToolBackgroundService;
|
|
764
773
|
pageExecution?: PageToolExecution;
|
|
765
774
|
providerState?: ProviderCheckpoint;
|
|
766
775
|
profile: ProfileId;
|
|
767
|
-
projectId?: string;
|
|
768
|
-
/**
|
|
769
|
-
* Sticky routing / cache session key for OpenRouter (`session_id`).
|
|
770
|
-
* Not the same as `projectId` or Gemini `previousInteractionId`.
|
|
771
|
-
*/
|
|
772
|
-
sessionId?: string;
|
|
773
|
-
/** Selected model id when `profile.allowModelSelect` is true. */
|
|
774
|
-
model?: ModelId;
|
|
775
|
-
/** Selected effort alias when the binding has `allowEffortSelect`. */
|
|
776
|
-
effort?: string;
|
|
777
776
|
/**
|
|
778
777
|
* Args for built-in tools on the chosen model's `builtInTools`, by tool id.
|
|
779
778
|
* Each is parsed by the schema the provider's adapter declares for that tool.
|
|
@@ -781,35 +780,42 @@ export interface TurnRequest {
|
|
|
781
780
|
builtInArgs?: BuiltInArgs;
|
|
782
781
|
/** Host-provided dynamic system prompt combined with profile persona */
|
|
783
782
|
system?: SystemPrompt;
|
|
784
|
-
/** This turn's voice, style, and speed, over `profile.speech`. Speech profiles only. */
|
|
785
|
-
speech?: TurnSpeech;
|
|
786
783
|
sessionPermissions?: string[];
|
|
787
784
|
/** Host channel/path for catalog `paths` filtering. */
|
|
788
785
|
path?: string;
|
|
789
|
-
/** This
|
|
786
|
+
/** This run's facts, one value for each of `profile.identity.conditions` but `path`. */
|
|
790
787
|
conditions?: Readonly<Record<string, string>>;
|
|
791
|
-
/** Host-owned metadata preserved for traces; the kernel does not interpret it. */
|
|
792
|
-
metadata?: Record<string, unknown>;
|
|
793
|
-
/**
|
|
794
|
-
* W3C `traceparent` of the host span this turn runs under. The turn's root
|
|
795
|
-
* span joins that trace as its child; without it the turn starts a new trace.
|
|
796
|
-
* A malformed value throws.
|
|
797
|
-
*/
|
|
798
|
-
traceparent?: string;
|
|
799
|
-
/** Host conversation id, recorded as `gen_ai.conversation.id`. */
|
|
800
|
-
conversationId?: string;
|
|
801
|
-
links?: TurnTraceLink[];
|
|
802
788
|
/**
|
|
803
789
|
* Opaque application context handed to tool `handler` / `preTool` and
|
|
804
790
|
* `tools.t1Policy` as `ctx.host`. The kernel never reads, logs, traces, or
|
|
805
791
|
* serializes it.
|
|
806
792
|
*/
|
|
807
793
|
host?: unknown;
|
|
794
|
+
/** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
|
|
795
|
+
credentials?: ToolCredentialSource;
|
|
808
796
|
/**
|
|
809
|
-
*
|
|
810
|
-
*
|
|
797
|
+
* Resolves remote tool and OAuth host names before each request; a name that
|
|
798
|
+
* resolves to a private address is refused (see `fetchGuarded`).
|
|
811
799
|
*/
|
|
812
|
-
|
|
800
|
+
resolveHost?: ResolveHost;
|
|
801
|
+
/** Text `runTurn` and `runSession` emit stages and apply the returned affordances. A session's is set once. */
|
|
802
|
+
onStage?: StageHandler;
|
|
803
|
+
/**
|
|
804
|
+
* Runs before each agent tool call in this run, and in the turns those
|
|
805
|
+
* calls run. Shape the called agent's request (history, model, provider) or
|
|
806
|
+
* refuse the call. Omit it: the agent runs on what the model sent.
|
|
807
|
+
*/
|
|
808
|
+
onAgentCall?: AgentCallHook;
|
|
809
|
+
}
|
|
810
|
+
/** A request to `runTurn`: the shared controls and the turn's input. */
|
|
811
|
+
export interface TurnRequest extends AgentRunRequest {
|
|
812
|
+
/**
|
|
813
|
+
* Sticky routing / cache session key for OpenRouter (`session_id`).
|
|
814
|
+
* Not the same as `projectId` or Gemini `previousInteractionId`.
|
|
815
|
+
*/
|
|
816
|
+
sessionId?: string;
|
|
817
|
+
/** This turn's voice, style, and speed, over `profile.speech`. Speech profiles only. */
|
|
818
|
+
speech?: TurnSpeech;
|
|
813
819
|
/**
|
|
814
820
|
* Continue a prior resumeable stop. On text profiles the turn's user message
|
|
815
821
|
* is the continue instruction (no `input.text`); the host passes the partial
|
|
@@ -834,21 +840,6 @@ export interface TurnRequest {
|
|
|
834
840
|
*/
|
|
835
841
|
stepsTaken?: number;
|
|
836
842
|
input?: TurnInput;
|
|
837
|
-
/** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
|
|
838
|
-
credentials?: ToolCredentialSource;
|
|
839
|
-
/**
|
|
840
|
-
* Resolves remote tool and OAuth host names before each request; a name that
|
|
841
|
-
* resolves to a private address is refused (see `fetchGuarded`).
|
|
842
|
-
*/
|
|
843
|
-
resolveHost?: ResolveHost;
|
|
844
|
-
/** Text `runTurn` emits stages and applies the returned affordances. */
|
|
845
|
-
onStage?: StageHandler;
|
|
846
|
-
/**
|
|
847
|
-
* Runs before each agent tool call in this turn, and in the turns those
|
|
848
|
-
* calls run. Shape the called agent's request (history, model, provider) or
|
|
849
|
-
* refuse the call. Omit it: the agent runs on what the model sent.
|
|
850
|
-
*/
|
|
851
|
-
onAgentCall?: AgentCallHook;
|
|
852
843
|
}
|
|
853
844
|
/**
|
|
854
845
|
* How an application runs its turns: the one value its own call sites, its web handler and the
|
|
@@ -963,19 +954,9 @@ export interface TurnModel {
|
|
|
963
954
|
* Host request to open a long-lived live session (`runSession`).
|
|
964
955
|
* Profile must be `type: 'live'`.
|
|
965
956
|
*/
|
|
966
|
-
export interface SessionRequest {
|
|
967
|
-
providerState?: ProviderCheckpoint;
|
|
968
|
-
profile: ProfileId;
|
|
969
|
-
/** Host-built system prompt merged with profile identity.system. */
|
|
970
|
-
system?: SystemPrompt;
|
|
957
|
+
export interface SessionRequest extends AgentRunRequest {
|
|
971
958
|
/** Override `profile.live.voice` for this session. */
|
|
972
959
|
voice?: string;
|
|
973
|
-
/** As `TurnRequest.builtInArgs`. */
|
|
974
|
-
builtInArgs?: BuiltInArgs;
|
|
975
|
-
path?: string;
|
|
976
|
-
/** As `TurnRequest.conditions`. */
|
|
977
|
-
conditions?: Readonly<Record<string, string>>;
|
|
978
|
-
sessionPermissions?: string[];
|
|
979
960
|
history?: TurnHistoryMessage[];
|
|
980
961
|
/** The value chosen for each of the profile's `inputs.slots`. */
|
|
981
962
|
slots?: Record<string, string>;
|
|
@@ -993,38 +974,6 @@ export interface SessionRequest {
|
|
|
993
974
|
* `tools.allow`; ids outside it are refused.
|
|
994
975
|
*/
|
|
995
976
|
snapshot?: TurnToolSnapshot;
|
|
996
|
-
signal?: AbortSignal;
|
|
997
|
-
/** Host-owned metadata preserved on every record the session writes. */
|
|
998
|
-
metadata?: Record<string, unknown>;
|
|
999
|
-
/**
|
|
1000
|
-
* W3C `traceparent` of the host span this session runs under. The session's
|
|
1001
|
-
* root span joins that trace as its child; without it the session starts a
|
|
1002
|
-
* new trace. A malformed value throws.
|
|
1003
|
-
*/
|
|
1004
|
-
traceparent?: string;
|
|
1005
|
-
/** Host conversation id, recorded as `gen_ai.conversation.id`. */
|
|
1006
|
-
conversationId?: string;
|
|
1007
|
-
links?: TurnTraceLink[];
|
|
1008
|
-
/** Immutable for the session; there is no `setOnStage`. */
|
|
1009
|
-
onStage?: StageHandler;
|
|
1010
|
-
/**
|
|
1011
|
-
* As `TurnRequest.onAgentCall`, for the agent tools this session's calls run.
|
|
1012
|
-
* Omit it: each agent runs on what the model sent, with the session's own
|
|
1013
|
-
* provider options.
|
|
1014
|
-
*/
|
|
1015
|
-
onAgentCall?: AgentCallHook;
|
|
1016
|
-
/**
|
|
1017
|
-
* Default credentials for `executeTool` (per-call args override). Without one, the
|
|
1018
|
-
* session keeps keys typed at its sign-in gates in memory.
|
|
1019
|
-
*/
|
|
1020
|
-
credentials?: ToolCredentialSource;
|
|
1021
|
-
/**
|
|
1022
|
-
* Resolves remote tool and OAuth host names before each request; a name that
|
|
1023
|
-
* resolves to a private address is refused (see `fetchGuarded`).
|
|
1024
|
-
*/
|
|
1025
|
-
resolveHost?: ResolveHost;
|
|
1026
|
-
/** Opaque host slot for stages / tool execute (per-call args override). */
|
|
1027
|
-
host?: unknown;
|
|
1028
977
|
}
|
|
1029
978
|
/**
|
|
1030
979
|
* Run a call the model made in this session, by its id: once, with the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theoremjs/agents",
|
|
3
|
-
"version": "0.3.4-next.
|
|
3
|
+
"version": "0.3.4-next.721.g7ff150a",
|
|
4
4
|
"description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|