runcap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirill D.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Runcap
+
+[![CI](https://github.com/kirder24-code/ai-agent-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/kirder24-code/ai-agent-manager/actions/workflows/ci.yml)
+
+**Know what your coding agent will cost before you build it — and set a hard ceiling so it never surprises you.**
+
+Runcap estimates the cost of an agent run as a range, enforces a hard spend ceiling that physically stops the run, and when the agent gets stuck it hands you the exact rescue prompt. Free, MIT, 100% local. Your code and tokens never touch a server.
+
+> Every other tool here is a rear-view mirror — it shows you the bill *after* you paid it. Runcap estimates the bill *before* you start and caps it. It is a circuit breaker, not a dashboard.
+
+## Why
+
+Multi-agent coding runs burn roughly **15x more tokens** than a single chat ([Anthropic engineering](https://www.anthropic.com/engineering/built-multi-agent-research-system)). Agents loop on the same error, rewrite plans, and hand you a confident summary while the task is not actually done. You find out what it cost when the invoice — or the subscription limit — arrives.
+
+Observability tools (Langfuse, Helicone, LangSmith, AgentOps) measure the past. Gateways (LiteLLM, Portkey, OpenRouter) route the present. None of them stop the spend *before* it happens. Runcap does the one thing the rear-view mirror can't:
+
+```text
+estimate before build  →  cap during run  →  rescue when stuck  →  verify it finished
+```
+
+## The honest claim
+
+Runcap does **not** promise an exact cost oracle. Agent trajectories are stochastic — nobody, including the model labs, can predict the exact token count of a run. So Runcap gives you a **range plus a hard cap**:
+
+> "This build is roughly $3–7. Cap it at $10." — then it kills the run the second it hits the ceiling.
+
+The range is the headline. The hard cap is the product.
+
+## 60-second demo
+
+No API key required.
+
+```bash
+git clone https://github.com/kirder24-code/ai-agent-manager.git
+cd ai-agent-manager
+npm run setup
+npm run demo
+```
+
+**1. Catch a too-broad request before it spends anything:**
+
+```text
+$ runcap preflight -- claude "build the full mobile app with auth payments and production deploy"
+
+Preflight: claude build the full mobile app with auth payments and production deploy
+Scope risk: high
+Fuel: 24% (medium confidence)
+Recommendation: Do not launch as one broad mission. Split into one vertical slice with a verification command.
+```
+
+**2. Wrap a run — and get a rescue prompt the moment it gets stuck:**
+
+```text
+$ runcap run --label demo -- npm run build
+
+Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/components' ...
+
+Runcap mission: 20260601T221531-demo-ff42c0a
+Status: stuck (medium confidence)
+Exit code: 1
+Changed files: 0
+Parsed errors: 1
+Primary recommendation: Resolve missing import before continuing feature work
+```
+
+The rescue report hands back a copyable prompt:
+
+```text
+Do not continue broad implementation. Diagnose this missing module first:
+Cannot find package '@/components'. Check package.json, tsconfig paths, and
+the latest git diff. Make the smallest change that resolves the import,
+then run the failing command again.
+```
+
+![Runcap dashboard rescue notice](docs/assets/dashboard-rescue-notice.png)
+
+## Install
+
+```bash
+npm install -g runcap     # exposes `runcap` (and `aim` as a legacy alias)
+```
+
+Or run from source with `node ./bin/runcap.mjs <command>`.
+
+## Core commands
+
+```bash
+runcap plan --fuel 24 -- "build a small auth feature and verify it"   # range + recommended cap, before you spend
+runcap preflight -- claude "build a full SaaS app"                     # is this prompt too broad?
+runcap run --label fix -- claude "fix one failing check. stop if blocked."  # wrap any agent/command
+runcap report                                                          # human-readable rescue report
+runcap export                                                          # evidence JSON with truth labels
+runcap dashboard                                                       # local cockpit at :8791
+runcap gateway                                                         # cost-tracking proxy with hard budget cap
+runcap fuel set 24                                                     # calibrate a %-only subscription
+```
+
+## The hard cap (gateway)
+
+Point any OpenAI- or Anthropic-compatible tool at the local gateway. It records real token usage, prices it from a sourced table, and **blocks calls the moment your daily ceiling is hit**.
+
+```bash
+# OpenAI-compatible agents
+OPENAI_API_KEY=sk-... AIM_DAILY_BUDGET_USD=5 runcap gateway
+#   then: OPENAI_BASE_URL=http://127.0.0.1:8792/v1
+
+# Anthropic-native (Claude Code, /v1/messages)
+ANTHROPIC_API_KEY=sk-ant-... AIM_DAILY_BUDGET_USD=5 runcap gateway
+#   then: ANTHROPIC_BASE_URL=http://127.0.0.1:8792/v1
+```
+
+When spend crosses the ceiling, the next call returns `429 budget_guard` instead of money leaving your account. Try it with no key: `runcap gateway --mock`.
+
+## Pricing table
+
+Costs are calculated from a sourced multi-provider table — Anthropic (Opus / Sonnet / Haiku) and OpenAI (GPT-5 family + legacy GPT-4), with cache-read and batch discounts handled — labeled with source and verification date. When a model is unknown, Runcap says `unknown_price` rather than guessing.
+
+## Trust model
+
+Runcap is built not to fake certainty. Every important output carries a truth label:
+
+- `observed` — git diff, exit code, file changes, terminal output;
+- `calculated` — parsed errors, diff hashes, stuck score, cost from the sourced price table;
+- `provider_usage` — token usage returned by the upstream provider;
+- `manual_calibration` — subscription % you entered before/after a run;
+- `unknown` — Runcap cannot honestly know.
+
+If it cannot prove something, it says so.
+
+## Pricing (the product, not the tokens)
+
+| Tier | Price | What you get |
+|---|---|---|
+| **OSS** (MIT, local) | $0 forever | All local runs, cost estimation, hard cap, run wrapping, stuck detection, rescue prompts, local dashboard. Never crippleware. |
+| **Pro** | $19/mo | Cloud sync across machines, hosted dashboard, estimate-vs-actual trends, shareable reports, alerts on cap breach |
+| **Team** | $49/seat/mo | Shared budget pools, org-wide ceilings, per-project rollups, role-based caps |
+
+The local core is free forever. Only persistence, collaboration, and aggregation are paid — the things that only matter once data leaves your laptop.
+
+## Current stage
+
+A working local tool, not a hosted SaaS. Ready for: wrapping real Codex / Claude / Cursor sessions, catching stuck agents, and proving rescue prompts save time. Not yet: a hosted cloud platform or a universal observability standard. It is not trying to replace Langfuse or LiteLLM — it does the thing they don't.
+
+## Documentation
+
+- [Product status](PRODUCT.md)
+- [Quickstart](docs/quickstart.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Business plan](docs/BUSINESS-PLAN.md)
+- [Integrations](docs/integrations.md)
+- [Trust model](docs/trust-model.md)
+
+---
+
+The thesis: **AI agents need managers.**

package/bin/runcap.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import {
+  calibrateFuel,
+  doctor,
+  exportSnapshot,
+  latestMissionId,
+  listMissions,
+  listPlans,
+  planMission,
+  preflightMission,
+  recordFuel,
+  renderReport,
+  runMission,
+  setupProject,
+  startDashboard,
+  startGateway,
+  showStatus,
+  templates
+} from "../src/mission-control.mjs";
+
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+
+function usage() {
+  console.log(`Runcap — cap every agent run before it starts
+
+Usage:
+  runcap run [--label name] [--fuel-before 24] -- <command...>
+  runcap plan [--fuel 24] [--quality high|balanced|cheap] -- <goal...>
+  runcap plans
+  runcap preflight -- <command or prompt...>
+  runcap status
+  runcap list
+  runcap report [mission-id]
+  runcap rescue [mission-id]
+  runcap export [mission-id]
+  runcap templates
+  runcap dashboard [--port 8791]
+  runcap gateway [--port 8792] [--mock]
+  runcap setup
+  runcap doctor
+  runcap fuel set <percent>
+  runcap fuel calibrate <mission-id> <after-percent>
+
+Examples:
+  runcap run --label auth-fix -- claude "fix the auth bug"
+  runcap plan --fuel 24 -- "build a mobile app MVP with auth and deployment"
+  runcap run -- npm test
+  runcap report
+  runcap fuel set 24
+
+(\`aim\` works as a legacy alias for every command.)
+`);
+}
+
+function takeOption(input, name) {
+  const index = input.indexOf(name);
+  if (index === -1) return undefined;
+  const value = input[index + 1];
+  input.splice(index, 2);
+  return value;
+}
+
+try {
+  if (command === "help" || command === "--help" || command === "-h") {
+    usage();
+  } else if (command === "run") {
+    const runArgs = args.slice(1);
+    const label = takeOption(runArgs, "--label");
+    const fuelBefore = takeOption(runArgs, "--fuel-before");
+    const separator = runArgs.indexOf("--");
+    const childArgs = separator === -1 ? runArgs : runArgs.slice(separator + 1);
+    if (childArgs.length === 0) {
+      throw new Error("Missing command after `aim run --`.");
+    }
+    const result = await runMission({
+      command: childArgs,
+      label,
+      fuelBefore: fuelBefore === undefined ? undefined : Number(fuelBefore)
+    });
+    console.log(result.summary);
+  } else if (command === "preflight") {
+    const runArgs = args.slice(1);
+    const separator = runArgs.indexOf("--");
+    const childArgs = separator === -1 ? runArgs : runArgs.slice(separator + 1);
+    if (childArgs.length === 0) {
+      throw new Error("Missing command or prompt after `aim preflight --`.");
+    }
+    console.log(await preflightMission(childArgs));
+  } else if (command === "plan") {
+    const planArgs = args.slice(1);
+    const fuelPercent = takeOption(planArgs, "--fuel");
+    const quality = takeOption(planArgs, "--quality") ?? "high";
+    const separator = planArgs.indexOf("--");
+    const goalArgs = separator === -1 ? planArgs : planArgs.slice(separator + 1);
+    const goal = goalArgs.join(" ").trim();
+    if (!goal) {
+      throw new Error("Missing goal after `aim plan --`.");
+    }
+    const plan = await planMission(goal, {
+      quality,
+      fuelPercent: fuelPercent === undefined ? undefined : Number(fuelPercent)
+    });
+    console.log([
+      "",
+      `Runcap plan: ${plan.id}`,
+      `Goal: ${plan.goal}`,
+      `Budget risk: ${plan.budget.risk}`,
+      `Expected waste reduction: ${plan.budget.expectedWasteReduction}`,
+      `Planning model: ${plan.routing.planningTier}`,
+      `Execution model: ${plan.routing.executionTier}`,
+      `Proof: ${plan.quality.proof}`,
+      `Stop rule: ${plan.stopRule}`,
+      `Report: .aim-control/plans/${plan.id}/plan.md`,
+      ""
+    ].join("\n"));
+  } else if (command === "plans") {
+    console.log(await listPlans());
+  } else if (command === "status") {
+    console.log(await showStatus());
+  } else if (command === "list") {
+    console.log(await listMissions());
+  } else if (command === "report" || command === "rescue") {
+    const id = args[1] ?? (await latestMissionId());
+    if (!id) throw new Error("No mission found.");
+    console.log(await renderReport(id));
+  } else if (command === "export") {
+    const id = args[1] ?? (await latestMissionId());
+    if (!id) throw new Error("No mission found.");
+    console.log(await exportSnapshot(id));
+  } else if (command === "templates") {
+    console.log(templates());
+  } else if (command === "dashboard") {
+    const port = Number(takeOption(args, "--port") ?? 8791);
+    await startDashboard({ port });
+  } else if (command === "gateway") {
+    const port = Number(takeOption(args, "--port") ?? 8792);
+    const gatewayArgs = args.slice(1);
+    const mock = gatewayArgs.includes("--mock");
+    await startGateway({ port, mock });
+  } else if (command === "setup") {
+    console.log(await setupProject());
+  } else if (command === "doctor") {
+    console.log(await doctor());
+  } else if (command === "fuel") {
+    const subcommand = args[1] ?? "show";
+    if (subcommand === "set") {
+      const value = Number(args[2]);
+      if (!Number.isFinite(value)) throw new Error("Usage: aim fuel set <percent>");
+      console.log(await recordFuel(value));
+    } else if (subcommand === "calibrate") {
+      const id = args[2];
+      const after = Number(args[3]);
+      if (!id || !Number.isFinite(after)) {
+        throw new Error("Usage: aim fuel calibrate <mission-id> <after-percent>");
+      }
+      console.log(await calibrateFuel(id, after));
+    } else {
+      console.log(await showStatus({ includeFuelOnly: true }));
+    }
+  } else {
+    usage();
+    process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`aim: ${error.message}`);
+  process.exitCode = 1;
+}

package/examples/broken-ts-app/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "broken-ts-app",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "node src/index.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/examples/broken-ts-app/src/index.ts

@@ -0,0 +1,5 @@
+import { Button } from "@/components/Button";
+
+export function renderLogin() {
+  return Button({ label: "Sign in" });
+}

package/examples/broken-ts-app/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "runcap",
+  "version": "0.1.0",
+  "description": "Cap every agent run before it starts: estimate cost, set a hard ceiling that stops the run, rescue stuck agents. Local, MIT, nothing uploaded.",
+  "license": "MIT",
+  "type": "module",
+  "author": "Kirill D. <kirill@launchsoloai.com> (https://launchsoloai.com)",
+  "homepage": "https://launchsoloai.com/runcap",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirder24-code/ai-agent-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kirder24-code/ai-agent-manager/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "coding-agent",
+    "cost",
+    "budget",
+    "claude",
+    "openai",
+    "gateway",
+    "cli",
+    "llm",
+    "token-cost"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "runcap": "./bin/runcap.mjs",
+    "aim": "./bin/runcap.mjs"
+  },
+  "scripts": {
+    "setup": "node ./bin/runcap.mjs setup",
+    "doctor": "node ./bin/runcap.mjs doctor",
+    "demo": "node ./scripts/demo-flow.mjs",
+    "acceptance": "node ./scripts/acceptance.mjs",
+    "smoke": "node ./bin/runcap.mjs run --label smoke -- npm --prefix examples/broken-ts-app run build",
+    "demo:broken": "node ./bin/runcap.mjs run --label broken-ts-demo -- npm --prefix examples/broken-ts-app run build",
+    "test": "node ./scripts/validate-demo.mjs",
+    "status": "node ./bin/runcap.mjs status",
+    "report": "node ./bin/runcap.mjs report",
+    "export": "node ./bin/runcap.mjs export",
+    "templates": "node ./bin/runcap.mjs templates",
+    "dashboard": "node ./bin/runcap.mjs dashboard",
+    "gateway": "node ./bin/runcap.mjs gateway",
+    "fuel": "node ./bin/runcap.mjs fuel",
+    "check": "node --check ./bin/runcap.mjs && node --check ./src/mission-control.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}