typeclaw 0.1.4 → 0.1.6

package/src/agent/multimodal/looker.ts

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { extname, isAbsolute } from 'node:path'
+
+import { z } from 'zod'
+
+const SUPPORTED_MIME_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+} as const
+
+// Caps on URL-fetched images. The agent chooses URLs autonomously, so a
+// malicious or accidentally-large response could otherwise hang the tool
+// (no timeout) or fill memory (no size cap). 20 MB is well above any
+// reasonable screenshot/photo and well below container memory budgets;
+// 30 s is generous for a single HTTP image fetch over a slow link.
+export const URL_FETCH_TIMEOUT_MS = 30_000
+export const URL_FETCH_MAX_BYTES = 20 * 1024 * 1024
+
+type Mime = (typeof SUPPORTED_MIME_TYPES)[keyof typeof SUPPORTED_MIME_TYPES]
+
+export type ImageInput =
+  | { kind: 'url'; url: string }
+  | { kind: 'file'; path: string }
+  | { kind: 'base64'; data: string; mimeType: string }
+
+export const imageInputSchema = z.union([
+  z.object({ kind: z.literal('url'), url: z.string().url() }),
+  z.object({ kind: z.literal('file'), path: z.string().min(1) }),
+  z.object({ kind: z.literal('base64'), data: z.string().min(1), mimeType: z.string().min(1) }),
+])
+
+export const multimodalLookerPayloadSchema = z.object({
+  images: z.array(imageInputSchema).min(1),
+  prompt: z.string().min(1).optional(),
+})
+
+export type MultimodalLookerPayload = z.infer<typeof multimodalLookerPayloadSchema>
+
+// System prompt is built per-invocation so the agent sees the exact task. With
+// `prompt`: focused Q&A. Without: open-ended description. Tone the same in
+// both branches so callers can plug either form into the same downstream
+// pipeline (the look_at tool just relays the resulting text).
+export function buildMultimodalLookerSystemPrompt(prompt: string | undefined): string {
+  const base =
+    'You are a multimodal vision subagent. The user message contains one or more images attached to a short instruction.'
+  if (prompt !== undefined && prompt.trim() !== '') {
+    return [
+      base,
+      '',
+      'Your job is to ANSWER the question below using ONLY what is visible in the attached image(s). Be precise, concrete, and faithful to the visual content. If the image does not contain enough information to answer, say so explicitly.',
+      '',
+      `Question: ${prompt.trim()}`,
+      '',
+      'Reply with the answer directly. No preamble, no acknowledgement of the task, no markdown headings.',
+    ].join('\n')
+  }
+  return [
+    base,
+    '',
+    "Your job is to DESCRIBE the attached image(s) faithfully and in detail. Cover: subject(s), composition, colors, text content (transcribed verbatim if legible), notable visual details, and anything that would help a downstream reader who cannot see the image. Do not speculate beyond what's visible.",
+    '',
+    'Reply with the description directly. No preamble, no markdown headings, no bullet list unless multiple images.',
+  ].join('\n')
+}
+
+export type ResolvedImage = {
+  data: string
+  mimeType: string
+}
+
+// Materializes an ImageInput into the base64-encoded form pi-ai expects.
+// - `url`: passthrough; pi-ai's image content does not accept URLs, so we fetch
+//   the bytes and base64-encode here (lazy; only when the tool is invoked).
+// - `file`: read from disk, infer MIME from extension. Path must be absolute or
+//   resolvable against the caller's cwd (callers should normalize ahead of
+//   time; this function rejects relative paths to avoid ambiguity).
+// - `base64`: passthrough.
+export async function resolveImage(input: ImageInput, signal?: AbortSignal): Promise<ResolvedImage> {
+  if (input.kind === 'base64') {
+    if (!input.mimeType.startsWith('image/')) {
+      throw new Error(`look_at: base64 mimeType must be image/* (got "${input.mimeType}")`)
+    }
+    return { data: input.data, mimeType: input.mimeType }
+  }
+  if (input.kind === 'file') {
+    if (!isAbsolute(input.path)) {
+      throw new Error(`look_at: file path must be absolute (got "${input.path}")`)
+    }
+    if (!existsSync(input.path)) {
+      throw new Error(`look_at: file not found at ${input.path}`)
+    }
+    const ext = extname(input.path).toLowerCase() as keyof typeof SUPPORTED_MIME_TYPES
+    const mimeType = (SUPPORTED_MIME_TYPES[ext] ?? null) as Mime | null
+    if (mimeType === null) {
+      throw new Error(
+        `look_at: unsupported image extension "${ext}" for ${input.path} (supported: ${Object.keys(SUPPORTED_MIME_TYPES).join(', ')})`,
+      )
+    }
+    const bytes = readFileSync(input.path)
+    return { data: bytes.toString('base64'), mimeType }
+  }
+  // URL branch: independent timeout + size cap on top of any caller-provided
+  // signal. The two abort signals are merged so the tool's overall abort wins
+  // over our timeout AND vice versa.
+  const timeoutSignal = AbortSignal.timeout(URL_FETCH_TIMEOUT_MS)
+  const mergedSignal = signal !== undefined ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal
+  const res = await fetch(input.url, { signal: mergedSignal })
+  if (!res.ok) {
+    throw new Error(`look_at: failed to fetch ${input.url}: HTTP ${res.status}`)
+  }
+  const mimeType = res.headers.get('content-type')?.split(';')[0]?.trim() ?? 'application/octet-stream'
+  if (!mimeType.startsWith('image/')) {
+    throw new Error(`look_at: ${input.url} did not return an image content-type (got "${mimeType}")`)
+  }
+  // Streaming size check: arrayBuffer() would read the whole body before we
+  // could enforce a cap. Read chunk-by-chunk and abort once we cross the
+  // limit. Content-Length is checked first when present, but absent or lying
+  // headers fall through to the streaming check.
+  const declared = Number(res.headers.get('content-length') ?? '')
+  if (Number.isFinite(declared) && declared > URL_FETCH_MAX_BYTES) {
+    throw new Error(`look_at: ${input.url} response too large (${declared} bytes > ${URL_FETCH_MAX_BYTES} cap)`)
+  }
+  const reader = res.body?.getReader()
+  if (reader === undefined) {
+    throw new Error(`look_at: ${input.url} returned an empty body`)
+  }
+  const chunks: Uint8Array[] = []
+  let total = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    if (value === undefined) continue
+    total += value.byteLength
+    if (total > URL_FETCH_MAX_BYTES) {
+      await reader.cancel()
+      throw new Error(`look_at: ${input.url} response exceeded ${URL_FETCH_MAX_BYTES}-byte cap`)
+    }
+    chunks.push(value)
+  }
+  const buf = Buffer.concat(chunks)
+  return { data: buf.toString('base64'), mimeType }
+}

package/src/agent/plugin-tools.ts

@@ -30,6 +30,8 @@ import type {
   ToolResult,
 } from '@/plugin'
 
+import type { SessionOrigin } from './session-origin'
+
 type AnyAgentTool =
   | typeof piReadTool
   | typeof piBashTool
@@ -73,16 +75,37 @@ export type WrapToolOptions = {
   sessionId: string
   logger: PluginLogger
   hooks: HookBus
+  // Called at tool-execute time (not at wrap time) so channel sessions whose
+  // origin mutates per turn surface the current-turn `lastInboundAuthorId`
+  // to `tool.before`. Sessions with a fixed origin can pass `() => origin`.
+  getOrigin?: () => SessionOrigin | undefined
 }
 
 export type WrapSystemToolOptions = {
   agentDir: string
   sessionId: string
   hooks: HookBus
+  getOrigin?: () => SessionOrigin | undefined
 }
 
+// Zod 4 emits a top-level `"$schema": "https://json-schema.org/draft/2020-12/schema"`
+// pointer on every converted schema. Ajv v8 (used by pi-ai's runtime tool-argument
+// validator and by ModelRegistry's models.json validator) is configured for
+// Draft 7 and rejects unknown `$schema` URIs with:
+//
+//   no schema with key or ref "https://json-schema.org/draft/2020-12/schema"
+//
+// That error is raised before the tool's execute is even invoked, so the model
+// sees the failure as a tool-call result and reacts by retrying or falling back
+// to other tools. In the memory-logger / dreaming subagents this meant the
+// `find_entry` tool was permanently broken: the subagent kept falling back to
+// `read(offset=1, limit=2000)` and chunked through entire multi-hundred-KB
+// transcripts on every channel turn. Stripping `$schema` is the minimal,
+// converter-version-independent fix; it leaves the actual JSON-schema body
+// untouched and lets Ajv use its default draft.
 export function zodToToolParameters(schema: z.ZodType<unknown>): TSchema {
-  const json = z.toJSONSchema(schema, { io: 'input', reused: 'inline' })
+  const json = z.toJSONSchema(schema, { io: 'input', reused: 'inline' }) as Record<string, unknown>
+  delete json.$schema
   return json as unknown as TSchema
 }
 
@@ -101,11 +124,13 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
       }
 
       const mutableArgs = validated.data as Record<string, unknown>
+      const liveOrigin = opts.getOrigin?.()
       const before: ToolBeforeEvent = {
         tool: opts.toolName,
         sessionId: opts.sessionId,
         callId: toolCallId,
         args: mutableArgs,
+        ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
       }
       const blockResult = await opts.hooks.runToolBefore(before)
       if (blockResult !== undefined) {
@@ -151,11 +176,13 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
     parameters: withGuardAcknowledgements(tool.name, tool.parameters),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const mutableArgs = params as Record<string, unknown>
+      const liveOrigin = opts.getOrigin?.()
       const blockResult = await opts.hooks.runToolBefore({
         tool: tool.name,
         sessionId: opts.sessionId,
         callId: toolCallId,
         args: mutableArgs,
+        ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
       })
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
@@ -198,11 +225,13 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
     parameters: withGuardAcknowledgements(tool.name, tool.parameters),
     async execute(toolCallId, params, signal, onUpdate) {
       const mutableArgs = params as Record<string, unknown>
+      const liveOrigin = opts.getOrigin?.()
       const blockResult = await opts.hooks.runToolBefore({
         tool: tool.name,
         sessionId: opts.sessionId,
         callId: toolCallId,
         args: mutableArgs,
+        ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
       })
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)

package/src/agent/session-origin.ts

@@ -22,7 +22,13 @@ export type ChannelOriginContext = {
 
 export type SessionOrigin =
   | { kind: 'tui'; sessionId: string }
-  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | {
+      kind: 'cron'
+      jobId: string
+      jobKind: 'prompt' | 'exec' | 'subagent'
+      scheduledByRole?: string
+      scheduledByOrigin?: SessionOrigin | { kind: 'config-file' }
+    }
   | {
       kind: 'channel'
       adapter: AdapterId
@@ -35,24 +41,105 @@ export type SessionOrigin =
       participants?: readonly ChannelParticipant[]
       membership?: MembershipCount
     }
-  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+  | {
+      kind: 'subagent'
+      subagent: string
+      parentSessionId: string
+      spawnedByRole?: string
+      spawnedByOrigin?: SessionOrigin
+    }
 
 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 {
+// Each adapter renders mentions differently and the model has to copy the
+// exact shape to actually notify a peer. Until this table existed, the
+// channel origin block hardcoded Discord syntax (`<@USER_ID>`) for every
+// non-Slack adapter, which silently misled KakaoTalk and Telegram sessions
+// into emitting addressing tokens that the platform doesn't recognise. The
+// participants block kept rendering `<@authorId> (name)` lines for the
+// same reason — see `renderParticipants`.
+//
+// `mentionMode` semantics:
+//   - 'angle-id'     — Slack/Discord: `<@USER_ID>` where USER_ID is the
+//                      raw `authorId` we already surface in participants.
+//   - 'at-username'  — Telegram: `@username` plain text. The numeric
+//                      `authorId` is NOT what gets mentioned; usernames are
+//                      a separate field that not every user has.
+//   - 'alias'        — KakaoTalk: type the bot's alias as plain text. The
+//                      adapter's classifier (`kakaotalk-classify.ts`) does
+//                      a substring match against configured aliases; there
+//                      is no in-band syntax to copy.
+type PlatformInfo = {
+  displayName: string
+  mentionMode: 'angle-id' | 'at-username' | 'alias'
+}
+
+const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
+  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
+  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
+}
+
+function getPlatformInfo(adapter: AdapterId): PlatformInfo {
+  return PLATFORM_INFO[adapter]
+}
+
+// Compact description of the role the runtime resolved for this session at
+// creation time. Rendered as a single block under the origin text for
+// non-TUI sessions so the agent knows what it can and cannot do without
+// having to call into the PermissionService itself. TUI is omitted because
+// TUI is always `owner` by construction — annotating it would add noise to
+// every interactive session for zero new information.
+//
+// For channel sessions this is a session-creation snapshot. The router
+// re-resolves per-turn for tool gating, but the system prompt is not
+// regenerated mid-session; the role line is accurate at admission and the
+// `typeclaw-permissions` skill spells out how to interpret it on later
+// turns when a different speaker may have spoken last.
+export type SessionRoleContext = {
+  role: string
+  permissions: readonly string[]
+}
+
+export function renderSessionOrigin(
+  origin: SessionOrigin,
+  now: number = Date.now(),
+  roleContext?: SessionRoleContext,
+): string {
   switch (origin.kind) {
     case 'tui':
-      return renderTuiOrigin()
+      return withRoleContext(renderTuiOrigin(), roleContext)
     case 'cron':
-      return renderCronOrigin(origin)
+      return withRoleContext(renderCronOrigin(origin), roleContext)
     case 'channel':
-      return renderChannelOrigin(origin, now)
+      return withRoleContext(renderChannelOrigin(origin, now), roleContext)
     case 'subagent':
-      return renderSubagentOrigin(origin)
+      return withRoleContext(renderSubagentOrigin(origin), roleContext)
   }
 }
 
+function withRoleContext(block: string, ctx: SessionRoleContext | undefined): string {
+  if (ctx === undefined) return block
+  return `${block}\n\n${renderRoleContext(ctx)}`
+}
+
+function renderRoleContext(ctx: SessionRoleContext): string {
+  const permList = ctx.permissions.length === 0 ? 'none' : ctx.permissions.map((p) => `\`${p}\``).join(', ')
+  return [
+    '## Your role in this session',
+    '',
+    `Role: \`${ctx.role}\`. Permissions: ${permList}.`,
+    '',
+    'This is the role the runtime resolved at session creation. Tool calls',
+    'and channel admission are gated by these permissions; a `blocked:` or',
+    '"denied by permissions" message means the current actor lacks the',
+    'permission the guard was looking for. See the `typeclaw-permissions`',
+    'skill for what each role can do and how to grant access.',
+  ].join('\n')
+}
+
 function renderTuiOrigin(): string {
   return [
     '## Session origin',
@@ -118,11 +205,11 @@ function renderChannelOrigin(
   // 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 platformInfo = getPlatformInfo(origin.adapter)
   const lines: string[] = [
     '## Session origin',
     '',
-    `You are responding inside a ${platform} channel session. There is no human`,
+    `You are responding inside a ${platformInfo.displayName} 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.',
   ]
@@ -157,11 +244,10 @@ function renderChannelOrigin(
     "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),
+    ...renderMentionGuidance(platformInfo, origin.participants ?? [], now),
   )
 
-  const participantsBlock = renderParticipants(origin.participants ?? [], now)
+  const participantsBlock = renderParticipants(origin.participants ?? [], platformInfo, now)
   const membershipLine = renderMembershipSummary(origin, now)
   if (membershipLine !== null) lines.push('', membershipLine)
   if (participantsBlock) lines.push('', participantsBlock)
@@ -189,23 +275,11 @@ function renderMembershipSummary(
   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(
+function renderMentionGuidance(
+  platformInfo: PlatformInfo,
   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)
@@ -214,11 +288,32 @@ function renderMentionExample(
   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.',
-  ]
+
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return [
+        `To mention someone in your reply, use ${platformInfo.displayName} syntax \`<@USER_ID>\`.`,
+        `For example, to address ${exampleName} in this conversation, write \`<@${exampleId}> hello\` —`,
+        `**not** "${exampleName} hello". Plain-text names do not notify the recipient on ${platformInfo.displayName},`,
+        'and other bots in this channel will not see the message as addressed to them.',
+      ]
+    case 'at-username':
+      return [
+        `To mention someone in your reply, use Telegram syntax \`@username\` in plain text.`,
+        `Telegram usernames are a SEPARATE field from \`authorId\`. The \`<@id>\` tokens you see in the participants`,
+        'block below are a typeclaw convention for parsing inbound mentions — do not echo them back as outbound mentions.',
+        'If you only know an author by their display name and they have no `@username`, address them by display name',
+        'and they will see the message via the reply context.',
+      ]
+    case 'alias':
+      return [
+        'KakaoTalk has no in-band mention syntax. To address someone, just type their display name as plain text;',
+        "the participants block below shows display names. To get the BOT's attention from outside this session,",
+        "a user types one of the bot's configured aliases — they do not need to copy any token from the participants list.",
+        `The \`<@id>\` tokens in the participants block below are a typeclaw convention for parsing inbound mentions —`,
+        'do not echo them back as outbound mentions; KakaoTalk would render them as literal text.',
+      ]
+  }
 }
 
 function renderConversationLine(origin: {
@@ -239,26 +334,22 @@ function renderConversationLine(origin: {
   return `Conversation: ${chatLabel} in ${workspaceLabel}.`
 }
 
-function renderParticipants(participants: readonly ChannelParticipant[], now: number): string {
+function renderParticipants(
+  participants: readonly ChannelParticipant[],
+  platformInfo: PlatformInfo,
+  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}`)
+    const addressing = renderParticipantAddressing(p, platformInfo)
+    lines.push(`- ${addressing} — last message: ${ago}, total: ${p.messageCount}`)
   }
   lines.push(
     '',
@@ -268,14 +359,71 @@ function renderParticipants(participants: readonly ChannelParticipant[], now: nu
     '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.',
+    ...renderParticipantsTrailing(platformInfo),
   )
   return lines.join('\n')
 }
 
+// Per-line addressing token shown for each participant. The shape must match
+// what the model will need to emit when addressing that participant, so the
+// model can copy-paste the leading token verbatim. The previous unconditional
+// `<@id> (name)` format trained the model toward angle-id syntax on every
+// platform — correct for Discord/Slack, wrong for KakaoTalk (no in-band
+// mention syntax) and Telegram (uses `@username`, where `authorId` is a
+// numeric id and NOT the username). See issue #188.
+//
+// Symptom in the wild before PR #183 + this fix: 돌쇠 addressing Winky as
+// "Winky님" (plain text) on Discord, which never trips Winky's `isBotMention`
+// check, so Winky observes silently and the conversation stalls. The
+// angle-id branch here is exactly the fix for that case; the at-username
+// and alias branches keep the platform contract honest for KakaoTalk and
+// Telegram instead of self-contradicting the per-adapter mention guidance
+// produced by `renderMentionGuidance`.
+function renderParticipantAddressing(p: ChannelParticipant, platformInfo: PlatformInfo): string {
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return `<@${p.authorId}> (${p.authorName})`
+    case 'at-username':
+    case 'alias':
+      return `${p.authorName} (${p.authorId})`
+  }
+}
+
+// Closing prose for the participants block. Mirrors the per-platform branch
+// in `renderParticipantAddressing` so the trailing "address them" guidance
+// matches the format the bullet points just demonstrated. The previous
+// unconditional `<@authorId>` prose was the second voice in the
+// self-contradiction noted in issue #188 — it told KakaoTalk/Telegram
+// sessions to address peers with a syntax `renderMentionGuidance` had
+// just told them not to use.
+function renderParticipantsTrailing(platformInfo: PlatformInfo): string[] {
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return [
+        "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.',
+      ]
+    case 'at-username':
+      return [
+        "If a sender in the current turn isn't in the list, you can still",
+        'address them by `@username` — Telegram usernames are a SEPARATE field',
+        'from the numeric `authorId` shown in parentheses above, and not every',
+        'user has one. The list is a convenience for "who\'s been around',
+        'lately," not an exhaustive directory.',
+      ]
+    case 'alias':
+      return [
+        "If a sender in the current turn isn't in the list, you can still",
+        'address them by display name as plain text — KakaoTalk has no in-band',
+        'mention syntax, so the `authorId` shown in parentheses above is for',
+        'your reference only and must not be echoed back. The list is a',
+        'convenience for "who\'s been around lately," not an exhaustive directory.',
+      ]
+  }
+}
+
 function formatAgo(ms: number): string {
   const sec = Math.max(0, Math.round(ms / 1000))
   if (sec < 60) return `${sec} seconds ago`