@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/builtins/ask.service.d.ts

@@ -0,0 +1,210 @@
+import type { SessionLock } from '../ports/coordination.js';
+import { type LoggerFactory } from '../ports/logger.js';
+import { type QuestionRecord, type QuestionStore, type SettledQuestionStatus } from '../ports/question-store.js';
+import type { SessionRecord, SessionStore } from '../ports/session-store.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type { AgentQuestion, AnswerAgentQuestionRequest, AskInput } from './ask-schema.js';
+/** `timeoutSeconds` 的缺省允许范围（秒）。宿主经 `AskServiceDeps.timeoutBounds` 换。 */
+export declare const ASK_TIMEOUT_MIN_DEFAULT = 30;
+export declare const ASK_TIMEOUT_MAX_DEFAULT = 1800;
+/**
+ * 不限时的问题最多等多久（秒）。「一直等」需要一个上限：等待期间那一轮占着会话锁、
+ * 占着一个 tick，而进程迟早要重启。到点问题作废（**不是**按默认项继续——不限时的
+ * 问题多半根本没有默认项，那正是模型选择不设超时的原因）。
+ */
+export declare const ASK_MAX_WAIT_SECONDS: number;
+/** 等待期间多久看一眼那一行。回答接口可能落在另一个实例上，所以是查存储而不是进程内通知。 */
+export declare const ASK_POLL_INTERVAL_MS = 1000;
+/** 有了结局的一行（`waitForOutcome` 的产出）。 */
+export type SettledQuestion = QuestionRecord & {
+    status: SettledQuestionStatus;
+};
+export type AskOutcome = {
+    ok: true;
+    question: AgentQuestion;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * 回答接口的失败。三种 `code` 对应 agent-base 的三个错误类，宿主按它映射 HTTP
+ * （not_found → 404，not_pending → 409，invalid → 400）。
+ */
+export declare class AskAnswerError extends Error {
+    readonly code: 'not_found' | 'not_pending' | 'invalid';
+    /** `not_pending` 时那一行此刻的状态（`'unknown'` = 读不到了）。 */
+    readonly status?: string | undefined;
+    constructor(code: 'not_found' | 'not_pending' | 'invalid', message: string, 
+    /** `not_pending` 时那一行此刻的状态（`'unknown'` = 读不到了）。 */
+    status?: string | undefined);
+}
+export interface AskServiceDeps {
+    questions: QuestionStore;
+    sessions: Pick<SessionStore, 'getSession'>;
+    /** 「等的那一轮还活着吗」= 会话锁有没有人持有。 */
+    lock: Pick<SessionLock, 'isHeld'>;
+    bus: Pick<StreamBus, 'publishSessionEvent'>;
+    /**
+     * 这条会话对面有人在看吗（挂在某个界面名下）。宿主的判据——agent-base 里是
+     * 「会话所属的形式有没有观看者」。只对有属主的根会话问。
+     */
+    hasViewer: (session: SessionRecord) => boolean | Promise<boolean>;
+    /** 本次部署允许的 `timeoutSeconds` 范围；每次提问现取（宿主可接系统参数）。 */
+    timeoutBounds?: () => {
+        min: number;
+        max: number;
+    };
+    /** 缺省 `ASK_MAX_WAIT_SECONDS`。 */
+    maxWaitSeconds?: number;
+    /** 缺省 `ASK_POLL_INTERVAL_MS`。 */
+    pollIntervalMs?: number;
+    logger?: LoggerFactory;
+}
+/**
+ * Agent 停下来问用户。搬自 agent-base `AskUserQuestionService`。
+ *
+ * ## 同步：工具在这一轮里等用户回答
+ *
+ * `AskTool` 落一行 pending，然后 `waitForOutcome` 一直等到这一行有了结局，把结局
+ * 作为工具的返回值交给模型。这一轮因此**没有结束**：同一个 run、同一条 assistant
+ * 消息，模型拿到回答接着干。
+ *
+ * **选同步不是因为它省事，是因为它不碰「一轮 = 一段完整的活」这条到处被默认的
+ * 前提。** agent-base 的第一版是挂起式的（问完本轮就结束、回答经 inbox 唤醒下一轮），
+ * 结果一路撞上这条前提的消费方：消息底部的动作栏挂在半句话下面、追问与产出整理在
+ * 「活做到一半」时就跑了、模型生成提问那几秒里用户发的插话被下一轮当成了回答。
+ * 同步之下这些问题整类不存在：等待期间到达的一切只是在 inbox 里排着。
+ *
+ * 代价是明确的、且都是**看得见的**失败：
+ * - 进程重启会打断正在等的那一轮（同 `Delegate` 同步等待）：宿主在孤儿 run 收尾里
+ *   调 `cancelPending`，界面显示「已中断」，用户说一句「继续」。
+ * - 「一直等」有上限（`maxWaitSeconds`）。
+ *
+ * ## 结局只有一个持有者
+ *
+ * 五种结局——用户点选（`answer`）、到点按默认项（等待方自己收）、用户改为打字回答
+ * （`supersedeOnUserTurn`）、停止 / 中断（`cancelPending`）、等过了上限——抢的是
+ * **同一个**带 pending 谓词的原子更新（`QuestionStore.settle` / `settleSession`）。
+ *
+ * ## 状态每变一次都经会话流广播
+ *
+ * `agent-question` 会话级事件，载荷 `{question}`（线上形态）。界面只认这一条通道。
+ *
+ * ## 宿主要接的线
+ *
+ * - 每 tick 问 `availableFor`，为假就把 `Ask` 放进 `excludeTools`。
+ * - 用户点名回答某个问题时发的那句话：`supersedeOnUserTurn`。
+ * - 停止会话（与 `LoopDriver.stopSession` 一起调）、孤儿 run 收尾
+ *   （`OrphanRunSweeper` 的 `onRunOrphaned: run => ask.cancelPending(run.sessionId)`）：
+ *   `cancelPending`。
+ * - 回答接口：`answer`；开始作答（停表）：`hold`；列表：`list`。
+ */
+export declare class AskService {
+    private readonly deps;
+    private readonly store;
+    private readonly logger;
+    readonly maxWaitSeconds: number;
+    private readonly pollIntervalMs;
+    constructor(deps: AskServiceDeps);
+    /**
+     * 这个会话问得了用户吗：根会话、有属主、且对面有人在看。
+     *
+     * 子 Agent、系统触发的运行这类会话对面没有人，端上桌只会让模型问出一个没人答的
+     * 问题，而那一轮会一直等到上限。
+     */
+    availableFor(session: SessionRecord): Promise<boolean>;
+    /**
+     * 工具落问题。**失败以 `{ok:false}` 返回而不抛**——每一条都是要原样说给模型
+     * 听、让它改了重来的话，不是故障。
+     */
+    ask(input: {
+        sessionId: string;
+        runId: string;
+        toolCallId: string;
+        request: AskInput;
+    }): Promise<AskOutcome>;
+    /**
+     * 等到这个问题有了结局，返回那一行。**工具就阻塞在这里。**
+     *
+     * 每隔 `pollIntervalMs` 看一眼那一行。三件事由等待方自己收：
+     * - **到点**：按默认项翻成 expired。没有单独的 sweeper——有人等着的问题由等的人
+     *   收；没人等的（等待方死了）不该按默认项继续，该作废，那归孤儿收尾。
+     * - **中止**（用户按了停止 / 进程优雅停机）：翻成 cancelled 再返回。
+     * - **等过了上限**：同上。
+     *
+     * 每一次「翻」都是带 pending 谓词的原子更新；没抢到就说明别的路径先给了结局，
+     * 下一圈读到那一行即返回。行没了（会话被删）返回 null。
+     */
+    waitForOutcome(questionId: string, signal: AbortSignal): Promise<SettledQuestion | null>;
+    /**
+     * 用户点选后提交。**鉴权（这个会话是不是他的）是宿主的事**，在调用之前做。
+     *
+     * 到点之后、等待方还没来得及收的那一刻提交的回答**照收**：人就在这儿，没有
+     * 理由因为晚了一秒把他的选择换成默认项。
+     *
+     * **等的那一轮已经死了就拒绝**（会话锁没人持有——问题挂着期间，能持有这把锁的
+     * 只有提问的那一轮）：收下的话界面上是「你已回答」，而什么都不会发生。把问题
+     * 作废并如实说，用户说一句「继续」即可。
+     */
+    answer(input: {
+        sessionId: string;
+        questionId: string;
+        request: AnswerAgentQuestionRequest;
+    }): Promise<AgentQuestion>;
+    /**
+     * 用户开始作答了（点了任意选项、或在「其他」里打了字）：**停表**——摘掉期限，
+     * 这个问题改为一直等到他点确定（仍受 `maxWaitSeconds` 约束）。
+     *
+     * 超时存在的理由是「人不在」。人在的时候让它走完，结局就是用户答到第三题时
+     * 默认项抢先生效，而他手上那份答到一半的选择换来一个冲突。
+     *
+     * 不是一种结局（状态仍是 pending），与到点互斥靠同一个 pending 谓词。幂等：已经
+     * 停过表、或已经有了结局，原样返回当前这一行。
+     */
+    hold(sessionId: string, questionId: string): Promise<AgentQuestion>;
+    /**
+     * 用户选了「改为打字回答」、发了一句话：那句话本身就是回答，这个问题记
+     * `superseded`。等着它的工具随即返回，内核回到循环顶部探到 inbox 有货、换轮，
+     * 那句话在下一轮被领走——模型读到的是「提问 → 用户直接回复了 → 那句话」。
+     *
+     * **只认界面点名的那一个问题**：没点名的发言是插话，不碰问题（用户发那句话的
+     * 时候可能还没见过这个问题），它在 inbox 里排着，等工具返回之后照常处理。
+     * **绝不抛**：消息已经进了 inbox，这边记账失败不能让那次发言报错。
+     */
+    supersedeOnUserTurn(sessionId: string, questionId: string): Promise<void>;
+    /**
+     * 这条会话挂着的问题一律作废。两个调用方：用户按了停止（等着它的工具同时会收到
+     * 中止信号，两条路抢同一句更新，谁先到都一样）；孤儿 run 收尾（等的那一轮已经
+     * 死了，问题留着只会让用户对着一个答了也没人接的面板）。**绝不抛**。
+     */
+    cancelPending(sessionId: string): Promise<void>;
+    /** 这条会话问过的全部问题（按时间正序）。界面按 `toolCallId` 对到工具卡上。 */
+    list(sessionId: string): Promise<AgentQuestion[]>;
+    /** 本次部署允许的 `timeoutSeconds` 范围。 */
+    timeoutBounds(): {
+        min: number;
+        max: number;
+    };
+    /**
+     * 给一个 pending 的问题一个结局——单个问题写结局的唯一入口（`settleQuietly` 是
+     * 按会话的批量版）。没抢到返回 null；抢到就广播。
+     */
+    private claim;
+    private settleQuietly;
+    /**
+     * 等这个问题的那一轮还活着吗。问题挂着期间，能持有会话锁的只有提问的那一轮
+     * （别的 tick 起不来），所以「锁有没有人持有」就是答案。
+     *
+     * 问不到时**当作还活着**：收下回答的最坏结果是没人接、稍后被孤儿收尾作废；
+     * 反过来猜「死了」会把一个正常在等的问题作废掉，那一轮拿到的是「用户取消了」。
+     */
+    private waiterAlive;
+    /** 行 → 线上形态。`remainingMs` 要存储时钟，只在有限时的 pending 行时才问。 */
+    private toWires;
+    private publishRows;
+    /** 会话级事件：`seq` / `streamId` / `runId` 是占位（见 `publishSessionEvent`）。 */
+    private publish;
+}
+/** 行 → 线上形态。`storeNow` 是存储时钟（算 `remainingMs`），不需要时可为 null。 */
+export declare function toQuestionWire(row: QuestionRecord, storeNow: Date | null): AgentQuestion;
+//# sourceMappingURL=ask.service.d.ts.map

package/dist/builtins/ask.service.d.ts.map

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

package/dist/builtins/ask.service.js

@@ -0,0 +1,373 @@
+import { silentLogger, } from '../ports/logger.js';
+import { QuestionConflictError, } from '../ports/question-store.js';
+import { ASK_TOOL_NAME } from '../tools/builtin-names.js';
+import { defaultAnswers, validateAnswers } from './ask-outcome.js';
+/** `timeoutSeconds` 的缺省允许范围（秒）。宿主经 `AskServiceDeps.timeoutBounds` 换。 */
+export const ASK_TIMEOUT_MIN_DEFAULT = 30;
+export const ASK_TIMEOUT_MAX_DEFAULT = 1800;
+/**
+ * 不限时的问题最多等多久（秒）。「一直等」需要一个上限：等待期间那一轮占着会话锁、
+ * 占着一个 tick，而进程迟早要重启。到点问题作废（**不是**按默认项继续——不限时的
+ * 问题多半根本没有默认项，那正是模型选择不设超时的原因）。
+ */
+export const ASK_MAX_WAIT_SECONDS = 24 * 3600;
+/** 等待期间多久看一眼那一行。回答接口可能落在另一个实例上，所以是查存储而不是进程内通知。 */
+export const ASK_POLL_INTERVAL_MS = 1_000;
+/**
+ * 回答接口的失败。三种 `code` 对应 agent-base 的三个错误类，宿主按它映射 HTTP
+ * （not_found → 404，not_pending → 409，invalid → 400）。
+ */
+export class AskAnswerError extends Error {
+    code;
+    status;
+    constructor(code, message, 
+    /** `not_pending` 时那一行此刻的状态（`'unknown'` = 读不到了）。 */
+    status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AskAnswerError';
+    }
+}
+/**
+ * Agent 停下来问用户。搬自 agent-base `AskUserQuestionService`。
+ *
+ * ## 同步：工具在这一轮里等用户回答
+ *
+ * `AskTool` 落一行 pending，然后 `waitForOutcome` 一直等到这一行有了结局，把结局
+ * 作为工具的返回值交给模型。这一轮因此**没有结束**：同一个 run、同一条 assistant
+ * 消息，模型拿到回答接着干。
+ *
+ * **选同步不是因为它省事，是因为它不碰「一轮 = 一段完整的活」这条到处被默认的
+ * 前提。** agent-base 的第一版是挂起式的（问完本轮就结束、回答经 inbox 唤醒下一轮），
+ * 结果一路撞上这条前提的消费方：消息底部的动作栏挂在半句话下面、追问与产出整理在
+ * 「活做到一半」时就跑了、模型生成提问那几秒里用户发的插话被下一轮当成了回答。
+ * 同步之下这些问题整类不存在：等待期间到达的一切只是在 inbox 里排着。
+ *
+ * 代价是明确的、且都是**看得见的**失败：
+ * - 进程重启会打断正在等的那一轮（同 `Delegate` 同步等待）：宿主在孤儿 run 收尾里
+ *   调 `cancelPending`，界面显示「已中断」，用户说一句「继续」。
+ * - 「一直等」有上限（`maxWaitSeconds`）。
+ *
+ * ## 结局只有一个持有者
+ *
+ * 五种结局——用户点选（`answer`）、到点按默认项（等待方自己收）、用户改为打字回答
+ * （`supersedeOnUserTurn`）、停止 / 中断（`cancelPending`）、等过了上限——抢的是
+ * **同一个**带 pending 谓词的原子更新（`QuestionStore.settle` / `settleSession`）。
+ *
+ * ## 状态每变一次都经会话流广播
+ *
+ * `agent-question` 会话级事件，载荷 `{question}`（线上形态）。界面只认这一条通道。
+ *
+ * ## 宿主要接的线
+ *
+ * - 每 tick 问 `availableFor`，为假就把 `Ask` 放进 `excludeTools`。
+ * - 用户点名回答某个问题时发的那句话：`supersedeOnUserTurn`。
+ * - 停止会话（与 `LoopDriver.stopSession` 一起调）、孤儿 run 收尾
+ *   （`OrphanRunSweeper` 的 `onRunOrphaned: run => ask.cancelPending(run.sessionId)`）：
+ *   `cancelPending`。
+ * - 回答接口：`answer`；开始作答（停表）：`hold`；列表：`list`。
+ */
+export class AskService {
+    deps;
+    store;
+    logger;
+    maxWaitSeconds;
+    pollIntervalMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.store = deps.questions;
+        this.logger = (deps.logger ?? silentLogger)('AskService');
+        this.maxWaitSeconds = deps.maxWaitSeconds ?? ASK_MAX_WAIT_SECONDS;
+        this.pollIntervalMs = deps.pollIntervalMs ?? ASK_POLL_INTERVAL_MS;
+    }
+    /**
+     * 这个会话问得了用户吗：根会话、有属主、且对面有人在看。
+     *
+     * 子 Agent、系统触发的运行这类会话对面没有人，端上桌只会让模型问出一个没人答的
+     * 问题，而那一轮会一直等到上限。
+     */
+    async availableFor(session) {
+        if (session.kind !== 'root' || !session.userId)
+            return false;
+        return this.deps.hasViewer(session);
+    }
+    /**
+     * 工具落问题。**失败以 `{ok:false}` 返回而不抛**——每一条都是要原样说给模型
+     * 听、让它改了重来的话，不是故障。
+     */
+    async ask(input) {
+        const { request } = input;
+        const session = await this.deps.sessions.getSession(input.sessionId);
+        if (!session || !session.userId || !(await this.availableFor(session))) {
+            return {
+                ok: false,
+                message: '这个会话没有可以回答问题的用户（子 Agent 或系统触发的运行）。' +
+                    '自己按最合理的选择继续，并在产出里写明这一项是你定的；' +
+                    '如果你是子 Agent 且这件事必须由人决定，把问题写进产出交回给调用方。',
+            };
+        }
+        const bounds = this.timeoutBounds();
+        if (request.timeoutSeconds !== undefined &&
+            (request.timeoutSeconds < bounds.min ||
+                request.timeoutSeconds > bounds.max)) {
+            // 拒绝而不是钳到范围内：钳了之后模型在正文里说的「5 分钟」就和界面上的
+            // 倒计时对不上，而它自己不知道。
+            return {
+                ok: false,
+                message: `timeoutSeconds 必须在 ${bounds.min}–${bounds.max} 秒之间（收到 ${request.timeoutSeconds}）。要等更久就不要给 timeoutSeconds，一直等到用户回答。`,
+            };
+        }
+        try {
+            const { question, swept } = await this.store.open({
+                sessionId: input.sessionId,
+                userId: session.userId,
+                runId: input.runId,
+                toolCallId: input.toolCallId,
+                questions: request.questions,
+                timeoutSeconds: request.timeoutSeconds,
+            });
+            const wires = await this.toWires([...swept, question]);
+            for (const w of wires)
+                this.publish(session, w);
+            return { ok: true, question: wires[wires.length - 1] };
+        }
+        catch (err) {
+            if (err instanceof QuestionConflictError) {
+                return {
+                    ok: false,
+                    message: `这一轮已经有一个问题在等用户回答。一次只能有一个 ${ASK_TOOL_NAME} ` +
+                        '在等——把要问的全部放进同一次调用的 questions 里（最多 4 题）。',
+                };
+            }
+            throw err;
+        }
+    }
+    /**
+     * 等到这个问题有了结局，返回那一行。**工具就阻塞在这里。**
+     *
+     * 每隔 `pollIntervalMs` 看一眼那一行。三件事由等待方自己收：
+     * - **到点**：按默认项翻成 expired。没有单独的 sweeper——有人等着的问题由等的人
+     *   收；没人等的（等待方死了）不该按默认项继续，该作废，那归孤儿收尾。
+     * - **中止**（用户按了停止 / 进程优雅停机）：翻成 cancelled 再返回。
+     * - **等过了上限**：同上。
+     *
+     * 每一次「翻」都是带 pending 谓词的原子更新；没抢到就说明别的路径先给了结局，
+     * 下一圈读到那一行即返回。行没了（会话被删）返回 null。
+     */
+    async waitForOutcome(questionId, signal) {
+        for (;;) {
+            const found = await this.store.probe(questionId, this.maxWaitSeconds);
+            if (!found)
+                return null;
+            const { question } = found;
+            if (question.status !== 'pending')
+                return question;
+            if (signal.aborted || found.overdue) {
+                await this.claim(questionId, 'cancelled', null);
+            }
+            else if (found.due) {
+                const answers = defaultAnswers(question.questions);
+                // 限时却缺默认项——入参校验保证不了的只有坏数据。不替用户编答案：作废。
+                await this.claim(questionId, answers ? 'expired' : 'cancelled', answers);
+            }
+            else {
+                await sleep(this.pollIntervalMs, signal);
+            }
+        }
+    }
+    /**
+     * 用户点选后提交。**鉴权（这个会话是不是他的）是宿主的事**，在调用之前做。
+     *
+     * 到点之后、等待方还没来得及收的那一刻提交的回答**照收**：人就在这儿，没有
+     * 理由因为晚了一秒把他的选择换成默认项。
+     *
+     * **等的那一轮已经死了就拒绝**（会话锁没人持有——问题挂着期间，能持有这把锁的
+     * 只有提问的那一轮）：收下的话界面上是「你已回答」，而什么都不会发生。把问题
+     * 作废并如实说，用户说一句「继续」即可。
+     */
+    async answer(input) {
+        const current = await this.store.get(input.questionId, input.sessionId);
+        if (!current) {
+            throw new AskAnswerError('not_found', `question ${input.questionId} not found`);
+        }
+        if (current.status !== 'pending') {
+            throw notPending(current.id, current.status);
+        }
+        if (!(await this.waiterAlive(input.sessionId))) {
+            await this.cancelPending(input.sessionId);
+            throw notPending(current.id, 'cancelled');
+        }
+        const checked = validateAnswers(current.questions, input.request);
+        if (!checked.ok)
+            throw new AskAnswerError('invalid', checked.message);
+        const row = await this.claim(input.questionId, 'answered', checked.answers);
+        if (!row) {
+            // 校验与抢占之间被别的路径抢走了——回头读一眼它现在是什么。
+            const now = await this.store.get(input.questionId, input.sessionId);
+            throw notPending(input.questionId, now?.status ?? 'unknown');
+        }
+        const [wire] = await this.toWires([row]);
+        return wire;
+    }
+    /**
+     * 用户开始作答了（点了任意选项、或在「其他」里打了字）：**停表**——摘掉期限，
+     * 这个问题改为一直等到他点确定（仍受 `maxWaitSeconds` 约束）。
+     *
+     * 超时存在的理由是「人不在」。人在的时候让它走完，结局就是用户答到第三题时
+     * 默认项抢先生效，而他手上那份答到一半的选择换来一个冲突。
+     *
+     * 不是一种结局（状态仍是 pending），与到点互斥靠同一个 pending 谓词。幂等：已经
+     * 停过表、或已经有了结局，原样返回当前这一行。
+     */
+    async hold(sessionId, questionId) {
+        const held = await this.store.hold(questionId, sessionId);
+        if (held) {
+            const [wire] = await this.toWires([held]);
+            await this.publishRows(sessionId, [wire]);
+            return wire;
+        }
+        const current = await this.store.get(questionId, sessionId);
+        if (!current) {
+            throw new AskAnswerError('not_found', `question ${questionId} not found`);
+        }
+        const [wire] = await this.toWires([current]);
+        return wire;
+    }
+    /**
+     * 用户选了「改为打字回答」、发了一句话：那句话本身就是回答，这个问题记
+     * `superseded`。等着它的工具随即返回，内核回到循环顶部探到 inbox 有货、换轮，
+     * 那句话在下一轮被领走——模型读到的是「提问 → 用户直接回复了 → 那句话」。
+     *
+     * **只认界面点名的那一个问题**：没点名的发言是插话，不碰问题（用户发那句话的
+     * 时候可能还没见过这个问题），它在 inbox 里排着，等工具返回之后照常处理。
+     * **绝不抛**：消息已经进了 inbox，这边记账失败不能让那次发言报错。
+     */
+    async supersedeOnUserTurn(sessionId, questionId) {
+        await this.settleQuietly(sessionId, 'superseded', questionId);
+    }
+    /**
+     * 这条会话挂着的问题一律作废。两个调用方：用户按了停止（等着它的工具同时会收到
+     * 中止信号，两条路抢同一句更新，谁先到都一样）；孤儿 run 收尾（等的那一轮已经
+     * 死了，问题留着只会让用户对着一个答了也没人接的面板）。**绝不抛**。
+     */
+    async cancelPending(sessionId) {
+        await this.settleQuietly(sessionId, 'cancelled');
+    }
+    /** 这条会话问过的全部问题（按时间正序）。界面按 `toolCallId` 对到工具卡上。 */
+    async list(sessionId) {
+        return this.toWires(await this.store.list(sessionId));
+    }
+    /** 本次部署允许的 `timeoutSeconds` 范围。 */
+    timeoutBounds() {
+        const { min, max } = this.deps.timeoutBounds?.() ?? {
+            min: ASK_TIMEOUT_MIN_DEFAULT,
+            max: ASK_TIMEOUT_MAX_DEFAULT,
+        };
+        // 两个值各自合法、合起来却可能倒挂（运营把下限调过了上限）。那时以上限为准
+        // 收成一个点，而不是让每一次带超时的提问都被拒。
+        return { min: Math.min(min, max), max };
+    }
+    // -------------------------------------------------------------------------
+    /**
+     * 给一个 pending 的问题一个结局——单个问题写结局的唯一入口（`settleQuietly` 是
+     * 按会话的批量版）。没抢到返回 null；抢到就广播。
+     */
+    async claim(questionId, status, answers) {
+        const row = await this.store.settle(questionId, status, answers);
+        if (!row)
+            return null;
+        await this.publishRows(row.sessionId, await this.toWires([row]));
+        return row;
+    }
+    async settleQuietly(sessionId, status, questionId) {
+        try {
+            const rows = await this.store.settleSession(sessionId, status, questionId);
+            await this.publishRows(sessionId, await this.toWires(rows));
+        }
+        catch (err) {
+            this.logger.warn(`settling questions of session ${sessionId} as ${status} failed: ${String(err)}`);
+        }
+    }
+    /**
+     * 等这个问题的那一轮还活着吗。问题挂着期间，能持有会话锁的只有提问的那一轮
+     * （别的 tick 起不来），所以「锁有没有人持有」就是答案。
+     *
+     * 问不到时**当作还活着**：收下回答的最坏结果是没人接、稍后被孤儿收尾作废；
+     * 反过来猜「死了」会把一个正常在等的问题作废掉，那一轮拿到的是「用户取消了」。
+     */
+    async waiterAlive(sessionId) {
+        try {
+            return await this.deps.lock.isHeld(sessionId);
+        }
+        catch (err) {
+            this.logger.warn(`lock probe for session ${sessionId} failed, assuming alive: ${String(err)}`);
+            return true;
+        }
+    }
+    /** 行 → 线上形态。`remainingMs` 要存储时钟，只在有限时的 pending 行时才问。 */
+    async toWires(rows) {
+        const timed = rows.some(r => r.status === 'pending' && r.deadlineAt);
+        const storeNow = timed ? await this.store.now() : null;
+        return rows.map(row => toQuestionWire(row, storeNow));
+    }
+    async publishRows(sessionId, wires) {
+        if (wires.length === 0)
+            return;
+        const session = await this.deps.sessions.getSession(sessionId);
+        if (!session)
+            return;
+        for (const w of wires)
+            this.publish(session, w);
+    }
+    /** 会话级事件：`seq` / `streamId` / `runId` 是占位（见 `publishSessionEvent`）。 */
+    publish(session, question) {
+        this.deps.bus.publishSessionEvent({
+            seq: 0,
+            streamId: session.id,
+            rootSessionId: session.rootSessionId,
+            sessionId: session.id,
+            runId: session.id,
+            parentRunId: null,
+            depth: 0,
+            ts: Date.now(),
+            type: 'agent-question',
+            payload: { question },
+        });
+    }
+}
+/** 行 → 线上形态。`storeNow` 是存储时钟（算 `remainingMs`），不需要时可为 null。 */
+export function toQuestionWire(row, storeNow) {
+    const live = row.status === 'pending' && row.deadlineAt !== null;
+    return {
+        id: row.id,
+        sessionId: row.sessionId,
+        runId: row.runId,
+        toolCallId: row.toolCallId,
+        questions: row.questions,
+        status: row.status,
+        deadlineAt: row.deadlineAt?.toISOString() ?? null,
+        remainingMs: live && storeNow && row.deadlineAt
+            ? Math.max(0, row.deadlineAt.getTime() - storeNow.getTime())
+            : null,
+        answers: row.answers,
+        createdAt: row.createdAt.toISOString(),
+        resolvedAt: row.resolvedAt?.toISOString() ?? null,
+    };
+}
+function notPending(id, status) {
+    return new AskAnswerError('not_pending', `question ${id} is not pending (${status})`, status);
+}
+/** 可中止的 sleep：信号一来立刻醒，不等这一拍走完。 */
+function sleep(ms, signal) {
+    return new Promise(resolve => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener('abort', done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        }
+    });
+}
+//# sourceMappingURL=ask.service.js.map

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

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

package/dist/builtins/ask.tool.d.ts

@@ -0,0 +1,49 @@
+import type { z } from 'zod';
+import { AgentTool } from '../tools/agent-tool.base.js';
+import type { ToolContext } from '../tools/agent-tool.interface.js';
+import type { ToolMeta } from '../tools/tool-meta.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { type ToolOut } from '../tools/tool-result.js';
+import type { AskService } from './ask.service.js';
+import { type AskInput } from './ask-schema.js';
+interface Out {
+    questionId: string;
+    /** 给模型看的那段话：问题的结局（用户选了什么 / 超时按默认项 / 改为打字 / 作废）。 */
+    text: string;
+}
+/** `Ask` 的登记信息。 */
+export declare const ASK_TOOL_META: ToolMeta;
+/**
+ * 向用户提问，**等到有了结局再返回**（原名见 `ASK_FORMER_NAMES`）。
+ *
+ * 同步工具：这一轮不结束，模型拿到回答接着干。为什么不做成「问完本轮就结束、
+ * 回答再唤醒下一轮」，见 `AskService` 的类注释。
+ *
+ * 等待由服务负责（`waitForOutcome`）；`ctx.abortSignal` 是「用户中止 ∪ 本工具超时」
+ * 的合成信号，两种情形服务都会把问题作废再返回。
+ */
+export declare class AskTool extends AgentTool<AskInput, Out> {
+    private readonly questions;
+    readonly inputSchema: z.ZodType<AskInput>;
+    /**
+     * 比服务里的等待上限多留两分钟：上限到点由服务把问题**作废**并正常返回一句话，
+     * 不该让基类的超时抢先把它变成一条「工具执行超时」的错误。
+     */
+    protected readonly timeoutMs: number;
+    constructor(questions: AskService);
+    protected run(raw: AskInput, ctx: ToolContext): Promise<ToolOut<Out>>;
+    protected render(out: {
+        kind: 'ok';
+    } & Out): string;
+    /** 界面按它把那一行问题对到这张工具卡上。 */
+    protected persistRef(out: ToolOut<Out>): Record<string, unknown> | undefined;
+    /**
+     * 钉住，不许上下文裁剪换成存根：这是一两句话的**用户决定**，裁掉之后模型无从
+     * 重新得知，只会按自己的猜测往下写、或把同一个问题再问一遍。
+     */
+    protected persistPinned(out: ToolOut<Out>): boolean;
+}
+/** 登记 `Ask`。 */
+export declare function registerAskTool(tools: ToolRegistry, service: AskService): AskTool;
+export {};
+//# sourceMappingURL=ask.tool.d.ts.map

package/dist/builtins/ask.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.tool.d.ts","sourceRoot":"","sources":["../../src/builtins/ask.tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,iBAAiB,CAAC;AAEhE,UAAU,GAAG;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mBAAmB;AACnB,eAAO,MAAM,aAAa,EAAE,QAoB3B,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,OAAQ,SAAQ,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC;IAWvC,OAAO,CAAC,QAAQ,CAAC,SAAS;IARtC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAE3D;;;OAGG;IACH,mBAA4B,SAAS,EAAE,MAAM,CAAC;gBAEjB,SAAS,EAAE,UAAU;cAKlC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IA6C3E,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,GAAG,GAAG,MAAM;IAInD,0BAA0B;IAC1B,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAI5E;;;OAGG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO;CAGpD;AAED,gBAAgB;AAChB,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,UAAU,GAClB,OAAO,CAIT"}