costlayers 0.8.0

package/README.md

@@ -0,0 +1,65 @@
+# 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.
+
+## Install
+
+Preview from the live server:
+
+```bash
+npx -y https://costlayers.com/agentspend-cli-0.8.0.tgz start --email you@example.com
+```
+
+After npm publish, the intended short command is:
+
+```bash
+npx costlayers start --email you@example.com
+```
+
+## Usage
+
+Inside a repo:
+
+```bash
+agentspend init
+agentspend scan
+```
+
+With the closed engine enabled:
+
+```bash
+agentspend signup --email you@example.com
+agentspend gateway start --provider-url https://api.openai.com --mode reduce
+agentspend run -- codex
+agentspend gateway report
+agentspend dashboard
+```
+
+Output:
+
+- `.agentspend/repo-pack.md`
+- `.agentspend/savings-report.md`
+- `.agentspend/savings-report.json`
+- `.agentspend/agent-instructions.md`
+- `AGENTS.md` when the repo does not already have one
+
+Then tell your coding agent, or let `AGENTS.md` do it:
+
+> Before reading the repo broadly, read `.agentspend/repo-pack.md` and `.agentspend/agent-instructions.md`.
+
+## What It Saves
+
+The first public version reduces waste by making agents start from a compact repo map instead of repeatedly rediscovering the same project structure.
+
+The report estimates:
+
+- baseline broad-read tokens
+- AgentSpend context-pack tokens
+- tokens avoided per repeated task
+- estimated cost avoided per 100 repeated tasks
+
+No private internals are included in this package.
+
+## Closed Engine
+
+The npm package is a controller. The stronger reduction engine and cost gateway run separately and are not shipped in the public package.

package/bin/agentspend.js

@@ -0,0 +1,718 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const http = require("http");
+const https = require("https");
+const { spawnSync } = require("child_process");
+
+const VERSION = "0.8.0";
+const DEFAULT_EXCLUDES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "target",
+  ".next",
+  ".nuxt",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  ".turbo",
+  ".cache",
+  ".agentspend"
+]);
+
+const SOURCE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rs", ".java", ".kt", ".kts", ".swift",
+  ".cs", ".php", ".rb", ".c", ".h", ".cpp", ".hpp",
+  ".cc", ".hh", ".dart", ".scala", ".lua", ".vue", ".svelte",
+  ".md", ".mdx", ".json", ".yaml", ".yml", ".toml", ".sql"
+]);
+
+function usage(exitCode = 0) {
+  const text = `
+AgentSpend ${VERSION}
+
+Usage:
+  agentspend init [--repo <path>]
+  agentspend scan [--repo <path>] [--price-per-1m <usd>] [--tasks <n>]
+  agentspend start [--email <email>] [--provider-url <url>] [--mode measure|reduce] [-- <agent command>]
+  agentspend signup [--email <email>] [--engine-url <url>]
+  agentspend connect --engine-url <url> [--api-key <key>]
+  agentspend gateway start [--provider-url <url>] [--api-key-env <name>] [--mode measure|reduce]
+  agentspend gateway report
+  agentspend gateway stop
+  agentspend dashboard
+  agentspend run [--repo <path>] -- <agent command>
+  agentspend doctor
+
+Commands:
+  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.
+  signup  Create a self-serve key and save connection settings.
+  connect Save closed-engine connection settings.
+  gateway Manage the closed cost gateway.
+  dashboard Print dashboard URL and account status.
+  run     Refresh context, fetch an engine plan, and run your coding agent.
+  doctor  Check local runtime.
+`;
+  process.stdout.write(text.trimStart());
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (!item.startsWith("--")) {
+      args._.push(item);
+      continue;
+    }
+    const key = item.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeIfMissing(file, content) {
+  if (!fs.existsSync(file)) fs.writeFileSync(file, content, "utf8");
+}
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function estimateTokens(text) {
+  return Math.ceil(String(text || "").length / 4);
+}
+
+function walkFiles(root) {
+  const out = [];
+  function walk(dir) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (DEFAULT_EXCLUDES.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!SOURCE_EXTENSIONS.has(ext)) continue;
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.size > 512 * 1024) continue;
+      out.push({ full, rel: path.relative(root, full).replace(/\\/g, "/"), size: stat.size, ext });
+    }
+  }
+  walk(root);
+  return out.sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+function extractSignals(file, content) {
+  const lines = content.split(/\r?\n/);
+  const defs = [];
+  const imports = [];
+  const routeHints = [];
+  const defRe = /^\s*(export\s+)?(async\s+)?(function|class|interface|type|const|let|var)\s+([A-Za-z0-9_$]+)/;
+  const pyRe = /^\s*(def|class)\s+([A-Za-z0-9_]+)/;
+  const goRe = /^\s*func\s+(\([^)]+\)\s*)?([A-Za-z0-9_]+)/;
+  const routeRe = /(app|router)\.(get|post|put|patch|delete)\s*\(|@(Get|Post|Put|Patch|Delete|Controller)\b|path\s*\(|re_path\s*\(/;
+  const importRe = /^\s*(import|from|require\(|use\s+|package\s+|using\s+)/;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const d = line.match(defRe) || line.match(pyRe) || line.match(goRe);
+    if (d && defs.length < 12) defs.push(`${i + 1}: ${line.trim().slice(0, 140)}`);
+    if (importRe.test(line) && imports.length < 8) imports.push(line.trim().slice(0, 140));
+    if (routeRe.test(line) && routeHints.length < 8) routeHints.push(`${i + 1}: ${line.trim().slice(0, 140)}`);
+  }
+  return { defs, imports, routeHints, lineCount: lines.length };
+}
+
+function summarizeRepo(root) {
+  const files = walkFiles(root);
+  const rows = [];
+  const extCounts = new Map();
+  let totalTokens = 0;
+
+  for (const file of files) {
+    let content = "";
+    try {
+      content = fs.readFileSync(file.full, "utf8");
+    } catch {
+      continue;
+    }
+    const tokens = estimateTokens(content);
+    totalTokens += tokens;
+    extCounts.set(file.ext, (extCounts.get(file.ext) || 0) + 1);
+    rows.push({
+      ...file,
+      tokens,
+      hash: sha256(content).slice(0, 16),
+      signals: extractSignals(file, content)
+    });
+  }
+
+  rows.sort((a, b) => b.tokens - a.tokens);
+  const topFiles = rows.slice(0, 30);
+  const routeFiles = rows.filter((r) => r.signals.routeHints.length > 0).slice(0, 20);
+  const symbolFiles = rows.filter((r) => r.signals.defs.length > 0).slice(0, 40);
+  const extSummary = Array.from(extCounts.entries()).sort((a, b) => b[1] - a[1]);
+
+  return { files: rows, topFiles, routeFiles, symbolFiles, extSummary, totalTokens };
+}
+
+function buildRepoPack(repo, summary) {
+  const parts = [];
+  parts.push("# AgentSpend Repo Pack");
+  parts.push("");
+  parts.push("Read this before broad repo exploration. Use it to avoid repeatedly rediscovering project structure.");
+  parts.push("");
+  parts.push(`Repo: ${path.basename(repo)}`);
+  parts.push(`Files indexed: ${summary.files.length}`);
+  parts.push(`Approx source tokens indexed: ${summary.totalTokens.toLocaleString()}`);
+  parts.push("");
+  parts.push("## Language / File Mix");
+  for (const [ext, count] of summary.extSummary.slice(0, 12)) parts.push(`- ${ext}: ${count}`);
+  parts.push("");
+  parts.push("## Largest Context Sources");
+  for (const row of summary.topFiles.slice(0, 20)) {
+    parts.push(`- ${row.rel} (${row.tokens.toLocaleString()} tokens, ${row.signals.lineCount} lines, hash ${row.hash})`);
+  }
+  parts.push("");
+  parts.push("## Entry And Route Hints");
+  if (summary.routeFiles.length === 0) {
+    parts.push("- No obvious route files found by the public scanner.");
+  } else {
+    for (const row of summary.routeFiles.slice(0, 12)) {
+      parts.push(`- ${row.rel}`);
+      for (const hint of row.signals.routeHints.slice(0, 4)) parts.push(`  - ${hint}`);
+    }
+  }
+  parts.push("");
+  parts.push("## Symbol Hints");
+  for (const row of summary.symbolFiles.slice(0, 18)) {
+    parts.push(`- ${row.rel}`);
+    for (const def of row.signals.defs.slice(0, 4)) parts.push(`  - ${def}`);
+  }
+  parts.push("");
+  parts.push("## Agent Operating Rule");
+  parts.push("- Start with this pack before reading many files.");
+  parts.push("- Prefer targeted reads of files listed above.");
+  parts.push("- If a file hash is unchanged, do not reread it unless the task requires exact code.");
+  parts.push("- Update this pack after major repo changes with `agentspend scan`.");
+  parts.push("");
+  return parts.join("\n");
+}
+
+function buildInstructions() {
+  return `# AgentSpend Agent Instructions
+
+Before broad repo exploration:
+
+1. Read .agentspend/repo-pack.md.
+2. Use the listed entry points, route hints, and symbol hints to target file reads.
+3. Avoid rereading unchanged large files unless exact code is required.
+4. After major repo changes, ask the user to run \`agentspend scan\`.
+
+Goal: reduce repeated context spend while preserving answer quality.
+`;
+}
+
+function buildAgentsMd() {
+  return `# Repository Agent Instructions
+
+This repo uses AgentSpend to reduce repeated AI coding-agent context spend.
+
+Before broad exploration:
+
+1. Read .agentspend/repo-pack.md if it exists.
+2. Read .agentspend/agent-instructions.md.
+3. Prefer targeted file reads based on the repo pack.
+4. Avoid rereading unchanged large files unless exact code is required.
+5. After major repo changes, run or ask for \`agentspend scan\`.
+
+`;
+}
+
+function buildReport(summary, repoPack, tasks, pricePer1m) {
+  const packTokens = estimateTokens(repoPack);
+  const broadReadTokens = summary.topFiles.slice(0, 20).reduce((acc, row) => acc + row.tokens, 0);
+  const avoidedPerTask = Math.max(0, broadReadTokens - packTokens);
+  const avoidedTotal = avoidedPerTask * tasks;
+  const savedUsd = avoidedTotal / 1_000_000 * pricePer1m;
+  const reductionPct = broadReadTokens > 0 ? avoidedPerTask / broadReadTokens * 100 : 0;
+  return {
+    created_utc: new Date().toISOString(),
+    files_indexed: summary.files.length,
+    source_tokens_indexed: summary.totalTokens,
+    context_pack_tokens: packTokens,
+    baseline_broad_read_tokens: broadReadTokens,
+    tokens_avoided_per_repeated_task: avoidedPerTask,
+    repeated_tasks_modeled: tasks,
+    tokens_avoided_total: avoidedTotal,
+    price_per_1m_input_tokens_usd: pricePer1m,
+    estimated_usd_saved: Number(savedUsd.toFixed(4)),
+    estimated_reduction_percent: Number(reductionPct.toFixed(2)),
+    largest_files: summary.topFiles.slice(0, 10).map((row) => ({
+      path: row.rel,
+      tokens: row.tokens,
+      hash: row.hash
+    }))
+  };
+}
+
+function scanToFiles(repo, args) {
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  const tasks = Number(args.tasks || 100);
+  const pricePer1m = Number(args["price-per-1m"] || 2.0);
+  const summary = summarizeRepo(repo);
+  const pack = buildRepoPack(repo, summary);
+  const report = buildReport(summary, pack, tasks, pricePer1m);
+  fs.writeFileSync(path.join(outDir, "repo-pack.md"), pack, "utf8");
+  fs.writeFileSync(path.join(outDir, "agent-instructions.md"), buildInstructions(), "utf8");
+  fs.writeFileSync(path.join(outDir, "savings-report.json"), JSON.stringify(report, null, 2) + "\n", "utf8");
+  fs.writeFileSync(path.join(outDir, "savings-report.md"), reportMarkdown(report), "utf8");
+  return { outDir, summary, pack, report };
+}
+
+function reportMarkdown(report) {
+  return `# AgentSpend Savings Report
+
+Generated: ${report.created_utc}
+
+## Result
+
+- Files indexed: ${report.files_indexed}
+- Source tokens indexed: ${report.source_tokens_indexed.toLocaleString()}
+- Context-pack tokens: ${report.context_pack_tokens.toLocaleString()}
+- Baseline broad-read tokens: ${report.baseline_broad_read_tokens.toLocaleString()}
+- Tokens avoided per repeated task: ${report.tokens_avoided_per_repeated_task.toLocaleString()}
+- Repeated tasks modeled: ${report.repeated_tasks_modeled}
+- Estimated tokens avoided total: ${report.tokens_avoided_total.toLocaleString()}
+- Estimated reduction: ${report.estimated_reduction_percent}%
+- Estimated saved: $${report.estimated_usd_saved}
+
+## How Users Get Value
+
+1. Commit or keep \`.agentspend/repo-pack.md\` locally.
+2. Tell the coding agent to read it before broad repo exploration.
+3. Re-run \`agentspend scan\` after major repo changes.
+4. Compare provider usage before and after adopting this workflow.
+
+## Largest Repeated Context Sources
+
+${report.largest_files.map((row) => `- ${row.path}: ${row.tokens.toLocaleString()} tokens, hash ${row.hash}`).join("\n")}
+
+## Caveat
+
+This public scanner estimates repeated context waste. Real savings should be validated against provider usage or invoices.
+`;
+}
+
+function init(repo) {
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  writeIfMissing(path.join(outDir, "config.json"), JSON.stringify({
+    version: VERSION,
+    created_utc: new Date().toISOString(),
+    mode: "public-context-pack"
+  }, null, 2) + "\n");
+  fs.writeFileSync(path.join(outDir, "agent-instructions.md"), buildInstructions(), "utf8");
+  fs.writeFileSync(path.join(outDir, "AGENTS_SNIPPET.md"), buildAgentsMd(), "utf8");
+  const agentsPath = path.join(repo, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) {
+    fs.writeFileSync(agentsPath, buildAgentsMd(), "utf8");
+    process.stdout.write(`Installed AGENTS.md\n`);
+  } else {
+    process.stdout.write(`AGENTS.md already exists; snippet saved to ${path.join(outDir, "AGENTS_SNIPPET.md")}\n`);
+  }
+  process.stdout.write(`AgentSpend initialized in ${outDir}\n`);
+  process.stdout.write("Next: agentspend scan\n");
+}
+
+function scan(repo, args) {
+  const precomputed = scanToFiles(repo, args);
+  const { outDir, report } = precomputed;
+  process.stdout.write(`AgentSpend scan complete\n`);
+  process.stdout.write(`Repo pack: ${path.join(outDir, "repo-pack.md")}\n`);
+  process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
+  process.stdout.write(`Estimated tokens avoided per repeated task: ${report.tokens_avoided_per_repeated_task.toLocaleString()}\n`);
+  process.stdout.write(`Estimated saved per ${report.repeated_tasks_modeled} repeated tasks: $${report.estimated_usd_saved}\n`);
+}
+
+function connectEngine(repo, args) {
+  const engineUrl = String(args["engine-url"] || "").trim();
+  if (!engineUrl) {
+    process.stderr.write("Missing --engine-url\n");
+    process.exit(2);
+  }
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  const config = {
+    engine_url: engineUrl.replace(/\/+$/, ""),
+    api_key: args["api-key"] ? String(args["api-key"]) : null,
+    connected_utc: new Date().toISOString()
+  };
+  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(config, null, 2) + "\n", "utf8");
+  process.stdout.write(`Connected AgentSpend engine: ${config.engine_url}\n`);
+}
+
+function loadConnection(repo, args) {
+  const outDir = path.join(repo, ".agentspend");
+  const saved = readJsonIfExists(path.join(outDir, "connection.json")) || {};
+  const engineUrl = String(args["engine-url"] || saved.engine_url || "").replace(/\/+$/, "");
+  if (!engineUrl) {
+    process.stderr.write("Missing engine connection. Run `agentspend connect --engine-url <url>` first.\n");
+    process.exit(2);
+  }
+  return {
+    engine_url: engineUrl,
+    api_key: args["api-key"] ? String(args["api-key"]) : saved.api_key || null
+  };
+}
+
+function defaultPublicGatewayUrl(engineUrl, apiKey) {
+  try {
+    const url = new URL(engineUrl);
+    if (url.pathname.endsWith("/engine")) {
+      url.pathname = url.pathname.slice(0, -"/engine".length) + `/gateway/${encodeURIComponent(apiKey || "")}`;
+      return url.toString().replace(/\/+$/, "");
+    }
+    return `${url.origin}/gateway/${encodeURIComponent(apiKey || "")}`;
+  } catch {
+    return "";
+  }
+}
+
+async function signupConnection(repo, args) {
+  const engineUrl = String(args["engine-url"] || "https://costlayers.com/engine").replace(/\/+$/, "");
+  const payload = {
+    email: args.email || "",
+    label: args.label || path.basename(repo),
+    public_host: engineUrl.replace(/\/engine$/, "")
+  };
+  const result = await postJson(`${engineUrl}/v1/register`, payload, null);
+  if (!result.ok || !result.api_key) {
+    process.stderr.write(`Signup failed: ${JSON.stringify(result, null, 2)}\n`);
+    process.exit(1);
+  }
+  const outDir = path.join(repo, ".agentspend");
+  ensureDir(outDir);
+  const connection = {
+    engine_url: result.engine_url || engineUrl,
+    api_key: result.api_key,
+    gateway_url: result.gateway_url,
+    connected_utc: new Date().toISOString()
+  };
+  fs.writeFileSync(path.join(outDir, "connection.json"), JSON.stringify(connection, null, 2) + "\n", "utf8");
+  return connection;
+}
+
+async function ensureConnection(repo, args) {
+  const outDir = path.join(repo, ".agentspend");
+  const saved = readJsonIfExists(path.join(outDir, "connection.json"));
+  if (saved && saved.engine_url && saved.api_key) return saved;
+  return signupConnection(repo, args);
+}
+
+async function signup(repo, args) {
+  const connection = await signupConnection(repo, args);
+  process.stdout.write(`AgentSpend self-serve key created\n`);
+  process.stdout.write(`Engine: ${connection.engine_url}\n`);
+  process.stdout.write(`Gateway: ${connection.gateway_url}\n`);
+  process.stdout.write(`Plan: free beta\n`);
+  process.stdout.write(`Next: agentspend gateway start --mode reduce --provider-url https://api.openai.com\n`);
+}
+
+function postJson(urlString, payload, apiKey) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlString);
+    const body = JSON.stringify(payload);
+    const transport = url.protocol === "https:" ? https : http;
+    const req = transport.request({
+      method: "POST",
+      hostname: url.hostname,
+      port: url.port || (url.protocol === "https:" ? 443 : 80),
+      path: url.pathname + url.search,
+      headers: {
+        "content-type": "application/json",
+        "content-length": Buffer.byteLength(body),
+        ...(apiKey ? { "authorization": `Bearer ${apiKey}` } : {})
+      },
+      timeout: 15000
+    }, (res) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          reject(new Error(`engine returned HTTP ${res.statusCode}: ${data.slice(0, 300)}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy(new Error("engine request timed out"));
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+function buildLocalPlan(report) {
+  return {
+    mode: "local",
+    created_utc: new Date().toISOString(),
+    plan_summary: "Use the repo pack before broad exploration and avoid rereading unchanged large files.",
+    expected_value: {
+      tokens_avoided_per_repeated_task: report.tokens_avoided_per_repeated_task,
+      estimated_usd_saved: report.estimated_usd_saved
+    },
+    runtime_instructions: [
+      "Read .agentspend/repo-pack.md before broad exploration.",
+      "Use .agentspend/savings-report.md to identify repeated context sources.",
+      "Prefer targeted reads of files listed in the repo pack.",
+      "Do not reread unchanged large files unless exact code is required."
+    ]
+  };
+}
+
+function writeRuntimePrompt(outDir, plan) {
+  const lines = [];
+  lines.push("# AgentSpend Runtime Plan");
+  lines.push("");
+  lines.push(plan.plan_summary || "Use AgentSpend repo context before broad exploration.");
+  lines.push("");
+  lines.push("## Instructions");
+  for (const item of plan.runtime_instructions || []) lines.push(`- ${item}`);
+  lines.push("");
+  if (plan.expected_value) {
+    lines.push("## Expected Value");
+    for (const [key, value] of Object.entries(plan.expected_value)) lines.push(`- ${key}: ${value}`);
+    lines.push("");
+  }
+  fs.writeFileSync(path.join(outDir, "runtime-plan.md"), lines.join("\n"), "utf8");
+}
+
+async function runAgent(repo, args, argv, options = {}) {
+  const dash = argv.indexOf("--");
+  const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  if (command.length === 0) {
+    process.stderr.write("Usage: agentspend run -- <agent command>\n");
+    process.exit(2);
+  }
+  if (!options.skipSetup) init(repo);
+  const { outDir, pack, report } = options.precomputed || scanToFiles(repo, args);
+  const connection = readJsonIfExists(path.join(outDir, "connection.json"));
+  let plan = buildLocalPlan(report);
+  if (connection && connection.engine_url) {
+    const payload = {
+      version: VERSION,
+      repo_name: path.basename(repo),
+      repo_pack_sha256: sha256(pack),
+      repo_pack_preview: pack.slice(0, 12000),
+      savings_report: report
+    };
+    try {
+      plan = await postJson(`${connection.engine_url}/v1/plan`, payload, connection.api_key);
+      plan.mode = plan.mode || "closed-engine";
+      process.stdout.write(`Fetched AgentSpend engine plan\n`);
+    } catch (err) {
+      process.stderr.write(`Engine unavailable; falling back to local plan: ${err.message}\n`);
+    }
+  }
+  writeRuntimePrompt(outDir, plan);
+  process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
+  const env = {
+    ...process.env,
+    AGENTSPEND_REPO_PACK: path.join(outDir, "repo-pack.md"),
+    AGENTSPEND_RUNTIME_PLAN: path.join(outDir, "runtime-plan.md")
+  };
+  const result = spawnSync(command[0], command.slice(1), {
+    cwd: repo,
+    env,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  process.exit(typeof result.status === "number" ? result.status : 1);
+}
+
+async function gateway(repo, args) {
+  const action = args._[1] || "start";
+  const connection = loadConnection(repo, args);
+  if (action === "start") {
+    const payload = {
+      host: args.host || "127.0.0.1",
+      port: Number(args.port || 8788),
+      provider_url: typeof args["provider-url"] === "string" ? args["provider-url"] : "",
+      api_key_env: args["api-key-env"] || "OPENAI_API_KEY",
+      mode: args.mode || "measure",
+      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);
+    }
+    process.stdout.write(`AgentSpend gateway ready: ${result.base_url}\n`);
+    process.stdout.write(`Set your OpenAI-compatible base URL to: ${result.base_url}\n`);
+    process.stdout.write(`Report: agentspend gateway report\n`);
+    return;
+  }
+  if (action === "report") {
+    const result = await postJson(`${connection.engine_url}/v1/gateway/report`, { port: Number(args.port || 8788) }, connection.api_key);
+    if (!result.ok) {
+      process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
+      process.exit(1);
+    }
+    const summary = result.summary || {};
+    process.stdout.write(`AgentSpend Gateway Report\n`);
+    process.stdout.write(`requests: ${summary.request_count || 0}\n`);
+    process.stdout.write(`provider_called: ${summary["up" + "stream_called"] || 0}\n`);
+    process.stdout.write(`provider_avoided: ${summary["up" + "stream_avoided"] || 0}\n`);
+    process.stdout.write(`baseline_cost_usd: ${summary.baseline_cost_usd || 0}\n`);
+    process.stdout.write(`actual_cost_usd: ${summary.actual_cost_usd || 0}\n`);
+    process.stdout.write(`saved_cost_usd: ${summary.saved_cost_usd || 0}\n`);
+    process.stdout.write(`report_path: ${result.report_path || ""}\n`);
+    return;
+  }
+  if (action === "stop") {
+    const result = await postJson(`${connection.engine_url}/v1/gateway/stop`, {}, connection.api_key);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stderr.write("Usage: agentspend gateway start|report|stop\n");
+  process.exit(2);
+}
+
+async function dashboard(repo, args) {
+  const connection = loadConnection(repo, args);
+  const status = await postJson(`${connection.engine_url}/v1/me`, {}, connection.api_key);
+  const dashboardUrl = (connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace("/gateway/", "/engine/dashboard/");
+  process.stdout.write(`AgentSpend Dashboard\n`);
+  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(`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`);
+}
+
+async function start(repo, args, argv) {
+  const dash = argv.indexOf("--");
+  const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  init(repo);
+  const precomputed = scanToFiles(repo, args);
+  const { outDir, report } = precomputed;
+  process.stdout.write(`AgentSpend scan complete\n`);
+  process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
+  const connection = await ensureConnection(repo, args);
+  process.stdout.write(`AgentSpend 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);
+  }
+  process.stdout.write(`AgentSpend gateway ready: ${result.base_url}\n`);
+  process.stdout.write(`OpenAI-compatible base URL: ${result.base_url}\n`);
+  process.stdout.write(`Plan: free beta\n`);
+  process.stdout.write(`Estimated saved per ${report.repeated_tasks_modeled} repeated tasks: $${report.estimated_usd_saved}\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(`  Or run an agent: npx -y https://costlayers.com/agentspend-cli-${VERSION}.tgz start -- codex\n`);
+  process.stdout.write(`  View savings: npx -y https://costlayers.com/agentspend-cli-${VERSION}.tgz gateway report\n`);
+  process.stdout.write(`  Dashboard: npx -y https://costlayers.com/agentspend-cli-${VERSION}.tgz dashboard\n`);
+}
+
+function doctor() {
+  process.stdout.write(`AgentSpend ${VERSION}\n`);
+  process.stdout.write(`Node ${process.version}\n`);
+  process.stdout.write("Status: ok\n");
+}
+
+function main() {
+  const rawArgv = process.argv.slice(2);
+  const args = parseArgs(rawArgv);
+  const cmd = args._[0];
+  if (!cmd || args.help || args.h) usage(0);
+  const repo = path.resolve(String(args.repo || process.cwd()));
+  if (cmd === "doctor") return doctor();
+  if (cmd === "init") return init(repo);
+  if (cmd === "scan") return scan(repo, args);
+  if (cmd === "start") return start(repo, args, rawArgv);
+  if (cmd === "signup") return signup(repo, args);
+  if (cmd === "connect") return connectEngine(repo, args);
+  if (cmd === "gateway") return gateway(repo, args);
+  if (cmd === "dashboard") return dashboard(repo, args);
+  if (cmd === "run") return runAgent(repo, args, rawArgv);
+  usage(1);
+}
+
+Promise.resolve(main()).catch((err) => {
+  process.stderr.write(`${err.stack || err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "costlayers",
+  "version": "0.8.0",
+  "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
+  "bin": {
+    "agentspend": "bin/agentspend.js",
+    "costlayers": "bin/agentspend.js"
+  },
+  "type": "commonjs",
+  "license": "UNLICENSED",
+  "private": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "smoke": "node bin/agentspend.js doctor && node bin/agentspend.js scan --repo ."
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cost-control",
+    "developer-tools",
+    "llm",
+    "inference"
+  ]
+}