Agent integration
How coding agents use Solwyn — the agent-context guardrails brief, the six-tool MCP server, and the check/confirm spend loop.
Solwyn gives coding agents a wrapper-side budget guardrail. It ships two things for that: a plain-text guardrails brief you can paste into an agent's context (solwyn agent-context), and a local server that exposes budget operations as tools (solwyn mcp). Both enforce the same rule — an agent guards the spend it makes itself, and never the spend the Solwyn SDK already tracks.
The one rule
Never wrap an SDK-instrumented call with a budget check or confirm. The Solwyn SDK already reserves budget before that call and confirms it after; checking it again double-counts — the reservation is held twice, and a project can end up denying itself. Budget check and confirm are only for un-instrumented spend an agent makes directly.
This works because the CLI is a wrapper-side guardrail, not a proxy. Its budget tools move quantities — token estimates and counts — never a prompt or a response. See Privacy for the full wire contract.
solwyn agent-context
solwyn agent-context prints the canonical "Solwyn budget guardrails" document as plain text. Pipe it into an agent's system context or save it alongside your other rules. It has three sections:
- Polling and reservations. Poll with
solwyn budget status --json— a pure read that holds no budget. Usebudget checkfollowed bybudget confirmonly around a specific un-instrumented provider call you make yourself. Fail-open is explicit: when a check returnsallowed=truewithreservation_id=null, skip confirm. Do not leave repeated unconfirmed checks outstanding — each one temporarily holds budget and can cause self-denial. - Machine contract and free-tier backoff. Use
--json(or--format json/SOLWYN_FORMAT=json) for schema-bearing output; success schema names are additive-only and JSON errors usesolwyn.error.v1on stderr. Exit codes are frozen —0success,1generic/API,2usage,3auth,4budget denial,5not found. On a rate limit, honorRetry-Afteronce for at most ten seconds; on the free tier, cache and back off rather than starting a retry storm. - Trust boundary. Keep Solwyn credentials in the OS keychain only — never echo them, and never place them in config files or argv. Solwyn must never collect, store, or proxy provider keys, prompts, or responses. Do not add telemetry or update checks.
solwyn init --agents writes these guardrails into your repository's agent files as a one-time setup step. See solwyn init.
solwyn mcp — the local tool server
solwyn mcp runs a local MCP server over stdio. It advertises tools only — no prompts, no resources — and exposes exactly six:
| Tool | What it does |
|---|---|
budget_status | Read budget utilization — a pure poll that reserves nothing |
budget_check | Reserve budget immediately before an un-instrumented call |
budget_confirm | Settle a non-null reservation after that call |
get_project_status | Read a project's budget and provider health |
get_costs | Read aggregated costs for one time range and grouping |
list_projects | List projects visible to the logged-in user (login/JWT required) |
The MCP tool names deliberately differ from the CLI command names: get_project_status maps to solwyn status, get_costs to solwyn costs, list_projects to solwyn projects list, and the three budget tools drop the budget prefix. Point any MCP-capable client at solwyn mcp to give the agent these six operations and nothing else.
The check → confirm loop
For un-instrumented spend — a provider call the SDK does not wrap — the guardrail is three steps, whether the agent calls the tools or the CLI:
Reserve. budget_check (or solwyn budget check) reserves budget before the call. A budget-denied outcome means do not spend.
Spend. Make the provider call yourself.
Settle. budget_confirm (or solwyn budget confirm) settles the reservation with the real token counts.
If the check comes back allowed with a null reservation, there is nothing to settle — skip confirm. And never run this loop around an SDK-instrumented call. To tag SDK spend to a named run instead, see Agent runs.
Related
- Scripting and CI — the JSON envelope and frozen exit codes the tools return
solwyn budget— every option forcheck,confirm, andstatussolwyn init— write the guardrails into your repo with--agents