@theoremjs/agents 0.3.5-next.917.g6cb0b91 → 0.3.5-next.918.g28ade76

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,7 @@
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';
5
6
  import { mediaKindForMime } from '../kernel/registry/catalog.js';
6
7
  import { formatToolFailureForModel, formatToolResult } from '../kernel/tools/model-text.js';
7
8
  import { keptReply } from '../kernel/turn-events.js';
@@ -171,7 +172,7 @@ function foldAssistantEvents(history, events, gated) {
171
172
  if (event.type === 'late_results') {
172
173
  flushStep();
173
174
  flushText();
174
- next = [...next, { role: 'user', content: event.text }];
175
+ next = [...next, lateResultsMessage(event.text, event.operationIds)];
175
176
  continue;
176
177
  }
177
178
  if (event.type === 'stage' && event.injected) {
@@ -234,7 +235,7 @@ function historyFromTranscriptBlocks(blocks) {
234
235
  continue;
235
236
  }
236
237
  if (block.kind === 'late-results') {
237
- history = [...history, { role: 'user', content: block.text }];
238
+ history = [...history, lateResultsMessage(block.text, block.operationIds)];
238
239
  continue;
239
240
  }
240
241
  if (block.kind === 'structured') {
@@ -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
  }
@@ -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
@@ -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.918.g28ade76",
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",