@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/agent-extensions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 宿主往 runtime 的 agent 视图上加自己的字段（module augmentation）：
+ *
+ * ```ts
+ * declare module '@qjp88995/agent-runtime' {
+ *   interface AgentExtensions {
+ *     identity: AgentIdentity;
+ *     mediaProviders: AgentMediaProviders;
+ *   }
+ * }
+ * ```
+ *
+ * runtime 不解释这些字段，只原样带着走：`AgentDefinition.extensions` →
+ * `ToolContext.agent`、`TurnContext.agent`、`AgentToolProvider.isAvailable/describe`。
+ * 工具与钩子因此拿得到带类型的宿主配置，而内核一个宿主字段都不认识。
+ */
+export interface AgentExtensions {
+}
+/**
+ * 一轮运行的发起人此刻有哪些权限点（宿主每轮现读）。权限点是宿主自己的字符串。
+ *
+ * 决定哪些声明了 `ToolMeta.permission` 的工具端上桌。**这不是门**：要权限的工具在
+ * 自己的 `run` 里还要现查一次。没有发起人（系统触发）、账号停用 → `NO_INITIATOR`：
+ * 退化方向必须是「什么都没有」。
+ */
+export interface Initiator {
+    permissions: ReadonlySet<string>;
+}
+export declare const NO_INITIATOR: Initiator;
+//# sourceMappingURL=agent-extensions.d.ts.map

package/dist/agent-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-extensions.d.ts","sourceRoot":"","sources":["../src/agent-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,eAAe;CAAG;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,YAAY,EAAE,SAEzB,CAAC"}

package/dist/agent-extensions.js

@@ -0,0 +1,4 @@
+export const NO_INITIATOR = Object.freeze({
+    permissions: new Set(),
+});
+//# sourceMappingURL=agent-extensions.js.map

package/dist/agent-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-extensions.js","sourceRoot":"","sources":["../src/agent-extensions.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAC,MAAM,YAAY,GAAc,MAAM,CAAC,MAAM,CAAC;IACnD,WAAW,EAAE,IAAI,GAAG,EAAU;CAC/B,CAAC,CAAC"}

package/dist/builtins/ask-outcome.d.ts

@@ -0,0 +1,49 @@
+import type { AgentQuestionAnswer, AnswerAgentQuestionRequest, AskQuestionItem } from './ask-schema.js';
+/**
+ * `Ask` 的纯函数层：回答的校验、默认项的推导、结局怎么写成那次工具
+ * 调用的返回值。
+ */
+export type AnswerValidation = {
+    ok: true;
+    answers: AgentQuestionAnswer[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * 对着那一行的选项校验用户提交的回答，产出落库形态。
+ *
+ * 逐条报「第几题错在哪」：这些错误只可能来自前端 bug 或手工调接口，报得含糊的话
+ * 排查的人要对着四道题各试一遍。
+ */
+export declare function validateAnswers(questions: readonly AskQuestionItem[], request: AnswerAgentQuestionRequest): AnswerValidation;
+/**
+ * 超时采用的默认项。任一题没有 `defaultOption` 时返回 null——工具入参校验保证
+ * 「限时 ⇒ 每题都有默认项」，这里的 null 只会来自坏数据，调用方据此不投默认值
+ * （宁可让问题一直挂着，也不替用户编一个答案）。
+ */
+export declare function defaultAnswers(questions: readonly AskQuestionItem[]): AgentQuestionAnswer[] | null;
+/** 秒数写成人话：整分钟说分钟，其余说秒。 */
+export declare function describeWait(seconds: number): string;
+/** 一个有了结局的问题：写成返回值要的全部材料。 */
+export interface QuestionOutcome {
+    status: 'answered' | 'expired' | 'superseded' | 'cancelled';
+    questions: readonly AskQuestionItem[];
+    /** `answered` 是用户选的，`expired` 是默认项，其余为 null。 */
+    answers: readonly AgentQuestionAnswer[] | null;
+    /** 从提问到期限的秒数；不限时为 null。只有 `expired` 用得上。 */
+    waitedSeconds: number | null;
+}
+/**
+ * 问题的结局 → **那次 `Ask` 调用的返回值**（工具等到有了结局才返回）。
+ *
+ * 四种结局各自要让模型做对一件事，文案就是为那件事写的：
+ * - `answered`：照用户选的做。
+ * - `expired`：按默认项往下做、**别再问一遍**（不说的话那是它最常见的反应，而用户
+ *   此刻多半不在），并在回复里说明这一项是按默认定的。
+ * - `superseded`：别按默认项——用户改为直接打字回复了，那句话紧随其后。
+ * - `cancelled`：**不要**按默认项继续。用户说了停，这里要是含糊，模型会体贴地
+ *   「那我先按推荐的来」。
+ */
+export declare function renderOutcomeResult(outcome: QuestionOutcome): string;
+//# sourceMappingURL=ask-outcome.d.ts.map

package/dist/builtins/ask-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-outcome.d.ts","sourceRoot":"","sources":["../../src/builtins/ask-outcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AAEH,MAAM,MAAM,gBAAgB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,mBAAmB,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,eAAe,EAAE,EACrC,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CA4ClB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,mBAAmB,EAAE,GAAG,IAAI,CAY9B;AAgCD,0BAA0B;AAC1B,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;IAC5D,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,gDAAgD;IAChD,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAAC;IAC/C,4CAA4C;IAC5C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAmBpE"}

package/dist/builtins/ask-outcome.js

@@ -0,0 +1,128 @@
+/**
+ * 对着那一行的选项校验用户提交的回答，产出落库形态。
+ *
+ * 逐条报「第几题错在哪」：这些错误只可能来自前端 bug 或手工调接口，报得含糊的话
+ * 排查的人要对着四道题各试一遍。
+ */
+export function validateAnswers(questions, request) {
+    if (request.answers.length !== questions.length) {
+        return {
+            ok: false,
+            message: `共 ${questions.length} 题，收到 ${request.answers.length} 个回答`,
+        };
+    }
+    const answers = [];
+    for (const [i, q] of questions.entries()) {
+        const a = request.answers[i];
+        const n = i + 1;
+        const known = new Set(q.options.map(o => o.label));
+        const unknown = a.labels.filter(l => !known.has(l));
+        if (unknown.length > 0) {
+            return {
+                ok: false,
+                message: `第 ${n} 题没有这个选项：${unknown.join('、')}`,
+            };
+        }
+        if (new Set(a.labels).size !== a.labels.length) {
+            return { ok: false, message: `第 ${n} 题的选项重复` };
+        }
+        // 空白的「其他」当作没写——前端展开了输入框但用户什么都没填。
+        const other = a.other && a.other.length > 0 ? a.other : null;
+        const picked = a.labels.length + (other ? 1 : 0);
+        if (picked === 0) {
+            // 跳过：有默认项的题按默认项算（并如实记下不是用户亲手选的），没有的必答。
+            if (q.defaultOption === undefined) {
+                return { ok: false, message: `第 ${n} 题为必答题` };
+            }
+            answers.push({
+                header: q.header,
+                labels: [q.defaultOption],
+                other: null,
+                byDefault: true,
+            });
+            continue;
+        }
+        if (!q.multiSelect && picked > 1) {
+            return { ok: false, message: `第 ${n} 题为单选题，只能选一项` };
+        }
+        answers.push({ header: q.header, labels: a.labels, other });
+    }
+    return { ok: true, answers };
+}
+/**
+ * 超时采用的默认项。任一题没有 `defaultOption` 时返回 null——工具入参校验保证
+ * 「限时 ⇒ 每题都有默认项」，这里的 null 只会来自坏数据，调用方据此不投默认值
+ * （宁可让问题一直挂着，也不替用户编一个答案）。
+ */
+export function defaultAnswers(questions) {
+    const out = [];
+    for (const q of questions) {
+        if (q.defaultOption === undefined)
+            return null;
+        out.push({
+            header: q.header,
+            labels: [q.defaultOption],
+            other: null,
+            byDefault: true,
+        });
+    }
+    return out;
+}
+/** 一题的回答写成一句话：选中的 label 在前，「其他」里写的话原样跟在后面。 */
+function answerPhrase(a) {
+    return [...a.labels, ...(a.other ? [a.other] : [])].join('、');
+}
+/**
+ * 逐题写成「问题 → 回答」。带着问题本身：这段话要脱离那次调用的入参也读得懂。
+ *
+ * `markSkipped`：用户提交时跳过的那几题如实标出来。模型得知道哪些是用户亲手定的、
+ * 哪些只是没反对它的默认项——后者用户回头想改是很自然的事，它不该当成一个已经
+ * 拍板的决定去坚持。整题超时的不逐条标（那段话开头已经说了「按你给的默认项继续」，
+ * 每一题都标一遍只是噪音）。
+ */
+function renderPicks(questions, answers, markSkipped) {
+    return questions
+        .map((q, i) => {
+        const a = answers[i];
+        const note = markSkipped && a.byDefault
+            ? '（用户没有选这一题，按你给的默认项）'
+            : '';
+        return `${q.question}\n→ ${answerPhrase(a)}${note}`;
+    })
+        .join('\n\n');
+}
+/** 秒数写成人话：整分钟说分钟，其余说秒。 */
+export function describeWait(seconds) {
+    return seconds >= 60 && seconds % 60 === 0
+        ? `${seconds / 60} 分钟`
+        : `${seconds} 秒`;
+}
+/**
+ * 问题的结局 → **那次 `Ask` 调用的返回值**（工具等到有了结局才返回）。
+ *
+ * 四种结局各自要让模型做对一件事，文案就是为那件事写的：
+ * - `answered`：照用户选的做。
+ * - `expired`：按默认项往下做、**别再问一遍**（不说的话那是它最常见的反应，而用户
+ *   此刻多半不在），并在回复里说明这一项是按默认定的。
+ * - `superseded`：别按默认项——用户改为直接打字回复了，那句话紧随其后。
+ * - `cancelled`：**不要**按默认项继续。用户说了停，这里要是含糊，模型会体贴地
+ *   「那我先按推荐的来」。
+ */
+export function renderOutcomeResult(outcome) {
+    const { status, questions, answers } = outcome;
+    if (status === 'answered' && answers) {
+        return `用户的回答：\n\n${renderPicks(questions, answers, true)}`;
+    }
+    if (status === 'expired' && answers) {
+        const waited = outcome.waitedSeconds === null
+            ? ''
+            : `等了 ${describeWait(outcome.waitedSeconds)}，`;
+        return (`${waited}用户没有回答，按你给的默认项继续：\n\n${renderPicks(questions, answers, false)}\n\n` +
+            '直接按默认项往下做，不要就同一件事再问一次；在回复里说明这一项是按默认定的，用户回来后可以改。');
+    }
+    if (status === 'superseded') {
+        return '用户没有点选项，而是直接发了一条消息来回答——那条消息紧随其后，以它为准，不要按默认项继续。';
+    }
+    return '这个问题已作废（用户停止了这一轮，或等待过久）。不要按默认项继续；用户接下来说什么就做什么，确有必要再重新问。';
+}
+//# sourceMappingURL=ask-outcome.js.map

package/dist/builtins/ask-outcome.js.map

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

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

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/**
+ * Agent 停下来问用户（`Ask` 工具，原名见 `ASK_FORMER_NAMES`）。
+ *
+ * **同步工具**：落一条待答问题（`QuestionStore`），然后这一轮就等在这儿，直到那一行有了
+ * 结局——结局就是那次工具调用的返回值，模型拿到它接着干（同一个 run、同一条
+ * 助手消息）。与 Claude Code 的同名工具同一个形状。
+ */
+/**
+ * 一个问题的去向。
+ *
+ * - `pending`：等用户回答（一个会话同时至多一个）。
+ * - `answered`：用户点选后提交了。
+ * - `expired`：到了 `deadlineAt` 没人答，按默认项继续。
+ * - `superseded`：用户没点选项、改为直接打字回复——那句话本身就是回答。
+ * - `cancelled`：作废了——用户按了停止、等它的那一轮中断了、或等过了上限。
+ */
+export declare const AGENT_QUESTION_STATUSES: readonly ["pending", "answered", "expired", "superseded", "cancelled"];
+export type AgentQuestionStatus = (typeof AGENT_QUESTION_STATUSES)[number];
+export declare const ASK_MAX_QUESTIONS = 4;
+export declare const ASK_MIN_OPTIONS = 2;
+export declare const ASK_MAX_OPTIONS = 4;
+/** 「其他」里用户自己写的那句话的上限。 */
+export declare const ASK_OTHER_MAX_CHARS = 500;
+export declare const AskOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AskOption = z.infer<typeof AskOptionSchema>;
+export declare const AskQuestionItemSchema: z.ZodObject<{
+    question: z.ZodString;
+    header: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    multiSelect: z.ZodDefault<z.ZodBoolean>;
+    defaultOption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AskQuestionItem = z.infer<typeof AskQuestionItemSchema>;
+/**
+ * 工具入参。三条交叉校验写在 schema 上而不是工具里：错误会随 zod 的 issue 路径
+ * 回给模型，它能看出是第几题的哪个字段。
+ */
+export declare const AskInputSchema: z.ZodObject<{
+    questions: z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        header: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        multiSelect: z.ZodDefault<z.ZodBoolean>;
+        defaultOption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AskInput = z.infer<typeof AskInputSchema>;
+/** 一题的回答。`labels` 是点选的选项，`other` 是用户在「其他」里写的话。 */
+export interface AgentQuestionAnswer {
+    header: string;
+    labels: string[];
+    other: string | null;
+    /**
+     * 这一题用户没有亲手选，`labels` 是 Agent 给的默认项。两种来源：整个问题超时了
+     * （每一题都为真）；或用户提交时跳过了这一题。缺省 = 用户亲手选的。
+     *
+     * **必答与否不是一个单独的开关，是从 `defaultOption` 推出来的**：有默认项的题
+     * 可以跳过，没有的必答。默认项本来就是「用户不做决定时会发生什么」，超时与跳过
+     * 是同一个语义；再给模型一个 `required` 参数，就多一种它判断错的方式。
+     */
+    byDefault?: boolean;
+}
+/**
+ * 提交回答。`answers` 与问题**按下标对齐**、长度必须相等。
+ * 单选题：`labels` 恰好一个且无 `other`，或 `labels` 为空且有 `other`；
+ * 多选题：两者合计至少一项。**两者都空 = 跳过这一题**：有默认项的题按默认项算，
+ * 没有默认项的题（必答）会被拒绝。具体校验在服务里（要对着那一行的选项判）。
+ */
+export declare const AnswerAgentQuestionRequestSchema: z.ZodObject<{
+    answers: z.ZodArray<z.ZodObject<{
+        labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        other: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AnswerAgentQuestionRequest = z.infer<typeof AnswerAgentQuestionRequestSchema>;
+export interface AgentQuestion {
+    id: string;
+    sessionId: string;
+    /** 提问的那一轮（= 那条 assistant 消息的 id）。 */
+    runId: string;
+    /** 那次 `Ask` 调用；前端按它把这一行对到工具卡上。 */
+    toolCallId: string;
+    questions: AskQuestionItem[];
+    status: AgentQuestionStatus;
+    /** null = 不限时。 */
+    deadlineAt: string | null;
+    /**
+     * 下发那一刻离 `deadlineAt` 还有多少毫秒（服务端按数据库时钟算）。
+     * **倒计时读它，不读 `deadlineAt`**——浏览器时钟与服务器差几十秒很常见，拿
+     * 本地 `Date.now()` 去减会让倒计时提前归零、或归零后迟迟不动。不限时或已不是
+     * pending 时为 null。
+     */
+    remainingMs: number | null;
+    /** `answered` 是用户选的，`expired` 是默认项，其余为 null。 */
+    answers: AgentQuestionAnswer[] | null;
+    createdAt: string;
+    resolvedAt: string | null;
+}
+//# sourceMappingURL=ask-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ask-schema.d.ts","sourceRoot":"","sources":["../../src/builtins/ask-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,wEAM1B,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,yBAAyB;AACzB,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,eAAO,MAAM,eAAe;;;iBAa1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;;;;;;iBA4BhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;iBAsCvB,CAAC;AACL,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC;;;;;iBAU3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kBAAkB;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gDAAgD;IAChD,OAAO,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}

package/dist/builtins/ask-schema.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+/**
+ * Agent 停下来问用户（`Ask` 工具，原名见 `ASK_FORMER_NAMES`）。
+ *
+ * **同步工具**：落一条待答问题（`QuestionStore`），然后这一轮就等在这儿，直到那一行有了
+ * 结局——结局就是那次工具调用的返回值，模型拿到它接着干（同一个 run、同一条
+ * 助手消息）。与 Claude Code 的同名工具同一个形状。
+ */
+/**
+ * 一个问题的去向。
+ *
+ * - `pending`：等用户回答（一个会话同时至多一个）。
+ * - `answered`：用户点选后提交了。
+ * - `expired`：到了 `deadlineAt` 没人答，按默认项继续。
+ * - `superseded`：用户没点选项、改为直接打字回复——那句话本身就是回答。
+ * - `cancelled`：作废了——用户按了停止、等它的那一轮中断了、或等过了上限。
+ */
+export const AGENT_QUESTION_STATUSES = [
+    'pending',
+    'answered',
+    'expired',
+    'superseded',
+    'cancelled',
+];
+export const ASK_MAX_QUESTIONS = 4;
+export const ASK_MIN_OPTIONS = 2;
+export const ASK_MAX_OPTIONS = 4;
+/** 「其他」里用户自己写的那句话的上限。 */
+export const ASK_OTHER_MAX_CHARS = 500;
+export const AskOptionSchema = z.object({
+    label: z
+        .string()
+        .trim()
+        .min(1)
+        .max(60)
+        .describe('选项名，简短（1–5 个词），同一题内不得重复'),
+    description: z
+        .string()
+        .trim()
+        .max(200)
+        .optional()
+        .describe('选了它意味着什么、有什么取舍。用户看着它做决定'),
+});
+export const AskQuestionItemSchema = z.object({
+    question: z
+        .string()
+        .trim()
+        .min(1)
+        .max(300)
+        .describe('完整的问题，一句话，以问号结尾'),
+    header: z
+        .string()
+        .trim()
+        .min(1)
+        .max(12)
+        .describe('这个问题的短标签（不超过 12 个字），如「开场方式」'),
+    options: z
+        .array(AskOptionSchema)
+        .min(ASK_MIN_OPTIONS)
+        .max(ASK_MAX_OPTIONS)
+        .describe('2–4 个互斥的选项。不要自己写「其他」——界面永远会提供一个让用户自由输入的「其他」'),
+    multiSelect: z.boolean().default(false).describe('是否允许选多个'),
+    defaultOption: z
+        .string()
+        .trim()
+        .optional()
+        .describe('用户不回答这一题时采用哪个选项，必须逐字等于某个选项的 label。**给了它，这一题用户就可以跳过**（提交时按它算，等待超时也按它算）；不给，这一题必答。给了 timeoutSeconds 时每一题都必须有'),
+});
+/**
+ * 工具入参。三条交叉校验写在 schema 上而不是工具里：错误会随 zod 的 issue 路径
+ * 回给模型，它能看出是第几题的哪个字段。
+ */
+export const AskInputSchema = z
+    .object({
+    questions: z.array(AskQuestionItemSchema).min(1).max(ASK_MAX_QUESTIONS),
+    timeoutSeconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('最多等多少秒；到点没人回答就按每一题的 defaultOption 继续。不给 = 一直等到用户回答'),
+})
+    .superRefine((input, ctx) => {
+    input.questions.forEach((q, i) => {
+        const labels = q.options.map(o => o.label);
+        if (new Set(labels).size !== labels.length) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['questions', i, 'options'],
+                message: '同一题里的选项 label 不能重复',
+            });
+        }
+        if (q.defaultOption !== undefined && !labels.includes(q.defaultOption)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['questions', i, 'defaultOption'],
+                message: `defaultOption 必须逐字等于某个选项的 label（可选：${labels.join(' / ')}）`,
+            });
+        }
+        if (input.timeoutSeconds !== undefined && q.defaultOption === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['questions', i, 'defaultOption'],
+                message: '给了 timeoutSeconds 就必须给每一题写 defaultOption——到点之后要按它继续',
+            });
+        }
+    });
+});
+/**
+ * 提交回答。`answers` 与问题**按下标对齐**、长度必须相等。
+ * 单选题：`labels` 恰好一个且无 `other`，或 `labels` 为空且有 `other`；
+ * 多选题：两者合计至少一项。**两者都空 = 跳过这一题**：有默认项的题按默认项算，
+ * 没有默认项的题（必答）会被拒绝。具体校验在服务里（要对着那一行的选项判）。
+ */
+export const AnswerAgentQuestionRequestSchema = z.object({
+    answers: z
+        .array(z.object({
+        labels: z.array(z.string()).max(ASK_MAX_OPTIONS).default([]),
+        other: z.string().trim().max(ASK_OTHER_MAX_CHARS).optional(),
+    }))
+        .min(1)
+        .max(ASK_MAX_QUESTIONS),
+});
+//# sourceMappingURL=ask-schema.js.map

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

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