@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.
@@ -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, replyToolIdsFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
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';
@@ -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, replyToolIdsFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
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
- /** The tools a paused reply holds: those on the list it paused with, and those a call has loaded since. */
7
- declare function replyToolIdsFromEvents(events: readonly TurnEvent[]): ToolId[];
8
- export { promotedToolIdsFromEvents, replyToolIdsFromEvents, toolSnapshotFromEvents };
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
- /** The tools a paused reply holds: those on the list it paused with, and those a call has loaded since. */
23
- function replyToolIdsFromEvents(events) {
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
- return [...new Set([...visible, ...promotedToolIdsFromEvents(events)])];
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, replyToolIdsFromEvents, toolSnapshotFromEvents };
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. before_end inject
466
- // re-entry inside this cycle still accumulates stepCount (do not reset there).
467
- state.stepCount = 0;
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
- ...(req.conversationId ? { conversationId: req.conversationId } : {}),
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(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'];
@@ -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
- /** 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
@@ -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
- * Resolves remote tool and OAuth host names before each request; a name that
836
- * resolves to a private address is refused (see `fetchGuarded`).
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
- resolveHost?: ResolveHost;
839
- /** Text `runTurn` emits stages and applies the returned affordances. */
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.711.g78e504a",
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",