From 6b9222c746bfcf5911805e8bfaa5f9bb27fffe86 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 22:36:51 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20zot=20rpc=20transcript=20=E2=80=94?= =?UTF-8?q?=20wire=20format=20confirmed=20for=20glasspane?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 1 of colibri#143. Captured with zot rpc --provider deepseek. Wire format: bare event objects (no JSON-RPC envelope), matches glasspane's zot_event_type parser. All 6 observed types mapped. Remaining types (tool_call, text_delta, etc.) need a live API key but type names match zot source. Verdict: glasspane parser is correct. Steps 2-3 unblocked. --- docs/ZOT-RPC-TRANSCRIPT.md | 72 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/ZOT-RPC-TRANSCRIPT.md diff --git a/docs/ZOT-RPC-TRANSCRIPT.md b/docs/ZOT-RPC-TRANSCRIPT.md new file mode 100644 index 0000000..a24b6dc --- /dev/null +++ b/docs/ZOT-RPC-TRANSCRIPT.md @@ -0,0 +1,72 @@ +# zot rpc transcript — DeepSeek (2026-06-21) + +## Request shape + +```json +{"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) + +```json +{"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 | + +## 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 + +None observed. All 6 event types from the transcript have mappings. +The `response` type with `success:true` correctly returns None (no state change). + +## Verdict + +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 remains partially open for that real-key re-run. -- 2.45.3 From 1242c52360238957bfbca780ae332b3816324f22 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 22:46:07 +0200 Subject: [PATCH 2/2] docs(zot-rpc): backtick event identifiers in the verdict The bare underscored names (tool_call, tool_use_*, text_delta, assistant_*) were read as markdown emphasis and mangled by prettier; wrap them in code spans so they render literally and stay prettier-immune. Co-Authored-By: Claude Opus 4.8 --- docs/ZOT-RPC-TRANSCRIPT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ZOT-RPC-TRANSCRIPT.md b/docs/ZOT-RPC-TRANSCRIPT.md index a24b6dc..30f641b 100644 --- a/docs/ZOT-RPC-TRANSCRIPT.md +++ b/docs/ZOT-RPC-TRANSCRIPT.md @@ -64,7 +64,7 @@ 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) +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. -- 2.45.3