Why this matters

OpenClaw plugins increasingly need typed actions that the host can expose and dispatch: approve a workflow, reopen a case, accept extracted data, retry a run, continue an agent after a human decision, or branch a workflow from a structured operator choice.

Without a generic seam, plugin authors end up with two bad options:

• invent bespoke gateway methods and one-off UI contracts for every product feature; or
• push product-specific action routers into OpenClaw core.

This PR adds the missing middle layer: plugins register typed session actions once, the Gateway exposes one stable dispatch method, and OpenClaw keeps ownership of schema validation, scope enforcement, stale-plugin safety, and client protocol/codegen.

What kinds of plugins this could support

This seam is intentionally generic. It can support many plugin families without adding plugin-specific action routes to core:

• Approval and review plugins: approve, reject, request changes, or continue the agent with a typed reason.
• Support and case-management plugins: escalate, close, reopen, request follow-up, or attach a structured disposition.
• CRM and sales plugins: mark contacted, accept extracted updates, hand off ownership, or snooze the next step.
• Task and workflow plugins: claim, retry, confirm completion, or branch the workflow from an operator choice.
• Ops and incident plugins: suppress an alert, rerun diagnostics, confirm mitigation, or start escalation.
• UI companion plugins: render action buttons or menus in Control UI, native Apple clients, CLI helpers, or external companion surfaces that all call back through the same Gateway seam.

The important part: the plugin defines the action semantics. OpenClaw owns dispatch, auth, and transport-level enforcement.

New SDK seam

This PR adds:

• OpenClawPluginApi.registerSessionAction(...)
• typed action context, payload schema, success/failure results, and optional continueAgent
• plugins.sessionAction on the Gateway protocol plus regenerated Swift models
• runtime scope classification that honors action-declared requiredScopes

Example plugin usage:

api.registerSessionAction({
  id: "approve",
  description: "Approve the current workflow",
  requiredScopes: ["operator.approvals"],
  schema: {
    type: "object",
    properties: {
      message: { type: "string" },
    },
  },
  handler: ({ payload, sessionKey }) => ({
    data: {
      approved: true,
      message: payload?.message,
      ...(sessionKey ? { sessionKey } : {}),
    },
    continueAgent: true,
  }),
});

Runtime architecture

flowchart LR
  Plugin["Plugin register()"] --> Registry["Typed session action registry"]
  Client["Gateway client / Control UI / native app / CLI"] --> RPC["plugins.sessionAction"]
  RPC --> Guard["Schema validation + scope classification"]
  Guard --> Dispatch["Registered plugin action handler"]
  Dispatch --> Result["Typed success or failure payload"]
  Result --> Client

The action is registered once inside the plugin runtime and can then be dispatched from any client surface that speaks the Gateway protocol.

Safety and boundaries

This stays intentionally narrow:

• action ids, schemas, and duplicate registrations are validated at registration time
• payloads are validated before handler execution and malformed traffic is rejected
• dispatch enforces action-declared requiredScopes instead of treating every action like the same write lane
• unresolved out-of-process callers fall back to the standard operator scope bundle instead of under-scoping to operator.write
• stale or unloaded plugins are blocked instead of dispatching into dead registry state
• the upstream ACP live-delivery / streaming defaults already on upstream/main stay preserved in this slice

This is a bounded typed action protocol, not arbitrary plugin-owned gateway method injection.

What changed

• Added OpenClawPluginApi.registerSessionAction plus SDK exports for action registration, context, and result types.
• Added registry storage, validation, duplicate detection, loader snapshot/restore support, and plugin test API/captured registration support.
• Added Gateway protocol schemas/types, generated Swift models, and plugins.sessionAction dispatch.
• Added dynamic Gateway scope classification so known actions keep their declared least-privilege scopes, while unresolved out-of-process callers fall back to the standard operator scope bundle instead of under-scoping to operator.write.
• Fixed the shared agent-event bridge teardown so duplicate runtime.ts module instances do not double-dispatch pinned/active registry subscriptions.
• Preserved the upstream ACP live-delivery / streaming default changes already on upstream/main; this slice stays narrowly focused on typed session-action registration, dispatch, and scope enforcement.
• Added focused contract coverage for registration validation, payload schema validation, typed success/failure result validation, dispatch auth, stale-plugin blocking, pinned-registry event fanout, and method-scope classification.

Relationship to adjacent seams

This is narrower than attachments, scheduled turns, SessionEntry projection, or run-context lifecycle. It only adds the typed session-action registration/dispatch protocol plus the host scope enforcement that makes it safe to call.

Non-goals

• Does not render UI on its own; clients still choose how to present actions.
• Does not replace generic plugin gateway methods or open arbitrary new RPC namespaces.
• Does not include host-mediated attachments, scheduled turns, derived path facts, SessionEntry projection, finalize retry/run-context lifecycle, or advanced workflow composition fixtures.
• Does not reopen ACP streaming/live-delivery defaults; it preserves the upstream behavior already on main.

Stack context

• Predecessors: [plugin sdk] Consolidate workflow seams and fixtures #73384, [plugin sdk] Add generic SDK seam followups #74483
• Docs split: [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853
• Foundation: [plugin sdk] Add generic plugin host-hook contracts #72287

Real behavior proof

Behavior or issue addressed:
This fixes the under-scoped least-privilege path for plugins.sessionAction without broadening the seam beyond the session-action protocol. Before this patch, out-of-process callers that could not resolve a local plugin registry entry fell back to operator.write, so actions that correctly declared scopes like operator.approvals failed before reaching the handler. After this patch, known actions still use their declared scopes, unresolved callers fall back to the standard operator scope bundle instead of under-scoping, dispatch still enforces requiredScopes, and typed payload/result validation still rejects malformed traffic.

Real environment tested:
Fresh loopback Gateway started from /Users/lume/openclaw-review-worktrees/pr-75578-rebase with a workspace-loaded proof plugin at /tmp/openclaw-pr75578-proof.4VP2Yu/workspace/.openclaw/extensions/session-action-proof. The runtime used HOME=/tmp/openclaw-pr75578-proof.4VP2Yu/home, OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/workspace, OPENCLAW_STATE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/state, and OPENCLAW_CONFIG_PATH=/tmp/openclaw-pr75578-proof.4VP2Yu/config/openclaw.json.

Exact steps or command run after this patch:

HOME=/tmp/openclaw-pr75578-proof.4VP2Yu/home OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/workspace OPENCLAW_STATE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/state OPENCLAW_CONFIG_PATH=/tmp/openclaw-pr75578-proof.4VP2Yu/config/openclaw.json pnpm openclaw plugins inspect session-action-proof --runtime --json

HOME=/tmp/openclaw-pr75578-proof.4VP2Yu/home OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/workspace OPENCLAW_STATE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/state OPENCLAW_CONFIG_PATH=/tmp/openclaw-pr75578-proof.4VP2Yu/config/openclaw.json pnpm openclaw gateway call plugins.sessionAction --json --params '{"pluginId":"session-action-proof","actionId":"approve","payload":{"message":"post-fix"}}'

HOME=/tmp/openclaw-pr75578-proof.4VP2Yu/home OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/workspace OPENCLAW_STATE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/state OPENCLAW_CONFIG_PATH=/tmp/openclaw-pr75578-proof.4VP2Yu/config/openclaw.json node --import tsx <<'NODE'
import { callGateway } from './src/gateway/call.ts';
import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from './src/utils/message-channel.ts';
const result = await callGateway({
  method: 'plugins.sessionAction',
  params: {
    pluginId: 'session-action-proof',
    actionId: 'approve',
    payload: { message: 'post-fix' },
  },
  token: 'proof-token',
  clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
  mode: GATEWAY_CLIENT_MODES.BACKEND,
});
console.log(JSON.stringify(result, null, 2));
NODE

HOME=/tmp/openclaw-pr75578-proof.4VP2Yu/home OPENCLAW_WORKSPACE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/workspace OPENCLAW_STATE_DIR=/tmp/openclaw-pr75578-proof.4VP2Yu/state OPENCLAW_CONFIG_PATH=/tmp/openclaw-pr75578-proof.4VP2Yu/config/openclaw.json node --import tsx <<'NODE'
import { callGateway } from './src/gateway/call.ts';
import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from './src/utils/message-channel.ts';
try {
  await callGateway({
    method: 'plugins.sessionAction',
    params: {
      pluginId: 'session-action-proof',
      actionId: 'approve',
      payload: { message: 42 },
    },
    token: 'proof-token',
    clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
    mode: GATEWAY_CLIENT_MODES.BACKEND,
  });
  console.log('unexpected success');
} catch (error) {
  console.error(String(error));
  process.exitCode = 1;
}
NODE

Evidence after fix:

$ pnpm openclaw gateway call plugins.sessionAction --json --params '{"pluginId":"session-action-proof","actionId":"approve","payload":{"message":"post-fix"}}'
gateway connect failed: GatewayClientRequestError: scope upgrade pending approval (requestId: f97fd499-4729-4cd9-b7e0-d7dc90334595)
Gateway call failed: GatewayTransportError: gateway closed (1008): pairing required: device is asking for more scopes than currently approved (requestId: f97fd499-4729-4cd9-b7e0-d7dc90334595)

$ node --import tsx <authorized backend proof>
{
  "ok": true,
  "result": {
    "approved": true,
    "message": "post-fix",
    "sessionKey": null,
    "scopes": [
      "operator.admin",
      "operator.read",
      "operator.write",
      "operator.approvals",
      "operator.pairing",
      "operator.talk.secrets"
    ]
  }
}

$ node --import tsx <invalid payload proof>
GatewayClientRequestError: plugin session action payload does not match schema: message: must be string

Observed result after fix:
The paired CLI flow no longer under-scopes plugins.sessionAction to operator.write; it now requests the broader operator scope bundle and hits the existing scope-upgrade approval gate, which preserves pairing/approval enforcement instead of failing with a misleading handler-level missing-scope error. An authorized backend/token caller successfully dispatches the typed session action and receives the typed success payload. A malformed payload is rejected before handler execution with the expected schema error.

What was not tested:
This proof did not run a full end-to-end Control UI or native Apple client invocation against the regenerated Swift models. The Swift surface was regenerated and covered at the protocol/codegen layer in this patch, but the live proof here is intentionally limited to real Gateway registration/dispatch/scope enforcement and typed payload validation.

Validation

• pnpm protocol:gen
• pnpm protocol:gen:swift
• pnpm test src/gateway/method-scopes.test.ts src/gateway/call.test.ts src/agents/tools/gateway.test.ts src/plugins/contracts/session-actions.contract.test.ts
• pnpm test src/plugins/runtime.channel-pin.test.ts
• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test src/plugins/runtime.test.ts src/plugins/runtime.channel-pin.test.ts
• git diff --check