Veranda

The repo is inferred, not guessed

Detection scores four signals: an explicit declaration, a GitHub URL, a label, and last, a repository name in prose. The first two count as high confidence and prose as low, and on low confidence it asks in a comment instead of proceeding, because a well-tested pull request against the wrong service is worse than a question. A cheap-tier model pass then confirms or corrects that guess, and returns whether the work needs a proto, a migration, or visual verification.

Context arrives in four layers

None of it is prepended to a prompt. It goes into the clone as a file the CLI reads as project instructions. Each layer is narrower than the one above:

• A generic prompt for any repository: security rules, commit conventions, when to split work across sub-agents.
• Organisation runbooks from an architecture repo, narrowed to the ones the ticket touches: the how-we-do-things-here a model cannot read off the source.
• Per-repo hints, for what only that repo knows. Regenerate the queries after a schema change; the integration tests need Docker.
• Facts read off the repository: lint config, build tags, whether integration tests need containers.

Lexical retrieval, and no embeddings on purpose

Seeds are extracted from the ticket and the selected expert dossiers by regex, backticked spans and camelCase identifiers, capped at eight. Each one is searched against GitHub's own code index, scoped per repository, and hits come back as twelve line windows around the match. There is no vector store, because an identifier is a lexical object and exact match already answers the question that embeddings would answer worse.

The pack is bounded, and bounded in bytes

Twelve searches, six files, twelve thousand bytes. Those are byte ceilings rather than token budgets by choice: there is no tokenizer in the service, and a cap that is exact and free to enforce beats a token estimate that has to be recomputed per model family and is wrong for at least one of them.

A citation the model is structurally unable to fake

Every reference the agent is allowed to cite is created by the retrieval tool itself and never by the model, so the citable set is closed by construction. Whatever it cites anyway is scraped back out of the draft and resolved against the default branch, and anything that does not exist is flagged in the output instead of shipping as a confident wrong line number.

Where they refuse to be the same

The vendors' CLIs are incompatible in every detail that matters, so the shared interface is kept deliberately tiny. They disagree on how they authenticate, on the instruction filename, on whether they can see an image, on what a reasoning-effort knob is called, and on what a model is even named. The port covers only the three things they genuinely share, and every difference stays inside its own adapter, because widening it to cover the rest is how you get an abstraction that lies.

A model id is not portable, so tiers are the currency

Model names do not cross vendors, so the system picks a tier and resolves a concrete id only for whichever family ends up running. A task asks for high, not for a name, so if the run moves to another vendor it still asks for high and that vendor's own model answers. The exception is a model someone pinned by hand: it cannot survive the move, so it is dropped and the ticket says what ran instead.

Health is measured, not configured

A configured key proves nothing, so every backend gets a real cheap call and the verdict, classified as quota, auth, a failed turn, an upstream error or unreachable, is what drives the fallback. The ping names no model on purpose, testing the key against the CLI's own default rather than a pinned id that may itself have been retired and would condemn a healthy backend. When something is down another mode of the same vendor is tried first, because staying with the vendor keeps the model, and the reason follows the run into the metrics and onto the ticket.

Capabilities are negotiated, not assumed

Each adapter declares what it can do, and when it cannot the system degrades in one place instead of failing. Reasoning effort is normalized once and mapped to each vendor's own knob; an adapter that cannot see images has them stripped and runs text-only rather than erroring. Writing that rule once means a new adapter inherits it for free, provided it answers honestly, and the dangerous one is the adapter that claims vision it does not have.

The limit that shaped the design

The MCP server drives the page but cannot intercept its traffic, so request and websocket stubbing are not available as tools; when a task needs them the agent writes an ephemeral Playwright script instead. Knowing where the tool boundary sits mattered more than adding tools: an agent that believes it can stub a request it cannot stub writes a test that passes for the wrong reason. The descriptor is backend-agnostic, so adding a tool server does not fork per provider.

CI gets one repair attempt, grounded

If CI goes red the agent gets exactly one pass at fixing it, because a retry loop against a genuinely broken change burns a full agent budget per round. A log tail is a weak prompt for that pass, so when the failing check is the static-analysis gate the prompt carries the exact violations, rule ids and thresholds, verified to belong to the commit being fixed rather than to someone else's code. The same gate guards Veranda's own pull requests.

Test-first, for a specific reason

The failure modes are combinatorial and expensive to reach live: provider times mode times availability times vision support. Verifying that a revoked key falls back to another vendor, drops the now-invalid model label and posts the reason to the ticket should not require revoking a key, so the adapters expose seams for the command runner and the login step and the whole matrix runs in unit tests in seconds.