diff --git a/docs/ZOT-RPC-TRANSCRIPT.md b/docs/ZOT-RPC-TRANSCRIPT.md index 30f641b..526f2c3 100644 --- a/docs/ZOT-RPC-TRANSCRIPT.md +++ b/docs/ZOT-RPC-TRANSCRIPT.md @@ -38,27 +38,12 @@ matches glasspane's `zot_event_type` parser exactly — it reads | `error` | `error` | ✅ Tested | | `done` | `agent_end` | ✅ Tested | -## Event types mapped but not in transcript (need live API key) - -| Event type | Glasspane mapping | Risk | -| ------------------- | ----------------------- | ------------------------------ | -| `assistant_start` | `message_start` | Low — name matches zot source | -| `text_delta` | `message_update` | Low — standard streaming event | -| `assistant_message` | `message_end` | Low — name matches zot source | -| `tool_call` | `tool_execution_start` | Low — name matches | -| `tool_use_start` | `tool_execution_start` | Low — name matches | -| `tool_use_args` | `tool_execution_update` | Low | -| `tool_progress` | `tool_execution_update` | Low | -| `tool_use_end` | `tool_execution_update` | Low | -| `tool_result` | `tool_execution_end` | Low | -| `usage` | None (no state change) | Low | - -## Type values NOT in the current mapping +## 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 +## 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, @@ -69,4 +54,84 @@ 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 remains partially open for that real-key re-run. +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) + +```json +{"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).