RFC 0015: normalized provider→channel stream grammar#16
Conversation
Emit always, archive always, gate only at presentation. Digests the companion spec (openclaw-provider-stream-spec) and references the stacked reference-impl PRs. Extends the agent event I/O contract (#92216) with four [AMENDS BASE] points. Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 8:30 PM ET / 00:30 UTC. Summary Reproducibility: not applicable. This PR proposes RFC documentation rather than a current-main bug reproduction path. Review metrics: 2 noteworthy metrics.
Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Risk before merge
Maintainer options:
Next step before merge
Maintainer decision needed
Security Review detailsBest possible solution: Have maintainers explicitly ratify or amend the RFC’s raw-reasoning archival boundary and final document/harness home, then update acceptance metadata before merge. Do we have a high-confidence way to reproduce the issue? Not applicable: this PR proposes RFC documentation rather than a current-main bug reproduction path. Is this the best way to solve the issue? Unclear: the document is coherent and the prior docs consistency findings look repaired, but accepting the RFC’s security/privacy boundary and final sidecar/harness home is maintainer product judgment. AGENTS.md: not found in the target repository. Codex review notes: model internal, reasoning high; reviewed against a8e0ba2701d6. Label changesLabel changes:
Label justifications:
Evidence reviewedWhat I checked:
Likely related people:
What the crustacean ranks mean
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
Review history (4 earlier review cycles)
|
Add the agent event I/O contract that RFC 0008's [AMENDS BASE] points extend, as the in-tree sidecar rfcs/0008/agent-event-io-contract.md, and repoint the RFC's base-contract reference from the dead docs/channels/agent-event-io-contract.md path to it. The contract was extracted from openclaw/openclaw #92216; the upstream maintainer asked that it be split out of that behavior PR so it could be owned and edited separately from runtime code. This RFC sidecar is that separately-ownable home, and gives the four [AMENDS BASE] points a real, pinned target instead of a path that 404s on openclaw main. Resolves the two base-contract review findings (wrong/missing base path; normative contract living in a mutable external repo) for the base half.
|
The base contract now has a home in the RFC tree ( 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 The PR into this RFC's branch is Marvinthebored#1 (clean, mergeable). It does two things:
This targets the two P2 findings directly:
Two items I deliberately left to @Marvinthebored rather than guess: folding the four |
rfc(0008): vendor agent event I/O contract as pinned base
…act; sync harness count Addresses ragesaq's two follow-ups on #1 and clawsweeper's P3: - Fold §3.2 (thinking emission unconditional, never dropped), §3.3 (item start at earliest id+name), §5.1 (thinking mirrored on its own stream, not as commentary), §7.3 (stable/composite idempotency ids, no synthesized counters) into rfcs/0008/agent-event-io-contract.md, each marked inline "[RFC 0008 amendment]" so the as-split #92216 baseline stays distinguishable. - Repoint the RFC Unresolved note: amendments folded (no longer pending). - Sync harness count 35 -> 37 tests / 28 goldens to match companion STATUS.md. Co-Authored-By: Claude Opus 4.8 <[email protected]>
- Renumber file + sidecar dir + all internal refs (0008-context-engine-runtime-settings was accepted on main in the interim) - Pin the companion spec repo at 0d354d9ed075 - Replace 'stacked draft PRs' reference-impl section with the landed-on-main implementation ledger (#92216 #93343 #95283 #97875 #96106 #98907, #99401 open) - Add explicit 'Reasoning privacy & archival boundary' section (review P1) - Move resolved unresolved-questions (deepseek boundary → #95283; F5 catalogue; base-contract behavior-half → #92216) to a 'Resolved since draft' list Co-Authored-By: Claude Fable 5 <[email protected]>
All seven cited implementation slices are now on main. The privacy-boundary section's open acceptance question for the CLI envelope was answered by the merge; restated as shipped policy awaiting RFC-level ratification. Co-Authored-By: Claude Fable 5 <[email protected]>
… add Shipped: annotations + applying-guide - Vendor stream-grammar-spec.md (from pinned companion @ 0d354d9ed075) — the normative text now lives in the RFC tree; companion keeps evidence + harness - Answer the channel-tier-minimums unresolved question with a concrete proposed T0/T1/T2 table (Discord/Telegram = shipped T1 references) - Per-clause 'Shipped:' annotations tie each Proposal section to its merged PR - New 'Applying this RFC to future work' section (contributor checklist) - Cite independently-reported issues closed by the landings (#96079, #90962) Co-Authored-By: Claude Fable 5 <[email protected]>
Addresses the two P2 review findings: - spec preamble: base-contract path repointed to the in-tree sidecar; stale 'F5 catalogue pending' superseded (completed 2026-06-18) - §7 tier taxonomy unified on the RFC's T0/T1/T2 (legacy A→T1, B→T2, C→T2-with-declared-clamp, D→T0; truth table, worked projections, glossary relabeled; the unrelated 'RATIFIED at T2' decision label disambiguated) Reasoning archival boundary unchanged. Sync delta recorded in the vendoring provenance header. Co-Authored-By: Claude Fable 5 <[email protected]>
|
ClawSweeper status: review started. I am starting a fresh review of this pull request: RFC 0015: normalized provider→channel stream grammar This is item 1/1 in the current shard. Shard 0/1. This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking. Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted. |
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
mainthrough 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
mainitself. Each row is a merged, maintainer-reviewed PR implementing a slice of the grammar (each carries its own live proof in its PR thread):/reasoning onphase: commentarytagging at the parser, display gated downstream/reasoning off|stream|onstreamed-lane gate + core-owned durable commentary (closed openclaw/openclaw#90962)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):
rfcs/0015/stream-grammar-spec.md(from the previously-pinned companion commit0d354d9ed075) — 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.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.
What changed in this revision (2026-07-04)
0008-context-engine-runtime-settingswas accepted onmainin the interim (review finding). File, sidecar dir, and all internal refs updated. (The head branch keeps its original name; branch names are cosmetic.)0d354d9ed075— the normative grammar no longer floats (review finding).Marking ready for review: the remaining open questions are maintainer-preference items, not design blockers. Frontmatter stays
status: draftper the template — acceptance is the maintainers' act at merge.🤖 Generated with Claude Code