Events and the socket

A turn is a stream of events exactly as the olix core emitted them. Each carries protocol (olix.codeui/1), type, session_id, request_id (the turn id), seq and ts. The last event of a turn is always task_complete, unless the core goes away, in which case an error event says so; the API never invents a completion.

A turn can also emit open_in_editor, answer_verification, auto_verify, plan_ready, inference_progress, compaction, memory_used and jobs. They are passed through unchanged. Clients must ignore event types they do not know.

Server-Sent Events

On POST /v1/turns each event is one SSE message: event: <type> and data: <json>. The turn id is also in the X-Olix-Turn header.

curl -sN http://127.0.0.1:8780/v1/turns \
  -H "Authorization: Bearer $OLIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Say hello in five words.", "cwd": "/tmp/olix-demo/project"}'

event: accepted
data: {"protocol":"olix.codeui/1","type":"accepted","request_id":"t_abd196b48cf83e93","session_id":"20261106132214-54f2e5"}

event: memory_used
data: {"fact_ids":[],"style":["length"],"ms":0.3,"protocol":"olix.codeui/1","type":"memory_used","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":0,"ts":1793971334.525,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":1}

event: assistant_start
data: {"protocol":"olix.codeui/1","type":"assistant_start","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":1,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":2}

event: assistant_delta
data: {"text":"stand-in reply to: Say hello in five words.","protocol":"olix.codeui/1","type":"assistant_delta","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":2,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":3}

event: assistant_end
data: {"text":"stand-in reply to: Say hello in five words.","protocol":"olix.codeui/1","type":"assistant_end","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":3,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":4}

event: usage
data: {"prompt_tokens":5,"cached_tokens":0,"output_tokens":1,"tok_s":0,"context_pct":0,"ttft_ms":1,"pass_id":"call_mw507ouf2","model":"olx-1","kind":"chat","protocol":"olix.codeui/1","type":"usage","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":4,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":5}

event: task_complete
data: {"outcome":"answered","text":"stand-in reply to: Say hello in five words.","result":{"state":"completed","answer":"stand-in reply to: Say hello in five words.","summary":"stand-in reply to: Say hello in five words."},"protocol":"olix.codeui/1","type":"task_complete","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":5,"ts":1793971334.549,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":6}

Event types

The NDJSON socket

The same API as NDJSON on a mode-0600 unix socket, for local tools that prefer it. The first line must be {"type":"auth","token":"..."}; then each line is one of the client messages below and replies are NDJSON events carrying the same request_id. Socket path: ~/.olx/api/api.sock. The gateway must be running.

Messages the socket accepts:

• auth
• input
• interrupt
• answer
• sessions
• history_list
• history_get
• history_search
• status
• settings_schema
• workspace_changes

The events of a turn carry the request_id you sent with the input (letters, digits, . _ -, up to 64). Replies to commands are info messages with the same request_id; failures are error messages. Anything outside this list gets bad_request: the socket is not a door to the rest of the core.

auth

interrupt

answer

Example

import json, os, socket, sys
s = socket.socket(socket.AF_UNIX); s.connect(sys.argv[1]); f = s.makefile("rw")
def send(o): f.write(json.dumps(o) + "\n"); f.flush()
send({"type": "auth", "token": os.environ["OLIX_API_TOKEN"]}); print(f.readline().strip())
send({"type": "input", "text": "Say hello in five words.", "cwd": sys.argv[2], "request_id": "r1"})
for line in f:
    ev = json.loads(line)
    if ev["type"] in ("accepted", "assistant_end", "task_complete"): print(line.strip())
    if ev["type"] == "task_complete": break

{"protocol":"olix.codeui/1","type":"info","command":"auth","result":{"app":"sample-app","scopes":["chat","models"]}}
{"protocol":"olix.codeui/1","type":"accepted","request_id":"r1","session_id":"20261106132216-883a92"}
{"text":"stand-in reply to: Say hello in five words.","protocol":"olix.codeui/1","type":"assistant_end","session_id":"20261106132216-883a92","request_id":"r1","seq":3,"ts":1793971336.587,"epoch":"c2d867b0-1dd2-4891-a4e2-3f5b281f25e0","session_seq":4}
{"outcome":"answered","text":"stand-in reply to: Say hello in five words.","result":{"state":"completed","answer":"stand-in reply to: Say hello in five words.","summary":"stand-in reply to: Say hello in five words."},"protocol":"olix.codeui/1","type":"task_complete","session_id":"20261106132216-883a92","request_id":"r1","seq":5,"ts":1793971336.641,"epoch":"c2d867b0-1dd2-4891-a4e2-3f5b281f25e0","session_seq":6}