dsh-bundle-antigravity-host 0.1.25 → 0.1.26

package/dist/adapter/antigravity-adapter.js

@@ -4,21 +4,19 @@
  * 形态：官方 ACP server（Gemini 主模型）走 stdio，工具留在 DSH 侧，经插件
  * 进程内的私有 loopback MCP 桥暴露给 agent（见 ../bridge/mcp-bridge.ts）。
  *
- * 历史权威是 DSH：**本文件不建任何会话存储/数据库/文件**。新轮用
- * 完整的 `options.messages` + `options.system` 建立 ACP prompt，工具结果续轮复用该 prompt
- * （见 prompt-transcript.ts）；唯一的跨回合内存态是「当前 ACP 回合」与
- * 「park 中的 MCP tools/call」，它们都随回合结束而释放。
- *
- * 不支持项一律抛 `LlmError(..., 'UNSUPPORTED_OPTION')`（dsh-llm 0.2.1 的
- * error.d.ts 未导出该码的官方常量，因此用字面量并在下方集中定义）。
+ * DSH 是历史权威：只有输入前缀、上轮实际交付输出与路由一致才复用会话；
+ * 不一致时完整重建。工具结果在同一个 ACP prompt 内经 MCP 回填。
+ * 可选磁盘映射只保存 ID、计数与指纹，不存消息正文。
  */
 import { LlmAdapter, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { BRIDGE_MCP_SERVER_NAME, McpToolBridge } from '../bridge/mcp-bridge.js';
 import { AGY_REASONING_EFFORTS, AGY_REASONING_EFFORT_NAMES, DEFAULT_AGY_REASONING_EFFORT, foldAgyModelFamilies, modelFamilyId, routeTieredModelId, tierForModelId, } from '../runtime/agy-cli.js';
 import { findModelSelector, toModelCatalog } from './model-catalog.js';
-import { buildPromptWithImages, buildToolResultContent } from './image-content.js';
+import { buildPromptDeltaWithImages, buildPromptWithImages, buildToolResultContent } from './image-content.js';
 import { AGY_TURN_ERROR, PromptTurn } from './prompt-turn.js';
 import { ContinuationState } from './continuation-state.js';
+import { incrementalMessages, outputHash, outputMatches, prefixHash, prefixMatches, reusableSessionKey, routeFingerprint } from './session-reuse.js';
+import { SessionMapStore } from '../runtime/session-map.js';
 /** DSH 侧 provider 标识符；与 cordis.patch.yml 的 id 及文档保持一致。 */
 export const AGY_PROVIDER_ID = 'antigravity-acp';
 /**
@@ -28,8 +26,7 @@ export const AGY_PROVIDER_ID = 'antigravity-acp';
  */
 export const AGY_PLACEHOLDER_MODEL_ID = 'server-default';
 /**
- * 不支持项的机器错误码。dsh-llm 0.2.1-alpha.2 的 `error.d.ts` 未导出
- * `UNSUPPORTED_OPTION` 常量，故使用字面量并集中在此定义。
+ * @deprecated 兼容旧导出的错误码；temperature / stop 现在只警告并忽略，不再抛此码。
  */
 export const AGY_UNSUPPORTED_OPTION = 'UNSUPPORTED_OPTION';
 /** 本 adapter 的其余原创错误码（AGY_* 体系）。 */
@@ -38,6 +35,8 @@ export const AGY_ADAPTER_ERROR = {
     BUSY: 'AGY_BUSY',
     /** 回合需要一个模型选择器，但 ACP 会话未声明任何 model 类 configOption。 */
     NO_MODEL_SELECTOR: 'AGY_NO_MODEL_SELECTOR',
+    /** agent 应答选模却没有确认请求的型号，不能静默使用其他模型。 */
+    MODEL_SELECTION_MISMATCH: 'AGY_MODEL_SELECTION_MISMATCH',
 };
 /*
  * 关于失败重试：**刻意不 override `providerRetryPolicy`**。
@@ -78,6 +77,24 @@ export class AntigravityAcpAdapter extends LlmAdapter {
     #loadCliCatalog;
     #log;
     #onMetadataChanged;
+    #reuseSessions;
+    #resumeSessions;
+    #sessionStore;
+    #sessionOwner = Symbol('acp-worker');
+    /** 同一 DSH 对话（普通聊天轮）→ 可复用的 ACP 会话，最多 64 个。 */
+    #sessions = new Map();
+    /** >0 时丢弃入站 session/update：`session/load` 会把整段历史重放回来。 */
+    #suppressUpdates = 0;
+    #keepProcessAfterCancel;
+    #cancelGraceMs;
+    #idleRecycleMs;
+    /** 取消后的确认定时器；agent 先确认停止就取消回收。 */
+    #cancelGrace;
+    /** 保留进程的空闲回收定时器；有新回合就撤销。 */
+    #idleRecycle;
+    #currentLink;
+    #ephemeral = new Map();
+    #sessionCloses = new Set();
     #continuationState;
     #readImage;
     #canReadImages;
@@ -136,6 +153,15 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         this.#loadCliCatalog = options.loadCliCatalog;
         this.#log = options.log;
         this.#onMetadataChanged = options.onMetadataChanged;
+        this.#reuseSessions = options.reuseSessions ?? true;
+        this.#resumeSessions = options.resumeSessions ?? false;
+        this.#sessionStore = options.sessionStore ?? (options.loadSessionMap && options.saveSessionMap
+            ? new SessionMapStore({ load: options.loadSessionMap, save: options.saveSessionMap,
+                onError: () => this.#log?.warn('antigravity-acp: 会话映射读写失败，跨进程恢复可能不可用') })
+            : undefined);
+        this.#keepProcessAfterCancel = options.keepProcessAfterCancel ?? false;
+        this.#cancelGraceMs = Math.max(0, options.cancelGraceMs ?? 30_000);
+        this.#idleRecycleMs = Math.max(0, options.idleRecycleMs ?? 300_000);
         this.#readImage = options.readImage;
         this.#canReadImages = options.canReadImages;
         this.#bridge = new McpToolBridge({
@@ -144,23 +170,37 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         this.#registerBridgeTeardown(async () => {
             this.#disposed = true;
             this.#wakeAccessWaiters();
+            if (this.#turn && !this.#isTurnClosed(this.#turn))
+                this.#turn.abort('adapter 卸载');
             this.#turn?.dispose();
             this.#releaseTurnSubscription();
+            this.#dropAllSessions('adapter 卸载');
+            for (const [turn, link] of this.#ephemeral)
+                this.#closeSession(link, turn.sessionId);
+            this.#ephemeral.clear();
+            this.#clearCancelGrace();
+            this.#clearIdleRecycle();
             await this.#bridge.close();
+            await Promise.allSettled(this.#sessionCloses);
+            this.#sessionStore?.release(this.#sessionOwner);
+            await this.#sessionStore?.flush();
         });
         this.#handlers = {
             onSessionUpdate: (notification) => {
+                // session/load 会把整段历史重放回来；那不是本轮输出，必须丢弃。
+                if (this.#disposed || this.#suppressUpdates > 0)
+                    return;
                 this.#observeUsageUpdate(notification);
                 return this.#turn?.handleSessionUpdate(notification);
             },
-            onRequestPermission: (request) => this.#turn?.handleRequestPermission(request)
+            onRequestPermission: (request) => (!this.#disposed ? this.#turn?.handleRequestPermission(request) : undefined)
                 ?? { outcome: { outcome: 'cancelled' } },
             onUnexpectedAgentRequest: (method, request) => this.#handleUnexpectedRequest(method, request),
         };
     }
     /** 设置页连接不能与正在进行的对话/工具回合竞争同一登录态。 */
     get busy() {
-        return this.#streamActive || Boolean(this.#turn && !this.#isTurnClosed(this.#turn));
+        return this.#streamActive || Boolean(this.#cancelGrace) || Boolean(this.#turn && !this.#isTurnClosed(this.#turn));
     }
     get streamActive() { return this.#streamActive; }
     get awaitingToolResults() { return this.#turn?.awaitingToolResults === true; }
@@ -194,7 +234,9 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         if (this.#disposed)
             throw new LlmError('Antigravity ACP adapter 已卸载', 'AGY_LINK_CLOSED');
         this.#streamActive = true;
+        this.#clearIdleRecycle();
         let link;
+        let discoverySession;
         try {
             await withAbort(this.#settleRecycle(), signal);
             link = await this.#getLink(this.#handlers, signal, interactive ? undefined : 'warmup');
@@ -204,6 +246,7 @@ export class AntigravityAcpAdapter extends LlmAdapter {
                 cwd: this.#cwd, mcpServers: [],
                 _meta: { antigravity: { enabledTools: [], eagerMcpServers: [] } },
             }, { signal });
+            discoverySession = session.sessionId;
             throwIfAborted(signal);
             if (!findModelSelector(session.configOptions))
                 throw new LlmError('ACP 会话未提供模型目录', AGY_ADAPTER_ERROR.NO_MODEL_SELECTOR);
@@ -216,7 +259,10 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             throw error;
         }
         finally {
+            if (link && discoverySession)
+                this.#closeSession(link, discoverySession);
             this.#streamActive = false;
+            this.#maybeIdle();
             this.#wakeAccessWaiters();
         }
     }
@@ -226,11 +272,21 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             throw new LlmError('Antigravity ACP adapter 已卸载', 'AGY_LINK_CLOSED');
         if (this.busy)
             throw new LlmError('ACP 正在处理对话，无需再次预热', AGY_ADAPTER_ERROR.BUSY);
-        await withAbort(this.#settleRecycle(), signal);
-        const link = await this.#getLink(this.#handlers, signal, interactive ? undefined : 'warmup');
-        this.#observeCapabilities(link);
+        this.#streamActive = true;
+        this.#clearIdleRecycle();
+        try {
+            await withAbort(this.#settleRecycle(), signal);
+            const link = await this.#getLink(this.#handlers, signal, interactive ? undefined : 'warmup');
+            this.#observeCapabilities(link);
+        }
+        finally {
+            this.#streamActive = false;
+            this.#maybeIdle();
+            this.#wakeAccessWaiters();
+        }
     }
     #observeCapabilities(link) {
+        this.#currentLink = link;
         const supported = link.initializeResponse?.agentCapabilities?.promptCapabilities?.image === true;
         if (supported === this.#imageSupported)
             return;
@@ -439,8 +495,12 @@ export class AntigravityAcpAdapter extends LlmAdapter {
      * 之前串行化 stream。工具 park 保留回合所有权，辅助请求等待而不是抢占主回合。
      */
     async *stream(options) {
-        // 1) 不支持项先行拒绝：必须在任何 IO 之前失败。
-        assertSupportedOptions(options);
+        // temperature / stop 在 ACP v1 没有会话通道：不因它们拒绝整个请求（否则宿主里
+        // 任何携带这两个字段的流程都会整单失败），只明确告知「值不生效」。
+        const unsupported = unsupportedOptions(options);
+        if (unsupported.length > 0) {
+            this.#log?.warn(`antigravity-acp: 忽略不支持的请求项 ${unsupported.join('、')}（ACP v1 无对应会话通道，值不会生效）`);
+        }
         if (options.signal?.aborted) {
             yield { type: 'finish', reason: { kind: 'aborted', failure: {
                         code: AGY_TURN_ERROR.ABORTED, message: 'Antigravity ACP 请求在发起前已取消',
@@ -448,6 +508,7 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             return;
         }
         await this.#acquireStream(options);
+        this.#clearIdleRecycle();
         let handedOff = false;
         try {
             for await (const chunk of this.#streamExclusive(options)) {
@@ -464,14 +525,247 @@ export class AntigravityAcpAdapter extends LlmAdapter {
                 this.#abandonTurn('消费者提前关闭流，取消未完成回合');
             }
             this.#streamActive = false;
+            this.#maybeIdle();
             this.#wakeAccessWaiters();
         }
     }
+    /* ── ACP 会话复用 ─────────────────────────────────────────────────── */
     /**
-     * 等待上一次回收完成。上一次失败时本轮照旧失败（屏障不能被绕过），但同时把
-     * 屏障复位为「重试同一条连接的回收」：失败的 promise 不再被每一轮原样重放。
+     * 跨进程恢复：重启后若磁盘上还留着该对话的 ACP 会话映射，尝试 `session/load`。
+     * 只信任「路由一致 + 历史仍以已发送前缀开头」；其余情况回退重建，不猜测。
      */
+    async #resumeSession(options, key, entry) {
+        if (!this.#reuseSessions || !this.#resumeSessions || !entry)
+            return undefined;
+        const discard = (reason) => {
+            this.#log?.info(`antigravity-acp: 放弃恢复 ACP 会话（${reason}）`);
+            this.#sessionStore?.delete(key, this.#sessionOwner);
+            return undefined;
+        };
+        if (entry.cwd !== this.#cwd)
+            return discard('会话工作目录与当前不一致');
+        if (entry.route !== routeFingerprint(options))
+            return discard('模型、系统提示或工具目录已变化');
+        if (options.messages.length <= entry.sentCount)
+            return discard('没有新增消息');
+        if (!prefixMatches(options.messages, entry.sentCount, entry.sentHash))
+            return discard('历史不是已发送前缀的追加');
+        if (!outputMatches(options.messages.slice(entry.sentCount), entry.outputHash))
+            return discard('上一轮输出已变化或来自其他会话');
+        if (options.messages.slice(entry.sentCount).some((message) => message.role === 'tool'))
+            return discard('新增消息包含工具结果');
+        if (incrementalMessages(options.messages, entry.sentCount).length === 0)
+            return discard('没有可发送的增量，按完整历史重建');
+        const link = await this.#getLink(this.#handlers, options.signal);
+        this.#observeCapabilities(link);
+        const tools = options.tools ?? [];
+        let mcpServers = [];
+        if (tools.length > 0) {
+            this.#bridge.beginRound(tools, key);
+            if (!this.#bridge.listening)
+                await this.#bridge.start();
+            mcpServers = this.#bridge.acpRegistration();
+        }
+        this.#suppressUpdates += 1;
+        try {
+            const response = await link.loadSession({
+                sessionId: entry.sessionId,
+                cwd: this.#cwd,
+                mcpServers,
+                _meta: { antigravity: { enabledTools: [], eagerMcpServers: tools.length > 0 ? [BRIDGE_MCP_SERVER_NAME] : [] } },
+            }, { signal: options.signal, timeoutMs: Math.min(this.#promptTimeoutMs, 120_000) });
+            this.observeSessionConfigOptions(response.configOptions);
+            await this.#applyModelSelection(link, entry.sessionId, options.model, options.reasoningEffort, options.signal);
+            throwIfAborted(options.signal);
+        }
+        catch (error) {
+            this.#log?.warn(`antigravity-acp: session/load 恢复失败，按新轮重建 session=${entry.sessionId}`, error);
+            // 恢复失败可能仍有迟到回放；重建前回收连接。
+            this.#bridge.invalidateRound('恢复失败');
+            this.#scheduleRecycle(link);
+            await this.#settleRecycle();
+            throwIfAborted(options.signal);
+            return discard('session/load 失败');
+        }
+        finally {
+            this.#suppressUpdates -= 1;
+        }
+        const record = {
+            key,
+            sessionId: entry.sessionId,
+            link,
+            sentCount: entry.sentCount,
+            sentHash: entry.sentHash,
+            outputHash: entry.outputHash,
+            route: entry.route,
+            usesTools: tools.length > 0,
+        };
+        this.#sessions.set(key, record);
+        this.#log?.info(`antigravity-acp: 已恢复 ACP 会话 session=${entry.sessionId} 已发送消息=${entry.sentCount}`);
+        return record;
+    }
+    /** 找到可复用的会话；记录失效时顺手丢弃（关闭对端会话，下一轮重建）。 */
+    #findReusableSession(options, key) {
+        if (!this.#reuseSessions)
+            return undefined;
+        const record = this.#sessions.get(key);
+        if (!record)
+            return undefined;
+        if (this.#resumeSessions && this.#sessionStore && !this.#sessionStore.owns(key, this.#sessionOwner)) {
+            this.#dropSession(record, '会话已迁移到其他 worker');
+            return undefined;
+        }
+        // 进程崩溃/被回收后链接已关闭：记录不可用，按新轮重建。
+        if (record.link.closed) {
+            this.#dropSession(record, 'ACP 链接已关闭');
+            return undefined;
+        }
+        if (record.route !== routeFingerprint(options)) {
+            this.#dropSession(record, '模型、系统提示或工具目录已变化');
+            return undefined;
+        }
+        // 用过工具的会话依赖桥的授权代次：桥被另一个对话接管后它的 MCP 连接
+        // 持有旧 token，沿用只会让工具调用被拒；直接重建。
+        if (record.usesTools && this.#bridge.owner !== record.key) {
+            this.#dropSession(record, 'MCP 桥已被其他对话接管');
+            return undefined;
+        }
+        if (options.messages.length <= record.sentCount) {
+            this.#dropSession(record, '没有严格追加的新输入');
+            return undefined;
+        }
+        if (!prefixMatches(options.messages, record.sentCount, record.sentHash)) {
+            this.#dropSession(record, '历史已不是已发送前缀的追加（压缩、回退或编辑）');
+            return undefined;
+        }
+        if (!outputMatches(options.messages.slice(record.sentCount), record.outputHash)) {
+            this.#dropSession(record, '上一轮输出已变化或来自其他会话');
+            return undefined;
+        }
+        // 新增部分若含工具结果，只能走 MCP 回喂，不能当 prompt 文本重发。
+        if (options.messages.slice(record.sentCount).some((message) => message.role === 'tool')) {
+            this.#dropSession(record, '新增消息包含工具结果');
+            return undefined;
+        }
+        if (incrementalMessages(options.messages, record.sentCount).length === 0) {
+            this.#dropSession(record, '没有可发送的增量，按完整历史重建');
+            return undefined;
+        }
+        return record;
+    }
+    /** 记录一个刚建立会话 / 刚完成全量发送的 ACP 会话。 */
+    #rememberSession(options, key, link, sessionId) {
+        const record = {
+            key,
+            sessionId,
+            link,
+            sentCount: options.messages.length,
+            sentHash: prefixHash(options.messages),
+            route: routeFingerprint(options),
+            usesTools: (options.tools?.length ?? 0) > 0,
+        };
+        this.#sessions.set(key, record);
+        while (this.#sessions.size > 64) {
+            const oldest = this.#sessions.values().next().value;
+            if (!oldest)
+                break;
+            this.#dropSession(oldest, '内存会话 LRU 淘汰');
+        }
+        return record;
+    }
+    /** 在 finish 对外可见之前提交输入与实际交付输出，消费者可立即 return。 */
+    #advanceSession(record, options, blocks, settled) {
+        if (this.#sessions.get(record.key) !== record)
+            return;
+        record.sentCount = options.messages.length;
+        record.sentHash = prefixHash(options.messages);
+        record.outputHash = outputHash(blocks);
+        this.#sessions.delete(record.key);
+        this.#sessions.set(record.key, record);
+        if (settled)
+            this.#sessionStore?.set(record.key, this.#sessionOwner, {
+                sessionId: record.sessionId, cwd: this.#cwd, sentCount: record.sentCount,
+                sentHash: record.sentHash, outputHash: record.outputHash, route: record.route, updatedAt: Date.now(),
+            });
+        else
+            this.#sessionStore?.delete(record.key, this.#sessionOwner);
+    }
+    /** 丢弃会话记录并关闭对端会话；失败忽略——记录本来就已经不可信。 */
+    #dropSession(record, reason) {
+        if (this.#sessions.get(record.key) !== record)
+            return;
+        this.#sessions.delete(record.key);
+        this.#sessionStore?.delete(record.key, this.#sessionOwner);
+        this.#log?.info(`antigravity-acp: 放弃 ACP 会话复用（${reason}）`);
+        this.#closeSession(record.link, record.sessionId);
+    }
+    #dropSessionsForLink(link, reason) {
+        for (const record of [...this.#sessions.values()]) {
+            if (record.link === link)
+                this.#dropSession(record, reason);
+        }
+    }
+    #dropSessionsForTurn(sessionId, reason) {
+        for (const record of [...this.#sessions.values()]) {
+            if (record.sessionId === sessionId)
+                this.#dropSession(record, reason);
+        }
+    }
+    /**
+     * 卸载时关闭所有对端会话，但**保留**磁盘映射：那正是下次启动 `session/load`
+     * 恢复的依据。真正失效的会话在 #dropSession 里连同映射一起删掉。
+     */
+    #dropAllSessions(reason, link) {
+        for (const record of [...this.#sessions.values()]) {
+            if (link && record.link !== link)
+                continue;
+            this.#sessions.delete(record.key);
+            this.#log?.info(`antigravity-acp: 关闭 ACP 会话（${reason}）`);
+            this.#closeSession(record.link, record.sessionId);
+        }
+    }
+    /** 跟踪尽力关闭请求，卸载时等待它们结束；错误不影响当前对话。 */
+    #closeSession(link, sessionId) {
+        const pending = link.closeSession(sessionId).catch(() => {
+            if (!link.closed)
+                this.#log?.warn('antigravity-acp: session/close 失败，会话由进程退出清理');
+        }).finally(() => this.#sessionCloses.delete(pending));
+        this.#sessionCloses.add(pending);
+    }
+    #maybeIdle() {
+        const link = this.#currentLink;
+        if (this.#disposed || this.busy || this.#unrecycledLink || !link || link.closed)
+            return;
+        this.#scheduleIdleRecycle(link);
+    }
+    /** 只有没有活动请求、工具 park 或取消排空时才启动空闲计时。 */
+    #scheduleIdleRecycle(link) {
+        this.#clearIdleRecycle();
+        if (this.#idleRecycleMs <= 0 || this.#disposed || this.busy || link.closed)
+            return;
+        const timer = setTimeout(() => {
+            if (this.#idleRecycle?.timer !== timer)
+                return;
+            this.#idleRecycle = undefined;
+            if (this.busy || this.#disposed || this.#currentLink !== link || link.closed)
+                return;
+            this.#log?.info(`antigravity-acp: 进程空闲 ${this.#idleRecycleMs}ms 无新消息，回收`);
+            this.#scheduleRecycle(link, true);
+        }, this.#idleRecycleMs);
+        timer.unref?.();
+        this.#idleRecycle = { timer, link };
+    }
+    #clearIdleRecycle() {
+        const idle = this.#idleRecycle;
+        if (!idle)
+            return;
+        clearTimeout(idle.timer);
+        this.#idleRecycle = undefined;
+    }
+    /** 等待取消排空与回收；回收失败仍保留屏障，后续调用可重试同一连接。 */
     async #settleRecycle() {
+        // 本地 aborted 不是停止证明；新回合不能撤销旧回合的排空屏障。
+        await this.#cancelGrace?.pending;
         try {
             await this.#cleanup;
         }
@@ -488,8 +782,59 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             throw error;
         }
     }
+    /**
+     * 取消后的宽限：等 agent 应答 `cancelled` 再决定是否回收进程。
+     *
+     * 官方 `session/cancel` 是通知，不代表执行已停止；直接保留进程可能让它继续
+     * 跑旧会话。因此默认仍立即回收；开启 keepProcessAfterCancel 后：
+     * - 宽限内收到 prompt 应答（取消生效）→ 只丢弃会话，保留进程；
+     * - 超时未应答 → 按原策略回收；
+     * - cancelGraceMs = 0 → 不等待，立即回收。
+     */
+    #scheduleCancelGrace(link, turn) {
+        this.#clearCancelGrace();
+        if (this.#cancelGraceMs <= 0) {
+            this.#scheduleRecycle(link);
+            return;
+        }
+        let resolve;
+        const pending = new Promise(done => { resolve = done; });
+        const timer = setTimeout(() => {
+            this.#log?.warn(`antigravity-acp: 取消后 ${this.#cancelGraceMs}ms 内未收到 agent 确认，回收进程`);
+            this.#scheduleRecycle(link);
+        }, this.#cancelGraceMs);
+        timer.unref?.();
+        this.#cancelGrace = { timer, link, turn, pending, resolve };
+        this.#log?.info(`antigravity-acp: 取消后保留进程，最多等待 ${this.#cancelGraceMs}ms 供 agent 停止`);
+    }
+    /** agent 已应答（取消生效）：撤销回收，只丢弃会话。 */
+    #confirmCancelGrace(turn) {
+        const grace = this.#cancelGrace;
+        if (!grace || grace.turn !== turn)
+            return;
+        this.#clearCancelGrace();
+        this.#log?.info('antigravity-acp: agent 已确认停止，保留 ACP 进程');
+        this.#maybeIdle();
+        this.#wakeAccessWaiters();
+    }
+    #clearCancelGrace() {
+        const grace = this.#cancelGrace;
+        if (!grace)
+            return;
+        clearTimeout(grace.timer);
+        this.#cancelGrace = undefined;
+        grace.resolve();
+    }
     /** 先允许当前拒绝响应出站，再回收；同一连接的接管/取消不得重复覆盖屏障。 */
-    #scheduleRecycle(link) {
+    #scheduleRecycle(link, preserveMapping = false) {
+        this.#clearCancelGrace();
+        this.#clearIdleRecycle();
+        if (preserveMapping)
+            this.#dropAllSessions('空闲回收，保留恢复映射', link);
+        else
+            this.#dropSessionsForLink(link, 'ACP 链接回收');
+        if (this.#currentLink === link)
+            this.#currentLink = undefined;
         if (this.#unrecycledLink === link)
             return;
         this.#unrecycledLink = link;
@@ -564,7 +909,7 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         }
     }
     /** 启动阶段也响应取消；迟到资源先回收，后续回合不能越过清理屏障。 */
-    async #prepareRound(options) {
+    async #prepareRound(options, owner) {
         let link;
         const check = () => {
             if (this.#disposed)
@@ -577,8 +922,11 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             this.#observeCapabilities(link);
             check();
             const tools = options.tools ?? [];
-            this.#bridge.beginRound(tools);
             let mcpServers = [];
+            // 复用会话时无工具的一次性请求（标题、压缩）不接管桥：轮换 token 会让同一
+            // worker 上仍在复用的 ACP 会话失去工具连接。关闭复用时恢复旧的每轮清桥。
+            if (tools.length > 0 || !this.#reuseSessions)
+                this.#bridge.beginRound(tools, owner);
             if (tools.length > 0) {
                 if (!this.#bridge.listening)
                     await this.#bridge.start();
@@ -626,6 +974,7 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         }
     }
     async *#runNewRound(options) {
+        this.#clearIdleRecycle();
         await withAbort(this.#settleRecycle(), options.signal);
         if (this.#disposed)
             throw new LlmError('Antigravity ACP adapter 已卸载', 'AGY_LINK_CLOSED');
@@ -637,22 +986,73 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         // usage_update 的上下文容量归属到本次请求的 DSH 路由键。
         this.#routeModelId = options.model;
         this.#lifecycle?.beginRound(options.model);
-        const { link, session, tools } = await this.#prepareRound(options).catch((error) => {
-            this.#lifecycle?.failed(error);
-            throw error;
-        });
-        const turn = new PromptTurn(session.sessionId, {
+        const key = reusableSessionKey(options);
+        const hadMemoryRecord = key !== undefined && this.#sessions.has(key);
+        // 必须先检查旧 owner，再 claim；反过来会把刚接回的陈旧内存记录误认为仍归自己。
+        let reused = key === undefined ? undefined : this.#findReusableSession(options, key);
+        const entry = key !== undefined && this.#reuseSessions && this.#resumeSessions
+            ? await withAbort(this.#sessionStore?.claim(key, this.#sessionOwner) ?? Promise.resolve(undefined), options.signal) : undefined;
+        // 内存里没有记录时（插件刚重启），只有 resume 开启才尝试从磁盘映射恢复。
+        if (!reused && key !== undefined && !hadMemoryRecord)
+            reused = await this.#resumeSession(options, key, entry);
+        const tools = options.tools ?? [];
+        let link;
+        let sessionId;
+        if (reused) {
+            // 复用：同一 ACP 会话已有原生历史，只发本轮新增消息。
+            link = reused.link;
+            sessionId = reused.sessionId;
+            this.#log?.info(`antigravity-acp: 复用 ACP 会话 session=${sessionId} 已发送消息=${reused.sentCount}` +
+                ` 本轮新增=${options.messages.length - reused.sentCount}`);
+        }
+        else {
+            const prepared = await this.#prepareRound(options, key).catch((error) => {
+                this.#lifecycle?.failed(error);
+                throw error;
+            });
+            link = prepared.link;
+            sessionId = prepared.session.sessionId;
+        }
+        const turn = new PromptTurn(sessionId, {
             link,
             bridge: this.#bridge,
-            promptTimeoutMs: this.#promptTimeoutMs,
+            promptTimeoutMs: purposeTimeoutMs(options.purpose, this.#promptTimeoutMs),
             parkSettleMs: this.#parkSettleMs,
+            onPromptSettled: (settledTurn, response) => {
+                if (this.#cancelGrace?.turn === settledTurn) {
+                    if (response && ['cancelled', 'end_turn', 'max_tokens', 'max_turn_requests', 'refusal'].includes(response.stopReason)) {
+                        this.#confirmCancelGrace(settledTurn);
+                    }
+                    else
+                        this.#scheduleRecycle(link);
+                }
+            },
             onTerminate: (reason, info) => {
+                if (this.#disposed) {
+                    this.#bridge.invalidateRound(reason);
+                    this.#dropSessionsForTurn(turn.sessionId, '卸载时终止未完成回合');
+                    this.#wakeAccessWaiters();
+                    return;
+                }
                 this.#lifecycle?.failed(reason);
-                this.#bridge.invalidateRound(reason);
                 this.#releaseTurnSubscription(turn);
+                // 干净失败（refusal / 空回复）不算异常：agent 已应答、状态自洽，桥与会话
+                // 都保留（含带工具的会话），下一次仍可复用。
+                if (info?.clean !== true) {
+                    this.#bridge.invalidateRound(reason);
+                    this.#dropSessionsForLink(link, '回合异常终止');
+                }
                 if (info?.clean === true) {
                     // prompt 已正常应答的干净失败（refusal / 空回复等）：agent 状态自洽，
                     // 链接可复用——不为下一次对话重新 spawn 官方进程、不重弹登录。
+                    // 只清未回喂的 park，不轮换 token/owner（否则带工具的会话无法复用）。
+                    this.#bridge.resetPending(reason);
+                    this.#wakeAccessWaiters();
+                    return;
+                }
+                // 用户取消且开启保留进程：先等 agent 确认停止；确认了就只丢会话、不回收。
+                if (info?.aborted === true && this.#keepProcessAfterCancel && turn.promptStarted) {
+                    this.#scheduleCancelGrace(link, turn);
                     this.#wakeAccessWaiters();
                     return;
                 }
@@ -669,26 +1069,52 @@ export class AntigravityAcpAdapter extends LlmAdapter {
                 `（${info.detail}，本回合第 ${info.count} 次；来源=ACP插件，尚未转交DSH工具审批）`),
         });
         this.#turn = turn;
+        if (key === undefined || !this.#reuseSessions)
+            this.#ephemeral.set(turn, link);
         this.#subscribeTurn(turn);
         // 回合生命周期打点：选具体型号后「没有反应」这类问题，只靠这条能分清是
         // 「prompt 没送出去」「送出去了但没有块回来」还是「块回来了但没被消费」。
-        this.#log?.info(`antigravity-acp: 回合开始 model=${options.model} purpose=${options.purpose ?? 'chat'} session=${session.sessionId} tools=${tools.length}` +
-            `${options.reasoningEffort === undefined ? '' : ` effort=${String(options.reasoningEffort)}`}`);
-        const content = await buildPromptWithImages(options.system, options.messages, tools, this.#imageOptions(options.signal));
+        this.#log?.info(`antigravity-acp: 回合开始 model=${options.model} purpose=${options.purpose ?? 'chat'} session=${sessionId} tools=${tools.length}` +
+            `${options.reasoningEffort === undefined ? '' : ` effort=${String(options.reasoningEffort)}`}` +
+            `${reused ? ' reused=true' : ''}`);
+        // 复用会话只发增量；否则全量重建（含 system、工具策略与历史强调块）。
+        const content = reused
+            ? await buildPromptDeltaWithImages(incrementalMessages(options.messages, reused.sentCount), this.#imageOptions(options.signal))
+            : await buildPromptWithImages(options.system, options.messages, tools, this.#imageOptions(options.signal));
         this.#lifecycle?.promptSent();
+        // 全量重建后先把「已发送」记到本轮完整历史，之后才有资格复用。
+        const record = reused ?? (key !== undefined && this.#reuseSessions
+            ? this.#rememberSession(options, key, link, sessionId)
+            : undefined);
+        // 在新 prompt 在途期间，不把上一轮的旧游标继续当作可恢复状态。
+        if (record) {
+            this.#sessionStore?.delete(record.key, this.#sessionOwner);
+            if (this.#sessionStore)
+                await withAbort(this.#sessionStore.flush(), options.signal);
+        }
+        if (this.#disposed) {
+            turn.abort('adapter 已卸载');
+            throw new LlmError('Antigravity ACP adapter 已卸载', 'AGY_LINK_CLOSED');
+        }
         turn.startPrompt(content, options.signal);
         try {
             let chunks = 0;
             let textChars = 0;
             let reasoningChars = 0;
             let finish = '';
+            const emitted = [];
             for await (const chunk of drainTurn(turn)) {
                 if (chunk.type === 'text-delta')
                     textChars += chunk.text.length;
                 if (chunk.type === 'reasoning-delta')
                     reasoningChars += chunk.text.length;
-                if (chunk.type === 'finish')
+                if (chunk.type === 'block-end')
+                    emitted.push(structuredClone(chunk.block));
+                if (chunk.type === 'finish') {
                     finish = chunk.reason.kind;
+                    if (record)
+                        this.#advanceSession(record, options, emitted, turn.promptSettled);
+                }
                 if (chunks === 0)
                     this.#log?.info(`antigravity-acp: 回合首块到达（type=${chunk.type}）`);
                 if (chunk.type !== 'finish')
@@ -706,6 +1132,8 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         }
         catch (error) {
             this.#log?.warn(`antigravity-acp: 回合失败 model=${options.model}`, error);
+            if (record)
+                this.#dropSession(record, '回合异常');
             throw error;
         }
         finally {
@@ -753,7 +1181,16 @@ export class AntigravityAcpAdapter extends LlmAdapter {
                 if (!turn.terminated)
                     throw error;
             }
+            const emitted = [];
             for await (const chunk of drainTurn(turn)) {
+                if (chunk.type === 'block-end')
+                    emitted.push(structuredClone(chunk.block));
+                if (chunk.type === 'finish') {
+                    const key = reusableSessionKey(options);
+                    const record = key === undefined ? undefined : this.#sessions.get(key);
+                    if (record?.sessionId === turn.sessionId)
+                        this.#advanceSession(record, options, emitted, turn.promptSettled);
+                }
                 if (chunk.type !== 'finish')
                     this.#lifecycle?.firstOutput(chunk.type === 'block-end' && chunk.block.type === 'tool-call');
                 else
@@ -762,6 +1199,10 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             }
         }
         finally {
+            // 续轮带来的 assistant/tool 消息已经在 ACP 会话里体现过：成功时推进游标，
+            // 让下一次用户轮只发送真正的新消息；回合被终止则作废该会话。
+            if (turn.terminated)
+                this.#dropSessionsForTurn(turn.sessionId, '续轮目标回合已终止');
             this.#releaseTurnSubscriptionIfClosed(turn);
         }
     }
@@ -793,13 +1234,17 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         if (!this.#isTurnClosed(turn))
             return;
         this.#releaseTurnSubscription(turn);
-        if (this.#turn === turn)
+        const link = this.#ephemeral.get(turn);
+        if (link) {
+            this.#ephemeral.delete(turn);
+            this.#closeSession(link, turn.sessionId);
+        }
+        // 复用会话时不再 invalidateRound：轮换 token 会让 agent 手里的 MCP 连接
+        // 立即失效。关闭复用时恢复旧行为（每轮结束清桥）。
+        if (!this.#reuseSessions && this.#turn === turn)
             this.#bridge.invalidateRound('ACP 回合已结束');
     }
-    /**
-     * 放弃当前回合：取消 ACP 会话、封口 chunk 队列、清空 bridge 的 park。
-     * 不等待 prompt 应答（agent 可能已挂起），避免放弃动作被拖死。
-     */
+    /** 放弃当前回合：取消 ACP 会话、封口 chunk 队列、清空 bridge 的 park。 */
     #abandonTurn(reason) {
         const turn = this.#turn;
         this.#turn = undefined;
@@ -811,13 +1256,16 @@ export class AntigravityAcpAdapter extends LlmAdapter {
         turn.finishRound();
         turn.dispose();
         this.#bridge.resetPending(reason);
+        // 续轮条件被放弃说明这个 ACP 会话已不可信，下一次按新轮重建。
+        this.#dropSessionsForTurn(turn.sessionId, reason);
+        this.#releaseTurnSubscriptionIfClosed(turn);
     }
     #isTurnClosed(turn) {
         // finished 的判定：回合已结束且不再等待工具结果。
         return turn.terminated || (turn.promptSettled && !turn.awaitingToolResults);
     }
     #handleUnexpectedRequest(method, _request) {
-        if (!this.#turn)
+        if (this.#disposed || !this.#turn)
             return;
         const params = _request.params;
         if (params?.sessionId !== undefined && params.sessionId !== this.#turn.sessionId)
@@ -953,6 +1401,10 @@ export class AntigravityAcpAdapter extends LlmAdapter {
             this.#log?.warn(`antigravity-acp: session/set_config_option 失败（configId=${selector.configId} value=${requested}）`, error);
             throw error;
         }
+        // 不完整/不匹配的响应不能确认选模，也不能抹掉上一份有效目录。
+        if (findModelSelector(response.configOptions)?.currentValue !== requested) {
+            throw new LlmError('Antigravity ACP 未确认请求的模型配置，已停止发送 prompt，避免静默使用其他模型', AGY_ADAPTER_ERROR.MODEL_SELECTION_MISMATCH);
+        }
         this.observeSessionConfigOptions(response.configOptions);
     }
 }
@@ -984,28 +1436,37 @@ async function* drainTurn(turn) {
         yield chunk;
     }
 }
+/**
+ * 按用途收紧等待上限：标题生成与压缩都是一次性请求，挂住会占住 worker 并拖慢
+ * 聊天；给它们各自更短的上限，而不是沿用聊天的 30 分钟。
+ */
+function purposeTimeoutMs(purpose, fallback) {
+    if (purpose === 'session-title')
+        return Math.min(fallback, 90_000);
+    if (purpose === 'compaction')
+        return Math.min(fallback, 600_000);
+    return fallback;
+}
 /** 把 DSH 传来的思考强度归一到官方档位；无法识别时返回 undefined（走默认档位）。 */
 function normalizeEffort(effort) {
     const raw = effort === undefined ? undefined : effort.toString().toLowerCase();
     return AGY_REASONING_EFFORTS.find((candidate) => candidate === raw);
 }
 /**
- * 不支持项检查。temperature / stop 没有 ACP 对应通道，显式传入即拒绝。
+ * 不支持项检查。temperature / stop 没有 ACP 对应通道，记录警告并忽略。
  *
  * `reasoningEffort` **不是**不支持项：它现在是家族 → 档位模型的路由键
  * （2026-10-16 用户指示「菜单选择思考强度自动路由到对应模型」），见
  * `#applyModelSelection`。`maxTokens` 同样静默忽略（宿主会话标题等流程固定
  * 携带它，硬拒绝会让这些功能永久失败）。
  */
-function assertSupportedOptions(options) {
+function unsupportedOptions(options) {
     const unsupported = [];
     if (options.temperature !== undefined)
         unsupported.push('temperature');
     if (options.stop !== undefined)
         unsupported.push('stop');
-    if (unsupported.length === 0)
-        return;
-    throw new LlmError(`Antigravity ACP provider 不支持这些请求项：${unsupported.join('、')}。ACP v1 未为它们定义会话通道，值由官方 agent 自身的会话配置决定`, AGY_UNSUPPORTED_OPTION);
+    return unsupported;
 }
 /** 取 messages 尾部连续的 tool 结果消息（按原顺序）。 */
 function trailingToolResults(messages) {