feat(openshell): route session reads over authenticated gRPC

[ericksoa]

Summary

Routes OpenClaw session-list reads through an authenticated direct gRPC client for the sandbox's named OpenShell gateway. The compatibility path retries through supported OpenShell CLI execution only when configuration or sandbox lookup fails before dispatch, so completed commands are never replayed.

This is PR 4 of 26 in the OpenShell gRPC migration stack.

Changes

• Resolve a named gateway's endpoint and auth mode from OpenShell user or system metadata, while loading mTLS and OIDC credentials only from the user's gateway directory.
• Construct authenticated direct-gRPC clients for plaintext loopback, mTLS, and OIDC gateways, and fail closed for edge-tunneled or unknown auth modes.
• Route OpenClaw session listing through direct gRPC with a bounded deadline; retry through the CLI only for read-only configuration or sandbox-lookup failures that occur before command dispatch.
• Distinguish pre-dispatch lookup failures from completed nonzero commands and post-dispatch stream failures so the fallback cannot replay a command with an unknown outcome.
• Cover credential resolution and routing in grpc-gateway-config.test.ts, grpc-sandbox-control.test.ts, sandbox-control-routing.test.ts, and passthrough.test.ts; a direct unconditional switch is insufficient because named gateways can require different auth material and staged compatibility is safe only before dispatch.

Stack

• Stack index: refactor(openshell): establish sandbox control boundary #6790
• Depends on: test(openshell): cover IPv6 loopback gRPC endpoint #6828
• Follow-up docs: docs(openshell): document direct session transport #6794
• Review this PR against base branch feat/openshell-grpc-client/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: the command-reference update is isolated in the immediate stacked docs-only follow-up docs(openshell): document direct session transport #6794; this implementation slice updates its inline CLI help together with the behavior.
• 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 review completed; only configuration and lookup failures before a read-only dispatch are eligible for CLI retry, while completed commands and post-dispatch failures are never replayed.
• 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 — the four focused gateway-config, gRPC-control, routing, and session-passthrough test files passed (60 tests); npm run typecheck:cli passed
• 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)
• 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: 449faa56-5875-433e-ae1f-1c57480469e4

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-gateway-auth/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 feat/openshell-grpc-... branch.

TypeScript / code-coverage/cli

The overall coverage in the feat/openshell-grpc-... branch is 79%. The coverage in the feat/openshell-grpc-... branch is 80%.

Show a code coverage summary of the most impacted files.

File	feat/openshell-grpc-... 3c4ea5a	feat/openshell-grpc-... c0ea436	+/-
src/lib/inference/local.ts	82%	71%	-11%
src/lib/shields/index.ts	72%	62%	-10%
src/lib/inference/vllm.ts	87%	77%	-10%
src/lib/sandbox/config.ts	73%	66%	-7%
src/lib/state/o...oard-session.ts	90%	85%	-5%
src/lib/policy/index.ts	58%	65%	+7%
src/lib/actions...ateway-state.ts	65%	75%	+10%
src/lib/tunnel/services.ts	73%	85%	+12%
src/lib/adapter...teway-config.ts	0%	90%	+90%
src/lib/adapter...dbox-control.ts	0%	98%	+98%

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of 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

2 optional E2E recommendations

• sessions-agents-cli
• openshell-gateway-auth-contract

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Document the compatibility fallback's source boundary and removal condition

• Location: src/lib/adapters/openshell/sandbox-control-routing.ts:31
• Category: architecture
• Problem: The new CLI compatibility retry documents which pre-dispatch failures it handles, but does not state why gateway configuration/lookup failures cannot be repaired at their source in this change or what condition will allow the fallback to be removed.
• Impact: Without an explicit source boundary and exit condition, this workaround can become a permanent alternate transport path and obscure whether direct gateway configuration support has converged.
• Recommendation: Add a concise source-of-truth note identifying the unsupported/pre-dispatch state, why it remains necessary here, and the concrete upstream capability or migration condition that permits removing the CLI retry.
• Verification: Read the routing docblock at sandbox-control-routing.ts:31-35 and the resolver's unsupported-auth branches in grpc-gateway-config.ts to confirm the fallback's stated scope and removal trigger.
• Test coverage: Existing sandbox-control-routing.test.ts covers fallback behavior; add or retain a contract-level assertion/documented test case tying fallback to the explicitly named unsupported configuration boundary when that boundary is changed.
• Evidence: sandbox-control-routing.ts:31-35 defines a CLI retry for direct-client configuration and pre-dispatch lookup failure. sandbox-control-routing.test.ts tests configuration failure and explicit pre-dispatch retry branches. The routing documentation does not identify a source-side limitation or a removal condition.

Workflow run details

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

[apurvvkumaria]

Blocking correctness/security findings on exact head 8fd2064:

1. execSandboxReadOnlyWithGrpcFallback wraps both client construction and await grpc.exec(...) in the same broad catch. A rejected execution promise is therefore labeled a configuration failure and replayed through the CLI, even though the outcome may be post-dispatch. This contradicts the PR's no-replay contract. Only an explicit OpenShellGrpcPreDispatchError should be eligible for fallback; an untyped rejection must be returned as the execution failure, with coverage for both rejected post-dispatch and rejected typed pre-dispatch cases.

2. The fallback control is a process-global, unscoped CLI client. When the sandbox is bound to a named gateway but a different gateway is active, a configuration/lookup fallback can execute against the active gateway instead of gatewayName—and a same-named sandbox can return another gateway's session data. Construct the CLI fallback for the requested gateway (and reject ambient endpoint overrides that can bypass that binding), and test the exact --gateway <name> invocation.

3. When the local registry row is absent, resolveSandboxGatewayName(undefined) silently chooses the default gateway even though ensureLiveSandboxOrExit may just have validated the sandbox on another active gateway. Preserve the legacy active-gateway CLI capture path for unregistered sandboxes, or fail before direct dispatch; do not direct gRPC to a guessed gateway.

I can address these with a narrow append-only maintainer commit while preserving the original author's credit.

[apurvvkumaria]

Verified on exact head 55e7d3f: post-dispatch rejections fail closed without CLI replay; typed pre-dispatch failures use a gateway-scoped fallback that rejects endpoint overrides; unregistered sandboxes preserve the active-gateway compatibility path. Focused tests, CLI type-checking, structural guards, formatting, commit hooks, DCO, and GitHub signature verification passed. CI and advisors are now running on this head.