@get-bb/plugin-sdk 0.4.6 → 0.4.8

package/dist/host.js

@@ -0,0 +1,13 @@
+// src/host-contract.ts
+function experimental_defineHostEntry(args) {
+  return {
+    experimental_apiVersion: 1,
+    contract: args.contract,
+    handlers: args.handlers,
+    ...args.experimental_signals === void 0 ? {} : { experimental_signals: args.experimental_signals },
+    ...args.dispose === void 0 ? {} : { dispose: args.dispose }
+  };
+}
+export {
+  experimental_defineHostEntry
+};

package/dist/index.js

@@ -1,11 +1,23 @@
 // src/backend-contract.ts
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
+// src/host-contract.ts
+function experimental_defineHostEntry(args) {
+  return {
+    experimental_apiVersion: 1,
+    contract: args.contract,
+    handlers: args.handlers,
+    ...args.experimental_signals === void 0 ? {} : { experimental_signals: args.experimental_signals },
+    ...args.dispose === void 0 ? {} : { dispose: args.dispose }
+  };
+}
+
 // src/rpc-contract.ts
 function defineRpcContract(contract) {
   return contract;
 }
 export {
   PLUGIN_CLI_OUTPUT_MAX_BYTES,
-  defineRpcContract
+  defineRpcContract,
+  experimental_defineHostEntry
 };

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

@@ -40,6 +40,14 @@ function requireSlotId(kind, value) {
   }
   return value;
 }
+function requireProviderId(kind, value) {
+  if (typeof value !== "string" || !PLUGIN_SLOT_ID_PATTERN.test(value)) {
+    throw new Error(
+      `${kind}: "providerId" 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(
@@ -233,6 +241,7 @@ export {
   requireMessageDirectiveId,
   requireNonEmptyString,
   requireOptionalString,
+  requireProviderId,
   requireSlotId,
   requireUniqueId
 };

package/dist/internal/host-policy.js

@@ -1,5 +1,10 @@
 // src/internal/host-policy.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
+
+// ../domain/src/plugin-icon.ts
+function isPluginOwnedIconPath(icon) {
+  return icon.startsWith("./");
+}
 
 // ../domain/src/plugin-cli.ts
 var RESERVED_BB_CLI_COMMANDS = [
@@ -16,6 +21,11 @@ var RESERVED_BB_CLI_COMMANDS = [
   "thread"
 ];
 
+// ../domain/src/provider-fork.ts
+import { z } from "zod";
+var PROVIDER_FORK_VALUES = ["none", "tip", "checkpoint"];
+var providerForkSchema = z.enum(PROVIDER_FORK_VALUES);
+
 // src/backend-contract.ts
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
@@ -43,33 +53,34 @@ 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 PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
 var SETTING_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var settingsBaseFields = {
-  label: z.string().min(1),
-  description: z.string().min(1).optional()
+  label: z2.string().min(1),
+  description: z2.string().min(1).optional()
 };
-var settingDescriptorSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("string"),
+var settingDescriptorSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("string"),
     ...settingsBaseFields,
-    secret: z.literal(true).optional(),
-    default: z.string().optional()
+    secret: z2.literal(true).optional(),
+    default: z2.string().optional()
   }).strict(),
-  z.object({
-    type: z.literal("boolean"),
+  z2.object({
+    type: z2.literal("boolean"),
     ...settingsBaseFields,
-    default: z.boolean().optional()
+    default: z2.boolean().optional()
   }).strict(),
-  z.object({
-    type: z.literal("select"),
+  z2.object({
+    type: z2.literal("select"),
     ...settingsBaseFields,
-    options: z.array(z.string().min(1)).min(1),
-    default: z.string().optional()
+    options: z2.array(z2.string().min(1)).min(1),
+    default: z2.string().optional()
   }).strict(),
-  z.object({
-    type: z.literal("project"),
+  z2.object({
+    type: z2.literal("project"),
     ...settingsBaseFields,
-    default: z.string().optional()
+    default: z2.string().optional()
   }).strict()
 ]);
 function registerSettingDescriptors(target, added) {
@@ -174,6 +185,171 @@ function normalizeMentionProviderTriggers(providerId, triggers) {
   }
   return normalized;
 }
+var PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+var PLUGIN_PROVIDER_PERMISSION_MODE_VALUES = [
+  "accept-edits",
+  "auto",
+  "full"
+];
+var PLUGIN_PROVIDER_REASONING_LEVEL_VALUES = [
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "ultracode",
+  "max",
+  "ultra"
+];
+var PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES = [
+  "plan",
+  "goal"
+];
+function validateProviderRelativePath(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`provider ${label} must be a non-blank relative path`);
+  }
+  if (value.includes("\\")) {
+    throw new Error(
+      `provider ${label} must use "/" separators, got ${JSON.stringify(value)}`
+    );
+  }
+  if (value.startsWith("/")) {
+    throw new Error(
+      `provider ${label} must be relative, got ${JSON.stringify(value)}`
+    );
+  }
+  if (value.split("/").some((segment) => segment === "..")) {
+    throw new Error(
+      `provider ${label} must not escape the plugin directory, got ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
+function validateProviderLiteralArray(args) {
+  const { providerId, field, value, allowed, requireNonEmpty } = args;
+  if (!Array.isArray(value)) {
+    throw new Error(`provider "${providerId}" ${field} must be an array`);
+  }
+  if (requireNonEmpty && value.length === 0) {
+    throw new Error(
+      `provider "${providerId}" ${field} must include at least one entry`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !allowed.includes(entry)) {
+      throw new Error(
+        `provider "${providerId}" ${field} entry ${JSON.stringify(entry)} is invalid; use one of ${allowed.join(", ")}`
+      );
+    }
+    const literal = entry;
+    if (seen.has(literal)) {
+      throw new Error(
+        `provider "${providerId}" ${field} entry ${JSON.stringify(entry)} is duplicated`
+      );
+    }
+    seen.add(literal);
+    normalized.push(literal);
+  }
+  return Object.freeze(normalized);
+}
+function validatePluginProviderDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new Error("provider declaration must be an object");
+  }
+  const id = declaration.id;
+  if (typeof id !== "string" || !PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `invalid provider id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, and "-", starting with a letter or digit`
+    );
+  }
+  const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
+  if (displayName.length === 0 || displayName.length > PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS) {
+    throw new Error(
+      `provider "${id}" displayName must be 1-${PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS} non-blank characters`
+    );
+  }
+  let icon;
+  if (declaration.icon !== void 0) {
+    if (typeof declaration.icon !== "string" || declaration.icon.trim() === "") {
+      throw new Error(
+        `provider "${id}" icon must be a non-blank string \u2014 a named host glyph ("Zap") or a plugin-relative path ("./icons/agent.svg")`
+      );
+    }
+    if (isPluginOwnedIconPath(declaration.icon)) {
+      icon = validateProviderRelativePath(declaration.icon, `"${id}" icon`);
+    } else if (/[/\\]/u.test(declaration.icon)) {
+      throw new Error(
+        `provider "${id}" icon looks like a path but does not start with "./" \u2014 use "./icons/agent.svg" for a plugin file, or a bare host glyph name like "Zap"`
+      );
+    } else {
+      icon = declaration.icon;
+    }
+  }
+  const capabilities = declaration.capabilities;
+  if (typeof capabilities !== "object" || capabilities === null) {
+    throw new Error(`provider "${id}" capabilities must be an object`);
+  }
+  const booleanCapabilityFields = [
+    "supportsServiceTier",
+    "supportsNativeUserQuestion",
+    "supportsManualCompaction",
+    "supportsThreadArchive",
+    "supportsThreadRename",
+    "supportsWorkflows"
+  ];
+  for (const field of booleanCapabilityFields) {
+    if (typeof capabilities[field] !== "boolean") {
+      throw new Error(
+        `provider "${id}" capabilities.${field} must be a boolean`
+      );
+    }
+  }
+  if (!PROVIDER_FORK_VALUES.includes(capabilities.fork)) {
+    throw new Error(
+      `provider "${id}" capabilities.fork must be one of ${PROVIDER_FORK_VALUES.join(", ")}`
+    );
+  }
+  const normalizedCapabilities = Object.freeze({
+    supportsServiceTier: capabilities.supportsServiceTier,
+    supportsNativeUserQuestion: capabilities.supportsNativeUserQuestion,
+    fork: capabilities.fork,
+    supportsManualCompaction: capabilities.supportsManualCompaction,
+    supportsThreadArchive: capabilities.supportsThreadArchive,
+    supportsThreadRename: capabilities.supportsThreadRename,
+    supportsWorkflows: capabilities.supportsWorkflows,
+    permissionModes: validateProviderLiteralArray({
+      providerId: id,
+      field: "capabilities.permissionModes",
+      value: capabilities.permissionModes,
+      allowed: PLUGIN_PROVIDER_PERMISSION_MODE_VALUES,
+      requireNonEmpty: true
+    }),
+    reasoningLevels: validateProviderLiteralArray({
+      providerId: id,
+      field: "capabilities.reasoningLevels",
+      value: capabilities.reasoningLevels,
+      allowed: PLUGIN_PROVIDER_REASONING_LEVEL_VALUES,
+      requireNonEmpty: true
+    })
+  });
+  const composerActions = validateProviderLiteralArray({
+    providerId: id,
+    field: "composerActions",
+    value: declaration.composerActions,
+    allowed: PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES,
+    requireNonEmpty: false
+  });
+  return Object.freeze({
+    id,
+    displayName,
+    ...icon === void 0 ? {} : { icon },
+    capabilities: normalizedCapabilities,
+    composerActions
+  });
+}
 function isStandardSchema(value) {
   if (typeof value !== "object" || value === null) return false;
   const standard = Reflect.get(value, "~standard");
@@ -202,6 +378,143 @@ function readRpcMethodContract(method, value) {
 function isZodSchemaLike(value) {
   return typeof value === "object" && value !== null && typeof value.safeParse === "function";
 }
+var SINGLE_SCHEMA_KEYWORDS = [
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties"
+];
+var SCHEMA_ARRAY_KEYWORDS = [
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "prefixItems"
+];
+var SCHEMA_MAP_KEYWORDS = [
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties"
+];
+function isJsonSchemaObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeJsonPointerToken(token) {
+  return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function resolveLocalJsonSchemaReference(document, anchors, reference) {
+  if (!reference.startsWith("#")) return void 0;
+  let pointer;
+  try {
+    pointer = decodeURIComponent(reference.slice(1));
+  } catch {
+    return void 0;
+  }
+  if (pointer.length === 0) return document;
+  if (!pointer.startsWith("/")) return anchors.get(pointer);
+  let current = document;
+  for (const encodedToken of pointer.slice(1).split("/")) {
+    const token = decodeJsonPointerToken(encodedToken);
+    if (Array.isArray(current)) {
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) return void 0;
+      current = current[Number(token)];
+      continue;
+    }
+    if (!isJsonSchemaObject(current) || !Object.hasOwn(current, token)) {
+      return void 0;
+    }
+    current = current[token];
+  }
+  return current;
+}
+function forEachJsonSchemaChild(schema, visit) {
+  for (const keyword of SINGLE_SCHEMA_KEYWORDS) {
+    const child = schema[keyword];
+    if (Array.isArray(child)) {
+      for (const entry of child) visit(entry);
+    } else {
+      visit(child);
+    }
+  }
+  for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+    const children = schema[keyword];
+    if (!Array.isArray(children)) continue;
+    for (const child of children) visit(child);
+  }
+  for (const keyword of SCHEMA_MAP_KEYWORDS) {
+    const children = schema[keyword];
+    if (!isJsonSchemaObject(children)) continue;
+    for (const child of Object.values(children)) visit(child);
+  }
+  const dependencies = schema.dependencies;
+  if (isJsonSchemaObject(dependencies)) {
+    for (const dependency of Object.values(dependencies)) {
+      if (!Array.isArray(dependency)) visit(dependency);
+    }
+  }
+}
+function assertNoRecursiveJsonSchemaReferences(schema, subject) {
+  if (!isJsonSchemaObject(schema)) return;
+  const document = schema;
+  const anchors = /* @__PURE__ */ new Map();
+  const indexed = /* @__PURE__ */ new Set();
+  function indexAnchors(candidate) {
+    if (!isJsonSchemaObject(candidate) || indexed.has(candidate)) return;
+    indexed.add(candidate);
+    for (const keyword of ["$anchor", "$dynamicAnchor"]) {
+      const anchor = candidate[keyword];
+      if (typeof anchor === "string") anchors.set(anchor, candidate);
+    }
+    for (const keyword of ["$id", "id"]) {
+      const id = candidate[keyword];
+      if (typeof id === "string" && /^#[^/]+$/.test(id)) {
+        anchors.set(id.slice(1), candidate);
+      }
+    }
+    forEachJsonSchemaChild(candidate, indexAnchors);
+  }
+  indexAnchors(document);
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  function visit(candidate, viaReference) {
+    if (typeof candidate === "boolean" || !isJsonSchemaObject(candidate)) {
+      return;
+    }
+    if (visiting.has(candidate)) {
+      throw new Error(
+        `${subject} contains recursive JSON Schema ${viaReference?.keyword ?? "$ref"} ${JSON.stringify(viaReference?.value ?? "#")}`
+      );
+    }
+    if (visited.has(candidate)) return;
+    visiting.add(candidate);
+    for (const keyword of ["$ref", "$recursiveRef", "$dynamicRef"]) {
+      const reference = candidate[keyword];
+      if (typeof reference === "string" && reference.startsWith("#")) {
+        const target = resolveLocalJsonSchemaReference(
+          document,
+          anchors,
+          reference
+        );
+        if (target !== void 0) {
+          visit(target, { keyword, value: reference });
+        }
+      }
+    }
+    forEachJsonSchemaChild(candidate, visit);
+    visiting.delete(candidate);
+    visited.add(candidate);
+  }
+  visit(schema);
+}
 function summarizeParseIssues(error) {
   const issues = error?.issues;
   if (Array.isArray(issues) && issues.length > 0) {
@@ -232,6 +545,56 @@ function enforcePluginCliOutputLimit(result, jsonOutput) {
     error
   } : { exitCode: 1, stdout: "", stderr: error.message, error };
 }
+function adoptHttpRouteResponse(value) {
+  if (value instanceof Response) return value;
+  if (!isResponseLike(value)) {
+    throw new Error("http route handler must return a Response");
+  }
+  const status = value.status;
+  const isNullBodyStatus = status === 101 || status === 204 || status === 205 || status === 304;
+  const init = {
+    status,
+    statusText: typeof value.statusText === "string" ? value.statusText : "",
+    headers: new Headers(value.headers)
+  };
+  if (isNullBodyStatus || value.body === null) {
+    return new Response(null, init);
+  }
+  return new Response(adoptBodyStream(value), init);
+}
+function adoptBodyStream(value) {
+  const source = value.body;
+  if (!isReadableStreamLike(source)) {
+    return new ReadableStream({
+      async start(controller) {
+        controller.enqueue(new Uint8Array(await value.arrayBuffer()));
+        controller.close();
+      }
+    });
+  }
+  const reader = source.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      const { done, value: chunk } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(chunk);
+    },
+    async cancel(reason) {
+      await reader.cancel(reason);
+    }
+  });
+}
+function isReadableStreamLike(value) {
+  return value !== null && typeof value === "object" && typeof value.getReader === "function";
+}
+function isResponseLike(value) {
+  if (value === null || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.status === "number" && typeof candidate.headers === "object" && candidate.headers !== null && typeof candidate.arrayBuffer === "function" && typeof candidate.clone === "function";
+}
 export {
   AGENT_TOOL_NAME_PATTERN,
   BACKGROUND_NAME_PATTERN,
@@ -245,10 +608,17 @@ export {
   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,
@@ -257,5 +627,6 @@ export {
   readRpcMethodContract,
   registerSettingDescriptors,
   summarizeParseIssues,
+  validatePluginProviderDeclaration,
   validateSettingsUpdate
 };