@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.
- package/esm/src/guardrails/boundaries.d.ts +1 -1
- package/esm/src/guardrails/boundaries.js +2 -2
- package/esm/src/guardrails/labels.js +1 -1
- package/esm/src/guardrails/tool-fence.d.ts +5 -1
- package/esm/src/guardrails/tool-fence.js +10 -1
- package/esm/src/guardrails/tool-result.d.ts +1 -1
- package/esm/src/guardrails/tool-result.js +1 -1
- package/esm/src/interface/blocks.js +6 -1
- package/esm/src/interface/history.js +3 -2
- package/esm/src/interface/tool-calls.js +0 -4
- package/esm/src/interface/types.d.ts +2 -1
- package/esm/src/kernel/engine/runner/mod.js +1 -1
- package/esm/src/kernel/engine/runner/state.d.ts +5 -2
- package/esm/src/kernel/engine/runner/state.js +23 -10
- package/esm/src/kernel/tools/handler-events.d.ts +1 -1
- package/esm/src/kernel/tools/handler-events.js +0 -9
- package/esm/src/kernel/tools/types.d.ts +0 -3
- package/esm/src/kernel/turn-events.d.ts +3 -5
- package/esm/src/kernel/turn-events.js +5 -2
- package/package.json +1 -1
|
@@ -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,
|
|
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,
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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 {
|
|
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,
|
|
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,
|
|
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',
|
|
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?:
|
|
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
|
|
70
|
-
|
|
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
|
|
91
|
+
return {
|
|
92
|
+
operationId,
|
|
93
|
+
text: `${labelText('tool.late_result', { tool: name }, labels)}\n${fenced}`,
|
|
94
|
+
};
|
|
80
95
|
});
|
|
81
|
-
const
|
|
82
|
-
|
|
83
|
-
|
|
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
|
|
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) {
|
|
@@ -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` / `
|
|
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({
|
|
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.
|
|
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",
|