Dispatch API

External systems can hand a coding task to the bot through an authenticated HTTP endpoint. The bot runs the task, opens a PR with the result, and the caller learns the outcome by watching the PR land on GitHub. This is fire-and-forget — there is no polling, streaming, or cancellation in v1.

This is repo-scoped: one token authorizes one repo. If you need to dispatch against several repos, mint one token per repo.

---

Issuing a token

1. Open the repository’s settings in the dashboard.
2. Go to the Integrations tab.
3. Click Create integration token, optionally giving it a name so you can identify it later (e.g. SEO scout).
4. Copy the token from the dialog immediately. The dashboard never shows it again — only the sha256 hash is stored. If you lose it, create a new one.

Token strings start with vgvbot_ so they’re easy to spot in logs and config files.

To revoke a token, find it in the Integrations tab and click the trash icon. Revocation is immediate.

---

Dispatching a task

Send a POST to the dispatchTask endpoint with the token as a bearer credential:

curl -X POST https://<region>-<project>.cloudfunctions.net/dispatchTask \
  -H "Authorization: Bearer vgvbot_<rest-of-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a button to the home page that opens the settings drawer."
  }'

The response is a JSON object with the new run id:

{ "runId": "h9JfRwn3PqL2vC0aZbXk" }

The endpoint is intentionally narrow:

Field	Required	Meaning
prompt	yes	The task description handed to the coding agent.
model	no	Override the coding agent model for this run.
codingAgent	no	Override which agent runs the task. One of claude-code, gemini-code, opencode.

The owner and repo are derived from the token; there is no body field for either. The caller never has to know the GitHub App installation id.

---

What the bot does

When a task lands on the endpoint:

1. The endpoint validates the bearer token and looks up the repo it’s scoped to.
2. A new task_runs doc is created (status pending) along with a per-run task_tokens doc the runner uses to authenticate back.
3. The Cloud Run job that hosts the coding agent is started with the payload.
4. The runner clones the repo’s default branch, runs the coding agent against the prompt, and opens a PR with the result.

The runner mirrors open_pull_request minus the GitHub issue context — there is no issue or PR to attach a progress comment to, so the run is silent. The PR description is generated from the diff and the prompt.

If the agent reports partial completion (e.g. <<<VGVBOT_STATUS: partial: ...>>>), the PR is opened as a draft with a warning at the top.

---

Security model

Tokens are hashed before storage. The Firestore integration_tokens/{hash} doc carries only:

• owner / repoName / repoKey
• installationId — the GitHub App installation that should run the task
• createdBy — the dashboard user that minted the token
• displayPrefix — the first few characters of the raw token, kept for UI identification only
• name, createdAt, lastUsedAt — metadata

A Firestore breach therefore yields no usable tokens. Cross-repo abuse is bounded by the token-to-repo scoping: a leaked token can dispatch against its repo, nothing else.

The endpoint requires the bearer token to start with vgvbot_ before any Firestore lookup, so a stray task_tokens value sent against /dispatchTask is rejected at parse time.

---

What’s out of scope (v1)

• Streaming task output to the caller
• Polling endpoints to query run status
• Cancellation from the caller
• An MCP server wrapper (planned for interactive agents that want to delegate; the HTTP API stays the load-bearing piece for cron jobs and CI)

The caller learns the outcome by watching the PR land. If a longer-running orchestration is needed, the caller should poll GitHub for the PR rather than the bot.