dsh-taskboard 0.1.0

package/src/host/tools.ts

@@ -0,0 +1,631 @@
+/**
+ * The eight `taskboard_*` agent tools. All writes require a calling agent
+ * session (ownership audit), carry optimistic-version checks, and enforce
+ * the protocol gates in CODE, not in prompt text:
+ *
+ * - `move → done` is rejected for agent callers (user confirmation only)
+ * - `move todo → in_progress` requires the calling session's workspace to
+ *   match the task's project (claim boundary)
+ * - taking over a task held by another session is rejected
+ * - `delete` for agent callers only sets the soft-delete marker
+ *
+ * OUTPUT CONTRACT (lesson: registry `createSuccessResult` renders
+ * `output.render(args, value)` into `result.content`, and the loop feeds
+ * exactly that content to the model — the raw JSON `value` never reaches
+ * the model): render() IS the model-facing tool result. Every render must
+ * carry the complete facts an agent needs to act (ids, versions, statuses);
+ * a "terse UI summary" here starves the agent.
+ *
+ * @module dsh-taskboard/host/tools
+ */
+import type { WorkspaceRegistry } from '@deepseek-ai/dsh-workspace'
+import { defineTool } from './sdk.ts'
+import {
+  asStatus,
+  asUrgency,
+  canTransition,
+  effectivePrompt,
+  isClaim,
+  newCommentId,
+  newTaskId,
+  normalizeBody,
+  normalizeExecution,
+  normalizePrompt,
+  normalizeTitle,
+  summarize,
+  type Actor,
+  type TaskModel,
+  type TaskRecord,
+} from '../shared/protocol.ts'
+import type { TaskStore } from './store.ts'
+
+/** Render side: one compact task line (id/status/version are load-bearing). */
+function taskLine(t: {
+  id: string
+  title: string
+  status: string
+  urgency: string
+  version: number
+  workspaceId: string
+  blocked: boolean
+  executionMode: string
+  commentCount?: number
+  lastExecutionOutcome?: string
+  trashed?: boolean
+}): string {
+  const parts = [
+    `- ${t.id} [${t.status}] v${t.version} · ${t.urgency} · 项目 ${t.workspaceId}`,
+    `「${t.title}」`,
+  ]
+  if (t.blocked) parts.push('·受阻')
+  if (t.executionMode === 'scheduled') parts.push('·定时')
+  if (t.commentCount !== undefined && t.commentCount > 0) parts.push(`·评论${t.commentCount}`)
+  if (t.lastExecutionOutcome !== undefined) parts.push(`·上次执行${t.lastExecutionOutcome}`)
+  if (t.trashed === true) parts.push('·已删')
+  return parts.join(' ')
+}
+
+/** Render side: the full task detail block (everything an executor needs). */
+function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
+  const lines: string[] = [
+    `任务 ${t.id} 「${t.title}」`,
+    `状态: ${t.status} (v${t.version}) · 紧急度: ${t.urgency} · 项目: ${t.workspaceId}${t.blocked ? ' · 受阻' : ''}`,
+    `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` cron=${t.execution.cron}` : ''}`,
+  ]
+  if (t.execution.nextRunAt !== undefined) lines.push(`下次触发: ${new Date(t.execution.nextRunAt).toISOString()}`)
+  if (t.model !== undefined) lines.push(`固定模型: ${t.model.provider}/${t.model.model}`)
+  lines.push(`描述: ${t.description.length > 0 ? t.description : '（无）'}`)
+  lines.push(`执行 Prompt: ${t.effectivePrompt ?? effectivePrompt(t)}`)
+  if (t.comments.length > 0) {
+    lines.push(`评论 (${t.comments.length}):`)
+    for (const c of t.comments) {
+      const who = c.threadId !== undefined ? `agent ${String(c.threadId).slice(0, 24)}` : 'user'
+      lines.push(`  - [${who} ${new Date(c.createdAt).toISOString()}] ${c.body}`)
+    }
+  } else {
+    lines.push('评论: 无')
+  }
+  if (t.executions.length > 0) {
+    lines.push(`执行记录 (${t.executions.length}):`)
+    for (const e of t.executions) {
+      const at = e.startedAt !== undefined ? new Date(e.startedAt).toISOString() : '?'
+      const err = e.error !== undefined ? ` 错误: ${e.error}` : ''
+      lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${err}`)
+    }
+  } else {
+    lines.push('执行记录: 无')
+  }
+  const updatedBy = t.updatedBy.kind === 'agent' ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : 'user'
+  lines.push(`更新: ${new Date(t.updatedAt).toISOString()} 由 ${updatedBy}`)
+  return lines.join('\n')
+}
+
+/** Stable error codes surfaced at the head of tool error messages. */
+export const ERR = {
+  notFound: 'not_found',
+  versionConflict: 'version_conflict',
+  workspaceMismatch: 'workspace_mismatch',
+  invalidTransition: 'invalid_transition',
+  forbidden: 'forbidden',
+  requiresAgent: 'unauthorized_actor',
+  invalidInput: 'invalid_input',
+} as const
+
+/** Tool failure: an Error whose message starts with a stable code. */
+class ToolError extends Error {
+  constructor(readonly code: string, detail: string) {
+    super(`Error: ${code}: ${detail}`)
+  }
+}
+
+/** The workspace face the tools need (narrow for tests). */
+export interface WorkspaceFace {
+  /** Resolve the workspace owning a canonical cwd, if any. */
+  resolveByPath(path: string): Promise<{ id: string } | undefined>
+  /** Get a workspace by id. */
+  get(id: string): { id: string; path: string; title: string } | undefined
+  /** List all workspaces. */
+  list(): Array<{ id: string; path: string; title: string }>
+}
+
+/** Adapt the real registry to the narrow face. */
+export function workspaceFace(registry: WorkspaceRegistry): WorkspaceFace {
+  // Explicit field mapping: Workspace entities expose path/title as prototype
+  // getters, which JSON.stringify skips (own enumerable properties only).
+  return {
+    resolveByPath: async (path) => {
+      const ws = await registry.resolveByPath(path as never)
+      return ws === undefined ? undefined : { id: ws.id }
+    },
+    get: id => {
+      const ws = registry.get(id as never)
+      return ws === undefined ? undefined : { id: ws.id, path: ws.path, title: ws.title }
+    },
+    list: () => registry.list().map(ws => ({ id: ws.id, path: ws.path, title: ws.title })),
+  }
+}
+
+/** Everything the tool set needs. */
+export interface ToolDeps {
+  store: TaskStore
+  workspaces: WorkspaceFace
+  /** Current epoch ms (injectable for tests). */
+  now: () => number
+}
+
+/** Resolve the calling agent's actor and session id. */
+function caller(exec: ToolRunContext): { actor: Actor & { kind: 'agent' }; sessionId: string } {
+  if (!exec.agent) throw new ToolError(ERR.requiresAgent, 'taskboard tools require a calling agent session')
+  const sessionId = exec.agent.id
+  return { actor: { kind: 'agent', sessionId }, sessionId }
+}
+
+/** The calling session's workspace id (undefined when unaffiliated). */
+async function callerWorkspace(deps: ToolDeps, exec: ToolRunContext): Promise<string | undefined> {
+  const cwd = exec.agent?.session.header.cwd
+  if (typeof cwd !== 'string' || cwd.length === 0) return undefined
+  const ws = await deps.workspaces.resolveByPath(cwd)
+  return ws?.id
+}
+
+/** Guard: version match. */
+function versionGuard(task: TaskRecord, ifVersion: number | undefined): void {
+  if (ifVersion === undefined) {
+    throw new ToolError(ERR.versionConflict, 'this write requires ifVersion; read the task first')
+  }
+  if (ifVersion !== task.version) {
+    throw new ToolError(ERR.versionConflict, `stale version ${ifVersion} (current ${task.version}); re-read the task and retry once`)
+  }
+}
+
+/** Re-throw with a stable code; non-ToolErrors become invalid_input. */
+function fail(error: unknown): never {
+  if (error instanceof ToolError) throw error
+  const message = error instanceof Error ? error.message : String(error)
+  throw new ToolError(ERR.invalidInput, message)
+}
+
+/** Loose json output schema shared by every taskboard tool. */
+const JSON_OUT = { type: 'json' } as const
+
+/** Deep-JSON a value for a json-rooted tool output (spread results lose implicit index signatures). */
+function json<T>(value: T): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
+}
+
+/** The exec context face the tools read (agent identity + session cwd). */
+export interface ToolRunContext {
+  agent?: { id: string; session: { header: { cwd?: string } } }
+}
+
+/** Registry-like context face (tests stub this). */
+export interface ToolContextFace {
+  tools: { register(tool: { name: string }): unknown }
+}
+
+/**
+ * Register all eight tools.
+ * @param ctx - a context exposing `tools.register`.
+ * @param deps - store + workspaces + clock.
+ * @returns dispose functions, one per tool.
+ */
+export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Array<() => void> {
+  const disposers: Array<() => void> = []
+  const { store, workspaces } = deps
+
+  // Env-gated tool-call tracing (ATB_TRACE=1) — evidence for protocol E2E.
+  const register = (tool: { name: string; execute?: unknown }) => {
+    if (process.env.ATB_TRACE === '1' && typeof tool.execute === 'function') {
+      const orig = tool.execute as (args: unknown, exec: unknown) => Promise<unknown>
+      tool.execute = async (args: unknown, exec: unknown) => {
+        console.error(`[atb ▶] ${tool.name}`, JSON.stringify(args).slice(0, 300))
+        try {
+          const result = await orig(args, exec)
+          console.error(`[atb ✓] ${tool.name}`, JSON.stringify(result).slice(0, 300))
+          return result
+        } catch (error) {
+          console.error(`[atb ✗] ${tool.name}`, String(error).slice(0, 400))
+          throw error
+        }
+      }
+    }
+    return ctx.tools.register(tool as { name: string })
+  }
+
+  // ------------------------------------------------------------------ list
+  disposers.push(register(defineTool({
+    name: 'taskboard_list',
+    description:
+      'List task-board tasks. Filter by project (workspaceId), status, or urgency. '
+      + 'Returns compact summaries (id, title, status, urgency, version, claim owner). '
+      + 'Check this before starting work to find claimable todo tasks in your project.',
+    parameters: {
+      workspaceId: { type: 'string', description: 'Filter by project (DSH workspace id).' },
+      status: { type: 'string', description: 'Filter by exact status (backlog/todo/in_progress/in_review/done/canceled/archived).' },
+      urgency: { type: 'string', description: 'Filter by urgency (urgent/normal/relaxed).' },
+      includeTrashed: { type: 'boolean', description: 'Include soft-deleted tasks (default false).' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { revision?: number; tasks?: Array<Record<string, unknown>> }
+        const tasks = v.tasks ?? []
+        const head = `任务 ${tasks.length} 条（台账 rev ${v.revision ?? '?'}）`
+        if (tasks.length === 0) return [{ type: 'text', text: `${head}：无匹配任务。` }]
+        return [{ type: 'text', text: [head, ...tasks.map(t => taskLine(t as never))].join('\n') }]
+      },
+    },
+    async execute(args) {
+      try {
+        const a = args as { workspaceId?: string; status?: string; urgency?: string; includeTrashed?: boolean }
+        const tasks = store.snapshot().tasks.filter(t =>
+          (a.workspaceId === undefined || t.workspaceId === a.workspaceId)
+          && (a.status === undefined || t.status === a.status)
+          && (a.urgency === undefined || t.urgency === a.urgency)
+          && (a.includeTrashed === true || t.trashedAt === undefined))
+        return json({ revision: store.snapshot().revision, tasks: tasks.map(summarize) })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ------------------------------------------------------------------- get
+  disposers.push(register(defineTool({
+    name: 'taskboard_get',
+    description:
+      'Read one task in full: description, prompt, project, urgency, status, comments, executions, version. '
+      + 'Read this (and the comments) BEFORE claiming or starting work on a task.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id from the board.' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { task?: TaskRecord & { effectivePrompt?: string } }
+        return [{ type: 'text', text: v.task === undefined ? '任务不存在。' : taskDetail(v.task) }]
+      },
+    },
+    async execute(args: { id: string }) {
+      try {
+        const { id } = args
+        const task = store.get(id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${id}`)
+        return json({ task: { ...task, effectivePrompt: effectivePrompt(task) } })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ---------------------------------------------------------------- create
+  disposers.push(register(defineTool({
+    name: 'taskboard_create',
+    description:
+      'Create a task on the board. Required: title, workspaceId (project), urgency (urgent/normal/relaxed). '
+      + 'Optional: description, prompt (sent to a fresh session on execution), status (default todo), '
+      + 'execution mode (claim|scheduled + cron), model {provider, model} to pin executions to a model. '
+      + 'Do not track trivial requests as tasks.',
+    parameters: {
+      title: { type: 'string', required: true, description: 'Short imperative line (1..200 chars).' },
+      workspaceId: { type: 'string', required: true, description: 'Project (DSH workspace id) this task belongs to.' },
+      urgency: { type: 'string', required: true, description: 'urgent (red) | normal (purple) | relaxed (blue).' },
+      description: { type: 'string', description: 'What the task involves (plain text).' },
+      prompt: { type: 'string', description: 'Prompt sent to a fresh session when executed; default = title+description.' },
+      status: { type: 'string', description: 'Initial status; default todo. backlog = not approved for execution.' },
+      execution: {
+        type: 'object',
+        additionalProperties: false,
+        description: 'Execution config: { mode: "claim" } (default) or { mode: "scheduled", cron: "m h dom mon dow" }.',
+        properties: {
+          mode: { type: 'string', description: 'claim | scheduled.' },
+          cron: { type: 'string', description: 'Five-field cron expression (scheduled only).' },
+        },
+      },
+      model: {
+        type: 'object',
+        additionalProperties: false,
+        description: 'Pin executions to one configured model: { provider, model }. Omit to use the default model.',
+        properties: {
+          provider: { type: 'string', description: 'Provider route id.' },
+          model: { type: 'string', description: 'Provider-owned model id.' },
+        },
+      },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const t = v.task
+        return [{ type: 'text', text: t === undefined ? '创建失败。' : `已创建任务 ${t.id} [${t.status}] v${t.version}。写入前先 taskboard_get 读取。` }]
+      },
+    },
+    async execute(args: {
+      title: string
+      workspaceId: string
+      urgency: string
+      status?: string
+      description?: string
+      prompt?: string
+      execution?: { mode?: string; cron?: string }
+      model?: { provider?: string; model?: string }
+    }, exec: unknown) {
+      try {
+        const { actor } = caller(exec as ToolRunContext)
+        const title = normalizeTitle(args.title)
+        if (workspaces.get(args.workspaceId) === undefined) {
+          throw new ToolError(ERR.notFound, `unknown workspaceId ${args.workspaceId}`)
+        }
+        const urgency = asUrgency(args.urgency)
+        const status = args.status === undefined ? 'todo' as const : asStatus(args.status)
+        if (status === 'done' || status === 'archived') {
+          throw new ToolError(ERR.invalidTransition, 'a new task cannot start as done/archived')
+        }
+        const execution = normalizeExecution(args.execution ?? {}, deps.now())
+        if (args.model !== undefined && (typeof args.model.provider !== 'string' || typeof args.model.model !== 'string')) {
+          throw new ToolError(ERR.invalidInput, 'model must be { provider: string, model: string }')
+        }
+        const now = deps.now()
+        const task: TaskRecord = {
+          id: newTaskId(),
+          title,
+          description: (args.description ?? '').trim(),
+          prompt: normalizePrompt(args.prompt),
+          workspaceId: args.workspaceId,
+          urgency,
+          status,
+          blocked: false,
+          execution,
+          model: args.model as TaskModel | undefined,
+          version: 1,
+          createdAt: now,
+          updatedAt: now,
+          createdBy: actor,
+          updatedBy: actor,
+          comments: [],
+          executions: [],
+        }
+        await store.mutate('task-created', ledger => {
+          ledger.tasks.push(task)
+          return [task]
+        })
+        return json({ task: summarize(task) })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ---------------------------------------------------------------- update
+  disposers.push(register(defineTool({
+    name: 'taskboard_update',
+    description:
+      'Update a task\'s title/description/prompt/urgency/blocked. Requires ifVersion (read first). '
+      + 'The model and execution config are read-only through this tool (they belong to the task owner/user).',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+      ifVersion: { type: 'number', required: true, description: 'The task version you read; the write fails on mismatch.' },
+      title: { type: 'string', description: 'New title.' },
+      description: { type: 'string', description: 'New description.' },
+      prompt: { type: 'string', description: 'New execution prompt.' },
+      urgency: { type: 'string', description: 'urgent | normal | relaxed.' },
+      blocked: { type: 'boolean', description: 'Blocked marker (work cannot continue right now).' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const t = v.task
+        return [{ type: 'text', text: t === undefined ? '更新失败。' : `已更新任务 ${t.id}，当前 v${t.version} [${t.status}]。` }]
+      },
+    },
+    async execute(args: {
+      id: string
+      ifVersion: number
+      title?: string
+      description?: string
+      prompt?: string
+      urgency?: string
+      blocked?: boolean
+    }, exec: unknown) {
+      try {
+        const { actor } = caller(exec as ToolRunContext)
+        const task = store.get(args.id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        versionGuard(task, args.ifVersion)
+        if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
+        const next: TaskRecord = structuredClone(task)
+        if (args.title !== undefined) next.title = normalizeTitle(args.title)
+        if (args.description !== undefined) next.description = args.description.trim()
+        if (args.prompt !== undefined) next.prompt = normalizePrompt(args.prompt)
+        if (args.urgency !== undefined) next.urgency = asUrgency(args.urgency)
+        if (args.blocked !== undefined) next.blocked = args.blocked
+        next.version = task.version + 1
+        next.updatedAt = deps.now()
+        next.updatedBy = actor
+        await store.mutate('task-updated', ledger => {
+          const i = ledger.tasks.findIndex(t => t.id === args.id)
+          ledger.tasks[i] = next
+          return [next]
+        })
+        return json({ task: summarize(next) })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ------------------------------------------------------------------ move
+  disposers.push(register(defineTool({
+    name: 'taskboard_move',
+    description:
+      'Move a task between statuses (requires ifVersion). Claim = todo→in_progress (only a session '
+      + 'inside the task\'s project may claim; never take over a task held by another session). '
+      + 'After implementing and self-verifying: comment, then in_progress→in_review. '
+      + 'You can NEVER move a task to done — that requires explicit user confirmation.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+      status: { type: 'string', required: true, description: 'Target status.' },
+      ifVersion: { type: 'number', required: true, description: 'Task version you read; fails on mismatch.' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const t = v.task
+        return [{ type: 'text', text: t === undefined ? '移动失败。' : `任务 ${t.id} 已移到 ${t.status}，当前 v${t.version}。` }]
+      },
+    },
+    async execute(args: { id: string; status: string; ifVersion: number }, exec: unknown) {
+      try {
+        const { actor } = caller(exec as ToolRunContext)
+        const to = asStatus(args.status)
+        const task = store.get(args.id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        versionGuard(task, args.ifVersion)
+
+        // Code-level gate: agents never complete a task.
+        if (to === 'done') {
+          throw new ToolError(ERR.forbidden, 'moving a task to done requires explicit user confirmation (GUI); agents cannot do it')
+        }
+        if (!canTransition(task.status, to)) {
+          throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`)
+        }
+        // Exclusive hold: while a task is in_progress under an agent, no other
+        // session may move it at all (that would be a takeover).
+        if (task.status === 'in_progress' && task.updatedBy.kind === 'agent' && task.updatedBy.sessionId !== actor.sessionId) {
+          throw new ToolError(ERR.forbidden, `task is held by session ${task.updatedBy.sessionId}; never take over another session's claim`)
+        }
+        // Claim boundary: the calling session must belong to the task's project.
+        if (isClaim(task.status, to)) {
+          const wsId = await callerWorkspace(deps, exec as ToolRunContext)
+          if (wsId !== task.workspaceId) {
+            throw new ToolError(ERR.workspaceMismatch, 'only a session inside this task\'s project may claim it')
+          }
+        }
+        const next: TaskRecord = structuredClone(task)
+        next.status = to
+        next.version = task.version + 1
+        next.updatedAt = deps.now()
+        next.updatedBy = actor
+        if (isClaim(task.status, to)) next.blocked = false
+        await store.mutate('task-moved', ledger => {
+          const i = ledger.tasks.findIndex(t => t.id === args.id)
+          ledger.tasks[i] = next
+          return [next]
+        })
+        return json({ task: summarize(next) })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ----------------------------------------------------------- comment_add
+  disposers.push(register(defineTool({
+    name: 'taskboard_comment_add',
+    description:
+      'Append a progress/report comment to a task. When handing off to review, the comment should cover: '
+      + 'what changed, how it was verified, outcome, and remaining risks.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+      body: { type: 'string', required: true, description: 'Comment text (1..4000 chars).' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { comment?: { id?: string }; task?: { id?: string; version?: number; status?: string } }
+        const c = v.comment
+        const t = v.task
+        if (c === undefined || t === undefined) return [{ type: 'text', text: '评论失败。' }]
+        // The comment bumped the version — echo it so the agent can chain the
+        // next write (e.g. move → in_review) WITHOUT re-reading.
+        return [{
+          type: 'text',
+          text: `评论 ${c.id} 已添加；任务 ${t.id} 当前 v${t.version} [${t.status}]（后续写操作用此版本号）.`,
+        }]
+      },
+    },
+    async execute(args: { id: string; body: string }, exec: unknown) {
+      try {
+        const { sessionId } = caller(exec as ToolRunContext)
+        const task = store.get(args.id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        const comment = {
+          id: newCommentId(),
+          body: normalizeBody(args.body),
+          version: 1,
+          createdAt: deps.now(),
+          threadId: sessionId,
+        }
+        const next: TaskRecord = structuredClone(task)
+        next.comments.push(comment)
+        next.version = task.version + 1
+        next.updatedAt = deps.now()
+        await store.mutate('comment-added', ledger => {
+          const i = ledger.tasks.findIndex(t => t.id === args.id)
+          ledger.tasks[i] = next
+          return [next]
+        })
+        return json({ comment, task: { id: next.id, version: next.version, status: next.status } })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // -------------------------------------------------------------- comments
+  disposers.push(register(defineTool({
+    name: 'taskboard_comments',
+    description: 'List a task\'s comments, oldest first. Read them before deciding to start work.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { comments?: unknown[] }
+        const list = v.comments as Array<{ body: string; createdAt: number; threadId?: string }> | undefined
+        if (list === undefined || list.length === 0) return [{ type: 'text', text: '无评论。' }]
+        const lines = list.map(c => {
+          const who = c.threadId !== undefined ? `agent ${String(c.threadId).slice(0, 24)}` : 'user'
+          return `- [${who} ${new Date(c.createdAt).toISOString()}] ${c.body}`
+        })
+        return [{ type: 'text', text: `评论 ${list.length} 条：\n${lines.join('\n')}` }]
+      },
+    },
+    async execute(args: { id: string }) {
+      try {
+        const task = store.get(args.id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        return json({ comments: task.comments })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ---------------------------------------------------------------- delete
+  disposers.push(register(defineTool({
+    name: 'taskboard_delete',
+    description:
+      'Soft-delete a task (marks it trashed; the user confirms the purge in the GUI). '
+      + 'Requires ifVersion. Prefer canceled/archived over delete unless the task was a mistake.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+      ifVersion: { type: 'number', required: true, description: 'Task version you read.' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { trashed?: boolean }
+        return [{ type: 'text', text: v.trashed === true ? '任务已标记删除（等待用户在 GUI 清除）。' : '删除失败。' }]
+      },
+    },
+    async execute(args: { id: string; ifVersion: number }, exec: unknown) {
+      try {
+        caller(exec as ToolRunContext)
+        const task = store.get(args.id)
+        if (task === undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        versionGuard(task, args.ifVersion)
+        const next: TaskRecord = structuredClone(task)
+        next.trashedAt = deps.now()
+        next.version = task.version + 1
+        await store.mutate('task-deleted', ledger => {
+          const i = ledger.tasks.findIndex(t => t.id === args.id)
+          ledger.tasks[i] = next
+          return [next]
+        })
+        return { trashed: true }
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  return disposers
+}