@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.
@@ -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
- ...(req.conversationId ? { conversationId: req.conversationId } : {}),
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(options.background, options.execution);
1143
- const { profile, generation: gen0 } = resolveTurnInRegistry(registry, options.background ? { ...safe, background: options.background } : safe);
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: options.execution,
1185
- ...(options.background ? { background: options.background } : {}),
1186
- pageExecution: options.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
- ...optional('gen_ai.conversation.id', req.conversationId),
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
- ...optional('gen_ai.conversation.id', req.conversationId),
818
+ ...runIdentity(req),
805
819
  'gen_ai.input.messages': turnInputMessages(req.input),
806
- ...optional('theorem.request.effort', req.effort),
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: TURN_TYPES,
113
- reason: 'only model turns take tool-loop steps',
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 event = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
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, { ...step, ...(hooks.bodyEnded ? { bodyEnded: hooks.bodyEnded } : {}) }), (outcome) => authorizeToolReplay({
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
- /** A request to `runTurn`: the profile, the input, and the host's hooks and keys. */
761
- export interface TurnRequest {
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 turn's facts, one value for each of `profile.identity.conditions` but `path`. */
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
- * Optional abort signal. When aborted, THEOREM stops the turn and cancels
810
- * in-flight provider HTTP where the adapter supports it.
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
- signal?: AbortSignal;
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.715.geef22fd",
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",