diff --git a/README.md b/README.md index 662e3dc..8001e76 100644 --- a/README.md +++ b/README.md @@ -4,35 +4,36 @@ ![Runcap terminal demo: estimate, cap, verify integrity, mission PASS - then a tampered run graded BLOCKED on the PR](docs/assets/demo.svg) -**An AI coding agent can pass CI by editing the test that proves its own success. Runcap caps the spend before the run and issues evidence about whether that success check can be trusted. Free, MIT, local-first. Local runs keep Runcap's control plane on your machine; optional CI adjudication runs in your GitHub Actions environment.** +**Control AI coding spend. Require proof before merge.** -> **An agent passing CI is not enough.** -> Runcap verifies whether the evidence of success was altered during the mission. +Runcap is a local-first control layer for AI coding agents. It can cap routed AI +spend and use a pinned GitHub Action to replay base-pinned verification before an +AI-generated PR earns merge eligibility. -| Status | Meaning | -|---|---| -| `VERIFIED_STRONG` | Result passed an unchanged verifier and a clean-worktree replay. | -| `VERIFIED_WEAK` | Result passed, but some integrity evidence is missing. | -| `UNVERIFIED` | Verification did not pass. | -| `VERIFIER_COMPROMISED` | The agent changed protected verification evidence. | +Current public position: ```text -Estimate the run → Cap the spend → Verify the outcome +Runcap controls AI coding missions. + +It caps routed AI spend, +constrains what an agent may change, +and requires proof before an AI-generated pull request earns merge eligibility. ``` -Most cost and observability tools measure **tokens** used. But you don't buy tokens - you buy a result that passes a check. So Runcap measures the number that actually decides whether the spend was worth it: +What Runcap sees: -> **Verified Outcome Cost = total run cost / tasks that passed verification.** An agent that talks but never fixes the bug can cost *more* than one that does - and a token dashboard calls it "cheaper." +- Spend controls apply only to requests routed through Runcap. +- The CI Proof Gate independently verifies code changes; it does not claim to independently meter all model usage. +- Hosted sync, team pools, organization reporting, and paid plans are not products available for purchase today. -| | Without Runcap | With Runcap | -|---|---|---| -| You find out the cost | when the invoice arrives | **before you press go, capped at your ceiling** | -| When the agent gets stuck | it keeps spending | **run stops, you get the exact rescue prompt** | -| What you paid for | tokens (delivered or not) | **dollars per *verified* result** | +See [current product status](docs/current-product-status.md) for the exact public boundary. -In a 6-run test on the same task, the run that **delivered nothing** cost *more* than the one that delivered, and the cheapest verified result was ~43x cheaper than the most expensive - same passing test. ([full table below](#real-results-6-runs-same-task-reproducible-offline)) +> **An agent passing CI is not enough.** +> Runcap verifies whether the evidence of success was altered during the mission. -> Most tools here are a rear-view mirror - they show you the bill *after* you paid it. Runcap estimates the bill *before* you start, caps it during the run, and issues evidence about whether the declared verification can be trusted. It is a circuit breaker with a receipt, not a dashboard. +```text +Estimate the run → Cap the spend → Verify the outcome +``` > If Runcap caps a run for you or compresses a call, please **star the repo** - it is the one signal that tells me to keep building it in the open. @@ -69,7 +70,7 @@ Observability tools (Langfuse, Helicone, LangSmith, AgentOps) measure the past, estimate before build → cap during run → compress every call → rescue when stuck → verify the outcome ``` -It also quietly trims waste on the way through: on a real OpenAI call, one edited-file re-read dropped from **1,186 to 737 prompt tokens (37.9% saved)** with the model still answering correctly about the changed line - lossless, and no other proxy does it ([details below](#token-compression-built-in-no-extra-deps)). +It also quietly trims waste on the way through: on a real OpenAI call, one edited-file re-read dropped from **1,186 to 737 prompt tokens (37.9% saved)** with the model still answering correctly about the changed line - see the details below. ## The honest claim @@ -418,7 +419,7 @@ A working local tool plus an optional CI adjudication mode, not a hosted SaaS. R ## Documentation -- [Product status](PRODUCT.md) +- [Current product status](docs/current-product-status.md) - [Quickstart](docs/quickstart.md) - [Roadmap](docs/ROADMAP.md) - [Business plan](docs/BUSINESS-PLAN.md) diff --git a/docs/BUSINESS-PLAN.md b/docs/BUSINESS-PLAN.md index 55ee2b0..5c2af11 100644 --- a/docs/BUSINESS-PLAN.md +++ b/docs/BUSINESS-PLAN.md @@ -1,5 +1,7 @@ # AI Agent Manager — Business Plan (idea → money) +> Historical planning document. It may describe ideas, pricing, or product direction that are not part of Runcap's current public offer. See `docs/current-product-status.md` for the current product boundary. + _Last updated: 2026-06-01_ This is the money path. It runs alongside `ROADMAP.md` (what to build) and answers: how do we sell it, get it in front of people, prove value, keep it simple, what it costs to build, what it costs to sell, and how every build step gets analyzed and improved before the next one. diff --git a/docs/LAUNCH-COPY.md b/docs/LAUNCH-COPY.md index 6a86ed2..83cb5e1 100644 --- a/docs/LAUNCH-COPY.md +++ b/docs/LAUNCH-COPY.md @@ -1,5 +1,7 @@ # Launch copy — Runcap +> Historical planning document. It may describe ideas, pricing, or product direction that are not part of Runcap's current public offer. See `docs/current-product-status.md` for the current product boundary. + Ready-to-paste posts for launch day. Post AFTER `npm publish` succeeds and `npm install -g runcap` works. Links used: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 7b224b7..a124313 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,5 +1,7 @@ # AI Agent Manager — Roadmap +> Historical planning document. It may describe ideas, pricing, or product direction that are not part of Runcap's current public offer. See `docs/current-product-status.md` for the current product boundary. + _Last updated: 2026-06-01_ This is the build-and-launch plan for AI Agent Manager. It is split into shippable parts so each phase ends with something usable, not half-finished infrastructure. diff --git a/docs/current-product-status.md b/docs/current-product-status.md new file mode 100644 index 0000000..adbc693 --- /dev/null +++ b/docs/current-product-status.md @@ -0,0 +1,69 @@ +# Runcap Current Product Status + +This is the current public boundary for Runcap. + +```text +Control AI coding spend. +Require proof before merge. +``` + +Runcap controls AI coding missions. It caps routed AI spend, constrains what an +agent may change, and requires proof before an AI-generated pull request earns +merge eligibility. + +## Available Now + +- **Local-first CLI controls.** Runcap can plan, preflight, wrap, report, export, + and display local AI coding missions from the command line. +- **Hard caps for routed AI calls.** Spend caps apply only to AI requests routed + through the Runcap gateway/control path. Calls made directly to providers, + subscriptions, invoices, personal cards, and unrelated tools are outside the + metered path. +- **Mission policies.** A repository can define `.runcap/mission.yaml` with + identity, budget limits, verification commands, protected paths, and allowed + change scope. +- **Public GitHub Proof Gate demo.** The demo repository shows three public pull + requests graded by a pinned Runcap GitHub Action. +- **PR verdicts.** The current public verdicts are `PASS`, `BLOCKED`, and + `HUMAN_APPROVAL_REQUIRED`. +- **GitHub/Node/npm-oriented CI adjudication.** The current Proof Gate is built + around GitHub Actions, Node/npm repositories, text diffs, declared mission + policy, and base-pinned verification replay. + +## Explicit Limits + +- Runcap does not see all AI spend across a company. +- It does not see subscription usage, personal cards, reimbursement data, + invoices, or AI tools outside its control path. +- CI adjudication does not independently meter all AI spend. It verifies code + changes and policy compliance; spend enforcement remains tied to routed calls + and mission receipts. +- Runcap does not claim cryptographic proof, fully independent verification, + or guaranteed safe merges. +- Hosted sync, team pools, organization reporting, paid Pro features, and paid + plans are not products available for purchase today. + +## Direction, Not Current Feature Claim + +The future Mission Receipt concept is: + +```text +owner + workload + cap + metered coverage + PR verdict +``` + +That concept is a product direction, not a shipped public guarantee. Today, +Runcap can write local receipts and CI verdicts for supported coding workflows, +but it does not yet provide a hosted company-wide receipt ledger or universal +coverage across all AI work. + +## Public-Interface Items Requiring Product Verification + +| Location | What it appears to promise | Current public documentation support | Recommended next decision | +|---|---|---|---| +| `bin/runcap.mjs` help: `runcap login ` | Pro license login enabling cloud sync and a hosted dashboard. | README Availability says hosted sync and paid plans are not available today. | Verify end-to-end before public launch, or mark experimental/remove from public help. | +| `src/cloud.mjs`: `loginCommand`, `whoamiCommand`, `syncRun` | Stored Pro license, remote sync endpoint, hosted dashboard URL. | No current public product page documents an available hosted dashboard or purchase flow. | Verify end-to-end with real license issuance and privacy terms, or mark experimental/remove from public help. | +| `bin/runcap.mjs` help and `src/alerts.mjs`: `runcap alerts` | Pro phone alerts for cap breaches through Telegram, WhatsApp, or webhooks. | README does not document alerts as an available product; Availability says paid plans are future ideas. | Verify end-to-end and publish setup/security docs, or mark experimental/remove from public help. | +| `README.md` Availability and pricing-adjacent language | Future hosted sync, team pools, organization reporting, and paid plans. | README now labels these as future ideas only. | Keep as direction only until a purchasable product exists. | +| `PRODUCT.md` root product status | Broad "AI efficiency control layer" for a person or company, including routing, monitoring, learning, and dashboard claims. | Current public boundary is narrower: AI coding missions, routed spend caps, mission scope, and Proof Gate. | Update or mark historical in a later docs pass. | +| `docs/ROADMAP.md`, `docs/BUSINESS-PLAN.md`, `docs/product-plan.md`, `docs/LAUNCH-COPY.md` | Planning language for teams, cloud, Pro, hosted dashboards, and launch copy. | These files are now marked historical and point here for current scope. | Keep as historical planning documents unless the product decision changes. | + diff --git a/docs/product-plan.md b/docs/product-plan.md index 8a1f011..f23ce69 100644 --- a/docs/product-plan.md +++ b/docs/product-plan.md @@ -1,5 +1,7 @@ # Product Plan: AI Efficiency Manager +> Historical planning document. It may describe ideas, pricing, or product direction that are not part of Runcap's current public offer. See `docs/current-product-status.md` for the current product boundary. + ## Position AI users do not only need more agents. They need a manager that turns AI spend into accountable work. diff --git a/docs/quickstart.md b/docs/quickstart.md index fcaaee0..c8a2712 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,7 +5,7 @@ This guide proves the product locally without any paid API call. ## 1. Setup ```bash -cd agent-manager-lab +cd ai-agent-manager npm run setup npm run doctor ``` @@ -37,7 +37,7 @@ Open: http://127.0.0.1:8791 ``` -The dashboard is local-only. It reads `.aim-control/missions` and `.aim-control/gateway-events.jsonl`. +The dashboard is local-first. It reads `.runcap/missions` and `.runcap/gateway-events.jsonl`. On macOS, double-click: