typeclaw 0.1.0

package/src/bundled-plugins/security/policies/secret-exfil-read.ts

@@ -0,0 +1,127 @@
+import path from 'node:path'
+
+import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
+
+export const GUARD_SECRET_EXFIL_READ = 'secretExfilRead'
+
+const SENSITIVE_BASENAMES = new Set([
+  '.env',
+  '.envrc',
+  '.netrc',
+  '.pgpass',
+  'credentials',
+  'credentials.json',
+  'credentials.yaml',
+  'credentials.yml',
+  'service-account.json',
+  'gha-creds.json',
+  'token.json',
+])
+
+const SENSITIVE_BASENAME_PATTERNS: ReadonlyArray<RegExp> = [
+  /^\.env\.[^/\\]+$/,
+  /^id_(?:rsa|ed25519|ecdsa|dsa)(?:\.pub)?$/,
+]
+
+const SENSITIVE_DIRECTORY_SEGMENTS = [
+  '.ssh',
+  '.gnupg',
+  '.aws',
+  '.docker',
+  '.kube',
+  '.hermes',
+  '.config/gh',
+  '.config/hub',
+  '.config/sops',
+  '.config/op',
+  '.config/hermes',
+]
+
+const HISTORY_BASENAMES = new Set([
+  '.bash_history',
+  '.zsh_history',
+  '.python_history',
+  '.node_repl_history',
+  '.lesshst',
+  '.viminfo',
+  '.mysql_history',
+  '.psql_history',
+])
+
+const PATH_LIKE_KEYS = ['path', 'paths', 'pattern', 'patterns', 'glob', 'globs', 'cwd', 'dir', 'directory']
+
+export function checkSecretExfilReadGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+}): SecurityBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'read' && tool !== 'grep' && tool !== 'find' && tool !== 'ls') return undefined
+  if (isGuardAcknowledged(args, GUARD_SECRET_EXFIL_READ)) return undefined
+
+  for (const key of PATH_LIKE_KEYS) {
+    const value = args[key]
+    const candidates = collectStringValues(value)
+    for (const candidate of candidates) {
+      const reason = classifySensitivePath(candidate)
+      if (reason) {
+        return {
+          block: true,
+          reason: [
+            `Guard \`${GUARD_SECRET_EXFIL_READ}\` blocked ${tool} of ${reason}: ${candidate}.`,
+            'Reading secret material is treated as exfiltration even when the agent only intends to inspect it.',
+            `If this is genuinely intentional, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SECRET_EXFIL_READ}: true\` in the tool arguments.`,
+          ].join(' '),
+        }
+      }
+    }
+  }
+  return undefined
+}
+
+function collectStringValues(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string')
+  return []
+}
+
+function classifySensitivePath(rawPath: string): string | undefined {
+  const normalized = rawPath.replace(/\\/g, '/').replace(/^~\//, '/home/__user__/').replace(/^~/, '/home/__user__/')
+  const basename = path.basename(normalized)
+
+  if (SENSITIVE_BASENAMES.has(basename)) return `${basename} (credentials file)`
+  if (HISTORY_BASENAMES.has(basename)) return `${basename} (shell history; may contain accidentally typed secrets)`
+  for (const pat of SENSITIVE_BASENAME_PATTERNS) {
+    if (pat.test(basename)) return `${basename} (looks like a credentials/secret file)`
+  }
+
+  const segments = normalized.split('/').filter((s) => s.length > 0)
+  for (const seg of SENSITIVE_DIRECTORY_SEGMENTS) {
+    const parts = seg.split('/')
+    if (containsSubsequence(segments, parts)) return `${seg}/ (sensitive directory)`
+  }
+
+  if (/(?:^|\/)\.config\/[^/]+\/(?:credentials|token|secret|auth|cookies|session)/.test(normalized)) {
+    return '~/.config/**/credentials-like file'
+  }
+
+  if (normalized.startsWith('/proc/') && normalized.endsWith('/environ')) {
+    return '/proc/*/environ (process environment)'
+  }
+
+  return undefined
+}
+
+function containsSubsequence<T>(haystack: T[], needle: T[]): boolean {
+  if (needle.length === 0) return false
+  for (let i = 0; i + needle.length <= haystack.length; i++) {
+    let ok = true
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return true
+  }
+  return false
+}

package/src/bundled-plugins/security/policies/session-search-secrets.ts

@@ -0,0 +1,86 @@
+import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
+
+export const GUARD_SESSION_SEARCH_SECRETS = 'sessionSearchSecrets'
+
+const SESSION_SEARCH_TOOLS: ReadonlySet<string> = new Set([
+  'session_search',
+  'session-search',
+  'sessionSearch',
+  'session_history_search',
+  'sessionHistorySearch',
+  'history_search',
+  'historySearch',
+])
+
+const QUERY_KEYS: ReadonlyArray<string> = ['query', 'q', 'search', 'pattern', 'keywords', 'text']
+
+const SECRET_KEYWORD_PATTERNS: ReadonlyArray<{ pattern: RegExp; label: string }> = [
+  { pattern: /\bpassword\b/i, label: 'password' },
+  { pattern: /\bpasswd\b/i, label: 'passwd' },
+  { pattern: /\bpassphrase\b/i, label: 'passphrase' },
+  { pattern: /\bapi[_-]?keys?\b/i, label: 'api_key' },
+  { pattern: /\bapikey\b/i, label: 'apikey' },
+  { pattern: /\bsecret(?:s|_key)?\b/i, label: 'secret' },
+  { pattern: /\bbearer\b/i, label: 'bearer' },
+  { pattern: /\bauth[_-]?token\b/i, label: 'auth_token' },
+  { pattern: /\baccess[_-]?token\b/i, label: 'access_token' },
+  { pattern: /\brefresh[_-]?token\b/i, label: 'refresh_token' },
+  { pattern: /\bprivate[_-]?key\b/i, label: 'private_key' },
+  { pattern: /\bcredentials?\b/i, label: 'credentials' },
+  { pattern: /\bcredit[_-]?card\b/i, label: 'credit_card' },
+  { pattern: /\bxox[baprs]-/i, label: 'slack token prefix' },
+  { pattern: /\bghp_/i, label: 'github PAT prefix' },
+  { pattern: /\bgho_/i, label: 'github OAuth prefix' },
+  { pattern: /\bsk-(?:ant|proj)?/i, label: 'openai/anthropic key prefix' },
+  { pattern: /\bAKIA\b/, label: 'AWS access key prefix' },
+  { pattern: /\bAIza[A-Za-z0-9]/, label: 'Google API key prefix' },
+]
+
+export function detectSessionSearchSecretQuery(query: string): ReadonlyArray<{ label: string }> {
+  const hits: Array<{ label: string }> = []
+  const seen = new Set<string>()
+  for (const { pattern, label } of SECRET_KEYWORD_PATTERNS) {
+    if (pattern.test(query) && !seen.has(label)) {
+      seen.add(label)
+      hits.push({ label })
+    }
+  }
+  return hits
+}
+
+export function checkSessionSearchSecretsGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+}): SecurityBlock | undefined {
+  const { tool, args } = options
+  if (!SESSION_SEARCH_TOOLS.has(tool)) return undefined
+  if (isGuardAcknowledged(args, GUARD_SESSION_SEARCH_SECRETS)) return undefined
+
+  const queries = collectQueryStrings(args)
+  for (const query of queries) {
+    const hits = detectSessionSearchSecretQuery(query)
+    if (hits.length === 0) continue
+    const summary = hits.map((h) => h.label).join(', ')
+    return {
+      block: true,
+      reason: [
+        `Guard \`${GUARD_SESSION_SEARCH_SECRETS}\` blocked ${tool}: query targets credential-shaped keywords (${summary}).`,
+        'Searching session history for secret-shaped strings is a recon pattern - even if the index returns no hits today, a future session that accidentally typed a credential will match.',
+        `If this is genuinely intentional (e.g. auditing past leaks deliberately), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SESSION_SEARCH_SECRETS}: true\` in the tool arguments.`,
+      ].join(' '),
+    }
+  }
+  return undefined
+}
+
+function collectQueryStrings(args: Record<string, unknown>): string[] {
+  const out: string[] = []
+  for (const key of QUERY_KEYS) {
+    const value = args[key]
+    if (typeof value === 'string' && value.length > 0) out.push(value)
+    else if (Array.isArray(value)) {
+      for (const v of value) if (typeof v === 'string' && v.length > 0) out.push(v)
+    }
+  }
+  return out
+}

package/src/bundled-plugins/security/policies/ssrf.ts

@@ -0,0 +1,196 @@
+import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
+
+export const GUARD_SSRF = 'ssrf'
+
+const ALWAYS_BLOCKED_HOSTS = new Set([
+  'localhost',
+  'localhost.localdomain',
+  'ip6-localhost',
+  'ip6-loopback',
+  'metadata.google.internal',
+  'metadata',
+  'metadata.aws.internal',
+  'instance-data',
+  'instance-data.ec2.internal',
+])
+
+const ALWAYS_BLOCKED_HOST_SUFFIXES = ['.internal', '.local', '.localhost', '.lan', '.intranet', '.corp', '.home']
+
+export type SsrfClassification = {
+  blocked: boolean
+  category?:
+    | 'loopback'
+    | 'private_ipv4'
+    | 'link_local'
+    | 'cloud_metadata'
+    | 'ipv6_internal'
+    | 'unspecified'
+    | 'shared_cgnat'
+    | 'reserved_internal_host'
+    | 'unsupported_scheme'
+  reason?: string
+}
+
+export function classifyUrl(rawUrl: string): SsrfClassification {
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    return { blocked: false }
+  }
+
+  if (
+    parsed.protocol === 'file:' ||
+    parsed.protocol === 'gopher:' ||
+    parsed.protocol === 'ftp:' ||
+    parsed.protocol === 'data:' ||
+    parsed.protocol === 'jar:' ||
+    parsed.protocol === 'php:' ||
+    parsed.protocol === 'dict:'
+  ) {
+    return {
+      blocked: true,
+      category: 'unsupported_scheme',
+      reason: `${parsed.protocol} URL is not allowed for outbound fetch`,
+    }
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { blocked: false }
+  }
+
+  const host = parsed.hostname.toLowerCase()
+  const decoded = decodeBracketedIpv6(host)
+
+  if (ALWAYS_BLOCKED_HOSTS.has(decoded)) {
+    return {
+      blocked: true,
+      category: 'reserved_internal_host',
+      reason: `host "${decoded}" resolves to internal/loopback infrastructure`,
+    }
+  }
+  for (const suffix of ALWAYS_BLOCKED_HOST_SUFFIXES) {
+    if (decoded.endsWith(suffix)) {
+      return {
+        blocked: true,
+        category: 'reserved_internal_host',
+        reason: `host suffix "${suffix}" is reserved for internal networks`,
+      }
+    }
+  }
+
+  const ipv4 = parseIpv4Loose(decoded)
+  if (ipv4) {
+    const cls = classifyIpv4(ipv4)
+    if (cls) return { blocked: true, category: cls.category, reason: cls.reason }
+  }
+
+  if (looksLikeIpv6(decoded)) {
+    const cls = classifyIpv6(decoded)
+    if (cls) return { blocked: true, category: cls.category, reason: cls.reason }
+  }
+
+  return { blocked: false }
+}
+
+export function checkSsrfGuard(options: { tool: string; args: Record<string, unknown> }): SecurityBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'webfetch') return undefined
+  const url = args.url
+  if (typeof url !== 'string') return undefined
+  if (isGuardAcknowledged(args, GUARD_SSRF)) return undefined
+
+  const result = classifyUrl(url)
+  if (!result.blocked) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_SSRF}\` blocked webfetch to a non-public destination (${result.category ?? 'unknown'}): ${result.reason ?? 'classified as internal'}.`,
+      'This protects against SSRF, cloud metadata exfiltration, and accidental fetches against internal services.',
+      `If this is genuinely intentional and you trust the URL, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SSRF}: true\` in the webfetch arguments.`,
+    ].join(' '),
+  }
+}
+
+function decodeBracketedIpv6(host: string): string {
+  if (host.startsWith('[') && host.endsWith(']')) return host.slice(1, -1)
+  return host
+}
+
+function parseIpv4Loose(host: string): [number, number, number, number] | undefined {
+  const dotted = host.match(/^(\d{1,10})\.(\d{1,10})\.(\d{1,10})\.(\d{1,10})$/)
+  if (dotted && dotted[1] && dotted[2] && dotted[3] && dotted[4]) {
+    const parts = [dotted[1], dotted[2], dotted[3], dotted[4]].map((s) => parseInt(s, 10))
+    if (parts.every((n) => Number.isFinite(n) && n >= 0 && n <= 255)) {
+      return parts as [number, number, number, number]
+    }
+  }
+  const decimal = host.match(/^(\d{6,12})$/)
+  if (decimal && decimal[1]) {
+    const n = Number(decimal[1])
+    if (Number.isFinite(n) && n >= 0 && n <= 0xffffffff) {
+      return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]
+    }
+  }
+  const hex = host.match(/^0x([0-9a-f]{1,8})$/i)
+  if (hex && hex[1]) {
+    const n = parseInt(hex[1], 16)
+    if (Number.isFinite(n) && n >= 0 && n <= 0xffffffff) {
+      return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]
+    }
+  }
+  return undefined
+}
+
+function classifyIpv4(
+  ip: [number, number, number, number],
+): { category: SsrfClassification['category']; reason: string } | undefined {
+  const [a, b] = ip
+  if (a === 127) return { category: 'loopback', reason: `IPv4 loopback (${ip.join('.')})` }
+  if (a === 10) return { category: 'private_ipv4', reason: `private RFC1918 10.0.0.0/8 (${ip.join('.')})` }
+  if (a === 172 && b >= 16 && b <= 31)
+    return { category: 'private_ipv4', reason: `private RFC1918 172.16.0.0/12 (${ip.join('.')})` }
+  if (a === 192 && b === 168)
+    return { category: 'private_ipv4', reason: `private RFC1918 192.168.0.0/16 (${ip.join('.')})` }
+  if (a === 169 && b === 254)
+    return { category: 'cloud_metadata', reason: `link-local / cloud metadata 169.254.0.0/16 (${ip.join('.')})` }
+  if (a === 100 && b >= 64 && b <= 127)
+    return { category: 'shared_cgnat', reason: `CGNAT 100.64.0.0/10 (${ip.join('.')})` }
+  if (a === 0) return { category: 'unspecified', reason: `unspecified 0.0.0.0/8 (${ip.join('.')})` }
+  if (a >= 224) return { category: 'private_ipv4', reason: `multicast/reserved (${ip.join('.')})` }
+  return undefined
+}
+
+function looksLikeIpv6(host: string): boolean {
+  return host.includes(':') && /^[0-9a-f:]+$/i.test(host)
+}
+
+function classifyIpv6(host: string): { category: SsrfClassification['category']; reason: string } | undefined {
+  const lower = host.toLowerCase()
+  if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return { category: 'loopback', reason: 'IPv6 loopback ::1' }
+  if (lower === '::' || lower === '0:0:0:0:0:0:0:0') return { category: 'unspecified', reason: 'IPv6 unspecified ::' }
+  if (lower.startsWith('fe80:') || lower.startsWith('fe80::'))
+    return { category: 'link_local', reason: 'IPv6 link-local fe80::/10' }
+  if (lower.startsWith('fc') || lower.startsWith('fd'))
+    return { category: 'ipv6_internal', reason: 'IPv6 unique-local fc00::/7' }
+  if (lower.startsWith('ff')) return { category: 'ipv6_internal', reason: 'IPv6 multicast ff00::/8' }
+  if (lower.startsWith('::ffff:')) {
+    const tail = lower.slice('::ffff:'.length)
+    const dotted = parseIpv4Loose(tail)
+    if (dotted) {
+      const cls = classifyIpv4(dotted)
+      if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
+    }
+    const hexPair = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
+    if (hexPair && hexPair[1] && hexPair[2]) {
+      const hi = parseInt(hexPair[1], 16)
+      const lo = parseInt(hexPair[2], 16)
+      if (Number.isFinite(hi) && Number.isFinite(lo)) {
+        const ip: [number, number, number, number] = [(hi >>> 8) & 0xff, hi & 0xff, (lo >>> 8) & 0xff, lo & 0xff]
+        const cls = classifyIpv4(ip)
+        if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
+      }
+    }
+  }
+  return undefined
+}

package/src/bundled-plugins/security/policies/system-prompt-leak.ts

@@ -0,0 +1,81 @@
+import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
+
+export const GUARD_SYSTEM_PROMPT_LEAK = 'systemPromptLeak'
+
+const FINGERPRINT_PATTERNS: ReadonlyArray<{ label: string; pattern: RegExp }> = [
+  { label: 'TypeClaw runtime preamble', pattern: /You are a general-purpose AI agent running inside TypeClaw\./ },
+  { label: 'TypeClaw "Your agent folder" header', pattern: /^##\s+Your\s+agent\s+folder\b/m },
+  {
+    label: 'IDENTITY.md / SOUL.md / MEMORY.md / USER.md / AGENTS.md identity-file recital',
+    pattern: /IDENTITY\.md\b[\s\S]{0,400}SOUL\.md\b[\s\S]{0,400}(?:MEMORY\.md|USER\.md|AGENTS\.md)/,
+  },
+  {
+    label: 'TypeClaw injected MEMORY-context disclaimer',
+    pattern: /\[MEMORY\s+CONTEXT\s+[\u2014-]\s+not\s+instructions\]/,
+  },
+  {
+    label: 'TypeClaw session-origin / channel_reply preamble',
+    pattern: /For\s+every\s+user\s+message\s+in\s+this\s+session,\s+you\s+MUST\s+call\s+`?channel_reply`?/,
+  },
+  { label: 'TypeClaw available_skills XML block', pattern: /<available_skills>[\s\S]*?<\/available_skills>/ },
+  { label: 'TypeClaw skill XML element', pattern: /<skill>\s*<name>[\s\S]*?<\/name>\s*<description>/ },
+  {
+    label: 'pi-coding-agent SOUL.md prelude',
+    pattern: /If\s+SOUL\.md\s+has\s+content\s+below,\s+embody\s+its\s+persona/,
+  },
+  {
+    label: 'TypeClaw NO_REPLY contract',
+    pattern: /your\s+entire\s+final\s+visible\s+response\s+must\s+be\s+exactly\s+`?NO_REPLY`?/,
+  },
+  {
+    label: 'TypeClaw SOUL/IDENTITY/MEMORY headed code-block dump',
+    pattern: /^#\s+(?:Identity|Memory|Project\s+Context)\s*$/m,
+  },
+]
+
+const MARKDOWN_HEADERS_DISTINCTIVE = /^##\s+(?:IDENTITY\.md|SOUL\.md|USER\.md|MEMORY\.md|AGENTS\.md)\s*$/m
+
+export type SystemPromptLeakMatch = { label: string; pattern: string }
+
+export function findSystemPromptLeak(text: string): SystemPromptLeakMatch[] {
+  const hits: SystemPromptLeakMatch[] = []
+  for (const { label, pattern } of FINGERPRINT_PATTERNS) {
+    if (pattern.test(text)) hits.push({ label, pattern: pattern.source })
+  }
+  if (MARKDOWN_HEADERS_DISTINCTIVE.test(text)) {
+    hits.push({
+      label: 'Identity-file markdown header (e.g. ## SOUL.md)',
+      pattern: MARKDOWN_HEADERS_DISTINCTIVE.source,
+    })
+  }
+  return hits
+}
+
+export function checkSystemPromptLeakGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+}): SecurityBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'channel_send' && tool !== 'channel_reply') return undefined
+  if (isGuardAcknowledged(args, GUARD_SYSTEM_PROMPT_LEAK)) return undefined
+
+  const candidates: string[] = []
+  for (const key of ['text', 'message', 'content', 'body']) {
+    const v = args[key]
+    if (typeof v === 'string' && v.length > 0) candidates.push(v)
+  }
+  for (const text of candidates) {
+    const hits = findSystemPromptLeak(text)
+    if (hits.length === 0) continue
+    const summary = hits.map((h) => h.label).join('; ')
+    return {
+      block: true,
+      reason: [
+        `Guard \`${GUARD_SYSTEM_PROMPT_LEAK}\` blocked ${tool}: outbound text contains TypeClaw system-prompt fingerprints (${summary}).`,
+        'Posting the system prompt or identity files to a channel exposes the agent to prompt-injection replay attacks.',
+        `If this is genuinely intentional (e.g. you are debugging your own agent), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SYSTEM_PROMPT_LEAK}: true\` in the tool arguments.`,
+      ].join(' '),
+    }
+  }
+  return undefined
+}

package/src/bundled-plugins/security/policy.ts

@@ -0,0 +1,9 @@
+export const ACKNOWLEDGE_GUARDS = 'acknowledgeGuards'
+
+export type SecurityBlock = { block: true; reason: string }
+
+export function isGuardAcknowledged(args: Record<string, unknown>, guard: string): boolean {
+  const acknowledgements = args[ACKNOWLEDGE_GUARDS]
+  if (!acknowledgements || typeof acknowledgements !== 'object') return false
+  return (acknowledgements as Record<string, unknown>)[guard] === true
+}

package/src/channels/adapters/discord-bot-channel-resolver.ts

@@ -0,0 +1,77 @@
+import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
+
+const DISCORD_API_BASE = 'https://discord.com/api/v10'
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
+
+export type DiscordChannelResolverOptions = {
+  token: string
+  now?: () => number
+  ttlMs?: number
+}
+
+type CacheEntry<T> = { value: T; expiresAt: number }
+
+type DiscordChannel = { id?: string; name?: string }
+type DiscordGuild = { id?: string; name?: string }
+
+export function createDiscordChannelResolver(options: DiscordChannelResolverOptions): ChannelNameResolver {
+  const now = options.now ?? Date.now
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+
+  const channelCache = new Map<string, CacheEntry<string>>()
+  const guildCache = new Map<string, CacheEntry<string>>()
+
+  const fetchCached = async <T>(
+    cache: Map<string, CacheEntry<T>>,
+    key: string,
+    fetcher: () => Promise<T | null>,
+  ): Promise<T | null> => {
+    const cached = cache.get(key)
+    if (cached && cached.expiresAt > now()) return cached.value
+    const value = await fetcher()
+    if (value !== null) cache.set(key, { value, expiresAt: now() + ttlMs })
+    return value
+  }
+
+  return async (key: ChannelKey): Promise<ResolvedChannelNames> => {
+    if (key.workspace === '@dm') return {}
+
+    const [chatName, workspaceName] = await Promise.all([
+      fetchCached(channelCache, key.chat, () => fetchChannelName(key.chat, options.token)),
+      fetchCached(guildCache, key.workspace, () => fetchGuildName(key.workspace, options.token)),
+    ])
+
+    const result: ResolvedChannelNames = {}
+    if (chatName !== null) result.chatName = chatName
+    if (workspaceName !== null) result.workspaceName = workspaceName
+    return result
+  }
+}
+
+async function fetchChannelName(channelId: string, token: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${DISCORD_API_BASE}/channels/${encodeURIComponent(channelId)}`, {
+      headers: { Authorization: `Bot ${token}` },
+    })
+    if (!response.ok) return null
+    const body = (await response.json()) as DiscordChannel
+    if (typeof body.name !== 'string' || body.name === '') return null
+    return body.name
+  } catch {
+    return null
+  }
+}
+
+async function fetchGuildName(guildId: string, token: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${DISCORD_API_BASE}/guilds/${encodeURIComponent(guildId)}`, {
+      headers: { Authorization: `Bot ${token}` },
+    })
+    if (!response.ok) return null
+    const body = (await response.json()) as DiscordGuild
+    if (typeof body.name !== 'string' || body.name === '') return null
+    return body.name
+  } catch {
+    return null
+  }
+}