RFC 0008: normalized provider→channel stream grammar

[Marvinthebored]

Summary

RFC 0008 — Normalized provider→channel stream grammar. Every provider wire format is normalized by core into one event grammar (text, thinking, narration, tools, lifecycle), archived regardless of display, and projected per channel: emit always, archive always, gate only at presentation.

This RFC is the design narrative. The full normative spec, per-family wire-capture evidence, a 35-test conformance harness, and two red-team passes live in the companion repo: https://github.com/Marvinthebored/openclaw-provider-stream-spec

Extends the agent event I/O contract (docs/channels/agent-event-io-contract.md, #92216); four points are marked [AMENDS BASE] and need to land in that doc too.

Reference implementation (stacked draft PRs)

• Core: pipeline: normalized provider→channel stream grammar (core) openclaw#93342
• Discord presentation gate (stacked): pipeline: Discord presentation gate (stacked on core #93342) Marvinthebored/openclaw#2

Status

status: draft per process — kept unmerged while draft. Opening a thread in maintainer-discussion next. Feedback on the [AMENDS BASE] coordination with #92216 and the channel-tier minimums (Unresolved questions) especially welcome.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 20, 2026, 5:54 AM ET / 09:54 UTC.

Summary
Adds a draft RFC and sidecar agent-event I/O contract for normalizing provider streams into a shared channel-facing event grammar.

Reproducibility: not applicable. This PR proposes a new RFC contract rather than reporting a reproducible current-main bug. Source and GitHub review confirm the remaining blockers are process, numbering, ownership, and product/security decisions.

Review metrics: 3 noteworthy metrics.

• RFC ID Collision: 1 existing 0008 RFC, 1 added 0008 RFC, 1 added 0008/ sidecar. The merge result would make the numbered RFC identity and sidecar ownership ambiguous.
• Diff Surface: 2 added Markdown files, 577 added lines, 0 runtime files. The review is about RFC contract correctness and merge policy rather than source execution in this repository.
• Linked Implementation State: 2 open draft implementation PRs. The RFC can be reviewed as design, but merge should not imply the core-plus-channel behavior is implementation-ready.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Renumber the RFC file and sidecar folder to the next unused id and update all relative links.
• Pin, vendor, or inline the normative stream grammar and key evidence before acceptance.
• [P1] Add maintainer-reviewed proof or discussion covering the reasoning archive/display privacy boundary.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body links companion tests and implementation branches, but it does not provide after-change real behavior proof for the proposed accepted contract; contributors should redact private details before posting proof and update the PR body to trigger a fresh review.

Risk before merge

• [P1] Merging as-is would leave two different RFCs with id 0008 and would place this PR's sidecar under a folder name that current main already associates with the accepted Context Engine Runtime Settings RFC.
• [P1] The RFC still makes a mutable personal companion repository the normative stream grammar contract, so accepted behavior could drift outside RFC review unless it is pinned, vendored, or made self-contained.
• [P1] The proposed emit/archive/mirror contract for reasoning is security- and privacy-sensitive and the linked implementation stack is still draft, so acceptance needs explicit maintainer product/security review.

Maintainer options:

1. Renumber And Pin Before Acceptance (recommended)
   Have the author move the RFC and sidecar to an unused id, then pin, vendor, or inline the normative stream grammar and reviewed evidence before maintainers consider acceptance.
2. Keep This As Draft Contract Review
   Maintainers can leave the PR open while the stream grammar, privacy boundary, and linked implementation stack settle.
3. Accept External Contract Ownership Explicitly
   Maintainers could intentionally allow the companion repository to remain normative, but that should be an explicit ownership decision recorded in the RFC.

Next step before merge

• [P1] Human maintainer review is needed because the blockers combine RFC numbering, normative spec ownership, and security-sensitive product direction rather than one safe automated repair.

Security
Needs attention: The RFC is Markdown-only, but it proposes a sensitive reasoning emission/archive/mirroring boundary that needs maintainer security and privacy approval before acceptance.

Review findings

• [P1] Use an unused RFC number and matching sidecar folder — rfcs/0008-provider-stream-grammar.md:1-9
• [P2] Pin the normative stream grammar before acceptance — rfcs/0008-provider-stream-grammar.md:26-30
• [P3] Qualify the OpenClaw core PR reference — rfcs/0008-provider-stream-grammar.md:200-201

Review details

Best possible solution:

Renumber this RFC to an unused id with a matching sidecar folder, keep it draft until maintainer acceptance, and pin or vendor the normative stream spec and evidence before merge.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR proposes a new RFC contract rather than reporting a reproducible current-main bug. Source and GitHub review confirm the remaining blockers are process, numbering, ownership, and product/security decisions.

Is this the best way to solve the issue?

No; the current draft is a useful direction but not the best merge shape until it uses an unused RFC id, pins or vendors the normative spec, and gets maintainer acceptance for the reasoning privacy boundary.

Full review comments:

• [P1] Use an unused RFC number and matching sidecar folder — rfcs/0008-provider-stream-grammar.md:1-9
  Current main already contains accepted rfcs/0008-context-engine-runtime-settings.md, and the README says sidecar material lives under a folder named exactly for the RFC id. Adding another 0008-* file plus rfcs/0008/ would make this contract collide with the existing RFC identity; renumber the RFC and all 0008/ references to an unused id before merge.
  Confidence: 0.95
• [P2] Pin the normative stream grammar before acceptance — rfcs/0008-provider-stream-grammar.md:26-30
  These lines still make the companion repository the normative provider-stream spec while linking only the mutable repository. Before this RFC can be accepted, vendor the normative spec/evidence into the RFC sidecar, pin the companion repo to a reviewed commit, or make the RFC self-contained so the contract cannot drift outside review.
  Confidence: 0.9
• [P3] Qualify the OpenClaw core PR reference — rfcs/0008-provider-stream-grammar.md:200-201
  From inside openclaw/rfcs, a bare #92216 points at the wrong repository context. Use the full https://github.com/openclaw/openclaw/pull/92216 URL or openclaw/openclaw#92216 for the remaining base-contract reference.
  Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 0e353436f90b.

Label changes

Label changes:

• add merge-risk: 🚨 security-boundary: The RFC would ratify emit/archive/mirror behavior for model thinking, which is a sensitive-data boundary requiring maintainer approval.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body links companion tests and implementation branches, but it does not provide after-change real behavior proof for the proposed accepted contract; contributors should redact private details before posting proof and update the PR body to trigger a fresh review.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 📣 needs proof.

Label justifications:

• P3: This is a draft RFC/product proposal with no immediate runtime code change in the RFC repository.
• merge-risk: 🚨 security-boundary: The RFC would ratify emit/archive/mirror behavior for model thinking, which is a sensitive-data boundary requiring maintainer approval.
• merge-risk: 🚨 other: The PR would create an RFC numbering collision and leave the normative contract in an unpinned external repository, which normal CI cannot validate.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body links companion tests and implementation branches, but it does not provide after-change real behavior proof for the proposed accepted contract; contributors should redact private details before posting proof and update the PR body to trigger a fresh review.

Evidence reviewed

Security concerns:

• [medium] Reasoning exposure boundary needs approval — rfcs/0008-provider-stream-grammar.md:93
  The RFC makes wire-carried reasoning emission unconditional and later mirrors thinking to hidden channel subscribers; accepting that as the contract before maintainer approval and proof could ratify a broader sensitive-data exposure model.
  Confidence: 0.86

What I checked:

• Target AGENTS.md check: No AGENTS.md exists inside the target openclaw/rfcs checkout; the only AGENTS.md found was outside this repository checkout. (0e353436f90b)
• RFC lifecycle policy: The README says new RFCs start as pull requests and should not be merged to main while still in draft status, then accepted RFCs get an implementation issue before merge. (README.md:77, 0e353436f90b)
• RFC id and sidecar policy: The README documents one RFC Markdown file named -.md with any sidecar material under a sibling folder named exactly . (README.md:17, f4fdf38f4717)
• Current-main RFC 0008 already exists: Current main already has an accepted RFC 0008 titled Context Engine Runtime Settings, so adding another 0008 file and rfcs/0008/ sidecar would create an ambiguous RFC identity. (rfcs/0008-context-engine-runtime-settings.md:2, 0e353436f90b)
• RFC 0008 provenance on main: The existing RFC 0008 was added by merged PR RFC: Context Engine Runtime Settings #14 at commit 951ec46. (rfcs/0008-context-engine-runtime-settings.md:1, 951ec46d8675)
• PR head adds duplicate RFC id: The proposed RFC is also named and linked as RFC 0008 at the current PR head. (rfcs/0008-provider-stream-grammar.md:1, e6c1aaad245a)

Likely related people:

• kevinlin-openai: Introduced and updated the RFC template and lifecycle guidance that governs draft status and acceptance flow. (role: RFC process contributor; confidence: high; commits: f4fdf38f4717, bbb4058da234, e366ea9825a4; files: README.md, rfcs/0000-template.md)
• RomneyDa: Authored the merged sidecar-layout guidance that is directly relevant to numbered sidecar ownership. (role: recent RFC layout contributor; confidence: high; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)
• ragesaq: Authored the accepted current-main RFC 0008 and contributed the base agent-event sidecar contract into this branch. (role: adjacent contract and RFC contributor; confidence: medium; commits: 951ec46d8675, 7028a7cf2550; files: rfcs/0008-context-engine-runtime-settings.md, rfcs/0008/agent-event-io-contract.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[ragesaq]

The base contract now has a home in the RFC tree (rfcs/0008/).

I collaborated with @Marvinthebored on the preamble/commentary normalization work behind this RFC, and we agreed the base contract it amends should live alongside the RFC so it can be owned and developed here instead of referenced from elsewhere.

That base contract is agent-event-io-contract.md. It was introduced in openclaw/openclaw#92216, then split out of that PR at maintainer request so it could be owned and edited separately from the behavior change. The RFC repo is exactly that separately-ownable home, so I've brought it back as an RFC sidecar.

The PR into this RFC's branch is Marvinthebored#1 (clean, mergeable). It does two things:

1. Adds rfcs/0008/agent-event-io-contract.md: the full 349-line contract (provider input contract, gateway session-mirror contract, channel output contract, test contract, and the ClickClack regression example), matching the rfcs/0007/ sidecar precedent.
2. Repoints the RFC's base reference from docs/channels/agent-event-io-contract.md (which 404s on current main) to the in-tree 0008/agent-event-io-contract.md.

This targets the two P2 findings directly:

• [P2] base-contract reference (L31-32): the four [AMENDS BASE] points now resolve to a real file in-tree, not a path that 404s on main plus a PR that only touched src/gateway/server-chat.*.
• [P2] pin the normative contract (L26-30): the base contract is now vendored in rfcs/0008/ rather than referenced from a mutable personal companion repo.

Two items I deliberately left to @Marvinthebored rather than guess: folding the four [AMENDS BASE] amendments into the contract text itself (the Unresolved-questions note is right that an implementer of the base alone shouldn't build a thinking-dropping gateway), and the P3 harness-count sync (RFC says 35; companion STATUS.md says 37/28). I staged the contract as the as-split baseline so the four deltas get reconciled together.