Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [RFC] Plugin session extensions and patch actions [1 pull requests, 1 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#71732•Fetched 2026-04-26 05:09:10
View on GitHub
Comments
1
Participants
1
Timeline
2
Reactions
0
Author
100yenadmin100yenadmin
Participants
100yenadmin100yenadmin
Timeline (top)
commented ×1cross-referenced ×1

Add a namespaced plugin session extension API so plugins can persist typed per-session state, expose an explicit public projection to gateway/UI clients, and mutate that state through gateway-authorized patch actions.

This is proposed SDK surface, not currently implemented API.

Error Message

  • Stable error codes for unknown plugin, unknown action, invalid payload, disabled plugin, and handler failure.

Root Cause

Plan Mode is the forcing case: PR #71676 adds root SessionEntry fields and hardcoded sessions.patch behavior. A first-class plugin needs the same durability, validation, projection, broadcast, and lifecycle behavior without Plan Mode-specific core fields.

The same host seam is reusable for any plugin that owns per-session workflow state: review gates, release/deploy workflows, memory/context managers, incident/ticket bots, cost governors, channel bindings, telemetry exporters, and workspace policy plugins.

Fix Action

Fix / Workaround

Add a namespaced plugin session extension API so plugins can persist typed per-session state, expose an explicit public projection to gateway/UI clients, and mutate that state through gateway-authorized patch actions.

Plan Mode is the forcing case: PR #71676 adds root SessionEntry fields and hardcoded sessions.patch behavior. A first-class plugin needs the same durability, validation, projection, broadcast, and lifecycle behavior without Plan Mode-specific core fields.

OpenClaw currently has fixed core session state, fixed sessions.patch, hardcoded gateway session rows, an internal post-write session:patch hook, and plugin gateway RPCs with declared scopes.

PR fix notes

PR #71731: docs: add Plan Mode plugin host hook RFC

Description (problem / solution / changelog)

Summary

This PR is a maintainer RFC package for making Plan Mode a first-class bundled plugin without merging the large host patch from #71676.

  • Problem: #71676 proves Plan Mode behavior, but it embeds the feature across session state, gateway patching, agent turn preparation, pending injections, tool policy, commands, Control UI, agent events, scheduler/cron, heartbeat prompts, docs, QA, and channel flows.
  • Why it matters: maintainers prefer a plugin path. A plugin port cannot reach 100% parity unless OpenClaw first exposes generic host seams in the plugin SDK.
  • What changed: added an RFC packet, public index page, six issue-sized RFC threads, current-SDK gap research, reusable plugin matrices, a #71676 entry-point coverage map, and fixture-test expectations for a future implementation PR.
  • What did NOT change: this PR intentionally does not implement hooks, Plan Mode behavior, prompts, tools, UI cards, session fields, scheduler changes, or runtime SDK APIs.

RFC Status Warning

This is proposed SDK design, not implemented SDK reference. The docs now include explicit warning callouts, and the public page has been moved out of SDK reference into a dedicated Plugin design RFCs nav group.

RFC Decision Threads

  • #71732 — Plugin session extensions and patch actions
  • #71733 — Durable next-turn injections and agent turn preparation hooks
  • #71734 — Trusted tool policy stage and plugin tool metadata
  • #71735 — Scoped plugin commands, trusted command ownership, and continuation
  • #71736 — Control UI plugin contribution slots
  • #71737 — Agent events, run context, scheduler lifecycle, and heartbeat contributions

The issue bodies have been expanded so each thread includes: proposed/not-implemented status, current SDK surface, missing host seam, Plan Mode parity use, reusable non-Plan plugin examples, decisions needed, and fixture acceptance criteria.

RFC Contents

The full RFC packet covers:

  • current SDK research against existing hooks, using #71427 as the comparison bar
  • reusable SDK capability matrix across public SDK, trusted/bundled SDK, gateway protocol, UI descriptors, runner boundary, lifecycle cleanup, and fixture tests
  • plugin archetype matrix for approval workflows, deploy/release, budget guards, memory/context, review/CI, incidents/tickets, channel integrations, workspace policy, telemetry/exporters, and long-running jobs
  • #71676 entry-point coverage map for Plan Mode parity
  • per-hook TypeScript-shaped API sketches
  • expected host files for each implementation slice
  • authorization, trust-tier, disablement, cleanup, and failure semantics
  • fixture-plugin acceptance tests for the future hook implementation PR
  • Plan Mode migration sequence and parity checklist

Change Type

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Related #71676
  • Related #71732
  • Related #71733
  • Related #71734
  • Related #71735
  • Related #71736
  • Related #71737
  • This PR fixes a bug or regression

Verification

Verified locally:

  • pnpm format:docs:check
  • pnpm lint:docs
  • pnpm docs:check-mdx
  • pnpm docs:check-links

Human Verification

  • Confirmed the docs nav no longer places the proposal under stable SDK reference.
  • Confirmed both docs pages warn that the named APIs are proposed, not implemented.
  • Confirmed the RFC packet includes a #71676 entry-point coverage map.
  • Confirmed all six live issue bodies are expanded beyond Plan Mode-only examples.
  • Did not run runtime Plan Mode behavior because this PR is docs/RFC-only and implements no hooks.

Compatibility / Migration

  • Backward compatible? Yes, docs-only.
  • Config/env changes? No.
  • Migration needed? No.

Risks and Mitigations

  • Risk: reviewers mistake the RFC for implemented SDK reference.
    • Mitigation: warning callouts plus Plugin design RFCs nav placement.
  • Risk: proposal appears Plan Mode-specific.
    • Mitigation: reusable SDK matrices, non-Plan plugin examples, and expanded issue bodies.
  • Risk: proposal overclaims parity.
    • Mitigation: #71676 entry-point coverage map and explicit note that actual parity requires the future hook implementation PR plus fixture tests.

Next Step After This PR

If maintainers accept the RFC direction, the next PR should implement the generic host hooks with a tiny fixture plugin. Only after that should Plan Mode itself move into a bundled plugin and be audited against #71676 for parity.

Changed files

  • docs/docs.json (modified, +4/-0)
  • docs/plan/plan-mode-plugin-host-hooks-rfc.md (added, +1289/-0)
  • docs/plugins/plan-mode-plugin-host-hooks.md (added, +492/-0)

Code Example

api.registerSessionExtension({
  key,
  schema,
  publicProjection,
  patchActions,
  lifecycle,
});
RAW_BUFFERClick to expand / collapse

Summary

Add a namespaced plugin session extension API so plugins can persist typed per-session state, expose an explicit public projection to gateway/UI clients, and mutate that state through gateway-authorized patch actions.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode is the forcing case: PR #71676 adds root SessionEntry fields and hardcoded sessions.patch behavior. A first-class plugin needs the same durability, validation, projection, broadcast, and lifecycle behavior without Plan Mode-specific core fields.

The same host seam is reusable for any plugin that owns per-session workflow state: review gates, release/deploy workflows, memory/context managers, incident/ticket bots, cost governors, channel bindings, telemetry exporters, and workspace policy plugins.

Current SDK surface

OpenClaw currently has fixed core session state, fixed sessions.patch, hardcoded gateway session rows, an internal post-write session:patch hook, and plugin gateway RPCs with declared scopes.

Those surfaces are useful but insufficient: a plugin can expose a separate RPC, but it cannot register typed session state that participates in native session patch, projection, broadcast, reset, delete, compaction, and disabled-plugin semantics.

Proposed solution

Add a generic registration surface such as:

api.registerSessionExtension({
  key,
  schema,
  publicProjection,
  patchActions,
  lifecycle,
});

Patch routing can be either a dedicated sessions.pluginPatch method or an additive sessions.patch.plugin envelope. Maintainers should choose one shape before implementation.

Reusable plugin examples

  • Plan Mode stores mode, approval status, question state, pending injection ids, blocking subagent ids, and nudge job ids.
  • Review gates store PR id, unresolved findings, reviewer decisions, and merge gate state.
  • Release plugins store environment, rollout phase, freeze window, and rollback id.
  • Memory plugins store pins, recall cursors, compaction policy, and source visibility.
  • Budget governors store spend counters, thresholds, override decisions, and expiry.
  • Channel plugins store thread bindings, delivery preferences, and auth handoff state.
  • Incident bots store severity, owner, ticket sync cursor, and SLA deadline.

Decisions needed

  • sessions.pluginPatch method vs sessions.patch.plugin envelope.
  • Public projection shape for session list/detail rows.
  • Patch action schema and handler typing.
  • Lifecycle hooks for reset, delete, compaction, migration, and plugin disablement.
  • Stable error codes for unknown plugin, unknown action, invalid payload, disabled plugin, and handler failure.
  • Gateway scope declaration and host enforcement model for patch actions.

Acceptance criteria

  • A fixture plugin can persist extension state.
  • Invalid payload fails closed without writing state.
  • Public projection appears in session rows/details.
  • Private extension fields do not leak.
  • Reset/delete/compaction lifecycle clears extension state.
  • Disabled plugin extension cannot be patched or projected.
  • Gateway scopes are enforced by the host before the plugin handler runs.

References

extent analysis

TL;DR

Implement a namespaced plugin session extension API to enable plugins to persist typed per-session state and expose it to gateway/UI clients.

Guidance

  • Define the api.registerSessionExtension method with required parameters such as key, schema, publicProjection, patchActions, and lifecycle to register a plugin's session extension.
  • Choose between a dedicated sessions.pluginPatch method or an additive sessions.patch.plugin envelope for patch routing.
  • Determine the public projection shape for session list/detail rows and patch action schema and handler typing.
  • Establish lifecycle hooks for reset, delete, compaction, migration, and plugin disablement to ensure proper state management.

Example

api.registerSessionExtension({
  key: 'myPlugin',
  schema: {
    type: 'object',
    properties: {
      mode: { type: 'string' },
      approvalStatus: { type: 'boolean' },
    },
  },
  publicProjection: {
    mode: true,
    approvalStatus: true,
  },
  patchActions: [
    {
      action: 'updateMode',
      schema: {
        type: 'object',
        properties: {
          mode: { type: 'string' },
        },
      },
    },
  ],
  lifecycle: {
    reset: () => {},
    delete: () => {},
  },
});

Notes

The implementation of the proposed solution requires careful consideration of the design decisions outlined in the "Decisions needed" section, including patch routing, public projection shape, and lifecycle hooks.

Recommendation

Apply the proposed solution by implementing the api.registerSessionExtension method and defining the required parameters, as it provides a flexible and extensible way for plugins to manage per-session state.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#tensor shape#autograd error#model save/load#optimization

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [RFC] Plugin session extensions and patch actions [1 pull requests, 1 comments, 1 participants]