docs(design): propose free trial credits at signup

[mmabrouk]

Revision, 2026-08-03. New research changed the plan. Start with docs/design/activation-credits/revised-plan.md; it supersedes decisions D6 and D7 of rfc.md. Two findings drive it: OpenRouter can mint API keys with a server-enforced dollar cap, expiry, and (via its Guardrails feature) a model allowlist, which makes renting enforcement possible; and the runner already has a tested route that pins a run to one model at any OpenAI-compatible endpoint. The revised plan compares per-user capped OpenRouter keys against a thin gateway route inside the existing API, and recommends the thin gateway because every line of it survives into the future credit system. Supporting evidence is in docs/design/activation-credits-gateway-spike/. The probe script there has never been run and needs approval before anyone runs it.

---

Problem

A new signup lands in the playground, describes their agent, commits it, and then hits a wall: the composer disables and a banner demands an LLM provider API key before their first message sends. The user does the work and gets none of the payoff.

What this PR contains

A full design workspace under docs/design/activation-credits/, in reading order:

• context.md — the situation today, goals, constraints, and a glossary defining every term.
• rfc.md — the decisions requested (D1-D8), including a smallest safe version that strips the hardening items, so scope can be cut deliberately.
• design.md — the full architecture: signup grant record, reservation with atomic charge, server-side funding provenance, and a small in-house inference gateway (the platform key never enters the user-controlled sandbox), composed with the Daytona secret-delivery work (docs(agent-workflows): Plan Daytona secret delivery #5223/[feat] Deliver agent credentials through Daytona Secrets #5277/[docs] Plan durable managed-resource reconciliation #5278).
• research.md — the evidence: current key-gate mechanics, PR [chore] Limit usage of agenta provided keys via credits #2957 prior art, the entitlements engine, measured activation token costs from production traces (~23.6K tokens of harness context per LLM call), model pricing and abuse math, anonymized competitor free-tier patterns, the Daytona-secrets possession-vs-usage analysis, and the gateway build-vs-adopt survey.
• implicit-decisions.md — a register of every requirement that entered the design beyond the original ask (own inference, review-forced, or codebase constraint), each with the cost of striking it. Read this to cut scope.

Review

Mahmoud is the reviewer. An external model review loop was used as a helper during drafting; its accreted requirements are itemized in implicit-decisions.md rather than baked in silently. Do not merge; that call is Mahmoud's.

https://claude.ai/code/session_013PybmGbRaSiFzFtzhCrESm

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 3, 2026 9:35am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ec7bf40b-5406-42d8-b616-3ada49242b60

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/activation-credits-proposal

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Tracked in #5506.

[mmabrouk]

Tracked in #5506.

[mmabrouk]

Revision pushed. What changed and what to look at:

Added in commit 85dd9c5: docs/design/activation-credits/revised-plan.md (the new entry point, 558 lines) and docs/design/activation-credits-gateway-spike/ (the supporting research: verified OpenRouter API facts, repo findings, findings, open questions, and an unrun probe script).

The recommendation changed. The original rfc.md recommended building the full gateway (D7). The revised plan compares two ways to enforce the spend limit: renting it from OpenRouter via per-user capped keys, or a thin gateway route inside the existing API service in front of OpenRouter. It recommends the thin gateway, because it costs about one extra week, keeps the real key out of the user-controlled sandbox entirely, and every line of it survives into the future credit system (model calls, tool calls, and beyond).

One finding that gates any implementation: a brand-new user's default agent sends no connection object on the wire, so the runner's custom-endpoint path never fires and the run would go to the wrong host. Version one needs a reserved connection identity on the wire, one small change on each side, proven end to end on day one.

Decisions requested are in section 9 of revised-plan.md: option choice, model class and cap, trial window, dedicated OpenRouter account, and whether to run the probe script (it spends a few cents against the live OpenRouter API and needs explicit approval).

[mmabrouk]

Superseded. The funding approach changed: we now have a much larger pool of provider credits from a different source, and that source does not sell per-key spending limits, so renting enforcement is off the table and a gateway plus a real credit ledger is the direction. That design work continues in a private repository. The research in this branch about our own runtime remains accurate and has been carried over.