@optima-chat/agentic-sdk 0.26.2 → 0.27.0

package/dist/client/delivery-outbox.d.ts

@@ -0,0 +1,84 @@
+/**
+ * gw#1587 客户端投递保证：出站 outbox 状态机 + 串行 drain 调度器。
+ *
+ * 语义源 = spec gw-1587-client-msg-delivery §5.1/§5.2/§5.3（v6.1，五轮评审收敛）。
+ * 关键不变量：
+ *  - G1：armed 连接上带生效 client_msg_id 的消息，终态只有 delivered / failed（可见可重试）。
+ *  - 终态信号 = reconnect_exhausted / 显式 disconnect() / disarm 判定——**绝不用**
+ *    'disconnected' 状态回调（reconnect() 的 identity guard 吞 onclose、不发回调，§1.8）。
+ *  - eventwait 60s 重探**不计 transientCount**（15min 兜底是唯一上限——v4 评审：计数会使
+ *    5×60s 恒先到顶，5-15min 在飞 turn false-failed 复活）。
+ *  - deliveryState 只驱动消息级指示，**绝不写 conv 级 processing/isThinking**（§5.4）。
+ */
+export type DeliveryState = 'pending' | 'delivered' | 'failed';
+export type FailedCause = 'arm_timeout' | 'disarm' | 'conn_terminal' | 'terminal' | 'timeout_exhaust' | 'transient_exhaust';
+export interface DeliveryOutboxHooks {
+    /** 直发一帧（true=已写入 socket buffer）。 */
+    sendFrame(frameJson: string): boolean;
+    /** ack 超时时主动重连（僵尸 socket 主模式的唯一有效动作，§1.8/F4）。 */
+    reconnect(): void;
+    /** 消息级投递状态变化（→ store per-message deliveryState；绝不碰 conv 级态）。 */
+    onStateChange(clientMsgId: string, state: DeliveryState, cause?: FailedCause): void;
+    /**
+     * MAJOR-2 修：一条帧真正投出（drain dispatch）时回调——host 在此置 thinking（spec §5.1
+     * 「入队不置 thinking，drain 投出时置位」）。gap 入队后终局 failed 的消息从不 dispatch →
+     * 不置 thinking → 不 wedge composer（#619 同型）。
+     */
+    onDispatch?(clientMsgId: string, conversationId: string): void;
+}
+export declare class DeliveryOutbox {
+    private readonly hooks;
+    private entries;
+    private draining;
+    private drainAgain;
+    private armed;
+    private connected;
+    private reconnectRequestedForTimeout;
+    constructor(hooks: DeliveryOutboxHooks);
+    /** connected 边沿（armed 判定尚未发生——只记状态，不 drain）。 */
+    onConnected(): void;
+    /** 连接断开（非终态——正常重连路径；in-flight ack 等待作废回 pending）。 */
+    onDisconnected(): void;
+    /**
+     * armed 判定（本连接 session_ready 处理完成 / 10s 兜底）。
+     * armed=true：全量 drain（eventwait 转 pending + failedCause∈{arm_timeout,disarm} 且未
+     * retry 的条目自动恢复——**跨连接**也生效，§5.1 恢复规则）。
+     * armed=false（disarm/兜底）：存量非 delivered 全量 failed（G1 例外③）。
+     */
+    onArmedDecision(armed: boolean, cause: 'session_ready' | 'arm_timeout'): void;
+    /** 终态信号：reconnect_exhausted / 显式 disconnect()。 */
+    onConnTerminal(): void;
+    get isArmed(): boolean;
+    /** armed 下 sendMessage 入队（先于任何 send；由 drain 统一按序投）。 */
+    enqueue(clientMsgId: string, conversationId: string, frame: Record<string, unknown>): void;
+    /**
+     * 手动重试（§5.2）：同 id、双计数归零（归零后从 0 重计）、resend:true；
+     * eventwait 中重试同语义；retry 后再次进入 eventwait 视为新「首次进入」（时钟重置）。
+     * disarmed 连接的 retry 由调用方（GatewayClient）走旧语义重发并调 removeEntry。
+     */
+    retry(clientMsgId: string): boolean;
+    /** disarmed retry：旧语义重发由调用方做，条目出 outbox（无跟踪，spec §5.1 明文）。 */
+    removeEntry(clientMsgId: string): Record<string, unknown> | null;
+    getState(clientMsgId: string): {
+        state: DeliveryState | 'eventwait';
+        failedCause?: FailedCause;
+    } | null;
+    /** PR-A「id∈本 tab outbox」判定（duplicate finish 提示过滤等）。 */
+    has(clientMsgId: string): boolean;
+    /** 只读取帧（disarmed retry 发送成功前不出队，MINOR-2）。 */
+    peekFrame(clientMsgId: string): Record<string, unknown> | null;
+    routeEvent(event: Record<string, unknown>): void;
+    private toPending;
+    private toEventwait;
+    private onTransient;
+    private toFailed;
+    private failAllNonDelivered;
+    private emit;
+    private emitState;
+    private clearTimers;
+    private kickDrain;
+    private drainLoop;
+    private dispatchOne;
+    private onAckTimeout;
+}
+//# sourceMappingURL=delivery-outbox.d.ts.map

package/dist/client/delivery-outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-outbox.d.ts","sourceRoot":"","sources":["../../src/client/delivery-outbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAC/D,MAAM,MAAM,WAAW,GACnB,aAAa,GACb,QAAQ,GACR,eAAe,GACf,UAAU,GACV,iBAAiB,GACjB,mBAAmB,CAAC;AAsBxB,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,iDAAiD;IACjD,SAAS,IAAI,IAAI,CAAC;IAClB,gEAAgE;IAChE,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACpF;;;;OAIG;IACH,UAAU,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAChE;AA0BD,qBAAa,cAAc;IAQb,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPlC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,4BAA4B,CAAS;gBAEhB,KAAK,EAAE,mBAAmB;IAIvD,gDAAgD;IAChD,WAAW,IAAI,IAAI;IAUnB,qDAAqD;IACrD,cAAc,IAAI,IAAI;IAUtB;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,aAAa,GAAG,IAAI;IAmB7E,kDAAkD;IAClD,cAAc,IAAI,IAAI;IAItB,IAAI,OAAO,IAAI,OAAO,CAErB;IAID,uDAAuD;IACvD,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAY1F;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAmBnC,8DAA8D;IAC9D,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQhE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI;IAKvG,uDAAuD;IACvD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIjC,6CAA6C;IAC7C,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAM9D,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAqEhD,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,SAAS;YAKH,SAAS;IA4BvB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,YAAY;CAerB"}

package/dist/client/delivery-outbox.js

@@ -0,0 +1,377 @@
+/**
+ * gw#1587 客户端投递保证：出站 outbox 状态机 + 串行 drain 调度器。
+ *
+ * 语义源 = spec gw-1587-client-msg-delivery §5.1/§5.2/§5.3（v6.1，五轮评审收敛）。
+ * 关键不变量：
+ *  - G1：armed 连接上带生效 client_msg_id 的消息，终态只有 delivered / failed（可见可重试）。
+ *  - 终态信号 = reconnect_exhausted / 显式 disconnect() / disarm 判定——**绝不用**
+ *    'disconnected' 状态回调（reconnect() 的 identity guard 吞 onclose、不发回调，§1.8）。
+ *  - eventwait 60s 重探**不计 transientCount**（15min 兜底是唯一上限——v4 评审：计数会使
+ *    5×60s 恒先到顶，5-15min 在飞 turn false-failed 复活）。
+ *  - deliveryState 只驱动消息级指示，**绝不写 conv 级 processing/isThinking**（§5.4）。
+ */
+const ACK_TIMEOUT_MS = 10_000;
+const MAX_SENDS = 3;
+const MAX_TRANSIENT = 5;
+const BACKOFF_BASE_MS = 5_000;
+const BACKOFF_CAP_MS = 60_000;
+const EVENTWAIT_PROBE_MS = 60_000;
+const EVENTWAIT_CEILING_MS = 15 * 60_000;
+const MIN_RESEND_GAP_MS = 1_000;
+/** billing_error 分类（spec §3.3）：rate_limited → transient；其余一切值（含未知）→ terminal。 */
+function billingIsTransient(reason) {
+    return reason === 'rate_limited';
+}
+/** 终结腿 error code 分类（spec §3.3 表）。 */
+const TERMINAL_ERROR_CODES = new Set(['GUARDRAIL_BLOCKED', 'CONVERSATION_ID_REQUIRED']);
+const TRANSIENT_ERROR_CODES = new Set(['SESSION_NOT_FOUND', 'MESSAGE_SAVE_FAILED', 'MESSAGE_QUEUE_FULL']);
+const EVENTWAIT_ERROR_CODE = 'CONCURRENT_CONVERSATION_BLOCKED';
+/** eventwait 等待键有效判据（v6 钉死）：非空 string 且 ≠'unknown' 哨兵。 */
+function validWaitKey(v) {
+    return typeof v === 'string' && v.length > 0 && v !== 'unknown';
+}
+export class DeliveryOutbox {
+    hooks;
+    entries = new Map();
+    draining = false;
+    drainAgain = false;
+    armed = false;
+    connected = false;
+    reconnectRequestedForTimeout = false; // 并发超时去抖：一轮至多一次 reconnect
+    constructor(hooks) {
+        this.hooks = hooks;
+    }
+    // ── 连接生命周期（由 GatewayClient 驱动） ──────────────────────
+    /** connected 边沿（armed 判定尚未发生——只记状态，不 drain）。 */
+    onConnected() {
+        this.connected = true;
+        // MAJOR-1 修：armed 必随连接重置为 false——判定在本连接 session_ready/兜底后重新下发。
+        // 否则重连 gap 内保留上一连接的 armed=true，enqueue/backoff-到期/迟到 receipt 的
+        // kickDrain 会在 session_ready 之前直发（spec §5.1「判定前窗口只入队不发」的 reconnect
+        // 路径回归——三方同判 BLOCKING 骨架不变量）。
+        this.armed = false;
+        this.reconnectRequestedForTimeout = false;
+    }
+    /** 连接断开（非终态——正常重连路径；in-flight ack 等待作废回 pending）。 */
+    onDisconnected() {
+        this.connected = false;
+        for (const e of this.entries.values()) {
+            if (e.awaitingAck) {
+                this.clearTimers(e);
+                e.awaitingAck = false; // 回 pending，重连 armed 后由 drain 重投
+            }
+        }
+    }
+    /**
+     * armed 判定（本连接 session_ready 处理完成 / 10s 兜底）。
+     * armed=true：全量 drain（eventwait 转 pending + failedCause∈{arm_timeout,disarm} 且未
+     * retry 的条目自动恢复——**跨连接**也生效，§5.1 恢复规则）。
+     * armed=false（disarm/兜底）：存量非 delivered 全量 failed（G1 例外③）。
+     */
+    onArmedDecision(armed, cause) {
+        this.armed = armed;
+        if (armed) {
+            for (const e of this.entries.values()) {
+                if (e.state === 'eventwait')
+                    this.toPending(e);
+                else if (e.state === 'failed' && !e.userRetried
+                    && (e.failedCause === 'arm_timeout' || e.failedCause === 'disarm')) {
+                    e.state = 'pending';
+                    e.failedCause = undefined;
+                    this.emit(e, 'pending');
+                }
+            }
+            this.kickDrain();
+        }
+        else {
+            const failCause = cause === 'arm_timeout' ? 'arm_timeout' : 'disarm';
+            this.failAllNonDelivered(failCause);
+        }
+    }
+    /** 终态信号：reconnect_exhausted / 显式 disconnect()。 */
+    onConnTerminal() {
+        this.failAllNonDelivered('conn_terminal');
+    }
+    get isArmed() {
+        return this.armed;
+    }
+    // ── 入队与重试 ────────────────────────────────────────────────
+    /** armed 下 sendMessage 入队（先于任何 send；由 drain 统一按序投）。 */
+    enqueue(clientMsgId, conversationId, frame) {
+        if (this.entries.has(clientMsgId))
+            return; // 幂等
+        this.entries.set(clientMsgId, {
+            clientMsgId, conversationId, frame,
+            state: 'pending', sendCount: 0, timeoutCount: 0, transientCount: 0,
+            lastSendAt: 0, enqueuedAt: Date.now(),
+            awaitingAck: false, userRetried: false,
+        });
+        this.emitState(clientMsgId, 'pending');
+        if (this.armed && this.connected)
+            this.kickDrain();
+    }
+    /**
+     * 手动重试（§5.2）：同 id、双计数归零（归零后从 0 重计）、resend:true；
+     * eventwait 中重试同语义；retry 后再次进入 eventwait 视为新「首次进入」（时钟重置）。
+     * disarmed 连接的 retry 由调用方（GatewayClient）走旧语义重发并调 removeEntry。
+     */
+    retry(clientMsgId) {
+        const e = this.entries.get(clientMsgId);
+        if (!e || e.state === 'delivered')
+            return false;
+        this.clearTimers(e);
+        e.userRetried = true;
+        e.sendCount = 0;
+        e.timeoutCount = 0;
+        e.transientCount = 0;
+        e.eventwaitKey = undefined;
+        e.eventwaitSince = undefined;
+        e.failedCause = undefined;
+        e.awaitingAck = false;
+        e.state = 'pending';
+        this.emit(e, 'pending');
+        if (this.connected && this.armed)
+            this.kickDrain();
+        else
+            this.hooks.reconnect(); // 非 connected：主动重连（§5.2 retryMessage 分支）
+        return true;
+    }
+    /** disarmed retry：旧语义重发由调用方做，条目出 outbox（无跟踪，spec §5.1 明文）。 */
+    removeEntry(clientMsgId) {
+        const e = this.entries.get(clientMsgId);
+        if (!e)
+            return null;
+        this.clearTimers(e);
+        this.entries.delete(clientMsgId);
+        return e.frame;
+    }
+    getState(clientMsgId) {
+        const e = this.entries.get(clientMsgId);
+        return e ? { state: e.state, failedCause: e.failedCause } : null;
+    }
+    /** PR-A「id∈本 tab outbox」判定（duplicate finish 提示过滤等）。 */
+    has(clientMsgId) {
+        return this.entries.has(clientMsgId);
+    }
+    /** 只读取帧（disarmed retry 发送成功前不出队，MINOR-2）。 */
+    peekFrame(clientMsgId) {
+        return this.entries.get(clientMsgId)?.frame ?? null;
+    }
+    // ── 事件路由（GatewayClient.handleMessage 每帧调用） ──────────────
+    routeEvent(event) {
+        const type = event['type'];
+        const cmid = event['client_msg_id'];
+        // 1) receipt：pending/eventwait → delivered；failed → delivered（迟到回执，§4.7 缓解②）
+        if (type === 'message_receipt' && typeof cmid === 'string') {
+            const e = this.entries.get(cmid);
+            if (!e)
+                return; // 旁观 tab / 未知——静默忽略
+            this.clearTimers(e);
+            e.awaitingAck = false;
+            e.state = 'delivered';
+            this.emit(e, 'delivered');
+            this.kickDrain(); // 串行 drain：本条到终态，投下一条
+            return;
+        }
+        // 2) 带本条目 id 的 error/billing_error/finish
+        if ((type === 'error' || type === 'billing_error' || type === 'finish') && typeof cmid === 'string') {
+            const e = this.entries.get(cmid);
+            if (!e)
+                return; // 旁观 tab：不动 outbox
+            if (e.state === 'delivered')
+                return; // post-receipt 腿（队列溢出等）：忽略，保持 delivered
+            if (e.state === 'failed')
+                return; // 已终态：只有迟到 receipt 能翻转
+            if (type === 'finish')
+                return; // 拒绝回声的配对 finish：不 wake 不 terminal（§5.2 排除规则）
+            if (type === 'billing_error') {
+                const reason = event['billing']?.['reason'];
+                if (billingIsTransient(reason))
+                    this.onTransient(e);
+                else
+                    this.toFailed(e, 'terminal');
+                return;
+            }
+            // type === 'error'
+            const code = event['error']?.['code'];
+            if (code === EVENTWAIT_ERROR_CODE) {
+                const waitKey = event['error']['activeConversationId'];
+                if (validWaitKey(waitKey))
+                    this.toEventwait(e, waitKey);
+                else
+                    this.onTransient(e); // 等待键无效（含 'unknown' 哨兵）→ 退化纯 backoff
+                return;
+            }
+            if (typeof code === 'string' && TERMINAL_ERROR_CODES.has(code)) {
+                this.toFailed(e, 'terminal');
+                return;
+            }
+            if (typeof code === 'string' && TRANSIENT_ERROR_CODES.has(code)) {
+                this.onTransient(e);
+                return;
+            }
+            // 未知 code：保守按 transient（retryable 语义缺省；超时漏斗兜底）
+            this.onTransient(e);
+            return;
+        }
+        // 3) eventwait wake：等待键 conv 的 finish/error 到达（不带本条目 id 的事件）
+        if ((type === 'finish' || type === 'error') && typeof event['conversation_id'] === 'string') {
+            const wakeConv = event['conversation_id'];
+            let woke = false;
+            for (const e of this.entries.values()) {
+                if (e.state === 'eventwait' && e.eventwaitKey === wakeConv) {
+                    this.toPending(e); // wake 不计数（§5.2）
+                    woke = true;
+                }
+            }
+            if (woke)
+                this.kickDrain();
+        }
+    }
+    // ── 内部：状态转移 ────────────────────────────────────────────
+    toPending(e) {
+        this.clearTimers(e);
+        e.awaitingAck = false;
+        e.state = 'pending';
+        this.emit(e, 'pending');
+        if (this.connected && this.armed)
+            this.kickDrain();
+    }
+    toEventwait(e, waitKey) {
+        this.clearTimers(e);
+        e.awaitingAck = false;
+        e.state = 'eventwait';
+        e.eventwaitKey = waitKey;
+        if (e.eventwaitSince === undefined)
+            e.eventwaitSince = Date.now(); // 首次进入锚定；重探/wake 往返不重置
+        this.emit(e, 'pending'); // 对外仍呈 pending（§6 文案「另一会话处理中」由 UI 层按需细分）
+        // 60s 重探（不计 transientCount——15min 兜底是唯一上限）
+        e.waitTimer = setTimeout(() => {
+            if (e.state !== 'eventwait')
+                return;
+            if (Date.now() - (e.eventwaitSince ?? 0) >= EVENTWAIT_CEILING_MS) {
+                this.toFailed(e, 'transient_exhaust');
+                return;
+            }
+            this.toPending(e);
+        }, EVENTWAIT_PROBE_MS);
+        this.kickDrain(); // 让位（§5.3）：本条离开可投集合，后续条目不被阻塞
+    }
+    onTransient(e) {
+        this.clearTimers(e);
+        e.awaitingAck = false;
+        e.transientCount += 1;
+        if (e.transientCount >= MAX_TRANSIENT) {
+            this.toFailed(e, 'transient_exhaust');
+            return;
+        }
+        // 指数 backoff 5s→60s，到期转 pending 入 drain（不直发）
+        const delay = Math.min(BACKOFF_BASE_MS * 2 ** (e.transientCount - 1), BACKOFF_CAP_MS);
+        e.state = 'eventwait'; // 复用等待态承载 backoff（无 waitKey——不响应 wake，只等定时器）
+        e.eventwaitKey = undefined;
+        e.waitTimer = setTimeout(() => {
+            if (e.state === 'eventwait')
+                this.toPending(e);
+        }, delay);
+        this.kickDrain(); // 让位：backoff 期间后续条目继续投
+    }
+    toFailed(e, cause) {
+        this.clearTimers(e);
+        e.awaitingAck = false;
+        e.state = 'failed';
+        e.failedCause = cause;
+        this.emit(e, 'failed');
+        this.kickDrain(); // 串行 drain：本条终态，投下一条
+    }
+    failAllNonDelivered(cause) {
+        for (const e of this.entries.values()) {
+            if (e.state !== 'delivered' && e.state !== 'failed')
+                this.toFailed(e, cause);
+        }
+    }
+    emit(e, state) {
+        this.hooks.onStateChange(e.clientMsgId, state, e.failedCause);
+    }
+    emitState(clientMsgId, state) {
+        const e = this.entries.get(clientMsgId);
+        if (e)
+            this.emit(e, state);
+    }
+    clearTimers(e) {
+        if (e.ackTimer) {
+            clearTimeout(e.ackTimer);
+            e.ackTimer = undefined;
+        }
+        if (e.waitTimer) {
+            clearTimeout(e.waitTimer);
+            e.waitTimer = undefined;
+        }
+    }
+    // ── 串行 drain（单飞；可投条目间 FIFO；eventwait/backoff 让位原序回位） ──
+    kickDrain() {
+        if (this.draining) {
+            this.drainAgain = true;
+            return;
+        }
+        void this.drainLoop();
+    }
+    async drainLoop() {
+        this.draining = true;
+        try {
+            do {
+                this.drainAgain = false;
+                while (this.connected && this.armed) {
+                    // 严格串行（§5.3）：任一条目在飞（awaitingAck）→ 等它终局；其终局处理必 kickDrain 续投
+                    if ([...this.entries.values()].some((e) => e.awaitingAck))
+                        break;
+                    const next = [...this.entries.values()]
+                        .filter((e) => e.state === 'pending' && !e.awaitingAck)
+                        .sort((a, b) => a.enqueuedAt - b.enqueuedAt)[0];
+                    if (!next)
+                        break;
+                    const gap = Date.now() - next.lastSendAt;
+                    if (gap < MIN_RESEND_GAP_MS) {
+                        await new Promise((r) => setTimeout(r, MIN_RESEND_GAP_MS - gap));
+                        continue; // 期间状态可能已变，重取
+                    }
+                    this.dispatchOne(next);
+                    // 串行：等本条离开 awaitingAck（receipt/terminal/超时清它并 kickDrain 续投）
+                    break;
+                }
+            } while (this.drainAgain);
+        }
+        finally {
+            this.draining = false;
+            if (this.drainAgain)
+                this.kickDrain();
+        }
+    }
+    dispatchOne(e) {
+        e.sendCount += 1;
+        e.lastSendAt = Date.now();
+        e.awaitingAck = true;
+        const frame = e.sendCount > 1 || e.userRetried
+            ? { ...e.frame, resend: true }
+            : e.frame;
+        this.hooks.sendFrame(JSON.stringify(frame)); // 返 false 也留 awaitingAck——超时漏斗兜底
+        this.hooks.onDispatch?.(e.clientMsgId, e.conversationId); // 投出时置 thinking（§5.1）
+        e.ackTimer = setTimeout(() => this.onAckTimeout(e), ACK_TIMEOUT_MS);
+    }
+    onAckTimeout(e) {
+        if (e.state !== 'pending' || !e.awaitingAck)
+            return;
+        e.awaitingAck = false;
+        e.timeoutCount += 1; // 独立超时轴（不含 transient 重投的 send——双轴混淆是 v4 评审教训）
+        if (e.timeoutCount >= MAX_SENDS) {
+            this.toFailed(e, 'timeout_exhaust'); // 第 3 次超时 → failed（漏斗封闭，v4 M-4）
+            return;
+        }
+        // k<3：不在原 socket 重投（僵尸 socket 主模式无效动作）→ 主动 reconnect（去抖），
+        // 重投发生在重连后的 armed 边沿全量 drain。
+        if (!this.reconnectRequestedForTimeout) {
+            this.reconnectRequestedForTimeout = true;
+            this.hooks.reconnect();
+        }
+    }
+}
+//# sourceMappingURL=delivery-outbox.js.map

package/dist/client/delivery-outbox.js.map

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

package/dist/client/gateway-client.d.ts

@@ -1,5 +1,6 @@
 import type { ServerEvent, ClientEvent } from '@optima-chat/gateway-protocol';
 import type { ChatError, ConnectionState, TokenProviderOpts } from '../types.js';
+import { type DeliveryState, type FailedCause } from './delivery-outbox.js';
 export interface GatewayClientOptions {
     gatewayUrl: string;
     tokenProvider: (opts?: TokenProviderOpts) => Promise<string> | string;
@@ -34,6 +35,17 @@ export interface GatewayClientOptions {
         maxDelay?: number;
     };
     heartbeatInterval?: number;
+    /**
+     * gw#1587 投递保证：消息级 deliveryState 变化（pending/delivered/failed）。
+     * 消费方（provider→chat-store）只驱动消息级指示——绝不写 conv 级 processing/isThinking
+     * （spec §5.4 分层）。cause 仅 failed 时有值。
+     */
+    onDeliveryStateChange?: (clientMsgId: string, state: DeliveryState, cause?: FailedCause) => void;
+    /**
+     * gw#1587 §5.1：一条消息真正投出（drain dispatch）时回调——host 在此置 thinking
+     * （入队不置、投出才置；gap 入队后 failed 的消息从不 dispatch，不 wedge composer）。
+     */
+    onMessageDispatched?: (clientMsgId: string, conversationId: string) => void;
 }
 /**
  * WebSocket client for the Optima gateway. Handles connect/reconnect,
@@ -90,7 +102,28 @@ export declare class GatewayClient {
     private pendingOpenResolve;
     private readonly reconnectConfig;
     private readonly heartbeatInterval;
+    /**
+     * gw#1587 armed 三态（per-connection）：connected 边沿置 undecided；本连接 session_ready
+     * 处理完成（或 10s 兜底）后定 armed/disarmed。判定前窗口（undecided）sendMessage 只入队
+     * 不发（spec §5.1）。
+     */
+    private deliveryArmState;
+    private armTimer;
+    private readonly delivery;
     constructor(options: GatewayClientOptions);
+    /**
+     * gw#1587：drain 直发（绕过 send() 的入队拦截；帧已含 outbox 序列化的 resend 标记）。
+     * OTel per-frame span 有意省略（重投帧非用户新动作；接受的观测简化）。
+     */
+    private sendRawFrame;
+    private cancelArmTimer;
+    /** gw#1587 §5.1：10s 兜底——connected 锚点起计，session_ready 到达或断连即取消。 */
+    private startArmTimer;
+    /** 手动重试：armed/undecided 走 outbox retry；disarmed 走旧语义重发（保 id+resend，出 outbox）。 */
+    retryDelivery(clientMsgId: string): boolean;
+    /** PR-A「id ∈ 本 tab outbox」判定（duplicate finish 提示过滤）。 */
+    hasDeliveryEntry(clientMsgId: string): boolean;
+    isDeliveryArmed(): boolean;
     /**
      * Current identity (userId/sessionId) for stamping OTel spans. Pulls the
      * latest values from the host-provided callbacks so spans reflect live store

package/dist/client/gateway-client.d.ts.map

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