taskchef 7.22.2 → 7.22.3

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.22.2",
+  "version": "7.22.3",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -25,11 +25,15 @@ request -> recorded TaskChef task -> Codex executor -> request/result turn timel
 TaskChef requires Node.js 18 or newer, Git, Codex desktop, and local access to
 the projects that will receive work.
 
-Install [`ccusage`](https://github.com/ccusage/ccusage) separately when you want
-the optional dashboard token and API-equivalent cost estimates. TaskChef calls
-its structured offline Codex report and does not parse Codex rollout files
-itself. Lifecycle reporting and the dashboard continue to work when `ccusage`
-is absent or incompatible.
+TaskChef pins [`ccusage`](https://github.com/ccusage/ccusage) as an optional
+dependency for dashboard token and API-equivalent cost estimates. A normal npm
+installation uses that package-local executable; plugin-only installations use
+an npm-cache-friendly `npx` fallback to resolve the same exact version's native
+executable. `npx` never launches the analyzer against Codex data. TaskChef then
+requests ccusage's live-capable online pricing and falls back to its bundled
+offline snapshot, while never parsing Codex rollout files itself. Lifecycle
+reporting and the dashboard continue to work when ccusage, npm, or pricing is
+unavailable.
 
 ```sh
 codex plugin marketplace add favoyang/codex-plugins
@@ -318,8 +322,12 @@ the terminal lifecycle callback precedes Codex's final output write. Historical
 tasks may show a trustworthy task total while older turns remain “Tokens
 unavailable” when no cumulative turn boundaries were recorded. Input, cached
 input, output, reasoning, and total counts retain ccusage's categories. Dollar
-figures are labeled API-equivalent estimates; zero-priced unknown models show
-cost unavailable rather than a misleading `$0.00`.
+figures are labeled API-equivalent estimates; provenance identifies the online
+pricing request or offline fallback mode, and zero-priced unknown models show
+cost unavailable rather than a misleading `$0.00`. Per-turn cost is also
+unavailable when its cumulative boundaries used different ccusage versions or
+pricing modes. ccusage 20.0.20 may omit GPT-5.6 cache-write charges, so TaskChef
+labels that analyzer limitation instead of presenting the estimate as complete.
 The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
 The canonical port is owned by a dashboard initialized in the TaskChef MCP host

package/docs/spec.md

@@ -120,11 +120,17 @@ aliases for existing callers.
 
 ## Optional usage projection
 
-TaskChef MAY invoke an installed `ccusage` executable as an optional local
-adapter using `ccusage codex session --json --offline`. TaskChef MUST NOT parse,
-store, or serve raw Codex rollout files, prompts, responses, transcripts, or
-reasoning. Analyzer absence, timeout, malformed output, unknown pricing, or an
-unresolved thread MUST NOT block lifecycle tools or dashboard loading.
+TaskChef MUST pin one tested `ccusage` version as an optional dependency. It
+MUST prefer that package-local executable and MAY use an exact-version,
+cache-friendly `npx` invocation when a plugin-only installation has no local
+dependency. The `npx` invocation MUST only resolve the pinned native executable
+and MUST NOT launch the analyzer against Codex data. TaskChef MUST execute that
+native binary directly. The adapter MUST first request structured Codex output
+with live-capable online pricing and retry with ccusage's bundled offline
+pricing after a bounded failure. TaskChef MUST NOT parse, store, or serve raw
+Codex rollout files, prompts, responses, transcripts, or reasoning. Analyzer,
+npm, network, timeout, malformed output, unknown pricing, or an unresolved
+thread MUST NOT block lifecycle tools or dashboard loading.
 
 Dashboard-manual turns are administrative events, not Codex executions. They
 MUST immediately report per-turn usage as unavailable, MUST NOT schedule or
@@ -162,9 +168,15 @@ in progress before its terminal report; a first historical terminal turn MUST
 remain unavailable even when its cumulative task total is resolvable.
 
 Every available projection MUST identify ccusage, its version when available,
-and freshness. Dollar values MUST be labeled API-equivalent estimates. Positive
-token usage with a zero or missing analyzer cost MUST display cost unavailable,
-not `$0.00`.
+the requested online or fallback offline pricing mode, and usage freshness.
+The online mode records TaskChef's request, not a claim about ccusage's internal
+cache. Dollar values MUST be labeled API-equivalent estimates. Positive token
+usage with a zero or missing analyzer cost MUST display cost unavailable, not
+`$0.00`. A per-turn dollar delta MUST be unavailable when its adjacent
+cumulative boundaries use different analyzer versions, requested pricing modes,
+or declared cost coverage. For GPT-5.6 with ccusage 20.0.20, provenance MUST
+disclose unverified cache-write coverage and TaskChef MUST NOT claim that the
+estimate includes those charges.
 
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.22.2",
+  "version": "7.22.3",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -64,5 +64,8 @@
     "@modelcontextprotocol/sdk",
     "proper-lockfile",
     "zod"
-  ]
+  ],
+  "optionalDependencies": {
+    "ccusage": "20.0.20"
+  }
 }

package/src/dashboard/app.js

@@ -429,8 +429,16 @@ function usagePresentation(usage, { wholeTask = false } = {}) {
   container.append(headline, breakdown);
   const provenance = document.createElement("span");
   const version = usage.provenance?.version ? ` ${usage.provenance.version}` : "";
+  const pricingMode = usage.provenance?.pricingMode
+    ? ` · ${usage.provenance.pricingMode === "online"
+      ? "online pricing requested"
+      : "offline pricing fallback"}`
+    : "";
   const freshness = usage.sourceUpdatedAt ?? usage.sampledAt;
-  provenance.textContent = `Source: ccusage${version}${freshness ? ` · updated ${formatRelativeTime(freshness)}` : ""}. Dollar cost is an API-equivalent estimate${wholeTask ? " for the task" : " for this turn"}.`;
+  provenance.textContent = `Source: ccusage${version}${pricingMode}${freshness ? ` · updated ${formatRelativeTime(freshness)}` : ""}. Dollar cost is an API-equivalent estimate${wholeTask ? " for the task" : " for this turn"}.`;
+  if (usage.provenance?.costCoverage === "cache_writes_unverified") {
+    provenance.textContent += " ccusage may omit GPT-5.6 cache-write charges.";
+  }
   container.append(provenance);
   return container;
 }

package/src/resolve-ccusage.js

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const [packageName, binaryName] = process.argv.slice(2);
+if (!/^@ccusage\/ccusage-(?:darwin|linux|win32)-(?:arm64|x64)$/u.test(packageName ?? "")
+  || !/^ccusage(?:\.exe)?$/u.test(binaryName ?? "")) {
+  process.exit(1);
+}
+
+const binDirectory = process.env.PATH
+  ?.split(path.delimiter)
+  .find((entry) => entry.endsWith(path.join("node_modules", ".bin")));
+const binary = binDirectory
+  ? path.join(path.dirname(binDirectory), packageName, "bin", binaryName)
+  : null;
+if (binary === null || !existsSync(binary)) process.exit(1);
+process.stdout.write(binary);

package/src/usage.js

@@ -1,10 +1,16 @@
 import { execFile as execFileCallback } from "node:child_process";
+import { existsSync } from "node:fs";
 import { lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
-import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 
-const execFile = promisify(execFileCallback);
+const require = createRequire(import.meta.url);
+const taskchefPackage = require("../package.json");
+const PINNED_CCUSAGE_VERSION = taskchefPackage.optionalDependencies?.ccusage;
+const CCUSAGE_RESOLVER = fileURLToPath(new URL("./resolve-ccusage.js", import.meta.url));
+let npxResolvedCcusageInvocation = null;
 const USAGE_FILE_NAME = ".taskchef-usage.json";
 const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/gi;
 const TOKEN_FIELDS = [
@@ -76,6 +82,13 @@ function normalizeProvenance(value, name, { includeSessionCount = false } = {})
   return {
     provider: "ccusage",
     version: typeof value.version === "string" ? value.version.slice(0, 64) : null,
+    pricingMode: value.pricingMode === "online" || value.pricingMode === "offline"
+      ? value.pricingMode
+      : null,
+    costCoverage: value.costCoverage === "cache_writes_unverified"
+      || value.costCoverage === "ccusage_reported"
+      ? value.costCoverage
+      : null,
     ...(includeSessionCount ? {
       sessionCount: nonNegativeNumber(value.sessionCount, `${name}.provenance.sessionCount`),
     } : {}),
@@ -107,6 +120,10 @@ function normalizeStoredSnapshot(value, name) {
   }
   snapshot.models = models;
   snapshot.provenance = normalizeProvenance(value.provenance, name, { includeSessionCount: true });
+  if (snapshot.provenance.pricingMode === null || snapshot.provenance.costCoverage === null) {
+    snapshot.estimatedCostUsd = null;
+    snapshot.costStatus = "unavailable";
+  }
   snapshot.sampledAt = timestampOrNull(value.sampledAt, `${name}.sampledAt`);
   snapshot.sourceUpdatedAt = timestampOrNull(value.sourceUpdatedAt, `${name}.sourceUpdatedAt`);
   return snapshot;
@@ -125,11 +142,15 @@ function normalizeStoredTurn(value, name) {
     normalized.estimatedCostUsd = value.estimatedCostUsd === null
       ? null
       : nonNegativeNumber(value.estimatedCostUsd, `${name}.estimatedCostUsd`);
+    const provenance = normalizeProvenance(value.provenance, name);
+    if (provenance.pricingMode === null || provenance.costCoverage === null) {
+      normalized.estimatedCostUsd = null;
+    }
     return {
       status: "available",
       ...normalized,
       costStatus: normalized.estimatedCostUsd === null ? "unavailable" : "estimated",
-      provenance: normalizeProvenance(value.provenance, name),
+      provenance,
       sampledAt: timestampOrNull(value.sampledAt, `${name}.sampledAt`),
       sourceUpdatedAt: timestampOrNull(value.sourceUpdatedAt, `${name}.sourceUpdatedAt`),
       updatedAt,
@@ -196,6 +217,7 @@ function normalizeStoredRecord(value, name) {
 export function aggregateCcusageSessions(payload, threadId, {
   sampledAt = new Date().toISOString(),
   version = null,
+  pricingMode = null,
 } = {}) {
   if (!payload || typeof payload !== "object" || !Array.isArray(payload.sessions)) {
     throw new Error("ccusage output must contain a sessions array");
@@ -241,6 +263,10 @@ export function aggregateCcusageSessions(payload, threadId, {
     provenance: {
       provider: "ccusage",
       version,
+      pricingMode,
+      costCoverage: Object.keys(models).some((model) => /^gpt-5\.6(?:-|$)/i.test(model))
+        ? "cache_writes_unverified"
+        : "ccusage_reported",
       sessionCount: sessions.length,
     },
     sampledAt,
@@ -248,41 +274,291 @@ export function aggregateCcusageSessions(payload, threadId, {
   };
 }
 
-export async function readCcusageThreadUsage(threadId, {
-  command = "ccusage",
-  run = execFile,
-  sampledAt = new Date().toISOString(),
-  timeoutMs = 8_000,
+export function managedCcusageInvocation({
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  resolvePath = (id) => require.resolve(id),
+  exists = existsSync,
+  npxCliPath = null,
 } = {}) {
-  let version = null;
-  try {
-    const result = await run(command, ["--version"], {
-      timeout: Math.min(timeoutMs, 2_000),
-      maxBuffer: 64 * 1024,
+  if (typeof PINNED_CCUSAGE_VERSION !== "string" || PINNED_CCUSAGE_VERSION.length === 0) {
+    throw new Error("TaskChef has no pinned ccusage version");
+  }
+  const packageName = {
+    "darwin-arm64": "@ccusage/ccusage-darwin-arm64",
+    "darwin-x64": "@ccusage/ccusage-darwin-x64",
+    "linux-arm64": "@ccusage/ccusage-linux-arm64",
+    "linux-x64": "@ccusage/ccusage-linux-x64",
+    "win32-arm64": "@ccusage/ccusage-win32-arm64",
+    "win32-x64": "@ccusage/ccusage-win32-x64",
+  }[`${platform}-${arch}`];
+  let nativeBinary = null;
+  if (packageName !== undefined) {
+    try {
+      nativeBinary = resolvePath(
+        `${packageName}/bin/${platform === "win32" ? "ccusage.exe" : "ccusage"}`,
+      );
+    } catch {
+      // Plugin-only installations can resolve the same pinned release through npx.
+    }
+  }
+  if (nativeBinary !== null) {
+    return {
+      command: nativeBinary,
+      args: [],
+      version: PINNED_CCUSAGE_VERSION,
+    };
+  }
+  if (packageName === undefined) {
+    throw new Error(`ccusage does not support ${platform}-${arch}`);
+  }
+  const binaryName = platform === "win32" ? "ccusage.exe" : "ccusage";
+  const npxArgs = [
+    "--yes",
+    "--prefer-offline",
+    `--package=ccusage@${PINNED_CCUSAGE_VERSION}`,
+    "node",
+    CCUSAGE_RESOLVER,
+    packageName,
+    binaryName,
+  ];
+  if (platform === "win32") {
+    const platformPath = path.win32;
+    const nodeDirectory = platformPath.dirname(process.execPath);
+    const candidates = [
+      npxCliPath,
+      typeof env.npm_execpath === "string"
+        ? platformPath.join(platformPath.dirname(env.npm_execpath), "npx-cli.js")
+        : null,
+      platformPath.join(nodeDirectory, "node_modules", "npm", "bin", "npx-cli.js"),
+      platformPath.resolve(
+        nodeDirectory,
+        "..", "lib", "node_modules", "npm", "bin", "npx-cli.js",
+      ),
+    ];
+    const npxCli = candidates.find((candidate) => typeof candidate === "string"
+      && platformPath.isAbsolute(candidate)
+      && exists(candidate));
+    if (npxCli === undefined) throw new Error("TaskChef could not resolve npm's npx CLI safely");
+    return {
+      command: process.execPath,
+      args: [npxCli, ...npxArgs],
+      version: PINNED_CCUSAGE_VERSION,
+      resolvesNative: true,
+    };
+  }
+  return {
+    command: "npx",
+    args: npxArgs,
+    version: PINNED_CCUSAGE_VERSION,
+    resolvesNative: true,
+  };
+}
+
+async function resolveManagedCcusageInvocation(invocation, run, timeoutMs) {
+  if (invocation.resolvesNative !== true) return invocation;
+  if (npxResolvedCcusageInvocation !== null
+    && existsSync(npxResolvedCcusageInvocation.command)) {
+    return npxResolvedCcusageInvocation;
+  }
+  npxResolvedCcusageInvocation = null;
+  const result = await run(invocation.command, invocation.args, {
+    timeout: timeoutMs,
+    maxBuffer: 64 * 1024,
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+  const command = String(result.stdout).trim();
+  if (!path.isAbsolute(command)
+    || !/^ccusage(?:\.exe)?$/iu.test(path.basename(command))
+    || !existsSync(command)) {
+    throw new Error("npx returned an invalid ccusage executable");
+  }
+  npxResolvedCcusageInvocation = {
+    command,
+    args: [],
+    version: invocation.version,
+  };
+  return npxResolvedCcusageInvocation;
+}
+
+function processTable() {
+  return new Promise((resolve) => {
+    execFileCallback("ps", ["-axo", "pid=,ppid="], {
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: 250,
+      windowsHide: true,
+    }, (error, stdout) => {
+      if (error) {
+        resolve([]);
+        return;
+      }
+      resolve(String(stdout).trim().split("\n").flatMap((line) => {
+        const [pid, parentPid] = line.trim().split(/\s+/u).map(Number);
+        return Number.isInteger(pid) && Number.isInteger(parentPid)
+          ? [{ pid, parentPid }]
+          : [];
+      }));
+    });
+  });
+}
+
+async function descendantProcessIds(parentPid) {
+  const table = await processTable();
+  const visit = (pid) => table
+    .filter((entry) => entry.parentPid === pid)
+    .flatMap((entry) => [...visit(entry.pid), entry.pid]);
+  return visit(parentPid);
+}
+
+async function terminateProcessTree(child, platform = process.platform) {
+  if (!Number.isInteger(child.pid)) return;
+  if (platform === "win32") {
+    await new Promise((resolve) => {
+      execFileCallback(
+        "taskkill",
+        ["/pid", String(child.pid), "/t", "/f"],
+        { timeout: 500, windowsHide: true },
+        () => {
+          child.kill("SIGKILL");
+          resolve();
+        },
+      );
     });
-    version = String(result.stdout).trim().replace(/^ccusage\s+/i, "") || null;
+    return;
+  }
+  try {
+    process.kill(-child.pid, "SIGKILL");
+    return;
   } catch {
-    // Usage remains useful if an older compatible ccusage cannot print its version.
+    // Resolve descendants only when process-group termination is unavailable.
   }
-  let result;
+  let descendants = [];
   try {
-    result = await run(command, ["codex", "session", "--json", "--offline"], {
-      timeout: timeoutMs,
-      maxBuffer: 32 * 1024 * 1024,
-      env: { ...process.env, NO_COLOR: "1" },
+    descendants = await descendantProcessIds(child.pid);
+  } catch {
+    // The detached process-group kill remains the fallback when ps is unavailable.
+  }
+  for (const pid of descendants) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // The group kill or normal process exit may have won the race.
+    }
+  }
+  child.kill("SIGKILL");
+}
+
+export function runBoundedProcess(command, args, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const timeout = options.timeout ?? 0;
+  const { platform: _platform, ...childOptions } = options;
+  return new Promise((resolve, reject) => {
+    let timedOut = false;
+    let timer = null;
+    let settled = false;
+    const rejectOnce = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    const child = execFileCallback(command, args, {
+      ...childOptions,
+      timeout: undefined,
+      detached: platform !== "win32",
+      windowsHide: true,
+    }, async (error, stdout, stderr) => {
+      if (timer !== null) clearTimeout(timer);
+      if (timedOut || settled) return;
+      if (error) {
+        await terminateProcessTree(child, platform);
+        rejectOnce(error);
+        return;
+      }
+      settled = true;
+      resolve({ stdout, stderr });
     });
-  } catch (error) {
-    if (error?.code === "ENOENT") throw new Error("ccusage is not installed");
-    if (error?.killed || error?.code === "ETIMEDOUT") throw new Error("ccusage timed out");
-    throw new Error("ccusage could not read Codex usage");
+    if (timeout > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        const timeoutError = new Error(`${command} timed out`);
+        timeoutError.code = "ETIMEDOUT";
+        timeoutError.killed = true;
+        Promise.race([
+          terminateProcessTree(child, platform),
+          new Promise((resolveTermination) => setTimeout(resolveTermination, 750)),
+        ]).catch(() => {}).then(() => rejectOnce(timeoutError));
+      }, timeout);
+      timer.unref();
+    }
+  });
+}
+
+export async function readCcusageThreadUsage(threadId, {
+  command = null,
+  commandArgs = [],
+  run = runBoundedProcess,
+  sampledAt = new Date().toISOString(),
+  timeoutMs = 8_000,
+} = {}) {
+  const invocation = command === null
+    ? managedCcusageInvocation()
+    : { command, args: commandArgs, version: null };
+  const resolvedInvocation = await resolveManagedCcusageInvocation(invocation, run, timeoutMs);
+  const invoke = (args, options) => run(
+    resolvedInvocation.command,
+    [...resolvedInvocation.args, ...args],
+    options,
+  );
+  let version = resolvedInvocation.version;
+  if (version === null) {
+    try {
+      const result = await invoke(["--version"], {
+        timeout: Math.min(timeoutMs, 2_000),
+        maxBuffer: 64 * 1024,
+      });
+      version = String(result.stdout).trim().replace(/^ccusage\s+/i, "") || null;
+    } catch {
+      // Usage remains useful if a custom compatible ccusage cannot print its version.
+    }
   }
-  let payload;
+  const report = async (pricingMode) => {
+    let result;
+    try {
+      result = await invoke([
+        "codex", "session", "--json",
+        pricingMode === "online" ? "--no-offline" : "--offline",
+      ], {
+        timeout: timeoutMs,
+        maxBuffer: 32 * 1024 * 1024,
+        env: { ...process.env, NO_COLOR: "1" },
+      });
+    } catch (error) {
+      if (error?.code === "ENOENT") throw new Error("ccusage is not installed");
+      if (error?.killed || error?.code === "ETIMEDOUT") throw new Error("ccusage timed out");
+      throw new Error("ccusage could not read Codex usage");
+    }
+    let payload;
+    try {
+      payload = JSON.parse(result.stdout);
+    } catch {
+      throw new Error("ccusage returned malformed JSON");
+    }
+    return aggregateCcusageSessions(payload, threadId, {
+      sampledAt,
+      version,
+      pricingMode,
+    });
+  };
   try {
-    payload = JSON.parse(result.stdout);
-  } catch {
-    throw new Error("ccusage returned malformed JSON");
+    return await report("online");
+  } catch (onlineError) {
+    try {
+      return await report("offline");
+    } catch {
+      throw onlineError;
+    }
   }
-  return aggregateCcusageSessions(payload, threadId, { sampledAt, version });
 }
 
 function usageFile(workspace) {
@@ -372,7 +648,10 @@ export function usageDelta(current, previous = null) {
     if (!Number.isFinite(value) || value < 0) return null;
     delta[field] = value;
   }
-  let estimatedCostUsd = current.estimatedCostUsd === null
+  const samePricingSource = previous === null || ["version", "pricingMode", "costCoverage"]
+    .every((field) => current.provenance?.[field] === previous.provenance?.[field]);
+  let estimatedCostUsd = !samePricingSource
+    || current.estimatedCostUsd === null
     || (previous !== null && previous.estimatedCostUsd === null)
     ? null
     : current.estimatedCostUsd - (previous?.estimatedCostUsd ?? 0);