@theoremjs/agents 0.3.5-next.918.g28ade76 → 0.3.5-next.919.gc55551d

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.
@@ -3,6 +3,7 @@
3
3
  import { TheoremError } from '../guardrails/error.js';
4
4
  import { labelText } from '../guardrails/labels.js';
5
5
  import { lateResultsMessage } from '../guardrails/tool-fence.js';
6
+ import { stepReplyMessages } from '../kernel/interaction-parts.js';
6
7
  import { mediaKindForMime } from '../kernel/registry/catalog.js';
7
8
  import { formatToolFailureForModel, formatToolResult } from '../kernel/tools/model-text.js';
8
9
  import { keptReply } from '../kernel/turn-events.js';
@@ -59,27 +60,15 @@ function appendUserDraftToHistory(history, draft, media = {}) {
59
60
  }
60
61
  return [...history, { role: 'user', parts }];
61
62
  }
62
- function toolCallEntry(tool) {
63
- return {
64
- id: tool.callId,
65
- type: 'function',
66
- function: { name: tool.name, arguments: JSON.stringify(tool.arguments) },
67
- };
68
- }
69
- /** The assistant message holding a step's calls, with the reasoning the model wrote before them. */
70
- function assistantCalls(tools) {
71
- const reasoning = tools.flatMap((tool) => tool.reasoning ?? []);
72
- return {
73
- role: 'assistant',
74
- tool_calls: tools.map(toolCallEntry),
75
- ...(reasoning.length ? { reasoning } : {}),
76
- };
77
- }
78
63
  function toolResultMessage(tool, content) {
79
64
  return { role: 'tool', tool_call_id: tool.callId, name: tool.name, content };
80
65
  }
81
66
  function appendToolCallPair(history, tool, content) {
82
- return [...history, assistantCalls([tool]), toolResultMessage(tool, content)];
67
+ return [
68
+ ...history,
69
+ ...stepReplyMessages({ text: '', calls: [tool] }),
70
+ toolResultMessage(tool, content),
71
+ ];
83
72
  }
84
73
  /** The history with a tool call and its result added. */
85
74
  function appendToolExchangeToHistory(history, call) {
@@ -109,12 +98,14 @@ function settledToolContent(call) {
109
98
  : undefined;
110
99
  }
111
100
  /**
112
- * One model step's settled calls: a single assistant message holding every call
113
- * the step made, with the reasoning written before them, then each result, as a provider
114
- * reads a step's calls back. With `gated: 'open'`, a
115
- * call waiting on its gate joins the message too, left without a result.
101
+ * One model step: a single assistant message holding what the step wrote and
102
+ * every settled call it made, with the reasoning written before them, then
103
+ * each result, as a provider reads a step back. With `gated: 'open'`, a call
104
+ * waiting on its gate joins the message too, left without a result. A step
105
+ * whose calls are all left out keeps its words.
116
106
  */
117
- function appendToolStepToHistory(history, calls, gated = 'omit') {
107
+ function appendToolStepToHistory(history, step, gated = 'omit') {
108
+ const { text, calls } = step;
118
109
  const entries = calls.flatMap((call) => {
119
110
  const content = settledToolContent(call);
120
111
  if (content !== undefined)
@@ -123,11 +114,9 @@ function appendToolStepToHistory(history, calls, gated = 'omit') {
123
114
  ? [{ tool: historyToolCall(call) }]
124
115
  : [];
125
116
  });
126
- if (entries.length === 0)
127
- return history;
128
117
  return [
129
118
  ...history,
130
- assistantCalls(entries.map(({ tool }) => tool)),
119
+ ...stepReplyMessages({ text, calls: entries.map(({ tool }) => tool) }),
131
120
  ...entries.flatMap(({ tool, content }) => content === undefined ? [] : [toolResultMessage(tool, content)]),
132
121
  ];
133
122
  }
@@ -160,7 +149,7 @@ function foldAssistantEvents(history, events, gated) {
160
149
  return;
161
150
  }
162
151
  const stepCalls = step.callKeys.flatMap((id) => calls.get(id) ?? []);
163
- next = appendToolStepToHistory(next, stepCalls, gated);
152
+ next = appendToolStepToHistory(next, { text: step.text, calls: stepCalls }, gated);
164
153
  step = undefined;
165
154
  };
166
155
  for (const event of keptReply(events)) {
@@ -200,8 +189,9 @@ function foldAssistantEvents(history, events, gated) {
200
189
  }
201
190
  if (!step || call.stepId === undefined || step.stepId !== call.stepId) {
202
191
  flushStep();
203
- flushText();
204
- step = { stepId: call.stepId, callKeys: [] };
192
+ // why: The words written just before a step's calls are that step's reply: one message.
193
+ step = { stepId: call.stepId, text: textBuf, callKeys: [] };
194
+ textBuf = '';
205
195
  }
206
196
  step.callKeys.push(key);
207
197
  }
@@ -212,26 +202,39 @@ function foldAssistantEvents(history, events, gated) {
212
202
  /** Attachment and voice blocks are omitted: their preview `data` is UI-only. */
213
203
  function historyFromTranscriptBlocks(blocks) {
214
204
  let history = [];
215
- let step = [];
205
+ let text = '';
206
+ let step = { text: '', calls: [] };
207
+ const flushText = () => {
208
+ if (text)
209
+ history = [...history, { role: 'assistant', content: text }];
210
+ text = '';
211
+ };
216
212
  const flushStep = () => {
217
- history = appendToolStepToHistory(history, step);
218
- step = [];
213
+ if (step.calls.length)
214
+ history = appendToolStepToHistory(history, step);
215
+ step = { text: '', calls: [] };
219
216
  };
220
217
  for (const block of blocks) {
221
218
  if (block.kind === 'tool') {
222
- const open = step[0];
219
+ const open = step.calls[0];
223
220
  if (open && (open.stepId === undefined || open.stepId !== block.tool.stepId))
224
221
  flushStep();
225
- step.push(block.tool);
222
+ if (step.calls.length === 0) {
223
+ // why: The words written just before a step's calls are that step's reply: one message.
224
+ step.text = text;
225
+ text = '';
226
+ }
227
+ step.calls.push(block.tool);
226
228
  continue;
227
229
  }
228
230
  flushStep();
231
+ flushText();
229
232
  if (block.kind === 'user-text') {
230
233
  history = appendUserDraftToHistory(history, { text: block.text });
231
234
  continue;
232
235
  }
233
236
  if (block.kind === 'text') {
234
- history = [...history, { role: 'assistant', content: block.text }];
237
+ text = block.text;
235
238
  continue;
236
239
  }
237
240
  if (block.kind === 'late-results') {
@@ -243,6 +246,7 @@ function historyFromTranscriptBlocks(blocks) {
243
246
  }
244
247
  }
245
248
  flushStep();
249
+ flushText();
246
250
  return history;
247
251
  }
248
252
  function lastToolStep(history) {
@@ -41,7 +41,8 @@ function withoutTextTail(events, count) {
41
41
  * history messages, from what the attempt gate reads, and from the reply. Returns `released` when
42
42
  * a draft was dropped.
43
43
  *
44
- * invariant: A message that keeps no text leaves history; a call it made stays on its own message.
44
+ * invariant: A message that keeps no text leaves history, unless it made calls: then it stays
45
+ * with its calls and without the words.
45
46
  */
46
47
  function dropDraft(state, released) {
47
48
  if (released === undefined || released >= state.replyText.length)
@@ -62,6 +63,10 @@ function dropDraft(state, released) {
62
63
  state.currentHistory[index] = cut;
63
64
  kept.push({ message: cut, at });
64
65
  }
66
+ else if (message.tool_calls) {
67
+ const { content: _dropped, ...calls } = message;
68
+ state.currentHistory[index] = calls;
69
+ }
65
70
  else
66
71
  state.currentHistory.splice(index, 1);
67
72
  }
@@ -486,7 +486,7 @@ function* applyToolSettlement(settlement, state, call) {
486
486
  }
487
487
  return settlement.ended ? 'ended' : 'continue';
488
488
  }
489
- /** A step's reply as the model reads it back: its text, then its calls with the reasoning before them. */
489
+ /** A step's reply as the model reads it back: one message with its text, its calls, and the reasoning before them. */
490
490
  function stepReply(outcome) {
491
491
  return stepReplyMessages({
492
492
  text: outcome.text,
@@ -11,6 +11,7 @@ import { resolveObservabilityPolicy } from '../../../observability/resolve-polic
11
11
  import { liveToolReadBack } from '../../../providers/live.js';
12
12
  import { memoryCredentialSource } from '../../auth/credential-source.js';
13
13
  import { historyHash } from '../../checkpoint.js';
14
+ import { stepReplyMessages } from '../../interaction-parts.js';
14
15
  import { openRegisteredLiveSession } from '../../provider-live.js';
15
16
  import { assertHistoryKept } from '../../provider-runtime.js';
16
17
  import { assertTurnContext } from '../../registry/ingress.js';
@@ -293,6 +294,23 @@ function finalTranscript(event, kind) {
293
294
  return;
294
295
  return event.text || undefined;
295
296
  }
297
+ /**
298
+ * Adds a live call to history in place. The words the model said just before
299
+ * it are the same reply, so the call joins that message, as every API reads a
300
+ * reply back.
301
+ */
302
+ function joinLiveCall(history, call) {
303
+ const last = history.at(-1);
304
+ const said = last?.role === 'assistant' &&
305
+ !last.tool_calls &&
306
+ !last.parts &&
307
+ typeof last.content === 'string'
308
+ ? last.content
309
+ : undefined;
310
+ if (said !== undefined)
311
+ history.pop();
312
+ history.push(...stepReplyMessages({ text: said ?? '', calls: [call] }));
313
+ }
296
314
  async function sealLiveCheckpoints(events, history, calls, keepsHistory) {
297
315
  const sealed = [];
298
316
  for (const event of events) {
@@ -308,16 +326,7 @@ async function sealLiveCheckpoints(events, history, calls, keepsHistory) {
308
326
  for (const [callId, held] of calls) {
309
327
  if (covered.some((message) => message.tool_calls?.some((call) => call.id === callId)))
310
328
  continue;
311
- covered.push({
312
- role: 'assistant',
313
- tool_calls: [
314
- {
315
- id: callId,
316
- type: 'function',
317
- function: { name: held.name, arguments: JSON.stringify(held.arguments) },
318
- },
319
- ],
320
- });
329
+ joinLiveCall(covered, { callId, name: held.name, arguments: held.arguments });
321
330
  }
322
331
  sealed.push({
323
332
  ...event,
@@ -412,19 +421,8 @@ function buildLiveSession(args) {
412
421
  history.push({ role: 'assistant', content: text });
413
422
  };
414
423
  const recordToolSettle = (tool, readBack, parts) => {
424
+ joinLiveCall(history, tool);
415
425
  history.push({
416
- role: 'assistant',
417
- tool_calls: [
418
- {
419
- id: tool.callId,
420
- type: 'function',
421
- function: {
422
- name: tool.name,
423
- arguments: JSON.stringify(tool.arguments),
424
- },
425
- },
426
- ],
427
- }, {
428
426
  role: 'tool',
429
427
  tool_call_id: tool.callId,
430
428
  name: tool.name,
@@ -1,3 +1,4 @@
1
+ import type { ToolCallRequest } from './turn-events.js';
1
2
  import type { InteractionMediaRefPart, InteractionPart, TurnHistoryMessage } from './types.js';
2
3
  /** True for a part that is media referenced by `uri` rather than carried as data. */
3
4
  export declare function isMediaRefPart(part: InteractionPart): part is InteractionMediaRefPart;
@@ -8,16 +9,16 @@ export declare function isMediaRefPart(part: InteractionPart): part is Interacti
8
9
  */
9
10
  export declare function historyMessageParts(msg: TurnHistoryMessage): InteractionPart[];
10
11
  /**
11
- * One model call's reply as the model reads it back later in its turn: what it
12
- * wrote (its structured reply, when it gave one), then the calls it made. Turn
13
- * history and a provider checkpoint both build it here, so the checkpoint
14
- * covers exactly the history the turn's next call sends.
12
+ * One model call's reply as the model reads it back later in its turn: one
13
+ * assistant message with what it wrote (its structured reply, when it gave
14
+ * one), the calls it made, and the reasoning it wrote with them. Every API
15
+ * takes a reply this way, as one message; split in two, the words read as a
16
+ * reply already finished, and the model writes them again. Turn history, a
17
+ * provider checkpoint, a live session, and a client's history all build it
18
+ * here, so the checkpoint covers exactly the history the turn's next call sends.
15
19
  */
16
20
  export declare function stepReplyMessages(reply: {
17
21
  text: string;
18
22
  structured?: unknown;
19
- calls: Parameters<typeof historyToolCalls>[0];
23
+ calls: readonly Pick<ToolCallRequest, 'callId' | 'name' | 'arguments' | 'reasoning'>[];
20
24
  }): TurnHistoryMessage[];
21
- /** One step's calls as the assistant message that made them, with the reasoning written before them. */
22
- declare function historyToolCalls(calls: readonly Pick<import('./turn-events.js').ToolCallRequest, 'callId' | 'name' | 'arguments' | 'reasoning'>[]): TurnHistoryMessage;
23
- export {};
@@ -12,32 +12,30 @@ export function historyMessageParts(msg) {
12
12
  return msg.content ? [{ type: 'text', text: msg.content }, ...parts] : [...parts];
13
13
  }
14
14
  /**
15
- * One model call's reply as the model reads it back later in its turn: what it
16
- * wrote (its structured reply, when it gave one), then the calls it made. Turn
17
- * history and a provider checkpoint both build it here, so the checkpoint
18
- * covers exactly the history the turn's next call sends.
15
+ * One model call's reply as the model reads it back later in its turn: one
16
+ * assistant message with what it wrote (its structured reply, when it gave
17
+ * one), the calls it made, and the reasoning it wrote with them. Every API
18
+ * takes a reply this way, as one message; split in two, the words read as a
19
+ * reply already finished, and the model writes them again. Turn history, a
20
+ * provider checkpoint, a live session, and a client's history all build it
21
+ * here, so the checkpoint covers exactly the history the turn's next call sends.
19
22
  */
20
23
  export function stepReplyMessages(reply) {
21
24
  const content = reply.structured !== undefined ? JSON.stringify(reply.structured) : reply.text;
25
+ if (!content && reply.calls.length === 0)
26
+ return [];
27
+ const reasoning = reply.calls.flatMap((call) => call.reasoning ?? []);
28
+ const tool_calls = reply.calls.map((call) => ({
29
+ id: call.callId,
30
+ type: 'function',
31
+ function: { name: call.name, arguments: JSON.stringify(call.arguments) },
32
+ }));
22
33
  return [
23
- ...(content ? [{ role: 'assistant', content }] : []),
24
- ...(reply.calls.length ? [historyToolCalls(reply.calls)] : []),
34
+ {
35
+ role: 'assistant',
36
+ ...(content ? { content } : {}),
37
+ ...(tool_calls.length ? { tool_calls } : {}),
38
+ ...(reasoning.length ? { reasoning } : {}),
39
+ },
25
40
  ];
26
41
  }
27
- /** One step's calls as the assistant message that made them, with the reasoning written before them. */
28
- function historyToolCalls(calls) {
29
- const reasoning = calls.flatMap((call) => call.reasoning ?? []);
30
- const tool_calls = [];
31
- for (const call of calls) {
32
- tool_calls.push({
33
- id: call.callId,
34
- type: 'function',
35
- function: { name: call.name, arguments: JSON.stringify(call.arguments) },
36
- });
37
- }
38
- return {
39
- role: 'assistant',
40
- tool_calls,
41
- ...(reasoning.length ? { reasoning: [...reasoning] } : {}),
42
- };
43
- }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.918.g28ade76",
3
+ "version": "0.3.5-next.919.gc55551d",
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",