Summary

This PR consolidates the implementation/test follow-up work that was stacked behind the now-merged generic host-hook foundation in #72287. Docs split update: the large host-hook recipe page/nav/glossary work has been moved to the separate docs-only PR #74853, so this PR now carries implementation, tests, generated protocol/API baselines, and QA hardening only (~4,542 additions / 151 deletions across 68 files).

• Supersedes [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383: workflow action, outbound attachment, scheduler, and finalize-retry seams.
• Supersedes [plugin sdk] Add advanced workflow plugin contract fixtures #72384: advanced workflow contract fixtures proving realistic plugin archetypes.
• The former [plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333 host-hook examples and recipes documentation is now split out to [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853.

Feature / LOC Breakdown

Approximate line counts from the current consolidated diff against main (after #72287 merged). These are grouped by original follow-up PR / feature area so maintainers can review the stack by purpose, not just by file list. Production counts include generated client/API model updates where they are part of the shipped protocol surface; test counts include contract fixtures and QA/CI hardening tests; docs counts include recipe docs, nav, glossary, and the generated SDK API baseline hash.

#72287 has merged, so keeping the remaining work split across three stale/stacked PRs now creates more review churn than clarity. This replacement keeps the original commit-level review slices, but presents them as one follow-up PR based on current main, with the implementation and executable fixture proofs here and the docs/examples isolated in #74853.

Process note: this stack went through roughly two days of GPT-5.5/Codex-assisted hardening plus maintainer, bot, and adversarial review loops. The earlier follow-ups were repeatedly tested, fixed, and restacked. Consolidating them now is meant to stop the hardening loop from scattering new feedback across stale PR diffs while preserving the original detail and review evidence.

This remains generic plugin SDK work. It does not add Plan Mode product code, prompts, /plan behavior, Telegram-specific behavior, or product-specific UI. #71676 remains a parity oracle only; #71731 is the RFC context.

Relationship To The Merged Foundation

flowchart TD
  RFC["RFC #71731: plugin host-hook capability requirements"] --> Foundation["#72287 merged: generic host-hook foundation"]
  Oracle["#71676 parity oracle: required entry-point classes"] --> Foundation
  Foundation --> ThisPR["This consolidated follow-up PR"]
  ThisPR --> Workflow["Workflow seams: session actions, attachments, scheduling, finalize retry"]
  ThisPR --> Fixtures["Advanced contract fixtures: approval, policy, monitor, artifact, retry"]
  ThisPR -.-> Docs["#74853 docs PR: recipes and examples map"]

#72287 established the generic host-hook foundation: session extension storage/projection, queued injections, trusted tool policies, tool metadata, control UI descriptors, lifecycle/event subscriptions, run-context helpers, scheduler ownership cleanup, Gateway schemas, and SDK exports.

This PR builds on that merged foundation with host-mediated workflow affordances that real plugins need after they can register hooks:

• Let plugins define typed session actions and return validated action results.
• Let plugins send session-bound attachments through host-owned outbound delivery.
• Let plugins schedule future session turns through existing cron-compatible scheduler plumbing.
• Let plugins request bounded agent-finalize retries without owning runner internals.
• Add adversarial fixtures that prove the seams compose safely.
• Keep the large docs recipes split to [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853 so this PR stays focused on code, tests, and generated API/protocol evidence.

Why Consolidate Now

The old PRs were useful while #72287 was still unmerged because they separated foundation, workflow, proof fixtures, and docs. After #72287 merged, that split became counterproductive:

• [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383 and [plugin sdk] Add advanced workflow plugin contract fixtures #72384 still showed large inherited diffs and stale stacking context.
• [plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333 documented APIs that are now better reviewed as [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853 after the implementation stack is current.
• Reviewers and bots kept re-checking overlapping surfaces across old branch heads.
• Maintainers need one current comparison against main, not three partially inherited views.

This branch is the current comparison surface. The old PRs should be closed after this PR is opened and linked.

Review Order

The commits intentionally preserve the old review slices. Suggested review order:

1. Workflow seam commits, starting at feat(plugin-sdk): add workflow host seams.
2. Hardening commits for validation, cron compatibility, cleanup, lazy imports, and schema normalization.
3. Fixture commits, starting at test(plugin-sdk): add advanced workflow fixtures.
4. Consolidation/support commits:
   • chore(plugin-sdk): refresh consolidated API baseline
   • chore(plugin-sdk): refresh rebased API baseline
   • test(security): isolate windows acl os mock

The former docs/recipe commit group is now isolated in #74853.

Runtime Architecture

sequenceDiagram
  participant Plugin
  participant Registry as Plugin registry
  participant Gateway as Gateway method
  participant Runner as Agent runner
  participant Cron as Existing cron scheduler
  participant Outbound as Host outbound delivery

  Plugin->>Registry: registerSessionAction(...)
  Plugin->>Registry: sendSessionAttachment(...)
  Plugin->>Registry: scheduleSessionTurn(...)
  Plugin->>Registry: before_agent_finalize retry hook

  Gateway->>Registry: plugins.sessionAction(name, input)
  Registry->>Registry: validate action id, input, output, failure shape
  Registry-->>Gateway: typed success/failure reply

  Runner->>Registry: agent lifecycle / event payloads
  Registry->>Plugin: scoped event subscriptions
  Plugin->>Registry: setRunContext / enqueueNextTurnInjection

  Plugin->>Registry: scheduleSessionTurn(session, when, text)
  Registry->>Cron: cron-compatible scheduled job payload
  Cron-->>Runner: future session turn

  Plugin->>Registry: sendSessionAttachment(...)
  Registry->>Outbound: lazy host-owned delivery path
  Outbound-->>Gateway: session-bound attachment delivery

What Future Plugins Can Now Do

flowchart LR
  Hooks["Merged #72287 host hooks"] --> Workflow["This PR workflow seams"]
  Workflow --> Deploy["Deploy approver plugin"]
  Workflow --> Budget["Budget guard plugin"]
  Workflow --> SLA["SLA / incident watcher plugin"]
  Workflow --> Artifact["Artifact responder plugin"]
  Workflow --> Review["Review concierge plugin"]
  Workflow --> Wizard["Setup wizard plugin"]
  Workflow --> Monitor["Background monitor plugin"]

  Deploy --> A1["Session action + continueAgent + scoped command"]
  Budget --> A2["Trusted policy + session state + typed denial"]
  SLA --> A3["Scheduled turn + agent events + run context"]
  Artifact --> A4["Attachment send + tool metadata + action result"]
  Review --> A5["Finalize retry + queued injection + event subscription"]
  Wizard --> A6["Control descriptor + session action + persisted extension"]
  Monitor --> A7["Cron-compatible schedule + lifecycle cleanup"]

Examples that are intentionally generic, not Plan Mode-specific:

• Deploy approver: registers a deploy.approve action, requires operator approval scope, stores the pending deployment in plugin-owned session state, and uses continueAgent after an approval action.
• Budget guard: registers trusted tool policy reads and blocks expensive tools when plugin-owned budget state is exhausted, with a typed denial instead of a thrown internal error.
• SLA watcher: subscribes to agent/session events, schedules a future session turn if a deadline is missed, and cleans scheduled jobs when the plugin/session is disabled or deleted.
• Artifact responder: sends session-bound files through host outbound delivery after a plugin tool produces a report, bundle, or review artifact.
• Review concierge: uses finalize retry and queued injection priority to ask the agent to repair a reply before the host finalizes delivery.
• Setup wizard: registers a control UI descriptor plus session actions so a UI can present plugin-defined setup state without arbitrary browser JS.

SDK And Gateway Surface Added In This PR

SDK / plugin API

• Session actions: plugins can register typed session actions that are invoked through the host rather than through ad hoc commands.
• Outbound attachment helper: plugins can ask the host to send a session-bound attachment without importing channel/runtime internals.
• Scheduled session turns: plugins can schedule future session turns through the existing cron-compatible host scheduler.
• Finalize retry support: plugins can request a bounded retry before a reply is finalized.
• Priority on queued next-turn injections: queued injections can express priority while still being validated by the host.
• Workflow hook config defaults: plugin workflow hook config is captured with safe defaults and validation.
• Runtime context helpers remain from [plugin sdk] Add generic plugin host-hook contracts #72287 and are exercised here in workflow scenarios.

Gateway / protocol

• Adds typed protocol support for plugin session actions and typed action errors.
• Normalizes workflow Gateway outputs so clients see deterministic success/failure shapes.
• Updates generated Swift Gateway models for the additive protocol surface.
• Preserves closed-schema behavior: invalid or oversized plugin data is rejected or skipped instead of leaking arbitrary payloads into host paths.

Runner / agent lifecycle

• Agent finalize retry requests are preserved long enough for bounded retry evaluation.
• CLI prompt preparation stays lazy when no prompt-consuming hooks are present.
• Workflow caches and runtime context are cleaned by host-owned cleanup paths.

Scheduler / cron

• Scheduled session turns are host-mediated over existing cron access.
• Runtime-only scheduled turns are preserved on plugin restart/reload.
• Cleanup exclusions are keyed by owner/job id so stale cleanup cannot delete another plugin's jobs.
• Default cron delivery mode is omitted because the cron payload schema is closed.

Docs / recipes

The large recipe page, docs navigation entry, and glossary entry were split to #74853. This PR keeps the implementation/tests/generated API surface only.

File-Group Changelog

SDK/API

• src/plugins/host-hooks.ts: expands the generic hook types with workflow action, outbound, scheduler, and retry concepts.
• src/plugins/types.ts: exposes additive plugin API types for workflow seams.
• src/plugin-sdk/core.ts, src/plugin-sdk/plugin-entry.ts, src/plugin-sdk/plugin-test-api.ts: project the new SDK methods into public plugin entry/test surfaces.
• docs/.generated/plugin-sdk-api-baseline.sha256: regenerated after the consolidated API surface was verified.

Registry/runtime

• src/plugins/registry.ts: captures workflow registrations, validates schemas, dispatches session actions, and wires cleanup.
• src/plugins/registry-types.ts, src/plugins/captured-registration.ts, src/plugins/runtime-state.ts: add durable capture/runtime typing for workflow hooks.
• src/plugins/host-hook-runtime.ts, src/plugins/host-hook-state.ts, src/plugins/host-hook-cleanup.ts: scope run context, side effects, lifecycle cleanup, and scheduler ownership cleanup.
• src/plugins/runtime.ts, src/plugins/registry-empty.ts: keep empty registries and runtime state compatible with the new surface.

Workflow bridge

• src/plugins/host-hook-workflow.ts: centralizes session action dispatch, attachment delivery, scheduled turn registration, and workflow helper behavior.
• src/agents/harness/lifecycle-hook-helpers.ts: factors finalize retry helper behavior so retry is bounded and testable.
• src/agents/pi-embedded-runner/run.ts: integrates finalize retry requests into the runner path.
• src/agents/cli-runner/prepare.ts: keeps prompt prep lazy when no prompt-consuming hooks are present.

Gateway/protocol

• src/gateway/server-methods/plugin-host-hooks.ts: adds Gateway methods for plugin workflow/session action calls.
• src/gateway/server-methods-list.ts, src/gateway/method-scopes.ts: wires method registration and scope metadata.
• src/gateway/protocol/schema/plugins.ts, src/gateway/protocol/schema/protocol-schemas.ts, src/gateway/protocol/schema/types.ts, src/gateway/protocol/index.ts: adds typed schemas and exported protocol entries.
• apps/macos/Sources/OpenClawProtocol/GatewayModels.swift and apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift: generated client model updates for the additive protocol surface.

Policy/catalog hardening touched by workflow seams

• src/plugins/trusted-tool-policy.ts: keeps policy parameter handling plain-object guarded and compatible with workflow use.
• src/agents/pi-tools.before-tool-call.integration.e2e.test.ts: retains coverage around intentional policy blocks as blocked results rather than generic tool execution failures.

Contract tests and fixtures

• src/plugins/contracts/host-hooks.contract.test.ts: expands contract coverage for workflow registration, validation, cleanup, scheduling, queued injection priority, side effects, and Gateway normalization.
• src/plugins/contracts/advanced-workflow-fixtures.ts: adds reusable fixture plugin archetypes.
• src/plugins/contracts/advanced-workflow-fixtures.contract.test.ts: proves approval, policy gate, background monitor, artifact reply, and finalize retry flows through executable fixtures.
• src/agents/harness/lifecycle-hook-helpers.test.ts: verifies bounded finalize retry semantics.

CI stabilization

• src/security/windows-acl.test.ts: adds explicit module reset before importing the Windows ACL module under test. This is not part of the plugin SDK surface; it keeps the broad core-unit-fast-support CI shard deterministic after current main started caching node:os before this test mock in the full shard.

Docs

• Large prose docs are intentionally out of scope here and live in [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853.
• This PR only updates generated SDK/API baseline artifacts needed by the implementation surface.

Hook Hardening Matrix

Before / After Examples

Scheduled turns stay cron-compatible

Before, a plugin schedule helper could produce payloads with default delivery metadata that the closed cron schema did not accept.

After, scheduled session turns only send cron-compatible fields:

api.scheduleSessionTurn({
  sessionKey,
  text: "Check whether the deployment window is still blocked.",
  runAt: new Date(Date.now() + 15 * 60_000).toISOString(),
});

Session action validation fails deterministically

Before, malformed action outputs could surface as generic runtime failures.

After, invalid action registration or invalid action results are rejected through typed plugin-action errors:

api.registerSessionAction({
  id: "deploy.approve",
  inputSchema: {
    type: "object",
    properties: { deploymentId: { type: "string" } },
    required: ["deploymentId"],
    additionalProperties: false,
  },
  async handler(ctx, input) {
    return {
      ok: true,
      reply: `Approved ${input.deploymentId}`,
      continueAgent: true,
    };
  },
});

Scheduler cleanup is owner-safe

Before, stale cleanup could be too broad when old and new scheduler records shared job ids.

After, cleanup exclusions are keyed by owner and job id. A plugin reload can preserve its active jobs, while disable/reset/delete still removes plugin-owned scheduled state.

Finalize retry is bounded

Before, a plugin that wanted to repair a final reply had no generic host-mediated finalize retry seam.

After, workflow plugins can request a bounded retry through the finalize hook path, and the helper tests prove retries clear their budget rather than looping indefinitely.

Example Plugin Shapes

Deploy approval plugin

api.registerSessionExtension({
  namespace: "deployApproval",
  description: "Pending deployment approvals for this session",
});

api.registerSessionAction({
  id: "deploy.approve",
  inputSchema: {
    type: "object",
    properties: { deploymentId: { type: "string" } },
    required: ["deploymentId"],
    additionalProperties: false,
  },
  async handler(ctx, input) {
    await api.enqueueNextTurnInjection({
      sessionKey: ctx.sessionKey,
      text: `Deployment ${input.deploymentId} was approved. Continue the release checklist.`,
      priority: "high",
    });
    return { ok: true, reply: "Approved.", continueAgent: true };
  },
});

Budget guard plugin

api.registerTrustedToolPolicy({
  id: "budget.guard",
  description: "Block expensive tools when the session budget is exhausted",
  async evaluate(ctx) {
    const budget = await api.getRunContext(ctx.runId, "budget.remainingUsd");
    if (typeof budget === "number" && budget <= 0) {
      return { block: true, reason: "Session budget exhausted" };
    }
    return { allow: true };
  },
});

SLA watcher plugin

api.registerAgentEventSubscription({
  streams: ["agent.lifecycle", "agent.tool"],
  async handler(event) {
    if (event.type === "agent.lifecycle" && event.name === "turn.started") {
      await api.scheduleSessionTurn({
        sessionKey: event.sessionKey,
        runAt: new Date(Date.now() + 30 * 60_000).toISOString(),
        text: "SLA watcher: check whether this incident still needs escalation.",
      });
    }
  },
});

Artifact responder plugin

api.registerSessionAction({
  id: "review.sendArtifact",
  inputSchema: {
    type: "object",
    properties: { path: { type: "string" }, label: { type: "string" } },
    required: ["path", "label"],
    additionalProperties: false,
  },
  async handler(ctx, input) {
    await api.sendSessionAttachment({
      sessionKey: ctx.sessionKey,
      path: input.path,
      label: input.label,
    });
    return { ok: true, reply: `Sent ${input.label}.` };
  },
});

Removed Or Refactored Code

No Plan Mode product code is added here. No Plan Mode prompts, /plan command behavior, Telegram routing, local installer patches, arbitrary browser JS, or Plan Mode-specific UI cards are introduced.

Refactors/removals are limited to keeping the generic workflow surface production-safe:

• Scheduled turn payload metadata was narrowed so the helper emits only fields accepted by the existing cron schema. Risk: plugin authors cannot depend on a default delivery string. Mitigation: docs and tests show the omitted-default form.
• Runtime workflow side effects are lazy/gated by config. Risk: code paths become more indirect. Mitigation: contract tests exercise both registered behavior and no-side-effect fixture behavior.
• Workflow helper logic is centralized in src/plugins/host-hook-workflow.ts rather than scattering session action, attachment, and scheduling paths through Gateway/runner code. Risk: one module carries more responsibility. Mitigation: focused contract tests cover validation and output normalization.
• Finalize retry helper behavior is factored into src/agents/harness/lifecycle-hook-helpers.ts to make bounded retry explicit. Risk: runner integration changes. Mitigation: lifecycle helper tests and host-hook contract coverage.
• Docs examples removed the core-tool metadata pattern from the earlier docs review because metadata projection is plugin-owned. Risk: less broad-looking example. Mitigation: examples now match the actual contract and avoid implying plugins can rewrite core-owned catalog entries.

Validation

Local validation on this consolidated branch:

pnpm test src/plugins/contracts/host-hooks.contract.test.ts src/plugins/contracts/advanced-workflow-fixtures.contract.test.ts src/agents/pi-tools.before-tool-call.integration.e2e.test.ts src/auto-reply/reply/commands-plugin.test.ts
# passed: 2 plugin contract files / 55 tests, 1 auto-reply file / 4 tests, 1 e2e file / 10 tests

pnpm docs:list
# passed

pnpm plugin-sdk:api:check
# passed after regenerating docs/.generated/plugin-sdk-api-baseline.sha256

pnpm tsgo:all
# passed

pnpm lint
# passed

pnpm check:architecture
# passed: import cycles, madge cycles, deprecated internal config API guard

pnpm check:changed
# passed

pnpm build
# passed

git diff --check upstream/main...HEAD
# passed

OPENCLAW_VITEST_MAX_WORKERS=2 OPENCLAW_VITEST_SHARD_NAME=core-unit-fast-support pnpm exec node scripts/test-projects.mjs test/vitest/vitest.unit-fast.config.ts test/vitest/vitest.unit-support.config.ts
# passed: 887 unit-fast files, 7911 tests

Maintainer Checklist

• Review this PR instead of [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383, [plugin sdk] Add advanced workflow plugin contract fixtures #72384, and [plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333.
• Confirm this PR's base is current main after [plugin sdk] Add generic plugin host-hook contracts #72287.
• Confirm CI is green for this exact head.
• Confirm no unresolved current or outdated review threads remain.
• Review commit groups in the order listed above.
• Check that SDK/Gateway surfaces are additive and generated baselines are committed.
• Review the split docs/examples in [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853 after this implementation stack is accepted.
• Merge this consolidated implementation follow-up after [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383/[plugin sdk] Add advanced workflow plugin contract fixtures #72384/[plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333 are closed as superseded.

Rollback: revert this PR. No DB migration is expected. The surfaces are additive; plugin-owned state and scheduled jobs are host-owned and cleanup/ignore paths are covered by the foundation plus this follow-up.

Issue / RFC Linkage

• RFC context: [plugin sdk] docs: plugin host hook RFC #71731; parity oracle only: Plan Mode rebased onto upstream/main + executing-state subsystem #71676.
• Foundation already merged: [plugin sdk] Add generic plugin host-hook contracts #72287.
• Current replacement stack: [plugin sdk] Consolidate workflow seams and fixtures #73384 carries workflow seams, fixtures, hardening, generated protocol/API evidence; [plugin sdk] Add generic SDK seam followups #74483 carries the draft generic seam follow-ups; [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853 carries docs/recipes.
• Supersedes stale follow-ups [plugin sdk] Add workflow action, outbound, scheduler, and retry host seams #72383 and [plugin sdk] Add advanced workflow plugin contract fixtures #72384 for implementation/fixture review; the old [plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333 docs material is now [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853.
• RFC slices materially exercised by this PR and the merged foundation: [RFC] Plugin session extensions and patch actions #71732 session-state/action projection, [RFC] Durable next-turn injections and agent turn preparation hooks #71733 queued injection/turn-prep workflow composition, [RFC] Trusted tool policy stage and plugin tool metadata #71734 trusted policy/tool metadata hardening, [RFC] Scoped plugin commands, trusted command ownership, and continuation #71735 command/session-action continuation, and [RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions #71737 lifecycle/event/scheduler coverage.
• Related but not fully closed here: [RFC] Control UI plugin contribution slots #71736 remains the broader Control UI contribution-slot/native-page design thread. This PR only carries generic descriptor/session-action foundations, not the full Control UI slot vocabulary.