@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/builtins/todo-schema.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+
+import {
+  isToolNamed,
+  TODO_FORMER_NAMES,
+  TODO_TOOL_NAME,
+} from '../tools/builtin-names.js';
+
+/**
+ * Agent 的待办清单 —— `Todo` 工具（原 `TodoWrite`）的入参形状，前后端共用。
+ *
+ * ## 它没有存储层，这是有意的
+ *
+ * 清单**不落业务表、不加 DDL、后端不持任何状态**：`Todo` 是纯记账工具，
+ * 一次调用把**整份清单**原样写进这次 tool-call 的入参，那条 `chat_message`
+ * 行就是它唯一的存放处。于是「当前清单」= 历史里最后一次 `Todo` 的入参，
+ * 前端按这个纯函数派生（`latestTodoList`）。
+ *
+ * 这么定的直接好处是它自动搭上了上下文预算那套机制：裁剪只把 tool-result 的
+ * **正文**换成存根、**tool-call 的入参原封不动**（见
+ * `parts-to-model-messages.ts`），所以清单被裁进阴影区之后模型照样看得见。
+ * 反过来，若把清单存去别处，就得再造一条「压缩之后把它送回上下文」的路
+ * —— Claude Code 正是因为存在会话文件里才必须那么做。
+ *
+ * ## 全量替换，没有增量
+ *
+ * 每次调用给的都是完整清单，改一条状态也要把五条一起发回来。少一个 patch
+ * 语义就少一整类「服务端与模型各持半份、谁也不知道对方改了什么」的 bug，
+ * 而代价（重发几十个 token）在这个体量下不值一提。**也正因为是全量，
+ * 才不需要一个读取工具**：最新一份就在模型自己上一次的入参里。
+ */
+
+/**
+ * 一条待办的三态。
+ *
+ * 刻意只有三个：`pending` 还没开始、`in_progress` 正在做、`completed` 做完了。
+ * 「阻塞中」「已放弃」这类第四态每次都有人想加，但模型表达它们的地方是对话正文
+ * （说清为什么卡住），不是这个枚举——多一个状态就多一处界面要渲染、多一条
+ * 模型要判断的规则，而它换回来的信息，一句话本来就说得更清楚。
+ */
+export const TODO_STATUSES = ['pending', 'in_progress', 'completed'] as const;
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+
+/**
+ * 单条待办。**只有正文与状态两个字段**。
+ *
+ * 刻意不要 Claude Code 那个 `activeForm`（同一件事的进行时说法，「加工具」→
+ * 「正在加工具」）：那是终端底部那行 spinner 逼出来的字段——一行的地方放不下
+ * 整份清单，只能显示当前这条的进行时。我们的界面上进行中那条本来就带着描边
+ * 待在清单里，不缺这个提示，而多一个字段就是多一份模型每次都要写对的东西。
+ */
+export const TodoItemSchema = z.object({
+  /**
+   * 一句话说清这一步要做什么。
+   *
+   * 200 字符上限是**拒绝**不是截断：清单是拿来扫的，一条写成一段的待办在面板
+   * 里会挤掉其余全部，而截断会把「做什么」最关键的后半句吃掉、还看不出被吃过。
+   */
+  content: z.string().trim().min(1).max(200),
+  status: z.enum(TODO_STATUSES),
+});
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+
+/**
+ * 整份清单。**顺序原样保留**——那是任务的依赖顺序（先定 schema 才谈得上写
+ * 实现），工具与后端一律不重排。界面按状态分组显示是另一层的取舍，且只重排
+ * 组、不动组内（见 portal / web 的待办面板）。
+ *
+ * 50 条上限同样是拒绝：真拆到 50 步的任务，缺的是再拆一层子任务（或派个子
+ * Agent），不是更长的清单。
+ */
+export const TodoListSchema = z.array(TodoItemSchema).max(50);
+
+/**
+ * 从一次 `Todo` 调用的入参里取出清单。
+ *
+ * **必须走 zod 而不是 `as`**，且有两处**都会正常发生**、必须落到 null 的情形：
+ *
+ * 1. **参数还在流式生成**：`tool-call` 事件要等整个 step 的流消费完才发，在那
+ *    之前入参是半截的（甚至是 `undefined`）。
+ * 2. **历史形状变过**：老会话里存的是当时那一版的入参。
+ *
+ * 两者都返回 null，由调用方决定怎么办——面板的做法是**继续用上一份**而不是
+ * 清空，否则每更新一次待办，面板就会闪一下空白再长回来。
+ */
+export function parseTodoInput(input: unknown): TodoItem[] | null {
+  if (input === null || typeof input !== 'object') return null;
+  const raw = (input as Record<string, unknown>).todos;
+  const parsed = TodoListSchema.safeParse(raw);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * 当前清单 = 历史里最后一次 `Todo` 调用的入参（现名或旧名都认）。`calls` 按发生顺序给；
+ * 最后一次解析不了（还在流式生成 / 老形状）就往前找上一份——面板**继续用上一份**而不是
+ * 清空，否则每更新一次待办就闪一下空白。一次都没有返回 null。
+ */
+export function latestTodoList(
+  calls: ReadonlyArray<{ toolName: string; input: unknown }>
+): TodoItem[] | null {
+  for (let i = calls.length - 1; i >= 0; i--) {
+    const c = calls[i];
+    if (!isToolNamed(c.toolName, TODO_TOOL_NAME, TODO_FORMER_NAMES)) continue;
+    const items = parseTodoInput(c.input);
+    if (items) return items;
+  }
+  return null;
+}

package/src/builtins/todo-settle.hook.ts

@@ -0,0 +1,221 @@
+/**
+ * 待办推进提醒：一轮结束时清单里还有没做完的条目，就投一条提醒、换一轮让模型
+ * 接着做（或至少把账结掉）。
+ *
+ * **它治的是模型的工作方式，不是逻辑错误**（2026-09-07 真库取证，会话
+ * `ad03599a` 与 `621632d1`）：模型列完清单后把某条置 in_progress、用正文把这条
+ * 做完，然后**停下来问「要不要继续」**——既不把它翻成 completed，也不接着做
+ * 下一条，两件事都要等用户下一句话。前端面板是「最后一次 Todo 入参」的
+ * 纯函数，只能照着显示；用户看到的就是「待办不会自己更新」「列了清单还是要
+ * 一步一步催」。
+ *
+ * ## 为什么是换一轮，而不是在本轮内多跑一步
+ *
+ * 提醒必须以 user 行进上下文（红线「模型看得见的一切都必须能从库里重建」），而
+ * 一条 user 行插在**正在跑的这一轮中间**，落库顺序就是错的：assistant 行的 seq
+ * 是它首次落库时取的，提醒行必然排在整条 assistant 行**之后**，刷新后模型的
+ * 回应会显示在提醒前面。「轮内插 user 行」那套切段机制正是因此被整块拆掉的
+ * （见 `TurnHost.hasPendingInbox`）。走 inbox + 换轮，顺序天然正确，新 runId /
+ * 新 assistant 行 / SSE 全由既有的 re-wake 白拿——本文件因此**零内核改动**，只是
+ * `observe('replied')` 上的一个事后动作。
+ *
+ * ## 两半合一个扩展
+ *
+ * 一个 hook 类只能挂一个 point（`hooks.register` 的 meta 是单数），而这件事
+ * 要看两处：`preToolUse` 记本轮最后一次 `Todo` 的入参，`observe` 在收尾时
+ * 判断并投递。两个类共用 `turnState` 里的**同一个槽**（键 `TODO_SETTLE_STATE_KEY`
+ * ——`turnStateOf` 那条「键用插件自己的 name」的规矩在这里让位于「一个扩展一个
+ * 槽」，两半的 name 各不相同、槽只有一个）。
+ *
+ * ## 三道闸门（改反了要么来回催、要么催不动）
+ *
+ * 1. **本轮写过清单才提醒**：从没写过、或上一轮遗留的未完成本轮没碰，都不管。
+ *    后者没有更好的判据——再催一次的收益比不上把每一轮都变成两轮的代价。
+ * 2. **回应提醒的那一轮只有「有推进」才再催**：提醒里带着投出时的完成数
+ *    （`metadata.completed`），本轮收尾时完成数比它大才允许再投。最初的版本是
+ *    「回应提醒的那轮一律不催」，真机上模型被催着做完一条后**又**停下来问，第二次
+ *    提醒就被挡掉了（会话 `621632d1`）。改成按推进判：模型每被催一次至少多做完
+ *    一条，清单至多 50 条，所以有界；模型答「确实在等用户」而不动清单，完成数
+ *    不涨，立刻停催——没有死循环的口子。
+ * 3. **只管根会话**（`depth === 0`）：子会话收尾后父会立刻拿它最后一条 assistant
+ *    行当终态（`finalizeIfIdle`），再往它 inbox 投东西会多出一轮、多出一份回执。
+ *
+ * 只在 `replied`（正常收尾）上投：中断与失败的一轮，模型没把话说完，清单状态本
+ * 来就说不上「做没做完」。
+ *
+ * **接受的代价**：模型合法地停下来等用户（用户明说「先只做第一步」、或它真需要
+ * 一个决定）时，也会收到一次提醒并回一句「在等你」——一次换轮、一条标记、一句话。
+ * 换来的是「列了清单就会做完」这条用户可以依赖的默契。
+ */
+
+import type { TurnHookRegistry } from '../hooks/turn-hook.registry.js';
+import {
+  type ObservePhase,
+  type PreToolUseResult,
+  type TurnContext,
+  type TurnHookImpl,
+  type TurnHookMeta,
+  turnStateOf,
+} from '../hooks/turn-hook.types.js';
+import type { MessageHub } from '../loop/message-hub.js';
+import type { WakeChannel } from '../ports/coordination.js';
+import { TODO_REMINDER_KIND } from '../schema/index.js';
+import { TODO_TOOL_NAME } from '../tools/builtin-names.js';
+import { parseTodoInput, type TodoItem } from './todo-schema.js';
+
+/** 两半共用的 `turnState` 键（见文件头「两半合一个扩展」）。 */
+export const TODO_SETTLE_STATE_KEY = 'todo-settle';
+
+interface TodoSettleState {
+  /** 本轮最后一次 `Todo` 的入参（原样，解析放到收尾时做）。 */
+  lastInput: unknown;
+}
+
+/**
+ * 记账半：记下本轮最后一次 `Todo` 的入参。
+ *
+ * **记在发起处、不看结果**：被拒绝的那次（两条 in_progress）同样记——它的清单里
+ * 必然有没做完的，收尾时会因此提醒，而模型正该借这一轮把清单修好。
+ */
+export const TODO_SETTLE_TRACK_META: TurnHookMeta = {
+  name: 'todo-settle-track',
+  point: 'preToolUse',
+  tools: [TODO_TOOL_NAME],
+  order: 20,
+  onError: 'open',
+};
+
+export class TodoSettleTrackHook implements TurnHookImpl {
+  preToolUse(
+    ctx: TurnContext,
+    _toolName: string,
+    input: unknown
+  ): Promise<PreToolUseResult> {
+    const state = turnStateOf<TodoSettleState>(
+      ctx,
+      TODO_SETTLE_STATE_KEY,
+      () => ({ lastInput: undefined })
+    );
+    state.lastInput = input;
+    return Promise.resolve({ action: 'continue' });
+  }
+}
+
+/**
+ * 投递半：收尾时清单里还有没做完的就投提醒、唤醒。
+ *
+ * 投递用 `MessageHub.post` + `WakeChannel.wake`，与子 Agent 回投同一条路
+ * （`SubagentSessions.finalizeIfIdle`）；本轮此刻还持有会话锁，wake 只是让 loop 在
+ * 释放锁后的那次自查里看到有货。
+ */
+export const TODO_SETTLE_REMINDER_META: TurnHookMeta = {
+  name: 'todo-settle-reminder',
+  point: 'observe',
+  order: 20,
+  onError: 'open',
+};
+
+export class TodoSettleReminderHook implements TurnHookImpl {
+  constructor(
+    private readonly hub: MessageHub,
+    private readonly waker: Pick<WakeChannel, 'wake'>
+  ) {}
+
+  async observe(ctx: TurnContext, phase: ObservePhase): Promise<void> {
+    if (phase !== 'replied') return;
+    if (ctx.depth !== 0) return;
+    const state = ctx.turnState.get(TODO_SETTLE_STATE_KEY) as
+      TodoSettleState | undefined;
+    if (!state) return;
+    const digest = digestTodos(state.lastInput);
+    if (digest.unfinished.length === 0) return;
+    if (!hasProgressSinceReminder(ctx, digest.completed)) return;
+
+    await this.hub.post({
+      sessionId: ctx.sessionId,
+      kind: 'system_reminder',
+      sourceKind: 'system',
+      // `completed` 随行落进 metadata，回应这条提醒的那一轮据此判「有没有推进」
+      // （闸门 2）。前端只读 `kind`。
+      source: {
+        kind: TODO_REMINDER_KIND,
+        completed: digest.completed,
+        total: digest.total,
+      },
+      parts: [{ type: 'text', text: renderTodoSettleReminder(digest) }],
+    });
+    await this.waker.wake(ctx.sessionId);
+  }
+}
+
+export interface TodoDigest {
+  total: number;
+  completed: number;
+  /** 没做完的（进行中 + 未开始），保持清单原序。 */
+  unfinished: TodoItem[];
+  /** 正在做的那条；零条合法。 */
+  active: TodoItem | null;
+}
+
+/** 一份入参的三个数；形状对不上（半截、老版本）按空清单处理。 */
+export function digestTodos(input: unknown): TodoDigest {
+  const items = parseTodoInput(input) ?? [];
+  const unfinished = items.filter(t => t.status !== 'completed');
+  return {
+    total: items.length,
+    completed: items.length - unfinished.length,
+    unfinished,
+    active: items.find(t => t.status === 'in_progress') ?? null,
+  };
+}
+
+/**
+ * 闸门 2：这一轮不是在回应提醒 → 放行；是 → 只有完成数比提醒投出时大才放行。
+ *
+ * 提醒行的 `completed` 缺失（老数据、别处投的）按「没推进」处理——方向是宁可
+ * 少催一次，也不在拿不到判据时无限催。
+ */
+export function hasProgressSinceReminder(
+  ctx: Pick<TurnContext, 'inbound'>,
+  completedNow: number
+): boolean {
+  const reminder = ctx.inbound
+    .map(m => m.metadata)
+    .find(md => md?.kind === TODO_REMINDER_KIND);
+  if (!reminder) return true;
+  const before = reminder.completed;
+  return typeof before === 'number' && completedNow > before;
+}
+
+/**
+ * 提醒文案。**说三件事**：还剩几条（点名进行中那条）、直接接着做别问要不要继续、
+ * 做完的要置 completed；再给一条出路——确实在等用户就说清在等什么、别动清单。
+ * 只说前三件的话，模型会为了「服从」把一条确实要等用户的事硬做下去或标成完成。
+ * 末句挡住最常见的画蛇添足：先把刚交付的正文复述一遍。
+ */
+export function renderTodoSettleReminder(digest: TodoDigest): string {
+  const active = digest.active
+    ? `，其中「${digest.active.content}」仍是 in_progress`
+    : '';
+  return (
+    `这一轮回复已经结束，但待办清单里还有 ${digest.unfinished.length} 条没做完` +
+    `（共 ${digest.total} 条）${active}。` +
+    '列了清单就意味着要连续做完它：如果不需要用户提供信息或做决定，直接接着做' +
+    '下一条，不要停下来问「要不要继续」；做完的条目用 Todo 置 completed' +
+    '（用正文交付的也算做完），其余条目原样带上。' +
+    '如果确实在等用户答复，说清在等什么即可，不必更新清单。' +
+    '不要复述已经交付的内容。'
+  );
+}
+
+/** 把待办推进提醒的两半挂到注册表上（runtime 的通用扩展，宿主可以不挂）。 */
+export function registerTodoSettleHooks(
+  hooks: TurnHookRegistry,
+  deps: { hub: MessageHub; wake: Pick<WakeChannel, 'wake'> }
+): void {
+  hooks.register(TODO_SETTLE_TRACK_META, new TodoSettleTrackHook());
+  hooks.register(
+    TODO_SETTLE_REMINDER_META,
+    new TodoSettleReminderHook(deps.hub, deps.wake)
+  );
+}

package/src/builtins/todo.tool.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+
+import { AgentTool } from '../tools/agent-tool.base.js';
+import { TODO_FORMER_NAMES, TODO_TOOL_NAME } from '../tools/builtin-names.js';
+import type { ToolMeta } from '../tools/tool-meta.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { toolError, type ToolOut } from '../tools/tool-result.js';
+import {
+  type TodoItem,
+  TodoListSchema,
+  type TodoStatus,
+} from './todo-schema.js';
+
+const InputSchema = z.object({
+  todos: TodoListSchema.describe(
+    '完整的待办清单，按执行顺序排列。每次都要给全份——本次入参会整份取代上一份。'
+  ),
+});
+type Input = z.infer<typeof InputSchema>;
+
+interface Out {
+  todos: TodoItem[];
+}
+
+/** 状态 → 回执里的说法。清单本身的顺序不动，这只是计数时的分组名。 */
+const STATUS_LABELS: Record<TodoStatus, string> = {
+  in_progress: '进行中',
+  pending: '未开始',
+  completed: '已完成',
+};
+
+/**
+ * 待办清单记账工具的登记信息。
+ *
+ * **它没有 service、不写任何表、没有副作用**——这次调用的入参就是清单本身的
+ * 存放处（判据全文见 `todo-schema.ts`）。所以 `run()` 里除了
+ * 一道守卫之外无事可做，这不是没写完。
+ *
+ * 它同时是第一个声明 `accounting: true` 的工具：记账不算「做了别的事」，
+ * 夹在两次相同调用中间不该打断重复调用链的计数（见 `runtime/loop-reminder.ts`）。
+ */
+export const TODO_TOOL_META: ToolMeta = {
+  name: TODO_TOOL_NAME,
+  formerNames: TODO_FORMER_NAMES,
+  description:
+    '把当前任务拆成一份待办清单，并在推进过程中随时更新它。多步骤、要跨很多次' +
+    '工具调用才能收尾的活儿用它记账：既让你自己不丢步骤，用户也能在界面上看到' +
+    '进度。**每次都要发完整清单**——只改一条的状态也要把其余各条一并带上，' +
+    '本次入参会整份取代上一份。' +
+    '**列清单之前先把要用户拍板的事问清**（范围、粒度、口径这类），或者自己定' +
+    '一个合理默认并写明；不要开工之后做到一半再回头问。' +
+    '**一条一条来**：开始做某一条时把它置 in_progress，这一条的正文写完就立刻' +
+    '再调一次把它置 completed、把下一条置 in_progress，然后才写下一条——' +
+    '不要把几条的内容写在同一段正文里再一起改状态；同一时刻至多一条 in_progress。' +
+    '**列了清单就意味着你会连续做完它**：做完一条紧接着做下一条，不要每完成' +
+    '一条就停下来问「要不要继续」——只有需要用户提供信息或做决定时才停，并说清' +
+    '在等什么。**结束回复之前必须结账**：正文交付的条目，正文写完就算做完，' +
+    '收尾前把它置 completed，不要留到用户下一句话再改。' +
+    '三两步就能答完的请求不必用它，为此记账反而更慢。',
+  category: 'system',
+  // 纯记账、零副作用 → 对重复调用链透明（见 `ToolMeta.accounting`）。
+  accounting: true,
+};
+
+/** 待办清单记账工具（原名见 `TODO_FORMER_NAMES`）。 */
+export class TodoTool extends AgentTool<Input, Out> {
+  readonly inputSchema = InputSchema;
+
+  protected run(input: Input): Promise<ToolOut<Out>> {
+    const running = input.todos.filter(t => t.status === 'in_progress');
+    // 至多一条「进行中」。**拒绝而不是替它挑一条**：多条并行进行中在界面上会让
+    // 「现在做到哪了」这个问题失去唯一答案，而模型实际上就是一次做一件事。
+    // 反过来**零条是合法的**——全部做完的那一次，以及刚列出计划还没动手的那
+    // 一次，都没有进行中的条目，把它也拦掉会逼出一条假的 in_progress。
+    if (running.length > 1) {
+      return Promise.resolve(
+        toolError(
+          `同一时刻至多一条待办可以是 in_progress，这次给了 ${running.length} 条：` +
+            `${running.map(t => t.content).join('、')}。` +
+            '挑一条正在做的置 in_progress，其余退回 pending。'
+        )
+      );
+    }
+    return Promise.resolve({ kind: 'ok', todos: input.todos });
+  }
+
+  /**
+   * 回执**只给一行计数，不复述整份清单**。
+   *
+   * 清单原文就在这次调用的入参里，模型下一步照样看得见；把它在输出里再抄一遍
+   * 是纯粹的重复计费。而这条回执本身还会在裁剪时被换成存根（入参不会），
+   * 所以复述的那份清单是活不过裁剪的那一份。
+   */
+  protected render(out: { kind: 'ok' } & Out): string {
+    if (out.todos.length === 0) {
+      return '待办清单已清空。';
+    }
+    const counts = new Map<TodoStatus, number>();
+    for (const t of out.todos) {
+      counts.set(t.status, (counts.get(t.status) ?? 0) + 1);
+    }
+    // 按 STATUS_LABELS 的键序（进行中 → 未开始 → 已完成）报，且**零的那档不报**
+    // ——「已完成 0 条」是噪音，而没有进行中的条目本就是合法状态。
+    const parts = (Object.keys(STATUS_LABELS) as TodoStatus[])
+      .filter(s => (counts.get(s) ?? 0) > 0)
+      .map(s => `${STATUS_LABELS[s]} ${counts.get(s) ?? 0}`);
+    const summary = `待办清单已更新，共 ${out.todos.length} 条（${parts.join(' / ')}）。`;
+    // 有进行中的那条就顺带提一句结账。**放在回执里而不是只写在 description**：
+    // 模型读这句话的时刻恰好是它要动手做这条的前一刻，而 description 在几十轮
+    // 之前的 system prompt 里。真正的兜底在收尾时（`extensions/todo-settle.hook.ts`），
+    // 这句是零成本的那一层——它管用一次，就省下一整轮换轮。
+    const running = out.todos.find(t => t.status === 'in_progress');
+    if (!running) return summary;
+    const remaining = out.todos.filter(t => t.status === 'pending').length;
+    // 还有没开始的就顺带说「接着做别问」：模型最常见的走样是做完一条停下来问
+    // 「要不要继续」（会话 621632d1），而它读这句话的时刻正是决定做完这条之后
+    // 干什么的时刻。
+    const next =
+      remaining > 0
+        ? `更新完再写下一条（还有 ${remaining} 条没开始），一条一条来，不要停下来问要不要继续。`
+        : '';
+    return (
+      `${summary}「${running.content}」进行中——只写这一条的内容，写完立刻` +
+      `再调一次 Todo 把它置 completed（用正文交付的也算做完）。${next}`
+    );
+  }
+}
+
+/** 登记 `Todo`。 */
+export function registerTodoTool(tools: ToolRegistry): TodoTool {
+  const tool = new TodoTool();
+  tools.register(TODO_TOOL_META, tool);
+  return tool;
+}