@theoremjs/agents 0.3.5-next.917.g6cb0b91 → 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.
@@ -10,7 +10,7 @@ declare const TOOL_KINDS: readonly ["function", "http", "mcp", "agent"];
10
10
  type ToolKind = (typeof TOOL_KINDS)[number];
11
11
  /**
12
12
  * The places a tool's text crosses: what the model sends, what comes back to it, its error text,
13
- * and what the call shows the person (its output, error, artifacts, and trace on the turn's events).
13
+ * and what the call shows the person (its output, error, and trace on the turn's events).
14
14
  */
15
15
  declare const TOOL_CROSSINGS: readonly ["tool_arguments", "tool_output", "tool_failure", "tool_shown"];
16
16
  /** One of {@linkcode TOOL_CROSSINGS}. */
@@ -12,7 +12,7 @@ function recordOf(keys, value) {
12
12
  const TOOL_KINDS = ['function', 'http', 'mcp', 'agent'];
13
13
  /**
14
14
  * The places a tool's text crosses: what the model sends, what comes back to it, its error text,
15
- * and what the call shows the person (its output, error, artifacts, and trace on the turn's events).
15
+ * and what the call shows the person (its output, error, and trace on the turn's events).
16
16
  */
17
17
  const TOOL_CROSSINGS = ['tool_arguments', 'tool_output', 'tool_failure', 'tool_shown'];
18
18
  /** The boundary where `crossing` happens for a `kind` tool. */
@@ -63,7 +63,7 @@ const TOOL_CROSSING_META = {
63
63
  }),
64
64
  tool_shown: (kind) => ({
65
65
  label: `Shown from ${kind} tools`,
66
- doc: `What a call to a tool of type ${kind} shows the person: its output, error, artifacts, and trace.`,
66
+ doc: `What a call to a tool of type ${kind} shows the person: its output, error, and trace.`,
67
67
  }),
68
68
  };
69
69
  function toolBoundaryMeta() {
@@ -704,7 +704,7 @@ export const LABEL_NOTES = {
704
704
  'detect.blocked': 'Shown to the user when a detector set to block matched something in what they sent, so the turn was refused.',
705
705
  'detect.call_blocked': 'Told to the model in place of a tool call a detector set to block stopped at its arguments.',
706
706
  'detect.output_blocked': "Told to the model in place of a tool's output or error text that a detector set to block matched.",
707
- 'detect.shown_blocked': "Shown to the person in place of a tool's output, error, artifact, or trace that a detector set to block matched at its `tool_shown` boundary.",
707
+ 'detect.shown_blocked': "Shown to the person in place of a tool's output, error, or trace that a detector set to block matched at its `tool_shown` boundary.",
708
708
  'egress.default_repair_guidance': 'Sent to the model, under the rejection, when a detector blocks a reply and the model is asked to write it again.',
709
709
  'detect.hint.ids': 'What the model is told to leave out when `ids` blocks a reply that is then retried.',
710
710
  'detect.hint.financial': 'What the model is told to leave out when `financial` blocks a reply that is then retried.',
@@ -20,4 +20,8 @@ declare function readToolData(content: string): ToolDataRead[];
20
20
  * word to the model. A person who types a fence only makes their own reply stricter.
21
21
  */
22
22
  declare function isLateResult(message: TurnHistoryMessage): boolean;
23
- export { isLateResult, readToolData, TOOL_CLOSE };
23
+ /** The history message `input.lateResults` opens; its metadata names the calls it holds. */
24
+ declare function lateResultsMessage(text: string, operationIds: readonly string[]): TurnHistoryMessage;
25
+ /** The calls whose late results a history message holds. */
26
+ declare function lateResultIds(message: TurnHistoryMessage): string[];
27
+ export { isLateResult, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
@@ -33,4 +33,13 @@ function isLateResult(message) {
33
33
  message.content !== undefined &&
34
34
  readToolData(message.content).length > 0);
35
35
  }
36
- export { isLateResult, readToolData, TOOL_CLOSE };
36
+ /** The history message `input.lateResults` opens; its metadata names the calls it holds. */
37
+ function lateResultsMessage(text, operationIds) {
38
+ return { role: 'user', content: text, metadata: { lateResults: [...operationIds] } };
39
+ }
40
+ /** The calls whose late results a history message holds. */
41
+ function lateResultIds(message) {
42
+ const ids = message.metadata?.lateResults;
43
+ return Array.isArray(ids) ? ids.filter((id) => typeof id === 'string') : [];
44
+ }
45
+ export { isLateResult, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
@@ -48,7 +48,7 @@ export interface ShownToolValue {
48
48
  event?: GuardrailEvent;
49
49
  }
50
50
  /**
51
- * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
51
+ * A call's output, error, and trace reach the person on the turn's events, apart from
52
52
  * what the model read back: the host's server forwards them to the browser as they are. Each is
53
53
  * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
54
54
  * untouched: what the model read is settled at `tool_output_<kind>`.
@@ -149,7 +149,7 @@ function guardToolFailureText(message, provenance, policy, boundary) {
149
149
  };
150
150
  }
151
151
  /**
152
- * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
152
+ * A call's output, error, and trace reach the person on the turn's events, apart from
153
153
  * what the model read back: the host's server forwards them to the browser as they are. Each is
154
154
  * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
155
155
  * untouched: what the model read is settled at `tool_output_<kind>`.
@@ -232,7 +232,12 @@ function standaloneBlock(event, idPrefix) {
232
232
  case 'evidence':
233
233
  return { id: nextBlockId(idPrefix), kind: 'evidence', evidence: event.evidence };
234
234
  case 'late_results':
235
- return { id: nextBlockId(idPrefix), kind: 'late-results', text: event.text };
235
+ return {
236
+ id: nextBlockId(idPrefix),
237
+ kind: 'late-results',
238
+ text: event.text,
239
+ operationIds: event.operationIds,
240
+ };
236
241
  case 'error':
237
242
  return event.error
238
243
  ? { id: nextBlockId(idPrefix), kind: 'error', message: event.error }
@@ -2,6 +2,8 @@
2
2
  // matches `runTurn` / `invokeTool`.
3
3
  import { TheoremError } from '../guardrails/error.js';
4
4
  import { labelText } from '../guardrails/labels.js';
5
+ import { lateResultsMessage } from '../guardrails/tool-fence.js';
6
+ import { stepReplyMessages } from '../kernel/interaction-parts.js';
5
7
  import { mediaKindForMime } from '../kernel/registry/catalog.js';
6
8
  import { formatToolFailureForModel, formatToolResult } from '../kernel/tools/model-text.js';
7
9
  import { keptReply } from '../kernel/turn-events.js';
@@ -58,27 +60,15 @@ function appendUserDraftToHistory(history, draft, media = {}) {
58
60
  }
59
61
  return [...history, { role: 'user', parts }];
60
62
  }
61
- function toolCallEntry(tool) {
62
- return {
63
- id: tool.callId,
64
- type: 'function',
65
- function: { name: tool.name, arguments: JSON.stringify(tool.arguments) },
66
- };
67
- }
68
- /** The assistant message holding a step's calls, with the reasoning the model wrote before them. */
69
- function assistantCalls(tools) {
70
- const reasoning = tools.flatMap((tool) => tool.reasoning ?? []);
71
- return {
72
- role: 'assistant',
73
- tool_calls: tools.map(toolCallEntry),
74
- ...(reasoning.length ? { reasoning } : {}),
75
- };
76
- }
77
63
  function toolResultMessage(tool, content) {
78
64
  return { role: 'tool', tool_call_id: tool.callId, name: tool.name, content };
79
65
  }
80
66
  function appendToolCallPair(history, tool, content) {
81
- return [...history, assistantCalls([tool]), toolResultMessage(tool, content)];
67
+ return [
68
+ ...history,
69
+ ...stepReplyMessages({ text: '', calls: [tool] }),
70
+ toolResultMessage(tool, content),
71
+ ];
82
72
  }
83
73
  /** The history with a tool call and its result added. */
84
74
  function appendToolExchangeToHistory(history, call) {
@@ -108,12 +98,14 @@ function settledToolContent(call) {
108
98
  : undefined;
109
99
  }
110
100
  /**
111
- * One model step's settled calls: a single assistant message holding every call
112
- * the step made, with the reasoning written before them, then each result, as a provider
113
- * reads a step's calls back. With `gated: 'open'`, a
114
- * 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.
115
106
  */
116
- function appendToolStepToHistory(history, calls, gated = 'omit') {
107
+ function appendToolStepToHistory(history, step, gated = 'omit') {
108
+ const { text, calls } = step;
117
109
  const entries = calls.flatMap((call) => {
118
110
  const content = settledToolContent(call);
119
111
  if (content !== undefined)
@@ -122,11 +114,9 @@ function appendToolStepToHistory(history, calls, gated = 'omit') {
122
114
  ? [{ tool: historyToolCall(call) }]
123
115
  : [];
124
116
  });
125
- if (entries.length === 0)
126
- return history;
127
117
  return [
128
118
  ...history,
129
- assistantCalls(entries.map(({ tool }) => tool)),
119
+ ...stepReplyMessages({ text, calls: entries.map(({ tool }) => tool) }),
130
120
  ...entries.flatMap(({ tool, content }) => content === undefined ? [] : [toolResultMessage(tool, content)]),
131
121
  ];
132
122
  }
@@ -159,7 +149,7 @@ function foldAssistantEvents(history, events, gated) {
159
149
  return;
160
150
  }
161
151
  const stepCalls = step.callKeys.flatMap((id) => calls.get(id) ?? []);
162
- next = appendToolStepToHistory(next, stepCalls, gated);
152
+ next = appendToolStepToHistory(next, { text: step.text, calls: stepCalls }, gated);
163
153
  step = undefined;
164
154
  };
165
155
  for (const event of keptReply(events)) {
@@ -171,7 +161,7 @@ function foldAssistantEvents(history, events, gated) {
171
161
  if (event.type === 'late_results') {
172
162
  flushStep();
173
163
  flushText();
174
- next = [...next, { role: 'user', content: event.text }];
164
+ next = [...next, lateResultsMessage(event.text, event.operationIds)];
175
165
  continue;
176
166
  }
177
167
  if (event.type === 'stage' && event.injected) {
@@ -199,8 +189,9 @@ function foldAssistantEvents(history, events, gated) {
199
189
  }
200
190
  if (!step || call.stepId === undefined || step.stepId !== call.stepId) {
201
191
  flushStep();
202
- flushText();
203
- 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 = '';
204
195
  }
205
196
  step.callKeys.push(key);
206
197
  }
@@ -211,30 +202,43 @@ function foldAssistantEvents(history, events, gated) {
211
202
  /** Attachment and voice blocks are omitted: their preview `data` is UI-only. */
212
203
  function historyFromTranscriptBlocks(blocks) {
213
204
  let history = [];
214
- 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
+ };
215
212
  const flushStep = () => {
216
- history = appendToolStepToHistory(history, step);
217
- step = [];
213
+ if (step.calls.length)
214
+ history = appendToolStepToHistory(history, step);
215
+ step = { text: '', calls: [] };
218
216
  };
219
217
  for (const block of blocks) {
220
218
  if (block.kind === 'tool') {
221
- const open = step[0];
219
+ const open = step.calls[0];
222
220
  if (open && (open.stepId === undefined || open.stepId !== block.tool.stepId))
223
221
  flushStep();
224
- 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);
225
228
  continue;
226
229
  }
227
230
  flushStep();
231
+ flushText();
228
232
  if (block.kind === 'user-text') {
229
233
  history = appendUserDraftToHistory(history, { text: block.text });
230
234
  continue;
231
235
  }
232
236
  if (block.kind === 'text') {
233
- history = [...history, { role: 'assistant', content: block.text }];
237
+ text = block.text;
234
238
  continue;
235
239
  }
236
240
  if (block.kind === 'late-results') {
237
- history = [...history, { role: 'user', content: block.text }];
241
+ history = [...history, lateResultsMessage(block.text, block.operationIds)];
238
242
  continue;
239
243
  }
240
244
  if (block.kind === 'structured') {
@@ -242,6 +246,7 @@ function historyFromTranscriptBlocks(blocks) {
242
246
  }
243
247
  }
244
248
  flushStep();
249
+ flushText();
245
250
  return history;
246
251
  }
247
252
  function lastToolStep(history) {
@@ -17,7 +17,6 @@ function applyToolEvent(call, tool) {
17
17
  arguments: tool.arguments,
18
18
  ...(tool.reasoning ? { reasoning: tool.reasoning } : {}),
19
19
  ...(tool.stepId ? { stepId: tool.stepId } : {}),
20
- artifacts: [],
21
20
  };
22
21
  }
23
22
  if (call === undefined) {
@@ -52,8 +51,6 @@ function applyToolEvent(call, tool) {
52
51
  return { ...settled(call), state: tool, endedAt: tool.at };
53
52
  case 'draft':
54
53
  return { ...call, outputDraft: (call.outputDraft ?? '') + tool.text };
55
- case 'artifact':
56
- return { ...call, artifacts: [...call.artifacts, tool.artifact] };
57
54
  case 'progress':
58
55
  return withAgentStep(call, tool.data);
59
56
  case 'dispatch':
@@ -74,7 +71,6 @@ function settled(call) {
74
71
  function applyToolDraft(call, draft) {
75
72
  return {
76
73
  arguments: {},
77
- artifacts: [],
78
74
  ...call,
79
75
  name: draft.name,
80
76
  callId: draft.callId,
@@ -183,7 +183,6 @@ export interface ToolCall {
183
183
  startedAt?: number;
184
184
  /** When it last settled: complete, failed, cancelled, or gated (epoch ms). */
185
185
  endedAt?: number;
186
- artifacts: unknown[];
187
186
  /** An agent tool's: the calls its agent made, in order, from the call's `progress` phases. */
188
187
  steps?: ToolCall[];
189
188
  }
@@ -241,6 +240,8 @@ export interface GuardrailBlock extends TranscriptBlockBase {
241
240
  export interface LateResultsBlock extends TranscriptBlockBase {
242
241
  kind: 'late-results';
243
242
  text: string;
243
+ /** The calls whose results the message holds. */
244
+ operationIds: string[];
244
245
  }
245
246
  export interface ErrorBlock extends TranscriptBlockBase {
246
247
  kind: 'error';
@@ -266,7 +266,7 @@ async function* emitTurn(args) {
266
266
  });
267
267
  args.outState.state = state;
268
268
  if (state.lateResults !== undefined) {
269
- const late = { type: 'late_results', text: state.lateResults };
269
+ const late = { type: 'late_results', ...state.lateResults };
270
270
  state.allEmittedEvents.push(late);
271
271
  yield late;
272
272
  }
@@ -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
  }
@@ -67,8 +67,11 @@ interface StepExecutionState {
67
67
  name: string;
68
68
  text: string;
69
69
  };
70
- /** The message `input.lateResults` opened, until the run can emit it. */
71
- lateResults?: string;
70
+ /** The message `input.lateResults` opened and the calls it holds, until the run can emit it. */
71
+ lateResults?: {
72
+ text: string;
73
+ operationIds: string[];
74
+ };
72
75
  /** The canary opening the last provider call ended on, read in front of the next call's reply. */
73
76
  canaryCarry?: string;
74
77
  /** What the last provider call's thoughts ended on, read in front of the next call's thoughts. */
@@ -1,7 +1,8 @@
1
1
  import { addFencedDestinations, addGivenDestinations, addResultDestinations, turnDestinations, } from '../../../guardrails/destinations.js';
2
2
  import { addSeenUrls, givenUrlSets } from '../../../guardrails/egress-urls.js';
3
+ import { TheoremError } from '../../../guardrails/error.js';
3
4
  import { labelText } from '../../../guardrails/labels.js';
4
- import { isLateResult, readToolData } from '../../../guardrails/tool-fence.js';
5
+ import { isLateResult, lateResultIds, lateResultsMessage, readToolData, } from '../../../guardrails/tool-fence.js';
5
6
  import { isRemoteOrigin, recordTaint, wrapToolData } from '../../../guardrails/tool-result.js';
6
7
  import { originOfTool } from '../../tools/execute.js';
7
8
  import { isFramedToolFailure } from '../../tools/model-text.js';
@@ -66,8 +67,19 @@ function carryReplyReads(state, history) {
66
67
  function openLateResults(state, outcomes, labels) {
67
68
  if (outcomes.length === 0)
68
69
  return;
69
- const blocks = outcomes.map(({ event, replay }) => {
70
- const { name, readBack = '' } = event.tool;
70
+ const read = new Set(state.currentHistory.flatMap(lateResultIds));
71
+ const unread = outcomes.filter(({ event }) => {
72
+ const { operationId } = event.tool;
73
+ if (!operationId) {
74
+ // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
75
+ throw new TheoremError('request', 'A late result needs the operationId of its call');
76
+ }
77
+ return !read.has(operationId);
78
+ });
79
+ if (unread.length === 0)
80
+ return;
81
+ const blocks = unread.map(({ event, replay }) => {
82
+ const { name, operationId = '', readBack = '' } = event.tool;
71
83
  const result = replay.modelResult;
72
84
  const provenance = result?.provenance ?? { origin: 'local', tool: name, depth: 1 };
73
85
  if (result?.provenance) {
@@ -76,16 +88,17 @@ function openLateResults(state, outcomes, labels) {
76
88
  }
77
89
  addSeenUrls(state.givenUrls.tools, readBack);
78
90
  const fenced = readToolData(readBack).length > 0 ? readBack : wrapToolData(readBack, provenance);
79
- return `${labelText('tool.late_result', { tool: name }, labels)}\n${fenced}`;
91
+ return {
92
+ operationId,
93
+ text: `${labelText('tool.late_result', { tool: name }, labels)}\n${fenced}`,
94
+ };
80
95
  });
81
- const unread = blocks.filter((block) => !state.currentHistory.some((message) => isLateResult(message) && message.content?.includes(block)));
82
- if (unread.length === 0)
83
- return;
84
- const text = unread.join('\n\n');
85
- const message = { role: 'user', content: text };
96
+ const text = blocks.map((block) => block.text).join('\n\n');
97
+ const operationIds = blocks.map((block) => block.operationId);
98
+ const message = lateResultsMessage(text, operationIds);
86
99
  state.givenUrls.own.add(message);
87
100
  state.currentHistory.push(message);
88
- state.lateResults = text;
101
+ state.lateResults = { text, operationIds };
89
102
  }
90
103
  /**
91
104
  * Step state for one turn. A text turn's history grows inside the turn (tool
@@ -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
- }
@@ -14,7 +14,7 @@ export interface HandlerEventChecks {
14
14
  policy: ResolvedGuardrailPolicy;
15
15
  /** `tool_output_<kind>`. */
16
16
  boundary: ToolBoundary;
17
- /** `tool_shown_<kind>`: what its artifacts and trace are read at. */
17
+ /** `tool_shown_<kind>`: what its trace is read at. */
18
18
  shown: ToolBoundary;
19
19
  callableTools: readonly string[];
20
20
  /** Whether the host sees the handler's drafts (`outputs.streaming.mode` `sse`). */
@@ -12,9 +12,6 @@ export function* yieldHandlerSideEvent(base, event) {
12
12
  else if (event.kind === 'trace') {
13
13
  yield toolEvent(base, { phase: 'trace', step: event.step });
14
14
  }
15
- else if (event.kind === 'artifact') {
16
- yield toolEvent(base, { phase: 'artifact', artifact: event.artifact });
17
- }
18
15
  else if (event.kind === 'warning') {
19
16
  yield toolEvent(base, { phase: 'warning', warning: event.warning });
20
17
  }
@@ -43,12 +40,6 @@ export class HandlerEvents {
43
40
  }
44
41
  if (event.kind === 'progress' && (yield* this.progressStops(event.data)))
45
42
  return;
46
- if (event.kind === 'artifact') {
47
- const artifact = yield* this.shown(event.artifact);
48
- if (artifact.shown)
49
- yield* yieldHandlerSideEvent(this.base, { ...event, artifact: artifact.value });
50
- return;
51
- }
52
43
  if (event.kind === 'trace') {
53
44
  const step = yield* this.shown(event.step);
54
45
  if (step.shown) {
@@ -180,9 +180,6 @@ export type ToolStreamEvent<TOut = unknown> = {
180
180
  } | {
181
181
  kind: 'trace';
182
182
  step: ToolTraceStep;
183
- } | {
184
- kind: 'artifact';
185
- artifact: unknown;
186
183
  } | {
187
184
  kind: 'warning';
188
185
  warning: ToolWarning;
@@ -431,7 +431,7 @@ export interface ToolCallEdit {
431
431
  *
432
432
  * - `running` — the body started; `edited` when the user changed the arguments;
433
433
  * `activity` is the tool's activity label filled from the call's input.
434
- * - `progress` / `trace` / `artifact` / `warning` — streamed while it ran. A `progress` its
434
+ * - `progress` / `trace` / `warning` — streamed while it ran. A `progress` its
435
435
  * output's check stops is not sent.
436
436
  * - `draft` — the next piece of what the tool is writing, for a preview, each piece read at
437
437
  * `tool_output_<kind>` first (an agent tool's: its agent's reply). Sent only under
@@ -466,9 +466,6 @@ export type ToolPhaseEvent = ToolPhaseBase & ({
466
466
  } | {
467
467
  phase: 'trace';
468
468
  step: ToolTraceStep;
469
- } | {
470
- phase: 'artifact';
471
- artifact: unknown;
472
469
  } | {
473
470
  phase: 'warning';
474
471
  warning: ToolWarning;
@@ -677,11 +674,12 @@ export type TurnEvent = {
677
674
  }
678
675
  /**
679
676
  * The message `input.lateResults` put in the conversation, role `user`. It enters a history built
680
- * from events like any other message.
677
+ * from events like any other message. `operationIds` are the calls whose results it holds.
681
678
  */
682
679
  | {
683
680
  type: 'late_results';
684
681
  text: string;
682
+ operationIds: string[];
685
683
  } | {
686
684
  type: 'media';
687
685
  media: {
@@ -294,7 +294,6 @@ const toolPhaseEvent = z.discriminatedUnion('phase', [
294
294
  z.object({ ...toolPhaseBase, phase: z.literal('progress'), data: z.unknown() }),
295
295
  z.object({ ...toolPhaseBase, phase: z.literal('draft'), text: z.string() }),
296
296
  z.object({ ...toolPhaseBase, phase: z.literal('trace'), step: toolTraceStep }),
297
- z.object({ ...toolPhaseBase, phase: z.literal('artifact'), artifact: z.unknown() }),
298
297
  z.object({ ...toolPhaseBase, phase: z.literal('warning'), warning: toolWarning }),
299
298
  z.object({
300
299
  ...toolPhaseBase,
@@ -430,7 +429,11 @@ const TURN_EVENTS = {
430
429
  attempt: z.number().int().positive(),
431
430
  reason: z.enum(['validation', 'egress']),
432
431
  }),
433
- late_results: z.object({ type: z.literal('late_results'), text: z.string() }),
432
+ late_results: z.object({
433
+ type: z.literal('late_results'),
434
+ text: z.string(),
435
+ operationIds: z.array(z.string()),
436
+ }),
434
437
  media: z.object({
435
438
  type: z.literal('media'),
436
439
  media: z.object({ mimeType: z.string(), data: z.string() }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.917.g6cb0b91",
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",