RFC 0002: Modular agent runtime integration packages

[ericksoa]

RFC 0002: Modular agent runtime integration packages

• Status: Proposed.
• Author: Aaron Erickson.
• Created: 2026-08-21.
• Discussion: This thread.
• Requested architecture reviewer: @cv.
• Related NemoClaw work: source-boundary roadmap #7691, onboarding authority roadmap #7700, OpenClaw artifact co-location #7698, Pi agent runtime epic #7923, DeepSeek Harness agent runtime epic #9328, and refactoring lessons discussion #9182.
• Related design: OpenClaw RFC 0027.
• Related OpenShell work: architecture at the NemoClaw-supported v0.0.106 baseline, public API, SDK, and extension stabilization #2565, OpenShell Drivers #1051, driver lifecycle #2417, and the OpenShell Roadmap.

Decision

NemoClaw should define one versioned contract for agent runtime integration packages.

After the migration:

• A first-party integration lives in a package-owned area of the NemoClaw repository.
• A new agent runtime changes its package, catalog data, tests, documentation, and qualification evidence. It does not add agent-specific core production code.
• NemoClaw core owns the product workflow, package catalog, generic plans, product state, rollback decisions, and support decisions.
• OpenShell owns sandbox lifecycle and state, compute-driver dispatch, policy enforcement, provider and credential handling, inference interception, and sandbox-local process execution.
• An external integration can implement the same public contract from another repository.
• Repository location and contract compatibility do not establish product support. The NemoClaw support catalog selects each supported release.

The term plugin remains reserved for a package loaded by an agent runtime. This RFC uses integration package for the NemoClaw boundary.

Problem

NemoClaw discovers agent manifests under agents/*/manifest.yaml. A manifest defines identity, runtime shape, configuration paths, health, inference, Model Context Protocol (MCP) support, state, and packaged artifacts.

The manifest does not own all agent-specific behavior. Core code still selects agent behavior during onboarding, startup, inference mutation, recovery, MCP configuration, messaging, Shields operations, state restore, image publication, and end-to-end (E2E) testing.

A scan of commit c6dbeae8 found:

• 443 explicit agent-name conditionals across 147 non-test files in src/lib, scripts, and tools.
• 123 non-test files outside agents/ with OpenClaw, Hermes, Deep Agents Code, or Pi in the filename.
• About 39,000 lines in those agent-named files.

These counts measure coupling. They do not estimate deletion.

Representative dispatch points include:

• profile-builder.ts, which builds separate startup profiles for each agent runtime.
• mcp-bridge-adapters.ts, which dispatches a closed set of MCP adapters.
• managed-image/contract.ts, which lists agents, image repositories, and runtime identities.
• gateway-restart.ts, which contains separate Hermes and OpenClaw recovery behavior.
• agents/openclaw/manifest.yaml, which records an incomplete artifact move.

This structure increases the review and qualification scope for each agent runtime. A change for one runtime can also affect another runtime through shared files.

The internal RuntimeProviderBundle has a different role. It contains core-only compatibility for Docker and Kubernetes. Integration packages must not import or extend it. NemoClaw can remove overlapping facets only after a supported OpenShell release provides equivalent behavior and passes the supported E2E matrix.

Scope

Goals

• Define one package contract for supported and candidate agent runtimes.
• Keep agent-specific executable behavior outside the NemoClaw host process.
• Give each package ownership of its image, startup declaration, native configuration, health semantics, diagnostics, MCP behavior, state declarations, and agent-specific tests.
• Give NemoClaw one package registry and one OpenShell client boundary.
• Apply the same package contract to first-party and external integrations.
• Pin the exact package, image, OpenShell release, provenance, and qualification identity for each selected release.
• Preserve current commands and supported behavior during migration.
• Prevent new agent-name branches in core production code.
• Align applicable terms with OpenClaw RFC 0027.

Non-goals

This RFC does not:

• Define a public marketplace or automatic package installation.
• Load arbitrary external code into the NemoClaw host process.
• Let a package call OpenShell, Docker, Podman, Kubernetes, or a credential backend directly.
• Use an OpenShell driver, gateway interceptor, or supervisor middleware module as the agent package system.
• Let a package widen effective policy or select a credential backend.
• Put an upstream provider credential in a sandbox, descriptor, plan, state record, log, or qualification artifact.
• Treat compatibility or launch success as product support.
• Change the current support matrix.
• Claim an OpenShell roadmap capability before NemoClaw pins and qualifies a release that provides it.
• Implement the OpenClaw Controller, multi-tenancy, OpenClaw Access Gateway, or OpenClaw AgentRevision storage.
• Move first-party integration source out of the NemoClaw repository.
• Replace every agent runtime or the internal runtime-provider abstraction in one change.

Terms

This RFC uses these OpenClaw RFC 0027 terms where they apply:

Term	Meaning in this RFC
Agent	The stable logical agent. Current fields can retain the literal agent during migration, but new contracts must distinguish the logical agent from its runtime.
AgentRevision	An immutable deployment input. NemoClaw does not add this resource, but package, image, plan, policy, inference, and qualification identities must be suitable revision inputs.
WorkloadIdentity	The stable runtime identity for one logical agent. A package cannot choose this identity or inherit the deploying user's credentials.
Harness	The installation-scoped agent runtime resource in OpenClaw RFC 0027. NemoClaw uses agent runtime for OpenClaw, Hermes, LangChain Deep Agents Code, Pi, and DeepSeek Harness.
Driver	An implementation of admitted infrastructure intent. An integration package is not a compute driver or sandbox driver. A future enterprise integration can map OpenShell enforcement to SandboxDriver, but this RFC does not claim that mapping as shipped.
Adapter	A bounded protocol translation. NemoClaw owns the OpenShell client adapter. A package can include an in-sandbox helper for native agent behavior.
Channel	A messaging surface. NemoClaw owns the messaging plan and transaction. A package declares capability and applies native configuration.
SecretBroker	Brokered secret access without a reusable credential in the workload. NemoClaw selects logical bindings. OpenShell owns credential custody and rewrite.
Restriction	A rule that can narrow access but cannot grant access. A package can request access or add restrictions. It cannot remove an applicable restriction.

A package update affects a later deployment or rebuild. It cannot mutate a running deployment through a tag or package selector change.

OpenShell boundary

This design uses two OpenShell references:

• Supported baseline: NemoClaw commit ec84074a pins OpenShell 0.0.106. Implementation and support qualification must use the pinned release until NemoClaw changes the pin.
• Upstream direction on 2026-08-21: OpenShell v0.0.110 and commit 56c45a99 show later work. They do not define NemoClaw-supported behavior.

OpenShell has three authority layers relevant to this design:

Layer	Authority
Gateway	Sandbox lifecycle and state, policy, providers and credentials, inference configuration, sessions, and relay.
ComputeDriver	Platform provisioning and backend-state reporting.
Supervisor	Policy enforcement, credential and inference interception, the canonical agent child process, bounded sandbox operations, and security events.

The OpenShell roadmap affects future convergence:

Work	State on 2026-08-21	RFC effect
Drivers #1051 and driver lifecycle #2417	In progress	Packages remain compute-agnostic and use only behavior in the pinned release.
Credential drivers #1931	In progress	Packages declare logical provider requirements, not credential backends or secret values.
Managed maximum policy #2109	In progress	NemoClaw can require a product baseline. OpenShell owns effective policy and denial.
Public gRPC documentation #1613	In progress	NemoClaw keeps a narrow adapter around the supported OpenShell interface.
Stable public contracts #2565	Todo	NemoClaw versions its package contract independently.
Gateway desired-state push #1731	Todo	A package must not add another reconciler.
Kubernetes Operator #1719	Idea	A package must not encode a future operator or Kubernetes lifecycle.

OpenShell drivers, gateway interceptors, and supervisor middleware are enforcement extension points. They are not agent runtime packages.

Convergence rules

• The OpenShell gateway remains the lifecycle authority for every sandbox operation.
• NemoClaw initiates product workflows through one OpenShell client boundary.
• Packages cannot import, register, or select a RuntimeProviderBundle.
• NemoClaw can remove a runtime-provider facet only after the pinned OpenShell release provides equivalent behavior and passes supported E2E.
• OpenShell roadmap work changes this design only after a NemoClaw pin update, contract review, migration plan, and qualification receipt.

Design

flowchart LR
    SOURCE["First-party source in NemoClaw or external source"] --> RELEASE["Versioned package release"]
    RELEASE --> CATALOG["NemoClaw support catalog"]
    CATALOG --> CORE["NemoClaw workflow and plan compiler"]
    CORE --> CLIENT["NemoClaw OpenShell client"]
    CLIENT --> GATEWAY["OpenShell gateway"]
    GATEWAY --> DRIVER["ComputeDriver"]
    GATEWAY --> SUPERVISOR["OpenShell supervisor"]
    SUPERVISOR --> HELPER["Agent runtime helper"]
    HELPER --> RUNTIME["Agent runtime"]
    RECEIPT["Qualification receipt"] --> CATALOG

Loading

Each integration package contains four parts.

1. Agent runtime descriptor

The descriptor is declarative, versioned, and credential-free. It defines:

• Package, publisher, contract, source, and agent runtime identities.
• Exact sandbox images for supported platforms.
• Runtime commands, ports, dashboard, and health declarations.
• Supported inference API families and model capabilities.
• MCP and messaging capabilities.
• Agent-owned configuration and state paths.
• Backup, restore, rebuild, and upgrade declarations.
• Required baseline policy entries.
• The helper path and protocol version when the package uses a helper.
• Qualification requirements and receipt identity.

The descriptor cannot contain arbitrary host commands, an OpenShell endpoint, a compute-driver selector, or a credential backend.

2. Generic operation plans

NemoClaw compiles operator intent into these versioned, serializable plans:

• AgentRuntimeStartupPlanV1
• AgentRuntimePolicyPlanV1
• AgentRuntimeStatePlanV1
• AgentRuntimeCapabilityPlanV1
• AgentRuntimeOperationRequestV1
• AgentRuntimeOperationResultV1

Plans contain no credential values. NemoClaw validates product intent and sends sandbox operations through its OpenShell client. OpenShell validates and enforces each sandbox operation.

3. In-sandbox agent runtime helper

A managed sandbox image can provide one helper at a fixed path. The helper accepts versioned JSON requests through a supported OpenShell sandbox operation.

The first protocol supports:

• Native configuration application.
• Health, version, capability, and diagnostic inspection.
• Agent-native MCP inspection and configuration.
• Pre-rebuild inspection and post-restore reconciliation of declared agent-owned state.
• A bounded agent-native administrative action that does not duplicate sandbox or canonical process lifecycle.

Each operation is read-only or configuration-changing. NemoClaw rejects a request whose effect class does not match the operation.

The helper cannot:

• Create, start, stop, restart, or destroy a sandbox.
• Select a compute driver, provider, credential backend, OpenShell version, or support state.
• Change OpenShell provider or credential state.
• Widen effective policy.
• Supervise the canonical agent process.
• Call the OpenShell gateway.
• Return a host command for NemoClaw to execute.

NemoClaw records the request identity, result, and applicable product-state receipt. OpenShell policy limits the helper's filesystem, process, network, and provider access.

4. Support catalog and qualification receipt

The NemoClaw repository owns the support catalog. Each selected release pins:

• Package and contract identity.
• Agent runtime version.
• Image digest for each supported platform.
• Source revision and provenance identity.
• Supported OpenShell release and required capabilities.
• Accepted ComputeDriver and platform matrix.
• Qualification receipt digest.
• Support state.

Source publication does not add a release to the catalog. A package cannot select itself or change its support state.

Ownership

Responsibility	NemoClaw core	OpenShell	Integration package
CLI and product workflow	Owns	Exposes sandbox operations	Consumes bounded intent
Package registry, catalog, and qualification	Owns	Supplies platform capabilities and evidence	Supplies exact artifacts and agent-specific evidence
Sandbox lifecycle and state	Requests operations and records product linkage	Gateway owns	Does not own or bypass
Compute provisioning	Selects admitted product configuration	Gateway dispatches; ComputeDriver implements	Does not branch on compute runtime
Network and filesystem policy	Compiles product requirements	Owns effective policy and enforcement	Declares requirements; cannot widen
Providers and credentials	Selects logical bindings	Owns state, custody, refresh, and rewrite	Receives logical references or placeholders
Inference interception	Selects admitted product intent	Owns sandbox interception	Declares compatible APIs and model capabilities
Canonical agent process	Selects the package entry declaration	Supervisor owns execution	Owns the image and entry declaration
Native configuration	Provides a generic plan	Provides the enforced execution boundary	Owns bounded translation or helper behavior
Agent-native health, diagnostics, and MCP	Orchestrates and records	Transports and enforces operations	Owns native semantics
Product state and rollback decisions	Owns	Owns sandbox state and executes supported operations	Declares agent-owned state and reconciliation
E2E qualification	Owns the supported matrix	Owns driver and sandbox conformance	Owns agent-specific journeys and assertions

Trust rules

• NemoClaw does not load external integration code into its host process.
• A package, descriptor, plan, state record, log, or qualification artifact contains no upstream provider credential.
• OpenShell remains the source of truth for sandbox lifecycle, sandbox state, effective policy, providers, credentials, inference interception, and supervisor execution.
• A package cannot call OpenShell, a compute backend, or a credential backend directly.
• A package cannot widen effective policy or remove an applicable restriction.
• A package update affects only a later deployment or rebuild.
• A missing, invalid, incompatible, unqualified, or unverifiable package fails closed.
• NemoClaw does not select another package or agent runtime as an automatic fallback.
• A read-only helper operation cannot change configuration or lifecycle state.
• The helper cannot become another sandbox or process supervisor.
• NemoClaw records the package, image, plan, policy, OpenShell, driver, and receipt identities needed for resume and recovery.

Support and source placement

Repository location does not determine support.

State	Meaning
Supported	Maintainers accepted the ownership, lifecycle, compatibility, security, and validation contract. The exact package and image digests passed the accepted qualification matrix.
Candidate	The exact release is available only through the protected qualification authority. Qualification does not establish support.
Compatible	The package passes the public contract and conformance tests. Stock NemoClaw does not select it.

Supported and candidate releases have catalog entries. Compatible source does not become selectable because it exists or is published.

First-party integrations

First-party source stays in a package-owned area of the NemoClaw repository. NemoClaw maintainers own review, release, compatibility, security response, qualification, and lifecycle expectations.

A first-party package uses the public descriptor, schemas, helper protocol, catalog, and qualification contract. Core can depend on the public contract and registry. Core cannot import a package implementation path.

The NemoClaw release can publish core and a first-party package together.

First-party source placement is permanent. It is not a staging step for repository extraction.

External integrations

An external integration can implement the same contract from another NVIDIA-maintained or third-party repository. External source is not first-party source. Compatibility is not support.

For an external release:

1. The package repository builds exact images and qualification artifacts.
2. Package CI runs the public conformance suite.
3. NemoClaw runs the applicable live E2E matrix against the exact candidate.
4. A NemoClaw catalog change pins the accepted package, images, and receipt.
5. Each later release requires another catalog change and qualification evidence.

The external package owner maintains upstream compatibility, dependencies, patches, images, native configuration, and agent-specific tests. NemoClaw maintainers own the contract, catalog, OpenShell integration, product workflow, support decision, and qualification matrix.

Moving source between repositories changes first-party ownership. It does not preserve or change support automatically.

Architecture guardrails

• The package registry is the only package composition root.
• The registry selects a package. It does not own lifecycle state or effects.
• NemoClaw coordinates the product workflow. OpenShell owns sandbox lifecycle and state.
• All OpenShell calls pass through one core client boundary.
• OpenShell extension points are not agent package registries.
• RuntimeProviderBundle remains a core-only compatibility boundary.
• A package cannot add another onboarding, sandbox lifecycle, rebuild, recovery, or rollback state machine.
• A package cannot add an agent-name branch to core production code.
• Read-only and configuration-changing helper requests use separate operations. Helper requests do not perform sandbox lifecycle operations.
• Package-specific compatibility code names its current consumer and removal condition.
• Tests exercise production contracts. Test-only implementations cannot duplicate package behavior.

Each migration reports these measures before and after the change:

• Core agent-name conditionals and files.
• Core imports of agent-specific modules.
• Agent-named production files outside package ownership.
• Product-state and sandbox-state authority for each changed operation.
• Remaining runtime-provider facets and their OpenShell convergence status.
• Compatibility exceptions.
• Required E2E journeys.

A migration fails this RFC if it reduces a switch but adds another lifecycle authority, OpenShell call site, cross-feature import, or agent-specific core decision.

Migration

Phase 0: accept the design

The decision must name:

• The accountable NemoClaw maintainer.
• The first package owner and migration target.
• The contract, OpenShell, and security reviewers.
• The supported OpenShell baseline and required capabilities.
• The required E2E evidence.

Coordinate this work with source-boundary roadmap #7691. Onboarding authority roadmap #7700 does not define a public package SDK and does not authorize this work.

Inventory each RuntimeProviderBundle facet as retain, converge, or remove. Remove a facet only after supported OpenShell parity and E2E qualification.

Phase 1: add the contract and registry

Add schemas, parsers, the package registry, conformance fixtures, and one OpenShell client boundary. Register existing in-tree implementations without changing behavior.

Add architecture checks that:

• Reject new agent-name comparisons in core production code.
• Permit agent identifiers in package code, catalog data, tests, and recorded compatibility exceptions.
• Reject package imports of core implementation paths, OpenShell clients, compute clients, and RuntimeProviderBundle.
• Reject compute and OpenShell client imports of package implementation paths.
• Ratchet current conditional and agent-named-file counts downward.

Phase 2: migrate LangChain Deep Agents Code

Use LangChain Deep Agents Code as the first complete migration. Preserve commands, state, policy, image identity, OpenShell behavior, and E2E results. Remove its core name dispatch.

Phase 3: migrate Hermes

Use Hermes to verify gateway, dashboard, messaging, MCP, state reconciliation, recovery, and restrictive policy. The package must not add direct OpenShell calls or another supervisor.

Phase 4: require the contract for new runtimes

Pi and DeepSeek Harness must use the package contract before supported activation. They cannot add a core lifecycle, recovery, compute, OpenShell, or state authority.

Phase 5: support external source repositories

After Deep Agents Code and Hermes pass the contract, publish the conformance, provenance, version-negotiation, and catalog-admission interfaces needed by external packages.

First-party source remains in NemoClaw. This phase does not make an external package first party or supported.

Phase 6: migrate OpenClaw

Complete artifact co-location under issue #7698. Migrate the default runtime after two representative packages pass the contract. Remove AgentDefinition behavior that duplicates the accepted contract.

Phase 7: adopt a stable OpenShell client

When OpenShell releases an accepted public API or SDK under #2565, evaluate it against the core client boundary. Adoption requires a pin update, compatibility review, state-migration analysis, and complete supported E2E.

Replace only redundant compatibility code. Do not expose OpenShell internals through the package contract.

Validation

Contract validation

• Validate descriptors and plans against strict versioned schemas.
• Reject behavior-changing unknown fields, credential values, undeclared paths, endpoints, backend selectors, and driver selectors.
• Verify exact package, image, source, policy, OpenShell, driver, and receipt identities.
• Verify deterministic plan compilation.
• Verify that a package cannot select its provider, driver, support state, lifecycle authority, or policy authority.

Migration equivalence

Each migration compares the old and package-backed paths for:

• Startup intent and native configuration.
• NemoClaw product state and OpenShell sandbox state.
• Policy, provider, and inference effects.
• Status and diagnostic classification.
• Restart, recover, rebuild, snapshot, restore, and destroy behavior.
• Failure and rollback results.

Live E2E

The registry and OpenShell client changes affect every supported agent runtime. Their pull request must run the complete supported live E2E matrix from a same-repository NVIDIA-owned branch.

Qualification records the exact supported OpenShell release. Results from upstream main or an unpinned release are exploratory evidence.

The evidence has two layers:

1. OpenShell conformance verifies sandbox lifecycle, state, policy, credentials, inference, and supervisor behavior for the selected driver.
2. NemoClaw E2E verifies the product workflow and package behavior on that exact OpenShell and driver identity.

Each package runs the journeys that apply to its declared capabilities:

• Onboarding and connect.
• Managed inference and structured tool calls.
• Dashboard and messaging.
• MCP add, status, use, and remove.
• Agent process and sandbox restart and recovery through their respective owners.
• Rebuild, snapshot, restore, upgrade, and destroy.
• Credential non-disclosure.
• Denial of undeclared network, filesystem, host-control, OpenShell, and provider access.
• Verification of package, image, policy, OpenShell, driver, configuration, and qualification identities.
• Each supported platform and compute driver.

Schema and conformance tests do not replace live E2E evidence for support.

Completion criteria

The migration is complete when:

• A new first-party agent runtime changes no agent-specific core production code.
• First-party source remains in package-owned areas of the NemoClaw repository.
• An external package can implement the public contract without entering core or becoming first party.
• Core dispatches agent behavior only through the package registry.
• Package code does not import core implementation paths, OpenShell clients, or compute clients.
• NemoClaw has one OpenShell client boundary, and OpenShell remains the sandbox lifecycle authority.
• Architecture budgets decrease after each migration.
• One terminal runtime and one gateway runtime pass the same contract.
• Each supported release is pinned and qualified against an exact OpenShell and driver matrix.
• Package failure cannot select a fallback, widen policy, expose a credential, mutate another runtime's state, or create another sandbox authority.

Alternatives

Alternative	Reason for rejection
Extend the manifest only	A manifest can describe static behavior. It cannot express all native configuration and reconciliation without becoming an executable language.
Load host-side npm packages	External code would run in the process that owns product state, package selection, and OpenShell coordination.
Keep a central switch registry	Core would still change for every agent runtime. The registry would preserve agent-specific core ownership.
Use an OpenShell extension point	Drivers, interceptors, and middleware have infrastructure and enforcement contracts. They do not own agent metadata, native configuration, support, or qualification.
Put first-party integrations in separate repositories	Repository separation adds release and provenance coordination. First-party source ownership is clearer in NemoClaw. External packages can use separate repositories.

Open questions

• Is the release artifact an OCI artifact, package archive, or descriptor attached to each sandbox image?
• Which signing and provenance mechanism does the catalog require?
• Does the helper apply native configuration, or return a bounded file-mutation plan for a core applier?
• Which helper result fields become stable product-state receipts?
• How does a package contract major version interact with the NemoClaw release version?
• Which current agent-name comparisons remain as recorded compatibility boundaries?
• Which RuntimeProviderBundle facets remain NemoClaw-owned after OpenShell parity, and what removes each obsolete facet?
• Which OpenShell API subset must stabilize before NemoClaw removes its compatibility adapter?
• How do external repositories publish artifacts and conformance evidence?
• Can one external repository contain several related agent runtimes?
• Which team owns the public conformance suite, OpenShell compatibility policy, and cross-project qualification matrix?

Requested decision

Maintainers should record one decision:

• Accept: Approve the architecture. Name the accountable maintainer, first migration target, and validation plan.
• Request changes: Name the required contract, ownership, trust, or migration changes.
• Defer: Name the decision or dependency that must complete first.
• Decline: Keep the manifest-plus-core-dispatch architecture and state why it is preferable.

Acceptance selects an architecture direction. It does not activate a supported agent runtime, approve an external package, or move first-party source out of the NemoClaw repository.

[cv]

I like the direction of one integration package per agent runtime. Before implementing that architecture, I would make these refactorings:

1. Define the existing package identities. The root CLI and OpenClaw plugin both use the nemoclaw package name. Give each real package a unique name and mark it public or private.
2. Adopt npm workspaces for source packages. Use one repository-level install and local package linking. Keep separate lockfiles only where sandbox-image builds require an independent dependency graph.
3. Separate development setup from packaging. The root prepare script currently builds code, installs dependencies, links the CLI, and installs Git hooks. Packaging should be a deterministic build from a clean checkout.
4. Define the shipped package contents. The current root package contains thousands of compiled files, source maps, declarations, and scripts. Add an explicit content contract and test installation from the generated tarball.
5. Prove the structure with one existing boundary. First give the OpenClaw plugin a distinct package identity. Then migrate LangChain Deep Agents Code as the first agent runtime package.

I would keep onboarding, messaging providers, policy, state, and OpenShell coordination inside the main NemoClaw package for now. They are product modules, not independently released integrations.

This preparation would let the RFC focus on the important boundary: one independently qualifiable integration package per agent runtime. npm workspaces can organize those packages without requiring every workspace to be published through npm.

[ljefford2-cmyk]

Separately from the package-identity, workspace, and deterministic-packaging preparation identified by @cv, I see three trust-contract points that read as request-changes items rather than implementation details. They concern what an integration-package result is allowed to establish, how the RFC’s read-only invariant is enforced per operation, and how current support eligibility can be revoked without rewriting historical qualification evidence.

1. A helper result should not silently become established product state

Section 3 permits the in-sandbox helper to apply native configuration, mutate MCP registrations, and reconcile declared agent-owned state. NemoClaw then “records the request identity, result, and applicable product-state receipt.”

As written, a result produced by the component performing the mutation can become a product-state receipt without any observation produced by a component independent of that helper.

Where an independent observation path exists, the accepted postcondition should be produced by that independent observer. A digest, configuration projection, status response, or similar value computed by the mutating helper would remain the executor’s account of its own effect; routing that value through NemoClaw or OpenShell would not make the evidence independent.

Where the pinned OpenShell release provides no independent observation path for a particular native operation, that limitation should remain visible in the record rather than being resolved by treating the helper result as established state. The receipt should distinguish at least:

• an executor-claimed result;
• an independently observed postcondition;
• the identity of the evidence producer;
• any resulting limitation on what product state may be asserted.

This would allow the 0.0.106 baseline to proceed where necessary without silently representing an unverified execution claim as equivalent to verified product state.

The RFC already asks whether the helper should apply native configuration or return a bounded file-mutation plan for a core applier. I do not think that question can remain only under “Open questions.” The answer determines the available effect-verification path and the meaning of the resulting product-state receipt. The architecture decision should therefore resolve the receipt and evidence semantics even if some operations at the current baseline can produce only executor-claimed results.

2. The read-only invariant needs a per-operation enforcement or detection mechanism

The RFC states:

“A read-only helper operation cannot change configuration or lifecycle state.”

The mechanism currently described checks whether the operation’s declared effect class matches the requested action. That establishes consistency between the request and the declaration; it does not establish that the implementation behaved according to the declaration.

Moving effect classification into the contract or catalog would correctly establish who owns the classification, but it would still not prove that a package implementation classified as read-only did not write configuration, alter process state, or otherwise mutate the runtime.

The RFC should name the mechanism that prevents or detects such a violation and state the consequence when it occurs. General OpenShell sandbox policy does not appear sufficient by itself if read-only and configuration-changing helper operations execute in the same sandbox under the same filesystem, process, network, and provider grants. A mechanism satisfying the invariant must discriminate at the operation boundary—for example through a separately constrained execution path, operation-specific capabilities, or an independently produced before-and-after observation—and must fail closed when a purportedly read-only operation produces a mutation.

This is not an additional invariant being proposed from outside the RFC. It is a request for the RFC to identify how one of its existing invariants is made true.

3. The catalog’s support state needs a defined lifecycle

The support catalog already pins a support state, but the RFC does not define the lifecycle of that state. I do not see a specified transition model, revocation trigger, supersession rule, or consequence for deployments already running a release that later becomes ineligible.

The qualification receipt should remain immutable historical evidence that an exact package, image, OpenShell release, driver, and platform combination passed an accepted matrix. That historical fact may remain true even after a vulnerability, compromised artifact, provenance failure, qualification defect, or violation of an asserted package boundary is discovered.

Current eligibility therefore needs separate, revocable semantics. Those semantics could be represented through a separate support decision or through explicit catalog fields and transitions, but the RFC should define:

• who may revoke or supersede support;
• which events can trigger that transition;
• whether new selection, rebuild, restore, or recovery is denied;
• how already-running deployments are handled;
• how the historical qualification receipt remains preserved;
• how the replacement or corrected release becomes authoritative.

Revocation and supersession are not currently represented in the catalog schema or tracked in the open questions.

These three issues are connected. If an operation classified as read-only is later found to have mutated state, prior helper-produced results and product-state receipts from that package may become suspect. The architecture therefore needs both explicit evidence status—executor-claimed versus independently observed—and a defined way to revoke or supersede current eligibility while preserving the historical record.

The RFC specifies the ownership and authority boundaries with considerable precision. Verification of effects, per-operation enforcement of effect classes, and the lifecycle of current support eligibility need comparable precision before those boundaries can be relied upon.

[HOYALIM]

I really like this direction and agree with the refactoring roadmap suggested by @cv.

Breaking the preparation into small, low-risk steps seems like the cleanest way to set up the foundation before migrating runtime boundaries across core:

1. Package identities: Give the root CLI and OpenClaw plugin distinct names and visibility.
2. npm workspaces: Organize source packages under workspaces with unified local linking.
3. Packaging vs. dev setup: Decouple developer convenience tooling from clean, deterministic packaging builds.
4. Shipped tarball contract: Define the content boundary for published artifacts and add installation validation from .tgz.
5. Initial runtime proof: Use the established boundary to extract LangChain Deep Agents Code as the first standalone agent runtime package.

I’m going to start working on step 1 to get the package naming and workspace layout sorted out, and will open a PR for review shortly.