Return boolean from every plugin SDK openPanel

[ymichael]

What was wrong

The plugin SDK had four ways to ask the host to open a panel, and they disagreed on how to report failure. PluginMessageActionContext.openPanel and useBbNavigate().openThreadPanel returned boolean; PluginThreadPanelActionContext.openPanel and PluginNewThreadPanelActionContext.openPanel returned void. Invalid params compounded it — that threw out of openPanel on the panel-action path but returned false on the message-action path, so the same mistake surfaced two different ways.

Those four are really two operations, each existing twice for surface reasons: open the panel I already am (no actionId — you are inside a panel action's run), available on the thread panel and the New thread screen; and open a panel I am not (actionId required), available as a callback context and as a hook. Nothing about that split required the return types to diverge — they diverged because each was declared independently.

The inconsistency also leaked into plugin code. plugins/side-chat/app.tsx shares one helper across two of those entry points, so it typed the injected openPanel as returning unknown — the only type that fits both a boolean and nothing — discarding a result it had no way to describe.

This PR does not fix a user-facing bug. An earlier revision added handling for a declined open in side chat; slopcop correctly pointed out that path is unreachable, and it has been removed. PluginThreadChat passes includePluginMessageActions={false}, and ThreadTimelineRows swaps in an empty slot snapshot when that is false, so a plugin messageAction never renders inside a plugin's own ThreadChat. Every surface that does render them supplies onOpenPluginPanel. This is a contract cleanup.

What changed

packages/plugin-sdk/src/app-contract.ts — both panel-action openPanels now return boolean, matching the other two. The doc comments state one rule: true accepted, false declined, never a throw. The two operations now share types that name them: PluginPanelActionOpenOptions ({ title?, params? }) for a panel action opening its own tab, and PluginTargetedPanelActionOpenOptions, which extends it with actionId, for a caller that is not itself a panel action. useBbNavigate().openThreadPanel previously inlined a shape identical to the latter and now uses it.

apps/app/src/components/plugin/PluginPanelActions.tsx — both panel-action closures go through one createPanelActionOpenPanel helper that catches non-JSON params, warns, and returns false rather than throwing into run, where the host swallows it. apps/app/src/lib/plugin-message-actions.ts — the no-side-panel branch returned false silently and now warns, so all three decline paths are diagnosable from the console.

plugins/side-chat/app.tsx — the injected openPanel is typed boolean instead of unknown, removing the cast that existed only to bridge the two old signatures. Nothing reads the result, and a comment records why.

Generated files were regenerated by script, not hand-edited: bundled-types/ via scripts/build-bundled-dts.mjs, and @bb/templates's embedded copy of the SDK .d.ts via generate-templates.mjs. That second one matters — its --check runs inside @bb/templates's typecheck and test, and would otherwise fail CI. Docs updated in packages/plugin-sdk/README.md, docs/api_to_audit.md, and the bb-plugin-authoring skill. No wire changes, so HOST_DAEMON_PROTOCOL_VERSION is unchanged.

What this deliberately does not do is reduce the count or unify the names — openPanel and openThreadPanel remain two names for one idea. That is a rename across the public API and deserves its own decision.

Breaking changes for plugin authors

1. run is declared void | Promise<void>, and boolean is not assignable to that union — TypeScript's void-return exemption applies only to a bare void. So the concise form run: ({ openPanel }) => openPanel({ ... }) no longer typechecks and needs braces:

run: ({ openPanel }) => { openPanel({ ... }); }

Three in-repo call sites and both examples in the authoring skill are fixed. We deliberately did not widen run's return type to absorb this: pre-1.0, a loud one-line compile error is an acceptable cost for keeping the type honest.

2. PluginMessageActionThreadPanelOptions is renamed PluginTargetedPanelActionOpenOptions, since it now describes both of its callers rather than one.

How you verified

• New: an accepted open reports true from both panel-action kinds (plugin-slot-mounts.test.tsx).
• Extended: the existing non-JSON-params test now asserts false is returned rather than thrown.
• Already covered: ThreadTimelineRows.actions.test.tsx:1423 pins messageAction.openPanel → false on a surface with no thread panel.
• pnpm exec turbo run typecheck test lint --filter=@get-bb/plugin-sdk --filter=@bb/templates --filter=bb-plugin-side-chat --filter=@bb/app — 3,041 tests passed, typecheck and lint clean.
• generate-templates.mjs --check verified failing on this branch before the regeneration and passing on main, confirming the staleness was introduced here rather than pre-existing.

Rebased on main after #1851, which made the declaration bundles deterministic; the generated-file conflicts were resolved by regenerating from source rather than by hand.

No issue was filed for this; it was found while reviewing #1457.

AGENT GENERATED: by Claude Opus 5

[bb-slop-cop]

🚨 SLOP COP 🚨 · review

I am the Slop Cop. I am reviewing this pull request now.

I will check security, code quality, architecture, performance, and the main user flow. I will post one final review after these checks finish.

[bb-slop-cop]

🚨 slopcop/review — The bundled declarations changed, but the scaffold copy did not change. The @bb/templates type check fails, and legacy plugin type updates still send the old void contract. Run the template generator and commit its output.

[bb-slop-cop]

🚨 SLOP COP 🚨 · review

Plain English summary: This change lets a plugin know whether BB opened its requested panel. It also adds an error message for a failed side-chat open.

I found two blockers:

• High: The generated scaffold declarations still use the old void return type. The @bb/templates type check fails.
• High: PluginPanelActionOpenOptions adds a stable public SDK export without the required experimental_ prefix and audit entry.

I also found two design concerns:

• The stated side-chat failure path is not reachable. The host disables global message actions inside plugin-hosted chats.
• Two host paths repeat the same validation, serialization, warning, open, and Boolean-return logic. A shared helper can prevent later drift.

Security review found no privilege or input-boundary problem. Performance review found no hot-path regression.

The live browser check passed the normal flow. It created a thread, opened a side chat, sent a reply, and received the reply.

The focused app, SDK, and side-chat tests passed. git diff --check passed. The SDK version guard passed because version 0.4.8 is not published.

The @bb/templates type check failed because the generated SDK template is stale. I posted this review as a comment only, as requested.

[bb-slop-cop]

🚨 slopcop/review — The stated product path does not occur. PluginThreadChat disables global message actions, so the side-chat panel does not show this action. The browser test confirmed this behavior. This direct mock test does not prove a reachable decline path.

[bb-slop-cop]

🚨 slopcop/review — This new public SDK type does not follow the required experimental-name rule. Keep the helper private, or add an experimental_ name and a separate audit entry.