@theoremjs/agents 0.3.4-next.733.g0520b79 → 0.3.4-next.735.g8d504c6

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.
@@ -7,6 +7,7 @@
7
7
  import { labelText } from './labels.js';
8
8
  import { TOOL_RULES } from './rules.js';
9
9
  import { textForScan } from './serialize.js';
10
+ import { isLateResult } from './tool-fence.js';
10
11
  import { isRemoteOrigin } from './tool-result.js';
11
12
  function turnDestinations() {
12
13
  return { given: new Set(), remote: new Map() };
@@ -165,8 +166,12 @@ function addGivenDestinations(turn, value) {
165
166
  function addHistoryDestinations(turn, messages, own) {
166
167
  for (const message of messages) {
167
168
  // why: An earlier turn's tool result is neither the user's word nor this turn's read.
168
- if (message.role === 'assistant' || message.role === 'tool' || own.has(message))
169
+ if (message.role === 'assistant' ||
170
+ message.role === 'tool' ||
171
+ own.has(message) ||
172
+ isLateResult(message)) {
169
173
  continue;
174
+ }
170
175
  addGivenDestinations(turn, textForScan(message).text);
171
176
  }
172
177
  }
@@ -15,6 +15,7 @@
15
15
  * @module
16
16
  */
17
17
  import { textForScan } from './serialize.js';
18
+ import { isLateResult } from './tool-fence.js';
18
19
  function givenUrlSets() {
19
20
  return { request: new Set(), tools: new Set(), own: new WeakSet() };
20
21
  }
@@ -156,7 +157,8 @@ function addHistoryUrls(given, messages) {
156
157
  for (const message of messages) {
157
158
  if (message.role === 'assistant' || given.own.has(message))
158
159
  continue;
159
- addSeenUrls(message.role === 'tool' ? given.tools : given.request, textForScan(message).text);
160
+ const read = message.role === 'tool' || isLateResult(message);
161
+ addSeenUrls(read ? given.tools : given.request, textForScan(message).text);
160
162
  }
161
163
  }
162
164
  function addRequestUrls(given, request) {
@@ -48,7 +48,8 @@ export type { ScanText } from './serialize.js';
48
48
  export { scanTextOf, textForScan } from './serialize.js';
49
49
  export type { Directive, DirectiveSignal } from './tool-directives.js';
50
50
  export { advisoryLevel, DIRECTIVE_SIGNALS, directives } from './tool-directives.js';
51
+ export { TOOL_CLOSE } from './tool-fence.js';
51
52
  export type { GuardedToolText, InspectedToolArguments } from './tool-result.js';
52
- export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, } from './tool-result.js';
53
+ export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, } from './tool-result.js';
53
54
  export type { AdvisoryLevel, BlockedReplyOnBlock, BlockedReplySpec, DecisionDisclosureEnforcer, DecisionDisclosureVerdict, DecisionGuardrailsSpec, DestinationGate, GuardrailAction, GuardrailContext, GuardrailEvent, GuardrailHit, GuardrailStage, HostGuardrailsSpec, NetworkGuardrailSpec, OutboundPayload, ProfileGuardrailsSpec, Provenance, QuotaGuardrailSpec, ResolvedBlockedReply, ResolvedGuardrailPolicy, Severity, TaintGate, TaintGuardrailSpec, ToolOrigin, TrustLevel, TurnTaint, Verdict, } from './types.js';
54
55
  export { ADVISORY_LEVELS, BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';
@@ -30,5 +30,6 @@ export { sensitiveSpans } from './sensitive.js';
30
30
  export { SENSITIVE_GROUPS } from './sensitive-groups.js';
31
31
  export { scanTextOf, textForScan } from './serialize.js';
32
32
  export { advisoryLevel, DIRECTIVE_SIGNALS, directives } from './tool-directives.js';
33
- export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, } from './tool-result.js';
33
+ export { TOOL_CLOSE } from './tool-fence.js';
34
+ export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, } from './tool-result.js';
34
35
  export { ADVISORY_LEVELS, BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';
@@ -0,0 +1,23 @@
1
+ import type { TurnHistoryMessage } from '../kernel/turn-events.js';
2
+ import type { GuardrailHit, Provenance } from './types.js';
3
+ /** The closing tag of the fence a tool result is wrapped in. */
4
+ declare const TOOL_CLOSE = "</tool_data>";
5
+ /** What a fence from `wrapToolData` says of the text inside it. */
6
+ export interface ToolDataRead {
7
+ provenance: Provenance;
8
+ suspicious: GuardrailHit[];
9
+ /** The result as `composeToolText` joined it. */
10
+ text: string;
11
+ }
12
+ /**
13
+ * Reads each whole fence in a message. A sign-in note can stand before one, and a late-result
14
+ * message holds one for each result. `stripToolFences` has taken any forged tag out of a body, so
15
+ * what a tag says is the kernel's.
16
+ */
17
+ declare function readToolData(content: string): ToolDataRead[];
18
+ /**
19
+ * Whether a role `user` message holds tool results that `input.lateResults` opened. It is no one's
20
+ * word to the model. A person who types a fence only makes their own reply stricter.
21
+ */
22
+ declare function isLateResult(message: TurnHistoryMessage): boolean;
23
+ export { isLateResult, readToolData, TOOL_CLOSE };
@@ -0,0 +1,38 @@
1
+ import { DETECT_RULES } from './rules.js';
2
+ /** The closing tag of the fence a tool result is wrapped in. */
3
+ const TOOL_CLOSE = '</tool_data>';
4
+ const FENCE_OPEN = /^<tool_data tool="([^"]*)" origin="([^"]*)"( advisory="[^"]*")?>\n/gm;
5
+ /**
6
+ * Reads each whole fence in a message. A sign-in note can stand before one, and a late-result
7
+ * message holds one for each result. `stripToolFences` has taken any forged tag out of a body, so
8
+ * what a tag says is the kernel's.
9
+ */
10
+ function readToolData(content) {
11
+ const reads = [];
12
+ for (const open of content.matchAll(FENCE_OPEN)) {
13
+ const [opening, tool = '', origin = '', advised] = open;
14
+ const start = open.index + opening.length;
15
+ const end = content.indexOf(`\n${TOOL_CLOSE}`, start);
16
+ if (end < 0)
17
+ continue;
18
+ const body = content.slice(start, end);
19
+ reads.push({
20
+ provenance: { origin: origin, tool, depth: origin === 'delegated' ? 2 : 1 },
21
+ suspicious: advised
22
+ ? [{ rule: DETECT_RULES.tool_instructions, severity: 'high' }]
23
+ : [],
24
+ text: advised ? body.slice(body.indexOf('\n') + 1) : body,
25
+ });
26
+ }
27
+ return reads;
28
+ }
29
+ /**
30
+ * Whether a role `user` message holds tool results that `input.lateResults` opened. It is no one's
31
+ * word to the model. A person who types a fence only makes their own reply stricter.
32
+ */
33
+ function isLateResult(message) {
34
+ return (message.role === 'user' &&
35
+ message.content !== undefined &&
36
+ readToolData(message.content).length > 0);
37
+ }
38
+ export { isLateResult, readToolData, TOOL_CLOSE };
@@ -2,8 +2,6 @@ import type { ToolBoundary } from './boundaries.js';
2
2
  import { type DetectScope } from './detect-at.js';
3
3
  import { type LabelOverrides } from './labels.js';
4
4
  import type { AdvisoryLevel, GuardrailEvent, GuardrailHit, Provenance, ResolvedGuardrailPolicy, ToolOrigin, TurnTaint, Verdict } from './types.js';
5
- /** The closing tag of the fence a tool result is wrapped in. */
6
- declare const TOOL_CLOSE = "</tool_data>";
7
5
  /** True when the tool's bytes come from outside the host. */
8
6
  declare function isRemoteOrigin(origin: ToolOrigin): boolean;
9
7
  /**
@@ -11,18 +9,6 @@ declare function isRemoteOrigin(origin: ToolOrigin): boolean;
11
9
  * friendlier provenance than it has by writing one into its own body.
12
10
  */
13
11
  declare function wrapToolData(text: string, provenance: Provenance, advisory?: AdvisoryLevel, labels?: LabelOverrides): string;
14
- /** What a fence from `wrapToolData` says of the text inside it. */
15
- export interface ToolDataRead {
16
- provenance: Provenance;
17
- suspicious: GuardrailHit[];
18
- /** The result as `composeToolText` joined it. */
19
- text: string;
20
- }
21
- /**
22
- * Reads the fence at the start of a tool message. `stripToolFences` has taken any forged tag out of
23
- * the body, so what the tag says is the kernel's. `undefined` when `content` is not one whole fence.
24
- */
25
- declare function readToolData(content: string): ToolDataRead | undefined;
26
12
  /** A tool result after the guard: the text the model sees, any event, and the suspicious hits. */
27
13
  export interface GuardedToolText {
28
14
  /** Absent when a match blocks: the model does not read the text. */
@@ -101,4 +87,4 @@ declare function isSuspicious(taint: TurnTaint | undefined): boolean;
101
87
  * or not enforcement is configured, so the risk is visible before a host opts in.
102
88
  */
103
89
  declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy, labels?: LabelOverrides): Verdict;
104
- export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, readToolData, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };
90
+ export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
@@ -5,8 +5,7 @@ import { labelText } from './labels.js';
5
5
  import { DETECT_RULES, EGRESS_RULES, TOOL_RULES } from './rules.js';
6
6
  import { textForScan } from './serialize.js';
7
7
  import { advisoryLevel } from './tool-directives.js';
8
- /** The closing tag of the fence a tool result is wrapped in. */
9
- const TOOL_CLOSE = '</tool_data>';
8
+ import { TOOL_CLOSE } from './tool-fence.js';
10
9
  const TOOL_OPEN = '<tool_data';
11
10
  /** Origins whose bytes the host does not author and cannot vouch for. */
12
11
  const REMOTE_ORIGINS = new Set(['http', 'mcp', 'delegated']);
@@ -66,25 +65,6 @@ function wrapToolData(text, provenance, advisory = 'none', labels) {
66
65
  : `${advisoryNotice(advisory, labels)}${guidance ? ` ${guidance}` : ''}\n`;
67
66
  return `<${'tool_data'} ${attrs}>\n${notice}${stripToolFences(text)}\n${TOOL_CLOSE}`;
68
67
  }
69
- /**
70
- * Reads the fence at the start of a tool message. `stripToolFences` has taken any forged tag out of
71
- * the body, so what the tag says is the kernel's. `undefined` when `content` is not one whole fence.
72
- */
73
- function readToolData(content) {
74
- const open = /^<tool_data tool="([^"]*)" origin="([^"]*)"(?: advisory="[^"]*")?>\n/.exec(content);
75
- if (!(open && content.endsWith(`\n${TOOL_CLOSE}`)))
76
- return undefined;
77
- const [opening, tool = '', origin = ''] = open;
78
- const body = content.slice(opening.length, -TOOL_CLOSE.length - 1);
79
- const advised = opening.includes(' advisory=');
80
- return {
81
- provenance: { origin: origin, tool, depth: origin === 'delegated' ? 2 : 1 },
82
- suspicious: advised
83
- ? [{ rule: DETECT_RULES.tool_instructions, severity: 'high' }]
84
- : [],
85
- text: advised ? body.slice(body.indexOf('\n') + 1) : body,
86
- };
87
- }
88
68
  /**
89
69
  * Deliberately an observation, not an instruction: what the agent should do about
90
70
  * it is product behaviour, supplied by the host as labels `advisory.guidance`. Emitted
@@ -288,4 +268,4 @@ function checkTaintGate(taint, access, policy, labels) {
288
268
  rejection: labelText('taint.blocked', { access, sources: read, reason }, labels),
289
269
  };
290
270
  }
291
- export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, readToolData, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };
271
+ export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
@@ -243,7 +243,7 @@ async function* emitTurn(args) {
243
243
  tools: args.registry.tools,
244
244
  profile,
245
245
  generation,
246
- input: safe.input ?? {},
246
+ request: safe,
247
247
  trace: args.trace,
248
248
  ...(args.agents ? { agents: args.agents } : {}),
249
249
  ...(args.background ? { background: args.background } : {}),
@@ -6,7 +6,7 @@ import type { SpanHandle } from '../../../observability/trace-span.js';
6
6
  import type { AgentCaller } from '../../tools/agent.js';
7
7
  import type { ToolBackgroundSupport } from '../../tools/background.js';
8
8
  import type { ToolRegistry } from '../../tools/registry.js';
9
- import type { InteractionPart, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnInput, TurnRequest, TurnStop, TurnToolResult } from '../../types.js';
9
+ import type { InteractionPart, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest, TurnStop, TurnToolResult } from '../../types.js';
10
10
  import type { ItemFailure } from './schema-validation.js';
11
11
  import type { CallUsage } from './usage.js';
12
12
  interface TurnTraceState {
@@ -109,8 +109,8 @@ declare function openTurnState(args: {
109
109
  tools: ToolRegistry;
110
110
  profile: Profile;
111
111
  generation: ResolvedGeneration;
112
- /** The request's input, on the run that opens the turn. */
113
- input?: TurnInput;
112
+ /** The request, on the run that opens the turn. */
113
+ request?: TurnRequest;
114
114
  trace: TurnTraceState;
115
115
  allEmittedEvents?: TurnEvent[];
116
116
  agents?: AgentCaller;
@@ -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
3
  import { labelText } from '../../../guardrails/labels.js';
4
- import { isRemoteOrigin, readToolData, recordTaint, wrapToolData, } from '../../../guardrails/tool-result.js';
4
+ import { isLateResult, readToolData } from '../../../guardrails/tool-fence.js';
5
+ import { isRemoteOrigin, recordTaint, wrapToolData } from '../../../guardrails/tool-result.js';
5
6
  import { originOfTool } from '../../tools/execute.js';
6
7
  import { ownToolsOf } from '../../tools/project.js';
7
8
  function recordStepEvent(event, state) {
@@ -18,26 +19,38 @@ function appendUserInput(state, parts) {
18
19
  : { role: 'user', parts: [...parts] });
19
20
  }
20
21
  /** Whether this run goes on with a reply that an earlier run began, not with a new message. */
21
- function continuesReply(input, history) {
22
- if (input.text || input.attachments?.length || input.voice?.length)
22
+ function continuesReply({ continueFrom, input }) {
23
+ if (continueFrom)
24
+ return true;
25
+ if (input?.text || input?.attachments?.length || input?.voice?.length)
23
26
  return false;
24
- return history.at(-1)?.role === 'tool';
27
+ return input?.history?.at(-1)?.role === 'tool';
28
+ }
29
+ /** The reply's part of the history. Late results that opened it stand before its first message. */
30
+ function replyTail(history) {
31
+ let start = history.findLastIndex((message) => message.role === 'user');
32
+ while (start > 0 && isLateResult(history[start - 1]))
33
+ start -= 1;
34
+ return history.slice(Math.max(start, 0));
25
35
  }
26
36
  /**
27
37
  * invariant: Taint lasts for the reply that first read the text, and a pause does not end a reply.
28
- * The run after a pause reads the marks back from the tool results of that reply.
38
+ * The run after a pause reads the marks back from the tool results of that reply, in the history the
39
+ * request sent, because compaction can rewrite those results.
29
40
  */
30
41
  function carryReplyReads(state, history) {
31
- const start = history.findLastIndex((message) => message.role === 'user') + 1;
32
- for (const message of history.slice(start)) {
33
- if (message.role !== 'tool' || message.content === undefined)
42
+ for (const message of replyTail(history)) {
43
+ if (message.content === undefined)
44
+ continue;
45
+ if (message.role !== 'tool' && !isLateResult(message))
34
46
  continue;
35
- const read = readToolData(message.content);
36
- if (read) {
47
+ const reads = readToolData(message.content);
48
+ for (const read of reads) {
37
49
  state.taint = recordTaint(state.taint, read.provenance, read.suspicious);
38
50
  addFencedDestinations(state.destinations, read.text, read.provenance);
39
- continue;
40
51
  }
52
+ if (reads.length > 0)
53
+ continue;
41
54
  const tool = message.name ? state.tools.get(message.name) : undefined;
42
55
  if (tool && !isRemoteOrigin(originOfTool(tool, state.tools))) {
43
56
  addGivenDestinations(state.destinations, message.content);
@@ -57,7 +70,7 @@ function openLateResults(state, outcomes, labels) {
57
70
  addResultDestinations(state.destinations, result, result.provenance);
58
71
  }
59
72
  addSeenUrls(state.givenUrls.tools, readBack);
60
- const fenced = readToolData(readBack) ? readBack : wrapToolData(readBack, provenance);
73
+ const fenced = readToolData(readBack).length > 0 ? readBack : wrapToolData(readBack, provenance);
61
74
  return `${labelText('tool.late_result', { tool: name }, labels)}\n${fenced}`;
62
75
  });
63
76
  const message = { role: 'user', content: blocks.join('\n\n') };
@@ -96,10 +109,10 @@ function openTurnState(args) {
96
109
  ...(args.background ? { background: args.background } : {}),
97
110
  };
98
111
  if (profile.type === 'text') {
99
- if (args.input && continuesReply(args.input, state.currentHistory)) {
100
- carryReplyReads(state, state.currentHistory);
112
+ if (args.request && continuesReply(args.request)) {
113
+ carryReplyReads(state, args.request.input?.history ?? []);
101
114
  }
102
- openLateResults(state, args.input?.lateResults ?? [], profile.labels);
115
+ openLateResults(state, args.request?.input?.lateResults ?? [], profile.labels);
103
116
  appendUserInput(state, generation.input);
104
117
  generation.input = [];
105
118
  }
@@ -235,7 +235,9 @@ class CoordinatedExecution {
235
235
  finally {
236
236
  clearTimeout(this.graceTimer);
237
237
  await this.close().catch(() => { });
238
- await Promise.resolve(detach.trace.end()).catch(() => { });
238
+ await Promise.resolve()
239
+ .then(() => detach.trace.end())
240
+ .catch(() => { });
239
241
  }
240
242
  }
241
243
  async drain(iterator, first, emit) {
@@ -312,7 +314,7 @@ class CoordinatedExecution {
312
314
  message: `The result of ${name} is ${bytes} bytes, more than the ${limit} bytes kept for one tool result`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
313
315
  details: { bytes, maxOutcomeBytes: limit },
314
316
  };
315
- return failedOutcome(outcome.event.tool, outcome.effects, failure);
317
+ return failedOutcome(outcome.event.tool, outcome.effects, failure, outcome.event.tool.tokens);
316
318
  }
317
319
  replay(error) {
318
320
  const saved = toolOperationOutcomeSchema.parse(operationWireValue(error.outcome));
@@ -1103,8 +1103,8 @@ async function* executeAgentTool(args) {
1103
1103
  return;
1104
1104
  }
1105
1105
  const event = next.value;
1106
- seen.push(event);
1107
1106
  if (event.type === 'tokens' || event.type === 'tool') {
1107
+ seen.push(event);
1108
1108
  const spent = sumTurnTokens(seen);
1109
1109
  // why: A stopped agent throws before it returns its usage.
1110
1110
  if (spent)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.733.g0520b79",
3
+ "version": "0.3.4-next.735.g8d504c6",
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",