typeclaw 0.1.0

package/src/agent/tools/channel-reply.ts

@@ -0,0 +1,182 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
+import type { AdapterId } from '@/channels/schema'
+
+export type ChannelReplyOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
+export type CreateChannelReplyToolOptions = {
+  router: ChannelRouter
+  origin: ChannelReplyOrigin
+}
+
+// channel_reply is the happy-path companion to channel_send for channel-routed
+// sessions. The session's origin already pins the conversation we're inside
+// (adapter, workspace, chat, thread), so the model shouldn't have to copy
+// those fields verbatim every turn — that copying is exactly where it has
+// historically dropped `thread` and posted to channel root by accident.
+//
+// channel_reply takes only `text` and addresses the message from the origin.
+// channel_send remains for posting somewhere else (different chat, breaking
+// out of a thread, sending DMs from a channel session, etc.).
+export function createChannelReplyTool({ router, origin }: CreateChannelReplyToolOptions) {
+  return defineTool({
+    name: 'channel_reply',
+    label: 'Channel Reply',
+    description:
+      'Reply in the current conversation. This is your default way to respond to a channel session — ' +
+      'addressing fields (adapter, workspace, chat, thread) are filled in from the session origin, so ' +
+      'you only supply the text. To post somewhere else (different chat, break out of the current ' +
+      'thread, etc.), use `channel_send` instead.',
+    parameters: Type.Object({
+      text: Type.Optional(
+        Type.String({
+          description:
+            'The message body. Use platform mention syntax `<@USER_ID>` for Slack/Discord mentions. Optional only when `attachments` is set.',
+          minLength: 1,
+        }),
+      ),
+      attachments: Type.Optional(
+        Type.Array(
+          Type.Object({
+            path: Type.String({
+              description: 'Absolute path inside the agent container to the file to upload.',
+              minLength: 1,
+            }),
+            filename: Type.Optional(Type.String({ minLength: 1 })),
+          }),
+          {
+            description:
+              'Optional files to attach. Slack folds `text` into the first file as a caption (single message). Discord uploads files separately and may post `text` as a follow-up message; uploaded files land in channel root even when replying inside a thread (upstream limitation).',
+            minItems: 1,
+          },
+        ),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const text = params.text
+      const attachments = params.attachments
+      if ((text === undefined || text === '') && (attachments === undefined || attachments.length === 0)) {
+        return {
+          content: [
+            { type: 'text' as const, text: 'channel_reply denied: must provide `text`, `attachments`, or both.' },
+          ],
+          details: { ok: false, error: 'missing text and attachments' },
+        }
+      }
+
+      const noReplyError = noReplyMisuseError(text)
+      if (noReplyError) {
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${noReplyError}` }],
+          details: { ok: false, error: noReplyError },
+        }
+      }
+
+      const result = await router.send({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        ...(text !== undefined ? { text } : {}),
+        ...(attachments !== undefined ? { attachments } : {}),
+      })
+
+      const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
+      // Echo the delivered text back to the model. The adapter classifier
+      // drops self-authored messages on the inbound path (`self_author`),
+      // so the bot otherwise has ZERO visibility into what it just said —
+      // not in the next iteration's context, not in later turns' history.
+      // Without this echo, a model that splits a multi-part reply has no
+      // way to tell "did I already send part 1?" from "I haven't started
+      // yet", and routinely re-sends near-duplicates within the same turn
+      // (observed in production: two consecutive identical
+      // greeting messages to one prompt).
+      //
+      // We deliberately do NOT cap sends-per-turn here. A complex user
+      // request legitimately needs split replies, and a hard cap would
+      // mutilate that. The fix is to give the model honest feedback —
+      // show it what it sent, let it decide whether to continue.
+      // Truncate past 500 chars so a long reply doesn't double the prompt
+      // size on every subsequent iteration; the prefix is enough to detect
+      // duplication, and the full text is recoverable from the session
+      // JSONL if needed.
+      const echo = renderOutboundEcho(text, attachments)
+      const baseText = result.ok
+        ? `posted to ${origin.adapter}:${origin.workspace}/${origin.chat}: ${echo}`
+        : `channel_reply denied: ${result.error}`
+      const hint = result.ok
+        ? consecutiveSendHint(
+            router.getConsecutiveSendCount({
+              adapter: origin.adapter,
+              workspace: origin.workspace,
+              chat: origin.chat,
+              thread: origin.thread,
+            }),
+          )
+        : ''
+      return {
+        content: [{ type: 'text' as const, text: hint ? `${baseText} — ${hint}` : baseText }],
+        details,
+      }
+    },
+  })
+}
+
+export const ECHO_MAX_CHARS = 500
+
+export function renderEcho(text: string): string {
+  if (text.length <= ECHO_MAX_CHARS) return JSON.stringify(text)
+  return `${JSON.stringify(text.slice(0, ECHO_MAX_CHARS))}... (${text.length} chars total)`
+}
+
+export function renderOutboundEcho(
+  text: string | undefined,
+  attachments: ReadonlyArray<{ path: string; filename?: string }> | undefined,
+): string {
+  const hasText = text !== undefined && text !== ''
+  const hasAttachments = attachments !== undefined && attachments.length > 0
+  if (hasText && hasAttachments) {
+    const filenames = attachments.map((a) => a.filename ?? a.path.split('/').pop() ?? a.path)
+    return `${renderEcho(text)} + ${attachments.length} file(s): ${filenames.join(', ')}`
+  }
+  if (hasText) return renderEcho(text)
+  if (hasAttachments) {
+    const filenames = attachments.map((a) => a.filename ?? a.path.split('/').pop() ?? a.path)
+    return `${attachments.length} file(s): ${filenames.join(', ')}`
+  }
+  return '(empty)'
+}
+
+// Mirror of the same guard used by channel_send. Blocks any silent-turn
+// signal (per `isNoReplySignal`) from being sent as a message body — same
+// misuse, same denial, regardless of which sending tool the model picked.
+// Returns '' when text is undefined (attachments-only reply, can't be
+// misusing the signal) or when text is non-empty and not a signal.
+function noReplyMisuseError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (text.trim() === '') return ''
+  if (!isNoReplySignal(text)) return ''
+  return (
+    '`NO_REPLY` is the silent-turn signal, not a message body. ' +
+    'To stay silent, end your turn with `NO_REPLY` as your entire visible response and NO channel tool call. ' +
+    'To send an actual reply, call this tool again with different text.'
+  )
+}
+
+// Mirror of the same hint used by channel_send. Kept identical so the model
+// sees the same yield signal regardless of which tool it picked.
+function consecutiveSendHint(countAfterSend: number): string {
+  if (countAfterSend <= 1) return ''
+  if (countAfterSend === 2) {
+    return 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
+  }
+  return `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+}

package/src/agent/tools/channel-send.ts

@@ -0,0 +1,212 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
+import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
+
+import { renderOutboundEcho } from './channel-reply'
+
+export type ChannelSendOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
+export type CreateChannelSendToolOptions = {
+  router: ChannelRouter
+  // Optional channel origin for the session this tool is wired into. When
+  // present, the tool can detect "you posted to the same conversation but
+  // dropped the thread" and surface that as a hint in the tool result, so
+  // the model can self-correct on its next turn. Absent for sessions whose
+  // origin isn't a channel (e.g. cron prompts that send to channels).
+  origin?: ChannelSendOrigin
+}
+
+export function createChannelSendTool({ router, origin }: CreateChannelSendToolOptions) {
+  return defineTool({
+    name: 'channel_send',
+    label: 'Channel Send',
+    description:
+      'Post a message to an external messenger channel. Specify adapter, workspace, chat, and text. ' +
+      'For Discord guild channels, workspace is the guild id; for Slack team channels, workspace is ' +
+      'the team id (e.g. "T0ACME"). For DMs on either platform, workspace is the literal "@dm". ' +
+      'The runtime checks the channel allow rules before delivering — if the target chat is not in ' +
+      'the configured allow list, the call fails with { ok: false, error }. There is no auto-reply: ' +
+      'the only way for an agent to post is via this tool.',
+    parameters: Type.Object({
+      adapter: Type.Union(
+        ADAPTER_IDS.map((a) => Type.Literal(a)),
+        { description: 'Adapter id. Supported: "discord-bot", "slack-bot".' },
+      ),
+      workspace: Type.String({
+        description:
+          'Discord guild id or Slack team id (e.g. "T0ACME"); use "@dm" for direct-message channels on either platform.',
+        minLength: 1,
+      }),
+      chat: Type.String({
+        description:
+          'Channel id. Discord channel id (numeric snowflake) or Slack channel id (e.g. "C0CHANNEL", "D0DMID").',
+        minLength: 1,
+      }),
+      thread: Type.Optional(
+        Type.String({
+          description:
+            'Optional thread id. For Discord, the thread channel id. For Slack, the parent message thread_ts.',
+          minLength: 1,
+        }),
+      ),
+      text: Type.Optional(
+        Type.String({
+          description:
+            'The message body. Use Discord syntax `<@USER_ID>` for Discord mentions or Slack syntax `<@USER_ID>` for Slack mentions (Slack user ids start with "U"). Optional only when `attachments` is set; one of `text` or `attachments` must be present.',
+          minLength: 1,
+        }),
+      ),
+      attachments: Type.Optional(
+        Type.Array(
+          Type.Object({
+            path: Type.String({
+              description:
+                'Absolute path inside the agent container to the file to upload (e.g. "/agent/workspace/report.pdf"). The runtime reads the file just before the API call.',
+              minLength: 1,
+            }),
+            filename: Type.Optional(
+              Type.String({
+                description:
+                  'Filename to display in the chat. Defaults to the basename of `path`. Useful when the on-disk name carries a tempdir suffix the user should not see.',
+                minLength: 1,
+              }),
+            ),
+          }),
+          {
+            description:
+              "Optional files to upload alongside the text. Slack: `text` is sent as the first file's caption (single Slack message). Discord: each file is uploaded individually (no caption support upstream), then `text` is posted as a separate message; uploads land in the channel root even when `thread` is set.",
+            minItems: 1,
+          },
+        ),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const adapter = params.adapter as AdapterId
+      const bodyText = params.text
+      const attachments = params.attachments
+      if ((bodyText === undefined || bodyText === '') && (attachments === undefined || attachments.length === 0)) {
+        return {
+          content: [
+            { type: 'text' as const, text: 'channel_send denied: must provide `text`, `attachments`, or both.' },
+          ],
+          details: { ok: false, error: 'missing text and attachments' },
+        }
+      }
+
+      const noReplyError = noReplyMisuseError(bodyText)
+      if (noReplyError) {
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${noReplyError}` }],
+          details: { ok: false, error: noReplyError },
+        }
+      }
+
+      const result = await router.send({
+        adapter,
+        workspace: params.workspace,
+        chat: params.chat,
+        ...(params.thread !== undefined ? { thread: params.thread } : {}),
+        ...(bodyText !== undefined ? { text: bodyText } : {}),
+        ...(attachments !== undefined ? { attachments } : {}),
+      })
+
+      const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
+      const echo = renderOutboundEcho(bodyText, attachments)
+      const baseText = result.ok
+        ? `posted to ${params.adapter}:${params.workspace}/${params.chat}: ${echo}`
+        : `channel_send denied: ${result.error}`
+      const hints: string[] = []
+      if (result.ok) {
+        const consecutive = consecutiveSendHint(
+          router.getConsecutiveSendCount({
+            adapter,
+            workspace: params.workspace,
+            chat: params.chat,
+            thread: params.thread ?? null,
+          }),
+        )
+        if (consecutive) hints.push(consecutive)
+
+        const threadMismatch = threadMismatchHint(origin, {
+          adapter,
+          workspace: params.workspace,
+          chat: params.chat,
+          thread: params.thread,
+        })
+        if (threadMismatch) hints.push(threadMismatch)
+      }
+      const responseText = hints.length > 0 ? `${baseText} — ${hints.join(' ')}` : baseText
+      return {
+        content: [{ type: 'text' as const, text: responseText }],
+        details,
+      }
+    },
+  })
+}
+
+// Returns a behavioral hint when the model posted to the SAME conversation
+// as the session's origin (same adapter+workspace+chat) but DROPPED the
+// thread. This catches the "model forgot to copy thread verbatim" failure
+// mode without blocking legitimate intent — if leaving the thread was on
+// purpose ("새 스레드에서 시작하자"), the model can ignore this hint; if it
+// wasn't, the next channel_send (or channel_reply) can correct course.
+//
+// Only fires when the origin had a thread to begin with — channel-root
+// sessions can't have a "missing thread" problem.
+function threadMismatchHint(
+  origin: ChannelSendOrigin | undefined,
+  sent: { adapter: AdapterId; workspace: string; chat: string; thread: string | undefined },
+): string {
+  if (!origin) return ''
+  if (origin.thread === null) return ''
+  if (sent.thread !== undefined) return ''
+  if (origin.adapter !== sent.adapter) return ''
+  if (origin.workspace !== sent.workspace) return ''
+  if (origin.chat !== sent.chat) return ''
+  return (
+    `note: this session's origin thread is ${JSON.stringify(origin.thread)} but you posted to channel root. ` +
+    `if breaking out of the thread was intentional, ignore this; otherwise prefer \`channel_reply\` ` +
+    `or pass \`thread: ${JSON.stringify(origin.thread)}\` on your next channel_send.`
+  )
+}
+
+// Blocks a specific misuse: the model tried to send a silent-turn signal
+// (e.g. `NO_REPLY`, `(NO_REPLY)`) as a channel message. Those forms belong
+// in the model's *visible response* when no channel tool is called (see
+// session-origin.ts and router.ts validateChannelTurn), NOT in the body of
+// a sent message. We short-circuit BEFORE router.send so the signal never
+// reaches the chat. Detection delegates to `isNoReplySignal` so the router
+// and both tools stay in lockstep. Empty/undefined text is fine — that
+// means "attachments-only send", not a signal.
+function noReplyMisuseError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (text.trim() === '') return ''
+  if (!isNoReplySignal(text)) return ''
+  return (
+    '`NO_REPLY` is the silent-turn signal, not a message body. ' +
+    'To stay silent, end your turn with `NO_REPLY` as your entire visible response and NO channel tool call. ' +
+    'To send an actual reply, call this tool again with different text.'
+  )
+}
+
+// Returns a behavioral hint to nudge the model toward yielding when it has
+// been the only voice in the conversation for several messages. The router
+// increments its counter AFTER router.send returns, so a count of 1 means
+// "this is the second consecutive bot message in this chat:thread" — which
+// is the first count where a hint is warranted. Empty string at count <= 1
+// preserves the original tool-result text for the common single-reply case.
+function consecutiveSendHint(countAfterSend: number): string {
+  if (countAfterSend <= 1) return ''
+  if (countAfterSend === 2) {
+    return 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
+  }
+  return `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+}

package/src/agent/tools/ddg.ts

@@ -0,0 +1,218 @@
+// DDG's no-JS "lite" endpoint is the only major engine that serves a
+// parseable, key-free, registration-free SERP. We POST a query and parse the
+// resulting <table> markup.
+//
+// We target `lite.duckduckgo.com/lite/` rather than `html.duckduckgo.com/html/`
+// because `html` is gated by the interactive "duck picker" CAPTCHA after a
+// single bad fingerprint match. `lite` exists for non-browser clients (text
+// browsers, accessibility tools) and historically gates less aggressively —
+// but as of 2026 it ALSO fingerprints at the TLS layer (JA3/JA4) and the
+// HTTP/2 SETTINGS frame, well before any HTTP header is read. Bun's native
+// fetch cannot match Chrome's handshake (upstream issue #11368), so requests
+// from `fetch()` get gated regardless of headers, body shape, or pacing —
+// confirmed empirically over a multi-hour session against a single home IP
+// where real Chromium succeeded continuously while every fetch variant got
+// 202 anomaly-modal or HTTP-200-with-anomaly responses.
+//
+// The fix is to shell out to `curl-impersonate` (lexiforest fork), which
+// replays Chrome's exact TLS handshake + HTTP/2 settings + header ordering.
+// The binary is installed by the typeclaw Dockerfile (see
+// src/init/dockerfile.ts CURL_IMPERSONATE_* constants) at /usr/local/bin/
+// and invoked via the version-pinned wrapper `curl_chrome136`.
+//
+// Why no `-H` overrides: curl_chrome136 already sends the full Chrome 136
+// header set with correct ordering, sec-ch-ua values, etc. Adding our own
+// headers would corrupt the impersonation. The previous code's
+// BROWSER_HEADERS const has been removed for the same reason.
+
+import { spawn } from 'bun'
+
+const DDG_LITE_URL = 'https://lite.duckduckgo.com/lite/'
+const CURL_IMPERSONATE_BINARY = 'curl_chrome136'
+const REQUEST_TIMEOUT_SECONDS = 30
+
+let curlBinary = CURL_IMPERSONATE_BINARY
+
+// Test-only seam: lets ddg.test.ts and websearch.test.ts point the spawn
+// at a fake `curl_chrome136` script in a tmpdir so we exercise the real
+// Bun.spawn path without depending on a curl-impersonate install on the
+// test host. Production code never calls this — the const-import default
+// above is what production sees.
+export function _setCurlBinaryForTest(binary: string | null): void {
+  curlBinary = binary ?? CURL_IMPERSONATE_BINARY
+}
+
+export type DdgResult = {
+  title: string
+  url: string
+  snippet: string
+}
+
+export async function ddgSearch(query: string, limit: number, signal?: AbortSignal): Promise<DdgResult[]> {
+  const html = await fetchDdgHtml(query, signal)
+  if (isCaptcha(html)) {
+    throw new DdgCaptchaError()
+  }
+  return parseDdgHtml(html).slice(0, limit)
+}
+
+export class DdgCaptchaError extends Error {
+  constructor() {
+    super('DuckDuckGo returned a CAPTCHA page (rate-limited). Try again later or with a different query.')
+    this.name = 'DdgCaptchaError'
+  }
+}
+
+export async function fetchDdgHtml(query: string, signal?: AbortSignal): Promise<string> {
+  // Spawn detached so the child becomes the leader of its own process group.
+  // The curl-impersonate wrappers (curl_chrome136 et al.) are bash scripts
+  // that call the real curl-impersonate binary WITHOUT `exec` — meaning the
+  // wrapper is the parent and curl-impersonate is its child. On a plain
+  // SIGKILL to the wrapper PID, the curl child becomes orphaned and keeps
+  // the stdout pipe open until --max-time fires (30s default), turning a
+  // 50ms abort into a 30s hang. process.kill(-pid) addresses the negative
+  // PID, which signals the entire process group, killing both the wrapper
+  // and the inner curl atomically. detached: true is what makes the child
+  // the pgid leader so -pid is well-defined; without it, the child shares
+  // our pgid and we'd nuke our own process.
+  const proc = spawn({
+    cmd: [
+      curlBinary,
+      '--silent',
+      '--show-error',
+      '--fail-with-body',
+      '--compressed',
+      '--max-time',
+      String(REQUEST_TIMEOUT_SECONDS),
+      '-X',
+      'POST',
+      '--data-urlencode',
+      `q=${query}`,
+      DDG_LITE_URL,
+    ],
+    stdout: 'pipe',
+    stderr: 'pipe',
+    detached: true,
+  })
+
+  const onAbort = () => {
+    try {
+      process.kill(-proc.pid, 'SIGKILL')
+    } catch {
+      proc.kill('SIGKILL')
+    }
+  }
+  signal?.addEventListener('abort', onAbort, { once: true })
+
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    if (signal?.aborted) {
+      throw new Error('aborted')
+    }
+    if (exitCode !== 0) {
+      const detail = stderr.trim() || 'no stderr'
+      throw new Error(`curl-impersonate exited ${exitCode}: ${detail}`)
+    }
+    return stdout
+  } finally {
+    signal?.removeEventListener('abort', onAbort)
+  }
+}
+
+// The `lite` endpoint's CAPTCHA page is plainer than `html`'s anomaly-modal:
+// it returns either an HTTP error (caught above) or a "challenge-form" page
+// asking the user to verify they're human. We also keep the legacy anomaly
+// markers as a belt-and-suspenders check in case DDG ever unifies the flows.
+function isCaptcha(html: string): boolean {
+  return (
+    html.includes('challenge-form') ||
+    html.includes('Please verify you are a human') ||
+    html.includes('anomaly-modal') ||
+    html.includes('class="anomaly"')
+  )
+}
+
+// Parses the lite SERP HTML. Each result is a triplet of `<tr>` rows:
+//   1. <a class='result-link' href="…">Title</a>
+//   2. <td class='result-snippet'>snippet…</td>
+//   3. <span class='link-text'>display.url</span>
+// Rows 2 and 3 are sometimes absent (e.g. ad placements without snippets), so
+// we anchor on `result-link` and walk forward looking for the optional
+// snippet within a small window. Sponsored entries are wrapped in adjacent
+// rows that don't carry `result-link`, so they fall out naturally.
+export function parseDdgHtml(html: string): DdgResult[] {
+  const results: DdgResult[] = []
+  const linkRegex = /<a\s+[^>]*href=(['"])([^'"]+)\1[^>]*class=(['"])result-link\3[^>]*>([\s\S]*?)<\/a>/g
+  for (const match of html.matchAll(linkRegex)) {
+    const url = decodeDdgUrl(match[2] ?? '')
+    const title = stripHtml(match[4] ?? '').trim()
+    if (!url || !title) continue
+
+    const blockEnd = match.index !== undefined ? match.index + 2000 : html.length
+    const blockStart = match.index !== undefined ? match.index : 0
+    const window = html.slice(blockStart, blockEnd)
+    const snippetMatch = /<td\s+[^>]*class=(['"])result-snippet\1[^>]*>([\s\S]*?)<\/td>/.exec(window)
+    const snippet = snippetMatch ? stripHtml(snippetMatch[2] ?? '').trim() : ''
+
+    results.push({ title, url, snippet })
+  }
+  return results
+}
+
+// DDG sometimes wraps result URLs in a redirect like
+//   //duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2F&rut=...
+// Unwrap when present so the model sees the real destination.
+function decodeDdgUrl(href: string): string {
+  if (!href) return ''
+  const normalized = href.startsWith('//') ? `https:${href}` : href
+  try {
+    const parsed = new URL(normalized)
+    if (parsed.hostname.endsWith('duckduckgo.com') && parsed.pathname === '/l/') {
+      const inner = parsed.searchParams.get('uddg')
+      if (inner) return inner
+    }
+    return parsed.toString()
+  } catch {
+    return href
+  }
+}
+
+function stripHtml(input: string): string {
+  return decodeEntities(input.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ')
+}
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  mdash: '—',
+  ndash: '–',
+  hellip: '…',
+  laquo: '«',
+  raquo: '»',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+}
+
+function decodeEntities(input: string): string {
+  return input.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body: string) => {
+    if (body.startsWith('#x') || body.startsWith('#X')) {
+      const code = parseInt(body.slice(2), 16)
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole
+    }
+    if (body.startsWith('#')) {
+      const code = parseInt(body.slice(1), 10)
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole
+    }
+    return NAMED_ENTITIES[body] ?? whole
+  })
+}