@theoremjs/agents 0.3.4-next.717.gd16ffc6 → 0.3.4-next.723.g003a589

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.
@@ -1,4 +1,4 @@
1
- import type { TurnEvent } from '../types.js';
1
+ import type { TurnEvent, TurnTokens } from '../types.js';
2
2
  import type { ToolDetach } from './background.js';
3
3
  import type { ToolExecuteSettlement } from './execute.js';
4
4
  import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperationIdentity, type ToolOperationOutcome } from './operation.js';
@@ -6,6 +6,7 @@ import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperat
6
6
  export interface ToolCallHooks {
7
7
  signal: AbortSignal | undefined;
8
8
  bodyEnded?: () => void;
9
+ spent?: (tokens: TurnTokens) => void;
9
10
  }
10
11
  export type ToolRun = (beginBody: ((preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) | undefined, hooks: ToolCallHooks) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
11
12
  export declare function coordinateTool(coordinator: ToolExecutionCoordinator | undefined, identity: Omit<ToolOperationIdentity, 'invocationHash'>, invocation: unknown, signal: AbortSignal | undefined, run: ToolRun, authorizeReplay?: (outcome?: ToolOperationOutcome) => void | Promise<void>, detach?: ToolDetach): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;
@@ -64,10 +64,11 @@ class DetachTrigger {
64
64
  }
65
65
  }
66
66
  /** A settled failure in place of what the run gave. */
67
- function failedOutcome(base, effects, failure) {
67
+ function failedOutcome(base, effects, failure, tokens) {
68
68
  const { name, callId, operationId } = base;
69
69
  const modelResult = formatToolFailureForModel(failure);
70
- const event = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
70
+ const failed = failureEvent({ name, callId, ...(operationId ? { operationId } : {}) }, failure);
71
+ const event = tokens ? { ...failed, tool: { ...failed.tool, tokens } } : failed;
71
72
  return toolOperationOutcomeSchema.parse(operationWireValue({ event, effects, replay: { modelResult, failure } }));
72
73
  }
73
74
  /** A gate after the claim cannot pause a call that was already sent; only a sign-in can ask for one there. */
@@ -85,6 +86,7 @@ class CoordinatedExecution {
85
86
  writeFailed = false;
86
87
  terminal;
87
88
  stopped;
89
+ spent;
88
90
  cut = settleable();
89
91
  graceTimer;
90
92
  constructor(coordinator, operation, accepted, signal, trigger) {
@@ -114,6 +116,9 @@ class CoordinatedExecution {
114
116
  this.trigger?.claimed();
115
117
  return this.claim;
116
118
  }
119
+ spend(tokens) {
120
+ this.spent = tokens;
121
+ }
117
122
  observe(event) {
118
123
  if (event.type !== 'tool')
119
124
  return true;
@@ -285,7 +290,7 @@ class CoordinatedExecution {
285
290
  }, emit);
286
291
  }
287
292
  async settleFailed(failure, emit) {
288
- const saved = failedOutcome(this.base(), 'unknown', failure);
293
+ const saved = failedOutcome(this.base(), 'unknown', failure, this.spent);
289
294
  await this.save(saved);
290
295
  await emit(saved.event);
291
296
  }
@@ -381,6 +386,7 @@ export async function* coordinateTool(coordinator, identity, invocation, signal,
381
386
  }
382
387
  const iterator = run((input) => execution.beginBody(input), {
383
388
  signal: callSignal,
389
+ spent: (tokens) => execution.spend(tokens),
384
390
  ...(trigger ? { bodyEnded: trigger.bodyEnded } : {}),
385
391
  });
386
392
  let handedOff = false;
@@ -6,6 +6,7 @@ import { labelText } from '../../guardrails/labels.js';
6
6
  import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
7
7
  import { checkTaintGate, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
8
8
  import { recordToolCheck, startToolTrace, } from '../engine/tool-trace.js';
9
+ import { sumTurnTokens } from '../engine/usage.js';
9
10
  import { jsonObjectSchema } from '../json.js';
10
11
  import { isAwaitingUserInput } from '../turn-events.js';
11
12
  import { isRecord } from '../util/record.js';
@@ -1091,6 +1092,7 @@ async function* executeAgentTool(args) {
1091
1092
  });
1092
1093
  // why: A retry throws away the reply drafted so far; the drafts stop there, and the output arrives whole.
1093
1094
  let retried = false;
1095
+ const seen = [];
1094
1096
  for (;;) {
1095
1097
  const next = await run.next();
1096
1098
  if (next.done) {
@@ -1101,6 +1103,13 @@ async function* executeAgentTool(args) {
1101
1103
  return;
1102
1104
  }
1103
1105
  const event = next.value;
1106
+ seen.push(event);
1107
+ if (event.type === 'tokens' || event.type === 'tool') {
1108
+ const spent = sumTurnTokens(seen);
1109
+ // why: A stopped agent throws before it returns its usage.
1110
+ if (spent)
1111
+ args.stages?.spent?.(spent);
1112
+ }
1104
1113
  if (event.type === 'attempt')
1105
1114
  retried = true;
1106
1115
  if (event.type === 'text' || event.type === 'structured_draft') {
@@ -248,7 +248,11 @@ function runCall(registry, request, profile, snapshot, callId, openSpan, failBef
248
248
  turnInput: request.turnInput,
249
249
  promoted: request.promoted,
250
250
  },
251
- }, request.signal, (beginBody, hooks) => invokePrepared(registry, { ...request, ...(hooks.signal ? { signal: hooks.signal } : {}) }, profile, snapshot, callId, detach?.trace.open ?? openSpan, failBeforeTool, canaries, beginBody, { ...step, ...(hooks.bodyEnded ? { bodyEnded: hooks.bodyEnded } : {}) }), (outcome) => authorizeToolReplay({
251
+ }, request.signal, (beginBody, hooks) => invokePrepared(registry, { ...request, ...(hooks.signal ? { signal: hooks.signal } : {}) }, profile, snapshot, callId, detach?.trace.open ?? openSpan, failBeforeTool, canaries, beginBody, {
252
+ ...step,
253
+ ...(hooks.bodyEnded ? { bodyEnded: hooks.bodyEnded } : {}),
254
+ ...(hooks.spent ? { spent: hooks.spent } : {}),
255
+ }), (outcome) => authorizeToolReplay({
252
256
  outcome,
253
257
  tools: registry.tools,
254
258
  profile,
@@ -3,7 +3,7 @@ import { type LabelOverrides } from '../../guardrails/labels.js';
3
3
  import type { SpanHandle } from '../../observability/trace-span.js';
4
4
  import type { ToolAccess } from '../schema.js';
5
5
  import { type InjectUnit, type StageHandler, type StageResult, type StepCall } from '../stages.js';
6
- import type { Profile, TurnEvent, TurnHistoryMessage } from '../types.js';
6
+ import type { Profile, TurnEvent, TurnHistoryMessage, TurnTokens } from '../types.js';
7
7
  import { type ToolCallBase } from './events.js';
8
8
  import type { ModelToolResult, ToolContext, ToolFailure, ToolGate, ToolLabels } from './types.js';
9
9
  /** How a call's wait for other calls in its step ended: they settled, or the wait cannot end. */
@@ -36,6 +36,8 @@ export interface ToolStageSupport {
36
36
  drafts?: boolean;
37
37
  /** Told when the body has ended, before `post_tool` reads it. */
38
38
  bodyEnded?: () => void;
39
+ /** Told what an agent tool's turn has spent so far. */
40
+ spent?: (tokens: TurnTokens) => void;
39
41
  }
40
42
  export type PreBodyOutcome = {
41
43
  ok: true;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.717.gd16ffc6",
3
+ "version": "0.3.4-next.723.g003a589",
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",