@get-bb/plugin-sdk 0.4.3

package/bundled-types/bb-plugin-sdk-app.d.ts

@@ -0,0 +1,1519 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { z } from 'zod';
+
+/** A JSON-safe path segment reported by a Standard Schema validation issue. */
+type PluginRpcIssuePathSegment = string | number;
+/** Validator-neutral validation detail carried by an RPC error envelope. */
+interface PluginRpcValidationIssue {
+    message: string;
+    path?: PluginRpcIssuePathSegment[];
+}
+/** Stable wire error categories for plugin RPC. */
+type PluginRpcErrorCode = "invalid_json" | "invalid_input" | "handler_error" | "invalid_output" | "non_json_result" | "unknown_method";
+/** Structured RPC failure returned as `{ ok: false, error }`. */
+interface PluginRpcError {
+    code: PluginRpcErrorCode;
+    message: string;
+    issues?: PluginRpcValidationIssue[];
+}
+/**
+ * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
+ * Zod 4 schemas implement this interface directly; other validators can do
+ * the same without becoming part of BB's public protocol.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+type StandardSchemaV1Result<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaV1Issue[];
+};
+interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: PropertyKey | readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[];
+}
+type StandardSchemaV1InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+type StandardSchemaV1InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+interface PluginRpcMethodContract<InputSchema extends StandardSchemaV1 = StandardSchemaV1, OutputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+}
+type PluginRpcContract = Readonly<Record<string, PluginRpcMethodContract>>;
+type PluginRpcHandlers<Contract extends PluginRpcContract> = {
+    [Method in keyof Contract]: (input: StandardSchemaV1InferOutput<Contract[Method]["input"]>) => StandardSchemaV1InferInput<Contract[Method]["output"]> | Promise<StandardSchemaV1InferInput<Contract[Method]["output"]>>;
+};
+type PluginRpcCallInput<Method extends PluginRpcMethodContract> = StandardSchemaV1InferInput<Method["input"]>;
+type PluginRpcCallArgs<Method extends PluginRpcMethodContract> = null extends PluginRpcCallInput<Method> ? [input?: PluginRpcCallInput<Method>] : [input: PluginRpcCallInput<Method>];
+type PluginRpcResult<Method extends PluginRpcMethodContract> = StandardSchemaV1InferOutput<Method["output"]>;
+
+declare const reasoningLevelSchema: z.ZodEnum<{
+    none: "none";
+    low: "low";
+    medium: "medium";
+    high: "high";
+    xhigh: "xhigh";
+    ultracode: "ultracode";
+    max: "max";
+    ultra: "ultra";
+}>;
+type ReasoningLevel = z.infer<typeof reasoningLevelSchema>;
+declare const serviceTierSchema: z.ZodEnum<{
+    default: "default";
+    fast: "fast";
+}>;
+type ServiceTier = z.infer<typeof serviceTierSchema>;
+declare const permissionModeSchema: z.ZodEnum<{
+    full: "full";
+    auto: "auto";
+    "accept-edits": "accept-edits";
+}>;
+type PermissionMode = z.infer<typeof permissionModeSchema>;
+declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodEnum<{
+        "agent-only": "agent-only";
+    }>>;
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+    mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        resource: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"thread">;
+            threadId: z.ZodString;
+            projectId: z.ZodOptional<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"project">;
+            projectId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"section">;
+            sectionId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            source: z.ZodEnum<{
+                workspace: "workspace";
+                "thread-storage": "thread-storage";
+            }>;
+            entryKind: z.ZodEnum<{
+                file: "file";
+                directory: "directory";
+            }>;
+            path: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"command">;
+            trigger: z.ZodEnum<{
+                "/": "/";
+            }>;
+            name: z.ZodString;
+            source: z.ZodEnum<{
+                command: "command";
+                skill: "skill";
+            }>;
+            origin: z.ZodEnum<{
+                user: "user";
+                project: "project";
+                builtin: "builtin";
+            }>;
+            label: z.ZodString;
+            argumentHint: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"plugin">;
+            pluginId: z.ZodString;
+            icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            itemId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodEnum<{
+        "agent-only": "agent-only";
+    }>>;
+    type: z.ZodLiteral<"image">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodEnum<{
+        "agent-only": "agent-only";
+    }>>;
+    type: z.ZodLiteral<"localImage">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodEnum<{
+        "agent-only": "agent-only";
+    }>>;
+    type: z.ZodLiteral<"localFile">;
+    path: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    mimeType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+type PromptInput = z.infer<typeof promptInputSchema>;
+
+declare const createThreadEnvironmentArgsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"reuse">;
+    environmentId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"host">;
+    hostId: z.ZodOptional<z.ZodString>;
+    workspace: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"unmanaged">;
+        path: z.ZodNullable<z.ZodString>;
+        branch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"existing">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"new">;
+            baseBranch: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"managed-worktree">;
+        baseBranch: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"named">;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"default">;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"personal">;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"project-default">;
+}, z.core.$strip>], "type">;
+type CreateThreadEnvironmentArgs = z.infer<typeof createThreadEnvironmentArgsSchema>;
+
+declare const createExecutionInputSourcesSchema: z.ZodObject<{
+    providerId: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        "client-preference": "client-preference";
+    }>>;
+    model: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        "client-preference": "client-preference";
+    }>>;
+    serviceTier: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        "client-preference": "client-preference";
+    }>>;
+    reasoningLevel: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        "client-preference": "client-preference";
+    }>>;
+    permissionMode: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        "client-preference": "client-preference";
+    }>>;
+}, z.core.$strict>;
+type CreateExecutionInputSources = z.infer<typeof createExecutionInputSourcesSchema>;
+
+/**
+ * A value that survives a JSON round trip without coercion or data loss.
+ *
+ * Host boundaries still validate values at runtime because TypeScript cannot
+ * exclude non-finite numbers and plugin bundles can bypass static types.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
+/**
+ * The `@get-bb/plugin-sdk/app` contract (plugin design §5.2) — pure types with no
+ * side effects. The BB app imports these to keep its real implementation in
+ * sync (`satisfies PluginSdkApp`). Plugin authors import the same shapes through
+ * `@get-bb/plugin-sdk/app`.
+ *
+ * Per-slot props are versioned contracts: additive-only within an SDK major.
+ */
+/** Props passed to a `homepageSection` component. */
+interface PluginHomepageSectionProps {
+    /** Project in view on the compose surface; null when none is selected. */
+    projectId: string | null;
+}
+/**
+ * Props passed to a `settingsSection` component.
+ *
+ * Deliberately empty in V1; versioned additive like the other slot props.
+ */
+interface PluginSettingsSectionProps {
+}
+/** Props passed to a `navPanel` component (it owns its whole route). */
+interface PluginNavPanelProps {
+    /**
+     * The route remainder after the panel root, "" at the root. The panel's
+     * route is `/plugins/<pluginId>/<path>/*`, so a deep link like
+     * `/plugins/notes/notes/work/ideas.md` renders the panel with
+     * `subPath: "work/ideas.md"`. Navigate within the panel via
+     * `useBbNavigate().toPluginPanel(path, { subPath })` — browser
+     * back/forward then walks panel-internal history.
+     */
+    subPath: string;
+}
+/**
+ * Props passed to a panel tab opened by a `threadPanelAction`.
+ *
+ * This slot is rendered only for an existing thread. Use
+ * `experimental_newThreadPanelAction` for the root New thread screen.
+ */
+interface PluginThreadPanelProps {
+    threadId: string;
+    /**
+     * The JSON value the action's `openPanel` call passed (round-tripped
+     * through persistence, so the tab restores across reloads); null when the
+     * action opened the panel without params.
+     */
+    params: JsonValue | null;
+}
+/** Props passed to a panel tab opened by `experimental_newThreadPanelAction`. */
+interface PluginNewThreadPanelProps {
+    /** Project selected in the root composer; null in projectless compose. */
+    projectId: string | null;
+    /**
+     * The JSON value the action's `openPanel` call passed (round-tripped
+     * through persistence, so the tab restores across reloads); null when the
+     * action opened the panel without params.
+     */
+    params: JsonValue | null;
+}
+interface PluginPendingInteractionView {
+    id: string;
+    threadId: string;
+    title: string;
+    payload: JsonValue;
+    createdAt: number;
+    expiresAt: number | null;
+}
+interface PluginPendingInteractionProps {
+    interaction: PluginPendingInteractionView;
+    submit(value: JsonValue): Promise<void>;
+    cancel(): Promise<void>;
+}
+/**
+ * Props for a `sidebarFooterAction` — host-rendered (no plugin component).
+ * Deliberately empty; the registration's `run` carries the behavior.
+ */
+interface PluginSidebarFooterActionProps {
+}
+/**
+ * Props passed to an `experimental_threadList` component — the sidebar's
+ * scrolling thread area, replaced wholesale by one plugin.
+ */
+interface PluginThreadListProps {
+    /** The thread the route currently shows; null on non-thread routes. */
+    activeThreadId: string | null;
+    /** The project the route currently shows; null when none is selected. */
+    activeProjectId: string | null;
+    /** True on phone-width viewports and coarse pointers. */
+    isCompactViewport: boolean;
+    /**
+     * Call after the user opens a thread. It closes the mobile sidebar drawer,
+     * and it clears the host search field on every viewport. Always call it, or
+     * the sidebar stays in search mode after the thread opens.
+     */
+    onNavigate: () => void;
+    /**
+     * The host search field's current text, or "" when the field is closed.
+     * The host owns that field, so a plugin list filters by this rather than
+     * shipping a second search box.
+     */
+    searchQuery: string;
+}
+/**
+ * Props passed to an `experimental_threadHeaderAction` component, rendered in
+ * the thread header's action row.
+ */
+interface PluginThreadHeaderActionProps {
+    /**
+     * The thread this header belongs to. Never null: the slot is not rendered
+     * on the compose screen or other non-thread routes. A split layout renders
+     * one header per pane, so the component mounts once per visible thread,
+     * each with its own id — keep per-thread state in the component, never in a
+     * module-level singleton.
+     */
+    threadId: string;
+    projectId: string;
+    /**
+     * True on phone-width viewports and coarse pointers. Collapse to an
+     * icon-sized control when it is true — the row is short.
+     */
+    isCompactViewport: boolean;
+}
+/**
+ * Where a file being opened by a `fileOpener` lives. `path` semantics follow
+ * the source: workspace paths are relative to the environment's worktree,
+ * thread-storage paths are relative to the thread's storage root, host paths
+ * are absolute on the thread's host.
+ */
+interface PluginFileOpenerSource {
+    kind: "workspace" | "host" | "thread-storage";
+    threadId: string | null;
+    environmentId: string | null;
+    projectId: string | null;
+}
+/** Props passed to a `fileOpener` component (rendered as a panel file tab). */
+interface PluginFileOpenerProps {
+    path: string;
+    source: PluginFileOpenerSource;
+}
+/**
+ * Message context passed to a `messageDirective` component — the assistant
+ * (or nested agent) message that contained the directive.
+ */
+interface PluginMessageDirectiveMessage {
+    id: string;
+    threadId: string;
+    turnId: string | null;
+    projectId: string | null;
+}
+/**
+ * Open a worktree-relative file in the host's workspace file viewer. Returns
+ * true when the host accepted the path; false when the path is invalid or the
+ * viewer declined it.
+ */
+type PluginMessageDirectiveOpenWorkspaceFile = (path: string) => boolean;
+/**
+ * Props passed to a `messageDirective` component. Attributes are untrusted
+ * strings parsed from the directive; the plugin validates its own fields.
+ */
+interface PluginMessageDirectiveProps {
+    /** Parsed, untrusted directive attributes (e.g. `{ file: "demo.html" }`). */
+    attributes: Readonly<Record<string, string>>;
+    /** Original directive source text (useful for diagnostics / crash fallback). */
+    source: string;
+    message: PluginMessageDirectiveMessage;
+    /**
+     * Opens a worktree-relative file in the host's workspace file viewer. Null
+     * when the message surface has no workspace viewer available.
+     */
+    openWorkspaceFile: PluginMessageDirectiveOpenWorkspaceFile | null;
+}
+interface PluginHomepageSectionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    title: string;
+    component: ComponentType<PluginHomepageSectionProps>;
+}
+interface PluginSettingsSectionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Optional host-rendered section heading. */
+    title?: string;
+    /**
+     * Optional one-line host-rendered subheading under `title`, in the built-in
+     * SettingsSection idiom (ignored when `title` is absent).
+     */
+    description?: string;
+    component: ComponentType<PluginSettingsSectionProps>;
+}
+interface PluginNavPanelRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    title: string;
+    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
+    icon: string;
+    /** URL segment under `/plugins/<pluginId>/`; letters, digits, `-`, `_`. */
+    path: string;
+    component: ComponentType<PluginNavPanelProps>;
+    /**
+     * Optional presentational component rendered at the trailing edge of this
+     * panel's sidebar row. It receives no props so it can own a narrow live
+     * value through the ordinary SDK hooks without coupling that state to the
+     * host sidebar. The host does not mount it on compact viewports and clips it
+     * to a small, single-line box on wider viewports. It shares the trailing
+     * action column, fading out for the host's options button on hover or focus;
+     * do not render controls or rely on unbounded content here.
+     *
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_sidebarAccessory?: ComponentType;
+    /**
+     * Optional component rendered on the right side of the shared title bar
+     * (e.g. a sync button or a count). Contained separately from the body: a
+     * throwing headerContent is hidden without breaking the title bar.
+     */
+    headerContent?: ComponentType<PluginNavPanelProps>;
+}
+/**
+ * Context handed to a `threadPanelAction`'s `run`.
+ *
+ * The action is thread-only and is never offered on the root New thread
+ * screen, so `threadId` is always present.
+ */
+interface PluginThreadPanelActionContext {
+    /** The thread whose panel launcher invoked the action. */
+    threadId: string;
+    /**
+     * Open a tab in the thread's side panel rendering this action's
+     * `component`. `title` labels the tab (default: the action's `title`);
+     * `params` must be JSON-serializable — it is persisted with the tab and
+     * reaches the component as its `params` prop. Opening with params
+     * identical to an already-open tab of this action focuses that tab
+     * (updating its title) instead of duplicating it. May be called more than
+     * once (different params ⇒ multiple tabs) or not at all.
+     */
+    openPanel(options?: {
+        title?: string;
+        params?: JsonValue;
+    }): void;
+}
+interface PluginThreadPanelActionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Label of the action row in the panel's new-tab launcher. */
+    title: string;
+    /**
+     * Icon hint (BB icon name) used when the plugin ships no logo; the
+     * launcher row and opened tabs prefer the plugin's logo.
+     */
+    icon?: string;
+    /** Rendered inside every panel tab this action opens. */
+    component: ComponentType<PluginThreadPanelProps>;
+    /**
+     * How the host frames the tab content. "padded" (default) wraps the
+     * component in the panel's scroll container with standard padding —
+     * right for document-like content. "flush" gives the component the full
+     * tab area (no padding, definite height, no host scrolling) — right for
+     * app-like content that manages its own layout, such as
+     * `ThreadChat`.
+     */
+    layout?: "padded" | "flush";
+    /**
+     * Runs when the user activates the action: call your RPC methods, show a
+     * toast, and/or open panel tabs via `context.openPanel`. Omitted =
+     * immediately open a panel tab with defaults. Errors (sync or async) are
+     * contained and logged; they never break the launcher.
+     */
+    run?(context: PluginThreadPanelActionContext): void | Promise<void>;
+}
+/** Context handed to an `experimental_newThreadPanelAction`'s `run`. */
+interface PluginNewThreadPanelActionContext {
+    /** Project selected in the root composer; null in projectless compose. */
+    projectId: string | null;
+    /**
+     * Open a tab in the root New thread screen's side panel rendering this
+     * action's `component`. The title, params, deduplication, and error
+     * semantics match `threadPanelAction`.
+     */
+    openPanel(options?: {
+        title?: string;
+        params?: JsonValue;
+    }): void;
+}
+/** Registration for the root New thread screen's panel Actions list. */
+interface PluginNewThreadPanelActionRegistration {
+    /** Unique within this slot for the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Label of the action row in the panel's new-tab launcher. */
+    title: string;
+    /** Icon hint (BB icon name) used when the plugin ships no logo. */
+    icon?: string;
+    /** Rendered inside every panel tab this action opens. */
+    component: ComponentType<PluginNewThreadPanelProps>;
+    /** Host framing; matches `threadPanelAction`. */
+    layout?: "padded" | "flush";
+    /**
+     * Runs when the user activates the action. Omitted = immediately open a
+     * panel tab with defaults. Errors are contained and logged.
+     */
+    run?(context: PluginNewThreadPanelActionContext): void | Promise<void>;
+}
+interface PluginPendingInteractionRegistration {
+    /** Matches `rendererId` passed to `bb.ui.requestInput`. */
+    id: string;
+    component: ComponentType<PluginPendingInteractionProps>;
+}
+/** Context handed to a `sidebarFooterAction`'s `run`. */
+interface PluginSidebarFooterActionContext {
+    /**
+     * Navigate to this plugin's detail page in Tools, where declarative settings
+     * and `settingsSection` slots render.
+     */
+    openSettings(): void;
+}
+/**
+ * An icon button in the app sidebar footer (next to Settings / bug report).
+ * Host-rendered for consistent chrome — plugins supply icon, label, and
+ * `run` behavior only.
+ */
+interface PluginSidebarFooterActionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Tooltip and accessible label for the icon button. */
+    title: string;
+    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
+    icon: string;
+    /**
+     * Runs when the user activates the action (e.g. call `openSettings()`,
+     * open a panel via other surfaces, toast). Errors (sync or async) are
+     * contained and logged; they never break the sidebar.
+     */
+    run(context: PluginSidebarFooterActionContext): void | Promise<void>;
+}
+/**
+ * The one status bb would paint for a thread, already resolved through the
+ * host's precedence (attention before work; plan and goal before the generic
+ * spinner). Draw your own glyph for it — the SDK ships no status component.
+ *
+ * Treat an unrecognized value as "none": bb adds kinds over time, and an
+ * older plugin must degrade to drawing nothing rather than throwing.
+ *
+ * "draft" and "working-draft" are never reported here: an unsubmitted composer
+ * draft is per-client state the host reads per row, which an array-wide view
+ * cannot. A thread holding a draft reports whatever it would report without
+ * one.
+ */
+type PluginSidebarThreadIndicator = "unread-error" | "waiting-for-input" | "working-draft" | "workflow" | "background-agent" | "background-command" | "plan-mode" | "goal" | "runtime" | "draft" | "unread-success" | "none";
+/**
+ * How a thread's environment presents its workspace: a worktree bb manages,
+ * a worktree the user manages, or anything else (a plain checkout).
+ */
+type PluginSidebarWorkspaceKind = "managed-worktree" | "unmanaged-worktree" | "other";
+/** Live work counts on a thread. All zero means nothing is running. */
+interface PluginSidebarThreadActivity {
+    workflows: number;
+    backgroundAgents: number;
+    backgroundCommands: number;
+    planMode: number;
+    goals: number;
+}
+/**
+ * One thread in the sidebar's live view.
+ *
+ * A deliberate copy of the fields a sidebar needs — not a re-export of the
+ * host's internal thread row type, which changes whenever the app needs a
+ * field. Timestamps are epoch milliseconds.
+ */
+interface PluginSidebarThread {
+    id: string;
+    projectId: string;
+    /** Null while a thread is still unnamed; pair with `titleFallback`. */
+    title: string | null;
+    titleFallback: string | null;
+    /** The thread this one was forked from or spawned under; null at the root. */
+    parentThreadId: string | null;
+    sectionId: string | null;
+    /** How this thread came to exist under its parent; null for root threads. */
+    originKind: "fork" | null;
+    /** The plugin that spawned it, or null for non-plugin origins. */
+    originPluginId: string | null;
+    /** The agent provider this thread runs on, e.g. "codex", "claude-code". */
+    providerId: string;
+    /** The agent is blocked on the user: an approval or a question. */
+    hasPendingInteraction: boolean;
+    activity: PluginSidebarThreadActivity;
+    indicator: PluginSidebarThreadIndicator;
+    /**
+     * The host's accessible label for `indicator`, e.g. "Thread needs user
+     * input"; null when the indicator is "none". Use it for `aria-label` so
+     * screen-reader text stays consistent across sidebars.
+     */
+    indicatorLabel: string | null;
+    isUnread: boolean;
+    isPinned: boolean;
+    isArchived: boolean;
+    environment: {
+        id: string | null;
+        name: string | null;
+        branchName: string | null;
+        workspaceDisplayKind: PluginSidebarWorkspaceKind;
+    } | null;
+    /**
+     * The machine this thread's work runs on, with the name resolved for you.
+     * Null when the thread has no environment yet, or when its host is not in
+     * the known-hosts list. Useful where a thread has no branch to show — a
+     * personal-project thread has a machine but no worktree.
+     */
+    host: {
+        id: string;
+        name: string;
+    } | null;
+    createdAt: number;
+    updatedAt: number;
+    lastReadAt: number | null;
+    latestAttentionAt: number;
+}
+/**
+ * The pull request for a thread's branch, narrowed to what a sidebar row
+ * needs. `attention` is bb's rolled-up "does this need you" signal, so a row
+ * can colour a badge without reading checks, review, and mergeability itself.
+ */
+interface PluginSidebarPullRequest {
+    number: number;
+    title: string;
+    url: string;
+    state: "draft" | "open" | "merged" | "closed";
+    attention: "checks_failed" | "checks_pending" | "changes_requested" | "review_requested" | "conflicts" | "blocked" | "draft" | "ready_to_merge" | "merged" | "closed" | "none";
+}
+interface PluginSidebarThreadPullRequestState {
+    /** True while the first lookup for this thread's environment is in flight. */
+    isLoading: boolean;
+    /**
+     * The pull request, or null when the branch has none, the thread has no
+     * environment, or the lookup could not run (a git-host hiccup). A row should
+     * treat null as "nothing to show", never as an error.
+     */
+    pullRequest: PluginSidebarPullRequest | null;
+}
+/** One project in the sidebar's live view. */
+interface PluginSidebarProject {
+    id: string;
+    name: string;
+    /** True for the implicit personal project. */
+    isPersonal: boolean;
+}
+interface PluginSidebarThreadsState {
+    status: "loading" | "ready" | "error";
+    threads: readonly PluginSidebarThread[];
+    projects: readonly PluginSidebarProject[];
+}
+/**
+ * Act on threads from a plugin surface. Every method routes to the host's own
+ * flow, so optimistic updates, toasts, dialogs, pane closing, and route repair
+ * behave exactly as they do in the built-in sidebar. Unknown thread ids are
+ * ignored by `open` and rejected by the rest.
+ */
+interface PluginSidebarThreadActions {
+    /**
+     * Navigate to a thread. `split: true` applies bb's split placement rules —
+     * a right split by default, focus when the thread is already open, replace
+     * at the pane cap — and falls back to plain navigation where splits are off.
+     */
+    open(threadId: string, options?: {
+        split?: boolean;
+    }): void;
+    /**
+     * Go to the new-thread screen. Passing `projectId` also makes that project
+     * the composer's selection, so the thread is created where you asked.
+     */
+    openNewThread(options?: {
+        projectId?: string;
+        focusPrompt?: boolean;
+    }): void;
+    setPinned(threadId: string, pinned: boolean): Promise<void>;
+    setRead(threadId: string, read: boolean): Promise<void>;
+    /** Silent rename — no dialog. For inline editing in your own row. */
+    rename(threadId: string, title: string): Promise<void>;
+    /** Archives the thread AND its children, closing any panes showing them. */
+    archive(threadId: string): void;
+    /**
+     * Opens bb's delete confirmation, which counts child threads first. Deletion
+     * is destructive and recursive, so the host owns the confirmation: there is
+     * deliberately no silent `delete`.
+     */
+    requestDelete(threadId: string): void;
+}
+/**
+ * Render a plugin component in the thread header's action row.
+ *
+ * The frontend sibling of the backend `bb.ui.registerThreadAction`, which
+ * renders a host-owned button and runs server-side. Use that one for "do a
+ * thing"; use this one when the control must draw live state.
+ *
+ * The host places it at the left end of the action row, before the workspace
+ * button, git actions, the panel toggle, maximize, and close. That row is a
+ * 48px chrome row with 28px controls: render one inline control that fits, and
+ * put anything taller in a portalled popover.
+ */
+interface PluginThreadHeaderActionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /**
+     * Names the region the host wraps around your component (a labelled group).
+     * It does NOT label your control: an icon-only button still needs its own
+     * accessible name.
+     */
+    title: string;
+    component: ComponentType<PluginThreadHeaderActionProps>;
+}
+/** One pane's place in the split layout, as fractions of the split area. */
+interface PluginSidebarSplitPane {
+    paneId: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** This pane holds the thread the row represents. */
+    isMe: boolean;
+    isFocused: boolean;
+}
+/**
+ * Drag-to-split support for one row, plus where that thread currently sits in
+ * the split layout.
+ */
+interface PluginSidebarThreadSplit {
+    /**
+     * Spread onto the row's interactive element. Carries the pointer handler
+     * that starts a split drag; empty when splits are unavailable, so spreading
+     * it is always safe.
+     *
+     * The host owns every rule: the gesture engages only once the pointer leaves
+     * the sidebar toward the main area (so a list with its own drag-to-reorder
+     * keeps working), an edge drop splits, a center drop replaces, an
+     * already-open thread focuses its pane, and the pane cap coerces a split
+     * into a replace.
+     */
+    splitProps: {
+        onPointerDown?: (event: react.PointerEvent<HTMLElement>) => void;
+    };
+    /**
+     * False on compact viewports, when the user disabled splits, and for an
+     * unknown thread id. Gate any "open in split" affordance you draw on it.
+     */
+    isAvailable: boolean;
+    /**
+     * Where this thread sits in the split layout, or null when it is not open in
+     * one (including single-pane layouts). Draw a mini-map, a tint, or nothing.
+     */
+    layout: {
+        panes: readonly PluginSidebarSplitPane[];
+    } | null;
+}
+/**
+ * Replace the sidebar's thread list with a plugin component.
+ *
+ * Unlike every other slot, this one is EXCLUSIVE: two lists cannot share one
+ * scroll area. The built-in list stays the default; the user picks a provider
+ * in Settings → Appearance, stored per client. A provider that is uninstalled,
+ * disabled, or crashing falls back to the built-in list rather than leaving
+ * the user with no sidebar.
+ *
+ * The plugin gets the scrolling list and nothing else. The New-thread button,
+ * the search field, the plugin nav rows, and the footer stay host-rendered in
+ * every sidebar — they are shared surfaces (other plugins live in two of
+ * them), and a replaced list must not be able to remove them.
+ */
+interface PluginThreadListRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Label in the Settings → Appearance → Sidebar picker. */
+    title: string;
+    /** Optional one-line description under the title in that picker. */
+    description?: string;
+    component: ComponentType<PluginThreadListProps>;
+}
+/**
+ * Register this plugin as a viewer/editor for file extensions. The user
+ * picks (and can set as default) an opener per extension via the file tab's
+ * "Open with" menu; matching files opened in the panel then render
+ * `component` in a plugin tab instead of the built-in preview. Applies to
+ * working-tree, host, and thread-storage files — never to git-ref snapshots
+ * (diff views always use the built-in preview). The built-in preview stays
+ * one menu click away, and a missing/disabled opener falls back to it.
+ */
+interface PluginFileOpenerRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Label in the "Open with" menu (e.g. "Notes editor"). */
+    title: string;
+    /** Lowercase extensions without the dot (e.g. ["md", "mdx"]). */
+    extensions: readonly string[];
+    component: ComponentType<PluginFileOpenerProps>;
+}
+/**
+ * Register a leaf message directive rendered inside assistant (and nested
+ * agent) message Markdown. `id` is the directive name: `inline-vis` matches
+ * `::inline-vis{file="demo.html"}`.
+ */
+interface PluginMessageDirectiveRegistration {
+    /**
+     * The directive name. Lowercase kebab-case beginning with a letter.
+     */
+    id: string;
+    component: ComponentType<PluginMessageDirectiveProps>;
+}
+/**
+ * A narrow, stable reference to one rendered chat message — NOT an internal
+ * timeline row. `sourceSeqEnd` is the last source event sequence the message
+ * covers, the anchor the server accepts for provider-history forks.
+ */
+interface ThreadChatMessageReference {
+    id: string;
+    threadId: string;
+    role: "user" | "assistant";
+    /** Visible text of the message. */
+    text: string;
+    sourceSeqEnd: number;
+}
+interface PluginMessageActionThreadPanelOptions {
+    /** A `threadPanelAction` id registered by this same plugin. */
+    actionId: string;
+    title?: string;
+    params?: JsonValue;
+}
+/** Context handed to a `messageAction`'s `run`. */
+interface PluginMessageActionContext {
+    /** The thread whose timeline surfaced the action. */
+    threadId: string;
+    message: ThreadChatMessageReference;
+    /**
+     * Present only when the action was invoked from the text-selection menu;
+     * the exact text the user highlighted inside `message`.
+     */
+    selectedText?: string;
+    /**
+     * Open one of this plugin's `threadPanelAction` components in the current
+     * thread's side panel — the registration-callback equivalent of
+     * `useBbNavigate().openThreadPanel`. Returns true when the host
+     * accepted (the action id exists and the surface has a panel); false
+     * otherwise.
+     */
+    openPanel(options: PluginMessageActionThreadPanelOptions): boolean;
+}
+/**
+ * An action on chat messages: an icon button in the per-message action bar
+ * (user and assistant messages) and an entry in the assistant-message
+ * text-selection menu. Host-rendered chrome — the plugin supplies title,
+ * icon hint, and `run` behavior only.
+ */
+interface PluginMessageActionRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Tooltip / menu label for the action. */
+    title: string;
+    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
+    icon?: string;
+    /**
+     * Runs when the user activates the action. Errors (sync or async) are
+     * contained and logged; they never break the timeline.
+     */
+    run(context: PluginMessageActionContext): void | Promise<void>;
+}
+interface PluginAppSlots {
+    homepageSection(registration: PluginHomepageSectionRegistration): void;
+    settingsSection(registration: PluginSettingsSectionRegistration): void;
+    navPanel(registration: PluginNavPanelRegistration): void;
+    /**
+     * Add an action to an existing thread's panel launcher. This slot is
+     * thread-only; use `experimental_newThreadPanelAction` for root compose.
+     */
+    threadPanelAction(registration: PluginThreadPanelActionRegistration): void;
+    /**
+     * Add an action to the root New thread screen's panel launcher (see
+     * {@link PluginNewThreadPanelActionRegistration}). Experimental: see
+     * docs/api_to_audit.md.
+     */
+    experimental_newThreadPanelAction(registration: PluginNewThreadPanelActionRegistration): void;
+    pendingInteraction(registration: PluginPendingInteractionRegistration): void;
+    sidebarFooterAction(registration: PluginSidebarFooterActionRegistration): void;
+    /**
+     * Replace the sidebar's thread list (see
+     * {@link PluginThreadListRegistration}). Experimental: see
+     * docs/api_to_audit.md for what to audit before the prefix drops.
+     */
+    experimental_threadList(registration: PluginThreadListRegistration): void;
+    /**
+     * Render a component in the thread header's action row (see
+     * {@link PluginThreadHeaderActionRegistration}). Experimental: see
+     * docs/api_to_audit.md.
+     */
+    experimental_threadHeaderAction(registration: PluginThreadHeaderActionRegistration): void;
+    fileOpener(registration: PluginFileOpenerRegistration): void;
+    messageDirective(registration: PluginMessageDirectiveRegistration): void;
+    messageAction(registration: PluginMessageActionRegistration): void;
+}
+interface PluginAppComposer {
+    customize(registration: ComposerCustomization): void;
+}
+/** Stable lifecycle values for one content-script instance in one bb client. */
+interface PluginContentScriptContext {
+    /** The id of the plugin that owns this script. */
+    readonly pluginId: string;
+    /** Monotonic per-client generation, starting at 1. */
+    readonly generation: number;
+    /** Aborted before cleanup begins on replacement, deactivation, or teardown. */
+    readonly signal: AbortSignal;
+    /**
+     * Persistently decorate any thread row for this plugin generation.
+     *
+     * The status is owned by the frontend generation and therefore survives
+     * route changes. Passing `null` clears the plugin's status for that thread.
+     * The host clears every remaining status when the frontend generation
+     * deactivates.
+     *
+     * Optional so bundles can feature-detect support while this experimental
+     * surface rolls out across 0.x clients.
+     */
+    readonly experimental_setThreadRowStatus?: (threadId: string, status: PluginComposerThreadRowStatus | null) => void;
+}
+/** Cleanup returned by a frontend content script. */
+type PluginContentScriptDisposer = () => void | Promise<void>;
+/**
+ * Trusted same-origin JavaScript/TypeScript mounted once per active frontend
+ * generation in each bb app window or browser tab.
+ */
+interface PluginContentScriptRegistration {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /**
+     * Install behavior into the bb app shell. The host awaits a returned
+     * promise, contains failures, and calls the returned disposer exactly once.
+     */
+    mount(context: PluginContentScriptContext): void | PluginContentScriptDisposer | Promise<void | PluginContentScriptDisposer>;
+}
+/** Lifecycle surface for trusted frontend content scripts. */
+interface PluginAppContentScripts {
+    register(registration: PluginContentScriptRegistration): void;
+}
+interface PluginAppBuilder {
+    slots: PluginAppSlots;
+    composer: PluginAppComposer;
+    contentScripts: PluginAppContentScripts;
+}
+type PluginAppSetup = (app: PluginAppBuilder) => void;
+/**
+ * The opaque product of `definePluginApp` — a plugin's `app.tsx` default
+ * export. The host re-runs `setup` against a fresh collector on every
+ * (re)interpretation, replacing that plugin's registrations wholesale.
+ */
+interface PluginAppDefinition {
+    /** Brand the host checks before interpreting a bundle's default export. */
+    readonly __bbPluginApp: true;
+    readonly setup: PluginAppSetup;
+}
+interface PluginRpcClient<Contract extends PluginRpcContract = PluginRpcContract> {
+    /**
+     * Invoke one of the plugin's `bb.rpc` methods (POST
+     * /api/v1/plugins/&lt;id&gt;/rpc/&lt;method&gt;). Resolves with the method's
+     * inferred output; rejects with an `Error` carrying the server's message,
+     * stable `code`, and validation `issues` when present.
+     */
+    call<Method extends Extract<keyof Contract, string>>(method: Method, ...args: PluginRpcCallArgs<Contract[Method]>): Promise<PluginRpcResult<Contract[Method]>>;
+}
+interface PluginSettingsState {
+    /**
+     * Effective non-secret setting values (secret settings are excluded —
+     * read them server-side). Undefined while loading or unavailable.
+     */
+    values: Record<string, string | boolean> | undefined;
+    isLoading: boolean;
+}
+/** State of the app's shared realtime connection to the bb server. */
+type PluginRealtimeConnectionState = "connecting" | "connected" | "reconnecting";
+/** Where `useComposer()` writes. */
+type PluginComposerScope = {
+    kind: "thread";
+    threadId: string;
+} | {
+    kind: "queued-message";
+    threadId: string;
+    queuedMessageId: string;
+} | {
+    kind: "side-chat";
+    projectId: string;
+    parentThreadId: string;
+    tabId: string;
+    childThreadId: string | null;
+} | {
+    kind: "new-thread";
+    /** Root compose's effective selected project; null only while unresolved. */
+    projectId: string | null;
+};
+/** One plugin-owned composer customization registration. */
+interface ComposerCustomization {
+    /** Unique within the plugin; letters, digits, `-`, `_`. */
+    id: string;
+    /** Composer kinds where this customization is active; omit for all kinds. */
+    scopes?: readonly PluginComposerScope["kind"][];
+    actions?: readonly {
+        id: string;
+        component: ComponentType;
+    }[];
+    banners?: readonly {
+        id: string;
+        /** Host chrome around the banner. Defaults to `"card"`. */
+        chrome?: "card" | "bare";
+        component: ComponentType;
+    }[];
+    plusMenu?: readonly ComposerPlusMenuItem[];
+    richText?: ComposerRichTextSpec;
+}
+/** Host-rendered menu row in the composer's `+` menu. */
+interface ComposerPlusMenuItem {
+    id: string;
+    label: string;
+    /** BB icon name; unknown names fall back to the generic plugin icon. */
+    icon?: string;
+    /** Accessible description for the host-rendered row. */
+    description?: string;
+    disabled?: boolean | ((view: ComposerView) => boolean);
+    run(context: {
+        composer: PluginComposerApi;
+        view: ComposerView;
+    }): void | Promise<void>;
+}
+/** Reactive read-side of the composer a plugin surface is mounted in. */
+interface ComposerView {
+    scope: PluginComposerScope;
+    layout: "expanded" | "compact" | "zen";
+    draft: {
+        text: string;
+        isEmpty: boolean;
+        attachmentCount: number;
+    };
+    run: {
+        isRunning: boolean;
+        isSubmitting: boolean;
+    };
+}
+interface ComposerRichTextSpec {
+    /** Content-derived paint: match ranges receive `className`; text is never mutated. */
+    effects?: readonly {
+        id: string;
+        /** Plain-text offsets into the current structured draft. */
+        match(text: string): readonly {
+            from: number;
+            to: number;
+        }[];
+        className: string;
+    }[];
+    /** Debounced, read-only observation of the structured draft. */
+    onDraftChange?(draft: ComposerStructuredDraft, view: ComposerView): void;
+}
+interface ComposerStructuredDraft {
+    text: string;
+    mentions: readonly {
+        from: number;
+        to: number;
+        provider: string;
+        id: string;
+        label: string;
+    }[];
+}
+/** Host-rendered paint applied to the editable composer text. */
+interface PluginComposerTextEffect {
+    className: string;
+}
+/** Host-rendered status that temporarily replaces a thread's draft glyph. */
+interface PluginComposerThreadRowStatus {
+    /** BB icon-name hint; unknown names fall back to the generic plugin icon. */
+    icon: string;
+    /** Accessible label for the status glyph. */
+    label: string;
+    /**
+     * Semantic host treatment for the status glyph. `running` automatically
+     * shimmers; terminal `success` and `error` tones are static. Defaults to the
+     * neutral tone.
+     */
+    tone?: "default" | "running" | "success" | "error";
+}
+/** An @-mention pill bound to one of the calling plugin's mention providers. */
+interface PluginComposerMention {
+    /** Mention provider id registered by THIS plugin via `bb.ui.registerMentionProvider`. */
+    provider: string;
+    /** Item id your provider's `resolve` will receive at send time. */
+    id: string;
+    /** Pill text shown in the composer. */
+    label: string;
+}
+/**
+ * Programmatic access to the chat composer draft — the same shared draft the
+ * built-in "Add to chat" affordances (file preview, diff, terminal selections)
+ * write to. While a queued message is being edited, writes land in that
+ * message's inline editor. In a side chat, writes land in the visible side-chat
+ * draft. Otherwise, inside a thread context writes land in that thread's draft;
+ * anywhere else (nav panel, homepage section) they seed the new-thread composer
+ * draft, which persists until the user sends or clears it.
+ */
+interface PluginComposerApi {
+    scope: PluginComposerScope;
+    /** Current plain text for this composer scope. */
+    readonly text: string;
+    /**
+     * Replace the draft's plain text. Attachments are preserved. Inline mentions
+     * outside the changed range are preserved and rebased; mentions overlapped
+     * by the replacement are removed because their text representation changed.
+     */
+    setText(next: string): void;
+    /**
+     * Replace the draft's plain text from the latest committed value. Uses the
+     * same structured-state reconciliation as `setText`.
+     */
+    updateText(updater: (current: string) => string): void;
+    /** Clear plain text without clearing independently attached files. */
+    clear(): void;
+    /**
+     * Apply a host-rendered effect to this composer's editable text, or clear it.
+     * Effects are scoped to the calling plugin and automatically clear when the
+     * slot unmounts or its composer scope changes.
+     */
+    setTextEffect(effect: PluginComposerTextEffect | null): void;
+    /**
+     * Lock or unlock editing for this composer. Locks are scoped to the calling
+     * plugin and automatically release when the slot unmounts or its composer
+     * scope changes.
+     */
+    setInputLock(locked: boolean): void;
+    /**
+     * Append text to the draft as a `> ` blockquote block and focus the
+     * composer. Blank text is a no-op. This is the "reference this selection
+     * in chat" primitive.
+     */
+    addQuote(text: string): void;
+    /**
+     * Insert an @-mention pill that resolves through this plugin's mention
+     * provider at send time — the durable way to reference an entity whose
+     * content should be fetched fresh when the message is sent.
+     */
+    insertMention(mention: PluginComposerMention): void;
+    /** Focus the composer caret at the end of the draft. */
+    focus(): void;
+}
+/**
+ * A consumer-supplied action on the messages of one `ThreadChat` instance,
+ * rendered in the embedded timeline's per-message action bar alongside the
+ * native and slot-registered actions. Unlike the `messageAction` slot this is
+ * scoped to the rendering component, not registered globally.
+ */
+interface ThreadChatMessageAction {
+    /** Unique within this ThreadChat instance; letters, digits, `-`, `_`. */
+    id: string;
+    /** Tooltip / menu label for the action. */
+    title: string;
+    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
+    icon?: string;
+    /**
+     * Message roles the action applies to. Omitted = both user and assistant
+     * messages.
+     */
+    roles?: readonly ("user" | "assistant")[];
+    /**
+     * Runs when the user activates the action. Errors (sync or async) are
+     * contained and logged; they never break the timeline.
+     */
+    run(message: ThreadChatMessageReference): void | Promise<void>;
+}
+/**
+ * Props of the host-owned `ThreadChat` component — one thread's chat
+ * (timeline, and for the composer variants the full send/queue/draft
+ * engine), rendered by the BB app inside a plugin slot. This is the
+ * deliberate exception to the no-host-components rule (§5.5): a stable
+ * product capability, not a UI kit. Versioned additive like slot props;
+ * internal timeline rows, query hooks, and prompt-box configuration are
+ * deliberately not exposed.
+ */
+interface ThreadChatProps {
+    threadId: string;
+    /**
+     * "full" (default) is the page presentation (centered reading width);
+     * "compact" is the side-panel presentation; "timeline" renders the
+     * transcript without a composer.
+     */
+    variant?: "full" | "compact" | "timeline";
+    /**
+     * "contained" (default) fills and scrolls inside a bounded parent;
+     * "document" grows with its content and defers scrolling to the page.
+     */
+    layout?: "contained" | "document";
+    /** Bump to focus the composer (ignored by `variant: "timeline"`). */
+    focusRequest?: number;
+    /**
+     * Who controls the permission mode sends run with. "inherit" (default)
+     * pins every send to the thread's own resolved default and renders the
+     * picker as a dimmed label — a plugin surface can never widen it.
+     * "editable" gives this chat its own picker, so the user can raise or
+     * lower permissions for this thread independently of the thread it was
+     * forked from. Ignored by `variant: "timeline"` (no composer).
+     */
+    permissionPolicy?: "inherit" | "editable";
+    className?: string;
+    /** Rendered above the conversation, scrolling with it. */
+    leadingContent?: ReactNode;
+    /**
+     * Actions rendered in this instance's per-message action bar (see
+     * {@link ThreadChatMessageAction}).
+     */
+    messageActions?: readonly ThreadChatMessageAction[];
+}
+/**
+ * Every selection the composer resolved, JSON-serializable so a plugin can
+ * forward it to its own backend rpc verbatim and hand it straight to
+ * `bb.sdk.threads.spawn`.
+ *
+ * The split is deliberate: the composer owns *user selections*, the plugin
+ * owns *filing and attribution*. `bb.sdk.threads.spawn` auto-fills
+ * `origin: "plugin"` and `originPluginId`, so a thread created this way stays
+ * attributed to the plugin — which it would not be if the component created
+ * the thread itself. The plugin adds `sectionId`, `parentThreadId`, `title`,
+ * and `visibility` to the request on its own; they are deliberately not
+ * composer props.
+ */
+interface NewThreadRequest {
+    projectId: string;
+    providerId: string;
+    model: string;
+    reasoningLevel: ReasoningLevel;
+    permissionMode: PermissionMode;
+    /** Omitted when the selected provider has no service tiers. */
+    serviceTier?: ServiceTier;
+    /**
+     * Per-field provenance (caller-explicit vs. default) for the execution
+     * options above, forwarded to `spawn` so the server records what the user
+     * actually chose.
+     */
+    executionInputSources: CreateExecutionInputSources;
+    environment: CreateThreadEnvironmentArgs;
+    input: PromptInput[];
+}
+/**
+ * Props of the host-owned `experimental_NewThreadComposer` component — bb's
+ * full new-thread compose surface (prompt editor with @-mentions and expand,
+ * attachments, provider/model/reasoning picker, voice, submit, and the row
+ * beneath with project, environment, branch-from, and permission mode),
+ * rendered by the BB app inside a plugin slot.
+ *
+ * It is the create-side counterpart to `ThreadChat`: same deliberate
+ * exception to the no-host-components rule (§5.5), same additive versioning.
+ */
+interface NewThreadComposerProps {
+    /** Seeds the project picker. The user can change it. */
+    defaultProjectId?: string;
+    /**
+     * Seeds the provider picker. Like every `default*` prop this is a SEED, not
+     * a controlled value: the composer stays uncontrolled, the user can change
+     * it, and when omitted the composer falls back to the project's remembered
+     * execution defaults exactly as before. When provided it takes precedence
+     * over those project defaults.
+     *
+     * Re-seeding: the `default*` props are value-compared each render. When any
+     * of them changes after mount, the composer re-seeds EVERY execution and
+     * environment selection from the new props — including selections the user
+     * had already touched — so switching between two saved records in the same
+     * mounted composer reloads that record's values (the same rule
+     * `defaultProjectId` already follows).
+     *
+     * Every seeded field is reported as caller-explicit in the submitted
+     * request's `executionInputSources`. That is what makes the seed survive
+     * `threads.spawn`: the server drops a requested `providerId`/`model` that
+     * carries no provenance source and re-derives it from the project's stored
+     * defaults, which would silently undo the seed.
+     */
+    defaultProviderId?: string;
+    /** Seeds the model picker. Same seed semantics as {@link defaultProviderId}. */
+    defaultModel?: string;
+    /**
+     * Seeds the reasoning-level picker. Same seed semantics as
+     * {@link defaultProviderId}. If the seeded model does not support this
+     * level, the composer reconciles to the closest supported one.
+     */
+    defaultReasoningLevel?: ReasoningLevel;
+    /**
+     * Seeds the service-tier picker. Same seed semantics as
+     * {@link defaultProviderId}. Ignored (and omitted from the submitted
+     * request) when the selected provider has no service tiers.
+     */
+    defaultServiceTier?: ServiceTier;
+    /** Seeds the permission-mode picker. Same seed semantics as {@link defaultProviderId}. */
+    defaultPermissionMode?: PermissionMode;
+    /**
+     * Seeds the environment and branch pickers from a previously submitted
+     * `NewThreadRequest.environment`. Same seed semantics as
+     * {@link defaultProviderId}: a seed the user can change, taking precedence
+     * over the composer's own environment default when provided.
+     *
+     * Round trip: feeding a submitted request's `environment` back in and
+     * resubmitting untouched reproduces an equivalent environment, with these
+     * documented limits — the composer cannot represent every args variant:
+     *
+     * - `{ type: "project-default" }` seeds nothing; the composer resolves its
+     *   own default and submits that concrete environment instead.
+     * - A `host` environment whose host no longer exists (or whose project has
+     *   no source on it) falls back to the composer's default host, exactly as
+     *   the primary compose surface would.
+     * - A `reuse` environment whose worktree no longer has unarchived threads
+     *   falls back the same way.
+     * - An `unmanaged` workspace's `path` has no composer control; the seeded
+     *   selection submits `path: null` (the host's configured checkout). The
+     *   composer itself never produces a non-null `path`, so real round trips
+     *   are unaffected.
+     * - A `managed-worktree` with `baseBranch: { kind: "default" }` leaves the
+     *   branch picker on its default, which may resolve to a named base branch
+     *   when the project configures a dedicated worktree base — the same branch
+     *   the original `default` submission would have created from.
+     */
+    defaultEnvironment?: CreateThreadEnvironmentArgs;
+    /** Seeds the draft, only while the draft is still empty. */
+    initialPrompt?: string;
+    placeholder?: string;
+    /**
+     * "contained" (default) fills and scrolls inside a bounded parent;
+     * "document" grows with its content and defers scrolling to the page.
+     */
+    layout?: "contained" | "document";
+    /** Bump to focus the editor. */
+    focusRequest?: number;
+    className?: string;
+    /**
+     * Where the draft persists. Drafts survive reloads and are shared by every
+     * composer using the same key; defaults to a key scoped to this plugin.
+     */
+    draftKey?: string;
+    /**
+     * Fires on submit with every selection resolved. The draft clears when this
+     * resolves and is KEPT if it throws, so a failed create never loses what the
+     * user typed.
+     */
+    onSubmit: (request: NewThreadRequest) => void | Promise<void>;
+}
+/**
+ * Props of the host-owned `Markdown` component — bb's chat message renderer
+ * (the same typography, spacing, and code styling as timeline messages).
+ * Use it wherever plugin UI quotes or previews message content so it reads
+ * like the rest of the chat. Like `ThreadChat`, this is a stable product
+ * capability, not a UI kit; renderer internals stay private.
+ */
+interface MarkdownProps {
+    /** Markdown source, rendered exactly like a chat message body. */
+    content: string;
+    className?: string;
+}
+/** Current app selection, derived from the route. */
+interface BbContext {
+    projectId: string | null;
+    threadId: string | null;
+}
+interface BbNavigate {
+    toThread(threadId: string): void;
+    toProject(projectId: string): void;
+    /**
+     * Navigate to one of this plugin's own nav panels by its `path`.
+     * `subPath` targets a location inside the panel (the component's
+     * `subPath` prop); `replace` swaps the current history entry instead of
+     * pushing — use it for redirects so back does not bounce.
+     */
+    toPluginPanel(path: string, options?: {
+        subPath?: string;
+        replace?: boolean;
+    }): void;
+    /**
+     * Navigate to the root compose surface (the new-thread screen). Pass
+     * `initialPrompt` to seed the composer draft and `focusPrompt` to focus the
+     * composer on arrival — the pairing behind "Create via chat" style entry
+     * points that drop the user into chat with a prefilled prompt.
+     */
+    toCompose(options?: {
+        initialPrompt?: string;
+        focusPrompt?: boolean;
+    }): void;
+    /**
+     * Open one of this plugin's registered thread-panel actions in the current
+     * thread surface. Returns false when the surface has no thread side panel or
+     * the action is unavailable.
+     */
+    openThreadPanel(options: {
+        actionId: string;
+        title?: string;
+        params?: JsonValue;
+    }): boolean;
+}
+/**
+ * Everything `@get-bb/plugin-sdk/app` resolves to at runtime. The BB app builds
+ * the real implementation and `satisfies` this interface; `bb plugin build`
+ * shims the specifier to that object on `globalThis.__bbPluginRuntime`.
+ */
+interface PluginSdkApp {
+    definePluginApp(setup: PluginAppSetup): PluginAppDefinition;
+    useRpc<Contract extends PluginRpcContract = PluginRpcContract>(): PluginRpcClient<Contract>;
+    useRealtime(channel: string, handler: (payload: unknown) => void): void;
+    /**
+     * Observe the same shared connection that delivers `useRealtime` signals.
+     * Use a subsequent transition to `connected` to reconcile server state that
+     * may have changed while ephemeral signals could not be delivered. The first
+     * connection can transition from `connecting` and is not a reconnection.
+     */
+    useRealtimeConnectionState(): PluginRealtimeConnectionState;
+    useSettings(): PluginSettingsState;
+    useBbContext(): BbContext;
+    useBbNavigate(): BbNavigate;
+    useComposer(): PluginComposerApi;
+    /**
+     * The sidebar's live thread view (see {@link PluginSidebarThreadsState}).
+     * Reads the host's own cache and realtime subscriptions, so it costs no
+     * extra request and updates exactly when the built-in sidebar does.
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_useSidebarThreads(): PluginSidebarThreadsState;
+    /**
+     * Thread actions bound to the host's mutations (see
+     * {@link PluginSidebarThreadActions}). Experimental: see
+     * docs/api_to_audit.md.
+     */
+    experimental_useSidebarThreadActions(): PluginSidebarThreadActions;
+    /**
+     * The pull request for one thread's branch (see
+     * {@link PluginSidebarThreadPullRequestState}).
+     *
+     * Per row and opt-in, because it costs a git-host lookup: it is NOT on the
+     * thread payload every sidebar loads. Threads sharing an environment share
+     * one query, and the host owns the polling and staleness rules — an open PR
+     * with pending checks refreshes, a merged one does not.
+     *
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_useSidebarThreadPullRequest(threadId: string): PluginSidebarThreadPullRequestState;
+    /**
+     * Per-row drag-to-split support (see {@link PluginSidebarThreadSplit}).
+     * Call it once per rendered row, like the built-in sidebar does.
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_useSidebarThreadSplit(threadId: string): PluginSidebarThreadSplit;
+    /**
+     * The host-owned chat component (see {@link ThreadChatProps}). Together
+     * with `Markdown`, the only components the SDK ships — everything else
+     * stays vendored per §5.5.
+     */
+    ThreadChat: ComponentType<ThreadChatProps>;
+    /**
+     * The host-owned chat-message markdown renderer (see
+     * {@link MarkdownProps}).
+     */
+    Markdown: ComponentType<MarkdownProps>;
+    /**
+     * The host-owned new-thread compose surface (see
+     * {@link NewThreadComposerProps}). Experimental: see
+     * docs/api_to_audit.md for what to audit before the prefix drops.
+     */
+    experimental_NewThreadComposer: ComponentType<NewThreadComposerProps>;
+    useComposerView(): ComposerView;
+}
+
+declare const definePluginApp: (setup: PluginAppSetup) => PluginAppDefinition;
+declare const ThreadChat: react.ComponentType<ThreadChatProps>;
+declare const Markdown: react.ComponentType<MarkdownProps>;
+declare const experimental_NewThreadComposer: react.ComponentType<NewThreadComposerProps>;
+declare const useRpc: <Contract extends PluginRpcContract = Readonly<Record<string, PluginRpcMethodContract<StandardSchemaV1<unknown, unknown>, StandardSchemaV1<unknown, unknown>>>>>() => PluginRpcClient<Contract>;
+declare const useRealtime: (channel: string, handler: (payload: unknown) => void) => void;
+declare const useRealtimeConnectionState: () => PluginRealtimeConnectionState;
+declare const useSettings: () => PluginSettingsState;
+declare const useBbContext: () => BbContext;
+declare const useBbNavigate: () => BbNavigate;
+declare const useComposer: () => PluginComposerApi;
+declare const useComposerView: () => ComposerView;
+declare const experimental_useSidebarThreads: () => PluginSidebarThreadsState;
+declare const experimental_useSidebarThreadActions: () => PluginSidebarThreadActions;
+declare const experimental_useSidebarThreadPullRequest: (threadId: string) => PluginSidebarThreadPullRequestState;
+declare const experimental_useSidebarThreadSplit: (threadId: string) => PluginSidebarThreadSplit;
+
+export { Markdown, ThreadChat, definePluginApp, experimental_NewThreadComposer, experimental_useSidebarThreadActions, experimental_useSidebarThreadPullRequest, experimental_useSidebarThreadSplit, experimental_useSidebarThreads, useBbContext, useBbNavigate, useComposer, useComposerView, useRealtime, useRealtimeConnectionState, useRpc, useSettings };
+export type { BbContext, BbNavigate, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAppBuilder, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageActionThreadPanelOptions, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginRealtimeConnectionState, PluginRpcCallArgs, PluginRpcClient, PluginRpcContract, PluginRpcError, PluginRpcErrorCode, PluginRpcHandlers, PluginRpcIssuePathSegment, PluginRpcMethodContract, PluginRpcResult, PluginRpcValidationIssue, PluginSdkApp, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsState, PluginSidebarFooterActionContext, PluginSidebarFooterActionProps, PluginSidebarFooterActionRegistration, PluginSidebarProject, PluginSidebarPullRequest, PluginSidebarSplitPane, PluginSidebarThread, PluginSidebarThreadActions, PluginSidebarThreadActivity, PluginSidebarThreadIndicator, PluginSidebarThreadPullRequestState, PluginSidebarThreadSplit, PluginSidebarThreadsState, PluginSidebarWorkspaceKind, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps };