feat(openshell): document sessions and carry stdin over gRPC

[ericksoa]

Summary

Documents OpenClaw session listing's direct gRPC path and adds stdin transport so later migration slices can stream scripts and archives without SSH. The read-only session consumer retains CLI retry only before dispatch, while stdin preserves the existing request-size and timeout bounds.

This is PR 3 of 21 in the OpenShell gRPC migration stack.

Changes

• Update the existing nemoclaw <name> sessions reference to describe authenticated direct gRPC, the read-only pre-dispatch CLI retry, and the no-replay boundary.
• Encode string and binary stdin in direct sandbox exec requests.
• Preserve request-size bounds and timeout behavior for stdin-bearing requests.
• Cover empty, text, and binary stdin payloads while preserving the existing session examples and warm-up-session filtering documentation.
• Verify binary stdin crosses the runtime capture wrapper unchanged.

Stack

• Stack index: refactor(openshell): establish sandbox control boundary #6790
• Depends on: feat(openshell): route session reads over pinned gRPC #6791
• Review this PR against base branch chore/openshell-grpc-protocol/ae to see only this slice.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: transport-boundary self-review completed; session reads retry only before dispatch, stdin is carried once over the selected transport, and existing request-size and timeout bounds remain enforced.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — gRPC stdin, runtime-capture, and request-boundary tests passed; npm run docs passed with 0 errors
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — targeted and changed-graph validation were used; required CI supplies the broad repository gates
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — the strict docs build passed with 0 errors and no unsuppressed warnings; Fern reported 2 configured suppressed warnings
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d49fa594-f72b-4e1e-bb48-b5352d72ac4e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openshell-grpc-stdin/ae

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the chore/openshell-grpc... branch.

TypeScript / code-coverage/cli

The overall coverage in the feat/openshell-grpc-... branch remains at 79%, unchanged from the chore/openshell-grpc... branch.

Show a code coverage summary of the most impacted files.

File	chore/openshell-grpc... 33d55b0	feat/openshell-grpc-... c6975ba	+/-
src/lib/adapter.../docker/pull.ts	83%	79%	-4%
src/lib/onboard...er-gpu-patch.ts	91%	88%	-3%
src/lib/runner.ts	72%	75%	+3%
src/lib/onboard...shboard-port.ts	89%	94%	+5%
src/lib/policy/tiers.ts	80%	94%	+14%
src/lib/adapter...ocker/volume.ts	70%	85%	+15%
src/lib/adapter...teway-config.ts	0%	90%	+90%
src/lib/adapter...trol-routing.ts	0%	92%	+92%
src/lib/adapter...dbox-control.ts	0%	98%	+98%
src/lib/adapter...dbox-control.ts	0%	100%	+100%

---

_{Updated July 14, 2026 13:23 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: PR review advisor failed: PR review advisor SDK execution failed: session: 429 status code (no body); turn: tests-regressions: 429 status code (no body)

Model lanes

• GPT-5.6 Terra (primary): Failed
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: onboard-repair, onboard-resume

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Reviewed exact head c6975ba against stacked base b348231. The transport-neutral stdin and output boundary validates command arguments, protobuf request size, uint32 timeout representation, and output limits before dispatch; direct gRPC preserves binary stdin, binds one end-to-end deadline, caps combined raw output before UTF-8 decoding, and only classifies sandbox lookup errors as pre-dispatch. The read-only sessions router falls back through the same named gateway only for configuration/lookup failures and never replays a completed or potentially dispatched command. The CLI fallback rejects ambient endpoint overrides, preserves binary stdin, and normalizes bounded raw output consistently. Endpoint/TLS/bearer validation remains fail closed. All 52 commits are Verified and DCO-signed; exact-head CI, CodeQL, automated advisors, and E2E PR Gate are green with no unresolved threads or linked issue. No blocking finding.

[ericksoa]

Closing as superseded: NemoClaw will consume the upstream OpenShell TypeScript SDK from NVIDIA/OpenShell#2122 instead of maintaining this raw gRPC/proto transport stack.