[docs][plugin sdk] Split host-hook recipes from workflow follow-ups by 100yenadmin · Pull Request #74853 · openclaw/openclaw

100yenadmin · 2026-04-30T04:41:06Z

Summary

This PR splits the large host-hook recipe documentation out of the implementation stack so maintainers can review code/tests and docs separately. It carries the product-neutral recipe page, docs navigation entry, and zh-CN glossary entries that were previously part of #73384.

Why This Exists

The implementation PRs are already substantial, and the recipe page adds about 2.7k lines of prose/examples/diagrams by itself. Splitting it keeps the review surfaces smaller:

[plugin sdk] Consolidate workflow seams and fixtures #73384 after split: implementation/tests/generated protocol only, ~4,542 additions / 151 deletions across 68 files.
[plugin sdk] Add generic SDK seam followups #74483 after restack: one follow-up commit, ~2,027 additions / 26 deletions across 41 files.
This docs PR: ~2,680 additions / 0 deletions across 3 docs files.

Scope

Adds docs/plugins/host-hooks-examples.md.
Adds the page to docs/docs.json.
Adds zh-CN glossary labels for the page title/sidebar.
Keeps the examples SDK-wide and product-neutral: approval flows, policy gates, background monitors, setup wizards, review assistants, and release workflows.

Stack Order

Review/merge order should be:

[plugin sdk] Consolidate workflow seams and fixtures #73384 - workflow seams, fixtures, and host-hook runtime hardening.
[plugin sdk] Add generic SDK seam followups #74483 - generic SDK seam follow-ups.
This docs PR - recipe map for the additive SDK surfaces.

The docs intentionally reference APIs introduced by the implementation stack, so this PR should land after those implementation PRs.

Validation

pnpm docs:list

[plugin sdk] docs: plugin host hook RFC #71731 RFC context for the host-hook capability requirements.
[RFC] Plugin session extensions and patch actions #71732, [RFC] Durable next-turn injections and agent turn preparation hooks #71733, [RFC] Trusted tool policy stage and plugin tool metadata #71734, [RFC] Scoped plugin commands, trusted command ownership, and continuation #71735, [RFC] Control UI plugin contribution slots #71736, and [RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions #71737 are the RFC issue threads this recipe page maps back to.
[plugin sdk] Add generic plugin host-hook contracts #72287 merged the generic host-hook foundation.
[plugin sdk] Consolidate workflow seams and fixtures #73384 carries the workflow seams / fixtures implementation follow-up.
[plugin sdk] Add generic SDK seam followups #74483 carries the draft generic SDK seam follow-up.
[RFC] Control UI plugin contribution slots #71736 remains open for broader Control UI contribution-slot/native-page design; this docs PR should land only after the implementation stack it describes.

clawsweeper · 2026-04-30T04:45:47Z

Codex review: needs maintainer review before merge.

Summary
The PR adds a product-neutral host-hook examples recipe page, docs navigation and zh-CN glossary entries, plus small plugin SDK docs updates for current and companion host-hook surfaces.

Reproducibility: not applicable. this is a docs PR rather than a runtime bug. I source-checked the PR content against current main contracts and Gateway behavior instead of exercising a failing reproduction.

Next step before merge
Maintainer action is ordinary review, final CI, and verifying that companion host-hook implementation PRs are merged or intentionally referenced before publishing the docs.

Security
Cleared: The diff is limited to documentation, navigation, and glossary text, with no workflow, dependency, script, secret, or package-resolution changes.

Review details

Best possible solution:

Land the docs recipe split after the companion host-hook implementation stack is ready, keeping future APIs labeled and stable examples matched to current contracts.

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

Not applicable; this is a docs PR rather than a runtime bug. I source-checked the PR content against current main contracts and Gateway behavior instead of exercising a failing reproduction.

Is this the best way to solve the issue?

Yes. A docs-only split is the maintainable review shape for this large recipe page, with the safe path being companion-stack merge ordering and explicit labels for APIs not yet on stable main.

Acceptance criteria:

pnpm docs:list
pnpm check:docs
pnpm format:docs:check
git diff --check
npm run check:no-conflict-markers

What I checked:

PR scope: GitHub reports the latest head 6fea20f changes five docs files with 2831 additions and 8 deletions: glossary, docs navigation, hooks docs, the new host-hook recipe page, and SDK overview. (6fea20fb1995)
Current main does not implement the docs split: Current main has no docs/plugins/host-hooks-examples.md and docs/docs.json still lists plugins/hooks followed by SDK channel/provider pages without the new host-hooks-examples page. Public docs: docs/docs.json. (docs/docs.json:1204, 90a5b08fb799)
Companion-only APIs are labeled: The new recipe page explicitly says session actions, host-mediated attachments, scheduled turn helpers, and guarded SessionEntry slot mirrors are companion PR surfaces not available on current stable main until those PRs merge. Public docs: docs/plugins/host-hooks-examples.md. (docs/plugins/host-hooks-examples.md:97, 6fea20fb1995)
Current contract comparison: Current main exposes the stable host-hook API methods listed by the docs, while registerSessionAction, sendSessionAttachment, and scheduleSessionTurn do not appear in the current OpenClawPluginApi search results. (src/plugins/types.ts:2479, 90a5b08fb799)
Gateway behavior alignment: Current main enforces operator.admin for sessions.pluginPatch, returns { ok, key, value }, emits a sessions change, and projects GatewaySessionRow.pluginExtensions as an array built by projectPluginSessionExtensionsSync. (src/gateway/server-methods/sessions.ts:1542, 90a5b08fb799)
Prior blockers addressed in latest head: The latest recipe page uses pluginExtensions[] array-safe source selectors and marks session action, attachment, scheduled turn, and emitAgentEvent sections as companion or non-current stable API surfaces. Public docs: docs/plugins/host-hooks-examples.md. (docs/plugins/host-hooks-examples.md:1334, 6fea20fb1995)

Likely related people:

100yenadmin: The PR body and related context tie this docs split to the merged generic host-hook foundation and the companion host-hook RFC/implementation stack that 100yenadmin has been carrying. (role: current stack owner and introduced behavior; confidence: high; commits: 68e5f2ce1913, 6fea20fb1995; files: docs/plugins/host-hooks-examples.md, src/plugins/host-hooks.ts, src/plugins/contracts/host-hooks.contract.test.ts)
jalehman: Josh Lehman authored the PR commit that documents session entry slots, and related review context identifies jalehman as a merger/reviewer of the host-hook foundation and current contract stabilization work. (role: recent host-hook maintainer; confidence: medium; commits: 8e0f581d5086; files: docs/plugins/hooks.md, docs/plugins/sdk-overview.md, src/plugins/host-hooks.ts)
Peter Steinberger: Current-main blame and shallow history show Peter Steinberger on the grafted commit that introduced the visible host-hook docs/types baseline in this checkout. (role: recent main maintainer; confidence: medium; commits: f74e901794c1; files: src/plugins/host-hooks.ts, docs/plugins/sdk-overview.md, src/plugins/contracts/host-hooks.contract.test.ts)

Remaining risk / open question:

The docs intentionally reference companion SDK surfaces, so merging before those implementation PRs are accepted could publish future API guidance despite the availability notes.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 90a5b08fb799.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57098df02f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a new Plugin SDK documentation page that collects host-hook “recipe” examples and wires it into the docs navigation + zh-CN glossary, enabling maintainers and plugin authors to reference composition patterns separately from the implementation PR stack.

Changes:

Added docs/plugins/host-hooks-examples.md (host-hook recipes/examples page).
Added the page to docs/docs.json navigation.
Added zh-CN glossary entries for the page title and sidebar label.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/plugins/host-hooks-examples.md	New long-form host-hook recipes page with contracts, examples, diagrams, and archetype compositions.
docs/docs.json	Adds the new page to the Plugins section nav.
docs/.i18n/glossary.zh-CN.json	Adds zh-CN glossary translations for the new page title/sidebar strings.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c04613815

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e66eb5cc1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 22618273b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-03T20:49:38Z

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.

100yenadmin · 2026-05-03T21:42:46Z

Fixed in 6fea20fb19959c7d5d22c2132729dcf699e511d7. The minimal copyable registerSessionExtension example no longer uses companion-only sessionEntrySlotKey / sessionEntrySlotSchema, and the meter descriptor prose no longer claims web/macOS/iOS ship a stable renderer; it is framed as a companion-client implementation contract. Test: pnpm docs:list; pnpm check:docs; pnpm format:docs:check; git diff --check; npm run check:no-conflict-markers.

chatgpt-codex-connector · 2026-05-03T21:42:48Z

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.

openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Apr 30, 2026

This was referenced Apr 30, 2026

[plugin sdk] Consolidate workflow seams and fixtures #73384

Closed

[plugin sdk] Add generic SDK seam followups #74483

Closed

100yenadmin marked this pull request as ready for review April 30, 2026 04:48

Copilot AI review requested due to automatic review settings April 30, 2026 04:48

Copilot started reviewing on behalf of 100yenadmin April 30, 2026 04:48 View session

chatgpt-codex-connector Bot reviewed Apr 30, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin force-pushed the docs/plugin-sdk-host-hook-recipes-split branch from 57098df to 268b469 Compare April 30, 2026 09:35

This was referenced Apr 30, 2026

[plugin sdk] docs: plugin host hook RFC #71731

Closed

[RFC] Control UI plugin contribution slots #71736

Open

clawsweeper Bot mentioned this pull request Apr 30, 2026

[Feature]: Shortcut/Keyword Sidebar Panel #46630

Open

100yenadmin requested a review from Copilot May 1, 2026 06:56

Copilot started reviewing on behalf of 100yenadmin May 1, 2026 06:57 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 1, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

chatgpt-codex-connector Bot reviewed May 1, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin requested a review from Copilot May 1, 2026 13:44

Copilot started reviewing on behalf of 100yenadmin May 1, 2026 13:44 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin requested a review from Copilot May 1, 2026 13:52

Copilot started reviewing on behalf of 100yenadmin May 1, 2026 13:52 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin requested review from Copilot May 1, 2026 14:55

Copilot started reviewing on behalf of 100yenadmin May 1, 2026 14:56 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md Outdated

Comment thread docs/plugins/host-hooks-examples.md

100yenadmin force-pushed the docs/plugin-sdk-host-hook-recipes-split branch from 16c0627 to 2261827 Compare May 3, 2026 19:04

chatgpt-codex-connector Bot reviewed May 3, 2026

View reviewed changes

Comment thread docs/plugins/host-hooks-examples.md Outdated

100yenadmin force-pushed the docs/plugin-sdk-host-hook-recipes-split branch from 3b44b32 to 2ce45c2 Compare May 3, 2026 20:08

Eva and others added 6 commits May 4, 2026 03:48

docs(plugin-sdk): split host-hook recipes

1246e0e

docs(plugin-sdk): align host hook recipes with contracts

547231b

docs(plugin-sdk): remove unavailable host hook APIs

2318d09

docs(plugin-sdk): document session entry slots

8e0f581

docs: align host hook recipes with current contracts

78f6266

docs: use array-safe plugin extension paths

07fe0d2

100yenadmin force-pushed the docs/plugin-sdk-host-hook-recipes-split branch from 2ce45c2 to 07fe0d2 Compare May 3, 2026 20:49

docs: keep host hook examples on stable contracts

6fea20f

Uh oh!

Conversation

100yenadmin commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why This Exists

Scope

Stack Order

Validation

Related

Uh oh!

clawsweeper Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented May 3, 2026

Uh oh!

100yenadmin commented May 3, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 3, 2026

Uh oh!

Reviewers

100yenadmin commented Apr 30, 2026 •

edited

Loading

clawsweeper Bot commented Apr 30, 2026 •

edited

Loading