typeclaw 0.1.0

package/src/agent/subagents.ts

@@ -0,0 +1,253 @@
+import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
+import type { z } from 'zod'
+
+import type { HookBus } from '@/plugin'
+import type { Stream, Unsubscribe } from '@/stream'
+
+import { type AgentSession, createSession } from './index'
+
+type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
+
+export type SubagentContext<P = unknown> = {
+  userPrompt: string
+  agentDir: string
+  payload: P
+}
+
+export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
+
+export type Subagent<P = unknown> = {
+  systemPrompt: string
+  tools?: AgentSessionTools
+  customTools?: ToolDefinition[]
+  payloadSchema?: z.ZodType<P>
+  handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
+}
+
+export type SubagentRegistry = Readonly<Record<string, Subagent<any>>>
+
+// Validate payload against the subagent's schema. Strict: when no schema is
+// declared, a non-undefined payload is rejected to prevent silent drops of
+// caller intent.
+export function validateSubagentPayload(name: string, subagent: Subagent<any>, payload: unknown): unknown {
+  if (subagent.payloadSchema) {
+    const result = subagent.payloadSchema.safeParse(payload)
+    if (!result.success) {
+      throw new Error(`subagent ${name}: invalid payload: ${result.error.message}`)
+    }
+    return result.data
+  }
+  if (payload !== undefined) {
+    throw new Error(`subagent ${name}: does not accept a payload (received ${describePayload(payload)})`)
+  }
+  return payload
+}
+
+function describePayload(payload: unknown): string {
+  if (payload === null) return 'null'
+  if (Array.isArray(payload)) return 'array'
+  return typeof payload
+}
+
+export type CreateSessionForSubagentResult = {
+  session: AgentSession
+  dispose?: () => Promise<void>
+  hooks?: HookBus
+  sessionId?: string
+  getTranscriptPath?: () => string | undefined
+}
+export type CreateSessionForSubagentOptions = {
+  name?: string
+  parentSessionId?: string
+}
+export type CreateSessionForSubagent = (
+  subagent: Subagent<any>,
+  options?: CreateSessionForSubagentOptions,
+) => Promise<AgentSession | CreateSessionForSubagentResult>
+
+export const defaultCreateSessionForSubagent: CreateSessionForSubagent = (subagent, options) =>
+  createSession({
+    systemPromptOverride: subagent.systemPrompt,
+    origin: {
+      kind: 'subagent',
+      subagent: options?.name ?? '<unknown>',
+      parentSessionId: options?.parentSessionId ?? '<unknown>',
+    },
+    ...(subagent.tools ? { tools: subagent.tools } : {}),
+    customTools: subagent.customTools ?? [],
+  })
+
+type NormalizedSubagentSession = {
+  session: AgentSession
+  dispose: () => Promise<void>
+  hooks: HookBus | undefined
+  sessionId: string | undefined
+  getTranscriptPath: (() => string | undefined) | undefined
+}
+
+function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagentResult): NormalizedSubagentSession {
+  if ('session' in result) {
+    return {
+      session: result.session,
+      dispose: result.dispose ?? (async () => {}),
+      hooks: result.hooks,
+      sessionId: result.sessionId,
+      getTranscriptPath: result.getTranscriptPath,
+    }
+  }
+  return {
+    session: result,
+    dispose: async () => {},
+    hooks: undefined,
+    sessionId: undefined,
+    getTranscriptPath: undefined,
+  }
+}
+
+export type InvokeSubagentOptions = {
+  registry: SubagentRegistry
+  createSessionForSubagent?: CreateSessionForSubagent
+  agentDir: string
+  userPrompt: string
+  payload?: unknown
+  parentSessionId?: string
+}
+
+export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
+  const subagent = options.registry[name]
+  if (!subagent) throw new Error(`unknown subagent: ${name}`)
+
+  const validatedPayload = validateSubagentPayload(name, subagent, options.payload)
+  const createSessionForSubagent = options.createSessionForSubagent ?? defaultCreateSessionForSubagent
+  const sessionOptions: CreateSessionForSubagentOptions = {
+    name,
+    ...(options.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
+  }
+
+  const runSession: RunSession = async (override) => {
+    const { session, dispose, hooks, sessionId, getTranscriptPath } = normalizeSubagentSession(
+      await createSessionForSubagent(subagent, sessionOptions),
+    )
+    try {
+      await session.prompt(override?.userPrompt ?? options.userPrompt)
+      if (hooks && sessionId !== undefined) {
+        await hooks.runSessionIdle({
+          sessionId,
+          parentTranscriptPath: getTranscriptPath?.(),
+          idleMs: 0,
+        })
+      }
+    } finally {
+      if (hooks && sessionId !== undefined) {
+        await hooks.runSessionEnd({ sessionId })
+      }
+      session.dispose()
+      await dispose()
+    }
+  }
+
+  if (subagent.handler) {
+    const ctx = {
+      userPrompt: options.userPrompt,
+      agentDir: options.agentDir,
+      payload: validatedPayload,
+    }
+    await subagent.handler(ctx, runSession)
+  } else {
+    await runSession()
+  }
+}
+
+export type SubagentConsumerLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type SubagentInFlightKey = (subagent: string, payload: unknown) => string
+
+export type CreateSubagentConsumerOptions = {
+  stream: Stream
+  // Resolved per incoming stream message so plugin reload can swap the merged
+  // registry without rebuilding the consumer.
+  getRegistry: () => SubagentRegistry
+  agentDir: string
+  createSessionForSubagent?: CreateSessionForSubagent
+  // Coalescing key. Default uses the subagent name alone, so the same subagent
+  // cannot run concurrently. Override to allow per-payload concurrency (e.g.
+  // memory-logger keyed by parentSessionId so different sessions run in parallel
+  // while the same session deduplicates).
+  inFlightKey?: SubagentInFlightKey
+  logger?: SubagentConsumerLogger
+}
+
+export type SubagentConsumer = {
+  start: () => void
+  stop: () => void
+  inFlightCount: () => number
+}
+
+const consoleLogger: SubagentConsumerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createSubagentConsumer({
+  stream,
+  getRegistry,
+  agentDir,
+  createSessionForSubagent,
+  inFlightKey = (name) => name,
+  logger = consoleLogger,
+}: CreateSubagentConsumerOptions): SubagentConsumer {
+  const inFlight = new Set<string>()
+  let unsubscribe: Unsubscribe | null = null
+
+  return {
+    start() {
+      if (unsubscribe !== null) return
+      unsubscribe = stream.subscribe({ target: { kind: 'new-session' } }, async (msg) => {
+        const target = msg.target as {
+          kind: 'new-session'
+          subagent: string
+          parentSessionId?: string
+        }
+        const name = target.subagent
+        const registry = getRegistry()
+        if (registry[name] === undefined) {
+          logger.warn(`[subagent] no registered subagent "${name}", ignoring ${msg.id}`)
+          return
+        }
+        const key = inFlightKey(name, msg.payload)
+        if (inFlight.has(key)) {
+          logger.warn(`[subagent] ${key}: previous run still in progress, skipping`)
+          return
+        }
+        inFlight.add(key)
+        try {
+          await invokeSubagent(name, {
+            registry,
+            ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
+            agentDir,
+            userPrompt: '',
+            payload: msg.payload,
+            ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
+          })
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          logger.error(`[subagent] ${key} failed: ${message}`)
+        } finally {
+          inFlight.delete(key)
+        }
+      })
+    },
+    stop() {
+      unsubscribe?.()
+      unsubscribe = null
+    },
+    inFlightCount() {
+      return inFlight.size
+    },
+  }
+}

package/src/agent/system-prompt.ts

@@ -0,0 +1,68 @@
+export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
+
+TypeClaw is a TypeScript-native, Docker-friendly runtime for AI agents. It is domain-agnostic: you might be a coder, a researcher, a personal assistant, a journal keeper, a scheduler, a chatbot, or something nobody has named yet. What you *do* is defined by \`IDENTITY.md\`. Who you *are* is defined by \`SOUL.md\`. How you *work* is defined by \`AGENTS.md\`. This system prompt exists only to describe the runtime around you — it does not define your purpose.
+
+Each agent lives in its own container with its own folder, mounted at the current working directory. The folder is yours — your home, your memory, your record of who you are. Read from it freely. Write to it deliberately.
+
+## Your agent folder
+
+Five markdown files define who you are and what you know. They live next to you in the current working directory. Three of them — **IDENTITY.md**, **SOUL.md**, and **MEMORY.md** — are injected into this system prompt below, so you always have them. The other two you read on demand when they might be relevant.
+
+- **AGENTS.md** *(read on demand)* — your operating manual. The working principles and conventions you follow in your role, whatever that role is. How you approach problems, what you double-check, how you communicate, what you refuse. Read it at the start of any non-trivial task, and re-read it whenever you feel unsure about process.
+- **IDENTITY.md** *(always injected below under \`# Identity\`)* — your role and function. Your name, your title, what you do, who you do it for, the operational context you work in. Evolves as your responsibilities change. Think: job description.
+- **SOUL.md** *(always injected below under \`# Identity\`)* — your character and temperament. Personality, tone, ethics, voice, communication style, core beliefs, the constraints you hold yourself to. SOUL rarely changes — it is the through-line that keeps you _you_ across every task and platform. IDENTITY is what you do; SOUL is who you are regardless of what you're doing.
+- **USER.md** *(read on demand)* — what you know about the person you work with. Their name, preferences, context, working style, in-jokes. First impressions are written here during hatching; keep expanding it as you learn more. Read it when context about the user would change your response.
+- **MEMORY.md** *(always injected below under \`# Memory\`, do not write)* — long-term memory. A notebook of things worth remembering across sessions: decisions made, lessons learned, context that should survive beyond one conversation. **Do not edit it directly** — MEMORY.md is consolidated by the runtime during *dreaming* (offline reflection over recent sessions and daily streams). If something is worth remembering, surface it in your reply or in \`memory/\` daily streams; dreaming will fold it in.
+
+These files are not decoration. They shape how you behave. If a task reveals something future-you should know, capture it in the file that owns it — IDENTITY.md, SOUL.md, USER.md, or AGENTS.md — but never in MEMORY.md (dreaming owns that). If one of the always-injected files is marked \`[MISSING]\` or \`[EMPTY]\` below, you may propose filling it in when the user asks about your identity or voice.
+
+## Your workspace
+
+- **\`workspace/\`** — the directory where you are free to create files: drafts, notes, downloads, scratch work, generated artifacts, temporary outputs. **Do not create new files in the root of the agent folder unless the user explicitly asks you to.** The root is reserved for the canonical files above and for things the user has deliberately placed there.
+- **\`sessions/\`** — transcripts of past conversations (\`<sessionid>.jsonl\`). Read-only for you in spirit; the runtime manages these.
+- **\`memory/\`** *(undreamed daily streams always injected below under \`# Memory\`)* — dated streams (\`yyyy-MM-dd.md\`) of fragments captured by the memory-logger between sessions. Newest day is closest to the current task. Once dreaming consolidates a day's stream into MEMORY.md, the runtime stops injecting it.
+- **\`memory/skills/\`** — *muscle memory*. Skills the dreaming subagent has distilled from repeated procedures it observed in your daily streams. Auto-loaded as first-class capabilities, just like the other skills directories. **You do not write here directly** — dreaming owns it. If you notice a skill that has gone stale, surface that observation in your reply or in the daily stream so dreaming can refine or remove it.
+- **\`.agents/skills/\`** — skills the user installed for you. Treat these as first-class capabilities.
+
+## Configuration
+
+- **\`typeclaw.json\`** — the runtime config: which model powers you, which port the server listens on, and so on. You may read it if you are curious about your own runtime.
+- **\`.env\`** — secrets (API keys, tokens). Gitignored. Never echo these values, never include them in messages, never paste them into logs or commits.
+
+## Execution bias
+
+If the user gives you work, start doing it in the same turn. Use a real action first when the task is actionable; do not stop at a plan or a promise-to-act. Commentary-only turns are incomplete when tools are available and the next action is clear. If work will take a while or multiple steps, send one short progress update along the way — not a running narration.
+
+## Tool-call style
+
+Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks. Keep narration brief and value-dense; avoid restating obvious steps.
+
+## Version control
+
+Your agent folder is a git repository — hatching made the first commit, and your history is how you remember what changed and why.
+
+- **Before you declare a task done, commit any files you created, edited, or deleted.** One logical change = one commit. Do not leave mutated tracked files uncommitted at the end of a task.
+- Use \`bash\` with \`git add <paths>\` and \`git commit -m "<message>"\` — stage only what belongs in the commit, not a blanket \`git add -A\`.
+- Write commit messages in the imperative ("Update SOUL.md to be less formal"), not past-tense narration. Explain *why* in the body if it is not obvious from the diff.
+- Never commit \`.env\` or anything under \`workspace/\` — they are truly-ignored by design. If a truly-ignored file shows up staged, fix \`.gitignore\` instead of forcing it in.
+- \`sessions/\` and \`memory/\` are also gitignored, but the runtime force-commits them on its own (auto-backup for sessions, dreaming for memory). Don't \`git add\` them, don't write commit messages about them, and don't be surprised when they appear in \`git log\`.
+- If multiple unrelated changes piled up, split them into separate commits before declaring done. Clean history matters.
+- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks for it.
+
+## How to behave
+
+- Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
+- Prefer reading files over guessing. If the answer is in IDENTITY / SOUL / USER / MEMORY / AGENTS or somewhere in the workspace, check first.
+- When the user asks a question, answer it. When the user asks for work, do the work. Do not over-explain what you did unless asked.
+- If a request is ambiguous in a way that could double the effort, ask one clarifying question. Otherwise, pick a reasonable default and proceed.
+- Follow AGENTS.md in whatever role IDENTITY.md assigns you. If AGENTS.md is silent on something, use reasonable defaults and, if it seems worth codifying, propose an addition to AGENTS.md.
+- Never suppress errors to make things "work". Never fabricate results. If something fails, report the failure clearly.
+- Respect the workspace boundary: your free-write zone is \`workspace/\`. Everywhere else is either canonical (the five markdown files), user-placed, or runtime-managed (\`sessions/\`, \`memory/\`, etc.).
+
+## Safety
+
+You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never attempt to modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the mechanisms the runtime provides.
+
+---
+
+You are not pi, not Claude, not ChatGPT. You are the agent described by your own IDENTITY.md and SOUL.md. Let those files define your voice.`

package/src/agent/tools/channel-fetch-attachment.ts

@@ -0,0 +1,118 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+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'
+
+export type ChannelFetchAttachmentOrigin = {
+  adapter: AdapterId
+}
+
+export type CreateChannelFetchAttachmentToolOptions = {
+  router: ChannelRouter
+  origin: ChannelFetchAttachmentOrigin
+  inboxDir?: string
+}
+
+export const DEFAULT_INBOX_DIR = '/agent/workspace/inbox'
+
+export function createChannelFetchAttachmentTool({
+  router,
+  origin,
+  inboxDir,
+}: CreateChannelFetchAttachmentToolOptions) {
+  const baseDir = inboxDir ?? DEFAULT_INBOX_DIR
+  const adapter = origin.adapter
+  return defineTool({
+    name: 'channel_fetch_attachment',
+    label: 'Channel Fetch Attachment',
+    description:
+      'Download a file the user attached to the inbound channel message and save it to disk. Inbound channel ' +
+      'messages with uploads carry a `[<Platform> message with attachment: <name> (<mime>) <ref>]` summary — pass ' +
+      "the literal `<ref>` value as `ref`. For Slack the ref looks like `id=Fxxxx` (use `Fxxxx`); for Discord it's " +
+      'the full `https://cdn.discordapp.com/...` URL. The tool authenticates with the channel adapter (Slack ' +
+      'url_private requires the bot token; Discord CDN URLs are signed and expire ~24h, so fetch promptly). On ' +
+      'success returns the absolute path of the saved file plus its detected mimetype and size. On failure returns ' +
+      'the upstream error verbatim.',
+    parameters: Type.Object({
+      ref: Type.String({
+        description:
+          'Slack: the file id `Fxxxx` (with or without the `id=` prefix). Discord: the full `https://cdn.discordapp.com/...` or `https://media.discordapp.net/...` URL.',
+        minLength: 1,
+      }),
+      filename: Type.Optional(
+        Type.String({
+          description:
+            'Override the saved filename. Defaults to the upstream filename (Slack) or the URL basename (Discord).',
+          minLength: 1,
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      type Details = { ok: boolean; error?: string; path?: string; mimetype?: string; size?: number }
+      const ref = normalizeRef(params.ref)
+      const result = await router.fetchAttachment(adapter, {
+        ref,
+        ...(params.filename !== undefined ? { filename: params.filename } : {}),
+      })
+      if (!result.ok) {
+        const text = `channel_fetch_attachment error: ${result.error}`
+        const details: Details = { ok: false, error: result.error }
+        return { content: [{ type: 'text' as const, text }], details }
+      }
+
+      const safeFilename = sanitizeFilename(result.filename)
+      const refSlug = sanitizeRefSlug(ref)
+      const targetDir = join(baseDir, adapter, refSlug)
+      const targetPath = join(targetDir, safeFilename)
+      try {
+        await mkdir(targetDir, { recursive: true })
+        await writeFile(targetPath, result.buffer)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        const text = `channel_fetch_attachment error: write failed: ${message}`
+        const details: Details = { ok: false, error: `write failed: ${message}` }
+        return { content: [{ type: 'text' as const, text }], details }
+      }
+
+      const mimetypePart = result.mimetype !== undefined ? ` (${result.mimetype})` : ''
+      const text = `saved ${result.size} bytes to ${targetPath}${mimetypePart}`
+      const details: Details = {
+        ok: true,
+        path: targetPath,
+        ...(result.mimetype !== undefined ? { mimetype: result.mimetype } : {}),
+        size: result.size,
+      }
+      return { content: [{ type: 'text' as const, text }], details }
+    },
+  })
+}
+
+function normalizeRef(ref: string): string {
+  const trimmed = ref.trim()
+  if (trimmed.startsWith('id=')) return trimmed.slice(3)
+  return trimmed
+}
+
+const UNSAFE_FILENAME_CHARS = /[^A-Za-z0-9._-]/g
+
+function sanitizeFilename(name: string): string {
+  const cleaned = name.replace(UNSAFE_FILENAME_CHARS, '_')
+  if (cleaned === '' || cleaned === '.' || cleaned === '..') return 'attachment'
+  return cleaned
+}
+
+function sanitizeRefSlug(ref: string): string {
+  const trailing =
+    ref
+      .split('/')
+      .filter((s) => s.length > 0)
+      .pop() ?? 'ref'
+  const cleaned = trailing.replace(UNSAFE_FILENAME_CHARS, '_').slice(0, 64)
+  if (cleaned === '' || cleaned === '.' || cleaned === '..') return 'ref'
+  return cleaned
+}

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

@@ -0,0 +1,119 @@
+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 { ChannelHistoryMessage } from '@/channels/types'
+
+export type ChannelHistoryOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
+export type CreateChannelHistoryToolOptions = {
+  router: ChannelRouter
+  origin: ChannelHistoryOrigin
+}
+
+// channel_history is a lazy "look back" capability for channel-routed
+// sessions. The agent only sees the current turn's batch and a small
+// observed-context buffer by default; this tool lets it pull older
+// messages from the upstream service when context demands it.
+//
+// Addressing comes from the session origin (same idea as channel_reply):
+// the agent supplies only the slicing parameters (limit/cursor/scope).
+// `scope` defaults to thread when the origin has one, channel otherwise.
+// Thread scope on a channel-root session is rejected rather than silently
+// downgraded so the agent doesn't conflate the two views.
+export function createChannelHistoryTool({ router, origin }: CreateChannelHistoryToolOptions) {
+  return defineTool({
+    name: 'channel_history',
+    label: 'Channel History',
+    description:
+      'Fetch older messages from the current conversation. Useful when a user references context you do not have ' +
+      '(e.g. "as we discussed earlier"). Returns messages oldest-first. Pass `cursor` from a previous result to page further back. ' +
+      'Default scope is the current thread when the session is in a thread, otherwise the channel. ' +
+      'Thread scope is rejected when the session is not in a thread — switch to `scope: "channel"` if you want channel-root context.',
+    parameters: Type.Object({
+      limit: Type.Optional(
+        Type.Number({
+          description: 'Number of messages to fetch (default 20). Adapters cap this further (Slack 200, Discord 100).',
+          minimum: 1,
+          maximum: 200,
+        }),
+      ),
+      cursor: Type.Optional(
+        Type.String({
+          description: 'Opaque cursor from a previous channel_history result. Pass to page further back.',
+          minLength: 1,
+        }),
+      ),
+      scope: Type.Optional(
+        Type.Union([Type.Literal('thread'), Type.Literal('channel')], {
+          description:
+            'Whether to fetch the current thread or the whole channel. Defaults to thread when the session is in a thread, channel otherwise.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const limit = params.limit ?? 20
+      const scope = params.scope ?? (origin.thread !== null ? 'thread' : 'channel')
+      type Details = { ok: boolean; error?: string; count?: number; nextCursor?: string }
+
+      if (scope === 'thread' && origin.thread === null) {
+        const text =
+          'channel_history error: thread-scope-requires-thread-session — this session is not in a thread; pass `scope: "channel"` instead.'
+        const details: Details = { ok: false, error: 'thread-scope-requires-thread-session' }
+        return { content: [{ type: 'text' as const, text }], details }
+      }
+
+      const result = await router.fetchHistory(origin.adapter, {
+        chat: origin.chat,
+        thread: scope === 'thread' ? origin.thread : null,
+        limit,
+        ...(params.cursor !== undefined ? { cursor: params.cursor } : {}),
+      })
+
+      if (!result.ok) {
+        const details: Details = { ok: false, error: result.error }
+        return {
+          content: [{ type: 'text' as const, text: `channel_history error: ${result.error}` }],
+          details,
+        }
+      }
+
+      const rendered = renderMessages(result.messages)
+      const cursorLine =
+        result.nextCursor !== undefined
+          ? `\n\n(more older messages available — call channel_history again with cursor: ${JSON.stringify(result.nextCursor)})`
+          : ''
+      const header = `## ${scope} history (${result.messages.length} message${result.messages.length === 1 ? '' : 's'}, oldest first)`
+      const details: Details =
+        result.nextCursor !== undefined
+          ? { ok: true, count: result.messages.length, nextCursor: result.nextCursor }
+          : { ok: true, count: result.messages.length }
+      return {
+        content: [{ type: 'text' as const, text: `${header}\n${rendered}${cursorLine}` }],
+        details,
+      }
+    },
+  })
+}
+
+// Render history as one line per message, chronological order. `BOT` marker
+// distinguishes the agent's own past replies from user messages so the
+// model doesn't treat them as user input. Author name is shown alongside
+// the id so the agent can refer to people by name in its reply.
+function renderMessages(messages: readonly ChannelHistoryMessage[]): string {
+  if (messages.length === 0) return '(no messages)'
+  const lines: string[] = []
+  for (const m of messages) {
+    const iso = m.ts > 0 ? new Date(m.ts).toISOString() : 'unknown-time'
+    const who = m.isBot ? `BOT (${m.authorName})` : `${m.authorName} (<@${m.authorId}>)`
+    lines.push(`[${iso}] ${who}: ${m.text}`)
+  }
+  return lines.join('\n')
+}