costlayers 0.8.11 → 0.8.14

package/README.md

@@ -1,6 +1,6 @@
 # CostLayers CLI
 
-CostLayers helps teams reduce wasted AI coding-agent spend by creating a compact repo context pack, an OpenAI-compatible gateway, and a savings dashboard.
+CostLayers helps coding-agent users stop paying for repeated repo context. API users can route model calls through the gateway for invoice savings. ChatGPT-login Codex users get a usage-stretch meter that shows how much repeated context was avoided.
 
 ## Install
 
@@ -30,8 +30,31 @@ npx -y costlayers@latest start --email you@example.com -- codex
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
 so it can avoid repeated broad repo exploration. It also writes
 `~/.codex/costlayers.config.toml` and runs Codex as
-`codex --profile costlayers`, enabling gateway metering and redacted Codex token
-telemetry for ChatGPT-login sessions.
+`codex --profile costlayers`, enabling redacted Codex telemetry for
+ChatGPT-login sessions while preserving Codex's native model provider.
+
+This mode is for getting more useful work out of the same ChatGPT/Codex plan.
+It does not reduce a flat ChatGPT subscription invoice.
+
+## Invoice Savings Mode
+
+To reduce an OpenAI Platform invoice, route API-key billed model calls through
+the CostLayers gateway. This requires an OpenAI Platform API key with Responses
+API write permission:
+
+```bash
+export OPENAI_API_KEY=sk-proj-...
+npx -y costlayers@latest start --email you@example.com --codex-proxy -- codex
+```
+
+ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
+Platform invoice savings because it is not billed through your Platform API key.
+
+## Which Mode Should I Use?
+
+- ChatGPT-login Codex: use `start -- codex` to reduce repeated repo context and stretch usage limits.
+- OpenAI Platform API billing: use `--codex-proxy` with `OPENAI_API_KEY` for invoice-backed savings.
+- Other OpenAI-compatible clients: point the client at the CostLayers gateway URL and check `costlayers gateway report`.
 
 To install only the Codex profile after signup:
 
@@ -50,9 +73,10 @@ costlayers gateway report
 costlayers dashboard
 ```
 
-Metered dashboard savings only increase when model API traffic is routed through
-the CostLayers gateway URL. Codex-metered dashboard savings increase when Codex
-uses the CostLayers profile or emits token telemetry to the CostLayers meter.
+Metered gateway savings increase when model API traffic is routed through the
+CostLayers gateway URL with a provider API key. Codex-metered dashboard savings
+increase when Codex uses the CostLayers profile or emits token telemetry to the
+CostLayers meter.
 For ChatGPT-login Codex, dollar savings are modeled from observed Codex token
 events because the ChatGPT plan invoice is not an OpenAI Platform API invoice.
 

package/bin/agentspend.js

@@ -9,7 +9,8 @@ const https = require("https");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
-const VERSION = "0.8.11";
+const VERSION = "0.8.14";
+const INSTALL_SPEC = "costlayers@latest";
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
 const DEFAULT_EXCLUDES = new Set([
@@ -51,9 +52,9 @@ CostLayers ${VERSION}
 Usage:
   costlayers init [--repo <path>]
   costlayers scan [--repo <path>] [--price-per-1m <usd>] [--tasks <n>] [--runs-per-week <n>]
-  costlayers start [--email <email>] [--provider-url <url>] [--mode measure|reduce] [--runs-per-week <n>] [-- <agent command>]
+  costlayers start [--email <email>] [--provider-url <url>] [--mode measure|reduce] [--runs-per-week <n>] [--codex-proxy] [-- <agent command>]
   costlayers signup [--email <email>] [--engine-url <url>]
-  costlayers codex-profile [--repo <path>]
+  costlayers codex-profile [--repo <path>] [--codex-proxy]
   costlayers connect --engine-url <url> [--api-key <key>]
   costlayers gateway start [--provider-url <url>] [--api-key-env <name>] [--mode measure|reduce]
   costlayers gateway report
@@ -122,7 +123,7 @@ function guardRepoRoot(repo, args) {
     "",
     "Run it inside a project folder instead:",
     "  cd path/to/your-repo",
-    "  npx -y costlayers@latest start --email you@example.com",
+    `  npx -y ${INSTALL_SPEC} start --email you@example.com`,
     "",
     "Or pass --repo path/to/your-repo from anywhere.",
     "If you really intend to scan your whole home directory, add --allow-home.",
@@ -506,6 +507,7 @@ function printSavingsSummary(report) {
   const projection = savingsProjection(report);
   const avoided = Number(report.tokens_avoided_per_repeated_task || 0);
   process.stdout.write(`\n${avoided > 0 ? "CostLayers found repeated context waste" : "CostLayers built your repo context pack"}\n`);
+  process.stdout.write(`  Evidence: context estimate from local repo scan\n`);
   process.stdout.write(`  Tokens avoided per repeated task: ${formatInt(report.tokens_avoided_per_repeated_task)}\n`);
   if (avoided > 0) {
     process.stdout.write(`  Before vs after context: ${formatInt(report.baseline_broad_read_tokens)} -> ${formatInt(report.context_pack_tokens)} tokens (${report.estimated_reduction_percent}% less)\n`);
@@ -513,8 +515,9 @@ function printSavingsSummary(report) {
     process.stdout.write(`  No repeated-context reduction found yet for this small/simple repo.\n`);
     process.stdout.write(`  Context pack size: ${formatInt(report.context_pack_tokens)} tokens from ${formatInt(report.source_tokens_indexed)} indexed source tokens\n`);
   }
-  process.stdout.write(`  Modeled savings per ${formatInt(report.repeated_tasks_modeled)} repeated tasks: ${formatUsd(report.estimated_usd_saved)}\n`);
-  process.stdout.write(`  Projected at ${formatInt(projection.runsPerWeek)} agent runs/week: ${formatUsd(projection.weeklyUsd)}/week, ${formatUsd(projection.monthlyUsd)}/month\n`);
+  process.stdout.write(`  Estimated waste value per ${formatInt(report.repeated_tasks_modeled)} repeated tasks: ${formatUsd(report.estimated_usd_saved)}\n`);
+  process.stdout.write(`  Usage-stretch estimate at ${formatInt(projection.runsPerWeek)} agent runs/week: ${formatUsd(projection.weeklyUsd)}/week, ${formatUsd(projection.monthlyUsd)}/month\n`);
+  process.stdout.write(`  Invoice savings require API traffic through CostLayers invoice mode.\n`);
   process.stdout.write(`  Source tokens indexed: ${formatInt(report.source_tokens_indexed)}\n`);
   process.stdout.write(`  Compact repo pack: ${formatInt(report.context_pack_tokens)} tokens\n`);
 }
@@ -523,22 +526,58 @@ function codexHomeDir() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
-function profileTomlString(connection) {
+function codexProxyEnabled(args = {}) {
+  return Boolean(args["codex-proxy"] || args["proxy-codex"]);
+}
+
+function codexProxyApiKeyEnv(args = {}) {
+  return String(args["api-key-env"] || "OPENAI_API_KEY");
+}
+
+function assertCodexProxyApiKey(args = {}) {
+  if (!codexProxyEnabled(args)) return;
+  const keyEnv = codexProxyApiKeyEnv(args);
+  if (process.env[keyEnv]) return;
+  process.stderr.write([
+    `CostLayers invoice mode needs ${keyEnv} in this shell.`,
+    "",
+    "Set an OpenAI Platform API key with Responses API write permission, then rerun:",
+    `  export ${keyEnv}=sk-proj-...`,
+    `  npx -y ${INSTALL_SPEC} start --email you@example.com --codex-proxy -- codex`,
+    "",
+    "ChatGPT-login Codex can be metered, but it cannot produce provider invoice savings because there is no per-request Platform invoice to reduce.",
+    ""
+  ].join("\n"));
+  process.exit(2);
+}
+
+function profileTomlString(connection, args = {}) {
   const gateway = String(connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace(/\/+$/, "");
   const baseUrl = `${gateway}/v1`;
   const engineUrl = String(connection.engine_url || "https://costlayers.com/engine").replace(/\/+$/, "");
-  return [
-    "# Generated by CostLayers. This profile routes Codex through the CostLayers meter.",
+  const apiKeyEnv = codexProxyApiKeyEnv(args);
+  const lines = [
+    "# Generated by CostLayers. This profile sends Codex telemetry to the CostLayers meter.",
     "# Keep this file private because it contains your keyed CostLayers endpoint.",
-    "",
+    "# Default mode preserves Codex's native model provider/auth, which works with ChatGPT-login Codex.",
+    ""
+  ];
+  if (codexProxyEnabled(args)) {
+    lines.push(
+      "# Proxy mode routes Codex model calls through the CostLayers gateway.",
+      `# It uses ${apiKeyEnv} from your shell and requires OpenAI Platform Responses API write scope.`,
+      "",
     'model_provider = "costlayers"',
     "",
     "[model_providers.costlayers]",
     'name = "CostLayers"',
     `base_url = ${JSON.stringify(baseUrl)}`,
     'wire_api = "responses"',
-    "requires_openai_auth = true",
-    "",
+    `env_key = ${JSON.stringify(apiKeyEnv)}`,
+      ""
+    );
+  }
+  lines.push(
     "[otel]",
     'environment = "costlayers"',
     "log_user_prompt = false",
@@ -550,14 +589,15 @@ function profileTomlString(connection) {
     '[otel.exporter."otlp-http".headers]',
     `"x-costlayers-key" = ${JSON.stringify(connection.api_key || "")}`,
     ""
-  ].join("\n");
+  );
+  return lines.join("\n");
 }
 
-function writeCodexProfile(connection) {
+function writeCodexProfile(connection, args = {}) {
   const dir = codexHomeDir();
   ensureDir(dir);
   const file = path.join(dir, "costlayers.config.toml");
-  fs.writeFileSync(file, profileTomlString(connection), "utf8");
+  fs.writeFileSync(file, profileTomlString(connection, args), "utf8");
   return file;
 }
 
@@ -625,9 +665,10 @@ async function signup(repo, args) {
 
 async function codexProfile(repo, args) {
   const connection = await ensureConnection(repo, args);
-  const profilePath = writeCodexProfile(connection);
+  const profilePath = writeCodexProfile(connection, args);
   process.stdout.write(`CostLayers Codex profile installed\n`);
   process.stdout.write(`Profile: ${profilePath}\n`);
+  process.stdout.write(`Mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode, native Codex provider preserved"}\n`);
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
   process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Run: codex --profile costlayers\n`);
@@ -747,10 +788,12 @@ async function runAgent(repo, args, argv, options = {}) {
   process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
   let commandToRun = command;
   if (connection && connection.engine_url && isCodexCommand(command)) {
-    const profilePath = writeCodexProfile(connection);
+    assertCodexProxyApiKey(args);
+    const profilePath = writeCodexProfile(connection, args);
     commandToRun = withCostLayersCodexProfile(command);
     process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
     process.stdout.write(`Codex metering enabled: ${commandToRun.join(" ")}\n`);
+    process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
     process.stdout.write(`Savings dashboard: ${dashboardUrlFromConnection(connection)}\n`);
     process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   }
@@ -827,19 +870,22 @@ async function dashboard(repo, args) {
   process.stdout.write(`URL: ${dashboardUrl}\n`);
   process.stdout.write(`status: ${status.status || "unknown"}\n`);
   process.stdout.write(`plan: ${status.free_beta ? "free beta" : "metered"}\n`);
-  process.stdout.write(`metered_savings_usd: ${status.metered_savings_usd ?? ""}\n`);
-  process.stdout.write(`codex_metered_savings_usd: ${status.codex_metered_savings_usd ?? ""}\n`);
+  process.stdout.write(`api_invoice_savings_usd: ${status.metered_savings_usd ?? ""}\n`);
+  process.stdout.write(`chatgpt_codex_usage_stretch_usd: ${status.codex_metered_savings_usd ?? ""}\n`);
   process.stdout.write(`codex_meter_total_tokens: ${status.codex_meter_total_tokens ?? 0}\n`);
-  process.stdout.write(`codex_context_savings_usd: ${status.context_savings_usd ?? ""}\n`);
+  process.stdout.write(`context_waste_estimate_usd: ${status.context_savings_usd ?? ""}\n`);
   process.stdout.write(`context_tokens_avoided_per_task: ${status.context_tokens_avoided_per_task ?? 0}\n`);
   process.stdout.write(`gateway_requests: ${status.gateway_request_count ?? 0}\n`);
   process.stdout.write(`blocked_requests: ${status.blocked_request_count ?? 0}\n`);
   process.stdout.write(`rate_limit_per_minute: ${status.rate_limit_per_minute ?? ""}\n`);
+  process.stdout.write(`claim: API invoice savings only count when provider API traffic is routed through CostLayers. ChatGPT-login Codex shows usage stretch, not invoice reduction.\n`);
 }
 
 async function start(repo, args, argv) {
   const dash = argv.indexOf("--");
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
+  if (command.length > 0 && isCodexCommand(command)) assertCodexProxyApiKey(args);
   init(repo);
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
@@ -855,37 +901,49 @@ async function start(repo, args, argv) {
     process.stderr.write(`Dashboard sync delayed; local report is still available: ${err.message}\n`);
   }
   process.stdout.write(`CostLayers connection ready\n`);
-  const providerUrl = typeof args["provider-url"] === "string" ? args["provider-url"] : "https://api.openai.com";
-  const payload = {
-    host: args.host || "127.0.0.1",
-    port: Number(args.port || 8788),
-    provider_url: providerUrl,
-    api_key_env: args["api-key-env"] || "OPENAI_API_KEY",
-    mode: args.mode || "reduce",
-    dry_run: Boolean(args["dry-run"]),
-    public_gateway_url: args["public-gateway-url"] || connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)
-  };
-  const result = await postJson(`${connection.engine_url}/v1/gateway/start`, payload, connection.api_key);
-  if (!result.ok) {
-    process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
-    process.exit(1);
+  let gatewayBaseUrl = connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key);
+  if (codexTelemetryRun) {
+    process.stdout.write(`ChatGPT-login Codex mode: native Codex provider preserved; model calls are not routed through CostLayers.\n`);
+    process.stdout.write(`What users get: less repeated repo context and a usage-stretch meter. This does not reduce a flat ChatGPT subscription invoice.\n`);
+  } else {
+    const providerUrl = typeof args["provider-url"] === "string" ? args["provider-url"] : "https://api.openai.com";
+    const payload = {
+      host: args.host || "127.0.0.1",
+      port: Number(args.port || 8788),
+      provider_url: providerUrl,
+      api_key_env: args["api-key-env"] || "OPENAI_API_KEY",
+      mode: args.mode || "reduce",
+      dry_run: Boolean(args["dry-run"]),
+      public_gateway_url: args["public-gateway-url"] || gatewayBaseUrl
+    };
+    const result = await postJson(`${connection.engine_url}/v1/gateway/start`, payload, connection.api_key);
+    if (!result.ok) {
+      process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
+      process.exit(1);
+    }
+    gatewayBaseUrl = result.base_url || gatewayBaseUrl;
+    process.stdout.write(`CostLayers gateway ready: ${gatewayBaseUrl}\n`);
+    process.stdout.write(`OpenAI-compatible base URL: ${gatewayBaseUrl}\n`);
+    if (codexProxyEnabled(args)) {
+      process.stdout.write(`API invoice mode: Codex will use ${codexProxyApiKeyEnv(args)} through the CostLayers gateway.\n`);
+    }
   }
-  process.stdout.write(`CostLayers gateway ready: ${result.base_url}\n`);
-  process.stdout.write(`OpenAI-compatible base URL: ${result.base_url}\n`);
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
   process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Plan: free beta\n`);
-  const profilePath = writeCodexProfile(connection);
+  const profilePath = writeCodexProfile(connection, args);
   process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
+  process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
   if (command.length > 0) {
     return runAgent(repo, args, argv, { skipSetup: true, precomputed });
   }
   process.stdout.write(`\nNext options:\n`);
-  process.stdout.write(`  Use gateway URL in your model client: ${result.base_url}\n`);
-  process.stdout.write(`  Run Codex metered: npx -y costlayers@latest start --email you@example.com -- codex\n`);
+  process.stdout.write(`  Use gateway URL in your model client: ${gatewayBaseUrl}\n`);
+  process.stdout.write(`  Run Codex metered: npx -y ${INSTALL_SPEC} start --email you@example.com -- codex\n`);
+  process.stdout.write(`  Reduce an OpenAI API invoice: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} start --email you@example.com --codex-proxy -- codex\n`);
   process.stdout.write(`  Or run Codex directly: codex --profile costlayers\n`);
-  process.stdout.write(`  View savings: npx -y costlayers@latest gateway report\n`);
-  process.stdout.write(`  Dashboard: npx -y costlayers@latest dashboard\n`);
+  process.stdout.write(`  View report: npx -y ${INSTALL_SPEC} gateway report\n`);
+  process.stdout.write(`  Dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
 }
 
 function doctor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "costlayers",
-  "version": "0.8.11",
+  "version": "0.8.14",
   "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
   "bin": {
     "agentspend": "bin/agentspend.js",