@hackerrank/astra-cli 0.1.23 → 0.1.25

package/README.md

@@ -80,7 +80,7 @@ astra -m claude-sonnet-5            # start chatting
 astra -m claude-sonnet-5 -y         # auto-run commands (no prompts)
 ```
 
-In-REPL commands: `/help /exit /clear /history /tokens /yolo`.
+In-REPL commands: `/help /plan <task> /exit /clear /history /tokens /yolo`.
 
 ### Autonomous task run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackerrank/astra-cli",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Minimal zero-dependency AI coding agent for the HackerRank AI Gateway.",
   "type": "module",
   "bin": {

package/src/model.js

@@ -42,7 +42,7 @@ export class GatewayModel {
    * @param {number} [opts.maxRetries]
    * @param {(info:object)=>void} [opts.onRetry] called before each retry sleep
    */
-  constructor({ model, baseUrl, apiKey, modelKwargs = {}, maxRetries = 5, maxTokens = 8192, requestTimeoutMs = 0, onRetry } = {}) {
+  constructor({ model, baseUrl, apiKey, modelKwargs = {}, maxRetries = 8, maxTokens = 8192, requestTimeoutMs = 0, onRetry } = {}) {
     if (!model) throw new Error("GatewayModel: `model` is required");
     this.model = model;
     this.maxTokens = maxTokens;
@@ -124,14 +124,15 @@ export class GatewayModel {
           // Retry on transient server / rate-limit errors with exponential
           // 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);
+            const serverWait = retryAfterMs(res.headers, text);
+            const wait = serverWait != null ? Math.max(serverWait + 250, 1000) : backoffMs(attempt);
             this.nRetries++;
             this.onRetry({
               attempt: attempt + 1,
               maxRetries: this.maxRetries,
               status: res.status,
               waitMs: wait,
-              reason: `HTTP ${res.status}`,
+              reason: res.status === 429 ? "HTTP 429 (rate limited)" : `HTTP ${res.status}`,
             });
             await sleep(wait);
             continue;
@@ -282,14 +283,180 @@ function hintForStatus(status) {
   }
 }
 
-/** Parse a Retry-After header (seconds or HTTP-date) into milliseconds. */
-function retryAfterMs(headers) {
-  const v = headers?.get?.("retry-after");
-  if (!v) return null;
-  const secs = Number(v);
-  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
-  const when = Date.parse(v);
-  if (Number.isFinite(when)) return Math.max(0, when - Date.now());
+/**
+ * Parse a duration string, number, or date into milliseconds.
+ * Supports numbers (seconds or timestamps), units (ms, s, m, h, d),
+ * composite durations ("1m 30s"), and HTTP/ISO dates.
+ */
+export function parseDurationMs(val) {
+  if (typeof val === "number" && Number.isFinite(val) && val >= 0) {
+    if (val > 1e11) return Math.max(0, val - Date.now());
+    if (val > 1e9) return Math.max(0, val * 1000 - Date.now());
+    return Math.max(0, Math.round(val * 1000));
+  }
+  if (!val || typeof val !== "string") return null;
+  const s = val.trim();
+
+  const rawNum = Number(s);
+  if (Number.isFinite(rawNum) && rawNum >= 0) {
+    if (rawNum > 1e11) return Math.max(0, rawNum - Date.now());
+    if (rawNum > 1e9) return Math.max(0, rawNum * 1000 - Date.now());
+    return Math.max(0, Math.round(rawNum * 1000));
+  }
+
+  const when = Date.parse(s);
+  if (Number.isFinite(when) && when > Date.now()) {
+    return Math.max(0, when - Date.now());
+  }
+
+  const pattern = /([0-9]+(?:\.[0-9]+)?)\s*(milliseconds?|millis?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/gi;
+  let match;
+  let totalMs = 0;
+  let matched = false;
+  while ((match = pattern.exec(s)) !== null) {
+    matched = true;
+    const n = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    if (!Number.isFinite(n)) continue;
+    if (unit.startsWith("ms") || unit.startsWith("milli")) {
+      totalMs += n;
+    } else if (unit.startsWith("s")) {
+      totalMs += n * 1000;
+    } else if (unit.startsWith("m")) {
+      totalMs += n * 60 * 1000;
+    } else if (unit.startsWith("h")) {
+      totalMs += n * 3600 * 1000;
+    } else if (unit.startsWith("d")) {
+      totalMs += n * 86400 * 1000;
+    }
+  }
+  return matched ? Math.round(totalMs) : null;
+}
+
+/**
+ * Extract retry duration from unstructured error message text.
+ * Matches phrases like "retry after 12.5s", "try again in 5 seconds", "resets in 30s", "wait 10s".
+ */
+export function extractDurationFromText(text) {
+  if (!text || typeof text !== "string") return null;
+
+  const p1 = /(?:retry(?:ing)?|try\s+again|wait(?:ing)?|resets?|available|back\s*off)\s+(?:again\s+)?(?:after|in|for)\s+([0-9]+(?:\.[0-9]+)?\s*(?:milliseconds?|millis?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b(?:\s+[0-9]+(?:\.[0-9]+)?\s*(?:milliseconds?|millis?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b)*|[0-9]+(?:\.[0-9]+)?)/i;
+  const m1 = text.match(p1);
+  if (m1) {
+    const parsed = parseDurationMs(m1[1]);
+    if (parsed != null) return parsed;
+  }
+
+  const p2 = /(?:wait(?:ing)?)\s+([0-9]+(?:\.[0-9]+)?\s*(?:milliseconds?|millis?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b)/i;
+  const m2 = text.match(p2);
+  if (m2) {
+    const parsed = parseDurationMs(m2[1]);
+    if (parsed != null) return parsed;
+  }
+
+  const p3 = /in\s+([0-9]+(?:\.[0-9]+)?\s*(?:milliseconds?|millis?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b)\s*[,.]?\s*(?:please\s+)?(?:retry|try)/i;
+  const m3 = text.match(p3);
+  if (m3) {
+    const parsed = parseDurationMs(m3[1]);
+    if (parsed != null) return parsed;
+  }
+
+  return null;
+}
+
+/**
+ * Parse retry delay from response headers or error response body into milliseconds.
+ * Checks standard and provider-specific rate-limit headers as well as JSON fields
+ * and error messages returned by AI gateways (HackerRank, OpenAI, Anthropic, LiteLLM, Gemini, etc.).
+ */
+export function retryAfterMs(headers, bodyText) {
+  const msHeader = headers?.get?.("retry-after-ms");
+  if (msHeader) {
+    const ms = Number(msHeader);
+    if (Number.isFinite(ms) && ms >= 0) return Math.round(ms);
+  }
+
+  const headerKeys = [
+    "retry-after",
+    "x-retry-after",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    "x-ratelimit-reset",
+  ];
+  for (const k of headerKeys) {
+    const val = headers?.get?.(k);
+    if (val) {
+      const parsed = parseDurationMs(val);
+      if (parsed != null) return parsed;
+    }
+  }
+
+  if (bodyText) {
+    let json = null;
+    if (typeof bodyText === "object") {
+      json = bodyText;
+    } else if (typeof bodyText === "string") {
+      try {
+        json = JSON.parse(bodyText);
+      } catch {}
+    }
+
+    if (json && typeof json === "object") {
+      const msCandidates = [json.retry_after_ms, json.error?.retry_after_ms];
+      for (const c of msCandidates) {
+        if (Number.isFinite(Number(c)) && Number(c) >= 0) {
+          return Math.round(Number(c));
+        }
+      }
+
+      const durationCandidates = [
+        json.retry_after,
+        json.retryAfter,
+        json.retry_after_seconds,
+        json.retry_after_sec,
+        json.reset_in,
+        json.reset_after,
+        json.reset_at,
+        json.wait_seconds,
+        json.wait_time,
+        json.error?.retry_after,
+        json.error?.retryAfter,
+        json.error?.retry_after_seconds,
+        json.error?.retry_after_sec,
+        json.error?.reset_in,
+        json.error?.reset_after,
+        json.error?.reset_at,
+        json.error?.wait_seconds,
+        json.error?.wait_time,
+      ];
+      for (const c of durationCandidates) {
+        if (c != null) {
+          const parsed = parseDurationMs(c);
+          if (parsed != null) return parsed;
+        }
+      }
+
+      const msgCandidates = [
+        json.error?.message,
+        typeof json.error === "string" ? json.error : null,
+        json.message,
+        json.detail,
+        typeof json.details === "string" ? json.details : null,
+      ];
+      for (const msg of msgCandidates) {
+        if (msg) {
+          const extracted = extractDurationFromText(msg);
+          if (extracted != null) return extracted;
+        }
+      }
+    }
+
+    if (typeof bodyText === "string") {
+      const extracted = extractDurationFromText(bodyText);
+      if (extracted != null) return extracted;
+    }
+  }
+
   return null;
 }
 

package/src/prompts.js

@@ -102,3 +102,27 @@ export function render(template, vars) {
     key in vars && vars[key] != null ? String(vars[key]) : ""
   );
 }
+
+export const PLAN_PROMPT_TEMPLATE = `Please explore the workspace and create a clear, actionable plan for this task:
+
+Task:
+{{task}}
+
+Instructions for planning:
+1. Run read-only commands (e.g. ls, find, grep, cat) to explore and understand the relevant files.
+2. Present a structured plan with:
+   - **Objective & Scope**: Summary of what needs to be done.
+   - **Files to Modify / Create**: List of target files.
+   - **Self-Testing & Verification Strategy**: Exact test commands or verification scripts to write/run.
+   - **Self-Review Checklist**: Code quality, edge cases, and cleanliness checks.
+3. Finish with a chat response presenting the complete plan so the user can review it before execution.`;
+
+export const AUTONOMOUS_EXECUTION_PROMPT = `The plan has been approved. Execute the plan end-to-end now in autonomous mode without asking further questions.
+
+Workflow requirements:
+1. Implement the changes with clean, focused edits.
+2. Self-verify by writing or running test scripts to prove the solution works.
+3. Review your changes with \`git diff\` (or inspect modified files) to ensure no regressions, unintended files, or debug prints remain.
+4. If any tests or checks fail, diagnose and fix the errors.
+5. When completely finished, verified, and reviewed, run:
+\`echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT\``;

package/src/repl.js

@@ -17,6 +17,7 @@ import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { ask, saveAgentPrefs } from "./config.js";
 import { AVAILABLE_MODELS, REASONING_LEVELS } from "./models.js";
+import { PLAN_PROMPT_TEMPLATE, AUTONOMOUS_EXECUTION_PROMPT, render } from "./prompts.js";
 
 const C = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
@@ -517,6 +518,7 @@ Interactive commands:
   /help            show this help
   /exit, /quit     leave (session is saved)
   /clear           start a fresh conversation (new context)
+  /plan <task>     plan a task, review it, then execute autonomously with self-review
   /history         print the message history
   /tokens          show token usage so far
   /yolo            toggle auto-run of commands (no confirmation)
@@ -643,6 +645,25 @@ async function runStickyRepl(agent, model, yolo, intro = [], { runBench = null }
         if (cmd === "history") { printHistory(agent, log); continue; }
         if (cmd === "tokens") { log(tokensLine(model)); continue; }
         if (cmd === "yolo") { yolo = !yolo; log(C.dim(`[astra] auto-run ${yolo ? "ON" : "OFF"}.`)); refresh(); continue; }
+        if (cmd === "plan") {
+          const taskText = line.slice(line.indexOf("plan") + 4).trim();
+          const prevYolo = yolo;
+          await handlePlanWorkflow({
+            taskText,
+            agent,
+            model,
+            log,
+            readInput: (promptText) => screen.readLine(promptText, { guardEnter: true, echo: true }),
+            startBusy: (label) => screen.startBusy(label),
+            stopBusy: () => screen.stopBusy(),
+            interrupt,
+            setYolo: (v) => { yolo = v; },
+            onProgress: () => refresh(),
+          });
+          yolo = prevYolo;
+          refresh();
+          continue;
+        }
         log(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
         continue;
       }
@@ -742,6 +763,25 @@ async function runPlainRepl(agent, model, yolo) {
         if (cmd === "history") { printHistory(agent, log); continue; }
         if (cmd === "tokens") { console.error(tokensLine(model)); continue; }
         if (cmd === "yolo") { yolo = !yolo; console.error(C.dim(`[astra] auto-run ${yolo ? "ON" : "OFF"}.`)); continue; }
+        if (cmd === "plan") {
+          const taskText = line.slice(line.indexOf("plan") + 4).trim();
+          const prevYolo = yolo;
+          await handlePlanWorkflow({
+            taskText,
+            agent,
+            model,
+            log: (t) => console.error(t),
+            readInput: (promptText) => new Promise((res) => rl.question(promptText, res)),
+            startBusy: () => {},
+            stopBusy: () => {},
+            interrupt: { aborted: false, quit: false },
+            setYolo: (v) => { yolo = v; },
+            onProgress: () => printFooterInline(agent, model, yolo),
+          });
+          yolo = prevYolo;
+          printFooterInline(agent, model, yolo);
+          continue;
+        }
         console.error(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
         continue;
       }
@@ -859,3 +899,161 @@ function tokensLine(model) {
   const dollars = usd < 0.01 ? "$" + usd.toFixed(5) : "$" + usd.toFixed(4);
   return C.dim(`[astra] tokens: prompt=${pt} completion=${ct} total=${pt + ct} · cost=${dollars} (${src})`);
 }
+
+
+/**
+ * Run the plan-and-execute workflow:
+ * 1. Prompt model to explore workspace and draft a structured plan.
+ * 2. Pause and prompt user for approval / feedback.
+ * 3. On approval, execute autonomously to completion with auto-review and auto-fix.
+ */
+export async function handlePlanWorkflow({
+  taskText,
+  agent,
+  model,
+  log,
+  readInput,
+  startBusy,
+  stopBusy,
+  interrupt,
+  setYolo = () => {},
+  onProgress = () => {},
+}) {
+  let task = taskText;
+  if (!task) {
+    task = (await readInput(C.yellow("Enter task to plan: "))).trim();
+  }
+  if (!task) {
+    log(C.dim("[astra] plan cancelled (empty task)."));
+    return;
+  }
+
+  log(C.cyan(`[astra] exploring workspace and drafting plan for: "${task}"...`));
+  agent.addUserMessage(render(PLAN_PROMPT_TEMPLATE, { task }));
+
+  model._abort = new AbortController();
+  model.signal = model._abort.signal;
+  startBusy("planning");
+  try {
+    await driveUntilChat(agent, log, interrupt);
+  } finally {
+    stopBusy();
+    model.signal = null;
+    model._abort = null;
+  }
+  if (interrupt?.quit || interrupt?.aborted) return;
+
+  // Review gate loop
+  let approved = false;
+  while (!approved) {
+    const ans = (await readInput(
+      C.yellow("\nApprove plan and begin autonomous execution? [Y/n/feedback] ")
+    )).trim();
+    const lower = ans.toLowerCase();
+
+    if (lower === "n" || lower === "no" || lower === "cancel" || lower === "abort") {
+      log(C.dim("[astra] plan cancelled. Returning to interactive mode."));
+      return;
+    }
+    if (ans === "" || lower === "y" || lower === "yes") {
+      approved = true;
+      break;
+    }
+
+    // Feedback provided: refine plan
+    log(C.cyan(`[astra] updating plan with feedback: "${ans}"...`));
+    agent.addUserMessage(
+      `Here is feedback on the plan: "${ans}". Please refine the plan accordingly and present the updated plan.`
+    );
+    model._abort = new AbortController();
+    model.signal = model._abort.signal;
+    startBusy("planning");
+    try {
+      await driveUntilChat(agent, log, interrupt);
+    } finally {
+      stopBusy();
+      model.signal = null;
+      model._abort = null;
+    }
+    if (interrupt?.quit || interrupt?.aborted) return;
+  }
+
+  // Execute autonomously
+  log(C.green("\n[astra] plan approved! Starting unattended autonomous execution with auto-review & auto-fix..."));
+  const prevMode = agent.mode;
+  setYolo(true);
+  agent.mode = "autonomous";
+  agent.addUserMessage(AUTONOMOUS_EXECUTION_PROMPT);
+
+  model._abort = new AbortController();
+  model.signal = model._abort.signal;
+  startBusy("executing plan");
+  let status = "Completed";
+  try {
+    status = await driveAutonomous(agent, log, interrupt);
+  } catch (err) {
+    log(C.red(`[astra] error during autonomous execution: ${err?.message || err}`));
+    status = "Error";
+  } finally {
+    stopBusy();
+    model.signal = null;
+    model._abort = null;
+    agent.mode = prevMode;
+    agent.exitStatus = null;
+    onProgress();
+  }
+
+  log(C.green(`\n[astra] plan execution finished (${status}). You are now back in interactive mode.`));
+}
+
+/**
+ * Drive turns autonomously until the model submits with the completion sentinel.
+ */
+export async function driveAutonomous(agent, log, interrupt = null) {
+  while (true) {
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] autonomous execution interrupted — returning to prompt."));
+      return "Interrupted";
+    }
+    let turn;
+    try {
+      turn = await agent.runTurn();
+    } catch (err) {
+      if (err && (err.name === "GatewayError" || err.name === "ContextWindowError")) {
+        log(C.red(`[astra] ${err.message}`));
+        return err.name;
+      }
+      throw err;
+    }
+
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] autonomous execution interrupted — returning to prompt."));
+      return "Interrupted";
+    }
+    if (turn.kind === "exit") {
+      log(C.dim(`[astra] autonomous run ended: ${turn.exit_status}`));
+      return turn.exit_status;
+    }
+    if (turn.kind === "command") {
+      const rc = turn.returncode;
+      const tag = rc === 0 ? C.dim(`[rc ${rc}]`) : C.red(`[rc ${rc}]`);
+      log(tag + "\n" + indent(turn.output));
+      continue;
+    }
+    if (turn.kind === "declined") {
+      log(C.dim("[astra] command skipped."));
+      continue;
+    }
+    if (turn.kind === "format_error") {
+      log(C.dim(`[astra] (reprompting: ${turn.error})`));
+      continue;
+    }
+    if (turn.kind === "chat") {
+      log("\n" + C.cyan("astra › ") + turn.content.trim());
+      agent.addUserMessage(
+        "Continue executing the approved plan in autonomous mode. When all changes are implemented, tested, and self-reviewed, run:\necho COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT"
+      );
+      continue;
+    }
+  }
+}