RFC 0015: normalized provider→channel stream grammar

[Marvinthebored]

Summary

Normalize every provider wire format into one event grammar — final text, thinking/reasoning, narration/commentary, tool activity, usage, errors — emit always, archive always, gate only at presentation. The RFC is the design narrative; the pinned companion spec is the contract; the vendored sidecar (rfcs/0015/agent-event-io-contract.md, from openclaw/openclaw#92216) is the base contract with four explicit [AMENDS BASE] points.

Since this was drafted (2026-06-15), the framework has been substantially ratified by landed commits: its core behaviors were implemented piecewise on main through maintainer-reviewed PRs. This RFC thus seeks to provide the canonical documentation for future or peripheral development, and the normative grammar for the parts not yet upstream.

Real behavior proof — the landed-implementation ledger

The proof for this contract is main itself. Each row is a merged, maintainer-reviewed PR implementing a slice of the grammar (each carries its own live proof in its PR thread):

PR	Merged	Contract slice
openclaw/openclaw#92216	2026-06-13	Base I/O contract behavior-half: gateway mirrors hidden commentary-phase events
openclaw/openclaw#93343	2026-06-16	Codex envelope: commentary dedup via stable-id idempotency
openclaw/openclaw#95283	2026-06-22	F2: reasoning/answer boundary seal under /reasoning on
openclaw/openclaw#97875	2026-06-30	Telegram: durable reasoning, presentation-gated
openclaw/openclaw#96106	2026-07-01	F1 Anthropic: pre-tool phase: commentary tagging at the parser, display gated downstream
openclaw/openclaw#98907	2026-07-03	Telegram: full /reasoning off|stream|on streamed-lane gate + core-owned durable commentary (closed openclaw/openclaw#90962)
openclaw/openclaw#99401	2026-07-04	F1e claude-cli thinking into the same gates

Update 2026-07-05: openclaw/openclaw#99401 has merged — every implementation slice in the ledger is now on main. Its merge also answers, in practice, the reasoning archival/privacy acceptance question for the CLI envelope: the same emit-to-bus / gate-at-presentation model the RFC's privacy-boundary section states.

Update 2026-07-06 (addressing the review's remaining decision points):

• Normative spec vendored in-tree at rfcs/0015/stream-grammar-spec.md (from the previously-pinned companion commit 0d354d9ed075) — the companion repo now holds only evidence goldens + the executable harness. Resolves the "pinned personal repository as normative source" concern; maintainers may still choose a different final home.
• Channel-tier minimums answered with a concrete proposal: a T0 persist-only / T1 editable-draft / T2 native-stream table with per-tier minimum obligations and an all-tiers path-independence rule, anchored on the shipped Discord/Telegram (T1) behavior — proposed for amendment rather than left as an open question. Unresolved questions: 3 → 2 (both pure location/preference calls).
• Per-clause "Shipped:" annotations tie each Proposal section to its merged implementation PR; a new "Applying this RFC to future work" section gives contributors a checklist (new adapter / new channel / display changes / triage); the landings' closure of independently-reported issues (Anthropic models on Discord: reasoning (/reasoning on) and pre-tool narration (/verbose on) are produced but never surfaced in the channel openclaw#96079, Telegram: inter-tool commentary clobbers tool progress in non-persist progress mode (diverges from other streaming channels) openclaw#90962) is now cited.

Update 2026-07-07 (docs repair per the review's two P2 findings): the vendored spec is now internally consistent with the RFC — base-contract reference repointed to the in-tree sidecar, stale "F5 catalogue pending" superseded, and the §7 tier taxonomy unified on the RFC's T0/T1/T2 table (legacy A→T1, B→T2, C→T2-with-declared-clamp, D→T0; truth table, worked projections, and glossary relabeled). The reasoning archival boundary is unchanged; the sync delta is recorded in the vendoring provenance header for auditability against the pinned original.

Update 2026-08-12 (resolves the standing P1, Define the archive access-control precondition):

The finding asked who may read archived reasoning, given that archival is display-independent. The RFC previously deferred to "inherits the session-record store's access control" without naming that model, which left the privacy-sensitive half of emit always, archive always, gate only at presentation unspecified. A new subsection, Archive access-control precondition, names it. Nothing in it proposes new behavior — the seven landed PRs above already work this way.

• Authorized readers. Archive reads require operator.read (or a scope satisfying it) on the session-history RPC/HTTP surface, authorized by negotiated operator scope, independent of client.id / client.mode.
• Enforcement point — a constraint on the projection path, not on the identity of the surface. Some rendering surfaces legitimately hold operator.read: the Control UI and CLI connect as operator clients, and that scope covers chat.history / sessions.list / sessions.subscribe. A role-based boundary would therefore be false. The rule is that projection renders from mirrored events subject to the presentation gate and retrieves no archived content; §7.3's crash-orphaned draft settle reads lifecycle markers only and remains required.
• Scope of the exposure — two classes, not three. §3.2 labels three variants by provenance, but the normative truth table in §4.3 already collapses raw and summary into a single row with a single behavior. Where a provider withholds chain-of-thought and offers a summary instead, that summary is the readable content and is handled identically (Gemini includeThoughts, §6 F5). Encrypted or withheld reasoning is archived as a content-free marker; per the two-store invariant (§2, AS5-02) opaque material never leaves the adapter provider-native transcript, and the archive tap holds displayable content and markers only. Where a provider encrypts its own chain-of-thought, that privacy decision was made upstream at the API and is not OpenClaw's to gate or undo.
• Who that leaves. Two privilege systems bound the answer and they nest: slash commands and directives are honored only for authorized senders (channel allowlists / pairing plus commands.useAccessGroups), while the history read requires operator.read. A channel participant who cannot turn /reasoning back on is not an operator either, and cannot reach the archive at all. That is the distinction the contract preserves — an operator inspecting a session record versus a chat participant from whom output was deliberately gated.
• Retention. No new class and no separate knob; archived thinking ages, compacts, and is deleted with its containing session record.
• Stated rather than glossed. Two caveats a reviewer would otherwise find alone: on a channel whose allowlist is empty or contains "*", directives are effectively open, so the nesting above is a property of a configured deployment rather than a guarantee of the design; and shared-secret bearer auth is upgraded to the full default operator scope set on session-history endpoints even when the caller declares narrower ones.

On the question as posed. The review asked for proof that channel-session scopes cannot read raw thinking. There is no channel-session scope separable from operator.read, so a proof of the literal claim would be either vacuous or an assertion about a boundary the Gateway does not implement. The RFC answers the provable form — the projection path retrieves no archived content — and records the literal boundary (gating raw-thinking fields behind a distinct scope) as a separate RFC rather than foreclosing it.

Sidecars updated to match: normative bullets in the vendored event I/O contract, and §8.2 conformance rewritten into falsifiable cases stating (route, auth mode, effective scopes after negotiation, expected result), with shared-secret HTTP marked as a deliberately allowed case rather than a refusal assertion that would encode a boundary the Gateway does not have.

Commits: 9db11f4, df1b792. AI-assisted; both revisions went through adversarial review passes, which corrected three material errors in the first draft (a false role-based claim, an over-broad prohibition that would have failed §7.3 crash recovery, and two overstated guarantees).

What changed in this revision (2026-07-04)

• Renumbered 0008 → 0015 — 0008-context-engine-runtime-settings was accepted on main in the interim (review finding). File, sidecar dir, and all internal refs updated. (The head branch keeps its original name; branch names are cosmetic.)
• Companion spec pinned at 0d354d9ed075 — the normative grammar no longer floats (review finding).
• New "Reasoning privacy & archival boundary" section — the P1: explicit policy that archival is display-independent by design, no new retention/access/export surface, mirroring stays inside the gateway trust boundary, presentation gates are the only user-facing exposure decision. Stated so maintainers can ratify or amend it, not discover it.
• Reference-impl section → implementation-status ledger (above); the original stacked drafts (pipeline: normalized provider→channel stream grammar (core) openclaw#93342, the Discord overlay) are demoted to lineage.
• Unresolved questions refreshed — deepseek boundary (resolved by fix(openai-completions): seal native reasoning before the answer under /reasoning on openclaw#95283), F5 catalogue completeness, and the base-contract behavior-half moved to "Resolved since the initial draft"; still open: sidecar doc home, channel tier minimums, harness home.
• Sidecar frontmatter moved to byte 0 (parser compatibility).

Marking ready for review: the remaining open questions are maintainer-preference items, not design blockers. Frontmatter stays status: draft per the template — acceptance is the maintainers' act at merge.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 11, 2026, 9:36 PM ET / August 12, 2026, 01:36 UTC.

ClawSweeper review

What this changes

This PR adds RFC 0015 plus two in-tree Markdown contracts defining normalized provider events, session archival, and presentation-gated channel output.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep open: the RFC and its sidecars are not on current main, and accepting its archive-reader rule is a security and product decision rather than routine documentation cleanup.

Priority: P2
Reviewed head: df1b792c3dd75b5d8eb92ff98b05f9b7415540d4
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is a coherent, self-contained documentation proposal, but its security-sensitive runtime assertions require maintainer validation before acceptance.
Proof confidence	🌊 off-meta tidepool	Not applicable: All changed files are Markdown RFC documentation; runtime proof is not required for this docs-only proposal, though its external implementation claims still need owner validation.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All changed files are Markdown RFC documentation; runtime proof is not required for this docs-only proposal, though its external implementation claims still need owner validation.
Evidence reviewed	5 items	RFC is not already on main: Current main has no RFC 0015 document at the proposed path, so this PR remains a distinct documentation contribution. RFC lifecycle requires acceptance: The repository lifecycle keeps draft RFCs out of main until acceptance and requires a maintainer-discussion thread before the acceptance/merge path. RFC-process provenance: Current RFC lifecycle and template guidance was most recently shaped by kevinlin-openai, while Dallin Romney later clarified the sidecar layout used by this PR.
Findings	None	None.
Security	Needs attention	Confirm authorization for archived readable reasoning: The RFC makes operator.read the archive-reader boundary and records shared-secret scope elevation; maintainers should confirm this is the intended security contract before future adapters rely on it.

How this fits together

Provider adapters turn vendor-specific streaming responses into common events; those events are retained in session history and then filtered by each channel’s presentation settings before delivery.

flowchart LR
  A[Provider streams] --> B[Provider adapters]
  B --> C[Normalized event grammar]
  C --> D[Session archive]
  C --> E[Presentation gate]
  E --> F[Channel output]

Loading

Decision needed

Question	Recommendation
Should this RFC accept operator.read, including shared-secret scope elevation, as the authorization boundary for archived readable reasoning, or require a distinct raw-thinking scope before making that contract normative?	Confirm and accept the documented boundary: Validate the current Gateway behavior with the relevant core owner, then accept operator.read as the intended archive-reader scope and merge the RFC through the normal lifecycle.

Why: The PR documents a privacy-sensitive boundary for future adapters and channel projections; repository policy requires a maintainer acceptance decision for a draft RFC, and the runtime implementation was not available here to independently validate the asserted behavior.

Before merge

• Add real behavior proof - Not applicable: All changed files are Markdown RFC documentation; runtime proof is not required for this docs-only proposal, though its external implementation claims still need owner validation.
• Resolve security concern: Confirm authorization for archived readable reasoning - The RFC makes operator.read the archive-reader boundary and records shared-secret scope elevation; maintainers should confirm this is the intended security contract before future adapters rely on it.
• Resolve merge risk (P1) - Merging would make operator.read, including the disclosed shared-secret scope behavior, the normative authorization model for archived readable reasoning without an explicit core security acceptance.
• Resolve merge risk (P1) - The linked OpenClaw implementation and seven-PR ledger could not be independently validated from this RFC-only checkout, so their claimed correspondence to the proposed contract remains unverified in this review.
• Complete next step (P2) - A maintainer must resolve the archive-access security boundary and RFC acceptance path; there is no safe mechanical repair to dispatch.

Findings

• [medium] Confirm authorization for archived readable reasoning

Agent review details

Security

Needs attention: The documentation patch makes a privacy-sensitive archive access rule normative and needs explicit core security acceptance.

Review metrics

Metric	Value	Why it matters
Normative documentation surface	3 Markdown files, +1,501 lines	The PR establishes a broad RFC plus two contracts, so its compatibility and access-control language needs deliberate ownership review.

Merge-risk options

Maintainer options:

1. Confirm the intended archive-reader contract (recommended)
   Before merge, have the relevant core owner verify that the documented session-history scope and shared-secret behavior are intentional and compatible with existing clients.
2. Preserve a narrower reasoning boundary
   Require a distinct authorization rule for readable reasoning before turning this proposal into the normative contract for future adapters and channels.
3. Pause the RFC pending policy direction
   Leave the draft open if maintainers do not yet want to ratify archival access for readable reasoning.

Technical review

Best possible solution:

Adopt one core-owned stream grammar only after maintainers explicitly approve the archived-reasoning access boundary or revise the RFC to require a separate raw-thinking authorization scope.

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

Not applicable: this is a documentation-only RFC. Its claimed runtime behavior needs core-source validation, not a reproduction within the RFC repository.

Is this the best way to solve the issue?

Unclear: vendoring the contract follows the repository’s sidecar pattern, but the readable-reasoning authorization boundary needs explicit maintainer acceptance before this is the best durable solution.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a substantial but non-urgent RFC acceptance decision with no demonstrated current runtime regression.
• merge-risk: 🚨 compatibility: The proposed grammar defines cross-provider and cross-channel behavior that future integrations may treat as a compatibility contract.
• merge-risk: 🚨 security-boundary: The RFC normatively describes who can read archived reasoning and acknowledges shared-secret scope elevation.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: All changed files are Markdown RFC documentation; runtime proof is not required for this docs-only proposal, though its external implementation claims still need owner validation.

Evidence

Security concerns:

• [medium] Confirm authorization for archived readable reasoning
  The RFC makes operator.read the archive-reader boundary and records shared-secret scope elevation; maintainers should confirm this is the intended security contract before future adapters rely on it.
  Confidence: 0.84

What I checked:

• RFC is not already on main: Current main has no RFC 0015 document at the proposed path, so this PR remains a distinct documentation contribution. (rfcs/0015-provider-stream-grammar.md, af708f0ddb6f)
• RFC lifecycle requires acceptance: The repository lifecycle keeps draft RFCs out of main until acceptance and requires a maintainer-discussion thread before the acceptance/merge path. (README.md:78, af708f0ddb6f)
• RFC-process provenance: Current RFC lifecycle and template guidance was most recently shaped by kevinlin-openai, while Dallin Romney later clarified the sidecar layout used by this PR. (README.md:73, e366ea9825a4)
• Security-sensitive normative update: The PR head adds the RFC and states that archive reads use operator.read, including the documented shared-secret scope behavior; this is a normative access-boundary decision, not a mechanical docs correction. (rfcs/0015-provider-stream-grammar.md, df1b792c3dd7)
• External implementation verification unavailable: This sparse RFC checkout does not contain the linked OpenClaw runtime source; attempting to read the PR-head object required a remote fetch that failed because GitHub DNS was unavailable, so the claimed runtime ledger was not independently verified here. (df1b792c3dd7)

Likely related people:

• kevinlin-openai: Authored the current RFC-process and template updates that define the acceptance lifecycle for this proposal. (role: RFC-process author; confidence: high; commits: e366ea9825a4, bbb4058da234; files: README.md, rfcs/0000-template.md)
• Dallin Romney: Most recently clarified the RFC sidecar layout that this RFC uses for its two normative supporting documents. (role: sidecar-layout contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)
• ragesaq: Contributed the vendored agent-event I/O contract referenced by this RFC and explained its intended RFC ownership in the PR discussion. (role: base-contract contributor; confidence: medium; commits: 7028a7cf2550; files: rfcs/0015/agent-event-io-contract.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain a core-owner decision on the archive-reader authorization boundary.
• Confirm the RFC lifecycle discussion and acceptance path required by the repository README.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (15 earlier review cycles; latest 8 shown)

• reviewed 2026-07-30T14:35:30.227Z sha e34b6cf :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T17:58:13.138Z sha e34b6cf :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T19:47:08.812Z sha e34b6cf :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T15:20:09.666Z sha e34b6cf :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T20:36:18.041Z sha e34b6cf :: needs real behavior proof before merge. :: [P1] Resolve the archive access-control precondition
• reviewed 2026-08-02T09:40:40.808Z sha e34b6cf :: needs real behavior proof before merge. :: [P1] Define the archive access-control precondition
• reviewed 2026-08-02T17:06:46.436Z sha e34b6cf :: needs real behavior proof before merge. :: [P1] Define the archive access-control precondition
• reviewed 2026-08-12T01:08:11.883Z sha 9db11f4 :: needs real behavior proof before merge. :: none

[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.

[Marvinthebored]

Pushed df1b792 addressing the standing P1, Define the archive access-control precondition. The description carries the full explanation under Update 2026-08-12; briefly:

The RFC previously deferred to "inherits the session-record store's access control" without naming that model. It now names the authorized readers (operator.read on the session-history surface), states the enforcement point as a constraint on the projection path rather than on the identity of the surface — some rendering surfaces legitimately hold that scope — and scopes the exposure to readable thinking only, since encrypted reasoning is archived as a content-free marker and opaque material never leaves the adapter transcript per the two-store invariant (§2, AS5-02).

On the finding as worded: there is no channel-session scope separable from operator.read, so the RFC answers the provable form (the projection path retrieves no archived content) and records the literal boundary — a distinct raw-thinking scope — as a separate RFC rather than foreclosing it. §8.2 conformance is rewritten into falsifiable cases, with shared-secret HTTP marked as a deliberately allowed case rather than a refusal assertion that would encode a boundary the Gateway does not have.

Two inherited limits are disclosed in the text rather than left implicit: an empty or "*" channel allowlist leaves directives effectively open, and shared-secret bearer auth is upgraded to the default operator scope set on session-history endpoints.