PR #74847: feat(gateway): add SDK task ledger RPCs

• Repository: openclaw/openclaw
• Author: tmimmanuel
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74847

Description (problem / solution / changelog)

Summary

• Problem: @openclaw/sdk exposed oc.tasks.*, but list, get, and cancel still threw unsupported errors because Gateway had no SDK-facing task ledger RPCs.
• Why it matters: OpenMeow and other app clients need stable task visibility for detached/background work without reading internal logs or CLI-only surfaces.
• What changed: Added tasks.list, tasks.get, and tasks.cancel Gateway RPCs, SDK methods/types, protocol schemas, scopes, docs, and regression coverage.
• What did NOT change (scope boundary): This does not add tool invocation, artifact APIs, environment provisioning, or new task runtime semantics.

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 #74707
• Related #74704
• Related #74705
• Related #74706
• Related #74708
• Related #74709
• Related https://github.com/OpenCoven/open-meow-sdk
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Gateway already had a durable task registry, but no public RPC contract or SDK bridge exposed it to external app clients.
• Missing detection / guardrail: SDK coverage only locked in unsupported task errors instead of the app-client task ledger contract.
• Contributing context (if known): The OpenMeow gap map calls out tasks.list, tasks.get, and tasks.cancel as missing basics.

Regression Test Plan (if applicable)

• Coverage level that should have caught this: Unit test and seam / integration test.
• Target test or file: src/gateway/server-methods/tasks.test.ts, src/gateway/protocol/index.test.ts, packages/sdk/src/index.test.ts, packages/sdk/src/index.e2e.test.ts.
• Scenario the test should lock in: SDK task methods route to Gateway RPCs, task statuses are app-facing and stable, filters work, scopes are classified, and cancel returns a clear result contract.
• Why this is the smallest reliable guardrail: It exercises the protocol and SDK seams without requiring a live detached task runtime.
• Existing test that already covers this (if any): Existing task registry tests cover the underlying task lifecycle.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

oc.tasks.list(), oc.tasks.get(taskId), and oc.tasks.cancel(taskId) now call Gateway task ledger RPCs instead of throwing unsupported errors.

Diagram (if applicable)

Before:
[external app] -> [@openclaw/sdk oc.tasks.*] -> [unsupported error]

After:
[external app] -> [@openclaw/sdk oc.tasks.*] -> [Gateway tasks.* RPC] -> [durable task registry]

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: tasks.list and tasks.get require operator.read; tasks.cancel requires operator.write. The RPCs expose task metadata from the existing durable task registry and do not expose secrets.

Repro + Verification

Environment

• OS: Ubuntu/Linux local workspace
• Runtime/container: Node 22.22.0 via nvm, pnpm 10.33.2
• 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.tasks.list(), oc.tasks.get("task-id"), or oc.tasks.cancel("task-id").
2. Observe the SDK unsupported error.
3. Apply this PR.
4. Call the same SDK methods against a Gateway with task records.

Expected

• SDK task methods route to Gateway task ledger RPCs and return stable task summaries or cancel results.

Actual

• Before this PR, SDK task methods throw unsupported errors.

Evidence

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

Lint evidence:

• git diff --check HEAD~1 HEAD
• targeted oxlint on changed TS files
• markdownlint-cli2 docs/concepts/openclaw-sdk.md

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: SDK-facing task statuses intentionally differ from internal registry statuses.
• Mitigation: Tests lock in the public mapping, including succeeded to completed and lost to failed.

Changed files

• apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +214/-0)
• apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +214/-0)
• docs/concepts/openclaw-sdk.md (modified, +12/-5)
• packages/sdk/src/client.ts (modified, +13/-9)
• packages/sdk/src/index.e2e.test.ts (modified, +54/-0)
• packages/sdk/src/index.test.ts (modified, +64/-9)
• packages/sdk/src/index.ts (modified, +6/-0)
• packages/sdk/src/types.ts (modified, +50/-0)
• src/gateway/method-scopes.test.ts (modified, +3/-0)
• src/gateway/method-scopes.ts (modified, +3/-0)
• src/gateway/protocol/index.test.ts (modified, +21/-0)
• src/gateway/protocol/index.ts (modified, +31/-0)
• src/gateway/protocol/schema.ts (modified, +1/-0)
• src/gateway/protocol/schema/protocol-schemas.ts (modified, +16/-0)
• src/gateway/protocol/schema/tasks.ts (added, +91/-0)
• src/gateway/protocol/schema/types.ts (modified, +7/-0)
• src/gateway/server-methods-list.ts (modified, +3/-0)
• src/gateway/server-methods.ts (modified, +2/-0)
• src/gateway/server-methods/tasks.test.ts (added, +167/-0)
• src/gateway/server-methods/tasks.ts (added, +205/-0)
• src/tasks/detached-task-runtime-contract.ts (modified, +1/-0)
• src/tasks/task-registry.ts (modified, +5/-2)

PR #74852: feat(gateway): add environment discovery RPCs

• Repository: openclaw/openclaw
• Author: gazeatcode
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74852

Description (problem / solution / changelog)

Summary

• Problem: @openclaw/sdk exposed oc.environments.*, but list and status still threw unsupported errors and Gateway advertised no environment discovery RPCs.
• Why it matters: app clients need a read-only way to discover local, Gateway, connected node, and managed environment candidates before provisioning semantics exist.
• What changed: added typed environments.list and environments.status Gateway RPCs, SDK call-through/types, read-scope classification, protocol schemas/generated Swift models, docs, and regression coverage.
• What did NOT change (scope boundary): oc.environments.create/delete remain unsupported, and per-run runtime, environment, workspace, and approvals 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 #74708
• Related https://github.com/OpenCoven/open-meow-sdk
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: N/A, this is the first additive read-only environment discovery contract for the SDK/Gateway surface.
• Missing detection / guardrail: Existing SDK tests only locked in unsupported environment namespace behavior.
• Contributing context (if known): The external OpenMeow proposal needs environment discovery/status before create/delete/provisioning APIs are designed.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: packages/sdk/src/index.test.ts, src/gateway/server-methods/environments.test.ts, src/gateway/protocol/index.test.ts, src/gateway/method-scopes.test.ts.
• Scenario the test should lock in: SDK oc.environments.list/status call Gateway RPCs, create/delete still throw unsupported, params/results validate, and methods are read-scoped/classified.
• Why this is the smallest reliable guardrail: It exercises the SDK, protocol, handler, and authorization seams without provisioning a managed runtime.
• Existing test that already covers this (if any): Existing SDK run option tests already verify unsupported per-run runtime/environment options fail before submission.
• If no new test is added, why not: 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 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: environments.list and environments.status require operator.read. They expose only environment candidate metadata and connected node-declared caps/commands, which are already represented in Gateway node discovery surfaces; they do not create environments or run commands.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node v24.14.1, pnpm 10.33.2
• 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("local").
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:

• pnpm test packages/sdk/src/index.test.ts src/gateway/server-methods/environments.test.ts src/gateway/protocol/index.test.ts src/gateway/method-scopes.test.ts
• pnpm tsgo:core
• pnpm tsgo:test:src && pnpm tsgo:test:packages
• pnpm protocol:check
• pnpm check:docs
• git diff --check upstream/main..HEAD

Human Verification (required)

• Verified scenarios: environment list/status SDK calls, Gateway handler output for local/gateway/node/managed candidates, unknown environment status rejection, create/delete unsupported errors, read-scope classification, protocol generation, and docs rendering/link checks.
• Edge cases checked: invalid params, unknown statuses, additional properties, connected node capability normalization, managed candidate remains unavailable, and per-run unsupported option coverage remains in the SDK test suite.
• What you did not verify: no live managed environment provisioning or live node runtime was started, because this PR intentionally does not add provisioning or execution 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 names may need future refinement as managed runtime semantics mature.
  • Mitigation: This PR keeps the API read-only, leaves create/delete unsupported, and reports managed Testbox as unavailable until provisioning is designed.

Changed files

• CHANGELOG.md (modified, +1/-0)
• apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +98/-0)
• apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +98/-0)
• docs/.i18n/glossary.zh-CN.json (modified, +40/-0)
• docs/concepts/openclaw-sdk.md (modified, +9/-2)
• docs/gateway/protocol.md (modified, +1/-0)
• docs/reference/openclaw-sdk-api-design.md (modified, +3/-2)
• packages/sdk/src/client.ts (modified, +6/-6)
• packages/sdk/src/index.test.ts (modified, +31/-6)
• packages/sdk/src/index.ts (modified, +4/-0)
• packages/sdk/src/types.ts (modified, +16/-0)
• src/gateway/method-scopes.test.ts (modified, +2/-0)
• src/gateway/method-scopes.ts (modified, +2/-0)
• src/gateway/protocol/index.test.ts (modified, +39/-0)
• src/gateway/protocol/index.ts (modified, +36/-0)
• src/gateway/protocol/schema.ts (modified, +1/-0)
• src/gateway/protocol/schema/environments.ts (added, +44/-0)
• src/gateway/protocol/schema/protocol-schemas.ts (modified, +14/-0)
• src/gateway/protocol/schema/types.ts (modified, +6/-0)
• src/gateway/server-methods-list.ts (modified, +2/-0)
• src/gateway/server-methods.ts (modified, +2/-0)
• src/gateway/server-methods/environments.test.ts (added, +142/-0)
• src/gateway/server-methods/environments.ts (added, +129/-0)

PR #74867: feat(gateway): add SDK environment discovery RPCs

• Repository: openclaw/openclaw
• Author: ai-hpc
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74867

Description (problem / solution / changelog)

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 #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.

Changed files

• CHANGELOG.md (modified, +1/-0)
• apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +98/-0)
• apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +98/-0)
• docs/concepts/openclaw-sdk.md (modified, +25/-19)
• docs/gateway/protocol.md (modified, +1/-0)
• docs/reference/openclaw-sdk-api-design.md (modified, +2/-2)
• packages/sdk/src/client.ts (modified, +6/-6)
• packages/sdk/src/index.test.ts (modified, +30/-6)
• packages/sdk/src/index.ts (modified, +2/-0)
• packages/sdk/src/types.ts (modified, +12/-0)
• src/gateway/method-scopes.test.ts (modified, +2/-0)
• src/gateway/method-scopes.ts (modified, +2/-0)
• src/gateway/protocol/index.ts (modified, +30/-0)
• src/gateway/protocol/schema.ts (modified, +1/-0)
• src/gateway/protocol/schema/environments.ts (added, +37/-0)
• src/gateway/protocol/schema/protocol-schemas.ts (modified, +14/-0)
• src/gateway/protocol/schema/types.ts (modified, +6/-0)
• src/gateway/server-methods-list.ts (modified, +2/-0)
• src/gateway/server-methods.ts (modified, +2/-0)
• src/gateway/server-methods/environments.test.ts (added, +118/-0)
• src/gateway/server-methods/environments.ts (added, +95/-0)