chainlesschain 0.162.157 → 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);
         }

package/src/lib/web-ui-server.js

@@ -19,6 +19,7 @@
 import http from "http";
 import fs from "fs";
 import path from "path";
+import crypto from "crypto";
 import { fileURLToPath } from "url";
 import { getInlineSource as getEnvelopeInlineSource } from "./web-ui-envelope.js";
 import { CLISkillLoader } from "./skill-loader.js";
@@ -1224,28 +1225,140 @@ function findWebPanelDist(staticDir) {
   return null;
 }
 
+/** Constant-time token check (same construction as ws-server's): hash both
+ *  sides to a fixed length so length differences don't leak, then compare in
+ *  constant time. `null`/absent configured token → no auth required. */
+function downloadTokenOk(configuredToken, req) {
+  if (!configuredToken) return true;
+  let supplied = "";
+  const auth = String(req.headers?.authorization || "");
+  if (auth.toLowerCase().startsWith("bearer ")) {
+    supplied = auth.slice(7).trim();
+  } else {
+    try {
+      supplied =
+        new URL(req.url, "http://localhost").searchParams.get("token") || "";
+    } catch {
+      supplied = "";
+    }
+  }
+  const a = crypto.createHash("sha256").update(String(supplied)).digest();
+  const b = crypto
+    .createHash("sha256")
+    .update(String(configuredToken))
+    .digest();
+  return crypto.timingSafeEqual(a, b);
+}
+
+/** RFC 5987 filename* value for a Content-Disposition header. */
+function encodeDispositionFilename(name) {
+  const base = String(name || "artifact").replace(/[\r\n"]/g, "_");
+  return `attachment; filename*=UTF-8''${encodeURIComponent(base)}`;
+}
+
 /**
  * Handle `/api/*` routes. Returns `true` if the request was handled (caller
  * must stop further processing) and `false` for everything else (caller
  * continues with the static/SPA handler).
  *
- * Currently exposes a single read-only endpoint:
+ * Endpoints:
  *
  *   GET /api/skills → 200 { schema: 1, skills: [{name, source, category,
  *                    description, version}] }
+ *   GET /api/artifacts/<id>/download → the artifact's stored copy as an
+ *                    attachment (full file — the WS artifact-content preview
+ *                    route is capped; this is the uncapped download path the
+ *                    web-panel's 下载 button uses). When the server was
+ *                    created with a wsToken, the same token must accompany
+ *                    the request (`Authorization: Bearer` or `?token=`).
  *
- * The smoke-runner's project-mode probe (packer/smoke-runner.js) hits this
- * to verify bundled skills were materialized and registered. The shape is
- * deliberately minimal — the Web UI's richer skill views use WS.
+ * The smoke-runner's project-mode probe (packer/smoke-runner.js) hits
+ * /api/skills to verify bundled skills were materialized and registered. The
+ * shapes are deliberately minimal — the Web UI's richer views use WS.
  *
  * @param {import("http").IncomingMessage} req
  * @param {import("http").ServerResponse}  res
+ * @param {{ wsToken?: string|null }} [ctx]  server context (auth for downloads)
  * @returns {boolean}  true if handled, false if the caller should continue
  */
-export function handleApiRequest(req, res) {
+export function handleApiRequest(req, res, ctx = {}) {
   const urlPath = req.url.split("?")[0];
   if (!urlPath.startsWith("/api/")) return false;
 
+  const artifactMatch = urlPath.match(
+    /^\/api\/artifacts\/([A-Za-z0-9_]+)\/download$/,
+  );
+  if (artifactMatch) {
+    if (req.method !== "GET") {
+      res.writeHead(405, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Method Not Allowed" }));
+      return true;
+    }
+    // The panel authenticates its WS with this token; the download endpoint
+    // serves artifact FILE CONTENT, so it must not be weaker than the WS.
+    if (!downloadTokenOk(ctx.wsToken || null, req)) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return true;
+    }
+    // Async body in a sync router: the route is claimed (return true) and the
+    // response completes when the store import resolves.
+    (async () => {
+      try {
+        const { ArtifactStore } = await import("./artifact-store.js");
+        const store = new ArtifactStore();
+        const entry = store.get(artifactMatch[1]);
+        if (!entry) {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Not Found" }));
+          return;
+        }
+        // Same tamper guard as the WS content route: the stored filename must
+        // be a plain basename or the index row is refused.
+        if (
+          !entry.file ||
+          entry.file !== path.basename(entry.file) ||
+          entry.file.includes("..")
+        ) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Bad artifact index row" }));
+          return;
+        }
+        const storedPath = store.storedPath(entry);
+        let size;
+        try {
+          size = fs.statSync(storedPath).size;
+        } catch {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Stored copy missing" }));
+          return;
+        }
+        const downloadName =
+          entry.title && path.extname(entry.title)
+            ? entry.title
+            : path.basename(entry.sourcePath || entry.file);
+        res.writeHead(200, {
+          "Content-Type": entry.mime || "application/octet-stream",
+          "Content-Length": size,
+          "Content-Disposition": encodeDispositionFilename(downloadName),
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+        });
+        const stream = fs.createReadStream(storedPath);
+        stream.on("error", () => res.destroy());
+        stream.pipe(res);
+      } catch (err) {
+        try {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: err.message }));
+        } catch {
+          /* headers already sent — connection is torn down by the stream */
+        }
+      }
+    })();
+    return true;
+  }
+
   if (urlPath === "/api/skills") {
     if (req.method !== "GET") {
       res.writeHead(405, { "Content-Type": "application/json" });
@@ -1328,7 +1441,7 @@ export function createWebUIServer(opts) {
     return http.createServer((req, res) => {
       // /api/* routes are handled before the static file logic so GET /api/skills
       // doesn't accidentally resolve to index.html via the SPA fallback.
-      if (handleApiRequest(req, res)) return;
+      if (handleApiRequest(req, res, { wsToken: opts.wsToken || null })) return;
 
       if (req.method !== "GET") {
         res.writeHead(405, { "Content-Type": "text/plain" });
@@ -1415,7 +1528,7 @@ export function createWebUIServer(opts) {
   // ── Fallback: embedded classic single-page HTML ─────────────────────────
   const html = buildHtml(opts);
   return http.createServer((req, res) => {
-    if (handleApiRequest(req, res)) return;
+    if (handleApiRequest(req, res, { wsToken: opts.wsToken || null })) return;
 
     const urlPath = req.url.split("?")[0];
     if (