chainlesschain 0.162.158 → 0.162.159

package/src/lib/session-usage.js

@@ -31,6 +31,30 @@ function toNumber(v) {
   return Number.isFinite(n) ? n : 0;
 }
 
+/**
+ * Extract the optional usage-attribution frame (用量归因) persisted alongside
+ * a token_usage event's data: `{ origin, skill?, subagentId?, role?,
+ * parentSessionId?, depth? }`. Written by the agent drivers for sub-agent /
+ * isolated-skill usage; absent on legacy events and on plain main-loop usage
+ * (absence ⇒ origin "main"). Returns a normalized copy or null.
+ */
+export function extractAttribution(event) {
+  const a = event?.data?.attribution;
+  if (!a || typeof a !== "object") return null;
+  const origin = typeof a.origin === "string" && a.origin ? a.origin : null;
+  if (!origin) return null;
+  const out = { origin };
+  if (typeof a.skill === "string" && a.skill) out.skill = a.skill;
+  if (typeof a.subagentId === "string" && a.subagentId)
+    out.subagentId = a.subagentId;
+  if (typeof a.role === "string" && a.role) out.role = a.role;
+  if (typeof a.parentSessionId === "string" && a.parentSessionId)
+    out.parentSessionId = a.parentSessionId;
+  const depth = Number(a.depth);
+  if (Number.isFinite(depth)) out.depth = depth;
+  return out;
+}
+
 /**
  * Extract a normalized usage record from a single event, or null if none.
  * Accepts both snake_case (OpenAI/Anthropic) and camelCase variants.
@@ -75,6 +99,9 @@ export function extractUsage(event) {
     return null;
   }
 
+  // Attribution rides along ONLY when present, so records built from legacy
+  // events stay byte-identical (callers using exact-equality keep passing).
+  const attribution = extractAttribution(event);
   return {
     provider: d.provider || raw.provider || null,
     model: d.model || raw.model || null,
@@ -84,6 +111,223 @@ export function extractUsage(event) {
     cacheReadTokens,
     cacheCreationTokens,
     timestamp: event.timestamp || null,
+    ...(attribution ? { attribution } : {}),
+  };
+}
+
+// ── Usage attribution roll-ups (用量归因) ───────────────────────────────────
+
+function _newSums() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    calls: 0,
+  };
+}
+
+function _addSums(sums, u) {
+  sums.inputTokens += u.inputTokens || 0;
+  sums.outputTokens += u.outputTokens || 0;
+  sums.totalTokens += u.totalTokens || 0;
+  sums.cacheReadTokens += u.cacheReadTokens || 0;
+  sums.cacheCreationTokens += u.cacheCreationTokens || 0;
+  sums.calls += u.calls != null ? u.calls : 1;
+}
+
+const _byTokensDesc = (a, b) => b.totalTokens - a.totalTokens;
+
+/**
+ * Roll usage events up by attribution: origin (main | subagent | skill —
+ * events without an attribution frame count as "main", which keeps every
+ * pre-attribution transcript aggregating exactly as before), by skill name,
+ * and by individual sub-agent.
+ */
+export function aggregateUsageAttribution(events) {
+  const byOrigin = new Map();
+  const bySkill = new Map();
+  const bySubagent = new Map();
+
+  for (const evt of events || []) {
+    const u = extractUsage(evt);
+    if (!u) continue;
+    const attr = u.attribution || null;
+    const origin = attr?.origin || "main";
+
+    const o = byOrigin.get(origin) || { origin, ..._newSums() };
+    _addSums(o, u);
+    byOrigin.set(origin, o);
+
+    if (origin === "skill") {
+      const key = attr?.skill || "?";
+      const s = bySkill.get(key) || { skill: key, ..._newSums() };
+      _addSums(s, u);
+      bySkill.set(key, s);
+    }
+
+    if (attr?.subagentId) {
+      const key = attr.subagentId;
+      const r = bySubagent.get(key) || {
+        subagentId: key,
+        role: attr.role || null,
+        origin,
+        ..._newSums(),
+      };
+      _addSums(r, u);
+      bySubagent.set(key, r);
+    }
+  }
+
+  return {
+    byOrigin: Array.from(byOrigin.values()).sort(_byTokensDesc),
+    bySkill: Array.from(bySkill.values()).sort(_byTokensDesc),
+    bySubagent: Array.from(bySubagent.values()).sort(_byTokensDesc),
+  };
+}
+
+/**
+ * MCP tools reach the loop as `mcp__<server>__<tool>`; returns the server
+ * segment or null for a non-MCP tool name.
+ */
+export function mcpServerOf(toolName) {
+  if (typeof toolName !== "string" || !toolName.startsWith("mcp__"))
+    return null;
+  const rest = toolName.slice(5);
+  const sep = rest.indexOf("__");
+  return sep > 0 ? rest.slice(0, sep) : null;
+}
+
+/** Lenient tool_result error detection (mirrors session-insights). */
+function _isToolResultError(event) {
+  const r = event?.data?.result;
+  return Boolean(
+    event?.data?.error ||
+    (r && typeof r === "object" && (r.error || r.is_error || r.isError)),
+  );
+}
+
+/**
+ * Aggregate the transcript's tool events: per-tool call/error counts, an MCP
+ * server bucket (`mcp__<server>__*`), and a turn-associated token figure.
+ *
+ * `turnTokens` is an APPROXIMATION: turns are delimited by `user_message`
+ * events, and every token_usage event inside a turn is attributed to EVERY
+ * tool that ran in that turn ("tokens of turns that used tool X"). A turn's
+ * tokens therefore count once per distinct tool — do NOT sum turnTokens
+ * across tools/servers, it is not a partition. Headless sessions persist one
+ * aggregated usage event per run, so there the whole run's tokens associate
+ * with each tool the run used.
+ *
+ * Accepts both the compact `tool_call` shape ({tool, is_error, skill?}) the
+ * drivers write now and the legacy `tool_call`({tool, args}) + `tool_result`
+ * pair (errors read off the result, calls only off tool_call — no double
+ * count). Sessions without tool events aggregate to zeros.
+ */
+export function aggregateToolCalls(events) {
+  const byTool = new Map();
+  const byServer = new Map();
+  let totalCalls = 0;
+  let totalErrors = 0;
+
+  const bumpTool = (name) => {
+    let t = byTool.get(name);
+    if (!t) {
+      t = {
+        tool: name,
+        mcpServer: mcpServerOf(name),
+        calls: 0,
+        errors: 0,
+        turnTokens: 0,
+      };
+      byTool.set(name, t);
+    }
+    return t;
+  };
+  const bumpServer = (server) => {
+    let s = byServer.get(server);
+    if (!s) {
+      s = { server, calls: 0, errors: 0, turnTokens: 0 };
+      byServer.set(server, s);
+    }
+    return s;
+  };
+
+  let turnTools = new Set();
+  let turnServers = new Set();
+  let turnTokens = 0;
+  const flushTurn = () => {
+    if (turnTokens > 0) {
+      for (const name of turnTools) bumpTool(name).turnTokens += turnTokens;
+      for (const server of turnServers)
+        bumpServer(server).turnTokens += turnTokens;
+    }
+    turnTools = new Set();
+    turnServers = new Set();
+    turnTokens = 0;
+  };
+
+  for (const evt of events || []) {
+    if (!evt || typeof evt !== "object") continue;
+    if (evt.type === "user_message") {
+      flushTurn();
+      continue;
+    }
+    if (evt.type === "tool_call") {
+      const name = evt.data?.tool || "?";
+      totalCalls++;
+      const t = bumpTool(name);
+      t.calls++;
+      const isErr = evt.data?.is_error === true;
+      if (isErr) {
+        totalErrors++;
+        t.errors++;
+      }
+      turnTools.add(name);
+      const server = mcpServerOf(name);
+      if (server) {
+        const s = bumpServer(server);
+        s.calls++;
+        if (isErr) s.errors++;
+        turnServers.add(server);
+      }
+      continue;
+    }
+    if (evt.type === "tool_result") {
+      const name = evt.data?.tool || "?";
+      turnTools.add(name);
+      const server = mcpServerOf(name);
+      if (server) turnServers.add(server);
+      if (_isToolResultError(evt)) {
+        totalErrors++;
+        bumpTool(name).errors++;
+        if (server) bumpServer(server).errors++;
+      }
+      continue;
+    }
+    const u = extractUsage(evt);
+    if (u) turnTokens += u.totalTokens;
+  }
+  flushTurn();
+
+  const byCallsDesc = (a, b) => b.calls - a.calls;
+  return {
+    totalCalls,
+    totalErrors,
+    byTool: Array.from(byTool.values()).sort(byCallsDesc),
+    byMcpServer: Array.from(byServer.values()).sort(byCallsDesc),
+  };
+}
+
+/**
+ * Full attribution section for a transcript: origin/skill/subagent usage
+ * roll-ups + the tool/MCP call aggregation. Pure.
+ */
+export function sessionAttribution(events) {
+  return {
+    ...aggregateUsageAttribution(events),
+    tools: aggregateToolCalls(events),
   };
 }
 
@@ -141,12 +385,13 @@ export function aggregateUsage(events) {
 }
 
 /**
- * Roll up usage for a single JSONL session.
+ * Roll up usage for a single JSONL session. The pre-attribution keys
+ * (total/byModel) are unchanged; `attribution` is additive.
  */
 export function sessionUsage(sessionId) {
   const events = _deps.readEvents(sessionId);
   const agg = aggregateUsage(events);
-  return { sessionId, ...agg };
+  return { sessionId, ...agg, attribution: sessionAttribution(events) };
 }
 
 /**
@@ -206,6 +451,66 @@ export function allSessionsUsage({ limit = 1000 } = {}) {
     }
   }
 
+  // Global attribution roll-up: merge each session's attribution rows by key.
+  const gOrigin = new Map();
+  const gSkill = new Map();
+  const gSubagent = new Map();
+  const gTool = new Map();
+  const gServer = new Map();
+  let gToolCalls = 0;
+  let gToolErrors = 0;
+  const mergeRow = (map, key, row, seed) => {
+    const entry = map.get(key) || { ...seed, ..._newSums() };
+    _addSums(entry, row);
+    map.set(key, entry);
+  };
+  for (const s of perSession) {
+    const a = s.attribution;
+    if (!a) continue;
+    for (const row of a.byOrigin || []) {
+      mergeRow(gOrigin, row.origin, row, { origin: row.origin });
+    }
+    for (const row of a.bySkill || []) {
+      mergeRow(gSkill, row.skill, row, { skill: row.skill });
+    }
+    for (const row of a.bySubagent || []) {
+      mergeRow(gSubagent, row.subagentId, row, {
+        subagentId: row.subagentId,
+        role: row.role || null,
+        origin: row.origin,
+      });
+    }
+    const tools = a.tools || {};
+    gToolCalls += tools.totalCalls || 0;
+    gToolErrors += tools.totalErrors || 0;
+    for (const row of tools.byTool || []) {
+      const entry = gTool.get(row.tool) || {
+        tool: row.tool,
+        mcpServer: row.mcpServer || null,
+        calls: 0,
+        errors: 0,
+        turnTokens: 0,
+      };
+      entry.calls += row.calls || 0;
+      entry.errors += row.errors || 0;
+      entry.turnTokens += row.turnTokens || 0;
+      gTool.set(row.tool, entry);
+    }
+    for (const row of tools.byMcpServer || []) {
+      const entry = gServer.get(row.server) || {
+        server: row.server,
+        calls: 0,
+        errors: 0,
+        turnTokens: 0,
+      };
+      entry.calls += row.calls || 0;
+      entry.errors += row.errors || 0;
+      entry.turnTokens += row.turnTokens || 0;
+      gServer.set(row.server, entry);
+    }
+  }
+  const byCallsDesc = (a, b) => b.calls - a.calls;
+
   return {
     sessions: perSession,
     skipped,
@@ -213,6 +518,17 @@ export function allSessionsUsage({ limit = 1000 } = {}) {
     byModel: Array.from(byKey.values()).sort(
       (a, b) => b.totalTokens - a.totalTokens,
     ),
+    attribution: {
+      byOrigin: Array.from(gOrigin.values()).sort(_byTokensDesc),
+      bySkill: Array.from(gSkill.values()).sort(_byTokensDesc),
+      bySubagent: Array.from(gSubagent.values()).sort(_byTokensDesc),
+      tools: {
+        totalCalls: gToolCalls,
+        totalErrors: gToolErrors,
+        byTool: Array.from(gTool.values()).sort(byCallsDesc),
+        byMcpServer: Array.from(gServer.values()).sort(byCallsDesc),
+      },
+    },
   };
 }
 

package/src/lib/sub-agent-context.js

@@ -115,6 +115,14 @@ export class SubAgentContext {
     // Optional progress callback for streaming events to consumers
     this._onProgress = options.onProgress || null;
 
+    // Usage-attribution seam (用量归因): forwards the child loop's REAL
+    // provider-reported token usage to the spawner (the ~4-chars/token
+    // estimate kept in _tokenCount below is only a budget heuristic and never
+    // leaves this context). Wired by spawn_sub_agent / isolated run_skill so
+    // the parent loop can re-yield attributed `token-usage` events.
+    this._onUsage =
+      typeof options.onUsage === "function" ? options.onUsage : null;
+
     // Optional abort signal for cancellation
     this._signal = options.signal || null;
 
@@ -295,6 +303,21 @@ export class SubAgentContext {
       for await (const event of gen) {
         this._iterationCount++;
 
+        if (event.type === "token-usage" && this._onUsage) {
+          // Forward real usage to the spawner. A nested child's event already
+          // carries its own attribution frame — preserve it (deepest wins).
+          try {
+            this._onUsage({
+              provider: event.provider || null,
+              model: event.model || null,
+              usage: event.usage || null,
+              attribution: event.attribution || null,
+            });
+          } catch (_e) {
+            // Usage forwarding is best-effort — never break the child loop
+          }
+        }
+
         if (event.type === "tool-executing") {
           this._toolsUsed.push(event.tool);
         }