fix: prevent user echo and duplicate snapshots in message:stream

README.md

@@ -1,5 +1,9 @@
 # opencode-a2a-serve
 
+> **Turning OpenCode into a production-ready, stateful Agent API with REST/JSON-RPC endpoints, authentication, streaming, and session management.**
+>
+> **Tech Stack:** Python 3.11+ | FastAPI | A2A SDK | `uv` | `pytest`
+
 `opencode-a2a-serve` is an adapter layer that exposes OpenCode as an A2A service (FastAPI + A2A SDK). It provides:
 
 - A2A HTTP+JSON (REST): `/v1/message:send`, `/v1/message:stream`,
@@ -38,8 +42,9 @@ Additional notes:
 ## Capabilities
 
 - Standard A2A chat: forwards `message:send` / `message:stream` to OpenCode.
-- SSE streaming: `/v1/message:stream` emits incremental
-  `TaskArtifactUpdateEvent`, then `TaskStatusUpdateEvent(final=true)`.
+- SSE streaming: `/v1/message:stream` emits incremental updates and then
+  closes with `TaskStatusUpdateEvent(final=true)`. For detailed streaming
+  contract and event semantics, see `docs/guide.md`.
 - Re-subscribe after disconnect: `GET /v1/tasks/{task_id}:subscribe`
   (available while the task is not in a terminal state).
 - Session continuation contract: clients can explicitly bind to an existing

docs/deployment.md

@@ -396,5 +396,8 @@ Application-level safeguards:
   `GET /v1/tasks/{task_id}:subscribe`
 - service subscribes to OpenCode `/event` stream and forwards filtered
   per-session updates
-- stream emits incremental `TaskArtifactUpdateEvent` (`append=true`) and closes
-  with `TaskStatusUpdateEvent(final=true)`
+- stream emits incremental `TaskArtifactUpdateEvent` with channel metadata
+  (`reasoning` / `tool_call` / `final_answer`)
+- events without `message_id` are discarded to avoid ambiguous correlation
+- final snapshot is emitted only when stream chunks did not already produce
+  the same final answer; stream then closes with `TaskStatusUpdateEvent(final=true)`

docs/guide.md

@@ -55,9 +55,13 @@ This guide covers configuration, authentication, API behavior, streaming re-subs
 - The service forwards A2A `message:send` to OpenCode session/message calls.
 - Task state defaults to `input-required` to support multi-turn interactions.
 - Streaming (`/v1/message:stream`) emits incremental
-  `TaskArtifactUpdateEvent` (`append=true`) and then
-  `TaskStatusUpdateEvent(final=true)`. Full output content is carried in
-  artifacts; non-streaming requests return a `Task` directly.
+  `TaskArtifactUpdateEvent` and then
+  `TaskStatusUpdateEvent(final=true)`. Stream artifacts carry
+  `artifact.metadata.opencode.channel` with values
+  `reasoning` / `tool_call` / `final_answer`. Events without
+  `message_id` are dropped. A final snapshot is only emitted when stream
+  chunks did not already produce the same final answer text.
+  Non-streaming requests return a `Task` directly.
 - Requests require `Authorization: Bearer <token>`; otherwise `401` is
   returned. Agent Card endpoints are public.
 - Within one `opencode-a2a-serve` instance, all consumers share the same