From 1dfd57ca723704bf90e9bcde52129f9c6c5cbf8e Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 11 Aug 2026 11:25:26 -0700 Subject: [PATCH 01/33] docs: propose OpenClaw Control Model Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 398 +++++++++++++++++++++ rfcs/0029/conformance-and-adoption-plan.md | 173 +++++++++ rfcs/0029/control-model-v1-spec.md | 305 ++++++++++++++++ rfcs/0029/implementation-plan.md | 207 +++++++++++ rfcs/0029/ui-artifact-v1-spec.md | 255 +++++++++++++ 5 files changed, 1338 insertions(+) create mode 100644 rfcs/0029-openclaw-control-model.md create mode 100644 rfcs/0029/conformance-and-adoption-plan.md create mode 100644 rfcs/0029/control-model-v1-spec.md create mode 100644 rfcs/0029/implementation-plan.md create mode 100644 rfcs/0029/ui-artifact-v1-spec.md diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md new file mode 100644 index 00000000..a55f2797 --- /dev/null +++ b/rfcs/0029-openclaw-control-model.md @@ -0,0 +1,398 @@ +--- +title: OpenClaw Control Model +authors: + - Gio Della-Libera +created: 2026-08-11 +last_updated: 2026-08-11 +status: draft +issue: +rfc_pr: +--- + +# Proposal: OpenClaw Control Model + +## Summary + +OpenClaw should provide a framework-neutral Control Model above +`@openclaw/gateway-client`. The model would expose immutable state snapshots, +typed commands, history/live reconciliation, and renderer-neutral UI artifacts +without depending on Lit, React, routes, or product presentation. OpenClaw's +Control UI and independently owned product shells could consume the same +behavior while retaining their own components, navigation, theming, +authentication, and rollout. + +This document is a fork-only design preview. It does not request RFC intake, +open an upstream pull request, or claim maintainer acceptance. + +## Motivation + +OpenClaw already publishes a reference Gateway client. It owns protocol +handshake, authentication helpers, request correlation, timeouts, reconnect +primitives, sequence-gap detection, and event delivery. + +OpenClaw's Control UI builds a richer application model above that client: +session catalogs, history/live reconciliation, connection epochs, chat stream +state, tool lifecycle, approvals, config state, and other capabilities. That +model is assembled inside the Lit application and is not a supported headless +consumer boundary. + +An independently owned UI therefore has two unattractive choices: + +1. host or fork OpenClaw's complete Control UI even when the product needs a + different framework and experience; or +2. consume raw Gateway methods and events and independently reimplement the + state machines already required by Control UI. + +The first choice couples product presentation to OpenClaw's application. The +second creates semantic drift around reconnect, event ordering, history +reconciliation, tool outcomes, approvals, and compatibility. + +Tool-provided UI has a related gap. OpenClaw can materialize Canvas documents +and MCP Apps, but the current projection selects those presentation paths +before another host can choose a trusted native renderer. First-party products +that need native components either add tool-specific interpretation or bypass +the existing projection. + +The desired architecture is: + +```text +OpenClaw Gateway + | +@openclaw/gateway-client + | +@openclaw/control-model + snapshots / commands / UI artifacts + | + +-------------------------+ + | | +OpenClaw Control UI Independent product shell +Lit presentation React/native presentation +``` + +One OpenClaw-owned behavioral model can serve multiple presentations without +making OpenClaw own those products. + +## Goals + +- Publish a framework-neutral state and command boundary above the Gateway + client. +- Keep Gateway protocol and server behavior authoritative. +- Provide stable immutable projections for connection, session catalog, and a + selected conversation. +- Reconcile history, live events, reconnects, and tool lifecycle once. +- Return typed command failures without success-shaped fallbacks. +- Preserve renderer-neutral UI artifacts long enough for a host to select a + native renderer, structured fallback, or sandboxed MCP App. +- Let OpenClaw Control UI become a reference adopter without changing its + presentation. +- Support independently owned browser, desktop, mobile, terminal, and hosted + shells without importing a UI framework. +- Make adoption incremental and tie each layer to conformance and deletion + evidence. + +## Non-Goals + +- Replacing `@openclaw/gateway-client` or introducing another wire protocol. +- Standardizing routes, navigation, layout, CSS, theme, localization, or + product design systems. +- Moving product-owned React, Lit, native, or terminal components into the + Control Model. +- Publishing Control UI's complete internal `ApplicationContext` as-is. +- Defining browser credential storage, tenant authentication, runtime routing, + or host deployment. +- Making UI visibility, disabled state, or command preflight authoritative. +- Loading executable React components or arbitrary JavaScript named by a tool + result. +- Replacing MCP Apps as the sandboxed third-party executable-UI contract. +- Requiring JSON Render or any other renderer library. +- Adding a sidecar, service, or new process boundary. The Control Model is an + in-process library over an existing Gateway client. +- Defining generic model-authored dashboards, arbitrary layout generation, or a + public component marketplace in v1. +- Including config forms, settings navigation, channels, skills, workboards, + or every existing Control UI capability in v1. + +## Proposal + +The normative candidate contracts and delivery gates are split into companion +documents: + +- [Control Model v1 specification](0029/control-model-v1-spec.md) +- [UI artifact v1 specification](0029/ui-artifact-v1-spec.md) +- [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) +- [Implementation and PR plan](0029/implementation-plan.md) + +### Package boundary + +Add `@openclaw/control-model` to the OpenClaw monorepo. The package is +framework-neutral and browser-safe. Its public module graph must not import +Lit, React, DOM components, route definitions, product authentication, +localization catalogs, CSS, or Control UI presentation helpers. + +The package consumes a narrow host-supplied Gateway binding compatible with the +public Gateway client: + +```ts +export interface ControlGateway { + getSnapshot(): GatewayConnectionSnapshot; + subscribe(listener: () => void): () => void; + subscribeEvents(listener: (event: GatewayEvent) => void): () => void; + request(method: string, params?: unknown, options?: RequestOptions): Promise; +} +``` + +The binding lets the package reuse OpenClaw's browser, Node, or hosted transport +without owning credential persistence, product routing, or socket creation. + +The Control Model exposes immutable snapshots and typed commands: + +```ts +export interface ControlModel { + getSnapshot(): ControlSnapshot; + subscribe(listener: () => void): () => void; + conversation(sessionKey: string): ConversationModel; + sessions: SessionCommands; + dispose(): void; +} +``` + +Subscriptions are invalidation signals. Consumers read the current immutable +snapshot after notification. This works with framework adapters without +embedding framework hooks in the package. + +### V1 capability boundary + +V1 contains: + +- connection phase, accepted protocol/session metadata, and structured errors; +- session catalog snapshots and refresh/reconciliation state; +- one or more lazily selected conversation models; +- canonical ordered messages; +- active run, stream, tool invocation, approval, and question state needed by + conversation presentation; +- typed chat/session commands supported by the selected Gateway; and +- renderer-neutral UI artifacts associated with messages or tool invocations. + +V1 excludes broader Control UI capabilities until each has a bounded, +framework-neutral contract and an independent consumer. + +### Snapshot and event semantics + +Snapshots are serializable except for explicitly documented command handles. +They use stable identifiers, finite retained state, and typed lifecycle states. +They do not expose mutable Control UI objects. + +The package owns: + +- the initial history snapshot; +- live event application; +- connection-epoch retirement; +- duplicate and stale event handling; +- explicit sequence-gap and partial-state presentation; +- reconnect resynchronization; +- tool invocation/result association; +- cancellation and terminal run reconciliation; and +- artifact association and revision ordering. + +Raw Gateway events remain available from the Gateway client. They are not the +Control Model's stable UI contract. + +### Command semantics + +Commands express typed user intent. Candidate v1 commands include session +refresh, select, create, rename, archive/delete where authorized, chat send, +abort, retry where supported, answer, approve, and deny. + +The model may expose command availability for presentation. The Gateway remains +authoritative. A command must return a typed result or throw a typed error. It +must not silently treat a rejected, stale, disconnected, or unsupported +operation as success. + +Commands are connection- and session-aware. An operation captured under a +retired connection epoch must not execute against a replacement session unless +the command contract explicitly permits safe retry. + +### Renderer-neutral UI artifacts + +A UI artifact is data and identity, not executable presentation: + +```ts +export interface UiArtifact { + id: string; + revision: number; + templateUri: string; + dataVersion: number; + data: JsonValue; + structuredContent?: JsonValue; + state: "pending" | "ready" | "failed" | "expired"; + source: { + sessionKey: string; + messageId?: string; + toolCallId?: string; + }; + fallback?: McpAppArtifact | CanvasArtifact; +} +``` + +`templateUri` is opaque. It does not grant trust, select a JavaScript import, +or authorize an action. A host may map a locally registered URI to a native +component. It must schema-validate artifact data before rendering. If no native +renderer is registered, the host may show structured/text output or use an +explicit sandboxed fallback. + +`dataVersion` selects a schema version within the host's exact local +registration. Registration and component code ship through the host's ordinary +reviewed supply chain; tool output cannot add, replace, or widen a registration. + +V1 uses complete immutable revisions. It does not standardize JSON Patch, +JSONL, or a renderer-specific component tree. A later extension may introduce a +negotiated patch dialect after conformance evidence demonstrates a shared need. + +### Security boundary + +The Control Model is presentation support, not an authorization authority. + +- Native renderers are registered and allowlisted by the host. +- Tool output cannot select an import path, module URL, or privileged action. +- Artifact data is untrusted input with finite size and depth. +- Artifact data and structured content remain separate from hidden model or + credential state. +- Component actions call named host bindings that re-enter typed model commands. +- The Gateway independently authorizes every protected action. +- Native action audit and telemetry can correlate the renderer registration, + artifact ID, revision, action name, session, and tool call without recording + raw artifact data. +- MCP Apps and Canvas retain their sandbox, CSP, lifecycle, and capability + boundaries. +- Unknown versions, malformed data, expired state, and stale revisions fail + visibly and do not trigger executable fallback automatically. + +### Ownership boundary + +OpenClaw maintainers own: + +- package contracts and implementation; +- Gateway-to-model normalization and reconciliation; +- stable state, command, error, and artifact semantics; +- compatibility fixtures and release versioning; +- Control UI reference adoption; and +- server-side authorization behavior. + +Independent products own: + +- product navigation, layout, components, design systems, accessibility, and + localization; +- renderer registration and component schemas; +- registration provenance, code review, signing, and deployment through the + product's ordinary component supply chain; +- product authentication, tenant routing, telemetry, deployment, and rollout; +- optional adapters into an existing product view model; and +- product-specific actions that call supported OpenClaw commands. + +Tool and MCP server authors own structured domain results and UI resources. +They do not choose whether a host trusts a native renderer. + +### Compatibility and release + +The package follows the OpenClaw calendar release train and declares its +compatible Gateway protocol window. Additive fields must not break consumers. +Incompatible snapshot or command changes require a documented migration and a +major contract-version decision independent of the wire protocol number. + +The package begins as a monorepo workspace package. Publication requires: + +- adoption by OpenClaw Control UI; +- adoption by one independent host; +- exact shared conformance fixtures; +- package-acceptance and browser-safe module-graph checks; +- a declared support and compatibility policy; and +- evidence that one duplicate consumer implementation can be deleted. + +Subscriber callbacks run outside the Gateway receive stack. Model ingestion, +normalization, notification, and retained queues must remain bounded; a slow or +throwing subscriber cannot be awaited by protocol event delivery. + +### Delivery shape + +The implementation is intentionally incremental: + +1. package boundary plus connection and session-catalog snapshots; +2. selected-conversation projection and commands; +3. renderer-neutral artifact projection and existing MCP App/Canvas adapters; +4. OpenClaw Control UI adoption of one complete slice; and +5. publication after independent adoption and compatibility evidence. + +No later layer is required to accept an earlier bounded layer. +Adding another capability after v1 requires an independent consumer, a bounded +contract, and a named duplicate implementation or inference path it can delete. + +## Rationale + +### Why not inject a model into Control UI + +Control UI already has an internal capability graph, but its bootstrap, +application context, route ownership, and presentation lifecycle are +application internals. Making that graph injectable would still require an +independent host to load the Lit application and track private module changes. +The reusable boundary belongs below the application. + +### Why not use the Gateway client directly + +The Gateway client deliberately exposes protocol methods and events. It should +not absorb session catalogs, conversation snapshots, tool outcomes, and UI +artifacts. Those are a distinct state-and-command layer, and every UI otherwise +reimplements them. + +### Why not publish Control UI's application context + +The current context includes theme, navigation, overlays, browser settings, +native bridges, and capabilities whose state mixes domain and presentation +concerns. Publishing it wholesale would freeze application internals and make +framework-independent use difficult. V1 extracts only the proven independent +slice. + +### Why immutable snapshots + +Immutable snapshots work with React external stores, Lit controllers, native +bridges, tests, and non-UI consumers. They keep ordering and mutation inside +the owner package and avoid making raw event accumulation a renderer +responsibility. + +### Why UI artifacts are not components + +A renderer identifier plus validated data supports native first-party +presentation without letting untrusted tool output load code. It also preserves +MCP Apps as the executable third-party boundary and keeps renderer choice with +the host. + +### Why not standardize JSON Render in v1 + +JSON Render is a useful adopter and comparator: it demonstrates schema-defined +catalogs, named actions, and streamed revisions. Making its component tree or +patch dialect normative would couple OpenClaw state reuse to one renderer +before two OpenClaw consumers prove the need. The v1 artifact contract can +carry validated JSON data that a host renders with JSON Render or another +library. + +### Why OpenClaw owns the model + +The model interprets OpenClaw protocol behavior and must change atomically with +Gateway and Control UI semantics. Product-owned copies would drift. Product +presentation remains outside OpenClaw, so upstream ownership does not absorb +independent UX. + +## Unresolved questions + +- Which exact session and chat commands form the smallest useful v1? +- Should the first package release be public or remain workspace-only until + independent adoption lands? +- Which existing Control UI normalizers can move unchanged, and which require a + clean implementation because they mix UI concerns? +- Does artifact streaming need complete revisions only, or does adoption + evidence justify a negotiated patch dialect? +- Should generic MCP tool-result metadata be projected directly, or should the + Gateway first publish a narrower sanitized artifact envelope? +- What finite size, depth, count, and retention defaults should v1 require? +- Which Control UI slice should become the first reference adopter? +- Which maintainers own package compatibility and security review if the + package is published? diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md new file mode 100644 index 00000000..495138cb --- /dev/null +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -0,0 +1,173 @@ +# Control Model conformance and adoption plan + +This plan turns RFC 0029 into independently reviewable gates. A package, UI +artifact, or adopter is not supported until source behavior, fixtures, live +proof, and deletion agree. + +## Evidence principles + +- The Gateway protocol and server are authoritative for wire behavior and + authorization. +- OpenClaw Control UI is the executable behavioral reference until shared + fixtures replace UI-local interpretation. +- Raw Gateway events are evidence inputs, not the stable Control Model API. +- A source harness proves reconciliation; a real Gateway proves integration; a + second host proves framework neutrality. +- Native rendering is not proof of action authorization. +- Every proof records repository, exact head, OpenClaw version, command, + result, and known gap. +- Every adopter names duplicate code that becomes deletable. + +## Acceptance layers + +| Layer | Review surface | Required proof | Deletion unlocked | +| --- | --- | --- | --- | +| M1 package boundary | OpenClaw PR 1 | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | +| M2 conversation projection | OpenClaw PR 2 | Shared history/live/reconnect/tool/approval corpus | Per-consumer chat reducers and event folding | +| A1 UI artifacts | OpenClaw PR 3 | Native, structured-only, MCP fallback, malformed, stale, history cases | Tool-specific presentation interpretation | +| O1 Control UI adoption | OpenClaw PR 4 | Existing Control UI behavior unchanged on shared fixtures and E2E | Adopted UI-local capability/reducer code | +| H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | +| H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | +| R1 publication | OpenClaw PR 5/release | Two consumers, package acceptance, compatibility and support policy | Workspace-only distribution | + +## Shared fixture families + +| Family | Minimum cases | +| --- | --- | +| Store | read/subscribe race, immutable identity, unsubscribe, disposal | +| Scheduling | receive-stack isolation, bounded reconciliation queue, slow/throwing subscriber | +| Connection | connect, reconnect, offline, terminal error, retired epoch | +| Sessions | initial list, live create/update/delete, observer outage, resync | +| History | initial load, pagination/truncation, live-before-history, duplicate persisted/live | +| Runs | start, stream, progress, success, failure, cancellation, disconnect | +| Tools | call/result association, out-of-order result, duplicate ID, bounded progress | +| Approvals/questions | allowed action, denial, expiry, reconnect, stale action | +| Commands | success, forbidden, conflict, timeout, abort, unsupported, idempotent retry | +| Artifacts | native, unknown, malformed, fallback, revisions, history, expiry | +| Bounds | messages, progress, artifacts, bytes/depth, inactive conversations | + +Each fixture identifies: + +- wire/projection schema version; +- canonical source behavior; +- initial state; +- ordered inputs; +- expected snapshots; +- expected commands or failures; and +- one mutation that must fail in a deliberately nonconforming implementation. + +## Validation ladder + +### Per-commit + +- formatting, lint, typecheck, and diff hygiene; +- affected package tests; +- browser-safe import graph; +- fixture schema validation; and +- no framework or product imports in core. +- no subscriber/render work in the Gateway receive stack. + +### Per-PR + +- complete `@openclaw/control-model` tests; +- Gateway protocol compatibility tests; +- current Control UI tests for affected behavior; +- source fixture and real loopback Gateway proof; +- memory/retention bounds under representative history and progress; and +- independent review of error, reconnect, and authorization semantics. + +### Native artifact adoption + +- exact local registry and schema version; +- valid and invalid artifact data; +- allowed and denied action; +- stale artifact action; +- unknown renderer; +- MCP App/structured fallback; +- theme, accessibility, localization, and responsive behavior owned by the + adopter; and +- no dynamic import derived from artifact data. + +### Hosted adoption + +- real product authentication and Gateway route; +- cold start and reconnect; +- history/live overlap; +- mid-stream disconnect and resync; +- tenant/session isolation; +- rollback to the incumbent path; and +- telemetry without raw tool data or credentials. + +## Compatibility + +Before publication, test: + +- the exact supported OpenClaw release; +- the declared predecessor release where compatibility is promised; +- OpenClaw `main` as a drift canary; +- browser and Node host bindings; and +- every supported serialized fixture version. + +The Control Model contract version and Gateway wire protocol version are +distinct. A wire-compatible server may still require an additive model +projection update. An incompatible model change requires migration guidance +and a declared support-window decision. + +## Performance and memory gates + +The package must measure: + +- initial session and conversation projection time; +- per-event reconciliation cost; +- snapshot allocation rate during streaming; +- retained bytes for messages, progress, tools, and artifacts; +- inactive conversation eviction; and +- reconnect/resync latency. + +No renderer callback runs in the Gateway receive loop. Slow subscribers must +not block protocol event processing. Unbounded history, progress, artifact, or +listener retention blocks release. + +## Security gates + +The following are blocking: + +- native renderer registration from tool-provided data; +- component/module import paths derived from artifact metadata; +- action execution without model command and server authorization; +- success-shaped state after forbidden/conflicting commands; +- cross-session or retired-epoch artifact/action confusion; +- credentials, hidden model context, capability URLs, or unbounded payloads in + logs/errors; +- implicit executable fallback for unknown artifacts; +- loss of MCP App sandbox/CSP/expiry behavior; and +- deletion of the incumbent path before rollback proof; +- unreviewed renderer registration or unsupported artifact data version. + +## Independent adopter proof + +The first independent adopter should: + +1. consume the package through an existing supported Gateway route; +2. adapt snapshots into its existing view model rather than create another + shared vocabulary; +3. render one representative conversation; +4. register one native artifact; +5. exercise one denied action; +6. fall back safely when registration is absent; +7. reconnect mid-stream; and +8. identify exact reducer/projection code deleted after parity. + +## Promotion and deletion ledger + +Every adoption PR records: + +1. incumbent implementation; +2. owner behavior preserved; +3. exact conformance fixtures; +4. real integration proof; +5. rollout and rollback control; +6. observation window; and +7. deletion commit or follow-up owner. + +No deletion credit is granted because a package compiles or a demo renders. diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md new file mode 100644 index 00000000..46ddda6b --- /dev/null +++ b/rfcs/0029/control-model-v1-spec.md @@ -0,0 +1,305 @@ +# Control Model v1 specification + +This document defines the candidate behavioral contract for +`@openclaw/control-model`. It specifies framework-neutral state and commands +above a supported OpenClaw Gateway client. It does not define presentation, +product authentication, or another wire protocol. + +Status: draft. This is a fork-only preview and has not been submitted or +accepted upstream. + +## Scope + +A conforming v1 model provides: + +- explicit lifecycle and disposal; +- immutable connection and session-catalog snapshots; +- lazily created conversation snapshots; +- history/live/reconnect reconciliation; +- typed tool, approval, question, and run state needed by chat; +- typed commands with structured failure; +- renderer-neutral UI artifacts; and +- finite retained state with observable partial/lag conditions. + +## Host binding + +The model consumes one host-owned Gateway binding. The binding must provide: + +- the current connection snapshot and an invalidation subscription; +- Gateway event subscription; +- correlated request execution; +- the accepted hello/protocol metadata required for feature detection; and +- typed request and connection errors. + +The host owns: + +- socket creation and route selection; +- credentials, signing, and device-token persistence; +- product authentication and tenant admission; +- reconnect policy outside shared Gateway-client behavior; and +- logging and telemetry sinks. + +The model must not start a network connection at import or construction time. +It must not persist credentials. + +## Root lifecycle + +Construction is inert except for validating options. `start()` may subscribe to +an already managed Gateway binding; alternatively, construction may start +subscriptions when the API makes that behavior explicit. The selected shape +must have one unambiguous lifecycle. + +`dispose()` is idempotent and must: + +- unsubscribe from Gateway state and events; +- abort or retire model-owned refreshes; +- wake model waiters with a terminal disposed error; +- retire conversation epochs; +- release retained snapshots not reachable by the caller; and +- prevent later events from mutating published state. + +No subscription callback may fire after its unsubscribe function returns, +except a callback already executing on the same stack. + +Gateway event callbacks must not synchronously run consumer render or +subscriber work. The model may enqueue bounded reconciliation work and publish +outside the protocol receive stack. It must not await subscribers. One +subscriber exception must not prevent other subscribers or future Gateway +events from being processed. + +## Snapshot contract + +Snapshots are immutable values. A consumer must be able to: + +1. read a snapshot; +2. subscribe; +3. read again to close the read/subscribe race; and +4. compare snapshot identity to determine whether state changed. + +Every state transition publishes a new root or capability snapshot identity. +Unchanged state must retain identity where practical to avoid unnecessary +renderer work. + +Snapshots use JSON-compatible data except documented opaque handles. Dates are +ISO-8601 strings or integer epoch milliseconds consistently within one public +type family. + +## Connection snapshot + +The connection projection contains: + +- phase: stopped, connecting, connected, reconnecting, offline, or disposed; +- a monotonically increasing connection epoch; +- accepted protocol version and declared capabilities where available; +- current session/instance identity safe for presentation; +- structured last error and reconnect classification; and +- whether state is complete, stale, partial, or resynchronizing. + +A transport connection alone does not imply conversation readiness. Readiness +requires the required initial snapshots or an explicit partial state. + +## Session catalog + +The catalog contains stable session keys and the Gateway-authoritative fields +needed to list, select, and mutate sessions. Unknown additive fields must not +break projection. + +The model owns: + +- initial list loading; +- live `sessions.changed` reconciliation; +- explicit deleted-session handling; +- refresh after sequence gaps or observer outages; +- duplicate suppression; +- connection-epoch retirement; +- bounded retry for retryable observer errors; and +- typed loading, refreshing, stale, and error state. + +Local optimistic mutation may be used only when reconciliation and rollback are +specified. A failed mutation must not leave success-shaped catalog state. + +## Conversation model + +`conversation(sessionKey)` returns a stable model handle for that normalized +session key until release or root disposal. A host may release inactive +conversation handles through an explicit API. The package must bound inactive +retention. + +The conversation snapshot contains: + +- normalized session identity; +- loading, ready, stale, partial, terminal, and error state; +- canonical ordered messages with stable IDs; +- the active run and stream projection; +- tool invocations and outcomes; +- approval and question requests; +- UI artifacts; +- command availability hints; and +- the connection and history revisions used to derive the snapshot. + +## History and live reconciliation + +The model must define one deterministic merge for: + +- an initial or refreshed history response; +- live messages received before, during, or after history loading; +- duplicate live and persisted messages; +- live tool calls and later persisted tool results; +- run start, progress, terminal, abort, and disconnect; +- sequence gaps; +- history truncation or pagination; and +- reconnection to a replacement Gateway client. + +Stable server IDs are authoritative. Where the server does not provide an ID, +the model may derive a bounded provisional key, but it must expose provisional +status and reconcile it when canonical state arrives. + +A reconnect must not duplicate a message, tool invocation, approval, question, +or UI artifact. Events from a retired connection epoch must not mutate the +current conversation. + +When a gap prevents complete reconciliation, the model publishes explicit +partial/stale state and requests an authoritative refresh. It must not silently +continue with success-shaped complete state. + +## Tool and run projection + +Every tool invocation has: + +- a stable call ID; +- tool identity safe for display; +- finite structured input or a redacted/unavailable marker; +- pending, running, succeeded, failed, cancelled, or unknown outcome; +- live progress with finite retention; +- structured output or a redacted/unavailable marker; +- associated UI artifact IDs; and +- timestamps/revisions needed for deterministic ordering. + +Approved-but-failed execution remains distinct from approval denial. +Cancellation remains distinct from failure. Unknown output is not success. + +Progress retention must be bounded by count and bytes. Truncation is explicit. + +## Approval and question projection + +An approval or question contains: + +- a stable request ID and owning session/run/tool identity; +- typed presentation-safe description; +- exactly the actions currently allowed by the Gateway contract; +- pending, answered, expired, cancelled, or unavailable lifecycle; +- an optional deadline; and +- structured source/authority information safe for presentation. + +The model must reject a locally requested action that is not in the current +allowed set, but that preflight is not authorization. The Gateway independently +authorizes the request. + +When the server provides a safe denial reason, policy source, or responsible +owner, the projection preserves it so adapters can present an actionable +explanation rather than a generic disabled state. Adapters must not widen or +replace the server-provided allowed-action set. + +## Commands + +Candidate v1 commands are: + +- refresh session catalog; +- create/select/rename/archive/delete session where supported; +- load/refresh conversation history; +- send chat content and supported attachments; +- abort the active run; +- answer a question; +- approve or deny a pending request; and +- retry only where the Gateway exposes a safe retry contract. + +Each command defines: + +- required current state; +- exact Gateway method and parameter contract; +- whether it is idempotent; +- abort behavior; +- stale/retired epoch behavior; +- optimistic state, if any; +- success result; and +- typed failures. + +The model must not retry a non-idempotent command automatically unless the +Gateway contract provides an idempotency key and the retry preserves it. + +## Error contract + +Public errors distinguish at least: + +- disconnected or not ready; +- disposed; +- unsupported by negotiated capability; +- invalid input; +- stale connection/session epoch; +- forbidden; +- conflict; +- not found or expired; +- timeout or abort; +- retryable transport/startup failure; +- sequence gap/partial state; and +- malformed or incompatible server data. + +Errors preserve safe canonical codes, retryability, and retry-after hints where +available. Arbitrary server details, credentials, raw headers, and unbounded +payloads must not enter public messages or logs. + +## Bounds + +V1 must define finite defaults for: + +- retained inactive conversations; +- messages per loaded page and total retained pages; +- live progress lines and bytes; +- pending tool/approval/question entries; +- UI artifacts per message/conversation; +- artifact data bytes/depth; +- observer retry delay; +- refresh concurrency; and +- command timeout inheritance. + +The package must expose truncation, pagination, or partial state rather than +silently dropping retained state. + +The implementation must also bound queued reconciliation work between Gateway +event delivery and snapshot publication. Exceeding that bound produces an +explicit lag/partial state and authoritative refresh rather than unbounded +memory growth. + +## Framework neutrality + +The published runtime graph must not import: + +- Lit, React, Vue, Svelte, or framework adapters; +- DOM custom elements or browser storage; +- Control UI routes, theme, localization, CSS, or components; +- product authentication or telemetry; or +- Node-only modules from the browser entry. + +Framework adapters may live in separate optional packages or adopter +repositories. + +## Required conformance evidence + +Before v1 support is claimed, shared fixtures must cover: + +- read/subscribe race closure and immutable identity; +- initial session list plus live create/update/delete; +- retryable observer outage and authoritative refresh; +- history/live overlap; +- duplicate and out-of-order message/tool events; +- sequence gap and explicit partial state; +- reconnect with retired-epoch event rejection; +- active stream completion, cancellation, and disconnect; +- approval allowed/denied/expired paths; +- typed command rejection and conflict; +- artifact association and revision ordering; +- bounds and truncation; and +- disposal during every active wait. + +At least OpenClaw Control UI and one independent host must consume the same +fixtures before publication. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md new file mode 100644 index 00000000..f3fc739a --- /dev/null +++ b/rfcs/0029/implementation-plan.md @@ -0,0 +1,207 @@ +# Control Model implementation and PR plan + +This plan is a proposed review sequence, not an accepted roadmap. It keeps each +OpenClaw layer independently useful and delays publication until two consumers +prove the contract. + +## Source extraction rules + +- Move behavior only after a shared fixture captures it. +- Keep protocol and schema types in their current owner packages. +- Do not copy Control UI helpers that import presentation, localization, + browser storage, routing, or DOM behavior. +- Prefer pure normalization and capability factories over a new universal + application framework. +- Keep OpenClaw Control UI behavior unchanged during adoption. + +## OpenClaw PR 1: package and session snapshots + +### Scope + +- Add workspace package `packages/control-model`. +- Define host Gateway binding, immutable external-store contract, lifecycle, + structured errors, and bounds configuration. +- Isolate bounded reconciliation and subscriber notification from the Gateway + receive stack. +- Project connection state and session catalog. +- Reuse canonical protocol types without re-exporting the entire protocol. +- Add package documentation and browser-safe import checks. + +### Explicit exclusions + +- Conversation messages and streaming. +- UI artifacts. +- React/Lit adapters. +- Public npm publication. + +### Proof + +- Store race/disposal tests. +- Slow/throwing subscriber and reconciliation-queue saturation tests. +- Session list plus create/update/delete reconciliation. +- Connection-epoch retirement. +- Retryable observer outage and authoritative refresh. +- Package graph contains no framework, DOM component, or product import. + +### Deletion target + +One duplicate session-catalog reducer in an adopter, after later adoption. + +## OpenClaw PR 2: selected conversation and commands + +### Scope + +- Add lazy conversation models. +- Extract deterministic history/live merge. +- Project messages, runs, tools, approvals, and questions. +- Add typed chat/session commands and command errors. +- Add finite progress and inactive-conversation retention. + +### Proof + +- Shared fixture corpus consumed by Control Model and current Control UI tests. +- History/live overlap and duplicate suppression. +- Sequence gap plus explicit partial state and refresh. +- Mid-stream reconnect and retired-epoch rejection. +- Allowed, forbidden, conflict, timeout, abort, and disposal command paths. + +### Deletion target + +Control UI and independent-host reducers for the adopted conversation slice. + +## OpenClaw PR 3: renderer-neutral UI artifacts + +### Scope + +- Define and validate v1 artifacts. +- Preserve sanitized artifact data through live projection and history. +- Adapt existing MCP App and Canvas previews into explicit fallbacks. +- Add revision, expiry, bound, and structured failure behavior. +- Keep renderer registries outside the package. + +### Proof + +- Known and unknown template URIs. +- Malformed/oversized data. +- Increasing, duplicate, stale, and conflicting revisions. +- History reload and reconnect. +- MCP App fallback and expiry. +- Proof that metadata cannot select an import or register a component. + +### Deletion target + +Tool-specific native rendering interpretation and duplicate Canvas/MCP +association logic. + +## OpenClaw PR 4: Control UI reference adoption + +### Scope + +- Adapt the existing Control UI Gateway store to the package binding. +- Move the session catalog and one complete conversation route to Control Model + snapshots. +- Keep Lit components, routes, styling, and behavior unchanged. +- Render current Canvas/MCP fallbacks through a Control UI-local artifact + registry/adapter. + +### Proof + +- Existing focused Control UI tests. +- Shared model fixtures. +- Real browser/Gateway chat flow. +- No regression in reconnect, approval, tool cards, MCP Apps, or history. +- Bundle and startup impact measured. + +### Deletion target + +Superseded UI-local session/conversation capability and reconciliation code. + +## Lobster/M PR 1: adapter into existing SessionView + +### Scope + +- Consume the workspace or fork package through Lobster's hosted Gateway seam. +- Map model snapshots into M's existing `SessionView`. +- Keep the renderer passive. +- Preserve current desktop and web service-port boundaries. +- Add a runtime flag and incumbent fallback. + +### Proof + +- Existing `SessionView` fixtures. +- Hosted auth and real Gateway. +- Session list, selection, one conversation, tool result, and approval. +- Mid-stream reconnect without duplication. + +### Deletion target + +The adopted web-specific Gateway fold/reducer path after parity. + +## Lobster/M PR 2: first native UI artifact + +### Scope + +- Add a host-owned exact-URI renderer registry. +- Register one bounded first-party component, preferably a calendar golden + scenario already represented by structured tool output. +- Add schema validation and named action binding. +- Pin registration and artifact data versions and emit safe action correlation. +- Preserve text and MCP App fallback. + +### Proof + +- Valid, invalid, unknown, fallback, and expired artifacts. +- Fluent/M365 theme, accessibility, localization, and responsive behavior. +- Allowed and server-denied action. +- No dynamic import from artifact metadata. + +### Deletion target + +One bespoke tool-output parsing/rendering path. + +## Lobster/M PR 3: streaming, actions, and operations + +### Scope + +- Apply complete artifact revisions during live tool execution. +- Add stale-revision action protection. +- Add telemetry for projection lag, renderer selection, validation failure, + fallback, and action outcome. +- Prove reconnect and rollback. + +### Proof + +- Progressive pending/ready revisions. +- Duplicate/stale revision handling. +- Mid-stream disconnect/resync. +- Slow native renderer does not block Gateway processing. +- Product telemetry contains no raw sensitive artifact payload. + +## OpenClaw PR 5: publication + +### Preconditions + +- Control UI and independent host are live on the same contract. +- Compatibility and package acceptance pass. +- Bounds and security review pass. +- At least one duplicate implementation is deleted. +- Named package, protocol, security, and release owners agree. + +### Scope + +- Publish `@openclaw/control-model`. +- Document supported versions and migration policy. +- Add framework-neutral quickstart and conformance fixtures. +- Keep optional framework adapters outside the core package unless separately + justified. + +## Deferred work + +- Config/settings capability. +- Channels, skills, nodes, workboards, and admin surfaces. +- JSON Patch/JSONL artifact dialect. +- Model-visible component catalogs and generative dashboards. +- Third-party native component SDK. +- Stable framework-specific adapters. + +Each deferred surface requires a separate owner-first slice and deletion case. diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md new file mode 100644 index 00000000..cde3a4a6 --- /dev/null +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -0,0 +1,255 @@ +# UI artifact v1 specification + +This document defines a renderer-neutral UI artifact projected by +`@openclaw/control-model`. An artifact lets a host select native first-party +presentation while preserving structured output and sandboxed third-party +fallback. + +Status: draft. This is a fork-only preview. + +## Principles + +- An artifact is data and identity, not executable code. +- A template URI is a lookup key, not a trust or authorization claim. +- Native rendering is host-registered and allowlist-only. +- Unknown artifacts remain useful through structured/text output. +- Third-party executable UI remains sandboxed through MCP Apps or another + explicitly supported sandbox contract. +- UI actions never bypass model commands or Gateway authorization. + +## Artifact shape + +```ts +export type JsonValue = + | null + | boolean + | number + | string + | JsonValue[] + | { [key: string]: JsonValue }; + +export interface UiArtifact { + version: 1; + id: string; + revision: number; + templateUri: string; + dataVersion: number; + data: JsonValue; + structuredContent?: JsonValue; + state: "pending" | "ready" | "failed" | "expired"; + source: UiArtifactSource; + error?: UiArtifactError; + fallback?: UiArtifactFallback; +} + +export interface UiArtifactSource { + sessionKey: string; + messageId?: string; + toolCallId?: string; + toolName?: string; +} +``` + +The final field names may change during implementation, but every accepted +shape must retain the semantics below. + +## Identity and revisions + +`id` is stable for one logical artifact in one conversation. It must not be +derived only from `templateUri`. + +`revision` is a non-negative integer that increases monotonically for accepted +updates to that artifact. A duplicate revision with byte-equivalent normalized +content is ignored. A duplicate revision with different content is a +structured conflict. A lower revision is stale and must not replace current +state. + +An artifact from a retired connection epoch may be reconciled only through +authoritative history. It must not update live state directly. + +## Template URI + +`templateUri` is a bounded absolute URI. Schemes are not globally trusted. +Hosts may register product-specific schemes such as +`clawpilot://widgets/calendar` or use a standardized `ui://` resource +identifier. + +The URI: + +- does not identify a JavaScript module to import; +- does not grant network, tool, command, credential, or DOM authority; +- does not select native rendering unless the host registry contains an exact + compatible registration; and +- must be preserved as opaque data when unknown. + +Hosts should match exact URIs or an explicitly versioned registry rule. Generic +wildcard registrations require a separate security review. + +`dataVersion` is a positive integer interpreted only by the exact host +registration. A registration declares the versions it accepts and any pure, +bounded migration into its current schema. Tool output cannot declare a +migration. + +## Data and structured content + +`data` contains component-shaped untrusted JSON. A native renderer registration +must provide a schema and reject invalid data before component construction. + +`structuredContent` contains model- or transcript-relevant domain output when +available. It is not a private channel for secrets, hidden instructions, +credentials, or host-only state. Hosts may show it when native rendering is +unavailable. + +Artifact data must have finite encoded bytes, depth, collection lengths, and +string lengths. Oversized artifacts become structured failures while ordinary +text/tool output remains available. + +## Lifecycle + +- `pending`: identity is known but complete render data is not ready. +- `ready`: the current revision passed model-level validation. +- `failed`: artifact materialization failed; `error` contains a safe code and + message. +- `expired`: a referenced resource or interactive view is no longer available. + +Lifecycle transitions are monotonic within one revision unless a higher +revision explicitly recovers the artifact. Expired interactive fallback must +not be reopened with stale credentials or capability URLs. + +## Native renderer registry + +The host registry maps a supported template URI and artifact version to: + +- a local component factory; +- a validation schema; +- optional migration from older data versions; +- named action bindings; +- presentation metadata such as supported surfaces; and +- an explicit fallback policy. + +Registration is deployment-owned code or configuration. Tool output cannot add +or modify registrations. + +Registration provenance follows the host's ordinary component supply chain, +including code review, dependency policy, signing, and deployment controls +where those controls apply. The Control Model does not create a second runtime +component marketplace. + +The Control Model does not import or execute registry components. A framework +adapter reads artifacts and invokes the host registry. + +## Actions + +A native component may emit only a named action declared by its local +registration. The action handler receives: + +- artifact ID and revision; +- normalized action name; +- schema-validated action data; +- current session/message/tool source; and +- an abort signal. + +The handler maps the action to a supported Control Model command or a +product-owned operation. It must verify that the artifact revision is current. +Every OpenClaw operation re-enters Gateway authorization. + +The host records a safe correlation tuple for attempted actions: registration +identity/version, artifact ID/revision, action name, session key, and tool call +ID when present. It must not record raw artifact data by default. + +Artifact data must not contain an executable callback, JavaScript expression, +module reference, or unrestricted Gateway method name. + +## Fallback + +Candidate fallback kinds are: + +```ts +type UiArtifactFallback = + | { + kind: "mcp-app"; + viewId: string; + uiResourceUri?: string; + } + | { + kind: "canvas"; + viewId?: string; + url: string; + sandbox: "strict" | "scripts"; + }; +``` + +Fallback is explicit. An unknown URI does not cause arbitrary HTML, URL, or +module execution. + +MCP App fallback uses the existing OpenClaw materialization, sandbox, CSP, +bridge, expiry, and authorization contracts. Canvas fallback uses existing +host URL and sandbox policy. Structured/text output remains available when no +executable fallback is accepted. + +## Streaming + +V1 exposes complete immutable artifact revisions. A source may update an +artifact progressively by publishing higher revisions. + +V1 does not standardize: + +- RFC 6902 patches; +- JSONL framing; +- JSON Render component trees; +- renderer-owned state mutation; or +- client-authored merge semantics. + +A future dialect may add patches if it defines: + +- a base revision; +- finite patch count and bytes; +- atomic validation; +- failure and resynchronization; +- unknown operation handling; +- history persistence; and +- conformance across at least two renderers. + +## History and portability + +The Gateway's sanitized history projection must preserve enough artifact +identity, data, source, revision, and explicit fallback metadata to reproduce +the same safe presentation after reload. + +If the source contract cannot persist an interactive artifact, history must +retain structured content and mark the interactive state expired or +unavailable. It must not silently omit the entire tool result. + +## Security failures + +The following fail artifact rendering without failing the surrounding message: + +- unknown artifact version; +- invalid or unsupported URI; +- data schema failure; +- size/depth/count violation; +- stale/conflicting revision; +- unknown native registration; +- expired fallback; +- unsupported sandbox request; and +- action requested against a stale revision. + +Failures are observable and safe to log after redaction. They must not contain +raw credentials, capability URLs, hidden model context, or unbounded tool data. + +## Required conformance evidence + +Fixtures must cover: + +- registered native URI; +- unknown URI with structured output only; +- unknown URI with accepted MCP App fallback; +- malformed and oversized data; +- duplicate, stale, conflicting, and increasing revisions; +- history reload; +- reconnect with a retired live revision; +- expired fallback; +- allowed, denied, unknown, and stale-revision actions; +- component schema evolution; +- registration provenance and data-version rejection/migration; and +- proof that tool output cannot register or import native code. From e0b7e3c6041b173079afe82149348beb71e17621 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 11 Aug 2026 11:34:45 -0700 Subject: [PATCH 02/33] docs: clarify artifact capability ownership Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 28 ++++++++++++++++++++++ rfcs/0029/conformance-and-adoption-plan.md | 3 +++ rfcs/0029/ui-artifact-v1-spec.md | 22 +++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index a55f2797..38f8c09d 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -292,6 +292,34 @@ Independent products own: Tool and MCP server authors own structured domain results and UI resources. They do not choose whether a host trusts a native renderer. +### Extension and client capability split + +Installed and enabled OpenClaw extensions determine which tools, structured +results, and optional UI artifacts can be produced. The client determines which +artifact versions and native renderers it has installed, registered, and +trusted. + +The Control Model does not generate UI capabilities independently of either +side. It normalizes the artifact emitted by the active extension, exposes the +current client-rendering decision, and preserves a safe fallback: + +```text +installed extension emits artifact + | + v +Control Model normalizes identity, data, lifecycle, and fallback + | + v +client registry selects native renderer + or structured/MCP App fallback +``` + +Client capability advertisement may let an extension avoid producing an +unsupported optional artifact, but it is an optimization rather than an +authorization grant. Extensions should preserve useful structured or text +output when no native renderer is available. A client must not claim support +unless an exact compatible local registration exists. + ### Compatibility and release The package follows the OpenClaw calendar release train and declares its diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 495138cb..e06aec98 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -44,6 +44,7 @@ proof, and deletion agree. | Approvals/questions | allowed action, denial, expiry, reconnect, stale action | | Commands | success, forbidden, conflict, timeout, abort, unsupported, idempotent retry | | Artifacts | native, unknown, malformed, fallback, revisions, history, expiry | +| Capability split | extension absent/disabled, renderer absent, version mismatch, stale advertisement | | Bounds | messages, progress, artifacts, bytes/depth, inactive conversations | Each fixture identifies: @@ -83,6 +84,8 @@ Each fixture identifies: - allowed and denied action; - stale artifact action; - unknown renderer; +- extension-installed but renderer-unsupported and renderer-installed but + extension-absent cases; - MCP App/structured fallback; - theme, accessibility, localization, and responsive behavior owned by the adopter; and diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index cde3a4a6..1f028358 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -10,6 +10,8 @@ Status: draft. This is a fork-only preview. ## Principles - An artifact is data and identity, not executable code. +- Installed and enabled extensions determine which artifacts can be produced. +- The client determines which native artifact renderers it supports and trusts. - A template URI is a lookup key, not a trust or authorization claim. - Native rendering is host-registered and allowlist-only. - Unknown artifacts remain useful through structured/text output. @@ -138,6 +140,26 @@ component marketplace. The Control Model does not import or execute registry components. A framework adapter reads artifacts and invokes the host registry. +## Capability discovery + +An exact local renderer registration is the authority for native-renderer +support. A client may advertise a bounded set of supported template URI and +data-version pairs during connection or tool invocation when the Gateway +contract provides such a carrier. + +Capability advertisement: + +- is optional and may be stale; +- lets an extension omit an unsupported optional native artifact; +- does not install a component or grant trust; +- does not authorize an OpenClaw operation; and +- must not be required for structured/text or sandboxed fallback output. + +An extension that emits an artifact remains responsible for useful structured +or text output when practical. The client independently resolves the artifact +against its current registry. If no exact compatible registration exists, it +uses the declared safe fallback or renders the structured/text result. + ## Actions A native component may emit only a named action declared by its local From 585c3741b9dd315bf0b831d9da07be3de42ceb15 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 11 Aug 2026 11:37:45 -0700 Subject: [PATCH 03/33] docs: expose client-selectable view offers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 48 ++++++++++++++-------- rfcs/0029/conformance-and-adoption-plan.md | 7 ++-- rfcs/0029/implementation-plan.md | 5 +++ rfcs/0029/ui-artifact-v1-spec.md | 44 +++++++++++++++----- 4 files changed, 73 insertions(+), 31 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 38f8c09d..b3ff871b 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -81,8 +81,9 @@ making OpenClaw own those products. selected conversation. - Reconcile history, live events, reconnects, and tool lifecycle once. - Return typed command failures without success-shaped fallbacks. -- Preserve renderer-neutral UI artifacts long enough for a host to select a - native renderer, structured fallback, or sandboxed MCP App. +- Preserve renderer-neutral UI artifacts and all applicable OpenClaw-provided + view offers long enough for a host to select its preferred native renderer, + product view model, structured fallback, or sandboxed MCP App. - Let OpenClaw Control UI become a reference adopter without changing its presentation. - Support independently owned browser, desktop, mobile, terminal, and hosted @@ -220,10 +221,8 @@ A UI artifact is data and identity, not executable presentation: export interface UiArtifact { id: string; revision: number; - templateUri: string; - dataVersion: number; - data: JsonValue; structuredContent?: JsonValue; + views: UiArtifactView[]; state: "pending" | "ready" | "failed" | "expired"; source: { sessionKey: string; @@ -232,17 +231,29 @@ export interface UiArtifact { }; fallback?: McpAppArtifact | CanvasArtifact; } + +export interface UiArtifactView { + id: string; + templateUri: string; + dataVersion: number; + data: JsonValue; + fallback?: McpAppArtifact | CanvasArtifact; +} ``` +OpenClaw core and installed extensions may offer zero or more views of the same +artifact, such as calendar, list, table, summary, or an MCP App. A view's `templateUri` is opaque. It does not grant trust, select a JavaScript import, or authorize an action. A host may map a locally registered URI to a native -component. It must schema-validate artifact data before rendering. If no native -renderer is registered, the host may show structured/text output or use an -explicit sandboxed fallback. +component. It must schema-validate view data before rendering. -`dataVersion` selects a schema version within the host's exact local +Each view's `dataVersion` selects a schema version within the host's exact local registration. Registration and component code ship through the host's ordinary reviewed supply chain; tool output cannot add, replace, or widen a registration. +OpenClaw may identify a recommended default, but the client remains free to +choose any compatible offered view or project the underlying structured content +into its own product view model. If no compatible renderer is registered, the +host may show structured/text output or use an explicitly sandboxed fallback. V1 uses complete immutable revisions. It does not standardize JSON Patch, JSONL, or a renderer-specific component tree. A later extension may introduce a @@ -295,30 +306,33 @@ They do not choose whether a host trusts a native renderer. ### Extension and client capability split Installed and enabled OpenClaw extensions determine which tools, structured -results, and optional UI artifacts can be produced. The client determines which -artifact versions and native renderers it has installed, registered, and -trusted. +results, UI artifacts, and alternative view offers can be produced. The client +determines which artifact views and native renderers it has installed, +registered, and trusted, and which product view model should consume the +projection. The Control Model does not generate UI capabilities independently of either side. It normalizes the artifact emitted by the active extension, exposes the current client-rendering decision, and preserves a safe fallback: ```text -installed extension emits artifact +installed extension emits artifact plus view offers | v -Control Model normalizes identity, data, lifecycle, and fallback +Control Model normalizes identity, views, data, lifecycle, and fallback | v -client registry selects native renderer +client selects a compatible view and local view-model projection or structured/MCP App fallback ``` Client capability advertisement may let an extension avoid producing an unsupported optional artifact, but it is an optimization rather than an authorization grant. Extensions should preserve useful structured or text -output when no native renderer is available. A client must not claim support -unless an exact compatible local registration exists. +output when no native renderer is available. A client must not claim native +support unless an exact compatible local registration exists. OpenClaw owns +the available view offers and their semantics; Lobster or another host owns +which offer it selects and how it maps that projection into its own view model. ### Compatibility and release diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index e06aec98..e9f7b9a9 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -43,7 +43,7 @@ proof, and deletion agree. | Tools | call/result association, out-of-order result, duplicate ID, bounded progress | | Approvals/questions | allowed action, denial, expiry, reconnect, stale action | | Commands | success, forbidden, conflict, timeout, abort, unsupported, idempotent retry | -| Artifacts | native, unknown, malformed, fallback, revisions, history, expiry | +| Artifacts | multiple view offers, client selection, native, unknown, malformed, fallback, revisions, history, expiry | | Capability split | extension absent/disabled, renderer absent, version mismatch, stale advertisement | | Bounds | messages, progress, artifacts, bytes/depth, inactive conversations | @@ -80,6 +80,7 @@ Each fixture identifies: ### Native artifact adoption - exact local registry and schema version; +- multiple OpenClaw view offers and a client-selected non-default view; - valid and invalid artifact data; - allowed and denied action; - stale artifact action; @@ -152,8 +153,8 @@ The following are blocking: The first independent adopter should: 1. consume the package through an existing supported Gateway route; -2. adapt snapshots into its existing view model rather than create another - shared vocabulary; +2. choose among OpenClaw-provided views and adapt the selected projection into + its existing view model rather than create another shared vocabulary; 3. render one representative conversation; 4. register one native artifact; 5. exercise one denied action; diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index f3fc739a..dae3308a 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -74,6 +74,8 @@ Control UI and independent-host reducers for the adopted conversation slice. ### Scope - Define and validate v1 artifacts. +- Preserve all applicable OpenClaw core/extension view offers and let the + client select among compatible views. - Preserve sanitized artifact data through live projection and history. - Adapt existing MCP App and Canvas previews into explicit fallbacks. - Add revision, expiry, bound, and structured failure behavior. @@ -82,6 +84,7 @@ Control UI and independent-host reducers for the adopted conversation slice. ### Proof - Known and unknown template URIs. +- Multiple offered views with client-owned selection. - Malformed/oversized data. - Increasing, duplicate, stale, and conflicting revisions. - History reload and reconnect. @@ -122,6 +125,8 @@ Superseded UI-local session/conversation capability and reconciliation code. - Consume the workspace or fork package through Lobster's hosted Gateway seam. - Map model snapshots into M's existing `SessionView`. +- Select the Lobster-compatible OpenClaw view projection without making that + choice canonical for other clients. - Keep the renderer passive. - Preserve current desktop and web service-port boundaries. - Add a runtime flag and incumbent fallback. diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 1f028358..69231303 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -34,13 +34,18 @@ export interface UiArtifact { version: 1; id: string; revision: number; - templateUri: string; - dataVersion: number; - data: JsonValue; structuredContent?: JsonValue; + views: UiArtifactView[]; state: "pending" | "ready" | "failed" | "expired"; source: UiArtifactSource; error?: UiArtifactError; +} + +export interface UiArtifactView { + id: string; + templateUri: string; + dataVersion: number; + data: JsonValue; fallback?: UiArtifactFallback; } @@ -57,8 +62,9 @@ shape must retain the semantics below. ## Identity and revisions -`id` is stable for one logical artifact in one conversation. It must not be -derived only from `templateUri`. +`id` is stable for one logical artifact in one conversation. A view ID is +stable within that artifact. Neither identity may be derived only from +`templateUri`. `revision` is a non-negative integer that increases monotonically for accepted updates to that artifact. A duplicate revision with byte-equivalent normalized @@ -69,7 +75,13 @@ state. An artifact from a retired connection epoch may be reconciled only through authoritative history. It must not update live state directly. -## Template URI +## Offered views and template URI + +OpenClaw core and installed extensions may contribute zero or more applicable +views for an artifact. Multiple views may represent the same structured +content as a calendar, list, table, summary, form, dashboard, or sandboxed app. +View order is deterministic but is not a requirement that the client render +the first view. `templateUri` is a bounded absolute URI. Schemes are not globally trusted. Hosts may register product-specific schemes such as @@ -92,9 +104,15 @@ registration. A registration declares the versions it accepts and any pure, bounded migration into its current schema. Tool output cannot declare a migration. +A client selects a view by exact compatibility, product policy, surface, +accessibility, and user preference. OpenClaw may mark one view as recommended, +but the recommendation neither grants trust nor overrides the client choice. +A client may ignore every offered view and project `structuredContent` into its +own product view model. + ## Data and structured content -`data` contains component-shaped untrusted JSON. A native renderer registration +Each view's `data` contains component-shaped untrusted JSON. A native renderer registration must provide a schema and reject invalid data before component construction. `structuredContent` contains model- or transcript-relevant domain output when @@ -145,7 +163,9 @@ adapter reads artifacts and invokes the host registry. An exact local renderer registration is the authority for native-renderer support. A client may advertise a bounded set of supported template URI and data-version pairs during connection or tool invocation when the Gateway -contract provides such a carrier. +contract provides such a carrier. OpenClaw can use that information to filter +or rank view offers, but the client makes the final selection against its +current registry. Capability advertisement: @@ -156,9 +176,9 @@ Capability advertisement: - must not be required for structured/text or sandboxed fallback output. An extension that emits an artifact remains responsible for useful structured -or text output when practical. The client independently resolves the artifact -against its current registry. If no exact compatible registration exists, it -uses the declared safe fallback or renders the structured/text result. +or text output when practical. The client independently resolves all offered +views against its current registry. If no exact compatible registration exists, +it uses an accepted declared fallback or renders the structured/text result. ## Actions @@ -264,6 +284,7 @@ raw credentials, capability URLs, hidden model context, or unbounded tool data. Fixtures must cover: - registered native URI; +- multiple compatible views with a non-first client selection; - unknown URI with structured output only; - unknown URI with accepted MCP App fallback; - malformed and oversized data; @@ -274,4 +295,5 @@ Fixtures must cover: - allowed, denied, unknown, and stale-revision actions; - component schema evolution; - registration provenance and data-version rejection/migration; and +- client-owned projection into a product view model without native rendering; - proof that tool output cannot register or import native code. From b964e72bceac86db3fb5cc6b7bda5b4853dbf247 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 11 Aug 2026 11:44:03 -0700 Subject: [PATCH 04/33] Refine control model view offers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 19 +++++- rfcs/0029/conformance-and-adoption-plan.md | 15 +++-- rfcs/0029/control-model-v1-spec.md | 1 + rfcs/0029/implementation-plan.md | 6 ++ rfcs/0029/ui-artifact-v1-spec.md | 68 ++++++++++++++++++++-- 5 files changed, 96 insertions(+), 13 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index b3ff871b..74ffbdef 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -222,7 +222,7 @@ export interface UiArtifact { id: string; revision: number; structuredContent?: JsonValue; - views: UiArtifactView[]; + views: UiArtifactViewOffer[]; state: "pending" | "ready" | "failed" | "expired"; source: { sessionKey: string; @@ -232,11 +232,13 @@ export interface UiArtifact { fallback?: McpAppArtifact | CanvasArtifact; } -export interface UiArtifactView { +export interface UiArtifactViewOffer { id: string; templateUri: string; dataVersion: number; - data: JsonValue; + availability: "inline" | "deferred"; + data?: JsonValue; + recommended?: boolean; fallback?: McpAppArtifact | CanvasArtifact; } ``` @@ -255,6 +257,12 @@ choose any compatible offered view or project the underlying structured content into its own product view model. If no compatible renderer is registered, the host may show structured/text output or use an explicitly sandboxed fallback. +OpenClaw exposes every authorized applicable descriptor, not every fully +materialized payload. A bounded view may be inline. An expensive or sensitive +view is deferred until the client selects it and requests materialization +through a typed, read-only Control Model command. Materialization remains +extension-owned and Gateway-authorized. + V1 uses complete immutable revisions. It does not standardize JSON Patch, JSONL, or a renderer-specific component tree. A later extension may introduce a negotiated patch dialect after conformance evidence demonstrates a shared need. @@ -334,6 +342,11 @@ support unless an exact compatible local registration exists. OpenClaw owns the available view offers and their semantics; Lobster or another host owns which offer it selects and how it maps that projection into its own view model. +View discovery is filtered to the authenticated caller, selected session, +enabled extension surface, and current policy. It must not disclose hidden +extensions or unavailable tools. Client renderer advertisement is delivered to +the trusted Gateway and is not exposed verbatim to extensions by default. + ### Compatibility and release The package follows the OpenClaw calendar release train and declares its diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index e9f7b9a9..ab9b545f 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -43,8 +43,8 @@ proof, and deletion agree. | Tools | call/result association, out-of-order result, duplicate ID, bounded progress | | Approvals/questions | allowed action, denial, expiry, reconnect, stale action | | Commands | success, forbidden, conflict, timeout, abort, unsupported, idempotent retry | -| Artifacts | multiple view offers, client selection, native, unknown, malformed, fallback, revisions, history, expiry | -| Capability split | extension absent/disabled, renderer absent, version mismatch, stale advertisement | +| Artifacts | multiple view descriptors, lazy materialization, client selection, native, unknown, malformed, fallback, revisions, history, expiry | +| Capability split | extension absent/disabled, renderer absent, version mismatch, stale/private advertisement, authorization-filtered discovery | | Bounds | messages, progress, artifacts, bytes/depth, inactive conversations | Each fixture identifies: @@ -64,8 +64,8 @@ Each fixture identifies: - formatting, lint, typecheck, and diff hygiene; - affected package tests; - browser-safe import graph; -- fixture schema validation; and -- no framework or product imports in core. +- fixture schema validation; +- no framework or product imports in core; and - no subscriber/render work in the Gateway receive stack. ### Per-PR @@ -81,6 +81,7 @@ Each fixture identifies: - exact local registry and schema version; - multiple OpenClaw view offers and a client-selected non-default view; +- deferred descriptors with only the selected payload materialized; - valid and invalid artifact data; - allowed and denied action; - stale artifact action; @@ -125,6 +126,7 @@ The package must measure: - per-event reconciliation cost; - snapshot allocation rate during streaming; - retained bytes for messages, progress, tools, and artifacts; +- descriptor enumeration and selected-view materialization latency/bytes; - inactive conversation eviction; and - reconnect/resync latency. @@ -146,7 +148,10 @@ The following are blocking: - implicit executable fallback for unknown artifacts; - loss of MCP App sandbox/CSP/expiry behavior; and - deletion of the incumbent path before rollback proof; -- unreviewed renderer registration or unsupported artifact data version. +- unreviewed renderer registration or unsupported artifact data version; +- eager materialization of unselected deferred views; +- discovery that reveals unauthorized extension/tool/view availability; and +- verbatim extension access to unrelated client renderer inventory. ## Independent adopter proof diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index 46ddda6b..83239ff1 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -211,6 +211,7 @@ Candidate v1 commands are: - abort the active run; - answer a question; - approve or deny a pending request; and +- materialize one exact deferred UI view for the current artifact revision; and - retry only where the Gateway exposes a safe retry contract. Each command defines: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index dae3308a..68c2eb75 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -76,6 +76,8 @@ Control UI and independent-host reducers for the adopted conversation slice. - Define and validate v1 artifacts. - Preserve all applicable OpenClaw core/extension view offers and let the client select among compatible views. +- Enumerate authorized descriptors cheaply and materialize only the selected + deferred view. - Preserve sanitized artifact data through live projection and history. - Adapt existing MCP App and Canvas previews into explicit fallbacks. - Add revision, expiry, bound, and structured failure behavior. @@ -85,6 +87,7 @@ Control UI and independent-host reducers for the adopted conversation slice. - Known and unknown template URIs. - Multiple offered views with client-owned selection. +- Authorization-filtered discovery and selected-only materialization. - Malformed/oversized data. - Increasing, duplicate, stale, and conflicting revisions. - History reload and reconnect. @@ -127,6 +130,8 @@ Superseded UI-local session/conversation capability and reconciliation code. - Map model snapshots into M's existing `SessionView`. - Select the Lobster-compatible OpenClaw view projection without making that choice canonical for other clients. +- Keep a compatible user selection stable across reconnect and artifact + revisions. - Keep the renderer passive. - Preserve current desktop and web service-port boundaries. - Add a runtime flag and incumbent fallback. @@ -152,6 +157,7 @@ The adopted web-specific Gateway fold/reducer path after parity. - Add schema validation and named action binding. - Pin registration and artifact data versions and emit safe action correlation. - Preserve text and MCP App fallback. +- Request deferred data only after Lobster selects that view. ### Proof diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 69231303..1876c0dc 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -35,17 +35,19 @@ export interface UiArtifact { id: string; revision: number; structuredContent?: JsonValue; - views: UiArtifactView[]; + views: UiArtifactViewOffer[]; state: "pending" | "ready" | "failed" | "expired"; source: UiArtifactSource; error?: UiArtifactError; } -export interface UiArtifactView { +export interface UiArtifactViewOffer { id: string; templateUri: string; dataVersion: number; - data: JsonValue; + availability: "inline" | "deferred"; + data?: JsonValue; + recommended?: boolean; fallback?: UiArtifactFallback; } @@ -83,6 +85,16 @@ content as a calendar, list, table, summary, form, dashboard, or sandboxed app. View order is deterministic but is not a requirement that the client render the first view. +OpenClaw exposes all authorized applicable view descriptors. It does not need +to eagerly compute every view payload: + +- `inline` includes bounded validated `data` in the offer. +- `deferred` omits `data` until the client selects the view and requests + materialization through a typed Control Model command. + +A deferred view must not perform external work, access protected data, or +consume a tool invocation merely because its descriptor was enumerated. + `templateUri` is a bounded absolute URI. Schemes are not globally trusted. Hosts may register product-specific schemes such as `clawpilot://widgets/calendar` or use a standardized `ui://` resource @@ -110,10 +122,16 @@ but the recommendation neither grants trust nor overrides the client choice. A client may ignore every offered view and project `structuredContent` into its own product view model. +A client should keep a compatible user selection stable across artifact +revisions and reconnects. It must not silently switch to a newly recommended +view while the current choice remains valid. A fallback caused by an invalid, +expired, or unavailable selection is observable to the product UX. + ## Data and structured content -Each view's `data` contains component-shaped untrusted JSON. A native renderer registration -must provide a schema and reject invalid data before component construction. +An inline or materialized view's `data` contains component-shaped untrusted +JSON. A native renderer registration must provide a schema and reject invalid +data before component construction. `structuredContent` contains model- or transcript-relevant domain output when available. It is not a private channel for secrets, hidden instructions, @@ -167,6 +185,11 @@ contract provides such a carrier. OpenClaw can use that information to filter or rank view offers, but the client makes the final selection against its current registry. +The Gateway filters discovery to views authorized for the authenticated caller, +selected session, enabled extension surface, and current policy. Enumeration +must not reveal hidden extensions, unavailable tools, tenant-external +capabilities, or view data that would require a denied operation. + Capability advertisement: - is optional and may be stale; @@ -175,11 +198,42 @@ Capability advertisement: - does not authorize an OpenClaw operation; and - must not be required for structured/text or sandboxed fallback output. +Renderer advertisement is bounded client metadata delivered to the trusted +Gateway. The Gateway must not forward the client's complete renderer inventory +verbatim to extensions by default. It may answer an extension's bounded +compatibility question or select/rank offers without disclosing unrelated +client capabilities. + An extension that emits an artifact remains responsible for useful structured or text output when practical. The client independently resolves all offered views against its current registry. If no exact compatible registration exists, it uses an accepted declared fallback or renders the structured/text result. +## Deferred materialization + +The candidate Control Model command is conceptually: + +```ts +materializeView(input: { + artifactId: string; + artifactRevision: number; + viewId: string; + signal?: AbortSignal; +}): Promise; +``` + +The final method name may differ. The contract must: + +- require the current artifact revision and exact offered view ID; +- be read-only and idempotent for that revision; +- re-enter Gateway authentication, session scope, extension availability, and + policy checks; +- enforce finite time, result bytes, depth, and retained cache; +- return the same view ID with `availability: "inline"` and validated data; +- reject stale, removed, unsupported, forbidden, expired, and oversized views + distinctly; and +- avoid materializing any unselected sibling view. + ## Actions A native component may emit only a named action declared by its local @@ -285,6 +339,8 @@ Fixtures must cover: - registered native URI; - multiple compatible views with a non-first client selection; +- deferred view enumeration without payload computation; +- selected materialization and proof that sibling views remain unmaterialized; - unknown URI with structured output only; - unknown URI with accepted MCP App fallback; - malformed and oversized data; @@ -296,4 +352,6 @@ Fixtures must cover: - component schema evolution; - registration provenance and data-version rejection/migration; and - client-owned projection into a product view model without native rendering; +- authorization-filtered discovery and renderer-advertisement privacy; +- stable user selection across revisions and reconnect; and - proof that tool output cannot register or import native code. From 110604c08cd171527b409f75caca877a0e65b31b Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 11 Aug 2026 14:17:12 -0700 Subject: [PATCH 05/33] Clarify durable artifact projections Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 8 ++++++++ rfcs/0029/implementation-plan.md | 4 ++++ rfcs/0029/ui-artifact-v1-spec.md | 15 +++++++++++++++ 3 files changed, 27 insertions(+) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 74ffbdef..27e759f6 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -263,6 +263,14 @@ view is deferred until the client selects it and requests materialization through a typed, read-only Control Model command. Materialization remains extension-owned and Gateway-authorized. +Presentation placement does not define artifact identity. A client may render +the same artifact revision inline in chat, in an expanded panel, or in a +dedicated artifact surface. Its stable `id` and monotonic `revision` let later +turns or tool runs update that logical artifact instead of emitting unrelated +cards. V1 durability means addressable, revisioned session state that survives +history reload and reconnect. It does not require permanent document storage, +cross-session retention, or a collaborative document protocol. + V1 uses complete immutable revisions. It does not standardize JSON Patch, JSONL, or a renderer-specific component tree. A later extension may introduce a negotiated patch dialect after conformance evidence demonstrates a shared need. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 68c2eb75..de4ad8cc 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -79,6 +79,8 @@ Control UI and independent-host reducers for the adopted conversation slice. - Enumerate authorized descriptors cheaply and materialize only the selected deferred view. - Preserve sanitized artifact data through live projection and history. +- Preserve one artifact identity across inline chat and dedicated product + surfaces, including higher revisions published by later turns. - Adapt existing MCP App and Canvas previews into explicit fallbacks. - Add revision, expiry, bound, and structured failure behavior. - Keep renderer registries outside the package. @@ -91,6 +93,8 @@ Control UI and independent-host reducers for the adopted conversation slice. - Malformed/oversized data. - Increasing, duplicate, stale, and conflicting revisions. - History reload and reconnect. +- Inline and dedicated projections of the same artifact ID. +- Later-turn revision without creating a duplicate artifact. - MCP App fallback and expiry. - Proof that metadata cannot select an import or register a component. diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 1876c0dc..04ae9f05 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -74,6 +74,19 @@ content is ignored. A duplicate revision with different content is a structured conflict. A lower revision is stale and must not replace current state. +An artifact's presentation location is not part of its identity. A client may +project the current revision inline beside its source message, in an expanded +panel, or in a dedicated artifact surface. Later conversation turns and tool +runs may publish a higher revision for the same logical `id`, subject to normal +authorization and reconciliation rules. + +V1 durability is scoped to the owning session: current artifact identity and +revision survive authoritative history reload and reconnect. Permanent +document storage, cross-session retention, collaborative editing, and merging +concurrent user-authored revisions are outside this contract. A product may +persist or promote an artifact through a separate explicitly authorized +operation. + An artifact from a retired connection epoch may be reconciled only through authoritative history. It must not update live state directly. @@ -347,6 +360,8 @@ Fixtures must cover: - duplicate, stale, conflicting, and increasing revisions; - history reload; - reconnect with a retired live revision; +- inline and dedicated-surface projections of the same artifact identity; +- a later turn publishing a higher revision of an existing artifact; - expired fallback; - allowed, denied, unknown, and stale-revision actions; - component schema evolution; From 97d6bfc1ee48ae2a125d2c78f6d8fc949da768f5 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 13 Aug 2026 17:30:14 -0700 Subject: [PATCH 06/33] docs(rfc): place Control Model in Gateway Client Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 123 ++++++++++++--------- rfcs/0029/conformance-and-adoption-plan.md | 13 ++- rfcs/0029/control-model-v1-spec.md | 6 +- rfcs/0029/implementation-plan.md | 19 ++-- rfcs/0029/ui-artifact-v1-spec.md | 6 +- 5 files changed, 92 insertions(+), 75 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 27e759f6..eb58f01f 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -3,7 +3,7 @@ title: OpenClaw Control Model authors: - Gio Della-Libera created: 2026-08-11 -last_updated: 2026-08-11 +last_updated: 2026-08-14 status: draft issue: rfc_pr: @@ -13,13 +13,13 @@ rfc_pr: ## Summary -OpenClaw should provide a framework-neutral Control Model above -`@openclaw/gateway-client`. The model would expose immutable state snapshots, -typed commands, history/live reconciliation, and renderer-neutral UI artifacts -without depending on Lit, React, routes, or product presentation. OpenClaw's -Control UI and independently owned product shells could consume the same -behavior while retaining their own components, navigation, theming, -authentication, and rollout. +OpenClaw should provide a framework-neutral Control Model as optional +`@openclaw/gateway-client/model` subpaths above the existing browser transport. +The model would expose immutable state snapshots, typed commands, history/live +reconciliation, and renderer-neutral UI artifacts without depending on Lit, +React, routes, or product presentation. OpenClaw's Control UI and independently +owned product shells could consume the same behavior while retaining their own +components, navigation, theming, authentication, and rollout. This document is a fork-only design preview. It does not request RFC intake, open an upstream pull request, or claim maintainer acceptance. @@ -55,18 +55,17 @@ the existing projection. The desired architecture is: -```text -OpenClaw Gateway - | -@openclaw/gateway-client - | -@openclaw/control-model - snapshots / commands / UI artifacts - | - +-------------------------+ - | | -OpenClaw Control UI Independent product shell -Lit presentation React/native presentation +```mermaid +flowchart TB + gateway["OpenClaw Gateway"] + transport["@openclaw/gateway-client/browser
transport, authentication, reconnect"] + model["@openclaw/gateway-client/model
sessions, conversations, commands, artifacts"] + controlUi["OpenClaw Control UI
Lit presentation"] + product["Independent product shell
React or native presentation"] + + gateway --> transport --> model + model --> controlUi + model --> product ``` One OpenClaw-owned behavioral model can serve multiple presentations without @@ -123,15 +122,28 @@ documents: - [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) - [Implementation and PR plan](0029/implementation-plan.md) -### Package boundary +### Draft implementation stack -Add `@openclaw/control-model` to the OpenClaw monorepo. The package is -framework-neutral and browser-safe. Its public module graph must not import -Lit, React, DOM components, route definitions, product authentication, -localization catalogs, CSS, or Control UI presentation helpers. +The proposed boundary has four fork-only implementation drafts: -The package consumes a narrow host-supplied Gateway binding compatible with the -public Gateway client: +1. [OC1: Gateway Client model foundation](https://github.com/giodl73-repo/openclaw/pull/230) +2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) +3. [OC3: renderer-neutral UI artifacts](https://github.com/giodl73-repo/openclaw/pull/232) +4. [OC4: Control UI reference adoption](https://github.com/giodl73-repo/openclaw/pull/238) + +These drafts are evidence for review, not an upstream submission or accepted +roadmap. + +### Module boundary + +Add the framework-neutral, browser-safe Control Model as optional exports from +`@openclaw/gateway-client`: `model`, `model/catalog`, and +`model/session-event-refresh`. The model module graph must not import Lit, +React, DOM components, route definitions, product authentication, localization +catalogs, CSS, or Control UI presentation helpers. + +The model consumes a narrow host-supplied Gateway binding compatible with the +public Gateway Client: ```ts export interface ControlGateway { @@ -142,7 +154,7 @@ export interface ControlGateway { } ``` -The binding lets the package reuse OpenClaw's browser, Node, or hosted transport +The binding lets the model reuse OpenClaw's browser, Node, or hosted transport without owning credential persistence, product routing, or socket creation. The Control Model exposes immutable snapshots and typed commands: @@ -159,7 +171,7 @@ export interface ControlModel { Subscriptions are invalidation signals. Consumers read the current immutable snapshot after notification. This works with framework adapters without -embedding framework hooks in the package. +embedding framework hooks in the model. ### V1 capability boundary @@ -183,7 +195,7 @@ Snapshots are serializable except for explicitly documented command handles. They use stable identifiers, finite retained state, and typed lifecycle states. They do not expose mutable Control UI objects. -The package owns: +The model owns: - the initial history snapshot; - live event application; @@ -298,7 +310,7 @@ The Control Model is presentation support, not an authorization authority. OpenClaw maintainers own: -- package contracts and implementation; +- Gateway Client model contracts and implementation; - Gateway-to-model normalization and reconciliation; - stable state, command, error, and artifact semantics; - compatibility fixtures and release versioning; @@ -331,15 +343,17 @@ The Control Model does not generate UI capabilities independently of either side. It normalizes the artifact emitted by the active extension, exposes the current client-rendering decision, and preserves a safe fallback: -```text -installed extension emits artifact plus view offers - | - v -Control Model normalizes identity, views, data, lifecycle, and fallback - | - v -client selects a compatible view and local view-model projection - or structured/MCP App fallback +```mermaid +flowchart TB + extension["Installed extension emits artifact and view offers"] + model["Control Model normalizes identity, views, data, lifecycle, and fallback"] + selection{"Client selects a compatible trusted view"} + native["Local view-model projection
and native renderer"] + fallback["Structured or sandboxed
MCP App fallback"] + + extension --> model --> selection + selection -->|compatible registration| native + selection -->|no compatible registration| fallback ``` Client capability advertisement may let an extension avoid producing an @@ -357,12 +371,13 @@ the trusted Gateway and is not exposed verbatim to extensions by default. ### Compatibility and release -The package follows the OpenClaw calendar release train and declares its -compatible Gateway protocol window. Additive fields must not break consumers. -Incompatible snapshot or command changes require a documented migration and a -major contract-version decision independent of the wire protocol number. +The Gateway Client model follows the OpenClaw calendar release train and +declares its compatible Gateway protocol window. Additive fields must not break +consumers. Incompatible snapshot or command changes require a documented +migration and a major contract-version decision independent of the wire +protocol number. -The package begins as a monorepo workspace package. Publication requires: +The model subpaths begin as fork-only exports. Publication requires: - adoption by OpenClaw Control UI; - adoption by one independent host; @@ -379,7 +394,7 @@ throwing subscriber cannot be awaited by protocol event delivery. The implementation is intentionally incremental: -1. package boundary plus connection and session-catalog snapshots; +1. Gateway Client model boundary plus connection and session-catalog snapshots; 2. selected-conversation projection and commands; 3. renderer-neutral artifact projection and existing MCP App/Canvas adapters; 4. OpenClaw Control UI adoption of one complete slice; and @@ -399,12 +414,12 @@ application internals. Making that graph injectable would still require an independent host to load the Lit application and track private module changes. The reusable boundary belongs below the application. -### Why not use the Gateway client directly +### Why not use the Gateway Client browser transport directly -The Gateway client deliberately exposes protocol methods and events. It should -not absorb session catalogs, conversation snapshots, tool outcomes, and UI -artifacts. Those are a distinct state-and-command layer, and every UI otherwise -reimplements them. +The browser transport deliberately exposes protocol methods and events. Session +catalogs, conversation snapshots, tool outcomes, and UI artifacts remain a +distinct optional state-and-command layer under `gateway-client/model`; every UI +otherwise reimplements them. ### Why not publish Control UI's application context @@ -447,7 +462,7 @@ independent UX. ## Unresolved questions - Which exact session and chat commands form the smallest useful v1? -- Should the first package release be public or remain workspace-only until +- When should the optional Gateway Client model subpaths publish after independent adoption lands? - Which existing Control UI normalizers can move unchanged, and which require a clean implementation because they mix UI concerns? @@ -457,5 +472,5 @@ independent UX. Gateway first publish a narrower sanitized artifact envelope? - What finite size, depth, count, and retention defaults should v1 require? - Which Control UI slice should become the first reference adopter? -- Which maintainers own package compatibility and security review if the - package is published? +- Which maintainers own model compatibility and security review if the subpaths + are published? diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index ab9b545f..9b70e045 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -1,7 +1,7 @@ # Control Model conformance and adoption plan -This plan turns RFC 0029 into independently reviewable gates. A package, UI -artifact, or adopter is not supported until source behavior, fixtures, live +This plan turns RFC 0029 into independently reviewable gates. A model subpath, +UI artifact, or adopter is not supported until source behavior, fixtures, live proof, and deletion agree. ## Evidence principles @@ -22,13 +22,13 @@ proof, and deletion agree. | Layer | Review surface | Required proof | Deletion unlocked | | --- | --- | --- | --- | -| M1 package boundary | OpenClaw PR 1 | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | +| M1 Gateway Client model boundary | OpenClaw PR 1 | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | | M2 conversation projection | OpenClaw PR 2 | Shared history/live/reconnect/tool/approval corpus | Per-consumer chat reducers and event folding | | A1 UI artifacts | OpenClaw PR 3 | Native, structured-only, MCP fallback, malformed, stale, history cases | Tool-specific presentation interpretation | | O1 Control UI adoption | OpenClaw PR 4 | Existing Control UI behavior unchanged on shared fixtures and E2E | Adopted UI-local capability/reducer code | | H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | -| R1 publication | OpenClaw PR 5/release | Two consumers, package acceptance, compatibility and support policy | Workspace-only distribution | +| R1 publication | OpenClaw PR 5/release | Two consumers, package acceptance, compatibility and support policy | Fork-only distribution | ## Shared fixture families @@ -70,7 +70,7 @@ Each fixture identifies: ### Per-PR -- complete `@openclaw/control-model` tests; +- complete `@openclaw/gateway-client/model` tests; - Gateway protocol compatibility tests; - current Control UI tests for affected behavior; - source fixture and real loopback Gateway proof; @@ -157,7 +157,8 @@ The following are blocking: The first independent adopter should: -1. consume the package through an existing supported Gateway route; +1. consume the Gateway Client model through an existing supported Gateway + route; 2. choose among OpenClaw-provided views and adapt the selected projection into its existing view model rather than create another shared vocabulary; 3. render one representative conversation; diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index 83239ff1..0c0a4427 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -1,9 +1,9 @@ # Control Model v1 specification This document defines the candidate behavioral contract for -`@openclaw/control-model`. It specifies framework-neutral state and commands -above a supported OpenClaw Gateway client. It does not define presentation, -product authentication, or another wire protocol. +`@openclaw/gateway-client/model`. It specifies framework-neutral state and +commands above the Gateway Client browser transport. It does not define +presentation, product authentication, or another wire protocol. Status: draft. This is a fork-only preview and has not been submitted or accepted upstream. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index de4ad8cc..261069ab 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -14,18 +14,18 @@ prove the contract. application framework. - Keep OpenClaw Control UI behavior unchanged during adoption. -## OpenClaw PR 1: package and session snapshots +## OpenClaw PR 1: Gateway Client model foundation ### Scope -- Add workspace package `packages/control-model`. +- Add optional `@openclaw/gateway-client/model` subpaths. - Define host Gateway binding, immutable external-store contract, lifecycle, structured errors, and bounds configuration. - Isolate bounded reconciliation and subscriber notification from the Gateway receive stack. - Project connection state and session catalog. - Reuse canonical protocol types without re-exporting the entire protocol. -- Add package documentation and browser-safe import checks. +- Add Gateway Client model documentation and browser-safe import checks. ### Explicit exclusions @@ -41,7 +41,7 @@ prove the contract. - Session list plus create/update/delete reconciliation. - Connection-epoch retirement. - Retryable observer outage and authoritative refresh. -- Package graph contains no framework, DOM component, or product import. +- Model graph contains no framework, DOM component, or product import. ### Deletion target @@ -83,7 +83,7 @@ Control UI and independent-host reducers for the adopted conversation slice. surfaces, including higher revisions published by later turns. - Adapt existing MCP App and Canvas previews into explicit fallbacks. - Add revision, expiry, bound, and structured failure behavior. -- Keep renderer registries outside the package. +- Keep renderer registries outside the model. ### Proof @@ -107,7 +107,7 @@ association logic. ### Scope -- Adapt the existing Control UI Gateway store to the package binding. +- Adapt the existing Control UI Gateway store to the model binding. - Move the session catalog and one complete conversation route to Control Model snapshots. - Keep Lit components, routes, styling, and behavior unchanged. @@ -130,7 +130,8 @@ Superseded UI-local session/conversation capability and reconciliation code. ### Scope -- Consume the workspace or fork package through Lobster's hosted Gateway seam. +- Consume the fork-only Gateway Client model through Lobster's hosted Gateway + seam. - Map model snapshots into M's existing `SessionView`. - Select the Lobster-compatible OpenClaw view projection without making that choice canonical for other clients. @@ -204,10 +205,10 @@ One bespoke tool-output parsing/rendering path. ### Scope -- Publish `@openclaw/control-model`. +- Publish the optional `@openclaw/gateway-client/model` subpaths. - Document supported versions and migration policy. - Add framework-neutral quickstart and conformance fixtures. -- Keep optional framework adapters outside the core package unless separately +- Keep optional framework adapters outside the core model unless separately justified. ## Deferred work diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 04ae9f05..6f9a8524 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -1,9 +1,9 @@ # UI artifact v1 specification This document defines a renderer-neutral UI artifact projected by -`@openclaw/control-model`. An artifact lets a host select native first-party -presentation while preserving structured output and sandboxed third-party -fallback. +`@openclaw/gateway-client/model`. An artifact lets a host select native +first-party presentation while preserving structured output and sandboxed +third-party fallback. Status: draft. This is a fork-only preview. From b64f7ee51afc0348ef8d985dfb8694a0eac9c906 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 07:15:21 -0700 Subject: [PATCH 07/33] docs(rfc): record completed adopter evidence Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 57 ++++++++-- rfcs/0029/conformance-and-adoption-plan.md | 24 ++++ rfcs/0029/implementation-plan.md | 124 ++++++++++----------- rfcs/0029/ui-artifact-v1-spec.md | 7 ++ 4 files changed, 133 insertions(+), 79 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index eb58f01f..4456659a 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -107,10 +107,14 @@ making OpenClaw own those products. - Requiring JSON Render or any other renderer library. - Adding a sidecar, service, or new process boundary. The Control Model is an in-process library over an existing Gateway client. -- Defining generic model-authored dashboards, arbitrary layout generation, or a - public component marketplace in v1. +- Replacing OpenClaw's existing dashboard/workboard model, registered widget + providers, layout persistence, or `show_widget`/`dashboard` tool semantics. +- Defining generic model-authored layouts or a public component marketplace in + v1. A dashboard-shaped artifact view is presentation, not the authoritative + OpenClaw board model. - Including config forms, settings navigation, channels, skills, workboards, - or every existing Control UI capability in v1. + or every existing Control UI capability in v1. Configuration requires a + separate authority- and provenance-aware model. ## Proposal @@ -134,6 +138,22 @@ The proposed boundary has four fork-only implementation drafts: These drafts are evidence for review, not an upstream submission or accepted roadmap. +The independent Lobster evidence is also available as a temporary carry plus +six bounded adopter slices: + +1. [L0: temporary Control Model carry](https://microsoft.ghe.com/bic/lobster/pull/8165) +2. [LM1: adapt canonical snapshots into `SessionView`](https://microsoft.ghe.com/giodl/lobster/pull/63) +3. [LM2: render one allowlisted native table artifact](https://microsoft.ghe.com/giodl/lobster/pull/64) +4. [LM3: route one native refresh action through the model](https://microsoft.ghe.com/giodl/lobster/pull/65) +5. [LM4: route ordinary sends through the model](https://microsoft.ghe.com/giodl/lobster/pull/66) +6. [LM5: route active-run aborts through the model](https://microsoft.ghe.com/giodl/lobster/pull/67) +7. [LM6: hydrate selected-session history through the model](https://microsoft.ghe.com/giodl/lobster/pull/68) + +This series proves native React rendering, actions, send, abort, reconnect, and +history while deleting duplicate Lobster Gateway behavior. It intentionally +stops at LM6: remaining raw paths are host-owned operational/security or +compatibility lanes rather than equivalent Control Model behavior. + ### Module boundary Add the framework-neutral, browser-safe Control Model as optional exports from @@ -398,12 +418,25 @@ The implementation is intentionally incremental: 2. selected-conversation projection and commands; 3. renderer-neutral artifact projection and existing MCP App/Canvas adapters; 4. OpenClaw Control UI adoption of one complete slice; and -5. publication after independent adoption and compatibility evidence. +5. independent Lobster adoption through `SessionView`, including native + artifact, action, send, abort, and history deletion evidence; +6. package publication and support ownership after compatibility, security, + and package-acceptance gates; and +7. product rollout with live hosted-Gateway proof, flags, rollback, telemetry, + accessibility, localization, and shareable demo evidence. No later layer is required to accept an earlier bounded layer. Adding another capability after v1 requires an independent consumer, a bounded contract, and a named duplicate implementation or inference path it can delete. +Existing OpenClaw dashboards and settings follow separate adoption paths. +Lobster can host version-matched dashboard and settings routes immediately. +Native dashboards require an optional projection of OpenClaw's existing board +model; native settings require an optional sibling configuration model that +preserves schema, effective value, provenance, authority, validation, candidate +diffs, generation, and transactional activation. Neither belongs in the +conversation snapshot. + ## Rationale ### Why not inject a model into Control UI @@ -461,16 +494,18 @@ independent UX. ## Unresolved questions -- Which exact session and chat commands form the smallest useful v1? - When should the optional Gateway Client model subpaths publish after - independent adoption lands? -- Which existing Control UI normalizers can move unchanged, and which require a - clean implementation because they mix UI concerns? + fork-only two-consumer evidence is accepted? - Does artifact streaming need complete revisions only, or does adoption evidence justify a negotiated patch dialect? -- Should generic MCP tool-result metadata be projected directly, or should the - Gateway first publish a narrower sanitized artifact envelope? - What finite size, depth, count, and retention defaults should v1 require? -- Which Control UI slice should become the first reference adopter? - Which maintainers own model compatibility and security review if the subpaths are published? +- Should a future dashboard projection be a Gateway Client optional subpath or + a separate workboard client while retaining OpenClaw board authority? +- Should the settings projection be + `@openclaw/gateway-client/model/config` or a separate Managed Configuration + client surface? +- If cross-client user-message delivery becomes required, what identity + contract aligns host `clientMessageId`, model idempotency, retry/reconnect, + persisted history, and renderer deduplication? diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 9b70e045..39e7de6c 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -30,6 +30,25 @@ proof, and deletion agree. | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | | R1 publication | OpenClaw PR 5/release | Two consumers, package acceptance, compatibility and support policy | Fork-only distribution | +## Evidence to date + +Fork-only evidence now covers the full bounded V1 thesis: + +| Evidence | Result | +| --- | --- | +| OC1 | Immutable bounded catalog snapshots, explicit host binding, epoch-safe refresh, typed errors, and subscriber isolation. | +| OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | +| OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | +| OC4 | Control UI adoption of canonical active-session and selected-chat state without visual or startup-budget regression. | +| LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | +| LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | + +The independent-adopter gate is therefore demonstrated, not merely planned. +Publication is still blocked on upstream acceptance, package ownership, +compatibility/security gates, and a released dependency. Product shipment is +additionally blocked on Lobster CI, live hosted-Gateway proof, rollout and +rollback controls, telemetry, UX quality, and shareable evidence. + ## Shared fixture families | Family | Minimum cases | @@ -168,6 +187,11 @@ The first independent adopter should: 7. reconnect mid-stream; and 8. identify exact reducer/projection code deleted after parity. +LM1-LM6 satisfy this bounded proof. Future work should not extend the stack +merely to remove every raw Gateway call. Remaining raw lanes must be classified +by ownership first; host operational/security behavior is not Control Model +duplication. + ## Promotion and deletion ledger Every adoption PR records: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 261069ab..8dd282ce 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -126,72 +126,31 @@ association logic. Superseded UI-local session/conversation capability and reconciliation code. -## Lobster/M PR 1: adapter into existing SessionView - -### Scope - -- Consume the fork-only Gateway Client model through Lobster's hosted Gateway - seam. -- Map model snapshots into M's existing `SessionView`. -- Select the Lobster-compatible OpenClaw view projection without making that - choice canonical for other clients. -- Keep a compatible user selection stable across reconnect and artifact - revisions. -- Keep the renderer passive. -- Preserve current desktop and web service-port boundaries. -- Add a runtime flag and incumbent fallback. - -### Proof - -- Existing `SessionView` fixtures. -- Hosted auth and real Gateway. -- Session list, selection, one conversation, tool result, and approval. -- Mid-stream reconnect without duplication. - -### Deletion target - -The adopted web-specific Gateway fold/reducer path after parity. - -## Lobster/M PR 2: first native UI artifact - -### Scope - -- Add a host-owned exact-URI renderer registry. -- Register one bounded first-party component, preferably a calendar golden - scenario already represented by structured tool output. -- Add schema validation and named action binding. -- Pin registration and artifact data versions and emit safe action correlation. -- Preserve text and MCP App fallback. -- Request deferred data only after Lobster selects that view. - -### Proof - -- Valid, invalid, unknown, fallback, and expired artifacts. -- Fluent/M365 theme, accessibility, localization, and responsive behavior. -- Allowed and server-denied action. -- No dynamic import from artifact metadata. - -### Deletion target - -One bespoke tool-output parsing/rendering path. - -## Lobster/M PR 3: streaming, actions, and operations - -### Scope - -- Apply complete artifact revisions during live tool execution. -- Add stale-revision action protection. -- Add telemetry for projection lag, renderer selection, validation failure, - fallback, and action outcome. -- Prove reconnect and rollback. - -### Proof - -- Progressive pending/ready revisions. -- Duplicate/stale revision handling. -- Mid-stream disconnect/resync. -- Slow native renderer does not block Gateway processing. -- Product telemetry contains no raw sensitive artifact payload. +## Lobster/M evidence series + +The bounded independent-adopter series is complete in fork-local drafts. It +uses Lobster's existing hosted Gateway seam and keeps M's `SessionView` as the +passive renderer vocabulary. + +| Slice | Scope and result | Deletion or boundary proved | +| --- | --- | --- | +| L0 | Temporarily carries OC1-OC3 into Lobster and preserves sanitized artifacts through the pinned OpenClaw history projection. | Source-resolved evidence only; not the publication shape. | +| LM1 | Maps canonical conversation snapshots into existing `SessionView` while preserving host-owned raw operational lanes. | React does not parse Gateway events and no second M view model is introduced. | +| LM2 | Renders an exact allowlisted `clawpilot://widgets/table` v1 artifact with schema bounds, durable history identity, and visible fallback. | One trusted native first-party artifact works without importing Control UI. | +| LM3 | Adds one host-owned Refresh action, validates current artifact identity/revision, and dispatches through `conversation.send`. | Native components receive no raw Gateway authority; stale and denied actions fail visibly. | +| LM4 | Routes ordinary sends through `ControlModelConversation.send` while retaining Lobster attachment preprocessing and operational turn tracking. | Deletes the duplicate raw ordinary `chat.send` request path. | +| LM5 | Routes active foreground aborts through `ControlModelConversation.abort`. | Deletes duplicate raw active-run abort dispatch while retaining no-run abort-all recovery. | +| LM6 | Explicitly refreshes and projects canonical selected-session history through the model. | Deletes duplicate selected-session raw `chat.history` normalization. | + +The series stops at LM6. Operator/security approvals, no-run abort-all, +session administration, memory, automation compatibility, attachment +preprocessing, and host run ownership remain outside this bounded deletion +case. + +Cross-client user-message correlation is a separate future contract rather +than LM7. It must align Lobster `clientMessageId`, model idempotency, +retry/reconnect, non-renderer callers, persisted history, canonical user +identity, and renderer deduplication. ## OpenClaw PR 5: publication @@ -211,13 +170,42 @@ One bespoke tool-output parsing/rendering path. - Keep optional framework adapters outside the core model unless separately justified. +## Productization after publication + +1. Land the supported package surface and replace Lobster's temporary source + carry with a released OpenClaw dependency. +2. Resolve Lobster required checks and land the bounded stack behind a runtime + flag with rollback. +3. Run a live hosted-Gateway proof covering authentication, reconnect, + history, streaming, native artifact action, send, and abort. +4. Add safe telemetry for projection lag, fallback, validation failure, action + outcome, and rollback without recording raw artifact data. +5. Finish Fluent quality, accessibility, localization, security review, and + shareable screenshots or recordings. + +## Adjacent surfaces + +- **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. + A future native surface must project OpenClaw's board identity, registered + widget providers, layout, persistence, focus, docking, and tool operations; + it must not recreate dashboards from generic conversation artifacts. +- **Settings:** host OpenClaw settings first, read-only when Lobster lacks + secure write authority. A future native settings surface should consume a + sibling configuration model with descriptors, effective value, provenance, + owner, writability and lock reason, validation findings, candidate diff, + generation, and transactional apply/reload status. +- **Canvas and MCP Apps:** preserve them as explicit sandboxed fallbacks rather + than converting their executable state into trusted native React. + ## Deferred work -- Config/settings capability. - Channels, skills, nodes, workboards, and admin surfaces. - JSON Patch/JSONL artifact dialect. -- Model-visible component catalogs and generative dashboards. +- Model-visible component catalogs and generic generated layouts. - Third-party native component SDK. - Stable framework-specific adapters. +- Cross-client user-message identity and retry correlation. +- First-class action-run lifecycle, typed interaction payloads, stateful + artifact evolution, and durable document semantics. Each deferred surface requires a separate owner-first slice and deletion case. diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 6f9a8524..0a51abe9 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -98,6 +98,13 @@ content as a calendar, list, table, summary, form, dashboard, or sandboxed app. View order is deterministic but is not a requirement that the client render the first view. +A dashboard-shaped artifact view is only a presentation of one conversation +artifact. It does not replace OpenClaw's authoritative dashboard/workboard +model, registered widget providers, board identity, layout, persistence, +focus, docking, or `show_widget`/`dashboard` tool operations. A native client +for those capabilities requires a separate projection of the existing board +model. + OpenClaw exposes all authorized applicable view descriptors. It does not need to eagerly compute every view payload: From 1d1715498507a0aa47342052a8defce71a8cf8e4 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 08:44:47 -0700 Subject: [PATCH 08/33] docs(rfc): record board and config model evidence Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 34 +++++++++++++++------- rfcs/0029/conformance-and-adoption-plan.md | 2 ++ rfcs/0029/implementation-plan.md | 17 ++++++----- 3 files changed, 36 insertions(+), 17 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 4456659a..4e1be14e 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -154,6 +154,18 @@ history while deleting duplicate Lobster Gateway behavior. It intentionally stops at LM6: remaining raw paths are host-owned operational/security or compatibility lanes rather than equivalent Control Model behavior. +Two adjacent owner-first projections now have separate fork-only evidence: + +- `@openclaw/gateway-client/model/board` extracts the existing selected-session + board reconciliation from Control UI while preserving OpenClaw board, + provider, ticket, grant, persistence, and sandbox authority. Control UI is + the reference adopter. A Lobster adopter remains blocked on selecting an + OpenClaw/LobsterClaw generation that contains the coordinated board stack. +- `@openclaw/gateway-client/model/config` provides read-only authored + configuration snapshots and read-scoped schema lookup. Lobster LC1 consumes + it through Electron-owned Gateway transport and renders one native read-only + settings category without exposing raw config or write authority to React. + ### Module boundary Add the framework-neutral, browser-safe Control Model as optional exports from @@ -431,11 +443,13 @@ contract, and a named duplicate implementation or inference path it can delete. Existing OpenClaw dashboards and settings follow separate adoption paths. Lobster can host version-matched dashboard and settings routes immediately. -Native dashboards require an optional projection of OpenClaw's existing board -model; native settings require an optional sibling configuration model that -preserves schema, effective value, provenance, authority, validation, candidate -diffs, generation, and transactional activation. Neither belongs in the -conversation snapshot. +The Board Model proof now demonstrates the optional projection of OpenClaw's +existing board model, but not a Lobster adopter on the pinned pre-board +generation. The Config Model and LC1 proof demonstrate a native read-only +settings surface over authored values and schema descriptors. Governed writes +still require provenance, authority, validation, candidate diffs, generation, +and transactional activation from Managed Configuration. Neither model belongs +in the conversation snapshot. ## Rationale @@ -501,11 +515,11 @@ independent UX. - What finite size, depth, count, and retention defaults should v1 require? - Which maintainers own model compatibility and security review if the subpaths are published? -- Should a future dashboard projection be a Gateway Client optional subpath or - a separate workboard client while retaining OpenClaw board authority? -- Should the settings projection be - `@openclaw/gateway-client/model/config` or a separate Managed Configuration - client surface? +- What release and support gates should promote the proven optional + `@openclaw/gateway-client/model/board` subpath? +- Should governed settings writes extend the proven read-only + `@openclaw/gateway-client/model/config` surface or remain a separate Managed + Configuration client? - If cross-client user-message delivery becomes required, what identity contract aligns host `clientMessageId`, model idempotency, retry/reconnect, persisted history, and renderer deduplication? diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 39e7de6c..f4f27a50 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,6 +42,8 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC4 | Control UI adoption of canonical active-session and selected-chat state without visual or startup-budget regression. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | +| Board Model | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. A second host waits on a board-capable LobsterClaw generation. | +| Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. Publication is still blocked on upstream acceptance, package ownership, diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 8dd282ce..c8a6bf33 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -186,14 +186,17 @@ identity, and renderer deduplication. ## Adjacent surfaces - **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. - A future native surface must project OpenClaw's board identity, registered - widget providers, layout, persistence, focus, docking, and tool operations; - it must not recreate dashboards from generic conversation artifacts. + The first fork-only Board Model proof now extracts selected-session board + reconciliation into `@openclaw/gateway-client/model/board` and keeps Control + UI as the reference adopter. A native Lobster adapter must use a board-capable + OpenClaw generation and must not recreate dashboards from generic + conversation artifacts. - **Settings:** host OpenClaw settings first, read-only when Lobster lacks - secure write authority. A future native settings surface should consume a - sibling configuration model with descriptors, effective value, provenance, - owner, writability and lock reason, validation findings, candidate diff, - generation, and transactional apply/reload status. + secure write authority. The read-only Config Model and Lobster LC1 proof now + render selected authored values with descriptors and reload impact through a + main-process adapter. Effective defaults, provenance, owner, writability and + lock reason, validation findings, candidate diff, generation, and + transactional apply/reload status remain Managed Configuration work. - **Canvas and MCP Apps:** preserve them as explicit sandboxed fallbacks rather than converting their executable state into trusted native React. From 61e00dba552bed2a9cedf87c09a7b90a0411797f Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 10:26:45 -0700 Subject: [PATCH 09/33] docs(rfc): link adjacent model proofs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 4e1be14e..2805c867 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -156,12 +156,14 @@ compatibility lanes rather than equivalent Control Model behavior. Two adjacent owner-first projections now have separate fork-only evidence: -- `@openclaw/gateway-client/model/board` extracts the existing selected-session - board reconciliation from Control UI while preserving OpenClaw board, +- [Board Model fork proof](https://github.com/giodl73-repo/openclaw/pull/240) + extracts the existing selected-session reconciliation into + `@openclaw/gateway-client/model/board` from Control UI while preserving OpenClaw board, provider, ticket, grant, persistence, and sandbox authority. Control UI is the reference adopter. A Lobster adopter remains blocked on selecting an OpenClaw/LobsterClaw generation that contains the coordinated board stack. -- `@openclaw/gateway-client/model/config` provides read-only authored +- [Config Model LC1 fork proof](https://microsoft.ghe.com/giodl/lobster/pull/69) + provides `@openclaw/gateway-client/model/config` read-only authored configuration snapshots and read-scoped schema lookup. Lobster LC1 consumes it through Electron-owned Gateway transport and renders one native read-only settings category without exposing raw config or write authority to React. From dacfda0f21f4bee31f2259e3014347bfebbb78fa Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 13:01:18 -0700 Subject: [PATCH 10/33] docs: record adjacent model proof gates Document the Config LC1 Electron evidence and the first compatible Board Model release tag. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 2805c867..5fa699f5 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -160,13 +160,19 @@ Two adjacent owner-first projections now have separate fork-only evidence: extracts the existing selected-session reconciliation into `@openclaw/gateway-client/model/board` from Control UI while preserving OpenClaw board, provider, ticket, grant, persistence, and sandbox authority. Control UI is - the reference adopter. A Lobster adopter remains blocked on selecting an - OpenClaw/LobsterClaw generation that contains the coordinated board stack. + the reference adopter. Release ancestry shows no stable tag contains the + coordinated board stack. `v2026.8.1-beta.2` is the first tag containing the + full implementation plus the later ownership and UI hardening; the extraction + applies cleanly there with 55 focused tests and a Gateway Client build. + Lobster adoption therefore remains gated on a stable board-capable generation + or an explicit beta-admission decision. - [Config Model LC1 fork proof](https://microsoft.ghe.com/giodl/lobster/pull/69) provides `@openclaw/gateway-client/model/config` read-only authored configuration snapshots and read-scoped schema lookup. Lobster LC1 consumes it through Electron-owned Gateway transport and renders one native read-only - settings category without exposing raw config or write authority to React. + settings category without exposing raw config or write authority to React. A + real Electron Gateway fixture now proves the populated native page, authored + value boundary, and restart guidance. ### Module boundary @@ -447,11 +453,14 @@ Existing OpenClaw dashboards and settings follow separate adoption paths. Lobster can host version-matched dashboard and settings routes immediately. The Board Model proof now demonstrates the optional projection of OpenClaw's existing board model, but not a Lobster adopter on the pinned pre-board -generation. The Config Model and LC1 proof demonstrate a native read-only -settings surface over authored values and schema descriptors. Governed writes -still require provenance, authority, validation, candidate diffs, generation, -and transactional activation from Managed Configuration. Neither model belongs -in the conversation snapshot. +generation. No stable OpenClaw tag currently contains the coordinated board +stack; `v2026.8.1-beta.2` is the first fully compatible tag and passes the +Board Model extraction proof. The Config Model and LC1 proof demonstrate a +native read-only settings surface over authored values and schema descriptors, +including a real Electron screenshot. Governed writes still require provenance, +authority, validation, candidate diffs, generation, and transactional +activation from Managed Configuration. Neither model belongs in the +conversation snapshot. ## Rationale From a3e894557c02b1d62b7a9bb8223a38468dca4237 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 17:55:01 -0700 Subject: [PATCH 11/33] docs: prepare Control Model RFC filing Update the fork-only RFC with Board LB1 evidence, a narrow review scope, and proposed OC5-OC7 plus adjacent Board and Config follow-up gates. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 90 +++++++++++++----- rfcs/0029/conformance-and-adoption-plan.md | 15 +-- rfcs/0029/implementation-plan.md | 102 +++++++++++++++++---- 3 files changed, 160 insertions(+), 47 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 5fa699f5..c4ded26a 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -3,10 +3,10 @@ title: OpenClaw Control Model authors: - Gio Della-Libera created: 2026-08-11 -last_updated: 2026-08-14 +last_updated: 2026-08-15 status: draft issue: -rfc_pr: +rfc_pr: https://github.com/giodl73-repo/rfcs/pull/8 --- # Proposal: OpenClaw Control Model @@ -126,7 +126,18 @@ documents: - [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) - [Implementation and PR plan](0029/implementation-plan.md) -### Draft implementation stack +### Review scope + +RFC acceptance would cover only the framework-neutral Control Model v1 and UI +artifact contracts defined here and in the two specifications. It would not +accept a Lobster product roadmap, a framework adapter, a generic dashboard +system, or writable configuration. + +The Board Model and Config Model evidence below is non-normative. It tests the +same owner-first extraction pattern against adjacent OpenClaw domains, but each +surface keeps its own contract, release gate, and implementation review. + +### Fork-only implementation evidence The proposed boundary has four fork-only implementation drafts: @@ -164,8 +175,12 @@ Two adjacent owner-first projections now have separate fork-only evidence: coordinated board stack. `v2026.8.1-beta.2` is the first tag containing the full implementation plus the later ownership and UI hardening; the extraction applies cleanly there with 55 focused tests and a Gateway Client build. - Lobster adoption therefore remains gated on a stable board-capable generation - or an explicit beta-admission decision. + [Lobster Board LB1](https://microsoft.ghe.com/giodl/lobster/pull/70) + independently consumes a private carry through a main-process safe projection + and renders one allowlisted native status widget plus inert unsupported + fallbacks. Its Electron proof uses a mocked beta-generation board protocol; + it is not release admission and does not make pinned LobsterClaw 2026.6.33 + board-capable. - [Config Model LC1 fork proof](https://microsoft.ghe.com/giodl/lobster/pull/69) provides `@openclaw/gateway-client/model/config` read-only authored configuration snapshots and read-scoped schema lookup. Lobster LC1 consumes @@ -174,6 +189,31 @@ Two adjacent owner-first projections now have separate fork-only evidence: real Electron Gateway fixture now proves the populated native page, authored value boundary, and restart guidance. +### Proposed future OpenClaw PR sequence + +No additional upstream PRs or branches are opened by this RFC update. The +remaining work is proposed here so maintainers can review the intended shape +before any implementation is prepared, and any drafts should remain fork-only +until RFC intake and owner approval. + +| Candidate | Scope | Gate | +| --- | --- | --- | +| OC5: shared conformance and package hardening | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | +| OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, and support ownership. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; independent-host evidence remains valid. | +| OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation and compatibility paths for the adopted slice. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies the exact old path. | + +Adjacent proposals remain separate from Control Model v1 acceptance: + +| Candidate | Scope | Gate | +| --- | --- | --- | +| BM2: Board Model release admission | Reconstruct the Board Model extraction and native-host conformance against an accepted board-capable OpenClaw release, then decide whether `model/board` is supportable. | Stable board-capable tag, or explicit beta admission with complete persistence, grants, tickets, sandbox, and compatibility review. | +| CM1: read-only Config Model | Extract framework-neutral authored config snapshots and read-scoped schema descriptors into an OpenClaw-owned optional model with Control UI reference adoption. | Config owner review, secret redaction, schema compatibility, and proof that read projection does not imply write authority. | +| CM2: governed configuration commands | Add provenance, owner, lock reason, candidate preview, validation findings, generation, commit, and activation status only through Managed Configuration contracts. | Separate owner approval and transactional write/activation design; not implied by this RFC or CM1. | + +Cross-client user-message identity, generic generated layouts, framework +adapters, and third-party native component SDKs remain separate future +proposals rather than implied follow-up PRs. + ### Module boundary Add the framework-neutral, browser-safe Control Model as optional exports from @@ -452,15 +492,16 @@ contract, and a named duplicate implementation or inference path it can delete. Existing OpenClaw dashboards and settings follow separate adoption paths. Lobster can host version-matched dashboard and settings routes immediately. The Board Model proof now demonstrates the optional projection of OpenClaw's -existing board model, but not a Lobster adopter on the pinned pre-board -generation. No stable OpenClaw tag currently contains the coordinated board -stack; `v2026.8.1-beta.2` is the first fully compatible tag and passes the -Board Model extraction proof. The Config Model and LC1 proof demonstrate a -native read-only settings surface over authored values and schema descriptors, +existing board model and a bounded Lobster native adopter, but only with a +mocked beta-generation protocol. No stable OpenClaw tag currently contains the +coordinated board stack; `v2026.8.1-beta.2` is the first fully compatible tag +and passes the extraction proof. The adopter does not change the pinned +2026.6.33 support boundary. The Config Model and LC1 proof demonstrate a native +read-only settings surface over authored values and schema descriptors, including a real Electron screenshot. Governed writes still require provenance, authority, validation, candidate diffs, generation, and transactional -activation from Managed Configuration. Neither model belongs in the -conversation snapshot. +activation from Managed Configuration. Neither adjacent model belongs in the +conversation snapshot or expands Control Model v1. ## Rationale @@ -519,18 +560,19 @@ independent UX. ## Unresolved questions -- When should the optional Gateway Client model subpaths publish after - fork-only two-consumer evidence is accepted? -- Does artifact streaming need complete revisions only, or does adoption - evidence justify a negotiated patch dialect? -- What finite size, depth, count, and retention defaults should v1 require? -- Which maintainers own model compatibility and security review if the subpaths - are published? -- What release and support gates should promote the proven optional - `@openclaw/gateway-client/model/board` subpath? -- Should governed settings writes extend the proven read-only - `@openclaw/gateway-client/model/config` surface or remain a separate Managed - Configuration client? +- Do maintainers accept the optional Gateway Client model subpaths as the + correct owner boundary, with OC5 conformance hardening before OC6 + publication? +- Which package, protocol, Control UI, security, and release maintainers own + compatibility decisions and support after publication? +- What finite size, depth, count, retention, and performance defaults should + v1 standardize rather than leave configurable? +- Should v1 remain on complete immutable artifact revisions, or is there + sufficient two-renderer evidence for a separately negotiated patch dialect? +- What observation window and rollback evidence must pass before OC7 can + delete incumbent Control UI paths? +- Should Board Model and Config Model proceed as the separate BM2/CM1 proposals + above, or remain fork-only evidence until a later RFC? - If cross-client user-message delivery becomes required, what identity contract aligns host `clientMessageId`, model idempotency, retry/reconnect, persisted history, and renderer deduplication? diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index f4f27a50..45e44ab9 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -28,7 +28,9 @@ proof, and deletion agree. | O1 Control UI adoption | OpenClaw PR 4 | Existing Control UI behavior unchanged on shared fixtures and E2E | Adopted UI-local capability/reducer code | | H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | -| R1 publication | OpenClaw PR 5/release | Two consumers, package acceptance, compatibility and support policy | Fork-only distribution | +| C1 shared conformance | OpenClaw PR 5 | Shared fixtures, finite defaults, browser/Node package acceptance, compatibility canaries, performance bounds, and security review | Publication uncertainty | +| R1 publication | OpenClaw PR 6/release | Accepted conformance, two consumers, compatibility window, migration policy, release and support ownership | Fork-only distribution | +| D1 incumbent cleanup | OpenClaw PR 7 | Observation window, rollback proof, and exact deletion ledger | Superseded Control UI reconciliation | ## Evidence to date @@ -42,14 +44,15 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC4 | Control UI adoption of canonical active-session and selected-chat state without visual or startup-budget regression. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | -| Board Model | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. A second host waits on a board-capable LobsterClaw generation. | +| Board Model + LB1 | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. Lobster LB1 independently renders one safe native status widget and inert unsupported fallbacks through a main-process projection. Its mocked beta protocol is evidence only; release admission remains open. | | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, package ownership, -compatibility/security gates, and a released dependency. Product shipment is -additionally blocked on Lobster CI, live hosted-Gateway proof, rollout and -rollback controls, telemetry, UX quality, and shareable evidence. +Publication is still blocked on upstream acceptance, PR 5 conformance +hardening, package ownership, compatibility/security gates, and a released +dependency through PR 6. Incumbent cleanup remains PR 7 after observation and +rollback proof. Product shipment is additionally blocked on Lobster CI, live +hosted-Gateway proof, rollout and rollback controls, telemetry, and UX quality. ## Shared fixture families diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index c8a6bf33..6ded3c37 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -152,27 +152,86 @@ than LM7. It must align Lobster `clientMessageId`, model idempotency, retry/reconnect, non-renderer callers, persisted history, canonical user identity, and renderer deduplication. -## OpenClaw PR 5: publication +The adjacent native adopter evidence is also complete: + +| Slice | Scope and result | Boundary proved | +| --- | --- | --- | +| Config LC1 | Consumes a private read-only Config Model through Electron-owned transport and renders authored values plus schema guidance in native React. | Read projection can remain OpenClaw-owned without giving React raw config or write authority. | +| Board LB1 | Consumes a private Board Model through main-process routing, renders one exact native status-summary widget, and keeps HTML/Canvas/MCP/unknown widgets inert. | OpenClaw board semantics can drive a product-owned Dashboard without importing Control UI or granting renderer authority. | + +Board LB1 uses a mocked beta-generation board protocol because pinned +LobsterClaw 2026.6.33 predates boards. It is conformance evidence, not release +admission. + +## OpenClaw PR 5: shared conformance and package hardening ### Preconditions -- Control UI and independent host are live on the same contract. -- Compatibility and package acceptance pass. -- Bounds and security review pass. -- At least one duplicate implementation is deleted. -- Named package, protocol, security, and release owners agree. +- RFC scope and ownership boundary are accepted for implementation. +- OC1-OC4 evidence is reviewed against current source. +- Control UI and independent-host fixtures agree on the bounded contract. + +### Scope + +- Promote the proven fixture families into shared conformance assets. +- Finalize finite defaults and explicit truncation/partial-state behavior. +- Add browser and Node import/package acceptance checks. +- Add compatibility canaries for the supported release, predecessor where + promised, and `main`. +- Measure projection, reconciliation, retained-memory, and resync bounds. +- Complete malformed-data, authorization, retired-epoch, and subscriber + isolation security coverage. +- Keep the subpaths private or fork-only until the release/support gate passes. + +### Deletion target + +None. This PR hardens the contract before publication. + +## OpenClaw PR 6: supported model subpaths + +### Preconditions + +- PR 5 conformance, compatibility, performance, package, and security gates + pass. +- Named package, protocol, Control UI, security, and release owners agree. +- The independent-host proof remains valid against the candidate release. ### Scope - Publish the optional `@openclaw/gateway-client/model` subpaths. -- Document supported versions and migration policy. -- Add framework-neutral quickstart and conformance fixtures. -- Keep optional framework adapters outside the core model unless separately - justified. +- Document supported versions, compatibility window, and migration policy. +- Add a framework-neutral quickstart and release notes. +- Define support ownership and deprecation policy. +- Keep framework adapters outside the core model unless separately justified. + +### Deletion target + +Fork-only source carries after adopters move to a released dependency. + +## OpenClaw PR 7: incumbent-path cleanup + +### Preconditions + +- PR 6 is released and adopted by Control UI. +- The model-backed path has an agreed observation window and rollback proof. +- The exact superseded implementation is named and no supported fallback + depends on it. + +### Scope + +- Remove only the superseded Control UI reconciliation and compatibility paths + for the adopted catalog/conversation slice. +- Retain operational, diagnostic, or unsupported-capability paths that the + Control Model does not own. +- Update ownership docs and deletion ledger. + +### Deletion target + +The incumbent UI-local state/reconciliation path identified by OC4 adoption. ## Productization after publication -1. Land the supported package surface and replace Lobster's temporary source +1. Land the supported package surface from PR 6 and replace Lobster's temporary source carry with a released OpenClaw dependency. 2. Resolve Lobster required checks and land the bounded stack behind a runtime flag with rollback. @@ -188,15 +247,17 @@ identity, and renderer deduplication. - **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. The first fork-only Board Model proof now extracts selected-session board reconciliation into `@openclaw/gateway-client/model/board` and keeps Control - UI as the reference adopter. A native Lobster adapter must use a board-capable - OpenClaw generation and must not recreate dashboards from generic - conversation artifacts. + UI as the reference adopter. Lobster Board LB1 proves the native adapter + boundary with a mocked beta protocol. A future BM2 proposal must reconstruct + the proof against an admitted board-capable release and must not recreate + dashboards from generic conversation artifacts. - **Settings:** host OpenClaw settings first, read-only when Lobster lacks secure write authority. The read-only Config Model and Lobster LC1 proof now render selected authored values with descriptors and reload impact through a - main-process adapter. Effective defaults, provenance, owner, writability and - lock reason, validation findings, candidate diff, generation, and - transactional apply/reload status remain Managed Configuration work. + main-process adapter. A future CM1 may upstream only that read projection. + Effective defaults, provenance, owner, writability and lock reason, + validation findings, candidate diff, generation, and transactional + apply/reload status remain the separate CM2/Managed Configuration work. - **Canvas and MCP Apps:** preserve them as explicit sandboxed fallbacks rather than converting their executable state into trusted native React. @@ -212,3 +273,10 @@ identity, and renderer deduplication. artifact evolution, and durable document semantics. Each deferred surface requires a separate owner-first slice and deletion case. + +## Fork-only proposal policy + +This plan names OC5-OC7, BM2, CM1, and CM2 for maintainer review. It does not +open those PRs, create upstream branches, or claim roadmap acceptance. Any +implementation drafts should remain in the author's forks until RFC intake and +the relevant OpenClaw owners approve the surface. From af5775608650a98725cf28c6cdf0bc8de44515bb Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 18:25:51 -0700 Subject: [PATCH 12/33] docs: tighten Control Model filing scope Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 24 ++++++++++++++-------- rfcs/0029/conformance-and-adoption-plan.md | 4 +++- rfcs/0029/control-model-v1-spec.md | 18 +++++++++++----- rfcs/0029/implementation-plan.md | 11 ++++++---- 4 files changed, 39 insertions(+), 18 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index c4ded26a..7b8ea87c 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -3,7 +3,7 @@ title: OpenClaw Control Model authors: - Gio Della-Libera created: 2026-08-11 -last_updated: 2026-08-15 +last_updated: 2026-08-16 status: draft issue: rfc_pr: https://github.com/giodl73-repo/rfcs/pull/8 @@ -199,7 +199,7 @@ until RFC intake and owner approval. | Candidate | Scope | Gate | | --- | --- | --- | | OC5: shared conformance and package hardening | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | -| OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, and support ownership. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; independent-host evidence remains valid. | +| OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, support ownership, and install/import proof from the packed release artifact rather than a workspace checkout. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; the packed artifact passes clean browser and Node consumer checks; independent-host evidence remains valid. | | OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation and compatibility paths for the adopted slice. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies the exact old path. | Adjacent proposals remain separate from Control Model v1 acceptance: @@ -207,8 +207,8 @@ Adjacent proposals remain separate from Control Model v1 acceptance: | Candidate | Scope | Gate | | --- | --- | --- | | BM2: Board Model release admission | Reconstruct the Board Model extraction and native-host conformance against an accepted board-capable OpenClaw release, then decide whether `model/board` is supportable. | Stable board-capable tag, or explicit beta admission with complete persistence, grants, tickets, sandbox, and compatibility review. | -| CM1: read-only Config Model | Extract framework-neutral authored config snapshots and read-scoped schema descriptors into an OpenClaw-owned optional model with Control UI reference adoption. | Config owner review, secret redaction, schema compatibility, and proof that read projection does not imply write authority. | -| CM2: governed configuration commands | Add provenance, owner, lock reason, candidate preview, validation findings, generation, commit, and activation status only through Managed Configuration contracts. | Separate owner approval and transactional write/activation design; not implied by this RFC or CM1. | +| CFG1: read-only Config Model | Extract framework-neutral authored config snapshots and read-scoped schema descriptors into an OpenClaw-owned optional model with Control UI reference adoption. | Config owner review, secret redaction, schema compatibility, and proof that read projection does not imply write authority. | +| CFG2: governed configuration commands | Add provenance, owner, lock reason, candidate preview, validation findings, generation, commit, and activation status only through Managed Configuration contracts. | Separate owner approval and transactional write/activation design; not implied by this RFC or CFG1. | Cross-client user-message identity, generic generated layouts, framework adapters, and third-party native component SDKs remain separate future @@ -236,6 +236,10 @@ export interface ControlGateway { The binding lets the model reuse OpenClaw's browser, Node, or hosted transport without owning credential persistence, product routing, or socket creation. +It is a construction-time capability owned by the host and model +implementation. It is not exposed through snapshots, conversations, artifacts, +renderer registrations, or framework adapters, so consumers cannot use it to +bypass typed model commands. The Control Model exposes immutable snapshots and typed commands: @@ -263,11 +267,14 @@ V1 contains: - canonical ordered messages; - active run, stream, tool invocation, approval, and question state needed by conversation presentation; -- typed chat/session commands supported by the selected Gateway; and +- typed conversation commands plus explicit catalog and history refresh; and - renderer-neutral UI artifacts associated with messages or tool invocations. V1 excludes broader Control UI capabilities until each has a bounded, framework-neutral contract and an independent consumer. +Session create, rename, archive, delete, and other administration commands are +not required by v1 conformance. They remain host-owned or future optional model +capabilities until they have the same independent-adopter and deletion proof. ### Snapshot and event semantics @@ -293,8 +300,9 @@ Control Model's stable UI contract. ### Command semantics Commands express typed user intent. Candidate v1 commands include session -refresh, select, create, rename, archive/delete where authorized, chat send, -abort, retry where supported, answer, approve, and deny. +catalog refresh, conversation history refresh, chat send, active-run abort, +retry where the Gateway exposes a safe contract, answer, approve, deny, and +exact deferred-view materialization. The model may expose command availability for presentation. The Gateway remains authoritative. A command must return a typed result or throw a typed error. It @@ -571,7 +579,7 @@ independent UX. sufficient two-renderer evidence for a separately negotiated patch dialect? - What observation window and rollback evidence must pass before OC7 can delete incumbent Control UI paths? -- Should Board Model and Config Model proceed as the separate BM2/CM1 proposals +- Should Board Model and Config Model proceed as the separate BM2/CFG1 proposals above, or remain fork-only evidence until a later RFC? - If cross-client user-message delivery becomes required, what identity contract aligns host `clientMessageId`, model idempotency, retry/reconnect, diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 45e44ab9..c6ae416c 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -29,7 +29,7 @@ proof, and deletion agree. | H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | | C1 shared conformance | OpenClaw PR 5 | Shared fixtures, finite defaults, browser/Node package acceptance, compatibility canaries, performance bounds, and security review | Publication uncertainty | -| R1 publication | OpenClaw PR 6/release | Accepted conformance, two consumers, compatibility window, migration policy, release and support ownership | Fork-only distribution | +| R1 publication | OpenClaw PR 6/release | Accepted conformance, two consumers, compatibility window, migration policy, release and support ownership, and clean install/import proof from the packed release artifact | Fork-only distribution | | D1 incumbent cleanup | OpenClaw PR 7 | Observation window, rollback proof, and exact deletion ledger | Superseded Control UI reconciliation | ## Evidence to date @@ -135,6 +135,8 @@ Before publication, test: - the declared predecessor release where compatibility is promised; - OpenClaw `main` as a drift canary; - browser and Node host bindings; and +- a packed release artifact installed into clean browser and Node consumers, + including every supported subpath and declaration entrypoint; and - every supported serialized fixture version. The Control Model contract version and Gateway wire protocol version are diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index 0c0a4427..e4363301 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -31,6 +31,10 @@ The model consumes one host-owned Gateway binding. The binding must provide: - the accepted hello/protocol metadata required for feature detection; and - typed request and connection errors. +The binding is a construction-only capability for the host and model +implementation. It must not be exposed through public snapshots, conversation +handles, artifacts, renderer registrations, or framework adapters. + The host owns: - socket creation and route selection; @@ -101,8 +105,8 @@ requires the required initial snapshots or an explicit partial state. ## Session catalog The catalog contains stable session keys and the Gateway-authoritative fields -needed to list, select, and mutate sessions. Unknown additive fields must not -break projection. +needed to list and identify sessions. Unknown additive fields must not break +projection. The model owns: @@ -115,8 +119,8 @@ The model owns: - bounded retry for retryable observer errors; and - typed loading, refreshing, stale, and error state. -Local optimistic mutation may be used only when reconciliation and rollback are -specified. A failed mutation must not leave success-shaped catalog state. +Any future optional catalog mutation must specify reconciliation and rollback. +A failed mutation must not leave success-shaped catalog state. ## Conversation model @@ -205,7 +209,6 @@ replace the server-provided allowed-action set. Candidate v1 commands are: - refresh session catalog; -- create/select/rename/archive/delete session where supported; - load/refresh conversation history; - send chat content and supported attachments; - abort the active run; @@ -214,6 +217,11 @@ Candidate v1 commands are: - materialize one exact deferred UI view for the current artifact revision; and - retry only where the Gateway exposes a safe retry contract. +Session creation, rename, archive, delete, and other administration operations +are not required by v1 conformance. A later optional capability must add its own +independent-adopter, authorization, reconciliation, rollback, and deletion +evidence. + Each command defines: - required current state; diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 6ded3c37..7e7d1a49 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -54,7 +54,7 @@ One duplicate session-catalog reducer in an adopter, after later adoption. - Add lazy conversation models. - Extract deterministic history/live merge. - Project messages, runs, tools, approvals, and questions. -- Add typed chat/session commands and command errors. +- Add typed conversation commands, catalog/history refresh, and command errors. - Add finite progress and inactive-conversation retention. ### Proof @@ -201,6 +201,9 @@ None. This PR hardens the contract before publication. - Publish the optional `@openclaw/gateway-client/model` subpaths. - Document supported versions, compatibility window, and migration policy. - Add a framework-neutral quickstart and release notes. +- Pack the release artifact and prove clean browser and Node consumers can + install it, resolve every supported subpath, and consume its declarations + without workspace-only files or dependencies. - Define support ownership and deprecation policy. - Keep framework adapters outside the core model unless separately justified. @@ -254,10 +257,10 @@ The incumbent UI-local state/reconciliation path identified by OC4 adoption. - **Settings:** host OpenClaw settings first, read-only when Lobster lacks secure write authority. The read-only Config Model and Lobster LC1 proof now render selected authored values with descriptors and reload impact through a - main-process adapter. A future CM1 may upstream only that read projection. + main-process adapter. A future CFG1 may upstream only that read projection. Effective defaults, provenance, owner, writability and lock reason, validation findings, candidate diff, generation, and transactional - apply/reload status remain the separate CM2/Managed Configuration work. + apply/reload status remain the separate CFG2/Managed Configuration work. - **Canvas and MCP Apps:** preserve them as explicit sandboxed fallbacks rather than converting their executable state into trusted native React. @@ -276,7 +279,7 @@ Each deferred surface requires a separate owner-first slice and deletion case. ## Fork-only proposal policy -This plan names OC5-OC7, BM2, CM1, and CM2 for maintainer review. It does not +This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. It does not open those PRs, create upstream branches, or claim roadmap acceptance. Any implementation drafts should remain in the author's forks until RFC intake and the relevant OpenClaw owners approve the surface. From ea3836e62ea8f9edc35b5d35299f79e07b7d6439 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 19:21:27 -0700 Subject: [PATCH 13/33] docs: record first OC5 hardening slice Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 9 +++++++-- rfcs/0029/conformance-and-adoption-plan.md | 13 ++++++++----- rfcs/0029/implementation-plan.md | 12 ++++++++++-- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 7b8ea87c..6329e377 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -145,9 +145,14 @@ The proposed boundary has four fork-only implementation drafts: 2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) 3. [OC3: renderer-neutral UI artifacts](https://github.com/giodl73-repo/openclaw/pull/232) 4. [OC4: Control UI reference adoption](https://github.com/giodl73-repo/openclaw/pull/238) +5. [OC5: first conformance and package-hardening slice](https://github.com/giodl73-repo/openclaw/pull/241) These drafts are evidence for review, not an upstream submission or accepted -roadmap. +roadmap. OC5 currently proves finite defaults, one reusable catalog +accepted/failure fixture pair, and clean packed-package Node, declaration, and +browser consumption. Compatibility canaries, measured performance/memory +thresholds, the broader fixture corpus, security review, and support-owner +assignment remain open. The independent Lobster evidence is also available as a temporary carry plus six bounded adopter slices: @@ -198,7 +203,7 @@ until RFC intake and owner approval. | Candidate | Scope | Gate | | --- | --- | --- | -| OC5: shared conformance and package hardening | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | +| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. The fork draft contains the first bounded slice only. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | | OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, support ownership, and install/import proof from the packed release artifact rather than a workspace checkout. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; the packed artifact passes clean browser and Node consumer checks; independent-host evidence remains valid. | | OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation and compatibility paths for the adopted slice. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies the exact old path. | diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index c6ae416c..a0bbcc17 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,17 +42,20 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Control UI adoption of canonical active-session and selected-chat state without visual or startup-budget regression. | +| OC5 first slice | Centralized finite defaults, reusable accepted/malformed catalog fixtures, packed protocol/client installation, every Gateway Client export imported from the tarball, declaration consumption, browser bundling, and repair of a package-only browser export failure. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | | Board Model + LB1 | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. Lobster LB1 independently renders one safe native status widget and inert unsupported fallbacks through a main-process projection. Its mocked beta protocol is evidence only; release admission remains open. | | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, PR 5 conformance -hardening, package ownership, compatibility/security gates, and a released -dependency through PR 6. Incumbent cleanup remains PR 7 after observation and -rollback proof. Product shipment is additionally blocked on Lobster CI, live -hosted-Gateway proof, rollout and rollback controls, telemetry, and UX quality. +Publication is still blocked on upstream acceptance, completion of the broader +PR 5 history/live/reconnect and authorization corpus, measured +performance/memory thresholds, compatibility canaries, security review, package +ownership, and a released dependency through PR 6. Incumbent cleanup remains +PR 7 after observation and rollback proof. Product shipment is additionally +blocked on Lobster CI, live hosted-Gateway proof, rollout and rollback controls, +telemetry, and UX quality. ## Shared fixture families diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 7e7d1a49..6da329ec 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -165,6 +165,13 @@ admission. ## OpenClaw PR 5: shared conformance and package hardening +Fork-only draft: +[giodl73-repo/openclaw#241](https://github.com/giodl73-repo/openclaw/pull/241). +Its first slice centralizes finite defaults, adds an authoritative/malformed +catalog fixture pair, proves clean packed-package Node/declaration/browser +consumption, and fixes a package-only browser export failure found by that +proof. It does not yet satisfy the full PR 5 gate. + ### Preconditions - RFC scope and ownership boundary are accepted for implementation. @@ -279,7 +286,8 @@ Each deferred surface requires a separate owner-first slice and deletion case. ## Fork-only proposal policy -This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. It does not -open those PRs, create upstream branches, or claim roadmap acceptance. Any +This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has +one fork-only draft for its first bounded hardening slice; no upstream branch or +PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further implementation drafts should remain in the author's forks until RFC intake and the relevant OpenClaw owners approve the surface. From 4f8292a3840f18c961805ab9c492d638a37c9328 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 20:20:06 -0700 Subject: [PATCH 14/33] docs(rfc): plan incremental Control UI adoption Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 36 ++++++++++++----- rfcs/0029/conformance-and-adoption-plan.md | 19 ++++----- rfcs/0029/implementation-plan.md | 47 ++++++++++++++++------ 3 files changed, 72 insertions(+), 30 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 6329e377..85958d1e 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -139,20 +139,21 @@ surface keeps its own contract, release gate, and implementation review. ### Fork-only implementation evidence -The proposed boundary has four fork-only implementation drafts: +The proposed boundary has five fork-only implementation drafts: 1. [OC1: Gateway Client model foundation](https://github.com/giodl73-repo/openclaw/pull/230) 2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) 3. [OC3: renderer-neutral UI artifacts](https://github.com/giodl73-repo/openclaw/pull/232) 4. [OC4: Control UI reference adoption](https://github.com/giodl73-repo/openclaw/pull/238) -5. [OC5: first conformance and package-hardening slice](https://github.com/giodl73-repo/openclaw/pull/241) +5. [OC5: conformance and package-hardening slices](https://github.com/giodl73-repo/openclaw/pull/241) These drafts are evidence for review, not an upstream submission or accepted -roadmap. OC5 currently proves finite defaults, one reusable catalog -accepted/failure fixture pair, and clean packed-package Node, declaration, and -browser consumption. Compatibility canaries, measured performance/memory -thresholds, the broader fixture corpus, security review, and support-owner -assignment remain open. +roadmap. OC5 currently proves finite defaults, reusable catalog +accepted/failure fixtures, representative history/live overlap, sequence-gap +recovery with retired-epoch rejection, approval authorization and terminal +state, and clean packed-package Node, declaration, and browser consumption. +Compatibility canaries, measured performance/memory thresholds, the remaining +fixture families, security review, and support-owner assignment remain open. The independent Lobster evidence is also available as a temporary carry plus six bounded adopter slices: @@ -201,11 +202,28 @@ remaining work is proposed here so maintainers can review the intended shape before any implementation is prepared, and any drafts should remain fork-only until RFC intake and owner approval. +Control UI adoption is also intentionally incremental. OC4 already proves the +first three slices; it does not yet make every Control UI command, interaction, +or artifact path model-backed. + +| Slice | Scope | Status and gate | +| --- | --- | --- | +| CU1: runtime binding | Create one lazy Control Model runtime over the existing Control UI Gateway client and forward connection/event invalidations without changing Lit presentation. | Complete in OC4. | +| CU2: catalog and selection | Drive the active session roster and selected-session lookup from immutable catalog snapshots while retaining unsupported archived/all roster behavior. | Complete in OC4. | +| CU3: selected conversation projection | Drive selected-chat history, live subscription, reconnect, and retryable fallback from the lazy conversation handle. | Complete in OC4; the representative overlap/gap/retired-epoch fixtures are now shared in OC5. | +| CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Next fork-only adopter slice after the relevant OC5 command fixtures are stable. | +| CU5: interactions and artifacts | Project selected-session approvals/questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus a Control UI-local exact renderer registry. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Requires authorization, stale-action, malformed-artifact, and fallback conformance plus focused browser proof. | +| CU6: observation and deletion | Run the model-backed path through an observation window, retain rollback, then delete only the superseded UI-local reducers, requests, and compatibility adapters named by the earlier slices. | Maps to OC7 and cannot precede OC6 publication, rollback proof, and an exact deletion ledger. | + +Board and configuration adoption are not hidden CU slices. They remain the +separate Board Model and Config Model proposals because their authority, +persistence, and release contracts differ from conversation state. + | Candidate | Scope | Gate | | --- | --- | --- | -| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. The fork draft contains the first bounded slice only. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | +| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. The fork draft now contains catalog/package proof plus representative history/live/reconnect and authorization fixtures; it is still not the complete gate. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | | OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, support ownership, and install/import proof from the packed release artifact rather than a workspace checkout. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; the packed artifact passes clean browser and Node consumer checks; independent-host evidence remains valid. | -| OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation and compatibility paths for the adopted slice. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies the exact old path. | +| OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation, standard command, interaction, artifact-adapter, and compatibility paths actually replaced by CU1-CU5. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies each exact old path. | Adjacent proposals remain separate from Control Model v1 acceptance: diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index a0bbcc17..0decba7d 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -25,7 +25,7 @@ proof, and deletion agree. | M1 Gateway Client model boundary | OpenClaw PR 1 | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | | M2 conversation projection | OpenClaw PR 2 | Shared history/live/reconnect/tool/approval corpus | Per-consumer chat reducers and event folding | | A1 UI artifacts | OpenClaw PR 3 | Native, structured-only, MCP fallback, malformed, stale, history cases | Tool-specific presentation interpretation | -| O1 Control UI adoption | OpenClaw PR 4 | Existing Control UI behavior unchanged on shared fixtures and E2E | Adopted UI-local capability/reducer code | +| O1 Control UI adoption | OC4 plus CU4-CU6 | Existing Control UI behavior unchanged as runtime, catalog, selected conversation, ordinary commands, interactions, and artifacts move through the model in bounded slices | Only the UI-local capability/reducer/request code replaced by each observed slice | | H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | | C1 shared conformance | OpenClaw PR 5 | Shared fixtures, finite defaults, browser/Node package acceptance, compatibility canaries, performance bounds, and security review | Publication uncertainty | @@ -41,21 +41,22 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC1 | Immutable bounded catalog snapshots, explicit host binding, epoch-safe refresh, typed errors, and subscriber isolation. | | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | -| OC4 | Control UI adoption of canonical active-session and selected-chat state without visual or startup-budget regression. | -| OC5 first slice | Centralized finite defaults, reusable accepted/malformed catalog fixtures, packed protocol/client installation, every Gateway Client export imported from the tarball, declaration consumption, browser bundling, and repair of a package-only browser export failure. | +| OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | +| OC5 current slices | Centralized finite defaults; reusable accepted/malformed catalog fixtures; representative history/live overlap, gap recovery, retired-epoch rejection, approval denial/allow forwarding, and terminal approval projection; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | | Board Model + LB1 | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. Lobster LB1 independently renders one safe native status widget and inert unsupported fallbacks through a main-process projection. Its mocked beta protocol is evidence only; release admission remains open. | | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, completion of the broader -PR 5 history/live/reconnect and authorization corpus, measured +Publication is still blocked on upstream acceptance, completion of the +remaining PR 5 run/tool/question/artifact/bounds fixture families, measured performance/memory thresholds, compatibility canaries, security review, package -ownership, and a released dependency through PR 6. Incumbent cleanup remains -PR 7 after observation and rollback proof. Product shipment is additionally -blocked on Lobster CI, live hosted-Gateway proof, rollout and rollback controls, -telemetry, and UX quality. +ownership, and a released dependency through PR 6. Control UI CU4 and CU5 +remain fork-only adopter work. Incumbent cleanup remains CU6/PR 7 after +observation and rollback proof. Product shipment is additionally blocked on +Lobster CI, live hosted-Gateway proof, rollout and rollback controls, telemetry, +and UX quality. ## Shared fixture families diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 6da329ec..8fd7e610 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -105,26 +105,46 @@ association logic. ## OpenClaw PR 4: Control UI reference adoption -### Scope +OC4 is the initial reference-adoption draft, not the entire Control UI +migration. It completes the runtime, catalog, and selected-conversation +projection slices while deliberately leaving ordinary commands, interactions, +artifacts, and operational callers for later bounded work. + +### Completed scope - Adapt the existing Control UI Gateway store to the model binding. -- Move the session catalog and one complete conversation route to Control Model - snapshots. +- Move the active session catalog and selected-chat history/subscription route + to Control Model snapshots. - Keep Lit components, routes, styling, and behavior unchanged. -- Render current Canvas/MCP fallbacks through a Control UI-local artifact - registry/adapter. +- Retain retryable Gateway fallback when the lazy model cannot load. ### Proof - Existing focused Control UI tests. - Shared model fixtures. - Real browser/Gateway chat flow. -- No regression in reconnect, approval, tool cards, MCP Apps, or history. +- No regression in catalog selection, reconnect, or history. - Bundle and startup impact measured. ### Deletion target -Superseded UI-local session/conversation capability and reconciliation code. +Superseded UI-local catalog and selected-history capability after publication, +observation, and rollback proof. + +### Remaining Control UI adoption slices + +| Slice | Scope | Explicit boundary | +| --- | --- | --- | +| CU1 runtime binding | Lazy Control Model runtime over the existing Gateway store. | Complete in OC4; no new process, route, or framework adapter. | +| CU2 catalog and selection | Active roster and selected-session lookup from catalog snapshots. | Complete in OC4; archived/all rosters remain raw until separately modeled. | +| CU3 selected conversation projection | History, live subscription, reconnect, and retryable fallback from the conversation handle. | Complete in OC4; OC5 now owns representative overlap/gap/retired-epoch fixtures. | +| CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. | Do not absorb steer/inject, realtime talk, background-task history, no-run abort-all, or other operational paths without separate ownership proof. | +| CU5 interactions and artifacts | Selected-session approvals/questions plus Canvas, MCP App, and structured fallback through snapshot projections and an exact Control UI-local registry. | Global/operator approval lanes remain outside the slice unless they prove semantic equivalence; artifact data never selects executable code. | +| CU6 observation and deletion | Roll out the model-backed route, retain rollback, and remove only named incumbent reducers/requests/adapters. | Post-OC6 and implemented as OC7 with an exact deletion ledger. | + +Board and settings are separate Board Model and Config Model adoption series, +not CU7/CU8. Their authority and persistence contracts are non-normative to +Control Model v1. ## Lobster/M evidence series @@ -170,7 +190,10 @@ Fork-only draft: Its first slice centralizes finite defaults, adds an authoritative/malformed catalog fixture pair, proves clean packed-package Node/declaration/browser consumption, and fixes a package-only browser export failure found by that -proof. It does not yet satisfy the full PR 5 gate. +proof. Its second slice promotes representative history/live overlap, +gap-triggered authoritative refresh, retired-epoch rejection, and approval +authorization/terminal-state behavior into the shared corpus. It does not yet +satisfy the full PR 5 gate. ### Preconditions @@ -222,22 +245,22 @@ Fork-only source carries after adopters move to a released dependency. ### Preconditions -- PR 6 is released and adopted by Control UI. +- PR 6 is released and CU1-CU5 are adopted by Control UI. - The model-backed path has an agreed observation window and rollback proof. - The exact superseded implementation is named and no supported fallback depends on it. ### Scope -- Remove only the superseded Control UI reconciliation and compatibility paths - for the adopted catalog/conversation slice. +- Remove only the superseded Control UI reconciliation, standard command, + interaction, artifact-adapter, and compatibility paths named by CU1-CU5. - Retain operational, diagnostic, or unsupported-capability paths that the Control Model does not own. - Update ownership docs and deletion ledger. ### Deletion target -The incumbent UI-local state/reconciliation path identified by OC4 adoption. +The exact incumbent UI-local paths identified by CU1-CU5 adoption. ## Productization after publication From 9caac239aacd88c73911df9fd8492b67e71dcfdf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 21:02:42 -0700 Subject: [PATCH 15/33] docs: record CU4 Control UI command adoption Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 5 +++-- rfcs/0029/conformance-and-adoption-plan.md | 5 +++-- rfcs/0029/implementation-plan.md | 22 +++++++++++++++++++--- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 85958d1e..881a8129 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -139,13 +139,14 @@ surface keeps its own contract, release gate, and implementation review. ### Fork-only implementation evidence -The proposed boundary has five fork-only implementation drafts: +The proposed boundary has six fork-only implementation drafts: 1. [OC1: Gateway Client model foundation](https://github.com/giodl73-repo/openclaw/pull/230) 2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) 3. [OC3: renderer-neutral UI artifacts](https://github.com/giodl73-repo/openclaw/pull/232) 4. [OC4: Control UI reference adoption](https://github.com/giodl73-repo/openclaw/pull/238) 5. [OC5: conformance and package-hardening slices](https://github.com/giodl73-repo/openclaw/pull/241) +6. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) These drafts are evidence for review, not an upstream submission or accepted roadmap. OC5 currently proves finite defaults, reusable catalog @@ -211,7 +212,7 @@ or artifact path model-backed. | CU1: runtime binding | Create one lazy Control Model runtime over the existing Control UI Gateway client and forward connection/event invalidations without changing Lit presentation. | Complete in OC4. | | CU2: catalog and selection | Drive the active session roster and selected-session lookup from immutable catalog snapshots while retaining unsupported archived/all roster behavior. | Complete in OC4. | | CU3: selected conversation projection | Drive selected-chat history, live subscription, reconnect, and retryable fallback from the lazy conversation handle. | Complete in OC4; the representative overlap/gap/retired-epoch fixtures are now shared in OC5. | -| CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Next fork-only adopter slice after the relevant OC5 command fixtures are stable. | +| CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. The adapter preserves session identity, attachment/reply/fencing inputs, reconnect-resume fallback, and structured command errors used by incumbent recovery. | | CU5: interactions and artifacts | Project selected-session approvals/questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus a Control UI-local exact renderer registry. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Requires authorization, stale-action, malformed-artifact, and fallback conformance plus focused browser proof. | | CU6: observation and deletion | Run the model-backed path through an observation window, retain rollback, then delete only the superseded UI-local reducers, requests, and compatibility adapters named by the earlier slices. | Maps to OC7 and cannot precede OC6 publication, rollback proof, and an exact deletion ledger. | diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 0decba7d..35dd1a27 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -43,6 +43,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | | OC5 current slices | Centralized finite defaults; reusable accepted/malformed catalog fixtures; representative history/live overlap, gap recovery, retired-epoch rejection, approval denial/allow forwarding, and terminal approval projection; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. | +| CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | | Board Model + LB1 | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. Lobster LB1 independently renders one safe native status widget and inert unsupported fallbacks through a main-process projection. Its mocked beta protocol is evidence only; release admission remains open. | @@ -52,8 +53,8 @@ The independent-adopter gate is therefore demonstrated, not merely planned. Publication is still blocked on upstream acceptance, completion of the remaining PR 5 run/tool/question/artifact/bounds fixture families, measured performance/memory thresholds, compatibility canaries, security review, package -ownership, and a released dependency through PR 6. Control UI CU4 and CU5 -remain fork-only adopter work. Incumbent cleanup remains CU6/PR 7 after +ownership, and a released dependency through PR 6. Control UI CU5 remains +fork-only adopter work. Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on Lobster CI, live hosted-Gateway proof, rollout and rollback controls, telemetry, and UX quality. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 8fd7e610..0999f453 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -107,8 +107,9 @@ association logic. OC4 is the initial reference-adoption draft, not the entire Control UI migration. It completes the runtime, catalog, and selected-conversation -projection slices while deliberately leaving ordinary commands, interactions, -artifacts, and operational callers for later bounded work. +projection slices. Fork-only CU4 now adds ordinary foreground commands while +deliberately leaving interactions, artifacts, and operational callers for +later bounded work. ### Completed scope @@ -138,7 +139,7 @@ observation, and rollback proof. | CU1 runtime binding | Lazy Control Model runtime over the existing Gateway store. | Complete in OC4; no new process, route, or framework adapter. | | CU2 catalog and selection | Active roster and selected-session lookup from catalog snapshots. | Complete in OC4; archived/all rosters remain raw until separately modeled. | | CU3 selected conversation projection | History, live subscription, reconnect, and retryable fallback from the conversation handle. | Complete in OC4; OC5 now owns representative overlap/gap/retired-epoch fixtures. | -| CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. | Do not absorb steer/inject, realtime talk, background-task history, no-run abort-all, or other operational paths without separate ownership proof. | +| CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. | Preserves session identity, attachment/reply/fencing inputs, reconnect-resume and steer fallback, structured active-leaf recovery errors, and raw no-run/session-wide abort ownership. Do not absorb realtime talk, background-task history, or other operational paths without separate ownership proof. | | CU5 interactions and artifacts | Selected-session approvals/questions plus Canvas, MCP App, and structured fallback through snapshot projections and an exact Control UI-local registry. | Global/operator approval lanes remain outside the slice unless they prove semantic equivalence; artifact data never selects executable code. | | CU6 observation and deletion | Roll out the model-backed route, retain rollback, and remove only named incumbent reducers/requests/adapters. | Post-OC6 and implemented as OC7 with an exact deletion ledger. | @@ -146,6 +147,21 @@ Board and settings are separate Board Model and Config Model adoption series, not CU7/CU8. Their authority and persistence contracts are non-normative to Control Model v1. +### CU4 fork-only result + +CU4 reuses the selected conversation handle already owned by OC4 rather than +creating a second runtime or command client. Ordinary selected sends pass +message content, attachments, idempotency, reply targets, expected leaf/run +fences, queue mode, and authoritative session identity through +`ControlModelConversation.send`. Connected exact-run stops use +`ControlModelConversation.abort`. + +Reconnect-resume sends, steer/inject, background or non-selected routes, +realtime talk, skill-workshop revisions, queued replay, and session-wide +`sessions.abort` remain on their incumbent paths. Model command errors retain +structured Gateway details so existing active-leaf recovery and retry behavior +remain visible rather than becoming generic failures. + ## Lobster/M evidence series The bounded independent-adopter series is complete in fork-local drafts. It From c0fd250ec0bfae7c8ea3217089445c754fb741a0 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 15 Aug 2026 22:45:27 -0700 Subject: [PATCH 16/33] docs(rfc-0029): record Control UI CU5 adoption Document the fork-only selected-question and safe Canvas/MCP artifact adoption slice, its ownership boundaries, and the remaining CU6 observation and deletion gate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 5 +++- rfcs/0029/implementation-plan.md | 30 +++++++++++++++++++--- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 35dd1a27..3105b503 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -44,6 +44,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | | OC5 current slices | Centralized finite defaults; reusable accepted/malformed catalog fixtures; representative history/live overlap, gap recovery, retired-epoch rejection, approval denial/allow forwarding, and terminal approval projection; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | +| CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | | LM4-LM6 | Ordinary send, active-run abort, and selected-session history cut over to the model, deleting equivalent raw Lobster paths. | | Board Model + LB1 | Existing Control UI board reconciliation extracted to `@openclaw/gateway-client/model/board`; 55 focused tests, Gateway Client build, and clean review. Lobster LB1 independently renders one safe native status widget and inert unsupported fallbacks through a main-process projection. Its mocked beta protocol is evidence only; release admission remains open. | @@ -54,7 +55,9 @@ Publication is still blocked on upstream acceptance, completion of the remaining PR 5 run/tool/question/artifact/bounds fixture families, measured performance/memory thresholds, compatibility canaries, security review, package ownership, and a released dependency through PR 6. Control UI CU5 remains -fork-only adopter work. Incumbent cleanup remains CU6/PR 7 after +fork-only adopter evidence in +[OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). +Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on Lobster CI, live hosted-Gateway proof, rollout and rollback controls, telemetry, and UX quality. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 0999f453..fcc948db 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -107,9 +107,10 @@ association logic. OC4 is the initial reference-adoption draft, not the entire Control UI migration. It completes the runtime, catalog, and selected-conversation -projection slices. Fork-only CU4 now adds ordinary foreground commands while -deliberately leaving interactions, artifacts, and operational callers for -later bounded work. +projection slices. Fork-only CU4 adds ordinary foreground commands, and +fork-only CU5 adds selected-session question commands plus safe Canvas/MCP +artifact projection. Operational callers and global/operator interaction queues +remain outside these bounded adoption slices. ### Completed scope @@ -140,7 +141,7 @@ observation, and rollback proof. | CU2 catalog and selection | Active roster and selected-session lookup from catalog snapshots. | Complete in OC4; archived/all rosters remain raw until separately modeled. | | CU3 selected conversation projection | History, live subscription, reconnect, and retryable fallback from the conversation handle. | Complete in OC4; OC5 now owns representative overlap/gap/retired-epoch fixtures. | | CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. | Preserves session identity, attachment/reply/fencing inputs, reconnect-resume and steer fallback, structured active-leaf recovery errors, and raw no-run/session-wide abort ownership. Do not absorb realtime talk, background-task history, or other operational paths without separate ownership proof. | -| CU5 interactions and artifacts | Selected-session approvals/questions plus Canvas, MCP App, and structured fallback through snapshot projections and an exact Control UI-local registry. | Global/operator approval lanes remain outside the slice unless they prove semantic equivalence; artifact data never selects executable code. | +| CU5 interactions and artifacts | Exact selected-session question answer/cancel commands plus Canvas, MCP App, and structured fallback through snapshot projections. Complete in fork-only [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | Preserves the incumbent prompt lifecycle, expiry deadline, local resolution publication, and raw fallback. Global/operator approval lanes remain outside the slice because their ownership and resolver semantics differ. Artifact data never selects executable code. | | CU6 observation and deletion | Roll out the model-backed route, retain rollback, and remove only named incumbent reducers/requests/adapters. | Post-OC6 and implemented as OC7 with an exact deletion ledger. | Board and settings are separate Board Model and Config Model adoption series, @@ -162,6 +163,27 @@ realtime talk, skill-workshop revisions, queued replay, and session-wide structured Gateway details so existing active-leaf recovery and retry behavior remain visible rather than becoming generic failures. +### CU5 fork-only result + +CU5 reuses the exact cached selected-conversation route and its authoritative +agent identity, including main aliases. Pending question answer/cancel commands +pass through the conversation model with the incumbent question deadline while +Control UI retains submitting/error state, response validation, local +resolution confirmation, shared-client publication, and raw compatibility +fallback. + +Validated ready artifact snapshots feed only the existing sandboxed Canvas and +MCP App presentation adapters. Model metadata cannot choose an import, module, +custom element, or executable template. Correlation prefers canonical message +and tool-call provenance; ordered tool-only matching is restricted to +source-less compatibility data, and occurrence/timestamp evidence prevents +reused tool IDs or persisted/live overlap from hiding distinct views. + +Global/operator approval queues remain raw because they are not selected- +conversation commands and use different resolver ownership. Unknown, +malformed, failed, source-less, and unsupported artifacts continue through the +incumbent compatibility behavior. + ## Lobster/M evidence series The bounded independent-adopter series is complete in fork-local drafts. It From 85c45012410bd618678e4271989c627ea2dc79fb Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 07:57:18 -0700 Subject: [PATCH 17/33] docs(rfc-0029): record complete fixture families Add the fork-only OC5 run, tool, question, artifact, and retained-bounds conformance continuation while keeping performance, compatibility, security, and publication as separate remaining gates. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 9 ++++----- rfcs/0029/implementation-plan.md | 17 +++++++++++------ 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 3105b503..a6e52ca2 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,7 +42,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable accepted/malformed catalog fixtures; representative history/live overlap, gap recovery, retired-epoch rejection, approval denial/allow forwarding, and terminal approval projection; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. The latest test-only slice is fork [OpenClaw PR #244](https://github.com/giodl73-repo/openclaw/pull/244). | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -51,10 +51,9 @@ Fork-only evidence now covers the full bounded V1 thesis: | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, completion of the -remaining PR 5 run/tool/question/artifact/bounds fixture families, measured -performance/memory thresholds, compatibility canaries, security review, package -ownership, and a released dependency through PR 6. Control UI CU5 remains +Publication is still blocked on upstream acceptance, measured +performance/memory thresholds, compatibility canaries, security review, +package ownership, and a released dependency through PR 6. Control UI CU5 remains fork-only adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index fcc948db..e387abf6 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -230,8 +230,13 @@ catalog fixture pair, proves clean packed-package Node/declaration/browser consumption, and fixes a package-only browser export failure found by that proof. Its second slice promotes representative history/live overlap, gap-triggered authoritative refresh, retired-epoch rejection, and approval -authorization/terminal-state behavior into the shared corpus. It does not yet -satisfy the full PR 5 gate. +authorization/terminal-state behavior into the shared corpus. A test-only +continuation in +[giodl73-repo/openclaw#244](https://github.com/giodl73-repo/openclaw/pull/244) +adds representative run, tool, question, artifact, and retained-bounds +families, including exact non-active abort targeting and selected-only deferred +materialization. OC5 still does not satisfy the performance, compatibility, +security-owner, or publication gates. ### Preconditions @@ -348,7 +353,7 @@ Each deferred surface requires a separate owner-first slice and deletion case. ## Fork-only proposal policy This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has -one fork-only draft for its first bounded hardening slice; no upstream branch or -PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further -implementation drafts should remain in the author's forks until RFC intake and -the relevant OpenClaw owners approve the surface. +fork-only hardening drafts for package/shared-fixture evidence; no upstream +branch or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. +Any further implementation drafts should remain in the author's forks until +RFC intake and the relevant OpenClaw owners approve the surface. From 701283206bb59f1c6b6070b137abe557e31d1679 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 09:05:26 -0700 Subject: [PATCH 18/33] docs(rfc-0029): record OC5 performance proof Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 22 +++++++++++++++++----- rfcs/0029/implementation-plan.md | 19 +++++++++++++------ 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index a6e52ca2..657c62f4 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,7 +42,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; and repair of a package-only browser export failure. The latest test-only slice is fork [OpenClaw PR #244](https://github.com/giodl73-repo/openclaw/pull/244). | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; and an asserted artifact-heavy projection benchmark with exact finite-snapshot checks. The latest test-only slice is fork [OpenClaw PR #245](https://github.com/giodl73-repo/openclaw/pull/245), stacked on fixture PR #244. Its Testbox proof projects 24,000 measured events at 2,211.45 ms p95 per 4,000 events, 52,272 bytes retained heap growth, and 8,482.51 bytes/batch retained slope. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -51,10 +51,11 @@ Fork-only evidence now covers the full bounded V1 thesis: | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, measured -performance/memory thresholds, compatibility canaries, security review, -package ownership, and a released dependency through PR 6. Control UI CU5 remains -fork-only adopter evidence in +Publication is still blocked on upstream acceptance, the remaining performance +scenarios, compatibility canaries, security review, package ownership, and a +released dependency through PR 6. The bounded steady-state projection and +retained-memory threshold slice is now measured in PR #245. Control UI CU5 +remains fork-only adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on @@ -167,6 +168,17 @@ No renderer callback runs in the Gateway receive loop. Slow subscribers must not block protocol event processing. Unbounded history, progress, artifact, or listener retention blocks release. +The first asserted performance slice is fork +[OpenClaw PR #245](https://github.com/giodl73-repo/openclaw/pull/245). It runs +six measured batches after warmup, with 1,000 artifact-heavy cycles and 4,000 +events per batch. The gate requires p95 projection latency at or below 4,000 ms, +retained heap growth at or below 2 MiB, retained heap slope at or below 256 KiB +per batch, and exact finite snapshot lengths with truncation evidence. +Blacksmith Testbox `tbx_01m05mrxhzajxpdqb6ggdzx4y1` passed at 2,211.45 ms p95, +52,272 bytes retained growth, and 8,482.51 bytes/batch retained slope. Initial +projection, selected-view materialization, inactive eviction, and +reconnect/resync measurements remain separate OC5 evidence slices. + ## Security gates The following are blocking: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index e387abf6..6238f88b 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -235,8 +235,14 @@ continuation in [giodl73-repo/openclaw#244](https://github.com/giodl73-repo/openclaw/pull/244) adds representative run, tool, question, artifact, and retained-bounds families, including exact non-active abort targeting and selected-only deferred -materialization. OC5 still does not satisfy the performance, compatibility, -security-owner, or publication gates. +materialization. A second test-only continuation in +[giodl73-repo/openclaw#245](https://github.com/giodl73-repo/openclaw/pull/245) +adds an asserted artifact-heavy projection benchmark with exact finite-snapshot +checks and Testbox-oriented thresholds for p95 latency, retained heap growth, +and retained heap slope. Its Blacksmith Testbox proof projects 24,000 measured +events at 2,211.45 ms p95 per 4,000 events, 52,272 bytes retained growth, and +8,482.51 bytes/batch retained slope. OC5 still does not satisfy the remaining +performance scenarios, compatibility, security-owner, or publication gates. ### Preconditions @@ -353,7 +359,8 @@ Each deferred surface requires a separate owner-first slice and deletion case. ## Fork-only proposal policy This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has -fork-only hardening drafts for package/shared-fixture evidence; no upstream -branch or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. -Any further implementation drafts should remain in the author's forks until -RFC intake and the relevant OpenClaw owners approve the surface. +fork-only hardening drafts for package/shared-fixture evidence and bounded +projection/retained-memory thresholds; no upstream branch or PR was opened. +OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further implementation +drafts should remain in the author's forks until RFC intake and the relevant +OpenClaw owners approve the surface. From 7ffba4e1b3310d3c37797cd9a2946e855c492d37 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 10:28:04 -0700 Subject: [PATCH 19/33] docs(rfc-0029): record compatibility canary Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 21 ++++++++++++++++----- rfcs/0029/implementation-plan.md | 20 ++++++++++++++------ 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 657c62f4..9327db3a 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,7 +42,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; and an asserted artifact-heavy projection benchmark with exact finite-snapshot checks. The latest test-only slice is fork [OpenClaw PR #245](https://github.com/giodl73-repo/openclaw/pull/245), stacked on fixture PR #244. Its Testbox proof projects 24,000 measured events at 2,211.45 ms p95 per 4,000 events, 52,272 bytes retained heap growth, and 8,482.51 bytes/batch retained slope. | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; an asserted artifact-heavy projection benchmark with exact finite-snapshot checks; and an asserted candidate/predecessor/main wire-compatibility matrix. The latest test-only slice is fork [OpenClaw PR #246](https://github.com/giodl73-repo/openclaw/pull/246), stacked on performance PR #245. It proves baseline Control Model methods, scopes, requests, and representative events against the candidate protocol, published predecessor `2026.7.2-beta.7`, and current main while explicitly treating run-fenced send as unavailable on the predecessor. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -52,10 +52,10 @@ Fork-only evidence now covers the full bounded V1 thesis: The independent-adopter gate is therefore demonstrated, not merely planned. Publication is still blocked on upstream acceptance, the remaining performance -scenarios, compatibility canaries, security review, package ownership, and a -released dependency through PR 6. The bounded steady-state projection and -retained-memory threshold slice is now measured in PR #245. Control UI CU5 -remains fork-only adopter evidence in +scenarios, security review, package ownership, and a released dependency +through PR 6. The bounded steady-state projection and retained-memory threshold +slice is measured in PR #245, and the wire-compatibility canary is measured in +PR #246. Control UI CU5 remains fork-only adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on @@ -152,6 +152,17 @@ distinct. A wire-compatible server may still require an additive model projection update. An incompatible model change requires migration guidance and a declared support-window decision. +The first asserted compatibility slice is fork +[OpenClaw PR #246](https://github.com/giodl73-repo/openclaw/pull/246). It checks +the candidate schema, published predecessor +`@openclaw/gateway-protocol@2026.7.2-beta.7`, and current `main` for the exact +methods, authorization scopes, request payloads, and representative events used +by the Control Model. Blacksmith Testbox `tbx_01m05spdcyy97ht168pfy3tqv1` +passed against `main@63401b730b55b40f691b004308cab45b66c8eb89`. The predecessor +accepts the baseline ordinary-send contract but rejects `expectedRunId`; the +canary records that capability boundary instead of promising an unsupported +fenced-send downgrade. + ## Performance and memory gates The package must measure: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 6238f88b..5d3d4ba7 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -241,8 +241,15 @@ adds an asserted artifact-heavy projection benchmark with exact finite-snapshot checks and Testbox-oriented thresholds for p95 latency, retained heap growth, and retained heap slope. Its Blacksmith Testbox proof projects 24,000 measured events at 2,211.45 ms p95 per 4,000 events, 52,272 bytes retained growth, and -8,482.51 bytes/batch retained slope. OC5 still does not satisfy the remaining -performance scenarios, compatibility, security-owner, or publication gates. +8,482.51 bytes/batch retained slope. A third test-only continuation in +[giodl73-repo/openclaw#246](https://github.com/giodl73-repo/openclaw/pull/246) +adds an asserted wire-compatibility matrix for the candidate protocol, +published predecessor `@openclaw/gateway-protocol@2026.7.2-beta.7`, and current +OpenClaw `main`. It preserves baseline catalog, subscription, history, ordinary +send, exact abort, approval, question, and representative event contracts while +recording run-fenced send as a candidate-era capability rather than claiming +unsupported predecessor behavior. OC5 still does not satisfy the remaining +performance scenarios, security-owner, or publication gates. ### Preconditions @@ -360,7 +367,8 @@ Each deferred surface requires a separate owner-first slice and deletion case. This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has fork-only hardening drafts for package/shared-fixture evidence and bounded -projection/retained-memory thresholds; no upstream branch or PR was opened. -OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further implementation -drafts should remain in the author's forks until RFC intake and the relevant -OpenClaw owners approve the surface. +projection/retained-memory thresholds plus candidate/predecessor/main wire +compatibility; no upstream branch or PR was opened. OC6, OC7, BM2, CFG1, and +CFG2 remain proposals only. Any further implementation drafts should remain in +the author's forks until RFC intake and the relevant OpenClaw owners approve +the surface. From e6abbaacf8322a16202073d65ffb94fdc305ab64 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 11:00:03 -0700 Subject: [PATCH 20/33] docs(rfc-0029): record lifecycle performance gate Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 26 ++++++++++++++++------ rfcs/0029/implementation-plan.md | 20 +++++++++++------ 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 9327db3a..85dd61bf 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,7 +42,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; an asserted artifact-heavy projection benchmark with exact finite-snapshot checks; and an asserted candidate/predecessor/main wire-compatibility matrix. The latest test-only slice is fork [OpenClaw PR #246](https://github.com/giodl73-repo/openclaw/pull/246), stacked on performance PR #245. It proves baseline Control Model methods, scopes, requests, and representative events against the candidate protocol, published predecessor `2026.7.2-beta.7`, and current main while explicitly treating run-fenced send as unavailable on the predecessor. | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; and asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds. The latest test-only slice is fork [OpenClaw PR #247](https://github.com/giodl73-repo/openclaw/pull/247), stacked on compatibility PR #246. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -51,11 +51,12 @@ Fork-only evidence now covers the full bounded V1 thesis: | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, the remaining performance -scenarios, security review, package ownership, and a released dependency -through PR 6. The bounded steady-state projection and retained-memory threshold -slice is measured in PR #245, and the wire-compatibility canary is measured in -PR #246. Control UI CU5 remains fork-only adopter evidence in +Publication is still blocked on upstream acceptance, security review, package +ownership, and a released dependency through PR 6. The bounded steady-state +projection and retained-memory threshold slice is measured in PR #245, the +wire-compatibility canary is measured in PR #246, and the lifecycle performance +scenarios are measured in PR #247. Control UI CU5 remains fork-only adopter +evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on @@ -188,7 +189,18 @@ per batch, and exact finite snapshot lengths with truncation evidence. Blacksmith Testbox `tbx_01m05mrxhzajxpdqb6ggdzx4y1` passed at 2,211.45 ms p95, 52,272 bytes retained growth, and 8,482.51 bytes/batch retained slope. Initial projection, selected-view materialization, inactive eviction, and -reconnect/resync measurements remain separate OC5 evidence slices. +reconnect/resync are asserted in fork +[OpenClaw PR #247](https://github.com/giodl73-repo/openclaw/pull/247). +Blacksmith Testbox `tbx_01m05veqewr76wd05191gt6sb8` passed with: + +- 14.32 ms initial projection p95 for 200 sessions, 200 messages, and 50 + artifacts, below a 100 ms ceiling; +- 0.58 ms selected deferred-view materialization p95 across 100 views, below a + 10 ms ceiling; +- 26.23 ms inactive eviction p95 per 1,000 handles, with exactly 50 retained + and 5,950 disposed, below a 250 ms ceiling; and +- 8.07 ms reconnect/resync p95 for authoritative 200-message history, below a + 100 ms ceiling. ## Security gates diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 5d3d4ba7..ad9a67b6 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -248,8 +248,14 @@ published predecessor `@openclaw/gateway-protocol@2026.7.2-beta.7`, and current OpenClaw `main`. It preserves baseline catalog, subscription, history, ordinary send, exact abort, approval, question, and representative event contracts while recording run-fenced send as a candidate-era capability rather than claiming -unsupported predecessor behavior. OC5 still does not satisfy the remaining -performance scenarios, security-owner, or publication gates. +unsupported predecessor behavior. A fourth test-only continuation in +[giodl73-repo/openclaw#247](https://github.com/giodl73-repo/openclaw/pull/247) +asserts initial catalog/conversation projection, selected deferred-view +materialization, bounded inactive-conversation eviction, and authoritative +reconnect/resync latency. Its Blacksmith Testbox proof passed at 14.32 ms, +0.58 ms, 26.23 ms, and 8.07 ms p95 respectively, with exact disposal and +resync invariants. OC5 still does not satisfy the security-owner or publication +gates. ### Preconditions @@ -367,8 +373,8 @@ Each deferred surface requires a separate owner-first slice and deletion case. This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has fork-only hardening drafts for package/shared-fixture evidence and bounded -projection/retained-memory thresholds plus candidate/predecessor/main wire -compatibility; no upstream branch or PR was opened. OC6, OC7, BM2, CFG1, and -CFG2 remain proposals only. Any further implementation drafts should remain in -the author's forks until RFC intake and the relevant OpenClaw owners approve -the surface. +projection/retained-memory thresholds, candidate/predecessor/main wire +compatibility, and lifecycle performance bounds; no upstream branch or PR was +opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further +implementation drafts should remain in the author's forks until RFC intake and +the relevant OpenClaw owners approve the surface. From b02efc3b23b930e827c31ebecc22471ab9c656ab Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 11:53:32 -0700 Subject: [PATCH 21/33] docs(rfc-0029): record security review gate Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029/conformance-and-adoption-plan.md | 26 ++++++++++++++++------ rfcs/0029/implementation-plan.md | 18 ++++++++++----- 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 85dd61bf..c93cbe36 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -42,7 +42,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; and asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds. The latest test-only slice is fork [OpenClaw PR #247](https://github.com/giodl73-repo/openclaw/pull/247), stacked on compatibility PR #246. | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds; and an independent security review with authority-epoch cache remediation. The latest slice is fork [OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248), stacked on lifecycle PR #247. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -51,12 +51,13 @@ Fork-only evidence now covers the full bounded V1 thesis: | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, security review, package -ownership, and a released dependency through PR 6. The bounded steady-state -projection and retained-memory threshold slice is measured in PR #245, the -wire-compatibility canary is measured in PR #246, and the lifecycle performance -scenarios are measured in PR #247. Control UI CU5 remains fork-only adopter -evidence in +Publication is still blocked on upstream acceptance, named package, protocol, +Control UI, security, and release ownership, and a released dependency through +PR 6. The bounded steady-state projection and retained-memory threshold slice +is measured in PR #245, the wire-compatibility canary is measured in PR #246, +and the lifecycle performance scenarios are measured in PR #247. The security +gate is reviewed and remediated in PR #248. Control UI CU5 remains fork-only +adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on @@ -221,6 +222,17 @@ The following are blocking: - discovery that reveals unauthorized extension/tool/view availability; and - verbatim extension access to unrelated client renderer inventory. +The first full-stack security review is recorded in fork +[OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248). Review +found one medium-severity authority-boundary flaw: selected deferred-view data +could remain materialized after disconnect or connection-epoch replacement. +The fix clears materialized payloads on both transitions, preserves only the +authorized descriptor from refreshed history, and requires a fresh +materialization request under the new epoch. Post-fix security review found no +remaining actionable vulnerabilities. Blacksmith Testbox +`tbx_01m05yh2krdyggq814g2jzyxf6` passed 55 Gateway Client security/conformance +tests and 46 Control UI Gateway-store tests. + ## Independent adopter proof The first independent adopter should: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index ad9a67b6..718f552e 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -254,8 +254,14 @@ asserts initial catalog/conversation projection, selected deferred-view materialization, bounded inactive-conversation eviction, and authoritative reconnect/resync latency. Its Blacksmith Testbox proof passed at 14.32 ms, 0.58 ms, 26.23 ms, and 8.07 ms p95 respectively, with exact disposal and -resync invariants. OC5 still does not satisfy the security-owner or publication -gates. +resync invariants. A fifth continuation in +[giodl73-repo/openclaw#248](https://github.com/giodl73-repo/openclaw/pull/248) +records the independent full-stack security review and fixes its one accepted +finding by retiring materialized deferred-view payloads on disconnect and +connection-epoch replacement. Refreshed history may restore the inert +descriptor, but the payload requires fresh server materialization under the +new authority context. Post-fix review found no actionable vulnerabilities. +OC5 still does not satisfy the named-owner or publication gates. ### Preconditions @@ -374,7 +380,7 @@ Each deferred surface requires a separate owner-first slice and deletion case. This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has fork-only hardening drafts for package/shared-fixture evidence and bounded projection/retained-memory thresholds, candidate/predecessor/main wire -compatibility, and lifecycle performance bounds; no upstream branch or PR was -opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further -implementation drafts should remain in the author's forks until RFC intake and -the relevant OpenClaw owners approve the surface. +compatibility, lifecycle performance bounds, and reviewed security hardening; +no upstream branch or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain +proposals only. Any further implementation drafts should remain in the author's +forks until RFC intake and the relevant OpenClaw owners approve the surface. From 574a8e027baa0e5788061f40c5ad3aab854e22ad Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 12:05:19 -0700 Subject: [PATCH 22/33] docs(rfc-0029): nominate publication owners Define explicit package, protocol, UI, security, release, and RFC ownership acceptance gates, and refresh the completed OC5 evidence. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 42 +++++---- rfcs/0029/conformance-and-adoption-plan.md | 14 +-- rfcs/0029/implementation-plan.md | 4 +- rfcs/0029/ownership-and-support-plan.md | 101 +++++++++++++++++++++ 4 files changed, 135 insertions(+), 26 deletions(-) create mode 100644 rfcs/0029/ownership-and-support-plan.md diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 881a8129..a522c1d5 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -125,6 +125,7 @@ documents: - [UI artifact v1 specification](0029/ui-artifact-v1-spec.md) - [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) - [Implementation and PR plan](0029/implementation-plan.md) +- [Ownership and support plan](0029/ownership-and-support-plan.md) ### Review scope @@ -139,22 +140,29 @@ surface keeps its own contract, release gate, and implementation review. ### Fork-only implementation evidence -The proposed boundary has six fork-only implementation drafts: +The proposed boundary has twelve fork-only implementation and reference-adopter +drafts: 1. [OC1: Gateway Client model foundation](https://github.com/giodl73-repo/openclaw/pull/230) 2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) 3. [OC3: renderer-neutral UI artifacts](https://github.com/giodl73-repo/openclaw/pull/232) 4. [OC4: Control UI reference adoption](https://github.com/giodl73-repo/openclaw/pull/238) 5. [OC5: conformance and package-hardening slices](https://github.com/giodl73-repo/openclaw/pull/241) -6. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) +6. [OC5: fixture-family continuation](https://github.com/giodl73-repo/openclaw/pull/244) +7. [OC5: steady-state performance and memory](https://github.com/giodl73-repo/openclaw/pull/245) +8. [OC5: wire-compatibility canary](https://github.com/giodl73-repo/openclaw/pull/246) +9. [OC5: lifecycle performance](https://github.com/giodl73-repo/openclaw/pull/247) +10. [OC5: security review and authority-epoch hardening](https://github.com/giodl73-repo/openclaw/pull/248) +11. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) +12. [CU5: Control UI interaction and artifact adoption](https://github.com/giodl73-repo/openclaw/pull/243) These drafts are evidence for review, not an upstream submission or accepted -roadmap. OC5 currently proves finite defaults, reusable catalog -accepted/failure fixtures, representative history/live overlap, sequence-gap -recovery with retired-epoch rejection, approval authorization and terminal -state, and clean packed-package Node, declaration, and browser consumption. -Compatibility canaries, measured performance/memory thresholds, the remaining -fixture families, security review, and support-owner assignment remain open. +roadmap. OC5 now proves finite defaults, the representative fixture families, +clean packed-package Node/declaration/browser consumption, measured +steady-state and lifecycle performance, candidate/predecessor/main wire +compatibility, and full-stack security review with the confirmed finding +remediated. Owner acceptance remains open under the +[ownership and support plan](0029/ownership-and-support-plan.md). The independent Lobster evidence is also available as a temporary carry plus six bounded adopter slices: @@ -213,7 +221,7 @@ or artifact path model-backed. | CU2: catalog and selection | Drive the active session roster and selected-session lookup from immutable catalog snapshots while retaining unsupported archived/all roster behavior. | Complete in OC4. | | CU3: selected conversation projection | Drive selected-chat history, live subscription, reconnect, and retryable fallback from the lazy conversation handle. | Complete in OC4; the representative overlap/gap/retired-epoch fixtures are now shared in OC5. | | CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. The adapter preserves session identity, attachment/reply/fencing inputs, reconnect-resume fallback, and structured command errors used by incumbent recovery. | -| CU5: interactions and artifacts | Project selected-session approvals/questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus a Control UI-local exact renderer registry. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Requires authorization, stale-action, malformed-artifact, and fallback conformance plus focused browser proof. | +| CU5: interactions and artifacts | Project selected-session questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus the existing Control UI adapters. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Complete in fork-only [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | | CU6: observation and deletion | Run the model-backed path through an observation window, retain rollback, then delete only the superseded UI-local reducers, requests, and compatibility adapters named by the earlier slices. | Maps to OC7 and cannot precede OC6 publication, rollback proof, and an exact deletion ledger. | Board and configuration adoption are not hidden CU slices. They remain the @@ -222,7 +230,7 @@ persistence, and release contracts differ from conversation state. | Candidate | Scope | Gate | | --- | --- | --- | -| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, add browser/Node import checks, performance bounds, package acceptance, and security-focused malformed-data coverage. The fork draft now contains catalog/package proof plus representative history/live/reconnect and authorization fixtures; it is still not the complete gate. | OC1-OC4 contract accepted; package, protocol, security, and Control UI owners agree on the support surface. | +| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, and prove package acceptance, steady-state and lifecycle performance, wire compatibility, and security through the stacked PRs #244-#248. | Fork-only technical evidence complete; OC6 remains blocked on explicit owner acceptance and a chosen support window. | | OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, support ownership, and install/import proof from the packed release artifact rather than a workspace checkout. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; the packed artifact passes clean browser and Node consumer checks; independent-host evidence remains valid. | | OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation, standard command, interaction, artifact-adapter, and compatibility paths actually replaced by CU1-CU5. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies each exact old path. | @@ -593,14 +601,12 @@ independent UX. ## Unresolved questions - Do maintainers accept the optional Gateway Client model subpaths as the - correct owner boundary, with OC5 conformance hardening before OC6 - publication? -- Which package, protocol, Control UI, security, and release maintainers own - compatibility decisions and support after publication? -- What finite size, depth, count, retention, and performance defaults should - v1 standardize rather than leave configurable? -- Should v1 remain on complete immutable artifact revisions, or is there - sufficient two-renderer evidence for a separately negotiated patch dialect? + correct owner boundary for OC6 publication? +- Do the nominated package, protocol, Control UI, security, release, and RFC + owners accept the responsibilities, deputies, and escalation paths in the + [ownership and support plan](0029/ownership-and-support-plan.md)? +- Which release vehicle and version window should carry the first supported + model subpaths? - What observation window and rollback evidence must pass before OC7 can delete incumbent Control UI paths? - Should Board Model and Config Model proceed as the separate BM2/CFG1 proposals diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index c93cbe36..861fa09a 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -51,13 +51,13 @@ Fork-only evidence now covers the full bounded V1 thesis: | Config Model + LC1 | Read-only authored config snapshots and schema lookup consumed by a native Lobster settings category through Electron-owned transport; principal-scoped cache, structured failure states, focused tests, and clean review. | The independent-adopter gate is therefore demonstrated, not merely planned. -Publication is still blocked on upstream acceptance, named package, protocol, -Control UI, security, and release ownership, and a released dependency through -PR 6. The bounded steady-state projection and retained-memory threshold slice -is measured in PR #245, the wire-compatibility canary is measured in PR #246, -and the lifecycle performance scenarios are measured in PR #247. The security -gate is reviewed and remediated in PR #248. Control UI CU5 remains fork-only -adopter evidence in +Publication is still blocked on upstream acceptance, explicit acceptance of the +[ownership and support plan](ownership-and-support-plan.md), and a released +dependency through PR 6. The bounded steady-state projection and +retained-memory threshold slice is measured in PR #245, the wire-compatibility +canary is measured in PR #246, and the lifecycle performance scenarios are +measured in PR #247. The security gate is reviewed and remediated in PR #248. +Control UI CU5 remains fork-only adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 718f552e..8d15b480 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -291,7 +291,9 @@ None. This PR hardens the contract before publication. - PR 5 conformance, compatibility, performance, package, and security gates pass. -- Named package, protocol, Control UI, security, and release owners agree. +- Named package, protocol, Control UI, security, and release owners accept the + obligations in the + [ownership and support plan](ownership-and-support-plan.md). - The independent-host proof remains valid against the candidate release. ### Scope diff --git a/rfcs/0029/ownership-and-support-plan.md b/rfcs/0029/ownership-and-support-plan.md new file mode 100644 index 00000000..0b102c71 --- /dev/null +++ b/rfcs/0029/ownership-and-support-plan.md @@ -0,0 +1,101 @@ +# Control Model ownership and support plan + +This plan names the existing OpenClaw teams and proposed directly responsible +individuals for the Control Model publication surface. It is a nomination +packet, not evidence that any person or team has accepted ownership. + +OC6 cannot begin until every accountable owner records acceptance on the RFC or +publication PR. One person may cover multiple roles, but each role keeps a +separate acceptance and escalation obligation. + +## Owner nominations + +| Surface | Accountable owner | DRI nominee | Deputy nominee | Evidence | Status | +| --- | --- | --- | --- | --- | --- | +| Gateway Client package and model API | `@openclaw/maintainer` | `@steipete` | `@vincentkoc` | Maintainer-team authority; highest recent Gateway Client contribution and review activity. | Acceptance pending | +| Gateway protocol compatibility | `@openclaw/maintainer` | `@steipete` | `@vincentkoc` | Maintainer-team authority; highest recent protocol contribution and both are RFC approvers. | Acceptance pending | +| Control UI reference adopter | `@openclaw/maintainer` | `@steipete` | `@vincentkoc` | Maintainer-team authority and sustained Control UI ownership. `@shakkernerd` is the proposed implementation reviewer for UI-specific behavior. | Acceptance pending | +| Security review and incident escalation | `@openclaw/openclaw-secops` | `@steipete` | `@vincentkoc` | Existing CODEOWNERS security team and current secops membership. | Acceptance pending | +| npm release and rollback | `@openclaw/openclaw-release-managers` | `@steipete` | `@vincentkoc` | Existing CODEOWNERS release boundary plus maintainer and release-history evidence. The release team must confirm or replace the individual nominees. | Acceptance pending | +| RFC contract approval | `@openclaw/openclaw-rfc-approvers` | `@steipete` | `@vincentkoc` | Current RFC approver team membership. | Acceptance pending | + +The team names above are existing GitHub teams. The individual nominations are +based on current team membership, repository contribution history, and the +existing CODEOWNERS boundaries as observed on 2026-08-16. They must be replaced +if the relevant teams choose different DRIs. + +## Required acceptance + +Each accountable owner must comment on the RFC or OC6 publication PR with: + +1. the surface accepted; +2. the named DRI and deputy; +3. the supported OpenClaw versions and compatibility window; +4. the required release, security, and rollback checks; +5. the triage expectation and response path for regressions or security + reports; +6. the conditions for deprecation or ownership transfer; and +7. a link to the accepting comment or approval. + +Silence, code review, team membership, or approval of a lower-stack evidence PR +does not count as support ownership. + +## Role obligations + +### Gateway Client package + +- Own the exported model subpaths, declarations, browser/Node compatibility, + finite defaults, and migration policy. +- Review breaking or behavior-changing projection updates. +- Keep package acceptance and conformance fixtures release-blocking. + +### Gateway protocol + +- Own the wire methods, scopes, request/event schemas, and supported predecessor + boundary used by the model. +- Classify additive model projection changes separately from incompatible wire + changes. +- Approve changes to command authorization or artifact materialization RPCs. + +### Control UI + +- Keep Control UI as the executable reference adopter for the supported slice. +- Confirm behavior parity, rollback, and the exact incumbent code eligible for + deletion. +- Keep product presentation, routing, and renderer registration outside the + model. + +### Security + +- Review trust-boundary changes, artifact normalization, selected-view + materialization, action authorization, epoch retirement, payload bounds, and + logging/error exposure. +- Route security reports through the existing OpenClaw security process. +- Block publication when a finding can cross session, agent, connection, or + authorization boundaries. + +### Release + +- Own packed-artifact verification, npm publication, release notes, rollback, + and support-window recording. +- Require clean browser and Node consumers to install every supported subpath + from the exact release artifact. +- Confirm the predecessor/main compatibility canaries before publication. +- Prevent a tag or release note from claiming support when publication or + install proof is partial, and record the deprecation or rollback action if a + bad artifact cannot be withdrawn. + +## Ownership changes + +If a DRI or deputy cannot continue, the accountable team must name a +replacement before the next behavior-changing release. Until then, release of +the affected surface remains blocked; maintainership must not silently fall to +the RFC author, an adopter, or an unacknowledged reviewer. + +## Publication decision + +OC5 technical evidence is complete enough to request owner acceptance: +conformance, package acceptance, performance, compatibility, lifecycle, and +security gates all have fork-only proof. OC6 remains blocked until the +acceptance records above are explicit and the owners choose the supported +version window, release vehicle, observation period, and rollback authority. From ec85014093e5d4b640c668de7c22dc4b4bdfaa33 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 16 Aug 2026 18:27:20 -0700 Subject: [PATCH 23/33] docs: record control model review closeout Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5715557-1677-47e0-9651-88e96e996584 --- rfcs/0029-openclaw-control-model.md | 14 ++++- rfcs/0029/conformance-and-adoption-plan.md | 11 ++++ rfcs/0029/implementation-plan.md | 16 ++++-- rfcs/0029/owner-acceptance-record.md | 60 ++++++++++++++++++++++ rfcs/0029/ownership-and-support-plan.md | 13 +++-- 5 files changed, 105 insertions(+), 9 deletions(-) create mode 100644 rfcs/0029/owner-acceptance-record.md diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index a522c1d5..1bea6bce 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -126,6 +126,7 @@ documents: - [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) - [Implementation and PR plan](0029/implementation-plan.md) - [Ownership and support plan](0029/ownership-and-support-plan.md) +- [Owner acceptance record](0029/owner-acceptance-record.md) ### Review scope @@ -161,7 +162,14 @@ roadmap. OC5 now proves finite defaults, the representative fixture families, clean packed-package Node/declaration/browser consumption, measured steady-state and lifecycle performance, candidate/predecessor/main wire compatibility, and full-stack security review with the confirmed finding -remediated. Owner acceptance remains open under the +remediated. A final whole-series review then covered OC1-OC5 and CU4-CU5 with +independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview passes, +followed by a clean Codex branch review. Accepted lifecycle, observer +ownership, canonical-session alias, metadata-bound, history, roster, routing, +and question-state findings were fixed at core head `a158436f085` in PR #248 +and Control UI head `0a8ad4188a6` in PR #243. Final focused proof passed 59 +Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, +and packed-package acceptance. Owner acceptance remains open under the [ownership and support plan](0029/ownership-and-support-plan.md). The independent Lobster evidence is also available as a temporary carry plus @@ -503,7 +511,9 @@ The model subpaths begin as fork-only exports. Publication requires: - adoption by one independent host; - exact shared conformance fixtures; - package-acceptance and browser-safe module-graph checks; -- a declared support and compatibility policy; and +- a declared support and compatibility policy; +- explicit owner acceptance recorded with the + [owner acceptance record](0029/owner-acceptance-record.md); and - evidence that one duplicate consumer implementation can be deleted. Subscriber callbacks run outside the Gateway receive stack. Model ingestion, diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 861fa09a..7981c8fc 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -43,6 +43,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | | OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds; and an independent security review with authority-epoch cache remediation. The latest slice is fork [OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248), stacked on lifecycle PR #247. | +| Whole-series review | Independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview reviews covered OC1-OC5 and CU4-CU5, followed by a clean Codex branch review. Accepted findings were fixed at core head `a158436f085` in PR #248 and Control UI head `0a8ad4188a6` in PR #243. Final focused proof passed 59 Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, and packed-package acceptance. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | | LM1-LM3 | Existing `SessionView` adaptation, exact native table rendering, visible fallback, and a host-owned action routed through the model. | @@ -59,6 +60,9 @@ canary is measured in PR #246, and the lifecycle performance scenarios are measured in PR #247. The security gate is reviewed and remediated in PR #248. Control UI CU5 remains fork-only adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). +The whole-series review closes the technical review gate but does not satisfy +the explicit acceptance records required by the +[ownership and support plan](ownership-and-support-plan.md). Incumbent cleanup remains CU6/PR 7 after observation and rollback proof. Product shipment is additionally blocked on Lobster CI, live hosted-Gateway proof, rollout and rollback controls, telemetry, @@ -233,6 +237,13 @@ remaining actionable vulnerabilities. Blacksmith Testbox `tbx_01m05yh2krdyggq814g2jzyxf6` passed 55 Gateway Client security/conformance tests and 46 Control UI Gateway-store tests. +The subsequent whole-series review exercised the complete OC1-OC5 and CU4-CU5 +stack across lifecycle/concurrency, security/compatibility/package, and Control +UI ownership/routing/artifact lenses. Accepted findings were fixed on the +owning branches. The final Codex branch review against +`42a4d0a9b8b3da55123217b8aa1ac495238d4ffd` reported no accepted or actionable +findings. + ## Independent adopter proof The first independent adopter should: diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 8d15b480..0758c7f4 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -261,7 +261,14 @@ finding by retiring materialized deferred-view payloads on disconnect and connection-epoch replacement. Refreshed history may restore the inert descriptor, but the payload requires fresh server materialization under the new authority context. Post-fix review found no actionable vulnerabilities. -OC5 still does not satisfy the named-owner or publication gates. + +A final whole-series review covered OC1-OC5 and CU4-CU5 with independent +GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview passes, followed by a +clean Codex branch review. Accepted findings were fixed at core head +`a158436f085` in PR #248 and Control UI head `0a8ad4188a6` in PR #243. Focused +proof passed 59 Gateway lifecycle/model tests, 61 integrated Control UI tests, +6 prompt tests, and packed-package acceptance. OC5 still does not satisfy the +named-owner or publication gates. ### Preconditions @@ -383,6 +390,7 @@ This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has fork-only hardening drafts for package/shared-fixture evidence and bounded projection/retained-memory thresholds, candidate/predecessor/main wire compatibility, lifecycle performance bounds, and reviewed security hardening; -no upstream branch or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain -proposals only. Any further implementation drafts should remain in the author's -forks until RFC intake and the relevant OpenClaw owners approve the surface. +the complete OC1-OC5 and CU4-CU5 stack is now review-clean. No upstream branch +or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any +further implementation drafts should remain in the author's forks until RFC +intake and the relevant OpenClaw owners approve the surface. diff --git a/rfcs/0029/owner-acceptance-record.md b/rfcs/0029/owner-acceptance-record.md new file mode 100644 index 00000000..6493c00e --- /dev/null +++ b/rfcs/0029/owner-acceptance-record.md @@ -0,0 +1,60 @@ +# Control Model owner acceptance record + +Use this record to accept, replace, or decline an ownership nomination for +RFC 0029. It does not assign ownership by default. Silence, team membership, +code review, or approval of an evidence PR does not count as acceptance. + +OC6 remains blocked until every surface has an explicit accepted owner and the +shared release decisions below are recorded. + +## Shared publication decisions + +| Decision | Required record | +| --- | --- | +| Release vehicle | Package, release train, and first supported version | +| Compatibility window | Supported OpenClaw versions and promised predecessor behavior | +| Required gates | Conformance, package, security, performance, and compatibility checks that block release | +| Regression response | Triage owner, response path, and escalation expectation | +| Security response | Private reporting and incident escalation path | +| Rollback authority | Who can halt, deprecate, or roll back a partial or bad publication | +| Observation window | Minimum evidence required before OC7/CU6 deletes incumbent paths | + +## Surface decisions + +Record one decision for each surface: + +| Surface | Accountable team | Decision | DRI | Deputy | Acceptance link | +| --- | --- | --- | --- | --- | --- | +| Gateway Client package and model API | `@openclaw/maintainer` | Pending | Pending | Pending | Pending | +| Gateway protocol compatibility | `@openclaw/maintainer` | Pending | Pending | Pending | Pending | +| Control UI reference adopter | `@openclaw/maintainer` | Pending | Pending | Pending | Pending | +| Security review and incident escalation | `@openclaw/openclaw-secops` | Pending | Pending | Pending | Pending | +| npm release and rollback | `@openclaw/openclaw-release-managers` | Pending | Pending | Pending | Pending | +| RFC contract approval | `@openclaw/openclaw-rfc-approvers` | Pending | Pending | Pending | Pending | + +Valid decisions are: + +- **Accept:** confirm the accountable team, DRI, deputy, and obligations. +- **Replace:** name the replacement accountable team, DRI, or deputy. +- **Decline:** state why the surface should not be published or who must decide. + +## Comment template + +Copy this block into the RFC review: + +```text +Surface: +Decision: Accept | Replace | Decline +Accountable team: +DRI: +Deputy: +Supported versions and compatibility window: +Required release and security gates: +Regression and security response path: +Rollback or deprecation authority: +Ownership-transfer conditions: +Acceptance applies to OC6 publication: Yes | No +``` + +An acceptance is complete only when every field is explicit or links to an +existing owner-controlled policy that supplies the answer. diff --git a/rfcs/0029/ownership-and-support-plan.md b/rfcs/0029/ownership-and-support-plan.md index 0b102c71..617aea4c 100644 --- a/rfcs/0029/ownership-and-support-plan.md +++ b/rfcs/0029/ownership-and-support-plan.md @@ -40,6 +40,10 @@ Each accountable owner must comment on the RFC or OC6 publication PR with: Silence, code review, team membership, or approval of a lower-stack evidence PR does not count as support ownership. +Use the [owner acceptance record](owner-acceptance-record.md) to make each +decision explicit and comparable. The record is a template, not an assignment +or default acceptance. + ## Role obligations ### Gateway Client package @@ -96,6 +100,9 @@ the RFC author, an adopter, or an unacknowledged reviewer. OC5 technical evidence is complete enough to request owner acceptance: conformance, package acceptance, performance, compatibility, lifecycle, and -security gates all have fork-only proof. OC6 remains blocked until the -acceptance records above are explicit and the owners choose the supported -version window, release vehicle, observation period, and rollback authority. +security gates all have fork-only proof. The complete OC1-OC5 and CU4-CU5 stack +also passed independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview +reviews plus a clean Codex branch review after accepted findings were fixed. +OC6 remains blocked until the acceptance records above are explicit and the +owners choose the supported version window, release vehicle, observation +period, and rollback authority. From 46c837d3394f0bda5bf9613e422b0624a656982d Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 12:40:20 -0700 Subject: [PATCH 24/33] RFC(0029): add handshake & capability-advertisement section; server filtering guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- rfcs/0029/control-model-v1-spec.md | 40 ++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index e4363301..f2d922f2 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -46,6 +46,46 @@ The host owns: The model must not start a network connection at import or construction time. It must not persist credentials. +## Handshake & capability advertisement + +Recommendation: the client advertises a bounded capability object during the +initial session handshake or subscription request so the server MAY filter or +rank offered artifact views and avoid sending unsupported large artifacts. +Advertisement is advisory only; it does not grant trust or authorization. + +Suggested capability object (client → server): + +``` +{ + "clientId": "product/instance-version", + "capabilities": { + "supports_html": true, + "supports_a2ui": false, + "supports_native_table": true, + "supports_streaming": true, + "supports_actions": true, + "max_artifact_size_bytes": 65536 + } +} +``` + +Server guidance: + +1. If an offered view's renderer matches a supported capability, favor + sending the full view (streaming when streamable && supports_streaming). +2. If the renderer is unsupported but a structured/text fallback exists, + send the fallback instead. +3. If artifact size exceeds `max_artifact_size_bytes` and the client + supports streaming, deliver as fragments (fragment/CID) with finalization + marker; otherwise send a summarized structured fallback. +4. Never expose private or scrubbed fields to clients lacking required + authorization regardless of advertised capabilities. +5. Treat capability advertisement as potentially stale or incomplete; the + client may still decline or ignore offers at render time. + +Note: this section proposes a concrete handshake schema and server filtering +rules. The full RFC update will include example exchanges, security privacy +considerations, and an appendix mapping uiDetails fields to capability flags. ## Root lifecycle Construction is inert except for validating options. `start()` may subscribe to From bd7da59dc978d448cd9c8d7f0a5868600d2e366a Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 13:10:09 -0700 Subject: [PATCH 25/33] RFC(0029): appendix mapping a2ui -> uiDetails; implementation guidance and streaming notes\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- rfcs/0029/ui-artifact-v1-spec.md | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 0a51abe9..7b646f71 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -353,6 +353,53 @@ The following fail artifact rendering without failing the surrounding message: Failures are observable and safe to log after redaction. They must not contain raw credentials, capability URLs, hidden model context, or unbounded tool data. +### Appendix: mapping a2ui → uiDetails + +This appendix shows a pragmatic mapping from common a2ui payload fields into the +Control Model's uiDetails/view offer shape. Use this as an implementation guide +when adapting an a2ui-producing tool or a2ui-capable Canvas to the Control Model. + +- a2ui.root -> UiArtifact.structuredContent or UiArtifactViewOffer.data + - When a2ui produces a single root HTML/DOM fragment, place a sanitized + structured representation under `structuredContent` and supply a `view` that + declares `templateUri: "ui://a2ui/"`. +- a2ui.components[] -> view.data component array + - Map named a2ui components to an array in `view.data.components` with the + minimal typed props; include `dataVersion` for component schema validation. +- a2ui.streamable -> view.streamable or UiArtifactViewOffer.meta.streamable + - If the a2ui renderer supports progressive hydration, set `streamable:true` + and provide a fragment/CID plan in `meta.streaming` describing chunk order + and finalization marker. +- a2ui.actions -> UiArtifactViewOffer.actions + - Convert a2ui-defined interactive handlers to typed action descriptors: + `{id,label,kind,schema,authRequired}`. Do not embed executable callbacks. +- a2ui.templateUri -> UiArtifactViewOffer.templateUri + - Normalize a2ui template references to `ui://a2ui/@` and + require exact match in host native registry for native rendering. +- a2ui.deferred -> UiArtifactViewOffer.availability = "deferred" + - When the a2ui payload requires server-side materialization, expose it as + `deferred` and require `materializeView` to fetch validated payload. +- a2ui.sizeHints -> UiArtifactViewOffer.preferredLayout / uiDetails.minWidth + - Map size and layout hints into `preferredLayout`, `minWidth`, `minHeight`. +- a2ui.privacyFlags -> UiArtifact.privacy + - Translate visibility/scrub flags into `privacy` with `visibility` and + `scrubbed` fields; servers must honor these when filtering offers. + +Security and runtime notes + +- Never copy executable code: a2ui payloads must not carry active JS callbacks + or module URIs. Use action descriptors that map to server-side commands. +- Require schema validation for any `view.data` consumed by a native renderer. +- Prefer deferred materialization for large or sensitive views so Gateway + re-enters auth and policy checks at materialization time. + +Examples and next steps + +- Append a short example mapping (a2ui JSON -> UiArtifact view) to this + appendix. Add a small fixture to the RFC's `required conformance evidence` + showing a2ui view enumeration, deferred materialization, and an action + invocation roundtrip. + ## Required conformance evidence Fixtures must cover: From dd2a15306241ba908b1e0935b373f9d0acafc632 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 15:13:21 -0700 Subject: [PATCH 26/33] docs: clarify control model additive scope --- rfcs/0029-openclaw-control-model.md | 63 +++++++++++-- rfcs/0029/conformance-and-adoption-plan.md | 13 +++ rfcs/0029/control-model-v1-spec.md | 55 +++++++---- rfcs/0029/implementation-plan.md | 8 ++ rfcs/0029/ui-artifact-v1-spec.md | 101 +++++++++++++++++---- 5 files changed, 198 insertions(+), 42 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 1bea6bce..171f63e4 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -3,7 +3,7 @@ title: OpenClaw Control Model authors: - Gio Della-Libera created: 2026-08-11 -last_updated: 2026-08-16 +last_updated: 2026-08-21 status: draft issue: rfc_pr: https://github.com/giodl73-repo/rfcs/pull/8 @@ -135,9 +135,31 @@ artifact contracts defined here and in the two specifications. It would not accept a Lobster product roadmap, a framework adapter, a generic dashboard system, or writable configuration. -The Board Model and Config Model evidence below is non-normative. It tests the -same owner-first extraction pattern against adjacent OpenClaw domains, but each -surface keeps its own contract, release gate, and implementation review. +This RFC is additive to the hosted Control UI and policy work rather than a +replacement for it: + +- hosted Control UI remains the fastest way for a host to serve the + version-matched OpenClaw application, enforce route and method policy, and + roll back to the incumbent product shell; +- the Control Model is the native-product path for conversation state, + commands, and renderer-neutral artifacts when the host owns presentation; +- the hosted policy decision vocabulary remains the server/runtime authority + for browser lockdown, settings read-only state, and forbidden mutations; the + Control Model may preserve safe denial details, but it does not become the + policy engine; +- Board Model and Config Model evidence tests the same owner-first extraction + pattern against adjacent OpenClaw domains, but each surface keeps its own + contract, release gate, and implementation review; and +- Managed Configuration remains the authority-aware path for governed config + writes. A read-only Config Model projection does not imply write authority. + +The "one shot" upstream ask should therefore be the family shape and sequence: +accept the optional Gateway Client Control Model and UI artifact contracts as +the first supported native surface, while explicitly reserving hosted Control +UI policy, Board Model, Config Model, and Managed Configuration as sibling +contracts. That lets maintainers review the complete architecture without +making Control Model v1 responsible for every UI, dashboard, settings, or +policy feature. ### Fork-only implementation evidence @@ -172,8 +194,8 @@ Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, and packed-package acceptance. Owner acceptance remains open under the [ownership and support plan](0029/ownership-and-support-plan.md). -The independent Lobster evidence is also available as a temporary carry plus -six bounded adopter slices: +The independent Lobster evidence started as a temporary carry plus six bounded +adopter slices: 1. [L0: temporary Control Model carry](https://microsoft.ghe.com/bic/lobster/pull/8165) 2. [LM1: adapt canonical snapshots into `SessionView`](https://microsoft.ghe.com/giodl/lobster/pull/63) @@ -188,6 +210,26 @@ history while deleting duplicate Lobster Gateway behavior. It intentionally stops at LM6: remaining raw paths are host-owned operational/security or compatibility lanes rather than equivalent Control Model behavior. +Same-repository Lobster follow-up has since turned the most important adopter +evidence into reviewable product slices: + +- [Lobster PR #9248](https://microsoft.ghe.com/bic/lobster/pull/9248) merged + the temporary OpenClaw v2026.6.33 Control Model and artifact projection carry + after required PullRequest, Build Validation, and POP gates passed. +- [Lobster PR #9384](https://microsoft.ghe.com/bic/lobster/pull/9384) merged + canonical conversation snapshots into Lobster `SessionView` without changing + React renderers, behind the default-off + `EnableOpenClawControlModel` rollout flight. Its exact-head evidence covered + focused desktop tests, Loki schema tests, static checks, Vite build, branch + review, all six Rust E2E shards, all three Playwright runtime shards, both + Git-workspace hard gates, and the multiplayer hard gate. +- [Lobster PR #9605](https://microsoft.ghe.com/bic/lobster/pull/9605) is the + separate native table follow-up. It keeps raw `chat.final` as the visual + commit owner while adding renderer-neutral artifact projection, exact + allowlisted native table rendering, artifact-only history hydration, + fallback coverage, live flight rollback, and Gateway/Electron proof. Its + rollout annotations inherit the existing `EnableOpenClawControlModel` gate. + Two adjacent owner-first projections now have separate fork-only evidence: - [Board Model fork proof](https://github.com/giodl73-repo/openclaw/pull/240) @@ -246,9 +288,11 @@ Adjacent proposals remain separate from Control Model v1 acceptance: | Candidate | Scope | Gate | | --- | --- | --- | +| HCU1: hosted Control UI policy | Serve the version-matched OpenClaw Control UI in a host runtime, advertise host policy through bootstrap, and enforce route/method lockdown server-side. | Already has Lobster hosted-route evidence and OpenClaw hosted-policy drafts; this is the immediate hosted fallback path, not a Control Model dependency. | | BM2: Board Model release admission | Reconstruct the Board Model extraction and native-host conformance against an accepted board-capable OpenClaw release, then decide whether `model/board` is supportable. | Stable board-capable tag, or explicit beta admission with complete persistence, grants, tickets, sandbox, and compatibility review. | | CFG1: read-only Config Model | Extract framework-neutral authored config snapshots and read-scoped schema descriptors into an OpenClaw-owned optional model with Control UI reference adoption. | Config owner review, secret redaction, schema compatibility, and proof that read projection does not imply write authority. | | CFG2: governed configuration commands | Add provenance, owner, lock reason, candidate preview, validation findings, generation, commit, and activation status only through Managed Configuration contracts. | Separate owner approval and transactional write/activation design; not implied by this RFC or CFG1. | +| POL1: hosted policy decisions for settings and Gateway actions | Reuse the hosted decision envelope for `enabled`, `readOnly`, and `disabled` behavior across Control UI settings and Gateway writes. | Policy remains the source of policy findings and constraints; Control Model consumers only receive presentation-safe state and command errors. | Cross-client user-message identity, generic generated layouts, framework adapters, and third-party native component SDKs remain separate future @@ -541,6 +585,13 @@ contract, and a named duplicate implementation or inference path it can delete. Existing OpenClaw dashboards and settings follow separate adoption paths. Lobster can host version-matched dashboard and settings routes immediately. +The hosted policy stack supplies the deployment and lockdown controls for that +path: runtime gates decide whether the hosted bundle is available, bootstrap +declares the host-owned Gateway route and scopes, and server enforcement +blocks forbidden mutations even if a browser affordance is stale or bypassed. +Control Model consumers can mirror disabled/read-only state and safe denial +reasons, but only the Gateway/runtime policy path is authoritative. + The Board Model proof now demonstrates the optional projection of OpenClaw's existing board model and a bounded Lobster native adopter, but only with a mocked beta-generation protocol. No stable OpenClaw tag currently contains the diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 7981c8fc..6eabee37 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -32,6 +32,19 @@ proof, and deletion agree. | R1 publication | OpenClaw PR 6/release | Accepted conformance, two consumers, compatibility window, migration policy, release and support ownership, and clean install/import proof from the packed release artifact | Fork-only distribution | | D1 incumbent cleanup | OpenClaw PR 7 | Observation window, rollback proof, and exact deletion ledger | Superseded Control UI reconciliation | +## Additive adoption map + +Control Model conformance is not the only path for OpenClaw UI in a host. The +supported architecture is additive: + +| Surface | Authority retained | Control Model relationship | +| --- | --- | --- | +| Hosted Control UI | OpenClaw owns the version-matched app; host runtime owns auth, route selection, rollout, and server-side policy enforcement. | Independent deployment/fallback path. It can use the same Gateway, but Control Model v1 does not gate or replace hosted policy enforcement. | +| Native conversation UX | OpenClaw owns conversation semantics; host owns React/native composition. | Primary v1 target: immutable snapshots, typed commands, and renderer-neutral artifacts. | +| Native board/dashboard UX | OpenClaw owns board identity, widgets, grants, tickets, layout, persistence, and sandbox semantics. | Sibling Board Model proposal. Dashboard-shaped conversation artifacts do not replace the board model. | +| Native settings UX | OpenClaw owns schema meaning and config read/write semantics; Managed Configuration owns governed writes and activation. | Sibling Config Model proposal. V1 may show safe command-denial details, but it does not define settings writes. | +| Policy and lockdown | Policy/Gateway/runtime enforcement owns allowed operations, read-only state, disabled state, and denial reasons. | Model consumers may project presentation-safe state and errors; they must not treat UI affordances as authorization. | + ## Evidence to date Fork-only evidence now covers the full bounded V1 thesis: diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index f2d922f2..ae181528 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -46,23 +46,31 @@ The host owns: The model must not start a network connection at import or construction time. It must not persist credentials. -## Handshake & capability advertisement +## Handshake and capability advertisement -Recommendation: the client advertises a bounded capability object during the -initial session handshake or subscription request so the server MAY filter or -rank offered artifact views and avoid sending unsupported large artifacts. -Advertisement is advisory only; it does not grant trust or authorization. +The client may advertise a bounded capability object during the initial +session handshake or subscription request so the server can filter or rank +offered artifact views and avoid sending unsupported large artifacts. +Advertisement is advisory only; it does not install a renderer, disclose the +full local registry, grant trust, or authorize an operation. -Suggested capability object (client → server): +Suggested capability object (client to server): -``` +```json { "clientId": "product/instance-version", "capabilities": { - "supports_html": true, - "supports_a2ui": false, - "supports_native_table": true, - "supports_streaming": true, + "artifactViews": [ + { + "templateUri": "clawpilot://widgets/table", + "artifactVersion": 1, + "dataVersions": [1], + "surfaces": ["inline", "expanded"] + } + ], + "sandboxFallbacks": ["mcp-app", "canvas"], + "structuredFallback": true, + "progressiveRevisions": true, "supports_actions": true, "max_artifact_size_bytes": 65536 } @@ -71,21 +79,30 @@ Suggested capability object (client → server): Server guidance: -1. If an offered view's renderer matches a supported capability, favor - sending the full view (streaming when streamable && supports_streaming). +1. If an offered view matches an advertised template URI, artifact version, and + data version, the server may rank that view higher or include bounded inline + data. 2. If the renderer is unsupported but a structured/text fallback exists, send the fallback instead. -3. If artifact size exceeds `max_artifact_size_bytes` and the client - supports streaming, deliver as fragments (fragment/CID) with finalization - marker; otherwise send a summarized structured fallback. +3. If artifact size exceeds `max_artifact_size_bytes`, send a bounded + structured fallback or expose the view as deferred. V1 publishes complete + immutable revisions; it does not standardize JSON Patch, JSONL, or + fragment/CID transport. 4. Never expose private or scrubbed fields to clients lacking required authorization regardless of advertised capabilities. 5. Treat capability advertisement as potentially stale or incomplete; the client may still decline or ignore offers at render time. -Note: this section proposes a concrete handshake schema and server filtering -rules. The full RFC update will include example exchanges, security privacy -considerations, and an appendix mapping uiDetails fields to capability flags. +Privacy guidance: + +- advertise exact supported template/version pairs, not unrelated installed + component inventory; +- keep renderer capability metadata between the trusted client and Gateway by + default rather than forwarding it verbatim to extensions; +- let extensions ask bounded compatibility questions when needed; and +- require the host registry to validate the selected view again before native + rendering, because the advertisement may be stale. + ## Root lifecycle Construction is inert except for validating options. `start()` may subscribe to diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 0758c7f4..d799b3fa 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -354,6 +354,14 @@ The exact incumbent UI-local paths identified by CU1-CU5 adoption. ## Adjacent surfaces +- **Hosted Control UI and policy:** keep the hosted `/openclaw` route, + bootstrap policy, rollout gates, and server-side method enforcement as the + immediate deployment and lockdown path for hosts that can use OpenClaw's + version-matched application. This path is additive to Control Model. It + proves host-owned auth/routing/rollout and policy enforcement, while Control + Model proves framework-neutral conversation state, commands, and artifacts + for native product shells. A stale or bypassed UI affordance is never + authoritative; Gateway/runtime policy remains the enforcement point. - **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. The first fork-only Board Model proof now extracts selected-session board reconciliation into `@openclaw/gateway-client/model/board` and keeps Control diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 7b646f71..1a39cd4e 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -353,35 +353,36 @@ The following fail artifact rendering without failing the surrounding message: Failures are observable and safe to log after redaction. They must not contain raw credentials, capability URLs, hidden model context, or unbounded tool data. -### Appendix: mapping a2ui → uiDetails +### Appendix: mapping a2ui to uiDetails This appendix shows a pragmatic mapping from common a2ui payload fields into the Control Model's uiDetails/view offer shape. Use this as an implementation guide when adapting an a2ui-producing tool or a2ui-capable Canvas to the Control Model. -- a2ui.root -> UiArtifact.structuredContent or UiArtifactViewOffer.data +- `a2ui.root` -> `UiArtifact.structuredContent` or + `UiArtifactViewOffer.data` - When a2ui produces a single root HTML/DOM fragment, place a sanitized structured representation under `structuredContent` and supply a `view` that declares `templateUri: "ui://a2ui/"`. -- a2ui.components[] -> view.data component array +- `a2ui.components[]` -> `view.data` component array - Map named a2ui components to an array in `view.data.components` with the minimal typed props; include `dataVersion` for component schema validation. -- a2ui.streamable -> view.streamable or UiArtifactViewOffer.meta.streamable - - If the a2ui renderer supports progressive hydration, set `streamable:true` - and provide a fragment/CID plan in `meta.streaming` describing chunk order - and finalization marker. -- a2ui.actions -> UiArtifactViewOffer.actions +- `a2ui.streamable` -> progressive complete artifact revisions + - If the source supports progressive hydration, publish successive complete + immutable artifact revisions. V1 does not standardize fragment/CID or JSONL + patch transport. +- `a2ui.actions` -> local action descriptors - Convert a2ui-defined interactive handlers to typed action descriptors: `{id,label,kind,schema,authRequired}`. Do not embed executable callbacks. -- a2ui.templateUri -> UiArtifactViewOffer.templateUri +- `a2ui.templateUri` -> `UiArtifactViewOffer.templateUri` - Normalize a2ui template references to `ui://a2ui/@` and require exact match in host native registry for native rendering. -- a2ui.deferred -> UiArtifactViewOffer.availability = "deferred" +- `a2ui.deferred` -> `UiArtifactViewOffer.availability = "deferred"` - When the a2ui payload requires server-side materialization, expose it as `deferred` and require `materializeView` to fetch validated payload. -- a2ui.sizeHints -> UiArtifactViewOffer.preferredLayout / uiDetails.minWidth +- `a2ui.sizeHints` -> presentation hints - Map size and layout hints into `preferredLayout`, `minWidth`, `minHeight`. -- a2ui.privacyFlags -> UiArtifact.privacy +- `a2ui.privacyFlags` -> `UiArtifact.privacy` - Translate visibility/scrub flags into `privacy` with `visibility` and `scrubbed` fields; servers must honor these when filtering offers. @@ -393,12 +394,78 @@ Security and runtime notes - Prefer deferred materialization for large or sensitive views so Gateway re-enters auth and policy checks at materialization time. -Examples and next steps +Example mapping: + +```json +{ + "a2ui": { + "templateUri": "ui://a2ui/table@1", + "components": [ + { + "type": "table", + "columns": ["name", "status"], + "rows": [["Northwind", "Ready"]] + } + ], + "actions": [ + { + "id": "refresh", + "schema": { "type": "object", "additionalProperties": false } + } + ], + "deferred": false, + "privacyFlags": { "visibility": "caller", "scrubbed": false } + } +} +``` + +becomes: + +```json +{ + "version": 1, + "id": "artifact-table-1", + "revision": 0, + "structuredContent": { + "columns": ["name", "status"], + "rows": [["Northwind", "Ready"]] + }, + "views": [ + { + "id": "table", + "templateUri": "ui://a2ui/table@1", + "dataVersion": 1, + "availability": "inline", + "data": { + "components": [ + { + "type": "table", + "columns": ["name", "status"], + "rows": [["Northwind", "Ready"]] + } + ], + "actions": [ + { + "id": "refresh", + "schema": { "type": "object", "additionalProperties": false } + } + ] + } + } + ], + "state": "ready", + "source": { + "sessionKey": "session-1", + "toolCallId": "tool-1", + "toolName": "example.table" + } +} +``` -- Append a short example mapping (a2ui JSON -> UiArtifact view) to this - appendix. Add a small fixture to the RFC's `required conformance evidence` - showing a2ui view enumeration, deferred materialization, and an action - invocation roundtrip. +The host may render this natively only when its reviewed local registry accepts +`ui://a2ui/table@1` and data version 1. The `refresh` action is still just a +named local action; the host must map it to a supported Control Model command +or product-owned operation and the Gateway must authorize any protected effect. ## Required conformance evidence From c079692b7e7453ed80ce1c7b102838c29e0cabd5 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 15:14:12 -0700 Subject: [PATCH 27/33] docs: point control model rfc to upstream pr --- rfcs/0029-openclaw-control-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 171f63e4..82d9dc50 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -6,7 +6,7 @@ created: 2026-08-11 last_updated: 2026-08-21 status: draft issue: -rfc_pr: https://github.com/giodl73-repo/rfcs/pull/8 +rfc_pr: https://github.com/openclaw/rfcs/pull/62 --- # Proposal: OpenClaw Control Model From c6a3bef244703d720f07d91fd84750690dbd98a8 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 16:27:16 -0700 Subject: [PATCH 28/33] docs: link control model upstream drafts --- rfcs/0029-openclaw-control-model.md | 58 +++++++++++++--------- rfcs/0029/conformance-and-adoption-plan.md | 16 +++--- rfcs/0029/implementation-plan.md | 46 +++++++++++------ 3 files changed, 75 insertions(+), 45 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 82d9dc50..af41db34 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -161,10 +161,18 @@ contracts. That lets maintainers review the complete architecture without making Control Model v1 responsible for every UI, dashboard, settings, or policy feature. -### Fork-only implementation evidence +### Upstream implementation drafts -The proposed boundary has twelve fork-only implementation and reference-adopter -drafts: +The proposed boundary is now filed upstream as five condensed draft PRs: + +1. [CM1: Control Model session foundation](https://github.com/openclaw/openclaw/pull/127670) +2. [CM2: Control Model conversations](https://github.com/openclaw/openclaw/pull/127671) +3. [CM3: renderer-neutral UI artifacts](https://github.com/openclaw/openclaw/pull/127672) +4. [CM4: conformance, package, performance, compatibility, lifecycle, and security hardening](https://github.com/openclaw/openclaw/pull/127674) +5. [CM5: Control UI command, interaction, and artifact adoption](https://github.com/openclaw/openclaw/pull/127675) + +These are draft review surfaces, not accepted roadmap or merge approval. They +condense the original fork-only evidence stack: 1. [OC1: Gateway Client model foundation](https://github.com/giodl73-repo/openclaw/pull/230) 2. [OC2: conversation model and commands](https://github.com/giodl73-repo/openclaw/pull/231) @@ -179,19 +187,20 @@ drafts: 11. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) 12. [CU5: Control UI interaction and artifact adoption](https://github.com/giodl73-repo/openclaw/pull/243) -These drafts are evidence for review, not an upstream submission or accepted -roadmap. OC5 now proves finite defaults, the representative fixture families, -clean packed-package Node/declaration/browser consumption, measured -steady-state and lifecycle performance, candidate/predecessor/main wire -compatibility, and full-stack security review with the confirmed finding -remediated. A final whole-series review then covered OC1-OC5 and CU4-CU5 with -independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview passes, -followed by a clean Codex branch review. Accepted lifecycle, observer -ownership, canonical-session alias, metadata-bound, history, roster, routing, -and question-state findings were fixed at core head `a158436f085` in PR #248 -and Control UI head `0a8ad4188a6` in PR #243. Final focused proof passed 59 -Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, -and packed-package acceptance. Owner acceptance remains open under the +The upstream PRs currently use the already-published fork heads and are draft +until the RFC and owner acceptance settle. OC5 proves finite defaults, +representative fixture families, clean packed-package Node/declaration/browser +consumption, measured steady-state and lifecycle performance, +candidate/predecessor/main wire compatibility, and full-stack security review +with the confirmed finding remediated. A final whole-series review then covered +OC1-OC5 and CU4-CU5 with independent GPT-5.6 Terra, Claude Opus 5, and Gemini +3.1 Pro Preview passes, followed by a clean Codex branch review. Accepted +lifecycle, observer ownership, canonical-session alias, metadata-bound, +history, roster, routing, and question-state findings were fixed at core head +`a158436f085` in PR #248 / upstream CM4 and Control UI head `0a8ad4188a6` in +PR #243 / upstream CM5. Final focused proof passed 59 Gateway lifecycle/model +tests, 61 integrated Control UI tests, 6 prompt tests, and packed-package +acceptance. Owner acceptance remains open under the [ownership and support plan](0029/ownership-and-support-plan.md). The independent Lobster evidence started as a temporary carry plus six bounded @@ -254,12 +263,13 @@ Two adjacent owner-first projections now have separate fork-only evidence: real Electron Gateway fixture now proves the populated native page, authored value boundary, and restart guidance. -### Proposed future OpenClaw PR sequence +### Proposed OpenClaw PR sequence -No additional upstream PRs or branches are opened by this RFC update. The -remaining work is proposed here so maintainers can review the intended shape -before any implementation is prepared, and any drafts should remain fork-only -until RFC intake and owner approval. +The first implementation review sequence is now visible as draft upstream PRs +CM1-CM5. The drafts remain review aids until RFC intake, owner approval, and +publication gates are explicit. Clean same-repository stacked branches may +replace the current fork-head drafts before merge if maintainers prefer a +non-cumulative diff shape. Control UI adoption is also intentionally incremental. OC4 already proves the first three slices; it does not yet make every Control UI command, interaction, @@ -270,8 +280,8 @@ or artifact path model-backed. | CU1: runtime binding | Create one lazy Control Model runtime over the existing Control UI Gateway client and forward connection/event invalidations without changing Lit presentation. | Complete in OC4. | | CU2: catalog and selection | Drive the active session roster and selected-session lookup from immutable catalog snapshots while retaining unsupported archived/all roster behavior. | Complete in OC4. | | CU3: selected conversation projection | Drive selected-chat history, live subscription, reconnect, and retryable fallback from the lazy conversation handle. | Complete in OC4; the representative overlap/gap/retired-epoch fixtures are now shared in OC5. | -| CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. The adapter preserves session identity, attachment/reply/fencing inputs, reconnect-resume fallback, and structured command errors used by incumbent recovery. | -| CU5: interactions and artifacts | Project selected-session questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus the existing Control UI adapters. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Complete in fork-only [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | +| CU4: ordinary conversation commands | Route the normal composer send and foreground active-run abort through typed conversation commands. Keep steer/inject, realtime talk, background tasks, no-run abort-all, and other operational callers raw until separately classified. | Filed upstream in [CM5](https://github.com/openclaw/openclaw/pull/127675); fork evidence is [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. The adapter preserves session identity, attachment/reply/fencing inputs, reconnect-resume fallback, and structured command errors used by incumbent recovery. | +| CU5: interactions and artifacts | Project selected-session questions and current Canvas/MCP/structured fallbacks through conversation snapshots plus the existing Control UI adapters. Preserve global/operator approval lanes and sandbox ownership where they are not equivalent. | Filed upstream in [CM5](https://github.com/openclaw/openclaw/pull/127675); fork evidence is [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | | CU6: observation and deletion | Run the model-backed path through an observation window, retain rollback, then delete only the superseded UI-local reducers, requests, and compatibility adapters named by the earlier slices. | Maps to OC7 and cannot precede OC6 publication, rollback proof, and an exact deletion ledger. | Board and configuration adoption are not hidden CU slices. They remain the @@ -280,7 +290,7 @@ persistence, and release contracts differ from conversation state. | Candidate | Scope | Gate | | --- | --- | --- | -| [OC5: shared conformance and package hardening](https://github.com/giodl73-repo/openclaw/pull/241) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, and prove package acceptance, steady-state and lifecycle performance, wire compatibility, and security through the stacked PRs #244-#248. | Fork-only technical evidence complete; OC6 remains blocked on explicit owner acceptance and a chosen support window. | +| [CM4: shared conformance and package hardening](https://github.com/openclaw/openclaw/pull/127674) | Promote the proven fixture families into shared Gateway Client/Control UI conformance, finalize finite defaults, and prove package acceptance, steady-state and lifecycle performance, wire compatibility, and security through the fork evidence stack #241 and #244-#248. | Draft upstream review surface filed; OC6 remains blocked on explicit owner acceptance and a chosen support window. | | OC6: supported model subpaths | Publish the optional model subpaths with compatibility window, migration policy, framework-neutral quickstart, release notes, support ownership, and install/import proof from the packed release artifact rather than a workspace checkout. Replace fork-only consumption only after a released package exists. | OC5 passes on the supported release, predecessor where promised, and `main`; the packed artifact passes clean browser and Node consumer checks; independent-host evidence remains valid. | | OC7: incumbent-path cleanup | After an observation window and rollback proof, remove only the superseded Control UI reconciliation, standard command, interaction, artifact-adapter, and compatibility paths actually replaced by CU1-CU5. | OC6 is released, Control UI is stable on the model, and deletion evidence identifies each exact old path. | diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 6eabee37..31845559 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -22,13 +22,13 @@ proof, and deletion agree. | Layer | Review surface | Required proof | Deletion unlocked | | --- | --- | --- | --- | -| M1 Gateway Client model boundary | OpenClaw PR 1 | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | -| M2 conversation projection | OpenClaw PR 2 | Shared history/live/reconnect/tool/approval corpus | Per-consumer chat reducers and event folding | -| A1 UI artifacts | OpenClaw PR 3 | Native, structured-only, MCP fallback, malformed, stale, history cases | Tool-specific presentation interpretation | -| O1 Control UI adoption | OC4 plus CU4-CU6 | Existing Control UI behavior unchanged as runtime, catalog, selected conversation, ordinary commands, interactions, and artifacts move through the model in bounded slices | Only the UI-local capability/reducer/request code replaced by each observed slice | +| M1 Gateway Client model boundary | [CM1 #127670](https://github.com/openclaw/openclaw/pull/127670) | Browser-safe module graph, lifecycle, immutable store contract | Consumer scaffolding for connection/session snapshots | +| M2 conversation projection | [CM2 #127671](https://github.com/openclaw/openclaw/pull/127671) | Shared history/live/reconnect/tool/approval corpus | Per-consumer chat reducers and event folding | +| A1 UI artifacts | [CM3 #127672](https://github.com/openclaw/openclaw/pull/127672) | Native, structured-only, MCP fallback, malformed, stale, history cases | Tool-specific presentation interpretation | +| O1 Control UI adoption | [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674), [CM5 #127675](https://github.com/openclaw/openclaw/pull/127675), and later CU6 | Existing Control UI behavior unchanged as runtime, catalog, selected conversation, ordinary commands, interactions, and artifacts move through the model in bounded slices | Only the UI-local capability/reducer/request code replaced by each observed slice | | H1 independent host | Lobster/M PR 1 | Real hosted Gateway projected into existing host view model | Host-owned Gateway reconciliation for adopted slice | | H2 native artifact | Lobster/M PR 2 | One allowlisted component plus denied action and fallback | One bespoke tool-output rendering path | -| C1 shared conformance | OpenClaw PR 5 | Shared fixtures, finite defaults, browser/Node package acceptance, compatibility canaries, performance bounds, and security review | Publication uncertainty | +| C1 shared conformance | [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674) | Shared fixtures, finite defaults, browser/Node package acceptance, compatibility canaries, performance bounds, and security review | Publication uncertainty | | R1 publication | OpenClaw PR 6/release | Accepted conformance, two consumers, compatibility window, migration policy, release and support ownership, and clean install/import proof from the packed release artifact | Fork-only distribution | | D1 incumbent cleanup | OpenClaw PR 7 | Observation window, rollback proof, and exact deletion ledger | Superseded Control UI reconciliation | @@ -55,7 +55,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC2 | Lazy conversations, deterministic history/live reconciliation, bounded messages/runs/tools/interactions, typed commands, reconnect, and retention. | | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | -| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds; and an independent security review with authority-epoch cache remediation. The latest slice is fork [OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248), stacked on lifecycle PR #247. | +| OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds; and an independent security review with authority-epoch cache remediation. Filed upstream in [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674); the latest fork slice is [OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248), stacked on lifecycle PR #247. | | Whole-series review | Independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview reviews covered OC1-OC5 and CU4-CU5, followed by a clean Codex branch review. Accepted findings were fixed at core head `a158436f085` in PR #248 and Control UI head `0a8ad4188a6` in PR #243. Final focused proof passed 59 Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, and packed-package acceptance. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | @@ -71,7 +71,9 @@ dependency through PR 6. The bounded steady-state projection and retained-memory threshold slice is measured in PR #245, the wire-compatibility canary is measured in PR #246, and the lifecycle performance scenarios are measured in PR #247. The security gate is reviewed and remediated in PR #248. -Control UI CU5 remains fork-only adopter evidence in +Control UI CU5 is filed upstream in +[CM5 #127675](https://github.com/openclaw/openclaw/pull/127675), with fork +adopter evidence in [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243). The whole-series review closes the technical review gate but does not satisfy the explicit acceptance records required by the diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index d799b3fa..eafcfd4c 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -4,6 +4,20 @@ This plan is a proposed review sequence, not an accepted roadmap. It keeps each OpenClaw layer independently useful and delays publication until two consumers prove the contract. +The implementation evidence is now filed upstream as five draft review PRs: + +| Upstream draft | Condensed scope | Fork evidence | +| --- | --- | --- | +| [CM1 #127670](https://github.com/openclaw/openclaw/pull/127670) | Gateway Client model foundation, immutable connection/session snapshots, host binding, lifecycle, and shared event-refresh policy. | OC1 [#230](https://github.com/giodl73-repo/openclaw/pull/230) | +| [CM2 #127671](https://github.com/openclaw/openclaw/pull/127671) | Lazy conversation models, bounded history/live state, runs, tools, approvals, questions, and typed commands. | OC2 [#231](https://github.com/giodl73-repo/openclaw/pull/231) | +| [CM3 #127672](https://github.com/openclaw/openclaw/pull/127672) | Renderer-neutral UI artifacts, view offers, revisions, deferred materialization, and MCP/Canvas fallback. | OC3 [#232](https://github.com/giodl73-repo/openclaw/pull/232) | +| [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674) | Initial Control UI reference adoption plus conformance, package, performance, compatibility, lifecycle, and security hardening. | OC4 [#238](https://github.com/giodl73-repo/openclaw/pull/238), OC5 [#241](https://github.com/giodl73-repo/openclaw/pull/241), [#244](https://github.com/giodl73-repo/openclaw/pull/244)-[#248](https://github.com/giodl73-repo/openclaw/pull/248) | +| [CM5 #127675](https://github.com/openclaw/openclaw/pull/127675) | Control UI ordinary commands, selected questions, and safe artifact-adapter adoption. | CU4 [#242](https://github.com/giodl73-repo/openclaw/pull/242), CU5 [#243](https://github.com/giodl73-repo/openclaw/pull/243) | + +These PRs are drafts until RFC intake, owner acceptance, and publication gates +settle. They currently use the published fork heads; clean same-repository +stacked branches may replace them before merge. + ## Source extraction rules - Move behavior only after a shared fixture captures it. @@ -14,7 +28,7 @@ prove the contract. application framework. - Keep OpenClaw Control UI behavior unchanged during adoption. -## OpenClaw PR 1: Gateway Client model foundation +## CM1 / OpenClaw PR 1: Gateway Client model foundation ### Scope @@ -47,7 +61,7 @@ prove the contract. One duplicate session-catalog reducer in an adopter, after later adoption. -## OpenClaw PR 2: selected conversation and commands +## CM2 / OpenClaw PR 2: selected conversation and commands ### Scope @@ -69,7 +83,7 @@ One duplicate session-catalog reducer in an adopter, after later adoption. Control UI and independent-host reducers for the adopted conversation slice. -## OpenClaw PR 3: renderer-neutral UI artifacts +## CM3 / OpenClaw PR 3: renderer-neutral UI artifacts ### Scope @@ -103,14 +117,17 @@ Control UI and independent-host reducers for the adopted conversation slice. Tool-specific native rendering interpretation and duplicate Canvas/MCP association logic. -## OpenClaw PR 4: Control UI reference adoption +## CM4 / OpenClaw PR 4: Control UI reference adoption OC4 is the initial reference-adoption draft, not the entire Control UI migration. It completes the runtime, catalog, and selected-conversation -projection slices. Fork-only CU4 adds ordinary foreground commands, and -fork-only CU5 adds selected-session question commands plus safe Canvas/MCP -artifact projection. Operational callers and global/operator interaction queues -remain outside these bounded adoption slices. +projection slices and is filed upstream as part of +[CM4 #127674](https://github.com/openclaw/openclaw/pull/127674). CU4 adds +ordinary foreground commands, and CU5 adds selected-session question commands +plus safe Canvas/MCP artifact projection; both are filed upstream as +[CM5 #127675](https://github.com/openclaw/openclaw/pull/127675). Operational +callers and global/operator interaction queues remain outside these bounded +adoption slices. ### Completed scope @@ -140,15 +157,15 @@ observation, and rollback proof. | CU1 runtime binding | Lazy Control Model runtime over the existing Gateway store. | Complete in OC4; no new process, route, or framework adapter. | | CU2 catalog and selection | Active roster and selected-session lookup from catalog snapshots. | Complete in OC4; archived/all rosters remain raw until separately modeled. | | CU3 selected conversation projection | History, live subscription, reconnect, and retryable fallback from the conversation handle. | Complete in OC4; OC5 now owns representative overlap/gap/retired-epoch fixtures. | -| CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. Complete in fork-only [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. | Preserves session identity, attachment/reply/fencing inputs, reconnect-resume and steer fallback, structured active-leaf recovery errors, and raw no-run/session-wide abort ownership. Do not absorb realtime talk, background-task history, or other operational paths without separate ownership proof. | -| CU5 interactions and artifacts | Exact selected-session question answer/cancel commands plus Canvas, MCP App, and structured fallback through snapshot projections. Complete in fork-only [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | Preserves the incumbent prompt lifecycle, expiry deadline, local resolution publication, and raw fallback. Global/operator approval lanes remain outside the slice because their ownership and resolver semantics differ. Artifact data never selects executable code. | +| CU4 ordinary conversation commands | Standard composer send and foreground active-run abort through `ControlModelConversation`. Filed upstream in [CM5 #127675](https://github.com/openclaw/openclaw/pull/127675); fork evidence is [OpenClaw PR #242](https://github.com/giodl73-repo/openclaw/pull/242), stacked on OC5. | Preserves session identity, attachment/reply/fencing inputs, reconnect-resume and steer fallback, structured active-leaf recovery errors, and raw no-run/session-wide abort ownership. Do not absorb realtime talk, background-task history, or other operational paths without separate ownership proof. | +| CU5 interactions and artifacts | Exact selected-session question answer/cancel commands plus Canvas, MCP App, and structured fallback through snapshot projections. Filed upstream in [CM5 #127675](https://github.com/openclaw/openclaw/pull/127675); fork evidence is [OpenClaw PR #243](https://github.com/giodl73-repo/openclaw/pull/243), stacked on CU4. | Preserves the incumbent prompt lifecycle, expiry deadline, local resolution publication, and raw fallback. Global/operator approval lanes remain outside the slice because their ownership and resolver semantics differ. Artifact data never selects executable code. | | CU6 observation and deletion | Roll out the model-backed route, retain rollback, and remove only named incumbent reducers/requests/adapters. | Post-OC6 and implemented as OC7 with an exact deletion ledger. | Board and settings are separate Board Model and Config Model adoption series, not CU7/CU8. Their authority and persistence contracts are non-normative to Control Model v1. -### CU4 fork-only result +### CU4 result CU4 reuses the selected conversation handle already owned by OC4 rather than creating a second runtime or command client. Ordinary selected sends pass @@ -163,7 +180,7 @@ realtime talk, skill-workshop revisions, queued replay, and session-wide structured Gateway details so existing active-leaf recovery and retry behavior remain visible rather than becoming generic failures. -### CU5 fork-only result +### CU5 result CU5 reuses the exact cached selected-conversation route and its authoritative agent identity, including main aliases. Pending question answer/cancel commands @@ -221,9 +238,10 @@ Board LB1 uses a mocked beta-generation board protocol because pinned LobsterClaw 2026.6.33 predates boards. It is conformance evidence, not release admission. -## OpenClaw PR 5: shared conformance and package hardening +## CM4 / OpenClaw PR 5: shared conformance and package hardening -Fork-only draft: +Filed upstream in +[CM4 #127674](https://github.com/openclaw/openclaw/pull/127674). Fork evidence: [giodl73-repo/openclaw#241](https://github.com/giodl73-repo/openclaw/pull/241). Its first slice centralizes finite defaults, adds an authoritative/malformed catalog fixture pair, proves clean packed-package Node/declaration/browser From 7bcfefd7df00a36ce9daf266e0b5f64d895bc443 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 16:41:22 -0700 Subject: [PATCH 29/33] docs: link hosted policy siblings --- rfcs/0029-openclaw-control-model.md | 13 +++++++++++-- rfcs/0029/conformance-and-adoption-plan.md | 7 +++++-- rfcs/0029/implementation-plan.md | 12 +++++++++++- 3 files changed, 27 insertions(+), 5 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index af41db34..4a3b217a 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -161,6 +161,15 @@ contracts. That lets maintainers review the complete architecture without making Control Model v1 responsible for every UI, dashboard, settings, or policy feature. +RFC 0029's sidecar specifications are intentionally limited to Control Model +v1 and UI artifact v1. Hosted Control UI policy is tracked as an adjacent +proposal through [openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), +[openclaw/openclaw#115408](https://github.com/openclaw/openclaw/pull/115408), +and [openclaw/openclaw#116013](https://github.com/openclaw/openclaw/pull/116013). +If maintainers want hosted policy to become normative rather than linked +evidence, it should receive its own RFC sidecar or follow-up RFC instead of +expanding the Control Model v1 contract. + ### Upstream implementation drafts The proposed boundary is now filed upstream as five condensed draft PRs: @@ -298,11 +307,11 @@ Adjacent proposals remain separate from Control Model v1 acceptance: | Candidate | Scope | Gate | | --- | --- | --- | -| HCU1: hosted Control UI policy | Serve the version-matched OpenClaw Control UI in a host runtime, advertise host policy through bootstrap, and enforce route/method lockdown server-side. | Already has Lobster hosted-route evidence and OpenClaw hosted-policy drafts; this is the immediate hosted fallback path, not a Control Model dependency. | +| HCU1: hosted Control UI policy | Serve the version-matched OpenClaw Control UI in a host runtime, advertise host policy through bootstrap, and enforce route/method lockdown server-side. | Tracked by the hosted-surface umbrella [#115423](https://github.com/openclaw/openclaw/issues/115423), host policy draft [#115408](https://github.com/openclaw/openclaw/pull/115408), and Gateway enforcement draft [#116013](https://github.com/openclaw/openclaw/pull/116013). This is the immediate hosted fallback path, not a Control Model dependency. | | BM2: Board Model release admission | Reconstruct the Board Model extraction and native-host conformance against an accepted board-capable OpenClaw release, then decide whether `model/board` is supportable. | Stable board-capable tag, or explicit beta admission with complete persistence, grants, tickets, sandbox, and compatibility review. | | CFG1: read-only Config Model | Extract framework-neutral authored config snapshots and read-scoped schema descriptors into an OpenClaw-owned optional model with Control UI reference adoption. | Config owner review, secret redaction, schema compatibility, and proof that read projection does not imply write authority. | | CFG2: governed configuration commands | Add provenance, owner, lock reason, candidate preview, validation findings, generation, commit, and activation status only through Managed Configuration contracts. | Separate owner approval and transactional write/activation design; not implied by this RFC or CFG1. | -| POL1: hosted policy decisions for settings and Gateway actions | Reuse the hosted decision envelope for `enabled`, `readOnly`, and `disabled` behavior across Control UI settings and Gateway writes. | Policy remains the source of policy findings and constraints; Control Model consumers only receive presentation-safe state and command errors. | +| POL1: hosted policy decisions for settings and Gateway actions | Reuse the hosted decision envelope for `enabled`, `readOnly`, and `disabled` behavior across Control UI settings and Gateway writes. | Fork-only policy-settings drafts [#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202) prove the shape. Policy remains the source of policy findings and constraints; Control Model consumers only receive presentation-safe state and command errors. | Cross-client user-message identity, generic generated layouts, framework adapters, and third-party native component SDKs remain separate future diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 31845559..564c633c 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -39,11 +39,14 @@ supported architecture is additive: | Surface | Authority retained | Control Model relationship | | --- | --- | --- | -| Hosted Control UI | OpenClaw owns the version-matched app; host runtime owns auth, route selection, rollout, and server-side policy enforcement. | Independent deployment/fallback path. It can use the same Gateway, but Control Model v1 does not gate or replace hosted policy enforcement. | +| Hosted Control UI | OpenClaw owns the version-matched app; host runtime owns auth, route selection, rollout, and server-side policy enforcement. | Independent deployment/fallback path tracked by [openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), [#115408](https://github.com/openclaw/openclaw/pull/115408), and [#116013](https://github.com/openclaw/openclaw/pull/116013). It can use the same Gateway, but Control Model v1 does not gate or replace hosted policy enforcement. | | Native conversation UX | OpenClaw owns conversation semantics; host owns React/native composition. | Primary v1 target: immutable snapshots, typed commands, and renderer-neutral artifacts. | | Native board/dashboard UX | OpenClaw owns board identity, widgets, grants, tickets, layout, persistence, and sandbox semantics. | Sibling Board Model proposal. Dashboard-shaped conversation artifacts do not replace the board model. | | Native settings UX | OpenClaw owns schema meaning and config read/write semantics; Managed Configuration owns governed writes and activation. | Sibling Config Model proposal. V1 may show safe command-denial details, but it does not define settings writes. | -| Policy and lockdown | Policy/Gateway/runtime enforcement owns allowed operations, read-only state, disabled state, and denial reasons. | Model consumers may project presentation-safe state and errors; they must not treat UI affordances as authorization. | +| Policy and lockdown | Policy/Gateway/runtime enforcement owns allowed operations, read-only state, disabled state, and denial reasons. | Model consumers may project presentation-safe state and errors; they must not treat UI affordances as authorization. Fork-only settings-constraint drafts [giodl73-repo/openclaw#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202) are sibling evidence, not Control Model conformance. | + +RFC 0029 has sidecar specifications for Control Model v1 and UI artifact v1. +It does not currently carry a hosted-policy sidecar specification. ## Evidence to date diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index eafcfd4c..e93e8e62 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -379,7 +379,17 @@ The exact incumbent UI-local paths identified by CU1-CU5 adoption. proves host-owned auth/routing/rollout and policy enforcement, while Control Model proves framework-neutral conversation state, commands, and artifacts for native product shells. A stale or bypassed UI affordance is never - authoritative; Gateway/runtime policy remains the enforcement point. + authoritative; Gateway/runtime policy remains the enforcement point. The + linked hosted-policy surfaces are umbrella issue + [openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), + host-policy draft [#115408](https://github.com/openclaw/openclaw/pull/115408), + and Gateway enforcement draft + [#116013](https://github.com/openclaw/openclaw/pull/116013). Policy-settings + constraints remain fork-only sibling evidence in + [giodl73-repo/openclaw#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202). + RFC 0029 does not define a hosted-policy sidecar spec; that contract should + be promoted through its own sidecar or follow-up RFC if maintainers want it + normative. - **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. The first fork-only Board Model proof now extracts selected-session board reconciliation into `@openclaw/gateway-client/model/board` and keeps Control From bca94c8a8ebc54fc825626cb1d27d350b7f5ab65 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 21 Aug 2026 16:58:02 -0700 Subject: [PATCH 30/33] docs: add hosted control ui policy sidecar --- rfcs/0029-openclaw-control-model.md | 23 ++- rfcs/0029/conformance-and-adoption-plan.md | 5 +- rfcs/0029/hosted-control-ui-policy-v1-spec.md | 181 ++++++++++++++++++ rfcs/0029/implementation-plan.md | 8 +- 4 files changed, 202 insertions(+), 15 deletions(-) create mode 100644 rfcs/0029/hosted-control-ui-policy-v1-spec.md diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 4a3b217a..c8eff3be 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -123,6 +123,7 @@ documents: - [Control Model v1 specification](0029/control-model-v1-spec.md) - [UI artifact v1 specification](0029/ui-artifact-v1-spec.md) +- [Hosted Control UI policy v1 specification](0029/hosted-control-ui-policy-v1-spec.md) - [Conformance and adoption plan](0029/conformance-and-adoption-plan.md) - [Implementation and PR plan](0029/implementation-plan.md) - [Ownership and support plan](0029/ownership-and-support-plan.md) @@ -130,10 +131,12 @@ documents: ### Review scope -RFC acceptance would cover only the framework-neutral Control Model v1 and UI -artifact contracts defined here and in the two specifications. It would not -accept a Lobster product roadmap, a framework adapter, a generic dashboard -system, or writable configuration. +RFC acceptance may cover the related family shape while keeping each contract's +acceptance gate independent: framework-neutral Control Model v1, UI artifact +v1, and hosted Control UI policy v1. Accepting one contract does not imply +accepting or shipping the others. This RFC would not accept a Lobster product +roadmap, a framework adapter, a generic dashboard system, or writable +configuration. This RFC is additive to the hosted Control UI and policy work rather than a replacement for it: @@ -161,14 +164,14 @@ contracts. That lets maintainers review the complete architecture without making Control Model v1 responsible for every UI, dashboard, settings, or policy feature. -RFC 0029's sidecar specifications are intentionally limited to Control Model -v1 and UI artifact v1. Hosted Control UI policy is tracked as an adjacent -proposal through [openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), +RFC 0029 therefore includes a hosted-policy sidecar, but that sidecar is not a +Control Model v1 dependency. Hosted Control UI policy is tracked through +[openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), [openclaw/openclaw#115408](https://github.com/openclaw/openclaw/pull/115408), and [openclaw/openclaw#116013](https://github.com/openclaw/openclaw/pull/116013). -If maintainers want hosted policy to become normative rather than linked -evidence, it should receive its own RFC sidecar or follow-up RFC instead of -expanding the Control Model v1 contract. +Its acceptance should be judged against hosted route, bootstrap, rollout, and +Gateway/runtime enforcement evidence rather than native conversation-model +conformance. ### Upstream implementation drafts diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index 564c633c..b0683d1e 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -45,8 +45,9 @@ supported architecture is additive: | Native settings UX | OpenClaw owns schema meaning and config read/write semantics; Managed Configuration owns governed writes and activation. | Sibling Config Model proposal. V1 may show safe command-denial details, but it does not define settings writes. | | Policy and lockdown | Policy/Gateway/runtime enforcement owns allowed operations, read-only state, disabled state, and denial reasons. | Model consumers may project presentation-safe state and errors; they must not treat UI affordances as authorization. Fork-only settings-constraint drafts [giodl73-repo/openclaw#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202) are sibling evidence, not Control Model conformance. | -RFC 0029 has sidecar specifications for Control Model v1 and UI artifact v1. -It does not currently carry a hosted-policy sidecar specification. +RFC 0029 has sidecar specifications for Control Model v1, UI artifact v1, and +Hosted Control UI policy v1. These contracts share an owner-first family shape, +but each has an independent conformance and acceptance gate. ## Evidence to date diff --git a/rfcs/0029/hosted-control-ui-policy-v1-spec.md b/rfcs/0029/hosted-control-ui-policy-v1-spec.md new file mode 100644 index 00000000..64616b57 --- /dev/null +++ b/rfcs/0029/hosted-control-ui-policy-v1-spec.md @@ -0,0 +1,181 @@ +# Hosted Control UI policy v1 specification + +This document defines the candidate hosted-policy contract for serving the +version-matched OpenClaw Control UI from a host runtime. It is related to the +Control Model because both surfaces let a product host OpenClaw behavior +without forking OpenClaw semantics. It remains a sibling contract: hosted +policy governs deployment, route access, and runtime enforcement, while the +Control Model governs native conversation state, commands, and artifacts. + +Status: draft. The active implementation surfaces are +[openclaw/openclaw#115423](https://github.com/openclaw/openclaw/issues/115423), +[openclaw/openclaw#115408](https://github.com/openclaw/openclaw/pull/115408), +and [openclaw/openclaw#116013](https://github.com/openclaw/openclaw/pull/116013). +Settings-constraint evidence is currently fork-only in +[giodl73-repo/openclaw#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202). + +## Scope + +A conforming v1 hosted-policy implementation provides: + +- an explicit host decision for whether the hosted OpenClaw Control UI route is + enabled; +- a bounded bootstrap payload that declares host-owned route, Gateway, rollout, + and lockdown decisions safe for the browser; +- server-side route and method enforcement that remains authoritative even when + browser state is stale or bypassed; +- policy decision states for enabled, disabled, and read-only affordances; +- safe denial reasons and owner/source metadata where policy permits display; +- rollback to the incumbent host shell or disabled route without changing the + OpenClaw bundle; and +- conformance evidence that blocked operations fail at the Gateway/runtime + boundary, not only in UI controls. + +This contract does not define a native renderer, a Control Model adapter, a +generic dashboard system, writable configuration authority, or a replacement +for Managed Configuration. + +## Ownership + +OpenClaw owns: + +- the version-matched Control UI bundle; +- the policy vocabulary consumed by the hosted UI; +- Gateway method names and protected operation classification; +- browser-safe bootstrap schema compatibility; and +- default denial and fallback behavior. + +The host runtime owns: + +- route selection and admission; +- product authentication and tenant/device gating; +- rollout, kill switches, and rollback; +- server-side route and method enforcement; +- policy source binding; and +- operational telemetry and audit sinks. + +Policy remains authoritative at the Gateway/runtime boundary. A browser control +may hide, disable, or annotate an operation, but that affordance is never +authorization. + +## Bootstrap payload + +The host may expose a bounded bootstrap payload to the hosted Control UI before +or during application startup. The shape may evolve, but v1 semantics must +cover: + +```ts +export interface HostedControlUiPolicyBootstrap { + version: 1; + hostedUi: { + enabled: boolean; + routeBase: string; + gatewayBase: string; + rollout?: HostedRolloutState; + }; + lockdown: { + allowedRoutes: string[]; + allowedGatewayMethods: string[]; + deniedGatewayMethods?: HostedPolicyDecision[]; + }; + settings?: { + constraints: HostedSettingsConstraint[]; + }; +} + +export interface HostedPolicyDecision { + target: string; + state: "enabled" | "readOnly" | "disabled"; + reasonCode?: string; + message?: string; + owner?: string; +} + +export interface HostedSettingsConstraint { + key: string; + state: "enabled" | "readOnly" | "disabled"; + reasonCode?: string; + message?: string; + owner?: string; +} + +export interface HostedRolloutState { + flight?: string; + enabled: boolean; + fallbackRoute?: string; +} +``` + +The bootstrap payload must not include credentials, bearer tokens, raw policy +documents, hidden model context, unrestricted Gateway method lists, or +unbounded error details. + +## Route policy + +The host runtime must decide whether the hosted OpenClaw Control UI route is +available for the current product, tenant, user, device, and rollout state. + +When hosted UI is disabled, the route must fail closed or redirect to an +explicit host-owned fallback. The browser bundle must not infer availability by +probing protected Gateway methods. + +Allowed route declarations are presentation hints. The server remains +authoritative for every request. + +## Gateway method policy + +Gateway method enforcement must happen server-side. A conforming v1 +implementation: + +- classifies protected Gateway methods before exposure to the hosted browser; +- denies forbidden methods even if a stale UI control still calls them; +- preserves safe structured denial codes; +- does not leak raw policy source data in denial payloads; +- keeps read-only decisions distinct from unavailable or unsupported methods; + and +- logs or meters denial outcomes without recording sensitive request payloads by + default. + +The hosted Control UI may use bootstrap decisions to hide, disable, or annotate +controls. Those controls improve usability only; they do not authorize the +operation. + +## Settings constraints + +Settings constraints describe browser-safe policy state for settings controls: + +- `enabled`: the setting may be shown and edited subject to ordinary schema and + Gateway validation; +- `readOnly`: the setting may be shown but mutation is disabled and server-side + writes must be denied or redirected to a governed path; and +- `disabled`: the setting is unavailable in this hosted context. + +Settings constraints do not create write authority. Governed writes require the +separate Managed Configuration contract for provenance, validation findings, +candidate preview, generation, commit, activation, and rollback. + +## Rollback and compatibility + +Hosted policy must be independently rollbackable from Control Model adoption. +A host can disable the hosted route, restrict methods, or return to an +incumbent shell without changing native Control Model consumers. + +Unknown additive bootstrap fields must be ignored. Missing required v1 fields +must fail closed rather than enabling hosted UI or protected Gateway methods by +default. + +## Required conformance evidence + +Before v1 support is claimed, evidence must cover: + +- hosted route disabled and enabled states; +- route rollback to an incumbent host surface; +- bootstrap payload shape and unknown-field compatibility; +- denied Gateway method blocked server-side despite a direct browser call; +- read-only setting visibly disabled and write denied server-side; +- disabled setting unavailable without leaking raw policy details; +- stale bootstrap state corrected by authoritative Gateway/runtime denial; +- safe denial reason preservation; +- audit/telemetry without raw sensitive payloads; and +- coexistence with Control Model consumers without making either surface a + dependency of the other. diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index e93e8e62..23112fcb 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -387,9 +387,11 @@ The exact incumbent UI-local paths identified by CU1-CU5 adoption. [#116013](https://github.com/openclaw/openclaw/pull/116013). Policy-settings constraints remain fork-only sibling evidence in [giodl73-repo/openclaw#196](https://github.com/giodl73-repo/openclaw/pull/196)-[#202](https://github.com/giodl73-repo/openclaw/pull/202). - RFC 0029 does not define a hosted-policy sidecar spec; that contract should - be promoted through its own sidecar or follow-up RFC if maintainers want it - normative. + RFC 0029 now carries + [Hosted Control UI policy v1](hosted-control-ui-policy-v1-spec.md) as a + sibling sidecar with its own route, bootstrap, rollout, and + Gateway/runtime-enforcement gates. That sidecar is related evidence, not a + Control Model v1 dependency. - **Dashboards and widgets:** host OpenClaw's existing dashboard routes first. The first fork-only Board Model proof now extracts selected-session board reconciliation into `@openclaw/gateway-client/model/board` and keeps Control From 939dc20ec8cbea4ae7e41f4fcc8f0b53d96601a7 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 23 Aug 2026 06:19:51 -0700 Subject: [PATCH 31/33] docs: align rfc submission status --- rfcs/0029-openclaw-control-model.md | 5 +++-- rfcs/0029/control-model-v1-spec.md | 4 ++-- rfcs/0029/implementation-plan.md | 15 ++++++++------- rfcs/0029/ui-artifact-v1-spec.md | 3 ++- 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index c8eff3be..41ee7af0 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -21,8 +21,9 @@ React, routes, or product presentation. OpenClaw's Control UI and independently owned product shells could consume the same behavior while retaining their own components, navigation, theming, authentication, and rollout. -This document is a fork-only design preview. It does not request RFC intake, -open an upstream pull request, or claim maintainer acceptance. +This document is the submitted draft for RFC 0029. It requests design review +of the proposed Control Model family, but does not claim maintainer acceptance, +implementation approval, release support, or product adoption. ## Motivation diff --git a/rfcs/0029/control-model-v1-spec.md b/rfcs/0029/control-model-v1-spec.md index ae181528..3bdeb94f 100644 --- a/rfcs/0029/control-model-v1-spec.md +++ b/rfcs/0029/control-model-v1-spec.md @@ -5,8 +5,8 @@ This document defines the candidate behavioral contract for commands above the Gateway Client browser transport. It does not define presentation, product authentication, or another wire protocol. -Status: draft. This is a fork-only preview and has not been submitted or -accepted upstream. +Status: submitted draft sidecar for RFC 0029. It has not been accepted or +released upstream; implementation evidence remains draft and review-gated. ## Scope diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 23112fcb..03f57360 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -424,11 +424,12 @@ Each deferred surface requires a separate owner-first slice and deletion case. ## Fork-only proposal policy -This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 now has -fork-only hardening drafts for package/shared-fixture evidence and bounded +This plan names OC5-OC7, BM2, CFG1, and CFG2 for maintainer review. OC5 has +fork-linked hardening drafts for package/shared-fixture evidence and bounded projection/retained-memory thresholds, candidate/predecessor/main wire -compatibility, lifecycle performance bounds, and reviewed security hardening; -the complete OC1-OC5 and CU4-CU5 stack is now review-clean. No upstream branch -or PR was opened. OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any -further implementation drafts should remain in the author's forks until RFC -intake and the relevant OpenClaw owners approve the surface. +compatibility, lifecycle performance bounds, and reviewed security hardening. +The complete OC1-OC5 and CU4-CU5 stack is review-clean and the condensed +Control Model evidence is now visible upstream through draft PRs CM1-CM5. +OC6, OC7, BM2, CFG1, and CFG2 remain proposals only. Any further implementation +drafts should remain in the author's forks until RFC intake and the relevant +OpenClaw owners approve the surface. diff --git a/rfcs/0029/ui-artifact-v1-spec.md b/rfcs/0029/ui-artifact-v1-spec.md index 1a39cd4e..bcbdcb17 100644 --- a/rfcs/0029/ui-artifact-v1-spec.md +++ b/rfcs/0029/ui-artifact-v1-spec.md @@ -5,7 +5,8 @@ This document defines a renderer-neutral UI artifact projected by first-party presentation while preserving structured output and sandboxed third-party fallback. -Status: draft. This is a fork-only preview. +Status: submitted draft sidecar for RFC 0029. It has not been accepted or +released upstream; implementation evidence remains draft and review-gated. ## Principles From 6a7d949bbc87e43d9c486d5d0154385aeb4c6d88 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 23 Aug 2026 13:25:07 -0700 Subject: [PATCH 32/33] docs: mark Lobster native table evidence merged --- rfcs/0029-openclaw-control-model.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 41ee7af0..9a3ccde1 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -245,8 +245,9 @@ evidence into reviewable product slices: focused desktop tests, Loki schema tests, static checks, Vite build, branch review, all six Rust E2E shards, all three Playwright runtime shards, both Git-workspace hard gates, and the multiplayer hard gate. -- [Lobster PR #9605](https://microsoft.ghe.com/bic/lobster/pull/9605) is the - separate native table follow-up. It keeps raw `chat.final` as the visual +- [Lobster PR #9605](https://microsoft.ghe.com/bic/lobster/pull/9605) merged + the separate native table follow-up as `476282420292` after required + PullRequest and POP gates passed. It keeps raw `chat.final` as the visual commit owner while adding renderer-neutral artifact projection, exact allowlisted native table rendering, artifact-only history hydration, fallback coverage, live flight rollback, and Gateway/Electron proof. Its From 7a8f437ce152c0f13860e43b04afbf56e50928ef Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 23 Aug 2026 15:22:57 -0700 Subject: [PATCH 33/33] docs: link session-list follow-up evidence --- rfcs/0029-openclaw-control-model.md | 16 ++++++++++------ rfcs/0029/conformance-and-adoption-plan.md | 1 + rfcs/0029/implementation-plan.md | 7 ++++++- 3 files changed, 17 insertions(+), 7 deletions(-) diff --git a/rfcs/0029-openclaw-control-model.md b/rfcs/0029-openclaw-control-model.md index 9a3ccde1..99680132 100644 --- a/rfcs/0029-openclaw-control-model.md +++ b/rfcs/0029-openclaw-control-model.md @@ -197,18 +197,22 @@ condense the original fork-only evidence stack: 8. [OC5: wire-compatibility canary](https://github.com/giodl73-repo/openclaw/pull/246) 9. [OC5: lifecycle performance](https://github.com/giodl73-repo/openclaw/pull/247) 10. [OC5: security review and authority-epoch hardening](https://github.com/giodl73-repo/openclaw/pull/248) -11. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) -12. [CU5: Control UI interaction and artifact adoption](https://github.com/giodl73-repo/openclaw/pull/243) +11. [Session-list projection follow-up](https://github.com/giodl73-repo/openclaw/pull/249) +12. [CU4: Control UI ordinary command adoption](https://github.com/giodl73-repo/openclaw/pull/242) +13. [CU5: Control UI interaction and artifact adoption](https://github.com/giodl73-repo/openclaw/pull/243) The upstream PRs currently use the already-published fork heads and are draft until the RFC and owner acceptance settle. OC5 proves finite defaults, representative fixture families, clean packed-package Node/declaration/browser consumption, measured steady-state and lifecycle performance, candidate/predecessor/main wire compatibility, and full-stack security review -with the confirmed finding remediated. A final whole-series review then covered -OC1-OC5 and CU4-CU5 with independent GPT-5.6 Terra, Claude Opus 5, and Gemini -3.1 Pro Preview passes, followed by a clean Codex branch review. Accepted -lifecycle, observer ownership, canonical-session alias, metadata-bound, +with the confirmed finding remediated. The session-list follow-up is additive +evidence that product shells can consume a smaller read-only roster projection +derived from the existing session catalog without adding Gateway methods, +session mutations, chat send, or history behavior. A final whole-series review +then covered OC1-OC5 and CU4-CU5 with independent GPT-5.6 Terra, Claude Opus +5, and Gemini 3.1 Pro Preview passes, followed by a clean Codex branch review. +Accepted lifecycle, observer ownership, canonical-session alias, metadata-bound, history, roster, routing, and question-state findings were fixed at core head `a158436f085` in PR #248 / upstream CM4 and Control UI head `0a8ad4188a6` in PR #243 / upstream CM5. Final focused proof passed 59 Gateway lifecycle/model diff --git a/rfcs/0029/conformance-and-adoption-plan.md b/rfcs/0029/conformance-and-adoption-plan.md index b0683d1e..fe7ca1cf 100644 --- a/rfcs/0029/conformance-and-adoption-plan.md +++ b/rfcs/0029/conformance-and-adoption-plan.md @@ -60,6 +60,7 @@ Fork-only evidence now covers the full bounded V1 thesis: | OC3 | Sanitized renderer-neutral artifacts, history/reconnect revisions, selected-only deferred materialization, MCP App/Canvas fallback, and provenance/identity hardening. | | OC4 | Initial Control UI adoption: lazy runtime binding, canonical active-session catalog, and selected-chat history/subscription state without visual or startup-budget regression. Ordinary commands, interactions, artifacts, and operational callers remain outside this draft. | | OC5 current slices | Centralized finite defaults; reusable catalog, history/live overlap, reconnect, approval authorization, run, tool, question, artifact, and retained-bounds fixtures; packed protocol/client installation; every Gateway Client export imported from the tarball; declaration consumption; browser bundling; repair of a package-only browser export failure; asserted steady-state projection and retained-memory bounds; an asserted candidate/predecessor/main wire-compatibility matrix; asserted initial projection, selected-view materialization, inactive eviction, and reconnect/resync lifecycle bounds; and an independent security review with authority-epoch cache remediation. Filed upstream in [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674); the latest fork slice is [OpenClaw PR #248](https://github.com/giodl73-repo/openclaw/pull/248), stacked on lifecycle PR #247. | +| Session-list follow-up | [OpenClaw PR #249](https://github.com/giodl73-repo/openclaw/pull/249) derives a product-shell read-only session roster from the existing bounded `sessionCatalog`, covering stable identity, title, status, model/provider, navigation metadata, and sanitized worktree summary without adding Gateway requests, session mutations, chat send, or history behavior. | | Whole-series review | Independent GPT-5.6 Terra, Claude Opus 5, and Gemini 3.1 Pro Preview reviews covered OC1-OC5 and CU4-CU5, followed by a clean Codex branch review. Accepted findings were fixed at core head `a158436f085` in PR #248 and Control UI head `0a8ad4188a6` in PR #243. Final focused proof passed 59 Gateway lifecycle/model tests, 61 integrated Control UI tests, 6 prompt tests, and packed-package acceptance. | | CU4 | Fork-only Control UI ordinary-command adoption: selected composer sends and connected exact-run aborts route through the existing conversation handle while reconnect-resume, steer/inject, background/non-selected, realtime, replay, and session-wide abort paths remain raw. Session identity, attachments, reply/fencing inputs, retry metadata, and active-leaf recovery details are preserved. | | CU5 | Fork-only selected-session interaction and artifact adoption: exact pending question answer/cancel commands route through the cached conversation identity while Control UI retains prompt lifecycle and raw fallback. Validated ready Canvas/MCP artifact snapshots feed only existing sandboxed adapters, with canonical-first provenance and occurrence-aware compatibility dedupe. Global/operator approval queues remain raw. | diff --git a/rfcs/0029/implementation-plan.md b/rfcs/0029/implementation-plan.md index 03f57360..3d5a3a1e 100644 --- a/rfcs/0029/implementation-plan.md +++ b/rfcs/0029/implementation-plan.md @@ -8,7 +8,7 @@ The implementation evidence is now filed upstream as five draft review PRs: | Upstream draft | Condensed scope | Fork evidence | | --- | --- | --- | -| [CM1 #127670](https://github.com/openclaw/openclaw/pull/127670) | Gateway Client model foundation, immutable connection/session snapshots, host binding, lifecycle, and shared event-refresh policy. | OC1 [#230](https://github.com/giodl73-repo/openclaw/pull/230) | +| [CM1 #127670](https://github.com/openclaw/openclaw/pull/127670) | Gateway Client model foundation, immutable connection/session snapshots, host binding, lifecycle, and shared event-refresh policy. | OC1 [#230](https://github.com/giodl73-repo/openclaw/pull/230), session-list follow-up [#249](https://github.com/giodl73-repo/openclaw/pull/249) | | [CM2 #127671](https://github.com/openclaw/openclaw/pull/127671) | Lazy conversation models, bounded history/live state, runs, tools, approvals, questions, and typed commands. | OC2 [#231](https://github.com/giodl73-repo/openclaw/pull/231) | | [CM3 #127672](https://github.com/openclaw/openclaw/pull/127672) | Renderer-neutral UI artifacts, view offers, revisions, deferred materialization, and MCP/Canvas fallback. | OC3 [#232](https://github.com/giodl73-repo/openclaw/pull/232) | | [CM4 #127674](https://github.com/openclaw/openclaw/pull/127674) | Initial Control UI reference adoption plus conformance, package, performance, compatibility, lifecycle, and security hardening. | OC4 [#238](https://github.com/giodl73-repo/openclaw/pull/238), OC5 [#241](https://github.com/giodl73-repo/openclaw/pull/241), [#244](https://github.com/giodl73-repo/openclaw/pull/244)-[#248](https://github.com/giodl73-repo/openclaw/pull/248) | @@ -18,6 +18,11 @@ These PRs are drafts until RFC intake, owner acceptance, and publication gates settle. They currently use the published fork heads; clean same-repository stacked branches may replace them before merge. +The session-list follow-up is additive evidence over CM1's catalog boundary. It +derives a smaller read-only roster projection from `sessionCatalog` for product +shells and deliberately adds no Gateway request, session mutation, chat send, or +history behavior. + ## Source extraction rules - Move behavior only after a shared fixture captures it.