Headless JSON protocol
kora send --json and kora chat --json speak a versioned JSONL protocol: one JSON object per line, v:1. stdout is frames only — chrome stays on stderr, so kora ... --json | jq is safe.
One-shot: send –json
Section titled “One-shot: send –json”SID=$(kora new)kora send "$SID" --json "say hi in five words" | jq -c '{type,kind,text}'kora send "$SID" -y --json "list the files in the project root" # -y auto-approves tool callsEach invocation emits event frames and exactly one terminal result frame with outcome (done, aborted, error) and exitCode. With -y, tool calls are auto-approved — no approval-requested event appears.
Multi-turn: chat –json
Section titled “Multi-turn: chat –json”kora chat --json (or kora -r <id> --json to resume) reads request frames from stdin and writes events/responses/results to stdout.
printf '%s\n' \ '{"v":1,"type":"request","id":"r1","op":"prompt","data":{"text":"hello"}}' \ '{"v":1,"type":"request","id":"r2","op":"shutdown"}' \ | kora chat --json | jq -c .typeFrames
Section titled “Frames”| Type | Shape | When |
|---|---|---|
request |
{v,type,id,op,data} |
stdin → kora |
response |
{v,type,id,ok,data?,error?} |
immediate ack/error for a request |
event |
{v,type,sessionId,kind,...} |
streamed turn progress |
result |
{v,type,sessionId,turnId,outcome,error?} |
terminal frame of a turn |
error |
{v,type,error} |
malformed input; the loop keeps reading |
Event kinds include turn-started, note, step-started, text-delta, reasoning-delta, tool-call, tool-result, step-complete, approval-requested, user-input-requested.
| Op | data |
Behaviour |
|---|---|---|
prompt |
{text} |
Queue a turn (queues while busy) |
command |
{name} |
Run a local command |
continue |
{} |
Continue the session |
steer |
{text} |
Inject steering text mid-turn |
cancel |
{} |
Abort the in-flight turn → result{aborted} |
approve |
{id, decision} |
allow / always / deny a pending tool call |
answer |
{id, value} |
Answer a pending user-input request |
shutdown |
{} |
Finish the active turn, then exit |
approve and answer correlate by data.id = the toolCallId field of the matching approval-requested / user-input-requested event.
Shutdown contract
Section titled “Shutdown contract”shutdown cancels a turn in flight, waits for its terminal result{aborted}, replies ok:false "request dropped by shutdown" to each queued request, then exits. A turn never ends without a result frame. EOF on stdin during an approval/input wait unblocks the turn.
Troubleshooting
Section titled “Troubleshooting”- Only
responseframes, no events/result → all requests fired before stdin closed and shutdown raced the queue; upgrade — fixed in the current build, which drains before exiting. resultnever arrives, session showsrunning→ the provider stream can stall without a deadline; check the session’s.status.json, kill the process if the PID is stale — the lock self-heals.approval-requestedblocks forever → nothing approved it. Send{"op":"approve","data":{"id":"<toolCallId>","decision":"deny"}}, or EOF to unblock.- Mixed
--dev/default profile → the session id lives in the other profile’ssessions/dir; keep one profile per pipeline.