colibri/docs/ZOT-RPC-TRANSCRIPT.md

zot rpc transcript — DeepSeek (2026-06-21)

Request shape

{"id":"1","type":"prompt","message":"check the current directory"}

zot uses its own protocol, NOT JSON-RPC 2.0. The type field is prompt, id is a correlation string.

Raw stdout (secrets redacted, auth failed — key was placeholder)

{"command":"prompt","data":{"started":true},"id":"1","success":true,"type":"response"}
{"content":[{"text":"check the current directory","type":"text"}],"time":"2026-06-21T22:36:06.817Z","type":"user_message"}
{"step":1,"type":"turn_start"}
{"error":"deepseek: http 401: ...","stop":"error","type":"turn_end"}
{"message":"deepseek: http 401: ...","type":"error"}
{"type":"done"}

Wire format decision

Bare event objects. Each line is a plain JSON object with a type field. No JSON-RPC envelope (no jsonrpc, method, params wrapping). This matches glasspane's zot_event_type parser exactly — it reads value.get("type") directly from the object.

Event types observed

Event type	Glasspane mapping	Status
response (success:true)	None (no state change)	✅ Correct
user_message	message_update	✅ Tested
turn_start	turn_start	✅ Tested
turn_end	turn_end	✅ Tested
error	error	✅ Tested
done	agent_end	✅ Tested

Type values NOT in the current mapping (phase 1 transcript)

None observed. All 6 event types from the transcript have mappings. The response type with success:true correctly returns None (no state change).

Verdict (phase 1 — placeholder key)

Wire format confirmed: bare event objects, no JSON-RPC envelope. Glasspane's parser shape is correct. The session-lifecycle events (turn_start, turn_end, error, done, user_message, response) are validated against real output.

Tool-lifecycle events (tool_call, tool_use_*, text_delta, assistant_*, tool_result) are NOT yet validated — the API key was a placeholder (DeepSeek returned 401 before reaching the agent loop). A re-run with a valid DEEPSEEK_API_KEY is needed to capture a real tool call before the driver can trust those mappings.

Step 1 of colibri#143 is complete after the real-key re-run below. Steps 2 and 3 are unblocked.

Real-key transcript (complete tool call, 2026-06-21)

Prompt: "run uname -a and tell me the kernel version in one sentence" 61 lines, 2 turns, 1 tool call (bash), DeepSeek v4-pro, cached tokens.

Raw stdout (secrets redacted)

{"command":"prompt","data":{"started":true},"id":"1","success":true,"type":"response"}
{"content":[{"text":"run uname -a and tell me the kernel version in one sentence","type":"text"}],"time":"...","type":"user_message"}
{"step":1,"type":"turn_start"}
{"type":"assistant_start"}
{"id":"call_00_...","name":"bash","type":"tool_use_start"}
{"delta":"{","id":"call_00_...","type":"tool_use_args"}
{"delta":"\\"command\\": \\"uname -a\\"","id":"call_00_...","type":"tool_use_args"}
{"delta":"}","id":"call_00_...","type":"tool_use_args"}
{"id":"call_00_...","type":"tool_use_end"}
{"cache_read":896,...,"type":"usage"}
{"stop":"tool_use","type":"turn_end"}
{"id":"call_00_...","text":"FreeBSD osa.smilepowered.org 15.0-RELEASE-p10...\\n","type":"tool_progress"}
{"content":[{"text":"$ uname -a\\n...","type":"text"}],"id":"call_00_...","is_error":false,"type":"tool_result"}
{"step":2,"type":"turn_start"}
{"type":"assistant_start"}
{"delta":"This","type":"text_delta"}
{"delta":" system","type":"text_delta"}
... (streaming text deltas, 30+ lines) ...
{"cache_read":896,...,"type":"usage"}
{"stop":"end","type":"turn_end"}
{"type":"done"}

Full 61-line transcript at /tmp/zot_transcript_full.txt (OSA).

Confirmed event types (real-key run)

Event type	Glasspane maps to	Notes
response (success:true)	None (no state change)	Command ack
user_message	message_update
turn_start	turn_start	step field for turn number
assistant_start	message_start	Before text or tool use
tool_use_start	tool_execution_start	zot uses tool_use_* — not bare tool_call — for streamed tool events
tool_use_args	tool_execution_update	Delta-streamed character by character
tool_use_end	tool_execution_update	Args complete
usage	None	cache_read, cache_write, cost_usd, cumulative
assistant_message	message_end	Two contexts: tool-call content block AND final text response
tool_call	tool_execution_start	Mapped by glasspane; NOT present in this run's raw stdout — see note
turn_end	turn_end	stop: "tool_use" (waiting) or "end" (finished)
tool_progress	tool_execution_update	Streaming tool output
tool_result	tool_execution_end	is_error field present
text_delta	message_update	Streaming text response
done	agent_end	Session end

Glasspane gaps

14 of 15 mapped types were observed. The tool cycle in this run used tool_use_start/args/end → tool_progress → tool_result (see raw stdout above) — no standalone {"type":"tool_call"} line appeared.

Open (for step 2): glasspane maps BOTH tool_use_start and tool_call to tool_execution_start. If zot also emits a standalone tool_call on some path, tool_execution_start would fire twice per tool call and the driver must treat the second as a no-op/confirmation. That double-fire was NOT observed here — the raw stdout shows only tool_use_*. Confirm against the full transcript whether tool_call ever fires before the driver relies on either behaviour; if it never does, tool_call is dead code in glasspane's mapping for this path.

Verified facts (observed, not inferred from source)

• tool_use_start/args/end for streamed tool calls (no standalone tool_call seen this run)
• text_delta streams response text character by character
• assistant_message appears in two contexts (tool block + final text)
• turn_end.stop distinguishes "tool_use" vs "end"
• tool_result carries is_error boolean
• usage carries cache_read, cache_write, cost_usd, cumulative

Step 1 of colibri#143 is complete — wire format and 14/15 event types validated against real output. One open item: confirm whether tool_call ever fires (see the step-2 note above).