@tangle-network/agent-app 0.60.274 → 0.60.276

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,5 +1,5 @@
1
1
  import type { ChatAttachmentInput } from '../chat-routes/wire.js';
2
- import type { OperatorApproval, OperatorAssetRef, OperatorFile, OperatorFileEntry, OperatorJournalEntry, OperatorRole, OperatorScorecard } from './contract.js';
2
+ import type { OperatorApproval, OperatorAssetRef, OperatorFile, OperatorFileEntry, OperatorJournalEntry, OperatorRole, OperatorScorecard, OperatorTurn } from './contract.js';
3
3
  import { type OperatorAdapter, type OperatorContext } from './server.js';
4
4
  /** The message fields the adapter reads; agent-app's chat-store rows satisfy it. */
5
5
  export interface ChatOperatorMessage {
@@ -12,6 +12,10 @@ export interface ChatOperatorMessage {
12
12
  model?: string | null;
13
13
  servedModel?: string | null;
14
14
  costUsd?: number | null;
15
+ /** Usage columns as chat-store stores them; see `operatorTurnUsage` for what `inputTokens` holds. */
16
+ inputTokens?: number | null;
17
+ cacheReadTokens?: number | null;
18
+ outputTokens?: number | null;
15
19
  /** The row's product metadata, for a `failureOf` that reads a stamped turn status. */
16
20
  metadata?: Record<string, unknown> | null;
17
21
  }
@@ -143,7 +147,40 @@ export interface ChatOperatorAdapterOptions<Identity> {
143
147
  code?: string;
144
148
  message: string;
145
149
  } | null;
150
+ /**
151
+ * Whether stored rows' `inputTokens` include cache reads, for
152
+ * `operatorTurnUsage`. A row does not say which writer or version stored
153
+ * it, so pass a boolean only when every writer of the app's rows is known
154
+ * to follow it. Default `'unknown'` reports `inputTokens` only on rows that
155
+ * record zero cache reads.
156
+ */
157
+ inputIncludesCache?: boolean | 'unknown';
146
158
  }
159
+ /**
160
+ * The operator turn usage of a stored assistant row, for `OperatorTurn.usage`.
161
+ * `cachedInputTokens` is the row's `cacheReadTokens` and `outputTokens` its
162
+ * `outputTokens`, each when the row has it. `inputTokens` is reported only as
163
+ * the prompt NOT read from cache, and a row does not record whether its
164
+ * `inputTokens` already excludes cache reads: the Router lane subtracts them
165
+ * before storing since 0.60.248 and included them before, and the sandbox
166
+ * lanes store the split their upstream reports. A missing `cacheReadTokens`
167
+ * is unknown, not 0. So:
168
+ * - `'unknown'` (the default) reports the row's `inputTokens` only when
169
+ * `cacheReadTokens` is a recorded 0, and omits it otherwise;
170
+ * - `inputIncludesCache: false` reports the row's `inputTokens`, with or
171
+ * without a recorded `cacheReadTokens`;
172
+ * - `inputIncludesCache: true` reports `inputTokens - cacheReadTokens` when
173
+ * `cacheReadTokens` is recorded and the difference is not negative, and
174
+ * omits it otherwise.
175
+ * `cachedInputTokens` and `outputTokens` are reported whenever the row
176
+ * records them, independent of `inputTokens`.
177
+ * A count that is not a finite number is omitted, never zeroed; a row with no
178
+ * count gives `undefined`. An app that builds its own operator turns from such
179
+ * rows calls this rather than mapping them itself.
180
+ */
181
+ export declare function operatorTurnUsage(row: Pick<ChatOperatorMessage, 'inputTokens' | 'cacheReadTokens' | 'outputTokens'>, options?: {
182
+ inputIncludesCache?: boolean | 'unknown';
183
+ }): OperatorTurn['usage'];
147
184
  /**
148
185
  * The operator adapter for an app built on agent-app's chat stack: threads and
149
186
  * messages from its chat store, turns through its own chat route. The app
@@ -107,6 +107,24 @@ export interface OperatorTurn {
107
107
  executionId?: string;
108
108
  model?: string;
109
109
  costUsd?: number;
110
+ /**
111
+ * Token usage the app stored on the turn's reply; `operatorTurnUsage` maps
112
+ * a chat-store row to it.
113
+ * - `inputTokens`: prompt tokens NOT read from the provider's cache. Unlike
114
+ * the turn trace's summary, it never includes cache reads; it is omitted
115
+ * when the row's split is ambiguous, including when the row records no
116
+ * cache count (see `operatorTurnUsage`).
117
+ * - `cachedInputTokens`: prompt tokens read from the provider's cache (the
118
+ * row's `cacheReadTokens`); with both present the whole prompt is
119
+ * `inputTokens + cachedInputTokens`. When absent the cache share is unknown.
120
+ * - `outputTokens`: completion tokens.
121
+ * Each field is present only when known; never a guessed zero.
122
+ */
123
+ usage?: {
124
+ inputTokens?: number;
125
+ cachedInputTokens?: number;
126
+ outputTokens?: number;
127
+ };
110
128
  completedAt?: string;
111
129
  /** The settled answer; null until the turn settles. */
112
130
  reply: {
@@ -596,6 +596,20 @@ function turnIdOf(message) {
596
596
  }
597
597
  return null;
598
598
  }
599
+ function operatorTurnUsage(row, options = {}) {
600
+ const count = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
601
+ const input = count(row.inputTokens);
602
+ const cached = count(row.cacheReadTokens);
603
+ const output = count(row.outputTokens);
604
+ const includes = options.inputIncludesCache ?? "unknown";
605
+ const uncached = input === void 0 ? void 0 : includes === false ? input : includes === true ? cached !== void 0 && input - cached >= 0 ? input - cached : void 0 : cached === 0 ? input : void 0;
606
+ const usage = {
607
+ ...uncached !== void 0 ? { inputTokens: uncached } : {},
608
+ ...cached !== void 0 ? { cachedInputTokens: cached } : {},
609
+ ...output !== void 0 ? { outputTokens: output } : {}
610
+ };
611
+ return Object.keys(usage).length > 0 ? usage : void 0;
612
+ }
599
613
  async function drain(response, signal) {
600
614
  if (!response.body) return;
601
615
  const reader = response.body.getReader();
@@ -663,6 +677,8 @@ function createChatOperatorAdapter(options) {
663
677
  const model = assistant.servedModel ?? assistant.model;
664
678
  if (model) turn.model = model;
665
679
  if (typeof assistant.costUsd === "number") turn.costUsd = assistant.costUsd;
680
+ const usage = operatorTurnUsage(assistant, { inputIncludesCache: options.inputIncludesCache ?? "unknown" });
681
+ if (usage) turn.usage = usage;
666
682
  if (state !== "working" && terminal) {
667
683
  const failure2 = (options.failureOf ?? defaultFailure)(assistant) ?? (status === "error" ? { code: "turn.error", message: "The turn failed; retained text may be partial" } : null);
668
684
  if (failure2) {
@@ -915,6 +931,7 @@ export {
915
931
  createOperatorClient,
916
932
  matchOperatorRoute,
917
933
  operatorKeyWorkspaces,
934
+ operatorTurnUsage,
918
935
  operatorWorkspaceScope,
919
936
  withPlatformAgentKeys
920
937
  };