@get-bb/plugin-sdk 0.4.6 → 0.4.8

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

@@ -0,0 +1,124 @@
+// 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
+
+/**
+ * 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>>;
+
+interface ExperimentalHostSignalContract<PayloadSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly payload: PayloadSchema;
+}
+type ExperimentalHostSignals = Readonly<Record<string, ExperimentalHostSignalContract>>;
+interface ExperimentalHostPaths {
+    /** Persistent directory scoped to this plugin on this daemon. */
+    readonly dataDir: string;
+    /** Temporary directory scoped to this worker process. */
+    readonly tempDir: string;
+}
+type ExperimentalHostWatchChangeType = "create" | "delete" | "update";
+interface ExperimentalHostWatchChange {
+    readonly path: string;
+    readonly type: ExperimentalHostWatchChangeType;
+}
+type ExperimentalHostWatchEvent = {
+    readonly kind: "changed";
+    readonly changes: readonly ExperimentalHostWatchChange[];
+} | {
+    readonly kind: "rescan-required";
+} | {
+    readonly kind: "watch-error";
+    readonly message: string;
+};
+interface ExperimentalHostWatchOptions {
+    /** Absolute directory observed by the daemon's native watcher service. */
+    readonly rootPath: string;
+    /** Root-relative ignore entries using the native watcher syntax. */
+    readonly ignoredPaths?: readonly string[];
+    /** Quiet period before one coalesced delivery. Defaults to 75 ms. */
+    readonly debounceMs?: number;
+    /** Maximum time changes may wait. Defaults to 500 ms. */
+    readonly maxWaitMs?: number;
+}
+interface ExperimentalHostWatchSubscription {
+    dispose(): Promise<void>;
+}
+interface ExperimentalHostWorkerLease {
+    /** Release this worker-retention lease. Safe to call more than once. */
+    dispose(): Promise<void>;
+}
+type ExperimentalHostWatchListener = (event: ExperimentalHostWatchEvent) => void | Promise<void>;
+interface ExperimentalHostRpcContext<Signals extends ExperimentalHostSignals = {}> {
+    /** Aborted when this request is cancelled or its worker is disposed. */
+    readonly signal: AbortSignal;
+    /** Aborted once for the lifetime of this worker process. */
+    readonly lifecycle: {
+        readonly signal: AbortSignal;
+    };
+    readonly experimental_paths: ExperimentalHostPaths;
+    /** Publish a validated, ephemeral event to this plugin's server entry. */
+    experimental_emitSignal<SignalName extends keyof Signals & string>(signal: SignalName, payload: StandardSchemaV1InferInput<Signals[SignalName]["payload"]>): Promise<void>;
+    /** Observe raw filesystem changes through the daemon's native watcher. */
+    experimental_watch(options: ExperimentalHostWatchOptions, listener: ExperimentalHostWatchListener): Promise<ExperimentalHostWatchSubscription>;
+    /**
+     * Keep this worker alive after the current call finishes. Active calls and
+     * filesystem watches already retain it; use this only for other background
+     * work. The daemon may stop an unretained worker after an idle period.
+     */
+    experimental_retainWorker(): ExperimentalHostWorkerLease;
+}
+type ExperimentalHostRpcHandlers<Contract extends PluginRpcContract, Signals extends ExperimentalHostSignals = {}> = {
+    [MethodName in keyof Contract]: (input: StandardSchemaV1InferOutput<Contract[MethodName]["input"]>, context: ExperimentalHostRpcContext<Signals>) => StandardSchemaV1InferInput<Contract[MethodName]["output"]> | Promise<StandardSchemaV1InferInput<Contract[MethodName]["output"]>>;
+};
+interface ExperimentalHostEntry<Contract extends PluginRpcContract = PluginRpcContract, Signals extends ExperimentalHostSignals = {}> {
+    readonly experimental_apiVersion: 1;
+    readonly contract: Contract;
+    readonly experimental_signals?: Signals;
+    readonly handlers: ExperimentalHostRpcHandlers<Contract, Signals>;
+    readonly dispose?: () => void | Promise<void>;
+}
+/** Define the single host executable exported by `bb.host`. */
+declare function experimental_defineHostEntry<const Contract extends PluginRpcContract, const Signals extends ExperimentalHostSignals = {}>(args: {
+    contract: Contract;
+    experimental_signals?: Signals;
+    handlers: ExperimentalHostRpcHandlers<Contract, Signals>;
+    dispose?: () => void | Promise<void>;
+}): ExperimentalHostEntry<Contract, Signals>;
+
+export { experimental_defineHostEntry };
+export type { ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignals, ExperimentalHostWatchChange, ExperimentalHostWatchChangeType, ExperimentalHostWatchEvent, ExperimentalHostWatchListener, ExperimentalHostWatchOptions, ExperimentalHostWatchSubscription, ExperimentalHostWorkerLease };

package/bundled-types/bb-plugin-sdk-internal-composer-customization-validation.d.ts

@@ -16,6 +16,11 @@ type RejectionReporter = (reason: string) => void;
  */
 declare function normalizePluginThreadRowStatus(value: unknown, onRejected: RejectionReporter): PluginComposerThreadRowStatus | null | undefined;
 declare function requireSlotId(kind: string, value: unknown): string;
+/**
+ * Provider ids follow the same character rules as slot ids, but they name a
+ * provider the host knows (`codex`, `acp-cursor`), not a per-plugin slot.
+ */
+declare function requireProviderId(kind: string, value: unknown): string;
 declare function requireMessageDirectiveId(kind: string, value: unknown): string;
 declare function requireNonEmptyString(kind: string, field: string, value: unknown): string;
 declare function requireOptionalString(kind: string, field: string, value: unknown): string | undefined;
@@ -27,4 +32,4 @@ declare function requireUniqueId(kind: string, seen: Set<string>, id: string): v
  */
 declare function collectComposerCustomization(registration: unknown, seenIds: Set<string>, onRejected: RejectionReporter): ComposerCustomization | null;
 
-export { PLUGIN_SLOT_ID_PATTERN, collectComposerCustomization, normalizePluginThreadRowStatus, requireComponent, requireMessageDirectiveId, requireNonEmptyString, requireOptionalString, requireSlotId, requireUniqueId };
+export { PLUGIN_SLOT_ID_PATTERN, collectComposerCustomization, normalizePluginThreadRowStatus, requireComponent, requireMessageDirectiveId, requireNonEmptyString, requireOptionalString, requireProviderId, requireSlotId, requireUniqueId };

package/bundled-types/bb-plugin-sdk-internal-host-policy.d.ts

@@ -16,6 +16,25 @@
  */
 declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 
+/**
+ * How completely a provider can clone one of its sessions — the single
+ * vocabulary shared by the provider declaration
+ * (`bb.agents.experimental_registerProvider`), the server→daemon
+ * `bridgeLaunch`, and the bridge's `initialize` handshake.
+ *
+ * - `"none"`: sessions cannot be cloned at all.
+ * - `"tip"`: only the current end of a session can be cloned (ACP
+ *   `session/fork`), so thread fork works but edit-past-message rewind
+ *   cannot.
+ * - `"checkpoint"`: a session can be recreated at an earlier point, which is
+ *   what edit-past-message rewind needs.
+ *
+ * The values are ordered least to most capable: a declaration is a ceiling
+ * the handshake may narrow but never widen.
+ */
+declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
+type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
+
 /**
  * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
  * Zod 4 schemas implement this interface directly; other validators can do
@@ -94,7 +113,107 @@ interface PluginCliExecutionResult {
     stderr: string;
     error?: PluginCliOutputLimitError;
 }
-type PluginMentionTrigger = "@" | "#" | "$" | "!" | "~";
+/**
+ * Permission modes a provider can run a session in — BB's own permission
+ * vocabulary, ordered least ("accept-edits") to most ("full") privileged.
+ */
+type PluginProviderPermissionMode = "accept-edits" | "auto" | "full";
+/**
+ * Coarse reasoning-effort ladder entries, ordered lowest to highest. The
+ * declared ladder is a fallback only: precise per-model reasoning sets come
+ * from the provider's model list at runtime.
+ */
+type PluginProviderReasoningLevel = "high" | "low" | "max" | "medium" | "none" | "ultra" | "ultracode" | "xhigh";
+/**
+ * Composer actions a provider supports, by name only. The skills
+ * slash-command typeahead is universal — BB injects skills into every
+ * provider — so it is implicit and never declared, and the composer owns the
+ * trigger syntax (`/plan `, `/goal `) rather than each declaration repeating
+ * it.
+ */
+type PluginProviderComposerAction = "goal" | "plan";
+/**
+ * Pre-session capability facts about a provider. A capability earns a field
+ * here only when it passes BOTH tests: (1) a consumer outside the provider's
+ * own plugin needs the fact, and (2) the fact is needed before / without a
+ * live session (picker rendering, route gating, cross-plugin tool
+ * composition — including with the host offline). Every boolean is a
+ * provider-native fact — the provider implements the feature; the flag only
+ * tells external consumers it exists. Everything else is a handshake fact the
+ * bridge reports at `initialize`, where it cannot drift from behavior.
+ */
+interface PluginProviderCapabilities {
+    /** The provider accepts a fast/priority service-tier choice — shows the
+     * service-tier toggle in the picker. */
+    supportsServiceTier: boolean;
+    /** The provider ships its own native ask-user-question tool — the
+     * ask-user-question plugin skips registering its duplicate. */
+    supportsNativeUserQuestion: boolean;
+    /**
+     * How completely the provider can clone a session: `"none"` (not at all),
+     * `"tip"` (only the current end, so thread fork works but edit-past-message
+     * rewind cannot), or `"checkpoint"` (recreate the session at an earlier
+     * point, which rewind needs). Gates the fork and edit-past-message
+     * affordances. The bridge reports the same fact at `initialize`, where it
+     * may narrow this declaration but never widen it.
+     */
+    fork: ProviderFork;
+    /** The provider accepts an explicit context-compaction request — gates the
+     * compact affordance. */
+    supportsManualCompaction: boolean;
+    /** The provider keeps its own thread archive, so BB mirrors archive and
+     * unarchive onto it instead of tracking the state only in bb's own rows. */
+    supportsThreadArchive: boolean;
+    /** The provider stores a thread name of its own, so BB forwards renames to
+     * it. */
+    supportsThreadRename: boolean;
+    /** The provider can run BB's Workflow tools — gates the workflows opt-in on
+     * new threads. */
+    supportsWorkflows: boolean;
+    /** Permission modes the provider can actually run in. Non-empty, no
+     * duplicates. */
+    permissionModes: readonly PluginProviderPermissionMode[];
+    /** The provider's coarse fallback reasoning ladder (see
+     * {@link PluginProviderReasoningLevel}). Non-empty, no duplicates. */
+    reasoningLevels: readonly PluginProviderReasoningLevel[];
+}
+/**
+ * One provider this plugin contributes to BB's provider registry.
+ *
+ * Ids are stable public identifiers — thread rows and routes reference them —
+ * and are collision-rejected: a declaration whose id matches another plugin's
+ * live registration, or reserves a first-party provider it does not own, is
+ * refused. Registrations are replaced wholesale on plugin reload, like every
+ * other plugin surface.
+ *
+ * A declaration is metadata only. The implementation is the plugin's own
+ * provider bridge, named by `bb.providerBridge` in the manifest and built into
+ * the artifact BB ships to hosts — declaring a provider without one is
+ * refused, because the picker entry would exist and no turn on it could ever
+ * run.
+ */
+interface PluginProviderDeclaration {
+    /** Stable provider id: 2–64 characters of lowercase letters, digits, and
+     * "-", starting with a letter or digit. Existing ids must never change —
+     * threads persist them. */
+    id: string;
+    /** Picker display name: 1–80 characters, non-blank. */
+    displayName: string;
+    /**
+     * Optional picker icon, in the same grammar as `bb.branding.icon`: either a
+     * named host glyph (`"Zap"`) or a plugin-relative path starting with `"./"`
+     * (`"./icons/agent.svg"`). Paths follow the manifest entry-path escape rules
+     * — no leading "/", no ".." segments, no backslashes.
+     */
+    icon?: string;
+    /** Pre-session capability facts (see the declaration tests on
+     * {@link PluginProviderCapabilities}). */
+    capabilities: PluginProviderCapabilities;
+    /** Composer actions this provider supports. No duplicates; may be empty
+     * (the universal skills typeahead is implicit). */
+    composerActions: readonly PluginProviderComposerAction[];
+}
+type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
 
 /**
  * Built-in dynamic tool names plugins may not shadow. Maintained by hand —
@@ -117,6 +236,7 @@ declare const PLUGIN_AGENT_SELECTION_MAX_IDS = 256;
 declare const PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
 declare const PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES: number;
 declare const MENTION_PROVIDER_ID_PATTERN: RegExp;
+declare const PROVIDER_ID_PATTERN: RegExp;
 declare const SETTING_KEY_PATTERN: RegExp;
 /**
  * Validate freeform descriptors from plugin code and merge them into the
@@ -129,13 +249,45 @@ declare function validateSettingsUpdate(descriptors: PluginSettingDescriptors, v
 declare const PLUGIN_MENTION_TRIGGER_VALUES: readonly ["@", "#", "$", "!", "~"];
 declare function isPluginMentionTrigger(value: unknown): value is PluginMentionTrigger;
 declare function normalizeMentionProviderTriggers(providerId: string, triggers: unknown): readonly PluginMentionTrigger[];
+declare const PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+declare const PLUGIN_PROVIDER_PERMISSION_MODE_VALUES: readonly ["accept-edits", "auto", "full"];
+declare const PLUGIN_PROVIDER_REASONING_LEVEL_VALUES: readonly ["none", "low", "medium", "high", "xhigh", "ultracode", "max", "ultra"];
+declare const PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES: readonly ["plan", "goal"];
+/**
+ * Validate one `bb.agents.experimental_registerProvider` declaration. Plugin
+ * sources are untyped at runtime, so every field is checked; the production
+ * host and the fake host both call this, so they accept and reject provider
+ * declarations identically. Throws a descriptive error on the first problem;
+ * returns a normalized, deeply frozen copy carrying only contract fields.
+ */
+declare function validatePluginProviderDeclaration(declaration: PluginProviderDeclaration): PluginProviderDeclaration;
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
 /** Duck-typed zod detection: plugin sources may carry their own zod copy,
  * so instanceof is useless — anything with safeParse is treated as zod. */
 declare function isZodSchemaLike(value: unknown): boolean;
+/**
+ * Reject recursive local references before a tool schema reaches a provider.
+ * Some providers reject the complete tool list when any one schema contains a
+ * recursive `$ref`, so this is a shared production/fake-host boundary rule.
+ */
+declare function assertNoRecursiveJsonSchemaReferences(schema: unknown, subject: string): void;
 /** Compact issue summary from a (possibly foreign-instance) zod error. */
 declare function summarizeParseIssues(error: unknown): string;
 declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResult, "error">, jsonOutput: boolean): PluginCliExecutionResult;
+/**
+ * Adopt the value a plugin HTTP route handler returned.
+ *
+ * Plugin handlers can run in a different realm (jiti-loaded modules, bundled
+ * fetch polyfills), so a valid `Response` from a handler can fail
+ * `instanceof Response` in the host (#1661). Both the real host and the fake
+ * host accept a structurally valid Response from any realm and re-wrap it
+ * into a this-realm `Response`, so Hono always consumes a native object and a
+ * malformed return still fails at the invoke boundary with a pointed error.
+ *
+ * The body streams through: a foreign `body` stream is piped chunk by chunk
+ * with cancellation forwarded to the source, so no full-size buffer is made.
+ */
+declare function adoptHttpRouteResponse(value: unknown): Response;
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SETTING_KEY_PATTERN, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validateSettingsUpdate };
+export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validatePluginProviderDeclaration, validateSettingsUpdate };

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

@@ -0,0 +1,37 @@
+// 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 { PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginProviderIconRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
+
+/** Validated registrations produced by one plugin app setup execution. */
+interface CollectedPluginAppRegistrations {
+    homepageSections: PluginHomepageSectionRegistration[];
+    settingsSections: PluginSettingsSectionRegistration[];
+    navPanels: PluginNavPanelRegistration[];
+    threadPanelActions: PluginThreadPanelActionRegistration[];
+    newThreadPanelActions: PluginNewThreadPanelActionRegistration[];
+    composerCustomizations: ComposerCustomization[];
+    pendingInteractions: PluginPendingInteractionRegistration[];
+    sidebarFooterActions: PluginSidebarFooterActionRegistration[];
+    threadLists: PluginThreadListRegistration[];
+    threadHeaderActions: PluginThreadHeaderActionRegistration[];
+    fileOpeners: PluginFileOpenerRegistration[];
+    messageDirectives: PluginMessageDirectiveRegistration[];
+    messageActions: PluginMessageActionRegistration[];
+    providerIcons: PluginProviderIconRegistration[];
+    contentScripts: PluginContentScriptRegistration[];
+}
+/**
+ * Run a plugin app definition against the canonical validating collector.
+ * Both the BB app and the public test harness use this implementation so a
+ * registration accepted by one cannot be rejected or normalized differently
+ * by the other.
+ */
+declare function collectPluginAppRegistrations(definition: PluginAppDefinition, onComposerCustomizationRejected?: (reason: string) => void): CollectedPluginAppRegistrations;
+
+export { collectPluginAppRegistrations };
+export type { CollectedPluginAppRegistrations };