curl -sf -N https://gateway.flocks.local/v1/execute \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "demo-1",
    "task": "Respond exactly: flocks-playground-ok",
    "driver": "codex",
    "auth_token": "ops"
  }'

​
Request

{
  "idempotency_key": "string",
  "task":            "string",
  "driver":          "claude | codex | gemini | …",
  "model":           "string (optional)",
  "auth_token":      "string"
}

​
Response (SSE)

The stream is a sequence of OutputEvent JSON payloads, one per data: line, terminated by a session_end event.

​
Event types

kindFieldsMeaning
agent_tokentext: stringA streamed assistant text delta. Concatenate to render the agent’s reply.
thinkingtext: stringA streamed thinking-mode delta (Claude). Reasoning surface, not part of the user-visible answer.
tool_callid, name, status: "started"|"completed"|"failed", detail?, input?Lifecycle marker for an agent-invoked tool.
tool_resulttool_call_id, output: any, is_error: boolResult of a previously-started tool call.
subagentid, status, labelA nested agent (e.g. Claude Task tool) was spawned.
hookid, name, statusA custom plugin hook (e.g. PreCommit). The lifecycle hooks SessionStart, Stop, Notification are filtered out.
usageinput_tokens, output_tokens, cache_read, cache_writeToken-usage telemetry for this turn.
stdoutline: stringA raw stdout line that did not match any of the structured shapes above.
stderrline: stringA raw stderr line. Suppressed unless the final exit code is non-zero.
session_endexit_code: i32, duration_ms: u64Terminal event. After this, the SSE stream closes.
errormessage: stringInternal failure path on the gateway side (rare; followed by a non-zero session_end).
Every event is forward-compatible: clients should treat unknown kind values as a no-op and continue consuming the stream until session_end. 
data: {"kind":"agent_token","text":"flocks"}

data: {"kind":"agent_token","text":"-playground-ok"}

data: {"kind":"usage","input_tokens":12,"output_tokens":4,"cache_read":0,"cache_write":0}

data: {"kind":"session_end","exit_code":0,"duration_ms":3411}

​
Driver behaviour

The gateway parses each driver’s native stream-json output centrally and maps it to the unified OutputEvent set above. This means every consumer (One, Connect’s Tauri UI, the CLI itself, future SDKs) gets the same semantic stream regardless of which underlying CLI ran.
DriverUnderlying invocationNotes
claudeclaude --print --output-format stream-json --verbose --include-partial-messages <task>text_delta → agent_token; thinking_delta → thinking; tool_use start/stop → tool_call; lifecycle hooks filtered; result usage → usage.
codexcodex exec --json <task>Single result-shaped event per turn; text field → agent_token.
geminigemini --output-format stream-json --prompt <task>text and candidates[0].content.parts[0].text → agent_token.
echobuilt-inOne agent_token carrying the task verbatim, then session_end{exit_code:0}. Reserved for tests.