kandev/docs/plans/plugins/PLUGIN-API.md

# Kandev Plugin API contract (native JS UI plugins — "option C")

This is the frozen interface every frontend + example task builds against. Do not
diverge without updating this file.

## Loading model

1. Backend boot payload gains `plugins: ActivePlugin[]` where
   `ActivePlugin = { id: string; name: string; bundleUrl: string; styleUrls?: string[];
repositoryProviderIds?: string[] }`. `repositoryProviderIds` is JSON
   `repositoryProviderIds`, copied from manifest `repository_providers`. It is optional
   only for additive compatibility with older boot payloads; a present empty list means
   the plugin declared no repository providers.
   `bundleUrl` = `/api/plugins/{id}/bundle` — kandev serves this **directly from the
   extracted package directory** on local disk
   (`~/.kandev/plugins/<id>/<version>/ui/...`, per manifest `ui.bundle`). There is no
   reverse proxy and no live upstream request: the plugin subprocess does not need to
   be running to serve the UI bundle, since installation already extracted the file.
   Before importing a bundle, the Host calls authenticated
   `GET /api/plugins/{id}/conversation/binding`. Success returns
   `{bindingToken,generation,expiresAt}` with `expiresAt` RFC3339 UTC; every
   response, including errors, sends `Cache-Control: no-store`. Errors use
   `{ "error": { "code": "...", "message": "...", "retryable": false|true } }`:
   `401/unauthenticated/false`, `404/not_found/false`, and
   `409/generation_superseded/true`. On `401` or `404`, the current load is
   skipped without disabling persisted state; on `409`, binding is retried with
   bounded backoff and import waits for success. Expiry rebinds or aborts. The
   grant remains in a Host-only closure and is never passed to bundle code/public
   API values.
2. On SPA boot, the **plugin host** (`apps/web/lib/plugins/host.ts`) iterates
   `bootPayload.plugins`, injects any `styleUrls` as `<link>`, and dynamically
   `import(/* @vite-ignore */ bundleUrl)` each bundle as a native ES module. Before a
   bundle can initialize, the loader supplies its `repositoryProviderIds` to the
   registry (for example `setDeclaredRepositoryProviderIds(pluginId, ids)`). The scoped
   registry then rejects `registerRepositoryProvider` or `registerReviewProvider` IDs
   outside that declared set. An omitted field preserves older-host compatibility;
   it does not invent provider ownership. Provider IDs are canonical lowercase
   identifiers: the manifest validator and frontend registry reject uppercase or
   otherwise non-canonical variants instead of creating case-dependent ownership.
3. Each bundle, when evaluated, calls the global:
   ```ts
   window.registerKandevPlugin(pluginId, {
     initialize(registry, host): void | Promise<void>,
     destroy?(): void,
   })
   ```
   The loader serializes stages per plugin and creates a private Host-only `(pluginId,generation,stageId,stageToken)` registration context before import. The public `window.registerKandevPlugin(id,plugin)` signature is unchanged; the Host routes each call to the currently open stage context for that plugin ID through an internal import-context handshake (closure-held stage token, never a public argument). Only the open stage's first registration is accepted. Registration after context closure (timeout, failure, or settled stage), a duplicate registration within the same stage, and a call presenting a foreign or retired stage token are rejected without mutating active state; the next stage does not import until the prior import settles.
   Generation lifecycle is `pending -> active -> retired` with one commit linearization point. `pending` owns staged style links keyed by `(pluginId,generation)`, staged registry contributions, staged runtime handles/subscriptions, and the staged binding grant. `active` is the single committed generation serving panels. `retired` is revoked and reclaimed. Failed or timed-out staging removes only pending style links, contributions, handles, and grants. Commit atomically swaps active registry contributions and styles, then retires the old generation: revoke its grant and binding token, call its `destroy?.()`, remove its `(pluginId,generation)` styles and registrations, and close its panels. Prior contributions stay visible until replacement succeeds.
4. After the module resolves, the host calls `initialize(registry, host)`. A
   reload/update stages binding, import, and initialization for the successor;
   the previous active generation remains usable until the successor commits.
   Failed or timed-out staging fences only the pending generation and leaves
   open/saved panels on the previous generation. On explicit disable/uninstall
   the host calls `destroy?.()`, revokes the active grant, removes registrations,
   and closes panels. Each initialization attempt is transactional for
   plugin-owned runtime state; its callbacks, subscriptions, and handles are
   fenced on failure, while successful replacement revokes the old generation.
   Failure does not unregister prior registry contributions until replacement
   succeeds.

## Global entry point

`window.registerKandevPlugin(id: string, plugin: KandevPlugin)` — defined by the
host before any bundle loads. Bundles are authored with React as an **external**;
they must use `host.React` (NOT bundle their own React) to share the host instance.

The independently consumable frontend type contract is the runtime-free
`@kandev/plugin-sdk` package in `apps/packages/plugin-sdk`. Official plugins import
these types instead of re-declaring this document or importing `apps/web` internals.
The host has a compile-time assignability test, and the real Bitbucket package is a
required exact-head compatibility consumer.
`HostReact` includes `Fragment`, `createElement`, `useState`, `useEffect`,
`useMemo`, `useCallback`, and `useLayoutEffect` with structural React-compatible
signatures. `host.ui.PromptMentionText` is a curated host component with
`{ text: string; interactive?: boolean }` props and owns alias loading plus
fine/coarse-pointer disclosure.

## `host: PluginHostApi`

```ts
interface PluginHostApi {
  pluginId: string;
  React: typeof import("react"); // host React instance (shared)
  jsx: typeof React.createElement; // convenience alias (h)
  context: {
    // Versioned provider-neutral reads; never exposes private AppState slices.
    getActiveWorkspaceId(): string | undefined;
    subscribeActiveWorkspace(listener): () => void;
    getWorkspaceIds(): readonly string[];
    subscribeWorkspaces(listener): () => void;
    getTaskCreationContext(workspaceId: string): TaskCreationContext | null;
    subscribeTaskCreationContext(workspaceId: string, listener): () => void;
    resolveRepositoryId(identity: RepositoryIdentityInput): string | undefined;
  };
  // Compatibility only for older bundles. Deliberately absent from
  // @kandev/plugin-sdk; new/official plugins must use host.context.
  store: Pick<StoreApi<AppState>, "getState" | "setState" | "subscribe">;
  api: {
    // Low-level request scoped to this plugin's host path. It MUST NOT target a
    // public webhook path or be used for authenticated provider commands.
    fetch(path: string, init?: RequestInit): Promise<Response>;
    // Authenticated action declared in this plugin's manifest. The host verifies the
    // indicated resource and passes it to the plugin separately from body JSON. This
    // is the only browser-to-plugin command path; never call a public webhook route.
    invokeAction<TResponse>(
      key: string,
      input?: {
        workspaceId?: string;
        taskId?: string;
        sessionId?: string;
        repositoryId?: string;
        body?: unknown;
      },
      options?: { signal?: AbortSignal },
    ): Promise<TResponse>;
    // Backend API origin ("" when SPA and API share an origin) — for reaching
    // first-party kandev REST endpoints without re-deriving the split-origin
    // dev/desktop base URL from window internals.
    baseUrl: string;
  };
  ui: PluginUIApi; // named curated host components; no open Record index
  // Plugin-scoped locale and translation API. Components use the reactive
  // hook; registry getters may use the imperative translator.
  i18n: {
    readonly locale: string;
    t(
      key: string,
      options?: {
        defaultValue?: string;
        count?: number;
        values?: Readonly<Record<string, string | number>>;
      },
    ): string;
    useTranslation(): {
      readonly locale: string;
      t: PluginHostApi["i18n"]["t"];
    };
  };
  // The resolved light/dark theme, read live on every access. `host` is built
  // once per plugin load, so copying this into a variable that outlives a
  // render freezes it; read it during render, and pair it with onThemeChange
  // for anything that paints imperatively (canvas, inline SVG colors).
  readonly theme: "light" | "dark";
  // Fires on every light/dark change — the settings picker, its live preview,
  // and an OS prefers-color-scheme flip while the app is set to "system".
  // Returns an unsubscribe function; call it on teardown (component unmount,
  // KandevPlugin.destroy) or the listener outlives the surface that owns it.
  onThemeChange(listener: (theme: "light" | "dark") => void): () => void;
  // Soft SPA navigation (history push/replace + SPA re-render) — same code
  // path as the app router, so plugin pages can link into native routes
  // (e.g. /t/{taskId}) without a full reload.
  navigate(href: string, options?: { replace?: boolean }): void;
  // Imperatively opens a modal window rendered by the host's <PluginModalHost/>
  // (mounted once at the app root with its own tooltip provider and isolated
  // behind its own error boundary).
  // Independent of keybindings — any plugin code path may call it.
  openModal(options: PluginModalOptions): PluginModalHandle;
  // Opens Kandev's native one-field task change-request linking workflow.
  // Provider code supplies copy, parsing, and mutation only; the host owns
  // validation placement, submitting state, footer, toast, and close behavior.
  openTaskLinkDialog(options: PluginTaskLinkDialogOptions): PluginModalHandle;
  // Opens a registered provider review in the native desktop dock panel or
  // current mobile session review. Plugins do not reach into host layout stores.
  openTaskReview(options: PluginTaskReviewOptions): void;
  // Sonner's imperative toast. The host mounts the single <Toaster/>, so
  // there is nothing to render and nothing to wire — and because it is
  // imperative rather than a component, it works from inside a plugin modal
  // regardless of which providers that modal sits under.
  toast: PluginToastApi;
  // Shared helpers — plain functions, so they live here rather than in `ui`
  // (a component map). See the "host.utils" section below.
  utils: PluginUtilsApi;
  // Registers one plugin-owned contributor with the native settings save bar.
  // The host prefixes the contributor id with `plugin:<pluginId>:` before it
  // reaches the shared coordinator, so ids only need to be unique inside the
  // plugin. The contributor owns persistence and draft state.
  useSettingsSaveContributor(contributor: SettingsSaveContributor): void;
  // Publishes one integration registration's live enabled state for one
  // workspace. The value is memory-only; persist it with host.storage and
  // republish it for every workspace after plugin load.
  setIntegrationEnabled(
    integrationId: string,
    workspaceId: string,
    enabled: boolean,
  ): void;
  // Authenticated, per-user key/value storage backed by
  // /api/plugins/{id}/user-state/... — see the "host.storage" section below.
  // Requires the plugin manifest to declare capabilities.user_state: true.
  storage: PluginStorageApi;
}

interface PluginStorageEntry {
  key: string;
  value: unknown;
  updatedAt: string;
}

interface PluginStorageSetOptions {
  // Abort the request when the owning surface or plugin generation ends.
  signal?: AbortSignal;
  // Optimistic-concurrency guard: the updatedAt the caller last read. The
  // write is rejected (the returned promise rejects with a
  // PluginStorageConflictError) if the stored row was modified after this
  // time, leaving the stored value unchanged. Omit for unconditional
  // last-write-wins (the default).
  ifUnmodifiedSince?: string;
  // Identifies which logical surface made this write, for echo suppression
  // (see subscribe's writerId filter below). Appended to the host's own
  // per-tab id — not a replacement for it — so a static surface id like a
  // dockview panelId (shared by every tab that has that panel open) can't
  // make two different tabs look like the same writer to each other. Omit
  // to use the shared per-tab default alone — fine for a one-shot write with
  // no ongoing subscription (e.g. a kanban menu action). A surface that also
  // subscribes to its own writes (e.g. a task panel) should pass something
  // stable and unique to that surface, such as its own panelId from
  // PluginTaskPanelProps — otherwise its writes are indistinguishable from
  // any other surface of the same plugin in this tab, and one surface's
  // legitimate write can be silently swallowed by another surface's
  // subscription as if it were that other surface's own echo.
  writerId?: string;
}

// Mirrors the backend's user-state route scopes.
type PluginStorageScope =
  | "instance"
  | "workspace"
  | "task"
  | "session"
  | "repository";

interface PluginStorageApi {
  get(
    scope: PluginStorageScope,
    scopeId: string,
    key: string,
    options?: { signal?: AbortSignal },
  ): Promise<PluginStorageEntry | undefined>;
  set(
    scope: PluginStorageScope,
    scopeId: string,
    key: string,
    value: unknown,
    options?: PluginStorageSetOptions,
  ): Promise<{ updatedAt: string }>;
  delete(
    scope: PluginStorageScope,
    scopeId: string,
    key: string,
    options?: Pick<PluginStorageSetOptions, "writerId" | "signal">,
  ): Promise<void>;
  // Every entry under (scope, scopeId), ordered by key. Not paginated.
  list(
    scope: PluginStorageScope,
    scopeId: string,
    options?: { signal?: AbortSignal },
  ): Promise<PluginStorageEntry[]>;
  // Subscribes to live updates for this plugin's own storage made from
  // another tab, device, or surface — e.g. the kanban Edit modal and the
  // task panel both editing the same document. filter.scope/scopeId/key
  // narrow to a specific tuple; omit a field to match any value.
  //
  // filter.writerId, if given, must be the same value this surface passes to
  // set/delete's own writerId option — the host combines it with its own
  // per-tab id the same way on both sides, so a notification carrying that
  // resulting combined id is this surface's own echo and is skipped, and its
  // editor never clobbers its own caret/selection reacting to its own write.
  // Omit to fall back to the shared per-tab default alone: correct for a
  // plugin with only one surface, but two independent surfaces of the same
  // plugin (e.g. an open task panel and a kanban quick-action) both omitting
  // it would incorrectly suppress each other's legitimate writes as if they
  // were one surface's own echo.
  subscribe(
    filter: {
      scope?: PluginStorageScope;
      scopeId?: string;
      key?: string;
      writerId?: string;
    },
    handler: (change: PluginUserStateChange) => void,
  ): () => void;
}

type SettingsSaveRevision = string | number;

interface SettingsSaveContributor {
  id: string;
  order?: number;
  revision: SettingsSaveRevision;
  isDirty: boolean;
  canSave?: boolean;
  invalidReason?: string;
  save(revision: SettingsSaveRevision): Promise<void> | void;
  discard(revision?: SettingsSaveRevision): Promise<void> | void;
}

interface PluginUserStateChange {
  scope: PluginStorageScope;
  scopeId: string;
  key: string;
  updatedAt: string;
  deleted?: boolean; // true when the change was a delete rather than a set
}

interface PluginModalOptions {
  title?: string; // rendered in a DialogHeader/DialogTitle; omit for no header title
  description?: string; // rendered below the title in the host-owned header
  content: React.ComponentType<{ slotProps?: unknown }>; // reuses the slot-component contract
  size?: "sm" | "md" | "lg" | "xl"; // maps to the host's Dialog width classes; default "md"
  dismissible?: boolean; // overlay click / Escape close the modal; default true
  presentation?: "dialog" | "drawer"; // default dialog; use drawer for native phone actions
}

interface PluginModalHandle {
  close(): void; // closes this modal instance; no-op if already closed
}

interface PluginTaskLinkDialogOptions {
  title: string;
  description: string;
  inputLabel: string;
  placeholder?: string;
  emptyError: string;
  failureMessage: string;
  successMessage: string;
  inputTestId?: string;
  errorTestId?: string;
  submitTestId?: string;
  // The host aborts this signal when the user cancels or closes the dialog.
  onSubmit(reference: string, signal: AbortSignal): Promise<void>;
}

interface PluginTaskReviewOptions {
  providerId: string;
  reviewKey: string;
  title?: string;
  presentation: "desktop" | "mobile";
  sessionId?: string;
}
```

For `host.api.invokeAction`, workspace-scoped actions accept only `workspaceId`;
repository-scoped actions accept `workspaceId` plus `repositoryId`; task-scoped
actions require `taskId`, may include a matching `workspaceId`, and may include
`repositoryId` only when that persisted repository is attached to the verified task.
A task action may also include `sessionId`; the host verifies it belongs to that task.
When both session and repository selectors are present, the host resolves the exact
non-empty worktree branch and exposes it only in the backend verified action context.
Resource selectors never become part of the untrusted action body.

An action handler may return an HTTP status from 200 through 599; zero preserves the
legacy 200 response. The host forwards only safe response headers (`Content-Type`,
`Cache-Control`, `ETag`, and `Retry-After`). Invalid statuses become 502, while
transport/runtime errors become 503 without exposing internal error text. Plugins
should use explicit statuses only for safe domain outcomes that callers can act on.

`host.ui` contents: shadcn primitives (Accordion*, Alert*, Badge, Button,
Card*, Checkbox, Collapsible*, Dialog*, DropdownMenu*, Empty*, Input, Kbd,
KbdGroup, Label, Pagination*, Popover*, Progress, ScrollArea, Select*,
Separator, Sheet*, Skeleton, Spinner, Switch, Table*, Tabs*, Textarea,
Tooltip*, including `TooltipProvider`), the recharts wrappers (`ChartContainer`,
`ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`,
`ChartStyle`), plus first-party app UI: `PageTopbar` (the kandev title bar, for
routes that opt out of the default chrome and own their layout),
`TaskCreateDialog` (kandev's real create-task modal, prefilled via
`initialValues`), `Combobox` (the app's Command+Popover picker), and the
provider-neutral code-host dashboard set: `ChangeRequestList`,
`ChangeRequestRow`, `ChangeRequestDetail`, `IntegrationListToolbar`, `IntegrationScopeBar`,
`IntegrationSaveQueryDialog`, `IntegrationRepositoryFilter`, `IntegrationCursorPagination`,
`IntegrationStartTaskMenu`, `IntegrationIcon`, `IntegrationChangeRequestStatus`, and
`TaskRowIndicator`, `PromptMentionText`, plus native integration settings
`IntegrationAuthStatusBanner`, `IntegrationEnabledControl`, `SettingsSection`,
`SettingsCard`, and `WorkspaceScopedSection`. The authoritative list is
`apps/web/lib/plugins/host-api.ts` (`PLUGIN_UI`).

In create mode, `TaskCreateDialog` accepts this optional transport seam:

```ts
createTask?: (
  payload: Parameters<typeof createTask>[0],
) => Promise<CreateTaskResponse>;
```

When omitted, the dialog uses the normal `/api/v1/tasks` REST client. A trusted
plugin wrapper may provide it to send the unchanged native payload through
`Host Tasks.Create`; the same callback handles both the initial submission and
the one allowed fresh-branch re-consent retry. Edit and session modes ignore it.
The browser callback must not manufacture a repository-provider descriptor. It sends
only native task choices plus an idempotency identifier to an authenticated plugin
action; the plugin resolves repository identity from its live provider connection.
Scope idempotency to one open dialog so retry does not create duplicates while a later
intentional launch for the same change request still can.

Code-host plugins use that dashboard set as one contract. The plugin supplies
normalized change-request data, filter state, task presets, and callbacks; the
host owns row density, external-title behavior, responsive task menus,
linked-task navigation, and loading/error/empty treatment. A row's sole workflow CTA
is the shared **Task** preset menu, whose selection opens `TaskCreateDialog`
directly. Review belongs to the registered task review-provider surface, not a
parallel dashboard button or plugin-specific launch modal. `IntegrationIcon` maps
semantic names (`pull-request`, `pull-request-closed`, `merged`, `filter`) to the same
host Tabler glyphs used by first-party code-host pages; plugins do not copy their SVG
paths. Runtime components stay in the Kandev host and are versioned with `host.ui`.
A task preset may provide a semantic `iconName`; the host maps `eye`, `message`, and
`tool` to the exact first-party **Review**, **Address feedback**, and **Fix CI** icons.
`ReviewItemSummary.taskStatus` is the normal code-host status integration. Once a
registered review provider publishes it, Kandev automatically mounts the exact shared
topbar button, composer CI chip, desktop hover popover, and mobile drawer. Each rendered
linked-task row acquires one deduplicated provider refresh so its indicator color is live
before hover; hover/focus can refresh again, while active topbar/composer status refreshes
every 90 seconds. Plugins must not register
a visual slot or a second poller for these surfaces. Linked-task indicators also derive
the same semantic color hierarchy from normalized state, review, and pipeline fields;
providers do not send CSS classes or provider-specific color tokens. While the initial
task detail request is pending, the indicator remains muted; publishing the snapshot
updates both its summary and color. `IntegrationChangeRequestStatus` remains exposed for non-review-
provider composition only.

`ChangeRequestDetail` is the exact provider-neutral detail component consumed by
Kandev's GitHub panel. A review provider supplies its normalized model and advertised
callbacks; Kandev owns header, branches, state/review badges, description, review/check/
comment sections, add-to-context controls, scrolling, loading/error states, and native
mobile sizing. Code-host plugins must use it instead of recreating the review page.
A future SDK package may contain types or pure helpers, but not duplicate React/Radix
runtime components.
The curated surface also includes `RichTextEditor`/`RichTextReadOnly`, narrow
wrappers over the Plan panel's tiptap markdown editor (see below).

Plugins must use these host instances — bundling copies of anything
Radix/portal/context-based would split React context across instances and
break refs/`asChild`. Pure-React libs (e.g. `@tabler/icons-react`) bundle
fine.

### First-use repository inspection action

A manifest-owned repository provider that supports native task creation from a
new URL declares this workspace-scoped action:

```yaml
actions:
  - key: "repositories.inspect"
    scope: "workspace"
    max_body_bytes: 16384
```

The host invokes the active manifest owner from the backend. The plugin receives
the verified workspace context and this bounded body. Browser descriptor fields
are not forwarded:

```json
{ "url": "https://code.example.com/owner/repository" }
```

Return the preferred nested response:

```json
{
  "repository": {
    "provider_id": "example-provider",
    "provider_host": "https://code.example.com",
    "provider_scope": "https://code.example.com/context-a",
    "provider_repository_id": "owner/repository",
    "owner_or_project": "owner",
    "name": "repository",
    "clone_url": "https://code.example.com/owner/repository.git",
    "default_branch": "main"
  }
}
```

The host accepts the descriptor at the top level for compatibility and accepts
`{"matched":false}` for a URL the provider does not own. A successful response
must use the requested provider ID and include a provider host, provider scope,
repository ID, owner or project, name, credential-free HTTPS clone URL, and
default branch. The clone origin must match the HTTPS provider origin. Provider
scope is limited to 512 bytes and identity fields cannot contain NUL bytes. Any
scope or repository ID hint from the task request must match the response.

The host enforces the manifest body limit, a 15-second timeout, and a 1 MiB
response limit. It validates the response before it writes a repository or task.
Malformed output is invalid, `matched:false` is not found, and provider or
transport failures are unavailable. Error responses do not include plugin body
content or upstream credentials.

### Persisted repository branch action

A manifest-owned repository provider that participates in Kandev's native task branch
picker declares this standardized action:

```yaml
actions:
  - key: "repositories.branches"
    scope: "workspace"
    max_body_bytes: 16384
```

Browser-invoked actions may additionally declare `access: "admin"`. Omitting
`access` preserves the default `authenticated` policy. The host rejects a
non-administrator before it forwards any request body to an admin action.

This action is invoked by the host backend, not the browser callback. Kandev resolves the
active plugin that owns the repository's persisted provider ID and supplies a verified
workspace context plus this snake-case body:

```json
{
  "repository": {
    "provider_id": "example-provider",
    "provider_host": "https://code.example.com",
    "provider_scope": "https://code.example.com/context-a",
    "provider_repository_id": "owner/repository",
    "owner_or_project": "owner",
    "name": "repository",
    "clone_url": "https://code.example.com/owner/repository.git",
    "default_branch": "main"
  }
}
```

Every field comes from the persisted workspace repository. The plugin returns
`{"branches":[{"name":"main","commit":"optional","is_default":true}]}`. Kandev
enforces the manifest request cap, a 15-second timeout, a 1 MiB response cap, at most
10,000 branches, non-empty names, and name deduplication. Missing ownership, an inactive
plugin, an undeclared/wrong-scope action, or malformed output fails closed. Providers
must not require browser-supplied repository authority on this path.

The host wraps plugin routes, slots, and `openModal` content in a
`TooltipProvider`, so a plain `Tooltip` works anywhere without one.
`TooltipProvider` is exported for plugins that want their own
`delayDuration`/`skipDelayDuration` over a dense cluster of tooltips; Radix
supports nesting it.

**Charts use the host's recharts.** `recharts` is already a dependency of both
`apps/web` and `@kandev/ui`, so the `Chart*` exports add no bundle weight — and
a plugin must never bundle its own copy. recharts drives layout through its own
React context and portals its tooltips, so a second copy splits that context
exactly the way a second Radix copy does: charts render at zero size, tooltips
attach to the wrong tree, and responsive containers stop resizing. Compose the
`Chart*` wrappers with the chart primitives they hand you rather than importing
`recharts` in plugin code.

### `host.toast` and `host.utils`

```ts
// Sonner's imperative toast — the host owns the single <Toaster/>, so there
// is nothing to render and it works from any plugin code path, modals
// included.
host.toast.success("Synced 12 issues");
host.toast.error("Sync failed");

interface PluginToastApi {
  (message: string, options?: Record<string, unknown>): string | number;
  success(message: string, options?: Record<string, unknown>): string | number;
  // Renders the same toast as any other variant, and additionally logs
  // `[plugins] toast.error from "<pluginId>":` to the browser console.
  // It does NOT file a report into kandev's frontend error log — that log is
  // for kandev's own application errors, and a plugin toasting an expected
  // condition (a failed poll, say) would otherwise record an Error-level
  // entry every cycle. Console is where every plugin failure surfaces.
  error(message: string, options?: Record<string, unknown>): string | number;
  warning(message: string, options?: Record<string, unknown>): string | number;
  info(message: string, options?: Record<string, unknown>): string | number;
  // Dismisses one toast by the id a variant returned, or all of them when
  // called with no argument.
  dismiss(id?: string | number): unknown;
}

interface PluginUtilsApi {
  // The host's clsx + tailwind-merge combiner, so class merging matches the
  // components it styles.
  cn(...inputs: unknown[]): string;
  // Non-security UUID with a fallback for supported insecure HTTP origins.
  generateUUID(): string;
  // Locale-aware relative time ("3 hours ago", "in 2 days", "yesterday") via
  // Intl.RelativeTimeFormat in the user's active locale; "" for unparseable
  // input. Prefer it over a hand-rolled ladder, which is English-only by
  // construction and goes untranslated for every non-English user.
  formatRelativeTime(value: string | number | Date): string;
  // Polling interval used by native integration health controls.
  integrationStatusRefreshMs: number;
}
```

These are functions, so they sit beside `navigate`/`openModal` rather than in
`ui`, which is a component map.

### Native integration settings state

`registerIntegrationSettings` may provide an `action` component. The host mounts
the action in the detail `SettingsSection` header and in the native integrations
index card. The host passes the routed `workspaceId` and a `surface` value of
`"detail"` or `"index"`. Use the workspace value for workspace-scoped reads and
writes. Do not use `getActiveWorkspaceId()` for a routed settings page.

`host.setIntegrationEnabled(integrationId, workspaceId, enabled)` publishes a
live value for one registration and workspace. The host checks that the
registration belongs to the current plugin. The value is not durable and is
cleared when the plugin unloads. Persist the source of truth with
`host.storage`, then republish it after load:

```ts
function publishAll(
  host: PluginHostApi,
  integrationId: string,
  enabledByWorkspace: Map<string, boolean>,
) {
  for (const workspaceId of host.context.getWorkspaceIds()) {
    host.setIntegrationEnabled(
      integrationId,
      workspaceId,
      enabledByWorkspace.get(workspaceId) === true,
    );
  }
}

const unsubscribe = host.context.subscribeWorkspaces((workspaceIds) => {
  // Load or refresh the durable value for the changed workspace ids.
});
```

`host.useSettingsSaveContributor` connects plugin drafts to the native save
bar. Contributor ids are local to the plugin because the host adds the
`plugin:<pluginId>:` namespace before registration. Save and discard remain
plugin-owned.

### `host.ui.RichTextEditor` / `host.ui.RichTextReadOnly`

Pixel-identical to the Plan panel's markdown editor (paste handling, slash
commands, drag handles, mermaid), so a plugin doesn't ship its own tiptap:

```ts
// RichTextEditor: editable, value/onChange round-trip markdown.
interface RichTextEditorProps {
  taskId: string; // required — scopes mermaid/image asset resolution
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  className?: string;
  testId?: string;
}
// RichTextReadOnly: renders markdown read-only, no taskId dependency.
interface RichTextReadOnlyProps {
  value: string;
  className?: string;
  testId?: string;
}
```

Deliberately narrow — not the plan editor's `comments`, `onSelectionChange`,
`onCommentClick`, `onCommentDeleted`, or `onEditorReady` props, so the plan
editor's internals can keep evolving without breaking this contract.

### `host.storage` — authenticated per-user key/value storage

Backed by `PUT/GET/DELETE /api/plugins/{id}/user-state/{scope}/{scopeId}/{key}`
and `GET /api/plugins/{id}/user-state/{scope}/{scopeId}` (list). Every
read/write is scoped to the calling user via the session/PAT identity — two
users writing the same `(scope, scopeId, key)` never see each other's value;
a `GET` for another user's key returns `404`. Requires the plugin manifest to
declare `capabilities.user_state: true` (`403` otherwise); an unknown or
disabled plugin returns `404`. `scopeId`/`key` must match
`[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`; the request body is capped (`413` over
the limit — see `apps/backend/internal/plugins/user_state_handlers.go`'s
`maxUserStateBodyBytes`). `PUT` accepts an optional `ifUnmodifiedSince`
(compared against the stored row's `updatedAt`) — a conflicting write returns
`409` and leaves the stored value unchanged.

This is entirely separate from the plugin-owned `plugin_state` table (written
only by a plugin's own gRPC-connected backend via the Host `SetState` RPC) —
`host.storage` needs no plugin backend at all, so a UI-only plugin bundle can
persist data with zero Go code.

`host.storage.set` stamps a per-browser-tab `writerId` on every write (one id
per page load, shared across every plugin in that tab). A successful
`PUT`/`DELETE` publishes the `plugin.user-state.updated` WS action to the
writing user's own connections only:

```ts
// WS message: { action: "plugin.user-state.updated", payload: PluginUserStateUpdatedPayload }
interface PluginUserStateUpdatedPayload {
  pluginId: string;
  scope: PluginStorageScope;
  scopeId: string;
  key: string;
  updatedAt: string;
  writerId?: string;
  deleted?: boolean;
}
```

The payload carries keys only, never the stored value — a subscriber refetches
via `host.storage.get`. `host.storage.subscribe(...)` is a typed convenience
wrapper over `registry.registerWsHandler("plugin.user-state.updated", ...)`
that already filters to this plugin's own events, applies your `scope`/
`scopeId`/`key` filter, and skips notifications whose `writerId` matches this
tab's own writes (so an editor never clobbers its own caret/selection from its
own write).

### `host.conversation` — live paginated session history

This browser-only facade requires the manifest capability
`capabilities.api_read: ["messages"]` and `min_kandev_version: "0.91.1"` or
higher. The same floor applies to the Go `Messages().List` reader. It is the
only supported browser way to read prompt history and does not expose Zustand
state, first-party `/api/v1` URLs, raw content, arbitrary metadata, or raw
WebSocket frames. The Host binds every request and event to the current
plugin generation and task-panel session context.

```ts
type PluginConversationErrorCode =
  | "unauthenticated"
  | "not_found"
  | "invalid_query"
  | "upstream_failure";

interface PluginConversationError {
  code: PluginConversationErrorCode;
  message: string;
  retryable: boolean;
}
Browser conversation routes map `401` to `unauthenticated` with
`retryable:false`, `404` to `not_found` with `retryable:false`, `400` to
`invalid_query` with `retryable:false`, and every authorized upstream `5xx` to
`upstream_failure` with `retryable:true`. Binding-only
`409/generation_superseded` is not plugin-visible; continuation-renewal
`409` is plugin-visible as retryable `upstream_failure`.

type PluginSessionKind = "managed" | "passthrough" | null;
type PluginConversationAuthor = "user" | "agent";
type PluginConversationSort = "asc" | "desc";

interface PluginConversationMessage {
  id: string;
  taskId: string | null;
  sessionId: string;
  turnId?: string;
  authorType: PluginConversationAuthor;
  type: string;
  content: string;
  createdAt: string;
  updatedAt: string;
  promptIndex?: number;
  senderTaskId?: string;
}

interface PluginConversationTurn {
  id: string;
  taskId: string | null;
  sessionId: string;
  startedAt: string;
  completedAt?: string;
  updatedAt: string;
}
interface PluginSessionMessagesQuery {
  sessionId: string | null;
  taskId?: string | null;
  authorTypes?: readonly PluginConversationAuthor[];
  sort?: PluginConversationSort;
  pageSize?: number;
}

interface PluginSessionMessagesState {
  messages: readonly PluginConversationMessage[];
  loading: boolean;
  hydrated: boolean;
  loadingMore: boolean;
  error: PluginConversationError | null;
  hasMore: boolean;
  removed: boolean;
  loadMore(): Promise<number>;
  retry(): void;
}

interface PluginSessionTurnsState {
  turns: readonly PluginConversationTurn[];
  loading: boolean;
  hydrated: boolean;
  error: PluginConversationError | null;
  removed: boolean;
  retry(): void;
}

interface PluginConversationApi {
  useSessionMessages(
    query: PluginSessionMessagesQuery,
  ): PluginSessionMessagesState;
  useSessionTurns(
    sessionId: string | null,
    taskId?: string | null,
  ): PluginSessionTurnsState;
  useMessageFavorite(sessionId: string | null, messageId: string): boolean;
}
```

Within a task-panel render, `host.conversation` resolves the Host-injected
panel scope; `props.conversation.history` is the equivalent explicit handle.
Outside a panel scope, nullable session reads return empty state. `taskId` is tri-state: `undefined` (field omitted) inherits the active panel context task via Host-side resolution before sending, so the server never observes `undefined`; explicit `null` means session-scoped with no task filter and encodes as absent `task_id`; an explicit string must equal the panel context task or the query fails `400/invalid_query` without network activity. An explicit string sends as its value; empty `task_id=` is `400`. Event `task_id` and public DTO `taskId` are nullable (`string | null`), with `null` for session-scoped rows. Cache identity, cursor fingerprint, and live-event filtering all key on the tri-state tag, so `undefined`, `null`, and `"t1"` never collapse; wrong-session or wrong-task events are dropped before merge.
Live event matching is explicit: inherited `undefined` and an explicit task
string accept only events whose `session_id` and `task_id` equal the resolved
query context. Explicit `null` accepts every task ID in the selected session,
including event `task_id: null`. A `session.removed` barrier is accepted for
the selected session regardless of its event task ID and closes both hooks.

`loadMore()` resolves to the number of newly projected messages. Joined calls
resolve to the same committed count. Exhausted, closed, and terminal handles
resolve `0` without network activity; retryable transport or renewal failures
reject with `PluginConversationError` while leaving committed state unchanged.
Non-retryable query errors also reject and remain in `error`; `retry()` clears
the error and starts a fresh snapshot only for a live, retryable handle.
Turn `retry()` follows the same live-handle rule: it clears a retryable error
and starts a fresh ready snapshot, while closed, removed, exhausted, and
non-retryable handles do not issue network requests.
Each mounted `PluginTaskPanel` is wrapped in a Host-owned scope provider with its own cache, consumer identity, and abort controller. `history` is the authoritative panel handle; global `host.conversation` resolves only the nearest scope. Unmount or any plugin/panel/task/session/generation change aborts in-flight work, releases that consumer, and closes the handle. Closed handles and calls outside a scope return the stable empty state without network activity; two panels never share scope state. Message pages are bounded, newest-first by default, deterministic keyset pages with opaque cursors. `loadMore` is idempotent and preserves cursor, sort, filters, and generation. The Host owns cutoff, sidecars, replay, gaps, deduplication, tombstones, and lifecycle abort; none is public DTO state.
Lifecycle invalidation also includes a presentation change. `loadMore` is
idempotent operationally: concurrent calls for the same committed continuation
join one in-flight request, and calls after `hasMore` is `false` resolve without
network activity.
On `session.removed`, the facade retains already projected rows, sets
`removed` to `true`, sets `hasMore` to `false` for messages, and makes
subsequent `loadMore` and retry operations no-ops without network activity.
The `removed` terminal state is observable and stable; subsequent retries and
pagination calls resolve without network activity.
Each panel scope owns a monotonic `continuation_revision` over `{cursor,snapshot_token,cutoff,fingerprint,generation}` starting at sentinel `0` on scope creation. Query identity change, explicit `retry`, and close/invalidate increment the revision (close moves to an invalid tombstone that rejects all in-flight completions). Renewal and `loadMore` serialize dispatch per scope and CAS-install only when the current revision still equals the captured one; every response is checked against both the revision and the full tuple. Renewal may change only expiry, token rotation, and cursor re-encoding while preserving cutoff and fingerprint. Failed renewal or failed page leaves the committed page state unchanged; close or retry invalidates pending completions.
The HTTP facade returns the public page shapes above. The Host transport carries the subscribe ACK's `snapshot_token` in a Host-only request header; it remains valid through the signed cursor/query expiry (maximum 10 minutes) and rotates only on rebind. The server validates its plugin/session/generation binding and committed cutoff, then returns internal row-sequence sidecars. The Host strips those sidecars before this API resolves. Cursors reject tampering or a different session, task, filter, sort, generation, or expiry; reads are not caller-selectable as-of queries.
The Host renews a continuation before 80% of expiry through its private `POST /api/plugins/{id}/conversation/continuation/renew` operation. It accepts the current cursor and snapshot token, returns replacements with the same cutoff/fingerprint and a new expiry, and never selects a new cutoff. If retention or generation cannot preserve the cutoff, `loadMore` leaves existing state unchanged and reports retryable `upstream_failure`; explicit `retry` starts a fresh snapshot.

Endpoint error matrix: `GET /conversation/binding` `409/generation_superseded/true` is Host-loader-only (bounded retry, never import until success, `Cache-Control: no-store` on success and every error). `POST /conversation/continuation/renew` `409` maps to public retryable `upstream_failure` without changing the loaded cutoff, also `Cache-Control: no-store`. Plugin-visible errors never carry `generation_superseded`.
Binding tokens expire no later than 10 minutes after issuance; the loader
rebinds before expiry and never sends an expired token to plugin code.
The Host establishes ordered readiness before the initial snapshot. The Host-only
request uses the discriminated `SubscribeRequest` branches below: core requires
`wire_id`; plugin requires `plugin_id`, `generation`, `binding_token`, and
`consumer_id`; identities are mutually exclusive. Success returns the matching
identity, while failure has no success-only fields. Legacy payloads are
accepted only with all ordered fields absent.

#### Host-only conversation wire contract

The Host-only snapshot header is `X-Kandev-Snapshot-Token`. HTTP page and
renewal shapes, plus ordered event payloads, are:

```ts
type CoreSubscribeRequest = {
  session_id: string;
  consumer_kind: "core";
  last_seen_sequence?: number;
  resume_token?: string;
  wire_id: string;
  plugin_id?: never;
  generation?: never;
  binding_token?: never;
  consumer_id?: never;
};
type PluginSubscribeRequest = {
  session_id: string;
  consumer_kind: "plugin";
  plugin_id: string;
  generation: number;
  binding_token: string;
  last_seen_sequence?: number;
  resume_token?: string;
  consumer_id: string;
  wire_id?: never;
};
type SubscribeRequest = CoreSubscribeRequest | PluginSubscribeRequest;
type SessionWireFailureCode =
  | "unauthorized"
  | "invalid_binding"
  | "generation_superseded"
  | "invalid_request"
  | "session_not_found"
  | "cursor_expired"
  | "forward_gap"
  | "session_removed";
type SessionWireError = {
  code: SessionWireFailureCode;
  message: string;
  retryable: boolean;
};
type SubscribeSuccessPayload = {
  success: true;
  session_id: string;
  result: "fresh" | "replay" | "gap" | "invalid_resume";
  event_watermark: number;
  snapshot_cutoff: number;
  snapshot_token: string;
  replay_from?: number;
  replay_to?: number;
  oldest_sequence?: number;
  resume_token: string;
} & (
  | { wire_id: string; consumer_id?: never }
  | { consumer_id: string; wire_id?: never }
);
type SubscribeFailurePayload = {
  success: false;
  session_id?: string;
  error: SessionWireError;
};
type SubscribeAck = {
  id: string;
  type: "response";
  action: "session.subscribe";
  payload: SubscribeSuccessPayload | SubscribeFailurePayload;
};
type CoreSessionAckRequest = {
  session_id: string;
  consumer_kind: "core";
  sequence: number;
  resume_token?: string;
  wire_id: string;
  plugin_id?: never;
  generation?: never;
  consumer_id?: never;
};
type PluginSessionAckRequest = {
  session_id: string;
  consumer_kind: "plugin";
  plugin_id: string;
  generation: number;
  sequence: number;
  resume_token?: string;
  consumer_id: string;
  wire_id?: never;
};
type SessionAckRequest = CoreSessionAckRequest | PluginSessionAckRequest;
type SessionAckSuccessPayload = {
  success: true;
  session_id: string;
  acknowledged_sequence: number;
  resume_token: string;
} & (
  | { wire_id: string; consumer_id?: never }
  | { consumer_id: string; wire_id?: never }
);
type SessionAckFailurePayload = {
  success: false;
  session_id?: string;
  error: SessionWireError;
};
type SessionAckResponse = {
  id: string;
  type: "response";
  action: "session.ack";
  payload: SessionAckSuccessPayload | SessionAckFailurePayload;
};
type PluginConversationPage = {
  messages: readonly PluginConversationMessage[];
  hasMore: boolean;
  cursor: string | null;
};
type PluginConversationTurnsPage = {
  turns: readonly PluginConversationTurn[];
};
type ContinuationRenewRequest = {
  cursor: string;
  snapshot_token: string;
};
type ContinuationRenewResponse = {
  cursor: string;
  snapshot_token: string;
  cutoff: number;
  fingerprint: string;
  expires_at: string;
};
type RawSessionEvent = {
  type: "session.event";
  protocol_version: number;
  event_type: string;
  session_id: string;
  task_id: string | null;
  sequence: number;
  event_id: string;
  payload: unknown;
};

// Validation converts RawSessionEvent to this projected union only after
// protocol, identity, event-type, and payload checks succeed.
type SessionEventPayload =
  | { event_type: "message.added"; message: PluginConversationMessage }
  | { event_type: "message.updated"; message: PluginConversationMessage }
  | { event_type: "message.deleted"; message_id: string }
  | { event_type: "session.turn.started"; turn: PluginConversationTurn }
  | { event_type: "session.turn.completed"; turn: PluginConversationTurn }
  | { event_type: "session.removed" };
type SessionEventBase = {
  type: "session.event";
  protocol_version: 1;
  session_id: string;
  task_id: string | null;
  sequence: number;
  event_id: string;
};
type SessionEvent = {
  [T in SessionEventPayload["event_type"]]: SessionEventBase & {
    event_type: T;
    payload: Extract<SessionEventPayload, { event_type: T }>;
  };
}[SessionEventPayload["event_type"]];
```

The Host sends `X-Kandev-Snapshot-Token` on snapshot reads and validates the
renewal request before exposing only the public page state. `cursor` is
nullable only on a page with no next page; renewal receives and returns the
current non-null cursor. The Host maps event payloads to public DTOs and
strips protocol sidecars before plugin code sees them. Removal is terminal
whether it precedes or follows poison; the replacement cursor is closed.
Only `message.added`, `message.updated`, `message.deleted`,
`session.turn.started`, `session.turn.completed`, and `session.removed` use
this migrated contract.
The raw envelope is decoded with `protocol_version: number` and arbitrary
`event_type`/`payload`; `SessionEvent` is the validated projected union.
Validation requires `payload.type === event_type`; a mismatch is durable
poison, is not projected, and cannot advance ACK. Strict subscribe ACKs require
`session_id`, `result`, `event_watermark`, `snapshot_cutoff`, `snapshot_token`,
and `resume_token`. `fresh` forbids replay and oldest-sequence fields;
`replay` requires `replay_from` and `replay_to` with
`replay_from <= replay_to <= snapshot_cutoff`.
For `replay`, `replay_from` is the first delivered sequence (inclusive) and
equals `last_seen_sequence + 1`; `replay_to` is the final delivered sequence
(inclusive) and equals the committed `snapshot_cutoff`.
`replay` is returned only when `last_seen_sequence` was supplied; otherwise
the initial result is `fresh`.
`gap` requires `oldest_sequence` and forbids replay fields; `invalid_resume`
forbids replay fields and reports the replacement cursor state. The
`resume_token` is always the current token for the returned consumer state.

Subscribe and ACK failures use the same outer response envelope with
`success:false`, the requested `session_id` when known, and
`error:{code,message,retryable}`; no success-only ordered fields are present.
Codes distinguish `unauthorized`, `invalid_binding`, `generation_superseded`,
`invalid_request`, `session_not_found`, `cursor_expired`, `forward_gap`, and
`session_removed`. Binding/generation failures are non-projection failures;
`generation_superseded` is retryable only for the Host loader, while expired
or retained-cursor failures produce `gap` reconciliation rather than a
plugin-visible subscribe exception. ACK rejects forward gaps and malformed
identity/range/token input without advancing the durable cursor.
Core wire identity: the Host mints one opaque `wireId` per core consumer mount and carries it in subscribe/ACK state as `wire_id`. Plugin panels receive a separate Host-minted opaque `consumer_id`, carried in subscribe/ACK state and never caller-supplied. Broker state is keyed by `(session,consumer_kind,plugin,generation,wire_id|consumer_id)`; each applicable identity survives reconnect through its persisted entry, while a new mount mints a new identity at its registration watermark. Identities transition `registered -> ready -> streaming -> suspended (reconnect window) -> released` and release on unsubscribe/unmount or after the reconnect plus token-retention window expires. Plugin panels from one plugin/generation never share a cursor.
Reconnect grace is 10 minutes after disconnect. Resume and snapshot tokens
expire no later than 10 minutes after issuance; delivery cursors and immutable
event rows remain for the maximum token expiry plus the reconnect grace.
Garbage collection runs only after those bounds and preserves terminal
tombstones until all resumable consumer identities are released.
If `session.removed` precedes poison, the rebind still produces terminal
removal and a closed replacement cursor; no later event is admitted. This is
the same terminal outcome as poison followed by removal.
If a previously authorized consumer reconnects to `session_removed` or a
terminal replacement cursor, the facade preserves committed rows, sets
`removed:true`, sets message `hasMore:false`, and makes `loadMore` and `retry`
no-ops. A fresh unauthorized or nonexistent lookup remains ordinary
`404/not_found` and never reveals deletion state.
Ordered event envelopes carry `protocol_version`; canonical policy registry is `{1:{ignorable:["session.workspace_sources.updated"]}}`. Only a type listed by its matching version may advance ACK without projection. Missing, malformed, or unsupported versions and other unknown types remain durable poison: the cursor stays before the event, diagnostics retain its ID/version, and advancement stops. Rebind atomically snapshots past poison at a new cutoff, commits that cutoff, returns a replacement cursor/token, and does not project the poison. When `session.removed` arrives after a poison cursor, rebind snapshots past both to a terminal cutoff: the outcome is terminal removal, the replacement cursor is terminally closed and admits no post-terminal events, and poison diagnostics remain durable.
Poison operations are owned by `SessionDeliveryDispatcher`: each record moves
`pending -> leased -> exhausted -> requeued`, with a 30-second lease, five
attempts, and exponential backoff capped at 30 seconds. Exhaustion records
event ID, protocol version, and last error, and emits structured
`session_event_poison_total` diagnostics. The Host-only
`session.event.poison.requeue` command requires an authenticated operator with
`session_events:requeue`; it accepts session, event ID, and expected owner epoch,
audits actor, prior state, attempt count, and timestamp, increments owner epoch,
resets attempts, and returns `pending` without changing sequence or payload.
Repeated requests after requeue return current state without mutation; stale
expected epochs are rejected without mutation. Startup reclaims expired leases
but never clears or skips poison.
Legacy projection coalescing: pending contiguous sequence ranges project at most once per `event_id`/sequence per wire, then ACK the highest contiguous sequence. Example: `seq 10 = message.updated id A` followed by `seq 11 = message.updated id A` coalesces to one projection of the latest image `A@11`, then a single `session.ack` for `11`; a `session.removed` barrier after `11` is a separate terminal projection. Same-`event_id` replays and same-sequence redeliveries are dropped; any event with `sequence <= acknowledged_sequence` is suppressed without a second projection.
After contiguous delivery the Host-only `session.ack` uses the discriminated
`SessionAckRequest` branches below: core requires `wire_id`; plugin requires
`plugin_id`, `generation`, and `consumer_id`; identities are mutually exclusive.
Success returns the matching identity and failure has no success-only fields.
The shared client retains the full response envelope, validates outer
IDs/types/actions before payload parsing, and retries by consumer sequence/token.
The Host validates binding/generation, strict integer/range rules, applicable
identity, current or prior token on retry, and contiguous advancement. Snapshot
tokens and sidecars never reach plugin code. Reload, disable, uninstall, panel
switch, or unmount revokes generation.

Registry ownership matrix: every `register*` call and Host-owned resource is keyed by `(pluginId,generation,stageId,kind,localId)` and staged invisibly until commit. `kind` is the registration method (`route`, `navItem`, `settingsRoute`, `component`, `wsHandler`, `keybinding`, `integrationSettings`, `repositoryProvider`, `reviewProvider`, `taskAction`, `taskPanel`, `taskMenuAction`, `taskFilter`, `taskListFacet`, `translations`) or Host-owned resource (`styleLink`, `modal`, `conversationScope`, `bindingGrant`). A duplicate `(kind,localId)` within the same stage rejects the second call; a call from a foreign or retired `(pluginId,generation,stageId)` is rejected without side effects; stage abort discards all its staged entries without notifications. Commit atomically publishes the stage's entries and revokes the retired generation's entries in one linearization step, emitting notifications only for the committed delta.

## `registry: PluginRegistry`

```ts
// icon: curated icon name (apps/web/lib/plugins/icons.ts — "ticket", "chart",
// "robot", "database", ...) or a plugin-owned component rendered with host
// React. Unknown/missing names render a puzzle glyph in the sidebar.
// section: "main" (default) renders as a top-level sidebar entry;
// "integrations" renders inside the sidebar's Integrations section alongside
// the first-party integration links (GitHub, Jira, ...); "sidebar-footer"
// renders as an icon button in the sidebar footer's icon row and as a
// labelled row in the phone menu's Utilities group, subject to the footer's
// inline budget — an over-budget item is reached through the footer's
// overflow menu instead of an inline button; "settings" is accepted but
// renders on no surface. Hosts predating a section value, or seeing an
// unrecognised one, simply degrade to "main"'s placement — nothing is ever
// silently dropped.
type PluginIcon = string | React.ComponentType<{ className?: string }>;
export type PluginNavSection =
  | "main"
  | "settings"
  | "integrations"
  | "sidebar-footer";

interface NavItem {
  id: string;
  label: string;
  path: string;
  icon?: PluginIcon;
  section?: PluginNavSection;
}

// Configuration for the kandev-style title bar the host renders above a plugin
// route. All fields optional; defaults are derived (see registerRoute below).
interface PluginPageChrome {
  title?: string; // default: nav-item label for the same path, else plugin name
  subtitle?: string; // muted text next to the title
  icon?: PluginIcon; // default: matching nav item's icon
  backHref?: string; // back-link target (host default "/")
  backLabel?: string; // back-link label (host default "Kandev")
  actions?: React.ComponentType; // rendered on the right side of the topbar
}

interface PluginRouteOptions {
  // Default: enabled with derived title. Object → configure; false → render the
  // route full-bleed and own the chrome (e.g. with host.ui.PageTopbar).
  topbar?: boolean | PluginPageChrome;
}

interface PluginRegistry {
  // Installs flat locale catalogs under this plugin's isolated namespace.
  // English is required as the fallback. Registration is atomic; unload
  // removes all catalog bundles and locale changes invalidate host consumers.
  registerTranslations(
    catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>,
  ): void;

  // Top-level SPA route, e.g. "/jira". Component rendered by the SPA route resolver
  // when window.location path === path (exact match; trailing segments via ":param" not
  // required for v1 — exact + startsWith("/plugins/{id}") allowed). The host wraps the
  // page in kandev chrome (PageTopbar + scrollable content area) by default —
  // configure or opt out via options.topbar.
  registerRoute(
    path: string,
    Component: React.ComponentType,
    options?: PluginRouteOptions,
  ): void;

  // Sidebar/main nav entry. Rendered by <PluginNavItems/> in the app sidebar,
  // and by <MobilePluginNavSection/> in the phone menu sheet (the sidebar is
  // hidden below md), with item.icon resolved against the curated icon map
  // (fallback: puzzle).
  registerNavItem(item: NavItem): void;

  // Route under /settings/plugins/{id}/... rendered inside settings shell.
  // The exact /settings/plugins/{id} route retains the host-owned personal
  // shortcut card beside the plugin component; nested routes are fully
  // plugin-owned. The settings shell already provides its own topbar chrome.
  registerSettingsRoute(path: string, Component: React.ComponentType): void;

  // Native Settings > Integrations contribution. The host adds index/navigation
  // entries and wraps this component in the shared settings section.
  registerIntegrationSettings(
    registration: IntegrationSettingsRegistration,
  ): void;

  // Named slot injection. Host renders all components registered for a slot via
  // <PluginSlot name="..." slotProps={...}/>. Initial slots: "task-sidebar",
  // "settings-nav", "chat-input-actions", "chat-submit-decoration",
  // "task-create-input-actions",
  // "new-session-input-actions", "chat-top-bar",
  // "main-top-bar", "app-status-bar-left", "app-status-bar-right",
  // "plugin-settings", "task-card-indicators", "task-card-tags",
  // "task-row-metadata", and
  // "sidebar-workspace-actions".
  // "task-card-indicators" renders a small icon/badge beside the PR status
  // icon on every kanban card and forwards
  // `{ taskId, workspaceId, workflowStepId }` as `slotProps`. Not a closed
  // union — hosts may register additional slot names.
  // "task-card-tags" renders in its own row on every kanban card, below the
  // badges row — for contributions too wide for the cramped title-row
  // "task-card-indicators" spot (e.g. a row of tag chips) — and forwards the
  // same `{ taskId: string, workspaceId: string | null, workflowStepId: string | null }`
  // shape as `slotProps` (`workspaceId` is null with no active workspace, and
  // `workflowStepId` is null when the task has no workflow step assigned).
  // "task-row-metadata" renders compact, read-only metadata on the sidebar
  // task tree and `/tasks` list. It forwards
  // `{ taskId, workspaceId, workflowStepId, surface }`, where `surface` is
  // "sidebar" or "task-list". The slot is plugin-agnostic.
  // "chat-input-actions", "task-create-input-actions", and
  // "new-session-input-actions" render composer actions for task/Quick Chat,
  // task creation, and new-session creation. Each forwards the typed
  // `PluginComposerSlotProps`, including native insert/focus/submit capabilities.
  // "chat-submit-decoration" renders *over* the chat composer's send button
  // rather than beside it — for adornments that belong on the send affordance
  // itself (a progress ring, a state dot), which a sibling slot cannot draw.
  // The host owns the geometry: the layer is absolutely positioned to the send
  // button's 28px circular box, so a decoration sizes itself against `inset-0`
  // without measuring the DOM and stays on the button's rim; a negative inset
  // can be clipped by the collapsed desktop toolbar. The plugin component is
  // rendered inside the layer, not beside the button. The layer is
  // `pointer-events-none` so a decoration can never swallow a click meant for
  // send. For hover or focus disclosure, keep the decoration inert and observe
  // the host button from an effect, removing listeners on unmount. Use
  // `pointer-events-auto` only as a last resort for a separate hit target that
  // does not obstruct send; prefer "chat-input-actions" when the plugin needs
  // its own action. The slot forwards
  // `ChatSubmitDecorationSlotProps`: `{ taskId, taskTitle, activeSessionId,
  // sessionIds, presentation, isSending, isAgentBusy, disabled,
  // planModeEnabled }`, so a decoration can react to the button's live state.
  // The slot renders only while the send button does: when the agent is
  // mid-turn with an empty composer the button is replaced by Cancel, and the
  // decoration goes with it.
  // "chat-top-bar" renders status in the session top bar (beside the
  // document/editor/debug controls) and forwards
  // `{ taskId, taskTitle, workspaceId, activeSessionId, sessionIds }`. Both
  // carry the active session plus every kandev session id on the task.
  // "main-top-bar" renders status/actions in the default app top bar on the
  // Home / Kanban / Tasks views (beside the CPU/DB metrics and the view/display
  // controls) and forwards `{ workspaceId, workspaceLabel, currentPage,
  // presentation }`, where presentation is "desktop" or "mobile". On a phone,
  // listing contributions live inside the topbar menu with 44px touch targets
  // and 16px SVG icons. Slots own their controls and disclosure state; the host
  // does not dismiss the menu on arbitrary plugin interactions. Desktop
  // contribution sizing is unchanged. It is the app-wide,
  // task-agnostic counterpart to "chat-top-bar", so it carries no task/session
  // ids.
  // "sidebar-workspace-actions" renders icon buttons after the built-in Quick
  // Terminal and Quick Chat actions in the desktop sidebar's New Task row and
  // in the shared phone navigation sheet. It forwards
  // `SidebarWorkspaceActionsSlotProps` as `slotProps`, with `presentation` set
  // to "desktop" or "mobile". The mobile presentation must use a touch target
  // of at least 44px in its active dimension.
  // Resolving a session id to an agent/ACP transcript id (e.g. to key
  // tokscale cost data on a session) is the plugin's job, done server-side in
  // the plugin backend via the Host data API; the host only propagates ids.
  // "plugin-settings" renders inline on a plugin's own settings page
  // (Settings > Plugins > <plugin>, at the top above the schema-driven settings
  // form) and forwards `{ pluginId: string, status: PluginStatus }`
  // as `slotProps`. It is owner-scoped: the host renders only the component
  // registered by the plugin currently being viewed, so your card appears on
  // your own settings page and never on another plugin's — no per-id gating
  // needed in your component.
  registerComponent(
    slot: string,
    Component: React.ComponentType<{ slotProps?: unknown }>,
  ): void;

  // WS action handler. Bridged into the existing lib/ws dispatch; called with the
  // decoded message payload for that action string.
  registerWsHandler(action: string, handler: (payload: unknown) => void): void;

  // Binds a handler to a keybinding declared in this plugin's manifest
  // (ui.keybindings[].id — { id, default, description, allow_in_editor? },
  // see manifest schema).
  // The host resolves the effective combo (user override if the user
  // rebound it, else the manifest default) and dispatches globally, skipping
  // editable targets the same way core app shortcuts do — unless that entry
  // declared `allow_in_editor: true`, which lets it fire while an input,
  // textarea or contenteditable has focus. That opt-in exists for bindings
  // whose whole job is to act on the focused composer (dictation); the
  // manifest validator only accepts it on a combo carrying a
  // ctrl/cmd/mod/alt modifier, and the dispatcher re-checks the *resolved*
  // combo, so a user override that drops the modifier silently falls back to
  // skipping editables rather than swallowing ordinary keystrokes. Combos are
  // user-overridable on the installed plugin detail page (Settings > Plugins >
  // <plugin>), namespaced `plugin:{pluginId}:{id}`. Overrides are personal to
  // the signed-in user; plugin configuration and lifecycle controls remain
  // administrator-only. Binding an id the manifest didn't declare still
  // stores the handler (a console warning is logged) since the dispatcher's
  // effective-shortcut resolution keys off the manifest list.
  //
  // Combo grammar (manifest `default` and any user override): `+`-separated
  // tokens, one of the modifiers `mod|ctrl|cmd|meta|alt|option|shift`
  // (repeatable) plus exactly one key token. `mod` resolves to Cmd on macOS
  // and Ctrl elsewhere (⌘/Ctrl). `shift` may not be combined with a digit or
  // symbol key (e.g. `shift+1`, `shift+slash`) — Shift changes the character
  // a browser reports for those keys, so the combo could never dispatch; both
  // the manifest validator and the frontend parser reject it.
  registerKeybinding(id: string, handler: (event: KeyboardEvent) => void): void;

  // Requires manifest ownership of provider.id. One active plugin owns one provider;
  // unload revokes it and aborts in-flight provider work. inspectURL returns browser
  // picker data only. Native first-use task creation also requires repositories.inspect.
  registerRepositoryProvider(provider: RepositoryProviderRegistration): void;

  // Native task-menu contribution. placement "link" renders in Link menus on desktop
  // and visible mobile action surfaces; host closes the menu before handler invocation.
  registerTaskAction(action: TaskActionRegistration): void;

  // Native desktop/mobile review integration. Use external-store callbacks, never a
  // plugin hook, so enable/disable does not alter host hook ordering.
  registerReviewProvider(provider: ReviewProviderRegistration): void;

  // Contributes a panel to the task workspace "+" menu and, when enabled,
  // the phone Panels picker.
  registerTaskPanel(registration: TaskPanelRegistration): void;

  // Contributes an item to the kanban card's Edit submenu (group "edit") or
  // a flat, top-level card menu item after "Move to"/"Send to workflow"
  // and before "Archive"/"Delete" (group "primary"). See "Kanban card contributions" below.
  registerTaskMenuAction(registration: TaskMenuActionRegistration): void;

  // Contributes a client-side filter section to the kanban board's display
  // dropdown, alongside the built-in Workflow/Repository sections. See
  // "Task filters" below.
  registerTaskFilter(registration: TaskFilterRegistration): void;
  registerTaskListFacet(registration: TaskListFacetRegistration): void;
}

interface IntegrationSettingsRegistration {
  id: string;
  label: string;
  description: string;
  icon?: PluginIcon;
  Component: React.ComponentType<{ workspaceId?: string }>;
  // Optional action for the detail section header and integrations index card.
  // The surface identifies the host location and the workspace id identifies
  // the settings target.
  action?: React.ComponentType<IntegrationSettingsActionProps>;
}

type IntegrationSettingsActionSurface = "detail" | "index";

interface IntegrationSettingsActionProps {
  workspaceId?: string;
  surface: IntegrationSettingsActionSurface;
}

// Integration settings render at /settings/integrations/{id} and
// /settings/workspaces/{workspaceId}/integrations/{id}. IDs are URL-safe, cannot
// shadow first-party integrations, and have one active owner; unload revokes them.

interface RepositoryProviderRegistration {
  id: string;
  label: string;
  icon?: PluginIcon;
  listRepositories(context: {
    workspaceId: string;
    /** Optional server-side search text. */
    query?: string;
    /** Opaque cursor returned by this provider for the same query. */
    cursor?: string;
    /** Requested page size; a provider may return fewer items. */
    limit?: number;
    signal: AbortSignal;
  }): Promise<RepositoryInspection[] | RepositoryProviderPage>;
  // Optional synchronous performance hint. It never establishes ownership.
  matchesURL?(url: string): boolean;
  listBranches(context: {
    workspaceId: string;
    repository: RepositoryInspection;
    signal: AbortSignal;
  }): Promise<RepositoryProviderBranch[]>;
  // Browser picker callback. Its result is not authoritative for a native task write.
  inspectURL(context: {
    workspaceId: string;
    url: string;
    signal: AbortSignal;
  }): Promise<RepositoryInspection | null>;
  supportsDraft?: boolean; // default true; false hides the native draft option
  // Kandev pushes the verified checkout branch before invoking this callback.
  createChangeRequest?(context: {
    workspaceId: string;
    taskId: string;
    sessionId: string; // session whose checkout Kandev pushed
    repositoryId: string;
    repository: PluginHostRepository; // persisted host repository, not browser authority
    title: string;
    body: string;
    baseBranch?: string;
    draft: boolean;
    signal: AbortSignal;
  }): Promise<RepositoryChangeRequestCreateResult>;
}

interface RepositoryProviderPage {
  repositories: RepositoryInspection[];
  nextCursor?: string;
}

// The host binds every returned RepositoryInspection.providerId to the
// registration's manifest-owned id; result data cannot spoof another namespace.
// Legacy arrays remain valid. The host follows page cursors and rejects a cursor
// repeated by a broken provider instead of looping forever.
interface PluginHostRepository {
  id: string;
  workspace_id: string;
  name: string;
  provider: string;
  source_type?: string;
  provider_repo_id?: string;
  provider_host?: string;
  provider_scope?: string;
  provider_owner?: string;
  provider_name?: string;
  remote_url?: string;
  default_branch?: string;
}
interface RepositoryProviderBranch {
  name: string;
}
interface RepositoryChangeRequestCreateResult {
  url: string;
  provider?: string;
  output?: string;
  // False means remote creation succeeded but task association did not.
  linked?: boolean;
  // Safe detail shown with recovery guidance. Never retry remote creation.
  associationError?: string;
}
interface RepositoryInspection {
  providerId: string;
  providerHost: string;
  // Opaque, credential-free connection identity. Required when one authority
  // can host multiple independent provider roots.
  providerScope?: string;
  ownerOrProject: string;
  repositoryId: string;
  repositoryName: string;
  cloneUrl: string;
  defaultBranch?: string;
  baseBranch?: string;
  headBranch?: string;
  pullRequest?: { number: number; title: string };
}
interface TaskActionRegistration {
  id: string;
  label: string;
  icon?: PluginIcon;
  placement: "link";
  group?: string;
  visible?(context: PluginTaskActionContext): boolean;
  singleTaskOnly?: boolean;
  run(context: PluginTaskActionContext): Promise<void>;
}
interface PluginTaskActionContext {
  workspaceId: string;
  taskId: string;
  repositories: readonly PluginHostRepository[];
  pathname: string;
  presentation: "desktop" | "mobile";
}
interface ReviewProviderRegistration {
  id: string;
  label: string;
  icon?: PluginIcon;
  changeRequestNoun: string;
  order: number;
  getSnapshot(taskId: string): readonly ReviewItemSummary[];
  subscribe(taskId: string, listener: () => void): () => void;
  refresh(taskId: string, signal: AbortSignal): Promise<void>;
  // Implement all three association callbacks together. The host performs one
  // workspace-bounded association refresh and renders native task-list/card
  // indicators. Each rendered linked task leases refresh(taskId), deduplicated
  // with topbar/panel consumers; hover/focus may refresh it again.
  getAssociationSnapshot?(
    workspaceId: string,
  ): readonly ReviewTaskAssociation[];
  subscribeAssociations?(workspaceId: string, listener: () => void): () => void;
  refreshAssociations?(workspaceId: string, signal: AbortSignal): Promise<void>;
  // Removes only this task link; it never deletes the remote change request.
  unlink?(context: {
    workspaceId: string;
    taskId: string;
    reviewKey: string;
    signal: AbortSignal;
  }): Promise<void>;
  ReviewPanel: React.ComponentType<PluginReviewPanelProps>;
  Selector?: React.ComponentType;
  EmptyState?: React.ComponentType;
}
interface ReviewTaskAssociation {
  providerId: string;
  taskId: string;
  reviewKey: string;
  connectionScope: string;
  repositoryId: string;
  changeRequestNumber: string | number;
}
interface ReviewItemSummary {
  providerId: string;
  reviewKey: string;
  title: string;
  url: string;
  connectionScope: string;
  repositoryId: string;
  changeRequestNumber: string | number;
  // open/opened/draft participates in native Create PR eligibility.
  state: string;
  statusBadge?: { label: string; tone?: string };
  taskStatus?: ReviewTaskStatus;
}
type ReviewTaskPipelineState = "success" | "failure" | "pending" | "neutral";
interface ReviewTaskStatus {
  number: number | string;
  state: "open" | "merged" | "closed" | "draft";
  pipelineState: ReviewTaskPipelineState;
  checks: readonly {
    id: string;
    label: string;
    state: ReviewTaskPipelineState;
    detail?: string;
    url?: string;
  }[];
  review?: {
    state: "approved" | "changes_requested" | "pending";
    approved: number;
    required?: number;
    requested?: number;
  };
  unresolvedComments?: number;
  loading?: boolean;
  error?: string;
  updatedAt?: number;
}
interface PluginReviewPanelProps {
  panelId: string;
  presentation: "desktop" | "mobile";
  workspaceId: string;
  taskId: string;
  sessionId?: string;
  reviewKey: string;
  connectionScope: string;
  repositoryId: string;
  changeRequestNumber: string | number;
}

type PluginPresentation = "desktop" | "mobile";

type PluginComposerSurface =
  | "task-chat"
  | "quick-chat"
  | "task-create"
  | "new-session";
interface PluginComposerCapability {
  insertText(text: string): { status: "inserted" | "ignored" | "unavailable" };
  focus(): { status: "focused" | "unavailable" };
  submit(): Promise<{
    status: "submitted" | "blocked" | "unavailable";
    reason?: string;
  }>;
}
interface PluginComposerSlotProps {
  surface: PluginComposerSurface;
  presentation: PluginPresentation;
  taskId: string | null;
  taskTitle?: string;
  activeSessionId: string | null;
  sessionIds: string[];
  disabled: boolean;
  submittable: boolean;
  disabledReason?: string;
  composer: PluginComposerCapability;
}
type PluginOpenMessageResult = { status: "accepted" | "unavailable" };
interface PluginTaskPanelConversationCapability {
  openMessage(messageId: string): PluginOpenMessageResult;
  /** Host-created API bound to this panel's context and generation. */
  history: PluginConversationApi;
}

interface PluginTaskPanelContext {
  taskId: string;
  sessionId: string | null;
  sessionKind: PluginSessionKind;
  presentation: PluginPresentation;
}

interface PluginTaskPanelProps extends PluginTaskPanelContext {
  panelId: string; // this registration's panel id, so one Component can back multiple panels
  conversation: PluginTaskPanelConversationCapability;
}

interface TaskPanelRegistration {
  id: string; // plugin-local panel id (unique within the plugin, not globally)
  title: string; // add-panel-menu row label and dockview tab title
  titleKey?: string;
  icon?: PluginIcon;
  Component: React.ComponentType<PluginTaskPanelProps>; // wrapped in a PluginErrorBoundary
  mobileEnabled?: boolean; // include in the phone's grouped Panels picker. Default: false.
  visible?(context: PluginTaskPanelContext): boolean;
}

interface PluginTaskMenuContext {
  workspaceId: string;
  taskId: string;
  taskTitle: string;
  workflowStepId: string | null;
  presentation: PluginPresentation; // the actual kanban layout: desktop or mobile
}

interface TaskMenuActionRegistration {
  id: string;
  label: string;
  icon?: React.ReactNode;
  // "edit" nests the item in the card's Edit submenu; "primary" renders it
  // as a flat, top-level item after the "Move to"/"Send to workflow"
  // submenus and before the "Archive"/"Delete" items.
  group: "edit" | "primary";
  visible?(context: PluginTaskMenuContext): boolean; // default: always visible
  run(context: PluginTaskMenuContext): void | Promise<void>; // a rejection is caught and logged
}

interface PluginTaskFilterContext {
  taskId: string;
}

interface PluginTaskFilterOption {
  value: string;
  label: string;
  color?: string; // optional swatch color rendered beside the option label
}

interface TaskFilterRegistration {
  id: string; // plugin-local filter id (unique within the plugin, not globally)
  label: string; // filter section label shown in the dropdown
  getOptions(): PluginTaskFilterOption[];
  // Called only when `selected` is non-empty — an empty selection is
  // implicit "All" and always matches without invoking this method.
  matches(context: PluginTaskFilterContext, selected: string[]): boolean;
}
```

The host treats `matchesURL` only as a coarse candidate filter. It runs every
remaining provider's cancellable, workspace-scoped `inspectURL`; `null` means the
configured provider does not own the URL. One structured result wins, more than one
is an ambiguity error, and registration order never decides ownership.

### App-status-bar slots

`app-status-bar-left` and `app-status-bar-right` are live named component slots.
Each registration is one opaque status item; the slot chooses its default side,
not a permanent side after user customization. Components receive
`slotProps` with this exact shape:

```ts
interface AppStatusBarSlotProps {
  placement: "left" | "right";
  presentation: "bar" | "mobile-drawer";
  density: "full" | "compact";
  pathname: string;
  activeWorkspaceId: string | null;
  activeTaskId: string | null;
  activeSessionId: string | null;
}
```

`placement` matches registration slot. `presentation` identifies the mounted host;
the host mounts only one presentation at once. `density` is `full` on desktop and
phone drawer, `compact` on tablet. `pathname` and active IDs are current-context
hints, not entity payloads. Use a typed `host.context` read or host-verified action;
do not inspect private store slices from a released plugin.

Before customization, registration order is render order within each default side.
Users can Cmd-drag on macOS or Ctrl-drag elsewhere with a mouse to move any item
across the whole desktop/tablet bar. Kandev stores that order in backend user
settings; disabled contributions keep their place and return there when enabled.
Phone renders the saved left sequence followed by the saved right sequence, without
dragging. There is no cross-plugin priority API, keyboard-arrow ordering, or touch
ordering. Enable, disable, and uninstall update slots without reload. Each component
is isolated by an owner-aware error boundary, so plugins must tolerate remounting and
render a compact bar control or touch-usable drawer row for the supplied presentation.
The host neither inspects nor separately reorders children inside a registration, and
does not add a nested interactive wrapper.

A full-bleed plugin route (`topbar: false`) opts out of host chrome. It may mount
the host-provided Status drawer trigger when its own chrome should expose status;
otherwise status access is intentionally its responsibility.

### Task panels

`registerTaskPanel` adds one row to the task workspace's "+" (add panel)
menu, after "Plan". Selecting it opens a dockview panel using a single
generic `"plugin-panel"` dockview component shared by every plugin panel —
panel identity lives in `params: { pluginId, panelKey }`, and the panel id is
`plugin:{pluginId}:{panelKey}`. This keeps the host's panel-rendering dispatch
to one branch per host release rather than one per plugin, and lets a saved
layout round-trip a plugin panel reference even when that plugin is no
longer installed: the layout manager drops (not throws on) an unresolvable
plugin panel, and `Settings > Layouts` renders a generic placeholder box for
one it can't render live.

Disabling or uninstalling a plugin closes any of its open panels in the
current session and removes its add-panel-menu row; a panel your Component
was actively rendering unmounts in place (no console error, no dockview
exception). A plugin `Component` that throws during render shows a small
"failed to load" fallback inside just that panel — the panel error boundary
is scoped to your panel only, not the surrounding dockview layout.

On a phone viewport, `mobileEnabled: true` adds the panel to one grouped
**Panels** bottom-nav action (after Terminal); it does not add one navigation item
per panel. The touch-sized `MobilePickerSheet` presents every available panel in
an internally scrolling list. Selecting a row dismisses the picker and renders
your `Component` as the single full-height mobile surface with
`presentation: "mobile"` — the same `Component`, no separate mobile
registration. During a slow or failed reload, the host preserves a selected panel;
after a ready generation, a panel omitted by the new registration is closed. An
explicit disable or uninstall closes every panel owned by the plugin.

### Kanban card contributions

With no plugin registered for group `"edit"`, the kanban card's context/
dropdown menu shows the same flat `Edit` item as today. Once any plugin
registers a `registerTaskMenuAction({ group: "edit", ... })`, that item
becomes an `Edit` submenu: `Edit task` (the original action) first, then each
visible plugin action in registration order. An action whose `visible(context)`
returns `false` is filtered out entirely (not shown disabled). Selecting an
action calls `run(context)`; a rejected promise is caught and logged to the
console, and the menu still closes either way (Radix's own close-on-select,
independent of the async result).

Group `"primary"` renders each visible action as its own flat, top-level menu
item instead of nesting it under `Edit`. It appears after the movement items
and before the Archive/Delete items on cards and on the shared desktop/mobile
task-row menu. Group `"edit"` remains card-only. Visibility filtering,
registration order, and `run()`/error handling are identical; the two groups
are independent lists (an action only ever belongs to one).

`"task-card-indicators"` (documented above with the other slots) is the
matching read-only surface: a small icon/badge rendered beside the PR status
icon on every card, receiving `{ taskId, workspaceId, workflowStepId }`.

`"task-card-tags"` is a second, sibling read-only surface for the same
context — same `{ taskId, workspaceId, workflowStepId }` shape — but mounted
in its own row on the card instead of the cramped title row
`"task-card-indicators"` shares with `PRTaskIcon`. Use it for a contribution
that needs its own width, e.g. a row of tag chips.

`"task-row-metadata"` is a separate, plugin-agnostic slot for compact,
read-only metadata in the sidebar task tree and `/tasks` list. Its shape is
`{ taskId, workspaceId, workflowStepId, surface }`, with `surface` equal to
`"sidebar"` or `"task-list"`. The host emits no wrapper when the slot is empty.

### Task filters

`registerTaskFilter` adds one section to the kanban board's display dropdown
(the same menu that holds the built-in Workflow and Repository filters),
rendered below Repository and above the Preview Panel section. Each
registration's `getOptions()` supplies the section's checkbox list; the
plugin owns option identity, ordering, and labels — including any
"untagged"-style sentinel, which is just a normal option value the host does
not special-case.

Selections are multi-select and purely client-side against tasks already
loaded in the board's in-memory state: there is no backend query, pagination,
or persistence for this filter, and selections reset on reload (unlike
Workflow/Repository, which persist to backend user settings). An empty
selection is implicit "All" for that section — `matches()` is only invoked
once at least one option is selected, and multiple plugin filter sections
combine with AND (a task must match every section with an active selection),
mirroring how Workflow/Repository combine with the search query today. If
`matches()` throws, the task is treated as non-matching and the error is
logged (mirroring `TaskMenuActionRegistration.visible`'s error handling).

### Task-list facets

`registerTaskListFacet({ id, label, getValues, subscribe? })` adds a choice to `/tasks` Sort and
Group controls. `getValues({ taskId, workspaceId })` synchronously returns `{ value, label,
color? }[]`; `subscribe` invalidates the loaded page. Return each value at most once for a task,
and keep one label and color for a value across all tasks. Facet sorting uses the first value label
after a case-insensitive alphabetical comparison. Facets are page-local: no facet selection is
persisted or sent to the backend. The host catches callback errors and revokes registrations and
active subscriptions when the owning plugin unloads. A task with multiple values appears in each
matching group; a task without a value appears in the host's `Ungrouped` section. Parent/child
indentation is preserved only within a group both tasks match, so a matching child without its
parent is rendered at that group's root.

## Registry internals (host side)

`apps/web/lib/plugins/registry.ts` holds a singleton `PluginRegistry` whose data
is reactive (a small zustand store or event emitter) so host React components
re-render when registrations change. Every registration records the owning
`pluginId` so the host can bulk-unregister on disable. Exposes read selectors:
`getRoutes()` (each entry carries `pluginId` + `options`), `getNavItems()`,
`getSettingsRoutes()`, `getSlotComponents(slot)`, `getWsHandlers(action)`,
`getPluginName(pluginId)` (display name recorded by `forPlugin(id, name)`, used
for derived page-chrome titles), `getTaskPanels()` / `getTaskPanel(pluginId, id)`,
and `getTaskMenuActions(group?)`. `unregisterWsHandler(pluginId, action, handler)`
removes exactly one WS handler (used by `host.storage.subscribe`'s returned
unsubscribe) without disturbing the plugin's other registrations.

Before `initialize`, the loader records `ActivePlugin.repositoryProviderIds` for the
plugin ID. A present declaration is an allowlist for provider/review registration; an
absent declaration is tolerated only for older payload compatibility. Disable/unload
removes this declaration with the plugin's registrations. Failed/timed-out activation
performs the same cleanup and an attempt token prevents late async registrations from
reappearing.

Plugin top-level routes render inside `PluginPageFrame`
(`apps/web/components/plugins/plugin-page.tsx`): a `PageTopbar` title bar above
a scrollable content area, resolved from `options.topbar` with derived
defaults, or the bare component when the route opted out (`topbar: false`).

## Integration points the app must add (task-19)

- `src/spa-routes.tsx`: after the static route switch, before the not-found
  fallback, consult `registry.getRoutes()` for a matching path and render it inside
  the normal app shell.
- `src/settings-routes.tsx`: consult `registry.getSettingsRoutes()` for
  `/settings/plugins/{id}/*` paths.
- App sidebar (grep the nav list component): render `<PluginNavItems/>` reading
  `registry.getNavItems()`.
- `lib/ws/router.ts` / `lib/ws/client.ts`: after built-in dispatch, forward the
  message to any `registry.getWsHandlers(action)`.
- `components/plugins/plugin-slot.tsx`: `<PluginSlot name props/>` renders all
  slot components; drop into task detail sidebar + settings nav as initial hosts.
  The chat composer toolbar
  (`components/task/chat/chat-input-toolbar-desktop.tsx` and
  `-mobile.tsx`, via `chat-input-plugin-actions.tsx`) hosts the
  `chat-input-actions` slot for task and Quick Chat, passing the typed
  `PluginComposerSlotProps`. Task creation and new-session creation mount
  `task-create-input-actions` and `new-session-input-actions` with the same
  capability contract. `kanban-card-plugin-slots.tsx`
  hosts `task-card-indicators` beside `PRTaskIcon` and `task-card-tags` as its
  own row, both mounted from `kanban-card-content.tsx`'s `KanbanCardBody`.
- `components/task/dockview-shared.tsx` / `dockview-panel-content.tsx` /
  `dockview-desktop-layout.tsx`: the generic `"plugin-panel"` dockview
  component + `pluginPanelTab`, and `renderPanel`'s `"plugin-panel"` case
  resolving `{ pluginId, panelKey }` via `registry.getTaskPanel(...)`.
  `dockview-add-panel-items.tsx` renders one "+" menu row per
  `registry.getTaskPanels()`. `use-close-revoked-plugin-panels.ts` closes an
  open panel whose registration disappeared.
- `components/task/mobile/session-mobile-bottom-nav.tsx` /
  `plugin-panel-picker.tsx` / `session-mobile-layout.tsx`: expose all
  `mobileEnabled` registrations through one grouped Panels picker, and reconcile
  the focused panel against host lifecycle state; `MobilePanelArea` renders the
  selected `plugin:{pluginId}:{panelKey}` panel.
- `components/kanban-card-edit-submenu.tsx`: builds the card's `Edit` entry
  from `registry.getTaskMenuActions("edit")`.
- `lib/state/layout-manager/plugin-panels.ts`: `pluginPanelId`/
  `parsePluginPanelId` identity helpers plus registry-aware
  `isKnownPanelId`/`isStructuralComponent`/`resolvePluginPanelDefinition`,
  consulted by the layout manager's persistence/merge logic.
- `lib/plugins/host-api.ts` / `user-state-sync.ts`: `host.storage`
  implementation (fetch against the user-state routes, per-tab `writerId`)
  and `host.storage.subscribe` (over `registerWsHandler`).
- `internal/gateway/websocket/user_notifications.go` (backend): subscribes
  the `plugin.user-state.updated` bus event into the existing
  `UserEventBroadcaster` (user-scoped fan-out, same path as
  `user.settings.updated`).

## Security posture (documented, enforced where cheap)

Plugin JS runs in the kandev origin with store access — this is the accepted
tradeoff of option C. v1 mitigations: only **active, operator-installed** plugins
load; bundles are served by kandev from the extracted package directory (same-origin,
no third-party CDN, no upstream network hop); host wraps `initialize` in try/catch so
a broken plugin can't crash boot; failed/timed-out activation is rolled back; and
registrations are namespaced + bulk-revocable per plugin. No credentials are ever
displayed to the operator — installing a plugin (via
URL or upload) has nothing to copy or reveal, unlike the old register flow's one-time
API key/webhook secret. Sandboxing plugin JS (worker/realms) is explicit future work.

## Example plugin must (task-21)

Ship a bundle that on `initialize` registers: a nav item "Hello" → route
`/plugins/hello` rendering a native page (uses `host.jsx` + `host.ui`), a
`task-sidebar` slot component, and a WS handler for `task.created` that updates a
counter in its page via the plugin's own module state. No bundled React.