@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/builtins/ask.tool.js

@@ -0,0 +1,109 @@
+import { AgentTool } from '../tools/agent-tool.base.js';
+import { ASK_FORMER_NAMES, ASK_TOOL_NAME } from '../tools/builtin-names.js';
+import { toolError } from '../tools/tool-result.js';
+import { renderOutcomeResult } from './ask-outcome.js';
+import { AskInputSchema } from './ask-schema.js';
+/** `Ask` 的登记信息。 */
+export const ASK_TOOL_META = {
+    name: ASK_TOOL_NAME,
+    formerNames: ASK_FORMER_NAMES,
+    description: '向用户提一到四个选择题，并**等用户回答后返回**。用在两种时候：动手之前缺一个' +
+        '只有用户能定的决定（方向、取舍、范围）；或者你有几个方案，需要用户挑。' +
+        '每题 2–4 个互斥选项；界面会自动附一个「其他」让用户自由输入，不要自己写。' +
+        '**给了 `defaultOption` 的题用户可以跳过**（按它算，结果里会标明这一题不是用户' +
+        '亲手选的）；你没法替用户猜的事不要给默认项，那一题就是必答。' +
+        '你有倾向时把推荐的选项放第一个，并在它的 label 末尾写「（推荐）」。' +
+        '用户回答之前你说不了话——要对用户说的（为什么问、各选项的背景）写在调用之前' +
+        '的正文里。用户也可能不点选项、改为直接打字回复，那时返回值会告诉你，他的话在' +
+        '紧随其后的那条消息里。' +
+        '`timeoutSeconds`：只在「用户不在也该接着干」且默认项安全、事后能改时才给' +
+        '（风格、篇幅这类偏好），到点按每一题的 `defaultOption` 继续。会覆盖或删除' +
+        '用户的东西、对外发送、或无法撤销的决定**不要给超时**，一直等到用户回答。' +
+        '不要用它问自己能查到的事（先用工具查）；不要问「要不要继续」「这样可以吗」' +
+        '这类客套确认；一次把要问的问全（最多 4 题），不要连着问好几次。',
+    // 每个 agent 都有；端不端上桌由宿主按 `AskService.availableFor` 摘（`excludeTools`）。
+    category: 'system',
+};
+/**
+ * 向用户提问，**等到有了结局再返回**（原名见 `ASK_FORMER_NAMES`）。
+ *
+ * 同步工具：这一轮不结束，模型拿到回答接着干。为什么不做成「问完本轮就结束、
+ * 回答再唤醒下一轮」，见 `AskService` 的类注释。
+ *
+ * 等待由服务负责（`waitForOutcome`）；`ctx.abortSignal` 是「用户中止 ∪ 本工具超时」
+ * 的合成信号，两种情形服务都会把问题作废再返回。
+ */
+export class AskTool extends AgentTool {
+    questions;
+    // 交叉校验（限时必须有默认项、默认项必须是选项之一）写在 schema 上；类型标注
+    // 只为满足基类的 `z.ZodType<TInput>`（`multiSelect` 有缺省值，入参类型比出参宽）。
+    inputSchema = AskInputSchema;
+    /**
+     * 比服务里的等待上限多留两分钟：上限到点由服务把问题**作废**并正常返回一句话，
+     * 不该让基类的超时抢先把它变成一条「工具执行超时」的错误。
+     */
+    timeoutMs;
+    constructor(questions) {
+        super();
+        this.questions = questions;
+        this.timeoutMs = (questions.maxWaitSeconds + 120) * 1000;
+    }
+    async run(raw, ctx) {
+        // 自己再 parse 一次：不假定入参跑过 schema 上那几条交叉校验，而它们每一条都
+        // 对应一个「落了行才发现问不下去」的问题。
+        const parsed = AskInputSchema.safeParse(raw);
+        if (!parsed.success) {
+            return toolError(`入参不合法：${parsed.error.issues
+                .map(i => `${i.path.join('.')}：${i.message}`)
+                .join('；')}`);
+        }
+        const asked = await this.questions.ask({
+            sessionId: ctx.sessionId,
+            runId: ctx.runId,
+            toolCallId: ctx.toolCallId,
+            request: parsed.data,
+        });
+        if (!asked.ok)
+            return toolError(asked.message);
+        const settled = await this.questions.waitForOutcome(asked.question.id, ctx.abortSignal);
+        return {
+            kind: 'ok',
+            questionId: asked.question.id,
+            text: renderOutcomeResult(settled
+                ? {
+                    status: settled.status,
+                    questions: settled.questions,
+                    answers: settled.answers,
+                    waitedSeconds: parsed.data.timeoutSeconds ?? null,
+                }
+                : // 那一行没了（会话被删）：按作废说。
+                    {
+                        status: 'cancelled',
+                        questions: parsed.data.questions,
+                        answers: null,
+                        waitedSeconds: null,
+                    }),
+        };
+    }
+    render(out) {
+        return out.text;
+    }
+    /** 界面按它把那一行问题对到这张工具卡上。 */
+    persistRef(out) {
+        return out.kind === 'ok' ? { questionId: out.questionId } : undefined;
+    }
+    /**
+     * 钉住，不许上下文裁剪换成存根：这是一两句话的**用户决定**，裁掉之后模型无从
+     * 重新得知，只会按自己的猜测往下写、或把同一个问题再问一遍。
+     */
+    persistPinned(out) {
+        return out.kind === 'ok';
+    }
+}
+/** 登记 `Ask`。 */
+export function registerAskTool(tools, service) {
+    const tool = new AskTool(service);
+    tools.register(ASK_TOOL_META, tool);
+    return tool;
+}
+//# sourceMappingURL=ask.tool.js.map

package/dist/builtins/ask.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.tool.js","sourceRoot":"","sources":["../../src/builtins/ask.tool.ts"],"names":[],"mappings":"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"}

package/dist/builtins/index.d.ts

@@ -0,0 +1,8 @@
+export { ASK_MAX_WAIT_SECONDS, ASK_POLL_INTERVAL_MS, ASK_TIMEOUT_MAX_DEFAULT, ASK_TIMEOUT_MIN_DEFAULT, AskAnswerError, type AskOutcome, AskService, type AskServiceDeps, type SettledQuestion, toQuestionWire, } from './ask.service.js';
+export { ASK_TOOL_META, AskTool, registerAskTool } from './ask.tool.js';
+export { type AnswerValidation, defaultAnswers, describeWait, type QuestionOutcome, renderOutcomeResult, validateAnswers, } from './ask-outcome.js';
+export * from './ask-schema.js';
+export { registerTodoTool, TODO_TOOL_META, TodoTool } from './todo.tool.js';
+export * from './todo-schema.js';
+export * from './todo-settle.hook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builtins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EACd,KAAK,UAAU,EACf,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EACL,KAAK,gBAAgB,EACrB,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC5E,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/builtins/index.js

@@ -0,0 +1,8 @@
+export { ASK_MAX_WAIT_SECONDS, ASK_POLL_INTERVAL_MS, ASK_TIMEOUT_MAX_DEFAULT, ASK_TIMEOUT_MIN_DEFAULT, AskAnswerError, AskService, toQuestionWire, } from './ask.service.js';
+export { ASK_TOOL_META, AskTool, registerAskTool } from './ask.tool.js';
+export { defaultAnswers, describeWait, renderOutcomeResult, validateAnswers, } from './ask-outcome.js';
+export * from './ask-schema.js';
+export { registerTodoTool, TODO_TOOL_META, TodoTool } from './todo.tool.js';
+export * from './todo-schema.js';
+export * from './todo-settle.hook.js';
+//# sourceMappingURL=index.js.map

package/dist/builtins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EAEd,UAAU,EAGV,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAEL,cAAc,EACd,YAAY,EAEZ,mBAAmB,EACnB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC5E,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/builtins/todo-schema.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+/**
+ * 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 declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed"];
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+/**
+ * 单条待办。**只有正文与状态两个字段**。
+ *
+ * 刻意不要 Claude Code 那个 `activeForm`（同一件事的进行时说法，「加工具」→
+ * 「正在加工具」）：那是终端底部那行 spinner 逼出来的字段——一行的地方放不下
+ * 整份清单，只能显示当前这条的进行时。我们的界面上进行中那条本来就带着描边
+ * 待在清单里，不缺这个提示，而多一个字段就是多一份模型每次都要写对的东西。
+ */
+export declare const TodoItemSchema: z.ZodObject<{
+    content: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        in_progress: "in_progress";
+    }>;
+}, z.core.$strip>;
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+/**
+ * 整份清单。**顺序原样保留**——那是任务的依赖顺序（先定 schema 才谈得上写
+ * 实现），工具与后端一律不重排。界面按状态分组显示是另一层的取舍，且只重排
+ * 组、不动组内（见 portal / web 的待办面板）。
+ *
+ * 50 条上限同样是拒绝：真拆到 50 步的任务，缺的是再拆一层子任务（或派个子
+ * Agent），不是更长的清单。
+ */
+export declare const TodoListSchema: z.ZodArray<z.ZodObject<{
+    content: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        in_progress: "in_progress";
+    }>;
+}, z.core.$strip>>;
+/**
+ * 从一次 `Todo` 调用的入参里取出清单。
+ *
+ * **必须走 zod 而不是 `as`**，且有两处**都会正常发生**、必须落到 null 的情形：
+ *
+ * 1. **参数还在流式生成**：`tool-call` 事件要等整个 step 的流消费完才发，在那
+ *    之前入参是半截的（甚至是 `undefined`）。
+ * 2. **历史形状变过**：老会话里存的是当时那一版的入参。
+ *
+ * 两者都返回 null，由调用方决定怎么办——面板的做法是**继续用上一份**而不是
+ * 清空，否则每更新一次待办，面板就会闪一下空白再长回来。
+ */
+export declare function parseTodoInput(input: unknown): TodoItem[] | null;
+/**
+ * 当前清单 = 历史里最后一次 `Todo` 调用的入参（现名或旧名都认）。`calls` 按发生顺序给；
+ * 最后一次解析不了（还在流式生成 / 老形状）就往前找上一份——面板**继续用上一份**而不是
+ * 清空，否则每更新一次待办就闪一下空白。一次都没有返回 null。
+ */
+export declare function latestTodoList(calls: ReadonlyArray<{
+    toolName: string;
+    input: unknown;
+}>): TodoItem[] | null;
+//# sourceMappingURL=todo-schema.d.ts.map

package/dist/builtins/todo-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-schema.d.ts","sourceRoot":"","sources":["../../src/builtins/todo-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,kDAAmD,CAAC;AAC9E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;iBASzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;kBAAkC,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,GAAG,IAAI,CAKhE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GACzD,QAAQ,EAAE,GAAG,IAAI,CAQnB"}

package/dist/builtins/todo-schema.js

@@ -0,0 +1,97 @@
+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'];
+/**
+ * 单条待办。**只有正文与状态两个字段**。
+ *
+ * 刻意不要 Claude Code 那个 `activeForm`（同一件事的进行时说法，「加工具」→
+ * 「正在加工具」）：那是终端底部那行 spinner 逼出来的字段——一行的地方放不下
+ * 整份清单，只能显示当前这条的进行时。我们的界面上进行中那条本来就带着描边
+ * 待在清单里，不缺这个提示，而多一个字段就是多一份模型每次都要写对的东西。
+ */
+export const TodoItemSchema = z.object({
+    /**
+     * 一句话说清这一步要做什么。
+     *
+     * 200 字符上限是**拒绝**不是截断：清单是拿来扫的，一条写成一段的待办在面板
+     * 里会挤掉其余全部，而截断会把「做什么」最关键的后半句吃掉、还看不出被吃过。
+     */
+    content: z.string().trim().min(1).max(200),
+    status: z.enum(TODO_STATUSES),
+});
+/**
+ * 整份清单。**顺序原样保留**——那是任务的依赖顺序（先定 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) {
+    if (input === null || typeof input !== 'object')
+        return null;
+    const raw = input.todos;
+    const parsed = TodoListSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * 当前清单 = 历史里最后一次 `Todo` 调用的入参（现名或旧名都认）。`calls` 按发生顺序给；
+ * 最后一次解析不了（还在流式生成 / 老形状）就往前找上一份——面板**继续用上一份**而不是
+ * 清空，否则每更新一次待办就闪一下空白。一次都没有返回 null。
+ */
+export function latestTodoList(calls) {
+    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;
+}
+//# sourceMappingURL=todo-schema.js.map

package/dist/builtins/todo-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-schema.js","sourceRoot":"","sources":["../../src/builtins/todo-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,WAAW,CAAU,CAAC;AAG9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;CAC9B,CAAC,CAAC;AAGH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,GAAG,GAAI,KAAiC,CAAC,KAAK,CAAC;IACrD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAA0D;IAE1D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE,cAAc,EAAE,iBAAiB,CAAC;YAAE,SAAS;QAC1E,MAAM,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/builtins/todo-settle.hook.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 待办推进提醒：一轮结束时清单里还有没做完的条目，就投一条提醒、换一轮让模型
+ * 接着做（或至少把账结掉）。
+ *
+ * **它治的是模型的工作方式，不是逻辑错误**（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 } from '../hooks/turn-hook.types.js';
+import type { MessageHub } from '../loop/message-hub.js';
+import type { WakeChannel } from '../ports/coordination.js';
+import { type TodoItem } from './todo-schema.js';
+/** 两半共用的 `turnState` 键（见文件头「两半合一个扩展」）。 */
+export declare const TODO_SETTLE_STATE_KEY = "todo-settle";
+/**
+ * 记账半：记下本轮最后一次 `Todo` 的入参。
+ *
+ * **记在发起处、不看结果**：被拒绝的那次（两条 in_progress）同样记——它的清单里
+ * 必然有没做完的，收尾时会因此提醒，而模型正该借这一轮把清单修好。
+ */
+export declare const TODO_SETTLE_TRACK_META: TurnHookMeta;
+export declare class TodoSettleTrackHook implements TurnHookImpl {
+    preToolUse(ctx: TurnContext, _toolName: string, input: unknown): Promise<PreToolUseResult>;
+}
+/**
+ * 投递半：收尾时清单里还有没做完的就投提醒、唤醒。
+ *
+ * 投递用 `MessageHub.post` + `WakeChannel.wake`，与子 Agent 回投同一条路
+ * （`SubagentSessions.finalizeIfIdle`）；本轮此刻还持有会话锁，wake 只是让 loop 在
+ * 释放锁后的那次自查里看到有货。
+ */
+export declare const TODO_SETTLE_REMINDER_META: TurnHookMeta;
+export declare class TodoSettleReminderHook implements TurnHookImpl {
+    private readonly hub;
+    private readonly waker;
+    constructor(hub: MessageHub, waker: Pick<WakeChannel, 'wake'>);
+    observe(ctx: TurnContext, phase: ObservePhase): Promise<void>;
+}
+export interface TodoDigest {
+    total: number;
+    completed: number;
+    /** 没做完的（进行中 + 未开始），保持清单原序。 */
+    unfinished: TodoItem[];
+    /** 正在做的那条；零条合法。 */
+    active: TodoItem | null;
+}
+/** 一份入参的三个数；形状对不上（半截、老版本）按空清单处理。 */
+export declare function digestTodos(input: unknown): TodoDigest;
+/**
+ * 闸门 2：这一轮不是在回应提醒 → 放行；是 → 只有完成数比提醒投出时大才放行。
+ *
+ * 提醒行的 `completed` 缺失（老数据、别处投的）按「没推进」处理——方向是宁可
+ * 少催一次，也不在拿不到判据时无限催。
+ */
+export declare function hasProgressSinceReminder(ctx: Pick<TurnContext, 'inbound'>, completedNow: number): boolean;
+/**
+ * 提醒文案。**说三件事**：还剩几条（点名进行中那条）、直接接着做别问要不要继续、
+ * 做完的要置 completed；再给一条出路——确实在等用户就说清在等什么、别动清单。
+ * 只说前三件的话，模型会为了「服从」把一条确实要等用户的事硬做下去或标成完成。
+ * 末句挡住最常见的画蛇添足：先把刚交付的正文复述一遍。
+ */
+export declare function renderTodoSettleReminder(digest: TodoDigest): string;
+/** 把待办推进提醒的两半挂到注册表上（runtime 的通用扩展，宿主可以不挂）。 */
+export declare function registerTodoSettleHooks(hooks: TurnHookRegistry, deps: {
+    hub: MessageHub;
+    wake: Pick<WakeChannel, 'wake'>;
+}): void;
+//# sourceMappingURL=todo-settle.hook.d.ts.map

package/dist/builtins/todo-settle.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-settle.hook.d.ts","sourceRoot":"","sources":["../../src/builtins/todo-settle.hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjE,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAOnD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,YAMpC,CAAC;AAEF,qBAAa,mBAAoB,YAAW,YAAY;IACtD,UAAU,CACR,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC;CAS7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,YAKvC,CAAC;AAEF,qBAAa,sBAAuB,YAAW,YAAY;IAEvD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;IAG7C,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAyBpE;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,mBAAmB;IACnB,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC;CACzB;AAED,oCAAoC;AACpC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAStD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,EACjC,YAAY,EAAE,MAAM,GACnB,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAanE;AAED,8CAA8C;AAC9C,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;CAAE,GACzD,IAAI,CAMN"}

package/dist/builtins/todo-settle.hook.js

@@ -0,0 +1,174 @@
+/**
+ * 待办推进提醒：一轮结束时清单里还有没做完的条目，就投一条提醒、换一轮让模型
+ * 接着做（或至少把账结掉）。
+ *
+ * **它治的是模型的工作方式，不是逻辑错误**（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 { turnStateOf, } from '../hooks/turn-hook.types.js';
+import { TODO_REMINDER_KIND } from '../schema/index.js';
+import { TODO_TOOL_NAME } from '../tools/builtin-names.js';
+import { parseTodoInput } from './todo-schema.js';
+/** 两半共用的 `turnState` 键（见文件头「两半合一个扩展」）。 */
+export const TODO_SETTLE_STATE_KEY = 'todo-settle';
+/**
+ * 记账半：记下本轮最后一次 `Todo` 的入参。
+ *
+ * **记在发起处、不看结果**：被拒绝的那次（两条 in_progress）同样记——它的清单里
+ * 必然有没做完的，收尾时会因此提醒，而模型正该借这一轮把清单修好。
+ */
+export const TODO_SETTLE_TRACK_META = {
+    name: 'todo-settle-track',
+    point: 'preToolUse',
+    tools: [TODO_TOOL_NAME],
+    order: 20,
+    onError: 'open',
+};
+export class TodoSettleTrackHook {
+    preToolUse(ctx, _toolName, input) {
+        const state = turnStateOf(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 = {
+    name: 'todo-settle-reminder',
+    point: 'observe',
+    order: 20,
+    onError: 'open',
+};
+export class TodoSettleReminderHook {
+    hub;
+    waker;
+    constructor(hub, waker) {
+        this.hub = hub;
+        this.waker = waker;
+    }
+    async observe(ctx, phase) {
+        if (phase !== 'replied')
+            return;
+        if (ctx.depth !== 0)
+            return;
+        const state = ctx.turnState.get(TODO_SETTLE_STATE_KEY);
+        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 function digestTodos(input) {
+    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, completedNow) {
+    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) {
+    const active = digest.active
+        ? `，其中「${digest.active.content}」仍是 in_progress`
+        : '';
+    return (`这一轮回复已经结束，但待办清单里还有 ${digest.unfinished.length} 条没做完` +
+        `（共 ${digest.total} 条）${active}。` +
+        '列了清单就意味着要连续做完它：如果不需要用户提供信息或做决定，直接接着做' +
+        '下一条，不要停下来问「要不要继续」；做完的条目用 Todo 置 completed' +
+        '（用正文交付的也算做完），其余条目原样带上。' +
+        '如果确实在等用户答复，说清在等什么即可，不必更新清单。' +
+        '不要复述已经交付的内容。');
+}
+/** 把待办推进提醒的两半挂到注册表上（runtime 的通用扩展，宿主可以不挂）。 */
+export function registerTodoSettleHooks(hooks, deps) {
+    hooks.register(TODO_SETTLE_TRACK_META, new TodoSettleTrackHook());
+    hooks.register(TODO_SETTLE_REMINDER_META, new TodoSettleReminderHook(deps.hub, deps.wake));
+}
+//# sourceMappingURL=todo-settle.hook.js.map

package/dist/builtins/todo-settle.hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-settle.hook.js","sourceRoot":"","sources":["../../src/builtins/todo-settle.hook.ts"],"names":[],"mappings":"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"}