ycodium-acp-executor 0.2.2488

package/dist/executor.js

@@ -0,0 +1,1179 @@
+// @effect-diagnostics nodeBuiltinImport:off
+// @effect-diagnostics globalDate:off
+// @effect-diagnostics globalTimers:off
+import * as NodeCrypto from "node:crypto";
+import { CLIENT_METHODS, RequestError, createAcpConnection, } from "./protocol.js";
+import { acpApprovalOptions, acpPromptSettlementBelongsToContext, isAcpRequestPermissionParams, selectAcpPermissionOptionId, selectAutoApprovedAcpPermissionOption, } from "./adapter-support.js";
+import { approvalOutcomeForDecision, createApprovalGate, } from "./approvals.js";
+import { UnboundedEventStream } from "./event-stream.js";
+import { AcpExecutorCancelTimeoutError, AcpExecutorDisposedError, AcpExecutorError, AcpExecutorNotStartedError, AcpExecutorRequestError, } from "./errors.js";
+import { fileChangesFromAcpPermission, makeAcpAssistantItemEvent, makeAcpContentDeltaEvent, makeAcpPlanUpdatedEvent, makeAcpRequestOpenedEvent, makeAcpRequestResolvedEvent, makeAcpToolCallEvent, } from "./events.js";
+import { findAcpEffortConfig } from "./config-options.js";
+import { acpModeConfigId } from "./runtime-mode.js";
+import { acpInitializePayload } from "./handshake.js";
+import { unhandledConfigCategories } from "./config-option-wiring.js";
+import { Mutex } from "./mutex.js";
+import { collectSessionConfigOptionValues, collectSessionModelIds, decideToolCallUpdateEmission, extractModelConfigId, filterMcpServersByAgentCapabilities, findSessionConfigOption, matchAdvertisedModelValue, mergeToolCallState, parseAvailableCommandsUpdate, parsePermissionRequest, parseSessionModeState, parseSessionUpdateEvent, } from "./runtime-model.js";
+import { isRecord } from "./util.js";
+import { defaultVendorHooks, } from "./vendor-hooks.js";
+const DEFAULT_CANCEL_GRACE_MS = 5_000;
+/** 原生选择题只能回传一个已提供的选项 ID，不能把任意文本当作答案。 */
+const userInputAnswerOptionId = (question, answers) => {
+    const answer = answers[question.id];
+    const selected = typeof answer === "string"
+        ? answer
+        : Array.isArray(answer) && answer.length === 1 && typeof answer[0] === "string"
+            ? answer[0]
+            : undefined;
+    return selected !== undefined && question.options.some((option) => option.id === selected)
+        ? selected
+        : undefined;
+};
+function defaultNowIso() {
+    return new Date().toISOString();
+}
+function defaultRandomId() {
+    return NodeCrypto.randomUUID();
+}
+function normalizeModelId(value) {
+    return value?.trim() || undefined;
+}
+function modelSelectionStateFromSetup(setup) {
+    const sessionModels = isRecord(setup.models) ? setup.models : undefined;
+    const modelConfigId = extractModelConfigId(setup);
+    // `models` 优先；只有配置项时走它。两样都没报仍选 set_model，发送守卫会保持静默。
+    const strategy = sessionModels === undefined && modelConfigId !== undefined
+        ? "config-option"
+        : "session/set_model";
+    const modelConfigOption = modelConfigId === undefined
+        ? undefined
+        : findSessionConfigOption(setup.configOptions, modelConfigId);
+    const configModel = modelConfigOption?.currentValue;
+    const currentModelId = strategy === "config-option"
+        ? typeof configModel === "string"
+            ? normalizeModelId(configModel)
+            : undefined
+        : typeof sessionModels?.["currentModelId"] === "string"
+            ? normalizeModelId(sessionModels["currentModelId"])
+            : undefined;
+    return {
+        strategy,
+        sessionModelsAdvertised: sessionModels !== undefined,
+        modelConfigId,
+        currentModelId,
+        advertisedModelValues: strategy === "config-option"
+            ? modelConfigOption === undefined
+                ? []
+                : collectSessionConfigOptionValues(modelConfigOption)
+            : collectSessionModelIds(sessionModels),
+    };
+}
+export function createAcpExecutor(options) {
+    const hooks = { ...defaultVendorHooks, ...options.hooks };
+    const cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+    const nowIso = options.nowIso ?? defaultNowIso;
+    const randomId = options.randomId ?? defaultRandomId;
+    const eventStream = new UnboundedEventStream();
+    const threadMutex = new Mutex();
+    const promptMutex = new Mutex();
+    let generation = 0;
+    let disposed = false;
+    let status = "idle";
+    let sessionId;
+    let modelSelectionState = {
+        strategy: "session/set_model",
+        sessionModelsAdvertised: false,
+        modelConfigId: undefined,
+        currentModelId: undefined,
+        advertisedModelValues: [],
+    };
+    /** 上一个对不上目录的请求型号：同一个 id 每轮都来，日志只记一次。 */
+    let lastUnmatchedModelId;
+    let initializeResult;
+    let startResult;
+    let startInFlight;
+    let activeTurnId;
+    let promptsInFlight = 0;
+    const interruptedTurnIds = new Set();
+    const approvals = createApprovalGate({
+        singleResolver: false,
+    });
+    // 结构化用户输入（厂商钩子把 permission 认成提问/计划时）的挂起表，
+    // 与 approvals 同理：答复 / 取消 / 断连三者竞争只完成一次。
+    const pendingUserInputs = new Map();
+    /** 这一轮挂着的「提前收口」等待。同一时刻至多一条：prompt 之间有 promptMutex。 */
+    let pendingSettlement;
+    /**
+     * 已经结算过的 promptKey。通知与 RPC 应答都可能带同一个 key 再来一次，
+     * 不记住就会把下一轮的等待错误地收掉。有界：只留最近这些。
+     */
+    const settledPromptKeys = [];
+    const SETTLED_PROMPT_KEY_LIMIT = 32;
+    const rememberSettledPromptKey = (key) => {
+        if (settledPromptKeys.includes(key))
+            return;
+        settledPromptKeys.push(key);
+        if (settledPromptKeys.length > SETTLED_PROMPT_KEY_LIMIT)
+            settledPromptKeys.shift();
+    };
+    const toolCalls = new Map();
+    let assistantSegment = { nextSegmentIndex: 0 };
+    let modeState;
+    let availableCommands = [];
+    const assistantItemRuntimeId = randomId();
+    let promptWaiters = [];
+    let abortLocalPrompt;
+    let connectionClosed = false;
+    const stamp = () => ({
+        eventId: randomId(),
+        createdAt: nowIso(),
+    });
+    // 迟到的结果先验身份：dispose 之后、或已经换代的那次 start/prompt 完成时，
+    // 不许回写状态。`Promise.race` 输掉的那一方还在跑，这是唯一的拦截点。
+    const isLive = (expectedGeneration) => !disposed && generation === expectedGeneration;
+    const publish = (event) => {
+        if (disposed) {
+            return;
+        }
+        eventStream.publish(options.originBindingGeneration === undefined
+            ? event
+            : { ...event, originBindingGeneration: options.originBindingGeneration });
+    };
+    const emit = (event) => {
+        publish(event);
+    };
+    const failIfDisposed = () => {
+        if (disposed) {
+            throw new AcpExecutorDisposedError();
+        }
+    };
+    const closeActiveAssistantSegment = (turnId) => {
+        if (!assistantSegment.activeItemId) {
+            return;
+        }
+        const itemId = assistantSegment.activeItemId;
+        assistantSegment = { nextSegmentIndex: assistantSegment.nextSegmentIndex };
+        emit(makeAcpAssistantItemEvent({
+            stamp: stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            turnId,
+            itemId,
+            lifecycle: "item.completed",
+        }));
+    };
+    const ensureActiveAssistantSegment = (acpSessionId, turnId) => {
+        if (assistantSegment.activeItemId) {
+            return assistantSegment.activeItemId;
+        }
+        const itemId = `assistant:${acpSessionId}:runtime:${assistantItemRuntimeId}:segment:${assistantSegment.nextSegmentIndex}`;
+        assistantSegment = {
+            nextSegmentIndex: assistantSegment.nextSegmentIndex + 1,
+            activeItemId: itemId,
+        };
+        emit(makeAcpAssistantItemEvent({
+            stamp: stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            turnId,
+            itemId,
+            lifecycle: "item.started",
+        }));
+        return itemId;
+    };
+    const handleSessionUpdate = (params) => {
+        const parsed = parseSessionUpdateEvent(params);
+        if (parsed.modeId && modeState) {
+            modeState = {
+                ...modeState,
+                currentModeId: parsed.modeId,
+            };
+        }
+        const commands = parseAvailableCommandsUpdate(params);
+        if (commands !== undefined) {
+            availableCommands = commands;
+        }
+        for (const event of parsed.events) {
+            if (event._tag === "ToolCallUpdated") {
+                closeActiveAssistantSegment(activeTurnId);
+                const tracked = toolCalls.get(event.toolCall.toolCallId);
+                const previous = tracked?.state;
+                const nextToolCall = mergeToolCallState(previous, event.toolCall);
+                const decision = decideToolCallUpdateEmission({
+                    previous,
+                    next: nextToolCall,
+                    lastEmittedDetailLength: tracked?.lastEmittedDetailLength,
+                    skippedSinceEmit: tracked?.skippedSinceEmit ?? 0,
+                });
+                if (nextToolCall.status === "completed" || nextToolCall.status === "failed") {
+                    toolCalls.delete(nextToolCall.toolCallId);
+                }
+                else {
+                    toolCalls.set(nextToolCall.toolCallId, {
+                        state: nextToolCall,
+                        lastEmittedDetailLength: decision.emit
+                            ? nextToolCall.detail?.length
+                            : tracked?.lastEmittedDetailLength,
+                        skippedSinceEmit: decision.skippedSinceEmit,
+                    });
+                }
+                if (!decision.emit) {
+                    continue;
+                }
+                emit(makeAcpToolCallEvent({
+                    stamp: stamp(),
+                    provider: options.provider,
+                    threadId: options.threadId,
+                    turnId: activeTurnId,
+                    toolCall: nextToolCall,
+                    rawPayload: event.rawPayload,
+                }));
+                continue;
+            }
+            if (event._tag === "ContentDelta") {
+                if (event.streamKind === "reasoning_text") {
+                    // 思考不得开 assistant 段：item.started 会把思考段收口，字会进正式回答。
+                    if (event.text.trim().length === 0) {
+                        continue;
+                    }
+                    emit(makeAcpContentDeltaEvent({
+                        stamp: stamp(),
+                        provider: options.provider,
+                        threadId: options.threadId,
+                        turnId: activeTurnId,
+                        text: event.text,
+                        streamKind: "reasoning_text",
+                        rawPayload: event.rawPayload,
+                    }));
+                    continue;
+                }
+                if (event.text.trim().length === 0 && !assistantSegment.activeItemId) {
+                    continue;
+                }
+                const itemId = sessionId
+                    ? ensureActiveAssistantSegment(sessionId, activeTurnId)
+                    : undefined;
+                emit(makeAcpContentDeltaEvent({
+                    stamp: stamp(),
+                    provider: options.provider,
+                    threadId: options.threadId,
+                    turnId: activeTurnId,
+                    ...(itemId ? { itemId } : {}),
+                    text: event.text,
+                    streamKind: "assistant_text",
+                    rawPayload: event.rawPayload,
+                }));
+                continue;
+            }
+            if (event._tag === "PlanUpdated") {
+                emit(makeAcpPlanUpdatedEvent({
+                    stamp: stamp(),
+                    provider: options.provider,
+                    threadId: options.threadId,
+                    turnId: activeTurnId,
+                    payload: event.payload,
+                    source: "acp.jsonrpc",
+                    method: "session/update",
+                    rawPayload: event.rawPayload,
+                }));
+            }
+        }
+    };
+    const emitResolved = (pending, decision, reason) => {
+        emit(makeAcpRequestResolvedEvent({
+            stamp: stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            turnId: pending.turnId,
+            requestId: pending.requestId,
+            permissionRequest: pending.permissionRequest,
+            decision,
+            ...(reason !== undefined ? { reason } : {}),
+        }));
+    };
+    const settleApproval = (pending, outcome, decision, reason) => {
+        if (!approvals.settle(pending, outcome)) {
+            return false;
+        }
+        emitResolved(pending, decision, reason);
+        return true;
+    };
+    const settleAllApprovals = (decision) => {
+        for (const entry of approvals.settleAll({ outcome: "cancelled" })) {
+            emitResolved(entry, decision);
+        }
+    };
+    const emitUserInputResolved = (pending, answers) => {
+        emit({
+            type: "user-input.resolved",
+            ...stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            ...(pending.turnId !== undefined ? { turnId: pending.turnId } : {}),
+            requestId: pending.requestId,
+            payload: { answers },
+        });
+    };
+    /** 挂着的提前收口等待。四个清理点（流断 / 连接关 / 取消 / dispose）都要过它。 */
+    const abortPendingSettlement = (reason) => {
+        const waiting = pendingSettlement;
+        if (waiting === undefined)
+            return;
+        pendingSettlement = undefined;
+        waiting.settle({ error: new AcpExecutorRequestError("session/prompt", reason) });
+    };
+    const settleAllUserInputs = () => {
+        for (const pending of pendingUserInputs.values()) {
+            if (pending.settled)
+                continue;
+            pending.settled = true;
+            pending.resolve({ kind: "cancelled" });
+        }
+        pendingUserInputs.clear();
+    };
+    /**
+     * 一条通知能不能收掉这一轮。返回 true 表示它是收口信号，已消费。
+     *
+     * 四条语义都在这里，不外放给钩子——外放的话每家会各写一遍，而其中第三条有事故记录：
+     * 1. 带 key 按 key 配，不带 key 按 sessionId 配当前这一轮（Grok 的 promptId 是可选的）
+     * 2. 已结算过的 key 丢弃，防迟到的重复通知收掉下一轮
+     * 3. `error` 走失败通道，**绝不能归成正常结束**——Grok 额度耗尽正是发它，
+     *    归成成功的话用户看到一条空白回复（`cba38ce0d`）
+     * 4. 赢了之后输掉的那条 RPC 不会有人再等，交给 dispose/close 时的 rejectPending 收
+     */
+    const settleFromNotification = (method, params) => {
+        const hook = hooks.promptSettlement;
+        if (hook === undefined || pendingSettlement === undefined)
+            return false;
+        const signal = hook.fromNotification(method, params);
+        if (signal === undefined)
+            return false;
+        const waiting = pendingSettlement;
+        if (signal.sessionId !== waiting.sessionId)
+            return false;
+        if (signal.promptKey !== undefined && signal.promptKey !== waiting.promptKey) {
+            // 不是这一轮的：可能是上一轮迟到的重复通知，消费掉但不结算。
+            return settledPromptKeys.includes(signal.promptKey);
+        }
+        pendingSettlement = undefined;
+        rememberSettledPromptKey(waiting.promptKey);
+        if (signal.outcome === "error") {
+            waiting.settle({
+                error: new AcpExecutorRequestError("session/prompt", signal.detail ?? "prompt failed without an error detail"),
+            });
+        }
+        else {
+            waiting.settle({
+                response: { stopReason: signal.stopReason ?? "end_turn" },
+            });
+        }
+        return true;
+    };
+    /**
+     * 把一组问题交给用户，等回答。权限那条（Kimi 借 permission 传提问）与厂商扩展那条
+     * （Grok 的 `_x.ai/ask_user_question`）共用这一份等待表——两边各自登记会让
+     * `settleAllUserInputs` 漏掉一半，CLI 崩溃时那一半永远不 settle。
+     */
+    const askUserInput = async (input) => {
+        // dispose 之后迟到的请求不得再登记：清理已经跑完，塞进去就再也 settle 不了。
+        failIfDisposed();
+        const requestId = randomId();
+        const { promise: settlement, resolve: settle } = Promise.withResolvers();
+        const pending = {
+            requestId,
+            questions: input.questions,
+            turnId: activeTurnId,
+            settled: false,
+            resolve: settle,
+        };
+        pendingUserInputs.set(requestId, pending);
+        emit({
+            type: "user-input.requested",
+            ...stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            ...(activeTurnId !== undefined ? { turnId: activeTurnId } : {}),
+            requestId,
+            payload: { questions: input.questions },
+            raw: {
+                source: "acp.jsonrpc",
+                method: input.method,
+                payload: input.payload,
+            },
+        });
+        const resolution = await settlement;
+        pendingUserInputs.delete(requestId);
+        emitUserInputResolved(pending, resolution.kind === "answered" ? resolution.answers : {});
+        return resolution;
+    };
+    /** 每次扩展请求现造一份，把真实方法名与原始载荷带进 `raw`，排障时看得出是谁问的。 */
+    const makeExtensionContext = (method, params) => ({
+        askUserInput: (questions) => askUserInput({ questions, method, payload: params }),
+    });
+    /** 厂商钩子认出的提问/计划走 `user-input.*`，返回 undefined 表示没接管。 */
+    const handlePermissionAsUserInput = async (params) => {
+        if (hooks.permissionUserInput === undefined)
+            return undefined;
+        let question;
+        try {
+            question = hooks.permissionUserInput(params);
+        }
+        catch (error) {
+            // 认出来却形状不全的交互绝不能降格成批准/拒绝两档——回协议错误。
+            throw RequestError.invalidParams({
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (question === undefined)
+            return undefined;
+        const resolution = await askUserInput({
+            questions: [question],
+            method: CLIENT_METHODS.session_request_permission,
+            payload: params,
+        });
+        const optionId = resolution.kind === "answered"
+            ? userInputAnswerOptionId(question, resolution.answers)
+            : undefined;
+        return {
+            outcome: optionId !== undefined ? { outcome: "selected", optionId } : { outcome: "cancelled" },
+        };
+    };
+    const handlePermissionRequest = async (params) => {
+        if (!isAcpRequestPermissionParams(params)) {
+            throw RequestError.invalidParams({ detail: "Malformed session/request_permission" });
+        }
+        const userInputOutcome = await handlePermissionAsUserInput(params);
+        if (userInputOutcome !== undefined)
+            return userInputOutcome;
+        const permissionRequest = parsePermissionRequest(params);
+        if (options.autoApprove?.(permissionRequest) === true) {
+            // 选项表认不出唯一的「允许」项就照常弹给用户，不替它猜。
+            const optionId = selectAutoApprovedAcpPermissionOption(params);
+            if (optionId !== undefined) {
+                return { outcome: { outcome: "selected", optionId } };
+            }
+        }
+        const requestId = randomId();
+        const outcome = await new Promise((resolve) => {
+            const pending = {
+                requestId,
+                request: params,
+                permissionRequest,
+                turnId: activeTurnId,
+                settled: false,
+                resolve,
+            };
+            approvals.add(pending);
+            emit(makeAcpRequestOpenedEvent({
+                stamp: stamp(),
+                provider: options.provider,
+                threadId: options.threadId,
+                turnId: activeTurnId,
+                requestId,
+                permissionRequest,
+                detail: permissionRequest.detail ?? "Approve this tool call?",
+                args: permissionRequest.toolCall?.data["rawInput"] ?? params.toolCall.rawInput,
+                options: acpApprovalOptions(params),
+                fileChanges: fileChangesFromAcpPermission(permissionRequest),
+                source: "acp.jsonrpc",
+                method: "session/request_permission",
+                rawPayload: params,
+            }));
+        });
+        return { outcome };
+    };
+    const connection = createAcpConnection({
+        readable: options.readable,
+        writable: options.writable,
+        onInboundFailure: (error) => {
+            options.log?.warn?.("acp connection closed: an inbound request could not be answered", {
+                threadId: options.threadId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        },
+        onNotification: (notification) => {
+            if (notification.method === "session/update") {
+                handleSessionUpdate(notification.params);
+                return;
+            }
+            if (settleFromNotification(notification.method, notification.params))
+                return;
+            void hooks.onExtensionNotification?.(notification.method, notification.params);
+        },
+        onRequest: async (method, params) => {
+            if (method === CLIENT_METHODS.session_request_permission) {
+                return handlePermissionRequest(params);
+            }
+            if (hooks.onExtensionRequest) {
+                // undefined = 这家不认这个方法。当成合法结果回去的话，只认自己那两个方法的
+                // 钩子会让其它未知方法静默收到 null——agent 以为调成功了。
+                const handled = await hooks.onExtensionRequest(method, params, makeExtensionContext(method, params));
+                if (handled !== undefined)
+                    return handled;
+            }
+            throw RequestError.methodNotFound(method);
+        },
+    });
+    void connection.closed.then(() => {
+        connectionClosed = true;
+        if (disposed) {
+            return;
+        }
+        settleAllApprovals("cancel");
+        settleAllUserInputs();
+        abortPendingSettlement("connection closed");
+        promptWaiters.splice(0).forEach((wake) => wake());
+    }, () => {
+        connectionClosed = true;
+    });
+    // 入流一死就当场结算挂着的审批/用户输入/轮次等待，不能等 connection.closed：
+    // 协议的 shutdown 排在入站队列后面，而队列正卡在等这些 handler settle——
+    // 等 closed 才动手就是死锁。这里先结算，队列疏通后剩余缓冲帧照常投递。
+    const onInputDead = () => {
+        if (disposed) {
+            return;
+        }
+        settleAllApprovals("cancel");
+        settleAllUserInputs();
+        // 提前收口的等待不在这里中止：清掉审批 / 用户输入之后入站队列就通了，协议层的
+        // shutdown 随即 reject 那条 prompt RPC，竞速的另一边自己会赢（实测两版都 reject，
+        // 只是理由从 "input stream ended" 变成流上的那个 error）。
+        promptWaiters.splice(0).forEach((wake) => wake());
+    };
+    options.readable.once("end", onInputDead);
+    options.readable.once("error", onInputDead);
+    const applyRequestedModel = async (input) => {
+        const requestedModelId = normalizeModelId(input.requestedModelId);
+        if (requestedModelId === undefined ||
+            requestedModelId === input.state.currentModelId ||
+            (input.state.strategy === "session/set_model" && !input.state.sessionModelsAdvertised) ||
+            (input.state.strategy === "config-option" && input.state.modelConfigId === undefined)) {
+            return input.state;
+        }
+        const value = matchAdvertisedModelValue(requestedModelId, input.state.advertisedModelValues);
+        if (value === undefined) {
+            // 对不上就保留手自己的型号，只记一次日志（带上手的目录）；没有别处替它改写上游请求。
+            if (requestedModelId !== lastUnmatchedModelId) {
+                lastUnmatchedModelId = requestedModelId;
+                options.log?.info("requested model is not in the agent catalog; keeping its own model", {
+                    requestedModelId,
+                    currentModelId: input.state.currentModelId,
+                    advertisedModelValues: input.state.advertisedModelValues,
+                });
+            }
+            return input.state;
+        }
+        if (value === input.state.currentModelId) {
+            return input.state;
+        }
+        if (input.state.strategy === "config-option") {
+            await connection.request("session/set_config_option", {
+                sessionId: input.acpSessionId,
+                configId: input.state.modelConfigId,
+                value,
+            });
+        }
+        else {
+            await connection.request("session/set_model", {
+                sessionId: input.acpSessionId,
+                modelId: value,
+            });
+        }
+        if (!isLive(input.expectedGeneration)) {
+            throw new AcpExecutorDisposedError();
+        }
+        return { ...input.state, currentModelId: value };
+    };
+    /**
+     * 把用户选的思考档位发给这只手。
+     *
+     * 三种情况不发：没选、这只手不报力度档、选的值不在它报的那几档里。最后一种尤其重要——
+     * 各家的档位值不是同一套（dsh 有 `off`，claude-agent-acp 有 `default`），发一个它不认的
+     * 值要么被拒、要么被当成未知档，不如保留它自己的默认。
+     *
+     * 发失败只记一笔，不让会话起不来：档位是锦上添花，为它把整条会话废掉不值。
+     */
+    const applyRequestedEffort = async (input) => {
+        const requested = input.requestedEffort?.trim();
+        if (!requested)
+            return;
+        const configOptions = typeof input.setup === "object" && input.setup !== null
+            ? input.setup.configOptions
+            : undefined;
+        const effort = findAcpEffortConfig(configOptions);
+        if (effort === undefined)
+            return;
+        const matched = effort.choices.find((choice) => choice.value === requested);
+        if (matched === undefined) {
+            options.log?.info("requested effort is not in the agent catalog; keeping its own", {
+                requestedEffort: requested,
+                advertised: effort.choices.map((choice) => choice.value),
+            });
+            return;
+        }
+        if (matched.isDefault === true)
+            return;
+        if (!isLive(input.expectedGeneration))
+            return;
+        try {
+            await connection.request("session/set_config_option", {
+                sessionId: input.acpSessionId,
+                configId: effort.configId,
+                value: requested,
+            });
+        }
+        catch (error) {
+            options.log?.info("setting the effort level failed; the session keeps its own", {
+                requestedEffort: requested,
+                configId: effort.configId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+    const startOnce = async (expectedGeneration) => {
+        // 载荷与探测路径共用一份（`handshake.ts`）：agent 按客户端能力决定播报什么，
+        // 两边各写一份就会问出两个不同的问题。
+        const initializePayload = acpInitializePayload(options.clientInfo, options.clientCapabilities);
+        const initialized = await connection.request("initialize", initializePayload);
+        if (!isLive(expectedGeneration)) {
+            throw new AcpExecutorDisposedError();
+        }
+        initializeResult = initialized;
+        const authMethodId = typeof options.authMethodId === "function"
+            ? options.authMethodId(initialized)
+            : options.authMethodId;
+        if (authMethodId !== undefined) {
+            await connection.request("authenticate", { methodId: authMethodId });
+            if (!isLive(expectedGeneration)) {
+                throw new AcpExecutorDisposedError();
+            }
+        }
+        const mcpServers = filterMcpServersByAgentCapabilities(options.mcpServers ?? [], initialized.agentCapabilities);
+        let setup;
+        let nextSessionId;
+        if (options.resumeSessionId && options.resumeMethod === "session/resume") {
+            setup = await connection.request("session/resume", {
+                sessionId: options.resumeSessionId,
+                cwd: options.cwd,
+                mcpServers,
+            });
+            nextSessionId = options.resumeSessionId;
+        }
+        else if (options.resumeSessionId) {
+            setup = await connection.request("session/load", {
+                sessionId: options.resumeSessionId,
+                cwd: options.cwd,
+                mcpServers,
+            });
+            nextSessionId = options.resumeSessionId;
+        }
+        else {
+            const created = await connection.request("session/new", {
+                cwd: options.cwd,
+                mcpServers,
+            });
+            nextSessionId = created.sessionId;
+            setup = created;
+        }
+        // 报了一类从没登记过的选项，说一声。在此之前只挑 `model` 与力度档，其余整个丢掉、
+        // 零痕迹——界面上少一格，日志里一个字都没有（2026-09-19 力度档就是这么漏的）。
+        const unhandledCategories = unhandledConfigCategories(setup.configOptions);
+        if (unhandledCategories.length > 0) {
+            options.log?.info("acp session reported config option categories we do not handle", {
+                sessionId: nextSessionId,
+                categories: unhandledCategories,
+            });
+        }
+        const nextModelSelectionState = await applyRequestedModel({
+            state: modelSelectionStateFromSetup(setup),
+            acpSessionId: nextSessionId,
+            requestedModelId: options.requestedModelId,
+            expectedGeneration,
+        });
+        await applyRequestedEffort({
+            setup,
+            acpSessionId: nextSessionId,
+            requestedEffort: options.requestedEffort,
+            expectedGeneration,
+        });
+        if (options.beforeApplyResult) {
+            await options.beforeApplyResult();
+        }
+        if (!isLive(expectedGeneration)) {
+            throw new AcpExecutorDisposedError();
+        }
+        sessionId = nextSessionId;
+        modelSelectionState = nextModelSelectionState;
+        modeState = parseSessionModeState(setup);
+        const result = {
+            sessionId: nextSessionId,
+            generation: expectedGeneration,
+            initializeResult: initialized,
+            sessionSetupResult: setup,
+            modelConfigId: extractModelConfigId(setup),
+            modelId: nextModelSelectionState.currentModelId,
+        };
+        startResult = result;
+        status = "ready";
+        emit({
+            type: "session.started",
+            ...stamp(),
+            provider: options.provider,
+            ...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
+            threadId: options.threadId,
+            payload: {
+                sessionId: nextSessionId,
+                cwd: options.cwd,
+            },
+        });
+        return result;
+    };
+    const start = async () => {
+        failIfDisposed();
+        if (startResult) {
+            return startResult;
+        }
+        if (startInFlight) {
+            return startInFlight;
+        }
+        generation += 1;
+        const expectedGeneration = generation;
+        status = "starting";
+        startInFlight = startOnce(expectedGeneration).then((result) => {
+            startInFlight = undefined;
+            return result;
+        }, (error) => {
+            startInFlight = undefined;
+            if (isLive(expectedGeneration) && !startResult) {
+                status = "idle";
+                generation = expectedGeneration;
+            }
+            throw error;
+        });
+        return startInFlight;
+    };
+    const requireStarted = () => {
+        failIfDisposed();
+        if (!sessionId || !startResult) {
+            throw new AcpExecutorNotStartedError();
+        }
+        return { sessionId, generation: startResult.generation };
+    };
+    const notifyPromptSettled = () => {
+        const waiters = promptWaiters.splice(0);
+        for (const waiter of waiters) {
+            waiter();
+        }
+    };
+    const waitForPromptIdle = async (timeoutMs) => {
+        if (!promptMutex.isLocked) {
+            return true;
+        }
+        return await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                promptWaiters = promptWaiters.filter((waiter) => waiter !== onSettle);
+                resolve(false);
+            }, timeoutMs);
+            const onSettle = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            promptWaiters.push(onSettle);
+        });
+    };
+    const settleTurn = (input) => {
+        if (!isLive(input.expectedGeneration)) {
+            return;
+        }
+        if (!acpPromptSettlementBelongsToContext({
+            liveAcpSessionId: sessionId ?? "",
+            expectedAcpSessionId: input.expectedSessionId,
+            liveActiveTurnId: activeTurnId,
+            liveSessionActiveTurnId: activeTurnId,
+            turnId: input.turnId,
+        })) {
+            return;
+        }
+        closeActiveAssistantSegment(input.turnId);
+        promptsInFlight = Math.max(0, promptsInFlight - 1);
+        if (promptsInFlight === 0 && activeTurnId === input.turnId) {
+            activeTurnId = undefined;
+            if (status !== "disposed") {
+                status = "ready";
+            }
+            emit({
+                type: "turn.completed",
+                ...stamp(),
+                provider: options.provider,
+                threadId: options.threadId,
+                turnId: input.turnId,
+                payload: {
+                    state: input.state,
+                    stopReason: input.stopReason,
+                },
+            });
+            interruptedTurnIds.delete(input.turnId);
+        }
+    };
+    const prompt = async (input) => {
+        failIfDisposed();
+        const started = requireStarted();
+        let turnId;
+        // thread 锁只罩短临界区（开轮、结算），不罩整个 prompt RPC。把整轮锁进去的话，
+        // 取消与审批答复会排在这把锁后面——「停止」和「允许」就永远到不了。
+        await threadMutex.acquire();
+        try {
+            failIfDisposed();
+            turnId = input.turnId ?? (promptsInFlight > 0 ? activeTurnId : undefined) ?? randomId();
+            promptsInFlight += 1;
+            activeTurnId = turnId;
+            status = "running";
+            if (promptsInFlight === 1) {
+                emit({
+                    type: "turn.started",
+                    ...stamp(),
+                    provider: options.provider,
+                    threadId: options.threadId,
+                    turnId,
+                    payload: {},
+                });
+            }
+        }
+        finally {
+            threadMutex.release();
+        }
+        const promptParts = input.prompt ??
+            (input.text !== undefined
+                ? [{ type: "text", text: input.text }]
+                : [{ type: "text", text: "" }]);
+        await promptMutex.acquire();
+        let response;
+        try {
+            failIfDisposed();
+            if (interruptedTurnIds.has(turnId)) {
+                settleTurn({
+                    expectedGeneration: started.generation,
+                    expectedSessionId: started.sessionId,
+                    turnId,
+                    stopReason: "cancelled",
+                    state: "cancelled",
+                });
+                return {
+                    threadId: options.threadId,
+                    turnId,
+                    stopReason: "cancelled",
+                };
+            }
+            modelSelectionState = await applyRequestedModel({
+                state: modelSelectionState,
+                acpSessionId: started.sessionId,
+                requestedModelId: input.requestedModelId,
+                expectedGeneration: started.generation,
+            });
+            closeActiveAssistantSegment(turnId);
+            const settlementHooks = hooks.promptSettlement;
+            // 有提前收口钩子时给这一轮一个关联 id，通知才认得回来。
+            const promptKey = settlementHooks === undefined ? undefined : randomId();
+            const promptRpc = connection.request("session/prompt", {
+                sessionId: started.sessionId,
+                prompt: promptParts,
+                ...(settlementHooks !== undefined && promptKey !== undefined
+                    ? settlementHooks.requestFields(promptKey)
+                    : {}),
+            });
+            // 老实等对端应答。取消走 `session/cancel` 通知让 agent 自己收尾，不在本地
+            // 假装 resolve —— 那会让「调用方不再等」被误当成「远端已经停了」。
+            //
+            // 唯一的例外是提前收口钩子：Grok 1.0.24 起发完 `prompt_complete` 就不再回这条
+            // 应答，只等它这一轮永远收不了口。那不是本地假装 resolve——收口信号是对端发的。
+            try {
+                if (settlementHooks === undefined || promptKey === undefined) {
+                    response = await promptRpc;
+                }
+                else {
+                    const { promise: early, resolve: settleEarly } = Promise.withResolvers();
+                    pendingSettlement = { promptKey, sessionId: started.sessionId, settle: settleEarly };
+                    try {
+                        const outcome = await Promise.race([
+                            promptRpc.then((value) => {
+                                const key = settlementHooks.responseKey?.(value);
+                                if (key !== undefined)
+                                    rememberSettledPromptKey(key);
+                                return { response: value };
+                            }),
+                            early,
+                        ]);
+                        if (outcome.error !== undefined)
+                            throw outcome.error;
+                        response = outcome.response;
+                    }
+                    finally {
+                        pendingSettlement = undefined;
+                        // 输掉的那条 RPC 没人再等。协议层没有单请求取消，它挂在 pending 表里
+                        // 直到连接关闭——一轮一条，所以这里吞掉它的 rejection，不留未处理拒绝。
+                        void promptRpc.catch(() => undefined);
+                    }
+                }
+            }
+            catch (error) {
+                if (disposed) {
+                    throw new AcpExecutorDisposedError();
+                }
+                throw error;
+            }
+            // 应答唤醒调用方不代表同批通知已经派发：一次 stdio read 可能同时带回应答与
+            // 排在它后面的 `session/update`。不等排空就结算会漏事件。
+            await connection.awaitInboundIdle();
+            if (options.beforeApplyResult) {
+                await options.beforeApplyResult();
+            }
+        }
+        finally {
+            promptMutex.release();
+            notifyPromptSettled();
+        }
+        if (!isLive(started.generation)) {
+            throw new AcpExecutorDisposedError();
+        }
+        if (turnId === undefined) {
+            throw new AcpExecutorError("internal", "ACP prompt settled without a turn id");
+        }
+        const settledTurnId = turnId;
+        // 上下文占用在这家 CLI 自己写的记录里（厂商钩子）；读不到、读坏都不挡
+        // 轮次收尾——少一条事件，界面不画圈，而不是画一个编出来的数。
+        let contextWindow;
+        if (hooks.readContextWindow !== undefined) {
+            try {
+                contextWindow =
+                    (await hooks.readContextWindow({
+                        sessionId: started.sessionId,
+                        promptResponse: response,
+                    })) ?? undefined;
+            }
+            catch {
+                contextWindow = undefined;
+            }
+        }
+        const finishPrompt = () => {
+            if (interruptedTurnIds.has(settledTurnId)) {
+                settleTurn({
+                    expectedGeneration: started.generation,
+                    expectedSessionId: started.sessionId,
+                    turnId: settledTurnId,
+                    stopReason: "cancelled",
+                    state: "cancelled",
+                });
+                return {
+                    threadId: options.threadId,
+                    turnId: settledTurnId,
+                    stopReason: "cancelled",
+                };
+            }
+            const stopReason = hooks.completedStopReason?.(response) ?? response.stopReason;
+            if (contextWindow !== undefined) {
+                emit({
+                    type: "thread.token-usage.updated",
+                    ...stamp(),
+                    provider: options.provider,
+                    threadId: options.threadId,
+                    turnId: settledTurnId,
+                    payload: {
+                        usage: {
+                            usedTokens: contextWindow.usedTokens,
+                            ...(contextWindow.maxTokens === undefined
+                                ? {}
+                                : { maxTokens: contextWindow.maxTokens }),
+                        },
+                    },
+                });
+            }
+            settleTurn({
+                expectedGeneration: started.generation,
+                expectedSessionId: started.sessionId,
+                turnId: settledTurnId,
+                stopReason,
+                state: response.stopReason === "cancelled" ? "cancelled" : "completed",
+            });
+            return {
+                threadId: options.threadId,
+                turnId: settledTurnId,
+                stopReason,
+                ...(response.usage !== undefined && response.usage !== null
+                    ? { usage: response.usage }
+                    : {}),
+            };
+        };
+        if (threadMutex.tryAcquire()) {
+            try {
+                return finishPrompt();
+            }
+            finally {
+                threadMutex.release();
+            }
+        }
+        await threadMutex.acquire();
+        try {
+            return finishPrompt();
+        }
+        finally {
+            threadMutex.release();
+        }
+    };
+    const cancel = async (turnId) => {
+        failIfDisposed();
+        const started = requireStarted();
+        const targetTurnId = turnId ?? activeTurnId;
+        if (targetTurnId !== undefined) {
+            interruptedTurnIds.add(targetTurnId);
+        }
+        settleAllApprovals("cancel");
+        settleAllUserInputs();
+        abortPendingSettlement("turn cancelled");
+        const runCancel = async () => {
+            if (sessionId) {
+                await connection.notify("session/cancel", { sessionId });
+            }
+            const settled = await waitForPromptIdle(cancelGraceMs);
+            if (!settled) {
+                throw new AcpExecutorCancelTimeoutError();
+            }
+            if (targetTurnId !== undefined && isLive(started.generation)) {
+                if (activeTurnId === targetTurnId || interruptedTurnIds.has(targetTurnId)) {
+                    if (status === "running") {
+                        closeActiveAssistantSegment(targetTurnId);
+                        promptsInFlight = 0;
+                        activeTurnId = undefined;
+                        status = "ready";
+                        emit({
+                            type: "turn.completed",
+                            ...stamp(),
+                            provider: options.provider,
+                            threadId: options.threadId,
+                            turnId: targetTurnId,
+                            payload: {
+                                state: "cancelled",
+                                stopReason: "cancelled",
+                            },
+                        });
+                        interruptedTurnIds.delete(targetTurnId);
+                    }
+                }
+            }
+        };
+        // 取消不走 thread 锁。今天 thread 锁只罩开轮与结算两段短临界区，prompt RPC 在锁外，
+        // 所以排进去也不会被 RPC 堵住——但那是「锁范围恰好正确」带来的，不是设计保证。
+        // 让取消独立于这把锁，是为了以后有人加长临界区时，Stop 仍然到得了。
+        await runCancel();
+    };
+    const respondToRequest = async (requestId, decision, reason) => {
+        failIfDisposed();
+        const apply = () => {
+            const pending = approvals.get(requestId);
+            if (!pending || pending.requestId !== requestId) {
+                throw new AcpExecutorRequestError("session/request_permission", `Unknown pending approval request: ${requestId}`);
+            }
+            if (pending.settled) {
+                return;
+            }
+            const selectedOptionId = decision === "cancel" ? undefined : selectAcpPermissionOptionId(pending.request, decision);
+            if (decision !== "cancel" && selectedOptionId === undefined) {
+                throw new AcpExecutorRequestError("session/request_permission", `Unsupported approval decision for this request: ${decision}`);
+            }
+            settleApproval(pending, approvalOutcomeForDecision(decision, selectedOptionId), decision, reason);
+        };
+        // 审批答复同样不走 thread 锁，理由同 `cancel`。
+        apply();
+    };
+    const setNativeMode = async (modeId) => {
+        failIfDisposed();
+        const started = startResult;
+        if (started === undefined) {
+            throw new AcpExecutorRequestError("session/set_mode", "session has not started yet");
+        }
+        // 报了 configOptions 那一项就走它，否则走 session/set_mode——两种报法各家挑一种，
+        // 发错通道会被回 `-32601 Method not found`（dsh 实测）。
+        const configId = acpModeConfigId(started.sessionSetupResult);
+        if (configId !== undefined) {
+            await connection.request("session/set_config_option", {
+                sessionId: started.sessionId,
+                configId,
+                value: modeId,
+            });
+            return;
+        }
+        await connection.request("session/set_mode", {
+            sessionId: started.sessionId,
+            modeId,
+        });
+    };
+    const respondToUserInput = async (requestId, answers) => {
+        failIfDisposed();
+        const pending = pendingUserInputs.get(requestId);
+        if (pending === undefined) {
+            throw new AcpExecutorRequestError("session/request_permission", `Unknown pending user-input request: ${requestId}`);
+        }
+        if (pending.settled) {
+            return;
+        }
+        pending.settled = true;
+        pendingUserInputs.delete(requestId);
+        pending.resolve({
+            kind: "answered",
+            answers: isRecord(answers) ? answers : {},
+        });
+    };
+    const dispose = async () => {
+        if (disposed) {
+            return;
+        }
+        settleAllApprovals("cancel");
+        settleAllUserInputs();
+        abortPendingSettlement("executor disposed");
+        notifyPromptSettled();
+        abortLocalPrompt?.();
+        emit({
+            type: "session.exited",
+            ...stamp(),
+            provider: options.provider,
+            threadId: options.threadId,
+            payload: { reason: "disposed" },
+        });
+        disposed = true;
+        generation += 1;
+        status = "disposed";
+        eventStream.close();
+        options.readable.off("end", onInputDead);
+        options.readable.off("error", onInputDead);
+        options.readable.pause();
+        if (!connectionClosed) {
+            await connection.awaitInboundIdle().catch(() => undefined);
+            await connection.close().catch(() => undefined);
+        }
+    };
+    return {
+        get generation() {
+            return generation;
+        },
+        get sessionId() {
+            return sessionId;
+        },
+        get modelId() {
+            return modelSelectionState.currentModelId;
+        },
+        get status() {
+            return status;
+        },
+        events: eventStream.subscribe(),
+        start,
+        prompt,
+        cancel,
+        respondToRequest,
+        respondToUserInput,
+        setNativeMode,
+        dispose,
+    };
+}
+export function isAcpExecutorError(error) {
+    return error instanceof AcpExecutorError;
+}
+//# sourceMappingURL=executor.js.map