Greptile Summary

This PR adds the runtime seams for advanced workflow plugins: plugin-attributed agent event emission (emitAgentEvent), host-mediated file delivery (sendSessionAttachment), cron-backed session wake-ups (scheduleSessionTurn), typed gateway session actions (plugins.sessionAction), hot-path session extension reads (ctx.getSessionExtension), priority-sorted durable turn injections, and a bounded finalize/retry path. The trusted-policy and reserved-surface gating is well-considered, input validation is thorough across all new registration paths, and the new test coverage (host-hooks.contract.test.ts) is extensive.

Two minor issues worth addressing: the finalize retry budget map accumulates entries without cleanup, and resolveSchedule can throw an unhandled RangeError for invalid at date strings.

Confidence Score: 4/5

Safe to merge; the two P2 findings are non-blocking and don't affect correctness on the happy path.

No P0 or P1 issues found. Two P2 issues: (1) the finalize retry budget map is never pruned, causing gradual memory growth in long-running processes; (2) an invalid at date string in scheduleSessionTurn throws an unhandled RangeError instead of returning undefined. Neither affects normal operation.

src/agents/harness/lifecycle-hook-helpers.ts (retry budget leak) and src/plugins/host-hook-workflow.ts (invalid date handling in resolveSchedule)

This is a comment left during a code review.
Path: src/agents/harness/lifecycle-hook-helpers.ts
Line: 95-113

Comment:
**Retry budget map grows without bound**

The `FINALIZE_RETRY_BUDGET_KEY` singleton `Map<string, number>` is written on every finalize retry invocation but never pruned. Each unique `(runId + instruction)` pair adds a permanent entry that survives for the life of the process. Since `runId` changes every agent run, a long-running server that regularly triggers finalize retries will accumulate one entry per retry-eligible run indefinitely.

The budget map should be cleared when a run terminates — either by hooking into the terminal lifecycle event in `dispatchPluginAgentEventSubscriptions` (which already clears `runContextByRunId` on end/error) or by adding a cleanup step to `clearPluginHostRuntimeState`.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/plugins/host-hook-workflow.ts
Line: 147-148

Comment:
**Invalid `at` date throws unhandled `RangeError`**

If a plugin passes an invalid date string as `params.at`, `new Date(params.at)` produces an `Invalid Date` object and the immediately following `.toISOString()` call throws `RangeError: Invalid time value`. Because there is no `try/catch` in `schedulePluginSessionTurn`, this propagates as a rejected Promise rather than the documented `undefined` return. A `isNaN(at.getTime())` guard before calling `toISOString()` would fix this.

```suggestion
  const at = params.at instanceof Date ? params.at : new Date(params.at);
  if (isNaN(at.getTime())) {
    return undefined;
  }
  return { kind: "at", at: at.toISOString() };
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(plugin-sdk): type priority next-turn..." | Re-trigger Greptile}

Codex automated review: keeping this open.

Keep this PR open. Current main contains the merged #72287 host-hook foundation, but it still does not implement this PR’s workflow action dispatch, host-mediated outbound attachments, scheduled session wakeups, priority next-turn ordering, plugin-emitted workflow events through OpenClawPluginApi, or bounded finalize-retry contract. The PR is an active public SDK/Gateway contract change with security-sensitive review threads, not conservative cleanup.

Best possible solution:

Keep this PR open as the workflow-seam implementation layer above #72287. Maintainers should review or reject the proposed SDK/Gateway contracts explicitly, resolve the remaining security-sensitive review threads, and require protocol/API generation plus focused host-hook contract tests before landing. If the APIs are accepted, this PR or an equivalent implementation should add typed session actions, host-mediated attachments, scheduled session turns, priority next-turn injections, trusted session reads, and bounded finalize retry semantics on top of the already-merged foundation.

What I checked:

• current-main-sdk-foundation-only: OpenClawPluginApi exposes foundation host hooks such as registerSessionExtension, enqueueNextTurnInjection, registerTrustedToolPolicy, registerControlUiDescriptor, registerAgentEventSubscription, run context helpers, and registerSessionSchedulerJob. It does not expose registerSessionAction, sendSessionAttachment, scheduleSessionTurn, or an OpenClawPluginApi emitAgentEvent seam. (src/plugins/types.ts:2337, ad57a6d61658)
• gateway-method-missing: The Gateway server method list includes plugins.uiDescriptors, but there is no plugins.sessionAction method on current main. (src/gateway/server-methods-list.ts:48, ad57a6d61658)
• gateway-handler-ui-only: The plugin host-hook Gateway handler only implements plugins.uiDescriptors. Current main has no session-action dispatch, action result validation, or scoped action permission path. (src/gateway/server-methods/plugin-host-hooks.ts:10, ad57a6d61658)
• protocol-schema-lacks-session-action: The plugin protocol schema defines PluginJsonValue as Type.Unknown plus UI descriptor params/result only. It has no PluginsSessionActionParams or PluginsSessionActionResult schema. (src/gateway/protocol/schema/plugins.ts:4, ad57a6d61658)
• priority-next-turn-not-implemented: Persisted next-turn injection records have no priority field, and drain ordering is chronological by createdAt rather than priority-aware. (src/config/sessions/types.ts:123, ad57a6d61658)
• bounded-finalize-retry-not-implemented: before_agent_finalize results support only action and reason, and the harness normalizer only maps continue/revise/finalize. There is no retry payload, retry budget, or cleanup contract on current main. (src/plugins/hook-types.ts:292, ad57a6d61658)

Remaining risk / open question:

• This PR adds public SDK and Gateway protocol authority around session actions, outbound attachments, scheduled wakeups, and plugin-emitted events; those surfaces need exact-head trust-tier, schema, ownership, cleanup, quota, and file/path-boundary review before merge.
• The latest provided review context still has security/contract-sensitive open threads: blocking plugin-emitted terminal lifecycle streams and enforcing registered session-action payload schemas before dispatch.
• Because this PR is paired with open follow-up stack PRs [plugin sdk] Add advanced workflow plugin contract fixtures #72384 and [plugin sdk] Add host-hook examples and recipes (#72287 follow-up) #72333 by the same author, closing only this layer would likely strand dependent fixture and docs work.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against ad57a6d61658.

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Superseded by #73384 now that #72287 has merged.\n\nThis PR's workflow action, outbound attachment, scheduler, finalize-retry, validation, and cleanup work has been preserved in the consolidated follow-up branch with the original commit history retained for review order. Please move review and CI attention to #73384 so maintainers have one current main comparison instead of this stale stacked diff.