Proj/channel protocol (POC)

.gitignore

@@ -31,4 +31,12 @@ agent-tmp
 !.env.example
 
 # ByteRover's skill for Claude Code
-.claude/skills/byterover
+.claude/skills/byterover
+# Phase-5 adapter SDK packages
+packages/agent-sdk/dist/
+packages/agent-sdk/node_modules/
+packages/brv-agent-py/.venv/
+packages/brv-agent-py/dist/
+packages/brv-agent-py/build/
+packages/brv-agent-py/**/__pycache__/
+packages/brv-agent-py/.pytest_cache/

bin/dev.js

@@ -8,7 +8,7 @@ process.env.BRV_ENV = 'development'
 
 // eslint-disable-next-line n/no-unsupported-features/node-builtins
 const root = resolve(import.meta.dirname, '..')
-loadEnv({path: resolve(root, '.env.development')})
+loadEnv({path: resolve(root, '.env.development'), quiet: true})
 
 
 // Inject default command 'main' (represents logic of a single 'brv' run) when no args provided

docs/channel-events.md

@@ -0,0 +1,67 @@
+# Channel Event Kinds
+
+Reference for canonical `kind` values emitted on the channel event stream.
+Used with `brv channel subscribe --kinds <kind1>,<kind2>` (filter to specific
+kinds) or `--all-kinds` (capture everything, for diagnostics).
+
+## Quick-reference: turn flavour → relevant kinds
+
+| Turn flavour | Required kinds to capture |
+|---|---|
+| Local outbound (operator prompt) | `message`, `turn_state_change` |
+| ACP-agent response (codex, kimi, etc.) | `agent_message_chunk`, `delivery_state_change`, `turn_state_change` |
+| Remote-peer response (bridge parley) | `agent_message_chunk`, `delivery_state_change`, `turn_state_change` |
+| Permission gate | `permission_request`, `permission_decision`, `delivery_state_change` |
+| Channel auto-created by bridge | `channel_auto_created` |
+
+**Common mistake:** subscribing with `--kinds message,delivery_state_change`
+for an inbound remote-peer flow will capture zero events because the response
+body is streamed as `agent_message_chunk`, not `message`. The terminal event
+is `turn_state_change` (turn-level), not `delivery_state_change` (member-level).
+
+## Event kind table
+
+| Kind | When emitted | Source | Payload key fields |
+|---|---|---|---|
+| `message` | Operator prompt posted via `brv channel mention` | Local outbound | `content`, `role: 'user'`, `turnId`, `seq` |
+| `agent_message_chunk` | Streaming LLM/agent text delta | Local ACP agent OR inbound remote-peer | `content`, `deliveryId`, `memberHandle`, `seq` |
+| `agent_thought_chunk` | Streaming agent internal thought (visible in verbose mode) | Local ACP agent | `content`, `deliveryId`, `memberHandle`, `seq` |
+| `tool_call` | Agent begins a tool call | Local ACP agent | `toolName`, `callId`, `deliveryId`, `seq` |
+| `tool_call_update` | Tool call result appended | Local ACP agent | `callId`, `output`, `status`, `seq` |
+| `agent_meta` | Agent emits structured metadata (model, version, etc.) | Local ACP agent | `meta`, `deliveryId`, `seq` |
+| `permission_request` | Agent requests operator approval for a sensitive action | Local ACP agent | `permissionRequestId`, `toolName`, `toolCall`, `deliveryId`, `seq` |
+| `permission_decision` | Operator approves or denies a permission request | Operator action | `permissionRequestId`, `decision`, `seq` |
+| `plan` | Agent emits a structured task plan | Local ACP agent | `plan`, `deliveryId`, `seq` |
+| `artifact` | Agent emits a structured artifact (file, code block, etc.) | Local ACP agent | `artifact`, `deliveryId`, `seq` |
+| `delivery_state_change` | A single member's delivery moves to a new state | Local ACP agent, remote-peer response | `deliveryId`, `memberHandle`, `state`, `seq` |
+| `turn_state_change` | The overall turn transitions to a new state | Any terminal delivery | `state` (`completed`/`cancelled`/`errored`), `seq` |
+| `channel_auto_created` | Bob's daemon auto-created a mirror channel for an inbound parley | Bridge inbound (§9.5.4) | `channelId`, `autoProvisionedFrom`, `autoProvisionedAt`, `multiaddr`, `addressability`, `seq` |
+
+## Delivery states (for `delivery_state_change`)
+
+`queued` → `dispatched` → `streaming` → `completed` | `cancelled` | `errored`
+
+A delivery in `awaiting_permission` means the agent is paused waiting for an
+operator decision; use `brv channel approve/deny` to resume it.
+
+## Subscribing for common use-cases
+
+**Wait for any turn to finish:**
+```bash
+brv channel subscribe <channel> --exit-on-terminal
+```
+
+**Wait for a specific agent to finish:**
+```bash
+brv channel subscribe <channel> --roles @codex --kinds delivery_state_change --count 1
+```
+
+**Capture everything for diagnostics:**
+```bash
+brv channel subscribe <channel> --all-kinds --json
+```
+
+**React to auto-created channels (bridge operators):**
+```bash
+brv channel subscribe <channel> --kinds channel_auto_created
+```

docs/curate-protocol.md

@@ -0,0 +1,177 @@
+# `brv curate` tool-mode session protocol
+
+The session protocol lets a calling agent (Claude Code, Cursor, etc.) drive `brv curate` without byterover holding any LLM provider config. ByteRover orchestrates the multi-step flow; the calling agent supplies LLM completions across multiple CLI invocations.
+
+This document defines the wire contract: CLI surface, JSON envelope, lifecycle. SKILL.md authors and other tool consumers key off the shapes documented here.
+
+## CLI surface
+
+### Kickoff
+
+```bash
+brv curate "<user intent>" --format json
+```
+
+Tool mode is the only path for `brv curate` — no provider configuration, no env-var opt-in.
+
+### Continuation — `--session` carries the prior call's id
+
+```bash
+brv curate --session <sessionId> --response "<calling agent's output>" --format json
+```
+
+Presence of `--session` resumes an in-flight session created by a prior kickoff.
+
+### Overwrite intent — `--overwrite` on continuation
+
+```bash
+brv curate --session <sessionId> --response "<calling agent's output>" --overwrite --format json
+```
+
+Default behavior: the writer refuses to clobber an existing topic at the resolved path and returns a `path-exists` correction step carrying the prior file's content. Pass `--overwrite` only when the calling agent has consciously decided to replace prior content. The flag is consumed on the continuation it appears on; subsequent continuations in the same session must repeat it if they still want to overwrite.
+
+### `--format text` fallback
+
+Both kickoff and continuation accept `--format text` for shell users. The output is a terse human digest. The primary consumer (the calling agent) uses `--format json`.
+
+## Wire envelope
+
+Every kickoff and continuation call returns the same JSON envelope under the standard CLI wrapper:
+
+```json
+{
+  "command": "curate",
+  "success": <ok>,
+  "data": {
+    "ok": <bool>,
+    "status": "done" | "needs-llm-step" | "failed",
+    "sessionId": "<uuid>",       // present on needs-llm-step AND on transient failed (see below)
+    "step": "generate-html" | "correct-html",
+    "prompt": "<free-text>",      // free-text instruction for the calling agent's LLM
+    "schema": { ... },            // optional per-step schema slice
+    "errors": [                   // present on correct-html and on failed
+      {
+        "kind": "<machine-readable>",
+        "tag": "<bv-element>?",
+        "attribute": "<attribute-name>?",
+        "message": "<human-readable>"
+      }
+    ],
+    "filePath": "<relative-path>"  // relative to .brv/context-tree/; present when status = done
+  },
+  "timestamp": "<iso>"
+}
+```
+
+### Status values
+
+| `status` | Meaning | Next action for calling agent |
+|---|---|---|
+| `needs-llm-step` | Byterover wants an LLM completion. `prompt` + `step` describe what. | Run the calling agent's own LLM on `prompt`, then `brv curate --session <sessionId> --response "<output>"`. |
+| `done` | Curate complete. `filePath` is the location of the written topic. | Report success to user. Session is cleaned up. |
+| `failed` | Terminal error. `errors[]` explains why. | Report failure to user; abandon session. |
+
+### `step` values (when `status === 'needs-llm-step'`)
+
+| `step` | Meaning | Expected `--response` payload |
+|---|---|---|
+| `generate-html` | First call asking the calling agent to author a `<bv-topic>` document. | The generated HTML. |
+| `correct-html` | A previous response failed validation. `errors[]` enumerates what to fix. | Corrected HTML. |
+
+### Error `kind` values
+
+| `kind` | Lifecycle | Terminal? | Notes |
+|---|---|---|---|
+| `missing-content` | Kickoff | **terminal** | Kickoff invoked without a context argument; no session created |
+| `missing-response` | Continuation | **terminal** | `--session` invoked without `--response`; session unaffected |
+| `invalid-flag-combination` | Continuation | **terminal** | Emitted before any session lookup when a flag is used outside its supported call shape. Today the only producer is `--overwrite` passed without `--session` (legacy curate path does not honour `--overwrite`). |
+| `unknown-session` | Continuation | **terminal** | Session id doesn't exist, was already completed, or fails uuid validation |
+| `empty-response` | Continuation | **transient** (session kept live) | Continuation received an empty `--response`; caller retries with the same `sessionId` |
+| `retry-cap-exceeded` | Continuation | **terminal** | `MAX_ATTEMPTS = 4` (1 generate + 3 corrections) reached without valid HTML; session cleared. Accompanied by the validation errors that pushed the session over the cap. |
+| `missing-bv-topic` | Continuation | **transient** (correction) | Response had zero `<bv-topic>` root elements |
+| `multiple-bv-topic` | Continuation | **transient** (correction) | Response had more than one `<bv-topic>` root |
+| `missing-path-attribute` | Continuation | **transient** (correction) | `<bv-topic>` is missing a non-empty `path` attribute |
+| `unsafe-path` | Continuation | **transient** (correction) | `<bv-topic path>` contains `..` or `.` segments |
+| `unknown-element` | Continuation | **transient** (correction) | Response contains a `<bv-*>` tag outside the closed registry; `tag` field carries the offending name |
+| `attribute-validation` | Continuation | **transient** (correction) | An element's attributes failed its registered validator. `tag` carries the element, `attribute` the offending field. |
+| `path-exists` | Continuation | **transient** (correction) | A topic already exists at the resolved path and `--overwrite` was not passed. The envelope error carries `existingContent` (the prior file's bytes); the correction prompt inlines the same content inside an `<existing-topic path="…">…</existing-topic>` block so the calling agent can merge new content into existing structure. The guard does not clear by re-emitting different content — `--overwrite` is required to write at this path. Default workflow: merge `existingContent` with the new content and re-emit with `--overwrite`. Alternative: choose a different `<bv-topic path>` (no `--overwrite` needed). |
+
+**Terminal vs transient.** Terminal failures end the session — the caller cannot retry the same `sessionId` and must start a new kickoff. Transient failures keep the session alive on disk; the envelope echoes the `sessionId` back and the caller is expected to issue a corrected continuation against it.
+
+**Retry cap.** Each transient correction increments an internal `attempts` counter on the session. After `MAX_ATTEMPTS = 4` consecutive invalid responses (the initial generate plus three corrections) the orchestrator terminates with `retry-cap-exceeded` and clears the session. Calling agents should surface this as "I couldn't produce valid HTML after several attempts; want to try a different framing?".
+
+Calling agents should switch on `kind`, fall back gracefully on unknown kinds, and surface the `message` text to the user.
+
+## Lifecycle — worked example
+
+A complete tool-mode curate session, end-to-end:
+
+### 1. Kickoff
+
+```bash
+brv curate "remember we decided to use RS256" --format json
+```
+
+Response (placeholder):
+
+```json
+{
+  "command": "curate",
+  "success": true,
+  "data": {
+    "ok": true,
+    "status": "needs-llm-step",
+    "sessionId": "8c3f9e2a-...",
+    "step": "generate-html",
+    "prompt": "Generate a <bv-topic>...</bv-topic> HTML document for the following user intent:\n\nremember we decided to use RS256\n\n..."
+  },
+  "timestamp": "2026-05-11T12:00:00.000Z"
+}
+```
+
+### 2. Calling agent's LLM produces HTML
+
+```html
+<bv-topic path="security/auth" title="JWT signing algorithm">
+  <bv-decision id="d-rs256">Use RS256 over HS256.</bv-decision>
+</bv-topic>
+```
+
+### 3. Continuation
+
+```bash
+brv curate --session 8c3f9e2a-... --response "<bv-topic ...>...</bv-topic>" --format json
+```
+
+Response on a valid HTML topic:
+
+```json
+{
+  "command": "curate",
+  "success": true,
+  "data": {
+    "ok": true,
+    "status": "done",
+    "filePath": "security/auth.html"
+  },
+  "timestamp": "2026-05-11T12:00:01.000Z"
+}
+```
+
+If validation fails (e.g. the agent forgot `path=` on `<bv-topic>`), the envelope instead carries `status: "needs-llm-step"`, `step: "correct-html"`, and `errors[]` for the calling agent to fix. Up to 3 corrections (MAX_ATTEMPTS = 4 total) before terminal `status: "failed"` with `kind: retry-cap-exceeded`.
+
+## Session storage
+
+CLI-side. Per-project, on disk at `<projectRoot>/.brv/sessions/curate-<sessionId>/state.json`. State carries `attempts`, `step` (`awaiting-generate` vs `awaiting-correct`), and the last response (for the correction prompt). State is removed when the session reaches terminal `done` or terminal `failed` (including `retry-cap-exceeded`).
+
+Abandoned sessions are not yet pruned — a 1-hour TTL is a planned follow-up that pairs with moving state into the daemon's existing task-session lifecycle.
+
+## Stability promise
+
+SKILL.md ships against this envelope, so renaming any key here is a breaking change. New error kinds and new step values can be added without breaking existing consumers — calling agents are expected to gracefully ignore unknown values.
+
+## What's not the protocol's job
+
+- **HTML generation.** Calling agent's LLM authors the HTML per the `prompt`. Byterover never touches an LLM in tool mode.
+- **Schema knowledge.** Embedded in the `prompt` (the prompt builder condenses the bv-* spec). Calling agent doesn't pre-load any schema.
+- **Retry strategy beyond the protocol's correct-html loop.** If the calling agent's LLM keeps producing invalid HTML for 3 rounds, the session terminates `failed` — the calling agent surfaces this and falls back to asking the user for clarification.

eslint.config.mjs

@@ -8,6 +8,12 @@ const gitignorePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 
 export default [
   includeIgnoreFile(gitignorePath),
+  // Phase-5 monorepo packages (agent-sdk, brv-agent-py) + the byterover-packages
+  // submodule have their own toolchains + ESLint configs (referencing
+  // @workspace/* packages) — skip them from the root lint run.
+  {
+    ignores: ['packages/**'],
+  },
   ...oclif,
   prettier,
   {