@hackerrank/astra-cli 0.1.23 → 0.1.24

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.24",
   "description": "Minimal zero-dependency AI coding agent for the HackerRank AI Gateway.",
   "type": "module",
   "bin": {

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;
+    }
+  }
+}