agent-orchestrator-kit 0.4.0 → 0.6.0

package/bin/spend-collect.js

@@ -0,0 +1,414 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+import { homedir as osHomedir } from 'os';
+
+const PLATFORMS = ['cursor', 'claude', 'amp'];
+
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function addNullable(a, b) {
+  if (a == null && b == null) return null;
+  return (a ?? 0) + (b ?? 0);
+}
+
+function emptyPlatform(source = 'none') {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    ampCredits: null,
+    source,
+  };
+}
+
+function emptyByPlatform() {
+  return {
+    cursor: emptyPlatform(),
+    claude: emptyPlatform(),
+    amp: emptyPlatform(),
+  };
+}
+
+function encodeClaudeProjectDir(cwd) {
+  return String(cwd || '').replace(/[/.]/g, '-');
+}
+
+function stripFileUri(uri) {
+  const value = String(uri || '');
+  return value.startsWith('file://') ? value.slice('file://'.length) : value;
+}
+
+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));
+}
+
+function inWindow(timestamp, windowStart, windowEnd) {
+  const t = parseTime(timestamp);
+  if (!Number.isFinite(t)) return false;
+  if (windowStart) {
+    const start = parseTime(windowStart);
+    if (Number.isFinite(start) && t < start) return false;
+  }
+  if (windowEnd) {
+    const end = parseTime(windowEnd);
+    if (Number.isFinite(end) && t > end) return false;
+  }
+  return true;
+}
+
+function sourceRecord({ id, platform, model, inputTokens, outputTokens, costUsd, ampCredits, at }) {
+  const input = numOrNull(inputTokens);
+  const output = numOrNull(outputTokens);
+  let total = null;
+  if (input != null || output != null) total = (input ?? 0) + (output ?? 0);
+  return {
+    id: String(id),
+    platform,
+    model: model == null || model === '' ? null : String(model),
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: total,
+    costUsd: numOrNull(costUsd),
+    ampCredits: numOrNull(ampCredits),
+    at: at == null ? null : String(at),
+  };
+}
+
+function claudeInputTokens(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  let has = false;
+  let sum = 0;
+  if (usage.input_tokens != null || usage.inputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.input_tokens ?? usage.inputTokens) ?? 0;
+  }
+  for (const [key, value] of Object.entries(usage)) {
+    if (key.startsWith('cache_') && value != null) {
+      has = true;
+      sum += numOrNull(value) ?? 0;
+    }
+  }
+  return has ? sum : null;
+}
+
+function claudeCostUsd(row, usage) {
+  const candidates = [
+    row && row.total_cost_usd,
+    row && row.totalCostUsd,
+    row && row.cost_usd,
+    row && row.costUsd,
+    usage && usage.total_cost_usd,
+    usage && usage.totalCostUsd,
+    usage && usage.cost_usd,
+    usage && usage.costUsd,
+  ];
+  for (const value of candidates) {
+    const n = numOrNull(value);
+    if (n != null) return n;
+  }
+  return null;
+}
+
+function isClaudeAssistant(row) {
+  if (!row || typeof row !== 'object') return false;
+  if (row.type === 'assistant') return true;
+  if (row.message && row.message.role === 'assistant') return true;
+  return false;
+}
+
+function collectClaude({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
+  const home = homedir || env.HOME || osHomedir();
+  const encoded = encodeClaudeProjectDir(cwd);
+  const projectDir = join(home, '.claude', 'projects', encoded);
+  const sources = [];
+  if (!existsSync(projectDir)) {
+    notes.push('claude: project folder missing');
+    return sources;
+  }
+  let files;
+  try {
+    files = readdirSync(projectDir).filter((name) => name.endsWith('.jsonl'));
+  } catch {
+    notes.push('claude: cannot read project folder');
+    return sources;
+  }
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(join(projectDir, file), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let row;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isClaudeAssistant(row)) continue;
+      const message = row.message || {};
+      const usage = message.usage;
+      if (!usage || typeof usage !== 'object') continue;
+      const id = message.id;
+      if (id == null || id === '') continue;
+      if (existing.has(String(id))) continue;
+      if (row.cwd !== cwd) continue;
+      if (!inWindow(row.timestamp, windowStart, windowEnd)) continue;
+      sources.push(sourceRecord({
+        id,
+        platform: 'claude',
+        model: message.model,
+        inputTokens: claudeInputTokens(usage),
+        outputTokens: usage.output_tokens ?? usage.outputTokens,
+        costUsd: claudeCostUsd(row, usage),
+        ampCredits: null,
+        at: row.timestamp,
+      }));
+    }
+  }
+  return sources;
+}
+
+function ampRoot(env, homedir) {
+  if (env.AMP_DATA_DIR && String(env.AMP_DATA_DIR).trim()) return String(env.AMP_DATA_DIR).trim();
+  if (env.XDG_DATA_HOME && String(env.XDG_DATA_HOME).trim()) {
+    return join(String(env.XDG_DATA_HOME).trim(), 'amp');
+  }
+  return join(homedir || env.HOME || osHomedir(), '.local', 'share', 'amp');
+}
+
+function ampTreesMatch(thread, cwd) {
+  const trees = thread && thread.env && thread.env.initial && thread.env.initial.trees;
+  if (!Array.isArray(trees) || trees.length === 0) return false;
+  return trees.some((tree) => tree && stripFileUri(tree.uri) === cwd);
+}
+
+function ampMessages(thread) {
+  const out = [];
+  if (Array.isArray(thread.messages)) out.push(...thread.messages);
+  else if (thread.messages && typeof thread.messages === 'object') out.push(...Object.values(thread.messages));
+  if (Array.isArray(thread.turns)) out.push(...thread.turns);
+  return out;
+}
+
+function ampUsage(message) {
+  if (message && message.usage && typeof message.usage === 'object') return message.usage;
+  if (message && message.message && message.message.usage && typeof message.message.usage === 'object') {
+    return message.message.usage;
+  }
+  return null;
+}
+
+function ampId(message) {
+  return (
+    (message && (message.messageId || message.toMessageId))
+    || (message && message.message && (message.message.messageId || message.message.toMessageId || message.message.id))
+    || null
+  );
+}
+
+function ampInputTokens(usage) {
+  if (usage.totalInputTokens != null) return numOrNull(usage.totalInputTokens);
+  let has = false;
+  let sum = 0;
+  if (usage.inputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.inputTokens) ?? 0;
+  }
+  if (usage.cacheCreationInputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.cacheCreationInputTokens) ?? 0;
+  }
+  if (usage.cacheReadInputTokens != null) {
+    has = true;
+    sum += numOrNull(usage.cacheReadInputTokens) ?? 0;
+  }
+  return has ? sum : null;
+}
+
+function collectAmp({ cwd, windowStart, windowEnd, existing, env, homedir, notes }) {
+  const root = ampRoot(env, homedir);
+  const threadsDir = join(root, 'threads');
+  const sources = [];
+  if (!existsSync(threadsDir)) {
+    notes.push('amp: threads folder missing');
+    return sources;
+  }
+  let files;
+  try {
+    files = readdirSync(threadsDir).filter((name) => name.endsWith('.json'));
+  } catch {
+    notes.push('amp: cannot read threads');
+    return sources;
+  }
+  for (const file of files) {
+    let thread;
+    try {
+      thread = JSON.parse(readFileSync(join(threadsDir, file), 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (!thread || typeof thread !== 'object') continue;
+    if (!ampTreesMatch(thread, cwd)) 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,
+      }));
+    }
+  }
+  return sources;
+}
+
+export const CURSOR_USAGE_FILE_REL = join('.agents', 'spend', 'cursor-usage.jsonl');
+
+function collectCursor({ cwd, windowStart, windowEnd, existing, notes }) {
+  const filePath = join(cwd, CURSOR_USAGE_FILE_REL);
+  if (!existsSync(filePath)) {
+    notes.push('cursor: usage file missing (spend hook not installed or no turns recorded yet)');
+    return [];
+  }
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf-8');
+  } catch {
+    notes.push('cursor: cannot read usage file');
+    return [];
+  }
+  // stop / afterAgentResponse / loop follow-ups may write the same generation_id
+  // several times with cumulative turn totals; keep the largest record per id.
+  const bestById = new Map();
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!row || typeof row !== 'object') continue;
+    const id = row.id == null || row.id === '' ? null : String(row.id);
+    if (!id) continue;
+    if (existing.has(id)) continue;
+    if (!inWindow(row.at, windowStart, windowEnd)) continue;
+    const inputTokens = numOrNull(row.inputTokens);
+    const outputTokens = numOrNull(row.outputTokens);
+    if (inputTokens == null && outputTokens == null) continue;
+    const record = sourceRecord({
+      id,
+      platform: 'cursor',
+      model: row.model || row.modelId,
+      inputTokens,
+      outputTokens,
+      costUsd: null,
+      ampCredits: null,
+      at: row.at,
+    });
+    const previous = bestById.get(id);
+    if (!previous || (record.totalTokens ?? 0) >= (previous.totalTokens ?? 0)) {
+      bestById.set(id, record);
+    }
+  }
+  return [...bestById.values()];
+}
+
+function aggregate(sources) {
+  const byPlatform = emptyByPlatform();
+  const byModel = new Map();
+  for (const src of sources) {
+    const platform = PLATFORMS.includes(src.platform) ? src.platform : null;
+    if (platform) {
+      const bucket = byPlatform[platform];
+      bucket.inputTokens = addNullable(bucket.inputTokens, src.inputTokens);
+      bucket.outputTokens = addNullable(bucket.outputTokens, src.outputTokens);
+      bucket.totalTokens = addNullable(bucket.totalTokens, src.totalTokens);
+      bucket.costUsd = addNullable(bucket.costUsd, src.costUsd);
+      bucket.ampCredits = addNullable(bucket.ampCredits, src.ampCredits);
+      if (platform === 'claude') bucket.source = 'claude-jsonl';
+      else if (platform === 'amp') bucket.source = 'amp-thread';
+      else bucket.source = 'cursor-hook';
+    }
+    const model = src.model;
+    if (model) {
+      const key = `${model}::${src.platform || ''}`;
+      const row = byModel.get(key) || {
+        model,
+        platform: src.platform || null,
+        inputTokens: null,
+        outputTokens: null,
+        totalTokens: null,
+        costUsd: null,
+        ampCredits: 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);
+      byModel.set(key, row);
+    }
+  }
+  return { byPlatform, byModel: [...byModel.values()] };
+}
+
+export function collectSpend(options = {}) {
+  const env = options.env || process.env;
+  const cwd = options.cwd != null ? options.cwd : process.cwd();
+  const homedir = options.homedir || env.HOME || osHomedir();
+  const existing = new Set(
+    Array.isArray(options.existingSourceIds)
+      ? options.existingSourceIds
+      : options.existingSourceIds instanceof Set
+        ? [...options.existingSourceIds]
+        : [],
+  );
+  const windowStart = options.windowStart;
+  const windowEnd = options.windowEnd;
+  const notes = [];
+  const ctx = { cwd, windowStart, windowEnd, existing, env, homedir, notes };
+  let sources = [];
+  try {
+    sources = sources.concat(collectClaude(ctx));
+  } catch {
+    notes.push('claude: adapter 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');
+  }
+  const { byPlatform, byModel } = aggregate(sources);
+  return { sources, byPlatform, byModel, notes };
+}

package/package.json

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

@@ -5,15 +5,15 @@ category: Workflow
 description: Archive a completed change via the agent-orchestrator-kit CLI
 ---
 
-Session Start / Session Exit: follow the protocol in `.agents/rules/session-handoff.mdc`. Announce the Archiver role.
+Session Start / Exit: `.agents/rules/session-handoff.mdc`. Announce Archiver.
 
-Archive is fully deterministic — one CLI call, no phase subagents.
+Archive is one CLI call, no phase subagents.
 
 **Steps**
 
-1. **Resolve the change name.** Use the name after `/opsx:archive`. If omitted or ambiguous, run `npx openspec list --json` and use the **AskUserQuestion tool** to let the user pick an active change. Never guess.
+1. **Resolve the name.** After `/opsx:archive`, or `npx openspec list --json` + AskUserQuestion. Never guess.
 
-2. **Decide on delta-spec sync.** If the change has delta specs, ask the user: merge them into main specs (`--sync`, recommended) or archive without merging (`--no-sync --force`).
+2. **Sync decision.** If delta specs exist, ask: merge (`--sync`) or skip (`--no-sync --force`).
 
 3. **Run the CLI:**
 
@@ -21,8 +21,8 @@ Archive is fully deterministic — one CLI call, no phase subagents.
    npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
    ```
 
-   The CLI checks gates (review APPROVE, all tasks `[x]`, no existing target), merges delta specs on `--sync`, moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, runs `npx openspec validate --all --strict` with full rollback on failure, and writes the final `handoff.md` (`next_command: none`) plus memory upsert.
+   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 runs collect unless `--no-collect`; if `spend.costUsd` is `null` — stderr warning, not a gate.
 
-4. **Show the CLI stdout as-is.** On exit ≠ 0, report the failed gate from stderr and stop — do not merge or move anything manually.
+4. **Show stdout as-is.** On exit ≠ 0, report the gate from stderr and stop — no manual merge/move.
 
-The pipeline ends here: no next-thread prompt is required after a successful archive.
+No next-thread prompt after a successful archive.

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

@@ -20,7 +20,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.
-2. `npx agent-orchestrator-kit handoff <name>` — require exit 0 (appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md`, upserts absolute-path Memory JSON, prints the expanded prompt on stdout). `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).
+2. `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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. 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. Spawn `session-handoff` in persist mode ONLY if step 2 failed (Amp: isolated `subagent-session-handoff`). Fallback, never routine.
 4. Memory MCP is an optional mirror: if tools are available, update `Change:<name>`, `Handoff:<name>`, `Decision:*` in one call; unavailability never blocks closing.
 5. 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/skills/agent-orchestration/SKILL.md

@@ -146,7 +146,7 @@ Archive is one deterministic CLI call — `npx agent-orchestrator-kit archive <n
 
 **End of each session (HARD STOP — you are NOT done):**
 1. Write `openspec/changes/<name>/handoff.md` in the parent using the template below.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
+2. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. The same command 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. The CLI appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (the git canon), upserts Memory JSON with an absolute path (`Decision:*` is a file→Memory mirror only), and prints the expanded self-contained prompt on stdout. Spawn `session-handoff` in persist mode ONLY if this CLI step failed.
 3. If Memory MCP tools are available, mirror `Change:<name>`, `Handoff:<name>`, and new `Decision:<topic>` entities in one call — optional; its absence never blocks closing.
 4. Paste the CLI stdout as one fenced next-session prompt. First line is `/opsx:<next> <name>`; body uses `project.agent_language`; keep Done/Decisions/Blocked/spawn/HARD STOP complete. No banner. Do not emit a thin “read Memory” stub.
 5. Do not start the next phase in this chat. If apply, include build/lint status in the persisted Done section.
@@ -218,7 +218,7 @@ The Prompt section is overwritten by `npx agent-orchestrator-kit handoff <name>`
 
 Before specialist work, the parent MUST restore context in order: honor the pasted `/opsx:*` command; run `npx agent-orchestrator-kit handoff --restore` (the CLI briefing is canonical — no separate Memory MCP read step); if the CLI failed, read `openspec/changes/<name>/handoff.md`; spawn `session-handoff` in restore mode ONLY when both failed. Missing Memory MCP never blocks a session. With one active change, free-form “continue” uses `Handoff.next_command` instead of asking for the phase. Amp spawns any needed subagent as an isolated `subagent-*` skill.
 
-Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name>` (exit 0) — this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. Never write Memory back into `decisions.md`. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
+Before declaring a session closed, the parent MUST, in order: (1) write `openspec/changes/<name>/handoff.md` itself, (2) run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` (exit 0) — NEVER pass a Closed role or subagent name as `--model`; persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl); the parent SHOULD still pass `--model` and MUST NOT guess tokens; spend flags override session totals only; optional `--platform`; the same CLI works in Cursor, Claude Code, and Amp and MUST NOT require Cursor SDK, Claude `/cost`, or Amp billing as a required step; this CLI appends `decisions.md` and mirrors `Decision:*` file→Memory; spawn `session-handoff` persist ONLY if this CLI step failed, (3) paste the CLI stdout prompt whose first line is `/opsx:<next> <name>`. Memory MCP mirroring is an optional single call. Never write Memory back into `decisions.md`. The prompt has no `NEXT_SESSION_PROMPT` label, uses `project.agent_language`, and MUST be self-contained (Done, Decisions, Blocked, attach, spawn, HARD STOP) so the next thread can run if Memory MCP is ignored. Never start the next phase in the current chat. Write session artifacts only to git-tracked paths (never `/tmp`, never gitignored caches). If runtime is cloud: after persist, commit → push → `npx agent-orchestrator-kit handoff <name> --cloud-check` with exit 0; closing without that is an incomplete handoff.
 
 | Entity | Required fields |
 |--------|-----------------|

package/templates/.agents/subagents/session-handoff.md

@@ -22,7 +22,7 @@ Use when the parent's restore failed (CLI restore and handoff.md both unavailabl
 Use when the parent's persist failed (`npx agent-orchestrator-kit handoff <name>` did not exit 0). A session is not closed until persist succeeds.
 
 1. Write or update `openspec/changes/<name>/handoff.md` with every required section: Closed role, Change, Done, Decisions, Blocked, Next command, Next role, Attach, Subagents to spawn, Constraints, Runtime.
-2. Run `npx agent-orchestrator-kit handoff <name>` and require exit 0. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
+2. Run `npx agent-orchestrator-kit handoff <name> --model <llm-product-id>` and require exit 0. `--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`. Persist auto-collects local usage from Claude JSONL, Amp threads, and the Cursor spend hook file (.agents/spend/cursor-usage.jsonl). 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. Optional `--platform cursor|claude|amp` or `AOK_PLATFORM`. The same command 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. This appends non-empty Decisions into append-only `openspec/changes/<name>/decisions.md` (git canon), upserts `.cursor/memory.json` using an absolute path (`Decision:*` mirrors that file, never the reverse), and prints the expanded next-session prompt on stdout. Cloud sessions pass `--runtime cloud` (or `AOK_RUNTIME` / `AOK_AGENT_ID`).
 3. If Memory MCP tools are available, also create/update `Change:<name>`, `Handoff:<name>`, and each `Decision:<topic>` to match `decisions.md`. MCP failure is not a blocker after the CLI succeeds.
 4. Put the CLI stdout prompt (first line `/opsx:…`) into **Next prompt** unchanged. Do not shorten it. Do not add a banner.
 5. If runtime is cloud: after persist, commit and push `openspec/changes/<name>/`, then `npx agent-orchestrator-kit handoff <name> --cloud-check` (exit 0 required). Closing without this is an incomplete handoff. The CLI never runs `git commit` / `git push`.

package/templates/scripts/cursor-spend-hook.cjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Cursor hook (stop / subagentStop): appends per-turn token usage from the hook
+// payload to .agents/spend/cursor-usage.jsonl so `agent-orchestrator-kit handoff`
+// can collect real Cursor spend offline. Silent and fail-open by design: a hook
+// must never block the agent loop, so every failure path exits 0 with no output.
+'use strict';
+
+const { existsSync, mkdirSync, appendFileSync } = require('fs');
+const { join } = require('path');
+
+function numOrNull(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function resolveBaseDir(payload) {
+  const cwd = process.cwd();
+  if (existsSync(join(cwd, '.agents'))) return cwd;
+  const roots = Array.isArray(payload.workspace_roots) ? payload.workspace_roots : [];
+  for (const root of roots) {
+    if (root && existsSync(join(String(root), '.agents'))) return String(root);
+  }
+  return cwd;
+}
+
+function main(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== 'object') return;
+
+  const inputTokens = numOrNull(payload.input_tokens);
+  const outputTokens = numOrNull(payload.output_tokens);
+  // Token fields are optional in Cursor hook payloads. No numbers -> no record;
+  // never write zeros for turns that did not report usage.
+  if (inputTokens == null && outputTokens == null) return;
+
+  const generationId = payload.generation_id ? String(payload.generation_id) : '';
+  const conversationId = payload.conversation_id ? String(payload.conversation_id) : '';
+  const id = generationId || (conversationId ? `${conversationId}:${Date.now()}` : `cursor:${Date.now()}`);
+
+  const record = {
+    id,
+    event: payload.hook_event_name ? String(payload.hook_event_name) : null,
+    conversationId: conversationId || null,
+    model: payload.model ? String(payload.model) : null,
+    modelId: payload.model_id ? String(payload.model_id) : null,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens: numOrNull(payload.cache_read_tokens),
+    cacheWriteTokens: numOrNull(payload.cache_write_tokens),
+    at: new Date().toISOString(),
+  };
+
+  const spendDir = join(resolveBaseDir(payload), '.agents', 'spend');
+  mkdirSync(spendDir, { recursive: true });
+  appendFileSync(join(spendDir, 'cursor-usage.jsonl'), `${JSON.stringify(record)}\n`);
+}
+
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  try {
+    main(input);
+  } catch {}
+  process.exit(0);
+});
+process.stdin.on('error', () => process.exit(0));