@theoremjs/agents 0.3.4-next.711.g78e504a → 0.3.4-next.717.gd16ffc6
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/interface/mod.d.ts +1 -1
- package/esm/src/interface/mod.js +1 -1
- package/esm/src/interface/tool-invoke.d.ts +11 -3
- package/esm/src/interface/tool-invoke.js +11 -4
- package/esm/src/kernel/api-catalog.js +4 -0
- 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/gates.js +4 -3
- package/esm/src/kernel/engine/runner/mod.js +4 -1
- package/esm/src/kernel/engine/runner/steps.js +4 -0
- 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/turn-events.d.ts +2 -0
- package/esm/src/kernel/turn-events.js +1 -0
- package/esm/src/kernel/types.d.ts +59 -105
- package/package.json +1 -1
|
@@ -26,7 +26,7 @@ export type { WordedStopKind } from './stop.js';
|
|
|
26
26
|
export { stopText, WORDED_STOP_KINDS } from './stop.js';
|
|
27
27
|
export type { SettledToolCallEvent } from './tool-calls.js';
|
|
28
28
|
export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
|
|
29
|
-
export { promotedToolIdsFromEvents,
|
|
29
|
+
export { promotedToolIdsFromEvents, type ReplyCarried, replyCarriedFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
|
|
30
30
|
export type { PromotedToolMedia } from './tool-media.js';
|
|
31
31
|
export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';
|
|
32
32
|
export type { AttachmentValidationResult, ComposerInterfaceFields, ComposerProfileInterface, FoldTurnEventsOptions, ImageProfileInterface, LiveProfileInterface, ModelBindingView, PendingAttachment, ProfileGuardrailsView, ProfileInputsInterface, ProfileInterface, ProfileObservabilityView, ProfileOutputsView, ProfileToolsView, SpeechProfileInterface, TextProfileInterface, TranscriptBlock, TranscriptBlockKind, TranscriptionProfileInterface, UserTurnDraft, } from './types.js';
|
package/esm/src/interface/mod.js
CHANGED
|
@@ -17,6 +17,6 @@ export { profileInterfaceSchema } from './profile-interface.js';
|
|
|
17
17
|
export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, } from './session.js';
|
|
18
18
|
export { stopText, WORDED_STOP_KINDS } from './stop.js';
|
|
19
19
|
export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
|
|
20
|
-
export { promotedToolIdsFromEvents,
|
|
20
|
+
export { promotedToolIdsFromEvents, replyCarriedFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
|
|
21
21
|
export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';
|
|
22
22
|
export { streamThoughtsEnabled } from './types.js';
|
|
@@ -3,6 +3,14 @@ import type { ToolId, TurnEvent, TurnToolSnapshot } from '../kernel/types.js';
|
|
|
3
3
|
declare function promotedToolIdsFromEvents(events: readonly TurnEvent[]): ToolId[];
|
|
4
4
|
/** The tool snapshot on the last `done` event that carries one, which only a turn stopped on a tool or gate does. */
|
|
5
5
|
declare function toolSnapshotFromEvents(events: readonly TurnEvent[]): TurnToolSnapshot | undefined;
|
|
6
|
-
/**
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
/** What a reply that goes on after a pause carries into its next run. */
|
|
7
|
+
export type ReplyCarried = {
|
|
8
|
+
promoted: ToolId[];
|
|
9
|
+
stepsTaken: number;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* What a paused reply holds: the tools on the list it paused with, those a call has loaded since,
|
|
13
|
+
* and the steps its last run counted.
|
|
14
|
+
*/
|
|
15
|
+
declare function replyCarriedFromEvents(events: readonly TurnEvent[]): ReplyCarried;
|
|
16
|
+
export { promotedToolIdsFromEvents, replyCarriedFromEvents, toolSnapshotFromEvents };
|
|
@@ -19,9 +19,16 @@ function toolSnapshotFromEvents(events) {
|
|
|
19
19
|
const done = findLast(events, (event) => event.type === 'done' && event.tools !== undefined);
|
|
20
20
|
return done?.type === 'done' ? done.tools : undefined;
|
|
21
21
|
}
|
|
22
|
-
/**
|
|
23
|
-
|
|
22
|
+
/**
|
|
23
|
+
* What a paused reply holds: the tools on the list it paused with, those a call has loaded since,
|
|
24
|
+
* and the steps its last run counted.
|
|
25
|
+
*/
|
|
26
|
+
function replyCarriedFromEvents(events) {
|
|
24
27
|
const visible = toolSnapshotFromEvents(events)?.visible ?? [];
|
|
25
|
-
|
|
28
|
+
const done = findLast(events, (event) => event.type === 'done' && event.steps !== undefined);
|
|
29
|
+
return {
|
|
30
|
+
promoted: [...new Set([...visible, ...promotedToolIdsFromEvents(events)])],
|
|
31
|
+
stepsTaken: done?.type === 'done' ? (done.steps ?? 0) : 0,
|
|
32
|
+
};
|
|
26
33
|
}
|
|
27
|
-
export { promotedToolIdsFromEvents,
|
|
34
|
+
export { promotedToolIdsFromEvents, replyCarriedFromEvents, toolSnapshotFromEvents };
|
|
@@ -141,6 +141,10 @@ export const REQUEST_FIELDS = {
|
|
|
141
141
|
type: 'ToolId[]',
|
|
142
142
|
doc: 'Tools this reply already had when an earlier run of it paused; the turn opens with them on its list.',
|
|
143
143
|
},
|
|
144
|
+
'runTurn.stepsTaken': {
|
|
145
|
+
type: 'number',
|
|
146
|
+
doc: 'Steps this reply already took when an earlier run of it paused; they count against maxSteps.',
|
|
147
|
+
},
|
|
144
148
|
'runTurn.speech': {
|
|
145
149
|
type: 'TurnSpeech',
|
|
146
150
|
doc: "This turn's voice, style, and speed; each one given replaces the profile's speech field of that name. Refused on a profile that is not speech.",
|
|
@@ -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,
|
|
@@ -462,9 +462,10 @@ function gateStatusToAction(status) {
|
|
|
462
462
|
}
|
|
463
463
|
async function* executeSingleAttemptCycle(args) {
|
|
464
464
|
const { flow, state, profile, system, provider } = args;
|
|
465
|
-
// invariant: Fresh maxSteps budget per validation/egress attempt
|
|
466
|
-
// re-entry inside this cycle still accumulates stepCount
|
|
467
|
-
|
|
465
|
+
// invariant: Fresh maxSteps budget per validation/egress attempt, past the steps an earlier run
|
|
466
|
+
// of this reply took. before_end inject re-entry inside this cycle still accumulates stepCount
|
|
467
|
+
// (do not reset there).
|
|
468
|
+
state.stepCount = flow.currentReq.stepsTaken ?? 0;
|
|
468
469
|
// invariant: The attempt's reply spans its before_end re-entries; only a new attempt starts it again.
|
|
469
470
|
state.replyText = '';
|
|
470
471
|
state.replyMessages = [];
|
|
@@ -283,6 +283,7 @@ async function* emitTurn(args) {
|
|
|
283
283
|
const tokens = sumTurnTokens(state.allEmittedEvents);
|
|
284
284
|
const done = turnDoneOf({
|
|
285
285
|
stop: state.lastStop ?? { kind: 'completed' },
|
|
286
|
+
steps: state.stepCount,
|
|
286
287
|
...(state.providerState &&
|
|
287
288
|
!cutConversation(state) &&
|
|
288
289
|
!('providerContinuation' in profile && profile.providerContinuation?.history === 'stateless') &&
|
|
@@ -604,7 +605,9 @@ async function compactHistoryInRegistry(registry, req, provider, sinkOverride) {
|
|
|
604
605
|
const turnReq = {
|
|
605
606
|
profile: req.profile,
|
|
606
607
|
input: {},
|
|
607
|
-
|
|
608
|
+
conversationId: req.conversationId,
|
|
609
|
+
projectId: req.projectId,
|
|
610
|
+
links: req.links,
|
|
608
611
|
};
|
|
609
612
|
const tree = startTrace(`invoke_agent ${req.profile}`, {
|
|
610
613
|
...turnSpanOptions(turnReq),
|
|
@@ -568,6 +568,10 @@ async function* executeAttempt(args) {
|
|
|
568
568
|
replyIsJudged(resolveGuardrailPolicy(profile.guardrails), TURN_REPLY);
|
|
569
569
|
// why: Buffered delivery holds each attempt's text and media until it passes; streamed delivery shows them live.
|
|
570
570
|
const holdVisible = validation !== undefined && generation.stream === false;
|
|
571
|
+
// why: A reply that spent its steps before it paused has no step left to read the answered call.
|
|
572
|
+
if (isStepLimitReached(state.stepCount, generation.maxSteps ?? 0)) {
|
|
573
|
+
state.lastStop = { kind: 'step_limit' };
|
|
574
|
+
}
|
|
571
575
|
// why: Ceiling is cumulative `state.stepCount` across before_end inject re-entries
|
|
572
576
|
// within this attempt. Validation/egress repair resets stepCount at the start
|
|
573
577
|
// of each attempt cycle.
|
|
@@ -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'];
|
|
@@ -569,6 +569,8 @@ export interface DoneBase {
|
|
|
569
569
|
tokens?: TurnTokens;
|
|
570
570
|
/** The turn's root span as a W3C `traceparent`, for a later request's `links`. */
|
|
571
571
|
traceparent?: string;
|
|
572
|
+
/** The model calls that count against `maxSteps` so far, those of `stepsTaken` included. */
|
|
573
|
+
steps?: number;
|
|
572
574
|
compaction?: CompactionSignal;
|
|
573
575
|
/** A user utterance interrupted an in-flight live response (barge-in). */
|
|
574
576
|
interrupted?: boolean;
|
|
@@ -360,6 +360,7 @@ const doneBase = {
|
|
|
360
360
|
type: z.literal('done'),
|
|
361
361
|
tokens: turnTokens.optional(),
|
|
362
362
|
traceparent: z.string().optional(),
|
|
363
|
+
steps: z.number().int().nonnegative().optional(),
|
|
363
364
|
compaction: compactionSignal.optional(),
|
|
364
365
|
interrupted: z.boolean().optional(),
|
|
365
366
|
interactionId: z.string().optional(),
|
|
@@ -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
|
|
@@ -828,22 +834,12 @@ export interface TurnRequest {
|
|
|
828
834
|
* path does not grant is left out, as for `tools.t1Policy`.
|
|
829
835
|
*/
|
|
830
836
|
promoted?: ToolId[];
|
|
831
|
-
input?: TurnInput;
|
|
832
|
-
/** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
|
|
833
|
-
credentials?: ToolCredentialSource;
|
|
834
837
|
/**
|
|
835
|
-
*
|
|
836
|
-
*
|
|
838
|
+
* Steps this reply already took when an earlier run of it paused. They count against `maxSteps`,
|
|
839
|
+
* so an answered call does not give the reply its steps back. Read `done.steps`.
|
|
837
840
|
*/
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
onStage?: StageHandler;
|
|
841
|
-
/**
|
|
842
|
-
* Runs before each agent tool call in this turn, and in the turns those
|
|
843
|
-
* calls run. Shape the called agent's request (history, model, provider) or
|
|
844
|
-
* refuse the call. Omit it: the agent runs on what the model sent.
|
|
845
|
-
*/
|
|
846
|
-
onAgentCall?: AgentCallHook;
|
|
841
|
+
stepsTaken?: number;
|
|
842
|
+
input?: TurnInput;
|
|
847
843
|
}
|
|
848
844
|
/**
|
|
849
845
|
* How an application runs its turns: the one value its own call sites, its web handler and the
|
|
@@ -958,19 +954,9 @@ export interface TurnModel {
|
|
|
958
954
|
* Host request to open a long-lived live session (`runSession`).
|
|
959
955
|
* Profile must be `type: 'live'`.
|
|
960
956
|
*/
|
|
961
|
-
export interface SessionRequest {
|
|
962
|
-
providerState?: ProviderCheckpoint;
|
|
963
|
-
profile: ProfileId;
|
|
964
|
-
/** Host-built system prompt merged with profile identity.system. */
|
|
965
|
-
system?: SystemPrompt;
|
|
957
|
+
export interface SessionRequest extends AgentRunRequest {
|
|
966
958
|
/** Override `profile.live.voice` for this session. */
|
|
967
959
|
voice?: string;
|
|
968
|
-
/** As `TurnRequest.builtInArgs`. */
|
|
969
|
-
builtInArgs?: BuiltInArgs;
|
|
970
|
-
path?: string;
|
|
971
|
-
/** As `TurnRequest.conditions`. */
|
|
972
|
-
conditions?: Readonly<Record<string, string>>;
|
|
973
|
-
sessionPermissions?: string[];
|
|
974
960
|
history?: TurnHistoryMessage[];
|
|
975
961
|
/** The value chosen for each of the profile's `inputs.slots`. */
|
|
976
962
|
slots?: Record<string, string>;
|
|
@@ -988,38 +974,6 @@ export interface SessionRequest {
|
|
|
988
974
|
* `tools.allow`; ids outside it are refused.
|
|
989
975
|
*/
|
|
990
976
|
snapshot?: TurnToolSnapshot;
|
|
991
|
-
signal?: AbortSignal;
|
|
992
|
-
/** Host-owned metadata preserved on every record the session writes. */
|
|
993
|
-
metadata?: Record<string, unknown>;
|
|
994
|
-
/**
|
|
995
|
-
* W3C `traceparent` of the host span this session runs under. The session's
|
|
996
|
-
* root span joins that trace as its child; without it the session starts a
|
|
997
|
-
* new trace. A malformed value throws.
|
|
998
|
-
*/
|
|
999
|
-
traceparent?: string;
|
|
1000
|
-
/** Host conversation id, recorded as `gen_ai.conversation.id`. */
|
|
1001
|
-
conversationId?: string;
|
|
1002
|
-
links?: TurnTraceLink[];
|
|
1003
|
-
/** Immutable for the session; there is no `setOnStage`. */
|
|
1004
|
-
onStage?: StageHandler;
|
|
1005
|
-
/**
|
|
1006
|
-
* As `TurnRequest.onAgentCall`, for the agent tools this session's calls run.
|
|
1007
|
-
* Omit it: each agent runs on what the model sent, with the session's own
|
|
1008
|
-
* provider options.
|
|
1009
|
-
*/
|
|
1010
|
-
onAgentCall?: AgentCallHook;
|
|
1011
|
-
/**
|
|
1012
|
-
* Default credentials for `executeTool` (per-call args override). Without one, the
|
|
1013
|
-
* session keeps keys typed at its sign-in gates in memory.
|
|
1014
|
-
*/
|
|
1015
|
-
credentials?: ToolCredentialSource;
|
|
1016
|
-
/**
|
|
1017
|
-
* Resolves remote tool and OAuth host names before each request; a name that
|
|
1018
|
-
* resolves to a private address is refused (see `fetchGuarded`).
|
|
1019
|
-
*/
|
|
1020
|
-
resolveHost?: ResolveHost;
|
|
1021
|
-
/** Opaque host slot for stages / tool execute (per-call args override). */
|
|
1022
|
-
host?: unknown;
|
|
1023
977
|
}
|
|
1024
978
|
/**
|
|
1025
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.717.gd16ffc6",
|
|
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",
|