typeclaw 0.1.0

package/src/channels/engagement.ts

@@ -0,0 +1,227 @@
+import type { ChannelParticipant } from '@/agent/session-origin'
+
+import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from './membership'
+import type { EngagementConfig } from './schema'
+import type { InboundMessage } from './types'
+
+export type EngagementDecision = 'engage' | 'observe'
+
+export type StickyCredit = { authorId: string; expiresAt: number }
+
+// Per-key sticky credit ledger. Each key (channel tuple) carries at most one
+// active credit per author at a time (subsequent grants overwrite expiry).
+export class StickyLedger {
+  private byKey = new Map<string, Map<string, number>>()
+
+  grant(key: string, authorId: string, expiresAt: number): void {
+    let inner = this.byKey.get(key)
+    if (!inner) {
+      inner = new Map()
+      this.byKey.set(key, inner)
+    }
+    inner.set(authorId, expiresAt)
+  }
+
+  consume(key: string, authorId: string, now: number): boolean {
+    const inner = this.byKey.get(key)
+    if (!inner) return false
+    const expiresAt = inner.get(authorId)
+    if (expiresAt === undefined) return false
+    inner.delete(authorId)
+    if (inner.size === 0) this.byKey.delete(key)
+    return expiresAt > now
+  }
+
+  has(key: string, authorId: string, now: number): boolean {
+    const expiresAt = this.byKey.get(key)?.get(authorId)
+    return expiresAt !== undefined && expiresAt > now
+  }
+
+  clear(key: string): void {
+    this.byKey.delete(key)
+  }
+}
+
+export type EngagementInput = {
+  message: InboundMessage
+  config: EngagementConfig
+  key: string
+  ledger: StickyLedger
+  now: number
+  // Router updates this cache with the current sender BEFORE calling here,
+  // so a fresh channel's first human message arrives with length 1. Peer
+  // bots DO enter the cache now (they were dropped at adapter level
+  // before), so the solo-human fallback below filters them out explicitly
+  // — otherwise a 1-human + N-bot channel would silently exit solo mode.
+  participants: readonly ChannelParticipant[]
+  membership: MembershipCount | null
+  // Names the agent answers to in plain text (no @mention syntax). Built
+  // by the router as `[basename(agentDir), ...config.alias]` and lowered
+  // once. Empty list means alias-based engagement is off — useful for
+  // tests and for agents that explicitly want strict-mention behavior.
+  // Match semantics: case-insensitive substring of inbound text. This is
+  // the operator contract documented in typeclaw-config; if a name is too
+  // generic ("bot", "ai") it WILL produce false matches and the operator
+  // owns curation.
+  selfAliases: readonly string[]
+  // True when the bot has previously sent into this exact thread (or
+  // channel — the suppressor only checks this when the message is a
+  // thread reply, but the field is general). Set by the router from
+  // `live.successfulChannelSends > 0` plus any bot-authored prefetched
+  // history in `contextBuffer`. Suppresses the `replyToOtherMessageId`
+  // gate below: once the bot is participating in a thread, subsequent
+  // replies are part of OUR conversation even when `parent_user_id` (the
+  // thread root author) is a human. Without this, a thread that started
+  // with a human @-mention drops every follow-up reply because Slack's
+  // `parent_user_id` always points at the (human) thread root, never the
+  // bot's intermediate replies — see incident in PR #58 follow-up.
+  botInThread: boolean
+}
+
+export function decideEngagement(input: EngagementInput): EngagementDecision {
+  const { message, config, key, ledger, now, participants, selfAliases, botInThread } = input
+
+  if (config.trigger.includes('dm') && message.isDm) return 'engage'
+  if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
+  if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
+
+  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
+    return 'engage'
+  }
+
+  // Plain-text name addressing: the user wrote our name (or an alias)
+  // somewhere in the message without using <@id> syntax. Engage at the
+  // same priority as an explicit mention — operators add aliases
+  // precisely because they expect the bot to respond when called by
+  // name. Suppression on `mentionsOthers` would defeat the point: the
+  // user can address two bots by name in one message ("봉봉아 펭펭아 둘
+  // 다 봐") and both should engage. Each bot only knows its own
+  // aliases, so cross-bot suppression isn't possible at this layer
+  // anyway — the router-side peer-name suppression in the solo-human
+  // fallback handles that case (follow-up).
+  if (matchesAnyAlias(message.text, selfAliases)) return 'engage'
+
+  // Solo-human fallback: the strict mention/reply/dm gate keeps the bot
+  // quiet in multi-human conversations, but in a 1-human channel that
+  // same gate makes the agent silent on messages plainly meant for it.
+  // The fallback engages on any human inbound when the channel has at
+  // most one human participant, and reverts to strict the moment a second
+  // human posts. Peer bots are tracked as participants for context but
+  // excluded from the count here, so a 1-human channel stays "solo" even
+  // when several bots also speak in it.
+  //
+  // Two suppressors override the fallback when the message is clearly
+  // addressed to someone else:
+  //   1. `mentionsOthers` — the message tags at least one other user and
+  //      none of the mentions resolve to us.
+  //   2. `replyToOtherMessageId` — the message is a reply, but the parent
+  //      was authored by someone other than us (Discord's threaded reply
+  //      arrow is the canonical case).
+  // Both are populated by the adapter classifiers; either one flips the
+  // fallback off for that single message without changing channel state.
+  // Explicit triggers (DM, mention-of-us, reply-to-us, sticky) above are
+  // unaffected — those still engage even when the message also tags a
+  // third party.
+  //
+  // PEER BOTS NEVER QUALIFY for this fallback. It is a courtesy to humans
+  // who don't want to type `@bot` in their own DM-like channel; peer bots
+  // have no such ergonomic excuse. Letting peer bots ride the fallback
+  // produced bot-to-bot conversations in 1-human-N-bot channels (observed:
+  // Winky and 돌쇠 introducing themselves to each other after a single
+  // "얘들아" from the human, then continuing to address each other for
+  // ~6 turns). The router's loop guard only trips after 5 consecutive
+  // peer engagements, which is too late to prevent the embarrassment.
+  //
+  // PHILOSOPHY (do not relitigate): peer bots remain reachable through
+  // the SAME triggers as humans (mention/reply/dm/sticky); we do NOT
+  // downgrade them to "mention-only". Bot-to-bot conversation is a
+  // legitimate first-class use case in this codebase. The fix is to
+  // close the unintended fallback, not to firewall bots behind explicit
+  // mentions. A future maintainer (human or AI) tempted to add a
+  // `peerBotTriggers: 'mention-only'` config — or any equivalent gate
+  // that demands explicit `@bot` from peer bots — should not. The user
+  // has rejected that design repeatedly. The right knob is `trigger`
+  // (which already applies symmetrically to humans and bots) plus this
+  // fallback fix.
+  if (message.mentionsOthers) return 'observe'
+  // The replyToOtherMessageId suppressor exists to keep the bot out of
+  // human-to-human side conversations in busy channels. But Slack's
+  // `parent_user_id` is the THREAD ROOT author, not the immediate parent
+  // author — so a thread the human starts by @-mentioning the bot
+  // produces `replyToOtherMessageId` on every follow-up (root author is
+  // the human, not us), which would silently drop every reply after the
+  // first. Once the bot has actually sent into this thread, subsequent
+  // replies are part of OUR conversation regardless of who started it,
+  // so the suppressor stops applying. The two-humans-in-a-thread case
+  // PR #58 fixed is preserved because the bot never sent into that
+  // thread in the first place.
+  if (message.replyToOtherMessageId !== null && !botInThread) return 'observe'
+
+  // Plain-text peer-bot addressing as a fallback suppressor. We've reached
+  // here because the message lacks a structural mention/reply/dm AND
+  // doesn't contain our own alias. If it DOES contain a known peer bot's
+  // observed display name, the solo-human fallback would still engage us
+  // — same wrong behavior the alias trigger is meant to fix, just for
+  // peers instead of self. Each bot only configures its own aliases, so
+  // the only source of peer names is `participants[]` (observed
+  // authorName once a peer has spoken at least once in this channel).
+  // First-time addressing of a never-seen peer slips through; after that
+  // peer's first message it's caught forever.
+  if (textTargetsAnyPeerBot(message.text, participants)) return 'observe'
+
+  const persistedHumans = participants.filter((p) => p.isBot !== true).length
+  const effectiveHumans = resolveEffectiveHumans(persistedHumans, input.membership, now)
+  if (effectiveHumans <= 1 && !message.authorIsBot) return 'engage'
+
+  return 'observe'
+}
+
+function textTargetsAnyPeerBot(text: string, participants: readonly ChannelParticipant[]): boolean {
+  const haystack = text.toLocaleLowerCase()
+  for (const p of participants) {
+    if (p.isBot !== true) continue
+    if (p.authorName === '') continue
+    if (haystack.includes(p.authorName.toLocaleLowerCase())) return true
+  }
+  return false
+}
+
+export function resolveEffectiveHumans(
+  persistedHumans: number,
+  membership: MembershipCount | null,
+  now: number,
+): number {
+  if (membership === null) return persistedHumans
+  // A fresh complete API read is the only signal that can see lurkers AND
+  // prune recent leavers. Letting persisted speakers win here would preserve
+  // the exact stale-authorship bug the membership lookup exists to fix.
+  const isFresh = now - membership.fetchedAt < MEMBERSHIP_FRESHNESS_MS
+  if (!membership.truncated && isFresh) return membership.humans
+  // Truncated and stale reads are useful quieting hints, not ground truth.
+  // Persisted speakers are bounded to the last 7 days, so `max()` avoids
+  // under-counting active humans while the platform count is approximate.
+  return Math.max(persistedHumans, membership.humans)
+}
+
+export function grantStickyForReplyTargets(
+  ledger: StickyLedger,
+  key: string,
+  authorIds: readonly string[],
+  config: EngagementConfig,
+  now: number,
+): void {
+  if (config.stickiness === 'off') return
+  const window = config.stickiness.perReply.window
+  for (const id of authorIds) {
+    ledger.grant(key, id, now + window)
+  }
+}
+
+export function matchesAnyAlias(text: string, lowercasedAliases: readonly string[]): boolean {
+  if (lowercasedAliases.length === 0) return false
+  const haystack = text.toLocaleLowerCase()
+  for (const alias of lowercasedAliases) {
+    if (haystack.includes(alias)) return true
+  }
+  return false
+}

package/src/channels/index.ts

@@ -0,0 +1,21 @@
+export { createChannelManager, type ChannelManager, type ChannelManagerOptions } from './manager'
+export {
+  createChannelRouter,
+  type ChannelRouter,
+  type CreateChannelRouterOptions,
+  type CreateSessionForChannel,
+} from './router'
+export { createChannelsReloadable } from './reloadable'
+export {
+  channelsSchema,
+  isAllowed,
+  ADAPTER_IDS,
+  STICKY_DEFAULT_WINDOW_MS,
+  type AdapterId,
+  type AllowRule,
+  type ChannelAdapterConfig,
+  type ChannelsConfig,
+  type EngagementConfig,
+} from './schema'
+export type { ChannelKey, InboundMessage, OutboundCallback, OutboundMessage, SendResult } from './types'
+export { channelKeyId } from './types'

package/src/channels/manager.ts

@@ -0,0 +1,292 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
+import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
+import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
+import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
+import { createChannelRouter, type ChannelRouter, type CreateSessionForChannel } from './router'
+import { ADAPTER_IDS, type AdapterId, type ChannelAdapterConfig, type ChannelsConfig } from './schema'
+
+export type ChannelManagerLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+const consoleLogger: ChannelManagerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export type ChannelManagerOptions = {
+  agentDir: string
+  channelsConfigRef: () => ChannelsConfig
+  // Plain-text names the agent answers to in channel engagement (the
+  // `alias` field in `typeclaw.json`), forwarded to the router as
+  // `configuredAliases`. Read live on every inbound so an `applied`-class
+  // reload of `alias` takes effect without a container restart. Omitted
+  // means alias-based engagement is off — `basename(agentDir)` is still
+  // implicit. This MUST be wired up in production (`src/run/index.ts`)
+  // or the configured aliases are silently orphaned: parsed by the
+  // schema, never read by anyone. See `manager.test.ts` for the
+  // end-to-end engagement assertion that guards this wiring.
+  aliasesRef?: () => readonly string[]
+  logger?: ChannelManagerLogger
+  env?: NodeJS.ProcessEnv
+  // Production wiring passes a factory that builds sessions with the full
+  // runtime plumbing (channelRouter, stream, plugins, reloadRegistry). When
+  // omitted, the router falls back to a hollow factory that creates sessions
+  // without a channelRouter — the agent then has no `channel_send` tool and
+  // cannot reply, which is fine for tests but a bug in production. See
+  // src/run/index.ts where this is wired.
+  createSessionForChannel?: CreateSessionForChannel
+  // Test seams: let fake adapters replace the real adapter wiring per id.
+  createDiscordAdapter?: typeof createDiscordBotAdapter
+  createKakaotalkAdapter?: typeof createKakaotalkAdapter
+  createSlackAdapter?: typeof createSlackBotAdapter
+  createTelegramAdapter?: typeof createTelegramBotAdapter
+}
+
+export type ChannelManager = {
+  router: ChannelRouter
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  reload: () => Promise<{ started: string[]; stopped: string[]; restartRequired: string[] }>
+}
+
+type AnyAdapter = DiscordBotAdapter | KakaotalkAdapter | SlackBotAdapter | TelegramBotAdapter
+
+// Credential signature is the comparison key for credential-rotation
+// detection on reload. Discord and Telegram each use a single bot token;
+// Slack needs both a bot token and an app-level token (Socket Mode);
+// KakaoTalk authenticates via a credentials file under
+// AGENT_MESSENGER_CONFIG_DIR (workspace/), so its signature is the file's
+// content hash. The "credential" naming (vs "token") generalizes across the
+// env-var-based adapters and KakaoTalk's file-based credential pathway.
+type AdapterEntry = {
+  adapter: AnyAdapter
+  credentialSignature: string
+}
+
+export function createChannelManager(options: ChannelManagerOptions): ChannelManager {
+  const logger = options.logger ?? consoleLogger
+  const env = options.env ?? process.env
+  const router = createChannelRouter({
+    agentDir: options.agentDir,
+    configForAdapter: (adapter) => options.channelsConfigRef()[adapter],
+    logger,
+    ...(options.aliasesRef ? { configuredAliases: options.aliasesRef } : {}),
+    ...(options.createSessionForChannel ? { createSessionForChannel: options.createSessionForChannel } : {}),
+  })
+  const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
+  const createKakaotalk = options.createKakaotalkAdapter ?? createKakaotalkAdapter
+  const createSlackAdapter = options.createSlackAdapter ?? createSlackBotAdapter
+  const createTelegramAdapter = options.createTelegramAdapter ?? createTelegramBotAdapter
+
+  const live = new Map<AdapterId, AdapterEntry>()
+
+  const buildCredentialSignature = (name: AdapterId): { signature: string; missing: string[] } => {
+    if (name === 'kakaotalk') return buildKakaotalkSignature(options.agentDir, env)
+    const requiredEnvs = TOKEN_ENV[name]
+    const parts: string[] = []
+    const missing: string[] = []
+    for (const key of requiredEnvs) {
+      const value = env[key]
+      if (value === undefined || value.trim() === '') missing.push(key)
+      else parts.push(`${key}=${value}`)
+    }
+    return { signature: parts.join('|'), missing }
+  }
+
+  const buildAdapter = (name: AdapterId, cfg: ChannelAdapterConfig): AnyAdapter | null => {
+    if (name === 'discord-bot') {
+      const token = env.DISCORD_BOT_TOKEN
+      if (token === undefined || token.trim() === '') return null
+      return createDiscordAdapter({
+        router,
+        configRef: () => options.channelsConfigRef()[name] ?? cfg,
+        token,
+        logger,
+      })
+    }
+    if (name === 'slack-bot') {
+      const token = env.SLACK_BOT_TOKEN
+      const appToken = env.SLACK_APP_TOKEN
+      if (token === undefined || token.trim() === '') return null
+      if (appToken === undefined || appToken.trim() === '') return null
+      return createSlackAdapter({
+        router,
+        configRef: () => options.channelsConfigRef()[name] ?? cfg,
+        token,
+        appToken,
+        logger,
+        selfAliasesRef: () => router.getSelfAliases(),
+      })
+    }
+    if (name === 'kakaotalk') {
+      return createKakaotalk({
+        router,
+        configRef: () => options.channelsConfigRef()[name] ?? cfg,
+        logger,
+        selfAliasesRef: () => router.getSelfAliases(),
+        credentialsDir: resolveKakaoConfigDir(options.agentDir, env),
+      })
+    }
+    if (name === 'telegram-bot') {
+      const token = env.TELEGRAM_BOT_TOKEN
+      if (token === undefined || token.trim() === '') return null
+      return createTelegramAdapter({
+        router,
+        configRef: () => options.channelsConfigRef()[name] ?? cfg,
+        token,
+        logger,
+      })
+    }
+    return null
+  }
+
+  const startAdapter = async (name: AdapterId, cfg: ChannelAdapterConfig): Promise<boolean> => {
+    if (cfg.enabled === false) {
+      logger.info(`[channels] adapter "${name}" is disabled; skipping`)
+      return false
+    }
+    const { signature, missing } = buildCredentialSignature(name)
+    if (missing.length > 0) {
+      logger.error(`[channels] adapter "${name}" missing credentials: ${missing.join(', ')}; skipping`)
+      return false
+    }
+    const adapter = buildAdapter(name, cfg)
+    if (adapter === null) {
+      logger.error(`[channels] adapter "${name}" could not be constructed; skipping`)
+      return false
+    }
+    try {
+      await adapter.start()
+      live.set(name, { adapter, credentialSignature: signature })
+      logger.info(`[channels] adapter "${name}" started`)
+      return true
+    } catch (err) {
+      logger.error(`[channels] adapter "${name}" failed to start: ${describe(err)}`)
+      return false
+    }
+  }
+
+  const stopAdapter = async (name: AdapterId): Promise<void> => {
+    const entry = live.get(name)
+    if (!entry) return
+    live.delete(name)
+    try {
+      await entry.adapter.stop()
+      logger.info(`[channels] adapter "${name}" stopped`)
+    } catch (err) {
+      logger.error(`[channels] adapter "${name}" failed to stop: ${describe(err)}`)
+    }
+  }
+
+  return {
+    router,
+
+    async start(): Promise<void> {
+      const cfg = options.channelsConfigRef()
+      for (const name of ADAPTER_IDS) {
+        const adapterCfg = cfg[name]
+        if (adapterCfg !== undefined) await startAdapter(name, adapterCfg)
+      }
+    },
+
+    async stop(): Promise<void> {
+      for (const name of Array.from(live.keys())) await stopAdapter(name)
+      await router.stop()
+    },
+
+    async reload(): Promise<{ started: string[]; stopped: string[]; restartRequired: string[] }> {
+      const cfg = options.channelsConfigRef()
+      const started: string[] = []
+      const stopped: string[] = []
+      const restartRequired: string[] = []
+
+      for (const name of ADAPTER_IDS) {
+        const desired = cfg[name]
+        const current = live.get(name)
+        if (desired === undefined || desired.enabled === false) {
+          if (current) {
+            await stopAdapter(name)
+            stopped.push(name)
+          }
+        } else if (!current) {
+          const ok = await startAdapter(name, desired)
+          if (ok) started.push(name)
+        } else {
+          const { signature, missing } = buildCredentialSignature(name)
+          if (missing.length > 0) {
+            // Required credentials disappeared (env vars removed from .env, or
+            // KakaoTalk credentials file deleted). Continuing to use the
+            // in-memory credentials would silently honor a credential the
+            // operator explicitly removed, so stop the adapter instead of
+            // waiting for a manual restart.
+            logger.warn(
+              `[channels] adapter "${name}" missing credentials after reload (${missing.join(', ')}); stopping`,
+            )
+            await stopAdapter(name)
+            stopped.push(name)
+          } else if (signature !== current.credentialSignature) {
+            const reason = name === 'kakaotalk' ? 'credential rotation' : 'token rotation'
+            restartRequired.push(`${name} (${reason})`)
+          }
+        }
+      }
+
+      return { started, stopped, restartRequired }
+    },
+  }
+}
+
+// Token-based adapters only. KakaoTalk's credentials live in a file under
+// AGENT_MESSENGER_CONFIG_DIR (workspace/.agent-messenger/), not in env, so
+// it goes through buildKakaotalkSignature instead.
+const TOKEN_ENV: Record<Exclude<AdapterId, 'kakaotalk'>, readonly string[]> = {
+  'discord-bot': ['DISCORD_BOT_TOKEN'],
+  'slack-bot': ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN'],
+  'telegram-bot': ['TELEGRAM_BOT_TOKEN'],
+}
+
+const KAKAO_DEFAULT_SUBDIR = '.agent-messenger'
+const KAKAO_CREDENTIALS_FILE = 'kakaotalk-credentials.json'
+
+function resolveKakaoConfigDir(agentDir: string, env: NodeJS.ProcessEnv): string {
+  const override = env.AGENT_MESSENGER_CONFIG_DIR
+  if (override !== undefined && override.trim() !== '') return override
+  return join(agentDir, 'workspace', KAKAO_DEFAULT_SUBDIR)
+}
+
+function resolveKakaoCredentialsPath(agentDir: string, env: NodeJS.ProcessEnv): string {
+  return join(resolveKakaoConfigDir(agentDir, env), KAKAO_CREDENTIALS_FILE)
+}
+
+function buildKakaotalkSignature(agentDir: string, env: NodeJS.ProcessEnv): { signature: string; missing: string[] } {
+  const path = resolveKakaoCredentialsPath(agentDir, env)
+  if (!existsSync(path)) {
+    return { signature: '', missing: [`kakaotalk credentials file at ${path}`] }
+  }
+  try {
+    // Content hash, not mtime+size: KakaoTalk's credential file is small
+    // (a few hundred bytes of JSON) and is rewritten on every OAuth token
+    // refresh. Hashing avoids two failure modes mtime+size could miss:
+    //   (a) a refresh that produces byte-identical content (rare but
+    //       possible when nothing actually rotated) — we correctly skip;
+    //   (b) a refresh that lands on the same mtime due to FS resolution
+    //       (some host filesystems quantize to seconds).
+    const buf = readFileSync(path)
+    const digest = createHash('sha256').update(buf).digest('hex')
+    return { signature: `${path}@sha256:${digest}`, missing: [] }
+  } catch (err) {
+    return { signature: '', missing: [`kakaotalk credentials file at ${path} (${describe(err)})`] }
+  }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/membership-cache.ts

@@ -0,0 +1,116 @@
+import {
+  MEMBERSHIP_CACHE_PERMANENT_TTL_MS,
+  MEMBERSHIP_CACHE_TRANSIENT_TTL_MS,
+  MEMBERSHIP_CACHE_TTL_MS,
+  type MembershipCount,
+  type MembershipResolver,
+  type MembershipResolverFailure,
+  type MembershipResolverResult,
+} from './membership'
+import type { ChannelKey } from './types'
+import { channelKeyId } from './types'
+
+export type MembershipCacheRead =
+  | { kind: 'hit'; membership: MembershipCount | null }
+  | { kind: 'stale'; membership: MembershipCount }
+  | { kind: 'miss' }
+
+type CacheEntry = {
+  result: MembershipResolverResult
+  expiresAt: number
+  servedStale: boolean
+}
+
+export type MembershipCacheLogger = {
+  warn: (msg: string) => void
+}
+
+export type MembershipCacheOptions = {
+  resolver: MembershipResolver
+  now?: () => number
+  logger?: MembershipCacheLogger
+}
+
+export type MembershipCache = {
+  read: (key: ChannelKey) => MembershipCacheRead
+  get: (key: ChannelKey) => MembershipCount | null
+  warmUp: (key: ChannelKey) => Promise<MembershipCount | null>
+  invalidate: (key: ChannelKey) => void
+}
+
+export function createMembershipCache(options: MembershipCacheOptions): MembershipCache {
+  const now = options.now ?? Date.now
+  const entries = new Map<string, CacheEntry>()
+  const inFlight = new Map<string, Promise<MembershipCount | null>>()
+
+  const read = (key: ChannelKey): MembershipCacheRead => {
+    const entry = entries.get(channelKeyId(key))
+    if (entry === undefined) return { kind: 'miss' }
+
+    if (entry.expiresAt > now()) return { kind: 'hit', membership: toMembership(entry.result) }
+    if (isMembershipCount(entry.result) && !entry.servedStale) {
+      entry.servedStale = true
+      return { kind: 'stale', membership: entry.result }
+    }
+    return { kind: 'miss' }
+  }
+
+  const warmUp = (key: ChannelKey): Promise<MembershipCount | null> => {
+    const keyId = channelKeyId(key)
+    const cached = read(key)
+    if (cached.kind === 'hit') return Promise.resolve(cached.membership)
+    if (cached.kind === 'stale') return Promise.resolve(cached.membership)
+
+    const existing = inFlight.get(keyId)
+    if (existing !== undefined) return existing
+
+    const promise = resolveAndStore(key, keyId).finally(() => {
+      inFlight.delete(keyId)
+    })
+    inFlight.set(keyId, promise)
+    return promise
+  }
+
+  const resolveAndStore = async (key: ChannelKey, keyId: string): Promise<MembershipCount | null> => {
+    let result: MembershipResolverResult
+    try {
+      result = await options.resolver(key)
+    } catch (err) {
+      options.logger?.warn(`[channels] membership resolver threw for ${keyId}: ${describe(err)}`)
+      result = { kind: 'transient' }
+    }
+    entries.set(keyId, { result, expiresAt: now() + ttlFor(result), servedStale: false })
+    return toMembership(result)
+  }
+
+  return {
+    read,
+    get: (key) => {
+      const cached = read(key)
+      return cached.kind === 'hit' ? cached.membership : null
+    },
+    warmUp,
+    invalidate: (key) => {
+      entries.delete(channelKeyId(key))
+    },
+  }
+}
+
+function ttlFor(result: MembershipResolverResult): number {
+  if (isMembershipCount(result)) return MEMBERSHIP_CACHE_TTL_MS
+  return result.kind === 'permanent' ? MEMBERSHIP_CACHE_PERMANENT_TTL_MS : MEMBERSHIP_CACHE_TRANSIENT_TTL_MS
+}
+
+function toMembership(result: MembershipResolverResult): MembershipCount | null {
+  return isMembershipCount(result) ? result : null
+}
+
+function isMembershipCount(result: MembershipResolverResult): result is MembershipCount {
+  return 'humans' in result
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+export type { MembershipResolverFailure }