#OpenSeek Protocol

{"event":"assistant_delta","content":"Hel"}

#Why it exists

• tool_result was emitted with brief from one site and without it from two.
• mcp_connect_failed was emitted with error from one site and without it from another.
• compaction_failed was reported at warn from one site and error from two.

• reasoning_delta had not been emitted since 2026-06-21 (a85d5682), yet the TUI and the desktop both still decoded it under tests that passed on fabricated lines. The agent now emits it unconditionally; interactive clients render it live, while other consumers may ignore the high-volume stream.
• runtime_update had not been emitted since 2026-07-05 (4b1ec831), yet the desktop host still decoded it, likewise under a passing test.
• The desktop host synthesized compaction_failed with reason while the engine writes error, under a comment claiming "the same wire shape the engine emits". One decoder happened to accept both spellings, so nothing noticed.

#API

// Report an event. The line is `to_json`, nothing more.
@emit.emit(AssistantDelta(content="Hel"))
@emit.emit(AgentAborted(reason="interrupted"))

// Or build the line without logging it — what the desktop host forwards for a
// compaction whose engine died before reporting one itself.
let line = CompactionFailed(error="engine exited").to_json()

// Read one back. `None` means "not an event this engine emits" — an unknown
// name or a malformed payload — so a client stays tolerant of a newer engine.
match @protocol.parse(line) {
  Some(AssistantDelta(content~)) => render(content)
  Some(_) | None => ()
}

#When a field may be absent

#The command direction

// A controller writes a line.
let line = (Prompt(text="do it") : @protocol.Command).to_jsonl()

// The engine reads one back. `Err` is a line it cannot read — and only that:
// whether a readable command is *acceptable* is the engine's to say, which is
// why `serve`, not `parse`, refuses a blank goal.
match @protocol.Command::parse(line) {
  Ok(Prompt(text~)) => start_turn(text)
  Ok(_) => ()
  Err(message) => report(message)
}

#Invariants

• parse is emit's inverse for every variant. emit/emit_test.mbt pins this per sample — it needs both halves, so it lives with the writer; it is the property the package exists to provide.
• Optional string fields are written as the value or null, never omitted. A field's own ToJson would encode Some(v) as the one-element array [v], which every decoder's string lookup rejects — silently turning a present field into an absent one. or_null is why, and the round-trip test is what caught it.
• Usage is owned here, not borrowed from the provider. It is structurally identical to @deepseek.Usage — same fields, same order, same JSON — and deliberately a separate type. The wire format must not be whatever a vendor's response struct happens to be, and this module cannot depend on the engine's provider layer without a cycle. agent's wire_usage is the single place the two meet.

#Known gaps

• The stream has no clock. timestamp and source were the log envelope's; events are not log entries, so a line does not say when it was written or where it was emitted. A client that needs ordering uses stream order (the engine writes events in order), and one that needs an authoritative time uses the durable session record.