@hackerrank/astra-cli 0.1.0

package/src/cli.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * astra CLI — a minimal, zero-dependency AI coding agent for the
+ * HackerRank AI Gateway.
+ *
+ * Usage:
+ *   astra -m <model>                       interactive assistant (chat REPL)
+ *   astra -m <model> -t "<task text>"        autonomous task run
+ *   astra -m <model> -f path/to/instruction.md
+ *   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
+ *   -C, --cwd <path>        Working directory for commands (default: cwd)
+ *   -o, --output <path>     Also write trajectory JSON here (autonomous mode)
+ *   -s, --steps <n>         Step limit (default: 40)
+ *   -w, --wall <seconds>    Wall-clock limit (default: 0 = none)
+ *       --timeout <seconds> Per-command timeout (default: 60)
+ *       --max-output <n>    Max chars of command output kept (default: 16000)
+ *       --base-url <url>    Override gateway base URL
+ *       --api-key <key>     Gateway API key (else env/config/prompt)
+ *       --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)
+ *   -h, --help              Show this help
+ *
+ * API key resolution (first hit wins):
+ *   1. --api-key flag
+ *   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)
+ */
+
+import fs from "node:fs";
+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 {
+  newSessionId,
+  saveSession,
+  loadSession,
+  sessionExists,
+  listSessions,
+  deriveTitle,
+} from "./session.js";
+import { runRepl } from "./repl.js";
+
+function parseArgs(argv) {
+  const args = { steps: 40, wall: 0, timeout: 60, quiet: false, "max-output": 16000 };
+  const alias = {
+    "-m": "model", "--model": "model",
+    "-t": "task", "--task": "task",
+    "-f": "task-file", "--task-file": "task-file",
+    "-C": "cwd", "--cwd": "cwd",
+    "-o": "output", "--output": "output",
+    "-s": "steps", "--steps": "steps",
+    "-w": "wall", "--wall": "wall",
+    "--timeout": "timeout",
+    "--max-output": "max-output",
+    "--base-url": "base-url",
+    "--api-key": "api-key",
+    "--resume": "resume",
+    "--sessions": "sessions",
+    "-q": "quiet", "--quiet": "quiet",
+    "-y": "yolo", "--yolo": "yolo",
+    "-h": "help", "--help": "help",
+  };
+  const flags = new Set(["quiet", "yolo", "help", "sessions"]);
+  for (let i = 2; i < argv.length; i++) {
+    const key = alias[argv[i]];
+    if (!key) { console.error(`Unknown option: ${argv[i]}`); process.exit(2); }
+    if (flags.has(key)) { args[key] = true; continue; }
+    args[key] = argv[++i];
+  }
+  return args;
+}
+
+function resolveApiKey(cliKey, baseUrl) {
+  const { apiKey, baseUrl: resolvedBase } = resolveCredentials({ apiKey: cliKey, baseUrl });
+  if (resolvedBase) process.env.ASTRA_GATEWAY_BASE_URL = resolvedBase;
+  return apiKey;
+}
+
+const HELP = fs.readFileSync(new URL(import.meta.url), "utf8")
+  .split("\n").filter((l) => l.startsWith(" *")).map((l) => l.slice(3)).join("\n");
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.sessions) { printSessions(); process.exit(0); }
+  if (args.help) { console.log(HELP); process.exit(0); }
+
+  // Load a session to resume (if any) to infer defaults.
+  let resumeDoc = null;
+  if (args.resume) {
+    if (!sessionExists(args.resume)) {
+      console.error(`\x1b[31m[astra] no such session: ${args.resume}\x1b[0m`);
+      process.exit(2);
+    }
+    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.
+  let task = args.task;
+  if (args["task-file"]) task = fs.readFileSync(args["task-file"], "utf8");
+  const mode = task
+    ? "autonomous"
+    : resumeDoc?.info?.mode === "autonomous"
+    ? "autonomous"
+    : "interactive";
+
+  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"
+    );
+    process.exit(2);
+  }
+
+  let apiKey = resolveApiKey(args["api-key"], args["base-url"]);
+  if (!apiKey) {
+    if (canPrompt()) {
+      const creds = await promptForCredentials({ baseUrl: args["base-url"] });
+      if (creds?.apiKey) {
+        apiKey = creds.apiKey;
+        process.env.ASTRA_GATEWAY_BASE_URL = creds.baseUrl;
+      }
+    }
+    if (!apiKey) {
+      console.error(
+        "\x1b[31m[astra] No API key. Provide one via --api-key, the\n" +
+          "ASTRA_GATEWAY_API_KEY env var, or run interactively to be prompted.\x1b[0m"
+      );
+      process.exit(2);
+    }
+  }
+
+  const cwd = args.cwd ? path.resolve(args.cwd) : process.cwd();
+  const quiet = !!args.quiet;
+
+  const model = new GatewayModel({
+    model: modelId,
+    baseUrl: args["base-url"],
+    apiKey,
+    onRetry: quiet ? () => {} : (r) => printRetry(r),
+  });
+  const env = new LocalEnvironment({
+    cwd,
+    timeout: Number(args.timeout),
+    maxOutputChars: Number(args["max-output"]),
+  });
+
+  const sessionId = resumeDoc?.id || args.resume || newSessionId();
+  const agent = new Agent(model, env, {
+    mode,
+    stepLimit: Number(args.steps),
+    wallTimeLimitSeconds: Number(args.wall),
+    outputPath: args.output ? path.resolve(args.output) : null,
+    sessionId,
+    saveSession,
+    onEvent: quiet || mode === "interactive" ? () => {} : (msg) => printEvent(msg),
+    onStep: quiet || mode === "interactive" ? () => {} : (s) => printStep(s),
+  });
+
+  if (resumeDoc) {
+    agent.restore(resumeDoc);
+    console.error(`\x1b[2m[astra] resumed ${sessionId} (${agent.messages.length} messages)\x1b[0m`);
+  }
+
+  // -------------------- INTERACTIVE MODE --------------------
+  if (mode === "interactive") {
+    if (!resumeDoc) agent.start();
+    agent.title = agent.title || "interactive";
+    await runRepl(agent, { model, autoRun: !!args.yolo, fresh: !resumeDoc });
+    process.exit(0);
+  }
+
+  // -------------------- AUTONOMOUS MODE --------------------
+  if (!task && !resumeDoc) {
+    console.error("\x1b[31m[astra] provide a task with -t or -f.\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`);
+  }
+
+  const result =
+    resumeDoc && !task ? await continueAutonomous(agent) : await agent.run(task);
+  agent.save();
+
+  if (!quiet) {
+    const pt = model.totalPromptTokens;
+    const ct = model.totalCompletionTokens;
+    console.error(
+      `\n\x1b[1m[astra] exit=${result.exit_status} steps=${agent.nSteps} calls=${model.nCalls}\x1b[0m`
+    );
+    console.error(
+      `\x1b[1m[astra] tokens: prompt=${fmt(pt)} completion=${fmt(ct)} total=${fmt(pt + ct)} ` +
+        `| last context=${fmt(agent.lastContextTokens)}\x1b[0m`
+    );
+    console.error(
+      `\x1b[1m[astra] cost: ${fmtUsd(model.totalCostUsd)} (${model.costSource ?? "n/a"})` +
+        (model.costSource === "mixed"
+          ? ` — reported ${fmtUsd(model.reportedCostUsd)} + estimated ${fmtUsd(model.estimatedCostUsd)}`
+          : model.costSource === "estimated"
+          ? " — public-price estimate"
+          : "") +
+        `\x1b[0m`
+    );
+    console.error(`\x1b[2m[astra] session -> ${sessionId}\x1b[0m`);
+  }
+  if (result.submission) console.log(result.submission);
+  process.exit(result.exit_status === "Submitted" ? 0 : 1);
+}
+
+/** Drive an already-seeded autonomous agent to completion (used on resume). */
+async function continueAutonomous(agent) {
+  while (true) {
+    if (agent.stepLimit > 0 && agent.nSteps >= agent.stepLimit) return agent.exit("LimitsExceeded", "");
+    const turn = await agent.runTurn();
+    if (turn.kind === "exit") return { exit_status: turn.exit_status, submission: turn.submission };
+  }
+}
+
+/** Print the saved-session table for --sessions. */
+function printSessions() {
+  const list = listSessions();
+  if (list.length === 0) {
+    console.error("\x1b[2m[astra] no saved sessions.\x1b[0m");
+    return;
+  }
+  console.error("\x1b[1mid                      mode          model                steps  title\x1b[0m");
+  for (const s of list) {
+    console.error(
+      s.id.padEnd(23) + " " +
+        String(s.mode).padEnd(13) + " " +
+        String(s.model).padEnd(20) + " " +
+        String(s.n_steps).padStart(5) + "  " +
+        s.title
+    );
+  }
+  console.error(`\n\x1b[2m[astra] resume with: astra --resume <id>\x1b[0m`);
+}
+
+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`);
+}
+
+/** Compact per-step status line with exact token usage from the API. */
+function printStep(s) {
+  const limit = s.stepLimit > 0 ? `/${s.stepLimit}` : "";
+  const cached = s.usage.cached_tokens ? ` (cached ${fmt(s.usage.cached_tokens)})` : "";
+  const cost = s.costUsd != null
+    ? ` · ${fmtUsd(s.costUsd)}${s.costKind === "estimated" ? "~" : ""}`
+    : "";
+  console.error(
+    `\x1b[36m[astra] step ${s.step}${limit} · call ${s.nCalls} · ` +
+      `↑${fmt(s.usage.prompt_tokens)} ↓${fmt(s.usage.completion_tokens)} tok · ` +
+      `ctx ${fmt(s.contextTokens)}${cached}${cost} · ${s.elapsedSeconds.toFixed(1)}s\x1b[0m`
+  );
+}
+
+/** Thousands separator for readability. */
+function fmt(n) {
+  return Number(n).toLocaleString("en-US");
+}
+
+/** Format a USD amount with sensible precision for tiny costs. */
+function fmtUsd(n) {
+  const v = Number(n) || 0;
+  if (v === 0) return "$0";
+  if (v < 0.01) return "$" + v.toFixed(5);
+  if (v < 1) return "$" + v.toFixed(4);
+  return "$" + v.toFixed(2);
+}
+
+/** Log a retry attempt to stderr. */
+function printRetry(r) {
+  const secs = (r.waitMs / 1000).toFixed(1);
+  console.error(
+    `\x1b[33m[astra] retry ${r.attempt}/${r.maxRetries} · ${r.reason} · waiting ${secs}s…\x1b[0m`
+  );
+}
+
+main().catch((err) => {
+  // Classified gateway errors already carry an actionable hint; show that
+  // cleanly instead of a raw stack trace.
+  if (err && (err.name === "GatewayError" || err.name === "ContextWindowError")) {
+    console.error(`\x1b[31m[astra] ${err.message}\x1b[0m`);
+  } else {
+    console.error(`\x1b[31m[astra] fatal: ${err.stack || err.message}\x1b[0m`);
+  }
+  process.exit(1);
+});

package/src/config.js

@@ -0,0 +1,135 @@
+/**
+ * Dedicated astra configuration.
+ *
+ * astra keeps its own config at ~/.astra/config.json so the tool is fully
+ * self-contained (important now that this ships as an npm package).
+ *
+ * Config shape:
+ *   {
+ *     "gateway": {
+ *       "apiKey": "...",
+ *       "baseUrl": "https://gateway-central.ai.private.hackerrank.link/v1"
+ *     }
+ *   }
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+export const DEFAULT_BASE_URL = "https://gateway-central.ai.private.hackerrank.link/v1";
+
+export function configDir() {
+  return path.join(os.homedir(), ".astra");
+}
+
+export function configPath() {
+  return path.join(configDir(), "config.json");
+}
+
+/** Read the dedicated astra config, or {} if absent/unreadable. */
+export function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Write the dedicated astra config with restrictive permissions. */
+export function writeConfig(cfg) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+}
+
+/** Save gateway credentials into the dedicated config (merging existing). */
+export function saveGatewayCredentials({ apiKey, baseUrl }) {
+  const cfg = readConfig();
+  cfg.gateway = { ...(cfg.gateway || {}) };
+  if (apiKey) cfg.gateway.apiKey = apiKey;
+  if (baseUrl) cfg.gateway.baseUrl = baseUrl;
+  writeConfig(cfg);
+  return configPath();
+}
+
+/**
+ * Resolve gateway credentials in priority order (no prompting):
+ *   1. explicit args (CLI flags)
+ *   2. environment variables
+ *   3. dedicated ~/.astra/config.json
+ * Returns { apiKey, baseUrl, source }.
+ */
+export function resolveCredentials({ apiKey, baseUrl } = {}) {
+  if (apiKey) return { apiKey, baseUrl: baseUrl || DEFAULT_BASE_URL, source: "flag" };
+
+  if (process.env.ASTRA_GATEWAY_API_KEY) {
+    return {
+      apiKey: process.env.ASTRA_GATEWAY_API_KEY,
+      baseUrl: baseUrl || process.env.ASTRA_GATEWAY_BASE_URL || DEFAULT_BASE_URL,
+      source: "env",
+    };
+  }
+
+  const cfg = readConfig();
+  if (cfg.gateway?.apiKey) {
+    return {
+      apiKey: cfg.gateway.apiKey,
+      baseUrl: baseUrl || cfg.gateway.baseUrl || DEFAULT_BASE_URL,
+      source: "config",
+    };
+  }
+
+  return { apiKey: "", baseUrl: baseUrl || DEFAULT_BASE_URL, source: "none" };
+}
+
+/** True when we can interactively prompt the user. */
+export function canPrompt() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+/** Ask a question on the TTY; hides input when `secret` is true. */
+export function ask(question, { secret = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (secret) {
+      // Suppress echo of typed characters.
+      const onData = () => {
+        rl.output.write("\x1b[2K\r" + question);
+      };
+      rl.input.on("data", onData);
+      rl.question(question, (answer) => {
+        rl.input.off("data", onData);
+        rl.output.write("\n");
+        rl.close();
+        resolve(answer.trim());
+      });
+    } else {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    }
+  });
+}
+
+/**
+ * Interactively obtain a gateway API key when none was found, and offer to
+ * persist it to the dedicated config. Returns { apiKey, baseUrl } or null if
+ * the user provides nothing.
+ */
+export async function promptForCredentials({ baseUrl } = {}) {
+  const effectiveBase = baseUrl || DEFAULT_BASE_URL;
+  console.error("\x1b[33m[astra] No HackerRank AI Gateway API key found.\x1b[0m");
+  console.error(`\x1b[2m[astra] Gateway: ${effectiveBase}\x1b[0m`);
+  const apiKey = await ask("Enter gateway API key (leave blank to abort): ", { secret: true });
+  if (!apiKey) return null;
+
+  const save = (await ask(`Save to ${configPath()}? [Y/n] `)).toLowerCase();
+  if (save === "" || save === "y" || save === "yes") {
+    const saved = saveGatewayCredentials({ apiKey, baseUrl: effectiveBase });
+    console.error(`\x1b[2m[astra] Saved credentials to ${saved}\x1b[0m`);
+  }
+  return { apiKey, baseUrl: effectiveBase };
+}

package/src/environment.js

@@ -0,0 +1,121 @@
+/**
+ * Local execution environment.
+ *
+ * Every action is executed in a fresh subshell via `bash -c`: stateful cd /
+ * env changes do NOT persist between actions. The model must chain state with
+ * `cd /path && ...` in a single command.
+ */
+
+import { spawn } from "node:child_process";
+import os from "node:os";
+
+export class LocalEnvironment {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.cwd]      working directory for commands
+   * @param {number} [opts.timeout]  per-command timeout in seconds
+   * @param {object} [opts.env]      extra env vars merged over process.env
+   * @param {number} [opts.maxOutputChars] cap on observation size (default 16000)
+   */
+  constructor({ cwd = process.cwd(), timeout = 60, env = {}, maxOutputChars = 16000 } = {}) {
+    this.cwd = cwd;
+    this.timeout = timeout;
+    this.env = env;
+    this.maxOutputChars = maxOutputChars;
+  }
+
+  /**
+   * Execute a shell command.
+   * @param {string} command
+   * @returns {Promise<{output:string, returncode:number, exception_info:string}>}
+   */
+  execute(command) {
+    return new Promise((resolve) => {
+      const child = spawn("bash", ["-c", command], {
+        cwd: this.cwd,
+        env: { ...process.env, ...this.env },
+        // New process group so we can kill the whole tree on timeout.
+        detached: process.platform !== "win32",
+      });
+
+      let out = "";
+      let killedByTimeout = false;
+
+      const timer = setTimeout(() => {
+        killedByTimeout = true;
+        try {
+          if (process.platform !== "win32") {
+            process.kill(-child.pid, "SIGKILL");
+          } else {
+            child.kill("SIGKILL");
+          }
+        } catch {
+          /* already dead */
+        }
+      }, this.timeout * 1000);
+
+      child.stdout.on("data", (d) => (out += d.toString()));
+      child.stderr.on("data", (d) => (out += d.toString()));
+
+      child.on("error", (err) => {
+        clearTimeout(timer);
+        resolve({
+          output: truncateOutput(out, this.maxOutputChars),
+          returncode: -1,
+          exception_info: `Failed to execute command: ${err.message}`,
+        });
+      });
+
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        if (killedByTimeout) {
+          resolve({
+            output: truncateOutput(out, this.maxOutputChars),
+            returncode: -1,
+            exception_info: `Command timed out after ${this.timeout}s.`,
+          });
+        } else {
+          resolve({
+            output: truncateOutput(out, this.maxOutputChars),
+            returncode: code ?? 0,
+            exception_info: "",
+          });
+        }
+      });
+    });
+  }
+
+  templateVars() {
+    return {
+      cwd: this.cwd,
+      timeout: this.timeout,
+      system: os.type(),
+      release: os.release(),
+      machine: os.machine ? os.machine() : os.arch(),
+    };
+  }
+}
+
+/**
+ * Keep command output within a character budget so a single noisy command
+ * (a big `cat`, `npm install`, etc.) can't blow up the model context.
+ * Keeps the head and tail and drops the middle, since both ends usually carry
+ * the most signal (command intent + final result / error).
+ */
+export function truncateOutput(text, maxChars) {
+  if (!maxChars || text.length <= maxChars) return text;
+
+  // Reserve room for the marker; split the remaining budget head-heavy.
+  const headChars = Math.floor(maxChars * 0.6);
+  const tailChars = maxChars - headChars;
+  const head = text.slice(0, headChars);
+  const tail = text.slice(text.length - tailChars);
+
+  const omitted = text.length - headChars - tailChars;
+  const omittedLines = text.slice(headChars, text.length - tailChars).split("\n").length - 1;
+  const marker =
+    `\n\n[... ${omitted} characters (~${omittedLines} lines) omitted; ` +
+    `output truncated to ${maxChars} chars ...]\n\n`;
+
+  return head + marker + tail;
+}