@hackerrank/astra-cli 0.1.0 → 0.1.2

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;
@@ -63,6 +67,9 @@ export class GatewayModel {
     this.costSource = null; // "reported" | "estimated" | "mixed" | null
     // Preferred token-cap parameter; swapped automatically on 400 if needed.
     this._tokenParam = "max_tokens";
+    // Optional AbortSignal; when set and aborted, in-flight requests are
+    // cancelled (used to force-quit a long model call on a second Ctrl+C).
+    this.signal = null;
     if (!this.apiKey) {
       throw new Error(
         "GatewayModel: no API key. Set ASTRA_GATEWAY_API_KEY or configure ~/.astra/config.json."
@@ -96,6 +103,7 @@ export class GatewayModel {
             Authorization: `Bearer ${this.apiKey}`,
           },
           body: JSON.stringify(body),
+          signal: this.signal || undefined,
         });
 
         if (!res.ok) {
@@ -113,6 +121,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 +142,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 +157,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,
@@ -219,8 +232,10 @@ export class GatewayModel {
 
 function isRetryable(err) {
   // Never retry classified terminal errors (auth/quota/bad-request) or context
-  // overflow — those won't succeed on retry.
+  // overflow — those won't succeed on retry. Also never retry an aborted
+  // request (user force-quit via Ctrl+C).
   if (err instanceof GatewayError || err instanceof ContextWindowError) return false;
+  if (err?.name === "AbortError") return false;
   const msg = String(err?.message || err);
   return /HTTP 5\d\d|HTTP 429|ECONNRESET|ETIMEDOUT|fetch failed|network/i.test(msg);
 }

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:
 

package/src/repl.js

@@ -15,7 +15,8 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { ask } from "./config.js";
+import { ask, saveAgentPrefs } from "./config.js";
+import { AVAILABLE_MODELS, REASONING_LEVELS } from "./models.js";
 
 const C = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
@@ -55,9 +56,9 @@ function pkgVersion() {
 // ASCII wordmark (figlet "standard" style) shown when a new chat starts.
 const BANNER = [
   "              _                 ",
-  "  __ _  ___  | |_   __ __    __ _ ",
-  " / _` |/ __| | __| |__ __|  / _`  |",
-  "| (_| |\\__ \\ | |_  | |   | (_|  |",
+  "  __ _  ___  | |_   _ __   __ _ ",
+  " / _` |/ __| | __| | '__| / _` |",
+  "| (_| |\\__ \\ | |_  | |   | (_| |",
   " \\__,_||___/  \\__| |_|    \\__,_|",
 ];
 
@@ -131,13 +132,16 @@ function turnSummary({ turn, upTok, downTok, costUsd, costKind, seconds }) {
  * and cumulative token/context/cost usage. Returned as an array so the sticky
  * screen can pin them to the bottom rows.
  */
-function footerLines(agent, model, yolo) {
+function footerLines(agent, model, yolo, mode = "agent") {
   const cols = process.stdout.columns || 100;
-  const rule = "─".repeat(cols);
+  // Leave one cell of slack so a full-width rule never wraps to a new row
+  // (which pushes the whole footer up and looks broken on some terminals).
+  const rule = "─".repeat(Math.max(1, cols - 1));
 
-  const reasoning = model.modelKwargs?.reasoning_effort || model.modelKwargs?.reasoning?.effort;
+  const reasoning = model.modelKwargs?.reasoning_effort || model.modelKwargs?.reasoning?.effort || "off";
+  const modeTag = mode === "bench" ? C.yellow("◆ bench") : C.cyan("◆ agent");
   const modelBits = [`model: ${model.model}`];
-  if (reasoning) modelBits.push(`reasoning: ${reasoning}`);
+  modelBits.push(`reasoning: ${reasoning}`);
   modelBits.push(yolo ? "auto-run" : "approve");
 
   const up = model.totalPromptTokens;
@@ -152,16 +156,68 @@ function footerLines(agent, model, yolo) {
 
   return [
     C.dim(rule),
-    C.cyan(repoLabel()) + "    " + C.dim(modelBits.join("  ")),
+    modeTag + "  " + C.cyan(repoLabel()) + "    " + C.dim(modelBits.join("  ")),
     C.dim(usage),
+    C.dim("opt+left/right: model  ·  opt+up/down: reasoning  ·  shift+tab: mode"),
   ];
 }
 
-const FOOTER_LINES = 3; // divider + repo/model + usage
+const FOOTER_LINES = 4; // divider + repo/model + usage + shortcuts
 const PROMPT_PREFIX = C.green("› ");        // live input row (minimal)
 const HISTORY_PREFIX = C.green("you › ");   // echoed into transcript/history
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
+/**
+ * Recognize an Option/Alt + arrow key from a terminal input string.
+ * Returns "up" | "down" | "left" | "right" | null.
+ *
+ * Terminals encode these differently:
+ *   - xterm modifier form: ESC[1;3A/B/C/D  (3 = Alt/Option)
+ *   - meta word-move (iTerm2 default): ESC b (left word) / ESC f (right word)
+ *   - some send ESC ESC[A.. (double-ESC) for Alt+arrow
+ * When `latched` is true the leading ESC may already have been consumed, so we
+ * also accept the tails without the leading ESC.
+ */
+function matchOptionArrow(s, latched = false) {
+  const arrows = { A: "up", B: "down", C: "right", D: "left" };
+  // xterm modifier form with Alt (mod code 3) or Meta (mod code 9).
+  let m = s.match(/^\x1b\[1;(?:3|9)([ABCD])$/);
+  if (m) return arrows[m[1]];
+  // Double-ESC form: ESC ESC [ A..
+  m = s.match(/^\x1b\x1b\[([ABCD])$/);
+  if (m) return arrows[m[1]];
+  // Meta word-move: ESC b / ESC f -> treat as left/right (model cycling).
+  if (s === "\x1bb") return "left";
+  if (s === "\x1bf") return "right";
+  if (latched) {
+    // Leading ESC already latched; match the tail we reconstructed as ESC+tail.
+    m = s.match(/^\x1b\[1;(?:3|9)([ABCD])$/); // (handled above, kept for clarity)
+    if (m) return arrows[m[1]];
+    if (s === "\x1bb") return "left";
+    if (s === "\x1bf") return "right";
+  }
+  return null;
+}
+
+/** Read the model's current reasoning-effort level ("off" when unset). */
+function currentReasoning(model) {
+  const eff = model.modelKwargs?.reasoning_effort || model.modelKwargs?.reasoning?.effort;
+  return eff || "off";
+}
+
+/** Apply a reasoning-effort level to the live model's request kwargs. */
+function setReasoning(model, level) {
+  model.modelKwargs = { ...(model.modelKwargs || {}) };
+  const l = String(level || "").toLowerCase();
+  if (!l || l === "off" || l === "none" || l === "disabled") {
+    delete model.modelKwargs.reasoning_effort;
+    delete model.modelKwargs.reasoning;
+  } else {
+    model.modelKwargs.reasoning_effort = l;
+    delete model.modelKwargs.reasoning;
+  }
+}
+
 /**
  * A bottom-anchored screen: conversation output scrolls in the top region
  * (bounded by a DECSTBM scroll margin) while the footer + input prompt stay
@@ -189,8 +245,7 @@ class Screen {
     this._onResize = this._onResize.bind(this);
   }
 
-  get rows() { return this.out.rows || 24; }
-  // Footer block (4 rows) pinned to the bottom: divider, prompt, repo/model, usage.
+  get rows() { return this.out.rows || 24; }  // Footer block (4 rows) pinned to the bottom: divider, prompt, repo/model, usage.
   get reserved() { return FOOTER_LINES + 1; } // +1 for the prompt row
   get scrollBottom() { return Math.max(1, this.rows - this.reserved); } // last scrollable row
   get footerTop() { return this.scrollBottom + 1; } // divider row
@@ -216,6 +271,12 @@ class Screen {
     this.out.write(`\x1b[${this.rows};1H\n`);    // move below footer
   }
 
+  /** Cancel any pending lone-ESC latch/timer. */
+  _clearEscLatch() {
+    this._pendingEsc = false;
+    clearTimeout(this._escTimer);
+  }
+
   /** Write a block of text into the scrolling region (may contain newlines). */
   log(text) {
     this.out.write(`\x1b[${this.scrollBottom};1H`); // park at bottom of scroll area
@@ -278,6 +339,11 @@ class Screen {
     this.drawPrompt();
   }
 
+  /** True while the agent is working (a turn is in progress). */
+  isBusy() {
+    return this._busy || this._busyResume;
+  }
+
   /**
    * Resolve with the next full line the user types. An optional prompt label
    * replaces the default "you › " (used by the approval gate so the question
@@ -312,6 +378,86 @@ class Screen {
   }
 
   _onData(chunk) {
+    const s = chunk.toString();
+    // Optional key debug: set ASTRA_KEYDEBUG=1 to print the raw bytes of every
+    // keypress into the transcript. Use it to discover what your terminal
+    // actually sends for Option/Alt+Tab, then report it.
+    if (process.env.ASTRA_KEYDEBUG && this.log) {
+      const bytes = Array.from(chunk).map((b) => "0x" + b.toString(16).padStart(2, "0")).join(" ");
+      this.log(`\x1b[35m[keydebug] ${bytes}\x1b[0m`);
+    }
+    // --- Key sequences: mode toggle, model/reasoning cycling, Esc-to-clear ---
+    //
+    // Mode toggle: Alt/Option+Tab is delivered as ESC+Tab ("\x1b\t"); Shift+Tab
+    // ("\x1b[Z") is a reliable fallback. Model/reasoning cycling uses Option +
+    // arrow keys. A bare Esc (nothing following it) clears the input line.
+    //
+    // Because some terminals split escape sequences across reads (a lone ESC,
+    // then the rest), we latch a lone ESC briefly. If a Tab follows -> toggle;
+    // if nothing follows within the window -> treat it as bare Esc (clear).
+
+    // Whole-chunk fast paths first.
+    if (this.onToggleMode && (s === "\x1b\t" || s === "\x1b[Z")) {
+      this._clearEscLatch();
+      this.onToggleMode();
+      return;
+    }
+    {
+      const opt = matchOptionArrow(s, false);
+      if (opt) {
+        this._clearEscLatch();
+        if ((opt === "left" || opt === "right") && this.onCycleModel) {
+          this.onCycleModel(opt === "right" ? 1 : -1);
+          return;
+        }
+        if ((opt === "up" || opt === "down") && this.onCycleReasoning) {
+          this.onCycleReasoning(opt === "up" ? 1 : -1);
+          return;
+        }
+        return; // recognized an option-arrow we don't act on; swallow it
+      }
+    }
+
+    // A Tab following a latched ESC -> mode toggle (split Alt+Tab delivery).
+    if (this._pendingEsc && s === "\t" && this.onToggleMode) {
+      this._clearEscLatch();
+      this.onToggleMode();
+      return;
+    }
+    // A latched ESC followed by an arrow tail (e.g. "[C", "b", "f") -> option-arrow.
+    if (this._pendingEsc) {
+      const opt = matchOptionArrow("\x1b" + s, true);
+      if (opt) {
+        this._clearEscLatch();
+        if ((opt === "left" || opt === "right") && this.onCycleModel) {
+          this.onCycleModel(opt === "right" ? 1 : -1);
+          return;
+        }
+        if ((opt === "up" || opt === "down") && this.onCycleReasoning) {
+          this.onCycleReasoning(opt === "up" ? 1 : -1);
+          return;
+        }
+        return;
+      }
+      // Any other input right after a latched ESC cancels the latch and is
+      // processed normally below.
+      this._clearEscLatch();
+    }
+
+    // A lone ESC: latch briefly to disambiguate from split escape sequences.
+    // If nothing arrives, the timer treats it as a bare Esc and clears input.
+    if (s === "\x1b") {
+      this._pendingEsc = true;
+      clearTimeout(this._escTimer);
+      this._escTimer = setTimeout(() => {
+        this._pendingEsc = false;
+        if (this.onClearInput) this.onClearInput();
+        this.buf = "";
+        this.drawPrompt();
+      }, 60);
+      return;
+    }
+
     for (const ch of chunk) {
       if (ch === "\r" || ch === "\n") {
         // Collapse a CRLF pair into one Enter: ignore a \n right after a \r.
@@ -348,8 +494,12 @@ class Screen {
         this.buf = this.buf.slice(0, -1);
         this.drawPrompt();
       } else if (ch === "\x03") {                  // Ctrl+C
+        // If a prompt is pending (idle), resolve it so the loop can react.
+        // Also always notify the interrupt hook so a *running* agent turn can
+        // be aborted even when no readLine is pending.
         const r = this.resolve; this.resolve = null;
         if (r) r("__SIGINT__");
+        if (this.onInterrupt) this.onInterrupt();
       } else if (ch === "\x04") {                  // Ctrl+D
         const r = this.resolve; this.resolve = null;
         if (r) r("__EOF__");
@@ -370,24 +520,32 @@ Interactive commands:
   /history         print the message history
   /tokens          show token usage so far
   /yolo            toggle auto-run of commands (no confirmation)
+
+Keyboard shortcuts:
+  alt/opt+tab      switch agent / bench mode (shift+tab also works)
+  opt+left/right   cycle the model
+  opt+up/down      cycle reasoning effort (off/low/medium/high)
+  esc              clear the input line
 `;
 
 /**
  * Run the interactive loop against a prepared Agent.
  * @param {Agent} agent  a started (or restored) agent in interactive mode
- * @param {object} opts  { model, autoRun }
+ * @param {object} opts  { model, autoRun, fresh, reasoning, runBench }
+ *   runBench(taskText, log) => Promise  optional; invoked when the user submits
+ *     a message while the REPL is toggled to bench mode. Should run the task in
+ *     an isolated bench workspace and record metrics.
  */
-export async function runRepl(agent, { model, autoRun = false, fresh = true } = {}) {
+export async function runRepl(agent, { model, autoRun = false, fresh = true, reasoning = "", runBench = null } = {}) {
   let yolo = autoRun;
   const tty = !!process.stdout.isTTY && !!process.stdin.isTTY;
 
   const intro = fresh
     ? bannerLines({ session: agent.sessionId })
     : [C.dim(`[astra] resumed session ${agent.sessionId} · model=${model.model}`)];
-  intro.push(C.dim(`Type a request, or /help. Commands ${yolo ? "auto-run" : "need approval"}.`));
 
   if (tty) {
-    await runStickyRepl(agent, model, yolo, intro);
+    await runStickyRepl(agent, model, yolo, intro, { runBench });
   } else {
     for (const line of intro) console.error(line);
     await runPlainRepl(agent, model, yolo);
@@ -395,10 +553,65 @@ export async function runRepl(agent, { model, autoRun = false, fresh = true } =
 }
 
 /** Sticky bottom-anchored REPL (real terminals). */
-async function runStickyRepl(agent, model, yolo, intro = []) {
+async function runStickyRepl(agent, model, yolo, intro = [], { runBench = null } = {}) {
   const screen = new Screen();
   const log = (text) => screen.log(text);
-  const refresh = () => screen.refresh(footerLines(agent, model, yolo));
+  let mode = "agent"; // "agent" | "bench"
+  const refresh = () => screen.refresh(footerLines(agent, model, yolo, mode));
+
+  // Alt/Option+Tab (or Shift+Tab) toggles between agent and bench mode.
+  screen.onToggleMode = () => {
+    mode = mode === "agent" ? "bench" : "agent";
+    refresh();
+  };
+
+  // Option+Left/Right cycles the model; Option+Up/Down cycles reasoning effort.
+  // Changes apply to the live model and are cached as the preferred agent
+  // prefs so the next `astra` launch reuses them.
+  screen.onCycleModel = (dir) => {
+    const list = AVAILABLE_MODELS;
+    const cur = list.indexOf(model.model);
+    const next = ((cur === -1 ? 0 : cur) + dir + list.length) % list.length;
+    model.model = list[next];
+    saveAgentPrefs({ model: model.model });
+    refresh();
+  };
+  screen.onCycleReasoning = (dir) => {
+    const list = REASONING_LEVELS;
+    const cur = list.indexOf(currentReasoning(model));
+    const next = ((cur === -1 ? 0 : cur) + dir + list.length) % list.length;
+    setReasoning(model, list[next]);
+    saveAgentPrefs({ reasoning: list[next] });
+    refresh();
+  };
+  // Bare Esc clears the current input line (handled by the screen; nothing
+  // extra needed here, but expose a hook for symmetry / future use).
+  screen.onClearInput = () => {};
+
+  // Ctrl+C handling. In raw mode Ctrl+C does NOT raise SIGINT — it arrives as
+  // a byte, so we handle it explicitly. The screen's key handler already
+  // resolves any pending readLine with "__SIGINT__" (idle case); here we only
+  // deal with the *busy* case where no readLine is pending:
+  //   - first Ctrl+C while working -> request an abort after the current step
+  //   - second Ctrl+C while working -> force an immediate quit
+  const interrupt = { aborted: false, quit: false };
+  screen.onInterrupt = () => {
+    if (!screen.isBusy()) {
+      // Idle: the readLine resolver was already fired with "__SIGINT__", which
+      // breaks the loop and quits gracefully. Nothing more to do here.
+      return;
+    }
+    if (interrupt.aborted) {
+      // Second Ctrl+C while working -> force quit: abort the in-flight model
+      // request so a long call unblocks immediately.
+      interrupt.quit = true;
+      log(C.red("[astra] force quitting…"));
+      if (model._abort) { try { model._abort.abort(); } catch {} }
+      return;
+    }
+    interrupt.aborted = true;
+    log(C.yellow("[astra] interrupting… (press Ctrl+C again to force quit)"));
+  };
 
   // Approval gate: show the command, then ask for y/n/a on the prompt row.
   agent.confirm = async (command) => {
@@ -436,13 +649,50 @@ async function runStickyRepl(agent, model, yolo, intro = []) {
 
       const before = usageSnapshot(model);
       const t0 = Date.now();
+
+      // Bench mode: run the message as an autonomous task in an isolated
+      // workspace, record metrics, then drop back to agent mode.
+      if (mode === "bench") {
+        if (!runBench) {
+          log(C.red("[astra] bench runner unavailable in this session."));
+          mode = "agent"; refresh(); continue;
+        }
+        screen.startBusy("benching");
+        interrupt.aborted = false;
+        try {
+          await runBench(line, log);
+        } catch (err) {
+          log(C.red(`[astra] bench failed: ${err?.message || err}`));
+        } finally {
+          screen.stopBusy();
+        }
+        if (interrupt.quit) break;
+        mode = "agent";
+        refresh();
+        continue;
+      }
+
       agent.addUserMessage(line);
+      interrupt.aborted = false; // reset per turn
+      // Fresh AbortController for this turn so a force-quit can cancel an
+      // in-flight model request. Cleared in `finally`.
+      model._abort = new AbortController();
+      model.signal = model._abort.signal;
       screen.startBusy("working");
       try {
-        await driveUntilChat(agent, log);
+        await driveUntilChat(agent, log, interrupt);
+      } catch (err) {
+        if (err?.name === "AbortError" || interrupt.quit) {
+          // Force-quit path: swallow the abort and fall through to break.
+        } else {
+          throw err;
+        }
       } finally {
         screen.stopBusy();
+        model.signal = null;
+        model._abort = null;
       }
+      if (interrupt.quit) break; // force-quit requested via a second Ctrl+C
       const after = usageSnapshot(model);
       log(
         turnSummary({
@@ -536,10 +786,16 @@ function usageSnapshot(model) {
 
 /**
  * Take turns until the agent produces a chat reply (or terminates). Commands
- * run in between; their output goes back to the model automatically.
+ * run in between; their output goes back to the model automatically. If an
+ * `interrupt` signal is provided, the loop stops cleanly between turns when
+ * `interrupt.aborted` becomes true (Ctrl+C while working).
  */
-async function driveUntilChat(agent, log) {
+async function driveUntilChat(agent, log, interrupt = null) {
   while (true) {
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] interrupted — returning to prompt."));
+      return;
+    }
     let turn;
     try {
       turn = await agent.runTurn();
@@ -551,6 +807,10 @@ async function driveUntilChat(agent, log) {
       throw err;
     }
 
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] interrupted — returning to prompt."));
+      return;
+    }
     if (turn.kind === "chat") {
       log("\n" + C.cyan("astra › ") + turn.content.trim());
       return;