@get-bb/plugin-sdk 0.4.40 → 0.4.45

package/dist/internal/host-policy.js

@@ -280,6 +280,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;
@@ -1716,6 +1752,8 @@ export {
   PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES,
   PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES,
   PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS,
+  PLUGIN_PROVIDER_ENV_MAX_ENTRIES,
+  PLUGIN_PROVIDER_ENV_NAME_PATTERN,
   PLUGIN_PROVIDER_PERMISSION_MODE_VALUES,
   PLUGIN_PROVIDER_REASONING_LEVEL_VALUES,
   PROVIDER_ID_PATTERN,
@@ -1749,6 +1787,7 @@ export {
   undeclaredIconProblem,
   validatePluginAiServiceDeclaration,
   validatePluginProviderDeclaration,
+  validatePluginProviderEnvEntries,
   validateSettingsUpdate,
   zodSchemaToJsonSchema
 };

package/dist/provider-bridge-acp.js

@@ -684,13 +684,21 @@ var threadEventItemPresentationTintSchema = z6.object({
   light: z6.string().min(1),
   dark: z6.string().min(1)
 });
+var THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH = 80;
+var threadEventItemPresentationBadgeSchema = z6.object({
+  glyph: z6.string().min(1),
+  label: z6.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  hint: z6.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  tone: z6.enum(["neutral", "destructive"])
+});
 var threadEventItemPresentationSchema = z6.object({
   label: threadEventItemPresentationLabelSchema,
   icon: threadEventItemPresentationIconSchema,
   title: z6.string().optional(),
   detail: z6.string().max(THREAD_EVENT_ITEM_PRESENTATION_DETAIL_MAX_LENGTH).optional(),
   suppress: z6.boolean().optional(),
-  tint: threadEventItemPresentationTintSchema.optional()
+  tint: threadEventItemPresentationTintSchema.optional(),
+  badge: threadEventItemPresentationBadgeSchema.optional()
 });
 
 // ../domain/src/provider-extension-kind.ts
@@ -1409,6 +1417,10 @@ var threadEventScopeDefinitionByType = {
     policy: "thread",
     rationale: "Subscription usage is account-scoped state that can affect multiple turns and threads."
   },
+  "provider.env-resolved": {
+    policy: "thread",
+    rationale: "Resolved provider environment is session state and can change between turns."
+  },
   "thread/extensionState/updated": {
     policy: "thread",
     rationale: "Plugin-declared thread state is current thread metadata (like goals), not part of a specific turn transcript; latest snapshot per kind wins."
@@ -2052,6 +2064,25 @@ var unscopedProviderEventSchema = z14.discriminatedUnion("type", [
     providerThreadId: z14.string(),
     rateLimits: providerRateLimitStateSchema
   }),
+  z14.object({
+    type: z14.literal("provider.env-resolved"),
+    threadId: z14.string(),
+    providerThreadId: z14.string(),
+    entries: z14.array(
+      z14.object({
+        name: z14.string(),
+        source: z14.union([
+          z14.literal("shell"),
+          z14.object({ plugin: z14.string() }).strict()
+        ]),
+        value: z14.union([
+          z14.string(),
+          z14.object({ masked: z14.literal(true) }).strict()
+        ]),
+        reason: z14.string().optional()
+      }).strict()
+    )
+  }),
   z14.object({
     type: z14.literal("thread/extensionState/updated"),
     threadId: z14.string(),
@@ -2705,7 +2736,8 @@ var sessionReplacedNotificationSchema = z23.object({
   threadId: z23.string().min(1),
   providerThreadId: z23.string().min(1).nullable(),
   reason: z23.string().min(1),
-  contextLost: z23.boolean().default(false)
+  contextLost: z23.boolean().default(false),
+  showRuntimeNote: z23.boolean().default(false)
 }).passthrough();
 var providerRawNotificationSchema = z23.object({
   threadId: z23.string().min(1).optional(),

package/dist/provider-bridge-testing.js

@@ -322,13 +322,21 @@ var threadEventItemPresentationTintSchema = z4.object({
   light: z4.string().min(1),
   dark: z4.string().min(1)
 });
+var THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH = 80;
+var threadEventItemPresentationBadgeSchema = z4.object({
+  glyph: z4.string().min(1),
+  label: z4.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  hint: z4.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  tone: z4.enum(["neutral", "destructive"])
+});
 var threadEventItemPresentationSchema = z4.object({
   label: threadEventItemPresentationLabelSchema,
   icon: threadEventItemPresentationIconSchema,
   title: z4.string().optional(),
   detail: z4.string().max(THREAD_EVENT_ITEM_PRESENTATION_DETAIL_MAX_LENGTH).optional(),
   suppress: z4.boolean().optional(),
-  tint: threadEventItemPresentationTintSchema.optional()
+  tint: threadEventItemPresentationTintSchema.optional(),
+  badge: threadEventItemPresentationBadgeSchema.optional()
 });
 
 // ../domain/src/provider-extension-kind.ts
@@ -1041,6 +1049,10 @@ var threadEventScopeDefinitionByType = {
     policy: "thread",
     rationale: "Subscription usage is account-scoped state that can affect multiple turns and threads."
   },
+  "provider.env-resolved": {
+    policy: "thread",
+    rationale: "Resolved provider environment is session state and can change between turns."
+  },
   "thread/extensionState/updated": {
     policy: "thread",
     rationale: "Plugin-declared thread state is current thread metadata (like goals), not part of a specific turn transcript; latest snapshot per kind wins."
@@ -1693,6 +1705,25 @@ var unscopedProviderEventSchema = z12.discriminatedUnion("type", [
     providerThreadId: z12.string(),
     rateLimits: providerRateLimitStateSchema
   }),
+  z12.object({
+    type: z12.literal("provider.env-resolved"),
+    threadId: z12.string(),
+    providerThreadId: z12.string(),
+    entries: z12.array(
+      z12.object({
+        name: z12.string(),
+        source: z12.union([
+          z12.literal("shell"),
+          z12.object({ plugin: z12.string() }).strict()
+        ]),
+        value: z12.union([
+          z12.string(),
+          z12.object({ masked: z12.literal(true) }).strict()
+        ]),
+        reason: z12.string().optional()
+      }).strict()
+    )
+  }),
   z12.object({
     type: z12.literal("thread/extensionState/updated"),
     threadId: z12.string(),
@@ -4564,7 +4595,8 @@ var sessionReplacedNotificationSchema = z24.object({
   threadId: z24.string().min(1),
   providerThreadId: z24.string().min(1).nullable(),
   reason: z24.string().min(1),
-  contextLost: z24.boolean().default(false)
+  contextLost: z24.boolean().default(false),
+  showRuntimeNote: z24.boolean().default(false)
 }).passthrough();
 var providerRawNotificationSchema = z24.object({
   threadId: z24.string().min(1).optional(),

package/dist/provider-bridge.js

@@ -1980,13 +1980,21 @@ var threadEventItemPresentationTintSchema = z10.object({
   light: z10.string().min(1),
   dark: z10.string().min(1)
 });
+var THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH = 80;
+var threadEventItemPresentationBadgeSchema = z10.object({
+  glyph: z10.string().min(1),
+  label: z10.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  hint: z10.string().min(1).max(THREAD_EVENT_ITEM_PRESENTATION_BADGE_LABEL_MAX_LENGTH),
+  tone: z10.enum(["neutral", "destructive"])
+});
 var threadEventItemPresentationSchema = z10.object({
   label: threadEventItemPresentationLabelSchema,
   icon: threadEventItemPresentationIconSchema,
   title: z10.string().optional(),
   detail: z10.string().max(THREAD_EVENT_ITEM_PRESENTATION_DETAIL_MAX_LENGTH).optional(),
   suppress: z10.boolean().optional(),
-  tint: threadEventItemPresentationTintSchema.optional()
+  tint: threadEventItemPresentationTintSchema.optional(),
+  badge: threadEventItemPresentationBadgeSchema.optional()
 });
 
 // ../domain/src/provider-extension-kind.ts
@@ -2714,6 +2722,10 @@ var threadEventScopeDefinitionByType = {
     policy: "thread",
     rationale: "Subscription usage is account-scoped state that can affect multiple turns and threads."
   },
+  "provider.env-resolved": {
+    policy: "thread",
+    rationale: "Resolved provider environment is session state and can change between turns."
+  },
   "thread/extensionState/updated": {
     policy: "thread",
     rationale: "Plugin-declared thread state is current thread metadata (like goals), not part of a specific turn transcript; latest snapshot per kind wins."
@@ -3357,6 +3369,25 @@ var unscopedProviderEventSchema = z18.discriminatedUnion("type", [
     providerThreadId: z18.string(),
     rateLimits: providerRateLimitStateSchema
   }),
+  z18.object({
+    type: z18.literal("provider.env-resolved"),
+    threadId: z18.string(),
+    providerThreadId: z18.string(),
+    entries: z18.array(
+      z18.object({
+        name: z18.string(),
+        source: z18.union([
+          z18.literal("shell"),
+          z18.object({ plugin: z18.string() }).strict()
+        ]),
+        value: z18.union([
+          z18.string(),
+          z18.object({ masked: z18.literal(true) }).strict()
+        ]),
+        reason: z18.string().optional()
+      }).strict()
+    )
+  }),
   z18.object({
     type: z18.literal("thread/extensionState/updated"),
     threadId: z18.string(),
@@ -4280,7 +4311,8 @@ var sessionReplacedNotificationSchema = z29.object({
   threadId: z29.string().min(1),
   providerThreadId: z29.string().min(1).nullable(),
   reason: z29.string().min(1),
-  contextLost: z29.boolean().default(false)
+  contextLost: z29.boolean().default(false),
+  showRuntimeNote: z29.boolean().default(false)
 }).passthrough();
 var providerRawNotificationSchema = z29.object({
   threadId: z29.string().min(1).optional(),

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);
@@ -2466,6 +2504,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 +2971,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 = {
@@ -3060,6 +3138,8 @@ function createFakePluginHostInternal(options, sharedState) {
       },
       mentionProviders,
       providerRegistrations,
+      providerEnvResolvers,
+      providerEnvHealthResolvers,
       aiServiceRegistrations
     },
     get pendingInteractions() {
@@ -3077,6 +3157,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) {
@@ -3348,6 +3465,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 +3747,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.45",
   "homepage": "https://github.com/get-bb/bb#readme",
   "bugs": {
     "url": "https://github.com/get-bb/bb/issues"