@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/skills/zaip-skill-module-scaffold/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Module Scaffold"
+  short_description: "Create a safe minimal module shell"
+  default_prompt: "Use $zaip-skill-module-scaffold to create a minimal module for this capability."

package/templates/.agents/skills/zaip-skill-module-scaffold/references/scaffold-contract.md

@@ -0,0 +1,9 @@
+# Scaffold grammar and output
+
+Run `node .agents/skills/zaip-skill-module-scaffold/scripts/scaffold.mjs <module-name> [--root <directory>] [--dry-run]`.
+
+The module name is lowercase kebab-case. `--root` defaults to the current directory; `--dry-run` writes nothing. Repeated flags are rejected. The helper requires stack id `zaip-aios-stack`, language `typescript`, and a safe relative `stack.layout.modules` path. It emits schema version, stack id, relative module path, dry-run state, and sorted `created` and `unchanged` paths.
+
+The generated shell has a domain type, an application factory, a public index, and a co-located TypeScript behavior check. It deliberately has no database, Hono, Kysely, Supabase, Redis, or BullMQ import.
+
+The consumer must provide TypeScript and `@types/node`. Compile with its project `tsconfig` or a portable temporary tsconfig that sets Node types and emits JavaScript, then run `node --test <emitted>/application.test.js`. This generated check is Node-test compatible; it does not promise automatic Vitest discovery.

package/templates/.agents/skills/zaip-skill-module-scaffold/scripts/helpers.test.mjs

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const skillRoot = resolve(import.meta.dirname, "..", "..");
+const root = resolve(skillRoot, "..", "..");
+const scaffold = resolve(skillRoot, "zaip-skill-module-scaffold/scripts/scaffold.mjs");
+const inventory = resolve(skillRoot, "zaip-skill-dev-environment/scripts/inventory.mjs");
+const fixture = resolve(skillRoot, "zaip-skill-test-data/scripts/generate.mjs");
+
+test("helpers are deterministic and avoid local secret values", async (context) => {
+  const directory = await mkdtemp(join(os.tmpdir(), "zaip-skill-helper-"));
+  context.after(() => rm(directory, { recursive: true, force: true }));
+  await mkdir(join(directory, ".agents", "config"), { recursive: true });
+  await writeFile(
+    join(directory, ".agents", "config", "project.yaml"),
+    "project:\n  id: consumer-project\nstack:\n  id: zaip-aios-stack\n  language: typescript\n  layout:\n    modules: features\n",
+  );
+  await writeFile(
+    join(directory, "package.json"),
+    JSON.stringify({ scripts: { test: "secret-command-value" } }),
+  );
+  await writeFile(join(directory, ".env"), "VISIBLE_NAME=private-value\n");
+  await writeFile(join(directory, ".env.example"), "VISIBLE_NAME=\nMISSING_NAME=\n");
+
+  const inventoryOutput = JSON.parse((await run(process.execPath, [inventory, directory])).stdout);
+  assert.deepEqual(inventoryOutput.package_scripts, ["test"]);
+  assert.deepEqual(inventoryOutput.environment_names[".env"], ["VISIBLE_NAME"]);
+  assert.equal(JSON.stringify(inventoryOutput).includes("private-value"), false);
+  assert.equal(JSON.stringify(inventoryOutput).includes("secret-command-value"), false);
+  assert.deepEqual(inventoryOutput.missing_required_environment_names, ["MISSING_NAME"]);
+  await assert.rejects(run(process.execPath, [inventory, directory, "extra"]), /Usage/);
+
+  const first = JSON.parse(
+    (await run(process.execPath, [scaffold, "orders", "--root", directory])).stdout,
+  );
+  assert.deepEqual(first.created, [
+    "src/application.test.ts",
+    "src/application.ts",
+    "src/domain.ts",
+    "src/index.ts",
+  ]);
+  const second = JSON.parse(
+    (await run(process.execPath, [scaffold, "orders", "--root", directory])).stdout,
+  );
+  assert.deepEqual(second.created, []);
+  await assert.rejects(
+    run(process.execPath, [scaffold, "con", "--root", directory]),
+    /reserved name/,
+  );
+  await assert.rejects(
+    run(process.execPath, [scaffold, "../escape", "--root", directory]),
+    /module-name/,
+  );
+  await assert.rejects(
+    run(process.execPath, [scaffold, "a--b", "--root", directory]),
+    /module-name/,
+  );
+  await assert.rejects(
+    run(process.execPath, [scaffold, "another", "--root", ".", "--root", directory]),
+    /Usage/,
+  );
+  const misleading = await mkdtemp(join(os.tmpdir(), "zaip-scaffold-layout-"));
+  context.after(() => rm(misleading, { recursive: true, force: true }));
+  await mkdir(join(misleading, ".agents", "config"), { recursive: true });
+  await writeFile(
+    join(misleading, ".agents", "config", "project.yaml"),
+    "project:\n  id: consumer\nstack:\n  id: zaip-aios-stack\n  language: typescript\n  layout:\n    frontend: apps/frontend\n  overrides:\n    modules: wrong-owned-tree\n",
+  );
+  await assert.rejects(
+    run(process.execPath, [scaffold, "orders", "--root", misleading]),
+    /stack\.layout\.modules/,
+  );
+  await writeFile(
+    join(misleading, ".agents", "config", "project.yaml"),
+    "stack:\n  id: zaip-aios-stack\n  language: typescript\n  layout:\n    modules: modules\nstack:\n  id: zaip-aios-stack\n",
+  );
+  await assert.rejects(
+    run(process.execPath, [scaffold, "orders", "--root", misleading]),
+    /duplicate top-level stack/,
+  );
+  await writeFile(join(directory, "features", "orders", "src", "domain.ts"), "changed\n");
+  await assert.rejects(
+    run(process.execPath, [scaffold, "orders", "--root", directory]),
+    /divergent/,
+  );
+
+  const output = join(directory, "fixture.json");
+  const generated = JSON.parse(
+    (await run(process.execPath, [fixture, output, "--seed", "same"])).stdout,
+  ).fixture;
+  const repeated = JSON.parse(
+    (await run(process.execPath, [fixture, output, "--seed", "same"])).stdout,
+  ).fixture;
+  assert.deepEqual(generated, repeated);
+  assert.equal((await readFile(output, "utf8")).includes("same"), true);
+  await writeFile(output, "{}\n");
+  await assert.rejects(run(process.execPath, [fixture, output, "--seed", "same"]), /divergent/);
+  await assert.rejects(
+    run(process.execPath, [fixture, join(directory, "other.json"), "extra"]),
+    /Usage/,
+  );
+  const outside = await mkdtemp(join(os.tmpdir(), "zaip-test-data-outside-"));
+  context.after(() => rm(outside, { recursive: true, force: true }));
+  const linked = join(directory, "linked-output");
+  try {
+    await symlink(outside, linked, process.platform === "win32" ? "junction" : "dir");
+  } catch (error) {
+    if (error.code !== "EPERM") throw error;
+    return;
+  }
+  await assert.rejects(
+    run(process.execPath, [fixture, join(linked, "fixture.json")]),
+    /symbolic link or junction/,
+  );
+});

package/templates/.agents/skills/zaip-skill-module-scaffold/scripts/scaffold.mjs

@@ -0,0 +1,169 @@
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+const [name, ...args] = process.argv.slice(2);
+let root = ".";
+let rootSeen = false;
+let dryRun = false;
+for (let index = 0; index < args.length; index += 1) {
+  if (args[index] === "--root" && typeof args[index + 1] === "string" && !rootSeen) {
+    rootSeen = true;
+    root = args[++index];
+    continue;
+  }
+  if (args[index] === "--dry-run" && !dryRun) {
+    dryRun = true;
+    continue;
+  }
+  throw new Error("Usage: scaffold.mjs <module-name> [--root <directory>] [--dry-run]");
+}
+if (!/^[a-z](?:[a-z0-9]|-(?=[a-z0-9]))*$/.test(name ?? "") || reserved(name))
+  throw new Error("module-name must be lowercase kebab-case and not a Windows reserved name");
+const rootPath = resolve(root);
+const configPath = resolve(rootPath, ".agents/config/project.yaml");
+const config = await readFile(configPath, "utf8").catch(() => {
+  throw new Error("missing .agents/config/project.yaml");
+});
+const stack = parseStackSubset(config);
+const stackId = stack.id;
+const language = stack.language;
+if (stackId !== "zaip-aios-stack" || language !== "typescript")
+  throw new Error("missing or unsupported stack profile");
+const modules = stack.modules;
+if (!modules || !safeRelative(modules))
+  throw new Error("missing or unsupported stack.layout.modules path");
+const modulesRoot = resolve(rootPath, modules);
+if (!inside(rootPath, modulesRoot)) throw new Error("modules path escapes root");
+const canonicalRoot = await realpath(rootPath);
+await ensureNoEscape(canonicalRoot, modulesRoot);
+const target = resolve(modulesRoot, name);
+if (!inside(modulesRoot, target)) throw new Error("module target escapes modules path");
+const collision = await caseCollision(modulesRoot, name);
+if (collision) throw new Error("case-insensitive module collision");
+await ensureNoEscape(canonicalRoot, target);
+const files = generated(name);
+const changes = [];
+let existingCount = 0;
+for (const [path, content] of Object.entries(files)) {
+  const absolute = resolve(target, path);
+  await ensureNoEscape(canonicalRoot, absolute);
+  const existing = await readFile(absolute, "utf8").catch(() => null);
+  if (existing === null) changes.push(path);
+  else {
+    existingCount += 1;
+    if (existing !== content) throw new Error(`refusing divergent or partial module file: ${path}`);
+  }
+}
+if (existingCount > 0 && changes.length > 0)
+  throw new Error("refusing divergent or partial module");
+if (!dryRun)
+  for (const [path, content] of Object.entries(files)) {
+    const absolute = resolve(target, path);
+    await mkdir(dirname(absolute), { recursive: true });
+    try {
+      await writeFile(absolute, content, { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      if (error.code !== "EEXIST" || (await readFile(absolute, "utf8")) !== content) throw error;
+    }
+  }
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      schema_version: 1,
+      stack_id: stackId,
+      module: `${modules}/${name}`,
+      dry_run: dryRun,
+      created: changes.sort(),
+      unchanged: Object.keys(files)
+        .filter((path) => !changes.includes(path))
+        .sort(),
+    },
+    null,
+    2,
+  )}\n`,
+);
+function generated(module) {
+  const symbol = module
+    .split("-")
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+  return {
+    "src/domain.ts": `export type ${symbol}Id = string;\nexport interface ${symbol} { id: ${symbol}Id; }\n`,
+    "src/application.ts": `import type { ${symbol} } from "./domain.js";\nexport function create${symbol}(id: string): ${symbol} { return { id }; }\n`,
+    "src/index.ts": `export * from "./application.js";\nexport * from "./domain.js";\n`,
+    "src/application.test.ts": `import assert from "node:assert/strict";\nimport test from "node:test";\nimport { create${symbol} } from "./application.js";\ntest("${module} factory", () => assert.equal(create${symbol}("id").id, "id"));\n`,
+  };
+}
+function reserved(value) {
+  return /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i.test(value);
+}
+function safeRelative(value) {
+  return (
+    !isAbsolute(value) && !value.split(/[\\/]+/).some((part) => part === ".." || part.length === 0)
+  );
+}
+function inside(parent, child) {
+  const value = relative(parent, child);
+  return value === "" || (!value.startsWith(`..${sep}`) && value !== "..");
+}
+async function ensureNoEscape(canonicalRoot, path) {
+  let current = canonicalRoot;
+  for (const part of relative(canonicalRoot, path).split(/[\\/]+/)) {
+    if (!part) continue;
+    current = resolve(current, part);
+    const stat = await lstat(current).catch(() => null);
+    if (!stat) continue;
+    const resolved = await realpath(current);
+    if (!inside(canonicalRoot, resolved))
+      throw new Error("modules path resolves through a junction outside root");
+  }
+}
+async function caseCollision(directory, candidate) {
+  const { readdir } = await import("node:fs/promises");
+  const entries = await readdir(directory).catch(() => []);
+  return entries.some(
+    (entry) => entry.toLowerCase() === candidate.toLowerCase() && entry !== candidate,
+  );
+}
+function parseStackSubset(source) {
+  const lines = source.replaceAll("\r\n", "\n").split("\n");
+  if (lines.filter((line) => /^stack:\s*(?:#.*)?$/.test(line)).length > 1)
+    throw new Error("duplicate top-level stack");
+  let inStack = false;
+  let inLayout = false;
+  const values = {};
+  for (const line of lines) {
+    if (/\t|[&*][A-Za-z_]/.test(line) && inStack)
+      throw new Error("unsupported YAML construct in stack mapping");
+    if (!inStack) {
+      if (/^stack:\s*(?:#.*)?$/.test(line)) {
+        inStack = true;
+        continue;
+      }
+      continue;
+    }
+    if (/^[^ \t#]/.test(line)) break;
+    if (/^ {2}layout:\s*(?:#.*)?$/.test(line)) {
+      if (inLayout) throw new Error("duplicate stack.layout");
+      inLayout = true;
+      continue;
+    }
+    const direct = line.match(/^ {2}(id|language):\s*([^#\s]+)\s*(?:#.*)?$/);
+    if (direct) {
+      inLayout = false;
+      if (values[direct[1]]) throw new Error(`duplicate stack.${direct[1]}`);
+      values[direct[1]] = direct[2];
+      continue;
+    }
+    if (/^ {2}[A-Za-z_][A-Za-z0-9_-]*:/.test(line)) {
+      inLayout = false;
+      continue;
+    }
+    const nested = line.match(/^ {4}modules:\s*([^#\s]+)\s*(?:#.*)?$/);
+    if (nested && inLayout) {
+      if (values.modules) throw new Error("duplicate stack.layout.modules");
+      values.modules = nested[1];
+    }
+  }
+  return values;
+}

package/templates/.agents/skills/zaip-skill-move-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-move-prd
-description: Explicitly move, cancel, execute, or deliver a ZAIP PRD while keeping child SPECs, Tasks, Changes, and Executions lifecycle-consistent. Use only when a user asks to move a PRD between dashboard columns, execute it, cancel or finalize it, or repair descendants left behind by a PRD status change.
+description: Move, cancel, execute, or deliver a ZAIP PRD only on explicit lifecycle intent; preserve descendant consistency.
 ---
 
 # Mover PRD com descendentes
@@ -35,6 +35,8 @@ Use apenas comandos canônicos ZAIP. Não edite status diretamente no frontmatte
 
 ## Verificar
 
+Na continuação de um PRD preparado, reutilize a Execution de `plan_ref`/PreparedPlan. Para `blocked` ou `paused`, inspecione a causa e use a retomada canônica autorizada antes da captura; não repita `prd execute` contra um macro já materializado. `conversation start --intent continue --prd ID --execution EXEC` deve resolver a mesma Execution e fase `execution`, rejeitando divergências antes de escrever. Para colaboração nativa Codex, siga a seção de DAG nativa da skill de execução; `native-next` prepara envelopes e não substitui o spawn/capture observado nem os gates de entrega.
+
 1. Leia novamente o PRD e liste SPECs com `spec list --prd <PRD-ID> --json`.
 2. Após `prepare`, confirme que PRD e SPECs continuam `draft`; após `ready`, confirme que apenas as selecionadas ficaram `ready` e que Execution, Changes e Tasks permanecem `planned`.
 3. Confirme no resultado do cancelamento os arrays `cascade.specs`, `cascade.tasks`, `cascade.changes` e `cascade.executions`.

package/templates/.agents/skills/zaip-skill-move-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-move-spec
-description: Explicitly move, cancel, execute, or deliver a ZAIP SPEC while keeping descendant Tasks, Changes, and Executions lifecycle-consistent. Use only when a user asks to move a SPEC between dashboard columns, execute it, cancel or finalize it, or repair Tasks left behind by a SPEC status change.
+description: Move, cancel, execute, or deliver a ZAIP SPEC only on explicit lifecycle intent; preserve descendant consistency.
 ---
 
 # Mover SPEC com descendentes

package/templates/.agents/skills/zaip-skill-performance-engineering/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-performance-engineering
+description: Measure and improve application latency, throughput, queries, queues, and resource use under stated conditions.
+---
+
+# Engineer performance
+
+Use for a demonstrated latency, capacity, query, memory, or queue throughput concern.
+
+1. Define workload, data shape, environment, target metric, baseline, and success threshold before tuning.
+2. Profile the likely bottleneck across browser, API, database, cache, worker, and network boundaries before changing code.
+3. Change one justified cause at a time and preserve correctness, tenant isolation, and failure handling.
+4. Compare before and after under equivalent conditions using k6, autocannon, or a project-supported tool where appropriate.
+5. Report confidence limits, saturation behavior, and unmeasured production differences.

package/templates/.agents/skills/zaip-skill-performance-engineering/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Performance Engineering"
+  short_description: "Measure and improve runtime performance safely"
+  default_prompt: "Use $zaip-skill-performance-engineering to measure and improve this performance concern."

package/templates/.agents/skills/zaip-skill-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-prd
-description: Create, refine, prepare, and analyze complete ZAIP PRDs with technical SPECs and Task blueprints. Use for explicit requests to create a PRD or to think, develop, improve, or refine one; distinguish conversation from materialized creation and preserve draft until explicit ready or execution intent.
+description: Create, refine, prepare, or analyze a ZAIP PRD on explicit PRD work; keep draft until explicit ready or execute intent.
 ---
 
 # Trabalhar com PRDs
@@ -50,6 +50,8 @@ Durante essa etapa, a Execution universal `interaction` e sua Run raiz continuam
 
 ## Handoff e analyze
 
+Ao receber “execute esse PRD” em outro turno, reutilize o ID canônico e delegue à skill de execução a captura inicial como continuação desse PRD. Não repita o intake `conversation --definition prd,spec` da autoria anterior e não recrie o pacote. Se o documento citado existir apenas como rascunho local, informe essa diferença: a existência de um arquivo de planejamento não comprova PRD canônico nem Run de delivery.
+
 1. Pare em Definição após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-prd`: `prd ready` deixa PRD/SPECs selecionadas em `ready` e materializa a DAG sem executá-la; cada Task materializada `planned` e nunca iniciada aparece em Pronto para Executar, mesmo vinculada a SPEC. Somente após pedido explícito de execução, delegue a persistência da continuação, ativação e orquestração para `$zaip-skill-execution`.
 2. Na análise, mostre visão macro por PRD: SPECs, Tasks, Executions, Runs, outcomes, AC/evidência, retrabalho, tokens e custo por fase/total.
 

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs

@@ -409,6 +409,7 @@ if (apply && deduplicate) {
       tokens: {
         input: null,
         cached_input: null,
+        cache_write_input: null,
         output: null,
         reasoning: null,
         total: null,

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.mjs

@@ -102,6 +102,9 @@ export function usageView(record) {
       reasoning: tokens[3] ?? null,
       total: tokens[4] ?? null,
       source: tokens[5] ?? "unavailable",
+      // Appended to the compact tuple to retain compatibility with historical
+      // records that have only the first six fields.
+      cache_write_input: tokens[6] ?? null,
     },
     source_segment_key: record[12] ?? null,
     supersedes_event_id: record[13] ?? null,
@@ -324,6 +327,7 @@ export function exactRemeasurementSegment(
             ? {
                 input: last.input_tokens,
                 cached_input: last.cached_input_tokens,
+                cache_write_input: last.cache_write_input_tokens ?? null,
                 output: last.output_tokens,
                 reasoning: last.reasoning_output_tokens,
                 total: last.total_tokens,
@@ -331,8 +335,8 @@ export function exactRemeasurementSegment(
             : null;
           const same = (candidate) =>
             candidate !== null &&
-            ["input", "cached_input", "output", "reasoning", "total"].every(
-              (key) => candidate[key] === sourceTokens[key],
+            ["input", "cached_input", "cache_write_input", "output", "reasoning", "total"].every(
+              (key) => candidate[key] === (sourceTokens[key] ?? null),
             );
           return same(tokens) || same(lastTokens);
         })
@@ -494,6 +498,7 @@ export function sameTokenSnapshot(left, right) {
     left !== null &&
     left.input_tokens === right.input_tokens &&
     left.cached_input_tokens === right.cached_input_tokens &&
+    left.cache_write_input_tokens === right.cache_write_input_tokens &&
     left.output_tokens === right.output_tokens &&
     left.reasoning_output_tokens === right.reasoning_output_tokens &&
     left.total_tokens === right.total_tokens
@@ -522,6 +527,7 @@ export function aggregate(segment) {
   return {
     input,
     cached_input: completeSum("cached_input_tokens"),
+    cache_write_input: completeSum("cache_write_input_tokens"),
     output,
     reasoning: completeSum("reasoning_output_tokens"),
     total: reportedTotal ?? (input !== null && output !== null ? input + output : null),
@@ -534,6 +540,7 @@ function tokenSnapshot(value) {
   return {
     input_tokens: finite("input_tokens"),
     cached_input_tokens: finite("cached_input_tokens"),
+    cache_write_input_tokens: finite("cache_write_input_tokens"),
     output_tokens: finite("output_tokens"),
     reasoning_output_tokens: finite("reasoning_output_tokens"),
     total_tokens: finite("total_tokens"),
@@ -551,6 +558,7 @@ export function cumulativeSnapshotDelta(previous, current) {
   return {
     input_tokens: delta("input_tokens"),
     cached_input_tokens: delta("cached_input_tokens"),
+    cache_write_input_tokens: delta("cache_write_input_tokens"),
     output_tokens: delta("output_tokens"),
     reasoning_output_tokens: delta("reasoning_output_tokens"),
     total_tokens: delta("total_tokens"),
@@ -561,6 +569,7 @@ function hasPositiveTokenDelta(usage) {
   return [
     usage.input_tokens,
     usage.cached_input_tokens,
+    usage.cache_write_input_tokens,
     usage.output_tokens,
     usage.reasoning_output_tokens,
     usage.total_tokens,
@@ -593,22 +602,30 @@ export async function pricingFor(workspace, model, tokens) {
       (item) => matchesIdentity(item.id) || item.aliases?.some(matchesIdentity),
     ) ?? null;
   if (!price) return { usd: null, brl: null };
-  const uncached = Math.max(0, tokens.input - tokens.cached_input);
-  const reasoning = Math.max(0, tokens.reasoning ?? 0);
-  const visibleOutput = Math.max(0, tokens.output - reasoning);
+  const cacheWriteInput = tokens.cache_write_input ?? null;
+  const cacheWriteRate = price.cache_write_input_per_million_usd ?? null;
+  if (
+    (cacheWriteRate !== null && cacheWriteInput === null) ||
+    (cacheWriteInput !== null && cacheWriteInput > tokens.input) ||
+    ((cacheWriteInput ?? 0) > 0 && cacheWriteRate === null)
+  ) {
+    return { usd: null, brl: null };
+  }
+  const uncached = Math.max(0, tokens.input - tokens.cached_input - (cacheWriteInput ?? 0));
   const longContext =
     price.long_context_threshold_tokens !== null &&
     price.long_context_threshold_tokens !== undefined &&
     tokens.input > price.long_context_threshold_tokens;
   const inputMultiplier = longContext ? (price.long_context_input_multiplier ?? 1) : 1;
   const outputMultiplier = longContext ? (price.long_context_output_multiplier ?? 1) : 1;
+  if (tokens.cached_input > 0 && price.cached_input_per_million_usd == null) {
+    return { usd: null, brl: null };
+  }
   const usd =
     (uncached * price.input_per_million_usd * inputMultiplier +
       tokens.cached_input * (price.cached_input_per_million_usd ?? 0) * inputMultiplier +
-      visibleOutput * price.output_per_million_usd * outputMultiplier +
-      reasoning *
-        (price.reasoning_per_million_usd ?? price.output_per_million_usd) *
-        outputMultiplier) /
+      (cacheWriteInput ?? 0) * (cacheWriteRate ?? 0) * inputMultiplier +
+      tokens.output * price.output_per_million_usd * outputMultiplier) /
     1_000_000;
   const fxFiles = await filesUnder(join(workspace, ".agents", "config", "pricing", "fx"), ".json");
   let rate = null;

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.test.mjs

@@ -72,7 +72,7 @@ test("normalizes compact and object Run records without changing usage totals",
     "execution",
     "test",
     "current_context",
-    [10, 4, 3, 1, 13, "provider_reported"],
+    [10, 4, 3, 1, 13, "provider_reported", 0],
     [0.1, 0.5],
   ];
   const records = jsonLines(
@@ -84,6 +84,7 @@ test("normalizes compact and object Run records without changing usage totals",
   assert.deepEqual(usageView(records[1]).tokens, {
     input: 10,
     cached_input: 4,
+    cache_write_input: 0,
     output: 3,
     reasoning: 1,
     total: 13,
@@ -93,12 +94,19 @@ test("normalizes compact and object Run records without changing usage totals",
   assert.deepEqual(
     aggregate({
       usage: [
-        { input_tokens: 10, cached_input_tokens: 4, output_tokens: 3, reasoning_output_tokens: 1 },
+        {
+          input_tokens: 10,
+          cached_input_tokens: 4,
+          cache_write_input_tokens: 0,
+          output_tokens: 3,
+          reasoning_output_tokens: 1,
+        },
       ],
     }),
     {
       input: 10,
       cached_input: 4,
+      cache_write_input: 0,
       output: 3,
       reasoning: 1,
       total: 13,
@@ -106,25 +114,26 @@ test("normalizes compact and object Run records without changing usage totals",
   );
 });
 
-test("deduplicates cumulative snapshots and starts a new epoch after reset", () => {
-  const snapshot = (input, cached, output, reasoning) => ({
+test("preserves absent, zero, and positive cache-write snapshots through deltas", () => {
+  const snapshot = (input, cached, cacheWrite, output, reasoning) => ({
     input_tokens: input,
     cached_input_tokens: cached,
+    cache_write_input_tokens: cacheWrite,
     output_tokens: output,
     reasoning_output_tokens: reasoning,
     total_tokens: input + output,
   });
   assert.deepEqual(
-    cumulativeSnapshotDelta(snapshot(100, 80, 20, 5), snapshot(100, 80, 20, 5)),
-    snapshot(0, 0, 0, 0),
+    cumulativeSnapshotDelta(snapshot(100, 80, 0, 20, 5), snapshot(100, 80, 0, 20, 5)),
+    snapshot(0, 0, 0, 0, 0),
   );
   assert.deepEqual(
-    cumulativeSnapshotDelta(snapshot(100, 80, 20, 5), snapshot(140, 110, 35, 9)),
-    snapshot(40, 30, 15, 4),
+    cumulativeSnapshotDelta(snapshot(100, 80, 0, 20, 5), snapshot(140, 110, 10, 35, 9)),
+    snapshot(40, 30, 10, 15, 4),
   );
   assert.deepEqual(
-    cumulativeSnapshotDelta(snapshot(140, 110, 35, 9), snapshot(12, 8, 3, 1)),
-    snapshot(12, 8, 3, 1),
+    cumulativeSnapshotDelta(snapshot(140, 110, 10, 35, 9), snapshot(12, 8, null, 3, 1)),
+    snapshot(12, 8, null, 3, 1),
   );
 });
 
@@ -132,11 +141,13 @@ test("deduplicates only consecutive identical last_token_usage fallback snapshot
   const snapshot = {
     input_tokens: 10,
     cached_input_tokens: 2,
+    cache_write_input_tokens: 0,
     output_tokens: 3,
     reasoning_output_tokens: 1,
     total_tokens: 13,
   };
   assert.equal(sameTokenSnapshot(snapshot, { ...snapshot }), true);
+  assert.equal(sameTokenSnapshot(snapshot, { ...snapshot, cache_write_input_tokens: 1 }), false);
   assert.equal(sameTokenSnapshot(snapshot, { ...snapshot, output_tokens: 4 }), false);
   assert.equal(sameTokenSnapshot(null, snapshot), false);
 });
@@ -170,6 +181,7 @@ test("prices only exact or governed model identities", async () => {
           aliases: ["gpt-test-alias"],
           input_per_million_usd: 10,
           cached_input_per_million_usd: 1,
+          cache_write_input_per_million_usd: 12.5,
           output_per_million_usd: 20,
           reasoning_per_million_usd: 30,
           long_context_threshold_tokens: null,
@@ -177,9 +189,23 @@ test("prices only exact or governed model identities", async () => {
       ],
     }),
   );
-  const tokens = { input: 100, cached_input: 40, output: 20, reasoning: 5 };
-  const expected = (60 * 10 + 40 * 1 + 15 * 20 + 5 * 30) / 1_000_000;
-  assert.equal((await pricingFor(root, "gpt-test", tokens)).usd, expected);
+  const zeroCacheWrite = {
+    input: 100,
+    cached_input: 40,
+    cache_write_input: 0,
+    output: 20,
+    reasoning: 5,
+  };
+  assert.equal(
+    (await pricingFor(root, "gpt-test", { ...zeroCacheWrite, cache_write_input: null })).usd,
+    null,
+  );
+  assert.equal((await pricingFor(root, "gpt-test", zeroCacheWrite)).usd, 0.00104);
+  assert.equal(
+    (await pricingFor(root, "gpt-test", { ...zeroCacheWrite, cache_write_input: 10 })).usd,
+    0.001065,
+  );
+  const tokens = zeroCacheWrite;
   assert.equal((await pricingFor(root, "unknown", tokens)).usd, null);
 });
 

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.mjs

@@ -74,6 +74,7 @@ export const remeasureSelectedRuns = async ({
     const unchanged =
       superseded.tokens.input === tokens.input &&
       superseded.tokens.cached_input === tokens.cached_input &&
+      superseded.tokens.cache_write_input === tokens.cache_write_input &&
       superseded.tokens.output === tokens.output &&
       superseded.tokens.reasoning === tokens.reasoning &&
       superseded.tokens.total === tokens.total;