@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agents/grok.ts

@@ -0,0 +1,381 @@
+/**
+ * GrokSession — a real AgentSession backed by xAI's **Grok** CLI, run inside
+ * the task environment:
+ *
+ *   ~/.grok/bin/grok -p "<prompt>" \
+ *     --output-format streaming-json --permission-mode bypassPermissions \
+ *     -m grok-4.5 --rules "<briefing>" [-r <sessionId>]
+ *
+ * Like Kimi (and unlike Claude's persistent stdin / Codex's app-server), Grok
+ * headless mode is **one-shot per turn**: `-p` runs one prompt to completion,
+ * streams newline-delimited JSON, and exits. Each `send()` spawns a fresh
+ * provider process; sends are **serialized** so a second message can't race a
+ * running turn. Continuity is `-r <sessionId>` — captured from the turn-end
+ * event (per-agent isolation, since each session tracks its own id).
+ *
+ * Stream-json vocabulary (`--output-format streaming-json`, verified):
+ *   {"type":"thought","data":"…"}                 → skipped (internal reasoning)
+ *   {"type":"text","data":"…"}                    → message_delta (streamed)
+ *   {"type":"tool_call"|"tool_call_update",…}       → safely skipped (no cards yet)
+ *   {"type":"usage",…}                              → skipped (per model call)
+ *   {"type":"available_commands",…}                 → skipped
+ *   {"type":"end","stopReason","sessionId",…}     → message_complete + turn usage/end
+ * Grok 1.0.67 surfaces tool calls, but tool cards are deliberately outside
+ * this adapter slice. The final `end.usage` aggregates the invocation.
+ *
+ * AUTH is the operator's Grok subscription: `~/.grok/{auth.json, config.toml}`
+ * is docker-cp'd into the container at task-up (the Codex/Kimi config-dir
+ * pattern; the macOS `bin/` is NOT copied — the image supplies the Linux
+ * binary). auth.json is an OIDC token with a refresh_token, so the CLI renews
+ * it in-container. Cloud never sees it (ADR-015). `--rules` appends the channel briefing to
+ * Grok's default prompt (and retains the account's cloud user rules). The
+ * override/alias flags are ignored in 1.0.70 headless mode. Rules persist on
+ * resume; a changed briefing requires a fresh Grok session.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type {
+  TaskEnvironmentAgentSessionSurface,
+  TaskEnvironmentSessionRequest,
+} from "../task-environment/types";
+import {
+  AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+  spawnEnvironmentProcess,
+  type AgentEnvironmentProcess,
+} from "./proc";
+import { rateLimitErrorUsage } from "./rate-limit";
+import { register } from "./registry";
+import { GROK_MODELS } from "../../src/engine-models";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentUsage,
+  RosterAgent,
+} from "./types";
+
+const GROK_BIN = "/home/node/.grok/bin/grok";
+export const GROK_LOADER_LOGIN_ENV = "0";
+
+// Static fallback catalog verified against `grok models`; keep the shared list
+// in host-agent/src/engine-models.ts (GROK_MODELS) current with the pinned CLI.
+const GROK_DEFAULT_MODEL = "grok-4.7";
+// Grok has no per-invocation reasoning-effort flag.
+const GROK_EFFORTS: string[] = [];
+
+function grokAuthPath(): string {
+  return join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".grok", "auth.json");
+}
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — one streaming-json line → deltas / end.
+// ---------------------------------------------------------------------------
+
+export interface MappedGrokLine {
+  /** A streamed text chunk (assistant answer), if this line carried one. */
+  textDelta?: string;
+  /** True on the turn-end event. */
+  end?: boolean;
+  /** The session id from the end event, for `-r` on the next turn. */
+  sessionId?: string;
+  /** Per-invocation usage from the final end event. */
+  usage?: AgentUsage;
+}
+
+function nonNegativeInt(value: unknown): number | undefined {
+  return typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 0
+    ? value
+    : undefined;
+}
+
+function grokEndUsage(
+  msg: Record<string, unknown>,
+  model: string | undefined,
+): AgentUsage | undefined {
+  if (typeof msg.usage !== "object" || msg.usage === null) return undefined;
+  const raw = msg.usage as Record<string, unknown>;
+  const inputTokens = nonNegativeInt(raw.input_tokens);
+  const cacheReadTokens = nonNegativeInt(raw.cache_read_input_tokens);
+  const cacheCreateTokens = nonNegativeInt(raw.cache_creation_input_tokens);
+  const outputTokens = nonNegativeInt(raw.output_tokens);
+  const reasoningTokens = nonNegativeInt(raw.reasoning_tokens);
+  if (
+    inputTokens === undefined ||
+    cacheReadTokens === undefined ||
+    cacheCreateTokens === undefined ||
+    outputTokens === undefined ||
+    reasoningTokens === undefined
+  ) {
+    return undefined;
+  }
+  const reportedCost = msg.total_cost_usd;
+  const costUsd =
+    typeof reportedCost === "number" &&
+    Number.isFinite(reportedCost) &&
+    reportedCost >= 0
+      ? reportedCost
+      : undefined;
+  return {
+    // `modelUsage` exposes the backend build id (for example
+    // grok-4.5-build), while `model` is the semantic id passed to `-m` and
+    // therefore the id Uai's model guide resolves.
+    ...(model ? { model } : {}),
+    // Headless input_tokens is already uncached; both cache buckets are
+    // additive according to the 1.0.67 headless contract.
+    inputTokens,
+    cacheReadTokens,
+    cacheCreateTokens,
+    // The documented total excludes reasoning_tokens even though it includes
+    // output_tokens. Uai has no separate reasoning column, so include that
+    // distinct billed output once here.
+    outputTokens: outputTokens + reasoningTokens,
+    // Missing cost means unreported/partial, never free.
+    ...(costUsd === undefined ? {} : { costUsd }),
+  };
+}
+
+export function mapGrokLine(
+  line: string,
+  model?: string,
+): MappedGrokLine {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return {};
+  let msg: Record<string, unknown>;
+  try {
+    msg = JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+  if (msg.type === "text" && typeof msg.data === "string") {
+    return { textDelta: msg.data };
+  }
+  if (msg.type === "end") {
+    const usage = grokEndUsage(msg, model);
+    return {
+      end: true,
+      sessionId: typeof msg.sessionId === "string" ? msg.sessionId : undefined,
+      ...(usage ? { usage } : {}),
+    };
+  }
+  // "thought" (reasoning) and any other types: no user-facing event.
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+export type Spawner = (
+  request: TaskEnvironmentSessionRequest,
+) => AgentEnvironmentProcess;
+
+export class GrokSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "grok";
+
+  private readonly environment: TaskEnvironmentAgentSessionSurface;
+  private readonly model?: string;
+  private readonly systemPreamble: string;
+  private readonly agentEnv: Record<string, string>;
+  private readonly spawner: Spawner;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private sessionId: string | null = null;
+  private current: AgentEnvironmentProcess | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private closed = false;
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    environment: TaskEnvironmentAgentSessionSurface;
+    systemPreamble: string;
+    agentEnv?: Record<string, string>;
+    spawner?: Spawner;
+  }) {
+    this.agentId = args.agent.id;
+    this.environment = args.environment;
+    this.model = args.agent.model;
+    this.systemPreamble = args.systemPreamble;
+    this.agentEnv = args.agentEnv ?? {};
+    this.spawner =
+      args.spawner ?? ((request) => spawnEnvironmentProcess(this.environment, request));
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    const turn = this.queue.catch(() => {}).then(() => this.runTurn(text));
+    this.queue = turn;
+    return turn;
+  }
+
+  private buildRequest(prompt: string): TaskEnvironmentSessionRequest {
+    // Host-resident API key (pasted in the engines panel, ADR-015): forward
+    // name-only — docker takes the value from the client env, keeping the
+    // secret out of argv. Subscription logins need nothing here (task-up
+    // copies ~/.grok into the container instead).
+    const inheritEnv = process.env.XAI_API_KEY ? ["XAI_API_KEY"] : [];
+    const argv = [
+      GROK_BIN,
+      "-p",
+      prompt,
+      "--output-format",
+      "streaming-json",
+      // The container is the isolation boundary — auto-run tools.
+      "--permission-mode",
+      "bypassPermissions",
+    ];
+    if (this.model) argv.push("-m", this.model);
+    if (this.systemPreamble.trim().length > 0) {
+      // Verified on the shipped 1.0.70: headless ignores both system-prompt
+      // override flags, but --rules reaches the model whole and persists on -r.
+      argv.push("--rules", this.systemPreamble);
+    }
+    // Resume the same conversation across turns (captured from the last end).
+    if (this.sessionId) argv.push("-r", this.sessionId);
+    return {
+      argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
+      user: "node",
+      inheritEnv,
+      env: {
+        ...this.agentEnv,
+        // Grok gates MCP/LSP servers (even user-scope ones) behind folder
+        // trust, and /workspace is never trusted: it is not a git repo and
+        // headless runs have no prompt. `grok mcp doctor` on a task machine:
+        // "folder untrusted … not started for an untrusted folder"; with this
+        // off, "2 healthy". The container/machine IS the isolation boundary —
+        // the same reasoning as --permission-mode bypassPermissions above
+        // (live 2026-09-08, first Grok agents with MCP servers).
+        GROK_FOLDER_TRUST: "0",
+        // Grok 1.0.67 still enables login-shell capture by default and honors
+        // GROK_LOGIN_ENV. That capture reuses static state for
+        // LocalNonPersistent commands; loader tasks refresh per command, so
+        // keep the stale snapshot path disabled.
+        ...(this.environment.descriptor.envMode === "loader"
+          ? { GROK_LOGIN_ENV: GROK_LOADER_LOGIN_ENV }
+          : {}),
+      },
+      maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+    };
+  }
+
+  private async runTurn(text: string): Promise<void> {
+    if (this.closed) return;
+    requireContainerRuntimeOperational();
+    const child = this.spawner(this.buildRequest(text));
+    this.current = child;
+
+    let acc = "";
+    let sawText = false;
+    let turnUsage: AgentUsage | undefined;
+    let buf = "";
+    const consume = (chunk: string): void => {
+      buf += chunk;
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const m = mapGrokLine(line, this.model);
+        if (m.sessionId) this.sessionId = m.sessionId;
+        if (m.end) turnUsage = m.usage;
+        if (typeof m.textDelta === "string") {
+          sawText = true;
+          acc += m.textDelta;
+          this.emit({ type: "message_delta", text: m.textDelta });
+        }
+      }
+    };
+    child.stdout?.on("data", (b: Buffer) => consume(b.toString("utf8")));
+    let stderr = "";
+    child.stderr?.on("data", (b: Buffer) => {
+      stderr += b.toString("utf8");
+    });
+
+    await new Promise<void>((resolve) => {
+      const finish = (code: number | null, spawnErr?: string): void => {
+        this.current = null;
+        if (buf.trim().length > 0) consume("\n"); // flush trailing line
+        if (this.closed) return resolve();
+        if (spawnErr) {
+          this.emit({ type: "error", message: `grok spawn failed: ${spawnErr}` });
+        } else if (code !== 0) {
+          const tail = stderr.trim().slice(-500);
+          const message = `grok exited ${code ?? "null"}${tail ? `: ${tail}` : ""}`;
+          // Same path as Claude/Codex/OpenCode: a usage-cap / 429 error emits
+          // account_usage (source error-text) so the orchestrator can rotate.
+          const accountUsage = rateLimitErrorUsage(message);
+          if (accountUsage) {
+            this.emit({ type: "account_usage", usage: accountUsage });
+            this.emit({
+              type: "error",
+              message,
+              retryable: "rate_limit",
+              ...(accountUsage.resetsAt === undefined
+                ? {}
+                : { resetsAt: accountUsage.resetsAt }),
+            });
+          } else {
+            this.emit({ type: "error", message });
+          }
+        }
+        // Finalize the streamed message (no-op text if the turn produced none).
+        if (sawText) this.emit({ type: "message_complete", text: acc });
+        this.emit(
+          turnUsage
+            ? { type: "turn_complete", usage: turnUsage }
+            : { type: "turn_complete" },
+        );
+        resolve();
+      };
+      child.on("exit", (code) => finish(code));
+      child.on("error", (err) => finish(null, err.message));
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    this.current?.kill("SIGKILL");
+  }
+
+  // bypassPermissions auto-approves; no permission requests are emitted.
+  async resolvePermission(): Promise<void> {
+    /* no-op */
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.current?.kill("SIGKILL");
+    this.current = null;
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+register({
+  kind: "grok",
+  label: "Grok",
+  supportedModels: () => [...GROK_MODELS],
+  defaultModel: GROK_DEFAULT_MODEL,
+  supportedEfforts: () => [...GROK_EFFORTS],
+  available: () =>
+    existsSync(grokAuthPath()) || Boolean(process.env.XAI_API_KEY),
+  create: async ({ taskId, agent, environment, systemPreamble, agentEnv }) =>
+    new GrokSession({ taskId, agent, environment, systemPreamble, agentEnv }),
+});