typeclaw 0.1.0

package/src/agent/plugin-tools.ts

@@ -0,0 +1,269 @@
+import type { AgentTool } from '@mariozechner/pi-agent-core'
+import {
+  bashTool as piBashTool,
+  defineTool as piDefineTool,
+  editTool as piEditTool,
+  findTool as piFindTool,
+  grepTool as piGrepTool,
+  lsTool as piLsTool,
+  readTool as piReadTool,
+  writeTool as piWriteTool,
+} from '@mariozechner/pi-coding-agent'
+import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
+import type { Static, TSchema } from '@sinclair/typebox'
+import { Type } from '@sinclair/typebox'
+import { z } from 'zod'
+
+import {
+  ACKNOWLEDGE_GUARDS,
+  checkNonWorkspaceWriteGuard,
+  checkSkillAuthoringGuard,
+} from '@/bundled-plugins/guard/policy'
+import type {
+  BuiltinToolRef,
+  ContentPart,
+  HookBus,
+  PluginLogger,
+  Tool,
+  ToolBeforeEvent,
+  ToolContext,
+  ToolResult,
+} from '@/plugin'
+
+type AnyAgentTool =
+  | typeof piReadTool
+  | typeof piBashTool
+  | typeof piEditTool
+  | typeof piWriteTool
+  | typeof piGrepTool
+  | typeof piFindTool
+  | typeof piLsTool
+
+const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
+  Type.Object(
+    {
+      nonWorkspaceWrite: Type.Optional(Type.Boolean()),
+    },
+    { additionalProperties: false },
+  ),
+)
+
+const BUILTIN_TOOL_MAP: Record<string, AnyAgentTool> = {
+  bash: piBashTool,
+  edit: piEditTool,
+  find: piFindTool,
+  grep: piGrepTool,
+  ls: piLsTool,
+  read: piReadTool,
+  write: piWriteTool,
+}
+
+export function resolveBuiltinToolRefs(refs: BuiltinToolRef[]): AnyAgentTool[] {
+  return refs.map((ref) => {
+    const tool = BUILTIN_TOOL_MAP[ref.__builtinTool]
+    if (!tool) throw new Error(`unknown built-in tool ref: ${ref.__builtinTool}`)
+    return tool
+  })
+}
+
+export type WrapToolOptions = {
+  pluginName: string
+  toolName: string
+  agentDir: string
+  sessionId: string
+  logger: PluginLogger
+  hooks: HookBus
+}
+
+export type WrapSystemToolOptions = {
+  agentDir: string
+  sessionId: string
+  hooks: HookBus
+}
+
+export function zodToToolParameters(schema: z.ZodType<unknown>): TSchema {
+  const json = z.toJSONSchema(schema, { io: 'input', reused: 'inline' })
+  return json as unknown as TSchema
+}
+
+export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefinition {
+  const parameters = zodToToolParameters(tool.parameters)
+
+  return piDefineTool({
+    name: opts.toolName,
+    label: opts.toolName,
+    description: tool.description,
+    parameters,
+    async execute(toolCallId, params, signal) {
+      const validated = tool.parameters.safeParse(params)
+      if (!validated.success) {
+        return errorResult(`invalid arguments: ${validated.error.message}`)
+      }
+
+      const mutableArgs = validated.data as Record<string, unknown>
+      const before: ToolBeforeEvent = {
+        tool: opts.toolName,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        args: mutableArgs,
+      }
+      const blockResult = await opts.hooks.runToolBefore(before)
+      if (blockResult !== undefined) {
+        return errorResult(`blocked: ${blockResult.reason}`)
+      }
+
+      const toolCtx: ToolContext = {
+        signal,
+        sessionId: opts.sessionId,
+        agentDir: opts.agentDir,
+        logger: opts.logger,
+      }
+
+      let result: ToolResult
+      try {
+        result = await tool.execute(before.args, toolCtx)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        return errorResult(message)
+      }
+
+      await opts.hooks.runToolAfter({
+        tool: opts.toolName,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        result,
+      })
+
+      return {
+        content: result.content as ContentPart[],
+        details: result.details,
+      }
+    },
+  })
+}
+
+export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(
+  tool: ToolDefinition<TParams, TDetails, TState>,
+  opts: WrapSystemToolOptions,
+): ToolDefinition<TParams, TDetails, TState> {
+  return piDefineTool({
+    ...tool,
+    parameters: withGuardAcknowledgements(tool.name, tool.parameters),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const mutableArgs = params as Record<string, unknown>
+      const blockResult = await opts.hooks.runToolBefore({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        args: mutableArgs,
+      })
+      if (blockResult !== undefined) {
+        throw new Error(`blocked: ${blockResult.reason}`)
+      }
+      const guardResult = await runFinalWriteGuards({
+        tool: tool.name,
+        args: mutableArgs,
+        agentDir: opts.agentDir,
+      })
+      if (guardResult !== undefined) {
+        throw new Error(`blocked: ${guardResult.reason}`)
+      }
+      stripGuardAcknowledgements(mutableArgs)
+
+      const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate, ctx)
+      const hookResult: ToolResult = {
+        content: result.content as ContentPart[],
+        details: result.details,
+      }
+      await opts.hooks.runToolAfter({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        result: hookResult,
+      })
+      return {
+        content: hookResult.content,
+        details: hookResult.details as TDetails,
+      }
+    },
+  })
+}
+
+export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>(
+  tool: AgentTool<TParams, TDetails>,
+  opts: WrapSystemToolOptions,
+): AgentTool<TParams, TDetails> {
+  return {
+    ...tool,
+    parameters: withGuardAcknowledgements(tool.name, tool.parameters),
+    async execute(toolCallId, params, signal, onUpdate) {
+      const mutableArgs = params as Record<string, unknown>
+      const blockResult = await opts.hooks.runToolBefore({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        args: mutableArgs,
+      })
+      if (blockResult !== undefined) {
+        throw new Error(`blocked: ${blockResult.reason}`)
+      }
+      const guardResult = await runFinalWriteGuards({
+        tool: tool.name,
+        args: mutableArgs,
+        agentDir: opts.agentDir,
+      })
+      if (guardResult !== undefined) {
+        throw new Error(`blocked: ${guardResult.reason}`)
+      }
+      stripGuardAcknowledgements(mutableArgs)
+
+      const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
+      const hookResult: ToolResult = {
+        content: result.content as ContentPart[],
+        details: result.details,
+      }
+      await opts.hooks.runToolAfter({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        result: hookResult,
+      })
+      return {
+        content: hookResult.content,
+        details: hookResult.details as TDetails,
+      }
+    },
+  }
+}
+
+function errorResult(message: string) {
+  return {
+    content: [{ type: 'text' as const, text: message }],
+    details: { error: true, message },
+    isError: true,
+  }
+}
+
+async function runFinalWriteGuards(options: { tool: string; args: Record<string, unknown>; agentDir: string }) {
+  return (await checkSkillAuthoringGuard(options)) ?? checkNonWorkspaceWriteGuard(options)
+}
+
+function withGuardAcknowledgements<TParams extends TSchema>(toolName: string, parameters: TParams): TParams {
+  if (toolName !== 'write' && toolName !== 'edit') return parameters
+
+  const schema = parameters as Record<string, unknown>
+  const properties = schema.properties
+  if (!properties || typeof properties !== 'object' || Array.isArray(properties)) return parameters
+
+  return {
+    ...schema,
+    properties: {
+      ...(properties as Record<string, unknown>),
+      [ACKNOWLEDGE_GUARDS]: ACKNOWLEDGE_GUARDS_SCHEMA,
+    },
+  } as unknown as TParams
+}
+
+function stripGuardAcknowledgements(args: Record<string, unknown>): void {
+  delete args[ACKNOWLEDGE_GUARDS]
+}

package/src/agent/reload-tool.ts

@@ -0,0 +1,71 @@
+import { defineTool } from '@mariozechner/pi-coding-agent'
+import { Type } from '@sinclair/typebox'
+
+import type { ReloadRegistry, ReloadResult } from '@/reload'
+
+export type CreateReloadToolOptions = {
+  registry: ReloadRegistry
+}
+
+export function createReloadTool({ registry }: CreateReloadToolOptions) {
+  return defineTool({
+    name: 'reload',
+    label: 'Reload',
+    description:
+      'Reload typeclaw subsystems whose on-disk source has changed. Each reloadable is ' +
+      'all-or-nothing: invalid input leaves its live state unchanged and the failure reason is ' +
+      "reported in that scope's result. Boot-only config fields (port, mounts, memory.idleMs) " +
+      'are reported as restart-required. Safe to call any time. ' +
+      'Without a scope arg, runs every registered reloadable in registration order so later ' +
+      'scopes observe earlier swaps (e.g. cron sees a freshly-loaded plugins registry). ' +
+      'With a scope arg, runs only that one reloadable.',
+    parameters: Type.Object({
+      scope: Type.Optional(
+        Type.String({
+          description:
+            'Optional reload scope name. Common scopes: "config" (typeclaw.json), ' +
+            '"plugins" (re-resolve and re-run plugin factories), "skills" (read-only diagnostic ' +
+            'reporting which skills are visible to a new session), "cron" (cron.json). ' +
+            'Omit to reload all scopes.',
+        }),
+      ),
+    }),
+    execute: async (_id, args) => {
+      const items = registry.list()
+      if (items.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'nothing to reload (no reloadable subsystems registered)' }],
+          details: { results: [] },
+        }
+      }
+
+      const scope = (args as { scope?: string }).scope
+      if (scope !== undefined && scope.length > 0) {
+        const result = await registry.reloadOne(scope)
+        return {
+          content: [{ type: 'text', text: formatResults([result]) }],
+          details: { results: [result] },
+        }
+      }
+
+      const { results } = await registry.reloadAll()
+      return {
+        content: [{ type: 'text', text: formatResults(results) }],
+        details: { results },
+      }
+    },
+  })
+}
+
+function formatResults(results: ReloadResult[]): string {
+  const lines = results.map((r) => {
+    if (r.ok) return `[${r.scope}] ok: ${r.summary}`
+    return `[${r.scope}] failed: ${r.reason}`
+  })
+  const failedCount = results.filter((r) => !r.ok).length
+  const header =
+    failedCount === 0
+      ? `Reloaded ${results.length} subsystem(s).`
+      : `Reloaded ${results.length} subsystem(s); ${failedCount} failed.`
+  return [header, ...lines].join('\n')
+}

package/src/agent/self.ts

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const MAX_FILE_BYTES = 12 * 1024
+
+const SOUL_FRAMING =
+  'If SOUL.md has content below, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.'
+
+type FileEntry = {
+  name: string
+  path: string
+  content: string | null
+}
+
+export async function loadSelf(agentDir: string): Promise<string> {
+  const entries = await Promise.all([readEntry(agentDir, 'IDENTITY.md'), readEntry(agentDir, 'SOUL.md')])
+  return renderSection(entries)
+}
+
+async function readEntry(agentDir: string, name: string): Promise<FileEntry> {
+  const filePath = join(agentDir, name)
+  try {
+    const raw = await readFile(filePath, 'utf8')
+    const trimmed = raw.length > MAX_FILE_BYTES ? `${raw.slice(0, MAX_FILE_BYTES)}\n\n[truncated]` : raw
+    return { name, path: filePath, content: trimmed }
+  } catch {
+    return { name, path: filePath, content: null }
+  }
+}
+
+function renderSection(entries: FileEntry[]): string {
+  const lines = ['# Identity', '', SOUL_FRAMING, '']
+  for (const entry of entries) {
+    lines.push(`## ${entry.name}`, '')
+    if (entry.content === null) {
+      lines.push(`[MISSING] Expected at: ${entry.path}`)
+    } else if (entry.content.trim() === '') {
+      lines.push(`[EMPTY] Present at ${entry.path} but has no content yet.`)
+    } else {
+      lines.push(entry.content.trimEnd())
+    }
+    lines.push('')
+  }
+  return lines.join('\n').trimEnd()
+}

package/src/agent/session-origin.ts

@@ -0,0 +1,288 @@
+import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
+import type { AdapterId } from '@/channels/schema'
+
+export type ChannelParticipant = {
+  authorId: string
+  authorName: string
+  firstMessageAt: number
+  lastMessageAt: number
+  messageCount: number
+  // Optional with default false so persisted records from prior versions
+  // load cleanly. The solo-human engagement fallback in `decideEngagement`
+  // counts only `!isBot` participants, so a missing flag must read as
+  // human (current behavior) — never as bot (would silently disable the
+  // fallback for legacy channels).
+  isBot?: boolean
+}
+
+export type ChannelOriginContext = {
+  lastInboundAuthorId?: string
+  participants?: readonly ChannelParticipant[]
+}
+
+export type SessionOrigin =
+  | { kind: 'tui'; sessionId: string }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | {
+      kind: 'channel'
+      adapter: AdapterId
+      workspace: string
+      workspaceName?: string
+      chat: string
+      chatName?: string
+      thread: string | null
+      lastInboundAuthorId?: string
+      participants?: readonly ChannelParticipant[]
+      membership?: MembershipCount
+    }
+  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+
+export const PARTICIPANTS_TOP_K = 10
+export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+export function renderSessionOrigin(origin: SessionOrigin, now: number = Date.now()): string {
+  switch (origin.kind) {
+    case 'tui':
+      return renderTuiOrigin()
+    case 'cron':
+      return renderCronOrigin(origin)
+    case 'channel':
+      return renderChannelOrigin(origin, now)
+    case 'subagent':
+      return renderSubagentOrigin(origin)
+  }
+}
+
+function renderTuiOrigin(): string {
+  return [
+    '## Session origin',
+    '',
+    'You are running in the TUI session that the operator is currently',
+    'attached to. Verbose explanations are welcome. The operator can see',
+    'your tool calls and outputs in real time.',
+  ].join('\n')
+}
+
+function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }): string {
+  return [
+    '## Session origin',
+    '',
+    'You are running an unattended cron job.',
+    '',
+    `- Job ID:   \`${origin.jobId}\``,
+    `- Job kind: ${origin.jobKind}`,
+    '',
+    'No human is watching this turn. Produce side effects (e.g. via',
+    '`channel_send`) where appropriate. Do not ask clarifying questions —',
+    "the prompt has everything you should need. If you can't proceed, log",
+    'your blockers and exit.',
+  ].join('\n')
+}
+
+function renderSubagentOrigin(origin: { subagent: string; parentSessionId: string }): string {
+  return [
+    '## Session origin',
+    '',
+    `You are a \`${origin.subagent}\` subagent spawned by parent session`,
+    `\`${origin.parentSessionId}\`. Stay narrowly within the task you were given.`,
+    'Return cleanly when done; do not sprawl into unrelated work.',
+  ].join('\n')
+}
+
+function renderChannelOrigin(
+  origin: {
+    adapter: AdapterId
+    workspace: string
+    workspaceName?: string
+    chat: string
+    chatName?: string
+    thread: string | null
+    participants?: readonly ChannelParticipant[]
+    membership?: MembershipCount
+  },
+  now: number,
+): string {
+  // The OBLIGATION-not-permission framing here exists because Kimi K2.5 Turbo
+  // (and likely other models) will otherwise treat short / casual messages as
+  // "ambient observation" and emit no tool call. Plain-text output from the
+  // agent in a channel session is dead text — there is no human attached to
+  // a stdout to read it. The only way to talk to the user is the tool. Making
+  // that obligation crisp and pre-filling the addressing fields removed a
+  // class of "model finishes silently, no reply ever lands" failures that we
+  // could only see in the logs as `prompted` followed by no `outbound`.
+  //
+  // The original wording told the model to call channel_send and copy
+  // adapter/workspace/chat/thread verbatim. Models still routinely dropped
+  // `thread`, so the same conversation got bisected into a fresh top-level
+  // thread on Slack. channel_reply now exists for that reason: it takes
+  // only `text` and pulls addressing from this origin. We point the model at
+  // it as the default, and keep channel_send as the escape hatch for posting
+  // elsewhere (different chat, breaking out of the thread on purpose, etc.).
+  const platform = origin.adapter === 'slack-bot' ? 'Slack' : 'Discord'
+  const lines: string[] = [
+    '## Session origin',
+    '',
+    `You are responding inside a ${platform} channel session. There is no human`,
+    'attached to a console here — your only way to communicate with the user',
+    'is a tool call. Plain-text output is invisible.',
+  ]
+
+  const conversationLine = renderConversationLine(origin)
+  if (conversationLine !== null) lines.push('', conversationLine)
+
+  lines.push(
+    '',
+    '**For every user message in this session, you MUST call `channel_reply`',
+    '(or `channel_send`) at least once before ending your turn**, unless the',
+    'user explicitly told you to stay silent. If you intentionally do not',
+    'reply, your entire final visible response must be exactly `NO_REPLY`.',
+    'Any other visible text without a channel tool call is blocked.',
+    '',
+    'To reply in this conversation, call `channel_reply({ text })`. Addressing',
+    `is filled in from this session, including the thread${origin.thread !== null ? '' : ' (none here — this is a channel-root session)'}, so you don't`,
+    'need to copy any of these fields:',
+    '',
+    '```json',
+    '{',
+    `  "adapter": ${JSON.stringify(origin.adapter)},`,
+    `  "workspace": ${JSON.stringify(origin.workspace)},`,
+    `  "chat": ${JSON.stringify(origin.chat)},`,
+    origin.thread !== null ? `  "thread": ${JSON.stringify(origin.thread)}` : '  "thread": null',
+    '}',
+    '```',
+    '',
+    'To post somewhere else (different chat, break out of the current',
+    'thread on purpose, send a DM from this channel session, etc.), use',
+    '`channel_send` and pass the addressing fields explicitly. Only chats',
+    "matching the channel's `allow` rules are accepted (the tool returns",
+    '`{ ok: false }` otherwise).',
+    '',
+    `To mention someone in your reply, use ${platform} syntax \`<@USER_ID>\`.`,
+    ...renderMentionExample(origin.participants ?? [], platform, now),
+  )
+
+  const participantsBlock = renderParticipants(origin.participants ?? [], now)
+  const membershipLine = renderMembershipSummary(origin, now)
+  if (membershipLine !== null) lines.push('', membershipLine)
+  if (participantsBlock) lines.push('', participantsBlock)
+
+  lines.push('', 'Be concise; chat clients punish multi-paragraph replies.')
+  return lines.join('\n')
+}
+
+function renderMembershipSummary(
+  origin: { adapter: AdapterId; workspace: string; membership?: MembershipCount },
+  now: number,
+): string | null {
+  const membership = origin.membership
+  if (membership === undefined) return null
+
+  const total = membership.humans + membership.bots
+  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.)'
+      : ''
+  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.`
+}
+
+function renderMentionExample(
+  participants: readonly ChannelParticipant[],
+  platform: 'Discord' | 'Slack',
+  now: number,
+): string[] {
+  // Concrete worked example anchored on a REAL participant when possible.
+  // Models reliably copy concrete examples; abstract `<@USER_ID>` placeholders
+  // get treated as generic instructions and ignored. Prefer a peer bot for
+  // the example because that's the addressing case where plain-text names
+  // silently fail (the human path is forgiving — humans see their name and
+  // respond regardless of mention syntax). Fall back to any non-self
+  // participant, then to a generic placeholder if the channel is brand new.
+  //
+  // Apply the SAME staleness cutoff as `renderParticipants` so we never name
+  // someone in the example who isn't shown in the participants block — that
+  // would surface a "ghost" name from >7d ago and confuse the model about
+  // who is actually around.
+  const cutoff = now - PARTICIPANTS_MAX_AGE_MS
+  const fresh = [...participants]
+    .filter((p) => p.lastMessageAt >= cutoff)
+    .sort((a, b) => b.lastMessageAt - a.lastMessageAt)
+  const peerBot = fresh.find((p) => p.isBot === true)
+  const anyPeer = peerBot ?? fresh[0]
+  const exampleId = anyPeer?.authorId ?? '123456789'
+  const exampleName = anyPeer?.authorName ?? 'PeerBot'
+  return [
+    `For example, to address ${exampleName} in this conversation, write \`<@${exampleId}> hello\` —`,
+    `**not** "${exampleName} hello". Plain-text names do not notify the recipient on ${platform},`,
+    'and other bots in this channel will not see the message as addressed to them.',
+  ]
+}
+
+function renderConversationLine(origin: {
+  adapter: AdapterId
+  workspace: string
+  workspaceName?: string
+  chat: string
+  chatName?: string
+}): string | null {
+  const hasChat = origin.chatName !== undefined && origin.chatName !== ''
+  const hasWorkspace = origin.workspaceName !== undefined && origin.workspaceName !== ''
+  if (!hasChat && !hasWorkspace) return null
+
+  const chatPrefix = origin.adapter === 'slack-bot' ? '#' : ''
+  const chatLabel = hasChat ? `**${chatPrefix}${origin.chatName!}** (${origin.chat})` : `\`${origin.chat}\``
+  const workspaceLabel = hasWorkspace ? `**${origin.workspaceName!}** (${origin.workspace})` : `\`${origin.workspace}\``
+
+  return `Conversation: ${chatLabel} in ${workspaceLabel}.`
+}
+
+function renderParticipants(participants: readonly ChannelParticipant[], now: number): string {
+  const cutoff = now - PARTICIPANTS_MAX_AGE_MS
+  const fresh = participants.filter((p) => p.lastMessageAt >= cutoff)
+  if (fresh.length === 0) return ''
+
+  const top = [...fresh].sort((a, b) => b.lastMessageAt - a.lastMessageAt).slice(0, PARTICIPANTS_TOP_K)
+
+  // Format flipped from `name (id: 123)` to `<@123> (name)` so the model sees
+  // the SAME shape it will need to emit when addressing someone — copy-paste
+  // the leading `<@id>` token verbatim. The previous format presented the
+  // human-readable name first and the ID parenthetically, which (combined
+  // with `<@id> (name) [bot]:` in inbound message lines) trained the model
+  // to treat `<@id>` as Discord's render-time decoration rather than syntax
+  // it must produce. Symptom in the wild: 돌쇠 addressing Winky as "Winky님"
+  // (plain text), which never trips Winky's `isBotMention` check, so Winky
+  // observes silently and the conversation stalls.
+  const lines = ['## Recent participants (last 7 days, top 10 by recency)', '']
+  for (const p of top) {
+    const ago = formatAgo(now - p.lastMessageAt)
+    lines.push(`- <@${p.authorId}> (${p.authorName}) — last message: ${ago}, total: ${p.messageCount}`)
+  }
+  lines.push(
+    '',
+    'This list is **bounded** — it shows only the 10 most recently active',
+    'authors in this conversation, all of whom have posted in the last 7',
+    'days. Older or less recent authors are not shown even if they exist.',
+    'This is **not** the full guild member list, and **not** an audit log',
+    'of everyone who ever spoke here.',
+    '',
+    "If a sender in the current turn isn't in the list, you can still",
+    'address them — `<@authorId>` works for any author you have seen,',
+    'even once. The list is a convenience for "who\'s been around lately,"',
+    'not an exhaustive directory.',
+  )
+  return lines.join('\n')
+}
+
+function formatAgo(ms: number): string {
+  const sec = Math.max(0, Math.round(ms / 1000))
+  if (sec < 60) return `${sec} seconds ago`
+  const min = Math.round(sec / 60)
+  if (min < 60) return `${min} minute${min === 1 ? '' : 's'} ago`
+  const hr = Math.round(min / 60)
+  if (hr < 48) return `${hr} hour${hr === 1 ? '' : 's'} ago`
+  const days = Math.round(hr / 24)
+  return `${days} day${days === 1 ? '' : 's'} ago`
+}