costlayers 0.8.15 → 0.8.16

package/README.md

@@ -2,29 +2,30 @@
 
 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
+## Quick Start
 
-One-command setup:
+Daily Codex use:
 
 ```bash
 cd your-repo
-npx -y costlayers@latest start --email you@example.com
+npx -y costlayers@latest codex --email you@example.com
 ```
 
-## Usage
+If `OPENAI_API_KEY` is set, CostLayers automatically uses API invoice mode.
+If no API key is set, it uses ChatGPT-login usage-stretch mode.
 
-Inside a repo:
+Run a one-command API savings test:
 
 ```bash
-costlayers init
-costlayers scan
+npx -y costlayers@latest test --email you@example.com
 ```
 
-Launch Codex with CostLayers context:
+## Usage
+
+Inside a repo:
 
 ```bash
-cd your-repo
-npx -y costlayers@latest start --email you@example.com -- codex
+npx -y costlayers@latest codex --email you@example.com
 ```
 
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
@@ -44,7 +45,7 @@ API write permission:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y costlayers@latest start --email you@example.com --codex-proxy -- codex
+npx -y costlayers@latest codex --email you@example.com
 ```
 
 ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
@@ -52,8 +53,9 @@ 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.
+- ChatGPT-login Codex: use `costlayers codex --email you@example.com --chatgpt` to reduce repeated repo context and stretch usage limits.
+- OpenAI Platform API billing: set `OPENAI_API_KEY`, then use `costlayers codex --email you@example.com` for invoice-backed savings.
+- Savings proof: set `OPENAI_API_KEY`, then run `costlayers test --email you@example.com`.
 - 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:

package/bin/agentspend.js

@@ -9,7 +9,7 @@ const https = require("https");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
-const VERSION = "0.8.15";
+const VERSION = "0.8.16";
 const INSTALL_SPEC = "costlayers@latest";
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
@@ -50,6 +50,8 @@ function usage(exitCode = 0) {
 CostLayers ${VERSION}
 
 Usage:
+  costlayers codex [--email <email>] [--chatgpt|--api] [-- <codex args>]
+  costlayers test [--email <email>] [--prompt <text>]
   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>] [--codex-proxy] [-- <agent command>]
@@ -64,6 +66,8 @@ Usage:
   costlayers doctor
 
 Commands:
+  codex   Start Codex with CostLayers. Uses API invoice mode automatically when OPENAI_API_KEY is set.
+  test    Run a safe read-only Codex task and print the CostLayers savings report.
   init    Create .agentspend config and agent instructions.
   scan    Build repo context pack and savings report.
   start   One-command setup, signup, gateway start, and optional agent run.
@@ -123,7 +127,7 @@ function guardRepoRoot(repo, args) {
     "",
     "Run it inside a project folder instead:",
     "  cd path/to/your-repo",
-    `  npx -y ${INSTALL_SPEC} start --email you@example.com`,
+    `  npx -y ${INSTALL_SPEC} codex --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.",
@@ -538,6 +542,28 @@ function codexProxyApiKeyEnv(args = {}) {
   return String(args["api-key-env"] || "OPENAI_API_KEY");
 }
 
+function apiInvoiceModeRequested(args = {}) {
+  return Boolean(args.api || args.invoice || args["api-mode"] || codexProxyEnabled(args));
+}
+
+function chatgptModeRequested(args = {}) {
+  return Boolean(args.chatgpt || args["no-api"]);
+}
+
+function codexArgsAfterDash(argv) {
+  const dash = argv.indexOf("--");
+  return dash >= 0 ? argv.slice(dash + 1) : [];
+}
+
+function withAutoCodexMode(args = {}, options = {}) {
+  const next = { ...args };
+  const keyEnv = codexProxyApiKeyEnv(next);
+  const hasApiKey = Boolean(process.env[keyEnv]);
+  const wantsInvoice = apiInvoiceModeRequested(next) || (options.preferInvoice && hasApiKey);
+  if (!chatgptModeRequested(next) && wantsInvoice) next["codex-proxy"] = true;
+  return next;
+}
+
 function assertCodexProxyApiKey(args = {}) {
   if (!codexProxyEnabled(args)) return;
   const keyEnv = codexProxyApiKeyEnv(args);
@@ -547,7 +573,7 @@ function assertCodexProxyApiKey(args = {}) {
     "",
     "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`,
+    `  npx -y ${INSTALL_SPEC} codex --email you@example.com --api`,
     "",
     "ChatGPT-login Codex can be metered, but it cannot produce provider invoice savings because there is no per-request Platform invoice to reduce.",
     ""
@@ -845,7 +871,9 @@ async function runAgent(repo, args, argv, options = {}) {
     stdio: "inherit",
     shell: process.platform === "win32"
   });
-  process.exit(typeof result.status === "number" ? result.status : 1);
+  const status = typeof result.status === "number" ? result.status : 1;
+  if (options.returnStatus) return status;
+  process.exit(status);
 }
 
 async function gateway(repo, args) {
@@ -918,7 +946,51 @@ async function dashboard(repo, args) {
   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) {
+async function codexShortcut(repo, args, argv) {
+  const codexTail = codexArgsAfterDash(argv);
+  const command = codexTail.length > 0 ? codexTail : ["codex"];
+  const commandToRun = isCodexCommand(command) ? command : ["codex", ...command];
+  const nextArgs = withAutoCodexMode(args, { preferInvoice: true });
+  if (codexProxyEnabled(nextArgs)) {
+    process.stdout.write(`CostLayers Codex: API invoice mode enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
+  } else {
+    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Set ${codexProxyApiKeyEnv(nextArgs)} or pass --api for invoice savings.\n`);
+  }
+  return start(repo, nextArgs, ["start", "--", ...commandToRun]);
+}
+
+async function savingsTest(repo, args) {
+  const nextArgs = withAutoCodexMode(args, { preferInvoice: true });
+  if (!codexProxyEnabled(nextArgs)) {
+    const keyEnv = codexProxyApiKeyEnv(nextArgs);
+    process.stderr.write([
+      `CostLayers test needs ${keyEnv} for real API invoice savings.`,
+      "",
+      "Set your OpenAI Platform API key, then rerun:",
+      `  source ~/.config/costlayers/env`,
+      `  npx -y ${INSTALL_SPEC} test --email you@example.com`,
+      "",
+      `For ChatGPT-login metering without invoice savings, run:`,
+      `  npx -y ${INSTALL_SPEC} codex --email you@example.com --chatgpt`,
+      ""
+    ].join("\n"));
+    process.exit(2);
+  }
+  const prompt = typeof args.prompt === "string"
+    ? args.prompt
+    : "Analyze this repository. Find the main entry points, data flow, and the 5 files most worth reading. Do not edit files.";
+  process.stdout.write("CostLayers savings test: running one safe read-only Codex task.\n");
+  const status = await start(repo, nextArgs, ["start", "--", "codex", "exec", "--sandbox", "read-only", prompt], { returnStatus: true });
+  process.stdout.write("\nCostLayers savings test report\n");
+  try {
+    await gateway(repo, { ...nextArgs, _: ["gateway", "report"] });
+  } catch (err) {
+    process.stderr.write(`Could not fetch savings report: ${err.message}\n`);
+  }
+  process.exit(status);
+}
+
+async function start(repo, args, argv, options = {}) {
   const dash = argv.indexOf("--");
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
   const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
@@ -972,12 +1044,12 @@ async function start(repo, args, argv) {
   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 });
+    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus });
   }
   process.stdout.write(`\nNext options:\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(`  Run Codex: npx -y ${INSTALL_SPEC} codex --email you@example.com\n`);
+  process.stdout.write(`  Prove API savings: npx -y ${INSTALL_SPEC} test --email you@example.com\n`);
   process.stdout.write(`  Or run Codex directly: codex --profile costlayers\n`);
   process.stdout.write(`  View report: npx -y ${INSTALL_SPEC} gateway report\n`);
   process.stdout.write(`  Dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
@@ -995,8 +1067,10 @@ function main() {
   const cmd = args._[0];
   if (!cmd || args.help || args.h) usage(0);
   const repo = path.resolve(String(args.repo || process.cwd()));
-  if (["init", "scan", "start", "run", "codex-profile"].includes(cmd)) guardRepoRoot(repo, args);
+  if (["init", "scan", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
   if (cmd === "doctor") return doctor();
+  if (cmd === "codex") return codexShortcut(repo, args, rawArgv);
+  if (cmd === "test") return savingsTest(repo, args);
   if (cmd === "init") return init(repo);
   if (cmd === "scan") return scan(repo, args);
   if (cmd === "start") return start(repo, args, rawArgv);

package/package.json

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