ycodium-acp-executor 0.2.2488

package/README.md

@@ -0,0 +1,127 @@
+# ycodium-acp-executor
+
+The Agent Client Protocol (ACP) client that Ycodium's own agent plugins run on, published so
+your plugin can use it too. Point it at the stdio streams of any ACP-speaking CLI and it
+gives you a session that emits Ycodium executor events: assistant text, tool calls, plans,
+approvals, structured questions, token usage.
+
+If the CLI you want to add to Ycodium speaks ACP, you should not have to write framing,
+handshakes, permission round trips or cancellation yourself. This package is that layer. It has
+no dependency on Ycodium or on Effect.
+
+## Install
+
+```
+npm install --save-dev ycodium-acp-executor
+```
+
+Bundle it into your plugin. Only `@ycodium-ai/plugin-api` stays external, because the host
+provides that one (see the [plugin-api README](https://www.npmjs.com/package/@ycodium-ai/plugin-api)).
+With esbuild:
+
+```js
+await esbuild.build({
+  entryPoints: ["src/index.ts"],
+  outfile: "dist/index.js",
+  bundle: true,
+  external: ["@ycodium-ai/plugin-api", "@ycodium-ai/plugin-api/*"],
+  format: "esm",
+  platform: "node",
+  target: "node24",
+});
+```
+
+It is an ES module for Node. The package depends on `@agentclientprotocol/sdk` and
+`zod` and re-exports the SDK types you need, so you do not have to install the SDK separately.
+
+## Build an ACP agent plugin
+
+An agent plugin declares an executor with `definePlugin` from `@ycodium-ai/plugin-api`. This
+package covers the ACP half: turning a spawned CLI into a session.
+
+```ts
+import { nodeStreamsFromHandle } from "@ycodium-ai/plugin-api/process-stdin";
+import { createAcpExecutor, parseAcpResumeCursor } from "ycodium-acp-executor";
+
+// Inside your ExecutorInstance.startSession(input):
+const handle = await host.process.spawn({
+  program: "my-agent",
+  args: ["acp"],
+  cwd,
+  owner: { bindingId: host.bindingId },
+});
+const { readable, writable } = nodeStreamsFromHandle(handle);
+
+const executor = createAcpExecutor({
+  readable,
+  writable,
+  cwd,
+  threadId: input.threadId,
+  provider: "myAgent",
+  providerInstanceId: host.instanceId,
+  clientInfo: { name: "ycodium", version: "1.0.0" },
+  log: host.log,
+  resumeSessionId: parseAcpResumeCursor(input.resumeCursor, 1)?.sessionId,
+});
+
+const started = await executor.start(); // initialize, then session/new or session/load
+for await (const event of executor.events) {
+  // Forward each event to the executor events your plugin exposes.
+}
+
+// In sendTurn / interruptTurn / stop:
+await executor.prompt({ text: "Explain this repository", turnId });
+await executor.cancel(turnId);
+await executor.dispose();
+```
+
+`executor.events` yields `ExecutorEvent` values with the same shape as the type of that name in
+`@ycodium-ai/plugin-api/executor`. This package does not import plugin-api, so the two types are
+structurally compatible rather than shared.
+
+What the executor handles for you:
+
+- The `initialize` handshake, session creation, and resume through `session/load` or
+  `session/resume` (`resumeMethod`).
+- Prompt turns, cancellation with a grace period, and settling a turn exactly once.
+- Permission requests, mapped to approval requests you answer with `respondToRequest`, with an
+  optional `autoApprove` for the host's own approval levels.
+- Model and effort selection, using whichever route the agent advertises: session models or
+  configuration options.
+- Runtime and native modes, through `setNativeMode`.
+- Tool calls, plan updates and content deltas as executor events.
+- Token usage and context window readings.
+
+## Vendor differences go in hooks
+
+Do not fork the state machine for one CLI's quirks. Pass `hooks` (`AcpVendorHooks`) instead:
+
+- `permissionUserInput` turns a permission request into a structured question.
+- `onExtensionRequest` and `onExtensionNotification` handle vendor-private methods.
+- `readContextWindow` reads context usage that the CLI records somewhere other than ACP.
+- `promptSettlement` lets a turn end on a signal other than the prompt response.
+- `resolveRequestedModelId` and `resolveDisplayModelId` map model names.
+
+## Probing a CLI
+
+Before a session exists, an instance usually has to report whether the CLI is installed, its
+version and its models:
+
+- `probeCliVersion`, `parseCliVersion` and `collectProbeProcess` run a CLI and read its output.
+- `openAcpProbeHandshake` opens a throwaway connection over the CLI's stdio, runs `initialize`, and
+  lets you send further requests (`session/new`, `session/list`) with one timeout.
+- `acpModelChoicesFromConfigOptions`, `acpModelChoicesFromSessionModels`, `findAcpEffortConfig`,
+  `acpAvailableModes` and `acpAgentVersion` read models, effort levels, modes and the agent
+  version out of those answers.
+
+## Lower level
+
+`createAcpConnection` is the newline-delimited JSON-RPC transport underneath, and the package
+re-exports the SDK's method tables and request and response types (`CLIENT_METHODS`,
+`AGENT_METHODS`, `PromptRequest`, `SessionNotification`, and so on). Reach for it only if
+`createAcpExecutor` does not fit; everything above is built on it.
+
+## Stability
+
+Ycodium's own agent plugins (ACP, DSH, Grok, Kimi Code) depend on this package, so its exports
+change deliberately. It is versioned and released with the Ycodium plugins as `0.2.<n>`.

package/dist/adapter-support.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 从 `AcpAdapterSupport.ts` 搬来的纯函数。只改类型，业务规则没改。
+ */
+import type { AcpApprovalDecision, AcpApprovalOption, AcpPermissionOption, AcpRequestPermissionParams } from "./types.ts";
+export declare function acpPermissionOutcome(decision: AcpApprovalDecision): string;
+export declare function selectAcpPermissionOptionId(request: {
+    readonly options: ReadonlyArray<AcpPermissionOption>;
+}, decision: Exclude<AcpApprovalDecision, "cancel">): string | undefined;
+export declare function acpApprovalOptions(request: {
+    readonly options: ReadonlyArray<AcpPermissionOption>;
+}): ReadonlyArray<AcpApprovalOption>;
+export declare function selectAutoApprovedAcpPermissionOption(request: {
+    readonly options: ReadonlyArray<AcpPermissionOption>;
+}): string | undefined;
+export declare function parseAcpResumeCursor(raw: unknown, schemaVersion: number): {
+    sessionId: string;
+} | undefined;
+export declare function acpPromptSettlementBelongsToContext(input: {
+    readonly liveAcpSessionId: string;
+    readonly expectedAcpSessionId: string;
+    readonly liveActiveTurnId: string | undefined;
+    readonly liveSessionActiveTurnId: string | undefined;
+    readonly turnId: string;
+}): boolean;
+export declare function isAcpRequestPermissionParams(value: unknown): value is AcpRequestPermissionParams;
+//# sourceMappingURL=adapter-support.d.ts.map

package/dist/adapter-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-support.d.ts","sourceRoot":"","sources":["../src/adapter-support.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAW1E;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAA;CAAE,EACjE,QAAQ,EAAE,OAAO,CAAC,mBAAmB,EAAE,QAAQ,CAAC,GAC/C,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACtD,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAoBnC;AAED,wBAAgB,qCAAqC,CAAC,OAAO,EAAE;IAC7D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACtD,GAAG,MAAM,GAAG,SAAS,CAQrB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,MAAM,GACpB;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMnC;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAKV;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAgBhG"}

package/dist/adapter-support.js

@@ -0,0 +1,79 @@
+export function acpPermissionOutcome(decision) {
+    switch (decision) {
+        case "acceptForSession":
+        case "acceptAlways":
+            return "allow-always";
+        case "accept":
+            return "allow-once";
+        case "decline":
+        default:
+            return "reject-once";
+    }
+}
+export function selectAcpPermissionOptionId(request, decision) {
+    const kind = decision === "acceptForSession" || decision === "acceptAlways"
+        ? "allow_always"
+        : decision === "accept"
+            ? "allow_once"
+            : "reject_once";
+    const options = request.options.filter((entry) => entry.kind === kind);
+    const optionId = options.length === 1 ? options[0]?.optionId : undefined;
+    return optionId?.trim() ? optionId : undefined;
+}
+export function acpApprovalOptions(request) {
+    const options = [{ decision: "cancel", label: "Cancel" }];
+    for (const option of request.options) {
+        const decision = option.kind === "allow_once"
+            ? "accept"
+            : option.kind === "allow_always"
+                ? "acceptForSession"
+                : option.kind === "reject_once"
+                    ? "decline"
+                    : undefined;
+        if (decision !== undefined &&
+            selectAcpPermissionOptionId(request, decision) !== undefined &&
+            option.name.trim().length > 0) {
+            options.push({ decision, label: option.name });
+        }
+    }
+    return options;
+}
+export function selectAutoApprovedAcpPermissionOption(request) {
+    if (new Set(request.options.map((option) => option.kind)).size !== request.options.length) {
+        return undefined;
+    }
+    return (selectAcpPermissionOptionId(request, "acceptForSession") ??
+        selectAcpPermissionOptionId(request, "accept"));
+}
+export function parseAcpResumeCursor(raw, schemaVersion) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    if (record["schemaVersion"] !== schemaVersion)
+        return undefined;
+    if (typeof record["sessionId"] !== "string" || !record["sessionId"].trim())
+        return undefined;
+    return { sessionId: record["sessionId"].trim() };
+}
+export function acpPromptSettlementBelongsToContext(input) {
+    return (input.liveAcpSessionId === input.expectedAcpSessionId &&
+        (input.liveActiveTurnId === input.turnId || input.liveSessionActiveTurnId === input.turnId));
+}
+export function isAcpRequestPermissionParams(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    if (typeof record["sessionId"] !== "string") {
+        return false;
+    }
+    const toolCall = record["toolCall"];
+    if (typeof toolCall !== "object" || toolCall === null) {
+        return false;
+    }
+    if (typeof toolCall["toolCallId"] !== "string") {
+        return false;
+    }
+    return Array.isArray(record["options"]);
+}
+//# sourceMappingURL=adapter-support.js.map

package/dist/adapter-support.js.map

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

package/dist/approvals.d.ts

@@ -0,0 +1,39 @@
+import type { AcpApprovalDecision, AcpRequestPermissionParams } from "./types.ts";
+import type { AcpPermissionRequest } from "./runtime-model.ts";
+export type PermissionOutcome = {
+    readonly outcome: "cancelled";
+} | {
+    readonly outcome: "selected";
+    readonly optionId: string;
+};
+export type PendingApproval = {
+    readonly requestId: string;
+    readonly request: AcpRequestPermissionParams;
+    readonly permissionRequest: AcpPermissionRequest;
+    readonly turnId: string | undefined;
+    settled: boolean;
+    readonly resolve: (outcome: PermissionOutcome) => void;
+};
+/**
+ * 按 requestId 分开的审批门。不是全会话一个 resolver。
+ * 答复 / 取消 / 断连三者竞争只完成一次。
+ */
+/**
+ * 审批闸：每个请求一份记录，不是全会话一个 resolver。
+ *
+ * `singleResolver` 只给测试用——把闸退回「全会话一个 resolver」的错误实现，好证明
+ * 那条测试确实测得着。生产路径不传它。它是显式参数而不是环境变量，正因为环境变量
+ * 在任何地方被设都会生效，而参数只有调用点能给。
+ */
+export declare function createApprovalGate(input?: {
+    readonly singleResolver?: boolean;
+}): {
+    add: (entry: PendingApproval) => void;
+    get: (requestId: string) => PendingApproval | undefined;
+    list: () => PendingApproval[];
+    settle: (entry: PendingApproval, outcome: PermissionOutcome) => boolean;
+    settleAll: (outcome: PermissionOutcome) => ReadonlyArray<PendingApproval>;
+};
+export type ApprovalGate = ReturnType<typeof createApprovalGate>;
+export declare function approvalOutcomeForDecision(decision: AcpApprovalDecision, optionId: string | undefined): PermissionOutcome;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,oBAAoB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF;;;GAGG;AACH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE;iBAkB1D,eAAe,KAAG,IAAI;qBAPlB,MAAM,KAAG,eAAe,GAAG,SAAS;gBAP3C,eAAe,EAAE;oBAsBX,eAAe,WAAW,iBAAiB,KAAG,OAAO;yBAahD,iBAAiB,KAAG,aAAa,CAAC,eAAe,CAAC;EAkB/E;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEjE,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,iBAAiB,CAInB"}

package/dist/approvals.js

@@ -0,0 +1,69 @@
+/**
+ * 按 requestId 分开的审批门。不是全会话一个 resolver。
+ * 答复 / 取消 / 断连三者竞争只完成一次。
+ */
+/**
+ * 审批闸：每个请求一份记录，不是全会话一个 resolver。
+ *
+ * `singleResolver` 只给测试用——把闸退回「全会话一个 resolver」的错误实现，好证明
+ * 那条测试确实测得着。生产路径不传它。它是显式参数而不是环境变量，正因为环境变量
+ * 在任何地方被设都会生效，而参数只有调用点能给。
+ */
+export function createApprovalGate(input) {
+    const pending = new Map();
+    let single;
+    const list = () => {
+        if (input?.singleResolver) {
+            return single ? [single] : [];
+        }
+        return [...pending.values()];
+    };
+    const get = (requestId) => {
+        if (input?.singleResolver) {
+            return single;
+        }
+        return pending.get(requestId);
+    };
+    const add = (entry) => {
+        if (input?.singleResolver) {
+            single = entry;
+            return;
+        }
+        pending.set(entry.requestId, entry);
+    };
+    const settle = (entry, outcome) => {
+        if (entry.settled) {
+            return false;
+        }
+        entry.settled = true;
+        pending.delete(entry.requestId);
+        if (single?.requestId === entry.requestId) {
+            single = undefined;
+        }
+        entry.resolve(outcome);
+        return true;
+    };
+    const settleAll = (outcome) => {
+        const entries = list();
+        const settled = [];
+        for (const entry of entries) {
+            if (settle(entry, outcome)) {
+                settled.push(entry);
+            }
+        }
+        return settled;
+    };
+    return {
+        add,
+        get,
+        list,
+        settle,
+        settleAll,
+    };
+}
+export function approvalOutcomeForDecision(decision, optionId) {
+    return decision !== "cancel" && optionId !== undefined
+        ? { outcome: "selected", optionId }
+        : { outcome: "cancelled" };
+}
+//# sourceMappingURL=approvals.js.map

package/dist/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA6C;IAC9E,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,IAAI,MAAmC,CAAC;IAExC,MAAM,IAAI,GAAG,GAAsB,EAAE;QACnC,IAAI,KAAK,EAAE,cAAc,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,CAAC;QACD,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,CAAC,SAAiB,EAA+B,EAAE;QAC7D,IAAI,KAAK,EAAE,cAAc,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,CAAC,KAAsB,EAAQ,EAAE;QAC3C,IAAI,KAAK,EAAE,cAAc,EAAE,CAAC;YAC1B,MAAM,GAAG,KAAK,CAAC;YACf,OAAO;QACT,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,KAAsB,EAAE,OAA0B,EAAW,EAAE;QAC7E,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,MAAM,EAAE,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;YAC1C,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,OAA0B,EAAkC,EAAE;QAC/E,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,GAAG;QACH,GAAG;QACH,IAAI;QACJ,MAAM;QACN,SAAS;KACV,CAAC;AACJ,CAAC;AAID,MAAM,UAAU,0BAA0B,CACxC,QAA6B,EAC7B,QAA4B;IAE5B,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,SAAS;QACpD,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE;QACnC,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC"}

package/dist/config-option-wiring.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ACP 会话报回来的 `configOptions`，这只手对每一类的处置登记。
+ *
+ * **这张表为什么是三态，不是编译期穷尽**：`category` 是**开放联合**——协议原文
+ * "Clients MUST handle missing or unknown categories gracefully"，且 `_` 开头留给厂商
+ * 自定义。开放集做不了穷尽检查，所以：
+ *
+ * - `consumed: true` —— 已经接到生效点，`via` 写明接在哪。
+ * - `consumed: false` —— **知道有、还没接**，`note` 写明为什么。
+ * - 表外 —— 上游或厂商报了从没见过的一类，`unhandledConfigCategories` 挑出来记一条诊断。
+ *
+ * 第三态是这张表存在的理由。在此之前只挑 `model` 一项，其余整个丢掉、零痕迹：
+ * 2026-09-19 实测 `@agentclientprotocol/claude-agent-acp@0.79.0` 同时报了
+ * `mode` / `model` / `thought_level` 三项，接了两项，力度档那一整格因此在界面上缺席，
+ * 而没有任何日志说过这件事——只有手工连一次协议才看得见。
+ *
+ * **2026-09-20 从 `apps/server/src/provider/acp/configOptionWiring.ts` 搬来，三行处置
+ * 跟着变了**：宿主那份记的是宿主消费点，而宿主的 ACP 路本来就是留给 cursor 的，
+ * cursor 废弃删除之后整片成了孤儿。搬过来必须按**这只手**的实情重填——
+ * `thought_level` / `model_option` 在这里是接了的（`findAcpEffortConfig` 两处都认），
+ * `model_config` 原来只有 CursorProvider 消费，现在没有消费点。
+ *
+ * @module @ycodium/acp-executor/config-option-wiring
+ */
+import type { AcpSessionConfigOption } from "./runtime-model.ts";
+/**
+ * 今天见过的几类。
+ *
+ * 加一类到这里不会自动接上任何东西——`consumed: true` 必须同时有真的接线，
+ * 配套测试钉着这一点。
+ */
+export declare const ACP_CONFIG_CATEGORY_HANDLING: {
+    readonly mode: {
+        readonly consumed: true;
+        readonly via: "runtime-mode.ts：acpAvailableModes / acpCurrentModeId / acpModeConfigId";
+    };
+    readonly model: {
+        readonly consumed: true;
+        readonly via: "runtime-model.ts:extractModelConfigId → executor.ts:applyRequestedModel";
+    };
+    readonly thought_level: {
+        readonly consumed: true;
+        readonly via: "config-options.ts:findAcpEffortConfig → executor.ts:applyRequestedEffort";
+    };
+    readonly model_option: {
+        readonly consumed: true;
+        readonly via: "config-options.ts:findAcpEffortConfig（候选里的最高优先级，压过 thought_level）";
+    };
+    readonly model_config: {
+        readonly consumed: false;
+        readonly note: "只有宿主的 CursorProvider 消费过（context / fast / thinking 三个开关）。Cursor 2026-09-20 废弃删除，这一类现在没有消费点；没见过别家的真实载荷，先记账不猜形状。";
+    };
+};
+/** 一条表外 category 的诊断材料。 */
+export type UnhandledConfigCategory = {
+    readonly category: string;
+    /** 报出它的那个选项 id，方便直接去 CLI 那边对。 */
+    readonly optionId: string;
+    /** `_` 开头是厂商扩展，不是 ACP spec 新增。两者处置不同，所以分开标。 */
+    readonly vendorExtension: boolean;
+};
+/**
+ * 挑出这次会话里从没登记过的 category。
+ *
+ * 缺席 `category` 的选项不算漏接——协议明说它是 UX 提示、可以没有，按 id 用的那些
+ * （`findSessionConfigOption`）不依赖它。
+ */
+export declare function unhandledConfigCategories(configOptions: ReadonlyArray<AcpSessionConfigOption> | null | undefined): ReadonlyArray<UnhandledConfigCategory>;
+/** 表里登记了、但还没接到生效点的 category。界面缺一格的已知来源。 */
+export declare function declaredButUnconsumedCategories(): ReadonlyArray<string>;
+//# sourceMappingURL=config-option-wiring.d.ts.map

package/dist/config-option-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-option-wiring.d.ts","sourceRoot":"","sources":["../src/config-option-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAiBjE;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;CAyBY,CAAC;AAKtD,2BAA2B;AAC3B,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,aAAa,CAAC,sBAAsB,CAAC,GAAG,IAAI,GAAG,SAAS,GACtE,aAAa,CAAC,uBAAuB,CAAC,CAiBxC;AAED,2CAA2C;AAC3C,wBAAgB,+BAA+B,IAAI,aAAa,CAAC,MAAM,CAAC,CAIvE"}

package/dist/config-option-wiring.js

@@ -0,0 +1,71 @@
+/** 协议给厂商自定义留的前缀。这类不算「上游新增」，诊断里分开说。 */
+const VENDOR_CATEGORY_PREFIX = "_";
+/**
+ * 今天见过的几类。
+ *
+ * 加一类到这里不会自动接上任何东西——`consumed: true` 必须同时有真的接线，
+ * 配套测试钉着这一点。
+ */
+export const ACP_CONFIG_CATEGORY_HANDLING = {
+    mode: {
+        consumed: true,
+        via: "runtime-mode.ts：acpAvailableModes / acpCurrentModeId / acpModeConfigId",
+    },
+    model: {
+        consumed: true,
+        via: "runtime-model.ts:extractModelConfigId → executor.ts:applyRequestedModel",
+    },
+    thought_level: {
+        consumed: true,
+        via: "config-options.ts:findAcpEffortConfig → executor.ts:applyRequestedEffort",
+    },
+    model_option: {
+        consumed: true,
+        // 精确说法：它不是**识别器**，是**优先级**。`looksLikeEffortOption` 先筛出候选，
+        // 标了 `model_option` 的在候选里排第一（厂商自己标的最准），排在 id 叫 `effort`
+        // 的和标 `thought_level` 的前面。光有这个 category 而 id/name 不像力度档的，
+        // 压根进不了候选。
+        via: "config-options.ts:findAcpEffortConfig（候选里的最高优先级，压过 thought_level）",
+    },
+    model_config: {
+        consumed: false,
+        note: "只有宿主的 CursorProvider 消费过（context / fast / thinking 三个开关）。Cursor 2026-09-20 废弃删除，这一类现在没有消费点；没见过别家的真实载荷，先记账不猜形状。",
+    },
+};
+/** 登记在表里的 category 名单。 */
+const KNOWN_CATEGORIES = new Set(Object.keys(ACP_CONFIG_CATEGORY_HANDLING));
+/**
+ * 挑出这次会话里从没登记过的 category。
+ *
+ * 缺席 `category` 的选项不算漏接——协议明说它是 UX 提示、可以没有，按 id 用的那些
+ * （`findSessionConfigOption`）不依赖它。
+ */
+export function unhandledConfigCategories(configOptions) {
+    if (!configOptions)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const option of configOptions) {
+        const category = option.category?.trim();
+        if (!category)
+            continue;
+        if (KNOWN_CATEGORIES.has(category))
+            continue;
+        if (seen.has(category))
+            continue;
+        seen.add(category);
+        out.push({
+            category,
+            optionId: option.id.trim(),
+            vendorExtension: category.startsWith(VENDOR_CATEGORY_PREFIX),
+        });
+    }
+    return out;
+}
+/** 表里登记了、但还没接到生效点的 category。界面缺一格的已知来源。 */
+export function declaredButUnconsumedCategories() {
+    return Object.entries(ACP_CONFIG_CATEGORY_HANDLING)
+        .filter(([, handling]) => !handling.consumed)
+        .map(([category]) => category);
+}
+//# sourceMappingURL=config-option-wiring.js.map

package/dist/config-option-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-option-wiring.js","sourceRoot":"","sources":["../src/config-option-wiring.ts"],"names":[],"mappings":"AA0BA,sCAAsC;AACtC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAcnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,IAAI,EAAE;QACJ,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,wEAAwE;KAC9E;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,yEAAyE;KAC/E;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE,0EAA0E;KAChF;IACD,YAAY,EAAE;QACZ,QAAQ,EAAE,IAAI;QACd,0DAA0D;QAC1D,wDAAwD;QACxD,0DAA0D;QAC1D,WAAW;QACX,GAAG,EAAE,mEAAmE;KACzE;IACD,YAAY,EAAE;QACZ,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,gHAAgH;KACvH;CACkD,CAAC;AAEtD,0BAA0B;AAC1B,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,CAAC;AAWjG;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,aAAuE;IAEvE,IAAI,CAAC,aAAa;QAAE,OAAO,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAA8B,EAAE,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAS;QAC7C,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAS;QACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnB,GAAG,CAAC,IAAI,CAAC;YACP,QAAQ;YACR,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;YAC1B,eAAe,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,+BAA+B;IAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,4BAA4B,CAAC;SAChD,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/config-options.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 从 ACP 会话回包的 `configOptions` 里认出思考档位（力度档）。
+ *
+ * **为什么住在这个包**：认法与翻法此前有两份，互不知道——`CursorProvider` 能把
+ * configOptions 里的力度档翻成界面画得出的 optionDescriptor；`agent-dsh` 的探测建了
+ * 会话、却只从同一份回包里取模型清单。结果同一种数据在 Cursor 上有力度档，在别的
+ * ACP 手上整格缺席。插件 import 不到宿主，所以通用那半只能落在这个两边都够得着的包里。
+ *
+ * **不归一化档位值**：Cursor 那份把 `extra-high` 折成 `xhigh`、认不出的一律丢掉，那是
+ * 它对齐自身固定集合的需要，留在 `CursorProvider`。通用这份照 agent 报什么算什么——
+ * 宿主 `ProviderOptionDescriptor` 的 option id 是自由字符串，归一化只会把 agent 真能收
+ * 的档位吃掉（`claude-agent-acp` 报的 `default` 就会中招），而写回时原样发回去才自洽。
+ *
+ * 入参收 `unknown`：插件侧拿到的是 raw JSON，宿主侧拿到的是 schema 类型，两边结构相同，
+ * 在这里各自不用先转一道。
+ *
+ * @module config-options
+ */
+/** 力度档里的一个可选值。 */
+export type AcpConfigChoice = {
+    readonly value: string;
+    /**
+     * agent 给的名字，**缺席就是缺席**——模型清单那边名字没报时不设 `name`，不拿 slug
+     * 冒充（宿主拿它当「CLI 说得出的名字」）。要给人看的那一行用 {@link label}。
+     */
+    readonly name?: string;
+    /** 给人看的一行：`name` 有就是它，没有退回 `value`。力度档那一格用这个。 */
+    readonly label: string;
+    /** agent 给这一档写的说明，有就带上（dsh 每档都有）。 */
+    readonly description?: string;
+    /** agent 报的 `currentValue` 命中这一档。 */
+    readonly isDefault?: boolean;
+};
+/** 认出来的力度档。 */
+export type AcpEffortConfig = {
+    /**
+     * 报出它的那个 configOption id。写回走 `session/set_config_option` 时用的是它，
+     * 不是我们自己起的名字——各家 id 不同（`effort` / `reasoning` / 厂商自定义）。
+     */
+    readonly configId: string;
+    /** agent 自己给的标题，当界面那一格的 label；空就由调用方兜底。 */
+    readonly label: string;
+    readonly choices: ReadonlyArray<AcpConfigChoice>;
+};
+/**
+ * 挑出力度档那一项。
+ *
+ * 优先级照 `CursorProvider` 既有那套：厂商自己标的 `model_option` 最准，其次是 id 就叫
+ * `effort` 的，再次是标了 `thought_level` 的，最后退回第一个长得像的。多家同时命中时
+ * 这个顺序决定谁赢，改它会改掉 Cursor 今天的行为。
+ */
+export declare function findAcpEffortConfig(configOptions: unknown): AcpEffortConfig | undefined;
+/**
+ * 从同一份 `configOptions` 里认出模型清单那一项，展平成可选值。
+ *
+ * 认法与力度档那边共用一套展平（平的 `{value,name}` 与按组分的
+ * `{group,name,options:[…]}` 都认，`currentValue` 标成默认）。此前这段只活在
+ * `agent-dsh` 的 `dshProbeModels` 里——`agent-acp` 要报清单时照抄一份就是第二个答案，
+ * 所以搬来这里，两条路读同一份。
+ *
+ * 返回 `undefined` 与空数组不是一回事：前者是「这份回包里认不出模型那一项」，后者是
+ * 「认出来了但一个选项都没有」。调用方据此决定报不报 `models`。
+ */
+export declare function acpModelChoicesFromConfigOptions(configOptions: unknown): ReadonlyArray<AcpConfigChoice> | undefined;
+/**
+ * 另一种报法：`session/new` 回包的 `models.availableModels`（ACP 的 UNSTABLE 那一位）。
+ *
+ * 两种报法都是标准的，各家挑一种——`claude-agent-acp` 与 dsh 走 `configOptions`，也有
+ * 走这一位的。只认一种就会对另一半的手整个报不出清单，所以两种都认，由调用方按顺序试。
+ *
+ * `collectSessionModelIds` 只取 id（够 `session/set_model` 用），这里要连名字和默认一起，
+ * 所以另起一个而不是改它——那个的调用方不需要多余字段。
+ */
+export declare function acpModelChoicesFromSessionModels(models: unknown): ReadonlyArray<AcpConfigChoice> | undefined;
+//# sourceMappingURL=config-options.d.ts.map

package/dist/config-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-options.d.ts","sourceRoot":"","sources":["../src/config-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kBAAkB;AAClB,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAe;AACf,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAClD,CAAC;AAmEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CA0BvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,OAAO,GACrB,aAAa,CAAC,eAAe,CAAC,GAAG,SAAS,CAO5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,OAAO,GACd,aAAa,CAAC,eAAe,CAAC,GAAG,SAAS,CAqB5C"}