Closes #80219.

This is Phase 1 of the whole-surface Plugin SDK consolidation plan in #80219. It intentionally cleans up the host-workflow/session-control slice plus the active proof-gated seams, not the entire SDK/API surface in one PR.

This PR consolidates the active Plugin SDK host-hook/runtime work into one cleanup-first branch instead of asking reviewers to reason across four separate PRs plus a follow-up architecture issue.

It folds together:

• [plugin sdk] Add session action gateway protocol #75578: typed session action registration/dispatch plus scope enforcement
• [plugin sdk] Add host-mediated session attachments #75581: host-mediated session attachments
• [plugin sdk] Add scheduled session turns #75588: scheduled session turns
• [plugin sdk] Add structured extraction media runtime #79334: structured extraction media runtime

It also adds one narrow consolidation slice on top:

• additive grouped host-hook aliases on OpenClawPluginApi
• shared late-callability metadata for runtime-callable post-register APIs

Why this matters

OpenClaw is moving more host behavior into plugins and extensions, but the current Plugin SDK surface was heading toward a flat pile of new top-level verbs. That makes every new capability feel like permanent API expansion even when the underlying runtime seams are valid.

This PR keeps the feature work, but makes the shape easier to grow from:

• typed session actions stay a clean control/RPC seam
• session attachments and scheduled turns stay host-mediated workflow seams
• structured extraction stays inside media understanding instead of widening generic runtime.llm
• the new grouped aliases make the host-hook-heavy parts of the SDK read like families instead of unrelated top-level escapes

What this PR does

1. Integrates the active host-hook/runtime slices

• session action gateway protocol, dispatch, and scope enforcement
• host-mediated session attachment delivery
• scheduled session turns plus tag-based unscheduling
• structured extraction in the media-understanding runtime

2. Adds a narrow consolidation layer

• api.session.state.*
• api.session.workflow.*
• api.session.controls.*
• api.agent.events.*
• api.runContext.*
• api.lifecycle.*

These are additive aliases over the current flat methods. Existing plugin code keeps working.

3. Centralizes loader late-callability policy

Instead of loader.ts hardcoding post-register callable methods inline, this PR moves that policy into shared metadata so the runtime-callable host-hook seams have one source of truth.

Current runtime-callable post-register methods remain:

• sendSessionAttachment
• scheduleSessionTurn
• unscheduleSessionTurnsByTag

Architecture

flowchart TD
    A["Plugin author surface"] --> B["OpenClawPluginApi"]
    B --> C["Flat legacy methods remain supported"]
    B --> D["Additive grouped aliases"]

    D --> E["session.state"]
    D --> F["session.workflow"]
    D --> G["session.controls"]
    D --> H["agent.events"]
    D --> I["runContext"]
    D --> J["lifecycle"]

    F --> K["next-turn injection"]
    F --> L["attachments"]
    F --> M["scheduled turns"]
    G --> N["session actions"]
    H --> O["event subscribe/emit"]
    J --> P["runtime cleanup"]

    Q["mediaUnderstanding runtime"] --> R["structured extraction"]
    Q --> S["explicit provider/model media inference lane"]

Plugin families this supports

This combined surface is meant to support more than one product feature. Concretely, it is a foundation for:

• approval and operator-control plugins
• reminder, follow-up, and scheduled workflow plugins
• channel companion plugins that need outbound attachment delivery
• session-aware UI/control plugins
• background monitor and lifecycle plugins
• media-understanding and structured extraction plugins

Boundaries

• This does not collapse structured extraction into generic runtime.llm.complete.
• This does not remove the flat Plugin SDK methods yet.
• This does not try to genericize all workflow seams into one catch-all runtime mutation API.
• This keeps the upstream ACP streaming/default-delivery behavior intact.

Real behavior proof

Behavior or issue addressed:
This combined branch keeps the new host-hook seams narrow while proving they work together on the #80229 head. After this patch, typed plugin session actions dispatch through the Gateway with the action-declared operator scope bundle, grouped late-call workflow aliases remain callable after register() closes for bundled-plugin attachment and scheduled-turn operations, registration-only APIs stay blocked after register, and bounded structured extraction stays inside the media-understanding runtime instead of widening generic runtime.llm.

Real environment tested:
Local macOS checkout at /Volumes/LEXAR/repos/openclaw-plugin-sdk-consolidation on head 564400622821b7f89b374f2e7c25ac0de61bfa4d. I used an isolated temp workspace/state/config root at /var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs, started a token-auth loopback Gateway on ws://127.0.0.1:18997, ran live gateway call requests for the session-action seam, ran a standalone bundled-origin guarded API script against that live cron.* backend for grouped workflow aliases, and ran a standalone runtime proof script for extractStructuredWithModel(...).

Exact steps or command run after this patch:

1. Started an isolated token-auth Gateway from the merged head:

   HOME=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/home \
   OPENCLAW_WORKSPACE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/workspace \
   OPENCLAW_STATE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/state \
   OPENCLAW_CONFIG_PATH=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/config/openclaw.json \
   pnpm openclaw gateway run --allow-unconfigured --auth token --token proof-token --bind loopback --port 18997

2. Called the typed session-action seam on that Gateway once with valid payload and once with invalid payload:

   HOME=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/home \
   OPENCLAW_WORKSPACE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/workspace \
   OPENCLAW_STATE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/state \
   OPENCLAW_CONFIG_PATH=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/config/openclaw.json \
   pnpm openclaw gateway call plugins.sessionAction --json --token proof-token --url ws://127.0.0.1:18997 --params '{"pluginId":"proof-combined","actionId":"approve","sessionKey":"agent:main:main","payload":{"message":"post-fix"}}'
   
   HOME=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/home \
   OPENCLAW_WORKSPACE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/workspace \
   OPENCLAW_STATE_DIR=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/state \
   OPENCLAW_CONFIG_PATH=/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/config/openclaw.json \
   pnpm openclaw gateway call plugins.sessionAction --json --token proof-token --url ws://127.0.0.1:18997 --params '{"pluginId":"proof-combined","actionId":"approve","sessionKey":"agent:main:main","payload":{"message":42}}'

3. Ran a standalone node --import tsx proof script from repo root that:
   • creates a real bundled-origin plugin record through createPluginRegistry(...)
   • captures the guarded API via loader.__testing.runPluginRegisterSync(...)
   • invokes capturedApi.session.workflow.sendSessionAttachment(...)
   • verifies capturedApi.session.state.registerSessionExtension(...) stays blocked after register()
   • invokes capturedApi.session.workflow.scheduleSessionTurn(...) twice plus invalid tag/deleteAfterRun cases
   • calls capturedApi.session.workflow.unscheduleSessionTurnsByTag(...)
   • queries live cron.list before and after cleanup through the running Gateway
4. Ran a standalone node --import tsx runtime proof script from repo root that invokes runtime.mediaUnderstanding.extractStructuredWithModel(...) once with image+text input and once with text-only input.

Evidence after fix:

$ pnpm openclaw gateway call plugins.sessionAction --json --token proof-token --url ws://127.0.0.1:18997 --params '{"pluginId":"proof-combined","actionId":"approve","sessionKey":"agent:main:main","payload":{"message":"post-fix"}}'
{
  "ok": true,
  "result": {
    "approved": true,
    "message": "post-fix",
    "sessionKey": "agent:main:main",
    "scopes": [
      "operator.admin",
      "operator.read",
      "operator.write",
      "operator.approvals",
      "operator.pairing",
      "operator.talk.secrets"
    ]
  },
  "continueAgent": true
}

$ pnpm openclaw gateway call plugins.sessionAction --json --token proof-token --url ws://127.0.0.1:18997 --params '{"pluginId":"proof-combined","actionId":"approve","sessionKey":"agent:main:main","payload":{"message":42}}'
Gateway call failed: GatewayClientRequestError: plugin session action payload does not match schema: message: must be string

$ node --import tsx <bundled-origin guarded workflow proof>
{
  "attachment": {
    "ok": true,
    "channel": "proofchat",
    "deliveredTo": "12345",
    "count": 1
  },
  "deliveries": [
    {
      "to": "12345",
      "text": "attachment ready",
      "mediaUrl": "/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr80229-proof-qGy5Vs/workspace/proof-report.txt",
      "accountId": "default"
    }
  ],
  "sessionExtensionsBefore": 0,
  "sessionExtensionsAfter": 0,
  "first": {
    "id": "f2f6d165-2356-402c-ab9a-9b67b4e62f31",
    "pluginId": "proof-combined",
    "sessionKey": "agent:main:main",
    "kind": "session-turn"
  },
  "second": {
    "id": "32447765-6139-4238-bc4e-f3fb15ed333d",
    "pluginId": "proof-combined",
    "sessionKey": "agent:main:main",
    "kind": "session-turn"
  },
  "badTag": null,
  "badDelete": null,
  "cronJobsAfterSchedule": {
    "jobs": [
      {
        "id": "32447765-6139-4238-bc4e-f3fb15ed333d",
        "name": "plugin:proof-combined:tag:nudge:agent:main:main:2396fa1c-f78a-49e6-93d0-9e0013a02afa",
        "deleteAfterRun": true,
        "sessionTarget": "session:agent:main:main",
        "payload": { "kind": "agentTurn", "message": "wake two" },
        "delivery": { "mode": "none" }
      },
      {
        "id": "f2f6d165-2356-402c-ab9a-9b67b4e62f31",
        "name": "plugin:proof-combined:tag:nudge:agent:main:main:4e148d8e-5e2b-4cdc-bc80-ce50f6cd8f47",
        "deleteAfterRun": true,
        "sessionTarget": "session:agent:main:main",
        "payload": { "kind": "agentTurn", "message": "wake one" },
        "delivery": { "mode": "announce", "channel": "last" }
      }
    ],
    "total": 2
  },
  "removed": {
    "removed": 2,
    "failed": 0
  },
  "cronJobsAfterCleanup": {
    "jobs": [],
    "total": 0
  }
}

$ node --import tsx <structured extraction runtime proof>
{
  "success": {
    "text": "{\"summary\":\"red square\",\"tags\":[\"shape\"]}",
    "model": "gpt-5.4",
    "provider": "codex",
    "contentType": "json",
    "parsed": {
      "summary": "red square",
      "tags": ["shape"]
    }
  },
  "authProfileIds": ["openai-codex:work"],
  "requestMethods": ["model/list", "thread/start", "turn/start"],
  "threadStart": {
    "approvalPolicy": "on-request",
    "sandbox": "read-only",
    "serviceName": "OpenClaw",
    "dynamicTools": [],
    "ephemeral": true
  },
  "guardError": "Structured extraction requires at least one image input."
}

Observed result after fix:
On the combined #80229 head, plugins.sessionAction dispatch succeeds with typed output and reaches the handler under the action-declared operator scope bundle, while malformed payloads are rejected before handler execution. The grouped late-call workflow aliases on api.session.workflow.* remain callable after register() closes for a bundled plugin, the registration-only session.state.registerSessionExtension(...) path stays blocked (sessionExtensionsBefore/After remained 0), a relative attachment path resolves against the session workspace and is delivered to the active direct-outbound route, two real host cron jobs are created and visible through cron.list, invalid tag/deleteAfterRun inputs fail closed, and tagged cleanup removes both jobs. Structured extraction stays bounded in the media-understanding runtime, forwards the selected auth profile into the provider-owned runtime, returns parsed JSON for image input, and rejects text-only calls before provider dispatch.

What was not tested:
This proof did not run a full end-to-end Control UI or native Apple client flow, and it did not use a credentialed live Codex desktop session. The live evidence here is intentionally limited to merged-head Gateway dispatch, bundled-origin guarded workflow aliases against a real cron.* backend, direct-outbound attachment delivery, and bounded runtime/provider structured extraction behavior.

Verification

Local verification on this combined branch:

node scripts/run-vitest.mjs run --config test/vitest/vitest.config.ts src/plugins/loader.test.ts --maxWorkers=1
node scripts/run-vitest.mjs run --config test/vitest/vitest.contracts-plugin.config.ts src/plugins/contracts/run-context-lifecycle.contract.test.ts src/plugins/contracts/session-actions.contract.test.ts --maxWorkers=1
pnpm plugin-sdk:api:gen
node scripts/run-oxlint-shards.mjs --threads=8

Notes for reviewers

• The feature work here originated as four active PR lines because each seam was independently useful.
• The maintainer concern about API accretion is valid, so this branch intentionally adds only the smallest consolidation layer that improves the author-facing shape without re-plumbing the runtime.
• If this direction lands, the next cleanup step should be export-surface reduction and alias/deprecation of the obvious debt lanes described in [plugin sdk] Consolidate author surface, lifecycle semantics, and export sprawl #80219.