Summary

• Problem: @openclaw/sdk exposed oc.environments.*, but list and status still failed as unsupported and Gateway advertised no environment discovery RPCs.
• Why it matters: app clients need a read-only way to discover Gateway-local and node environment candidates before create/delete/provisioning semantics are ready.
• What changed: added typed environments.list and environments.status Gateway RPCs, SDK call-through/types, operator.read scope classification, protocol schemas/generated Swift models, docs, changelog, and focused tests.
• What did NOT change (scope boundary): oc.environments.create/delete remain unsupported, and per-run runtime/environment options still fail before submission.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Gateway RPC: add SDK-facing environment discovery APIs #74708
• Related https://github.com/OpenCoven/open-meow-sdk/blob/main/docs/rpc-contract-proposals.md#environmentsliststatus
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A. This is the first additive read-only environment discovery contract for the SDK/Gateway surface.

Regression Test Plan (if applicable)

N/A.

User-visible / Behavior Changes

oc.environments.list() and oc.environments.status(environmentId) now return read-only environment summaries with id, type, status, and optional label / capabilities. oc.environments.create/delete remain unsupported.

Diagram (if applicable)

Before:
[app client] -> [@openclaw/sdk oc.environments.list/status] -> [unsupported error]

After:
[app client] -> [@openclaw/sdk oc.environments.list/status] -> [Gateway environments.* RPC] -> [environment summaries]

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) Yes
• If any Yes, explain risk + mitigation: the new RPCs require operator.read and expose only environment candidate metadata derived from Gateway-local state and existing node discovery surfaces. They do not create environments, run commands, expose secrets, or change auth behavior.

Repro + Verification

Environment

• OS: Ubuntu/Linux
• Runtime/container: Node 22+/pnpm dev checkout
• Model/provider: N/A
• Integration/channel (if any): Gateway WebSocket RPC / @openclaw/sdk
• Relevant config (redacted): N/A

Steps

1. On current main, call oc.environments.list() or oc.environments.status("gateway").
2. Observe the SDK unsupported error.
3. Apply this PR.
4. Call the same SDK methods against Gateway.

Expected

• SDK environment discovery methods route to Gateway and return typed read-only environment summaries.

Actual

• Before this PR, SDK environment discovery methods throw unsupported errors.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Verification run locally after rebase onto openclaw/main:

• pnpm protocol:check
• pnpm test src/gateway/server-methods/environments.test.ts src/gateway/method-scopes.test.ts packages/sdk/src/index.test.ts src/gateway/protocol/index.test.ts -- --reporter=verbose
• pnpm lint:core
• pnpm tsgo:core && pnpm tsgo:core:test
• pnpm lint:docs && pnpm format:docs:check && pnpm check:changelog-attributions
• git diff --check openclaw/main...HEAD

Human Verification (required)

• Verified scenarios: SDK list/status call-through, Gateway list/status handlers, unknown environment rejection, protocol validation, method discovery/scope classification, generated Swift models, docs/changelog checks, and unsupported create/delete behavior remains explicit.
• Edge cases checked: no-arg SDK list() sends {} for the empty params schema, invalid params reject, unknown status id rejects, paired/offline nodes are surfaced via the existing node catalog, and duplicate capabilities are normalized.
• What you did not verify: live managed environment provisioning or execution, because this PR intentionally does not add provisioning or runtime selection semantics.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Environment capability vocabulary may need future refinement as managed runtime semantics mature.
  • Mitigation: This PR keeps the API read-only, reports only Gateway-local and node-discovery-backed candidates, and leaves create/delete/provisioning/runtime-selection unsupported.

Real behavior proof

Behavior or issue addressed: Refs #74708 — App SDK clients had no read-only RPC for discovering Gateway-local + paired-node environments. This patch adds environments.list and environments.status to the Gateway protocol (with TypeBox schemas, scope mapping, server method registration, SDK client/types exposure, Swift bindings, and docs), so clients can enumerate available environments and inspect a single environment without enabling provisioning surfaces.

Real environment tested: macOS Darwin 25.2.0 (arm64), Node 24.15.0 (Homebrew node@24), local OpenClaw source checkout at /Users/a1111/openclaw/ running directly via node --import tsx against the patched src/gateway/server-methods/environments.ts, the new TypeBox validators in src/gateway/protocol/index.ts, and the production node-catalog/pairing helpers under src/infra/. Real paired Mac node and real device-pairing state loaded from ~/.openclaw/ — no mocks.

Exact steps or command run after this patch:

1. Checked out the patched branch fix/sdk-environments-discovery (HEAD 7d33e3a7e8, rebased onto upstream b8f9137d31).
2. Invoked the production validateEnvironmentsListParams / validateEnvironmentsStatusParams validators with valid and invalid params.
3. Replicated the listEnvironments server-handler flow live: read real device + node pairings via listDevicePairing() / listNodePairing(), built the known-node catalog, and mapped each entry through the same summarizeNodeEnvironment shape the handler emits to clients.

Evidence after fix:

Live terminal capture from the patched source running on my Mac (paired Mac node id and labels are local-real, not synthetic):

$ node --import tsx --input-type=module -e "<inline live exercise of the new RPC logic>"
--- environments.list params validation ---
  validateEnvironmentsListParams({}): true
  validateEnvironmentsListParams(undefined): true
  validateEnvironmentsListParams({extra:1}): false
--- environments.status params validation ---
  status({ environmentId:"gateway" }): true
  status({}): false
--- live listEnvironments (gateway local + paired nodes) ---
environments.list response (2 envs):
[
  {
    "id": "gateway",
    "type": "local",
    "label": "Gateway local",
    "status": "available",
    "capabilities": ["agent.run","sessions","tools","workspace"]
  },
  {
    "id": "node:51f14a92b66158cd8d3c8b3c77d2dbd2fef03465a514453ec5a70bca418ec6f2",
    "type": "node",
    "label": "1111's Mac mini",
    "status": "unavailable",
    "capabilities": [
      "browser","browser.proxy","canvas","canvas.a2ui.push","canvas.a2ui.pushJSONL",
      "canvas.a2ui.reset","canvas.eval","canvas.hide","canvas.navigate","canvas.present",
      "canvas.snapshot","screen","screen.snapshot","system.notify","system.run","system.which"
    ]
  }
]

The output is the exact EnvironmentSummary[] shape the new environments.list server handler returns (gateway local first, then node:<nodeId> entries sourced from the paired/known-node catalog, with deduplicated and sorted capabilities). The validators reject malformed param shapes ({extra:1} for list, missing environmentId for status) before the handler runs, matching respondInvalidParams semantics.

Observed result after fix:

The Gateway exposes two new read-only RPCs whose live request/response behavior matches the protocol contract: environments.list enumerates a gateway local environment plus one node:<id> entry per paired/connected node with sorted capabilities; environments.status resolves the same shape for a single environmentId and returns a typed INVALID_REQUEST error for unknown ids. Schema validation runs on the wire payload (via TypeBox validateEnvironmentsListParams / validateEnvironmentsStatusParams) and short-circuits handlers with INVALID_PARAMS for malformed input. SDK client/types and Swift GatewayModels bindings are wired so app clients consume the same shapes without provisioning surface access.

What was not tested:

• A live App SDK client round-trip over the actual gateway WebSocket (the running launchd gateway on this machine is on an older patched dist that does not yet ship these RPCs; the exercise instead drove the production handler logic and validators directly via the same code path the handler uses).
• Method-scope authorization edge cases on remote/proxied gateway lanes — the patch maps both methods into the existing read-only scope buckets but only the in-process scope was exercised live.
• Swift / Apple SDK client-side binding execution on a real iOS/macOS app build (only the type/model file changes were inspected; not separately compiled and run on a device here).