@ycodium-ai/agent-grok 0.2.2167 → 0.2.2488

package/README.md

@@ -1,7 +1,7 @@
 # @ycodium-ai/agent-grok
 
 Grok executor plugin. Spawns `grok agent stdio` over stdio and runs
-`ycodium-acp-executor` against `ycodium-acp-protocol`, with the Grok-specific
+the shared `ycodium-acp-executor` state machine, with the Grok-specific
 semantics that used to live in the host Grok adapter:
 
 - `_x.ai/ask_user_question` (and its `x.ai/ask_user_question` alias) is surfaced as
@@ -34,9 +34,19 @@ Facts:
   credential reads use the home the subprocess actually sees. An empty
   account directory means the CLI default `~/.grok` is used without injection.
 - Manifest permission is `{ kind: "executor" }`.
-- Native in-session model switching is `unsupported` on the card. The host applies
-  upstream model changes by rebinding the local endpoint and resuming the existing
-  conversation; the CLI's internal model is tracked separately.
+- Native in-session model switching is `unsupported` on the card.
+- Model connection is the instance's own: either `grok login --device-auth`, or
+  `GROK_MODELS_BASE_URL` plus `XAI_API_KEY` in the instance environment. A signed-out
+  instance still probes `ready` (auth reports `unauthenticated`) because the second
+  form needs no login.
+- Credential order warning: setting `GROK_MODELS_BASE_URL` does not switch the CLI to
+  API-key auth. Grok resolves `api_key` → `env_key` → the signed-in session token →
+  `XAI_API_KEY`, so a signed-in instance would send its x.ai session token to the custom
+  base URL. When the instance environment sets `GROK_MODELS_BASE_URL`, the plugin
+  therefore spawns the CLI with `GROK_AUTH_PATH` pointing at a fresh path that does not
+  exist (the card's `extraEnv` `$absentPath` entry), unless the instance sets
+  `GROK_AUTH_PATH` itself. The login file in the account directory is left untouched.
+  Settings also gives a new instance that sets these variables its own account directory.
 
 Develop with `vp run --filter @ycodium-ai/agent-grok typecheck`, `build`, and `test`.
 

package/dist/index.js

@@ -15,7 +15,7 @@ var GROK_CARD = {
   displayName: "Grok",
   iconUrl: "./assets/icon.svg",
   commandName: "grok",
-  // 启动命令是 `grok agent stdio`（GrokSettings 磁盘形状没有 launchArgs 字段，
+  // 启动命令是 `grok agent stdio`（磁盘上的设置形状没有 launchArgs 字段，
   // 宿主旧实现把它写死在 buildGrokAcpSpawnInput，这里落在名片上）。两个动态旗标
   // 都不走名片这一栏，而且**位置不同**：思考档位 `--reasoning-effort` 是 agent 级、
   // 插在 agent 与 stdio 之间；运行模式 `--permission-mode` 是顶层、排在 `agent`
@@ -24,7 +24,7 @@ var GROK_CARD = {
   launchArgs: "agent stdio",
   homeEnvVar: "GROK_HOME",
   // 只有这一条是实话：实测这个 CLI 从不播报 api key 认证方式，点名 XAI_API_KEY
-  // 是把用户指向死路（宿主 providerCatalog 同一条注释）。
+  // 是把用户指向死路。
   environment: [],
   install: {
     kind: "vendorScript",
@@ -48,16 +48,12 @@ var GROK_CARD = {
   defaultTextGenerationModel: "",
   customModelIdExample: "",
   modelSlugAliases: null,
-  // models.dev 只有 `xai` 一家发 Grok。
-  modelsDevProviderIds: ["xai"],
-  modelsDevSlugPrefixed: false,
-  modelSlugPrefix: "",
   mcpTransports: ["stdio", "http", "sse"],
   pluginManaged: true,
   verifiedSkills: false,
   everydayHarness: false,
   capabilities: {
-    // 插件不承诺原生会话内活切型号；宿主更换上游模型时重绑端点并续接原生会话。
+    // 插件不承诺原生会话内活切型号。
     sessionModelSwitch: "unsupported",
     // 运行模式只在 spawn 时定得了（`--permission-mode` 是启动旗标，ACP 那一侧
     // `modes: null`，`session/set_mode` 对它无效），所以不许声称能会话中途换。
@@ -79,11 +75,29 @@ var GROK_CARD = {
     }
   ],
   diagnostics: [],
+  // 设置表单照这份画：带 x-ycodium-form 的属性才进表单（enabled、customModels 等另有入口，不在此列），
+  // 顺序看 x-ycodium-form-order；文案键在本插件 locales/<locale>.json 里解析，宿主不兜底。
   configSchema: {
     type: "object",
+    "x-ycodium-form-order": ["binaryPath", "homePath"],
     properties: {
-      binaryPath: { type: "string" },
-      homePath: { type: "string" },
+      binaryPath: {
+        type: "string",
+        "x-ycodium-form": {
+          titleKey: "form.binaryPath.title",
+          descriptionKey: "form.binaryPath.description",
+          placeholderKey: "form.binaryPath.placeholder",
+          control: "executable-path"
+        }
+      },
+      homePath: {
+        type: "string",
+        "x-ycodium-form": {
+          titleKey: "form.homePath.title",
+          descriptionKey: "form.homePath.description",
+          placeholderKey: "form.homePath.placeholder"
+        }
+      },
       enabled: { type: "boolean" },
       customModels: { type: "array" },
       driver: { type: "string" },
@@ -93,41 +107,39 @@ var GROK_CARD = {
     additionalProperties: true
   },
   modelConnectivity: {
-    // 报绑定的默认入口方言：后缀是 `/chat/completions`，绑定也不替它改 `api_backend`，
-    // 所以主请求打本机端点说 chat。CLI 换了配置能说 messages / responses 不算——报三种时
-    // 兼容判定照着挑了「直通」，起手才发现后缀对不上，接 Anthropic 格式的脑与 Responses
-    // 格式的订阅全起不来。别家的脑经宿主翻译接上。它另有一笔标题请求走 `/v1/responses`，
-    // 本机端点按那一笔的路径另挑翻译对，不靠这一栏。
+    // 只报 `GROK_MODELS_BASE_URL` 下主请求说的那一种：后缀是 `/chat/completions`。CLI 换了
+    // 配置（`api_backend`）能说 messages / responses 不算。它另有一笔标题请求走
+    // `/v1/responses`，接外部服务时那个地址也得答得上。
     dialects: ["openai-chat-completions"],
     acceptsExternalEndpoints: true,
-    // 地址那一栏必须投：不设 `GROK_MODELS_BASE_URL` 的话整条请求根本不来我们这儿
-    // （`grokModelProxyEgress.test.ts` 拿掉这一栏就红）。
+    // 实例上设 `GROK_MODELS_BASE_URL` 加 `XAI_API_KEY`，CLI 就改连那个服务，不必登录。
     //
     // **但设了 base 并不会把客户端切成 API-key 认证。** 它的凭据顺序是
     // `api_key` → `env_key` → **已登录的 session token** → `XAI_API_KEY`
     // (`~/.grok/docs/user-guide/11-custom-models.md` 的 "Credential Resolution")。
     // 1.0.34 实测：账号目录里有 `auth.json` 时，启动预取 `/v1/models` 用的是
-    // `XAI_API_KEY`，而**推理请求带的是用户自己的 x.ai OIDC token**——本地端点只认
-    // 这笔绑定的凭据，别的一律 401。所以绑定时还要把 `GROK_AUTH_PATH` 指到一个不存在
-    // 的路径（见下面那栏），让这次进程读不到那份登录。同批的实测落在
-    // `grokModelProxyEgress.test.ts`。
+    // `XAI_API_KEY`，而**推理请求带的是用户自己的 x.ai OIDC token**——登录过的实例会把
+    // x.ai 会话 token 发给那个自定义地址。所以设置页给设了这些变量的新实例单独的账号
+    // 目录，插件对设了 `GROK_MODELS_BASE_URL` 的实例另把 `GROK_AUTH_PATH` 指到不存在的
+    // 路径（见下面那栏）。
     //
     // 它启动时先打 `{base_url}/models` 拉模型列表(README:1953「on startup」),不给就
-    // 当端点不可用——代理为此支持了 /models。
+    // 当端点不可用——接的服务得答 /models。
     //
     // base 含 /v1(它的例子是 `https://api.acme.com/v1`),后面自己加 /chat/completions。
     nativePathSuffix: "/chat/completions",
     baseUrlEnvKey: "GROK_MODELS_BASE_URL",
     credentialEnvKey: "XAI_API_KEY",
-    // 绑定这一轮不准用它自己的登录：凭据顺序里 session token 排在 `XAI_API_KEY`
-    // 前面，账号目录里有 `auth.json` 就一定发那一份，本机端点一律 401。
-    // `GROK_AUTH_PATH` 是 CLI 读登录文件的路径（1.0.34 的 argv 里与 `GROK_AUTH`、
-    // `GROK_DEPLOYMENT_KEY` 并列在同一张敏感变量表上）。`$absentPath` 是宿主按这次
-    // 绑定算的、必定不存在的路径——不用空设备是因为那是平台语义（POSIX `/dev/null`
-    // 对 Windows `NUL`），而「读不到」两边只有一种行为。1.0.34 实测：`authMethods`
-    // 少掉 `cached_token`、两笔请求（推理与标题）都改带绑定凭据，账号目录里那份
-    // `auth.json` 一个字节没动，也没在别处新建文件。
-    // 只在绑定时注入，非绑定会话照旧用用户自己的登录。
+    // 接外部服务时不能用它自己的登录：凭据顺序里 session token 排在 `XAI_API_KEY`
+    // 前面，账号目录里有 `auth.json` 就一定发那一份。`GROK_AUTH_PATH` 是 CLI 读登录文件
+    // 的路径（1.0.34 的 argv 里与 `GROK_AUTH`、`GROK_DEPLOYMENT_KEY` 并列在同一张敏感
+    // 变量表上）；指到一个必定不存在的路径，这次进程就读不到那份登录。不用空设备是因为
+    // 那是平台语义（POSIX `/dev/null` 对 Windows `NUL`），而「读不到」两边只有一种行为。
+    // 1.0.34 实测：`authMethods` 少掉 `cached_token`、两笔请求（推理与标题）都改带
+    // `XAI_API_KEY`，账号目录里那份 `auth.json` 一个字节没动，也没在别处新建文件。
+    // 宿主不注入它。插件在实例环境表设了 `GROK_MODELS_BASE_URL`、又没自己写
+    // `GROK_AUTH_PATH` 时替换 `$absentPath` 并填上（`grokInstance.ts` 的
+    // `ownEndpointAuthGuard`）；没换地址的实例照旧用用户自己的登录。
     extraEnv: [{ name: "GROK_AUTH_PATH", value: "$absentPath" }]
   }
 };
@@ -136,7 +148,7 @@ var GROK_CARD = {
 import * as NodeCrypto2 from "node:crypto";
 import * as NodeOS from "node:os";
 import * as NodePath2 from "node:path";
-import { mergeLaunchEnv, brainSlotEnvKeys } from "@ycodium-ai/plugin-api/executor";
+import { mergeLaunchEnv } from "@ycodium-ai/plugin-api/executor";
 import { nodeStreamsFromHandle as nodeStreamsFromHandle2 } from "@ycodium-ai/plugin-api/process-stdin";
 
 // ../../packages/ycodium-acp-executor/src/executor.ts
@@ -23527,10 +23539,44 @@ var legacyClientNotificationMethods = /* @__PURE__ */ new Set([
   CLIENT_METHODS.elicitation_complete
 ]);
 
-// ../../packages/ycodium-acp-protocol/src/connection.ts
+// ../../packages/ycodium-acp-executor/src/connection.ts
 import * as NodeStream from "node:stream";
 
-// ../../packages/ycodium-acp-protocol/src/errors.ts
+// ../../packages/ycodium-acp-executor/src/errors.ts
+var AcpExecutorError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "AcpExecutorError";
+    this.code = code;
+  }
+};
+var AcpExecutorDisposedError = class extends AcpExecutorError {
+  constructor(message = "ACP executor has been disposed") {
+    super("disposed", message);
+    this.name = "AcpExecutorDisposedError";
+  }
+};
+var AcpExecutorNotStartedError = class extends AcpExecutorError {
+  constructor(message = "ACP session has not been started") {
+    super("not-started", message);
+    this.name = "AcpExecutorNotStartedError";
+  }
+};
+var AcpExecutorCancelTimeoutError = class extends AcpExecutorError {
+  constructor(message = "Timed out waiting for session/prompt to finish after cancellation") {
+    super("cancel-timeout", message);
+    this.name = "AcpExecutorCancelTimeoutError";
+  }
+};
+var AcpExecutorRequestError = class extends AcpExecutorError {
+  method;
+  constructor(method, message) {
+    super("request-failed", message);
+    this.name = "AcpExecutorRequestError";
+    this.method = method;
+  }
+};
 var AcpConnectionClosedError = class extends Error {
   constructor(message = "ACP connection closed") {
     super(message);
@@ -23538,7 +23584,7 @@ var AcpConnectionClosedError = class extends Error {
   }
 };
 
-// ../../packages/ycodium-acp-protocol/src/jsonrpc.ts
+// ../../packages/ycodium-acp-executor/src/jsonrpc.ts
 function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
@@ -23576,7 +23622,7 @@ function readJsonRpcError(value) {
   };
 }
 
-// ../../packages/ycodium-acp-protocol/src/line-buffer.ts
+// ../../packages/ycodium-acp-executor/src/line-buffer.ts
 var newline2 = 10;
 var LineBuffer2 = class {
   #pending = [];
@@ -23620,7 +23666,7 @@ var LineBuffer2 = class {
   }
 };
 
-// ../../packages/ycodium-acp-protocol/src/session-update.ts
+// ../../packages/ycodium-acp-executor/src/session-update.ts
 var KNOWN_SESSION_UPDATES = /* @__PURE__ */ new Set([
   "user_message_chunk",
   "agent_message_chunk",
@@ -23665,7 +23711,7 @@ function decodeSessionUpdate(payload) {
   return { status: "raw", params: payload };
 }
 
-// ../../packages/ycodium-acp-protocol/src/connection.ts
+// ../../packages/ycodium-acp-executor/src/connection.ts
 var textDecoder = new TextDecoder();
 var textEncoder = new TextEncoder();
 function asBytes(chunk) {
@@ -24190,42 +24236,6 @@ var UnboundedEventStream = class {
   }
 };
 
-// ../../packages/ycodium-acp-executor/src/errors.ts
-var AcpExecutorError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "AcpExecutorError";
-    this.code = code;
-  }
-};
-var AcpExecutorDisposedError = class extends AcpExecutorError {
-  constructor(message = "ACP executor has been disposed") {
-    super("disposed", message);
-    this.name = "AcpExecutorDisposedError";
-  }
-};
-var AcpExecutorNotStartedError = class extends AcpExecutorError {
-  constructor(message = "ACP session has not been started") {
-    super("not-started", message);
-    this.name = "AcpExecutorNotStartedError";
-  }
-};
-var AcpExecutorCancelTimeoutError = class extends AcpExecutorError {
-  constructor(message = "Timed out waiting for session/prompt to finish after cancellation") {
-    super("cancel-timeout", message);
-    this.name = "AcpExecutorCancelTimeoutError";
-  }
-};
-var AcpExecutorRequestError = class extends AcpExecutorError {
-  method;
-  constructor(method, message) {
-    super("request-failed", message);
-    this.name = "AcpExecutorRequestError";
-    this.method = method;
-  }
-};
-
 // ../../packages/ycodium-acp-executor/src/events.ts
 function canonicalRequestTypeFromAcpKind(kind) {
   switch (kind) {
@@ -27075,6 +27085,17 @@ function resolveGrokHomePath(value) {
   if (trimmed2.length === 0) return NodePath2.join(NodeOS.homedir(), ".grok");
   return NodePath2.resolve(expandHomePath(trimmed2));
 }
+function probeGrokAccount(accountPath) {
+  const resolved = resolveGrokHomePath(accountPath);
+  const account = readGrokAccount(resolved);
+  return {
+    accountPath: resolved,
+    state: account.state,
+    ...account.email === void 0 ? {} : { email: account.email },
+    ...account.name === void 0 ? {} : { name: account.name },
+    ...account.expiresAt === void 0 ? {} : { expiresAt: account.expiresAt }
+  };
+}
 function grokContinuationKey(recipe) {
   return `grok:home:${resolveGrokHomePath(recipe.homePath)}`;
 }
@@ -27085,14 +27106,38 @@ function resolveAccountHomePath(recipe, configuredHome) {
   }
   return resolveGrokHomePath(configuredHome);
 }
-function buildSpawnEnv(recipe, resolvedHomePath, homeConfigured, launchEnv = {}) {
-  const homeInjection = homeConfigured ? { [GROK_CARD.homeEnvVar]: resolvedHomePath } : {};
+function absentPath() {
+  return NodePath2.join(
+    NodeOS.tmpdir(),
+    `ycodium-grok-no-auth-${NodeCrypto2.randomUUID()}`,
+    "auth.json"
+  );
+}
+function ownEndpointAuthGuard(recipe) {
+  const connectivity = GROK_CARD.modelConnectivity;
+  const baseUrlKey = connectivity.baseUrlEnvKey;
+  if (baseUrlKey === void 0 || (recipe.environment[baseUrlKey]?.trim() ?? "") === "") return {};
+  const guard = {};
+  for (const entry of connectivity.extraEnv ?? []) {
+    if (entry.value === "$absentPath") guard[entry.name] = absentPath();
+  }
+  return guard;
+}
+function buildSignInEnv(recipe) {
+  const configuredHome = recipe.homePath;
+  const homeInjection = configuredHome.trim().length > 0 ? { [GROK_CARD.homeEnvVar]: resolveGrokHomePath(configuredHome) } : {};
   return mergeLaunchEnv({
-    brainSlots: brainSlotEnvKeys(GROK_CARD),
     accountHome: homeInjection,
     instanceTable: recipe.environment,
-    handOverrides: { GROK_OAUTH2_REFERRER: "ycodium" },
-    launch: launchEnv
+    handOverrides: { GROK_OAUTH2_REFERRER: "ycodium" }
+  });
+}
+function buildSpawnEnv(recipe, resolvedHomePath, homeConfigured) {
+  const homeInjection = homeConfigured ? { [GROK_CARD.homeEnvVar]: resolvedHomePath } : {};
+  return mergeLaunchEnv({
+    accountHome: { ...homeInjection, ...ownEndpointAuthGuard(recipe) },
+    instanceTable: recipe.environment,
+    handOverrides: { GROK_OAUTH2_REFERRER: "ycodium" }
   });
 }
 function nowIso() {
@@ -27122,6 +27167,9 @@ var createGrokInstance = (config2, host) => {
     return booked;
   };
   const probeAuth = () => {
+    if ((recipe.environment["XAI_API_KEY"] ?? "").trim().length > 0) {
+      return { status: "authenticated", type: "api-key", label: "XAI_API_KEY" };
+    }
     const account = readGrokAccount(resolveAccountHomePath(recipe, recipe.homePath));
     switch (account.state) {
       case "signed-in":
@@ -27193,13 +27241,11 @@ var createGrokInstance = (config2, host) => {
         await stopBooked(existing);
         threads.delete(input2.threadId);
       }
-      const configuredHome = input2.launch.homePath?.trim() || recipe.homePath;
-      const resolvedHomePath = resolveGrokHomePath(configuredHome);
+      const configuredHome = recipe.homePath;
       const env = buildSpawnEnv(
         recipe,
-        resolvedHomePath,
-        configuredHome.length > 0,
-        input2.launch.processEnv
+        resolveGrokHomePath(configuredHome),
+        configuredHome.trim().length > 0
       );
       const effort = modelSelectionStringOption(input2.modelSelection, GROK_REASONING_OPTION_ID);
       const baseArgs = tokenizeLaunchArgs(recipe.launchArgs);
@@ -27220,7 +27266,7 @@ var createGrokInstance = (config2, host) => {
       });
       const { readable, writable } = nodeStreamsFromHandle2(handle);
       const resume = input2.discardResumeCursor === true ? void 0 : parseAcpResumeCursor(input2.resumeCursor, RESUME_SCHEMA_VERSION);
-      const requestedModelId = input2.launch.requestedModelId?.trim() || modelIdFromSelection(input2.modelSelection);
+      const requestedModelId = modelIdFromSelection(input2.modelSelection);
       let initializeResult;
       const executor = createAcpExecutor({
         readable,
@@ -27430,10 +27476,12 @@ var createGrokInstance = (config2, host) => {
         if (recipe.binaryPath.length === 0) {
           throw new Error("Grok program path is not configured");
         }
+        const env = buildSignInEnv(recipe);
         const handle = await host.process.spawn({
           program: recipe.binaryPath,
           args: [...GROK_CARD.deviceCodeSignInArgs],
-          owner: { bindingId: host.bindingId }
+          owner: { bindingId: host.bindingId },
+          ...Object.keys(env).length > 0 ? { env } : {}
         });
         const collected = [];
         let onCodeFound;
@@ -27496,7 +27544,8 @@ var executors = [
     createInstance: async (config2, host) => {
       host.log.info("createInstance");
       return createGrokInstance(config2, host);
-    }
+    },
+    probeAccount: async ({ accountPath }) => probeGrokAccount(accountPath)
   }
 ];
 var index_default = definePlugin({

package/locales/en.json

@@ -0,0 +1,14 @@
+{
+  "form": {
+    "binaryPath": {
+      "title": "Program path",
+      "description": "Path to the Grok program this provider runs.",
+      "placeholder": "grok"
+    },
+    "homePath": {
+      "title": "Account directory",
+      "description": "Sessions and the `grok login` credentials live here, so providers sharing this directory can pick up each other's threads and providers with different directories cannot. Leave empty to use the CLI's default (~/.grok).",
+      "placeholder": "e.g. ~/.grok-work"
+    }
+  }
+}

package/locales/zh-CN.json

@@ -0,0 +1,14 @@
+{
+  "form": {
+    "binaryPath": {
+      "title": "程序路径",
+      "description": "此 provider 运行的 Grok 程序的路径。",
+      "placeholder": "grok"
+    },
+    "homePath": {
+      "title": "账户目录",
+      "description": "会话和 `grok login` 的凭据都保存在这里，因此共用同一目录的 provider 可以接手彼此的会话，目录不同的则不能。留空则使用该命令行工具的默认目录（~/.grok）。",
+      "placeholder": "例如 ~/.grok-work"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/agent-grok",
-  "version": "0.2.2167",
+  "version": "0.2.2488",
   "description": "Grok executor: grok CLI over Agent Client Protocol stdio.",
   "keywords": [
     "ycodium",
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "assets",
+    "locales",
     "README.md"
   ],
   "type": "module",
@@ -20,10 +21,9 @@
     "@types/node": "24.12.4",
     "esbuild": "0.28.1",
     "vite-plus": "0.2.2",
-    "@ycodium-ai/plugin-api": "0.2.2167",
-    "ycodium-executor-testing": "0.0.0",
-    "ycodium-acp-executor": "0.0.0",
-    "ycodium-acp-protocol": "0.0.0"
+    "@ycodium-ai/plugin-api": "0.2.2488",
+    "ycodium-acp-executor": "0.2.2488",
+    "ycodium-executor-testing": "0.0.0"
   },
   "ycodium": {
     "plugin": "./dist/index.js",