[plugin sdk] Add generic SDK seam followups

[100yenadmin]

Draft status

This is a draft preview PR for the generic SDK seam follow-up branch. It is intentionally draft while #73384 is still open, because the branch is prepared on top of the #73384 head so maintainers can inspect the intended follow-up delta without reopening the closed dirty #73526. After #73384 lands, this branch should be rebased onto fresh main, revalidated, and then marked ready as a standalone PR.

Docs split update: the large host-hook recipe docs inherited from #73384 were moved to #74853, so this PR remains a single code/test follow-up commit (~2,027 additions / 26 deletions across 41 files) without the docs page in its stack diff.

This PR is generic plugin SDK work. It does not add product-specific prompts, command behavior, product UI, or channel-specific workflow logic. The goal is to close the remaining SDK gaps for non-trivial workflow plugins: deployment approvers, budget guards, SLA watchers, review assistants, channel-native workflow plugins, scheduled reminders, sub-agent observability plugins, and session projection consumers.

Feature / LOC Breakdown

Current intended delta against #73384:

Feature area	Production LOC	Tests LOC	Total diff	Files	What it adds
Host runtime reads + tool param derivation	~240	~375	~615	11	Read-only _host.runtime run context, subagent parent/settle tracking, derivedPaths for apply_patch, parser registry.
Channel attachment hints + Telegram helper exports	~40	~16	~56	6	Typed attachment caption/channel hints, Telegram formatting public re-exports, channel plumbing for parse/silent/thread hints.
Control UI descriptor input suppression	~35	covered in contract tests	~35	5	suppressHostInputWhile descriptor field carried through registry, Gateway schema, and generated clients.
Scheduler tag taxonomy + cleanup	~150	~160	~310	6	Tagged scheduled turns, deterministic unscheduleSessionTurnsByTag, canonical payload ordering, cleanup tests.
SessionEntry slot projection	~190	~190	~380	5	Validated plugin-owned session extension projection into safe SessionEntry slots, reserved-key guard, unset/projector-failure coverage.
QA/private package boundary cleanup	~20	small config tests	~40	4	Removes private openclaw/plugin-sdk/qa-channel dependency in favor of public @openclaw/qa-channel re-exports.
Total	~1,000	~1,000	+2027 / -26	41	One focused generic follow-up commit prepared for post-#73384 review.

Relationship To #73384

flowchart TD
  Foundation["#72287 merged: generic host-hook foundation"] --> Workflow["#73384: workflow seams, fixtures, recipes"]
  Workflow --> ThisPR["This draft: generic SDK seam followups"]
  ThisPR --> Runtime["Host runtime reads + derived tool paths"]
  ThisPR --> Channels["Channel attachment hints + helper exports"]
  ThisPR --> UI["Control UI input-suppression descriptor"]
  ThisPR --> Scheduler["Tagged scheduled turns + unschedule by tag"]
  ThisPR --> Slots["SessionEntry slot projection"]

Loading

#73384 adds the workflow affordances: session actions, attachments, scheduling, finalize retry, and fixtures. The large recipes/docs page is split to #74853. This draft adds the smaller SDK seams needed by plugins that compose those affordances without reaching into core internals.

What Future Plugins Can Do

flowchart LR
  SDK["Generic SDK seams"] --> Deploy["Deploy approver"]
  SDK --> Budget["Budget guard"]
  SDK --> SLA["SLA watcher"]
  SDK --> Review["Review assistant"]
  SDK --> Channel["Channel-native workflow plugin"]
  SDK --> Observe["Subagent observer"]

  Deploy --> A["SessionEntry slot + UI suppress hint + tagged timeout cleanup"]
  Budget --> B["Trusted policy + plugin session reads + typed denial"]
  SLA --> C["Scheduled turn tags + event/run context"]
  Review --> D["Derived apply_patch paths + host runtime reads"]
  Channel --> E["Attachment hints + Telegram formatting exports"]
  Observe --> F["Read-only parent/subagent runtime snapshot"]

Loading

Added SDK / Protocol Surface

• getHostRunContext("_host.runtime") for read-only host runtime snapshots.
• derivedPaths?: string[] on before_tool_call events for host-derived tool param facts.
• PluginSessionAttachmentParams.captionFormat and channelHints for typed channel delivery intent.
• PluginControlUiDescriptor.suppressHostInputWhile carried through registry and Gateway descriptors.
• PluginSessionTurnScheduleParams.tag and payloadExtras.
• unscheduleSessionTurnsByTag(...) for deterministic plugin-owned scheduled turn cleanup.
• PluginSessionExtensionRegistration.sessionEntrySlotKey and sessionEntrySlotSchema for safe slot projection.
• Telegram formatting helper re-exports from the public extension API.

Hardening Included

Area	Before	After
SessionEntry slot projection	Plugin slot keys could collide with core session fields.	Slot keys are validated against reserved keys before projection.
Tagged scheduler cleanup	Explicit names could bypass tag cleanup.	Tagged jobs keep the host-owned prefix; explicit names become deterministic suffixes.
Terminal cleanup waits	Slow cleanup could time out silently.	Timeout path warns before clearing host run context.
Trusted policy reads	Session extension cache was scoped too narrowly.	Cache is shared across policy evaluation by plugin/namespace.
Descriptor projection	suppressHostInputWhile could be dropped before Gateway clients.	Registry, schema, and generated clients preserve the descriptor field.
Attachment hints	Resolved parse/silent/thread hints were not fully plumbed.	Outbound message surfaces receive the typed resolved hints.
QA channel API	Runtime types could depend on private plugin-sdk subpaths.	Values and types are exported through public @openclaw/qa-channel API.

Review Guide

Suggested review order:

1. Runtime read surface: src/plugins/host-runtime-namespace.ts, src/plugins/host-hook-runtime.ts, src/infra/agent-events.ts.
2. Tool param derivation: src/agents/apply-patch-paths.ts, src/plugins/host-tool-param-parsers.ts, src/agents/pi-tools.before-tool-call.ts.
3. Workflow extension seams: src/plugins/host-hook-workflow.ts, src/plugins/host-hooks.ts, src/plugins/api-builder.ts, src/plugins/types.ts.
4. Session projection safety: src/plugins/session-entry-slot-keys.ts, src/plugins/host-hook-state.ts, registry validation.
5. Protocol/client projection: src/gateway/protocol/schema/plugins.ts, generated Swift models.
6. Tests: src/plugins/contracts/host-runtime-reads.contract.test.ts, src/plugins/contracts/sdk-seam-followups.contract.test.ts, focused unit tests.

Validation

Local validation from the cleaned follow-up branch before the latest #73384 restack:

pnpm test src/plugins/contracts/host-runtime-reads.contract.test.ts src/plugins/contracts/sdk-seam-followups.contract.test.ts src/plugins/host-runtime-namespace.test.ts src/plugins/host-tool-param-parsers.test.ts src/agents/apply-patch-paths.test.ts extensions/telegram/api.test.ts
# passed: 3 Vitest shards, 55 tests

pnpm plugin-sdk:api:check
# passed

pnpm lint
# passed

pnpm tsgo:all
# passed

pnpm check:import-cycles
# passed: 0 runtime value cycles

git diff --check
# passed

Current pushed head after the latest restack: 09253bf6919743e65d5709cf31abf2bd9166cda5. Treat GitHub CI on that head as the exact-head signal until #73384 lands and this draft is rebased onto main.

Maintainer Notes

• This is draft because [plugin sdk] Consolidate workflow seams and fixtures #73384 is still the active base PR.
• Please do not merge this draft as-is while [plugin sdk] Consolidate workflow seams and fixtures #73384 is open; the final ready-for-review form should be rebased onto main after [plugin sdk] Consolidate workflow seams and fixtures #73384 lands.
• The closed [plugin sdk] sdk seam followups 6 seams stacked on #73384 #73526 was intentionally abandoned because its diff became dirty/noisy. This draft is the cleaned single-commit replacement branch.
• Rollback is a normal revert. No DB migration is expected; the added surfaces are optional/additive.

Issue / RFC Linkage

• Depends on [plugin sdk] Consolidate workflow seams and fixtures #73384 and the merged host-hook foundation [plugin sdk] Add generic plugin host-hook contracts #72287.
• Follow-up context: RFC [plugin sdk] docs: plugin host hook RFC #71731 and parity oracle Plan Mode rebased onto upstream/main + executing-state subsystem #71676.
• Extends the host-hook/RFC family with generic SDK seams: [RFC] Plugin session extensions and patch actions #71732 session-entry slot projection, [RFC] Durable next-turn injections and agent turn preparation hooks #71733/[RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions #71737 host runtime reads and lifecycle context, [RFC] Control UI plugin contribution slots #71736 descriptor input-suppression metadata, and scheduler tag cleanup for lifecycle-owned scheduled work.
• Does not close the broader Control UI contribution-slot/native-page work in [RFC] Control UI plugin contribution slots #71736 or [Feature]: Plugin UI Extension System — Allow Plugins to Contribute Native Pages to Control UI #66944.
• Does not implement the separate tool capability/provenance proposals [Feature]: Add optional capability descriptors to tool definitions #48510, [Feature]: Enrich before_tool_call event with action classification and input provenance #48503, or [Feature]: Tool security classification properties (isDestructive, isReadOnly, isConcurrencySafe) #62962, nor writable prompt mutation in [Feature]: Support writable user prompt modification in existing Plugin SDK hooks #74015.

[clawsweeper]

Codex review: found issues before merge.

What this changes:

The PR branch adds additive Plugin SDK and Gateway surfaces for host runtime reads, derived tool paths, attachment hints, Control UI input-suppression descriptors, tagged scheduled-turn cleanup, session-entry slot projection, session actions, QA boundary cleanup, generated Swift clients, and contract tests.

Maintainer follow-up before merge:

Maintainer next action: keep this as a normal active draft PR, have the author fix the stale tagged-unscheduling guard on the PR branch, resolve/rebase after #73384, and then rerun the expected SDK/protocol validation; this is not a separate ClawSweeper repair lane candidate.

Security review:

Security review cleared: The diff touches CI workflow defaults, Gateway scope classification, generated clients, and plugin SDK surfaces, but I found no concrete new supply-chain, secret, dependency, action-ref, or downloaded-code execution concern.

Review findings:

• [P2] Gate tag unscheduling on live plugin state — src/plugins/registry.ts:2506-2513

Review details

Best possible solution:

Keep the draft available for maintainer and author review, fix the stale-registry guard in tagged unscheduling, resolve and rebase after #73384, preserve the channel/tool-agnostic design questions from discussion, then rerun the focused SDK, protocol, generated-client, lint, type, and changed-lane validation before marking it ready.

Do we have a high-confidence way to reproduce the issue?

Yes for the review finding: retain a plugin API object from a retired registry, load a replacement registry with tagged scheduled turns for the same plugin/session, then call unscheduleSessionTurnsByTag on the stale API object. The PR head reaches cron.list and cron.remove without the live-plugin guard; this is not an end-user reproduction because the item is a draft SDK PR.

Is this the best way to solve the issue?

No, this is not mergeable as-is. The additive SDK direction fits the plugin boundary, but tagged unscheduling needs the same live side-effect guard used by the sibling workflow APIs, and the branch should be reviewed again after #73384 lands or is otherwise resolved.

Full review comments:

• [P2] Gate tag unscheduling on live plugin state — src/plugins/registry.ts:2506-2513
scheduleSessionTurn, sendSessionAttachment, and emitAgentEvent all stop stale API objects with shouldCommitWorkflowSideEffect, but unscheduleSessionTurnsByTag skips that guard before reaching cron.list/cron.remove. A plugin API object retained from a retired registry can remove current-generation tagged jobs for the same plugin/session after reload; pass the guard into the helper or check it before listing/removing cron jobs.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.84

Acceptance criteria:

• pnpm test src/plugins/contracts/host-runtime-reads.contract.test.ts src/plugins/contracts/sdk-seam-followups.contract.test.ts src/plugins/host-runtime-namespace.test.ts src/plugins/host-tool-param-parsers.test.ts src/agents/apply-patch-paths.test.ts extensions/telegram/api.test.ts
• pnpm plugin-sdk:api:check
• pnpm lint
• pnpm tsgo:all
• pnpm check:import-cycles

What I checked:

• PR state: GitHub API reports this PR is open, draft, unmerged, dirty/stacked, and currently at head 09253bf. (09253bf69197)
• Stack dependency remains open: GitHub API reports [plugin sdk] Consolidate workflow seams and fixtures #73384 is still open and unmerged at head 9e8cf8c, matching this PR body's draft/stack warning. (9e8cf8cb7170)
• Current main lacks requested SDK surfaces: Current main has the older PluginSessionExtensionRegistration and PluginControlUiDescriptor shapes without sessionEntrySlotKey, suppressHostInputWhile, attachment hints, scheduled-turn APIs, or session-action APIs. (src/plugins/host-hooks.ts:37, 4429ee7d2e7f)
• Current main lacks host runtime and derived path hook context: Current main's PluginHookToolContext and PluginHookBeforeToolCallEvent expose tool/session/run metadata but do not include getHostRunContext, getSessionExtension, or derivedPaths. (src/plugins/hook-types.ts:393, 4429ee7d2e7f)
• Current main Gateway schema is still pre-follow-up: PluginControlUiDescriptorSchema is closed with additionalProperties false and does not include renderer, stateNamespace, actionIds, suppressHostInputWhile, or plugins.sessionAction params/result schemas. (src/gateway/protocol/schema/plugins.ts:6, 4429ee7d2e7f)
• Functional review finding: At PR head, emitAgentEvent, scheduleSessionTurn, and sendSessionAttachment use shouldCommitWorkflowSideEffect, but unscheduleSessionTurnsByTag calls unschedulePluginSessionTurnsByTag without passing or checking that live-plugin guard. (src/plugins/registry.ts:2506, 09253bf69197)

Likely related people:

• 100yenadmin: GitHub API shows 100yenadmin authored the merged [plugin sdk] Add generic plugin host-hook contracts #72287 generic host-hook foundation and the open [plugin sdk] Consolidate workflow seams and fixtures #73384 workflow stack; this PR is the explicit follow-up to that feature family rather than an unrelated proposal. (role: introduced adjacent foundation and current SDK follow-up owner; confidence: high; commits: 1adaa28dc86b, 9e8cf8cb7170, 09253bf69197; files: src/plugins/host-hooks.ts, src/plugins/types.ts, src/plugins/registry.ts)
• Josh Lehman: The [plugin sdk] Add generic plugin host-hook contracts #72287 commit list includes several late foundation stabilization commits by Josh Lehman around host-hook changelog placement, prepare-gate drift, and plugin runtime lint expectations, making them relevant to the merged base this draft extends. (role: adjacent merged foundation contributor; confidence: medium; commits: 643329a5a2de, cc0c3fd48f47, 547c3f43b1a3; files: src/plugins/host-hooks.ts, src/plugins/types.ts, docs/.generated/plugin-sdk-api-baseline.sha256)
• 1fanwang: The PR discussion includes a focused review from 1fanwang endorsing the seam direction while calling out channel/tool agnosticism questions that should be preserved for the post-rebase review. (role: reviewer / adjacent maintainer signal; confidence: medium; files: src/plugins/host-hooks.ts, src/plugins/host-tool-param-parsers.ts, src/gateway/protocol/schema/plugins.ts)

Remaining risk / open question:

• The branch is draft/dirty and stacked on open [plugin sdk] Consolidate workflow seams and fixtures #73384, so the final merge shape, generated SDK/protocol artifacts, and validation are expected to change after rebase.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4429ee7d2e7f.

[1fanwang]

+1 on the seam set. The descriptor + registry shape — _host.runtime read-only namespace, scheduler tag taxonomy + unscheduleSessionTurnsByTag, SessionEntry slot projection with reserved-key validation, suppressHostInputWhile carried through Gateway descriptors — all read as the right kind of additive surface for plugin authors composing on top of #73384.

Two "what stays channel/tool-agnostic" questions I'd want to look at once this rebases onto fresh main and is out of draft, mostly around keeping channel- or tool-specific shape from creeping into the generic SDK:

1. How is channelHints typed? If it grows as a per-channel keyed schema ({ telegram?: ..., line?: ... }), every new channel hint vocabulary lands on the generic SDK schema; a more open shape (validated at the channel side) would let channel plugins ship their hint vocabulary inside the channel extension.
2. Is derivedPaths strictly plumbed through the parser registry such that the apply_patch parser itself could ship as a plugin if a host wanted to keep core tool-agnostic? Sounds like it from the description, but worth confirming so future tool-specific derivations don't accumulate in core.

Neither is a blocker for this draft — flagging now so they don't get lost when this goes ready-for-review.

[100yenadmin]

Closing this consolidated stack in favor of individual hook/seam PRs. The code has been through hardening, but the combined PR became too large and brittle against fast-moving upstream main plugin sprint leading to messy additional debugging. Splitting it back into focused fresh-main PRs should reduce reviewer load, isolate CI failures, and make each generic SDK seam independently mergeable even if main shifts.

[100yenadmin]

Closing this consolidated stack in favor of individual hook/seam PRs. The code has been through hardening, but the combined PR became too large and brittle against fast-moving upstream main. Splitting it into focused fresh-main PRs should reduce reviewer load, isolate CI failures, and make each generic SDK seam independently mergeable.

Replacement slices opened so far:

1. [plugin sdk] Add session action gateway protocol #75578 — Session actions + Gateway protocol
2. [plugin sdk] Add host-mediated session attachments #75581 — Host-mediated attachments
3. [plugin sdk] Add scheduled session turns #75588 — Scheduled turns + cleanup
4. [plugin sdk] Harden finalize retry and run context cleanup #75600 — Finalize retry + run context lifecycle
5. [plugin sdk] Derive tool target paths for hooks #75605 — Tool-derived path facts
6. [plugin sdk] Project session extension slots #75609 — SessionEntry slot projection

The advanced workflow fixture slice should be filed after these seams land on main; opening it now from fresh main would fail before the public seams exist, while stacking or duplicating those seams would recreate the brittle consolidated PR this split is replacing.

Docs remain split in #74853; foundation remains merged #72287.