cli.ts

#!/usr/bin/env node

/**
 * iris-agent CLI with ACP (Agent Client Protocol) support
 * Usage:
 *   iris-agent --acp
 *   iris-agent --workspace /path/to/workspace --modelId openrouter/openai/gpt-5.3-codex --chat
 */

import yargs from "yargs";
import { hideBin } from "yargs/helpers";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
import { createCodingAgent } from "./api/core/agent/index.js";
import { startAcpServer } from "./api/acp/acpServer.js";
import { getMissingProviderSetup } from "./api/core/library/providerSetup.js";
import { parseMcpServerConfigFile } from "./api/core/library/mcpSettings.js";
import {
  createCliChatUi,
  type CliChatUiMode,
  type CliChatTurnOutcome,
} from "./api/core/library/cliChatUi.js";
import { runCliChatTurn } from "./api/core/library/cliChatTurn.js";
import {
  buildConversationTurn,
  parseContextWindow,
  resolveModelContextBudget,
  resolvePromptTokenBudget,
} from "./api/helpers/promptBudget.js";
import { buildContextWindowStats } from "./api/helpers/tokenUsage.js";

const defaultModelId =
  process.env.MODEL_ID ||
  process.env.OPENROUTER_MODEL ||
  "openrouter/openai/gpt-5.3-codex";

const argv = yargs(hideBin(process.argv))
  .option("workspace", {
    alias: "w",
    type: "string",
    description: "Workspace root path",
    default: process.cwd(),
  })
  .option("acp", {
    alias: "a",
    type: "boolean",
    description: "Start ACP (Agent Client Protocol) server mode",
    default: false,
  })
  .option("chat", {
    alias: "c",
    type: "boolean",
    description: "Interactive chat mode",
    default: false,
  })
  .option("chat-ui", {
    choices: ["auto", "opentui", "plain"] as const,
    default: "auto",
    description: "Chat interface (auto uses OpenTUI on supported interactive terminals)",
  })
  .option("modelId", {
    type: "string",
    description: "Language model identifier",
    default: defaultModelId,
  })
  .option("context-window", {
    type: "string",
    description: "Override the model context window (for example, 100K)",
  })
  .option("observer-model", {
    type: "string",
    description: "Model used for observational memory (also enables observational memory)",
  })
  .option("mcp-config", {
    type: "string",
    description: "Path to a JSON file containing MCP server configuration (chat mode)",
  })
  .help()
  .parseSync();

async function main() {
  const workspaceRoot = argv.workspace as string;
  const modelId = argv.modelId;
  const contextWindow = argv.contextWindow
    ? parseContextWindow(argv.contextWindow)
    : undefined;
  const observerModelId = argv.observerModel;
  const observationalMemoryEnabled =
    contextWindow !== undefined || observerModelId !== undefined;
  const getContextMemoryOptions = (selectedModelId: string) => {
    if (!observationalMemoryEnabled) return {};
    // createCodingAgent derives the observation threshold from the effective
    // input budget and resolves the observer model through provider setup.
    return {
      useMastraObservationalMemory: true,
      observationalMemorySettings: {
        model: observerModelId || selectedModelId,
        scope: "thread" as const,
      },
    };
  };

  if (argv.mcpConfig && (!argv.chat || argv.acp)) {
    throw new Error("--mcp-config can only be used with --chat");
  }

  if (argv.acp) {
    const stderrLog = console.error.bind(console);
    console.log = stderrLog;
    console.debug = stderrLog;
    console.info = stderrLog;
    console.warn = stderrLog;
    console.dir = stderrLog;
    console.table = stderrLog;
    console.trace = stderrLog;
    console.group = stderrLog;
    console.groupCollapsed = stderrLog;
    console.groupEnd = stderrLog;
  }

  console.log(`🚀 Iris Agent CLI`);
  console.log(`📁 Workspace: ${workspaceRoot}`);
  console.log(`🤖 Model: ${modelId}`);

  if (argv.acp) {
    const missingProviderSetup = getMissingProviderSetup(modelId);
    if (missingProviderSetup) {
      console.error(missingProviderSetup);
      process.exitCode = 1;
      return;
    }
    console.log("🔗 Starting ACP server over stdio...");
    await startAcpServer(
      (requestedModelId, targetWorkspace) =>
        createCodingAgent(
          requestedModelId || modelId,
          targetWorkspace || workspaceRoot,
          {
            contextWindow,
            ...getContextMemoryOptions(requestedModelId || modelId),
          },
        ),
      workspaceRoot,
      modelId,
      {
        contextWindowTokens: contextWindow,
        useMastraObservationalMemory: observationalMemoryEnabled,
      },
    );
  } else if (argv.chat) {
    // Interactive chat mode
    const missingProviderSetup = getMissingProviderSetup(modelId, process.env, "chat");
    if (missingProviderSetup) {
      console.error(missingProviderSetup);
      process.exitCode = 1;
      return;
    }
    const mcpServers = argv.mcpConfig
      ? parseMcpServerConfigFile(
          await readFile(resolve(argv.mcpConfig), "utf8"),
        )
      : [];
    const agent = await createCodingAgent(modelId, workspaceRoot, {
      mcpServers,
      contextWindow,
      ...getContextMemoryOptions(modelId),
    });
    if (mcpServers.length > 0) {
      console.log(`🧩 MCP servers configured: ${mcpServers.length}`);
    }
    console.log(`💬 Entering chat mode (type "exit" to quit)`);
    await startChatMode(
      agent,
      workspaceRoot,
      modelId,
      argv["chat-ui"] as CliChatUiMode,
      contextWindow,
    );
  } else {
    // Default: show help
    yargs(hideBin(process.argv))
      .showHelp();
  }
}

/**
 * Extract a short, human-readable message from an error thrown by the agent
 * (including AI SDK `APICallError` instances from provider calls), instead of
 * dumping the full error object with headers, request/response bodies, and
 * stack traces to the terminal.
 */
function formatCliError(error: unknown): string {
  if (!error || typeof error !== "object") {
    return String(error);
  }

  const err = error as Record<string, unknown>;
  const parts: string[] = [];

  const baseMessage = typeof err.message === "string" ? err.message.trim() : "";
  if (baseMessage) {
    parts.push(baseMessage);
  }

  // AI SDK `APICallError` (and similar) expose statusCode/url/responseBody.
  // Surface a compact "(HTTP <code> from <url>)" suffix when available.
  const statusCode = typeof err.statusCode === "number" ? err.statusCode : undefined;
  const url = typeof err.url === "string" ? err.url : undefined;
  if (statusCode || url) {
    const location = [
      statusCode ? `HTTP ${statusCode}` : undefined,
      url ? `from ${url}` : undefined,
    ]
      .filter(Boolean)
      .join(" ");
    if (location) {
      parts.push(`(${location})`);
    }
  }

  // Try to pull a more specific message out of the provider's response body,
  // which is often more actionable than the generic AI SDK message.
  const providerMessage = extractProviderErrorMessage(err);
  if (providerMessage && providerMessage !== baseMessage) {
    parts.push(`- ${providerMessage}`);
  }

  if (parts.length === 0) {
    return error instanceof Error ? error.message : String(error);
  }

  const cause = (err as { cause?: unknown }).cause;
  const causeMessage =
    cause && cause !== error ? formatCliError(cause) : undefined;

  return causeMessage && !parts.join(" ").includes(causeMessage)
    ? `${parts.join(" ")} (caused by: ${causeMessage})`
    : parts.join(" ");
}

function extractProviderErrorMessage(
  err: Record<string, unknown>,
): string | undefined {
  const data = err.data as { error?: { message?: unknown } } | undefined;
  if (typeof data?.error?.message === "string") {
    return data.error.message;
  }

  const responseBody = err.responseBody;
  if (typeof responseBody === "string") {
    try {
      const parsed = JSON.parse(responseBody) as {
        error?: { message?: unknown };
      };
      if (typeof parsed?.error?.message === "string") {
        return parsed.error.message;
      }
    } catch {
      // responseBody wasn't JSON; ignore.
    }
  }

  return undefined;
}

/**
 * Produce an actionable one-line hint for common, recognizable failure
 * modes (bad model ID, missing/invalid API key, rate limiting, network
 * issues) so users aren't left staring at a raw provider error message.
 */
function getCliErrorHint(error: unknown, modelId?: string): string | undefined {
  if (!error || typeof error !== "object") {
    return undefined;
  }

  const err = error as Record<string, unknown>;
  const statusCode = typeof err.statusCode === "number" ? err.statusCode : undefined;
  const message = (
    (typeof err.message === "string" ? err.message : "") +
    " " +
    (extractProviderErrorMessage(err) || "")
  ).toLowerCase();
  const code = typeof err.code === "string" ? err.code : undefined;

  const modelHint = modelId ? ` (currently "${modelId}")` : "";

  if (
    statusCode === 404 &&
    (message.includes("no endpoints found") || message.includes("not found"))
  ) {
    return `💡 The model ID${modelHint} doesn't exist or isn't available from the provider. Double-check the spelling/provider prefix (e.g. "openrouter/anthropic/claude-sonnet-4.5") and pass a valid one via --modelId.`;
  }

  if (statusCode === 401 || message.includes("unauthorized") || message.includes("invalid api key")) {
    return "💡 Authentication failed. Check that the API key for this provider is set (e.g. OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) and hasn't expired.";
  }

  if (statusCode === 403) {
    return "💡 The request was forbidden. Your API key may lack access to this model or your account may need billing/credits set up.";
  }

  if (statusCode === 429 || message.includes("rate limit")) {
    return "💡 You've hit a rate limit or quota. Wait a moment and try again, or check your provider's usage/billing dashboard.";
  }

  if (statusCode && statusCode >= 500) {
    return "💡 The model provider is having issues on its end. Try again shortly, or switch to a different model/provider with --modelId.";
  }

  if (
    code === "ENOTFOUND" ||
    code === "ECONNREFUSED" ||
    code === "ETIMEDOUT" ||
    message.includes("fetch failed") ||
    message.includes("network")
  ) {
    return "💡 Couldn't reach the model provider. Check your internet connection (and any proxy/firewall settings) and try again.";
  }

  return undefined;
}

async function startChatMode(
  agent: any,
  workspaceRoot?: string,
  modelId?: string,
  mode: CliChatUiMode = "auto",
  contextWindow?: number,
) {
  const ui = await createCliChatUi({ mode, workspaceRoot, modelId });
  const threadId = `cli-chat-${Date.now()}`;
  const resourceId = "cli-session";

  try {
    while (true) {
      const input = await ui.readInput();
      if (input === null) break;
      const trimmedInput = input.trim();
      if (!trimmedInput) continue;
      if (["exit", "quit"].includes(trimmedInput.toLowerCase())) break;

      const controller = new AbortController();
      let outcome: CliChatTurnOutcome = "completed";
      ui.beginTurn(input, () => controller.abort());
      try {
        const modelContextBudget = await resolveModelContextBudget(
          modelId || defaultModelId,
          process.env,
          contextWindow,
        );
        const turn = await buildConversationTurn({
          // Preserve indentation and newlines in pasted code and multiline messages.
          currentMessage: input,
          maxPromptTokens: resolvePromptTokenBudget(
            modelContextBudget.inputTokens,
          ),
          maxConversationMessages: 12,
          maxConversationMessageTokens: 1_200,
        });
        const usage = await runCliChatTurn(agent, turn.prompt, {
          memory: { thread: threadId, resource: resourceId },
          maxSteps: 50,
          workspaceRoot,
        }, ui, controller.signal);
        if (usage) {
          ui.showContextStats?.(
            buildContextWindowStats(modelContextBudget, usage),
          );
        }
      } catch (error) {
        if (controller.signal.aborted) {
          outcome = "cancelled";
        } else {
          outcome = "failed";
          ui.showError(formatCliError(error), getCliErrorHint(error, modelId));
        }
      } finally {
        ui.finishTurn(outcome);
      }
    }
  } finally {
    ui.dispose();
  }
  console.log("👋 Goodbye!");
}

/**
 * Force-exit the process with the given code once pending stdout/stderr
 * writes have been flushed. This is needed because Mastra's Memory (LibSQL
 * store/vector) and provider HTTP clients can leave open handles behind
 * after a conversation, which would otherwise keep the event loop alive
 * indefinitely and make the CLI appear to hang after finishing its work.
 *
 * `process.exit()` on its own can truncate output when stdout/stderr are
 * piped or redirected, since writes to those streams are asynchronous in
 * that case. Writing an empty chunk and waiting for its callback ensures any
 * previously queued writes have actually been flushed before we exit.
 */
function exitAfterFlush(code: number): void {
  process.exitCode = code;

  let pending = 0;
  let settled = false;
  const finish = () => {
    pending -= 1;
    if (pending <= 0 && !settled) {
      settled = true;
      process.exit(code);
    }
  };

  for (const stream of [process.stdout, process.stderr]) {
    pending += 1;
    stream.write("", finish);
  }

  // Safety net in case a stream's callback never fires (e.g. it's already
  // closed) so the CLI doesn't hang waiting to exit.
  setTimeout(() => {
    if (!settled) {
      settled = true;
      process.exit(code);
    }
  }, 1000).unref();
}

main()
  .then(() => {
    // Preserve any non-zero exit code `main()` already set (e.g. for
    // missing provider setup) instead of always forcing a success exit.
    exitAfterFlush(process.exitCode ? Number(process.exitCode) : 0);
  })
  .catch((error) => {
    console.error(`❌ Fatal error: ${formatCliError(error)}`);
    const hint = getCliErrorHint(error);
    if (hint) {
      console.error(hint);
    }
    exitAfterFlush(1);
  });