feat(agents): support Grok Build subagents

docs/agent-profile-schema.md

@@ -73,6 +73,7 @@ provider: opencode
 provider: pi
 provider: cursor
 provider: copilot
+provider: grok
 ```
 
 Unsupported or custom providers are rejected. DevSpace maps providers to their
@@ -84,6 +85,7 @@ native integration:
 - `pi`: the installed Pi coding-agent SDK, one in-process session per DevSpace agent
 - `cursor`: ACP
 - `copilot`: ACP
+- `grok`: Grok Build ACP (`grok agent stdio`)
 
 Codex is resolved from the user's environment rather than bundled with
 DevSpace. Run `codex login` normally before using it; set `CODEX_COMMAND` when
@@ -119,6 +121,7 @@ DevSpace passes this through to providers that expose a matching control:
 - `pi`: the AgentSession thinking-level control.
 - `opencode`: model variant.
 - `cursor` and `copilot`: ACP thought-level config when supported.
+- `grok`: `--reasoning-effort` on startup and xAI's ACP model metadata for resumed sessions.
 
 ### `disabled`
 

docs/configuration.md

@@ -163,6 +163,12 @@ Enable providers and set their defaults in `~/.devspace/config.json`:
         "id": "claude",
         "enabled": true,
         "model": "sonnet"
+      },
+      {
+        "id": "grok",
+        "enabled": true,
+        "model": "grok-4.5",
+        "effort": "low"
       }
     ]
   }
@@ -180,6 +186,14 @@ workspace. Add `--json` to inspect the availability and usability of enabled
 providers. Disabled and unconfigured providers are omitted. Provider
 availability is runtime state and never rewrites the configuration.
 
+Grok Build is discovered from the `grok` executable. Authenticate it with
+`grok login` or `XAI_API_KEY`; DevSpace does not read or store Grok credentials.
+Grok supports `grok-build` by default and validates explicit model and effort
+values against the ACP session metadata when available. Set `GROK_COMMAND` when
+the executable is not on the normal PATH. If your Grok installation selects a
+custom agent profile, set `GROK_AGENT_PROFILE` to that profile's path; DevSpace
+passes it to `grok agent stdio` without writing to Grok's configuration.
+
 `open_workspace` returns a compact catalog containing profile names,
 descriptions, providers, and optional models/effort levels so the host model can choose an
 agent without reading provider-specific launch details. Disabled or unavailable

examples/agents/grok-builder.md

@@ -0,0 +1,10 @@
+---
+name: grok-builder
+description: Implement a focused change with Grok Build.
+provider: grok
+model: grok-4.5
+effort: low
+---
+
+Implement the requested change in the current workspace. Inspect the existing
+patterns first, keep the patch focused, and report the verification you ran.

package.json

@@ -29,7 +29,7 @@
     "dev": "node scripts/dev-server.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/onboarding.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/onboarding.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-grok.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],

src/config.test.ts

@@ -177,7 +177,7 @@ assert.equal(fileConfig.port, 8787);
 assert.equal(fileConfig.oauth.ownerToken, "persisted-owner-token-long-enough");
 assert.equal(fileConfig.publicBaseUrl, "https://devspace.example.com");
 assert.equal(fileConfig.subagents.enabled, true);
-assert.equal(fileConfig.subagents.providers.length, 6);
+assert.equal(fileConfig.subagents.providers.length, 7);
 assert.equal(fileConfig.artifactsEnabled, true);
 assert.equal(fileConfig.artifactMaxFileBytes, 321);
 assert.deepEqual(fileConfig.allowedHosts, [

src/local-agent-acp.test.ts

@@ -10,6 +10,7 @@ import {
   resolveAcpCommand,
   selectAcpPermissionOption,
 } from "./local-agent-acp.js";
+import { GrokPromptCompletionRegistry } from "./local-agent-grok.js";
 
 const requests: Array<{ method: string; params?: unknown }> = [];
 const queues = new Map<string, { values: unknown[] }>();
@@ -278,6 +279,18 @@ assert.equal(resolverCalls, 1, "ACP executable identity is resolved once per dri
 assert.deepEqual(acpCommandArgs("cursor", cachedContext), [
   "acp", "--sandbox", "enabled", "--workspace", resolvedProject,
 ]);
+assert.deepEqual(acpCommandArgs("grok", {
+  ...cachedContext,
+  provider: "grok",
+  effort: "low",
+}), ["agent", "--reasoning-effort", "low", "stdio"]);
+assert.deepEqual(acpCommandArgs("grok", {
+  ...cachedContext,
+  provider: "grok",
+  effort: "low",
+}, { GROK_AGENT_PROFILE: " /tmp/grok-coding-only.md " }), [
+  "agent", "--agent-profile", "/tmp/grok-coding-only.md", "--reasoning-effort", "low", "stdio",
+]);
 assert.deepEqual(acpCommandArgs("copilot", cachedContext), [
   "--acp", "--experimental", "--sandbox", "--allow-all-tools", "--add-dir", resolvedProject, "-C", resolvedProject,
 ]);
@@ -344,6 +357,125 @@ if (process.platform !== "win32") {
   }
 }
 
+const grokRequests: Array<{ method: string; params?: unknown }> = [];
+const grokQueues = new Map<string, { values: unknown[] }>();
+const grokCompletionRegistry = new GrokPromptCompletionRegistry();
+const grokConnection = {
+  agent: {
+    async request(method: string, params?: unknown): Promise<unknown> {
+      grokRequests.push({ method, params });
+      const input = params as { sessionId?: string; _meta?: { promptId?: string } } | undefined;
+      if (method === "session/new") {
+        grokQueues.set("grok_session_1", { values: [] });
+        return {
+          sessionId: "grok_session_1",
+          models: {
+            currentModelId: "grok-4.5",
+            availableModels: [{
+              modelId: "grok-4.5",
+              _meta: { reasoningEfforts: [{ id: "low", value: "low" }] },
+            }],
+          },
+        };
+      }
+      if (method === "session/set_model") return {};
+      if (method === "session/prompt") {
+        grokQueues.get(input?.sessionId ?? "")?.values.push({
+          update: {
+            sessionUpdate: "agent_message_chunk",
+            content: { type: "text", text: "Grok response" },
+          },
+        });
+        setImmediate(() => grokCompletionRegistry.resolve({
+          sessionId: input?.sessionId ?? "",
+          promptId: input?._meta?.promptId,
+          stopReason: "end_turn",
+        }));
+        return new Promise(() => undefined);
+      }
+      return {};
+    },
+  },
+  close() {},
+  closed: new Promise<void>(() => undefined),
+};
+const grokRuntime = new AcpRuntime({
+  provider: "grok",
+  command: "grok",
+  args: ["agent", "--reasoning-effort", "low", "stdio"],
+  env: {},
+  capabilities: { resume: true, close: true },
+  queues: grokQueues,
+  grokCompletionRegistry,
+  promptCompletionTimeoutMs: 100,
+}, grokConnection);
+const grokResult = await grokRuntime.run({
+  prompt: "which model are you",
+  workspaceRoot: "/tmp/project",
+  model: "grok-4.5",
+  effort: "low",
+});
+assert.equal(grokResult.isOk(), true);
+if (grokResult.isErr()) throw grokResult.error;
+assert.equal(grokResult.value.finalResponse, "Grok response");
+assert.deepEqual(
+  grokRequests.filter(({ method }) => method === "session/set_model").map(({ params }) => params),
+  [{ sessionId: "grok_session_1", modelId: "grok-4.5", _meta: { reasoningEffort: "low" } }],
+);
+assert.equal(grokCompletionRegistry.size, 0);
+await grokRuntime.close();
+
+const grokConfigurationConnection = {
+  agent: {
+    async request(method: string): Promise<unknown> {
+      if (method === "session/new") {
+        return {
+          sessionId: "grok_configuration_session",
+          models: {
+            currentModelId: "grok-4.5",
+            availableModels: [{
+              modelId: "grok-4.5",
+              _meta: { reasoningEfforts: [{ id: "low", value: "low" }] },
+            }],
+          },
+        };
+      }
+      return {};
+    },
+  },
+  close() {},
+  closed: new Promise<void>(() => undefined),
+};
+const grokConfigurationRuntime = new AcpRuntime({
+  provider: "grok",
+  command: "grok",
+  args: ["agent", "stdio"],
+  env: {},
+}, grokConfigurationConnection);
+const invalidGrokModel = await grokConfigurationRuntime.run({
+  prompt: "invalid model",
+  workspaceRoot: "/tmp/project",
+  model: "grok-unknown",
+});
+assert.equal(invalidGrokModel.isErr(), true);
+if (invalidGrokModel.isErr()) {
+  assert.equal(invalidGrokModel.error.code, "PROVIDER_PROTOCOL_ERROR");
+  assert.equal(invalidGrokModel.error.retryable, false);
+  assert.match(invalidGrokModel.error.message, /Available models: grok-4\.5/);
+}
+const invalidGrokEffort = await grokConfigurationRuntime.run({
+  prompt: "invalid effort",
+  workspaceRoot: "/tmp/project",
+  effort: "high",
+});
+assert.equal(invalidGrokEffort.isErr(), true);
+if (invalidGrokEffort.isErr()) {
+  assert.equal(invalidGrokEffort.error.code, "PROVIDER_PROTOCOL_ERROR");
+  assert.equal(invalidGrokEffort.error.retryable, false);
+  assert.match(invalidGrokEffort.error.message, /Available efforts: low/);
+}
+await grokConfigurationRuntime.close();
+
 await resumedRuntime.close();
 await resumedRuntime.close();
 assert.equal(resumedRuntime.isAlive(), false);