Add kai findings run to trigger a review for a PR

[AdamT]

Why

Starts the exact review a GitHub webhook would start for a PR — from a laptop (or an agent acting on a developer's behalf), against any kai-server — without waiting for GitHub to deliver a webhook.

Implements Task 6 of temp_adam_tasks/local-review/01-trigger-review-api.md.

Note

Depends on kaicontext/kai-server#69, which adds the POST /api/v1/orgs/{org}/repos/{repo}/reviews endpoint this calls. Merge that first — until it lands, this command gets a 404.

Usage

kai findings run --pr 123
kai findings run --pr https://github.com/kaicontext/kai-server/pull/123
kai findings run --pr 123 --repo kai/kai-server --wait

# the whole point of the initiative:
KAI_SERVER=http://localhost:8080 kai findings run --pr 123 --repo demo/hello-kai --wait

Lands under kai findings rather than kai review, which is already taken by changeset reviews — an unrelated concept.

Details worth a look

--pr takes a bare number or a full GitHub PR URL. The URL form is why github_repository is sent separately from --repo: the kai identity (org/repo, which routes the API call) and the real GitHub owner/repo (which the pod clones) can differ. So the URL's repo is authoritative for the review target and is never overridden by the origin remote.

findingsAPIPost is a POST sibling to findingsAPIGet with the same 401/403/404 mapping, plus 409 and 422 surfaced verbatim — the server's "no review workflow matched" guidance reaches the user unreworded. It returns the raw body alongside the error because the 409 carries a run_id worth showing.

A 409 is deliberately not a failure. The review the caller wanted is already running, so we report it and — with --wait — watch the existing run rather than erroring.

--wait polls the existing runs/{id} endpoint and exits non-zero if the run concludes anything but success. A dedicated status endpoint can replace the poll later without changing this command's UX.

Testing

Every genuine failure path returns a non-nil error with non-empty stderr and a non-zero exit — a CLI must not inherit the pipeline's log-and-continue habit, so the tests are table-driven over exactly that. Coverage includes both --pr forms (asserting the URL form populates github_repository from the URL, not the remote), the full status-code matrix against a fake control plane, and --wait returning an error when the run concludes failure even though the trigger itself succeeded.

Full kai-cli suite passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_015ruiguUJAqw6zhfGxgdut6

[kaicontext]

Kai review

✅ Ready to merge — intent verified, nothing flagged.

Check	Result
Intent	Matches
Coverage	No gaps
Risky claims	None

_{+570 −2 · 2 files · reaches 1}

View finding → · Awaiting your verdict — Kai never approves its own finding.