typeclaw 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -49,6 +49,7 @@ import {
 } from './tool-result-budget'
 import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachment'
 import { createChannelHistoryTool } from './tools/channel-history'
+import { createChannelReactTool } from './tools/channel-react'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
 import { createGrantRoleTool } from './tools/grant-role'
@@ -532,6 +533,12 @@ export function buildChannelTools(
     tools.push(createChannelReplyTool({ router: channelRouter, origin: channelOrigin }))
     tools.push(createChannelHistoryTool({ router: channelRouter, origin: channelOrigin }))
     tools.push(createChannelSendTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(
+      createChannelReactTool({
+        router: channelRouter,
+        origin: { ...channelOrigin, ...(origin.reactionRef !== undefined ? { reactionRef: origin.reactionRef } : {}) },
+      }),
+    )
     tools.push(
       createChannelFetchAttachmentTool({
         router: channelRouter,

package/src/agent/live-subagents.ts

@@ -19,6 +19,10 @@ export type LiveSubagent = {
   sessionId: string
   subagentName: string
   parentSessionId?: string
+  // Role that resolved at spawn time, captured for the provenance cap on
+  // subagent_output/subagent_cancel. Absent when no permission service was
+  // active at spawn, in which case the cap fails closed.
+  spawnedByRole?: string
   startedAt: number
   status: SubagentStatus
   completion?: SubagentCompletion

package/src/agent/restart/index.ts

@@ -0,0 +1,101 @@
+import { basename } from 'node:path'
+
+import { writeRestartHandoff } from '@/agent/restart-handoff'
+import { send, sendHttp } from '@/hostd/client'
+import { containerSocketPath } from '@/hostd/paths'
+import type { Stream } from '@/stream'
+
+const ACK_TIMEOUT_MS = 5_000
+
+export type ContainerRestartingBroadcast = {
+  kind: 'container-restarting'
+  restartedAt: string
+  originatingSessionId: string
+}
+
+export type RequestContainerRestartOptions = {
+  containerName: string
+  build?: boolean
+  socketPath?: string
+  hostdUrl?: string
+  hostdToken?: string
+  ackTimeoutMs?: number
+  // When present together with originatingSessionId, the post-ACK
+  // container-restarting broadcast is published here so every live session's
+  // subscribeRestartNotice fans out the restart notice (originator gets
+  // typeclaw.restart-self, siblings get typeclaw.restart). Both the tool and
+  // the server /restart path route through this so the broadcast->handoff
+  // ordering lives in one place.
+  stream?: Stream
+  agentDir?: string
+  originatingSessionId?: string
+  originatingSessionFile?: string
+  restartedAt?: string
+}
+
+export type RequestContainerRestartResult =
+  | { ok: true; containerName: string; restartedAt: string }
+  | { ok: false; containerName: string; reason: string }
+
+export async function requestContainerRestart({
+  containerName,
+  build,
+  socketPath,
+  hostdUrl,
+  hostdToken,
+  ackTimeoutMs,
+  stream,
+  agentDir,
+  originatingSessionId,
+  originatingSessionFile,
+  restartedAt,
+}: RequestContainerRestartOptions): Promise<RequestContainerRestartResult> {
+  const request = { kind: 'restart' as const, containerName, build: build === true }
+  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
+  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
+  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
+  const reply =
+    httpUrl && httpToken
+      ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
+      : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
+
+  if (!reply.ok) return { ok: false, containerName, reason: reply.reason }
+
+  const restartTimestamp = restartedAt ?? new Date().toISOString()
+
+  // Fan out the restart notice to every live session BEFORE writing the handoff.
+  // The originating session's subscribeRestartNotice appends the
+  // typeclaw.restart-self entry synchronously (broker delivery + the JSONL
+  // append are both synchronous), so the handoff below points at a JSONL that
+  // already carries the "I'm back" instruction the rebooted container hydrates.
+  // Only after an accepted ACK, never on a failed/timed-out restart.
+  if (stream !== undefined && originatingSessionId !== undefined) {
+    const broadcast: ContainerRestartingBroadcast = {
+      kind: 'container-restarting',
+      restartedAt: restartTimestamp,
+      originatingSessionId,
+    }
+    stream.publish({ target: { kind: 'broadcast' }, payload: broadcast })
+  }
+
+  // Post-ACK: hostd has committed the restart, so a handoff-write failure must
+  // never demote it to a failure — that would render a false error in the TUI
+  // and swallow the accepted response. The handoff is a best-effort resume hint
+  // only; a missing one just cold-starts the rebooted container without the
+  // "I'm back" greeting. writeRestartHandoff swallows its own errors today, but
+  // guard here too so this contract survives the writer being changed later.
+  if (agentDir !== undefined && originatingSessionId !== undefined && originatingSessionFile !== undefined) {
+    try {
+      await writeRestartHandoff(agentDir, {
+        schemaVersion: 1,
+        restartedAt: restartTimestamp,
+        originatingSessionId,
+        originatingSessionFile: basename(originatingSessionFile),
+      })
+    } catch {
+      // intentional swallow — see the post-ACK rationale above
+    }
+  }
+
+  return { ok: true, containerName, restartedAt: restartTimestamp }
+}

package/src/agent/session-origin.ts

@@ -1,5 +1,6 @@
 import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
 import type { AdapterId } from '@/channels/schema'
+import type { ReactionRef } from '@/channels/types'
 
 export type ChannelParticipant = {
   authorId: string
@@ -38,6 +39,7 @@ export type SessionOrigin =
       chatName?: string
       thread: string | null
       lastInboundAuthorId?: string
+      reactionRef?: ReactionRef
       participants?: readonly ChannelParticipant[]
       membership?: MembershipCount
     }
@@ -301,6 +303,13 @@ function renderChannelOrigin(
       'audience: post the answer (or review summary) itself, never a status',
       'line about having posted it elsewhere. A narrated "Posted review result',
       'for PR #N: …" inside the PR is exactly the failure to avoid.',
+      '',
+      '**Do not post an "On it" acknowledgment comment.** The runtime already',
+      'adds an :eyes: reaction to the triggering item the moment it engages, so a',
+      'separate "looking into this" comment is redundant noise on the PR. If you',
+      'want to signal acknowledgment explicitly, use `channel_react({ emoji })`',
+      '(it reacts, it does not comment) — never a text ack. Reserve `channel_reply`',
+      'for the actual substantive answer.',
     )
   }
 
@@ -339,12 +348,21 @@ function renderChannelOrigin(
     '`channel_reply` call, not narration. This includes acks.',
     '',
     '**One substantive reply per inbound.** If the answer needs more than one',
-    'tool call, send a one-line ack first via `channel_reply({ text: "On it.",',
-    'continue: true })`, keep working, then send the answer with a final',
-    '`channel_reply`. The ack is not your reply; the answer is. Once the answer',
-    'lands, end your turn. The `continue: true` is not optional on that ack:',
-    'without it the turn ends the instant the ack lands and the rest of your',
-    'work — the fetch, the subagent, the actual answer — is silently dropped.',
+    ...(origin.adapter === 'github'
+      ? [
+          'tool call, keep working and post the answer with a single final',
+          '`channel_reply`. Do not post an "On it" ack comment first — the runtime',
+          'already added an :eyes: reaction on engage; use `channel_react` if you',
+          'want to acknowledge explicitly. The answer is your reply.',
+        ]
+      : [
+          'tool call, send a one-line ack first via `channel_reply({ text: "On it.",',
+          'continue: true })`, keep working, then send the answer with a final',
+          '`channel_reply`. The ack is not your reply; the answer is. Once the answer',
+          'lands, end your turn. The `continue: true` is not optional on that ack:',
+          'without it the turn ends the instant the ack lands and the rest of your',
+          'work — the fetch, the subagent, the actual answer — is silently dropped.',
+        ]),
     '',
     '**Backgrounded work does not end the obligation.** If you spawn a',
     'subagent with `run_in_background: true` to answer the current inbound,',
@@ -400,15 +418,19 @@ function renderMembershipSummary(
   if (membership === undefined) return null
 
   const total = membership.humans + membership.bots
+  // Exact Discord counts are channel-scoped (filtered by who can VIEW_CHANNEL),
+  // so the count is the channel's room, not the guild. The truncated branch is
+  // history-derived recent speakers, which is not a channel-membership claim,
+  // so the caveat would mislead there.
+  const isExact = !membership.truncated && now - membership.fetchedAt < MEMBERSHIP_FRESHNESS_MS
   const caveat =
-    origin.adapter === 'discord-bot' && origin.workspace !== '@dm'
-      ? ' (Note: this is the count of guild members; private channels with permission overwrites may have fewer actual viewers.)'
+    isExact && origin.adapter === 'discord-bot' && origin.workspace !== '@dm'
+      ? ' (This counts only members who can view this channel, not the whole guild.)'
       : ''
-  const isExact = !membership.truncated && now - membership.fetchedAt < MEMBERSHIP_FRESHNESS_MS
   if (isExact) {
     return `This channel has ${total} members: ${membership.humans} humans, ${membership.bots} bots.${caveat} The 10 most recent speakers are listed below.`
   }
-  return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap).${caveat} The 10 most recent speakers are listed below.`
+  return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap). The 10 most recent speakers are listed below.`
 }
 
 function renderMentionGuidance(

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

@@ -0,0 +1,79 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { ChannelRouter } from '@/channels/router'
+import type { AdapterId } from '@/channels/schema'
+import type { ReactionRef } from '@/channels/types'
+
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+import { TOOL_RESULT_PREFIX } from './channel-reply'
+
+export type ChannelReactOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+  reactionRef?: ReactionRef
+}
+
+export type CreateChannelReactToolOptions = {
+  router: ChannelRouter
+  origin: ChannelReactOrigin
+  logger?: ChannelToolLogger
+}
+
+export function createChannelReactTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelReactToolOptions) {
+  return defineTool({
+    name: 'channel_react',
+    label: 'Channel React',
+    description:
+      'Add an emoji reaction to the message that triggered this turn — a lightweight acknowledgment that does not post a comment. ' +
+      'On GitHub this reacts to the triggering issue/PR/comment (e.g. :eyes: to signal "I am looking at this"). ' +
+      'Use this instead of a textual "on it" reply when a reaction is enough. Pass the bare emoji name, no colons.',
+    parameters: Type.Object({
+      emoji: Type.String({
+        description: 'Bare emoji name, no surrounding colons. e.g. "eyes", "+1", "rocket", "heart".',
+        minLength: 1,
+      }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const deny = (error: string) => {
+        logger.warn(formatChannelToolFailure('channel_react', error))
+        const details: { ok: boolean; error?: string } = { ok: false, error }
+        return {
+          content: [{ type: 'text' as const, text: `${TOOL_RESULT_PREFIX}channel_react denied: ${error}` }],
+          details,
+        }
+      }
+
+      if (origin.reactionRef === undefined) return deny('this conversation has no message to react to')
+
+      const result = await router.react({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        reactionRef: origin.reactionRef,
+        emoji: params.emoji,
+      })
+
+      if (!result.ok) return deny(`${origin.adapter}:${origin.workspace}/${origin.chat}: ${result.error}`)
+
+      const details: { ok: boolean; error?: string } = { ok: true }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `${TOOL_RESULT_PREFIX}reacted with :${params.emoji}: on ${origin.adapter}:${origin.workspace}/${origin.chat}`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}

package/src/agent/tools/restart.ts

@@ -1,14 +1,9 @@
-import { basename } from 'node:path'
-
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { writeRestartHandoff } from '@/agent/restart-handoff'
-import { send, sendHttp } from '@/hostd/client'
-import { containerSocketPath } from '@/hostd/paths'
+import { requestContainerRestart } from '@/agent/restart'
 import type { Stream } from '@/stream'
 
-const ACK_TIMEOUT_MS = 5_000
 const EXIT_DELAY_MS = 500
 
 export type CreateRestartToolOptions = {
@@ -61,11 +56,7 @@ export type CreateRestartToolOptions = {
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
 
-export type ContainerRestartingBroadcast = {
-  kind: 'container-restarting'
-  restartedAt: string
-  originatingSessionId: string
-}
+export type { ContainerRestartingBroadcast } from '@/agent/restart'
 
 export function createRestartTool({
   containerName,
@@ -80,9 +71,6 @@ export function createRestartTool({
   originatingSessionFile,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
-  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
-  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
-  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
 
   return defineTool({
     name: 'restart',
@@ -109,49 +97,32 @@ export function createRestartTool({
     }),
     async execute(_toolCallId, params) {
       const build = params.build === true
-      const request = { kind: 'restart' as const, containerName, build }
-      const reply =
-        httpUrl && httpToken
-          ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
-          : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
-      if (!reply.ok) {
-        const details: RestartToolDetails = { ok: false, containerName, reason: reply.reason }
+      // requestContainerRestart owns the post-ACK broadcast->handoff ordering:
+      // on a successful ACK it publishes the container-restarting notice (which
+      // every live session's subscribeRestartNotice turns into a transcript
+      // entry) and then writes the handoff. Handoff fields are gated to TUI
+      // origins by the caller passing originatingSessionFile only for those —
+      // see issue #291's scoping concerns.
+      const result = await requestContainerRestart({
+        containerName,
+        build,
+        originatingSessionId,
+        ...(socketPath !== undefined ? { socketPath } : {}),
+        ...(hostdUrl !== undefined ? { hostdUrl } : {}),
+        ...(hostdToken !== undefined ? { hostdToken } : {}),
+        ...(ackTimeoutMs !== undefined ? { ackTimeoutMs } : {}),
+        ...(stream !== undefined ? { stream } : {}),
+        ...(agentDir !== undefined ? { agentDir } : {}),
+        ...(originatingSessionFile !== undefined ? { originatingSessionFile } : {}),
+      })
+      if (!result.ok) {
+        const details: RestartToolDetails = { ok: false, containerName, reason: result.reason }
         return {
-          content: [{ type: 'text' as const, text: `restart denied: ${reply.reason}` }],
+          content: [{ type: 'text' as const, text: `restart denied: ${result.reason}` }],
           details,
         }
       }
 
-      // Hostd ACK == restart is committed. Fan out the notice to every live
-      // session BEFORE arming the exit timer. Stream broker delivery is
-      // synchronous (broker.ts deliver()) and SessionManager.appendCustomMessageEntry
-      // does a synchronous JSONL write, so the fan-out completes inside this
-      // tick — well before the EXIT_DELAY_MS timer fires.
-      const restartedAt = new Date().toISOString()
-      const broadcast: ContainerRestartingBroadcast = {
-        kind: 'container-restarting',
-        restartedAt,
-        originatingSessionId,
-      }
-      stream?.publish({ target: { kind: 'broadcast' }, payload: broadcast })
-
-      // Write the cross-restart handoff AFTER the broadcast has run so the
-      // originating session's JSONL already contains the `typeclaw.restart-self`
-      // custom message entry that the next container will hydrate on
-      // `SessionManager.open`. Without that ordering, the new container could
-      // theoretically open the JSONL before the entry was flushed and miss
-      // the model-instruction the entry carries. Gated on agentDir +
-      // originatingSessionFile so non-TUI origins (channel/cron/subagent)
-      // skip the file write — see issue #291's scoping concerns.
-      if (agentDir !== undefined && originatingSessionFile !== undefined) {
-        await writeRestartHandoff(agentDir, {
-          schemaVersion: 1,
-          restartedAt,
-          originatingSessionId,
-          originatingSessionFile: basename(originatingSessionFile),
-        })
-      }
-
       // Schedule the exit on the next tick so the tool result is delivered to
       // the model before the process dies. The host daemon polls for the
       // container's removal before re-running `start`, so a small delay here

package/src/agent/tools/spawn-subagent.ts

@@ -129,6 +129,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         sessionId: resolvedHandle.sessionId ?? '<pending>',
         subagentName,
         parentSessionId,
+        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
         startedAt,
         status: 'running' as const,
         abort: resolvedHandle.abort,

package/src/agent/tools/subagent-access.ts

@@ -0,0 +1,67 @@
+import type { PermissionService } from '@/permissions'
+
+import type { LiveSubagent, LiveSubagentRegistry } from '../live-subagents'
+import type { SessionOrigin } from '../session-origin'
+
+export type SubagentAccessPermission = 'subagent.output' | 'subagent.cancel'
+
+export type SubagentAccessResult = { ok: true; live: LiveSubagent } | { ok: false; message: string }
+
+export type AuthorizeLiveSubagentAccessArgs = {
+  permissions: PermissionService | undefined
+  origin: SessionOrigin | undefined
+  liveRegistry: LiveSubagentRegistry
+  taskId: string
+  permission: SubagentAccessPermission
+}
+
+// Authorizes a single subagent_output/subagent_cancel call and resolves the
+// live entry in one place so the two tools cannot drift. Caps access to the
+// requester's role: the caller must hold the permission AND resolve to a role
+// at least as high as the role that spawned the subagent.
+//
+// The ordering closes an existence oracle: the task-independent base-permission
+// check runs BEFORE any registry lookup, and for non-owner callers an absent
+// task, a capped task, and a task with missing provenance all collapse to one
+// identical denial — so a lower-role caller cannot probe which task IDs are
+// live. Only `owner` (the trust root, which outranks every spawner) learns the
+// truthful `Unknown task_id` for a genuine miss. The cap fails closed.
+export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArgs): SubagentAccessResult {
+  const { permissions, origin, liveRegistry, taskId, permission } = args
+
+  if (permissions === undefined) {
+    const live = liveRegistry.get(taskId)
+    if (live === undefined) {
+      return { ok: false, message: `Unknown task_id: ${taskId}.` }
+    }
+    return { ok: true, live }
+  }
+
+  if (!permissions.has(origin, permission)) {
+    return { ok: false, message: `${permission} denied: insufficient permissions` }
+  }
+
+  const requesterRole = permissions.resolveRole(origin)
+  const accessAll = requesterRole === 'owner'
+  const opaqueDenial = `${permission} denied: unknown task_id or insufficient role`
+
+  const live = liveRegistry.get(taskId)
+  if (live === undefined) {
+    return { ok: false, message: accessAll ? `Unknown task_id: ${taskId}.` : opaqueDenial }
+  }
+  if (accessAll) {
+    return { ok: true, live }
+  }
+
+  const spawnedByRole = live.spawnedByRole
+  if (spawnedByRole === undefined) {
+    return { ok: false, message: opaqueDenial }
+  }
+
+  const cmp = permissions.compareRoleSeverity(requesterRole, spawnedByRole)
+  if (cmp === undefined || cmp < 0) {
+    return { ok: false, message: opaqueDenial }
+  }
+
+  return { ok: true, live }
+}

package/src/agent/tools/subagent-cancel.ts

@@ -5,6 +5,7 @@ import type { PermissionService } from '@/permissions'
 
 import type { LiveSubagentRegistry } from '../live-subagents'
 import type { SessionOrigin } from '../session-origin'
+import { authorizeLiveSubagentAccess } from './subagent-access'
 
 export type SubagentCancelToolDetails =
   | { ok: true; taskId: string; subagent: string; alreadyDone: boolean }
@@ -33,13 +34,17 @@ export function createSubagentCancelTool(options: CreateSubagentCancelToolOption
     }),
 
     async execute(_toolCallId, params): Promise<ToolReturn> {
-      if (permissions !== undefined && !permissions.has(getOrigin(), 'subagent.cancel')) {
-        return errorResult('subagent.cancel denied: insufficient permissions')
-      }
-      const live = liveRegistry.get(params.task_id)
-      if (live === undefined) {
-        return errorResult(`Unknown task_id: ${params.task_id}.`)
+      const access = authorizeLiveSubagentAccess({
+        permissions,
+        origin: getOrigin(),
+        liveRegistry,
+        taskId: params.task_id,
+        permission: 'subagent.cancel',
+      })
+      if (!access.ok) {
+        return errorResult(access.message)
       }
+      const live = access.live
       if (live.status !== 'running') {
         const details: SubagentCancelToolDetails = {
           ok: true,

package/src/agent/tools/subagent-output.ts

@@ -5,6 +5,7 @@ import type { PermissionService } from '@/permissions'
 
 import type { LiveSubagentRegistry, StatusSnapshot, SubagentProgressEvent } from '../live-subagents'
 import type { SessionOrigin } from '../session-origin'
+import { authorizeLiveSubagentAccess } from './subagent-access'
 
 export type SubagentOutputToolDetails =
   | {
@@ -64,8 +65,15 @@ export function createSubagentOutputTool(options: CreateSubagentOutputToolOption
     }),
 
     async execute(_toolCallId, params) {
-      if (permissions !== undefined && !permissions.has(getOrigin(), 'subagent.output')) {
-        return errorResult('subagent.output denied: insufficient permissions')
+      const access = authorizeLiveSubagentAccess({
+        permissions,
+        origin: getOrigin(),
+        liveRegistry,
+        taskId: params.task_id,
+        permission: 'subagent.output',
+      })
+      if (!access.ok) {
+        return errorResult(access.message)
       }
       const snap = liveRegistry.snapshot(params.task_id, now())
       if (snap === undefined) {

package/src/channels/adapters/discord-bot-classify.ts

@@ -141,7 +141,13 @@ function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {
   return { text, attachments }
 }
 
-function describeDiscordMedia(event: DiscordGatewayMessageCreateEvent): InboundAttachment[] {
+export type DiscordMediaCarrier = {
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
+}
+
+export function describeDiscordMedia(event: DiscordMediaCarrier): InboundAttachment[] {
   return [
     ...(event.attachments ?? []).map(describeAttachment),
     ...(event.embeds ?? []).map(describeEmbed),
@@ -167,7 +173,7 @@ function describeSticker(sticker: DiscordGatewayStickerItem): Omit<InboundAttach
   return { kind: 'sticker', ref: '', filename: sticker.name }
 }
 
-function renderPlaceholder(attachment: InboundAttachment): string {
+export function renderPlaceholder(attachment: InboundAttachment): string {
   const parts: string[] = [`Discord attachment #${attachment.id}: ${attachment.kind}`]
   if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
   if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)