march-cli 0.1.0

package/src/supergrok/oauth-provider.mjs

@@ -0,0 +1,278 @@
+import { createHash, randomBytes } from "node:crypto";
+import http from "node:http";
+import { registerOAuthProvider } from "@earendil-works/pi-ai/oauth";
+import {
+  SUPERGROK_OAUTH_PROVIDER_ID,
+  XAI_BASE_URL,
+  XAI_OAUTH_CLIENT_ID,
+  XAI_OAUTH_DISCOVERY_URL,
+  XAI_OAUTH_REDIRECT_HOST,
+  XAI_OAUTH_REDIRECT_PATH,
+  XAI_OAUTH_REDIRECT_PORT,
+  XAI_OAUTH_SCOPE,
+  XAI_OAUTH_COMPAT_PROVIDER_ID,
+} from "./constants.mjs";
+
+export function registerSuperGrokOAuthProvider() {
+  registerOAuthProvider(superGrokOAuthProvider);
+  registerOAuthProvider({ ...superGrokOAuthProvider, id: XAI_OAUTH_COMPAT_PROVIDER_ID });
+}
+
+export const superGrokOAuthProvider = {
+  id: SUPERGROK_OAUTH_PROVIDER_ID,
+  name: "SuperGrok OAuth (xAI Subscription)",
+  usesCallbackServer: true,
+  async login(callbacks) {
+    return loginSuperGrok(callbacks);
+  },
+  async refreshToken(credentials) {
+    return refreshSuperGrokToken(credentials);
+  },
+  getApiKey(credentials) {
+    return credentials.access;
+  },
+};
+
+async function loginSuperGrok(callbacks) {
+  const discovery = await discoverXaiOAuth();
+  const verifier = createCodeVerifier();
+  const challenge = createCodeChallenge(verifier);
+  const state = randomBytes(16).toString("hex");
+  const nonce = randomBytes(16).toString("hex");
+  const redirectUri = `http://${XAI_OAUTH_REDIRECT_HOST}:${XAI_OAUTH_REDIRECT_PORT}${XAI_OAUTH_REDIRECT_PATH}`;
+  const server = await startCallbackServer(state);
+  const authorizeUrl = buildAuthorizeUrl({
+    authorizationEndpoint: discovery.authorization_endpoint,
+    redirectUri,
+    codeChallenge: challenge,
+    state,
+    nonce,
+  });
+
+  callbacks.onAuth({
+    url: authorizeUrl,
+    instructions: `Complete the xAI authorization. Waiting for callback on ${redirectUri}`,
+  });
+
+  try {
+    let code = null;
+    if (callbacks.onManualCodeInput) {
+      let manualInput;
+      let manualError;
+      const manualPromise = callbacks.onManualCodeInput()
+        .then((input) => {
+          manualInput = input;
+          server.cancelWait();
+        })
+        .catch((err) => {
+          manualError = err instanceof Error ? err : new Error(String(err));
+          server.cancelWait();
+        });
+      const callback = await server.waitForCode();
+      if (manualError) throw manualError;
+      if (callback?.code) code = callback.code;
+      if (!code && manualInput) code = parseAuthorizationInput(manualInput, state).code;
+      if (!code) {
+        await manualPromise;
+        if (manualError) throw manualError;
+        if (manualInput) code = parseAuthorizationInput(manualInput, state).code;
+      }
+    } else {
+      const callback = await server.waitForCode();
+      if (callback?.code) code = callback.code;
+    }
+
+    if (!code) {
+      const input = await callbacks.onPrompt({ message: "Paste the xAI redirect URL or authorization code" });
+      code = parseAuthorizationInput(input, state).code;
+    }
+    if (!code) throw new Error("Missing xAI authorization code");
+
+    const token = await exchangeAuthorizationCode({
+      tokenEndpoint: discovery.token_endpoint,
+      code,
+      verifier,
+      redirectUri,
+    });
+    return normalizeTokenCredentials(token, {
+      tokenEndpoint: discovery.token_endpoint,
+      redirectUri,
+    });
+  } finally {
+    server.close();
+  }
+}
+
+async function discoverXaiOAuth(fetchImpl = fetch) {
+  const response = await fetchImpl(XAI_OAUTH_DISCOVERY_URL, { headers: { Accept: "application/json" } });
+  if (!response.ok) throw new Error(`xAI OIDC discovery failed (${response.status})`);
+  const data = await response.json();
+  const authorizationEndpoint = String(data.authorization_endpoint || "").trim();
+  const tokenEndpoint = String(data.token_endpoint || "").trim();
+  if (!authorizationEndpoint || !tokenEndpoint) throw new Error("xAI OIDC discovery missing endpoints");
+  validateXaiAuthEndpoint(authorizationEndpoint, "authorization_endpoint");
+  validateXaiAuthEndpoint(tokenEndpoint, "token_endpoint");
+  return { authorization_endpoint: authorizationEndpoint, token_endpoint: tokenEndpoint };
+}
+
+function buildAuthorizeUrl({ authorizationEndpoint, redirectUri, codeChallenge, state, nonce }) {
+  const url = new URL(authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", XAI_OAUTH_CLIENT_ID);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("scope", XAI_OAUTH_SCOPE);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("nonce", nonce);
+  url.searchParams.set("plan", "generic");
+  url.searchParams.set("referrer", "hermes-agent");
+  return url.toString();
+}
+
+async function exchangeAuthorizationCode({ tokenEndpoint, code, verifier, redirectUri, fetchImpl = fetch }) {
+  validateXaiAuthEndpoint(tokenEndpoint, "token_endpoint");
+  const response = await fetchImpl(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: XAI_OAUTH_CLIENT_ID,
+      code_verifier: verifier,
+    }),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`xAI token exchange failed (${response.status}): ${text || response.statusText}`);
+  }
+  return response.json();
+}
+
+export async function refreshSuperGrokToken(credentials, { fetchImpl = fetch } = {}) {
+  const refreshToken = credentials.refresh || credentials.refresh_token;
+  if (!refreshToken) throw new Error("SuperGrok OAuth is missing a refresh token");
+  const tokenEndpoint = String(credentials.tokenEndpoint || "").trim() || (await discoverXaiOAuth(fetchImpl)).token_endpoint;
+  validateXaiAuthEndpoint(tokenEndpoint, "token_endpoint");
+  const response = await fetchImpl(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: XAI_OAUTH_CLIENT_ID,
+      refresh_token: refreshToken,
+    }),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`xAI token refresh failed (${response.status}): ${text || response.statusText}`);
+  }
+  const token = await response.json();
+  return normalizeTokenCredentials(token, {
+    tokenEndpoint,
+    redirectUri: credentials.redirectUri,
+    previousRefresh: refreshToken,
+  });
+}
+
+function normalizeTokenCredentials(token, { tokenEndpoint, redirectUri, previousRefresh = "" } = {}) {
+  const access = String(token.access_token || token.access || "").trim();
+  const refresh = String(token.refresh_token || token.refresh || previousRefresh || "").trim();
+  if (!access) throw new Error("xAI token response missing access_token");
+  if (!refresh) throw new Error("xAI token response missing refresh_token");
+  const expiresIn = Number(token.expires_in || 3600);
+  return {
+    access,
+    refresh,
+    expires: Date.now() + Math.max(60, expiresIn) * 1000,
+    idToken: String(token.id_token || token.idToken || ""),
+    tokenType: String(token.token_type || token.tokenType || "Bearer"),
+    tokenEndpoint,
+    redirectUri,
+    baseUrl: XAI_BASE_URL,
+  };
+}
+
+function startCallbackServer(expectedState) {
+  let settle;
+  const waitForCodePromise = new Promise((resolve) => {
+    settle = resolve;
+  });
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://${XAI_OAUTH_REDIRECT_HOST}:${XAI_OAUTH_REDIRECT_PORT}`);
+    if (url.pathname !== XAI_OAUTH_REDIRECT_PATH) {
+      res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+      res.end("Callback route not found.");
+      return;
+    }
+    if (url.searchParams.get("state") !== expectedState) {
+      res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+      res.end("State mismatch.");
+      settle(null);
+      return;
+    }
+    const code = url.searchParams.get("code");
+    const error = url.searchParams.get("error");
+    if (!code && error) {
+      res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(`xAI authorization failed: ${error}`);
+      settle(null);
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end("SuperGrok authentication completed. You can close this window.");
+    settle({ code });
+  });
+  return new Promise((resolve) => {
+    server.listen(XAI_OAUTH_REDIRECT_PORT, XAI_OAUTH_REDIRECT_HOST, () => {
+      resolve({
+        close: () => server.close(),
+        cancelWait: () => settle(null),
+        waitForCode: () => waitForCodePromise,
+      });
+    }).on("error", () => {
+      settle(null);
+      resolve({ close: () => {}, cancelWait: () => settle(null), waitForCode: () => waitForCodePromise });
+    });
+  });
+}
+
+function parseAuthorizationInput(input, expectedState) {
+  const value = String(input || "").trim();
+  if (!value) return {};
+  try {
+    const url = new URL(value);
+    const state = url.searchParams.get("state") || undefined;
+    if (state && state !== expectedState) throw new Error("State mismatch");
+    return { code: url.searchParams.get("code") || undefined };
+  } catch (err) {
+    if (err.message === "State mismatch") throw err;
+  }
+  if (value.includes("code=")) {
+    const params = new URLSearchParams(value);
+    const state = params.get("state") || undefined;
+    if (state && state !== expectedState) throw new Error("State mismatch");
+    return { code: params.get("code") || undefined };
+  }
+  return { code: value };
+}
+
+function createCodeVerifier() {
+  return base64Url(randomBytes(32));
+}
+
+function createCodeChallenge(verifier) {
+  return base64Url(createHash("sha256").update(verifier).digest());
+}
+
+function base64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function validateXaiAuthEndpoint(value, field) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || !url.hostname.endsWith("x.ai")) {
+    throw new Error(`Invalid xAI OAuth ${field}: ${value}`);
+  }
+}

package/src/supergrok/provider.mjs

@@ -0,0 +1,36 @@
+import { DEFAULT_SUPERGROK_MODEL, SUPERGROK_OAUTH_PROVIDER_ID, XAI_BASE_URL, XAI_OAUTH_COMPAT_PROVIDER_ID } from "./constants.mjs";
+import { registerSuperGrokOAuthProvider, superGrokOAuthProvider } from "./oauth-provider.mjs";
+
+const GROK_MODELS = [
+  { id: "grok-4.3", name: "Grok 4.3", contextWindow: 1000000, maxTokens: 128000 },
+  { id: "grok-4.20-reasoning", name: "Grok 4.20 Reasoning", contextWindow: 2000000, maxTokens: 128000 },
+  { id: "grok-4.20-non-reasoning", name: "Grok 4.20 Non Reasoning", contextWindow: 2000000, maxTokens: 128000 },
+  { id: "grok-4.20-multi-agent", name: "Grok 4.20 Multi Agent", contextWindow: 2000000, maxTokens: 128000 },
+  { id: "grok-code-fast-1", name: "Grok Code Fast 1", contextWindow: 256000, maxTokens: 128000 },
+];
+
+export function registerSuperGrokProvider(modelRegistry) {
+  registerSuperGrokOAuthProvider();
+  if (!modelRegistry?.registerProvider) return;
+  for (const providerId of [SUPERGROK_OAUTH_PROVIDER_ID, XAI_OAUTH_COMPAT_PROVIDER_ID]) {
+    modelRegistry.registerProvider(providerId, {
+      name: providerId === SUPERGROK_OAUTH_PROVIDER_ID ? "SuperGrok OAuth (xAI Subscription)" : "xAI OAuth (SuperGrok compatible)",
+      baseUrl: XAI_BASE_URL,
+      api: "openai-responses",
+      oauth: { ...superGrokOAuthProvider, id: providerId },
+      models: GROK_MODELS.map((model) => ({
+        ...model,
+        api: "openai-responses",
+        baseUrl: XAI_BASE_URL,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        compat: { supportsLongCacheRetention: true },
+      })),
+    });
+  }
+}
+
+export function getDefaultSuperGrokModelId() {
+  return DEFAULT_SUPERGROK_MODEL;
+}

package/src/supergrok/response.mjs

@@ -0,0 +1,76 @@
+export function successEnvelope({ credentialSource, action, model, query, answer = "", citations = [], inlineCitations = [], artifacts = [], extra = {} }) {
+  return {
+    success: true,
+    provider: "xai",
+    credential_source: credentialSource,
+    action,
+    model,
+    query,
+    answer,
+    citations,
+    inline_citations: inlineCitations,
+    artifacts,
+    ...extra,
+  };
+}
+
+export function errorEnvelope({ credentialSource = null, action, model = null, query = "", error, errorType = "error" }) {
+  return {
+    success: false,
+    provider: "xai",
+    credential_source: credentialSource,
+    action,
+    model,
+    query,
+    error,
+    error_type: errorType,
+  };
+}
+
+export function extractResponseText(payload) {
+  const outputText = String(payload?.output_text || "").trim();
+  if (outputText) return outputText;
+
+  const parts = [];
+  for (const item of payload?.output || []) {
+    if (item?.type !== "message") continue;
+    for (const content of item.content || []) {
+      if (content?.type !== "output_text" && content?.type !== "text") continue;
+      const text = String(content.text || "").trim();
+      if (text) parts.push(text);
+    }
+  }
+  return parts.join("\n\n").trim();
+}
+
+export function extractInlineCitations(payload) {
+  const citations = [];
+  for (const item of payload?.output || []) {
+    if (item?.type !== "message") continue;
+    for (const content of item.content || []) {
+      for (const annotation of content.annotations || []) {
+        if (annotation?.type !== "url_citation") continue;
+        citations.push({
+          url: annotation.url || "",
+          title: annotation.title || "",
+          start_index: annotation.start_index,
+          end_index: annotation.end_index,
+        });
+      }
+    }
+  }
+  return citations;
+}
+
+export async function readErrorMessage(response) {
+  const text = await response.text().catch(() => "");
+  if (!text) return response.statusText || `HTTP ${response.status}`;
+  try {
+    const json = JSON.parse(text);
+    if (typeof json.error === "string") return json.code && !json.error.includes(json.code) ? `${json.code}: ${json.error}` : json.error;
+    if (json.error?.message) return json.error.message;
+    return JSON.stringify(json).slice(0, 500);
+  } catch {
+    return text.slice(0, 500);
+  }
+}

package/src/supergrok/tool.mjs

@@ -0,0 +1,61 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+import { resolveSuperGrokCredentials } from "./auth.mjs";
+import { runSuperGrokImageGenerate } from "./actions/image-generate.mjs";
+import { runSuperGrokSearch } from "./actions/search.mjs";
+import { errorEnvelope } from "./response.mjs";
+
+const ACTIONS = ["web_search", "x_search", "image_generate"];
+
+export function createSuperGrokTool({ authStorage, projectMarchDir, resolveCredentials = resolveSuperGrokCredentials, fetchImpl = fetch } = {}) {
+  return defineTool({
+    name: "supergrok",
+    label: "SuperGrok",
+    description:
+      "Use SuperGrok capabilities through xAI: realtime web search, X/Twitter search, and Grok image generation. " +
+      "Default search behavior is broad and enables image/video understanding where supported. Requires SuperGrok OAuth or XAI_API_KEY.",
+    promptSnippet: "supergrok(action, query, options?) - Use SuperGrok web_search, x_search, or image_generate",
+    promptGuidelines: [
+      "Use action=web_search for current web/news/documentation facts.",
+      "Use action=x_search for current X/Twitter posts, reactions, profiles, and threads.",
+      "Use action=image_generate when the user asks Grok/SuperGrok to create an image.",
+      "Do not add domain, handle, or date filters unless the user asks for that narrower scope.",
+    ],
+    parameters: Type.Object({
+      action: Type.String({ enum: ACTIONS, description: "SuperGrok capability to invoke" }),
+      query: Type.String({ description: "Search query or image prompt" }),
+      options: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Action-specific optional controls" })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const action = params.action;
+      const query = String(params.query || "").trim();
+      const options = params.options && typeof params.options === "object" ? params.options : {};
+      if (!ACTIONS.includes(action)) return toolJson(errorEnvelope({ action, query, error: `Unsupported SuperGrok action: ${action}`, errorType: "invalid_action" }), { error: true });
+      if (!query) return toolJson(errorEnvelope({ action, query, error: "query is required", errorType: "invalid_request" }), { error: true });
+
+      let credentials;
+      try {
+        credentials = await resolveCredentials({ authStorage });
+        const payload = action === "image_generate"
+          ? await runSuperGrokImageGenerate({ query, options, credentials, projectMarchDir, fetchImpl })
+          : await runSuperGrokSearch({ action, query, options, credentials, fetchImpl });
+        return toolJson(payload, payload);
+      } catch (err) {
+        const payload = errorEnvelope({
+          credentialSource: credentials?.credentialSource ?? null,
+          action,
+          model: options.model ?? null,
+          query,
+          error: err.message,
+          errorType: err.name || "error",
+        });
+        return toolJson(payload, { ...payload, error: true });
+      }
+    },
+  });
+}
+
+function toolJson(payload, details = {}) {
+  return toolText(JSON.stringify(payload, null, 2), details);
+}

package/src/text/ansi.mjs

@@ -0,0 +1,3 @@
+export function stripAnsi(text) {
+  return String(text ?? "").replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "");
+}

package/src/web/config-command.mjs

@@ -0,0 +1,43 @@
+import { createInterface } from "node:readline";
+import { selectWithKeyboard } from "../cli/input/select-with-keyboard.mjs";
+import { globalConfigJsonPath, upsertWebSearchProvider } from "../config/config-json.mjs";
+import { WEB_SEARCH_PRESETS } from "./presets.mjs";
+
+export async function runWebSearchConfigCommand({
+  homeDir,
+  input = process.stdin,
+  output = process.stdout,
+  select = selectWithKeyboard,
+  readSecret = readLine,
+} = {}) {
+  const preset = await select({
+    input,
+    output,
+    message: "Choose web search provider to configure",
+    items: WEB_SEARCH_PRESETS.map((item) => ({ label: item.label, value: item })),
+  });
+  if (!preset) {
+    output.write("Web search configuration cancelled.\n");
+    return 1;
+  }
+
+  const apiKey = String(await readSecret({ input, output, prompt: `${preset.apiKeyLabel}: ` }) ?? "").trim();
+  if (!apiKey) {
+    output.write("API key is required.\n");
+    return 1;
+  }
+
+  const path = globalConfigJsonPath(homeDir);
+  upsertWebSearchProvider({ path, id: preset.id, apiKey });
+  output.write(`Saved web search provider: ${preset.label}\n`);
+  output.write(`Config: ${path}\n`);
+  return 0;
+}
+
+function readLine({ input = process.stdin, output = process.stdout, prompt }) {
+  const rl = createInterface({ input, output });
+  return new Promise((resolve) => rl.question(prompt, (answer) => {
+    rl.close();
+    resolve(answer);
+  }));
+}

package/src/web/fetch.mjs

@@ -0,0 +1,78 @@
+/**
+ * Web fetch tool — fetches a URL and extracts readable content.
+ * No API key required. Uses basic HTML-to-text extraction.
+ */
+
+const MAX_CONTENT_LENGTH = 50_000;
+
+export async function fetchWebPage(url, { timeout = 15_000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "March/0.1 (web-fetch)",
+        Accept: "text/html,application/xhtml+xml,text/plain",
+      },
+      redirect: "follow",
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    }
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("text/html") && !contentType.includes("text/plain")) {
+      throw new Error(`Unsupported content type: ${contentType}`);
+    }
+
+    const raw = await res.text();
+    return extractText(raw, url);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function extractText(html, baseUrl) {
+  // Strip scripts, styles, and metadata
+  let text = html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<head[^>]*>[\s\S]*?<\/head>/gi, "")
+    .replace(/<noscript[^>]*>[\s\S]*?<\/noscript>/gi, "");
+
+  // Convert block elements to newlines
+  text = text.replace(/<\/(div|p|h[1-6]|li|tr|article|section|header|footer|nav|main|aside)[^>]*>/gi, "\n");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<\/?(div|p|h[1-6]|li|tr|article|section|header|footer|nav|main|aside)[^>]*>/gi, "");
+
+  // Strip remaining tags
+  text = text.replace(/<[^>]+>/g, "");
+
+  // Decode entities
+  text = text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ");
+
+  // Collapse whitespace
+  text = text.replace(/[ \t]+/g, " ");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  text = text.trim();
+
+  if (text.length > MAX_CONTENT_LENGTH) {
+    text = text.slice(0, MAX_CONTENT_LENGTH) + "\n\n...(content truncated)";
+  }
+
+  return {
+    text,
+    url: baseUrl,
+    length: text.length,
+    truncated: text.length >= MAX_CONTENT_LENGTH,
+  };
+}

package/src/web/presets.mjs

@@ -0,0 +1,16 @@
+export const WEB_SEARCH_PRESETS = [
+  {
+    id: "tavily",
+    label: "Tavily",
+    apiKeyLabel: "Tavily API key",
+  },
+  {
+    id: "brave",
+    label: "Brave Search",
+    apiKeyLabel: "Brave Search API key",
+  },
+];
+
+export function getWebSearchPreset(id) {
+  return WEB_SEARCH_PRESETS.find((preset) => preset.id === id) ?? null;
+}

package/src/web/search.mjs

@@ -0,0 +1,83 @@
+/**
+ * Web search tool — supports tavily and brave search APIs.
+ * Falls back gracefully if no API key is configured.
+ */
+
+const TAVILY_API = "https://api.tavily.com/search";
+
+export async function tavilySearch(query, apiKey, { maxResults = 5, searchDepth = "basic" } = {}) {
+  if (!apiKey) throw new Error("TAVILY_API_KEY not configured");
+
+  const res = await fetch(TAVILY_API, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      api_key: apiKey,
+      query,
+      max_results: maxResults,
+      search_depth: searchDepth,
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Tavily search failed (${res.status}): ${err.slice(0, 200)}`);
+  }
+
+  const data = await res.json();
+  return (data.results ?? []).map((r) => ({
+    title: r.title ?? "",
+    url: r.url ?? "",
+    snippet: r.content ?? "",
+    score: r.score ?? null,
+  }));
+}
+
+const BRAVE_API = "https://api.search.brave.com/res/v1/web/search";
+
+export async function braveSearch(query, apiKey, { maxResults = 5 } = {}) {
+  if (!apiKey) throw new Error("BRAVE_API_KEY not configured");
+
+  const res = await fetch(`${BRAVE_API}?q=${encodeURIComponent(query)}&count=${maxResults}`, {
+    headers: {
+      Accept: "application/json",
+      "Accept-Encoding": "gzip",
+      "X-Subscription-Token": apiKey,
+    },
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Brave search failed (${res.status}): ${err.slice(0, 200)}`);
+  }
+
+  const data = await res.json();
+  return (data.web?.results ?? []).map((r) => ({
+    title: r.title ?? "",
+    url: r.url ?? "",
+    snippet: r.description ?? "",
+  }));
+}
+
+/**
+ * Try available search providers in order.
+ * Returns { results, provider } or throws if none are configured.
+ */
+export async function searchWeb(query, { tavilyKey, braveKey, maxResults = 5 } = {}) {
+  if (tavilyKey) {
+    try {
+      const results = await tavilySearch(query, tavilyKey, { maxResults });
+      return { results, provider: "tavily" };
+    } catch (err) {
+      // Fall through to next provider
+      if (!braveKey) throw err;
+    }
+  }
+
+  if (braveKey) {
+    const results = await braveSearch(query, braveKey, { maxResults });
+    return { results, provider: "brave" };
+  }
+
+  throw new Error("No search API key configured. Run: march websearch --config");
+}