ycodium-acp-executor 0.2.2488

package/dist/vendor-hooks.d.ts

@@ -0,0 +1,112 @@
+import type { AcpRequestPermissionParams } from "./types.ts";
+/**
+ * 厂商差异的钩子。各 `@ycodium-ai/agent-*` 手用这些钩子表达与通用机的差异，
+ * 不得各自再写分帧或会话状态机。
+ */
+export type AcpVendorHooks = {
+    readonly completedStopReason?: (response: {
+        readonly stopReason: string;
+    }) => string | null;
+    /**
+     * 把 `session/request_permission` 识别成结构化用户输入。返回问题则走
+     * `user-input.*` 而不是审批卡。抛错 = 这次交互不符合该厂商的协议形状，
+     * 通用机回 JSON-RPC 错误，绝不能降格成批准/拒绝两档。
+     */
+    readonly permissionUserInput?: (request: AcpRequestPermissionParams) => AcpUserInputQuestion | undefined;
+    /**
+     * 厂商私有的 agent→client 请求。`ctx.askUserInput` 是唯一能把问题送到用户面前
+     * 并等回答的出口——钩子自己造等待表的话，CLI 崩溃时通用机的清理漏得掉它。
+     */
+    readonly onExtensionRequest?: (method: string, params: unknown, ctx: AcpExtensionContext) => unknown | Promise<unknown>;
+    readonly onExtensionNotification?: (method: string, params: unknown) => void | Promise<void>;
+    /**
+     * 一轮 prompt 应答落地后读这家 CLI 写在别处的上下文占用（ACP 的
+     * `usage_update` 至今没有 agent 真发）。返回 undefined = 读不出来，
+     * 通用机不发 `thread.token-usage.updated`，界面照旧不画圈。
+     */
+    readonly readContextWindow?: (input: {
+        readonly sessionId: string;
+        readonly promptResponse: {
+            readonly stopReason: string;
+            readonly usage?: unknown;
+        };
+    }) => AcpContextWindowReading | undefined | Promise<AcpContextWindowReading | undefined>;
+    /** 这一轮可能被 RPC 应答之外的信号收口（Grok）。留空 = 只等应答。 */
+    readonly promptSettlement?: AcpPromptSettlementHooks;
+    readonly resolveRequestedModelId?: (model: string | null | undefined) => string | undefined;
+    readonly resolveDisplayModelId?: (modelId: string) => string;
+};
+/**
+ * 交给厂商扩展钩子的上下文。刻意只有一项：其余的（事件流、等待表、生成号）都是
+ * 通用机的内务，暴露出去就等于把生命周期防线的口子交给各家自己守。
+ */
+export type AcpExtensionContext = {
+    /**
+     * 把一组问题送到用户面前并等回答。返回 `cancelled` 的情形有三种：用户取消、
+     * 轮次被打断、CLI 崩溃——钩子按同一条路收尾即可，不必区分。
+     */
+    readonly askUserInput: (questions: ReadonlyArray<AcpUserInputQuestion>) => Promise<AcpUserInputResolution>;
+};
+export type AcpUserInputResolution = {
+    readonly kind: "answered";
+    readonly answers: Record<string, unknown>;
+} | {
+    readonly kind: "cancelled";
+};
+/**
+ * 这一轮除了 `session/prompt` 应答之外的收口渠道。
+ *
+ * Grok 1.0.24 起：发完私有通知 `_x.ai/session/prompt_complete` 就**不再回**那条 RPC
+ * 应答（`acp-mock-agent.ts` 用 `Effect.never` 建模，测试名 "when the prompt RPC hangs"）。
+ * 只等应答的话这一轮永远不收口。
+ *
+ * 钩子只做**纯数据翻译**：注入关联 id、认出应答里的 id、把通知翻成结局。配对、去重、
+ * 与 RPC 竞速、取消、放弃输掉的那一方——全是通用机的内务，交出去各家会各写一遍。
+ */
+export type AcpPromptSettlementHooks = {
+    /**
+     * 往 `session/prompt` 的请求体上添几个字段，把 `promptKey` 带给 agent，通知才好认回来。
+     * 返回的对象浅合进请求体顶层。
+     */
+    readonly requestFields: (promptKey: string) => Record<string, unknown>;
+    /** 正常 RPC 应答里的关联 id；认不出返回 undefined（那就按「这一轮」算）。 */
+    readonly responseKey?: (response: unknown) => string | undefined;
+    /**
+     * 把一条通知翻成这一轮的结局。不是收口信号就返回 undefined。
+     *
+     * `promptKey` 可以缺（Grok 的 `promptId` 是可选字段）：缺了就按 `sessionId` 配当前这一轮。
+     * `outcome` 为 `"error"` 时通用机走失败通道——**绝不能归成正常结束**：Grok 额度耗尽
+     * 正是发 `stopReason: "error"`，归成成功的话用户看到的是一条空白回复（`cba38ce0d`）。
+     */
+    readonly fromNotification: (method: string, params: unknown) => {
+        readonly sessionId: string;
+        readonly promptKey?: string;
+        readonly outcome: "completed" | "error";
+        readonly stopReason?: string;
+        readonly detail?: string;
+    } | undefined;
+};
+export type AcpContextWindowReading = {
+    readonly usedTokens: number;
+    readonly maxTokens?: number;
+};
+/**
+ * `user-input.requested` payload 里的问题形状。与 `@ycodium/contracts`
+ * `UserInputQuestion` 同构；本包不得 import 它，在这里自述，靠 CI 比对防分叉。
+ */
+export type AcpUserInputQuestionOption = {
+    readonly id?: string;
+    readonly label: string;
+    readonly description: string;
+};
+export type AcpUserInputQuestion = {
+    readonly id: string;
+    readonly header: string;
+    readonly question: string;
+    readonly options: ReadonlyArray<AcpUserInputQuestionOption>;
+    readonly allowFreeform?: boolean;
+    readonly kind?: "question" | "plan";
+    readonly multiSelect?: boolean;
+};
+export declare const defaultVendorHooks: AcpVendorHooks;
+//# sourceMappingURL=vendor-hooks.d.ts.map

package/dist/vendor-hooks.d.ts.map

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

package/dist/vendor-hooks.js

@@ -0,0 +1,4 @@
+export const defaultVendorHooks = {
+    completedStopReason: (response) => response.stopReason,
+};
+//# sourceMappingURL=vendor-hooks.js.map

package/dist/vendor-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendor-hooks.js","sourceRoot":"","sources":["../src/vendor-hooks.ts"],"names":[],"mappings":"AA2HA,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,mBAAmB,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU;CACvD,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ycodium-acp-executor",
+  "version": "0.2.2488",
+  "description": "Agent Client Protocol client and executor state machine for Ycodium agent plugins. Speaks ACP over stdio and emits Ycodium executor events.",
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "ycodium"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "typescript": "~6.0.3",
+    "vite-plus": "0.2.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsgo --noEmit",
+    "test": "vp test run"
+  }
+}