@get-bb/plugin-sdk 0.4.3

package/dist/app.js

@@ -0,0 +1,36 @@
+// src/app.ts
+var runtime = globalThis.__bbPluginRuntime?.pluginSdkApp ?? {};
+var definePluginApp = runtime.definePluginApp;
+var ThreadChat = runtime.ThreadChat;
+var Markdown = runtime.Markdown;
+var experimental_NewThreadComposer = runtime.experimental_NewThreadComposer;
+var useRpc = runtime.useRpc;
+var useRealtime = runtime.useRealtime;
+var useRealtimeConnectionState = runtime.useRealtimeConnectionState;
+var useSettings = runtime.useSettings;
+var useBbContext = runtime.useBbContext;
+var useBbNavigate = runtime.useBbNavigate;
+var useComposer = runtime.useComposer;
+var useComposerView = runtime.useComposerView;
+var experimental_useSidebarThreads = runtime.experimental_useSidebarThreads;
+var experimental_useSidebarThreadActions = runtime.experimental_useSidebarThreadActions;
+var experimental_useSidebarThreadPullRequest = runtime.experimental_useSidebarThreadPullRequest;
+var experimental_useSidebarThreadSplit = runtime.experimental_useSidebarThreadSplit;
+export {
+  Markdown,
+  ThreadChat,
+  definePluginApp,
+  experimental_NewThreadComposer,
+  experimental_useSidebarThreadActions,
+  experimental_useSidebarThreadPullRequest,
+  experimental_useSidebarThreadSplit,
+  experimental_useSidebarThreads,
+  useBbContext,
+  useBbNavigate,
+  useComposer,
+  useComposerView,
+  useRealtime,
+  useRealtimeConnectionState,
+  useRpc,
+  useSettings
+};

package/dist/index.js

@@ -0,0 +1,11 @@
+// src/backend-contract.ts
+var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
+
+// src/rpc-contract.ts
+function defineRpcContract(contract) {
+  return contract;
+}
+export {
+  PLUGIN_CLI_OUTPUT_MAX_BYTES,
+  defineRpcContract
+};

package/dist/internal/composer-customization-validation.js

@@ -0,0 +1,238 @@
+// src/internal/composer-customization-validation.ts
+var PLUGIN_SLOT_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var PLUGIN_MESSAGE_DIRECTIVE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function normalizePluginThreadRowStatus(value, onRejected) {
+  const kind = "contentScript.experimental_setThreadRowStatus";
+  if (value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    onRejected(`${kind}: status must be null or a non-array object`);
+    return void 0;
+  }
+  const status = value;
+  const icon = status.icon;
+  if (typeof icon !== "string" || icon.trim() === "") {
+    onRejected(`${kind}: "icon" must be a non-blank string`);
+    return void 0;
+  }
+  const label = status.label;
+  if (typeof label !== "string" || label.trim() === "") {
+    onRejected(`${kind}: "label" must be a non-blank string`);
+    return void 0;
+  }
+  const tone = status.tone;
+  if (tone !== void 0 && tone !== "default" && tone !== "running" && tone !== "success" && tone !== "error") {
+    onRejected(
+      `${kind}: "tone" must be "default", "running", "success", or "error" when set`
+    );
+    return void 0;
+  }
+  return {
+    icon: icon.trim(),
+    label: label.trim(),
+    ...tone !== void 0 ? { tone } : {}
+  };
+}
+function requireSlotId(kind, value) {
+  if (typeof value !== "string" || !PLUGIN_SLOT_ID_PATTERN.test(value)) {
+    throw new Error(
+      `${kind}: "id" must match ${String(PLUGIN_SLOT_ID_PATTERN)}, got ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
+function requireMessageDirectiveId(kind, value) {
+  if (typeof value !== "string" || !PLUGIN_MESSAGE_DIRECTIVE_ID_PATTERN.test(value)) {
+    throw new Error(
+      `${kind}: "id" must match ${String(PLUGIN_MESSAGE_DIRECTIVE_ID_PATTERN)}, got ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
+function requireNonEmptyString(kind, field, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${kind}: "${field}" must be a non-empty string`);
+  }
+  return value;
+}
+function requireOptionalString(kind, field, value) {
+  if (value !== void 0 && typeof value !== "string") {
+    throw new Error(`${kind}: "${field}" must be a string when set`);
+  }
+  return value;
+}
+function requireComponent(kind, value) {
+  if (typeof value !== "function") {
+    throw new Error(`${kind}: "component" must be a React component function`);
+  }
+  return value;
+}
+function requireFunction(kind, field, value) {
+  if (typeof value !== "function") {
+    throw new Error(`${kind}: "${field}" must be a function`);
+  }
+  return value;
+}
+function requireUniqueId(kind, seen, id) {
+  if (seen.has(id)) {
+    throw new Error(`${kind}: duplicate id "${id}"`);
+  }
+  seen.add(id);
+}
+function parseContributionArray(kind, value, onRejected, parse) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) {
+    onRejected(`${kind}: must be an array when set`);
+    return void 0;
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  const parsed = [];
+  for (const [index, entry] of value.entries()) {
+    const entryKind = `${kind}[${index}]`;
+    try {
+      const parsedEntry = parse(entryKind, entry);
+      requireUniqueId(entryKind, seenIds, parsedEntry.id);
+      parsed.push(parsedEntry);
+    } catch (error) {
+      onRejected(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return parsed;
+}
+function parseRegions(kind, registration, onRejected) {
+  const actions = parseContributionArray(`${kind}.actions`, registration.actions, onRejected, (entryKind, value) => {
+    const entry = value;
+    return {
+      id: requireSlotId(entryKind, entry?.id),
+      component: requireComponent(entryKind, entry?.component)
+    };
+  });
+  const banners = parseContributionArray(`${kind}.banners`, registration.banners, onRejected, (entryKind, value) => {
+    const entry = value;
+    const id = requireSlotId(entryKind, entry?.id);
+    const chrome = entry?.chrome;
+    if (chrome !== void 0 && chrome !== "card" && chrome !== "bare") {
+      throw new Error(
+        `${entryKind}: "chrome" must be "card" or "bare" when set`
+      );
+    }
+    return {
+      id,
+      ...chrome !== void 0 ? { chrome } : {},
+      component: requireComponent(entryKind, entry?.component)
+    };
+  });
+  const plusMenu = parseContributionArray(
+    `${kind}.plusMenu`,
+    registration.plusMenu,
+    onRejected,
+    (entryKind, value) => {
+      const entry = value;
+      const id = requireSlotId(entryKind, entry?.id);
+      const icon = requireOptionalString(entryKind, "icon", entry?.icon);
+      const description = requireOptionalString(
+        entryKind,
+        "description",
+        entry?.description
+      );
+      const disabled = entry?.disabled;
+      if (disabled !== void 0 && typeof disabled !== "boolean" && typeof disabled !== "function") {
+        throw new Error(
+          `${entryKind}: "disabled" must be a boolean or function when set`
+        );
+      }
+      return {
+        id,
+        label: requireNonEmptyString(entryKind, "label", entry?.label),
+        ...icon !== void 0 ? { icon } : {},
+        ...description !== void 0 ? { description } : {},
+        ...disabled !== void 0 ? {
+          disabled
+        } : {},
+        run: requireFunction(entryKind, "run", entry?.run)
+      };
+    }
+  );
+  let richText;
+  if (registration.richText !== void 0) {
+    const raw = registration.richText;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      onRejected(`${kind}.richText: must be an object when set`);
+    } else {
+      const effects = parseContributionArray(
+        `${kind}.richText.effects`,
+        raw.effects,
+        onRejected,
+        (entryKind, value) => {
+          const entry = value;
+          return {
+            id: requireSlotId(entryKind, entry?.id),
+            match: requireFunction(entryKind, "match", entry?.match),
+            className: requireNonEmptyString(
+              entryKind,
+              "className",
+              entry?.className
+            )
+          };
+        }
+      );
+      const onDraftChange = raw.onDraftChange;
+      if (onDraftChange !== void 0 && typeof onDraftChange !== "function") {
+        onRejected(
+          `${kind}.richText: "onDraftChange" must be a function when set`
+        );
+      }
+      richText = {
+        ...effects !== void 0 ? { effects } : {},
+        ...typeof onDraftChange === "function" ? {
+          onDraftChange
+        } : {}
+      };
+    }
+  }
+  return {
+    ...actions !== void 0 ? { actions } : {},
+    ...banners !== void 0 ? { banners } : {},
+    ...plusMenu !== void 0 ? { plusMenu } : {},
+    ...richText !== void 0 ? { richText } : {}
+  };
+}
+function collectComposerCustomization(registration, seenIds, onRejected) {
+  const kind = "composer.customize";
+  try {
+    const raw = registration;
+    const id = requireSlotId(kind, raw?.id);
+    const scopes = raw?.scopes;
+    if (scopes !== void 0) {
+      if (!Array.isArray(scopes)) {
+        throw new Error(`${kind}: "scopes" must be an array when set`);
+      }
+      for (const scope of scopes) {
+        if (scope !== "thread" && scope !== "queued-message" && scope !== "side-chat" && scope !== "new-thread") {
+          throw new Error(
+            `${kind}: invalid scope kind ${JSON.stringify(scope)}`
+          );
+        }
+      }
+    }
+    requireUniqueId(kind, seenIds, id);
+    return {
+      id,
+      ...scopes !== void 0 ? { scopes: [...scopes] } : {},
+      ...parseRegions(`${kind}(${id})`, raw ?? {}, onRejected)
+    };
+  } catch (error) {
+    onRejected(error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+export {
+  PLUGIN_SLOT_ID_PATTERN,
+  collectComposerCustomization,
+  normalizePluginThreadRowStatus,
+  requireComponent,
+  requireMessageDirectiveId,
+  requireNonEmptyString,
+  requireOptionalString,
+  requireSlotId,
+  requireUniqueId
+};

package/dist/internal/composer-view.js

@@ -0,0 +1,7 @@
+// src/internal/composer-view.ts
+function isComposerDraftEmpty(text, attachmentCount) {
+  return text.trim().length === 0 && attachmentCount === 0;
+}
+export {
+  isComposerDraftEmpty
+};

package/dist/internal/host-policy.js

@@ -0,0 +1,261 @@
+// src/internal/host-policy.ts
+import { z } from "zod";
+
+// ../domain/src/plugin-cli.ts
+var RESERVED_BB_CLI_COMMANDS = [
+  "environment",
+  "guide",
+  "help",
+  "manager",
+  "plugin",
+  "project",
+  "provider",
+  "skill",
+  "status",
+  "theme",
+  "thread"
+];
+
+// src/backend-contract.ts
+var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
+
+// src/internal/host-policy.ts
+var RESERVED_AGENT_TOOL_NAMES = [
+  "update_environment_directory"
+];
+var KV_VALUE_MAX_BYTES = 256 * 1024;
+var PLUGIN_HTTP_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS"
+]);
+var RPC_METHOD_PATTERN = /^[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_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS = 4096;
+var PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS = 80;
+var PLUGIN_AGENT_SELECTION_MAX_IDS = 256;
+var PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
+var PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES = 128 * 1024;
+var MENTION_PROVIDER_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var SETTING_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var settingsBaseFields = {
+  label: z.string().min(1),
+  description: z.string().min(1).optional()
+};
+var settingDescriptorSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("string"),
+    ...settingsBaseFields,
+    secret: z.literal(true).optional(),
+    default: z.string().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("boolean"),
+    ...settingsBaseFields,
+    default: z.boolean().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("select"),
+    ...settingsBaseFields,
+    options: z.array(z.string().min(1)).min(1),
+    default: z.string().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("project"),
+    ...settingsBaseFields,
+    default: z.string().optional()
+  }).strict()
+]);
+function registerSettingDescriptors(target, added) {
+  const validated = {};
+  for (const [key, raw] of Object.entries(added)) {
+    if (!SETTING_KEY_PATTERN.test(key)) {
+      throw new Error(
+        `invalid setting key "${key}" \u2014 use letters, digits, "-" and "_"`
+      );
+    }
+    if (key in target) {
+      throw new Error(`setting "${key}" is already defined`);
+    }
+    const parsed = settingDescriptorSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      const path = issue?.path.join(".") ?? "";
+      throw new Error(
+        `invalid descriptor for setting "${key}"${path ? ` (${path})` : ""}: ${issue?.message ?? "unknown error"}`
+      );
+    }
+    const descriptor = parsed.data;
+    if (descriptor.type === "select" && descriptor.default !== void 0 && !descriptor.options.includes(descriptor.default)) {
+      throw new Error(
+        `default for setting "${key}" must be one of its options`
+      );
+    }
+    validated[key] = descriptor;
+  }
+  Object.assign(target, validated);
+  return validated;
+}
+function validateSettingsUpdate(descriptors, values) {
+  const errors = [];
+  for (const [key, value] of Object.entries(values)) {
+    const descriptor = descriptors[key];
+    if (!descriptor) {
+      errors.push(`unknown setting "${key}"`);
+      continue;
+    }
+    if (value === null) continue;
+    if (descriptor.type === "boolean") {
+      if (typeof value !== "boolean") {
+        errors.push(`setting "${key}" expects a boolean`);
+      }
+      continue;
+    }
+    if (typeof value !== "string") {
+      errors.push(`setting "${key}" expects a string`);
+      continue;
+    }
+    if (descriptor.type === "select" && !descriptor.options.includes(value)) {
+      errors.push(
+        `setting "${key}" must be one of: ${descriptor.options.join(", ")}`
+      );
+    }
+  }
+  return errors;
+}
+var PLUGIN_MENTION_TRIGGER_VALUES = [
+  "@",
+  "#",
+  "$",
+  "!",
+  "~"
+];
+var DEFAULT_PLUGIN_MENTION_TRIGGERS = [
+  "@"
+];
+function isPluginMentionTrigger(value) {
+  return typeof value === "string" && PLUGIN_MENTION_TRIGGER_VALUES.includes(value);
+}
+function normalizeMentionProviderTriggers(providerId, triggers) {
+  if (triggers === void 0) {
+    return DEFAULT_PLUGIN_MENTION_TRIGGERS;
+  }
+  if (!Array.isArray(triggers)) {
+    throw new Error(
+      `mention provider "${providerId}" triggers must be an array`
+    );
+  }
+  if (triggers.length === 0) {
+    throw new Error(
+      `mention provider "${providerId}" triggers must include at least one trigger`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const trigger of triggers) {
+    if (!isPluginMentionTrigger(trigger)) {
+      throw new Error(
+        `mention provider "${providerId}" trigger ${JSON.stringify(trigger)} is invalid; use one of ${PLUGIN_MENTION_TRIGGER_VALUES.join(" ")}`
+      );
+    }
+    if (seen.has(trigger)) {
+      throw new Error(
+        `mention provider "${providerId}" trigger ${JSON.stringify(trigger)} is duplicated`
+      );
+    }
+    seen.add(trigger);
+    normalized.push(trigger);
+  }
+  return normalized;
+}
+function isStandardSchema(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const standard = Reflect.get(value, "~standard");
+  return typeof standard === "object" && standard !== null && Reflect.get(standard, "version") === 1 && typeof Reflect.get(standard, "vendor") === "string" && typeof Reflect.get(standard, "validate") === "function";
+}
+function readRpcMethodContract(method, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `rpc method "${method}" contract must provide input and output Standard Schemas`
+    );
+  }
+  const input = Reflect.get(value, "input");
+  const output = Reflect.get(value, "output");
+  if (!isStandardSchema(input)) {
+    throw new Error(
+      `rpc method "${method}" input must be a Standard Schema v1 validator`
+    );
+  }
+  if (!isStandardSchema(output)) {
+    throw new Error(
+      `rpc method "${method}" output must be a Standard Schema v1 validator`
+    );
+  }
+  return { input, output };
+}
+function isZodSchemaLike(value) {
+  return typeof value === "object" && value !== null && typeof value.safeParse === "function";
+}
+function summarizeParseIssues(error) {
+  const issues = error?.issues;
+  if (Array.isArray(issues) && issues.length > 0) {
+    return issues.map((issue) => {
+      const path = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path.join(".") : "(input)";
+      return `${path}: ${issue.message ?? "invalid"}`;
+    }).join("; ");
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function enforcePluginCliOutputLimit(result, jsonOutput) {
+  const stdoutBytes = Buffer.byteLength(result.stdout, "utf8");
+  const stderrBytes = Buffer.byteLength(result.stderr, "utf8");
+  const totalBytes = stdoutBytes + stderrBytes;
+  if (totalBytes <= PLUGIN_CLI_OUTPUT_MAX_BYTES) return result;
+  const error = {
+    code: "plugin_cli_output_too_large",
+    message: `Plugin CLI output is ${totalBytes} bytes (${stdoutBytes} stdout + ${stderrBytes} stderr), exceeding the ${PLUGIN_CLI_OUTPUT_MAX_BYTES}-byte limit. Narrow the query, request a smaller page, or use a file/streaming command.`,
+    maxBytes: PLUGIN_CLI_OUTPUT_MAX_BYTES,
+    stdoutBytes,
+    stderrBytes,
+    totalBytes
+  };
+  return jsonOutput ? {
+    exitCode: 1,
+    stdout: JSON.stringify({ error }),
+    stderr: "",
+    error
+  } : { exitCode: 1, stdout: "", stderr: error.message, error };
+}
+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
+};