botmux 2.47.0 → 2.47.2

package/dist/core/ask-api.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure helpers for the daemon's `POST /api/asks` IPC route.
+ *
+ * Kept separate from daemon.ts so the body-validator and the approver
+ * fallback chain (§6) are unit-testable without spinning up an HTTP server,
+ * registering bots, or mounting a full session map.
+ */
+import type { AskQuestion } from './ask-types.js';
+export interface AskApiBody {
+    sessionId: string;
+    chatId: string;
+    larkAppId: string;
+    rootMessageId: string | null;
+    /** v0.1.8：替换旧的 options/prompt，支持多问多选。 */
+    questions: AskQuestion[];
+    /** Already in milliseconds. CLI side converts from `--timeout` seconds. */
+    timeoutMs: number;
+    /** Empty array → use the §6 fallback chain. */
+    approvers: string[];
+}
+export type AskApiBodyError = 'bad_body' | 'bad_sessionId' | 'bad_chatId' | 'bad_larkAppId' | 'bad_rootMessageId' | 'bad_prompt' | 'bad_timeoutMs' | 'bad_options' | 'bad_option_shape' | 'bad_option_key' | 'bad_option_label' | 'duplicate_option_key' | 'bad_questions' | 'bad_question_shape' | 'bad_multiSelect';
+/** Validate the request body. Returns either the parsed body or an error code
+ *  ready to be sent back as `{ ok: false, error }` with HTTP 400.
+ *
+ *  v0.1.8：
+ *  - 优先识别 `questions[]` 新格式（多问多选）。
+ *  - 兼容旧的 `options[]` + `prompt` 格式，归一化为单问单选的 questions[]。
+ *  - 两者都没有则返回 `bad_options`。 */
+export declare function parseAskBody(raw: unknown): AskApiBody | {
+    error: AskApiBodyError;
+};
+/** Resolve the approver allowlist per §6 fallback chain:
+ *   1. explicit `--approver` list from CLI args (non-empty wins outright)
+ *   2. session.ownerOpenId ∩ bot.allowedUsers (single-owner topic chats)
+ *   3. bot.allowedUsers (shared chats / no owner / owner not in allow)
+ *
+ *  Pure function: caller injects the lookups. The daemon wires
+ *  `getBotAllowedUsers = (id) => getBot(id).resolvedAllowedUsers` and
+ *  `getSessionOwner` = scan over activeSessions; tests pass stub funcs. */
+export declare function resolveAskApprovers(args: {
+    larkAppId: string;
+    sessionId: string;
+    explicit: ReadonlyArray<string>;
+    getBotAllowedUsers: (larkAppId: string) => ReadonlyArray<string>;
+    getSessionOwner: (sessionId: string) => string | undefined;
+}): Set<string>;
+//# sourceMappingURL=ask-api.d.ts.map

package/dist/core/ask-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-api.d.ts","sourceRoot":"","sources":["../../src/core/ask-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yCAAyC;IACzC,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,eAAe,GACf,mBAAmB,GACnB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,sBAAsB,GACtB,eAAe,GACf,oBAAoB,GACpB,iBAAiB,CAAC;AAkCtB;;;;;;gCAMgC;AAChC,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG;IAAE,KAAK,EAAE,eAAe,CAAA;CAAE,CA4DlF;AAED;;;;;;;2EAO2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC;IACjE,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC5D,GAAG,GAAG,CAAC,MAAM,CAAC,CAQd"}

package/dist/core/ask-api.js

@@ -0,0 +1,139 @@
+/**
+ * Pure helpers for the daemon's `POST /api/asks` IPC route.
+ *
+ * Kept separate from daemon.ts so the body-validator and the approver
+ * fallback chain (§6) are unit-testable without spinning up an HTTP server,
+ * registering bots, or mounting a full session map.
+ */
+/** 校验单个 option 对象，返回解析后的 AskOption 或错误码。 */
+function parseOption(o) {
+    if (!o || typeof o !== 'object')
+        return 'bad_option_shape';
+    const oo = o;
+    if (typeof oo.key !== 'string' || !oo.key.trim())
+        return 'bad_option_key';
+    if (typeof oo.label !== 'string')
+        return 'bad_option_label';
+    return { key: oo.key, label: oo.label };
+}
+/** 校验 questions[] 数组，返回解析后的 AskQuestion[] 或错误码。 */
+function parseQuestions(arr) {
+    const result = [];
+    for (const q of arr) {
+        if (!q || typeof q !== 'object' || Array.isArray(q))
+            return 'bad_question_shape';
+        const qq = q;
+        if (typeof qq.prompt !== 'string' || !qq.prompt.trim())
+            return 'bad_question_shape';
+        if (typeof qq.multiSelect !== 'boolean')
+            return 'bad_multiSelect';
+        if (!Array.isArray(qq.options) || qq.options.length < 2)
+            return 'bad_options';
+        const opts = [];
+        const seen = new Set();
+        for (const o of qq.options) {
+            const parsed = parseOption(o);
+            if (typeof parsed === 'string')
+                return parsed;
+            if (seen.has(parsed.key))
+                return 'duplicate_option_key';
+            seen.add(parsed.key);
+            opts.push(parsed);
+        }
+        result.push({ prompt: qq.prompt, multiSelect: qq.multiSelect, options: opts });
+    }
+    return result;
+}
+/** Validate the request body. Returns either the parsed body or an error code
+ *  ready to be sent back as `{ ok: false, error }` with HTTP 400.
+ *
+ *  v0.1.8：
+ *  - 优先识别 `questions[]` 新格式（多问多选）。
+ *  - 兼容旧的 `options[]` + `prompt` 格式，归一化为单问单选的 questions[]。
+ *  - 两者都没有则返回 `bad_options`。 */
+export function parseAskBody(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { error: 'bad_body' };
+    const r = raw;
+    if (typeof r.sessionId !== 'string' || !r.sessionId.trim())
+        return { error: 'bad_sessionId' };
+    if (typeof r.chatId !== 'string' || !r.chatId.trim())
+        return { error: 'bad_chatId' };
+    if (typeof r.larkAppId !== 'string' || !r.larkAppId.trim())
+        return { error: 'bad_larkAppId' };
+    if (r.rootMessageId !== null && typeof r.rootMessageId !== 'string') {
+        return { error: 'bad_rootMessageId' };
+    }
+    if (typeof r.timeoutMs !== 'number' ||
+        !Number.isFinite(r.timeoutMs) ||
+        r.timeoutMs < 1000) {
+        return { error: 'bad_timeoutMs' };
+    }
+    const approvers = Array.isArray(r.approvers)
+        ? r.approvers.filter((s) => typeof s === 'string' && s.trim().length > 0)
+        : [];
+    let questions;
+    if (Array.isArray(r.questions)) {
+        // 新格式：questions[] 多问多选
+        if (r.questions.length === 0)
+            return { error: 'bad_questions' };
+        const parsed = parseQuestions(r.questions);
+        if (typeof parsed === 'string')
+            return { error: parsed };
+        questions = parsed;
+    }
+    else if (Array.isArray(r.options) && typeof r.prompt === 'string' && r.prompt.trim()) {
+        // 旧格式兼容：options[] + prompt → 归一化为单问单选
+        if (r.options.length < 2)
+            return { error: 'bad_options' };
+        const opts = [];
+        const seen = new Set();
+        for (const o of r.options) {
+            const parsed = parseOption(o);
+            if (typeof parsed === 'string')
+                return { error: parsed };
+            if (seen.has(parsed.key))
+                return { error: 'duplicate_option_key' };
+            seen.add(parsed.key);
+            opts.push(parsed);
+        }
+        questions = [{ prompt: r.prompt, multiSelect: false, options: opts }];
+    }
+    else {
+        // 旧格式：仅有 prompt 校验（无 options 或 options 不合法）
+        if (typeof r.prompt !== 'string' || !r.prompt.trim())
+            return { error: 'bad_prompt' };
+        if (!Array.isArray(r.options) || r.options.length < 2)
+            return { error: 'bad_options' };
+        // 走到这里说明 options 是数组但长度不足，上面已处理，此处不可达
+        return { error: 'bad_options' };
+    }
+    return {
+        sessionId: r.sessionId,
+        chatId: r.chatId,
+        larkAppId: r.larkAppId,
+        rootMessageId: r.rootMessageId,
+        questions,
+        timeoutMs: r.timeoutMs,
+        approvers,
+    };
+}
+/** Resolve the approver allowlist per §6 fallback chain:
+ *   1. explicit `--approver` list from CLI args (non-empty wins outright)
+ *   2. session.ownerOpenId ∩ bot.allowedUsers (single-owner topic chats)
+ *   3. bot.allowedUsers (shared chats / no owner / owner not in allow)
+ *
+ *  Pure function: caller injects the lookups. The daemon wires
+ *  `getBotAllowedUsers = (id) => getBot(id).resolvedAllowedUsers` and
+ *  `getSessionOwner` = scan over activeSessions; tests pass stub funcs. */
+export function resolveAskApprovers(args) {
+    const explicit = args.explicit.filter((s) => s.trim().length > 0);
+    if (explicit.length > 0)
+        return new Set(explicit);
+    const allow = args.getBotAllowedUsers(args.larkAppId);
+    const owner = args.getSessionOwner(args.sessionId);
+    if (owner && allow.includes(owner))
+        return new Set([owner]);
+    return new Set(allow);
+}
+//# sourceMappingURL=ask-api.js.map

package/dist/core/ask-api.js.map

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

package/dist/core/ask-args.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure helpers for `botmux ask` argument parsing.
+ *
+ * Kept in its own file (no I/O, no env reads) so the CSV / timeout / approver
+ * parsing can be unit-tested without spinning up a daemon. The actual CLI
+ * dispatch (`cmdAsk`) lives in cli.ts and calls these helpers.
+ */
+import type { AskOption } from './ask-types.js';
+export declare class AskArgsError extends Error {
+    readonly code: 'options_missing' | 'options_too_few' | 'options_empty_key' | 'options_duplicate_key' | 'timeout_out_of_range' | 'timeout_not_number';
+    constructor(code: 'options_missing' | 'options_too_few' | 'options_empty_key' | 'options_duplicate_key' | 'timeout_out_of_range' | 'timeout_not_number', message: string);
+}
+/** Parse `--options` CSV. Each item is either `key` (key==label) or `key=label`.
+ *
+ *  Rules:
+ *   - Trims whitespace around each item and around `key=label` halves.
+ *   - Drops empty items (trailing commas / `"a,,b"`); does not count them.
+ *   - Requires ≥ 2 distinct keys after parsing.
+ *   - Empty `key` (e.g. `"=label"`) is rejected.
+ *   - Duplicate keys are rejected — let the caller surface a clear error rather
+ *     than silently de-duping (which would change observable button count).
+ *   - The first `=` splits key/label; subsequent `=` are part of the label, so
+ *     `"go=继续=右"` → key=`go`, label=`继续=右`. */
+export declare function parseAskOptions(raw: string | undefined): AskOption[];
+/** Parse `--timeout <seconds>` → milliseconds. Bounds match §7:
+ *   - lower bound: 10s (sub-10s asks are almost always a bug)
+ *   - upper bound: 3600s (1h — past that, recovery should kick in v0.1.8)
+ *   - default: 300s (caller passes `undefined` to use it) */
+export declare function parseAskTimeoutSeconds(raw: string | undefined, defaults?: {
+    default: number;
+    min: number;
+    max: number;
+}): number;
+/** Resolve the `(sub, rest)` pair for `botmux ask`'s top-level dispatch.
+ *
+ *  Input: positional args *after* the `ask` token. So for the user typing
+ *  `botmux ask buttons --options yes,no "prompt"` we get
+ *  `['buttons', '--options', 'yes,no', 'prompt']`; for the bare alias
+ *  `botmux ask --options yes,no "prompt"` we get
+ *  `['--options', 'yes,no', 'prompt']`.
+ *
+ *  The first positional starting with `--` means the user skipped the
+ *  subcommand and went straight to flags — that's the bare-alias path; we
+ *  return `sub=''` and let `cmdAsk` apply its v0.1.7 `buttons` default.
+ *  Otherwise the first positional is the subcommand. */
+export declare function normalizeAskDispatch(tail: ReadonlyArray<string>): {
+    sub: string;
+    rest: string[];
+};
+/** Required env vars on the CLI side (§5). Returns the first missing one so
+ *  the caller can produce a single, specific error message. */
+export declare function findMissingAskEnv(env: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=ask-args.d.ts.map

package/dist/core/ask-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-args.d.ts","sourceRoot":"","sources":["../../src/core/ask-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,qBAAa,YAAa,SAAQ,KAAK;aAEnB,IAAI,EAChB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,uBAAuB,GACvB,sBAAsB,GACtB,oBAAoB;gBANR,IAAI,EAChB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,uBAAuB,GACvB,sBAAsB,GACtB,oBAAoB,EACxB,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;+CAU+C;AAC/C,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,CA8CpE;AAED;;;6DAG6D;AAC7D,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,GAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAIpD,GACA,MAAM,CAkBR;AAED;;;;;;;;;;;wDAWwD;AACxD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAMjC;AAED;+DAC+D;AAC/D,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,IAAI,CAWf"}

package/dist/core/ask-args.js

@@ -0,0 +1,122 @@
+/**
+ * Pure helpers for `botmux ask` argument parsing.
+ *
+ * Kept in its own file (no I/O, no env reads) so the CSV / timeout / approver
+ * parsing can be unit-tested without spinning up a daemon. The actual CLI
+ * dispatch (`cmdAsk`) lives in cli.ts and calls these helpers.
+ */
+export class AskArgsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AskArgsError';
+    }
+}
+/** Parse `--options` CSV. Each item is either `key` (key==label) or `key=label`.
+ *
+ *  Rules:
+ *   - Trims whitespace around each item and around `key=label` halves.
+ *   - Drops empty items (trailing commas / `"a,,b"`); does not count them.
+ *   - Requires ≥ 2 distinct keys after parsing.
+ *   - Empty `key` (e.g. `"=label"`) is rejected.
+ *   - Duplicate keys are rejected — let the caller surface a clear error rather
+ *     than silently de-duping (which would change observable button count).
+ *   - The first `=` splits key/label; subsequent `=` are part of the label, so
+ *     `"go=继续=右"` → key=`go`, label=`继续=右`. */
+export function parseAskOptions(raw) {
+    if (raw === undefined || raw.trim() === '') {
+        throw new AskArgsError('options_missing', '缺少 --options（需要 ≥ 2 项，例如 --options "yes,no" 或 --options "yes=继续,no=回滚"）');
+    }
+    const items = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const out = [];
+    const seen = new Set();
+    for (const item of items) {
+        const eq = item.indexOf('=');
+        let key;
+        let label;
+        if (eq < 0) {
+            key = item;
+            label = item;
+        }
+        else {
+            key = item.slice(0, eq).trim();
+            label = item.slice(eq + 1).trim();
+            if (label === '')
+                label = key; // `"yes="` → label falls back to key
+        }
+        if (key === '') {
+            throw new AskArgsError('options_empty_key', `--options 项的 key 不能为空（"${item}"）`);
+        }
+        if (seen.has(key)) {
+            throw new AskArgsError('options_duplicate_key', `--options 出现重复 key: ${key}`);
+        }
+        seen.add(key);
+        out.push({ key, label });
+    }
+    if (out.length < 2) {
+        throw new AskArgsError('options_too_few', `--options 至少需要 2 项，收到 ${out.length}`);
+    }
+    return out;
+}
+/** Parse `--timeout <seconds>` → milliseconds. Bounds match §7:
+ *   - lower bound: 10s (sub-10s asks are almost always a bug)
+ *   - upper bound: 3600s (1h — past that, recovery should kick in v0.1.8)
+ *   - default: 300s (caller passes `undefined` to use it) */
+export function parseAskTimeoutSeconds(raw, defaults = {
+    default: 300,
+    min: 10,
+    max: 3600,
+}) {
+    if (raw === undefined)
+        return defaults.default * 1000;
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return defaults.default * 1000;
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        throw new AskArgsError('timeout_not_number', `--timeout 必须是整数秒数，收到 "${raw}"`);
+    }
+    if (n < defaults.min || n > defaults.max) {
+        throw new AskArgsError('timeout_out_of_range', `--timeout 范围 [${defaults.min}, ${defaults.max}] 秒，收到 ${n}`);
+    }
+    return n * 1000;
+}
+/** Resolve the `(sub, rest)` pair for `botmux ask`'s top-level dispatch.
+ *
+ *  Input: positional args *after* the `ask` token. So for the user typing
+ *  `botmux ask buttons --options yes,no "prompt"` we get
+ *  `['buttons', '--options', 'yes,no', 'prompt']`; for the bare alias
+ *  `botmux ask --options yes,no "prompt"` we get
+ *  `['--options', 'yes,no', 'prompt']`.
+ *
+ *  The first positional starting with `--` means the user skipped the
+ *  subcommand and went straight to flags — that's the bare-alias path; we
+ *  return `sub=''` and let `cmdAsk` apply its v0.1.7 `buttons` default.
+ *  Otherwise the first positional is the subcommand. */
+export function normalizeAskDispatch(tail) {
+    const next = tail[0] ?? '';
+    if (next.startsWith('--')) {
+        return { sub: '', rest: tail.slice(0) };
+    }
+    return { sub: next, rest: tail.slice(1) };
+}
+/** Required env vars on the CLI side (§5). Returns the first missing one so
+ *  the caller can produce a single, specific error message. */
+export function findMissingAskEnv(env) {
+    const required = [
+        'BOTMUX_SESSION_ID',
+        'BOTMUX_CHAT_ID',
+        'BOTMUX_LARK_APP_ID',
+        'BOTMUX_ROOT_MESSAGE_ID',
+    ];
+    for (const k of required) {
+        if (!env[k] || !env[k].trim())
+            return k;
+    }
+    return null;
+}
+//# sourceMappingURL=ask-args.js.map

package/dist/core/ask-args.js.map

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

package/dist/core/ask-broker.d.ts

@@ -0,0 +1,98 @@
+/**
+ * In-memory broker for `botmux ask` (v0.1.8).
+ *
+ * Holds the pending-ask registry, runs the deadline timers, and arbitrates
+ * click resolution. IM-agnostic: the im/lark side wires a dispatcher via
+ * `setCardDispatcher` so the broker doesn't import Lark types.
+ *
+ * §3 / §6 / §7 / §8 of /tmp/botmux-ask.md.
+ */
+import type { AskCardDispatcher, AskClickOutcome, AskResult, CreateAskInput, PendingAsk } from './ask-types.js';
+/** Wire the IM-side dispatcher. Called once during daemon bootstrap from
+ *  daemon.ts after im/lark/ask-card.ts is constructed. */
+export declare function setCardDispatcher(d: AskCardDispatcher): void;
+/** Register a new pending ask. Returns a Promise that settles when:
+ *   - a valid click arrives (`kind:'answered'`)
+ *   - the deadline elapses (`kind:'timedOut'`)
+ *   - the broker invalidates the ask (`kind:'invalidated'`)
+ *
+ *  Side effects:
+ *   - generates askId + nonce
+ *   - starts the deadline timer
+ *   - dispatches the card; if the card send fails, the ask is immediately
+ *     invalidated and the Promise settles with `kind:'invalidated'`.
+ *
+ *  Throws synchronously only if no dispatcher has been wired — that's a
+ *  daemon-misconfiguration bug, not a runtime ask failure.
+ */
+export declare function registerAsk(input: CreateAskInput): Promise<AskResult>;
+/**
+ * 勾选/取消勾选某问题的某个选项（累积模式，不 settle）。
+ *
+ * 校验同 `tryResolveAsk`：askId 存在 / nonce 匹配 / 未 settle / 已授权 /
+ * questionIndex 合法 / key 在该问题的 options 中。
+ *
+ * 对于单选问题（multiSelect:false），翻转时 Set 内只保留该 key（相当于"换选"）。
+ * 对于多选问题（multiSelect:true），翻转规则：已在 Set 中则移除，否则添加。
+ *
+ * 成功返回 `'toggled'`；非法返回对应 AskClickOutcome。
+ */
+export declare function toggleAsk(args: {
+    askId: string;
+    nonce: string;
+    questionIndex: number;
+    key: string;
+    by: string;
+}): AskClickOutcome;
+/**
+ * 提交答案并 settle。
+ *
+ * `selections` 显式传入时直接使用（按钮单选 / 一次性表单提交场景）；
+ * 否则使用 `toggleAsk` 累积的勾选状态。
+ *
+ * 对于 `multiSelect:false` 的问题，要求恰好 1 个选中，否则返回 `'stale'`。
+ * 校验通过则 settle 并返回 `'accepted'`；非法返回对应 AskClickOutcome。
+ */
+export declare function submitAsk(args: {
+    askId: string;
+    nonce: string;
+    by: string;
+    selections?: ReadonlyArray<ReadonlyArray<string>>;
+}): AskClickOutcome;
+/** Resolve attempt from a card-button click. Returns one of the §10 outcomes;
+ *  caller (card click handler) maps to user-facing toast.
+ *
+ *  v0.1.8 起退化为单问单选的便捷封装：等价于
+ *  `submitAsk({..., selections:[[selected]]})`.
+ *  使 `botmux ask buttons` 与其已有测试零回归。
+ *
+ *  All four "no-op" outcomes (`unauthorized`/`stale`/`already_settled`) leave
+ *  the broker state unchanged so the original CLI Promise keeps waiting for
+ *  the real winner or the deadline. */
+export declare function tryResolveAsk(args: {
+    askId: string;
+    nonce: string;
+    selected: string;
+    by: string;
+}): AskClickOutcome;
+/** Invalidate every pending ask. Intended for daemon shutdown / restart paths
+ *  so CLI subprocesses unblock with `kind:'invalidated'` instead of waiting
+ *  forever on a dead daemon. Returns the number of asks actually settled
+ *  (settled-but-retained entries from the race window are skipped). */
+export declare function invalidateAll(reason: string): number;
+/** Count of asks still awaiting a click / timeout — excludes settled entries
+ *  retained within the race-loser feedback window. For tests and metrics only. */
+export declare function _pendingCount(): number;
+/** Read a pending ask by id. Returns a snapshot; mutating it has no effect on
+ *  broker state. Used by the card handler to PATCH toggle state. */
+export declare function getAskSnapshot(askId: string): PendingAsk | undefined;
+/** Read a pending ask by id — for tests only. Returns a snapshot; mutating it
+ *  has no effect on broker state. */
+export declare function _getPending(askId: string): PendingAsk | undefined;
+/** 返回当前 pending map 中所有 askId 列表（含 settled 但仍在 retention 内的条目）。
+ *  仅供测试使用。 */
+export declare function _allAskIds(): string[];
+/** Reset broker state — for tests only. Does NOT resolve outstanding promises,
+ *  so tests must not call this while real CLI processes might be waiting. */
+export declare function _resetForTest(): void;
+//# sourceMappingURL=ask-broker.d.ts.map

package/dist/core/ask-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-broker.d.ts","sourceRoot":"","sources":["../../src/core/ask-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,cAAc,EACd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAwBxB;0DAC0D;AAC1D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAmErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,eAAe,CA4BlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;CACnD,GAAG,eAAe,CA2ClB;AAED;;;;;;;;;uCASuC;AACvC,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,eAAe,CAOlB;AAED;;;uEAGuE;AACvE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBpD;AA8DD;kFACkF;AAClF,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED;oEACoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAGpE;AAED;qCACqC;AACrC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEjE;AAED;cACc;AACd,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,IAAI,IAAI,CAIpC"}