@action-llama/action-llama 0.13.0 → 0.13.2

package/docs/models.md

@@ -1,191 +0,0 @@
-# Models
-
-Action Llama supports 8 LLM providers. Each agent can use a different provider and model — configure a project-wide default in `config.toml` under `[model]`, and override per agent in `agent-config.toml`.
-
-## `[model]` Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | Provider name (see table below) |
-| `model` | string | Yes | Model ID |
-| `authType` | string | Yes | `"api_key"`, `"oauth_token"`, or `"pi_auth"` |
-| `thinkingLevel` | string | No | Reasoning budget (Anthropic only) |
-
-## Providers
-
-### Anthropic
-
-Claude models with optional extended thinking.
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `claude-opus-4-20250514` | Most capable, best for complex multi-step tasks |
-| `claude-sonnet-4-20250514` | Balanced performance and cost (recommended) |
-| `claude-haiku-3-5-20241022` | Fastest and cheapest |
-
-**Credential:** `anthropic_key` (field: `token`)
-
-**Auth types:**
-
-| `authType` | Token format | Description |
-|------------|-------------|-------------|
-| `api_key` | `sk-ant-api-...` | Standard Anthropic API key |
-| `oauth_token` | `sk-ant-oat-...` | OAuth token from `claude setup-token` |
-| `pi_auth` | _(none)_ | Uses existing pi auth credentials (`~/.pi/agent/auth.json`). No credential file needed. |
-
-**Note:** `pi_auth` is not supported in Docker mode. Switch to `api_key` or `oauth_token` for containerized runs.
-
-**Thinking level:** Anthropic is the only provider that supports `thinkingLevel`. Valid values:
-
-| Level | Description |
-|-------|-------------|
-| `off` | No extended thinking |
-| `minimal` | Minimal reasoning |
-| `low` | Light reasoning |
-| `medium` | Balanced (recommended) |
-| `high` | Deep reasoning |
-| `xhigh` | Maximum reasoning budget |
-
-If omitted, thinking is not explicitly configured. For other providers, `thinkingLevel` is ignored.
-
-### OpenAI
-
-```toml
-[model]
-provider = "openai"
-model = "gpt-4o"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `gpt-4o` | Flagship multimodal model (recommended) |
-| `gpt-4o-mini` | Smaller, faster, cheaper |
-| `gpt-4-turbo` | Previous generation |
-| `o1-preview` | Reasoning model |
-| `o1-mini` | Smaller reasoning model |
-
-**Credential:** `openai_key` (field: `token`)
-
-### Groq
-
-```toml
-[model]
-provider = "groq"
-model = "llama-3.3-70b-versatile"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `llama-3.3-70b-versatile` | Llama 3.3 70B on Groq inference |
-
-Groq runs open-source models at high speed. Check [Groq's docs](https://console.groq.com/docs/models) for the full list of available model IDs.
-
-**Credential:** `groq_key` (field: `token`)
-
-### Google Gemini
-
-```toml
-[model]
-provider = "google"
-model = "gemini-2.0-flash-exp"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `gemini-2.0-flash-exp` | Fast experimental model |
-
-Check [Google AI Studio](https://ai.google.dev/models) for the full list of available model IDs.
-
-**Credential:** `google_key` (field: `token`)
-
-### xAI
-
-```toml
-[model]
-provider = "xai"
-model = "grok-beta"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `grok-beta` | Grok beta |
-
-**Credential:** `xai_key` (field: `token`)
-
-### Mistral
-
-```toml
-[model]
-provider = "mistral"
-model = "mistral-large-2411"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `mistral-large-2411` | Mistral Large (November 2024) |
-
-Check [Mistral's docs](https://docs.mistral.ai/getting-started/models/) for the full list of available model IDs.
-
-**Credential:** `mistral_key` (field: `token`)
-
-### OpenRouter
-
-OpenRouter provides access to models from many providers through a single API.
-
-```toml
-[model]
-provider = "openrouter"
-model = "anthropic/claude-3.5-sonnet"
-authType = "api_key"
-```
-
-Model IDs use the `provider/model` format. See [OpenRouter's model list](https://openrouter.ai/models) for all available models.
-
-**Credential:** `openrouter_key` (field: `token`)
-
-### Custom
-
-For any provider not listed above. The model ID and API routing are handled by the underlying [pi.dev agent harness](https://github.com/badlogic/pi-mono).
-
-```toml
-[model]
-provider = "custom"
-model = "your-model-name"
-authType = "api_key"
-```
-
-**Credential:** `custom_key` (field: `token`)
-
-## Mixing Models
-
-Each agent can use a different model. Define a project default in `config.toml`, then override in specific agents:
-
-```
-config.toml          → [model] provider = "anthropic", model = "claude-sonnet-4-20250514"
-dev/agent-config.toml     → (no [model] section — inherits Claude Sonnet)
-reviewer/agent-config.toml → [model] provider = "openai", model = "gpt-4o"
-devops/agent-config.toml   → [model] provider = "groq", model = "llama-3.3-70b-versatile"
-```
-
-If an agent defines its own `[model]` section, it fully overrides the project default — there is no field-level merging.
-
-## Credential Setup
-
-Each provider requires a corresponding credential in `~/.action-llama/credentials/`. Run `al doctor` to configure them interactively.
-
-The LLM credential does not need to be listed in your agent's `credentials` array — it is loaded automatically based on the `[model]` config. The `credentials` array is for runtime credentials the agent uses during execution (GitHub tokens, SSH keys, etc.).
-
-See [Credentials](credentials.md) for the full credential reference.

package/docs/vps-deployment.md

@@ -1,285 +0,0 @@
-# VPS Deployment
-
-Deploy Action Llama on any VPS (DigitalOcean, Vultr, Hetzner, etc.) for cost-effective remote hosting.
-
-There are two approaches:
-
-1. **VPS cloud provider** (`provider: "vps"`) — manage the VPS from your local machine via SSH. Images are built on the VPS, credentials pushed over SSH, scheduler deployed as a Docker container. Set up with `al setup cloud`.
-2. **Manual deployment** — install Action Llama directly on the VPS and run `al start` with the `--expose` flag. Simpler, but requires SSH'ing into the server to manage.
-
-## Approach 1: VPS Cloud Provider (Recommended)
-
-The VPS cloud provider lets you manage your VPS deployment from your local machine, just like AWS or GCP.
-
-### Quick Start
-
-```bash
-# From your local machine:
-al setup cloud -p .         # Select "VPS (Vultr, etc.)" → connect or provision
-al doctor -c -p .           # Push credentials to VPS via SSH
-al cloud deploy -p .        # Deploy scheduler to VPS
-```
-
-### Setup Options
-
-The `al setup cloud` wizard offers two paths:
-
-#### Connect to an existing server
-
-Works with any VPS provider (DigitalOcean, Hetzner, Linode, etc.) or any server you can SSH into:
-
-1. Enter the server IP, SSH user, port, and key path
-2. Action Llama validates SSH connectivity and checks Docker is installed
-3. Configuration is written to your environment file
-
-Requirements:
-- SSH access to the server
-- Docker installed on the server (`curl -fsSL https://get.docker.com | sh`)
-
-#### Provision a new Vultr VPS
-
-Automated provisioning with Vultr as a supported backend:
-
-1. Configure `vultr_api_key` credential first: `al creds add vultr_api_key`
-2. Run `al setup cloud` and select "Provision a new Vultr VPS"
-3. Pick region, plan (minimum 2 vCPU / 2GB RAM), and SSH key
-4. Instance is created with cloud-init that installs Docker automatically
-5. Action Llama waits for the instance to become ready
-
-#### Provision a new Hetzner VPS
-
-Automated provisioning with Hetzner Cloud:
-
-1. Configure `hetzner_api_key` credential first: `al creds add hetzner_api_key`
-2. Run `al setup cloud` and select "Provision a new Hetzner VPS"
-3. Pick server type, location, OS image, and SSH key
-4. Server is created with cloud-init that installs Docker automatically
-5. Action Llama waits for the server to become ready
-
-### How It Works
-
-| Operation | Implementation |
-|-----------|---------------|
-| Image builds | `tar -c . \| ssh docker build -t <tag> -` (built on VPS, no registry) |
-| Credential storage | Filesystem on VPS (`~/.action-llama/credentials/`) via SSH |
-| Credential push | `al doctor -c` copies credentials over SSH |
-| Scheduler deploy | `docker run -d --restart unless-stopped` on VPS |
-| IAM reconciliation | No-op (SSH access = full access) |
-| Log streaming | Real-time via SSH (`docker logs -f`) |
-
-### Configuration
-
-In your environment file (`~/.action-llama/environments/<name>.toml`):
-
-```toml
-[cloud]
-provider = "vps"
-host = "5.6.7.8"
-sshUser = "root"          # default: "root"
-sshPort = 22              # default: 22
-sshKeyPath = "~/.ssh/id_rsa"  # default: "~/.ssh/id_rsa"
-
-# Set automatically if provisioned via Vultr:
-# vultrInstanceId = "abc123"
-# vultrRegion = "ewr"
-```
-
-### Teardown
-
-```bash
-al teardown cloud -p .
-```
-
-This stops all Action Llama containers and cleans up remote credentials. If the instance was provisioned via Vultr, you'll be offered the option to delete it.
-
-## Approach 2: Manual Deployment
-
-Install Action Llama directly on your VPS and run it there. Simpler but requires managing the server directly.
-
-### Quick Start
-
-On your VPS:
-
-```bash
-# Install Action Llama
-npm install -g @action-llama/action-llama
-
-# Set up your project (or clone from git)
-al new my-project
-cd my-project
-
-# Configure credentials and check setup
-al doctor
-
-# Start with public gateway binding
-al start -w --expose --headless
-```
-
-### Key Features
-
-The `--expose` flag enables VPS deployment by:
-
-- **Binding gateway to `0.0.0.0`** — makes webhooks accessible from external services
-- **Preserving local-mode features** — web UI, control routes, filesystem credentials, SQLite state
-- **No cloud infrastructure required** — works on any Linux VPS
-
-## TLS Setup with Caddy
-
-For production, put a reverse proxy in front with TLS termination:
-
-### 1. Install Caddy
-
-```bash
-# Ubuntu/Debian
-sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
-curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
-curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
-sudo apt update && sudo apt install caddy
-```
-
-### 2. Configure Caddy
-
-Edit `/etc/caddy/Caddyfile`:
-
-```
-your-domain.com {
-    reverse_proxy localhost:8080
-}
-```
-
-### 3. Start Caddy
-
-```bash
-sudo systemctl enable caddy
-sudo systemctl start caddy
-```
-
-## Process Management with systemd
-
-For the manual deployment approach, create `/etc/systemd/system/action-llama.service`:
-
-```ini
-[Unit]
-Description=Action Llama Scheduler
-After=network.target
-
-[Service]
-Type=simple
-User=action-llama
-WorkingDirectory=/home/action-llama/my-project
-Environment=NODE_ENV=production
-ExecStart=/usr/local/bin/al start -w --expose --headless
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Start the service:
-
-```bash
-sudo systemctl enable action-llama
-sudo systemctl start action-llama
-```
-
-## Alternative: nohup
-
-For simpler setups, use `nohup`:
-
-```bash
-nohup al start -w --expose --headless > action-llama.log 2>&1 &
-```
-
-## Firewall Configuration
-
-Ensure your VPS firewall allows:
-
-- Port 22 (SSH)
-- Port 80 (HTTP, for Caddy)
-- Port 443 (HTTPS, for Caddy)
-- Port 8080 only if not using a reverse proxy
-
-Example with `ufw`:
-
-```bash
-sudo ufw allow ssh
-sudo ufw allow http
-sudo ufw allow https
-sudo ufw enable
-```
-
-## Security Considerations
-
-- **Use TLS in production** — Don't expose port 8080 directly without HTTPS
-- **Gateway API key** — Action Llama generates an API key for dashboard access (run `al doctor` to view it)
-- **Credentials isolation** — Each agent runs in a Docker container with only its required credentials
-- **User separation** — Run Action Llama as a non-root user
-- **SSH key security** — The VPS cloud provider uses your SSH key for all operations. Protect it with a passphrase and restrict access.
-
-## Monitoring
-
-Check service status:
-
-```bash
-# systemd (manual deployment)
-sudo systemctl status action-llama
-
-# Cloud provider deployment
-al stat -c
-
-# Logs
-al logs scheduler
-al logs dev -c              # Cloud provider: view agent logs via SSH
-journalctl -u action-llama -f
-```
-
-## Cost Comparison
-
-| Provider | vCPU | RAM | Storage | Price/month |
-|----------|------|-----|---------|-------------|
-| DigitalOcean | 1 | 1GB | 25GB SSD | $6 |
-| Vultr | 1 | 1GB | 25GB SSD | $6 |
-| Hetzner | 1 | 2GB | 20GB SSD | €4.15 |
-| Linode | 1 | 1GB | 25GB SSD | $5 |
-
-Compare to managed cloud solutions that may cost $50+ per month for similar agent workloads.
-
-## Troubleshooting
-
-### Gateway not accessible externally
-
-- Check firewall settings
-- Verify `--expose` flag is used (manual deployment)
-
-### Docker issues
-
-```bash
-# Check Docker daemon
-sudo systemctl status docker
-
-# Test Docker access
-docker ps
-```
-
-### SSH connection issues (cloud provider)
-
-```bash
-# Test SSH manually
-ssh -o ConnectTimeout=10 root@your-vps-ip echo ok
-
-# Check SSH key permissions
-chmod 600 ~/.ssh/id_rsa
-```
-
-### Webhook delivery failures
-
-- Check reverse proxy configuration
-- Verify TLS certificate is valid
-- Test webhook URL accessibility from external services
-
-### Out of disk space
-
-- Clean up old Docker images: `docker system prune -a`
-- Rotate logs: configure systemd journal limits
-- Monitor disk usage: `df -h`

package/docs/web-dashboard.md

@@ -1,113 +0,0 @@
-# Web Dashboard
-
-Action Llama includes an optional web-based dashboard for monitoring agents in your browser. It provides a live view of agent statuses and streaming logs — similar to the terminal TUI, but accessible from any browser.
-
-## Enabling the Dashboard
-
-Pass `-w` or `--web-ui` to `al start`:
-
-```bash
-al start -w
-al start -w -p ./my-project
-```
-
-The dashboard URL is shown in the TUI header and in headless log output once the scheduler starts:
-
-```
-Dashboard: http://localhost:8080/dashboard
-```
-
-The port is controlled by the `[gateway].port` setting in `config.toml` (default: `8080`).
-
-## Authentication
-
-The dashboard is protected by a gateway API key. The same key is used for both browser sessions and CLI access.
-
-**Key location:** `~/.action-llama/credentials/gateway_api_key/default/key`
-
-The key is generated automatically by `al doctor` or on first `al start`. To view or regenerate it, run `al doctor`.
-
-### Browser login
-
-Navigate to `http://localhost:8080/dashboard`. You'll be redirected to a login page where you paste your API key. On success, an `al_session` cookie is set (HttpOnly, SameSite=Strict) so all subsequent requests — including SSE streams — are authenticated automatically.
-
-A **Logout** link is available in the dashboard header.
-
-### CLI access
-
-CLI commands (`al stat`, `al pause`, `al resume`, `al kill`) automatically read the API key from the credential store and send it as a `Bearer` token in the `Authorization` header.
-
-### What's protected
-
-The following routes require authentication:
-
-- `/dashboard` and `/dashboard/*` — all dashboard pages and SSE streams
-- `/control/*` — scheduler and agent control endpoints (pause, resume, kill, trigger, enable/disable)
-- `/locks/status` — active lock information
-
-Health checks (`/health`), webhook endpoints (`/webhooks/*`), and container management routes are **not** protected.
-
-### Migrating from `AL_DASHBOARD_SECRET`
-
-The old `AL_DASHBOARD_SECRET` environment variable (HTTP Basic Auth) is no longer used. If it's still set, a deprecation warning is logged. Remove it from your environment and run `al doctor` to set up the new API key.
-
-## Dashboard Pages
-
-### Main Page — `/dashboard`
-
-Displays a live overview of all agents:
-
-| Column | Description |
-|--------|-------------|
-| Agent | Agent name (click to view logs) |
-| State | Current state: idle, running, building, or error |
-| Status | Latest status text or error message |
-| Last Run | Timestamp of the most recent run |
-| Duration | How long the last run took |
-| Next Run | When the next scheduled run will happen |
-| Actions | **Run** (trigger an immediate run) and **Enable/Disable** (toggle the agent) |
-
-The header also includes:
-
-- **Pause/Resume** button — pauses or resumes the scheduler (all cron jobs)
-- **Logout** link — clears the session cookie and redirects to the login page
-
-Below the table, a **Recent Activity** section shows the last 20 log lines across all agents.
-
-All data updates in real time via Server-Sent Events (SSE) — no manual refresh needed.
-
-### Agent Logs — `/dashboard/agents/<name>/logs`
-
-Displays a live-streaming log view for a single agent. Logs follow automatically by default (new entries scroll into view as they arrive).
-
-Features:
-- **Follow mode** — enabled by default, auto-scrolls to the latest log entry. Scrolling up pauses follow; scrolling back to the bottom re-enables it.
-- **Clear** — clears the log display (does not delete log files).
-- **Connection status** — shows whether the SSE connection is active.
-- **Log levels** — color-coded: green for INFO, yellow for WARN, red for ERROR.
-
-On initial load, the last 100 log entries from the agent's log file are displayed, then new entries stream in as they are written.
-
-## How It Works
-
-The dashboard is served by the same gateway that handles webhooks and container communication. When `--web-ui` is enabled, the gateway starts even if Docker and webhooks are not configured.
-
-Live updates use **Server-Sent Events (SSE)** on two endpoints:
-
-- `GET /dashboard/api/status-stream` — pushes agent status and scheduler info whenever state changes
-- `GET /dashboard/api/logs/<agent>/stream` — streams log lines for a specific agent by tailing its log file (500ms poll interval)
-
-Dashboard actions (Run, Enable/Disable, Pause/Resume) call the control API endpoints:
-
-- `POST /control/trigger/<name>` — trigger an immediate agent run
-- `POST /control/agents/<name>/enable` — enable a disabled agent
-- `POST /control/agents/<name>/disable` — disable an agent (pauses its cron job)
-- `POST /control/agents/<name>/pause` — pause an agent (alias for disable)
-- `POST /control/agents/<name>/resume` — resume an agent (alias for enable)
-- `POST /control/agents/<name>/kill` — kill all running instances of an agent
-- `POST /control/pause` — pause the scheduler
-- `POST /control/resume` — resume the scheduler
-
-All control requests use `credentials: 'same-origin'` to carry the session cookie.
-
-No additional dependencies or frontend build steps are required. The dashboard is rendered as plain HTML with inline CSS and JavaScript.