npm - astrabot - Versions diffs - 0.1.0 → 0.1.1 - Mend

astrabot 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +730 -251
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,30 +1,52 @@
-# Astra
+<div align="center">
-**AI-native development companion — agentic coding in your terminal.**
+# ✨ Astra
-Astra gives a Large Language Model full programmatic access to your filesystem, shell, and the web — all gated behind a staging-first approval pipeline that keeps you in control. Built on [Bun](https://bun.sh), powered by [OpenRouter](https://openrouter.ai), and driven by the [Vercel AI SDK](https://sdk.vercel.ai).
+**AI-native development companion — Agent, Ask, Plan, and Multi-Agent modes in your terminal.**
+[![npm version](https://img.shields.io/npm/v/astrabot?style=flat-square&logo=npm)](https://www.npmjs.com/package/astrabot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-bun-black?style=flat-square&logo=bun)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+</div>
 ---
 ## Table of Contents
+- [What Is Astra?](#what-is-astra)
 - [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+  - [Option 1: Install Globally via npm](#option-1-install-globally-via-npm)
+  - [Option 2: Run Directly with npx (No Installation)](#option-2-run-directly-with-npx-no-installation)
+  - [Option 3: Install from Source](#option-3-install-from-source)
 - [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Required Environment Variables](#required-environment-variables)
+  - [Optional Environment Variables](#optional-environment-variables)
+  - [Running the Setup Wizard](#running-the-setup-wizard)
 - [Commands](#commands)
+  - [`astra wakeup`](#astra-wakeup)
+  - [`astra setup`](#astra-setup)
+  - [`astra play`](#astra-play)
+  - [`astra reset`](#astra-reset)
 - [Interaction Modes](#interaction-modes)
   - [Auto Mode](#auto-mode)
   - [Agent Mode](#agent-mode)
   - [Ask Mode](#ask-mode)
   - [Plan Mode](#plan-mode)
   - [Multi-Agent Mode](#multi-agent-mode)
-- [Architecture](#architecture)
-  - [Core Components](#core-components)
-  - [Tool System](#tool-system)
-  - [Staging & Approval Pipeline](#staging--approval-pipeline)
-  - [Action Tracking](#action-tracking)
-  - [Session Management](#session-management)
-  - [Auto-Retry Engine](#auto-retry-engine)
-- [Environment Variables](#environment-variables)
+- [Tool System — Complete Reference](#tool-system--complete-reference)
+- [Staging & Approval Pipeline](#staging--approval-pipeline)
+- [Session Management](#session-management)
+- [Multi-Agent Orchestration](#multi-agent-orchestration)
+  - [Orchestration Strategies](#orchestration-strategies)
+  - [Agent Roles](#agent-roles)
+  - [Workflow Templates](#workflow-templates)
+  - [Workflow Builder (Fluent API)](#workflow-builder-fluent-api)
+- [Retry & Error Handling](#retry--error-handling)
 - [Project Structure](#project-structure)
 - [Dependencies](#dependencies)
 - [Roadmap](#roadmap)
@@ -32,77 +54,290 @@ Astra gives a Large Language Model full programmatic access to your filesystem,
 ---
+## What Is Astra?
+Astra is an **AI-native development companion** that brings **agentic coding capabilities** directly to your terminal. Rather than being a simple chatbot or code-completion engine, Astra gives a Large Language Model (LLM) **full programmatic access** to your filesystem, shell, and the web — all gated behind a **carefully designed approval system** that keeps you in control at all times.
+Built on **[Bun](https://bun.sh)**, powered by **[OpenRouter](https://openrouter.ai)** (supporting any model on that platform), and leveraging the **[Vercel AI SDK](https://sdk.vercel.ai)**'s `ToolLoopAgent` for autonomous, multi-step tool-driven workflows.
+Astra provides **five distinct interaction modes** within a single CLI interface:
+| Mode | Purpose | File Mutations? |
+|------|---------|:---------------:|
+| **Auto** | LLM-powered intent router — automatically picks the best mode for your request | Depends on route |
+| **Agent** | Autonomous multi-step code modifications | ✅ (staged) |
+| **Ask** | Read-only Q&A about your codebase | ❌ (except optional save) |
+| **Plan** | Structured multi-step planning with selective execution | ✅ (staged) |
+| **Multi-Agent** | Multiple agents working together in configurable topologies | ✅ (staged) |
+---
 ## Features
+### 🧠 AI-Powered Development
 - **Five interaction modes** — Auto, Agent, Ask, Plan, and Multi-Agent, each tailored to a different development workflow
-- **Auto-router** — classifies user intent and routes to the correct mode automatically
-- **Full filesystem access** — read, create, modify, and delete files and directories through an AI agent, all via an in-memory staging overlay
-- **Shell execution** — queue arbitrary shell commands for agent-driven workflows (sync and background)
-- **Git integration** — `git status`, `git diff`, and `git log` tools for repository awareness
-- **Project-aware tooling** — run tests, linting, formatting, and framework detection by reading `package.json`
-- **Web research** — built-in web search (via DuckDuckGo or Firecrawl), URL crawling, and HTTP fetching
-- **Staging-first mutations** — no file is ever written or deleted without explicit user approval; all changes are staged in memory and presented for review before apply
+- **35+ agent tools** — full filesystem access, shell execution, git integration, web research, project-aware tooling, and more
+- **Auto-router** — automatically classifies your request and routes it to the most appropriate mode
+- **Multi-model support** — different agents can use different LLMs in Multi-Agent mode
+### 🔒 Safety First
+- **Staging-first mutations** — no file is ever written or deleted without your explicit approval; all changes are staged in memory and presented for review before apply
 - **Per-file diff review** — granular approval flow with unified diffs so you can inspect exactly what changed
-- **Skill system** — discover and load `SKILL.md` files from Cursor and Claude skill directories, plus custom directories via `SKILLS_DIRS`
-- **Session management** — sessions are persisted to disk with context summaries, enabling resumption after interruption
-- **Auto-retry engine** — exponential backoff with jitter for resilient AI provider calls
-- **Configurable safety** — exclude patterns, file size limits, and per-tool permission toggles per agent role
-- **Rich terminal UI** — interactive prompts via `@clack/prompts`, markdown rendering, ASCII banner on startup, animated spinners, and colored logging
+- **Configurable safety** — exclude patterns (`node_modules`, `.git`, `dist`, `build`, `.next`, `*.log`, `.env*`), file size limits (default 1 MB), and per-tool permission toggles per agent role
+- **Path traversal prevention** — strict boundary validation on all filesystem operations
+### 💾 Session Management
+- **Persistent sessions** — sessions are stored to disk with LLM-generated summaries, enabling resumption after interruption
+- **Auto-resume** — interrupted sessions are detected on startup and offered for resumption
+- **Session tools** — agents can query previous sessions via built-in `session_status`, `session_search`, and `session_resume_context` tools
+- **Multi-turn goal tracking** — tracks every user goal across a session for full context awareness
+### 👥 Multi-Agent Orchestration
+- **Four orchestration strategies** — Sequential, Parallel, Hierarchical, and Collaborative
+- **DAG (Directed Acyclic Graph)** — agents run when dependencies are satisfied, with cycle detection and deadlock handling
+- **Five agent roles** — Researcher, Implementer, Reviewer, Coordinator, and Custom
+- **Six pre-built workflow templates** — Code Review, Feature Development, Bug Fixing, Collaborative Research, Security Audit, and Full-Stack Feature
+- **Fluent workflow builder** — programmatically construct custom agent topologies with validation
+- **Inter-agent messaging** — publish-subscribe communication channel for collaborative workflows
+- **Per-agent retry** — configurable retry logic with exponential backoff for each agent
+### 🌐 Web Research
+- **Web search** — via Firecrawl SDK or DuckDuckGo fallback
+- **Web crawling** — scrape any URL into markdown via Firecrawl
+- **URL fetching** — HTTP GET with response body extraction
+### 🎨 Rich Terminal UI
+- **Interactive prompts** — via `@clack/prompts` (select, confirm, text, multiselect, autocomplete)
+- **Markdown rendering** — agent responses rendered as formatted markdown in the terminal
+- **ASCII art banner** — animated breathing banner with twinkling star field on startup
+- **Animated spinners** — metabolic-rate-based spinner with dynamic color gradients and elapsed time
+- **Colored logging** — green for agent actions, cyan for ask mode, yellow for warnings, red for errors
+### 🎮 Easter Egg
+- **Arcade mini-games** — Retro Snake Classic and Neon Brick Breaker, served via Bun's native HTTP server
 ---
-## Quick Start
-### Prerequisites
+## Prerequisites
 | Requirement | Version | Purpose |
 |-------------|---------|---------|
-| [Bun](https://bun.sh) | >=1.0.0 | Runtime and package manager |
-| [OpenRouter](https://openrouter.ai) API key | — | LLM provider access (required) |
-| [Firecrawl](https://www.firecrawl.dev/) API key | — | Web search and crawling (optional) |
+| [Bun](https://bun.sh) | >= 1.0.0 | JavaScript/TypeScript runtime |
+| [OpenRouter](https://openrouter.ai) API key | — | LLM provider access (**required**) |
+| [Firecrawl](https://www.firecrawl.dev/) API key | — | Web search and crawling (**optional**) |
+| [Node.js](https://nodejs.org) | >= 18 | For npm/npx (if not using Bun directly) |
-### Installation
+> **Note:** Astra runs on **Bun**, not Node.js. Bun is used as the runtime for executing the TypeScript source directly. npm/npx are used only for package distribution.
+---
+## Installation
+### Option 1: Install Globally via npm
+This is the recommended approach for regular use. Installing globally makes the `astra` command available system-wide.
 ```bash
-git clone <repository-url>
-cd astra
-bun install
+npm install -g astrabot
 ```
-### Configuration
+After installation, verify it works:
-Run the interactive setup wizard:
+```bash
+astra --version
+```
+You can now run Astra from any directory:
 ```bash
-bun run index.ts setup
+cd /path/to/your/project
+astra setup      # Configure API keys
+astra wakeup     # Launch the interactive menu
 ```
-This creates `~/.astra/.env` with your API keys and preferred model. Alternatively, create the file manually:
+To update to the latest version:
+```bash
+npm update -g astrabot
+```
+To uninstall:
+```bash
+npm uninstall -g astrabot
+```
+### Option 2: Run Directly with npx (No Installation)
+If you don't want to install anything permanently, you can run Astra directly using `npx`. This downloads and executes the package on-the-fly each time.
+```bash
+# Run the setup wizard
+npx astrabot setup
+# Launch the interactive menu
+npx astrabot wakeup
+# Show the version
+npx astrabot --version
-```env
-OPENROUTER_API_KEY=sk-or-...
-OPENROUTER_DEFAULT_MODEL=anthropic/claude-sonnet-4.5
-FIRECRAWL_API_KEY=fc-...            # optional
-SKILLS_DIRS=/path/to/skills         # optional
+# Launch the arcade easter egg
+npx astrabot play
+# Reset all configuration and sessions
+npx astrabot reset
 ```
-### Launch
+> **Tip:** The first run with `npx` may take a few seconds as it downloads the package. Subsequent runs are faster due to npx's cache.
+### Option 3: Install from Source
+For development or if you want to modify the code:
 ```bash
+# Clone the repository
+git clone https://github.com/<your-username>/astrabot.git
+cd astrabot
+# Install dependencies
+bun install
+# Link the binary globally (optional)
+bun link
+# Or run directly
+bun run index.ts setup
 bun run index.ts wakeup
 ```
 ---
+## Quick Start
+```bash
+# 1. Install Astra
+npm install -g astrabot
+# 2. Configure your API keys (interactive wizard)
+astra setup
+# → Enter your OpenRouter API key (required)
+# → Select a model (e.g., anthropic/claude-3.5-sonnet)
+# → Optionally set Firecrawl API key for web search
+# → Optionally set custom skills directories
+# 3. Navigate to your project
+cd /path/to/your/project
+# 4. Launch Astra
+astra wakeup
+# 5. Choose a mode:
+#    → Interactive CLI Mode → select Agent / Ask / Plan / Multi-Agent / Auto
+#    → Follow the prompts and approve changes when asked
+```
+---
+## Configuration
+Astra is configured entirely through environment variables, loaded from `~/.astra/.env`.
+### Required Environment Variables
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `OPENROUTER_API_KEY` | OpenRouter API key for LLM access | `sk-or-v1-abc123...` |
+| `OPENROUTER_DEFAULT_MODEL` | Default model identifier | `anthropic/claude-3.5-sonnet` |
+### Optional Environment Variables
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `FIRECRAWL_API_KEY` | Enables `web_search`, `web_crawl`, and `fetch_url` tools via Firecrawl SDK | `fc-abc123...` |
+| `SKILLS_DIRS` | Semicolon-separated paths to custom skill directories | `/path/to/skills;/another/dir` |
+### Retry Configuration Variables
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ASTRA_AGENT_RETRY_ENABLED` | `true` | Enable automatic retry for agent AI calls |
+| `ASTRA_AGENT_RETRY_MAX` | `3` | Maximum retry attempts for agent calls |
+| `ASTRA_AGENT_RETRY_PROGRESS` | `true` | Show retry progress in the terminal |
+| `ASTRA_MULTI_RETRY_ENABLED` | `true` | Enable retry for multi-agent steps |
+| `ASTRA_MULTI_RETRY_MAX` | `2` | Maximum retry attempts for multi-agent steps |
+| `ASTRA_MULTI_RETRY_BACKOFF` | `2` | Backoff multiplier for multi-agent retries |
+### Config File Locations
+| Path | Purpose |
+|------|---------|
+| `~/.astra/.env` | Environment variables (API keys, model, optional settings) |
+| `~/.astra/sessions/index.json` | Session store (persisted conversation history) |
+| `~/.astra/sessions/<session-id>.json` | Individual session action logs |
+### Running the Setup Wizard
+The easiest way to configure Astra is through the interactive setup wizard:
+```bash
+astra setup
+```
+The wizard will:
+1. Prompt for your **OpenRouter API key** (required)
+2. Fetch all available models from OpenRouter and let you **search and select** one with pricing information
+3. Optionally configure a **Firecrawl API key** for web search and crawling
+4. Optionally configure **custom skills directories**
+5. Save everything to `~/.astra/.env`, preserving existing values
+You can re-run `astra setup` at any time to update your configuration.
+---
 ## Commands
-| Command | Description |
-|---------|-------------|
-| `astra wakeup` | Display the banner and pick an interaction mode |
-| `astra setup` | Interactive configuration wizard for `~/.astra/.env` |
-| `astra play` | Launch the arcade mini-game (Snake or Neon Breaker) |
-| `astra reset` | Purge all stored configurations, sessions, and credentials |
-| `astra --version` | Print the current version |
+### `astra wakeup`
+```bash
+astra wakeup
+```
+Launches the main entry point. Displays the animated ASCII art banner and presents the top-level mode selection:
+- **Interactive CLI Mode** → enters the mode loop (Auto / Agent / Ask / Plan / Multi-Agent)
+- **Telegram Gateway Interface** → placeholder (not yet implemented)
+- **Exit Application** → quits
+Before the mode menu, it automatically checks for interrupted sessions and offers to resume them.
+### `astra setup`
+```bash
+astra setup
+```
+Interactive configuration wizard for API keys and settings. See [Configuration](#configuration) above.
+### `astra play`
+```bash
+astra play
+```
+Launches the arcade easter egg — an interactive game selector that lets you choose between:
+- **Retro Snake Classic** — full Snake game with gradient backgrounds, glow effects, snake eyes, input queue, high score in localStorage, mobile touch controls, pause/resume, and High DPI support
+- **Neon Brick Breaker** — Brick Breaker game built with HTML5 Canvas
+A local Bun HTTP server is spawned on port `4321` and the game is automatically opened in your default browser.
+### `astra reset`
+```bash
+astra reset
+```
+Interactive danger-zone command that completely purges **all** stored configurations, sessions, and credentials from `~/.astra/`. Requires explicit confirmation before proceeding.
 ---
@@ -110,302 +345,546 @@ bun run index.ts wakeup
 ### Auto Mode
-Auto mode classifies your natural-language request and routes it to the correct downstream mode (Agent, Ask, Plan, or Multi-Agent) automatically.
+Auto mode uses an LLM-based intent classifier to automatically determine which mode is best suited for your request:
 ```
-You: "fix the bug in store.ts"
-→ Router classifies as "agent" → executes Agent Mode
+User: "fix the bug in store.ts"
+  → Classified as: agent
+User: "explain how this app works"
+  → Classified as: ask
-You: "explain how this app works"
-→ Router classifies as "ask" → executes Ask Mode
+User: "design a new authentication system"
+  → Classified as: plan
+User: "run a security audit with multiple reviewers"
+  → Classified as: multi
 ```
-**How it works:**
+The classification prompt instructs the LLM to respond with exactly one word: `ask`, `plan`, `multi`, or `agent`. On classification failure, it defaults to `agent`. The user's original prompt is forwarded to the selected mode, so no information is lost.
-1. You type any request
-2. An LLM classifies the intent into one of four categories
-3. The session is logged with the routing decision
-4. The selected mode executes with your original prompt
+Auto mode creates its own session entry to log the routing decision before delegating.
 ### Agent Mode
-The primary autonomous coding mode. You describe a goal, and the agent iteratively uses its toolset — reading files, writing code, running shell commands — to accomplish it.
+The primary autonomous coding mode. The agent has full access to all tools and can perform multi-step file modifications, shell commands, and web research.
 **Flow:**
-1. You provide a natural-language goal
-2. The agent enters a tool loop (up to 50 steps), calling tools to explore and modify the codebase
-3. Each tool call is logged and displayed in real time
-4. After the agent finishes, the **approval flow** presents all staged changes grouped by file
-5. You can **accept all**, **review individually** (with diffs), or **cancel**
-6. Approved changes are applied to disk; rejected changes are discarded
-**Available tools (35+):**
-| Category | Tools |
-|----------|-------|
-| Filesystem | `read_file`, `create_file`, `modify_file`, `delete_file`, `create_folder`, `list_files`, `search_files`, `read_multiple_files`, `replace_in_file`, `append_to_file`, `insert_at_line` |
-| Shell | `run_command`, `run_background_command`, `execute_shell` |
-| Git | `git_status`, `git_diff`, `git_log` |
-| Project | `run_tests`, `run_test_file`, `lint_project`, `format_project`, `detect_framework`, `read_package_json`, `analyze_codebase` |
-| Search | `grep` |
-| Web | `web_search`, `fetch_url`, `web_crawl` (requires Firecrawl) |
-| Skills | `list_skills`, `read_skill` |
-| Session | `session_status`, `session_history` |
-| Planning | `create_plan`, `get_plan`, `show_pending_changes`, `discard_changes` |
+1. **Goal input** — "What would you like the agent to do for you?"
+2. **Agent execution** — the LLM autonomously calls tools (up to 50 steps) to accomplish the goal
+3. **Live tool logging** — each tool call is logged in real-time with the tool name and parameters
+4. **Approval flow** — all staged changes are presented for review with diffs
+5. **Apply** — approved changes are written to disk
+**Key behaviors:**
+- All mutations are staged in an in-memory overlay — nothing touches disk until you approve
+- File creations during the agent loop go through immediate per-file approval
+- On AI provider errors, automatic retry kicks in (configurable, default 3 retries with exponential backoff)
+- If all retries are exhausted, you're offered a manual retry option
+- Sessions are automatically created and can be resumed if interrupted
 ### Ask Mode
-A **read-only** Q&A interface. The agent can explore your codebase and the web to answer questions, but cannot modify files (with the optional exception of saving the response).
+A read-only Q&A interface. The agent can read files, search the codebase, and browse the web, but **cannot modify any files** (except optionally saving the response).
 **Flow:**
+1. **Question input** — "What do you like the agent to do for you?"
+2. **Read-only agent** — the LLM uses only read-only tools (up to 25 steps)
+3. **Answer display** — response rendered as formatted markdown in the terminal
+4. **Optional save** — you can save the Q&A as a `.md` file with `## Question` / `## Answer` formatting
-1. You ask a question
-2. The agent uses read-only tools to formulate an answer
-3. The answer is rendered as markdown in the terminal
-4. You're given the option to save the Q&A pair as a `.md` file
-**Available tools:** All read-only tools from Agent mode (filesystem read, search, codebase analysis, git, web, skills, session). All mutation tools are stripped.
+**Retry logic:** Ask mode has a bounded retry loop (max 5 attempts) with exponential backoff and jitter for resilience against transient provider errors.
 ### Plan Mode
-Breaks a high-level goal into a structured, executable plan. The agent researches your codebase, generates a step-by-step plan, and you select which steps to execute.
+Breaks a high-level goal into a structured, executable plan with selective step execution.
 **Flow:**
+1. **Goal input** — "What is your goal?"
+2. **Plan generation** — the LLM researches the codebase and generates a structured plan (1–20 steps) with complexity ratings (`low`, `medium`, `high`)
+3. **Plan display** — numbered steps with color-coded complexity tags
+4. **Step selection** — interactive multiselect to choose which steps to execute (all pre-selected)
+5. **Execution** — each selected step runs as an independent `ToolLoopAgent` (50 steps max each)
+6. **Batch approval** — all changes across all steps are presented together for review
+7. **Apply** — approved changes are written to disk
-1. You describe a high-level goal
-2. The agent researches the codebase and generates a structured plan (1–20 steps) with complexity ratings (`low`, `medium`, `high`)
-3. The plan is displayed with a research summary and numbered steps
-4. You select which steps to execute (all selected by default)
-5. Each selected step runs as an independent agent loop (up to 50 steps per step)
-6. All mutations across all steps are collected and presented in a single approval flow
+**Web research during planning:** If `FIRECRAWL_API_KEY` is set, the planner can search the web and crawl URLs during plan generation.
 ### Multi-Agent Mode
-Coordinates multiple AI agents working together on complex workflows.
+Coordinates multiple AI agents working together on complex tasks. This is the most powerful mode, supporting sophisticated agent topologies.
-**Workflow selection:**
+**Flow:**
+1. **Goal input** — "What complex operations workflow would you like to run?"
+2. **AI-powered workflow design** — the LLM analyzes your goal and either selects a pre-built template or designs a custom agent team with a specific orchestration strategy
+3. **Workflow validation** — 10+ validation checks ensure the workflow is well-formed
+4. **Execution** — agents run according to the chosen strategy
+5. **Results display** — execution summary with status, duration, pool stats, and per-agent results
+6. **Per-agent approval** — changes are reviewed per agent with diffs, then applied
-- **Use predefined template** — choose from 6 templates:
+**AI workflow designer:** The LLM analyzes your task and responds with a JSON configuration specifying:
+- Which pre-built template to use (if any), OR
+- A custom agent team with specific roles, models, and an orchestration strategy
-| Template | Agents | Strategy |
-|----------|--------|----------|
-| Code Review | Researcher → Implementer → Reviewer | Sequential |
-| Feature Development | Coordinator → Backend Dev + Frontend Dev → QA | Hierarchical |
-| Bug Fix | Debug Agent → Fix Agent → Test Agent | Sequential |
-| Collaborative Research | Researcher 1 + Researcher 2 + Researcher 3 | Parallel |
-| Security Audit | Scanner → Analyzer → Reporter | Sequential |
-| Full-Stack Feature | Database + API + UI (parallel) | Hierarchical |
+---
-- **AI-smart build** — the LLM analyzes your goal and automatically designs a custom agent topology with the optimal strategy and role assignments
+## Tool System — Complete Reference
-**Orchestration strategies:**
+Astra exposes **35+ tools** to the AI agent, organized into four categories:
-| Strategy | Behavior |
-|----------|----------|
-| **Sequential** | Agents run one after another; each agent's output is visible to subsequent agents |
-| **Parallel** | Agents run concurrently in batches (default 3 at a time) |
-| **Hierarchical** | Coordinator runs first (planning), then specialists execute |
-| **Collaborative** | Agents take turns; outputs are broadcast via a message broker |
+### File System Tools
-**Agent roles and permissions:**
+| Tool | Description | Mutates? |
+|------|-------------|:--------:|
+| `read_file` | Read a text file from the workspace | ❌ |
+| `read_multiple_files` | Read multiple files in a single call | ❌ |
+| `create_file` | Stage creation of a new file | ✅ |
+| `modify_file` | Stage a full-file replacement | ✅ |
+| `delete_file` | Stage deletion of a file | ✅ |
+| `create_folder` | Stage creation of a directory tree | ✅ |
+| `list_files` | List files and directories under a path | ❌ |
+| `search_files` | Find files matching a glob pattern with optional content filter | ❌ |
+| `analyze_codebase` | Summarize structure: file counts, directory counts | ❌ |
+| `grep` | Search file contents using a text query | ❌ |
+| `replace_in_file` | Replace text inside a file | ✅ |
+| `append_to_file` | Append content to the end of a file | ✅ |
+| `insert_at_line` | Insert content at a specific line number | ✅ |
-| Role | Permissions | Default Max Steps | Tools |
-|------|------------|-------------------|-------|
-| Researcher | Read-only | 30 | 16 |
-| Implementer | Full read/write/execute | 50 | 26 |
-| Reviewer | Read + execute (no write) | 25 | 15 |
-| Coordinator | Read-only + planning | 20 | 8 |
-| Custom | Based on selected tools | 30 | Variable |
+### Shell & Execution Tools
----
+| Tool | Description | Mutates? |
+|------|-------------|:--------:|
+| `run_command` | Run a command synchronously and capture output | ❌ |
+| `run_background_command` | Start a long-running detached process | ❌ |
+| `execute_shell` | Queue a shell command for post-approval execution | ✅ |
+| `run_tests` | Run the project's test suite (auto-detects runner) | ❌ |
+| `run_test_file` | Run a specific test file | ❌ |
+| `lint_project` | Run linting (auto-detects: eslint, etc.) | ❌ |
+| `format_project` | Run formatting (auto-detects: prettier, etc.) | ❌ |
-## Architecture
+### Git Tools
-### Core Components
+| Tool | Description |
+|------|-------------|
+| `git_status` | Get `git status --short` |
+| `git_diff` | Get `git diff` (optionally staged) |
+| `git_log` | Get recent commits (`git log --oneline`) |
-| File | Responsibility |
-|------|----------------|
-| `index.ts` | Entry point; registers commands via Commander |
-| `tui/wakeup.ts` | Banner rendering and top-level mode selection |
-| `tui/terminal-md.ts` | Markdown-to-terminal rendering via `marked` + `marked-terminal` |
-| `tui/spinner.ts` | Animated spinner with elapsed time display |
-| `modes/cli.ts` | CLI mode loop (Auto / Agent / Plan / Ask / Multi-Agent) |
-| `modes/auto.ts` | Auto-router: LLM-based intent classification |
-| `modes/setup.ts` | Interactive configuration wizard |
-| `ai/ai.config.ts` | OpenRouter provider initialization |
-| `ai/config-loader.ts` | Manages `~/.astra/.env` file |
-| `ai/auto-retry.ts` | Automatic retry with exponential backoff |
-| `ai/retry-prompt.ts` | Manual retry prompt fallback |
+### Project Intelligence Tools
-### Tool System
+| Tool | Description |
+|------|-------------|
+| `detect_framework` | Detect framework from `package.json` (Next.js, React, Vue, Svelte, Node.js) |
+| `read_package_json` | Read and summarize `package.json` |
-The tool system has two layers:
+### Web Tools
-1. **`ToolExecutor`** (`modes/agent/tool-executor.ts`) — The core execution engine. All filesystem operations, shell commands, and skill lookups are implemented here. Mutations are staged in an in-memory overlay and never touch disk until explicitly approved.
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `web_search` | Search the web (returns title/url/snippet) | Firecrawl key (or DuckDuckGo fallback) |
+| `web_crawl` | Scrape a URL into markdown | Firecrawl key |
+| `fetch_url` | HTTP GET for a URL, returns response body | — |
-2. **`createAgentTools()`** (`modes/agent/agent-tools.ts`) — Wraps every `ToolExecutor` method as a Vercel AI SDK `tool()` with a Zod input schema, making them available to the LLM agent.
+### Planning Tools
-Additional tool sets:
-- **`createWebTools()`** (`modes/plan/web-tools.ts`) — Firecrawl-based web search, crawl, and fetch tools
-- **`createSessionTools()`** (`session/session-tools.ts`) — `session_status` and `session_history` tools injected into every agent
+| Tool | Description |
+|------|-------------|
+| `create_plan` | Create a task execution plan |
+| `get_plan` | Retrieve the current plan |
-### Staging & Approval Pipeline
+### Staging Tools
-This is the safety backbone of Astra. No mutation ever touches disk without explicit consent.
+| Tool | Description |
+|------|-------------|
+| `show_pending_changes` | Display all staged (pending) operations |
+| `discard_changes` | Discard all staged operations |
-**Phase 1 — Staging:** When the agent calls a mutation tool, the `ToolExecutor` validates path safety (must be within workspace root, not excluded), records the operation in an in-memory overlay, and logs it to the `ActionTracker` with status `"pending"`.
+### Skill Tools
-**Phase 2 — Approval:** After the agent completes, all pending mutations are grouped by file path and presented to the user with three options:
-- **Approve and apply all** — marks every pending mutation as approved
-- **Review one by one** — iterates through each group, showing a unified diff and prompting for accept/reject
-- **Cancel** — rejects all pending mutations
+| Tool | Description |
+|------|-------------|
+| `list_skills` | List `SKILL.md` files from skill directories |
+| `read_skill` | Read a specific `SKILL.md` file |
-**Phase 3 — Application:** Approved actions are replayed against the real filesystem: folders are created, files are written or deleted, and shell commands are spawned.
+### Session Tools
-### Action Tracking
+| Tool | Description |
+|------|-------------|
+| `session_status` | Check recent session history (mode, goal, outcome, pending tasks) |
+| `session_resume_context` | Get full context of a previous session (transcript, files, summary) |
+| `session_search` | Search previous sessions by keyword, file name, or goal |
-The `ActionTracker` maintains an append-only log of every action the agent takes. Each entry includes a unique ID, timestamp, action type, file path, before/after content snapshots, and status (`pending`, `executed`, `approved`, `rejected`). This log powers the approval flow, enables auditability, and supports future undo/redo features.
+---
-### Session Management
+## Staging & Approval Pipeline
-Sessions are stored in `~/.astra/sessions/index.json` with atomic writes (temp file + rename). Each session records the workspace path, mode, status, LLM-generated summary, touched files, and action counts. Sessions support:
+This is the **safety backbone** of Astra. No mutation ever touches the disk without explicit user consent.
-- **Auto-resume** — interrupted sessions are detected on wakeup and offered for resumption
-- **Context injection** — on resume, the previous session's summary is injected into the agent's instructions
-- **Session tools** — agents can call `session_status` and `session_history` to recall previous work
+### How It Works
-### Auto-Retry Engine
+```
+Agent calls mutation tool (create_file, modify_file, etc.)
+    │
+    ▼
+┌──────────────────────────────────┐
+│  1. Path Safety Validation       │  ← Must be within workspace root
+│  2. Exclude Pattern Check        │  ← node_modules, .git, etc. blocked
+│  3. File Size Check              │  ← Max 1 MB for reads
+│  4. Stage in Memory Overlay      │  ← Map<string,string> + Set<string>
+│  5. Log to ActionTracker         │  ← Append-only audit trail
+└──────────────────────────────────┘
+    │
+    ▼
+Agent continues working (more tool calls, more staging)
+    │
+    ▼
+Agent finishes → Approval Flow
+    │
+    ▼
+┌──────────────────────────────────┐
+│  User chooses:                   │
+│  • "Approve and apply all"       │
+│  • "Review one by one"           │  ← Per-file with diff viewing
+│  • "Cancel"                      │  ← All discarded
+└──────────────────────────────────┘
+    │
+    ▼ (if approved)
+┌──────────────────────────────────┐
+│  applyApprovedFromTracker()      │
+│  1. Create folders (recursive)   │
+│  2. Write/delete files           │
+│  3. Execute queued shell cmds    │
+│  4. Return errors (if any)       │
+└──────────────────────────────────┘
+```
+### Review Groups
+When reviewing changes one-by-one, pending mutations are grouped by file path:
+- Multiple actions on the same file are collapsed into a single before→after diff
+- Folder creations are shown without diffs
+- Shell commands are shown individually
+### Diff Format
+Diffs are generated using unified diff format with 3 lines of context. Large diffs are truncated for readability with a warning message.
+---
+## Session Management
+### Session Lifecycle
+```
+User starts mode → beginSession()
+    │
+    ▼
+Session created (status: "active")
+    │  → Stored in ~/.astra/sessions/index.json
+    │  → Unique ID generated (e.g., sess_m5k2x3_abc123)
+    │
+Agent works → actions accumulate in tracker
+    │  → Transcript messages recorded
+    │  → Goals tracked
+    │
+Agent finishes → endSession()
+    │  → LLM generates 2-3 sentence summary
+    │  → Touched files extracted
+    │  → Action counts recorded
+    │  → Status set to "completed"
+    │
+OR: User hits Ctrl+C → markSessionInterrupted()
+    │  → Status set to "interrupted"
+    │  → All state preserved for resume
+    │
+Next wakeup → auto-resume offered
+    │  → Context summary injected into agent
+    │  → Previous actions hydrated into overlay
+```
+### Auto-Resume Heuristics
+When starting a new session, Astra checks for resumable sessions using a 3-tier priority:
+1. **Explicit resume** — a specific session ID was provided
+2. **Interrupted session** — an interrupted session exists in the same workspace
+3. **Related session** — keyword overlap ≥30% with a recent session (within 4 hours for completed, 30 minutes for non-interrupted)
+### Session Context on Resume
+When resuming, the agent receives a rich context block including:
+- Session metadata (ID, mode, start time)
+- All goals from the session
+- LLM-generated summary of what happened
+- Pending/incomplete tasks
+- Files touched (up to 20)
+- Action counts (applied/rejected)
+- Recent conversation transcript (configurable, default 10 turns)
+- The agent's last response
-Built-in retry logic with exponential backoff, jitter, and error classification. Four presets are available:
+---
-| Preset | Max Retries | Base Delay | Max Delay | Use Case |
-|--------|-------------|------------|-----------|----------|
-| `aiCall` | 3 | 1s | 30s | AI provider API calls |
-| `toolExecution` | 2 | 500ms | 5s | Tool execution |
-| `network` | 5 | 2s | 60s | Network operations |
-| `critical` | 5 | 1s | 60s | Critical operations |
+## Multi-Agent Orchestration
+### Orchestration Strategies
+| Strategy | Behavior | Failure Mode |
+|----------|----------|--------------|
+| **Sequential** | Agents run one after another; each agent sees previous agents' outputs | Fail-fast (default) |
+| **Parallel** | Agents run simultaneously in configurable batches with timeout | Continue (default) |
+| **Hierarchical** | Coordinator runs first, then specialists execute with coordinator's plan | Fail-fast (default) |
+| **Collaborative** | Agents take turns; each agent's output is broadcast to all others via MessageBroker | Continue (default) |
+| **DAG** | Agents run as soon as all their dependencies are satisfied; supports cycle detection and deadlock handling | Fail-at-end (default) |
+### Agent Roles
+| Role | Permissions | Default Max Steps | Tools Count |
+|------|------------|:-----------------:|:-----------:|
+| `researcher` | Read-only (filesystem, web, git, skills) | 30 | 16 |
+| `implementer` | Full read/write/execute (filesystem, shell, tests) | 50 | 26 |
+| `reviewer` | Read + execute (tests, lint) but no file writes | 25 | 15 |
+| `coordinator` | Read-only + planning tools | 20 | 8 |
+| `custom` | Based on selected tools | 30 | Variable |
+### Workflow Templates
+Six pre-built workflow templates are available:
+| Template | Agents | Strategy | Description |
+|----------|--------|----------|-------------|
+| **Code Review** | Researcher → Implementer → Reviewer | Sequential | Analyze code, implement fixes, review changes |
+| **Feature Development** | Coordinator → Backend Dev + Frontend Dev → QA | DAG | Plan, implement in parallel, test |
+| **Bug Fixing** | Debug Agent → Fix Agent → Test Agent | Sequential | Diagnose, fix, verify |
+| **Collaborative Research** | Researcher 1 + Researcher 2 + Researcher 3 | Parallel | Multiple researchers working simultaneously |
+| **Security Audit** | Scanner → Static Auditor + Dependency Auditor → Report Coordinator | DAG | Scan, audit in parallel, synthesize report |
+| **Full-Stack Feature** | Architect → DB Dev + API Dev + UI Dev → Integration Tester | DAG | Design, implement layers in parallel, test |
+### Workflow Builder (Fluent API)
+For programmatic workflow construction:
+```typescript
+import { WorkflowBuilder, WorkflowTemplates } from "./modes/multi/workflow-builder";
+// Use a template
+const workflow = WorkflowTemplates.featureDevelopmentWorkflow("wf_001", "Add OAuth2 support");
+// Or build custom
+const custom = new WorkflowBuilder("wf_custom", "Refactor the API layer")
+  .addResearcher("analyzer", "Code Analyzer", "Analyzes the current API structure")
+  .addImplementer("refactorer", "Refactoring Agent", "Implements the refactoring", {
+    dependsOn: ["analyzer"],
+  })
+  .addReviewer("validator", "Validation Agent", "Validates the refactoring", {
+    dependsOn: ["refactorer"],
+  })
+  .withDagStrategy(3, 60_000)  // max 3 concurrent, 60s timeout
+  .withRetryOnFailure(2)
+  .withExpectedOutput("Refactored API layer with passing tests")
+  .build();
+// Validate before execution
+const validation = WorkflowBuilder.validateWorkflow(custom);
+if (!validation.isValid) {
+  console.error(validation.errors);
+}
+```
-Errors are classified by category (rate limit, network, timeout, server, etc.) with per-category retryability and suggested delay overrides.
+### Validation Checks
+The workflow builder performs 10+ validation checks:
+- Workflow ID and goal are present
+- At least one agent exists
+- No duplicate agent IDs
+- No empty agent names or IDs
+- `maxSteps > 0` for each agent
+- At least 1 tool per agent
+- Valid strategy type
+- Hierarchical strategy requires a coordinator
+- Collaborative strategy with >1 agent needs a timeout
+- Fallback agent IDs exist in the workflow
+- Dependency references exist and are not self-referencing
+- **DAG cycle detection** — detects and reports dependency cycles
+- Warns if DAG strategy is used but no agent has dependencies
 ---
-## Environment Variables
+## Retry & Error Handling
+Astra has a comprehensive retry system for resilient operation:
+### Error Classification
+Errors are classified into 7 categories:
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for LLM access |
-| `OPENROUTER_DEFAULT_MODEL` | Yes | Model identifier (e.g., `anthropic/claude-sonnet-4.5`) |
-| `FIRECRAWL_API_KEY` | No | Enables `web_search`, `web_crawl`, and `fetch_url` via Firecrawl SDK |
-| `SKILLS_DIRS` | No | Semicolon-separated paths to additional skill directories |
+| Category | Retryable? | Suggested Delay | Examples |
+|----------|:----------:|-----------------|----------|
+| `TRANSIENT` | ✅ | 1s | 500, 502, 504 server errors |
+| `RATE_LIMIT` | ✅ | 5s | 429 Too Many Requests, 503 Service Unavailable |
+| `NETWORK` | ✅ | 2s | ECONNRESET, ETIMEDOUT, ENOTFOUND |
+| `TIMEOUT` | ✅ | 3s | Request timeout, deadline exceeded |
+| `UNKNOWN` | ✅ | 1s | Unrecognized errors (treated as transient) |
+| `PERMANENT` | ❌ | — | 400 Bad Request, 404 Not Found, malformed input |
+| `AUTH` | ❌ | — | 401 Unauthorized, 403 Forbidden, invalid API key |
-Config file location: `~/.astra/.env`
+### Retry Presets
+| Preset | Max Retries | Base Delay | Max Delay | Backoff | Jitter |
+|--------|:-----------:|------------|-----------|:-------:|:------:|
+| `aiCall` | 3 | 1s | 30s | 2x | ±1s |
+| `toolExecution` | 2 | 500ms | 5s | 2x | None |
+| `network` | 5 | 2s | 60s | 2x | ±2s |
+| `critical` | 5 | 1s | 60s | 2x | ±1.5s |
+### Retry Behavior
+- **Exponential backoff** — delay doubles (or by configured multiplier) with each attempt
+- **Jitter** — random jitter is added to prevent thundering herd problems
+- **Per-attempt timeouts** — optional timeout for individual attempts
+- **Callbacks** — `onRetry` and `onExhausted` callbacks for progress reporting
+- **Fallback to manual retry** — when automatic retries are exhausted, the user is offered a manual retry option
 ---
 ## Project Structure
 ```
-astra/
-├── index.ts                        # CLI entry point (Commander)
-├── package.json                    # Dependencies, scripts, bin config
-├── tsconfig.json                   # TypeScript config (strict, Bun types)
+astrabot/
+├── index.ts                        # CLI entry point (Commander). Registers all commands.
+├── package.json                    # Package config: name "astrabot", bin "astra", dependencies.
+├── tsconfig.json                   # TypeScript config: ESNext, strict, Bun types.
+├── bun.lock                        # Bun lockfile.
+├── .gitignore                      # Standard ignores.
+├── .npmignore                      # Excludes tests, .github from npm package.
+│
+├── bin/astra                       # Binary entry point (shebang: #!/usr/bin/env bun)
 │
-├── ai/                             # AI provider configuration
-│   ├── index.ts                    # Re-exports getAgentModel
-│   ├── ai.config.ts                # OpenRouter provider setup
-│   ├── config-loader.ts            # ~/.astra/.env management
-│   ├── auto-retry.ts               # Automatic retry integration
-│   └── retry-prompt.ts             # Manual retry prompt fallback
+├── ai/                             # AI provider configuration and utilities.
+│   ├── index.ts                    # Public API re-exports.
+│   ├── ai.config.ts                # OpenRouter provider setup and model resolution.
+│   ├── config-loader.ts            # ~/.astra/.env management (load, read, save).
+│   ├── auto-retry.ts               # withAiRetry() and createRetryableAiCall().
+│   └── retry-prompt.ts             # Manual retry prompt (promptToRetryAiCall).
 │
-├── tui/                            # Terminal UI
-│   ├── terminal-md.ts              # Markdown → terminal rendering
-│   ├── spinner.ts                  # Animated spinner with elapsed time
-│   └── wakeup.ts                   # Banner + top-level mode selection
+├── core/retry/                     # Core retry engine.
+│   ├── index.ts                    # Public API re-exports.
+│   ├── retry-config.ts             # ErrorCategory enum, RetryConfig, presets.
+│   ├── retry-engine.ts             # withRetry(), withRetryOrNull(), RetryPresets.
+│   └── error-classifier.ts         # Error classification (status codes, patterns, codes).
 │
-├── modes/                          # Interaction modes
-│   ├── cli.ts                      # CLI mode loop
-│   ├── auto.ts                     # Auto-router (intent classification)
-│   ├── setup.ts                    # Configuration wizard
+├── tui/                            # Terminal UI utilities.
+│   ├── terminal-md.ts              # Markdown-to-terminal rendering (marked + marked-terminal).
+│   ├── spinner.ts                  # Animated spinner with metabolic rate engine.
+│   └── wakeup.ts                   # ASCII banner with breathing animation + star field.
+│
+├── modes/                          # All interaction modes.
+│   ├── cli.ts                      # CLI mode loop (mode selection).
+│   ├── auto.ts                     # Auto mode (LLM intent classification router).
+│   ├── setup.ts                    # Interactive setup wizard.
 │   │
-│   ├── agent/                      # Agent mode
-│   │   ├── types.ts                # Type definitions + default config
-│   │   ├── action-tracker.ts       # Append-only action log
-│   │   ├── tool-executor.ts        # Core execution engine + staging overlay
-│   │   ├── agent-tools.ts          # Vercel AI SDK tool definitions
-│   │   ├── diff-view.ts            # Unified diff generation
-│   │   ├── approval.ts             # Interactive approval flow
-│   │   └── orchestrator.ts         # Agent loop + approval + apply
+│   ├── agent/                      # Agent mode.
+│   │   ├── types.ts                # ActionType, ActionStatus, ActionLog, AgentConfig.
+│   │   ├── action-tracker.ts       # ActionTracker (append-only log).
+│   │   ├── agent-tools.ts          # createAgentTools() — 35+ Vercel AI SDK tools.
+│   │   ├── tool-executor.ts        # ToolExecutor — staging overlay + all implementations.
+│   │   ├── diff-view.ts            # Unified diff generation.
+│   │   ├── approval.ts             # runApprovalFlow() — approve/review/reject.
+│   │   └── orchestrator.ts         # runAgentMode() — full agent lifecycle.
 │   │
-│   ├── ask/                        # Ask mode (read-only Q&A)
-│   │   └── orchestrator.ts
+│   ├── ask/                        # Ask mode.
+│   │   └── orchestrator.ts         # runAskMode() — read-only Q&A.
 │   │
-│   ├── plan/                       # Plan mode
-│   │   ├── types.ts                # Plan and PlanStep interfaces
-│   │   ├── planner.ts              # LLM-driven plan generation
-│   │   ├── selection.ts            # Interactive step picker
-│   │   ├── web-tools.ts            # Firecrawl web tools
-│   │   └── orchestrator.ts         # Plan → select → execute → approve
+│   ├── plan/                       # Plan mode.
+│   │   ├── types.ts                # PlanStep, Plan interfaces.
+│   │   ├── planner.ts              # generatePlan() — LLM-structured planning.
+│   │   ├── selection.ts            # printPlan(), selectSteps().
+│   │   ├── web-tools.ts            # Firecrawl-based web_search, web_crawl, fetch_url.
+│   │   └── orchestrator.ts         # runPlanMode() — plan → select → execute → approve.
 │   │
-│   └── multi/                      # Multi-agent mode
-│       ├── types.ts                # Full type system
-│       ├── agent-pool-manager.ts   # Agent registration and tracking
-│       ├── message-broker.ts       # Pub-sub communication channel
-│       ├── multi-agent-orchestrator.ts  # Strategy dispatch engine
-│       ├── workflow-builder.ts     # Fluent API + predefined templates
-│       ├── examples.ts             # Example workflow configurations
-│       └── orchestrator.ts         # Multi-agent approval flow
+│   └── multi/                      # Multi-agent mode.
+│       ├── types.ts                # Full type system (AgentRole, AgentConfig, etc.).
+│       ├── agent-pool-manager.ts   # AgentPoolManager — registration, tracking, stats.
+│       ├── message-broker.ts       # MessageBroker — pub-sub communication.
+│       ├── multi-agent-orchestrator.ts  # MultiAgentOrchestrator — strategy dispatch.
+│       ├── workflow-builder.ts     # WorkflowBuilder (fluent API) + WorkflowTemplates.
+│       ├── examples.ts             # 8 example workflow demonstrations.
+│       └── orchestrator.ts         # runMultiAgentMode() — AI workflow designer + execution.
 │
-├── session/                        # Session persistence
-│   ├── index.ts                    # Public API re-exports
-│   ├── store.ts                    # JSON file store (atomic writes)
-│   ├── session-manager.ts          # Begin/end/resume/summarise
-│   ├── session-context.ts          # Context capture and summary
-│   └── session-tools.ts            # session_status + session_history tools
+├── session/                        # Session persistence and management.
+│   ├── index.ts                    # Public API re-exports.
+│   ├── store.ts                    # JSON file store (atomic writes, CRUD).
+│   ├── session-manager.ts          # beginSession, endSession, auto-resume logic.
+│   ├── session-context.ts          # Context summary building for resumption.
+│   └── session-tools.ts            # session_status, session_resume_context, session_search.
 │
-├── core/                           # Core utilities
-│   └── retry/                      # Retry engine
-│       ├── index.ts                # Public API re-exports
-│       ├── retry-config.ts         # Configuration and presets
-│       ├── retry-engine.ts         # Execution with backoff + jitter
-│       └── error-classifier.ts     # Error categorisation
+├── game/                           # Arcade easter egg.
+│   ├── index.html                  # Retro Snake Classic (HTML5 Canvas).
+│   └── neon-breaker.html           # Neon Brick Breaker (HTML5 Canvas).
 │
-└── game/                           # Standalone arcade games
-    ├── index.html                  # Snake (HTML5 Canvas)
-    └── neon-breaker.html           # Brick Breaker
+└── tests/
+    └── cli.test.ts                 # CLI tests.
 ```
 ---
 ## Dependencies
-| Package | Purpose |
-|---------|---------|
-| `@openrouter/ai-sdk-provider` | OpenRouter as LLM provider for Vercel AI SDK |
-| `@clack/prompts` | Interactive terminal prompts |
-| `ai` | Vercel AI SDK (ToolLoopAgent, generateText, stepCountIs) |
-| `@mendable/firecrawl-js` | Web search, crawling, and scraping |
-| `commander` | CLI argument parsing |
-| `chalk` | Terminal string styling |
-| `figlet` | ASCII art banner generation |
-| `marked` + `marked-terminal` | Markdown parsing and terminal rendering |
-| `diff` | Unified diff generation |
-| `dotenv` | `.env` file loading |
-| `zod` | Schema validation |
+### Runtime Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@openrouter/ai-sdk-provider` | ^2.9.0 | OpenRouter as LLM provider for Vercel AI SDK |
+| `@clack/prompts` | ^1.4.0 | Interactive terminal prompts |
+| `@clack/core` | ^1.3.1 | Core prompt primitives |
+| `@mendable/firecrawl-js` | ^4.25.1 | Firecrawl SDK for web search and crawling |
+| `commander` | ^15.0.0 | CLI argument parsing |
+| `chalk` | ^5.6.2 | Terminal string styling |
+| `figlet` | ^1.11.0 | ASCII art banner generation |
+| `marked` | ^18.0.4 | Markdown parser |
+| `marked-terminal` | ^7.3.0 | Markdown renderer for terminal output |
+| `diff` | ^9.0.0 | Unified diff generation |
+| `dotenv` | ^17.4.2 | .env file loading |
+| `docx` | ^9.7.1 | Microsoft Word document generation |
+| `@types/node` | ^25.9.1 | Node.js type definitions |
+| `@types/marked-terminal` | ^6.1.1 | Type definitions for marked-terminal |
+### Dev Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@types/bun` | latest | Bun runtime type definitions |
+### Peer Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `typescript` | ^5 | TypeScript compiler |
 ---
 ## Roadmap
-- [ ] **Telegram mode** — stub present in wakeup menu
+Planned features not yet implemented:
+- [ ] **Telegram mode** — stub present in wakeup menu, not yet implemented
 - [ ] **Undo/redo support** — via action log replay
 - [ ] **Streaming token output** — for real-time agent response display
 - [ ] **Configurable tool allowlists per mode** — currently hardcoded per mode
-- [ ] **Multi-model support with per-mode model selection** — partially implemented in multi-agent
+- [ ] **Multi-model support with per-mode model selection** — partially implemented in multi-agent mode only
 - [ ] **Persistent action history across sessions** — sessions store summaries but not full action logs
 ---
 ## License
-MIT
+[MIT](LICENSE) — see the LICENSE file for details.
+---
+<div align="center">
+**Astra** — Your AI-native development companion.
+Built with ❤️ using [Bun](https://bun.sh) · [OpenRouter](https://openrouter.ai) · [Vercel AI SDK](https://sdk.vercel.ai)
+</div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "astrabot",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI-native development companion — Agent, Ask, and Plan modes in your terminal.",
   "module": "index.ts",
   "type": "module",