@gobing-ai/ts-ai-runner 0.4.7 → 0.4.8

package/README.md

@@ -32,7 +32,7 @@ bun add @gobing-ai/ts-ai-runner
 | `AGENT_SHIMS` / `TIER1_PRIORITY` / `TIER2_AGENTS` / `DISPLAY_ORDER` | Agent registry constants |
 | `isAgentName()` | Type guard for supported agent identifiers |
 
-Supported agent identifiers: `claude`, `codex`, `gemini` (deprecated), `pi`, `omp`, `opencode`, `antigravity-cli`, `openclaw`, `hermes`. The `antigravity` id is a deprecated alias of `antigravity-cli`. See [Deprecation & Aliases](#deprecation--aliases).
+Supported agent identifiers: `claude`, `codex`, `gemini` (deprecated), `pi`, `omp`, `opencode`, `antigravity-cli`, `openclaw`, `hermes`, `grok`. The `antigravity` id is a deprecated alias of `antigravity-cli`. See [Deprecation & Aliases](#deprecation--aliases).
 
 ## Architecture
 
@@ -433,6 +433,9 @@ Agent-specific behavior:
 | `opencode` | `opencode` | 1 | `opencode providers` | `run`, `-c`, `-m`, `--format json` |
 | `antigravity-cli` | `agy` | 1 | env-only | `-p`, `--continue`, `--model` |
 | `openclaw` | `openclaw` | 2 | `openclaw health` | `agent --local -m` |
+| `hermes` | `hermes` | 1 | `hermes doctor` | `chat -q`, `--continue`, `-m` |
+| `grok` | `grok` | 1 | env/file (`XAI_API_KEY` or `~/.grok/auth.json`) | `-p`, `-c` (resume), `-m`, `--output-format plain\|json` (maps ai-runner `text` → `plain`) |
+
 This is the right layer for UI previews, audit logging, and custom launchers.
 
 ## Deprecation & Aliases
@@ -458,6 +461,7 @@ resolveAgentName('cursor');          // → undefined
 | `gemini` | deprecated | `gemini` (self) → replaced by `antigravity-cli` | Gemini CLI sunset 2026-06-18. Shim stays functional. |
 | `omp` | canonical | `omp` | First-class; NOT a pi alias. |
 | `hermes` | canonical | `hermes` | First-class; OpenClaw-compatible but distinct binary. |
+| `grok` | canonical | `grok` | Grok Build CLI; headless via `-p`; auth is env/file only (no status verb). |
 
 `getAgentShim()` and `isAgentName()` are alias-aware: passing `'antigravity'` resolves to the `antigravity-cli` shim. `DoctorResult` and `DetectedAgent` surface `deprecated` + `replacedBy` when the resolved canonical id is marked deprecated.
 

package/dist/agents/auth-shims.d.ts

@@ -37,6 +37,8 @@ export interface AuthContext {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.

package/dist/agents/auth-shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-shims.d.ts","sourceRoot":"","sources":["../../src/agents/auth-shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAmC,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAExE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IACxB,0CAA0C;IAC1C,MAAM,EAAE,QAAQ,CAAC;IACjB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0EAA0E;IAC1E,UAAU,EAAE,UAAU,CAAC;IACvB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB5F;AA8CD,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"auth-shims.d.ts","sourceRoot":"","sources":["../../src/agents/auth-shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAmC,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAExE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IACxB,0CAA0C;IAC1C,MAAM,EAAE,QAAQ,CAAC;IACjB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0EAA0E;IAC1E,UAAU,EAAE,UAAU,CAAC;IACvB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAiB5F;AA+DD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/agents/auth-shims.js

@@ -49,6 +49,8 @@ function isNonEmpty(value) {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.
@@ -63,6 +65,8 @@ export async function isAuthenticated(agent, ctx) {
         return geminiSettingsContainCredentials(fs, home);
     if (agent === 'codex')
         return checkCodexAuth(ctx.runner, fs, home, timeout);
+    if (agent === 'grok')
+        return checkGrokAuth(fs, home, env);
     // pi and omp read provider keys from the environment; require a non-empty
     // value rather than mere presence (an empty export is not a usable credential).
     if ((agent === 'pi' || agent === 'omp') && (isNonEmpty(env.GOOGLE_API_KEY) || isNonEmpty(env.ANTHROPIC_API_KEY))) {
@@ -78,6 +82,20 @@ async function checkCodexAuth(runner, fs, home, timeout) {
         (await hasNonEmptyFile(fs, joinPath(home, '.codex', 'auth')));
     return hasFile ? 'authenticated' : 'unknown';
 }
+/**
+ * Grok has no auth-status CLI verb. Credential sources (never false-negative
+ * to `unauthenticated` when missing):
+ * 1. non-empty `XAI_API_KEY`
+ * 2. non-empty `~/.grok/auth.json`
+ * Else `unknown`.
+ */
+async function checkGrokAuth(fs, home, env) {
+    if (isNonEmpty(env.XAI_API_KEY))
+        return 'authenticated';
+    if (await hasNonEmptyFile(fs, joinPath(home, '.grok', 'auth.json')))
+        return 'authenticated';
+    return 'unknown';
+}
 async function geminiSettingsContainCredentials(fs, home) {
     try {
         const content = await fs.readFile(joinPath(home, '.gemini', 'settings.json'));

package/dist/agents/shims.d.ts

@@ -1,5 +1,5 @@
 /** Identifier for one supported coding agent (canonical id). */
-export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity-cli' | 'openclaw' | 'hermes' | 'omp';
+export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity-cli' | 'openclaw' | 'hermes' | 'omp' | 'grok';
 /** Output mode for prompt invocations. */
 export type OutputMode = 'text' | 'json';
 /** Concrete executable and argv pair returned by an agent shim. */

package/dist/agents/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACf,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,KAAK,CAAC;AAEZ,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AA+JD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAU9D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAQ9C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAU7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAyB,CAAC;AAU1E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAQrE;AAED;mEACmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAMxD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACf,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,KAAK,GACL,MAAM,CAAC;AAEb,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AAuLD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAW9D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAS9C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAW7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAyB,CAAC;AAU1E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAQrE;AAED;mEACmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAMxD"}

package/dist/agents/shims.js

@@ -166,6 +166,31 @@ const ompShim = {
     },
     getAuthCommand: () => ({ command: 'omp', args: ['--list-models'] }),
 };
+/**
+ * Grok Build CLI (`grok`) — xAI coding agent. Headless one-shot via `-p`/`--single`;
+ * continue with `-c`; model via `-m`. Output formats are `plain`/`json`/`streaming-json`
+ * (map ai-runner `text` → `plain`). No auth-status verb — `getAuthCommand` is null;
+ * credential probing lives in auth-shims (env / `~/.grok/auth.json`).
+ */
+const grokShim = {
+    name: 'grok',
+    command: 'grok',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'grok', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true)
+            args.push('-c');
+        if (options.model !== undefined)
+            args.push('-m', options.model);
+        // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
+        const format = (options.mode ?? 'text') === 'json' ? 'json' : 'plain';
+        args.push('--output-format', format);
+        return { command: 'grok', args };
+    },
+    getAuthCommand: () => null,
+};
 /** All bundled agent shims keyed by canonical agent name. */
 export const AGENT_SHIMS = {
     claude: claudeShim,
@@ -177,6 +202,7 @@ export const AGENT_SHIMS = {
     openclaw: openclawShim,
     hermes: hermesShim,
     omp: ompShim,
+    grok: grokShim,
 };
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
 export const TIER1_PRIORITY = [
@@ -187,6 +213,7 @@ export const TIER1_PRIORITY = [
     'claude',
     'hermes',
     'opencode',
+    'grok',
 ];
 /** Display order for doctor and list commands. */
 export const DISPLAY_ORDER = [
@@ -199,6 +226,7 @@ export const DISPLAY_ORDER = [
     'antigravity-cli',
     'openclaw',
     'hermes',
+    'grok',
 ];
 /** Set of gateway/TUI-constrained agents. */
 export const TIER2_AGENTS = new Set(['openclaw']);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.4.7",
+    "version": "0.4.8",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,9 +47,9 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.4.7",
-        "@gobing-ai/ts-infra": "^0.4.7",
-        "@gobing-ai/ts-runtime": "^0.4.7"
+        "@gobing-ai/ts-db": "^0.4.8",
+        "@gobing-ai/ts-infra": "^0.4.8",
+        "@gobing-ai/ts-runtime": "^0.4.8"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/src/agents/auth-shims.ts

@@ -83,6 +83,8 @@ function isNonEmpty(value: string | undefined): boolean {
  * - **gemini** — credential-like content in `~/.gemini/settings.json`.
  * - **codex** — `codex login status` CLI output, falling back to an
  *   `~/.codex/auth{.json,}` credential file.
+ * - **grok** — non-empty `XAI_API_KEY` env, else non-empty `~/.grok/auth.json`;
+ *   no CLI auth-status verb (shim `getAuthCommand` is null).
  * - **pi / omp** — a non-empty `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` in env
  *   (an empty export is not a usable credential), else the CLI auth probe.
  * - **others** — the shim's auth command; matched against {@link AUTH_PATTERNS}.
@@ -96,6 +98,7 @@ export async function isAuthenticated(agent: AgentName, ctx: AuthContext): Promi
 
     if (agent === 'gemini') return geminiSettingsContainCredentials(fs, home);
     if (agent === 'codex') return checkCodexAuth(ctx.runner, fs, home, timeout);
+    if (agent === 'grok') return checkGrokAuth(fs, home, env);
 
     // pi and omp read provider keys from the environment; require a non-empty
     // value rather than mere presence (an empty export is not a usable credential).
@@ -115,6 +118,23 @@ async function checkCodexAuth(runner: AiRunner, fs: FileSystem, home: string, ti
     return hasFile ? 'authenticated' : 'unknown';
 }
 
+/**
+ * Grok has no auth-status CLI verb. Credential sources (never false-negative
+ * to `unauthenticated` when missing):
+ * 1. non-empty `XAI_API_KEY`
+ * 2. non-empty `~/.grok/auth.json`
+ * Else `unknown`.
+ */
+async function checkGrokAuth(
+    fs: FileSystem,
+    home: string,
+    env: Record<string, string | undefined>,
+): Promise<AuthState> {
+    if (isNonEmpty(env.XAI_API_KEY)) return 'authenticated';
+    if (await hasNonEmptyFile(fs, joinPath(home, '.grok', 'auth.json'))) return 'authenticated';
+    return 'unknown';
+}
+
 async function geminiSettingsContainCredentials(fs: FileSystem, home: string): Promise<AuthState> {
     try {
         const content = await fs.readFile(joinPath(home, '.gemini', 'settings.json'));

package/src/agents/shims.ts

@@ -10,7 +10,8 @@ export type AgentName =
     | 'antigravity-cli'
     | 'openclaw'
     | 'hermes'
-    | 'omp';
+    | 'omp'
+    | 'grok';
 
 /** Output mode for prompt invocations. */
 export type OutputMode = 'text' | 'json';
@@ -232,6 +233,30 @@ const ompShim: AgentShim = {
     getAuthCommand: () => ({ command: 'omp', args: ['--list-models'] }),
 };
 
+/**
+ * Grok Build CLI (`grok`) — xAI coding agent. Headless one-shot via `-p`/`--single`;
+ * continue with `-c`; model via `-m`. Output formats are `plain`/`json`/`streaming-json`
+ * (map ai-runner `text` → `plain`). No auth-status verb — `getAuthCommand` is null;
+ * credential probing lives in auth-shims (env / `~/.grok/auth.json`).
+ */
+const grokShim: AgentShim = {
+    name: 'grok',
+    command: 'grok',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'grok', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true) args.push('-c');
+        if (options.model !== undefined) args.push('-m', options.model);
+        // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
+        const format = (options.mode ?? 'text') === 'json' ? 'json' : 'plain';
+        args.push('--output-format', format);
+        return { command: 'grok', args };
+    },
+    getAuthCommand: () => null,
+};
+
 /** All bundled agent shims keyed by canonical agent name. */
 export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     claude: claudeShim,
@@ -243,6 +268,7 @@ export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     openclaw: openclawShim,
     hermes: hermesShim,
     omp: ompShim,
+    grok: grokShim,
 };
 
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
@@ -254,6 +280,7 @@ export const TIER1_PRIORITY: readonly AgentName[] = [
     'claude',
     'hermes',
     'opencode',
+    'grok',
 ];
 
 /** Display order for doctor and list commands. */
@@ -267,6 +294,7 @@ export const DISPLAY_ORDER: readonly AgentName[] = [
     'antigravity-cli',
     'openclaw',
     'hermes',
+    'grok',
 ];
 
 /** Set of gateway/TUI-constrained agents. */