@matatbread/matbot-core 0.2.2 → 0.2.4

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.2",
+  "version": "0.2.4",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.2.2"
+    "@matatbread/matbot-plugin-api": "^0.2.4"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/index.ts

@@ -25,8 +25,11 @@ export {
   installPrincipalCarrier, currentPrincipal, tryCurrentPrincipal,
   runAs, enterPrincipal, createConstantPrincipalCarrier,
   contextSwitch, onContextQuiesce, flushIfQuiescent,
+  installUsageCarrier, createSerialUsageCarrier, recordUsage, currentUsageSink, withUsageScope,
+  lastActivityAt,
 } from '@matatbread/matbot-plugin-api';
 export * from './session.js';
+export * from './usage.js';
 export * from './hooks.js';
 export * from './runner.js';
 export * from './session-runner.js';

package/src/runner.ts

@@ -1,11 +1,13 @@
 import type {
-  Session, MessageContent,
+  Session, MessageContent, Usage,
   PipelineEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
+import { currentUsageSink } from '@matatbread/matbot-plugin-api';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
+import { addUsage } from './usage.js';
 
 export interface RunSessionOpts {
   session:        Session;
@@ -130,6 +132,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
     const pendingCalls: Array<{ id: string; name: string; input: unknown }> = [];
     const assistantParts: MessageContent[] = [];
     let textAcc = '';
+    let turnUsage: Usage | undefined;
 
     // One provider call. The outgoing array (system context + history, with screen's ephemeral
     // blocks appended onto the tail message) is assembled here and handed to `contribute` hooks for
@@ -172,6 +175,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             pendingCalls.push({ id: ev.id, name: ev.name, input: ev.input });
             break;
           case 'usage':
+            turnUsage = addUsage(turnUsage, ev);
             yield { type: 'usage', inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, traceId,
               ...(ev.costUsd              !== undefined ? { costUsd:              ev.costUsd              } : {}),
               ...(ev.cacheReadTokens     !== undefined ? { cacheReadTokens:     ev.cacheReadTokens     } : {}),
@@ -188,6 +192,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         if (assistantParts.length > 0) {
           session = appendMessage(session, createMessage({
             role: 'assistant', content: assistantParts, traceId, providerName: config.provider,
+            ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
           }));
         }
         await store.set(session.id, session);
@@ -210,6 +215,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         content:      assistantParts,
         traceId,
         providerName: config.provider,
+        ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
       });
       session = appendMessage(session, assistantMsg);
     } else {
@@ -257,6 +263,10 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
 
       let result: unknown;
       let isError = false;
+      // Token accounting for completions this tool runs (via singleTurn/complete) accrues into the
+      // ambient turn sink; slice off whatever it appends during *this* call to attribute it here.
+      const usageSink = currentUsageSink();
+      const usageMark = usageSink?.length ?? 0;
       const startedAt = Date.now();
 
       const toolCtx: ToolContext = {
@@ -299,7 +309,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         tool, result, isError, durationMs: Date.now() - startedAt,
       });
 
-      toolResults.push({ type: 'tool-result', id: tc.id, result, isError });
+      const callUsage = usageSink ? usageSink.slice(usageMark) : [];
+      toolResults.push({ type: 'tool-result', id: tc.id, result, isError,
+        ...(callUsage.length > 0 ? { usage: callUsage } : {}) });
       yield { type: 'tool:end', callId: tc.id, result, isError, traceId };
     }
 

package/src/session-runner.ts

@@ -6,7 +6,7 @@ import type {
 import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
-import { contextSwitch } from '@matatbread/matbot-plugin-api';
+import { contextSwitch, withUsageScope } from '@matatbread/matbot-plugin-api';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -219,7 +219,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // the callback: an async iterator returned out of the scope would lose it before it pulls.
           // contextSwitch (not bare runAs): a turn is the transactional unit, so a StorageBackend swap
           // deferred during it lands at this scope's quiescent edge — never mid-CAS.
-          await contextSwitch(head.principal, async () => {
+          await contextSwitch(head.principal, () => withUsageScope(async () => {
             for await (const ev of runSession({
               session,
               config:         { provider: head.provider, traceId: head.traceId },
@@ -242,7 +242,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
             })) {
               emit(s, ev);
             }
-          });
+          }));
 
           // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
           // head-enqueue a robo follow-up (its own real turn, running next). Skipped on abort; runs

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { Session, Message, MessageContent, MessageRole, Principal } from './types.js';
+import type { Session, Message, MessageContent, MessageRole, Principal, Usage } from './types.js';
 
 export interface CreateSessionOpts {
   ownerPrincipal:        Principal;
@@ -32,10 +32,12 @@ export function createSession(opts: CreateSessionOpts): Session {
 }
 
 export function appendMessage(session: Session, message: Message): Session {
+  // updatedAt tracks conversational activity: the new last message's timestamp (the lastActivityAt
+  // invariant), not a fresh `now()` — so it stays consistent with structural edits that preserve the tail.
   return {
     ...session,
     messages:  [...session.messages, message],
-    updatedAt: new Date().toISOString(),
+    updatedAt: message.createdAt,
     version:   crypto.randomUUID(),
   };
 }
@@ -45,6 +47,7 @@ export function createMessage(opts: {
   content:        MessageContent[];
   traceId:        string;
   providerName?:  string;
+  usage?:         Usage;
   metadata?:      Record<string, unknown>;
 }): Message {
   return {
@@ -54,6 +57,7 @@ export function createMessage(opts: {
     createdAt: new Date().toISOString(),
     traceId:   opts.traceId,
     ...(opts.providerName !== undefined ? { providerName: opts.providerName } : {}),
+    ...(opts.usage        !== undefined ? { usage:        opts.usage        } : {}),
     ...(opts.metadata     !== undefined ? { metadata:     opts.metadata     } : {}),
   };
 }

package/src/single-turn.ts

@@ -33,7 +33,9 @@ export function createSingleTurnTool(services: MatbotMachine): Tool {
         signal: ctx.signal,
         ...(typeof args.system === 'string' ? { system: args.system } : {}),
       });
-      yield { type: 'result', value: { text: res.text, usage: res.usage } };
+      // Usage is accounting, not conversation: it is captured ambiently (the host's complete() reports
+      // it into the turn's usage sink, attributed to this tool call) — the model gets only the text.
+      yield { type: 'result', value: { text: res.text } };
     },
   };
 
@@ -42,13 +44,13 @@ export function createSingleTurnTool(services: MatbotMachine): Tool {
     description:
       'Run a single-turn completion against a configured provider and return its reply. This is a ' +
       'one-shot call — not your own response: you send one `prompt` (and optional `system`), and get ' +
-      'back its text and token usage. Use it to consult a different model — e.g. a second, ' +
+      'back its text. Use it to consult a different model — e.g. a second, ' +
       'different-lineage model critiquing your draft, or any generation that should run on a specific ' +
       'provider. `provider` is OPTIONAL: omit it to run on the current conversation\'s model, or name ' +
       'a configured provider to switch models (list or add providers with the provider tool).\n\n' +
       'Parameters (TypeScript):\n' +
       '```ts\n' +
-      '{ provider?: string; prompt: string; system?: string }  // -> { text, usage: { inputTokens, outputTokens } }\n' +
+      '{ provider?: string; prompt: string; system?: string }  // -> { text }\n' +
       '```',
     inputSchema: {
       type:       'object',

package/src/usage.ts

@@ -0,0 +1,36 @@
+import type { Message, Usage } from './types.js';
+
+/** Fold one usage tally into a running total; optional fields are summed only when either side has them. */
+export function addUsage(acc: Usage | undefined, next: Usage): Usage {
+  const a = acc ?? { inputTokens: 0, outputTokens: 0 };
+  const add = (x: number | undefined, y: number | undefined): number | undefined =>
+    x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
+  return {
+    inputTokens:  a.inputTokens  + next.inputTokens,
+    outputTokens: a.outputTokens + next.outputTokens,
+    ...(((c) => c !== undefined ? { costUsd:             c } : {}))(add(a.costUsd,             next.costUsd)),
+    ...(((c) => c !== undefined ? { cacheReadTokens:     c } : {}))(add(a.cacheReadTokens,     next.cacheReadTokens)),
+    ...(((c) => c !== undefined ? { cacheCreationTokens: c } : {}))(add(a.cacheCreationTokens, next.cacheCreationTokens)),
+  };
+}
+
+/**
+ * Aggregate the token accounting recorded on a set of messages, keyed by the provider billed: an
+ * assistant turn's own `Message.usage` (billed to its `providerName`) plus every `tool-result` block's
+ * `usage` records (each provider-tagged — a tool may run completions against several). Pass a single
+ * turn's messages (filtered by `traceId`) for a per-turn breakdown, or a whole session for its total.
+ */
+export function usageByProvider(messages: Iterable<Message>): Map<string, Usage> {
+  const out = new Map<string, Usage>();
+  for (const m of messages) {
+    if (m.usage !== undefined && m.providerName !== undefined) {
+      out.set(m.providerName, addUsage(out.get(m.providerName), m.usage));
+    }
+    for (const c of m.content) {
+      if (c.type === 'tool-result' && c.usage !== undefined) {
+        for (const r of c.usage) out.set(r.provider, addUsage(out.get(r.provider), r.usage));
+      }
+    }
+  }
+  return out;
+}