@hackerrank/astra-cli 0.1.0 → 0.1.1

package/src/cli.js

@@ -3,19 +3,42 @@
  * astra CLI — a minimal, zero-dependency AI coding agent for the
  * HackerRank AI Gateway.
  *
+ * Two modes:
+ *   agent  (default)  interactive SWE assistant — a chat REPL. Toggle to bench
+ *                     mode at any time with Alt+Tab.
+ *   bench             benchmark runner — runs a task autonomously in an isolated
+ *                     workspace and records metrics. Entered automatically when
+ *                     a task (-t/-f) or task path (-p) is provided.
+ *
  * Usage:
- *   astra -m <model>                       interactive assistant (chat REPL)
- *   astra -m <model> -t "<task text>"        autonomous task run
+ *   astra                                   agent mode (uses cached / prompted model)
+ *   astra -m <model>                       agent mode (interactive assistant)
+ *   astra -m <model> -t "<task text>"        bench run from task text
  *   astra -m <model> -f path/to/instruction.md
+ *   astra -m <model> -p tasks/dummy-slugify  bench run from a task directory
  *   astra --resume <session-id>             resume a saved session
  *   astra --sessions                        list saved sessions
  *
  * Options:
- *   -m, --model <id>        Model id on the gateway (required unless --sessions)
- *   -t, --task <text>       Task text -> autonomous mode (run to completion)
- *   -f, --task-file <path>  Read task text from a file -> autonomous mode
+ *   -m, --model <id>        Model id on the gateway (bench mode: required;
+ *                           comma-separated for a multi-model matrix, e.g.
+ *                           m1,m2,m3; agent mode: falls back to cached prefs,
+ *                           then a first-run picker, then glm-5.2)
+ *   -r, --reasoning <lvl>   Reasoning effort (e.g. off|low|medium|high;
+ *                           comma-separated to sweep levels in bench mode).
+ *                           Sent to the model and recorded in the bench name.
+ *       --repeat <n>        Attempts per (model,reasoning) in a matrix (1)
+ *       --push              After a matrix, tar bench/ and upload to
+ *                           s3://astra-bench-results/<timestamp>/
+ *       --push-uri <s3-uri> Override the S3 push destination
+ *       --tar               After a matrix, write a bench/ tarball locally
+ *   -t, --task <text>       Task text -> bench mode (run to completion)
+ *   -f, --task-file <path>  Read task text from a file -> bench mode
+ *   -p, --path <dir>        Task directory (copied into an isolated bench
+ *                           workspace) -> bench mode
+ *       --bench-root <dir>  Root folder for bench runs (default: ./bench)
  *   -C, --cwd <path>        Working directory for commands (default: cwd)
- *   -o, --output <path>     Also write trajectory JSON here (autonomous mode)
+ *   -o, --output <path>     Also write trajectory JSON here (bench mode)
  *   -s, --steps <n>         Step limit (default: 40)
  *   -w, --wall <seconds>    Wall-clock limit (default: 0 = none)
  *       --timeout <seconds> Per-command timeout (default: 60)
@@ -25,8 +48,8 @@
  *       --resume <id>       Resume a saved session by id
  *       --sessions          List saved sessions and exit
  *   -y, --yolo              Auto-run commands without confirmation
- *                           (always on in autonomous mode)
- *   -q, --quiet             Do not stream steps (autonomous mode)
+ *                           (always on in bench mode)
+ *   -q, --quiet             Do not stream steps (bench mode)
  *   -h, --help              Show this help
  *
  * API key resolution (first hit wins):
@@ -34,6 +57,13 @@
  *   2. ASTRA_GATEWAY_API_KEY env var
  *   3. ~/.astra/config.json (dedicated astra config)
  *   4. interactive prompt (when run in a terminal); offers to save to (3)
+ *
+ * Agent model resolution (agent mode, first hit wins):
+ *   1. --model / --reasoning flags
+ *   2. resumed session
+ *   3. cached agent prefs in ~/.astra/config.json (last model used)
+ *   4. first-run interactive setup (list pickers for model + reasoning)
+ *   5. fallback: glm-5.2 with medium reasoning
  */
 
 import fs from "node:fs";
@@ -41,7 +71,8 @@ import path from "node:path";
 import { GatewayModel } from "./model.js";
 import { LocalEnvironment } from "./environment.js";
 import { Agent } from "./agent.js";
-import { resolveCredentials, promptForCredentials, canPrompt } from "./config.js";
+import { resolveCredentials, promptForCredentials, canPrompt, readAgentPrefs, saveAgentPrefs, promptForAgentPrefs } from "./config.js";
+import { AVAILABLE_MODELS, REASONING_LEVELS, DEFAULT_MODEL, DEFAULT_REASONING } from "./models.js";
 import {
   newSessionId,
   saveSession,
@@ -51,6 +82,26 @@ import {
   deriveTitle,
 } from "./session.js";
 import { runRepl } from "./repl.js";
+import {
+  allocateRun,
+  seedWorkspace,
+  collectMetrics,
+  writeMetrics,
+  runMatrix,
+  aggregate,
+  packBench,
+  pushToS3,
+  defaultPushUri,
+  benchRoot,
+} from "./bench.js";
+
+/** Map a reasoning level to gateway modelKwargs. Empty for off/none/unset. */
+function reasoningKwargs(level) {
+  if (!level) return {};
+  const l = String(level).toLowerCase();
+  if (l === "off" || l === "none" || l === "disabled") return {};
+  return { reasoning_effort: l };
+}
 
 function parseArgs(argv) {
   const args = { steps: 40, wall: 0, timeout: 60, quiet: false, "max-output": 16000 };
@@ -58,6 +109,13 @@ function parseArgs(argv) {
     "-m": "model", "--model": "model",
     "-t": "task", "--task": "task",
     "-f": "task-file", "--task-file": "task-file",
+    "-p": "path", "--path": "path",
+    "-r": "reasoning", "--reasoning": "reasoning",
+    "--repeat": "repeat",
+    "--push": "push",
+    "--push-uri": "push-uri",
+    "--tar": "tar",
+    "--bench-root": "bench-root",
     "-C": "cwd", "--cwd": "cwd",
     "-o": "output", "--output": "output",
     "-s": "steps", "--steps": "steps",
@@ -72,7 +130,7 @@ function parseArgs(argv) {
     "-y": "yolo", "--yolo": "yolo",
     "-h": "help", "--help": "help",
   };
-  const flags = new Set(["quiet", "yolo", "help", "sessions"]);
+  const flags = new Set(["quiet", "yolo", "help", "sessions", "tar", "push"]);
   for (let i = 2; i < argv.length; i++) {
     const key = alias[argv[i]];
     if (!key) { console.error(`Unknown option: ${argv[i]}`); process.exit(2); }
@@ -107,17 +165,12 @@ async function main() {
     resumeDoc = loadSession(args.resume);
   }
 
-  const modelId = args.model || resumeDoc?.info?.model;
-  if (!modelId) {
-    console.error("\x1b[31m[astra] --model is required.\x1b[0m\n");
-    console.log(HELP);
-    process.exit(2);
-  }
-
-  // Task text (flag/file) selects autonomous mode; otherwise interactive.
+  // A task (-t/-f) or task path (-p) selects bench mode; otherwise agent mode.
+  // Bench mode uses the autonomous engine; agent mode uses the interactive one.
   let task = args.task;
   if (args["task-file"]) task = fs.readFileSync(args["task-file"], "utf8");
-  const mode = task
+  const wantsBench = !!(task || args.path);
+  const mode = wantsBench
     ? "autonomous"
     : resumeDoc?.info?.mode === "autonomous"
     ? "autonomous"
@@ -125,12 +178,13 @@ async function main() {
 
   if (mode === "interactive" && !canPrompt()) {
     console.error(
-      "\x1b[31m[astra] interactive mode needs a terminal. Provide a task with -t/-f\n" +
-        "to run autonomously, or run in a TTY.\x1b[0m"
+      "\x1b[31m[astra] agent mode needs a terminal. Provide a task with -t/-f/-p\n" +
+        "to run a bench, or run in a TTY.\x1b[0m"
     );
     process.exit(2);
   }
 
+  // -------------------- API KEY RESOLUTION --------------------
   let apiKey = resolveApiKey(args["api-key"], args["base-url"]);
   if (!apiKey) {
     if (canPrompt()) {
@@ -149,6 +203,69 @@ async function main() {
     }
   }
 
+  // -------------------- MODEL + REASONING RESOLUTION --------------------
+  // Bench (autonomous) mode: an explicit --model is required so runs are
+  // reproducible and never silently pick a cached/default model.
+  //
+  // Agent (interactive) mode: resolve in priority order
+  //   1. --model flag / --reasoning flag
+  //   2. resumed session
+  //   3. cached agent prefs in ~/.astra/config.json ("remember last model")
+  //   4. first-time interactive setup (list pickers for model + reasoning)
+  //   5. hard fallback: glm-5.2 with medium reasoning
+  // The chosen values are cached so the next `astra` needs no flags.
+  let modelId = args.model || resumeDoc?.info?.model;
+  let reasoning = args.reasoning || "";
+
+  if (mode === "autonomous") {
+    if (!modelId) {
+      console.error("\x1b[31m[astra] --model is required for bench mode.\x1b[0m\n");
+      console.log(HELP);
+      process.exit(2);
+    }
+
+    // Multi-model / multi-reasoning / repeated matrix. Triggered by a
+    // comma-separated model or reasoning list, or --repeat > 1. Runs each cell
+    // sequentially in its own isolated workspace, then prints a leaderboard and
+    // optionally tars + uploads the whole bench/ folder.
+    const models = String(modelId).split(",").map((s) => s.trim()).filter(Boolean);
+    const reasonings = reasoning
+      ? String(reasoning).split(",").map((s) => s.trim()).filter(Boolean)
+      : [""];
+    const repeat = Math.max(1, Number(args.repeat) || 1);
+    const isMatrix = models.length > 1 || reasonings.length > 1 || repeat > 1;
+
+    if (isMatrix && !resumeDoc) {
+      await runBenchMatrix({ args, apiKey, models, reasonings, repeat, task, quiet: !!args.quiet });
+      return; // runBenchMatrix exits the process
+    }
+  } else {
+    const cached = readAgentPrefs();
+    if (!modelId) modelId = cached.model;
+    if (!reasoning) reasoning = cached.reasoning;
+
+    if (!modelId) {
+      // No flag, no resume, no cache — run first-time setup (list pickers).
+      if (canPrompt()) {
+        const prefs = await promptForAgentPrefs({
+          defaultModel: DEFAULT_MODEL,
+          defaultReasoning: DEFAULT_REASONING,
+        });
+        modelId = prefs.model;
+        reasoning = reasoning || prefs.reasoning;
+      }
+    }
+
+    // Hard fallback if we still have nothing.
+    if (!modelId) {
+      modelId = DEFAULT_MODEL;
+      reasoning = reasoning || DEFAULT_REASONING;
+    }
+
+    // Remember the last model/reasoning used in agent mode.
+    saveAgentPrefs({ model: modelId, reasoning: reasoning || DEFAULT_REASONING });
+  }
+
   const cwd = args.cwd ? path.resolve(args.cwd) : process.cwd();
   const quiet = !!args.quiet;
 
@@ -156,10 +273,30 @@ async function main() {
     model: modelId,
     baseUrl: args["base-url"],
     apiKey,
+    modelKwargs: reasoningKwargs(reasoning),
     onRetry: quiet ? () => {} : (r) => printRetry(r),
   });
+
+  // -------------------- BENCH SETUP --------------------
+  // A fresh bench run (task text or task path, not a resume) gets an isolated
+  // workspace under bench/<model-name-reasoning>/run-NN/. The agent's commands
+  // run inside that workspace and metrics are recorded when it finishes.
+  let benchRun = null;
+  if (mode === "autonomous" && !resumeDoc) {
+    benchRun = allocateRun({ model: modelId, reasoning, root: args["bench-root"] });
+    const seeded = seedWorkspace(benchRun.workspace, {
+      taskPath: args.path,
+      taskFile: args["task-file"],
+      taskText: task,
+    });
+    task = seeded.taskText || task || "";
+    // Persist the task text alongside the run for reproducibility.
+    fs.writeFileSync(path.join(benchRun.dir, "task.md"), task || "");
+  }
+
+  const cmdCwd = benchRun ? benchRun.workspace : cwd;
   const env = new LocalEnvironment({
-    cwd,
+    cwd: cmdCwd,
     timeout: Number(args.timeout),
     maxOutputChars: Number(args["max-output"]),
   });
@@ -169,7 +306,11 @@ async function main() {
     mode,
     stepLimit: Number(args.steps),
     wallTimeLimitSeconds: Number(args.wall),
-    outputPath: args.output ? path.resolve(args.output) : null,
+    outputPath: benchRun
+      ? path.join(benchRun.dir, "trajectory.json")
+      : args.output
+      ? path.resolve(args.output)
+      : null,
     sessionId,
     saveSession,
     onEvent: quiet || mode === "interactive" ? () => {} : (msg) => printEvent(msg),
@@ -184,26 +325,67 @@ async function main() {
   // -------------------- INTERACTIVE MODE --------------------
   if (mode === "interactive") {
     if (!resumeDoc) agent.start();
-    agent.title = agent.title || "interactive";
-    await runRepl(agent, { model, autoRun: !!args.yolo, fresh: !resumeDoc });
+    agent.title = agent.title || "agent";
+    // Bench runner for the in-REPL Alt+Tab toggle: runs a task autonomously in
+    // an isolated workspace under bench/<model-name-reasoning>/run-NN/.
+    const runBench = async (taskText, log) => {
+      const alloc = allocateRun({ model: modelId, reasoning, root: args["bench-root"] });
+      seedWorkspace(alloc.workspace, { taskText });
+      fs.writeFileSync(path.join(alloc.dir, "task.md"), taskText || "");
+      log(`[astra] bench ${alloc.slug}/${alloc.runId} → ${alloc.workspace}`);
+      const benchEnv = new LocalEnvironment({
+        cwd: alloc.workspace,
+        timeout: Number(args.timeout),
+        maxOutputChars: Number(args["max-output"]),
+      });
+      const benchAgent = new Agent(model, benchEnv, {
+        mode: "autonomous",
+        stepLimit: Number(args.steps),
+        wallTimeLimitSeconds: Number(args.wall),
+        outputPath: path.join(alloc.dir, "trajectory.json"),
+      });
+      const res = await benchAgent.run(taskText);
+      const metrics = collectMetrics({ agent: benchAgent, model, reasoning });
+      const paths = writeMetrics({ runDir: alloc.dir, root: alloc.root, metrics });
+      log(`[astra] bench done: exit=${res.exit_status} · metrics → ${paths.runMetrics}`);
+    };
+    await runRepl(agent, { model, autoRun: !!args.yolo, fresh: !resumeDoc, reasoning, runBench });
     process.exit(0);
   }
 
-  // -------------------- AUTONOMOUS MODE --------------------
+  // -------------------- BENCH MODE (autonomous engine) --------------------
   if (!task && !resumeDoc) {
-    console.error("\x1b[31m[astra] provide a task with -t or -f.\x1b[0m");
+    console.error("\x1b[31m[astra] provide a task with -t, -f, or -p.\x1b[0m");
     process.exit(2);
   }
   if (task) agent.title = deriveTitle({ info: { task }, messages: [] });
 
   if (!quiet) {
-    console.error(`\x1b[2m[astra] autonomous · model=${modelId} cwd=${cwd} steps<=${args.steps}\x1b[0m`);
+    if (benchRun) {
+      console.error(
+        `\x1b[2m[astra] bench · ${benchRun.slug}/${benchRun.runId} ` +
+          `· model=${modelId}${reasoning ? ` reasoning=${reasoning}` : ""} steps<=${args.steps}\x1b[0m`
+      );
+      console.error(`\x1b[2m[astra] workspace -> ${benchRun.workspace}\x1b[0m`);
+    } else {
+      console.error(`\x1b[2m[astra] bench · model=${modelId} cwd=${cmdCwd} steps<=${args.steps}\x1b[0m`);
+    }
   }
 
   const result =
     resumeDoc && !task ? await continueAutonomous(agent) : await agent.run(task);
   agent.save();
 
+  // Record benchmark metrics (per-run CSV + rolled-up index).
+  if (benchRun) {
+    const metrics = collectMetrics({ agent, model, reasoning });
+    const paths = writeMetrics({ runDir: benchRun.dir, root: benchRun.root, metrics });
+    if (!quiet) {
+      console.error(`\x1b[2m[astra] metrics -> ${paths.runMetrics}\x1b[0m`);
+      console.error(`\x1b[2m[astra] index   -> ${paths.index}\x1b[0m`);
+    }
+  }
+
   if (!quiet) {
     const pt = model.totalPromptTokens;
     const ct = model.totalCompletionTokens;
@@ -229,6 +411,113 @@ async function main() {
   process.exit(result.exit_status === "Submitted" ? 0 : 1);
 }
 
+/**
+ * Run a multi-model / multi-reasoning / repeated bench matrix, print a
+ * leaderboard, optionally tar + upload the bench/ folder, then exit.
+ */
+async function runBenchMatrix({ args, apiKey, models, reasonings, repeat, task, quiet }) {
+  const root = args["bench-root"];
+  const total = models.length * reasonings.length * repeat;
+  console.error(
+    `\x1b[1m[astra] bench matrix · ${models.length} model(s) × ` +
+      `${reasonings.length} reasoning × ${repeat} repeat = ${total} run(s)\x1b[0m`
+  );
+
+  let n = 0;
+  const rows = await runMatrix({
+    models,
+    reasonings,
+    repeat,
+    apiKey,
+    baseUrl: args["base-url"],
+    task,
+    taskPath: args.path,
+    taskFile: args["task-file"],
+    root,
+    steps: Number(args.steps),
+    wall: Number(args.wall),
+    timeout: Number(args.timeout),
+    maxOutputChars: Number(args["max-output"]),
+    onStart: (c) => {
+      n++;
+      if (!quiet) {
+        console.error(`\x1b[36m[astra] (${n}/${total}) ${c.slug}/${c.runId} …\x1b[0m`);
+      }
+    },
+    onDone: (r) => {
+      const mark = r.resolved ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
+      const status = r.error ? `Error: ${r.error.split("\n")[0]}` : r.exit_status;
+      console.error(
+        `  ${mark} ${String(r.model).padEnd(20)} ${String(r.reasoning).padEnd(8)} ` +
+          `${String(status).padEnd(16)} ${String(r.steps).padStart(3)} steps · ` +
+          `${fmt(r.total_tokens)} tok · ${fmtUsd(r.cost_usd)}` +
+          `${r.cost_source === "estimated" ? "~" : ""}`
+      );
+    },
+  });
+
+  printLeaderboard(aggregate(rows));
+
+  const indexPath = path.join(benchRoot(root), "metrics.csv");
+
+  // Collect the important artifact locations to print together at the end.
+  const links = [["metrics", indexPath]];
+
+  // Tar + optional S3 push of the whole bench/ folder.
+  if (args.tar || args.push) {
+    try {
+      const tarball = packBench({ root });
+      links.push(["tarball", tarball]);
+      if (args.push) {
+        // Bare --push uses the default bucket + timestamp prefix; --push-uri
+        // overrides the destination.
+        const dest = args["push-uri"] || defaultPushUri();
+        try {
+          const pushed = pushToS3(tarball, dest);
+          links.push(["s3 uri", pushed.uri]);
+          links.push(["s3 url", pushed.url]);
+        } catch (err) {
+          console.error(`\x1b[31m[astra] S3 push failed: ${err.message}\x1b[0m`);
+          console.error(`\x1b[33m[astra] tarball kept locally: ${tarball}\x1b[0m`);
+        }
+      }
+    } catch (err) {
+      console.error(`\x1b[31m[astra] tar failed: ${err.message}\x1b[0m`);
+    }
+  }
+
+  const solved = rows.filter((r) => r.resolved).length;
+  console.error(`\n\x1b[1m[astra] matrix done · ${solved}/${rows.length} resolved\x1b[0m`);
+
+  // Print the important URLs / paths, aligned, at the very end.
+  const w = Math.max(...links.map(([k]) => k.length));
+  console.error("");
+  for (const [k, v] of links) {
+    console.error(`\x1b[1m  ${k.padEnd(w)}\x1b[0m  ${v}`);
+  }
+
+  process.exit(solved === rows.length ? 0 : 1);
+}
+
+/** Print the per-(model,reasoning) leaderboard table. */
+function printLeaderboard(board) {
+  board.sort((a, b) => b.solved_rate - a.solved_rate || a.avg_steps - b.avg_steps);
+  console.error(
+    `\n\x1b[1m${"model".padEnd(20)} ${"reason".padEnd(8)} ${"solved".padEnd(8)} ` +
+      `${"steps".padStart(6)} ${"tokens".padStart(9)}  ${"cost".padStart(9)}  source\x1b[0m`
+  );
+  for (const g of board) {
+    const solved = `${g.solved}/${g.runs}`;
+    const rate = `${Math.round(g.solved_rate * 100)}%`;
+    const cost = g.cost_usd == null ? "n/a" : fmtUsd(g.cost_usd);
+    console.error(
+      `${String(g.model).padEnd(20)} ${String(g.reasoning).padEnd(8)} ` +
+        `${(solved + " " + rate).padEnd(8)} ${g.avg_steps.toFixed(1).padStart(6)} ` +
+        `${fmt(Math.round(g.avg_tokens)).padStart(9)}  ${cost.padStart(9)}  ${g.cost_source}`
+    );
+  }
+}
+
 /** Drive an already-seeded autonomous agent to completion (used on resume). */
 async function continueAutonomous(agent) {
   while (true) {
@@ -259,11 +548,11 @@ function printSessions() {
 }
 
 function printEvent(msg) {
-  const c = { system: 90, user: 36, assistant: 33, exit: 35 }[msg.role] ?? 0;
-  if (msg.role === "system") return; // too long, skip
-  const label = msg.role.toUpperCase().padEnd(9);
-  const body = msg.content.length > 1200 ? msg.content.slice(0, 1200) + " …[truncated]" : msg.content;
-  console.error(`\x1b[${c}m--- ${label} ---\x1b[0m\n${body}\n`);
+  // Bench mode keeps output compact: skip the verbose system/user/assistant
+  // message bodies (per-step progress is shown by printStep). Only surface a
+  // non-empty terminal exit event so the run's submission is still visible.
+  if (msg.role !== "exit" || !msg.content?.trim()) return;
+  console.error(`\x1b[35m--- SUBMISSION ---\x1b[0m\n${msg.content}\n`);
 }
 
 /** Compact per-step status line with exact token usage from the API. */

package/src/config.js

@@ -17,6 +17,12 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
+import {
+  AVAILABLE_MODELS,
+  REASONING_LEVELS,
+  DEFAULT_MODEL,
+  DEFAULT_REASONING,
+} from "./models.js";
 
 export const DEFAULT_BASE_URL = "https://gateway-central.ai.private.hackerrank.link/v1";
 
@@ -54,6 +60,32 @@ export function saveGatewayCredentials({ apiKey, baseUrl }) {
   return configPath();
 }
 
+/**
+ * Save the last / preferred agent model + reasoning into the dedicated config
+ * (merging existing). Used so agent mode remembers the last model — users can
+ * then just run `astra` without `-m`.
+ */
+export function saveAgentPrefs({ model, reasoning } = {}) {
+  const cfg = readConfig();
+  cfg.agent = { ...(cfg.agent || {}) };
+  if (model) cfg.agent.model = model;
+  if (reasoning != null) cfg.agent.reasoning = reasoning;
+  writeConfig(cfg);
+  return configPath();
+}
+
+/**
+ * Resolve the cached / preferred agent model + reasoning from the dedicated
+ * config. Returns { model, reasoning } (either may be empty when unset).
+ */
+export function readAgentPrefs() {
+  const cfg = readConfig();
+  return {
+    model: cfg.agent?.model || "",
+    reasoning: cfg.agent?.reasoning || "",
+  };
+}
+
 /**
  * Resolve gateway credentials in priority order (no prompting):
  *   1. explicit args (CLI flags)
@@ -133,3 +165,49 @@ export async function promptForCredentials({ baseUrl } = {}) {
   }
   return { apiKey, baseUrl: effectiveBase };
 }
+
+/**
+ * Present a numbered list on the TTY and return the chosen item. Re-prompts on
+ * invalid input; returns the default (index 0 or `defaultValue`) on blank.
+ * @param {string} label
+ * @param {string[]} options
+ * @param {object} [opts]
+ * @param {string} [opts.defaultValue]  pre-selected value (defaults to options[0])
+ */
+export async function selectFromList(label, options, { defaultValue } = {}) {
+  if (!options || options.length === 0) return defaultValue || "";
+  const def = defaultValue && options.includes(defaultValue) ? defaultValue : options[0];
+  console.error(`\x1b[1m${label}\x1b[0m`);
+  for (let i = 0; i < options.length; i++) {
+    const marker = options[i] === def ? "\x1b[36m•\x1b[0m" : " ";
+    console.error(`  ${marker} ${String(i + 1).padStart(2)}) ${options[i]}`);
+  }
+  while (true) {
+    const answer = (await ask(`Select [1-${options.length}] (default: ${def}): `)).trim();
+    if (answer === "") return def;
+    const n = Number(answer);
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1];
+    // Allow typing the value directly too.
+    if (options.includes(answer)) return answer;
+    console.error("\x1b[31m[astra] Invalid choice, try again.\x1b[0m");
+  }
+}
+
+/**
+ * Interactive first-time setup for the agent's preferred model + reasoning.
+ * Both are chosen from a list (not free-text) and saved to the dedicated
+ * config so agent mode remembers them. Returns { model, reasoning }.
+ */
+export async function promptForAgentPrefs({ defaultModel, defaultReasoning } = {}) {
+  const model = await selectFromList("[astra] Choose your preferred model:", AVAILABLE_MODELS, {
+    defaultValue: defaultModel || DEFAULT_MODEL,
+  });
+  const reasoning = await selectFromList("[astra] Choose reasoning effort:", REASONING_LEVELS, {
+    defaultValue: defaultReasoning || DEFAULT_REASONING,
+  });
+  saveAgentPrefs({ model, reasoning });
+  console.error(
+    `\x1b[2m[astra] Saved model=${model} reasoning=${reasoning} to ${configPath()}\x1b[0m`
+  );
+  return { model, reasoning };
+}

package/src/model.js

@@ -55,6 +55,10 @@ export class GatewayModel {
     // Cumulative token usage across all calls (exact, from the API).
     this.totalPromptTokens = 0;
     this.totalCompletionTokens = 0;
+    this.totalReasoningTokens = 0;
+    this.totalCachedTokens = 0;
+    this.totalCacheWriteTokens = 0;
+    this.nRetries = 0;
     // Cumulative USD cost. `reported` = summed from the gateway's usage.cost;
     // `estimated` = summed from the public price table (prices.js).
     this.totalCostUsd = 0;
@@ -113,6 +117,7 @@ export class GatewayModel {
           // backoff (honoring Retry-After when the server provides it).
           if ((res.status === 429 || res.status >= 500) && attempt < this.maxRetries) {
             const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
+            this.nRetries++;
             this.onRetry({
               attempt: attempt + 1,
               maxRetries: this.maxRetries,
@@ -133,6 +138,9 @@ export class GatewayModel {
         const usage = normalizeUsage(data?.usage);
         this.totalPromptTokens += usage.prompt_tokens;
         this.totalCompletionTokens += usage.completion_tokens;
+        this.totalReasoningTokens += usage.reasoning_tokens || 0;
+        this.totalCachedTokens += usage.cached_tokens || 0;
+        this.totalCacheWriteTokens += usage.cache_write_tokens || 0;
         // Cost: prefer the gateway's exact number; otherwise estimate from the
         // public price table. Attach per-call cost + source to usage.
         const cost = this._accountCost(usage);
@@ -145,6 +153,7 @@ export class GatewayModel {
         // (auth, quota, context window) are re-thrown immediately.
         if (attempt < this.maxRetries && isRetryable(err)) {
           const wait = backoffMs(attempt);
+          this.nRetries++;
           this.onRetry({
             attempt: attempt + 1,
             maxRetries: this.maxRetries,

package/src/models.js

@@ -0,0 +1,31 @@
+/**
+ * Central catalog of gateway models and reasoning levels used by astra.
+ *
+ * Kept in one place so the CLI, interactive setup, and any list-based pickers
+ * stay in sync. The list mirrors the context-window table in repl.js.
+ */
+
+/** Selectable model ids on the gateway. */
+export const AVAILABLE_MODELS = [
+  "claude-opus-5",
+  "claude-sonnet-5",
+  "gemini-3.7-flash",
+  "gpt-5.6-luna",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "grok-4.6",
+  "deepseek-v4-pro",
+  "glm-5.2",
+  "kimi-k3",
+  "qwen-3.8",
+];
+
+/** Selectable reasoning-effort levels. */
+export const REASONING_LEVELS = ["off", "low", "medium", "high"];
+
+/**
+ * Ultimate fallback when no model is configured, cached, or chosen.
+ * (Requested behavior: fall back to glm-5.2 with medium reasoning.)
+ */
+export const DEFAULT_MODEL = "glm-5.2";
+export const DEFAULT_REASONING = "medium";

package/src/prompts.js

@@ -42,13 +42,17 @@ Autonomous mode:
   After that command you cannot continue.`;
 
 export const INTERACTIVE_RULES = `
-Interactive mode:
-- You are a helpful pair-programming assistant. Work with the user turn by turn.
+Agent mode (interactive SWE assistant):
+- You are astra, a sharp, pragmatic senior software engineer pair-programming
+  with the user in their shell. Be concise, direct, and technically precise.
+- Work turn by turn. Prefer small, verifiable steps over large speculative ones.
 - To run a shell command, use the bash block as described above.
 - To talk to the user (answer a question, ask for clarification, summarize, or
   report you are done) respond with plain text and NO bash block. That hands
   the turn back to the user.
-- Prefer small, verifiable steps. Do not fabricate command output.`;
+- Explain what you are about to do in one or two lines before acting.
+- Never fabricate command output; always run the command and react to what you
+  actually observe.`;
 
 export const INSTANCE_TEMPLATE = `Please complete this task: