lark-remote 0.5.3 → 0.5.5

package/dist/runner/common/acp/base-acp-runner.js

@@ -20,9 +20,44 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
         // 那时 this 不可用，所以只能等 super() 返回后再赋值。
         connectionManager.stopper = ({ client }) => this.buildCooperativeStop(client);
     }
+    /**
+     * session/new|resume retry policy. Default: no retry. Agents whose ACP
+     * server sits behind a separately-starting service (opencode v2) override
+     * this to absorb a transient `ServiceUnavailableError` without failing the
+     * whole turn.
+     */
+    sessionSetupRetryDelaysMs() {
+        return [];
+    }
+    /** Whether a failed session/new|resume is safe to retry. */
+    isRetryableSessionSetupError(_err) {
+        return false;
+    }
+    /** Final error surfaced to the user after retries are exhausted. */
+    enrichSessionSetupError(err) {
+        return err instanceof Error ? err : new Error(String(err));
+    }
     // =========================================================================
     // Shared plumbing
     // =========================================================================
+    async withSessionSetupRetry(fn) {
+        const delays = this.sessionSetupRetryDelaysMs();
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                if (this.stopRequested ||
+                    attempt >= delays.length ||
+                    !this.isRetryableSessionSetupError(err)) {
+                    throw this.enrichSessionSetupError(err);
+                }
+                const delay = delays[attempt];
+                getLogger().warn(`[${this.logTag}] session setup failed (attempt ${attempt + 1}/${delays.length + 1}), retrying in ${delay}ms: ${err.message}`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
     currentSessionId() {
         return this.activeSessionId;
     }
@@ -132,14 +167,31 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
      * session/resume (existing sessionId) → applyTurnSettings → session/prompt.
      */
     async setupTurn(message, opts) {
+        // 本轮回调归属锚点：代际 + client 都不可变。旧轮迟到的 prompt
+        // 结果/通知在新轮开始时 stopRequested 已被重置，只有这两个值能识别它。
+        const generation = this.turnGeneration;
         const client = await this.connectionManager.acquire(opts.cwd);
         this.connectionManager.notifyActivity(opts.cwd);
         this.currentClient = client;
         this.onConnectionAcquired(opts);
         client.setHooks({
-            onNotification: (method, params) => this.handleNotification(method, params),
-            onServerRequest: (id, method, params) => this.handleServerRequest(id, method, params),
+            onNotification: (method, params) => {
+                if (!this.isCurrentTurn(generation, client)) {
+                    getLogger().debug(`[${this.logTag}] dropped notification from a finished turn`);
+                    return;
+                }
+                this.handleNotification(method, params);
+            },
+            onServerRequest: (id, method, params) => {
+                if (!this.isCurrentTurn(generation, client)) {
+                    getLogger().debug(`[${this.logTag}] dropped server request from a finished turn`);
+                    return;
+                }
+                this.handleServerRequest(id, method, params);
+            },
             onClose: () => {
+                if (!this.isCurrentTurn(generation, client))
+                    return;
                 getLogger().warn(`[${this.logTag}] client connection closed`);
                 this.onConnectionClosed();
                 this.failTurn(this.connectionClosedMessage);
@@ -151,13 +203,13 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
                 sessionId: opts.sessionId,
                 cwd: opts.cwd,
             };
-            const resumeResult = await client.request('session/resume', resumeParams);
+            const resumeResult = await this.withSessionSetupRetry(() => client.request('session/resume', resumeParams));
             this.onSessionEstablished(resumeResult);
             sessionId = opts.sessionId;
         }
         else {
             const newParams = { cwd: opts.cwd, mcpServers: [] };
-            const newResult = await client.request('session/new', newParams);
+            const newResult = await this.withSessionSetupRetry(() => client.request('session/new', newParams));
             this.onSessionEstablished(newResult);
             sessionId = newResult.sessionId;
         }
@@ -181,7 +233,19 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
         this.promptSettled = false;
         const promptPromise = client.request('session/prompt', promptParams, Number.POSITIVE_INFINITY);
         this.promptSent = true;
-        promptPromise.then((result) => this.handlePromptResolved(result, translator, sessionId), (err) => this.handlePromptRejected(err, translator, sessionId, ''));
+        promptPromise.then((result) => {
+            if (!this.isCurrentTurn(generation, client)) {
+                getLogger().debug(`[${this.logTag}] dropped late prompt result from a finished turn`);
+                return;
+            }
+            this.handlePromptResolved(result, translator, sessionId);
+        }, (err) => {
+            if (!this.isCurrentTurn(generation, client)) {
+                getLogger().debug(`[${this.logTag}] dropped late prompt rejection from a finished turn`);
+                return;
+            }
+            this.handlePromptRejected(err, translator, sessionId, '');
+        });
     }
     /**
      * Run a compact operation on the current session: resume → '/compact'
@@ -189,14 +253,25 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
      */
     async *runCompact(_message, opts) {
         yield* this.executeTurn(opts, async () => {
+            const generation = this.turnGeneration;
             const client = await this.connectionManager.acquire(opts.cwd);
             this.connectionManager.notifyActivity(opts.cwd);
             this.currentClient = client;
             this.onConnectionAcquired(opts);
             client.setHooks({
-                onNotification: (method, params) => this.handleNotification(method, params),
-                onServerRequest: (id, method, params) => this.handleServerRequest(id, method, params),
+                onNotification: (method, params) => {
+                    if (!this.isCurrentTurn(generation, client))
+                        return;
+                    this.handleNotification(method, params);
+                },
+                onServerRequest: (id, method, params) => {
+                    if (!this.isCurrentTurn(generation, client))
+                        return;
+                    this.handleServerRequest(id, method, params);
+                },
                 onClose: () => {
+                    if (!this.isCurrentTurn(generation, client))
+                        return;
                     this.onConnectionClosed();
                     this.failTurn(this.connectionClosedMessage);
                 },
@@ -211,7 +286,7 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
             // memory. On a reused connection the session is already loaded —
             // resume is idempotent and harmless.
             const resumeParams = { sessionId, cwd: opts.cwd };
-            const resumeResult = await client.request('session/resume', resumeParams);
+            const resumeResult = await this.withSessionSetupRetry(() => client.request('session/resume', resumeParams));
             this.onSessionEstablished(resumeResult);
             const translator = this.createTranslator();
             translator.setOperationKind('compact');

package/dist/runner/common/acp/protocol-types.d.ts

@@ -13,7 +13,9 @@
  * lark-remote 内部事件流对 ACP 系 agent（kimi acp、后续 opencode acp）的约定：
  *
  * 1. `assistant/text` 与 `assistant/thinking` 是**增量通道**：run-state 收到后
- *    向对应 item **追加**文本。
+ *    向对应 item **逐字追加**文本，绝不插入分隔符。thinking 必须携带 `itemId`
+ *    （wire 的 `messageId` 等块身份）：同一 itemId = 同一思考块的下一段 delta，
+ *    itemId 变化才开新块。块生产者（pi）自己决定块内段落分隔。
  * 2. `turn_diff` 是**快照通道**：run-state 按 itemId **原地替换**全文（kimi ACP
  *    文本/思考固定 itemId `'text'`/`'thinking'`）。
  * 3. kimi wire 的 `content.text`（agent_message_chunk / agent_thought_chunk）
@@ -135,7 +137,13 @@ export interface AgentMessageChunkEvent {
 }
 export interface AgentThoughtChunkEvent {
     sessionUpdate: 'agent_thought_chunk';
-    /** events-map.ts:280-288 — same content.text structure. */
+    /**
+     * 思考块身份。opencode acp/event.ts 用
+     * `${assistantMessageID}:reasoning:${ordinal}` 标识每个 reasoning part；
+     * 同 id 的连续 chunk 是同一块的 delta（loadSession 回放时该通道发整块全文）。
+     */
+    messageId?: string;
+    /** events-map.ts:280-288 — same content.text structure (delta, not snapshot). */
     content: {
         type: 'text';
         text: string;

package/dist/runner/common/acp/protocol-types.js

@@ -13,7 +13,9 @@
  * lark-remote 内部事件流对 ACP 系 agent（kimi acp、后续 opencode acp）的约定：
  *
  * 1. `assistant/text` 与 `assistant/thinking` 是**增量通道**：run-state 收到后
- *    向对应 item **追加**文本。
+ *    向对应 item **逐字追加**文本，绝不插入分隔符。thinking 必须携带 `itemId`
+ *    （wire 的 `messageId` 等块身份）：同一 itemId = 同一思考块的下一段 delta，
+ *    itemId 变化才开新块。块生产者（pi）自己决定块内段落分隔。
  * 2. `turn_diff` 是**快照通道**：run-state 按 itemId **原地替换**全文（kimi ACP
  *    文本/思考固定 itemId `'text'`/`'thinking'`）。
  * 3. kimi wire 的 `content.text`（agent_message_chunk / agent_thought_chunk）

package/dist/runner/common/connection-based-runner.d.ts

@@ -25,9 +25,19 @@ export declare abstract class ConnectionBasedRunner<TClient, TEvent = AgentEvent
     protected lastEventAt: number;
     protected _isRunning: boolean;
     protected readonly turnIdleTimeoutMs: number;
+    /**
+     * 单调递增的轮次代际。每轮 executeTurn 开始
+     * 自增；该轮安装的所有回调（prompt settle / notification / server request）
+     * 捕获当轮代际 + client，事件落地前校验归属。`_isRunning` / `stopRequested`
+     * 是可变跨轮字段，重置于下一轮开始——旧轮迟到的回调会在新轮看到
+     * `stopRequested === false` 并通过唯一检查，把旧 session 的 result 灌进新轮。
+     */
+    protected turnGeneration: number;
     /** Notification queue consumed by the active run generator. */
     protected notificationQueue: TEvent[];
     protected waitResolve: (() => void) | null;
+    /** 当前 waitForEvents 的兜底定时器（唤醒时必须清掉）。 */
+    private waitTimer;
     protected forceFinish: boolean;
     /** stop() 在 turn/start 或 prompt 响应前到达时置位，完成后再补发 cancel/interrupt。 */
     protected stopRequested: boolean;
@@ -126,6 +136,11 @@ export declare abstract class ConnectionBasedRunner<TClient, TEvent = AgentEvent
     protected waitForEvents(deadline: number): Promise<boolean>;
     protected pushEvents(events: TEvent[]): void;
     protected wakeWaiters(): void;
+    /**
+     * 归属校验：事件/回调是否仍属于当前轮次。旧轮迟到的 prompt 结果、通知、
+     * server request 一律只记 debug，不得进入共享 notificationQueue。
+     */
+    protected isCurrentTurn(generation: number, client: TClient | null): boolean;
     protected failTurn(message: string): void;
     protected resetRunState(): void;
     /** Release the connection + detach stale client hooks after a lost connection. */

package/dist/runner/common/connection-based-runner.js

@@ -16,9 +16,19 @@ export class ConnectionBasedRunner {
     lastEventAt = 0;
     _isRunning = false;
     turnIdleTimeoutMs;
+    /**
+     * 单调递增的轮次代际。每轮 executeTurn 开始
+     * 自增；该轮安装的所有回调（prompt settle / notification / server request）
+     * 捕获当轮代际 + client，事件落地前校验归属。`_isRunning` / `stopRequested`
+     * 是可变跨轮字段，重置于下一轮开始——旧轮迟到的回调会在新轮看到
+     * `stopRequested === false` 并通过唯一检查，把旧 session 的 result 灌进新轮。
+     */
+    turnGeneration = 0;
     /** Notification queue consumed by the active run generator. */
     notificationQueue = [];
     waitResolve = null;
+    /** 当前 waitForEvents 的兜底定时器（唤醒时必须清掉）。 */
+    waitTimer = null;
     forceFinish = false;
     /** stop() 在 turn/start 或 prompt 响应前到达时置位，完成后再补发 cancel/interrupt。 */
     stopRequested = false;
@@ -85,6 +95,8 @@ export class ConnectionBasedRunner {
             throw new Error(`${this.constructor.name} is already running`);
         }
         this._isRunning = true;
+        // 代际先于 setup 自增：setupTurn 里安装的回调捕获到的就是本轮代际。
+        this.turnGeneration++;
         this.resetRunState();
         try {
             try {
@@ -271,13 +283,24 @@ export class ConnectionBasedRunner {
             if (remaining <= 0)
                 return true;
             await new Promise((resolve) => {
-                this.waitResolve = resolve;
-                setTimeout(() => {
-                    if (this.waitResolve === resolve) {
+                // 唤醒与超时必须互斥清理：wakeWaiters() 提前 resolve 时要 clearTimeout，
+                // 否则高频事件会让 timer 在最长 30s 内持续堆积。
+                const waiter = () => {
+                    if (this.waitTimer === timer) {
+                        clearTimeout(timer);
+                        this.waitTimer = null;
+                    }
+                    resolve();
+                };
+                const timer = setTimeout(() => {
+                    if (this.waitResolve === waiter) {
                         this.waitResolve = null;
+                        this.waitTimer = null;
                         resolve();
                     }
                 }, Math.min(remaining, 30_000));
+                this.waitResolve = waiter;
+                this.waitTimer = timer;
             });
         }
         return false;
@@ -290,12 +313,20 @@ export class ConnectionBasedRunner {
         this.wakeWaiters();
     }
     wakeWaiters() {
-        if (this.waitResolve) {
-            const resolve = this.waitResolve;
+        const resolve = this.waitResolve;
+        if (resolve) {
+            // waiter 自己会 clearTimeout + 置空 waitTimer。
             this.waitResolve = null;
             resolve();
         }
     }
+    /**
+     * 归属校验：事件/回调是否仍属于当前轮次。旧轮迟到的 prompt 结果、通知、
+     * server request 一律只记 debug，不得进入共享 notificationQueue。
+     */
+    isCurrentTurn(generation, client) {
+        return this._isRunning && generation === this.turnGeneration && client === this.currentClient;
+    }
     failTurn(message) {
         this.pushEvents([
             {
@@ -309,6 +340,10 @@ export class ConnectionBasedRunner {
     resetRunState() {
         this.notificationQueue = [];
         this.waitResolve = null;
+        if (this.waitTimer !== null) {
+            clearTimeout(this.waitTimer);
+            this.waitTimer = null;
+        }
         this.lastEventAt = Date.now();
         this.forceFinish = false;
     }

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -78,6 +78,8 @@ export interface ConnectionManagerOptions<TClient extends ConnectionClient = Jso
     logTag?: string;
     /** 协议停止通道注册表注入（测试隔离）；默认进程级单例，透传给 transport。 */
     stoppers?: AgentStopperRegistry;
+    /** Called once after a fresh connection's initialize handshake resolves. */
+    onConnected?: (result: unknown, cwd: string) => void;
 }
 export declare class ConnectionManager<TClient extends ConnectionClient = JsonRpcClient> {
     private slots;
@@ -91,6 +93,7 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
     private readonly shouldReuse;
     private readonly logTag;
     private readonly stoppers;
+    private readonly onConnected?;
     /** Callback when a connection is lost — cleared from slot map. */
     onConnectionLost?: (cwd: string) => void;
     /**
@@ -112,6 +115,13 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
      * Creates a new connection if one does not exist or the previous one was lost
      * (or, for session-bound protocols, bound to a different session).
      * Serializes creation so concurrent calls share the same connection.
+     *
+     * 替换旧连接时必须先等 dispose 完成。旧实现
+     * `disposeSlot(cwd)` 不 await 就创建新连接，新旧两个 agent server 会重叠；
+     * codex 会报 "thread already has an active writer"（同一 workspace 写锁）。
+     * 现在的顺序：等旧连接真正 dispose → 重新读 slot（并发 acquire 可能已建好
+     * 新连接，直接复用/等它）→ 才进入创建。创建期间 slot 被 release/disposeAll
+     * 删掉时，新连接立即 dispose 并重试，不返回无人托管的连接。
      */
     acquire(cwd: string, req?: AcquireRequest): Promise<TClient>;
     /**
@@ -141,5 +151,10 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
     notifyIdle(cwd: string): void;
     private createClient;
     private clearIdleTimer;
+    /**
+     * Dispose the slot for `cwd`. Returns false when the underlying client's
+     * dispose failed — callers replacing a connection must abort the replacement
+     * rather than let two agent servers overlap.
+     */
     private disposeSlot;
 }

package/dist/runner/common/jsonrpc/connection-manager.js

@@ -19,6 +19,8 @@ import { getLogger } from '../../../logger/index.js';
 import { agentStopperRegistry, } from '../../../platform/agent-stopper.js';
 const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; // 60 seconds
+/** acquire() 的轮次上限：防止 slot 被持续释放时无限重建连接。 */
+const MAX_ACQUIRE_ATTEMPTS = 5;
 export class ConnectionManager {
     slots = new Map();
     binary;
@@ -31,6 +33,7 @@ export class ConnectionManager {
     shouldReuse;
     logTag;
     stoppers;
+    onConnected;
     /** Callback when a connection is lost — cleared from slot map. */
     onConnectionLost;
     /**
@@ -60,66 +63,88 @@ export class ConnectionManager {
         this.shouldReuse = opts.shouldReuse ?? (({ client }) => client.ready && client.healthy);
         this.logTag = opts.logTag ?? 'jsonrpc-connection-manager';
         this.stoppers = opts.stoppers ?? agentStopperRegistry;
+        this.onConnected = opts.onConnected;
     }
     /**
      * Acquire a connection for the given cwd.
      * Creates a new connection if one does not exist or the previous one was lost
      * (or, for session-bound protocols, bound to a different session).
      * Serializes creation so concurrent calls share the same connection.
+     *
+     * 替换旧连接时必须先等 dispose 完成。旧实现
+     * `disposeSlot(cwd)` 不 await 就创建新连接，新旧两个 agent server 会重叠；
+     * codex 会报 "thread already has an active writer"（同一 workspace 写锁）。
+     * 现在的顺序：等旧连接真正 dispose → 重新读 slot（并发 acquire 可能已建好
+     * 新连接，直接复用/等它）→ 才进入创建。创建期间 slot 被 release/disposeAll
+     * 删掉时，新连接立即 dispose 并重试，不返回无人托管的连接。
      */
     async acquire(cwd, req = {}) {
-        const existing = this.slots.get(cwd);
-        if (existing) {
-            // If a create is in flight, wait for it
-            if (existing.createPromise) {
-                return existing.createPromise;
-            }
-            // Reuse when the (session-aware) reuse predicate holds — e.g. the client
-            // is ready and its transport is alive (default), or it is bound to the
-            // requested session (pi). Otherwise replace it so the next run respawns
-            // the process.
-            if (this.shouldReuse({
-                client: existing.client,
-                req,
-                boundSessionId: existing.boundSessionId,
-            })) {
-                return existing.client;
-            }
-            this.disposeSlot(cwd);
-        }
-        const createPromise = this.createClient(cwd, req);
-        this.slots.set(cwd, {
-            client: null, // placeholder
-            boundSessionId: req.sessionId,
-            idleTimer: null,
-            createPromise,
-        });
-        try {
-            const client = await createPromise;
-            // 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
-            // dispose 连接）。此时不能再把新连接塞回 slot——否则会复活一个无人管理、
-            // 无 idle timer 的连接泄漏。归还给调用者继续使用，但不再缓存。
-            const slotAfterCreate = this.slots.get(cwd);
-            if (!slotAfterCreate || slotAfterCreate.createPromise !== createPromise) {
-                return client;
+        for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+            const existing = this.slots.get(cwd);
+            if (existing) {
+                // If a create is in flight, wait for it
+                if (existing.createPromise) {
+                    return existing.createPromise;
+                }
+                // Reuse when the (session-aware) reuse predicate holds — e.g. the client
+                // is ready and its transport is alive (default), or it is bound to the
+                // requested session (pi). Otherwise replace it so the next run respawns
+                // the process.
+                if (this.shouldReuse({
+                    client: existing.client,
+                    req,
+                    boundSessionId: existing.boundSessionId,
+                })) {
+                    return existing.client;
+                }
+                // Must finish before a replacement connection is created: two live
+                // agent servers for one cwd would contend on the same write lock.
+                const disposed = await this.disposeSlot(cwd);
+                if (!disposed) {
+                    throw new Error(`cannot replace connection for cwd=${cwd}: old connection failed to dispose`);
+                }
+                // Re-read: a concurrent acquire may have installed a new slot (or a
+                // create promise) while we awaited the dispose.
+                continue;
             }
-            this.slots.set(cwd, {
-                client,
+            const createPromise = this.createClient(cwd, req);
+            const slot = {
+                client: null, // placeholder until connect resolves
                 boundSessionId: req.sessionId,
                 idleTimer: null,
-                createPromise: null,
-            });
-            return client;
-        }
-        catch (err) {
-            // 只删除自己的槽位：并发 release + 重新 acquire 后 slot 可能已被新的
-            // createPromise 占据，误删会破坏新连接。
-            const current = this.slots.get(cwd);
-            if (current && current.createPromise === createPromise) {
-                this.slots.delete(cwd);
+                createPromise,
+            };
+            this.slots.set(cwd, slot);
+            try {
+                const client = await createPromise;
+                // 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
+                // dispose 连接）。旧实现把新连接直接交给调用方"继续使用但不缓存"，
+                // 留下一个无人管理、无 idle timer 的连接。现在主动 dispose 后重试；
+                // 连续被释放说明 manager 正在收摊，按失败上报而不是无限重连。
+                if (this.slots.get(cwd) !== slot) {
+                    try {
+                        await client.dispose();
+                    }
+                    catch (err) {
+                        getLogger().warn(`[${this.logTag}] dispose of released connection failed cwd=${cwd}: ${err}`);
+                    }
+                    continue;
+                }
+                slot.client = client;
+                slot.createPromise = null;
+                return client;
+            }
+            catch (err) {
+                // 只删除自己的槽位：并发 release + 重新 acquire 后 slot 可能已被新的
+                // createPromise 占据，误删会破坏新连接。
+                const current = this.slots.get(cwd);
+                if (current && current.createPromise === createPromise) {
+                    this.slots.delete(cwd);
+                }
+                throw err;
             }
-            throw err;
         }
+        throw new Error(`cannot acquire connection for cwd=${cwd}: slot repeatedly released`);
     }
     /**
      * Record the session id a fresh connection actually bound to (e.g. discovered
@@ -135,7 +160,7 @@ export class ConnectionManager {
      * Release (dispose) a connection for the given cwd.
      */
     async release(cwd) {
-        this.disposeSlot(cwd);
+        await this.disposeSlot(cwd);
     }
     /**
      * Dispose all connections.
@@ -203,7 +228,8 @@ export class ConnectionManager {
                 }
             },
         });
-        await client.connect();
+        const initResult = await client.connect();
+        this.onConnected?.(initResult, cwd);
         return client;
     }
     clearIdleTimer(slot) {
@@ -212,10 +238,15 @@ export class ConnectionManager {
             slot.idleTimer = null;
         }
     }
+    /**
+     * Dispose the slot for `cwd`. Returns false when the underlying client's
+     * dispose failed — callers replacing a connection must abort the replacement
+     * rather than let two agent servers overlap.
+     */
     async disposeSlot(cwd) {
         const slot = this.slots.get(cwd);
         if (!slot)
-            return;
+            return true;
         this.slots.delete(cwd);
         this.clearIdleTimer(slot);
         if (slot.client) {
@@ -224,8 +255,10 @@ export class ConnectionManager {
             }
             catch (err) {
                 getLogger().warn(`[${this.logTag}] dispose error cwd=${cwd}: ${err}`);
+                return false;
             }
         }
+        return true;
     }
 }
 //# sourceMappingURL=connection-manager.js.map

package/dist/runner/dsh/approval.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Correlate DSH's durable approval audit with its live answer waterfall.
+ *
+ * `session/follow` carries `approval/asked` / `approval/decided`; `$events`
+ * carries the answerable `approval/request` waterfall. The audit id is the
+ * stable identity shown on the Feishu card; the waterfall contributes the
+ * ephemeral `eventId` + `clientId` needed to answer it. Both are correlated by
+ * `callId`, with an order-independent pairing so either transport may arrive
+ * first.
+ */
+export interface DshApprovalAudit {
+    approvalId: string;
+    callId?: string;
+    toolName: string;
+    reason?: string;
+}
+export interface DshApprovalWaterfall {
+    eventId: string;
+    clientId: string;
+    callId?: string;
+    toolName: string;
+    reason?: string;
+}
+export interface DshApprovalBinding {
+    audit: DshApprovalAudit;
+    waterfall: DshApprovalWaterfall;
+}
+export declare class DshApprovalTracker {
+    private readonly audits;
+    private readonly waterfallByCallId;
+    private readonly bindings;
+    private readonly approvalIdByEventId;
+    private readonly waiters;
+    /** Record `approval/asked`; pair immediately when its waterfall is known. */
+    onAuditAsked(audit: DshApprovalAudit): DshApprovalBinding | undefined;
+    /** Record an `approval/request` waterfall; pair when its audit is known. */
+    onWaterfall(waterfall: DshApprovalWaterfall): DshApprovalBinding | undefined;
+    /** Mark an audit resolved (local response or an external decision). */
+    onDecided(approvalId: string): DshApprovalBinding | undefined;
+    /** Mark a waterfall cancelled by the Host (another client answered it). */
+    onCancelled(eventId: string): DshApprovalBinding | undefined;
+    getBinding(approvalId: string): DshApprovalBinding | undefined;
+    /**
+     * Wait for a waterfall to arrive after the audit card was rendered. The
+     * audit is appended before the waterfall is dispatched, so this window is
+     * normally tiny; the bound keeps a fast button click from failing.
+     */
+    waitForBinding(approvalId: string, timeoutMs: number, signal?: AbortSignal): Promise<DshApprovalBinding | undefined>;
+    /** Drop all in-flight state when a run ends. */
+    clear(): void;
+    private bind;
+    private resolveWaiters;
+}