[jyaunches]

Current v1 port

The current head ports the operator-managed R0/2 handoff to v1's explicit integration selection and native identity contracts. The integration kind is voiceclawR0, separate from the managed voiceclaw installer in #12160. Apply selects one attached OpenClaw agent and resolves its sandbox by name; Unix bootstrap credentials use descriptor 3. Windows rejects this bootstrap before launch.

Independent review found and fixed credential expiry during target revalidation and dispatch using a sandbox name instead of its native agent name. Both defects have failing-then-passing regression tests. Local validation passes: 609 workspace tests (94 opt-in ignored), formatting, workspace clippy, generated schema, and Fern documentation checks. Hosted CI is running. Draft status is unchanged.

The Brev results below are retained historical evidence from before this port; the current head has not repeated native VoiceClaw qualification. See the experimental CLI contract for prerequisites, retained-agent recovery, and unmanaged process lifetime.

---

Outcome

NemoClaw now implements the complete nemoclaw-voice-r0/2 boundary: after VoiceClaw establishes the scoped connection, an independent client can submit the one allowed question through VoiceClaw and trigger one native dispatch to the already-running sandboxed OpenClaw agent. Only a validated answer containing one ASCII 4, surrounded at most by Unicode whitespace or punctuation, is returned.

Brev R0 validation

Focused ARM64 Brev validation completed the R0 path. The independent client reached the sandboxed OpenClaw agent through VoiceClaw and NemoClaw. OpenRouter returned HTTP 200, and the client received exactly 4.

The run also verified duplicate-probe rejection, authenticated close, completed cleanup, and agent preservation. See the full redacted process, configuration, and evidence.

The pinned VoiceClaw runner has a cleanup-observation race. Post-run inspection confirmed zero run directories and processes, so this does not indicate a NemoClaw response or product-cleanup defect.

Reason

Revision 1 proved connection readiness but did not prove that the agent inside the sandbox was reachable. Revision 2 adds the smallest end-to-end semantic operation needed for R0 while keeping arbitrary prompts, multiple turns, correlation, receipts, replay, and speech or detail results deferred to R1a.

Related issues

Part of #11746

Refs #11747, #11749, #11750, #11751, #11752, #11753

Changes

• Serve the agreed loopback-only connection and /r0/probe endpoints with short-lived scoped access.
• Authenticate before parsing, require the exact profile, target, media type, and fixed question, and bound request and response bodies to 4096 bytes.
• Revalidate agent readiness immediately before dispatch and atomically reserve the single probe before native work starts.
• Dispatch the exact question through the existing OpenShell binding to the configured sandboxed OpenClaw agent; do not start a second runtime or expose native credentials, IDs, or frames.
• Bound dispatch to 60 seconds and credential or stream lifetime, preserve dispatched work across HTTP cancellation, and normalize replacement, unavailability, connection loss, and invalid responses to the agreed public errors.
• Validate and apply VoiceClaw configuration after agent readiness, invoke the operator-approved onboarding ABI, pass the credential through inherited file descriptor 3, protect the exchange directory, and preserve the healthy agent on VoiceClaw failure.

Verification

• python3 -m unittest discover -s . -p 'test*fixture.py' -v from the revision 2 fixture directory — passed 3 tests covering all 17 connection cases and all 17 probe cases.
• cargo test --offline -p nemoclaw-sdk --test voiceclaw_r0_server --test voiceclaw_r0_onboarding --test voiceclaw_r0_fixture — passed 22 tests: 15 semantic-server, 4 onboarding, and 3 fixture tests.
• cargo fmt --all -- --check — passed with Rust 1.98.1.
• cargo clippy --offline --workspace --all-targets --all-features -- -D warnings — passed with pinned protoc 36.1.
• cargo test --offline --workspace — passed; opt-in live and verified-bundle tests remained ignored by their declared contracts.
• Diff inspection — no secrets, API keys, or credentials.

Review notes

The maintainer accepted the revision 2 lifecycle contract and shared fixture bundle in #11747. PR #11814 owns those fixtures, and #11833 owns the separate Python 3.10 Fabric prerequisite. Until #11814 merges, its fixture commit also appears in this diff because both PRs target v1. This draft awaits independent review.

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[jyaunches]

CI disposition for v1 at cce800fa9d5dd4910e76a162018b29911cbcbfe8: the failing codebase-growth-guardrails and package-openshell-sdk jobs stop because this base lacks .github/actions/setup-reviewed-npm/action.yml. Where scheduled, check-pr-limit stops because this base lacks .github/pr-limits.json. These jobs do not reach the PR diff. Candidate-focused validation is recorded in the PR body; no candidate-owned CI failure was observed.

[cv]

@jyaunches, this needs an architecture revision before we merge it. The successful fixed-question exchange is useful experimental evidence, but the implementation couples the VoiceClaw connection to the lifetime of nemoclaw apply.

In Deployment::apply, the SDK starts VoiceServer, performs onboarding, and then waits in server.wait_for_run(...) until the connection ends. The operation returns an integration result of disconnected. That makes the deployment command part of the ongoing conversation path. Moving this server into an untracked background task would preserve the same ownership problem.

The required behavior is: apply establishes the deployment, verifies readiness, and returns. A separate client must then be able to connect through VoiceClaw to the already-running agent without another NemoClaw command.

1. Give every running component an explicit owner

Please revise the design around these responsibilities:

Component	Responsibility
NemoClaw SDK, consumed by the CLI and OpenTofu provider	Reconcile declared service resources, network access, credential references, and the authorized agent binding; perform bounded readiness checks and return.
Docker or another explicitly selected service supervisor	Run VoiceClaw independently of the provisioning process, with an explicit restart policy and observable identity.
VoiceClaw	Supply its package and startup behavior; own internal settings, client authentication, audio/transcription/playback, and client connection behavior.
Fabric	Own the agent runtime and its adapter.
OpenShell	Own sandbox isolation, protected sandbox access, and inference routing.
Native agent	Own conversation execution, tools, and native session state.

VoiceClaw supplying its installation/startup implementation is compatible with NemoClaw managing a declared VoiceClaw service. We need to specify that service's creation, readiness, observation, restart, and deletion behavior instead of starting processes and reporting their lifecycle as not-managed.

For the intended integrated deployment, use a pinned VoiceClaw artifact and a supervisor-owned service outside the agent sandbox. Configuration acquisition can be a separate explicit setup operation; ordinary reconciliation must not depend on an interactive onboarding session. Preserve secrets through protected storage and references rather than putting values into YAML, arguments, logs, exported configuration, or provider state.

The proposed steady-state path is:

client <-> VoiceClaw service <-> protected agent access <-> existing agent gateway
                                                           inside OpenShell
                                                           owned by Fabric

apply configures these resources and exits. It is not a hop in that path. Reusing a sandbox must not start a second Fabric runtime or another agent gateway for VoiceClaw.

2. Reuse existing agent interfaces; identify the actual access gap

The existing Fabric/OpenClaw adapter already owns a persistent native gateway. OpenShell service forwarding already gives us an example of access whose lifetime is independent of apply; see docs/interfaces.md.

OpenClaw exposes native WebSocket operations and an OpenResponses-compatible HTTP API. Please evaluate those existing interfaces against the pinned image and VoiceClaw's actual needs: ordinary text submission, streamed output, session continuity, and interruption. Use an existing protocol and client implementation where they meet those needs. Do not introduce a VoiceClaw-specific agent protocol merely to implement the demonstration.

There is a real authorization question to resolve. The requirement that VoiceClaw receives neither OpenClaw nor OpenShell credentials must remain explicit. Upstream OpenClaw documents shared-secret HTTP access as full operator access, so handing VoiceClaw the dashboard token is not a substitute for agent-scoped authorization:

• OpenClaw gateway protocol
• OpenClaw OpenResponses API and authorization

Those upstream interfaces are candidates, not evidence that the pinned composition already meets our requirements. Likewise, Fabric's runtime/adapter APIs do not by themselves establish a remotely attachable, appropriately authorized service.

First determine whether existing gateway authorization and OpenShell access can enforce the required restriction. If they cannot, describe the exact missing capability. Prefer adding that capability to an appropriate existing runtime component. If a separate access component is necessary, make it a declared, supervised service with a lifecycle independent of the CLI. Its responsibilities should be limited to authenticating VoiceClaw, enforcing the permitted agent binding, retaining native credentials, and adapting the selected existing request/streaming interface.

That component must not own voice-specific admission windows, speech formatting, or a hard-coded question/answer policy. Simply moving the current R0 server into a daemon would not resolve the unnecessary protocol and policy surface.

3. Define lifecycle behavior in user terms

Please make these behaviors explicit in the revised design and tests:

• Successful apply returns while the agent and VoiceClaw service remain available. Repeating unchanged apply preserves their identities and does not start another client run.
• A VoiceClaw setup or startup failure preserves the healthy agent and reports a concrete recovery action. Retry reuses the established deployment.
• Client disconnect and reconnect do not require another apply, repeated onboarding, or a manually issued per-run credential.
• Credential lifetime and renewal are handled by the deployed authorization mechanism. They must not depend on the provisioning process remaining alive. Revocation and agent replacement invalidate the old authority.
• Reconnecting transport does not authorize replaying an uncertain agent request. Define session continuation and interruption separately from reconnection, and preserve the existing no-blind-redispatch rule.
• Restarting VoiceClaw does not replace the agent. Readiness must distinguish a reachable VoiceClaw process from working authorized access to the agent.
• Destroy removes only owned integration resources and revokes their access, with explicit treatment of retained configuration and conversation data. The CLI and provider must share the same SDK lifecycle semantics.

These service and access capabilities are proposed implementation work, not claims that current v1 already supports them.

4. Put the demonstration in the integration test

The fixed question, the regular expression accepting only 4, and the one-probe-per-run rule belong to the experiment, not to SDK runtime behavior. The product interface should accept ordinary conversation input. A test can use a simple arithmetic question without the deployed implementation knowing the question or expected answer.

The first acceptance test should be structured so that the architecture in this PR cannot pass it:

1. Apply an owned deployment and assert that the apply process exits successfully within a bounded time.
2. After it exits, start a separate client and connect through VoiceClaw's actual interface.
3. Send ordinary text and receive a real response from the existing sandboxed agent, then complete a second turn.
4. Disconnect and reconnect without invoking NemoClaw or repeating onboarding; verify the documented session behavior.
5. Restart VoiceClaw through its supervisor and verify that the agent identity is unchanged and access can be re-established.
6. Verify rejection of unauthorized access and attempts to select another agent. Exercise replacement/revocation and an uncertain request outcome without blind redispatch.
7. Run unchanged apply and owned cleanup, verifying identities, retained data, and resource ownership.

Use focused deterministic tests for authorization and failure behavior, and an explicitly configured live test for the real composed path. Do not replace one narrow demo with a second large mock implementation of the product.

5. Rework the PR descriptions and dependencies around the revised result

Please keep #11822 and #11814 unmerged while the ownership and access design is revised. #11814's current fixtures describe the temporary R0 protocol; they should follow the selected interface rather than make that protocol a permanent requirement. A checksum proves that the fixture file has not changed, not that the deployed implementation conforms to it. Any retained shared corpus should exercise the actual implementation at its boundary.

The current descriptions obscure the consequential choices behind terms such as “semantic boundary” and “complete lifecycle.” The revision should lead with the user-visible behavior, identify which process serves requests after apply exits, state what is reused and what must be added, and distinguish experimental evidence from supported behavior. Preserve the old R0 results as historical evidence rather than presenting them as qualification of a revised architecture.

#11833 has also been closed as superseded by Docker Bake consolidation in 6141179. Rebase on current v1, drop that prerequisite, and requalify the eventual composition with the current image build. Its old Python 3.10 extraction helper should not be restored.

Please start with a concise architecture revision answering who owns the VoiceClaw service, where scoped agent access is enforced, which existing interface is used, and how both survive apply exiting. Then implement the smallest missing capability against the acceptance test above.

[cv]

@jyaunches The application integration definition/reference mechanism is now on v1 (implementation ec3a030020, authoring guide). Please rebase this PR onto it and add VoiceClaw through that mechanism. The lifecycle and service-boundary changes in the earlier review still apply.

Definitions and attachments are separate. A definition in spec.integrations is available throughout the deployment; a definition in spec.sandboxes[].integrations is available within that sandbox. Neither attaches automatically. Each consuming agent selects names with integrationRefs:

spec:
  integrations:
    search:
      kind: webSearch
      provider: brave
      credential:
        env: BRAVE_API_KEY
  sandboxes:
    - name: assistant
      agents:
        - name: researcher
          harness: openclaw
          integrationRefs: [search]
        - name: writer
          harness: openclaw
          integrationRefs: [search]

For one consumer, the same definition can be inline and attaches directly to that agent:

spec:
  sandboxes:
    - name: assistant
      agents:
        - name: researcher
          harness: openclaw
          integrations:
            search:
              kind: webSearch
              provider: brave
              credential:
                env: BRAVE_API_KEY

These are fragments; examples/openclaw-web-search.yaml contains a complete document. All three definition locations use the same typed Integration enum. Agent-inline definitions belong to their agent and cannot be referenced by siblings. References resolve only from enclosing deployment/sandbox definitions. Missing or duplicate references, duplicate YAML keys, and shadowing of enclosing names are rejected. There is no override or merge precedence; YAML anchors, aliases, and merges remain disabled. Unused enclosing definitions create no resources, grants, or credential requirements. Export preserves the authored scopes and references.

For the VoiceClaw revision:

1. Add a typed variant to Integration in crates/nemoclaw-sdk/src/config/integrations.rs, with the actual supported settings and validation. voiceclaw is deliberately not accepted yet. Do not introduce a parallel deployment-wide switch, an integration-owned agentRefs list, or a nemoclaw apply --voiceclaw path.
2. Use Sandbox::integration_bindings(&document.spec.integrations) to resolve definitions and their explicitly attached agents. Bindings carry the definition name, its inline owner when present, the typed definition, and selected agent names. Build service identity and access grants from those attachments; merely declaring a shared definition must not enable every agent.
3. Implement the service as an independently supervised runtime with desired-state lifecycle, readiness, observation, recovery, and teardown. apply reconciles it and returns; it must not own a long-running HTTP server. Dispatch through the existing agent runtime/Fabric path, with the scoped authorization boundary described in the earlier review. Keep fixed arithmetic probes and response filtering in test fixtures rather than the product protocol.
4. Keep the service lifecycle and access grants explicit when one definition is reused. Attaching another agent must not silently create a duplicate shared service or broaden unrelated agents' access. Define and test how inline instances are identified separately.
5. Cover shared, sandbox-local, and agent-inline forms; missing/colliding references and denied agents; service survival after apply exits; restart/recovery; unchanged apply; export/reapply; drift and teardown. Demonstrate ordinary agent requests through VoiceClaw, not only endpoint connectivity or an exact fixed question.

The current Brave implementation still supports one attached search definition per sandbox, which multiple agents may reference; distinct definitions are not silently deduplicated by equal settings. That is a Brave runtime constraint, not a global one-integration limit. The schema currently supports one sandbox; this change does not claim multi-sandbox support.

Validation for this mechanism: workspace tests, formatting, Clippy, generated schema/reference and documentation checks; the SDK/CLI/provider lifecycle fixture exercises all three forms against a local OpenShell fixture. This qualifies reference resolution and retained-state behavior, not a live VoiceClaw service or live Brave credentials.

[cv]

Independent code and documentation review completed on the v1 port. Fixed two reproduced review findings: grant expiry during target revalidation and native dispatch using a sandbox name instead of the configured agent identity. The port also preserves explicit integration selection, named sandbox lookup, persisted deployment recovery, and current OpenTofu readiness. Unix credential-descriptor support is enforced before bootstrap launch. Local validation: 609 workspace tests passed (94 opt-in ignored), fmt, workspace clippy, schema, and Fern docs passed. No remaining code findings. This review covers the implementation and fixtures; historical native VoiceClaw evidence has not been repeated on this head. Hosted CI is running and draft status is unchanged.

[github-actions]

v1 documentation preview: https://nvidia-preview-nemoclaw-v1-pr-11822.docs.buildwithfern.com/nemoclaw

[cv]

Reviewed the follow-up portability fix: the metadata binding now shares the Unix-only scope of the device/inode comparison, removing the Windows clippy failure while preserving the Unix identity check. Four onboarding tests, formatting, and all-target workspace clippy pass. Prior full review remains applicable; hosted CI is rerunning on this head. Draft status is unchanged.

[cv]

Reviewed the integration with current v1, including the hosted lifecycle test conflict resolution and the shared CLI signal-registration fix. The Hermes/OpenClaw lifecycle assertions remain intact; five result assertions now explicitly expect no VoiceClaw integrations. Tavily bindings, readiness, and non-interactive CLI behavior are preserved. Independent review found no remaining issue.

Validation on this head: formatting, workspace/all-target clippy, and 625 workspace tests passed (95 explicitly opt-in tests ignored). Schema and documentation checks passed before the CLI-only base update. Hosted checks are running. Existing draft status and live VoiceClaw qualification limits remain unchanged.

[cv]

Reviewed the final merge of the shared six-line snapshot fixture synchronization fix. Production, VoiceClaw behavior, and documented qualification limits remain unchanged. Formatting and the focused cancellation regression pass after integration; prior full workspace clippy and all 625 tests passed, along with schema/docs checks. Independent review confirms no assertions were weakened. No remaining review findings; hosted checks are running.