@hackerrank/astra-cli 0.1.0

package/src/model.js

@@ -0,0 +1,314 @@
+/**
+ * Minimal model client for the HackerRank AI Gateway.
+ *
+ * Zero external dependencies. Uses the OpenAI-compatible
+ * /chat/completions endpoint exposed by the gateway.
+ *
+ * The gateway (provider "hackerrank-ai-gateway") speaks the
+ * "openai-completions" API at:
+ *   https://gateway-central.ai.private.hackerrank.link/v1
+ *
+ * Configure via environment:
+ *   ASTRA_GATEWAY_BASE_URL   (default: the gateway URL above)
+ *   ASTRA_GATEWAY_API_KEY    (required)
+ */
+
+const DEFAULT_BASE_URL = "https://gateway-central.ai.private.hackerrank.link/v1";
+import { estimateCost } from "./prices.js";
+
+/** Thrown when the request exceeds the model's context window (terminal). */
+export class ContextWindowError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContextWindowError";
+  }
+}
+
+/** Detect a context-length-exceeded response across provider dialects. */
+export function isContextWindowError(status, text) {
+  if (status !== 400) return false;
+  return /context[_ ]length|context window|maximum context|too many tokens|reduce the length|input is too long|exceeds the (?:maximum|context)/i.test(
+    text || ""
+  );
+}
+
+export class GatewayModel {
+  /**
+   * @param {object} opts
+   * @param {string} opts.model        model id, e.g. "claude-sonnet-5"
+   * @param {string} [opts.baseUrl]
+   * @param {string} [opts.apiKey]
+   * @param {object} [opts.modelKwargs] extra body params (temperature, etc.)
+   * @param {number} [opts.maxRetries]
+   * @param {(info:object)=>void} [opts.onRetry] called before each retry sleep
+   */
+  constructor({ model, baseUrl, apiKey, modelKwargs = {}, maxRetries = 5, maxTokens = 8192, onRetry } = {}) {
+    if (!model) throw new Error("GatewayModel: `model` is required");
+    this.model = model;
+    this.maxTokens = maxTokens;
+    this.baseUrl = (baseUrl || process.env.ASTRA_GATEWAY_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.apiKey = apiKey || process.env.ASTRA_GATEWAY_API_KEY || "";
+    this.modelKwargs = modelKwargs;
+    this.maxRetries = maxRetries;
+    this.onRetry = onRetry || (() => {});
+    this.nCalls = 0;
+    // Cumulative token usage across all calls (exact, from the API).
+    this.totalPromptTokens = 0;
+    this.totalCompletionTokens = 0;
+    // Cumulative USD cost. `reported` = summed from the gateway's usage.cost;
+    // `estimated` = summed from the public price table (prices.js).
+    this.totalCostUsd = 0;
+    this.reportedCostUsd = 0;
+    this.estimatedCostUsd = 0;
+    this.costSource = null; // "reported" | "estimated" | "mixed" | null
+    // Preferred token-cap parameter; swapped automatically on 400 if needed.
+    this._tokenParam = "max_tokens";
+    if (!this.apiKey) {
+      throw new Error(
+        "GatewayModel: no API key. Set ASTRA_GATEWAY_API_KEY or configure ~/.astra/config.json."
+      );
+    }
+  }
+
+  /**
+   * Query the model with a full message list.
+   * @param {Array<{role:string, content:string}>} messages
+   * @returns {Promise<{content:string, raw:object, usage:object}>}
+   */
+  async query(messages) {
+    // Different models on the gateway want different token-cap params
+    // (`max_tokens` vs `max_completion_tokens`). We start with a preferred
+    // key and transparently swap if the gateway rejects it.
+    const body = {
+      model: this.model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      [this._tokenParam]: this.maxTokens,
+      ...this.modelKwargs,
+    };
+
+    let lastErr;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+          },
+          body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          // A context-window overflow is terminal, not retryable: surface it
+          // as a distinct error so the agent can end the run cleanly.
+          if (isContextWindowError(res.status, text)) {
+            throw new ContextWindowError(`Gateway HTTP ${res.status}: ${text.slice(0, 500)}`);
+          }
+          // Auto-swap the token-cap parameter if the model rejects it.
+          if (res.status === 400 && this._maybeSwapTokenParam(text, body)) {
+            continue;
+          }
+          // 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);
+            this.onRetry({
+              attempt: attempt + 1,
+              maxRetries: this.maxRetries,
+              status: res.status,
+              waitMs: wait,
+              reason: `HTTP ${res.status}`,
+            });
+            await sleep(wait);
+            continue;
+          }
+          // Non-retryable HTTP error: throw a classified, actionable error.
+          throw new GatewayError(res.status, text);
+        }
+
+        const data = await res.json();
+        this.nCalls++;
+        const content = data?.choices?.[0]?.message?.content ?? "";
+        const usage = normalizeUsage(data?.usage);
+        this.totalPromptTokens += usage.prompt_tokens;
+        this.totalCompletionTokens += usage.completion_tokens;
+        // 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);
+        usage.cost_usd = cost.usd;
+        usage.cost_kind = cost.kind; // "reported" | "estimated" | "unknown"
+        return { content, raw: data, usage };
+      } catch (err) {
+        lastErr = err;
+        // Network hiccups -> retry with backoff. Classified/terminal errors
+        // (auth, quota, context window) are re-thrown immediately.
+        if (attempt < this.maxRetries && isRetryable(err)) {
+          const wait = backoffMs(attempt);
+          this.onRetry({
+            attempt: attempt + 1,
+            maxRetries: this.maxRetries,
+            status: 0,
+            waitMs: wait,
+            reason: shortErr(err),
+          });
+          await sleep(wait);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastErr;
+  }
+
+  /**
+   * Compute and accumulate the USD cost of one call. Prefers the gateway's
+   * exact `usage.cost` (reported); falls back to the public price table
+   * (estimated). Updates totals and the aggregate cost source.
+   * @returns {{usd:number|null, kind:"reported"|"estimated"|"unknown"}}
+   */
+  _accountCost(usage) {
+    let usd = null;
+    let kind = "unknown";
+    if (usage.reported_cost != null) {
+      usd = usage.reported_cost;
+      kind = "reported";
+      this.reportedCostUsd += usd;
+    } else {
+      const est = estimateCost(this.model, usage);
+      if (est != null) {
+        usd = est;
+        kind = "estimated";
+        this.estimatedCostUsd += usd;
+      }
+    }
+    if (usd != null) {
+      this.totalCostUsd += usd;
+      this.costSource =
+        this.costSource == null || this.costSource === kind ? kind : "mixed";
+    }
+    return { usd, kind };
+  }
+
+  /**
+   * If the gateway rejects our token-cap param, swap it in-place on the body
+   * and record the new preference. Returns true if a swap happened.
+   */
+  _maybeSwapTokenParam(errText, body) {
+    const wantsCompletion =
+      /max_completion_tokens/.test(errText) && /max_tokens/.test(errText);
+    const wantsMaxTokens =
+      /max_tokens/.test(errText) &&
+      /not supported|unsupported/.test(errText) &&
+      "max_completion_tokens" in body;
+    if (wantsCompletion && "max_tokens" in body) {
+      delete body.max_tokens;
+      body.max_completion_tokens = this.maxTokens;
+      this._tokenParam = "max_completion_tokens";
+      return true;
+    }
+    if (wantsMaxTokens) {
+      delete body.max_completion_tokens;
+      body.max_tokens = this.maxTokens;
+      this._tokenParam = "max_tokens";
+      return true;
+    }
+    return false;
+  }
+}
+
+function isRetryable(err) {
+  // Never retry classified terminal errors (auth/quota/bad-request) or context
+  // overflow — those won't succeed on retry.
+  if (err instanceof GatewayError || err instanceof ContextWindowError) return false;
+  const msg = String(err?.message || err);
+  return /HTTP 5\d\d|HTTP 429|ECONNRESET|ETIMEDOUT|fetch failed|network/i.test(msg);
+}
+
+/** A classified, non-retryable HTTP error from the gateway with a hint. */
+export class GatewayError extends Error {
+  constructor(status, body) {
+    const hint = hintForStatus(status);
+    const snippet = String(body || "").slice(0, 300);
+    super(`Gateway HTTP ${status}${hint ? ` — ${hint}` : ""}${snippet ? `\n  ${snippet}` : ""}`);
+    this.name = "GatewayError";
+    this.status = status;
+    this.hint = hint;
+  }
+}
+
+/** Human-readable, actionable guidance per HTTP status. */
+function hintForStatus(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "authentication failed — check your API key (--api-key / ASTRA_GATEWAY_API_KEY / ~/.astra/config.json)";
+    case 402:
+      return "payment/quota required — the account has no credits for this model/route";
+    case 404:
+      return "model or endpoint not found — check the model id and --base-url";
+    case 429:
+      return "rate limited";
+    default:
+      if (status >= 500) return "gateway/server error";
+      return "";
+  }
+}
+
+/** 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());
+  return null;
+}
+
+/** Short one-line description of an error for retry logs. */
+function shortErr(err) {
+  return String(err?.message || err).split("\n")[0].slice(0, 120);
+}
+
+function backoffMs(attempt) {
+  const base = Math.min(1000 * 2 ** attempt, 30000);
+  return base + Math.floor(Math.random() * 500);
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Normalize the provider's `usage` object into a consistent shape.
+ * All gateway families return OpenAI-style usage; we keep the exact counts
+ * and surface cached prompt tokens when reported (Option C: provider truth,
+ * no local tokenizer / estimation).
+ */
+export function normalizeUsage(usage) {
+  const u = usage || {};
+  const prompt = num(u.prompt_tokens);
+  const completion = num(u.completion_tokens);
+  const total = u.total_tokens != null ? num(u.total_tokens) : prompt + completion;
+  const cached = num(u.prompt_tokens_details?.cached_tokens);
+  const cacheWrite = num(u.prompt_tokens_details?.cache_write_tokens);
+  const reasoning = num(u.completion_tokens_details?.reasoning_tokens);
+  // Some routes (OpenRouter-proxied) report the exact USD cost. Keep it when
+  // present so we never have to estimate for those models.
+  const reportedCost = u.cost != null && Number.isFinite(Number(u.cost)) ? Number(u.cost) : null;
+  return {
+    prompt_tokens: prompt,
+    completion_tokens: completion,
+    total_tokens: total,
+    cached_tokens: cached,
+    cache_write_tokens: cacheWrite,
+    reasoning_tokens: reasoning,
+    reported_cost: reportedCost,
+    cost_details: u.cost_details || null,
+  };
+}
+
+function num(v) {
+  return Number.isFinite(v) ? v : 0;
+}

package/src/prices.js

@@ -0,0 +1,60 @@
+/**
+ * Public list prices for cost ESTIMATION — used only for models whose gateway
+ * responses do NOT include an exact `usage.cost` (the "native" routes:
+ * Anthropic Claude, OpenAI GPT, Google Gemini).
+ *
+ * For the OpenRouter-proxied routes (deepseek, glm, grok, kimi, qwen) the
+ * gateway returns an exact `usage.cost` in USD, so those are NOT listed here —
+ * we use the reported number directly and never touch this table.
+ *
+ * IMPORTANT — these are ESTIMATES:
+ *   - The gateway exposes internal aliases (e.g. `gpt-5.6-sol`, `claude-opus-5`,
+ *     `gemini-3.7-flash`) that do not map 1:1 to a public SKU. Each entry below
+ *     maps an alias to the CLOSEST current public tier and cites the source.
+ *   - Prices are USD per 1,000,000 tokens (the unit every vendor publishes).
+ *   - `cachedInput` is the discounted rate for cached prompt tokens where the
+ *     vendor publishes one; if omitted, cached tokens are billed at `input`.
+ *   - Edit any number here in one place if you have the real gateway pricing.
+ *
+ * Sources (public list prices, captured for reference):
+ *   Anthropic:  https://www.anthropic.com/pricing
+ *   OpenAI:     https://openai.com/api/pricing/
+ *   Google:     https://ai.google.dev/gemini-api/docs/pricing
+ */
+
+// USD per 1M tokens. cachedInput optional.
+export const PRICES = {
+  // --- Anthropic Claude (native route, no reported cost) ---------------------
+  // Mapped to Claude Opus tier (highest). Source: anthropic.com/pricing.
+  "claude-opus-5": { input: 15.0, output: 75.0, cachedInput: 1.5, note: "~Claude Opus tier" },
+  // Mapped to Claude Sonnet tier. Source: anthropic.com/pricing.
+  "claude-sonnet-5": { input: 3.0, output: 15.0, cachedInput: 0.3, note: "~Claude Sonnet tier" },
+
+  // --- OpenAI GPT (native route, no reported cost) ---------------------------
+  // The gpt-5.6-* aliases (luna/sol/terra) are treated as one GPT-5-class tier.
+  // Mapped to GPT-5 public pricing. Source: openai.com/api/pricing.
+  "gpt-5.6-luna": { input: 1.25, output: 10.0, cachedInput: 0.125, note: "~GPT-5 tier" },
+  "gpt-5.6-sol": { input: 1.25, output: 10.0, cachedInput: 0.125, note: "~GPT-5 tier" },
+  "gpt-5.6-terra": { input: 1.25, output: 10.0, cachedInput: 0.125, note: "~GPT-5 tier" },
+
+  // --- Google Gemini (native route, no reported cost) ------------------------
+  // Mapped to Gemini Flash tier. Source: ai.google.dev/gemini-api/docs/pricing.
+  "gemini-3.7-flash": { input: 0.3, output: 2.5, cachedInput: 0.075, note: "~Gemini Flash tier" },
+};
+
+/**
+ * Estimate the USD cost of one call from token counts + the table above.
+ * Returns null when we have no price entry for the model (unknown alias).
+ */
+export function estimateCost(model, usage) {
+  const p = PRICES[model];
+  if (!p) return null;
+  const prompt = usage.prompt_tokens || 0;
+  const cached = Math.min(usage.cached_tokens || 0, prompt);
+  const uncached = prompt - cached;
+  const completion = usage.completion_tokens || 0;
+  const inRate = p.input / 1e6;
+  const cacheRate = (p.cachedInput ?? p.input) / 1e6;
+  const outRate = p.output / 1e6;
+  return uncached * inRate + cached * cacheRate + completion * outRate;
+}

package/src/prompts.js

@@ -0,0 +1,91 @@
+/**
+ * Prompt templates + a tiny {{var}} renderer.
+ *
+ * We use a TEXT-based action protocol (a single fenced bash block) rather than
+ * provider tool-calling, so the exact same harness works with every model on
+ * the gateway.
+ *
+ * The system prompt is assembled from a shared BASE plus a mode-specific block:
+ *   - AUTONOMOUS_RULES  when a --task is given (benchmark / run-to-completion)
+ *   - INTERACTIVE_RULES for the chat REPL (a personal SWE assistant)
+ */
+
+export const BASE_SYSTEM = `You are a precise software engineering agent working in a shell.
+
+To run a shell command, your response MUST contain exactly ONE bash code block
+containing ONE command (you may chain with && or ||). Explain your reasoning in
+plain text BEFORE the command block. Format exactly like <format_example>.
+
+<format_example>
+Your reasoning here: what you observed and what you will do next.
+
+\`\`\`bash
+your_command_here
+\`\`\`
+</format_example>
+
+Shell rules:
+1. A command-running response contains exactly one bash code block, one command.
+2. Directory and environment changes are NOT persistent — every command runs in
+   a fresh subshell. Chain state in a single command, e.g.
+   \`cd /path && VAR=1 some_command\`.
+
+System: {{system}} {{release}} {{machine}} | cwd: {{cwd}}`;
+
+export const AUTONOMOUS_RULES = `
+Autonomous mode:
+- Do NOT ask the user questions; work autonomously until the task is done.
+- You are permitted and expected to read and use any available credentials,
+  environment variables, and config files needed to complete the task.
+- When completely finished, run this and NOTHING else:
+  \`echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT\`
+  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.
+- 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.`;
+
+export const INSTANCE_TEMPLATE = `Please complete this task:
+
+{{task}}
+
+Recommended workflow:
+1. Explore the repository / working directory to understand context.
+2. Make focused edits to implement the required behavior.
+3. Verify by building and/or running tests.
+4. Iterate until it works, then submit.
+
+When done, submit by running exactly:
+\`echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT\``;
+
+export const FORMAT_ERROR = `Your last response could not be parsed.
+{{error}}
+
+Respond again with exactly ONE bash code block containing ONE command, like:
+
+\`\`\`bash
+your_command_here
+\`\`\``;
+
+export const OBSERVATION_TEMPLATE = `{{exception}}<returncode>{{returncode}}</returncode>
+<output>
+{{output}}
+</output>`;
+
+/** Build the full system prompt for a given mode ("autonomous" | "interactive"). */
+export function buildSystemPrompt(mode, vars) {
+  const rules = mode === "interactive" ? INTERACTIVE_RULES : AUTONOMOUS_RULES;
+  return render(BASE_SYSTEM + "\n" + rules, vars);
+}
+
+/** Minimal, safe {{var}} substitution (no logic, no eval). */
+export function render(template, vars) {
+  return template.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_, key) =>
+    key in vars && vars[key] != null ? String(vars[key]) : ""
+  );
+}