feat: per-activity and per-workflow token use tracking and cost estimation (#232)

schemas/session-file.schema.json

@@ -133,6 +133,107 @@
           },
           "default": {}
         },
+        "usage": {
+          "type": "object",
+          "properties": {
+            "perActivity": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "input_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "output_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "total_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "cache_read_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "cache_write_5m_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "cache_write_1h_tokens": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "model": {
+                    "type": "string"
+                  },
+                  "cost_usd": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": 0
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "priceTableVersion": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "input_tokens",
+                  "output_tokens",
+                  "total_tokens",
+                  "cost_usd"
+                ],
+                "additionalProperties": false
+              },
+              "default": {}
+            },
+            "workflowTotal": {
+              "type": "object",
+              "properties": {
+                "input_tokens": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "output_tokens": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "total_tokens": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cost_usd": {
+                  "anyOf": [
+                    {
+                      "type": "number",
+                      "minimum": 0
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "input_tokens",
+                "output_tokens",
+                "total_tokens",
+                "cost_usd"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "workflowTotal"
+          ],
+          "additionalProperties": false
+        },
         "history": {
           "type": "array",
           "items": {
@@ -170,7 +271,8 @@
                   "technique_fetched",
                   "resource_fetched",
                   "technique_bundled",
-                  "variables_seeded"
+                  "variables_seeded",
+                  "usage_recorded"
                 ]
               },
               "activity": {

schemas/state.schema.json

@@ -204,7 +204,8 @@
                   "technique_fetched",
                   "resource_fetched",
                   "technique_bundled",
-                  "variables_seeded"
+                  "variables_seeded",
+                  "usage_recorded"
                 ]
               },
               "activity": {

src/config.ts

@@ -31,8 +31,18 @@ export interface ServerConfig {
   traceStore?: TraceStore;
   /** Minimum seconds between checkpoint issuance and response. Default 3. Set to 0 for testing. */
   minCheckpointResponseSeconds?: number;
+  /**
+   * Per-model USD-per-MTok rates ({ input, output }) for cost estimation.
+   * Cache rates are derived from base input via universal multipliers.
+   */
+  priceTable?: PriceTable;
+  /** Version string stamped on each cost estimate; env-overridable via PRICE_TABLE_VERSION. */
+  priceTableVersion?: string;
 }
 
+/** USD-per-MTok base input/output rates keyed by model id. */
+export type PriceTable = Record<string, { input: number; output: number }>;
+
 /** Config shape after startup — traceStore is guaranteed present. */
 export interface ResolvedServerConfig extends ServerConfig {
   traceStore: TraceStore;
@@ -49,6 +59,19 @@ const PROJECT_ROOT = resolve(import.meta.dirname, '..');
 export const DEFAULT_BUNDLE_HEADROOM_FRACTION = 0.8;
 export const DEFAULT_BUNDLE_CHARS_PER_TOKEN = 4;
 
+/**
+ * Build-time price table seeded from Anthropic pricing (2026-07-15).
+ * Re-confirm figures at build time when pricing changes.
+ */
+export const DEFAULT_PRICE_TABLE: PriceTable = {
+  'claude-opus-4-8': { input: 5, output: 25 },
+  'claude-sonnet-5': { input: 2, output: 10 },
+  'claude-haiku-4-5': { input: 1, output: 5 },
+  'claude-fable-5': { input: 10, output: 50 },
+};
+
+export const DEFAULT_PRICE_TABLE_VERSION = '2026-07-15';
+
 function envOrDefault(key: string, fallback: string): string {
   const value = process.env[key]?.trim();
   return value || fallback;
@@ -131,5 +154,7 @@ export function loadConfig(argv: readonly string[] = process.argv.slice(2)): Ser
     serverVersion: envOrDefault('SERVER_VERSION', '2.1.0'),
     bundleHeadroomFraction: envNumberOrDefault('BUNDLE_HEADROOM_FRACTION', DEFAULT_BUNDLE_HEADROOM_FRACTION),
     bundleCharsPerToken: envNumberOrDefault('BUNDLE_CHARS_PER_TOKEN', DEFAULT_BUNDLE_CHARS_PER_TOKEN),
+    priceTable: DEFAULT_PRICE_TABLE,
+    priceTableVersion: envOrDefault('PRICE_TABLE_VERSION', DEFAULT_PRICE_TABLE_VERSION),
   };
 }

src/schema/session.schema.ts

@@ -48,6 +48,36 @@ export const ActiveCheckpointSchema = z.object({
 });
 export type ActiveCheckpoint = z.infer<typeof ActiveCheckpointSchema>;
 
+/** Per-activity token usage entry with cost frozen at capture time. */
+export const ActivityUsageEntrySchema = z.object({
+  input_tokens: z.number().int().nonnegative(),
+  output_tokens: z.number().int().nonnegative(),
+  total_tokens: z.number().int().nonnegative(),
+  cache_read_tokens: z.number().int().nonnegative().optional(),
+  cache_write_5m_tokens: z.number().int().nonnegative().optional(),
+  cache_write_1h_tokens: z.number().int().nonnegative().optional(),
+  model: z.string().optional(),
+  cost_usd: z.number().nonnegative().nullable(),
+  priceTableVersion: z.string().optional(),
+});
+export type ActivityUsageEntry = z.infer<typeof ActivityUsageEntrySchema>;
+
+/** Rolled-up per-workflow token totals (child-inclusive at completion). */
+export const WorkflowUsageTotalSchema = z.object({
+  input_tokens: z.number().int().nonnegative(),
+  output_tokens: z.number().int().nonnegative(),
+  total_tokens: z.number().int().nonnegative(),
+  cost_usd: z.number().nonnegative().nullable(),
+});
+export type WorkflowUsageTotal = z.infer<typeof WorkflowUsageTotalSchema>;
+
+/** Durable usage roll-up persisted on SessionFile. */
+export const SessionUsageSchema = z.object({
+  perActivity: z.record(ActivityUsageEntrySchema).default({}),
+  workflowTotal: WorkflowUsageTotalSchema,
+});
+export type SessionUsage = z.infer<typeof SessionUsageSchema>;
+
 /**
  * Base (non-recursive) shape of `SessionFile`. Used as the building block for
  * the recursive `SessionFileSchema` below; the only structural extension is
@@ -101,6 +131,12 @@ const SessionFileBaseSchema = z.object({
    */
   checkpointResponses: z.record(CheckpointResponseSchema).default({}),
 
+  /**
+   * Rolled-up token usage and cost estimate. Absent until the first
+   * `usage_recorded` event; child-inclusive at workflow completion.
+   */
+  usage: SessionUsageSchema.optional(),
+
   /** Append-only event log for the session. */
   history: z.array(HistoryEntrySchema).default([]),
 
@@ -177,6 +213,7 @@ export interface SessionFile {
   completedActivities: string[];
   skippedActivities: string[];
   checkpointResponses: Record<string, CheckpointResponse>;
+  usage?: SessionUsage;
   history: HistoryEntry[];
   status: 'running' | 'completed' | 'aborted';
   triggeredWorkflows: EmbeddedSessionRef[];

src/schema/state.schema.ts

@@ -27,6 +27,10 @@ export const HistoryEventTypeSchema = z.enum([
   // session variable bag at session creation. ONE event per session; `data`
   // carries { variables: <the seeded map> }.
   'variables_seeded',
+  // Token-use tracking (#232): per-activity native usage relayed by the
+  // orchestrator at the next_activity transition seam. `data` carries the
+  // token figures, model, cost_usd (nullable), and priceTableVersion.
+  'usage_recorded',
 ]);
 export type HistoryEventType = z.infer<typeof HistoryEventTypeSchema>;
 

src/tools/workflow-tools.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ServerConfig } from '../config.js';
-import { DEFAULT_BUNDLE_HEADROOM_FRACTION, DEFAULT_BUNDLE_CHARS_PER_TOKEN } from '../config.js';
+import { DEFAULT_BUNDLE_HEADROOM_FRACTION, DEFAULT_BUNDLE_CHARS_PER_TOKEN, DEFAULT_PRICE_TABLE, DEFAULT_PRICE_TABLE_VERSION } from '../config.js';
 import { listWorkflows, listWorkflowsWithDiagnostics, loadWorkflow, loadWorkflowWithDiagnostics, getActivity, getCheckpoint, readActivityRaw, buildFragmentsLookup, TERMINAL_SENTINEL } from '../loaders/workflow-loader.js';
 import { injectCheckpointFragmentBodies, resolveCheckpointFragment, scanCheckpointRefLines } from '../loaders/fragment-resolver.js';
 import { resolveTechniques, formatTechniqueBundle, composeActivityTechnique, projectTechnique, projectTechniqueToYaml } from '../loaders/technique-loader.js';
@@ -28,6 +28,7 @@ import {
 import type { SessionFile } from '../schema/session.schema.js';
 import { buildValidation, validateWorkflowVersion, validateActivityTransition, validateStepManifest, validateTechniqueFetches, validateTransitionCondition, validateActivityManifest } from '../utils/validation.js';
 import type { StepManifestEntry, ActivityManifestEntry } from '../utils/validation.js';
+import { finalizeUsageTree, recordActivityUsage, type UsageInput } from '../utils/usage.js';
 import { createTraceToken, decodeTraceToken } from '../trace.js';
 import type { TraceEvent, TraceTokenPayload } from '../trace.js';
 
@@ -42,6 +43,16 @@ const activityManifestSchema = z.array(z.object({
   transition_condition: z.string().optional(),
 })).optional().describe('Activity completion manifest from the orchestrator. Reports the sequence of activities completed so far with outcomes and transition conditions.');
 
+const usageParamSchema = z.object({
+  input_tokens: z.number().int().nonnegative(),
+  output_tokens: z.number().int().nonnegative(),
+  total_tokens: z.number().int().nonnegative().optional(),
+  cache_read_tokens: z.number().int().nonnegative().optional(),
+  cache_write_5m_tokens: z.number().int().nonnegative().optional(),
+  cache_write_1h_tokens: z.number().int().nonnegative().optional(),
+  model: z.string().min(1).optional(),
+}).optional().describe('Native model usage for the activity being EXITED, relayed by the orchestrator/harness (the worker cannot self-measure). Omit entirely when no usage is available — the run still completes. Absent sub-figures are omitted, not fabricated.');
+
 /**
  * Wrap a tool handler so any thrown `SessionStoreError` is re-thrown with a
  * user-facing message. Keeps the per-handler logic terse — handlers can
@@ -123,7 +134,7 @@ export async function composeActivityArtifacts(
 
 /** The views `inspect_session` can project. `summary` is the default composite. */
 export const INSPECT_SESSION_VIEWS = [
-  'summary', 'identity', 'variables', 'checkpoints', 'activities', 'history', 'children',
+  'summary', 'identity', 'variables', 'checkpoints', 'activities', 'history', 'children', 'usage',
 ] as const;
 export type InspectSessionView = (typeof INSPECT_SESSION_VIEWS)[number];
 
@@ -215,16 +226,24 @@ export function projectChildren(s: SessionFile): Array<Record<string, unknown>>
   });
 }
 
+/** Usage projection: rolled-up per-activity and per-workflow token figures. */
+export function projectUsage(s: SessionFile): Record<string, unknown> | undefined {
+  return s.usage ? { ...s.usage } : undefined;
+}
+
 /** Summary (default) view: the composite of all projections for the addressed session. */
 export function projectSummary(s: SessionFile): Record<string, unknown> {
-  return {
+  const summary: Record<string, unknown> = {
     identity: projectIdentity(s),
     activities: projectActivities(s),
     variables: s.variables ?? {},
     checkpoints: projectCheckpoints(s),
     history: projectHistory(s),
     children: projectChildren(s),
   };
+  const usage = projectUsage(s);
+  if (usage) summary['usage'] = usage;
+  return summary;
 }
 
 /**
@@ -247,6 +266,7 @@ export function projectSessionView(
     case 'activities': return projectActivities(s);
     case 'history': return projectHistory(s);
     case 'children': return projectChildren(s);
+    case 'usage': return projectUsage(s) ?? {};
     case 'summary':
     default:
       return projectSummary(s);
@@ -377,8 +397,9 @@ export function registerWorkflowTools(server: McpServer, config: ServerConfig):
       transition_condition: z.string().optional().describe('The transition condition that led to this activity (from the transitions field of the previous activity). Enables server-side validation of condition-activity consistency.'),
       step_manifest: stepManifestSchema,
       activity_manifest: activityManifestSchema,
+      usage: usageParamSchema,
     },
-    withAuditLog('next_activity', withSessionStoreErrors(async ({ session_index, activity_id, transition_condition, step_manifest, activity_manifest }) => {
+    withAuditLog('next_activity', withSessionStoreErrors(async ({ session_index, activity_id, transition_condition, step_manifest, activity_manifest, usage }) => {
       const loaded = await loadSessionForTool(config.workspaceDir, session_index);
       const { state } = loaded;
 
@@ -431,11 +452,23 @@ export function registerWorkflowTools(server: McpServer, config: ServerConfig):
         ...activityManifestWarnings,
       );
 
+      const priceTable = config.priceTable ?? DEFAULT_PRICE_TABLE;
+      const priceTableVersion = config.priceTableVersion ?? DEFAULT_PRICE_TABLE_VERSION;
+
       const next = advanceSession(state, (draft) => {
         const now = new Date().toISOString();
         // Exit-prior: any non-empty previous activity is recorded as
         // completed once we transition off it.
         if (draft.currentActivity) {
+          if (usage) {
+            recordActivityUsage(
+              draft,
+              draft.currentActivity,
+              usage as UsageInput,
+              priceTable,
+              priceTableVersion,
+            );
+          }
           draft.history.push({ timestamp: now, type: 'activity_exited', activity: draft.currentActivity });
           if (!draft.completedActivities.includes(draft.currentActivity)) {
             draft.completedActivities.push(draft.currentActivity);
@@ -450,6 +483,7 @@ export function registerWorkflowTools(server: McpServer, config: ServerConfig):
         // across the work-package, prism, and meta workflows; the TERMINAL_SENTINEL
         // is the contentless terminal reached via an explicit terminal transition.
         if (activity_id === 'complete' || isTerminal) {
+          finalizeUsageTree(draft);
           draft.history.push({ timestamp: now, type: 'workflow_completed' });
           draft.status = 'completed';
         }
@@ -1302,6 +1336,9 @@ export function registerWorkflowTools(server: McpServer, config: ServerConfig):
         };
       }
 
+      const usage = projectUsage(state);
+      if (usage) response['usage'] = usage;
+
       // get_workflow_status reads but does not advance — keep the on-disk state stable.
       response['session_index'] = session_index;
 

src/utils/session/store.ts

@@ -101,6 +101,7 @@ const TOP_LEVEL_KEY_PRIORITY = [
   'skippedActivities',
   'variables',
   'checkpointResponses',
+  'usage',
   'history',
   'triggeredWorkflows',
   'parentSession',