agent-orchestrator-kit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-31
+
+### Added
+- **`costUsdEstimated` first-class** in `metrics.json` (`spend`, platforms, models, sessions, sources). Cursor writes a labeled estimate whenever tokens exist: grok-4.5/4.6 keep xAI API rates (`costSource: "api-estimate"`); other models use a versioned fallback of $3/1M input + $15/1M output (or $3.50/1M when only `totalTokens` is present, `costSource: "api-estimate-fallback"`). This is **not** a Cursor invoice and is never mixed into billed `costUsd`. Self-report `cost_usd` stays billed and is not copied into `costUsdEstimated`. Amp without a `Cost:` line leaves `costUsd: null` (tokens are not converted to USD; credits stay separate). Archived `metrics.json` files are not backfilled.
+
 ## [0.9.0] - 2026-08-31
 
 ### Added
@@ -252,6 +257,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.10.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.6.0...v0.7.0

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (UTC timestamps + Amp stamp parse, Amp billed `$`, Cursor API estimate, archive auto-collect in v0.9.0; locked Amp/Cursor client in v0.8.0; `## Metrics` self-report + opt-in `--collect` in v0.7.0 — **BREAKING:** `--no-collect` is gone; change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (Cursor fallback estimate + first-class `costUsdEstimated` in v0.10.0; UTC timestamps + Amp stamp parse, Amp billed `$`, Cursor API estimate, archive auto-collect in v0.9.0; locked Amp/Cursor client in v0.8.0; `## Metrics` self-report + opt-in `--collect` in v0.7.0 — **BREAKING:** `--no-collect` is gone; change metrics in v0.5.0+, factory phases 1–3 in v0.4.0+, lean pipeline / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -804,7 +804,7 @@ Every change accumulates git-tracked `openspec/changes/<name>/metrics.json` —
 - **`## Metrics` self-report** — Session Exit fills `handoff.md` with `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source` (`unknown` when missing). Persist reads that section; `metrics.json` is the source of truth for what landed. CLI flags do not rewrite the section.
 - **`session.model`** — `--model` → `## Metrics: model` → `AOK_MODEL` → collected sources (only with `--collect`) → `null` (stderr warning). Never a Closed role.
 - **Session start** — `handoff --restore` writes a `pending` marker (`startedAt`, expected role).
-- **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and spend from flags → self-report → adapters. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Amp billed USD comes from `amp threads usage --details` (fail-open), not from converting credits. Cursor tokens get a labeled `costUsdEstimated` (xAI API rates for grok-4.6/4.5, including `-fast` and the 200k cliff) — that estimate is **not** the Cursor invoice and is never added into billed `costUsd`. Timestamps are ISO-8601 UTC (`…Z`). No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
+- **Session end** — `handoff <name>` closes the pending session: duration, closed role, mapped phase (`explore` / `design` / `spec` / `review` / `apply` / `archive`), runtime (local/cloud), tasks snapshot (`n/m`), and spend from flags → self-report → adapters. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session totals only and do not wipe `spendByPlatform` / `spendByModel`. Amp billed USD comes from `amp threads usage --details` (`Cost: $N` only; missing line → `costUsd: null`), not from converting credits. Cursor always writes a labeled `costUsdEstimated` when tokens exist: grok-4.6/4.5 use xAI API rates (`costSource: api-estimate`, including `-fast` and the 200k cliff); other models use a versioned fallback of $3/1M input + $15/1M output (or $3.50/1M when only `totalTokens` is present, `costSource: api-estimate-fallback`). That estimate is **not** the Cursor invoice and is never added into billed `costUsd`. Timestamps are ISO-8601 UTC (`…Z`). No restore marker? Pass `--started-at <iso>` or the duration stays honestly `null`.
 - **Archive** — successful `archive <name>` always creates or finalizes `metrics.json`, sets `archivedAt`, appends an Archiver session, collects the locked client (Cursor hook / Amp export+usage / Claude JSONL) in `[last session.endedAt, now]`, and prints the same human summary as `metrics <name>`. `--collect` still runs all three adapters. Leftover apply `## Metrics` that repeats the previous session is ignored so those tokens are not counted twice.
 - **Platform** — `--platform` → `## Metrics: platform` → `AOK_PLATFORM` → **pending client from `--restore`** → host env (Amp / Cursor / Claude Code) → collected sources (`cursor|claude|amp` only). Invalid `--platform` fails before persist/move.
 - **Locked client** — `--restore` records `pending.platform` and Amp `pending.threadId` before phase work. Persist follows that client’s flow even if persist runs in another shell (no `AMP_*` / `CURSOR_*`). Amp: `amp threads export` plus `amp threads usage --details` (`AOK_AMP_BIN`) and local `threads/*.json`. Export supplies `model` / tokens / `agentMode`; usage supplies billed `$`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. Cursor: spend hook file. Claude: `~/.claude/projects`. `--collect` still runs all three adapters.
@@ -1003,6 +1003,9 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.10.0
+- `costUsdEstimated` is first-class on `metrics.json`; Cursor writes a labeled estimate whenever tokens exist — grok via xAI API (`costSource: api-estimate`), other models via versioned fallback $3/1M in + $15/1M out (or $3.50/1M when only `totalTokens`, `costSource: api-estimate-fallback`). The estimate is **not** an invoice and is never mixed into billed `costUsd`. Amp without a `Cost:` line leaves `costUsd: null`; self-report `cost_usd` stays billed.
+
 ### 0.9.0
 - **UTC timestamps** in `metrics.json` (`…Z`; broken Amp stamps parsed and normalized)
 - Amp `threads usage --details` billed `$` + `agentMode` (never stored as `session.model`)

package/bin/agent-orchestrator.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import pc from 'picocolors';
-import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync, chmodSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync, chmodSync, realpathSync } from 'fs';
 import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -4248,4 +4248,18 @@ program
     for (const line of renderMetricsSummary(metrics)) console.log(line);
   });
 
-program.parse();
+function isDirectCliRun() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return resolve(entry) === fileURLToPath(import.meta.url);
+  }
+}
+
+if (isDirectCliRun()) {
+  program.parse();
+}
+
+export { formatMetricsCostLine, resolveSessionSpend };

package/bin/cursor-cost-estimate.js

@@ -14,6 +14,10 @@ const GROK_46 = {
   longAt: 200000,
 };
 
+const FALLBACK_INPUT_PER_M = 3;
+const FALLBACK_OUTPUT_PER_M = 15;
+const FALLBACK_TOTAL_PER_M = 3.5;
+
 function ratesForModel(model) {
   const id = String(model || '').toLowerCase();
   if (!id) return null;
@@ -32,19 +36,41 @@ function ratesForModel(model) {
   return rates;
 }
 
-export function estimateCursorCostUsd({ model, inputTokens, outputTokens, cacheReadTokens } = {}) {
+export function estimateCursorCostUsd({ model, inputTokens, outputTokens, cacheReadTokens, totalTokens } = {}) {
   const rates = ratesForModel(model);
-  if (!rates) return null;
+  if (rates) {
+    const input = numOrNull(inputTokens);
+    const output = numOrNull(outputTokens) ?? 0;
+    if (input == null && output == 0) return null;
+    const totalInput = input ?? 0;
+    const cached = Math.min(numOrNull(cacheReadTokens) ?? 0, totalInput);
+    const fresh = Math.max(0, totalInput - cached);
+    const long = totalInput >= rates.longAt;
+    const inputRate = long ? rates.longInputPerM : rates.inputPerM;
+    const cachedRate = long ? rates.longCachedPerM : rates.cachedPerM;
+    const outputRate = long ? rates.longOutputPerM : rates.outputPerM;
+    const usd = (fresh * inputRate + cached * cachedRate + output * outputRate) / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
   const input = numOrNull(inputTokens);
-  const output = numOrNull(outputTokens) ?? 0;
-  if (input == null && output == 0) return null;
-  const totalInput = input ?? 0;
-  const cached = Math.min(numOrNull(cacheReadTokens) ?? 0, totalInput);
-  const fresh = Math.max(0, totalInput - cached);
-  const long = totalInput >= rates.longAt;
-  const inputRate = long ? rates.longInputPerM : rates.inputPerM;
-  const cachedRate = long ? rates.longCachedPerM : rates.cachedPerM;
-  const outputRate = long ? rates.longOutputPerM : rates.outputPerM;
-  const usd = (fresh * inputRate + cached * cachedRate + output * outputRate) / 1e6;
-  return Math.round(usd * 10000) / 10000;
+  const output = numOrNull(outputTokens);
+  if (input != null || output != null) {
+    const usd = ((input ?? 0) * FALLBACK_INPUT_PER_M + (output ?? 0) * FALLBACK_OUTPUT_PER_M) / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
+  const total = numOrNull(totalTokens);
+  if (total != null) {
+    const usd = total * FALLBACK_TOTAL_PER_M / 1e6;
+    return Math.round(usd * 10000) / 10000;
+  }
+  return null;
+}
+
+export function describeCursorCostEstimate(args) {
+  const usd = estimateCursorCostUsd(args);
+  if (usd == null) return null;
+  return {
+    usd,
+    costSource: ratesForModel(args && args.model) != null ? 'api-estimate' : 'api-estimate-fallback',
+  };
 }

package/bin/spend-collect.js

@@ -4,7 +4,7 @@ import { homedir as osHomedir } from 'os';
 import { execFileSync } from 'child_process';
 import { listRecentAmpThreadIds } from './session-client.js';
 import { formatUtcIso, parseFlexibleIso } from './metrics-time.js';
-import { estimateCursorCostUsd } from './cursor-cost-estimate.js';
+import { describeCursorCostEstimate } from './cursor-cost-estimate.js';
 import { ampAgentMode, matchAmpUsageModel, parseAmpUsageDetails } from './amp-usage.js';
 
 const PLATFORMS = ['cursor', 'claude', 'amp'];
@@ -535,7 +535,7 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
     if (inputTokens == null && outputTokens == null) continue;
     const model = row.model || row.modelId;
     const cacheReadTokens = numOrNull(row.cacheReadTokens);
-    const estimated = estimateCursorCostUsd({
+    const described = describeCursorCostEstimate({
       model,
       inputTokens,
       outputTokens,
@@ -551,8 +551,8 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
       ampCredits: null,
       at: row.at,
       cacheReadTokens,
-      costUsdEstimated: estimated,
-      costSource: estimated != null ? 'api-estimate' : null,
+      costUsdEstimated: described?.usd ?? null,
+      costSource: described?.costSource ?? null,
     });
     const previous = bestById.get(id);
     if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff, factory gates and MCP setup, cloud-agent handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",