march-cli 0.1.0

package/src/shell/tool-read.mjs

@@ -0,0 +1,74 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+
+export function createTerminalReadTool(shellRuntime) {
+  return defineTool({
+    name: "terminal_read",
+    label: "Terminal Read",
+    description: "Read plain-text output from a running interactive terminal. Use this for normal shell inspection after shell hints, terminal_list, or terminal_send.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn, terminal_list, or shell_hints" }),
+      source: Type.Optional(Type.String({ description: "screen (default), scrollback, or both" })),
+      lines: Type.Optional(Type.Number({ description: "Number of trailing lines to return. Default 80, max 300" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const snapshot = shellRuntime.snapshotShell(resolved.id);
+      const source = normalizeReadSource(params.source);
+      const lineLimit = normalizeLineLimit(params.lines);
+      const text = formatTerminalRead(snapshot, { source, lines: lineLimit });
+      return toolText(text, { shell: snapshot.shell, source, lines: lineLimit, snapshot });
+    },
+  });
+}
+
+function resolveShellId(shellRuntime, ref) {
+  const value = String(ref ?? "").trim();
+  const shells = shellRuntime.listShells();
+  const shell = shells.find((shell) => shell.id === value || shell.name === value);
+  if (shell) return { ok: true, id: shell.id, shell };
+  const available = shells.length
+    ? ` Active shells: ${shells.map((shell) => `${shell.id} (${shell.name})`).join(", ")}.`
+    : " No active shells.";
+  return { ok: false, error: `shell not found: ${value}.${available}` };
+}
+
+function normalizeReadSource(value) {
+  const normalized = String(value ?? "screen").trim().toLowerCase();
+  if (normalized === "scrollback") return "scrollback";
+  if (normalized === "both") return "both";
+  return "screen";
+}
+
+function normalizeLineLimit(value) {
+  const number = Math.trunc(Number(value) || 80);
+  return Math.min(300, Math.max(1, number));
+}
+
+function formatTerminalRead(snapshot, { source, lines }) {
+  const shell = snapshot.shell;
+  const header = [
+    `## ${shell.name} (${shell.id})`,
+    `status: ${shell.status}`,
+    `command: ${shell.command}${shell.args?.length ? ` ${shell.args.join(" ")}` : ""}`,
+    `cwd: ${shell.cwd}`,
+    `source: ${source}`,
+    `lines: ${lines}`,
+    "",
+  ].join("\n");
+  if (source === "both") {
+    return `${header}${formatReadSection("screen", snapshot.screen?.plain, lines)}\n\n${formatReadSection("scrollback", snapshot.plain, lines)}`;
+  }
+  const content = source === "scrollback" ? snapshot.plain : snapshot.screen?.plain;
+  return `${header}${lastLines(content, lines) || "(empty shell output)"}`;
+}
+
+function formatReadSection(label, text, lines) {
+  return `-- ${label} --\n${lastLines(text, lines) || "(empty shell output)"}`;
+}
+
+function lastLines(text, lines) {
+  return String(text ?? "").split(/\r?\n/).slice(-lines).join("\n").trimEnd();
+}

package/src/shell/tools.mjs

@@ -0,0 +1,299 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+import { createTerminalReadTool } from "./tool-read.mjs";
+
+export function createShellTools(shellRuntime = null, { platform = process.platform } = {}) {
+  if (!shellRuntime) return [];
+
+  const terminalSpawn = defineTool({
+    name: "terminal_spawn",
+    label: "Terminal Spawn",
+    description: "Start a named interactive terminal process. Omit command to start the platform default terminal. Use this for long-running or prompt-based commands, not one-shot commands.",
+    parameters: Type.Object({
+      name: Type.Optional(Type.String({ description: "Optional user-facing shell name" })),
+      command: Type.Optional(Type.String({ description: "Command to launch; omitted means platform default terminal" })),
+      args: Type.Optional(Type.Array(Type.String(), { description: "Command arguments" })),
+      cwd: Type.Optional(Type.String({ description: "Working directory" })),
+      cols: Type.Optional(Type.Number({ description: "Initial PTY columns" })),
+      rows: Type.Optional(Type.Number({ description: "Initial PTY rows" })),
+      if_exists: Type.Optional(Type.String({ description: "Name conflict behavior: reuse (default), replace, or new" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const shell = shellRuntime.spawnShell({
+        name: params.name,
+        command: params.command,
+        args: params.args ?? [],
+        cwd: params.cwd,
+        cols: params.cols,
+        rows: params.rows,
+        nameConflict: normalizeNameConflict(params.if_exists),
+      });
+      return toolText(formatShell(shell), { shell });
+    },
+  });
+
+  const terminalSend = defineTool({
+    name: "terminal_send",
+    label: "Terminal Send",
+    description: "Send text and/or a control key to a running interactive terminal. If both text and key are provided, the key is appended after the text. Set wait_for_idle=true after sending Enter when you need output. Enter is converted for the current platform; Windows PTYs use CRLF.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+      text: Type.Optional(Type.String({ description: "Text to type into the terminal. Include a newline (\\n/\\r) or combine with key:\"enter\" to execute a command. Newlines are converted to the platform Enter sequence; Windows PTYs use CRLF." })),
+      key: Type.Optional(Type.String({ description: "Named control key to send after text when text is provided: enter, ctrl_c, ctrl_d, ctrl_z, tab, escape, backspace" })),
+      wait_for_idle: Type.Optional(Type.Boolean({ description: "Wait until terminal output becomes idle and return the output delta; does not press Enter automatically; default false" })),
+      timeout_ms: Type.Optional(Type.Number({ description: "Maximum wait time when wait_for_idle=true, default 10000" })),
+      idle_ms: Type.Optional(Type.Number({ description: "Output idle time before returning when wait_for_idle=true, default 1000 after Enter, otherwise 300" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const shellId = resolved.id;
+      const before = params.wait_for_idle ? shellRuntime.snapshotShell(shellId) : null;
+      const text = normalizeShellToolInput(params.text, params.key, { platform });
+      const result = shellRuntime.sendShell(shellId, text);
+      if (!result.ok) return toolText(`Error: ${result.error}`, { error: true, shell: result.shell });
+      if (params.wait_for_idle) {
+        const submitted = text.includes("\r") || text.includes("\n");
+        const idle = await waitForShellIdle(shellRuntime, shellId, before, {
+          timeoutMs: params.timeout_ms,
+          idleMs: params.idle_ms ?? (submitted ? 1000 : 300),
+          submittedText: submitted ? text : "",
+        });
+        const output = idle.delta || idle.screenDelta || idle.snapshot.screen?.plain || idle.snapshot.plain || "(no output)";
+        return toolText(output, {
+          shell: idle.shell,
+          timedOut: idle.timedOut,
+          delta: idle.delta,
+          screenDelta: idle.screenDelta,
+          snapshot: idle.snapshot,
+        });
+      }
+      return toolText(`Sent ${text.length} chars to ${result.shell.name} (${result.shell.id}).`, { shell: result.shell });
+    },
+  });
+
+  const terminalList = defineTool({
+    name: "terminal_list",
+    label: "Terminal List",
+    description: "List active and recently exited interactive terminals.",
+    parameters: Type.Object({}),
+    execute: async () => {
+      const shells = shellRuntime.listShells();
+      if (!shells.length) return toolText("No shells.", { shells });
+      return toolText(shells.map(formatShell).join("\n"), { shells });
+    },
+  });
+
+  const terminalKill = defineTool({
+    name: "terminal_kill",
+    label: "Terminal Kill",
+    description: "Terminate a running interactive terminal.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const result = shellRuntime.killShell(resolved.id);
+      if (!result.ok) return toolText(`Error: ${result.error}`, { error: true, shell: result.shell });
+      return toolText(`Killed ${result.shell.name} (${result.shell.id}).`, { shell: result.shell });
+    },
+  });
+
+  const terminalResize = defineTool({
+    name: "terminal_resize",
+    label: "Terminal Resize",
+    description: "Resize an interactive terminal PTY.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+      cols: Type.Number({ description: "Columns" }),
+      rows: Type.Number({ description: "Rows" }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const result = shellRuntime.resizeShell(resolved.id, { cols: params.cols, rows: params.rows });
+      if (!result.ok) return toolText(`Error: ${result.error}`, { error: true, shell: result.shell });
+      return toolText(`Resized ${result.shell.name} (${result.shell.id}) to ${result.shell.cols}x${result.shell.rows}.`, result);
+    },
+  });
+
+  const terminalClear = defineTool({
+    name: "terminal_clear",
+    label: "Terminal Clear",
+    description: "Clear March's captured scrollback and screen snapshot for a terminal without terminating the process.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+    }),
+    execute: async (_toolCallId, params) => {
+      let result;
+      try {
+        const resolved = resolveShellId(shellRuntime, params.shell_id);
+        if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+        result = shellRuntime.clearShell(resolved.id);
+      } catch (error) {
+        return toolText(`Error: ${error?.message ?? String(error)}`, { error: true });
+      }
+      if (!result.ok) return toolText(`Error: ${result.error}`, { error: true, shell: result.shell });
+      return toolText(`Cleared ${result.shell.name} (${result.shell.id}).`, result);
+    },
+  });
+
+  const terminalSearch = defineTool({
+    name: "terminal_search",
+    label: "Terminal Search",
+    description: "Search a terminal's plain-text output. Defaults to visible screen first, then captured scrollback, while filtering prompt-only noise.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+      pattern: Type.String({ description: "Plain text to search for" }),
+      source: Type.Optional(Type.String({ description: "auto (default), screen, or scrollback" })),
+      include_prompts: Type.Optional(Type.Boolean({ description: "Include shell prompt/echo lines in results; default false" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const result = shellRuntime.searchShell(resolved.id, params.pattern, {
+        source: params.source,
+        includePrompts: params.include_prompts,
+      });
+      if (!result.matches.length) return toolText(`No matches in ${result.shell.name} (${result.shell.id}).`, result);
+      const lines = result.matches.map((match) => `${match.index + 1}: ${match.line}`);
+      return toolText(lines.join("\n"), result);
+    },
+  });
+
+  const terminalRead = createTerminalReadTool(shellRuntime);
+
+  const terminalSnapshot = defineTool({
+    name: "terminal_snapshot",
+    label: "Terminal Snapshot",
+    description: "Return the current terminal screen and scrollback as plain text and ANSI text for visual debugging.",
+    parameters: Type.Object({
+      shell_id: Type.String({ description: "Shell id or name returned by terminal_spawn or terminal_list" }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const resolved = resolveShellId(shellRuntime, params.shell_id);
+      if (!resolved.ok) return toolText(`Error: ${resolved.error}`, { error: true });
+      const snapshot = shellRuntime.snapshotShell(resolved.id);
+      const text = snapshot.screen?.plain || snapshot.plain || "(empty shell output)";
+      return toolText(text, snapshot);
+    },
+  });
+
+  return [terminalSpawn, terminalSend, terminalList, terminalKill, terminalResize, terminalClear, terminalSearch, terminalRead, terminalSnapshot];
+}
+
+function formatShell(shell) {
+  const args = shell.args?.length ? ` ${shell.args.join(" ")}` : "";
+  const lines = `${shell.visibleLineCount ?? 0} visible, ${shell.scrollbackLineCount ?? shell.lineCount ?? 0} captured`;
+  const error = shell.error ? `  error: ${shell.error}` : "";
+  return `${shell.id}  ${shell.name}  ${shell.status}  ${shell.command}${args}  ${lines}${error}`;
+}
+
+function resolveShellId(shellRuntime, ref) {
+  const value = String(ref ?? "").trim();
+  const shells = shellRuntime.listShells();
+  const shell = shells.find((shell) => shell.id === value || shell.name === value);
+  if (shell) return { ok: true, id: shell.id, shell };
+  const available = shells.length
+    ? ` Active shells: ${shells.map((shell) => `${shell.id} (${shell.name})`).join(", ")}.`
+    : " No active shells.";
+  return { ok: false, error: `shell not found: ${value}.${available}` };
+}
+
+function normalizeNameConflict(value) {
+  const normalized = String(value ?? "reuse").trim().toLowerCase();
+  if (normalized === "replace") return "replace";
+  if (normalized === "new" || normalized === "suffix") return "suffix";
+  return "reuse";
+}
+
+function normalizeShellToolInput(text, key, { platform = process.platform } = {}) {
+  const enter = enterSequenceForPlatform(platform);
+  const marker = "\0MARCH_ENTER\0";
+  const normalizedText = String(text ?? "")
+    .replace(/\\r\\n|\\n|\\r/g, marker)
+    .replace(/\r\n|\n|\r/g, marker)
+    .replaceAll(marker, enter);
+  return normalizedText + (key ? controlKeyToSequence(key, { platform }) : "");
+}
+
+function controlKeyToSequence(key, { platform = process.platform } = {}) {
+  const normalized = String(key ?? "").trim().toLowerCase().replace(/[-+ ]/g, "_");
+  const sequences = {
+    enter: enterSequenceForPlatform(platform),
+    ctrl_c: "\x03",
+    ctrl_d: "\x04",
+    ctrl_z: "\x1a",
+    tab: "\t",
+    escape: "\x1b",
+    esc: "\x1b",
+    backspace: "\x7f",
+  };
+  if (!sequences[normalized]) throw new Error(`unsupported shell key: ${key}`);
+  return sequences[normalized];
+}
+
+async function waitForShellIdle(shellRuntime, shellId, beforeSnapshot, { timeoutMs = 10000, idleMs = 300, submittedText = "" } = {}) {
+  const timeout = Math.max(1, Number(timeoutMs) || 10000);
+  const idle = Math.max(1, Number(idleMs) || 300);
+  const submitted = Boolean(submittedText);
+  const echoOnlyGraceMs = Math.min(timeout, 2500);
+  const screenOnlyGraceMs = Math.min(timeout, 2500);
+  const beforePlain = beforeSnapshot?.plain ?? "";
+  const beforeScreenPlain = beforeSnapshot?.screen?.plain ?? "";
+  const started = Date.now();
+  let lastPlain = beforePlain;
+  let lastScreenPlain = beforeScreenPlain;
+  let lastChanged = Date.now();
+  let snapshot = shellRuntime.snapshotShell(shellId);
+
+  for (;;) {
+    await sleep(50);
+    snapshot = shellRuntime.snapshotShell(shellId);
+    const plain = snapshot.plain;
+    const screenPlain = snapshot.screen?.plain ?? "";
+    const hasPlainChange = plain !== beforePlain;
+    const hasScreenChange = screenPlain !== beforeScreenPlain;
+    const delta = plain.startsWith(beforePlain) ? plain.slice(beforePlain.length).replace(/^\n/, "") : plain;
+    const screenDelta = screenPlain.startsWith(beforeScreenPlain) ? screenPlain.slice(beforeScreenPlain.length).replace(/^\n/, "") : screenPlain;
+    if (plain !== lastPlain || screenPlain !== lastScreenPlain) {
+      lastPlain = plain;
+      lastScreenPlain = screenPlain;
+      lastChanged = Date.now();
+    }
+    const elapsed = Date.now() - started;
+    const timedOut = elapsed >= timeout;
+    const echoOnly = submitted && hasPlainChange && isLikelyEchoOnlyDelta(delta, submittedText);
+    const changedEnough = hasPlainChange || (!submitted && hasScreenChange) || (submitted && hasScreenChange && elapsed >= screenOnlyGraceMs);
+    const echoOnlyAllowed = !echoOnly || elapsed >= echoOnlyGraceMs;
+    if (timedOut || (changedEnough && echoOnlyAllowed && Date.now() - lastChanged >= idle)) {
+      return {
+        shell: shellRuntime.getShell(shellId),
+        snapshot,
+        delta,
+        screenDelta,
+        timedOut,
+      };
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function enterSequenceForPlatform(platform) {
+  return platform === "win32" ? "\r\n" : "\r";
+}
+
+function isLikelyEchoOnlyDelta(delta, submittedText) {
+  const submitted = String(submittedText ?? "").replace(/[\r\n]+$/g, "").trim();
+  const lines = String(delta ?? "")
+    .split("\n")
+    .map((line) => line.replace(/\r/g, "").trim())
+    .filter(Boolean);
+  if (!submitted || lines.length !== 1) return false;
+  return lines[0] === submitted || lines[0].endsWith(submitted);
+}

package/src/supergrok/actions/image-generate.mjs

@@ -0,0 +1,60 @@
+import { DEFAULT_SUPERGROK_IMAGE_MODEL } from "../constants.mjs";
+import { readErrorMessage, successEnvelope } from "../response.mjs";
+import { saveGeneratedImageAttachment } from "../../session/attachments.mjs";
+
+const ASPECT_RATIOS = new Set(["1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16"]);
+const RESOLUTIONS = new Set(["1k", "2k"]);
+
+export async function runSuperGrokImageGenerate({ query, options = {}, credentials, projectMarchDir, fetchImpl = fetch } = {}) {
+  if (!projectMarchDir) throw new Error("projectMarchDir is required for SuperGrok image generation");
+  const model = String(options.model || DEFAULT_SUPERGROK_IMAGE_MODEL).trim() || DEFAULT_SUPERGROK_IMAGE_MODEL;
+  const aspectRatio = normalizeEnum(options.aspect_ratio, ASPECT_RATIOS, "1:1");
+  const resolution = normalizeEnum(options.resolution, RESOLUTIONS, "1k");
+  const response = await fetchImpl(`${credentials.baseUrl}/images/generations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${credentials.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "March-SuperGrok/0.1",
+    },
+    body: JSON.stringify({
+      model,
+      prompt: query,
+      aspect_ratio: aspectRatio,
+      resolution,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`SuperGrok image generation failed (${response.status}): ${await readErrorMessage(response)}`);
+  }
+
+  const payload = await response.json();
+  const first = payload.data?.[0] || {};
+  const b64 = first.b64_json || first.image_base64 || "";
+  const url = first.url || "";
+  if (!b64 && !url) throw new Error("xAI image response contained neither b64_json nor url");
+
+  const artifacts = [];
+  if (b64) {
+    const saved = saveGeneratedImageAttachment({ projectMarchDir, data: b64, mimeType: "image/png" });
+    artifacts.push({ type: "image", path: saved.path, marker: saved.marker, mimeType: "image/png" });
+  } else {
+    artifacts.push({ type: "image", url, mimeType: first.mime_type || "image/png" });
+  }
+
+  return successEnvelope({
+    credentialSource: credentials.credentialSource,
+    action: "image_generate",
+    model,
+    query,
+    artifacts,
+    extra: { aspect_ratio: aspectRatio, resolution },
+  });
+}
+
+function normalizeEnum(value, allowed, fallback) {
+  const normalized = String(value || fallback).trim();
+  if (!allowed.has(normalized)) return fallback;
+  return normalized;
+}

package/src/supergrok/actions/search.mjs

@@ -0,0 +1,78 @@
+import { DEFAULT_SUPERGROK_SEARCH_MODEL } from "../constants.mjs";
+import { extractInlineCitations, extractResponseText, readErrorMessage, successEnvelope } from "../response.mjs";
+
+const MAX_DOMAINS = 5;
+const MAX_HANDLES = 10;
+
+export async function runSuperGrokSearch({ action, query, options = {}, credentials, fetchImpl = fetch } = {}) {
+  const model = String(options.model || DEFAULT_SUPERGROK_SEARCH_MODEL).trim() || DEFAULT_SUPERGROK_SEARCH_MODEL;
+  const tool = action === "x_search" ? buildXSearchTool(options) : buildWebSearchTool(options);
+  const response = await fetchImpl(`${credentials.baseUrl}/responses`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${credentials.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "March-SuperGrok/0.1",
+    },
+    body: JSON.stringify({
+      model,
+      input: [{ role: "user", content: query }],
+      tools: [tool],
+      store: false,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`SuperGrok ${action} failed (${response.status}): ${await readErrorMessage(response)}`);
+  }
+
+  const payload = await response.json();
+  return successEnvelope({
+    credentialSource: credentials.credentialSource,
+    action,
+    model,
+    query,
+    answer: extractResponseText(payload),
+    citations: payload.citations || [],
+    inlineCitations: extractInlineCitations(payload),
+  });
+}
+
+function buildWebSearchTool(options) {
+  const allowed = normalizeList(options.allowed_domains, "allowed_domains", MAX_DOMAINS);
+  const excluded = normalizeList(options.excluded_domains, "excluded_domains", MAX_DOMAINS);
+  if (allowed.length && excluded.length) throw new Error("allowed_domains and excluded_domains cannot both be set");
+  const tool = {
+    type: "web_search",
+    enable_image_understanding: options.enable_image_understanding ?? true,
+  };
+  if (allowed.length) tool.filters = { allowed_domains: allowed };
+  if (excluded.length) tool.filters = { excluded_domains: excluded };
+  return tool;
+}
+
+function buildXSearchTool(options) {
+  const allowed = normalizeHandles(options.allowed_x_handles, "allowed_x_handles");
+  const excluded = normalizeHandles(options.excluded_x_handles, "excluded_x_handles");
+  if (allowed.length && excluded.length) throw new Error("allowed_x_handles and excluded_x_handles cannot both be set");
+  const tool = {
+    type: "x_search",
+    enable_image_understanding: options.enable_image_understanding ?? true,
+    enable_video_understanding: options.enable_video_understanding ?? true,
+  };
+  if (allowed.length) tool.allowed_x_handles = allowed;
+  if (excluded.length) tool.excluded_x_handles = excluded;
+  if (String(options.from_date || "").trim()) tool.from_date = String(options.from_date).trim();
+  if (String(options.to_date || "").trim()) tool.to_date = String(options.to_date).trim();
+  return tool;
+}
+
+function normalizeHandles(value, fieldName) {
+  return normalizeList(value, fieldName, MAX_HANDLES).map((handle) => handle.replace(/^@+/, "")).filter(Boolean);
+}
+
+function normalizeList(value, fieldName, max) {
+  const list = Array.isArray(value) ? value.map((item) => String(item || "").trim()).filter(Boolean) : [];
+  if (list.length > max) throw new Error(`${fieldName} supports at most ${max} entries`);
+  return list;
+}

package/src/supergrok/auth.mjs

@@ -0,0 +1,36 @@
+import {
+  SUPERGROK_OAUTH_PROVIDER_ID,
+  XAI_API_PROVIDER_ID,
+  XAI_BASE_URL,
+  XAI_OAUTH_COMPAT_PROVIDER_ID,
+} from "./constants.mjs";
+import { registerSuperGrokOAuthProvider } from "./oauth-provider.mjs";
+
+export async function resolveSuperGrokCredentials({ authStorage, baseUrl = XAI_BASE_URL } = {}) {
+  registerSuperGrokOAuthProvider();
+
+  for (const providerId of [SUPERGROK_OAUTH_PROVIDER_ID, XAI_OAUTH_COMPAT_PROVIDER_ID]) {
+    const apiKey = await authStorage?.getApiKey?.(providerId, { includeFallback: false });
+    if (apiKey) {
+      const credentials = authStorage?.get?.(providerId) ?? {};
+      return {
+        provider: "xai",
+        credentialSource: providerId,
+        apiKey,
+        baseUrl: String(credentials.baseUrl || baseUrl).replace(/\/$/, ""),
+      };
+    }
+  }
+
+  const apiKey = await authStorage?.getApiKey?.(XAI_API_PROVIDER_ID, { includeFallback: true });
+  if (apiKey) {
+    return {
+      provider: "xai",
+      credentialSource: XAI_API_PROVIDER_ID,
+      apiKey,
+      baseUrl: String(baseUrl).replace(/\/$/, ""),
+    };
+  }
+
+  throw new Error("No SuperGrok credentials available. Run: march login supergrok-oauth, or configure XAI_API_KEY / xai provider.");
+}

package/src/supergrok/constants.mjs

@@ -0,0 +1,18 @@
+export const SUPERGROK_OAUTH_PROVIDER_ID = "supergrok-oauth";
+export const XAI_OAUTH_COMPAT_PROVIDER_ID = "xai-oauth";
+export const XAI_API_PROVIDER_ID = "xai";
+
+export const XAI_BASE_URL = "https://api.x.ai/v1";
+export const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+export const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
+
+// Hermes/Grok CLI client id. xAI currently ties SuperGrok subscription access to this public client.
+export const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+export const XAI_OAUTH_REDIRECT_HOST = "127.0.0.1";
+export const XAI_OAUTH_REDIRECT_PORT = 56121;
+export const XAI_OAUTH_REDIRECT_PATH = "/callback";
+
+export const DEFAULT_SUPERGROK_MODEL = "grok-4.3";
+export const DEFAULT_SUPERGROK_SEARCH_MODEL = "grok-4.3";
+export const DEFAULT_SUPERGROK_IMAGE_MODEL = "grok-imagine-image";