astra

A minimal, zero-dependency AI coding agent for the HackerRank AI Gateway, written in plain Node.js (ESM, Node ≥ 20).

astra is a small, self-contained agent that talks to the hackerrank-ai-gateway and works with every model on it. It runs in two modes from one engine:

• an interactive assistant — a chat REPL that can read files and run commands (with your approval), like a lightweight cline / claude-code;
• an autonomous task runner — give it a task and it works to completion on its own.

Every run is a resumable session, with exact token accounting and USD cost tracking.

Why it's minimal

• No dependencies. Uses Node's built-in fetch, spawn, and fs. No install step.
• Text-based action protocol. The model returns one fenced ```bash block per turn, so it works with every model on the gateway — no provider tool-calling required.
• Linear history. Every step just appends to the message list. The session is the conversation; trivial to debug and inspect.
• Stateless actions. Each command runs in a fresh bash -c subshell, so runs are easy to reason about and sandbox.

Layout

| File | Role | |---|---| | src/model.js | Gateway client (OpenAI-compatible /chat/completions). Handles retries, the max_tokens vs max_completion_tokens difference, and cost accounting. | | src/environment.js | Runs one command per action in a fresh subshell, with a per-command timeout that kills the whole process group and output truncation. | | src/prompts.js | System / instance / format-error / observation templates + a tiny {{var}} renderer, split into interactive vs autonomous rules. | | src/agent.js | The turn-based engine: query → parse one command → execute → observe → repeat. Handles submission, step/time limits, and format errors. | | src/repl.js | The interactive assistant loop: prompts, command approval, slash commands. | | src/session.js | Resumable sessions stored under ~/.astra/sessions/. | | src/config.js | Dedicated ~/.astra/config.json, credential resolution, interactive key prompt. | | src/prices.js | Public list prices used to estimate cost for models that don't report it. | | src/cli.js | Argument parsing, mode dispatch, and streaming output. |

Setup

Node ≥ 20. Install from npm:

npm install -g @hackerrank/astra

# or without a global install
npx @hackerrank/astra -m claude-sonnet-5

From a git checkout of this repo you can also run the CLI directly, or link it:

node src/cli.js -m claude-sonnet-5
npm link    # then `astra` uses this checkout

You also need an API key for the gateway. The CLI resolves it in this order (first hit wins):

1. --api-key flag
2. ASTRA_GATEWAY_API_KEY environment variable
3. ~/.astra/config.json — astra's own config (written with 0600 perms)
4. interactive prompt when run in a terminal — offers to save the key to ~/.astra/config.json so future runs pick it up automatically

The first interactive run asks for the key and can remember it. In CI, pass the key via flag or env var.

Usage

astra has two modes, sharing one engine:

Interactive assistant (no task)

A personal coding-assistant REPL. Commands need your approval by default; the whole chat is saved as a resumable session.

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.

Autonomous task run

When you pass a task with -t/-f, astra appends the autonomous rules and runs to completion, submitting via the sentinel when done.

# from an inline task
astra -m claude-sonnet-5 -t "Fix the failing test in ./app and submit."

# from a task file, running inside a specific repo
astra \
  -m gpt-5.6-sol \
  -f ./task/instruction.md \
  -C ./task/repo \
  -s 60 \
  -o ./runs/run-01.traj.json

Sessions

Every run (either mode) is saved under ~/.astra/sessions/<id>.json.

astra --sessions            # list saved sessions
astra --resume <id>         # resume (continue an interactive chat,
                            # or inspect/continue an autonomous run)

Verified working models on the gateway include claude-sonnet-5, claude-opus-5, gpt-5.6-sol, gpt-5.6-terra, gemini-3.7-flash, grok-4.6, kimi-k3, and others. Some routes (e.g. glm-5.2) may return HTTP 402 when the underlying provider is out of credits — that's a quota issue, not a bug.

Options

-m, --model <id>        Model id on the gateway (required unless --sessions)
-t, --task <text>       Task text -> autonomous mode
-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
    --sessions          List saved sessions and exit
-y, --yolo              Auto-run commands (always on in autonomous mode)
-q, --quiet             Do not stream steps (autonomous mode)
-h, --help              Show help

How the loop works

system + instance prompt
        │
        ▼
   ┌─► query model ──► parse ONE ```bash block ──► run in fresh subshell
   │        ▲                    │ (bad format)            │
   │        └── format-error ◄───┘                         ▼
   │                                              observe <returncode>/<output>
   └──────────────────────────────────────────────────────┘
                     │ command echoes the submit sentinel
                     ▼
                  Submitted

In interactive mode, a reply with no bash block is treated as a chat turn that hands control back to you; in autonomous mode the loop keeps going until the task is submitted or a limit is hit.

Termination reasons written to the session info.exit_status:

• Submitted — a command printed COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT with exit code 0.
• LimitsExceeded — hit the step limit.
• TimeExceeded — hit the wall-clock limit.
• RepeatedFormatError — too many unparseable replies in a row.
• ContextWindowExceeded — the request exceeded the model's context window.

Session / trajectory output

Each run is stored as JSON (astra-1 format):

{
  "trajectory_format": "astra-1",
  "info": {
    "mode": "autonomous",
    "exit_status": "Submitted",
    "submission": "",
    "n_steps": 2,
    "model": "claude-sonnet-5",
    "n_calls": 2,
    "elapsed_seconds": 6,
    "tokens": { "prompt": 3414, "completion": 208, "total": 3622, "last_context": 1361 },
    "cost": { "usd": 0.0139, "source": "estimated", "reported_usd": 0, "estimated_usd": 0.0139 }
  },
  "messages": [ /* full linear history: system, user, assistant, ... , exit */ ]
}

Cost & token tracking

Tokens are exact (from each response's usage). Cost is hybrid, tracking-only (no limits):

• Reported — some routes (the OpenRouter-proxied models: deepseek-v4-pro, glm-5.2, grok-4.6, kimi-k3, qwen-3.8) return an exact usage.cost in USD. We use that number directly (source: "reported").
• Estimated — native routes (Claude, GPT, Gemini) return no cost, so we estimate from src/prices.js, a table of public list prices ($/1M tokens). These are clearly marked source: "estimated" and shown with a ~ in the per-step line. Edit src/prices.js in one place if you have the real gateway pricing.

A run that mixes both is tagged source: "mixed" with the split preserved in reported_usd / estimated_usd.

Remote / Jenkins benchmarking lives in the sibling repo astra-bench, not here.