NVIDIA / NVIDIA/NemoClaw

Decide and qualify Hermes ACP transport over OpenShell

Open
#10,947 2 comments 0 reactions 1 assignee Claimed by @apurvvkumaria View on GitHub
needs: design
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Outcome

Decide whether NemoClaw will support a packaged Agent Client Protocol (ACP) launch path for Hermes over OpenShell. If maintainers accept the product surface, implement and qualify the complete transport contract.

Opening this task does not establish product support. Maintainers must first record ownership, lifecycle, compatibility, security, and validation expectations.

## Current state

- The managed Hermes image installs the `hermes-acp` executable.
- A reported integration required a host-side adapter because its sandbox command path did not provide the required duplex ACP stream.
- OpenShell issues NVIDIA/OpenShell#1330 and NVIDIA/OpenShell#2228 delivered bidirectional interactive and non-TTY execution behavior.
- NemoClaw #9804 owns the typed OpenShell exec, interactive-session, and SSH boundaries.
- NemoClaw has no public issue that owns a packaged Hermes ACP launch command and its end-to-end qualification.

## Product decisions required before implementation

- Name the supported user or service that consumes the ACP stream.
- Decide whether NemoClaw owns the host-side adapter, its command name, and its distribution.
- Select the authoritative OpenShell transport: bidirectional non-TTY execution, SSH, or another accepted interface.
- Define supported OpenShell and Hermes version ranges.
- Define supported host platforms and container runtimes.
- Define sandbox selection, OpenShell gateway selection, cancellation, restart, rebuild, and cleanup behavior.
- Define credential custody and prove whether the adapter needs any credential access.
- Define the compatibility and release evidence required before documentation can call the path supported.

If maintainers reject this product surface, record the owning external boundary and close this issue without adding a NemoClaw command or support claim.

## Required behavior if accepted

- Package one versioned NemoClaw adapter that launches the managed `hermes-acp` executable in the selected sandbox.
- Preserve duplex standard input and output, standard error, exit status, cancellation, signals, and backpressure.
- Use the selected OpenShell gateway and sandbox identity for every operation.
- Verify the exact NemoClaw, OpenShell, Hermes, ACP library, and adapter versions before the session starts.
- Reject a missing, ambiguous, stopped, or incompatible sandbox before launching the ACP process.
- Do not construct a shell command from unvalidated sandbox names, gateway endpoints, environment values, or ACP messages.
- Do not expose provider credentials, OpenShell credentials, authorization headers, or sandbox-private environment values.
- Terminate the remote process and host adapter after disconnect, cancellation, or transport failure.
- Preserve the same behavior after a supported gateway restart and sandbox rebuild.

## Acceptance criteria

### Product decision

- [ ] A maintainer records whether this is a supported NemoClaw product surface.
- [ ] The decision names the consumer, behavior owner, implementation owner, release owner, and test owner.
- [ ] The decision names supported platforms, OpenShell versions, Hermes versions, and lifecycle boundaries.
- [ ] The decision defines credential location, access, lifetime, transfer, and removal.
- [ ] The decision identifies the authoritative transport and explains why it satisfies duplex ACP.

### Delivery if accepted

- [ ] One packaged adapter launches the managed `hermes-acp` executable without requiring manual environment repair.
- [ ] A complete duplex ACP exchange succeeds through the selected OpenShell gateway and sandbox.
- [ ] Remote nonzero exit, connection loss, cancellation, timeout, and incompatible-version failures remain distinguishable.
- [ ] A failed launch leaves no remote ACP process, host adapter process, port forward, or temporary credential material.
- [ ] Input validation rejects shell metacharacters, ambiguous sandbox identity, non-loopback local control endpoints, and unsupported transport settings.
- [ ] Logs and artifacts contain no credential, authorization header, private environment value, or ACP payload content beyond the approved diagnostic fields.
- [ ] Deterministic tests cover command construction, input validation, environment selection, status propagation, cancellation, and cleanup.
- [ ] Live end-to-end evidence covers one complete ACP exchange, cancellation, OpenShell gateway restart, and sandbox rebuild.
- [ ] #9804 provides or exposes the typed execution boundary used by the adapter.
- [ ] Public documentation is added only after the exact candidate revision passes the accepted qualification matrix.

## Non-goals

- Modify OpenShell in this issue.
- Add another ACP implementation to the Hermes image.
- Use buffered execution for a duplex protocol.
- Forward host credentials into the sandbox.
- Document an unqualified compatibility path as supported.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.