@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/providers/acp-targets.ts

@@ -1,13 +1,42 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { type AcpTarget, getAcpTargetCatalogEntry, isAcpTarget } from "./acp-target-catalog";
-import type { ProviderSessionConfig } from "./types";
+import { normalizeGrokModel } from "@desplega/model-catalog";
+import { clampContextPercent, getContextWindowSize } from "../utils/context-window";
+import {
+  ACP_TARGET_IDS,
+  type AcpTarget,
+  getAcpTargetCatalogEntry,
+  isAcpTarget,
+} from "./acp-target-catalog";
+import { applyReasoningEffort } from "./reasoning-effort";
+import type { CostData, CostModelUsage, ProviderEvent, ProviderSessionConfig } from "./types";
 
 export interface AcpTargetProfile {
-  readonly target: AcpTarget;
+  /** An operator-selectable ACP target, or a first-class harness built on the ACP client. */
+  readonly target: AcpTarget | "grok";
   command(config: ProviderSessionConfig): string[];
   env(config: ProviderSessionConfig): Record<string, string>;
   configuredOptions(config: ProviderSessionConfig): Record<string, string | boolean>;
   writeSystemPromptArtifact(config: ProviderSessionConfig): Promise<void>;
+  /** Removes what writeSystemPromptArtifact wrote. Called once the session ends or fails to start. */
+  cleanupSystemPromptArtifact?(config: ProviderSessionConfig): Promise<void>;
+  /** Target-specific `session/new` `_meta`. Targets without one send none. */
+  sessionMeta?(config: ProviderSessionConfig): Record<string, unknown> | undefined;
+  /** A clearer message for a target error whose own text misleads, else undefined. */
+  describeError?(message: string): string | undefined;
+  /** Rewrites a translated event for display, e.g. unwrapping a tool proxy. */
+  rewriteEvent?(event: ProviderEvent): ProviderEvent;
+  /** Usage, cost and the model that ran, from the `session/prompt` response `_meta`. */
+  promptCost?(
+    meta: Record<string, unknown> | null | undefined,
+    model: string,
+  ): Partial<CostData> | undefined;
+  /** A context snapshot from the `session/prompt` response `_meta`, for targets without `usage_update`. */
+  promptContext?(
+    meta: Record<string, unknown> | null | undefined,
+    model: string,
+  ): Extract<ProviderEvent, { type: "context_usage" }> | undefined;
 }
 
 export class AcpTargetResolutionError extends Error {
@@ -181,16 +210,341 @@ const opencodeTargetProfile: AcpTargetProfile = {
   async writeSystemPromptArtifact() {},
 };
 
+// The prompt file is per session and lives outside the task cwd, so it never
+// lands in the repo tree. `env()` runs after `writeSystemPromptArtifact()` and
+// reads the path back from here.
+const geminiSystemPromptPaths = new WeakMap<ProviderSessionConfig, string>();
+
+const geminiTargetProfile: AcpTargetProfile = {
+  target: "gemini",
+  command() {
+    const entry = getAcpTargetCatalogEntry("gemini");
+    return [entry.command!, ...(entry.args ?? [])];
+  },
+  env(config) {
+    const env = baseTargetEnv(config);
+    const entry = getAcpTargetCatalogEntry("gemini");
+    copyEnvKeys(config, env, entry.envKeys);
+    // A worker has no interactive trust prompt; the task cwd is ours.
+    env.GEMINI_CLI_TRUST_WORKSPACE = "true";
+    // Startup fallback when the ACP `model` option is not advertised.
+    if (config.model.trim()) env.GEMINI_MODEL = config.model.trim();
+    const systemPromptPath = geminiSystemPromptPaths.get(config);
+    if (systemPromptPath) env.GEMINI_SYSTEM_MD = systemPromptPath;
+    return env;
+  },
+  configuredOptions,
+  async writeSystemPromptArtifact(config) {
+    // GEMINI_SYSTEM_MD replaces Gemini CLI's built-in prompt, so an empty
+    // swarm prompt keeps the built-in one instead of blanking it.
+    if (!config.systemPrompt?.trim()) return;
+    const directory = await mkdtemp(join(tmpdir(), "swarm-acp-gemini-"));
+    const path = join(directory, "system.md");
+    await Bun.write(path, config.systemPrompt);
+    geminiSystemPromptPaths.set(config, path);
+  },
+};
+
+/**
+ * Copilot CLI has no system-prompt flag. Under `--acp` it reads custom
+ * instructions from the git root, the cwd, and every directory listed in
+ * COPILOT_CUSTOM_INSTRUCTIONS_DIRS. Verified against 1.0.93: from those extra
+ * directories it loads `.github/instructions/*.instructions.md`, but not
+ * `AGENTS.md`. So the swarm prompt goes into a per-task directory outside the
+ * repo, and the repo's own AGENTS.md is never touched.
+ */
+export function copilotInstructionsDir(config: ProviderSessionConfig): string {
+  const key = new Bun.CryptoHasher("sha256")
+    .update(`${config.agentId}:${config.taskId}:${config.cwd}`)
+    .digest("hex")
+    .slice(0, 16);
+  return join(tmpdir(), "agent-swarm-copilot-instructions", key);
+}
+
+export const COPILOT_INSTRUCTIONS_FILE = join(
+  ".github",
+  "instructions",
+  "agent-swarm.instructions.md",
+);
+
+const copilotTargetProfile: AcpTargetProfile = {
+  target: "copilot",
+  command() {
+    const entry = getAcpTargetCatalogEntry("copilot");
+    return [entry.command!, ...(entry.args ?? [])];
+  },
+  env(config) {
+    const env = baseTargetEnv(config);
+    const entry = getAcpTargetCatalogEntry("copilot");
+    copyEnvKeys(config, env, entry.envKeys);
+    if (config.model.trim()) env.COPILOT_MODEL = config.model.trim();
+    // The image pins the CLI; a self-update would run an unpinned binary.
+    env.COPILOT_AUTO_UPDATE = "false";
+    const operatorDirs = readEnv(config, "COPILOT_CUSTOM_INSTRUCTIONS_DIRS")?.trim();
+    env.COPILOT_CUSTOM_INSTRUCTIONS_DIRS = [copilotInstructionsDir(config), operatorDirs]
+      .filter(Boolean)
+      .join(",");
+    return env;
+  },
+  configuredOptions,
+  async writeSystemPromptArtifact(config) {
+    const dir = copilotInstructionsDir(config);
+    await rm(dir, { recursive: true, force: true });
+    if (!config.systemPrompt) return;
+    await mkdir(join(dir, ".github", "instructions"), { recursive: true });
+    await Bun.write(
+      join(dir, COPILOT_INSTRUCTIONS_FILE),
+      `---\napplyTo: "**"\n---\n\n${config.systemPrompt}\n`,
+    );
+  },
+  async cleanupSystemPromptArtifact(config) {
+    await rm(copilotInstructionsDir(config), { recursive: true, force: true });
+  },
+};
+
+/**
+ * Grok CLI env keys passed through to `grok agent stdio`. `GROK_HOME` is the
+ * per-session state dir the grok adapter creates; the rest switch off the
+ * Claude/Cursor compat surfaces that would otherwise load the worker's own
+ * Claude hooks, MCP servers, CLAUDE.md and rules into a Grok session.
+ * Claude skills stay on so swarm skills remain invocable.
+ */
+export const GROK_ISOLATION_ENV: Readonly<Record<string, string>> = {
+  GROK_DISABLE_AUTOUPDATER: "1",
+  GROK_TELEMETRY_ENABLED: "0",
+  GROK_CLAUDE_HOOKS_ENABLED: "false",
+  GROK_CLAUDE_MCPS_ENABLED: "false",
+  GROK_CLAUDE_AGENTS_ENABLED: "false",
+  GROK_CLAUDE_RULES_ENABLED: "false",
+  GROK_CURSOR_HOOKS_ENABLED: "false",
+  GROK_CURSOR_MCPS_ENABLED: "false",
+  GROK_CURSOR_AGENTS_ENABLED: "false",
+  GROK_CURSOR_RULES_ENABLED: "false",
+  GROK_CURSOR_SKILLS_ENABLED: "false",
+};
+
+/**
+ * The Grok CLI's endpoint overrides for the xAI route (docs.x.ai settings
+ * reference): `GROK_MODELS_BASE_URL` points inference and the model list at
+ * any OpenAI-compatible gateway, authenticated with XAI_API_KEY.
+ */
+export const GROK_XAI_ENDPOINT_KEYS = [
+  "GROK_MODELS_BASE_URL",
+  "GROK_MODELS_LIST_URL",
+  "GROK_XAI_API_BASE_URL",
+] as const;
+
+/** `openrouter/<vendor>/<id>`: an OpenRouter model the grok adapter registers in `config.toml`. */
+export function isGrokOpenRouterModel(model: string): boolean {
+  return model.trim().startsWith("openrouter/");
+}
+
+/**
+ * Grok exposes MCP tools through its `use_tool` proxy (on-demand tool search),
+ * so every swarm call arrives as `use_tool {tool_name: "swarm__get-swarm",
+ * tool_input}`. Unwrap it to the `mcp__<server>__<tool>` name and its own
+ * input, the shape every other harness logs. Grok's in-progress updates
+ * repeat the input tagged with a `variant` (`UseTool`, `SearchTool`); the
+ * dashboard merges update input into the call, so the tag is dropped and a
+ * `UseTool` update carries only the inner input.
+ */
+function unwrapGrokToolProxy(event: ProviderEvent): ProviderEvent {
+  if (event.type === "tool_start" && event.toolName === "use_tool") {
+    const args = event.args as { tool_name?: unknown; tool_input?: unknown } | null;
+    if (typeof args?.tool_name !== "string" || !args.tool_name) return event;
+    return { ...event, toolName: `mcp__${args.tool_name}`, args: args.tool_input ?? {} };
+  }
+  if (event.type !== "custom" || event.name !== "acp_tool_call_update") return event;
+  const data = event.data as { rawInput?: unknown } | null;
+  const raw = data?.rawInput as Record<string, unknown> | null | undefined;
+  if (!raw || typeof raw !== "object" || typeof raw.variant !== "string") return event;
+  const { variant, ...rest } = raw;
+  const rawInput = variant === "UseTool" ? (rest.tool_input ?? {}) : rest;
+  return { ...event, data: { ...(data as Record<string, unknown>), rawInput } };
+}
+
+function finiteCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+/** xAI bills in ticks of 1e-10 USD (`costUsdTicks`). */
+const XAI_USD_TICKS = 10_000_000_000;
+
+/**
+ * The swarm id of a model Grok reports (`_meta.modelId`, a `modelUsage` key)
+ * in a session started on `sessionModel`. An OpenRouter session only reaches
+ * OpenRouter, so its ids keep the `openrouter/` namespace pricing and context
+ * lookups need; an xAI session's ids are bare xAI ids.
+ */
+export function grokReportedModel(reported: string, sessionModel: string): string {
+  const id = normalizeGrokModel(reported);
+  if (!isGrokOpenRouterModel(sessionModel) || isGrokOpenRouterModel(id)) return id;
+  return `openrouter/${id}`;
+}
+
+/** The model Grok says ran the prompt's last call, else the session's model. */
+function grokFinalModel(meta: Record<string, unknown> | null | undefined, model: string): string {
+  const reported = typeof meta?.modelId === "string" ? meta.modelId.trim() : "";
+  return reported ? grokReportedModel(reported, model) : normalizeGrokModel(model);
+}
+
+/**
+ * Grok's usage counts in the swarm's shape: its `inputTokens` include cache
+ * reads and its `outputTokens` exclude reasoning, so both are converted to the
+ * swarm's disjoint input and reasoning-inclusive output.
+ */
+function grokUsageCounts(usage: Record<string, unknown>) {
+  const input = finiteCount(usage.inputTokens) ?? 0;
+  const cacheRead = finiteCount(usage.cachedReadTokens) ?? 0;
+  const reasoning = finiteCount(usage.reasoningTokens) ?? 0;
+  const ticks = finiteCount(usage.costUsdTicks);
+  return {
+    inputTokens: Math.max(0, input - cacheRead),
+    cacheReadTokens: cacheRead,
+    cacheWriteTokens: finiteCount(usage.cacheCreationTokens) ?? 0,
+    outputTokens: (finiteCount(usage.outputTokens) ?? 0) + reasoning,
+    reasoningOutputTokens: reasoning,
+    costUsd: ticks ? ticks / XAI_USD_TICKS : undefined,
+  };
+}
+
+/** `_meta.usage.modelUsage` as per-model rows, keyed by the swarm model id. */
+function grokModelUsage(usage: Record<string, unknown>, model: string): CostModelUsage[] {
+  const byModel = usage.modelUsage;
+  if (!byModel || typeof byModel !== "object" || Array.isArray(byModel)) return [];
+  const rows: CostModelUsage[] = [];
+  for (const [reported, entry] of Object.entries(byModel as Record<string, unknown>)) {
+    if (!reported.trim() || !entry || typeof entry !== "object") continue;
+    const {
+      costUsd,
+      reasoningOutputTokens: _,
+      ...counts
+    } = grokUsageCounts(entry as Record<string, unknown>);
+    rows.push({
+      model: grokReportedModel(reported, model),
+      ...counts,
+      ...(costUsd !== undefined ? { harnessCostUsd: costUsd } : {}),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Grok answers `session/prompt` with `usage: null` and puts the prompt's
+ * cumulative usage in `_meta.usage`, split per model in `modelUsage` (a side
+ * model or a fallback shows up as its own entry). `_meta.modelId` names the
+ * model that ran, which can differ from the one requested. `costUsdTicks` is
+ * what xAI billed; a BYOK model (OpenRouter) reports none and is priced from
+ * the table, per model.
+ */
+export function grokPromptCost(
+  meta: Record<string, unknown> | null | undefined,
+  model: string,
+): Partial<CostData> | undefined {
+  const usage = meta?.usage as Record<string, unknown> | undefined;
+  if (!usage || typeof usage !== "object") return undefined;
+  const { costUsd, ...counts } = grokUsageCounts(usage);
+  const turns = finiteCount(usage.numTurns) ?? finiteCount(usage.modelCalls);
+  const models = grokModelUsage(usage, model);
+  return {
+    model: grokFinalModel(meta, model),
+    ...counts,
+    ...(models.length ? { models } : {}),
+    ...(costUsd !== undefined ? { totalCostUsd: costUsd } : {}),
+    ...(turns ? { numTurns: turns } : {}),
+  };
+}
+
+/**
+ * Grok sends no `usage_update`. The prompt response's top-level `_meta`
+ * describes the last model call: `totalTokens` is its input (cache reads
+ * included), output and reasoning, i.e. how full the context was at the end,
+ * and `modelId` is the model whose window that is.
+ */
+export function grokPromptContext(
+  meta: Record<string, unknown> | null | undefined,
+  model: string,
+): Extract<ProviderEvent, { type: "context_usage" }> | undefined {
+  const used = finiteCount(meta?.totalTokens);
+  if (!used) return undefined;
+  const id = grokFinalModel(meta, model);
+  const total = getContextWindowSize(isGrokOpenRouterModel(id) ? id : `xai/${id}`);
+  return {
+    type: "context_usage",
+    contextUsedTokens: used,
+    contextTotalTokens: total,
+    contextPercent: clampContextPercent(used, total),
+    outputTokens: finiteCount(meta?.outputTokens) ?? null,
+    contextFormula: "harness-reported",
+  };
+}
+
+/** `-32000 Authentication required` (ACP) or the CLI's "Not signed in" text. */
+const GROK_AUTH_ERROR_RE = /authentication required|not signed in/i;
+
+export const grokTargetProfile: AcpTargetProfile = {
+  target: "grok",
+  command(config) {
+    const binary = readEnv(config, "GROK_BINARY")?.trim() || "grok";
+    // `--no-leader` keeps each session on its own agent process (the default
+    // config may enable a shared leader socket). Flags go before `stdio`.
+    const args = [binary, "agent", "--no-leader", "--always-approve"];
+    if (config.model.trim()) args.push("--model", config.model.trim());
+    const effort = config.reasoningEffort
+      ? applyReasoningEffort("grok", config.model.trim(), config.reasoningEffort)
+      : null;
+    if (effort?.kind === "grok-effort") args.push("--reasoning-effort", effort.reasoningEffort);
+    args.push("stdio");
+    return args;
+  },
+  env(config) {
+    const env = baseTargetEnv(config);
+    // Each route gets only its own key: an OpenRouter session never sees
+    // XAI_API_KEY, so no side model (web search, summaries) bills xAI.
+    if (isGrokOpenRouterModel(config.model)) {
+      copyEnvKeys(config, env, ["OPENROUTER_API_KEY", "GROK_HOME"]);
+    } else {
+      copyEnvKeys(config, env, ["XAI_API_KEY", "GROK_HOME", ...GROK_XAI_ENDPOINT_KEYS]);
+    }
+    Object.assign(env, GROK_ISOLATION_ENV);
+    return env;
+  },
+  // Model and effort ride on the command line, which the CLI accepts before auth.
+  configuredOptions() {
+    return {};
+  },
+  async writeSystemPromptArtifact() {},
+  sessionMeta(config) {
+    // `rules` appends to Grok's own system prompt; `systemPromptOverride`
+    // would replace it, tool instructions included.
+    return {
+      ...(config.systemPrompt?.trim() ? { rules: config.systemPrompt } : {}),
+      yoloMode: true,
+    };
+  },
+  rewriteEvent: unwrapGrokToolProxy,
+  promptCost: grokPromptCost,
+  promptContext: grokPromptContext,
+  describeError(message) {
+    if (!GROK_AUTH_ERROR_RE.test(message)) return undefined;
+    return `Grok rejected the credentials (XAI_API_KEY or OPENROUTER_API_KEY invalid or missing): ${message}`;
+  },
+};
+
 export function resolveAcpTarget(config: ProviderSessionConfig): AcpTargetProfile {
   const target = readEnv(config, "ACP_TARGET") ?? "custom";
   if (!isAcpTarget(target)) {
     throw new AcpTargetResolutionError(
-      `Unsupported ACP target "${target}". Supported targets: opencode, custom.`,
+      `Unsupported ACP target "${target}". Supported targets: ${ACP_TARGET_IDS.join(", ")}.`,
     );
   }
   switch (target) {
     case "opencode":
       return opencodeTargetProfile;
+    case "gemini":
+      return geminiTargetProfile;
+    case "copilot":
+      return copilotTargetProfile;
     case "custom":
       return customTargetProfile;
   }

package/src/providers/amp-adapter.ts

@@ -44,7 +44,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1791316840-g709a2a";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1791403257-g05ffa9";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/cursor-adapter.ts

@@ -35,7 +35,7 @@ import type {
 } from "./types";
 
 /** Pinned in package.json and Dockerfile.worker; bump all three together. */
-export const CURSOR_SDK_VERSION = "1.0.36";
+export const CURSOR_SDK_VERSION = "1.0.37";
 
 /** MCP server name; Cursor reports its tools as `mcp` calls with this `providerIdentifier`. */
 const CURSOR_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/grok-adapter.ts

@@ -0,0 +1,186 @@
+// Bun has no temp-dir or recursive-delete API; file reads and writes use Bun.file/Bun.write.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalizeGrokModel } from "@desplega/model-catalog";
+import { getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+import { registerVolatileSecret } from "../utils/secret-scrubber";
+import { ACPAdapter } from "./acp-adapter";
+import { grokTargetProfile, isGrokOpenRouterModel } from "./acp-targets";
+import type {
+  CredStatus,
+  ProviderAdapter,
+  ProviderSession,
+  ProviderSessionConfig,
+  ProviderTraits,
+} from "./types";
+
+/**
+ * The xAI Grok CLI (`@xai-official/grok`) on the swarm's ACP client:
+ * `grok agent --no-leader stdio` is an ACP server, so spawn, swarm MCP
+ * injection, permissions, event translation and cost all come from
+ * {@link ACPAdapter}. This adapter adds the per-session `GROK_HOME`.
+ *
+ * Auth is `XAI_API_KEY` for xAI models, or `OPENROUTER_API_KEY` for an
+ * `openrouter/<id>` model, which runs as an OpenAI-compatible BYOK model. A
+ * SuperGrok OAuth pool needs the CLI's `auth.json` refresh behaviour measured
+ * first (issue #1952 follow-up).
+ */
+export function checkGrokCredentials(env: Record<string, string | undefined>): CredStatus {
+  return env.XAI_API_KEY?.trim() || env.OPENROUTER_API_KEY?.trim()
+    ? { ready: true, missing: [], satisfiedBy: "env" }
+    : {
+        ready: false,
+        missing: ["XAI_API_KEY", "OPENROUTER_API_KEY"],
+        hint: "Set XAI_API_KEY (console.x.ai) or OPENROUTER_API_KEY (openrouter/<id> models) for grok.",
+      };
+}
+
+/**
+ * Claude Code plugins installed for the worker's own harness. Grok discovers
+ * `~/.claude/plugins` and loads their MCP servers even with Claude MCP compat
+ * off, so each one is listed in `[plugins].disabled`.
+ */
+export async function installedClaudePluginNames(home: string | undefined): Promise<string[]> {
+  if (!home) return [];
+  try {
+    const parsed = (await Bun.file(
+      join(home, ".claude", "plugins", "installed_plugins.json"),
+    ).json()) as { plugins?: Record<string, unknown> };
+    const ids = Object.keys(parsed.plugins ?? {});
+    // Keys are `<plugin>@<marketplace>`; Grok matches on the plugin name.
+    return [...new Set(ids.map((id) => id.split("@")[0] ?? "").filter(Boolean))];
+  } catch {
+    return [];
+  }
+}
+
+/** An OpenAI-compatible model the session registers under `[model."<id>"]`. */
+export interface GrokCustomModel {
+  /** The swarm model string, which is also the id passed to `--model`. */
+  id: string;
+  /** The id sent to the endpoint. */
+  model: string;
+  baseUrl: string;
+  /** Env var holding the endpoint's API key. */
+  envKey: string;
+}
+
+/** `openrouter/<vendor>/<id>` -> a `[model."openrouter/<vendor>/<id>"]` block on OpenRouter. */
+export function grokOpenRouterModel(
+  model: string,
+  env: Record<string, string | undefined>,
+): GrokCustomModel | null {
+  const id = model.trim();
+  if (!isGrokOpenRouterModel(id)) return null;
+  return {
+    id,
+    model: id.slice("openrouter/".length),
+    baseUrl: getOpenRouterBaseUrl(env),
+    envKey: "OPENROUTER_API_KEY",
+  };
+}
+
+/** `$GROK_HOME/config.toml` for one swarm session. */
+export function buildGrokConfigToml(
+  disabledPlugins: readonly string[],
+  customModel: GrokCustomModel | null = null,
+): string {
+  const list = disabledPlugins.map((name) => JSON.stringify(name)).join(", ");
+  const modelBlock = customModel
+    ? [
+        "",
+        `[model.${JSON.stringify(customModel.id)}]`,
+        `model = ${JSON.stringify(customModel.model)}`,
+        `base_url = ${JSON.stringify(customModel.baseUrl)}`,
+        `env_key = ${JSON.stringify(customModel.envKey)}`,
+        `api_backend = "chat_completions"`,
+      ]
+    : [];
+  return [
+    "[cli]",
+    "auto_update = false",
+    "",
+    "[compat.codex]",
+    "hooks = false",
+    "skills = false",
+    "",
+    "[plugins]",
+    `disabled = [${list}]`,
+    ...modelBlock,
+    "",
+  ].join("\n");
+}
+
+/**
+ * `$GROK_HOME/requirements.toml`: a policy pin that skips every hook outside
+ * managed policy at dispatch (plugin hooks and the Claude/Cursor compat
+ * files included), so the worker's own Claude hooks never fire inside Grok.
+ * `grok inspect` reports it as "Hooks outside managed policy disabled".
+ */
+export const GROK_REQUIREMENTS_TOML = "allow_managed_hooks_only = true\n";
+
+export class GrokAdapter implements ProviderAdapter {
+  readonly name = "grok";
+
+  readonly traits: ProviderTraits = {
+    hasMcp: true,
+    hasToolSearch: false,
+    // Claude skills compat stays on, so Grok lists ~/.claude/skills itself.
+    nativeSkillDiscovery: true,
+    hasLocalEnvironment: true,
+    steerModes: [],
+  };
+
+  private readonly acp = new ACPAdapter({ providerName: "grok", target: grokTargetProfile });
+
+  async createSession(sessionConfig: ProviderSessionConfig): Promise<ProviderSession> {
+    // `xai/<id>` is the catalog's spelling of a bare xAI id; the CLI takes the bare one.
+    const config = { ...sessionConfig, model: normalizeGrokModel(sessionConfig.model) };
+    const env = { ...process.env, ...config.env };
+    const customModel = grokOpenRouterModel(config.model, env);
+    const keyName = customModel ? "OPENROUTER_API_KEY" : "XAI_API_KEY";
+    const apiKey = env[keyName]?.trim();
+    if (!apiKey) {
+      throw new Error(
+        customModel
+          ? `grok requires OPENROUTER_API_KEY for ${customModel.id}`
+          : "grok requires XAI_API_KEY",
+      );
+    }
+    registerVolatileSecret(apiKey, keyName);
+
+    // A fresh GROK_HOME per session: no shared auth.json, sessions or leader
+    // socket between tasks, and the config below applies to this run only.
+    const grokHome = await mkdtemp(join(tmpdir(), "swarm-grok-"));
+    try {
+      await Bun.write(
+        join(grokHome, "config.toml"),
+        buildGrokConfigToml(await installedClaudePluginNames(env.HOME), customModel),
+        { mode: 0o600 },
+      );
+      await Bun.write(join(grokHome, "requirements.toml"), GROK_REQUIREMENTS_TOML, {
+        mode: 0o600,
+      });
+      const session = await this.acp.createSession({
+        ...config,
+        env: { ...config.env, [keyName]: apiKey, GROK_HOME: grokHome },
+      });
+      void session
+        .waitForCompletion()
+        .finally(() => rm(grokHome, { recursive: true, force: true }));
+      return session;
+    } catch (error) {
+      await rm(grokHome, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
+  async canResume(_sessionId: string): Promise<boolean> {
+    return false;
+  }
+
+  formatCommand(commandName: string): string {
+    return `/${commandName}`;
+  }
+}

package/src/providers/index.ts

@@ -59,13 +59,17 @@ export async function createProviderAdapter(provider: string): Promise<ProviderA
       const { CursorAdapter } = await import("./cursor-adapter");
       return new CursorAdapter();
     }
+    case "grok": {
+      const { GrokAdapter } = await import("./grok-adapter");
+      return new GrokAdapter();
+    }
     case "acp": {
       const { ACPAdapter } = await import("./acp-adapter");
       return new ACPAdapter();
     }
     default:
       throw new Error(
-        `Unknown HARNESS_PROVIDER: "${provider}". Supported: claude, pi, codex, devin, claude-managed, opencode, acp, dsh, cursor, amp`,
+        `Unknown HARNESS_PROVIDER: "${provider}". Supported: claude, pi, codex, devin, claude-managed, opencode, acp, dsh, cursor, amp, grok`,
       );
   }
 }

package/src/providers/pricing-sources.md

@@ -69,6 +69,12 @@ rate by hand should also update this file.
     When the adapter reports what Amp billed (`amp threads usage`, only when
     every request was billed through Amp), that harness cost wins and the
     rows above only fill the per-model breakdown.
+  - xAI models (models.dev `xai` section, bare ids such as `grok-4.6`) → rows
+    under `provider='grok'`. Base rates only; the `context_over_200k` tier is
+    not projected (no provider projects context tiers yet). The adapter sends
+    what xAI billed (`_meta.usage.costUsdTicks`), which wins over these rows
+    as for amp. OpenRouter models also project under `provider='grok'` for
+    `openrouter/<id>` models, which report no USD.
   - OpenAI, Anthropic, Google and xAI models (bare vendor ids) → rows under
     `provider='cursor'`. Cursor bills the vendor's API rates and reports the
     vendor's own id. The adapter subtracts cache reads and writes from SDK

package/src/providers/reasoning-effort.ts

@@ -17,6 +17,7 @@ import {
   claudeCatalogModelId,
   cursorCatalogRef,
   dshCatalogRef,
+  grokCatalogRef,
   REASONING_EFFORT_LEVELS,
   type ReasoningEffortLevel,
   reasoningLevelsFor,
@@ -28,7 +29,15 @@ export { REASONING_EFFORT_LEVELS };
 export type ReasoningEffort = ReasoningEffortLevel;
 
 /** The local harnesses this feature covers (Devin / claude-managed / ACP are out of scope). */
-export type ReasoningHarness = "claude" | "codex" | "pi" | "opencode" | "dsh" | "cursor" | "amp";
+export type ReasoningHarness =
+  | "claude"
+  | "codex"
+  | "pi"
+  | "opencode"
+  | "dsh"
+  | "cursor"
+  | "amp"
+  | "grok";
 
 export interface ReasoningCapability {
   supported: boolean;
@@ -55,6 +64,7 @@ export type ReasoningEffortApplication =
   | { kind: "dsh-effort"; reasoningEffort: ReasoningEffort }
   | { kind: "amp-effort"; reasoningEffort: ReasoningEffort }
   | { kind: "cursor-effort"; reasoningEffort: ReasoningEffort }
+  | { kind: "grok-effort"; reasoningEffort: ReasoningEffort }
   | { kind: "noop" };
 
 // --- Capability lookup --------------------------------------------------------
@@ -90,6 +100,8 @@ function lookupModel(
     ({ providerId, modelId } = dshCatalogRef(model));
   } else if (harness === "cursor") {
     ({ providerId, modelId } = cursorCatalogRef(model));
+  } else if (harness === "grok") {
+    ({ providerId, modelId } = grokCatalogRef(model));
   } else {
     ({ providerId, modelId } = splitProviderModel(model));
     if (!providerId) return undefined;
@@ -223,6 +235,10 @@ export function applyReasoningEffort(
       // (`reasoning`, `reasoning_effort`, `effort`); the adapter maps the
       // level onto the live model list (see `src/providers/cursor-adapter.ts`).
       return { kind: "cursor-effort", reasoningEffort: level };
+    case "grok":
+      // Grok's `--reasoning-effort` takes the normalized names as-is; see
+      // `src/providers/grok-adapter.ts`.
+      return { kind: "grok-effort", reasoningEffort: level };
     default: {
       const _exhaustive: never = harness;
       return _exhaustive;