Mishka as a task source for orchestrators (MSH-135)
Orchestrators (Orca, Conductor, Kandev, Multica and the like) start coding agents on tasks they pull from somewhere. Mishka can be that somewhere: a small REST feed lists tickets that are ready, and claim, progress and finish map onto the same rules every agent already follows (the ticket lock, receipts, the review move). Mishka still never runs an agent.
Placeholders only: https://mishka.example.com is your Mishka address, mk_YOUR_KEY is a key from Settings > Agents and keys (see connect-an-agent.md). Keep the key in an environment variable, never in a repo or ticket. Give the orchestrator its own agent member and key, so the board names it.
The contract
All calls send Authorization: Bearer $MISHKA_KEY and content-type: application/json. Replies are { "data": ... }; errors are { "error": { code, message, hint } }.
| Step | Call | Maps onto |
|---|---|---|
| List ready tasks | GET /api/v1/tasks?app=KID&limit=20 | issue.list, Todo only |
| Claim | POST /api/v1/tasks/KID-4/claim { "machine": "runner-1", "branch": "msh-4-slug", "tool": "my-orchestrator" } | issue.start: takes the lock, starts a session, returns the context pack |
| Report progress | POST /api/v1/tasks/KID-4/progress { "body": "Tests written, fixing lint" } | issue.comment; any Mishka call also renews the lock |
| Keep the lock alive | POST /api/v1/checkout/ping {} every ~10 minutes | checkout.ping |
| Finish | POST /api/v1/tasks/KID-4/finish { "files_changed": [...], "verified": [{ "what": "tests", "how": "npm test" }], "next_step": "Review the PR", "head_sha": "abc1234", "comment": "PR: https://..." } | issue.finish: receipt, comment, move to review, session done |
What "ready" means. A task is listed when it is in Todo, not blocked and not locked or assigned. Triage and Backlog are never listed (a person decides what is ready). Those filters apply after paging, so a page can hold fewer than limit rows; follow next_cursor until it is absent. since (a cursor from an earlier reply) returns only what changed.
A feed row: { "id": "KID-4", "title": "...", "description": "(first 300 chars)", "priority": ..., "type": ..., "labels": [...], "state": "ready", "claim": "/api/v1/tasks/KID-4/claim" }. The claim reply carries the full ticket, done-means, rules and recent comments; use that as the agent's prompt.
Rules that still apply. Claiming a held ticket answers checkout_held (409) and names the holder: skip it. A claim on a frozen release or a high-risk ticket may come back as a pending approval (HTTP 202, executed: false): do not retry, take another task. Finishing needs a receipt for the current commit; done_means evidence is required when the ticket has done-means. The lock frees itself after 30 minutes of silence. The key needs issues:read to list, issues:write to claim and finish, comments:write for progress.
Shape of a runner loop
BASE=https://mishka.example.com/api/v1
AUTH="Authorization: Bearer ${MISHKA_KEY}"
id=$(curl -fsS -H "$AUTH" "$BASE/tasks?limit=1" | jq -r '.data[0].id // empty')
[ -n "$id" ] && curl -fsS -X POST -H "$AUTH" -H 'content-type: application/json' \
-d '{"machine":"runner-1","tool":"my-orchestrator"}' "$BASE/tasks/$id/claim"
Per orchestrator
We have not verified any of these tools' task-source configuration formats, so none is reproduced here. For each, the recipe is the same: find where the tool lets you plug in a task source (a command, a script, or an HTTP/JSON source), point it at the contract above, and read that tool's own docs for the exact setup.
- Orca. Orca's issue #8376 asks for a task source like this one. Use the contract through whatever command or HTTP hook Orca offers for pulling tasks; see Orca's docs for task-source setup.
- Conductor. Wrap the loop above in a script the tool can call, if it supports script or CLI task sources; see Conductor's docs for task-source setup.
- Kandev. Same: list with
GET /tasks, claim before starting work, finish when done; see Kandev's docs for task-source setup. - Multica. Same; see Multica's docs for task-source setup.
If the tool can only read a Linear- or GitHub-Issues-shaped API, it cannot read this feed directly; wrap the three calls in a small script that prints the shape the tool expects.
Not included
No webhooks or push: the orchestrator polls. No MCP tools were added (the tool list is full); MCP agents keep using issue.start and issue.finish, which are the same operations.