agent-orchestrator-kit 0.7.0 → 0.9.0

package/bin/spend-collect.js

@@ -1,6 +1,11 @@
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join, basename } from 'path';
 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 { ampAgentMode, matchAmpUsageModel, parseAmpUsageDetails } from './amp-usage.js';
 
 const PLATFORMS = ['cursor', 'claude', 'amp'];
 
@@ -22,6 +27,7 @@ function emptyPlatform(source = 'none') {
     totalTokens: null,
     costUsd: null,
     ampCredits: null,
+    costUsdEstimated: null,
     source,
   };
 }
@@ -57,11 +63,7 @@ function pathsEqual(a, b) {
 }
 
 function parseTime(value) {
-  if (value == null || value === '') return NaN;
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value < 1e12 ? value * 1000 : value;
-  }
-  return Date.parse(String(value));
+  return parseFlexibleIso(value);
 }
 
 function inWindow(timestamp, windowStart, windowEnd) {
@@ -78,12 +80,25 @@ function inWindow(timestamp, windowStart, windowEnd) {
   return true;
 }
 
-function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd, ampCredits, at }) {
+function sourceRecord({
+  id,
+  platform,
+  model,
+  inputTokens,
+  outputTokens,
+  costUsd,
+  ampCredits,
+  at,
+  cacheReadTokens,
+  costUsdEstimated,
+  costSource,
+  agentMode,
+}) {
   const input = numOrNull(inputTokens);
   const output = numOrNull(outputTokens);
   let total = null;
   if (input != null || output != null) total = (input ?? 0) + (output ?? 0);
-  return {
+  const record = {
     id: String(id),
     platform,
     model: model == null || model === '' ? null : String(model),
@@ -92,8 +107,15 @@ function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd,
     totalTokens: total,
     costUsd: numOrNull(costUsd),
     ampCredits: numOrNull(ampCredits),
-    at: at == null ? null : String(at),
+    at: at == null || at === '' ? null : (formatUtcIso(at) || String(at)),
   };
+  const cache = numOrNull(cacheReadTokens);
+  if (cache != null) record.cacheReadTokens = cache;
+  const estimated = numOrNull(costUsdEstimated);
+  if (estimated != null) record.costUsdEstimated = estimated;
+  if (costSource) record.costSource = String(costSource);
+  if (agentMode) record.agentMode = String(agentMode);
+  return record;
 }
 
 function claudeInputTokens(usage) {
@@ -309,6 +331,37 @@ function ampInputTokens(usage) {
   return has ? sum : null;
 }
 
+export function sourcesFromAmpThread(thread, ctx, fileName = '', via = null) {
+  const sources = [];
+  if (!thread || typeof thread !== 'object') return sources;
+  const { cwd, windowStart, windowEnd, existing, env } = ctx;
+  if (!ampThreadMatches(thread, cwd, env, fileName)) return sources;
+  const threadKey = thread.id ? String(thread.id) : basename(fileName || 'thread', '.json');
+  for (const message of ampMessages(thread)) {
+    const usage = ampUsage(message);
+    if (!usage) continue;
+    const rawId = ampId(message);
+    if (rawId == null || rawId === '') continue;
+    const id = `${threadKey}:${rawId}`;
+    if (existing.has(id)) continue;
+    if (!inWindow(usage.timestamp, windowStart, windowEnd)) continue;
+    const record = sourceRecord({
+      id,
+      platform: 'amp',
+      model: usage.model,
+      inputTokens: ampInputTokens(usage),
+      outputTokens: usage.outputTokens,
+      costUsd: null,
+      ampCredits: null,
+      at: usage.timestamp,
+      agentMode: ampAgentMode(thread),
+    });
+    if (via) record.via = via;
+    sources.push(record);
+  }
+  return sources;
+}
+
 function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
   const root = ampRoot(env, homedir);
   const threadsDir = join(root, 'threads');
@@ -324,6 +377,7 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     notes.push('amp: cannot read threads');
     return sources;
   }
+  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
   for (const file of files) {
     let thread;
     try {
@@ -331,34 +385,120 @@ function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes
     } catch {
       continue;
     }
-    if (!thread || typeof thread !== 'object') continue;
-    if (!ampThreadMatches(thread, cwd, env, file)) continue;
-    // messageId values are thread-local counters (1, 3, 5, ...), so a bare id
-    // collides across threads; namespace with the thread id for global dedup.
-    const threadKey = thread.id ? String(thread.id) : basename(file, '.json');
-    for (const message of ampMessages(thread)) {
-      const usage = ampUsage(message);
-      if (!usage) continue;
-      const rawId = ampId(message);
-      if (rawId == null || rawId === '') continue;
-      const id = `${threadKey}:${rawId}`;
-      if (existing.has(id)) continue;
-      if (!inWindow(usage.timestamp, windowStart, windowEnd)) continue;
-      sources.push(sourceRecord({
-        id,
-        platform: 'amp',
-        model: usage.model,
-        inputTokens: ampInputTokens(usage),
-        outputTokens: usage.outputTokens,
-        costUsd: null,
-        ampCredits: null,
-        at: usage.timestamp,
-      }));
-    }
+    sources.push(...sourcesFromAmpThread(thread, ctx, file));
   }
   return sources;
 }
 
+export function exportAmpThread(threadId, options = {}) {
+  const id = threadId == null ? '' : String(threadId).trim();
+  if (!id) return null;
+  if (typeof options.exportAmpThread === 'function') {
+    try {
+      return options.exportAmpThread(id);
+    } catch {
+      return null;
+    }
+  }
+  const bin = options.ampBin || (options.env && options.env.AOK_AMP_BIN) || 'amp';
+  if (bin !== 'amp' && !existsSync(bin)) return null;
+  try {
+    const out = execFileSync(bin, ['threads', 'export', id], {
+      encoding: 'utf-8',
+      timeout: options.timeoutMs != null ? Number(options.timeoutMs) : 15000,
+      env: options.env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const parsed = JSON.parse(out);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function fetchAmpThreadUsage(threadId, options = {}) {
+  const id = threadId == null ? '' : String(threadId).trim();
+  if (!id) return null;
+  if (typeof options.usageAmpThread === 'function') {
+    try {
+      const injected = options.usageAmpThread(id);
+      if (injected == null) return null;
+      if (typeof injected === 'string') return parseAmpUsageDetails(injected);
+      if (typeof injected === 'object') {
+        if (injected.text && injected.costUsd == null) return { ...parseAmpUsageDetails(injected.text), ...injected };
+        return injected;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  if (typeof options.exportAmpThread === 'function') return null;
+  const bin = options.ampBin || (options.env && options.env.AOK_AMP_BIN) || 'amp';
+  if (bin !== 'amp' && !existsSync(bin)) return null;
+  try {
+    const out = execFileSync(bin, ['threads', 'usage', id, '--details'], {
+      encoding: 'utf-8',
+      timeout: options.timeoutMs != null ? Number(options.timeoutMs) : 25000,
+      env: options.env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseAmpUsageDetails(out);
+  } catch {
+    return null;
+  }
+}
+
+function collectAmpCli(ctx) {
+  const { env, notes, ampThreadId } = ctx;
+  const ids = [];
+  const push = (value) => {
+    const id = value == null ? '' : String(value).trim();
+    if (id && !ids.includes(id)) ids.push(id);
+  };
+  push(ampThreadId);
+  push(ampCurrentThreadId(env));
+  if (!ids.length) {
+    for (const id of listRecentAmpThreadIds(ctx)) push(id);
+  }
+  const sources = [];
+  const threads = [];
+  for (const id of ids) {
+    const thread = exportAmpThread(id, ctx);
+    if (!thread) {
+      notes.push(`amp: export failed for ${id}`);
+      continue;
+    }
+    const agentMode = ampAgentMode(thread);
+    const extracted = sourcesFromAmpThread(thread, ctx, `${id}.json`, 'amp-cli');
+    if (!extracted.length) notes.push(`amp: export ${id} had no matching usage`);
+    sources.push(...extracted);
+    const usage = fetchAmpThreadUsage(id, ctx);
+    if (!usage) notes.push(`amp: usage failed for ${id}`);
+    const sourceModels = extracted.map((src) => src.model).filter(Boolean);
+    const usageModels = (usage && Array.isArray(usage.models) ? usage.models : []).map((row) => ({
+      ...row,
+      model: matchAmpUsageModel(row.model, sourceModels),
+    }));
+    if (usage && usage.costUsd != null) {
+      for (const src of extracted) {
+        src.costSource = 'amp-usage';
+      }
+    }
+    threads.push({
+      id,
+      agentMode,
+      costUsd: usage ? numOrNull(usage.costUsd) : null,
+      inputTokens: usage ? numOrNull(usage.inputTokens) : null,
+      outputTokens: usage ? numOrNull(usage.outputTokens) : null,
+      totalTokens: usage ? numOrNull(usage.totalTokens) : null,
+      cacheReadTokens: usage ? numOrNull(usage.cacheReadTokens) : null,
+      models: usageModels,
+    });
+  }
+  return { sources, threads };
+}
+
 export const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
 
 function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
@@ -393,15 +533,26 @@ function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
     const inputTokens = numOrNull(row.inputTokens);
     const outputTokens = numOrNull(row.outputTokens);
     if (inputTokens == null && outputTokens == null) continue;
+    const model = row.model || row.modelId;
+    const cacheReadTokens = numOrNull(row.cacheReadTokens);
+    const estimated = estimateCursorCostUsd({
+      model,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+    });
     const record = sourceRecord({
       id,
       platform: 'cursor',
-      model: row.model || row.modelId,
+      model,
       inputTokens,
       outputTokens,
       costUsd: null,
       ampCredits: null,
       at: row.at,
+      cacheReadTokens,
+      costUsdEstimated: estimated,
+      costSource: estimated != null ? 'api-estimate' : null,
     });
     const previous = bestById.get(id);
     if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
@@ -423,8 +574,9 @@ function aggregate(sources) {
       bucket.totalTokens = addNullable(bucket.totalTokens, src.totalTokens);
       bucket.costUsd = addNullable(bucket.costUsd, src.costUsd);
       bucket.ampCredits = addNullable(bucket.ampCredits, src.ampCredits);
+      bucket.costUsdEstimated = addNullable(bucket.costUsdEstimated, src.costUsdEstimated);
       if (platform === 'claude') bucket.source = 'claude-jsonl';
-      else if (platform === 'amp') bucket.source = 'amp-thread';
+      else if (platform === 'amp') bucket.source = src.via === 'amp-cli' ? 'amp-cli' : 'amp-thread';
       else bucket.source = 'cursor-hook';
     }
     const model = src.model;
@@ -438,12 +590,14 @@ function aggregate(sources) {
         totalTokens: null,
         costUsd: null,
         ampCredits: null,
+        costUsdEstimated: null,
       };
       row.inputTokens = addNullable(row.inputTokens, src.inputTokens);
       row.outputTokens = addNullable(row.outputTokens, src.outputTokens);
       row.totalTokens = addNullable(row.totalTokens, src.totalTokens);
       row.costUsd = addNullable(row.costUsd, src.costUsd);
       row.ampCredits = addNullable(row.ampCredits, src.ampCredits);
+      row.costUsdEstimated = addNullable(row.costUsdEstimated, src.costUsdEstimated);
       byModel.set(key, row);
     }
   }
@@ -464,23 +618,74 @@ export function collectSpend(options = {}) {
   const windowStart = options.windowStart;
   const windowEnd = options.windowEnd;
   const notes = [];
-  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
+  const wanted = Array.isArray(options.platforms)
+    ? options.platforms.filter((name) => PLATFORMS.includes(name))
+    : PLATFORMS;
+  const run = (name) => !wanted.length || wanted.includes(name);
+  const ctx = {
+    cwd,
+    windowStart,
+    windowEnd,
+    existing,
+    env,
+    homedir,
+    notes,
+    ampThreadId: options.ampThreadId,
+    exportAmpThread: options.exportAmpThread,
+    listAmpThreads: options.listAmpThreads,
+    usageAmpThread: options.usageAmpThread,
+    ampBin: options.ampBin,
+    timeoutMs: options.timeoutMs,
+  };
   let sources = [];
-  try {
-    sources = sources.concat(collectClaude(ctx));
-  } catch {
-    notes.push('claude: adapter failed');
+  const ampThreads = [];
+  if (run('claude')) {
+    try {
+      sources = sources.concat(collectClaude(ctx));
+    } catch {
+      notes.push('claude: adapter failed');
+    }
   }
-  try {
-    sources = sources.concat(collectAmp(ctx));
-  } catch {
-    notes.push('amp: adapter failed');
+  if (run('amp')) {
+    if (options.ampCli === true || typeof options.exportAmpThread === 'function') {
+      try {
+        const cli = collectAmpCli(ctx);
+        sources = sources.concat(cli.sources || []);
+        if (Array.isArray(cli.threads)) ampThreads.push(...cli.threads);
+      } catch {
+        notes.push('amp: cli export failed');
+      }
+    }
+    try {
+      sources = sources.concat(collectAmp(ctx));
+    } catch {
+      notes.push('amp: adapter failed');
+    }
   }
-  try {
-    sources = sources.concat(collectCursor(ctx));
-  } catch {
-    notes.push('cursor: adapter failed');
+  if (run('cursor')) {
+    try {
+      sources = sources.concat(collectCursor(ctx));
+    } catch {
+      notes.push('cursor: adapter failed');
+    }
   }
   const { byPlatform, byModel } = aggregate(sources);
-  return { sources, byPlatform, byModel, notes };
+  applyAmpThreadSpend(byPlatform, byModel, ampThreads);
+  return { sources, byPlatform, byModel, notes, ampThreads };
+}
+
+function applyAmpThreadSpend(byPlatform, byModel, threads) {
+  if (!threads || !threads.length) return;
+  let cost = null;
+  for (const thread of threads) {
+    cost = addNullable(cost, numOrNull(thread.costUsd));
+    for (const row of thread.models || []) {
+      if (!row.model) continue;
+      const key = `${row.model}::amp`;
+      const existing = byModel.find((item) => `${item.model}::${item.platform || ''}` === key)
+        || byModel.find((item) => item.platform === 'amp' && item.model === row.model);
+      if (existing && row.costUsd != null) existing.costUsd = addNullable(existing.costUsd, row.costUsd);
+    }
+  }
+  if (cost != null) byPlatform.amp.costUsd = addNullable(byPlatform.amp.costUsd, cost);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.7.0",
+  "version": "0.9.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",

package/templates/.agents/commands/opsx-archive.md

@@ -21,7 +21,7 @@ Archive is one CLI call, no phase subagents.
    npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-   Gates, optional `--sync`, move to `archive/YYYY-MM-DD-<name>`, validate+rollback, final `handoff.md` (`next_command: none`) + memory. A successful `archive` always creates or updates `metrics.json` (`archivedAt`, Archiver session) and prints the change-wide metrics summary. Collect runs only with `--collect`; if `spend.costUsd` is `null` — stderr warning, not a gate.
+   Gates, optional `--sync`, move to `archive/YYYY-MM-DD-<name>`, validate+rollback, final `handoff.md` (`next_command: none`) + memory. A successful `archive` always creates or updates `metrics.json` (`archivedAt`, Archiver session), collects the locked client into that session (Cursor hook / Amp usage / Claude JSONL; `--collect` = all adapters), and prints the change-wide metrics summary. If `spend.costUsd` is `null` — stderr warning, not a gate.
 
 4. **Show stdout as-is.** On exit ≠ 0, report the gate from stderr and stop — no manual merge/move.
 

package/templates/.agents/rules/session-handoff.mdc

@@ -12,7 +12,7 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 ## Session Start (before any work)
 1. Honor pasted `/opsx:<phase> <name>` and announce the role.
 2. `npx agent-orchestrator-kit status`
-3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. No separate Memory MCP read step.
+3. `npx agent-orchestrator-kit handoff --restore` (or `handoff <name> --restore`). The CLI briefing is canonical — it already reads memory.json and handoff.md; accumulated decisions print from git-tracked `openspec/changes/<name>/decisions.md`, not from Memory. No separate Memory MCP read step. Restore also locks the session client (`cursor` / `claude` / `amp`) into `metrics.json` `pending` — persist will follow that client’s spend flow. Override with `--platform` when detection is wrong.
 4. If the restore CLI failed → read `openspec/changes/<name>/handoff.md` directly.
 5. Spawn `session-handoff` in restore mode ONLY if both the CLI and handoff.md are unavailable (Amp: isolated `subagent-session-handoff`). This is a fallback, never a routine step.
 6. Free-form continue/next/«далі» with one active change → execute `Handoff.next_command`.
@@ -21,7 +21,7 @@ Agents (local or cloud) write session artifacts only to git-tracked paths — ne
 ## Session Exit (order)
 1. The parent writes `openspec/changes/<name>/handoff.md` itself: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime, Metrics.
 2. Fill `## Metrics` before running persist. Required keys: `platform`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `amp_credits`, `spend_source`. Use `unknown` when a value is missing — never invent `0`. This self-report is the primary spend source; `metrics.json` records what the CLI resolved.
-3. `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6`) — NEVER pass a Closed role (`Architect`, `Implementer`, `Explorer`) or a subagent name (`spec-architect`, `session-handoff`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps; they do not rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` also runs local spend adapters (Claude JSONL, Amp threads, Cursor spend hook file). The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, a Claude `/cost` parser, or an Amp billing API as a required step. `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
+3. `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, records the session into `openspec/changes/<name>/metrics.json`, prints the expanded prompt on stdout). `--model` is the LLM product id of this chat (`claude-opus-5`, `claude-fable-5`, `gpt-5.6-sol`, `cursor-grok-4.6`, `accounts/fireworks/models/glm-5p2`) — NEVER pass a Closed role, a subagent name, or an Amp **mode** (`low`, `medium`, `high`, `ultra`) as `--model`. The parent SHOULD still pass `--model`. The parent MUST NOT guess tokens. Persist collects spend for the client locked at restore (Amp: `amp threads export` + local threads; Cursor: hook file; Claude: JSONL). `--input-tokens` / `--output-tokens` / `--total-tokens` / `--cost-usd` override session-level totals only and do not wipe platform maps; they do not rewrite `## Metrics`. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. Optional `--collect` runs all three adapters, not only the locked client. The same `npx agent-orchestrator-kit handoff <name>` works in Cursor, Claude Code, and Amp. `decisions.md` is the git canon of change decisions; Memory `Decision:*` is a file→Memory mirror only. Cloud sessions pass `--runtime cloud` (or set `AOK_RUNTIME=cloud` / `AOK_AGENT_ID` in the cloud-agent environment).
 4. Spawn `session-handoff` in persist mode ONLY if step 3 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
 5. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
 6. Paste CLI stdout as one fenced block. First line `/opsx:…`. Body uses `project.agent_language`. Self-contained (Done/Decisions/Blocked/spawn/HARD STOP). No banner.

package/templates/.agents/subagents/spec-archiver.md

@@ -9,7 +9,7 @@ Workflow:
 
 1. Read `.agents/orchestrator.yaml`, the complete change, review verdict, task state, and verification/merge evidence supplied by the conductor.
 2. Refuse to archive unless required review is approved, all tasks are complete, and the configured merge/CI gate is satisfied.
-3. Fill `## Metrics` in the change `handoff.md` (Archiver self-report: platform, model, tokens, cost_usd, amp_credits, spend_source; use `unknown` when missing) before running archive.
+3. Fill `## Metrics` in the change `handoff.md` only when reporting Archiver-specific numbers (use `unknown` when missing). Do not copy the previous apply session. The CLI auto-collects the locked client into the Archiver session.
 4. Run `npx agent-orchestrator-kit archive <name>` so delta requirements are merged into main specs, the change moves to the dated archive path, and stdout prints the change-wide metrics summary (by phase / by platform / by model).
 5. Run strict validation after the move and report the resulting archive path and modified main specs.