yzcode-cli 1.0.0

package/services/mcp/channelAllowlist.ts

@@ -0,0 +1,76 @@
+/**
+ * Approved channel plugins allowlist. --channels plugin:name@marketplace
+ * entries only register if {marketplace, plugin} is on this list. server:
+ * entries always fail (schema is plugin-only). The
+ * --dangerously-load-development-channels flag bypasses for both kinds.
+ * Lives in GrowthBook so it can be updated without a release.
+ *
+ * Plugin-level granularity: if a plugin is approved, all its channel
+ * servers are. Per-server gating was overengineering — a plugin that
+ * sprouts a malicious second server is already compromised, and per-server
+ * entries would break on harmless plugin refactors.
+ *
+ * The allowlist check is a pure {marketplace, plugin} comparison against
+ * the user's typed tag. The gate's separate 'marketplace' step verifies
+ * the tag matches what's actually installed before this check runs.
+ */
+
+import { z } from 'zod/v4'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { parsePluginIdentifier } from '../../utils/plugins/pluginIdentifier.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js'
+
+export type ChannelAllowlistEntry = {
+  marketplace: string
+  plugin: string
+}
+
+const ChannelAllowlistSchema = lazySchema(() =>
+  z.array(
+    z.object({
+      marketplace: z.string(),
+      plugin: z.string(),
+    }),
+  ),
+)
+
+export function getChannelAllowlist(): ChannelAllowlistEntry[] {
+  const raw = getFeatureValue_CACHED_MAY_BE_STALE<unknown>(
+    'tengu_harbor_ledger',
+    [],
+  )
+  const parsed = ChannelAllowlistSchema().safeParse(raw)
+  return parsed.success ? parsed.data : []
+}
+
+/**
+ * Overall channels on/off. Checked before any per-server gating —
+ * when false, --channels is a no-op and no handlers register.
+ * Default false; GrowthBook 5-min refresh.
+ */
+export function isChannelsEnabled(): boolean {
+  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_harbor', false)
+}
+
+/**
+ * Pure allowlist check keyed off the connection's pluginSource — for UI
+ * pre-filtering so the IDE only shows "Enable channel?" for servers that will
+ * actually pass the gate. Not a security boundary: channel_enable still runs
+ * the full gate. Matches the allowlist comparison inside gateChannelServer()
+ * but standalone (no session/marketplace coupling — those are tautologies
+ * when the entry is derived from pluginSource).
+ *
+ * Returns false for undefined pluginSource (non-plugin server — can never
+ * match the {marketplace, plugin}-keyed ledger) and for @-less sources
+ * (builtin/inline — same reason).
+ */
+export function isChannelAllowlisted(
+  pluginSource: string | undefined,
+): boolean {
+  if (!pluginSource) return false
+  const { name, marketplace } = parsePluginIdentifier(pluginSource)
+  if (!marketplace) return false
+  return getChannelAllowlist().some(
+    e => e.plugin === name && e.marketplace === marketplace,
+  )
+}

package/services/mcp/channelNotification.ts

@@ -0,0 +1,316 @@
+/**
+ * Channel notifications — lets an MCP server push user messages into the
+ * conversation. A "channel" (Discord, Slack, SMS, etc.) is just an MCP server
+ * that:
+ *   - exposes tools for outbound messages (e.g. `send_message`) — standard MCP
+ *   - sends `notifications/claude/channel` notifications for inbound — this file
+ *
+ * The notification handler wraps the content in a <channel> tag and
+ * enqueues it. SleepTool polls hasCommandsInQueue() and wakes within 1s.
+ * The model sees where the message came from and decides which tool to reply
+ * with (the channel's MCP tool, SendUserMessage, or both).
+ *
+ * feature('KAIROS') || feature('KAIROS_CHANNELS'). Runtime gate tengu_harbor.
+ * Requires claude.ai OAuth auth — API key users are blocked until
+ * console gets a channelsEnabled admin surface. Teams/Enterprise orgs
+ * must explicitly opt in via channelsEnabled: true in managed settings.
+ */
+
+import type { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod/v4'
+import { type ChannelEntry, getAllowedChannels } from '../../bootstrap/state.js'
+import { CHANNEL_TAG } from '../../constants/xml.js'
+import {
+  getClaudeAIOAuthTokens,
+  getSubscriptionType,
+} from '../../utils/auth.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { parsePluginIdentifier } from '../../utils/plugins/pluginIdentifier.js'
+import { getSettingsForSource } from '../../utils/settings/settings.js'
+import { escapeXmlAttr } from '../../utils/xml.js'
+import {
+  type ChannelAllowlistEntry,
+  getChannelAllowlist,
+  isChannelsEnabled,
+} from './channelAllowlist.js'
+
+export const ChannelMessageNotificationSchema = lazySchema(() =>
+  z.object({
+    method: z.literal('notifications/claude/channel'),
+    params: z.object({
+      content: z.string(),
+      // Opaque passthrough — thread_id, user, whatever the channel wants the
+      // model to see. Rendered as attributes on the <channel> tag.
+      meta: z.record(z.string(), z.string()).optional(),
+    }),
+  }),
+)
+
+/**
+ * Structured permission reply from a channel server. Servers that support
+ * this declare `capabilities.experimental['claude/channel/permission']` and
+ * emit this event INSTEAD of relaying "yes tbxkq" as text via
+ * notifications/claude/channel. Explicit opt-in per server — a channel that
+ * just wants to relay text never becomes a permission surface by accident.
+ *
+ * The server parses the user's reply (spec: /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i)
+ * and emits {request_id, behavior}. CC matches request_id against its
+ * pending map. Unlike the regex-intercept approach, text in the general
+ * channel can never accidentally match — approval requires the server
+ * to deliberately emit this specific event.
+ */
+export const CHANNEL_PERMISSION_METHOD =
+  'notifications/claude/channel/permission'
+export const ChannelPermissionNotificationSchema = lazySchema(() =>
+  z.object({
+    method: z.literal(CHANNEL_PERMISSION_METHOD),
+    params: z.object({
+      request_id: z.string(),
+      behavior: z.enum(['allow', 'deny']),
+    }),
+  }),
+)
+
+/**
+ * Outbound: CC → server. Fired from interactiveHandler.ts when a
+ * permission dialog opens and the server has declared the permission
+ * capability. Server formats the message for its platform (Telegram
+ * markdown, iMessage rich text, Discord embed) and sends it to the
+ * human. When the human replies "yes tbxkq", the server parses that
+ * against PERMISSION_REPLY_RE and emits the inbound schema above.
+ *
+ * Not a zod schema — CC SENDS this, doesn't validate it. A type here
+ * keeps both halves of the protocol documented side by side.
+ */
+export const CHANNEL_PERMISSION_REQUEST_METHOD =
+  'notifications/claude/channel/permission_request'
+export type ChannelPermissionRequestParams = {
+  request_id: string
+  tool_name: string
+  description: string
+  /** JSON-stringified tool input, truncated to 200 chars with …. Full
+   *  input is in the local terminal dialog; this is a phone-sized
+   *  preview. Server decides whether/how to show it. */
+  input_preview: string
+}
+
+/**
+ * Meta keys become XML attribute NAMES — a crafted key like
+ * `x="" injected="y` would break out of the attribute structure. Only
+ * accept keys that look like plain identifiers. This is stricter than
+ * the XML spec (which allows `:`, `.`, `-`) but channel servers only
+ * send `chat_id`, `user`, `thread_ts`, `message_id` in practice.
+ */
+const SAFE_META_KEY = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+export function wrapChannelMessage(
+  serverName: string,
+  content: string,
+  meta?: Record<string, string>,
+): string {
+  const attrs = Object.entries(meta ?? {})
+    .filter(([k]) => SAFE_META_KEY.test(k))
+    .map(([k, v]) => ` ${k}="${escapeXmlAttr(v)}"`)
+    .join('')
+  return `<${CHANNEL_TAG} source="${escapeXmlAttr(serverName)}"${attrs}>\n${content}\n</${CHANNEL_TAG}>`
+}
+
+/**
+ * Effective allowlist for the current session. Team/enterprise orgs can set
+ * allowedChannelPlugins in managed settings — when set, it REPLACES the
+ * GrowthBook ledger (admin owns the trust decision). Undefined falls back
+ * to the ledger. Unmanaged users always get the ledger.
+ *
+ * Callers already read sub/policy for the policy gate — pass them in to
+ * avoid double-reading getSettingsForSource (uncached).
+ */
+export function getEffectiveChannelAllowlist(
+  sub: ReturnType<typeof getSubscriptionType>,
+  orgList: ChannelAllowlistEntry[] | undefined,
+): {
+  entries: ChannelAllowlistEntry[]
+  source: 'org' | 'ledger'
+} {
+  if ((sub === 'team' || sub === 'enterprise') && orgList) {
+    return { entries: orgList, source: 'org' }
+  }
+  return { entries: getChannelAllowlist(), source: 'ledger' }
+}
+
+export type ChannelGateResult =
+  | { action: 'register' }
+  | {
+      action: 'skip'
+      kind:
+        | 'capability'
+        | 'disabled'
+        | 'auth'
+        | 'policy'
+        | 'session'
+        | 'marketplace'
+        | 'allowlist'
+      reason: string
+    }
+
+/**
+ * Match a connected MCP server against the user's parsed --channels entries.
+ * server-kind is exact match on bare name; plugin-kind matches on the second
+ * segment of plugin:X:Y. Returns the matching entry so callers can read its
+ * kind — that's the user's trust declaration, not inferred from runtime shape.
+ */
+export function findChannelEntry(
+  serverName: string,
+  channels: readonly ChannelEntry[],
+): ChannelEntry | undefined {
+  // split unconditionally — for a bare name like 'slack', parts is ['slack']
+  // and the plugin-kind branch correctly never matches (parts[0] !== 'plugin').
+  const parts = serverName.split(':')
+  return channels.find(c =>
+    c.kind === 'server'
+      ? serverName === c.name
+      : parts[0] === 'plugin' && parts[1] === c.name,
+  )
+}
+
+/**
+ * Gate an MCP server's channel-notification path. Caller checks
+ * feature('KAIROS') || feature('KAIROS_CHANNELS') first (build-time
+ * elimination). Gate order: capability → runtime gate (tengu_harbor) →
+ * auth (OAuth only) → org policy → session --channels → allowlist.
+ * API key users are blocked at the auth layer — channels requires
+ * claude.ai auth; console orgs have no admin opt-in surface yet.
+ *
+ *   skip      Not a channel server, or managed org hasn't opted in, or
+ *             not in session --channels. Connection stays up; handler
+ *             not registered.
+ *   register  Subscribe to notifications/claude/channel.
+ *
+ * Which servers can connect at all is governed by allowedMcpServers —
+ * this gate only decides whether the notification handler registers.
+ */
+export function gateChannelServer(
+  serverName: string,
+  capabilities: ServerCapabilities | undefined,
+  pluginSource: string | undefined,
+): ChannelGateResult {
+  // Channel servers declare `experimental['claude/channel']: {}` (MCP's
+  // presence-signal idiom — same as `tools: {}`). Truthy covers `{}` and
+  // `true`; absent/undefined/explicit-`false` all fail. Key matches the
+  // notification method namespace (notifications/claude/channel).
+  if (!capabilities?.experimental?.['claude/channel']) {
+    return {
+      action: 'skip',
+      kind: 'capability',
+      reason: 'server did not declare claude/channel capability',
+    }
+  }
+
+  // Overall runtime gate. After capability so normal MCP servers never hit
+  // this path. Before auth/policy so the killswitch works regardless of
+  // session state.
+  if (!isChannelsEnabled()) {
+    return {
+      action: 'skip',
+      kind: 'disabled',
+      reason: 'channels feature is not currently available',
+    }
+  }
+
+  // OAuth-only. API key users (console) are blocked — there's no
+  // channelsEnabled admin surface in console yet, so the policy opt-in
+  // flow doesn't exist for them. Drop this when console parity lands.
+  if (!getClaudeAIOAuthTokens()?.accessToken) {
+    return {
+      action: 'skip',
+      kind: 'auth',
+      reason: 'channels requires claude.ai authentication (run /login)',
+    }
+  }
+
+  // Teams/Enterprise opt-in. Managed orgs must explicitly enable channels.
+  // Default OFF — absent or false blocks. Keyed off subscription tier, not
+  // "policy settings exist" — a team org with zero configured policy keys
+  // (remote endpoint returns 404) is still a managed org and must not fall
+  // through to the unmanaged path.
+  const sub = getSubscriptionType()
+  const managed = sub === 'team' || sub === 'enterprise'
+  const policy = managed ? getSettingsForSource('policySettings') : undefined
+  if (managed && policy?.channelsEnabled !== true) {
+    return {
+      action: 'skip',
+      kind: 'policy',
+      reason:
+        'channels not enabled by org policy (set channelsEnabled: true in managed settings)',
+    }
+  }
+
+  // User-level session opt-in. A server must be explicitly listed in
+  // --channels to push inbound this session — protects against a trusted
+  // server surprise-adding the capability.
+  const entry = findChannelEntry(serverName, getAllowedChannels())
+  if (!entry) {
+    return {
+      action: 'skip',
+      kind: 'session',
+      reason: `server ${serverName} not in --channels list for this session`,
+    }
+  }
+
+  if (entry.kind === 'plugin') {
+    // Marketplace verification: the tag is intent (plugin:slack@anthropic),
+    // the runtime name is just plugin:slack:X — could be slack@anthropic or
+    // slack@evil depending on what's installed. Verify they match before
+    // trusting the tag for the allowlist check below. Source is stashed on
+    // the config at addPluginScopeToServers — undefined (non-plugin server,
+    // shouldn't happen for plugin-kind entry) or @-less (builtin/inline)
+    // both fail the comparison.
+    const actual = pluginSource
+      ? parsePluginIdentifier(pluginSource).marketplace
+      : undefined
+    if (actual !== entry.marketplace) {
+      return {
+        action: 'skip',
+        kind: 'marketplace',
+        reason: `you asked for plugin:${entry.name}@${entry.marketplace} but the installed ${entry.name} plugin is from ${actual ?? 'an unknown source'}`,
+      }
+    }
+
+    // Approved-plugin allowlist. Marketplace gate already verified
+    // tag == reality, so this is a pure entry check. entry.dev (per-entry,
+    // not the session-wide bit) bypasses — so accepting the dev dialog for
+    // one entry doesn't leak allowlist-bypass to --channels entries.
+    if (!entry.dev) {
+      const { entries, source } = getEffectiveChannelAllowlist(
+        sub,
+        policy?.allowedChannelPlugins,
+      )
+      if (
+        !entries.some(
+          e => e.plugin === entry.name && e.marketplace === entry.marketplace,
+        )
+      ) {
+        return {
+          action: 'skip',
+          kind: 'allowlist',
+          reason:
+            source === 'org'
+              ? `plugin ${entry.name}@${entry.marketplace} is not on your org's approved channels list (set allowedChannelPlugins in managed settings)`
+              : `plugin ${entry.name}@${entry.marketplace} is not on the approved channels allowlist (use --dangerously-load-development-channels for local dev)`,
+        }
+      }
+    }
+  } else {
+    // server-kind: allowlist schema is {marketplace, plugin} — a server entry
+    // can never match. Without this, --channels server:plugin:foo:bar would
+    // match a plugin's runtime name and register with no allowlist check.
+    if (!entry.dev) {
+      return {
+        action: 'skip',
+        kind: 'allowlist',
+        reason: `server ${entry.name} is not on the approved channels allowlist (use --dangerously-load-development-channels for local dev)`,
+      }
+    }
+  }
+
+  return { action: 'register' }
+}

package/services/mcp/channelPermissions.ts

@@ -0,0 +1,240 @@
+/**
+ * Permission prompts over channels (Telegram, iMessage, Discord).
+ *
+ * Mirrors `BridgePermissionCallbacks` — when CC hits a permission dialog,
+ * it ALSO sends the prompt via active channels and races the reply against
+ * local UI / bridge / hooks / classifier. First resolver wins via claim().
+ *
+ * Inbound is a structured event: the server parses the user's "yes tbxkq"
+ * reply and emits notifications/claude/channel/permission with
+ * {request_id, behavior}. CC never sees the reply as text — approval
+ * requires the server to deliberately emit that specific event, not just
+ * relay content. Servers opt in by declaring
+ * capabilities.experimental['claude/channel/permission'].
+ *
+ * Kenneth's "would this let Claude self-approve?": the approving party is
+ * the human via the channel, not Claude. But the trust boundary isn't the
+ * terminal — it's the allowlist (tengu_harbor_ledger). A compromised
+ * channel server CAN fabricate "yes <id>" without the human seeing the
+ * prompt. Accepted risk: a compromised channel already has unlimited
+ * conversation-injection turns (social-engineer over time, wait for
+ * acceptEdits, etc.); inject-then-self-approve is faster, not more
+ * capable. The dialog slows a compromised channel; it doesn't stop one.
+ * See PR discussion 2956440848.
+ */
+
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js'
+
+/**
+ * GrowthBook runtime gate — separate from the channels gate (tengu_harbor)
+ * so channels can ship without permission-relay riding along (Kenneth: "no
+ * bake time if it goes out tomorrow"). Default false; flip without a release.
+ * Checked once at useManageMCPConnections mount — mid-session flag changes
+ * don't apply until restart.
+ */
+export function isChannelPermissionRelayEnabled(): boolean {
+  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_harbor_permissions', false)
+}
+
+export type ChannelPermissionResponse = {
+  behavior: 'allow' | 'deny'
+  /** Which channel server the reply came from (e.g., "plugin:telegram:tg"). */
+  fromServer: string
+}
+
+export type ChannelPermissionCallbacks = {
+  /** Register a resolver for a request ID. Returns unsubscribe. */
+  onResponse(
+    requestId: string,
+    handler: (response: ChannelPermissionResponse) => void,
+  ): () => void
+  /** Resolve a pending request from a structured channel event
+   *  (notifications/claude/channel/permission). Returns true if the ID
+   *  was pending — the server parsed the user's reply and emitted
+   *  {request_id, behavior}; we just match against the map. */
+  resolve(
+    requestId: string,
+    behavior: 'allow' | 'deny',
+    fromServer: string,
+  ): boolean
+}
+
+/**
+ * Reply format spec for channel servers to implement:
+ *   /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i
+ *
+ * 5 lowercase letters, no 'l' (looks like 1/I). Case-insensitive (phone
+ * autocorrect). No bare yes/no (conversational). No prefix/suffix chatter.
+ *
+ * CC generates the ID and sends the prompt. The SERVER parses the user's
+ * reply and emits notifications/claude/channel/permission with {request_id,
+ * behavior} — CC doesn't regex-match text anymore. Exported so plugins can
+ * import the exact regex rather than hand-copying it.
+ */
+export const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i
+
+// 25-letter alphabet: a-z minus 'l' (looks like 1/I). 25^5 ≈ 9.8M space.
+const ID_ALPHABET = 'abcdefghijkmnopqrstuvwxyz'
+
+// Substring blocklist — 5 random letters can spell things (Kenneth, in the
+// launch thread: "this is why i bias to numbers, hard to have anything worse
+// than 80085"). Non-exhaustive, covers the send-to-your-boss-by-accident
+// tier. If a generated ID contains any of these, re-hash with a salt.
+// prettier-ignore
+const ID_AVOID_SUBSTRINGS = [
+  'fuck',
+  'shit',
+  'cunt',
+  'cock',
+  'dick',
+  'twat',
+  'piss',
+  'crap',
+  'bitch',
+  'whore',
+  'ass',
+  'tit',
+  'cum',
+  'fag',
+  'dyke',
+  'nig',
+  'kike',
+  'rape',
+  'nazi',
+  'damn',
+  'poo',
+  'pee',
+  'wank',
+  'anus',
+]
+
+function hashToId(input: string): string {
+  // FNV-1a → uint32, then base-25 encode. Not crypto, just a stable
+  // short letters-only ID. 32 bits / log2(25) ≈ 6.9 letters of entropy;
+  // taking 5 wastes a little, plenty for this.
+  let h = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  h = h >>> 0
+  let s = ''
+  for (let i = 0; i < 5; i++) {
+    s += ID_ALPHABET[h % 25]
+    h = Math.floor(h / 25)
+  }
+  return s
+}
+
+/**
+ * Short ID from a toolUseID. 5 letters from a 25-char alphabet (a-z minus
+ * 'l' — looks like 1/I in many fonts). 25^5 ≈ 9.8M space, birthday
+ * collision at 50% needs ~3K simultaneous pending prompts, absurd for a
+ * single interactive session. Letters-only so phone users don't switch
+ * keyboard modes (hex alternates a-f/0-9 → mode toggles). Re-hashes with
+ * a salt suffix if the result contains a blocklisted substring — 5 random
+ * letters can spell things you don't want in a text message to your phone.
+ * toolUseIDs are `toolu_` + base64-ish; we hash rather than slice.
+ */
+export function shortRequestId(toolUseID: string): string {
+  // 7 length-3 × 3 positions × 25² + 15 length-4 × 2 × 25 + 2 length-5
+  // ≈ 13,877 blocked IDs out of 9.8M — roughly 1 in 700 hits the blocklist.
+  // Cap at 10 retries; (1/700)^10 is negligible.
+  let candidate = hashToId(toolUseID)
+  for (let salt = 0; salt < 10; salt++) {
+    if (!ID_AVOID_SUBSTRINGS.some(bad => candidate.includes(bad))) {
+      return candidate
+    }
+    candidate = hashToId(`${toolUseID}:${salt}`)
+  }
+  return candidate
+}
+
+/**
+ * Truncate tool input to a phone-sized JSON preview. 200 chars is
+ * roughly 3 lines on a narrow phone screen. Full input is in the local
+ * terminal dialog; the channel gets a summary so Write(5KB-file) doesn't
+ * flood your texts. Server decides whether/how to show it.
+ */
+export function truncateForPreview(input: unknown): string {
+  try {
+    const s = jsonStringify(input)
+    return s.length > 200 ? s.slice(0, 200) + '…' : s
+  } catch {
+    return '(unserializable)'
+  }
+}
+
+/**
+ * Filter MCP clients down to those that can relay permission prompts.
+ * Three conditions, ALL required: connected + in the session's --channels
+ * allowlist + declares BOTH capabilities. The second capability is the
+ * server's explicit opt-in — a relay-only channel never becomes a
+ * permission surface by accident (Kenneth's "users may be unpleasantly
+ * surprised"). Centralized here so a future fourth condition lands once.
+ */
+export function filterPermissionRelayClients<
+  T extends {
+    type: string
+    name: string
+    capabilities?: { experimental?: Record<string, unknown> }
+  },
+>(
+  clients: readonly T[],
+  isInAllowlist: (name: string) => boolean,
+): (T & { type: 'connected' })[] {
+  return clients.filter(
+    (c): c is T & { type: 'connected' } =>
+      c.type === 'connected' &&
+      isInAllowlist(c.name) &&
+      c.capabilities?.experimental?.['claude/channel'] !== undefined &&
+      c.capabilities?.experimental?.['claude/channel/permission'] !== undefined,
+  )
+}
+
+/**
+ * Factory for the callbacks object. The pending Map is closed over — NOT
+ * module-level (per src/CLAUDE.md), NOT in AppState (functions-in-state
+ * causes issues with equality/serialization). Same lifetime pattern as
+ * `replBridgePermissionCallbacks`: constructed once per session inside
+ * a React hook, stable reference stored in AppState.
+ *
+ * resolve() is called from the dedicated notification handler
+ * (notifications/claude/channel/permission) with the structured payload.
+ * The server already parsed "yes tbxkq" → {request_id, behavior}; we just
+ * match against the pending map. No regex on CC's side — text in the
+ * general channel can't accidentally approve anything.
+ */
+export function createChannelPermissionCallbacks(): ChannelPermissionCallbacks {
+  const pending = new Map<
+    string,
+    (response: ChannelPermissionResponse) => void
+  >()
+
+  return {
+    onResponse(requestId, handler) {
+      // Lowercase here too — resolve() already does; asymmetry means a
+      // future caller passing a mixed-case ID would silently never match.
+      // shortRequestId always emits lowercase so this is a noop today,
+      // but the symmetry makes the contract explicit.
+      const key = requestId.toLowerCase()
+      pending.set(key, handler)
+      return () => {
+        pending.delete(key)
+      }
+    },
+
+    resolve(requestId, behavior, fromServer) {
+      const key = requestId.toLowerCase()
+      const resolver = pending.get(key)
+      if (!resolver) return false
+      // Delete BEFORE calling — if resolver throws or re-enters, the
+      // entry is already gone. Also handles duplicate events (second
+      // emission falls through — server bug or network dup, ignore).
+      pending.delete(key)
+      resolver({ behavior, fromServer })
+      return true
+    },
+  }
+}