Drive the coding agents from outside: an authenticated web API that takes settings and a prompt and returns the answer

[dnviti]

Problem / Motivation

The coding agents can only be driven by a person sitting in front of the app: sign in with GitHub, open a conversation, type a prompt, read the answer. Anything else that would like to use them — a CI pipeline, an internal automation, a chat bot, a script on a laptop, another product — has no way in. The server already knows how to run several agents, keep each user's work separate, confine them to allowed folders and account for what they spend, and none of that is reachable except through the browser.

There is an HTTP surface today, but every part of it assumes a browser that has completed a sign-in and carries the resulting session. A machine has nothing to present, so today the honest answer to "can I call this from outside?" is no.

Goal

An external system can authenticate to the server with a credential of its own, ask a chosen runtime to run a prompt under a chosen set of settings, and receive the agent's answer — with the run recorded, attributed and accounted exactly like the same work done from the browser.

Scope

• A way for a signed-in user to create, name, list and revoke long-lived credentials meant for machines. The secret is shown once at creation; the list shows what exists and when each was last used.
• Those credentials authenticate the programmatic endpoints, as a channel of its own alongside — not instead of — the browser sign-in.
• Start a run: choose the runtime, the project folder to work in, and the prompt.
• Send settings with the run: which model, how much reasoning effort, how approvals should be handled, and whether to start fresh or continue existing work. Settings that decide what process actually runs stay under server control — the caller picks from what the server already permits, it does not get to define the launch.
• Get the answer back: wait for the run to finish and receive the final answer, or start it and check on it afterwards.
• Continue a conversation across calls, so an external caller can hold a multi-turn exchange rather than only one-shot prompts.
• Report outcomes honestly: an error, an interruption, a run that ended without answering, and a successful answer are all distinguishable.
• Report what the run cost and which model answered, and record it in the same per-user history as browser work.
• Runs started this way are ordinary conversations: their owner can open them in the app and read them.
• Documentation with a working example.

Non-goals

• Not a drop-in replacement for a model provider's completion API. This drives agents that read and write real files in a real workspace; it is not a stateless text endpoint.
• No new agent abilities. The API exposes what the runtimes already do.
• No anonymous, shared or public access, and no weakening of how the browser signs in.
• No new way to reach folders, files or conversations that the credential's owner could not already reach.

Security / Safety Considerations

• These agents read files, write files and run commands. A credential that can start a run is therefore roughly as powerful as the person who created it: it must act only as that user, obey the same folder confinement, and be revocable instantly with the revocation taking effect immediately.
• An unattended run has nobody to answer an approval prompt or a question from the agent. The API must be explicit here rather than silently hanging: a run either declares up front how approvals are to be handled, or it reports that it is blocked and waiting. Letting a run act without asking must be a deliberate, per-call decision that is visible in the record afterwards.
• Secrets are shown once and stored so they cannot be read back; "last used" is visible so a forgotten or leaked credential can be noticed.
• External callers must not become a way around what is measured: the same accounting and the same capacity considerations apply, plus limits on how many runs one caller can start at once, so a runaway script cannot spawn unbounded agent processes.

Acceptance Criteria

• A signed-in user can create a named machine credential, see it listed with its creation and last-used times, and revoke it. The secret appears once and is never retrievable again.
• A request carrying a valid credential is accepted; a missing, malformed, unknown or revoked one is refused with a clear reason and starts nothing.
• An external call can start a run on any runtime this server supports, with a prompt, and receive the agent's final answer.
• The same call can specify the model, the effort, how approvals are handled and which folder to work in, and the run demonstrably honours them; a value that is not allowed is refused with a clear reason instead of being silently ignored.
• A follow-up call can continue the same conversation, and the agent still has the earlier turn in context.
• A run that fails, is interrupted, or finishes without producing an answer is reported distinctly from a successful one.
• A run that stops for an approval or a question is reported as waiting, with enough detail to decide — or runs straight through when the call declared approvals pre-granted.
• A caller cannot reach a conversation, folder or file that the credential's owner could not reach from the browser, and cannot act as any other user.
• Work started through the API appears in its owner's conversation list and in the usage history, with its cost and the model that answered.
• The documentation covers authenticating, starting a run, sending settings, getting the answer and continuing a conversation, with an example that can be copied and run.

Suggested Phasing

1. Machine credentials: create, list, revoke, authenticate.
2. One-shot run: prompt in, answer out, with the core settings — recorded and accounted like any other work.
3. Multi-turn: continue an existing conversation and read back its transcript.
4. Follow a run while it works, instead of only waiting for the end.
5. Approvals and questions over the API, so an external caller can supervise a run rather than only pre-granting it.
6. Documentation and examples.

Open Questions

• Should a credential always act with its owner's full reach, or should it be possible to narrow one to a single project folder, a single runtime, or read-only work?
• When a run needs an approval and nobody is listening, should it wait, fail, or follow a default chosen when the credential was created?
• Should the response carry only the final answer, or optionally the full step-by-step trace the browser shows?
• Should there be a way to be told when a long run finishes — a callback to a caller-supplied address — instead of asking repeatedly?