@hackerrank/astra-cli 0.1.0

package/src/repl.js

@@ -0,0 +1,601 @@
+/**
+ * Interactive REPL — astra as a personal coding assistant (like cline / claude
+ * code). You type a request, the agent may run shell commands (with your
+ * approval by default) and then replies; you type the next thing. The whole
+ * conversation is a resumable session under ~/.astra/sessions/.
+ *
+ * Commands run one at a time (our text protocol). Between commands the agent
+ * loops autonomously within a single "turn" until it produces a chat reply
+ * (no bash block), which hands control back to you.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+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";
+
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+// Rough context-window sizes (tokens) for the % readout in the footer. The
+// gateway doesn't report these, so this is a best-effort lookup; unknown
+// models simply omit the percentage.
+const CONTEXT_WINDOWS = {
+  "claude-opus-5": 200000,
+  "claude-sonnet-5": 200000,
+  "gemini-3.7-flash": 1000000,
+  "gpt-5.6-luna": 400000,
+  "gpt-5.6-sol": 400000,
+  "gpt-5.6-terra": 400000,
+  "grok-4.6": 256000,
+  "deepseek-v4-pro": 128000,
+  "glm-5.2": 128000,
+  "kimi-k3": 256000,
+  "qwen-3.8": 256000,
+};
+
+function pkgVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// ASCII wordmark (figlet "standard" style) shown when a new chat starts.
+const BANNER = [
+  "              _                 ",
+  "  __ _  ___  | |_   __ __    __ _ ",
+  " / _` |/ __| | __| |__ __|  / _`  |",
+  "| (_| |\\__ \\ | |_  | |   | (_|  |",
+  " \\__,_||___/  \\__| |_|    \\__,_|",
+];
+
+/** Center a string within the current terminal width. */
+function center(s, cols) {
+  const pad = Math.max(0, Math.floor((cols - s.length) / 2));
+  return " ".repeat(pad) + s;
+}
+
+/** Build the centered banner lines (wordmark + version/status/session). */
+function bannerLines({ session } = {}) {
+  const cols = process.stdout.columns || 80;
+  const out = [""];
+  for (const line of BANNER) out.push(C.cyan(center(line, cols)));
+  out.push("");
+  out.push(C.dim(center(`astra CLI v${pkgVersion()}`, cols)));
+  out.push(C.green(center("All set up!", cols)));
+  if (session) out.push(C.dim(center(`Initialized conversation ${session}`, cols)));
+  out.push("");
+  return out;
+}
+
+/** Thousands / compact number formatting (1.1M, 26k, 512). */
+function fmt(n) {
+  const v = Number(n) || 0;
+  if (v >= 1_000_000) return (v / 1_000_000).toFixed(v >= 10_000_000 ? 0 : 1) + "M";
+  if (v >= 1_000) return (v / 1_000).toFixed(v >= 10_000 ? 0 : 1) + "k";
+  return String(v);
+}
+
+/** USD with sensible precision for tiny amounts. */
+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);
+}
+
+/** Working directory shown with a leading ~ for $HOME, plus git branch. */
+function repoLabel() {
+  let cwd = process.cwd();
+  const home = os.homedir();
+  if (cwd === home) cwd = "~";
+  else if (cwd.startsWith(home + path.sep)) cwd = "~" + cwd.slice(home.length);
+  let branch = "";
+  try {
+    branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    /* not a git repo */
+  }
+  return branch ? `${cwd} (${branch})` : cwd;
+}
+
+/** Compact one-line summary printed after each turn hands back to the user. */
+function turnSummary({ turn, upTok, downTok, costUsd, costKind, seconds }) {
+  const cost = costUsd != null
+    ? ` · ${fmtUsd(costUsd)}${costKind === "estimated" ? "~" : ""}`
+    : "";
+  return C.dim(
+    `turn ${turn} · ↑${fmt(upTok)} ↓${fmt(downTok)} tok${cost} · ${seconds.toFixed(1)}s`
+  );
+}
+
+/**
+ * Build the footer lines: a full-width divider + repo/branch, model/reasoning,
+ * 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) {
+  const cols = process.stdout.columns || 100;
+  const rule = "─".repeat(cols);
+
+  const reasoning = model.modelKwargs?.reasoning_effort || model.modelKwargs?.reasoning?.effort;
+  const modelBits = [`model: ${model.model}`];
+  if (reasoning) modelBits.push(`reasoning: ${reasoning}`);
+  modelBits.push(yolo ? "auto-run" : "approve");
+
+  const up = model.totalPromptTokens;
+  const down = model.totalCompletionTokens;
+  const ctx = agent.lastContextTokens || 0;
+  const win = CONTEXT_WINDOWS[model.model];
+  const ctxStr = win
+    ? `${((ctx / win) * 100).toFixed(1)}%/${fmt(win)}`
+    : `${fmt(ctx)} ctx`;
+  const src = model.costSource && model.costSource !== "n/a" ? ` ${model.costSource}` : "";
+  const usage = `↑${fmt(up)} ↓${fmt(down)} · ${ctxStr} · ${fmtUsd(model.totalCostUsd || 0)}${src}`;
+
+  return [
+    C.dim(rule),
+    C.cyan(repoLabel()) + "    " + C.dim(modelBits.join("  ")),
+    C.dim(usage),
+  ];
+}
+
+const FOOTER_LINES = 3; // divider + repo/model + usage
+const PROMPT_PREFIX = C.green("› ");        // live input row (minimal)
+const HISTORY_PREFIX = C.green("you › ");   // echoed into transcript/history
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * A bottom-anchored screen: conversation output scrolls in the top region
+ * (bounded by a DECSTBM scroll margin) while the footer + input prompt stay
+ * glued to the terminal's bottom rows. Input is read via raw keypresses (not
+ * readline) so nothing fights the scroll margin. Requires a TTY; callers use
+ * the readline fallback otherwise.
+ */
+class Screen {
+  constructor(out = process.stdout, inp = process.stdin) {
+    this.out = out;
+    this.inp = inp;
+    this.footer = [];
+    this.buf = "";       // current input line
+    this.resolve = null;  // pending readLine() resolver
+    this._lastWasCR = false;
+    this._guardEnterUntil = 0;  // ignore stray Enter until this timestamp
+    this._echoOnCommit = true;  // echo committed input to the transcript
+    this._busy = false;         // loading state (agent is working)
+    this._busyTimer = null;
+    this._busyFrame = 0;
+    this._busyLabel = "working";
+    this._busyResume = false;
+    this.promptLabel = PROMPT_PREFIX;
+    this._onData = this._onData.bind(this);
+    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 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
+  get promptRow() { return this.footerTop + 1; }    // input row: right under the divider
+
+  /** Enter sticky mode: set scroll margin, park cursor, start listening. */
+  enter() {
+    this.out.write(`\x1b[1;${this.scrollBottom}r`);     // scroll region = top area
+    this.out.write(`\x1b[${this.scrollBottom};1H`);      // cursor at bottom of scroll area
+    if (this.inp.isTTY) this.inp.setRawMode(true);
+    this.inp.resume();
+    this.inp.setEncoding("utf8");
+    this.inp.on("data", this._onData);
+    this.out.on("resize", this._onResize);
+  }
+
+  /** Leave sticky mode: reset scroll region, restore cooked input. */
+  leave() {
+    this.inp.off("data", this._onData);
+    this.out.off("resize", this._onResize);
+    if (this.inp.isTTY) this.inp.setRawMode(false);
+    this.out.write("\x1b[r");                    // reset scroll region
+    this.out.write(`\x1b[${this.rows};1H\n`);    // move below footer
+  }
+
+  /** 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
+    this.out.write(String(text) + "\n");            // trailing \n scrolls the region
+    this.drawFooter();
+    this.drawPrompt();
+  }
+
+  /** Redraw the pinned footer + prompt (e.g. when usage changes). */
+  refresh(footer) {
+    if (footer) this.footer = footer;
+    this.drawFooter();
+    this.drawPrompt();
+  }
+
+  drawFooter() {
+    this.out.write("\x1b[s"); // save cursor
+    // footer[0] = divider (row footerTop), footer[1..] = status lines that go
+    // BELOW the prompt row (footerTop+1). So skip the prompt row when placing
+    // the status lines.
+    this.out.write(`\x1b[${this.footerTop};1H\x1b[2K`);
+    this.out.write(this.footer[0] || "");           // divider
+    for (let i = 1; i < FOOTER_LINES; i++) {
+      const row = this.promptRow + i;               // status lines under the prompt
+      this.out.write(`\x1b[${row};1H\x1b[2K`);
+      this.out.write(this.footer[i] || "");
+    }
+    this.out.write("\x1b[u"); // restore cursor
+  }
+
+  drawPrompt() {
+    this.out.write(`\x1b[${this.promptRow};1H\x1b[2K`);
+    if (this._busy) {
+      const frame = SPINNER_FRAMES[this._busyFrame % SPINNER_FRAMES.length];
+      this.out.write(C.cyan(frame + " ") + C.dim(this._busyLabel + "…"));
+      return;
+    }
+    this.out.write((this.promptLabel || PROMPT_PREFIX) + this.buf);
+  }
+
+  /** Start the minimal loading state on the prompt row. */
+  startBusy(label = "working") {
+    this._busy = true;
+    this._busyLabel = label;
+    this._busyFrame = 0;
+    this.drawPrompt();
+    if (this._busyTimer) clearInterval(this._busyTimer);
+    this._busyTimer = setInterval(() => {
+      this._busyFrame++;
+      this.drawPrompt();
+    }, 90);
+    if (this._busyTimer.unref) this._busyTimer.unref();
+  }
+
+  /** Stop the loading state and restore the normal input prompt. */
+  stopBusy() {
+    if (this._busyTimer) { clearInterval(this._busyTimer); this._busyTimer = null; }
+    this._busy = false;
+    this._busyResume = false;
+    this.drawPrompt();
+  }
+
+  /**
+   * 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
+   * is shown right where the user is typing).
+   *
+   * `opts.guardEnter` ignores a bare Enter that lands within a short window of
+   * the prompt appearing. This prevents a stray newline still in the input
+   * buffer (from the previous line, a CRLF pair, or a paste) from instantly
+   * "answering" a confirmation prompt the user never actually saw.
+   */
+  readLine(promptLabel, opts = {}) {
+    return new Promise((res) => {
+      // A prompt (main input or approval) takes over the row; pause the spinner
+      // timer but remember whether we were busy so we can resume after.
+      this._busyResume = this._busy;
+      if (this._busyTimer) { clearInterval(this._busyTimer); this._busyTimer = null; }
+      this._busy = false;
+      this.promptLabel = promptLabel || PROMPT_PREFIX;
+      this.buf = "";
+      this.resolve = res;
+      this._guardEnterUntil = opts.guardEnter ? Date.now() + 250 : 0;
+      this._echoOnCommit = opts.echo !== false;
+      this.drawPrompt();
+    });
+  }
+
+  _onResize() {
+    this.out.write(`\x1b[1;${this.scrollBottom}r`);
+    this.footer = this.footer; // caller refreshes content separately
+    this.drawFooter();
+    this.drawPrompt();
+  }
+
+  _onData(chunk) {
+    for (const ch of chunk) {
+      if (ch === "\r" || ch === "\n") {
+        // Collapse a CRLF pair into one Enter: ignore a \n right after a \r.
+        if (ch === "\n" && this._lastWasCR) { this._lastWasCR = false; continue; }
+        this._lastWasCR = ch === "\r";
+        // Guard: ignore a bare Enter (empty buffer) that arrives immediately
+        // after a guarded prompt was shown. This stops a leftover newline from
+        // auto-resolving a confirmation the user never got to answer.
+        if (
+          this.buf === "" &&
+          this._guardEnterUntil &&
+          Date.now() < this._guardEnterUntil
+        ) {
+          continue;
+        }
+        const line = this.buf;
+        this.buf = "";
+        // Echo the committed line into the scroll area for a transcript.
+        // User input is echoed with the "you › " history prefix; approval
+        // prompts pass echo:false so their Q&A stays out of the transcript.
+        // Empty input is skipped so a bare Enter doesn't stack blank lines.
+        if (this._echoOnCommit && line.trim() !== "") {
+          const isUserPrompt = (this.promptLabel || PROMPT_PREFIX) === PROMPT_PREFIX;
+          this.log((isUserPrompt ? HISTORY_PREFIX : this.promptLabel) + line);
+        }
+        this.promptLabel = PROMPT_PREFIX;
+        this._echoOnCommit = true;
+        // Resume the loading state if a turn is still in progress (e.g. after
+        // an approval prompt hands control back to the running agent).
+        if (this._busyResume) { this._busyResume = false; this.startBusy(this._busyLabel); }
+        const r = this.resolve; this.resolve = null;
+        if (r) r(line);
+      } else if (ch === "\x7f" || ch === "\b") {  // backspace
+        this.buf = this.buf.slice(0, -1);
+        this.drawPrompt();
+      } else if (ch === "\x03") {                  // Ctrl+C
+        const r = this.resolve; this.resolve = null;
+        if (r) r("__SIGINT__");
+      } else if (ch === "\x04") {                  // Ctrl+D
+        const r = this.resolve; this.resolve = null;
+        if (r) r("__EOF__");
+      } else if (ch >= " ") {                       // printable
+        this._lastWasCR = false;
+        this.buf += ch;
+        this.drawPrompt();
+      }
+    }
+  }
+}
+
+const HELP = `
+Interactive commands:
+  /help            show this help
+  /exit, /quit     leave (session is saved)
+  /clear           start a fresh conversation (new context)
+  /history         print the message history
+  /tokens          show token usage so far
+  /yolo            toggle auto-run of commands (no confirmation)
+`;
+
+/**
+ * Run the interactive loop against a prepared Agent.
+ * @param {Agent} agent  a started (or restored) agent in interactive mode
+ * @param {object} opts  { model, autoRun }
+ */
+export async function runRepl(agent, { model, autoRun = false, fresh = true } = {}) {
+  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);
+  } else {
+    for (const line of intro) console.error(line);
+    await runPlainRepl(agent, model, yolo);
+  }
+}
+
+/** Sticky bottom-anchored REPL (real terminals). */
+async function runStickyRepl(agent, model, yolo, intro = []) {
+  const screen = new Screen();
+  const log = (text) => screen.log(text);
+  const refresh = () => screen.refresh(footerLines(agent, model, yolo));
+
+  // Approval gate: show the command, then ask for y/n/a on the prompt row.
+  agent.confirm = async (command) => {
+    log(C.yellow("$ " + command));
+    if (yolo) return true;
+    const ans = (await screen.readLine(C.yellow("run this command? [y/N/a=always] "), { guardEnter: true, echo: false })).trim().toLowerCase();
+    if (ans === "a" || ans === "always") { yolo = true; refresh(); return true; }
+    return ans === "y" || ans === "yes";
+  };
+
+  screen.enter();
+  refresh();
+  // Print the banner/intro into the scroll region so it sits above the pinned
+  // prompt instead of overlapping it.
+  for (const line of intro) log(line);
+  let turnNo = 0;
+  try {
+    while (true) {
+      const raw = await screen.readLine();
+      if (raw === "__EOF__" || raw === "__SIGINT__") break;
+      const line = raw.trim();
+      if (!line) { refresh(); continue; }
+
+      if (line.startsWith("/")) {
+        const [cmd] = line.slice(1).split(/\s+/);
+        if (cmd === "exit" || cmd === "quit") break;
+        if (cmd === "help") { log(HELP); continue; }
+        if (cmd === "clear") { agent.start(); log(C.dim("[astra] context cleared.")); refresh(); continue; }
+        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; }
+        log(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
+        continue;
+      }
+
+      const before = usageSnapshot(model);
+      const t0 = Date.now();
+      agent.addUserMessage(line);
+      screen.startBusy("working");
+      try {
+        await driveUntilChat(agent, log);
+      } finally {
+        screen.stopBusy();
+      }
+      const after = usageSnapshot(model);
+      log(
+        turnSummary({
+          turn: ++turnNo,
+          upTok: after.up - before.up,
+          downTok: after.down - before.down,
+          costUsd: after.cost - before.cost,
+          costKind: model.costSource === "reported" ? "reported" : "estimated",
+          seconds: (Date.now() - t0) / 1000,
+        })
+      );
+      refresh();
+    }
+  } finally {
+    screen.leave();
+    agent.save();
+    console.error(C.dim(`[astra] session saved: ${agent.sessionId}`));
+  }
+}
+
+/** Plain inline REPL fallback (no TTY: piped input, CI, etc.). */
+async function runPlainRepl(agent, model, yolo) {
+  agent.confirm = async (command) => {
+    console.error(C.yellow("\n$ " + command));
+    if (yolo) return true;
+    const ans = (await ask("Run this command? [y/N/a=always] ")).trim().toLowerCase();
+    if (ans === "a" || ans === "always") { yolo = true; return true; }
+    return ans === "y" || ans === "yes";
+  };
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = () => new Promise((res) => rl.question("\n" + C.green("› "), res));
+  const log = (text) => console.error(text);
+
+  try {
+    printFooterInline(agent, model, yolo);
+    let turnNo = 0;
+    while (true) {
+      const line = (await prompt()).trim();
+      if (!line) continue;
+
+      if (line.startsWith("/")) {
+        const [cmd] = line.slice(1).split(/\s+/);
+        if (cmd === "exit" || cmd === "quit") break;
+        if (cmd === "help") { console.error(HELP); continue; }
+        if (cmd === "clear") { agent.start(); console.error(C.dim("[astra] context cleared.")); printFooterInline(agent, model, yolo); continue; }
+        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; }
+        console.error(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
+        continue;
+      }
+
+      const before = usageSnapshot(model);
+      const t0 = Date.now();
+      agent.addUserMessage(line);
+      await driveUntilChat(agent, log);
+      const after = usageSnapshot(model);
+      console.error(
+        turnSummary({
+          turn: ++turnNo,
+          upTok: after.up - before.up,
+          downTok: after.down - before.down,
+          costUsd: after.cost - before.cost,
+          costKind: model.costSource === "reported" ? "reported" : "estimated",
+          seconds: (Date.now() - t0) / 1000,
+        })
+      );
+      printFooterInline(agent, model, yolo);
+    }
+  } finally {
+    rl.close();
+    agent.save();
+    console.error(C.dim(`\n[astra] session saved: ${agent.sessionId}`));
+  }
+}
+
+/** Inline footer print for the non-TTY fallback. */
+function printFooterInline(agent, model, yolo) {
+  for (const l of footerLines(agent, model, yolo)) console.error(l);
+}
+
+/** Snapshot cumulative usage counters so we can compute per-turn deltas. */
+function usageSnapshot(model) {
+  return {
+    up: model.totalPromptTokens,
+    down: model.totalCompletionTokens,
+    cost: model.totalCostUsd || 0,
+  };
+}
+
+/**
+ * Take turns until the agent produces a chat reply (or terminates). Commands
+ * run in between; their output goes back to the model automatically.
+ */
+async function driveUntilChat(agent, log) {
+  while (true) {
+    let turn;
+    try {
+      turn = await agent.runTurn();
+    } catch (err) {
+      if (err && (err.name === "GatewayError" || err.name === "ContextWindowError")) {
+        log(C.red(`[astra] ${err.message}`));
+        return;
+      }
+      throw err;
+    }
+
+    if (turn.kind === "chat") {
+      log("\n" + C.cyan("astra › ") + turn.content.trim());
+      return;
+    }
+    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; // keep going; model will react to the output
+    }
+    if (turn.kind === "declined") {
+      log(C.dim("[astra] command skipped."));
+      continue; // let the model suggest an alternative
+    }
+    if (turn.kind === "format_error") {
+      log(C.dim(`[astra] (reprompting: ${turn.error})`));
+      continue;
+    }
+    if (turn.kind === "exit") {
+      log(C.dim(`[astra] run ended: ${turn.exit_status}`));
+      return;
+    }
+  }
+}
+
+function indent(text, n = 2) {
+  const pad = " ".repeat(n);
+  const body = String(text || "").replace(/\s+$/, "");
+  return body ? body.split("\n").map((l) => pad + l).join("\n") : pad + "(no output)";
+}
+
+function printHistory(agent, log) {
+  for (const m of agent.messages) {
+    if (m.role === "system") continue;
+    const label = m.role === "assistant" ? "astra" : m.role;
+    log(C.dim(`--- ${label} ---`));
+    log(m.content.length > 800 ? m.content.slice(0, 800) + " …" : m.content);
+  }
+}
+
+function tokensLine(model) {
+  const pt = model.totalPromptTokens;
+  const ct = model.totalCompletionTokens;
+  const usd = model.totalCostUsd || 0;
+  const src = model.costSource ?? "n/a";
+  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})`);
+}

package/src/session.js

@@ -0,0 +1,99 @@
+/**
+ * Session persistence for astra.
+ *
+ * Every run (autonomous or interactive) is stored as a resumable session under
+ * ~/.astra/sessions/<id>.json. The file uses the same "astra-1" trajectory
+ * shape the Agent serializes, plus a small header (id, created, title).
+ *
+ * Interactive sessions can be resumed and continued; autonomous ones can be
+ * resumed for inspection / continuation too.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { configDir } from "./config.js";
+
+export function sessionsDir() {
+  return path.join(configDir(), "sessions");
+}
+
+export function sessionPath(id) {
+  return path.join(sessionsDir(), `${id}.json`);
+}
+
+/** Generate a short, sortable session id: YYYYMMDD-HHMMSS-<rand>. */
+export function newSessionId() {
+  const d = new Date();
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  const stamp =
+    `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-` +
+    `${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `${stamp}-${rand}`;
+}
+
+/** Persist a session document (trajectory + header) to disk. */
+export function saveSession(id, doc) {
+  const dir = sessionsDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(sessionPath(id), JSON.stringify(doc, null, 2) + "\n");
+  return sessionPath(id);
+}
+
+/** Load a session document by id. Throws if missing. */
+export function loadSession(id) {
+  const p = sessionPath(id);
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+/** True if a session with this id exists. */
+export function sessionExists(id) {
+  try {
+    fs.accessSync(sessionPath(id));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List sessions (newest first) with lightweight metadata for `--sessions`.
+ * Returns [{ id, created, mode, model, title, n_steps, exit_status }].
+ */
+export function listSessions() {
+  const dir = sessionsDir();
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    const id = f.replace(/\.json$/, "");
+    try {
+      const doc = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      out.push({
+        id,
+        created: doc.created ?? "",
+        mode: doc.info?.mode ?? "",
+        model: doc.info?.model ?? "",
+        title: doc.title ?? deriveTitle(doc),
+        n_steps: doc.info?.n_steps ?? 0,
+        exit_status: doc.info?.exit_status ?? "",
+      });
+    } catch {
+      out.push({ id, created: "", mode: "", model: "", title: "(unreadable)", n_steps: 0 });
+    }
+  }
+  out.sort((a, b) => (a.id < b.id ? 1 : -1));
+  return out;
+}
+
+/** Derive a short title from the first user/task message. */
+export function deriveTitle(doc) {
+  if (doc.title) return doc.title;
+  const firstUser = (doc.messages || []).find((m) => m.role === "user");
+  const text = (doc.info?.task || firstUser?.content || "").trim().replace(/\s+/g, " ");
+  return text ? text.slice(0, 60) : "(empty)";
+}