@get-bb/plugin-sdk 0.4.40 → 0.4.47

package/dist/testing/app.js

@@ -392,6 +392,127 @@ function normalizeExperimentalFileOpenOptions(value) {
 }
 
 // src/internal/plugin-app-collector.ts
+var sidebarFooterCommandSequence = 0;
+var SIDEBAR_FOOTER_ACTION_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "label",
+  "icon",
+  "kind",
+  "onActivate"
+]);
+var SIDEBAR_FOOTER_DISCLOSURE_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "label",
+  "icon",
+  "kind",
+  "component"
+]);
+var SidebarFooterItemRuntime = class {
+  listeners = /* @__PURE__ */ new Set();
+  snapshot = {
+    command: null
+  };
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getSnapshot = () => this.snapshot;
+  acknowledgeCommand = (sequence) => {
+    if (this.snapshot.command?.sequence !== sequence) return;
+    this.snapshot = { ...this.snapshot, command: null };
+    this.emit();
+  };
+  createDisclosureController() {
+    return Object.freeze({
+      open: () => this.request("open"),
+      close: () => this.request("close"),
+      toggle: () => this.request("toggle")
+    });
+  }
+  request(kind) {
+    sidebarFooterCommandSequence += 1;
+    this.snapshot = {
+      ...this.snapshot,
+      command: { sequence: sidebarFooterCommandSequence, kind }
+    };
+    this.emit();
+  }
+  emit() {
+    for (const listener of this.listeners) listener();
+  }
+};
+function adaptSidebarFooterAction(registration) {
+  return {
+    source: "sidebarFooterAction",
+    id: registration.id,
+    label: registration.title,
+    icon: registration.icon,
+    kind: "action",
+    onActivate: ({ openPluginDetails }) => registration.run({ openSettings: openPluginDetails }),
+    runtime: new SidebarFooterItemRuntime()
+  };
+}
+var SidebarFooterCollector = class {
+  constructor(collected, allCollected, seenIds) {
+    this.collected = collected;
+    this.allCollected = allCollected;
+    this.seenIds = seenIds;
+  }
+  collected;
+  allCollected;
+  seenIds;
+  register(registration) {
+    const kind = "experimental_sidebarFooter.register";
+    const id = requireSlotId(kind, registration?.id);
+    requireUniqueId(kind, this.seenIds, id);
+    const label = requireNonEmptyString(kind, "label", registration.label);
+    const icon = requireNonEmptyString(kind, "icon", registration.icon);
+    const runtime = new SidebarFooterItemRuntime();
+    if (registration.kind === "action") {
+      this.rejectUnknownKeys(kind, registration, SIDEBAR_FOOTER_ACTION_KEYS);
+      if (typeof registration.onActivate !== "function") {
+        throw new Error(`${kind}: "onActivate" must be a function`);
+      }
+      const item = {
+        id,
+        label,
+        icon,
+        kind: "action",
+        onActivate: registration.onActivate,
+        source: "experimental_sidebarFooter",
+        runtime
+      };
+      this.collected.push(item);
+      this.allCollected.push(item);
+      return;
+    }
+    if (registration.kind === "disclosure") {
+      this.rejectUnknownKeys(
+        kind,
+        registration,
+        SIDEBAR_FOOTER_DISCLOSURE_KEYS
+      );
+      const item = {
+        id,
+        label,
+        icon,
+        kind: "disclosure",
+        component: requireComponent(kind, registration.component),
+        source: "experimental_sidebarFooter",
+        runtime
+      };
+      this.collected.push(item);
+      this.allCollected.push(item);
+      return runtime.createDisclosureController();
+    }
+    throw new Error(`${kind}: "kind" must be "action" or "disclosure"`);
+  }
+  rejectUnknownKeys(kind, registration, allowed) {
+    for (const key of Object.keys(registration)) {
+      if (!allowed.has(key)) throw new Error(`${kind}: unknown field "${key}"`);
+    }
+  }
+};
 var NAV_PANEL_REGISTRATION_KEYS = new Set(
   Object.keys({
     id: true,
@@ -421,7 +542,9 @@ function rejectStaleNavPanelKeys(kind, registration) {
     }
   }
 }
+var sidebarFooterItemsByRegistrationSet = /* @__PURE__ */ new WeakMap();
 function collectPluginAppRegistrations(definition, onComposerCustomizationRejected = (reason) => console.warn(reason)) {
+  const sidebarFooterItems = [];
   const collected = {
     homepageSections: [],
     settingsSections: [],
@@ -432,6 +555,7 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
     composerCustomizations: [],
     pendingInteractions: [],
     sidebarFooterActions: [],
+    experimentalSidebarFooterItems: [],
     experimentalSidebarNavigations: [],
     threadLists: [],
     threadHeaderActions: [],
@@ -445,6 +569,7 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
     timelineRenderers: [],
     contentScripts: []
   };
+  sidebarFooterItemsByRegistrationSet.set(collected, sidebarFooterItems);
   const seenIds = {
     homepageSection: /* @__PURE__ */ new Set(),
     settingsSection: /* @__PURE__ */ new Set(),
@@ -454,7 +579,7 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
     newThreadPanelAction: /* @__PURE__ */ new Set(),
     composerCustomization: /* @__PURE__ */ new Set(),
     pendingInteraction: /* @__PURE__ */ new Set(),
-    sidebarFooterAction: /* @__PURE__ */ new Set(),
+    sidebarFooterItem: /* @__PURE__ */ new Set(),
     sidebarNavigation: /* @__PURE__ */ new Set(),
     threadList: /* @__PURE__ */ new Set(),
     threadHeaderAction: /* @__PURE__ */ new Set(),
@@ -645,16 +770,18 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
       sidebarFooterAction(registration) {
         const kind = "slots.sidebarFooterAction";
         const id = requireSlotId(kind, registration?.id);
-        requireUniqueId(kind, seenIds.sidebarFooterAction, id);
+        requireUniqueId(kind, seenIds.sidebarFooterItem, id);
         if (typeof registration.run !== "function") {
           throw new Error(`${kind}: "run" must be a function`);
         }
-        collected.sidebarFooterActions.push({
+        const legacyRegistration = {
           id,
           title: requireNonEmptyString(kind, "title", registration.title),
           icon: requireNonEmptyString(kind, "icon", registration.icon),
           run: registration.run
-        });
+        };
+        collected.sidebarFooterActions.push(legacyRegistration);
+        sidebarFooterItems.push(adaptSidebarFooterAction(legacyRegistration));
       },
       experimental_sidebarNavigation(registration) {
         const kind = "slots.experimental_sidebarNavigation";
@@ -816,6 +943,11 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
         });
       }
     },
+    experimental_sidebarFooter: new SidebarFooterCollector(
+      collected.experimentalSidebarFooterItems,
+      sidebarFooterItems,
+      seenIds.sidebarFooterItem
+    ),
     composer: {
       customize(registration) {
         const customization = collectComposerCustomization(

package/dist/testing/index.js

@@ -293,6 +293,42 @@ var RPC_METHOD_PATTERN = /^[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*$/;
 var BACKGROUND_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var CLI_COMMAND_NAME_PATTERN = /^[a-z0-9-]+$/;
 var AGENT_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var PLUGIN_PROVIDER_ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+var PLUGIN_PROVIDER_ENV_MAX_ENTRIES = 32;
+var pluginProviderEnvEntrySchema = z3.object({
+  name: z3.string().regex(PLUGIN_PROVIDER_ENV_NAME_PATTERN),
+  value: z3.union([
+    z3.string(),
+    z3.object({ serverPath: z3.string().startsWith("/") }).strict()
+  ]),
+  reason: z3.string(),
+  secret: z3.boolean()
+}).strict();
+var pluginProviderEnvEntriesSchema = z3.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
+  const names = /* @__PURE__ */ new Set();
+  for (let index = 0; index < entries.length; index += 1) {
+    const name = entries[index]?.name;
+    if (name !== void 0 && names.has(name)) {
+      context.addIssue({
+        code: "custom",
+        path: [index, "name"],
+        message: "must be unique within one resolver"
+      });
+    }
+    if (name !== void 0) names.add(name);
+  }
+});
+function validatePluginProviderEnvEntries(value) {
+  const parsed = pluginProviderEnvEntriesSchema.safeParse(value);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const path = issue?.path.length ? `[${issue.path.join(".")}] ` : "";
+    throw new Error(
+      `provider environment contribution ${path}${issue?.message ?? "is invalid"}`
+    );
+  }
+  return parsed.data;
+}
 var PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS = 4096;
 var PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS = 80;
 var PLUGIN_AGENT_SELECTION_MAX_IDS = 256;
@@ -2174,7 +2210,9 @@ function createFakePluginHostInternal(options, sharedState) {
           "ALTER TABLE _bb_migrations ADD COLUMN statement_hash TEXT"
         );
       }
-      const rows = database.prepare("SELECT id, statement_hash FROM _bb_migrations ORDER BY id").all();
+      const rows = database.prepare(
+        "SELECT id, statement_hash FROM _bb_migrations ORDER BY id"
+      ).all();
       const applied = /* @__PURE__ */ new Map();
       for (const row of rows) applied.set(row.id, row.statement_hash);
       const statementHashes = statements.map(migrationStatementHash);
@@ -2273,6 +2311,8 @@ function createFakePluginHostInternal(options, sharedState) {
     }
   };
   const httpRoutes = [];
+  const websocketRoutes = [];
+  const websocketSessions = /* @__PURE__ */ new Set();
   const http = {
     route(method, path, handler, opts) {
       assertLive();
@@ -2306,6 +2346,29 @@ function createFakePluginHostInternal(options, sharedState) {
         );
       }
       httpRoutes.push({ method: normalizedMethod, path, auth, handler });
+    },
+    experimental_websocket(path, handler, opts) {
+      assertLive();
+      if (typeof path !== "string" || !path.startsWith("/")) {
+        throw new Error(
+          `websocket route path must be a string starting with "/", got ${JSON.stringify(path)}`
+        );
+      }
+      if (typeof handler !== "function") {
+        throw new Error(
+          `websocket route handler for ${path} must be a function`
+        );
+      }
+      const auth = opts?.auth ?? "local";
+      if (auth !== "local" && auth !== "token" && auth !== "none") {
+        throw new Error(
+          `invalid auth mode "${String(auth)}" for websocket ${path} \u2014 use "local", "token", or "none"`
+        );
+      }
+      if (websocketRoutes.some((route) => route.path === path)) {
+        throw new Error(`websocket route ${path} is already registered`);
+      }
+      websocketRoutes.push({ path, auth, handler });
     }
   };
   const rpcHandlers = /* @__PURE__ */ new Map();
@@ -2466,6 +2529,8 @@ function createFakePluginHostInternal(options, sharedState) {
   };
   const agentTools = [];
   const providerRegistrations = [];
+  const providerEnvResolvers = /* @__PURE__ */ new Map();
+  const providerEnvHealthResolvers = /* @__PURE__ */ new Map();
   let agentConfigurationProvider = null;
   let instructionProvider = null;
   function registerProviderDeclaration(declaration) {
@@ -2931,6 +2996,44 @@ function createFakePluginHostInternal(options, sharedState) {
   const providers = {
     register(declaration) {
       return registerProviderDeclaration(declaration);
+    },
+    experimental_contributeEnv(providerId, resolve2) {
+      assertLive();
+      if (typeof providerId !== "string" || providerId.trim().length === 0) {
+        throw new Error(
+          "provider environment contribution requires a provider id"
+        );
+      }
+      if (providerEnvResolvers.has(providerId)) {
+        throw new Error(
+          `provider environment contribution for "${providerId}" is already registered`
+        );
+      }
+      if (typeof resolve2 !== "function") {
+        throw new Error(
+          "provider environment contribution requires a resolver function"
+        );
+      }
+      providerEnvResolvers.set(providerId, resolve2);
+    },
+    experimental_contributeEnvHealth(providerId, resolve2) {
+      assertLive();
+      if (typeof providerId !== "string" || providerId.trim().length === 0) {
+        throw new Error(
+          "provider environment health contribution requires a provider id"
+        );
+      }
+      if (providerEnvHealthResolvers.has(providerId)) {
+        throw new Error(
+          `provider environment health contribution for "${providerId}" is already registered`
+        );
+      }
+      if (typeof resolve2 !== "function") {
+        throw new Error(
+          "provider environment health contribution requires a resolver function"
+        );
+      }
+      providerEnvHealthResolvers.set(providerId, resolve2);
     }
   };
   const experimental_hooks = {
@@ -2981,6 +3084,9 @@ function createFakePluginHostInternal(options, sharedState) {
       pendingInteractions.delete(id);
       pending.resolve({ outcome: "cancelled", reason: "plugin-disposed" });
     }
+    for (const session of [...websocketSessions]) {
+      await session.closeForReload();
+    }
     for (const controller of serviceControllers) controller.abort();
     for (const hook of [...disposeHooks].reverse()) {
       try {
@@ -3026,6 +3132,7 @@ function createFakePluginHostInternal(options, sharedState) {
     registrations: {
       settingsDescriptors,
       httpRoutes,
+      websocketRoutes,
       get rpcMethods() {
         return [...rpcHandlers.keys()];
       },
@@ -3060,6 +3167,8 @@ function createFakePluginHostInternal(options, sharedState) {
       },
       mentionProviders,
       providerRegistrations,
+      providerEnvResolvers,
+      providerEnvHealthResolvers,
       aiServiceRegistrations
     },
     get pendingInteractions() {
@@ -3077,6 +3186,43 @@ function createFakePluginHostInternal(options, sharedState) {
         await handler({ hostId });
       }
     },
+    async resolveProviderEnv(providerId, context) {
+      assertLive();
+      const resolve2 = providerEnvResolvers.get(providerId);
+      if (resolve2 === void 0) return [];
+      try {
+        return validatePluginProviderEnvEntries(await resolve2(context));
+      } catch (error) {
+        emitLog(
+          "warn",
+          `provider environment contribution failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return [];
+      }
+    },
+    async resolveProviderEnvHealth(providerId, context) {
+      assertLive();
+      if (!providerEnvResolvers.has(providerId)) return null;
+      const resolve2 = providerEnvHealthResolvers.get(providerId);
+      if (resolve2 === void 0) return null;
+      try {
+        const value = await resolve2(context);
+        if (value === null) return null;
+        if (value.label.trim().length === 0) {
+          throw new Error("label must not be empty");
+        }
+        if (value.statusMessage.trim().length === 0) {
+          throw new Error("statusMessage must not be empty");
+        }
+        return value;
+      } catch (error) {
+        emitLog(
+          "warn",
+          `provider environment health contribution failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return null;
+      }
+    },
     async experimental_emitHostSignal(hostId, signal, payload) {
       assertLive();
       if (hostId.trim().length === 0) {
@@ -3204,6 +3350,127 @@ function createFakePluginHostInternal(options, sharedState) {
       });
       return app.request(path, { ...init, method: normalizedMethod });
     },
+    async experimental_openWebSocket(path, init) {
+      assertLive();
+      const url = new URL(path, "http://plugin.test");
+      const route = websocketRoutes.find(
+        (candidate) => candidate.path === url.pathname
+      );
+      if (!route) {
+        throw new Error(
+          `no websocket route ${url.pathname} is registered \u2014 registered: ${websocketRoutes.map((candidate) => candidate.path).join(", ") || "(none)"}`
+        );
+      }
+      const request = new Request(url, { ...init, method: "GET" });
+      let handlers;
+      try {
+        handlers = route.handler({
+          request,
+          url,
+          headers: request.headers
+        });
+        if (typeof handlers !== "object" || handlers === null || Array.isArray(handlers)) {
+          throw new Error("websocket route handler must return an object");
+        }
+        for (const name of [
+          "onOpen",
+          "onMessage",
+          "onClose",
+          "onError"
+        ]) {
+          const callback = handlers[name];
+          if (callback !== void 0 && typeof callback !== "function") {
+            throw new Error(
+              `websocket route handler ${name} must be a function`
+            );
+          }
+        }
+      } catch (error) {
+        emitLog(
+          "warn",
+          `websocket ${route.path} connect failed: ${errorMessage(error)}`
+        );
+        throw error;
+      }
+      const sent = [];
+      const closeCalls = [];
+      let readyState = 0;
+      let closeNotified = false;
+      let eventQueue = Promise.resolve();
+      const invoke = async (event, run) => {
+        eventQueue = eventQueue.then(async () => {
+          try {
+            await run();
+          } catch (error) {
+            emitLog(
+              "warn",
+              `websocket ${route.path} ${event} failed: ${errorMessage(error)}`
+            );
+          }
+        });
+        await eventQueue;
+      };
+      const socket = {
+        send(data) {
+          sent.push(typeof data === "string" ? data : new Uint8Array(data));
+        },
+        close(code, reason) {
+          closeCalls.push({ code: code ?? null, reason: reason ?? null });
+          if (readyState < 2) readyState = 2;
+        },
+        get readyState() {
+          return readyState;
+        }
+      };
+      const notifyClose = async (code, reason) => {
+        if (closeNotified) return;
+        closeNotified = true;
+        readyState = 3;
+        websocketSessions.delete(session);
+        if (handlers.onClose !== void 0) {
+          await invoke(
+            "close",
+            () => handlers.onClose?.(socket, { code, reason })
+          );
+        }
+      };
+      const session = {
+        sent,
+        closeCalls,
+        get readyState() {
+          return readyState;
+        },
+        async receive(data) {
+          if (readyState !== 1) {
+            throw new Error(
+              "cannot receive a websocket message while not open"
+            );
+          }
+          if (handlers.onMessage !== void 0) {
+            await invoke("message", () => handlers.onMessage?.(socket, data));
+          }
+        },
+        async close(code = 1e3, reason = "") {
+          if (readyState < 2) socket.close(code, reason);
+          await notifyClose(code, reason);
+        },
+        async error(error) {
+          if (handlers.onError !== void 0) {
+            await invoke("error", () => handlers.onError?.(socket, error));
+          }
+        },
+        async closeForReload() {
+          socket.close(1012, "Plugin reloaded or disabled");
+          await notifyClose(1012, "Plugin reloaded or disabled");
+        }
+      };
+      websocketSessions.add(session);
+      readyState = 1;
+      if (handlers.onOpen !== void 0) {
+        await invoke("open", () => handlers.onOpen?.(socket));
+      }
+      return session;
+    },
     runService(name) {
       const service = services.find((record) => record.name === name);
       if (!service) {
@@ -3348,6 +3615,151 @@ function makeThreadResponse(overrides = {}) {
     ...overrides
   };
 }
+function makePluginAgentConfigurationContext(overrides = {}) {
+  const context = {
+    thread: {
+      id: "thread-test",
+      title: null,
+      parentThreadId: null,
+      sourceThreadId: null
+    },
+    project: {
+      id: "project-test",
+      kind: "standard",
+      name: "Test project",
+      gitRemoteUrl: null
+    },
+    environment: {
+      id: "environment-test",
+      name: null,
+      path: "/tmp/test",
+      workspaceProvisionType: "unmanaged",
+      branchName: null
+    },
+    host: { id: "host-test", name: "Test host" },
+    provider: {
+      id: "test-provider",
+      model: "test-model",
+      capabilities: { supportsNativeUserQuestion: false }
+    },
+    origin: { kind: null, pluginId: null }
+  };
+  return {
+    thread: { ...context.thread, ...overrides.thread },
+    project: { ...context.project, ...overrides.project },
+    environment: { ...context.environment, ...overrides.environment },
+    host: { ...context.host, ...overrides.host },
+    provider: {
+      ...context.provider,
+      ...overrides.provider,
+      capabilities: {
+        ...context.provider.capabilities,
+        ...overrides.provider?.capabilities
+      }
+    },
+    origin: { ...context.origin, ...overrides.origin }
+  };
+}
+function makeMessageDispatchHookContext(overrides = {}) {
+  const context = {
+    thread: makeThreadResponse({ status: "pending" }),
+    project: {
+      id: "project-1",
+      kind: "standard",
+      name: "Test project",
+      gitRemoteUrl: null,
+      createdAt: 0,
+      updatedAt: 0
+    },
+    environment: null,
+    host: null,
+    input: { blocks: [], text: "Test message" },
+    requestedExecution: {
+      providerId: "test-provider",
+      model: null,
+      reasoningLevel: null,
+      serviceTier: null,
+      permissionMode: null
+    },
+    executionSources: {
+      providerId: null,
+      model: null,
+      reasoningLevel: null,
+      serviceTier: null,
+      permissionMode: null
+    },
+    attempt: "start-turn",
+    queuedMessage: null,
+    origin: null,
+    originPluginId: null,
+    startedOnBehalfOf: null,
+    parentThreadId: null
+  };
+  const environmentDefaults = {
+    id: "environment-1",
+    name: null,
+    projectId: "project-1",
+    hostId: "host-1",
+    path: "/tmp/test",
+    managed: true,
+    isGitRepo: true,
+    isWorktree: false,
+    workspaceProvisionType: "unmanaged",
+    branchName: "main",
+    baseBranch: null,
+    defaultBranch: "main",
+    mergeBaseBranch: null,
+    status: "ready",
+    createdAt: 0,
+    updatedAt: 0
+  };
+  const hostDefaults = {
+    id: "host-1",
+    name: "Test host",
+    type: "persistent",
+    status: "connected",
+    maxPermissionMode: "full",
+    lastSeenAt: null,
+    lastRejectedProtocolVersion: null,
+    createdAt: 0,
+    updatedAt: 0
+  };
+  const project = { ...context.project, ...overrides.project };
+  const host = overrides.host === void 0 ? context.host : overrides.host === null ? null : { ...hostDefaults, ...overrides.host };
+  const environment = overrides.environment === void 0 ? context.environment : overrides.environment === null ? null : {
+    ...environmentDefaults,
+    projectId: project.id,
+    hostId: host?.id ?? environmentDefaults.hostId,
+    ...overrides.environment
+  };
+  const thread = {
+    ...context.thread,
+    projectId: project.id,
+    environmentId: environment?.id ?? null,
+    ...overrides.thread
+  };
+  return {
+    ...context,
+    ...overrides,
+    thread,
+    project,
+    environment,
+    host,
+    input: { ...context.input, ...overrides.input },
+    requestedExecution: {
+      ...context.requestedExecution,
+      ...overrides.requestedExecution
+    },
+    executionSources: {
+      ...context.executionSources,
+      ...overrides.executionSources
+    },
+    queuedMessage: overrides.queuedMessage === void 0 ? context.queuedMessage : overrides.queuedMessage === null ? null : makeQueueEntry({
+      threadId: thread.id,
+      ...overrides.queuedMessage
+    })
+  };
+}
 function makeQueueEntry(overrides = {}) {
   return {
     id: "queued_1",
@@ -3485,6 +3897,8 @@ export {
   createFakePluginHost,
   createFakeSdk,
   scanPublicSdkOnly as experimental_scanPublicSdkOnly,
+  makeMessageDispatchHookContext,
+  makePluginAgentConfigurationContext,
   makeQueueEntry,
   makeThreadResponse,
   makeTurnFailedEvent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-bb/plugin-sdk",
-  "version": "0.4.40",
+  "version": "0.4.47",
   "homepage": "https://github.com/get-bb/bb#readme",
   "bugs": {
     "url": "https://github.com/get-bb/bb/issues"