@theoremjs/agents 0.3.4-next.632.g35631ef → 0.3.4-next.636.g3b66d8b

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.
@@ -2,6 +2,7 @@
2
2
  // session and history read calls through this fold only.
3
3
  import { TheoremError } from '../guardrails/error.js';
4
4
  import { labelText } from '../guardrails/labels.js';
5
+ import { turnEventSchema } from '../kernel/turn-events.js';
5
6
  import { partialJsonObject } from '../kernel/util/partial-json.js';
6
7
  /**
7
8
  * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
@@ -58,8 +59,9 @@ function applyToolEvent(call, tool) {
58
59
  return { ...call, outputDraft: (call.outputDraft ?? '') + tool.text };
59
60
  case 'artifact':
60
61
  return { ...call, artifacts: [...call.artifacts, tool.artifact] };
61
- case 'dispatch':
62
62
  case 'progress':
63
+ return withAgentStep(call, tool.data);
64
+ case 'dispatch':
63
65
  case 'trace':
64
66
  case 'warning':
65
67
  return call;
@@ -84,24 +86,62 @@ function applyToolDraft(call, draft) {
84
86
  draft: (call?.draft ?? '') + draft.text,
85
87
  };
86
88
  }
89
+ /** Adds one call event to `calls`, keyed as `toolCallsOf` keys them. */
90
+ function foldToolCall(calls, event) {
91
+ if (event.type === 'tool_draft') {
92
+ calls.set(event.callId, applyToolDraft(calls.get(event.callId), event));
93
+ return;
94
+ }
95
+ const { tool } = event;
96
+ const key = tool.operationId ?? tool.callId;
97
+ // why: The draft is keyed by the model's callId; the call that replaces it may carry an operation ID.
98
+ if (tool.phase === undefined && calls.get(tool.callId)?.draft !== undefined) {
99
+ calls.delete(tool.callId);
100
+ }
101
+ calls.set(key, applyToolEvent(calls.get(key), tool));
102
+ }
87
103
  /** Every call in `events`, in the order the model made them. */
88
104
  function toolCallsOf(events) {
89
105
  const calls = new Map();
90
106
  for (const event of events) {
91
- if (event.type === 'tool_draft') {
92
- calls.set(event.callId, applyToolDraft(calls.get(event.callId), event));
93
- continue;
94
- }
95
- if (event.type !== 'tool')
96
- continue;
97
- const { tool } = event;
98
- const key = tool.operationId ?? tool.callId;
99
- // why: The draft is keyed by the model's callId; the call that replaces it may carry an operation ID.
100
- if (tool.phase === undefined && calls.get(tool.callId)?.draft !== undefined) {
101
- calls.delete(tool.callId);
102
- }
103
- calls.set(key, applyToolEvent(calls.get(key), tool));
107
+ if (event.type === 'tool_draft' || event.type === 'tool')
108
+ foldToolCall(calls, event);
109
+ }
110
+ return [...calls.values()];
111
+ }
112
+ /**
113
+ * A call event of the agent an agent tool ran, which the kernel carries as the call's progress
114
+ * (`{ agent, event }`); any other progress is not a step.
115
+ */
116
+ function agentStep(data) {
117
+ if (typeof data !== 'object' || data === null || !('agent' in data) || !('event' in data)) {
118
+ return undefined;
119
+ }
120
+ const { event } = data;
121
+ if (event?.type !== 'tool' && event?.type !== 'tool_draft')
122
+ return undefined;
123
+ const parsed = turnEventSchema.safeParse(event);
124
+ return parsed.success ? parsed.data : undefined;
125
+ }
126
+ /** `call` with the agent step its progress carries, if it carries one that fits. */
127
+ function withAgentStep(call, data) {
128
+ const step = agentStep(data);
129
+ const steps = step && withStep(call.steps ?? [], step);
130
+ return steps ? { ...call, steps } : call;
131
+ }
132
+ /**
133
+ * `steps` with one more agent step folded in, or `undefined` when it does not fit.
134
+ * why: A step is progress, not the stream itself: one that does not fit its call is dropped, so it
135
+ * never breaks the transcript of the call that carries it.
136
+ */
137
+ function withStep(steps, event) {
138
+ const calls = new Map(steps.map((step) => [step.operationId ?? step.callId, step]));
139
+ if (event.type === 'tool' && event.tool.phase !== undefined) {
140
+ const known = calls.get(event.tool.operationId ?? event.tool.callId);
141
+ if (known?.callId !== event.tool.callId || known.name !== event.tool.name)
142
+ return undefined;
104
143
  }
144
+ foldToolCall(calls, event);
105
145
  return [...calls.values()];
106
146
  }
107
147
  /** The arguments shown for approval, or the user's edit, or the model's original call. */
@@ -182,6 +182,8 @@ export interface ToolCall {
182
182
  /** When it last settled: complete, failed, cancelled, or gated (epoch ms). */
183
183
  endedAt?: number;
184
184
  artifacts: unknown[];
185
+ /** An agent tool's: the calls its agent made, in order, from the call's `progress` phases. */
186
+ steps?: ToolCall[];
185
187
  }
186
188
  export interface ToolBlock extends TranscriptBlockBase {
187
189
  kind: 'tool';
@@ -145,6 +145,12 @@ function openingPrompt(profile, req, slots) {
145
145
  function assertSessionContext(profile, context) {
146
146
  assertTurnContext(profile, { profile: profile.id, input: { context } });
147
147
  }
148
+ function readSessionContext(profile, context) {
149
+ assertSessionContext(profile, context);
150
+ const start = performance.now();
151
+ const prepared = prepareLiveContext(profile, context);
152
+ return { ...prepared, ms: performance.now() - start };
153
+ }
148
154
  function applyVoiceOverride(generation, voice) {
149
155
  if (!voice || !generation.live) {
150
156
  return generation;
@@ -530,16 +536,19 @@ function buildLiveSession(args) {
530
536
  return prepared.text;
531
537
  };
532
538
  /** Context is background: it joins no history and opens no cycle, and its addresses count as given. */
533
- const landContext = (context) => {
534
- assertSessionContext(profile, context);
535
- const start = performance.now();
536
- const prepared = prepareLiveContext(profile, context);
537
- trace.inboundCheck(performance.now() - start, prepared.guardrails[0]);
538
- for (const guardrail of prepared.guardrails)
539
+ const noteContext = (read) => {
540
+ trace.inboundCheck(read.ms, read.guardrails[0]);
541
+ for (const guardrail of read.guardrails)
539
542
  enqueuePending(guardrail);
540
- for (const text of prepared.texts) {
543
+ for (const text of read.texts) {
541
544
  addSeenUrls(givenUrls.request, text);
542
545
  addGivenDestinations(destinations, text);
546
+ }
547
+ };
548
+ const landContext = (context) => {
549
+ const read = readSessionContext(profile, context);
550
+ noteContext(read);
551
+ for (const text of read.texts) {
543
552
  assertOpen();
544
553
  connection.sendContext(text);
545
554
  }
@@ -1075,11 +1084,12 @@ function buildLiveSession(args) {
1075
1084
  return trace.close({});
1076
1085
  },
1077
1086
  };
1078
- const { initialContext, opening } = args;
1079
- if (args.openInitialCycle || initialContext || opening) {
1087
+ const { openingContext, opening } = args;
1088
+ if (args.openInitialCycle || openingContext || opening) {
1080
1089
  void withIngress(async () => {
1081
- if (initialContext)
1082
- landContext(initialContext);
1090
+ // why: the provider already seeded these texts; only their bookkeeping is left.
1091
+ if (openingContext)
1092
+ noteContext(openingContext);
1083
1093
  if (!args.openInitialCycle && !opening)
1084
1094
  return;
1085
1095
  const opened = await openCycleIfNeeded();
@@ -1113,8 +1123,7 @@ async function openTracedSession(registry, req, options, trace) {
1113
1123
  throwIfAborted(safe.signal);
1114
1124
  const { profile, generation: gen0 } = resolveTurnInRegistry(registry, safe);
1115
1125
  assertLiveProfile(profile);
1116
- if (req.context)
1117
- assertSessionContext(profile, req.context);
1126
+ const openingContext = req.context ? readSessionContext(profile, req.context) : undefined;
1118
1127
  if (req.snapshot) {
1119
1128
  gen0.tools = sessionSnapshotWithinAllow(profile, req.snapshot);
1120
1129
  }
@@ -1129,6 +1138,7 @@ async function openTracedSession(registry, req, options, trace) {
1129
1138
  ]);
1130
1139
  const completeReq = {
1131
1140
  ...providerCompleteRequest(registry.tools, generation, system.text),
1141
+ ...(openingContext?.texts.length ? { context: openingContext.texts } : {}),
1132
1142
  signal: safe.signal,
1133
1143
  tapUpstream: trace.sent,
1134
1144
  };
@@ -1172,7 +1182,7 @@ async function openTracedSession(registry, req, options, trace) {
1172
1182
  historySeed: req.history,
1173
1183
  openInitialCycle: hasInitialInput,
1174
1184
  requestEvents,
1175
- initialContext: req.context,
1185
+ openingContext,
1176
1186
  opening: hasInitialInput ? undefined : openingPrompt(profile, req, safe.input?.slots),
1177
1187
  trace,
1178
1188
  agents: sessionAgentCaller(registry, req, options, trace.agentCanaries),
@@ -908,6 +908,8 @@ export interface ModelRequest extends Omit<ProviderGenerationConfig, 'summaries'
908
908
  image: ImageResponseFormat | null;
909
909
  speech?: ProfileSpeechSpec;
910
910
  live?: ProfileLiveSpec;
911
+ /** Live: the fenced context the session opens with, seeded after `history` so it lands before any input. */
912
+ context?: string[];
911
913
  /** Scrubbed SSE / HTTP rows for traces. */
912
914
  tapUpstream?: (row: Record<string, unknown>) => void;
913
915
  /** Host abort signal. */
@@ -167,11 +167,9 @@ export const geminiLive = defineProtocol({
167
167
  socket.close(NORMAL_CLOSE, 'setup-failed');
168
168
  throw error;
169
169
  }
170
- const history = wire.history?.length
171
- ? buildGeminiLiveClientContent(wire.history)
172
- : undefined;
173
- if (history)
174
- sendFrame(socket, history);
170
+ const seed = buildGeminiLiveClientContent(wire.history, wire.context);
171
+ if (seed)
172
+ sendFrame(socket, seed);
175
173
  for (const part of wire.input)
176
174
  sendFrame(socket, buildGeminiLiveRealtimeInput(part));
177
175
  return session(socket, frames, context, wire.sessionResumptionHandle);
@@ -12,7 +12,12 @@ export type LiveSetupRequest = ModelRequest & {
12
12
  sessionResumptionHandle?: string;
13
13
  };
14
14
  export declare function buildGeminiLiveSetupMessage(req: LiveSetupRequest): Record<string, unknown>;
15
- export declare function buildGeminiLiveClientContent(history: TurnHistoryMessage[]): Record<string, unknown> | null;
15
+ /**
16
+ * The opening seed: history, then the opening context as one user turn.
17
+ * why: Gemini does not order clientContent against realtimeInput, so context sent as its own
18
+ * frame can land after the first realtime text; in the seed it is read before any input.
19
+ */
20
+ export declare function buildGeminiLiveClientContent(history?: readonly TurnHistoryMessage[], context?: readonly string[]): Record<string, unknown> | null;
16
21
  export declare function buildGeminiLiveContext(text: string): Record<string, unknown>;
17
22
  export declare function buildGeminiLiveRealtimeInput(input: InteractionPart): Record<string, unknown>;
18
23
  export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown, parts?: InteractionPart[]): Record<string, unknown>;
@@ -124,7 +124,7 @@ export function buildGeminiLiveSetupMessage(req) {
124
124
  const sessionResumption = buildLiveSessionResumption(req);
125
125
  // why: `initialHistoryInClientContent` makes Gemini wait for clientContent before
126
126
  // realtime generation, so an empty session (e.g. Th30) would hang forever.
127
- const seedInitialHistory = Boolean(req.history && req.history.length > 0);
127
+ const seedInitialHistory = Boolean(req.history?.length || req.context?.length);
128
128
  const setup = {
129
129
  model: liveModelName(req.apiId),
130
130
  generationConfig: buildLiveGenerationConfig(req),
@@ -197,13 +197,21 @@ function historyTurnToGoogleTurn(msg) {
197
197
  }
198
198
  return { role, parts };
199
199
  }
200
- export function buildGeminiLiveClientContent(history) {
201
- if (!history || history.length === 0) {
200
+ /**
201
+ * The opening seed: history, then the opening context as one user turn.
202
+ * why: Gemini does not order clientContent against realtimeInput, so context sent as its own
203
+ * frame can land after the first realtime text; in the seed it is read before any input.
204
+ */
205
+ export function buildGeminiLiveClientContent(history = [], context = []) {
206
+ if (history.length === 0 && context.length === 0) {
202
207
  return null;
203
208
  }
204
209
  return {
205
210
  clientContent: {
206
- turns: history.map(historyTurnToGoogleTurn),
211
+ turns: [
212
+ ...history.map(historyTurnToGoogleTurn),
213
+ ...(context.length ? [{ role: 'user', parts: context.map((text) => ({ text })) }] : []),
214
+ ],
207
215
  turnComplete: true,
208
216
  },
209
217
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.632.g35631ef",
3
+ "version": "0.3.4-next.636.g3b66d8b",
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",