@action-llama/action-llama 0.13.0 → 0.13.2

package/docs/credentials.md

@@ -1,167 +0,0 @@
-# Credentials
-
-Credentials are stored in `~/.action-llama/credentials/<type>/<instance>/<field>`. Each credential type is a directory containing one file per field. Reference them in `agent-config.toml` by type name (e.g. `"github_token"`) for the `default` instance, or use `"type:instance"` for a named instance (e.g. `"git_ssh:botty"`).
-
-## Built-in Credentials
-
-| Type | Fields | Description | Runtime Injection |
-|------|--------|-------------|-------------------|
-| `github_token` | `token` | GitHub PAT with repo and workflow scopes | `GITHUB_TOKEN` and `GH_TOKEN` env vars |
-| `anthropic_key` | `token` | Anthropic API key, OAuth token, or pi auth | _(read by SDK)_ |
-| `openai_key` | `token` | OpenAI API key | _(read by SDK)_ |
-| `groq_key` | `token` | Groq API key | _(read by SDK)_ |
-| `google_key` | `token` | Google Gemini API key | _(read by SDK)_ |
-| `xai_key` | `token` | xAI API key | _(read by SDK)_ |
-| `mistral_key` | `token` | Mistral API key | _(read by SDK)_ |
-| `openrouter_key` | `token` | OpenRouter API key | _(read by SDK)_ |
-| `custom_key` | `token` | Custom provider API key | _(read by SDK)_ |
-| `sentry_token` | `token` | Sentry auth token for error monitoring | `SENTRY_AUTH_TOKEN` env var |
-| `linear_token` | `token` | Linear personal API token for workspace access | `LINEAR_API_TOKEN` env var |
-| `linear_oauth` | `client_id`, `client_secret`, `access_token`, `refresh_token` | Linear OAuth2 credentials for workspace access | `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, `LINEAR_ACCESS_TOKEN`, `LINEAR_REFRESH_TOKEN` env vars |
-| `bugsnag_token` | `token` | Bugsnag auth token for error monitoring and release management | `BUGSNAG_AUTH_TOKEN` env var |
-| `netlify_token` | `token` | Netlify Personal Access Token for site management | `NETLIFY_AUTH_TOKEN` env var |
-| `git_ssh` | `id_rsa`, `username`, `email` | SSH private key + git author identity | SSH key mounted as file; `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`/`GIT_COMMITTER_NAME`/`GIT_COMMITTER_EMAIL` set from `username`/`email` |
-| `gateway_api_key` | `key` | API key for dashboard and CLI access to the gateway | _(used by gateway + CLI)_ |
-| `github_webhook_secret` | `secret` | Shared secret for GitHub webhook verification | _(used by gateway)_ |
-| `sentry_client_secret` | `secret` | Client secret for Sentry webhook verification | _(used by gateway)_ |
-| `linear_webhook_secret` | `secret` | Shared secret for Linear webhook verification | _(used by gateway)_ |
-| `x_twitter_api` | `api_key`, `api_secret`, `bearer_token`, `access_token`, `access_token_secret` | X (Twitter) API credentials for platform access | `X_API_KEY`, `X_API_SECRET`, `X_BEARER_TOKEN`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` env vars |
-| `aws` | `access_key_id`, `secret_access_key`, `default_region` | AWS credentials for managing AWS resources | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION` env vars |
-| `vultr_api_key` | `api_key` | Vultr API key for VPS provisioning (not needed at agent runtime) | `VULTR_API_KEY` env var |
-
-## How Credentials Work
-
-1. **Configuration**: List credential types in your agent's `agent-config.toml`:
-   ```toml
-   credentials = ["github_token", "git_ssh"]
-   ```
-
-2. **Storage**: Credential values live in `~/.action-llama/credentials/<type>/<instance>/<field>`. Each field is a plain text file.
-
-3. **Injection**: When an agent runs, the credentials it requires are injected into the container.
-
-4. **Git identity**: The `git_ssh` credential includes `username` and `email` fields (prompted during `al new`/`al doctor`). These are injected as `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL` and `GIT_COMMITTER_NAME`/`GIT_COMMITTER_EMAIL` env vars at runtime, so `git commit` works without requiring `git config`.
-
-## Named Instances
-
-Each credential type supports named instances. For example, you could have webhook secrets for multiple GitHub orgs:
-
-```
-~/.action-llama/credentials/github_webhook_secret/MyOrg/secret
-~/.action-llama/credentials/github_webhook_secret/OtherOrg/secret
-```
-
-Or multiple SSH keys:
-
-```
-~/.action-llama/credentials/git_ssh/default/id_rsa
-~/.action-llama/credentials/git_ssh/default/username
-~/.action-llama/credentials/git_ssh/botty/id_rsa
-~/.action-llama/credentials/git_ssh/botty/username
-```
-
-By default, just reference `"git_ssh"` — this resolves to the `default` instance. To use a named instance, use colon syntax: `"git_ssh:botty"`.
-
-## Managing Credentials
-
-### `al creds add`
-
-Add or update a credential interactively. Runs validation for the credential type (e.g. API key format, GitHub API check):
-
-```bash
-al creds add github_token              # adds github_token:default
-al creds add github_webhook_secret:myapp
-al creds add git_ssh:prod
-```
-
-### `al creds rm`
-
-Remove a credential:
-
-```bash
-al creds rm github_token               # removes github_token:default
-al creds rm github_webhook_secret:myapp
-```
-
-### `al creds ls`
-
-List all stored credentials grouped by type:
-
-```bash
-al creds ls
-```
-
-### `al doctor`
-
-Scan all agents in a project and prompt for any missing credentials:
-
-```bash
-al doctor -p .
-```
-
-### During `al new`
-
-The `al new` command prompts for the Anthropic credential during initial setup. Other credentials are configured per-agent by `al doctor` or `al creds add`.
-
-### Manually
-
-Write credential files directly:
-
-```bash
-mkdir -p ~/.action-llama/credentials/github_token/default
-echo "ghp_your_token_here" > ~/.action-llama/credentials/github_token/default/token
-
-mkdir -p ~/.action-llama/credentials/anthropic_key/default
-echo "sk-ant-api-your_key_here" > ~/.action-llama/credentials/anthropic_key/default/token
-
-mkdir -p ~/.action-llama/credentials/openai_key/default
-echo "sk-your_openai_key_here" > ~/.action-llama/credentials/openai_key/default/token
-
-mkdir -p ~/.action-llama/credentials/groq_key/default
-echo "gsk_your_groq_key_here" > ~/.action-llama/credentials/groq_key/default/token
-
-mkdir -p ~/.action-llama/credentials/bugsnag_token/default
-echo "your_bugsnag_token_here" > ~/.action-llama/credentials/bugsnag_token/default/token
-
-mkdir -p ~/.action-llama/credentials/netlify_token/default
-echo "your_netlify_token_here" > ~/.action-llama/credentials/netlify_token/default/token
-```
-
-### Anthropic Auth Methods
-
-Three auth methods are supported:
-
-- **`api_key`** — Standard API key (`sk-ant-api-...`). Set `authType = "api_key"` in model config.
-- **`oauth_token`** — OAuth token (`sk-ant-oat-...`). Set `authType = "oauth_token"`.
-- **`pi_auth`** — Use existing pi auth credentials (`~/.pi/agent/auth.json`). Set `authType = "pi_auth"`. No credential file needed.
-
-## Webhook Secrets
-
-Webhook secrets use named credential instances. For example, to set up a GitHub webhook secret for your org:
-
-```bash
-mkdir -p ~/.action-llama/credentials/github_webhook_secret/MyOrg
-echo "your-webhook-secret" > ~/.action-llama/credentials/github_webhook_secret/MyOrg/secret
-```
-
-The gateway automatically loads secrets from all credential instances (e.g. `github_webhook_secret:MyOrg`, `sentry_client_secret:MyOrg`) and uses them to verify incoming webhook payloads. No global configuration is needed.
-
-## Cloud Credential Sync
-
-When using cloud runtimes, credentials are automatically pushed to the cloud secret manager by `al doctor -c` or `al setup cloud`. See [Cloud Run docs](cloud-run.md) and [ECS docs](ecs.md) for details.
-
-### Google Secret Manager (GSM)
-
-Secret naming: `{prefix}--{type}--{instance}--{field}` (dashes, since GSM disallows slashes).
-
-### AWS Secrets Manager (ASM)
-
-Secret naming: `{prefix}/{type}/{instance}/{field}` (slashes).
-
-Requires `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` env vars or a configured AWS CLI (`aws configure`).
-
-### VPS Filesystem (SSH)
-
-Secret naming: `~/.action-llama/credentials/{type}/{instance}/{field}` on the remote server (same layout as local).
-
-Credentials are transferred via SSH. No external secrets manager needed — same trust model as SSH access.

package/docs/docker.md

@@ -1,323 +0,0 @@
-# Container Isolation
-
-All agents run in isolated containers for security and consistency. Container isolation is always enabled.
-
-## How it works
-
-When `al start` runs:
-
-1. The base image (`al-agent:latest`) is built from `docker/Dockerfile` on first run
-2. Per-agent images are built for any agent that has a custom `Dockerfile`
-3. Each agent run launches a fresh container with:
-   - Read-only root filesystem
-   - Credentials mounted read-only at `/credentials/`
-   - Writable tmpfs at `/tmp` (2GB)
-   - All capabilities dropped, no-new-privileges
-   - PID, memory, and CPU limits
-   - Non-root user (uid 1000)
-   - A unique shutdown secret for the anti-exfiltration kill switch
-
-## Container runtime
-
-Each agent run is a short-lived container that boots, runs a single LLM session, and exits. The entry point is `node /app/dist/agents/container-entry.js`.
-
-### Environment
-
-The container receives everything it needs via environment variables and mounts:
-
-| Env var | Description |
-|---------|-------------|
-| `AGENT_CONFIG` | JSON-serialized agent config (model, credentials, params) plus `ACTIONS.md` content |
-| `PROMPT` | The fully assembled prompt (`<agent-config>` + `<credential-context>` + trigger text) |
-| `TIMEOUT_SECONDS` | Max runtime in seconds (default: 3600). The container self-terminates if exceeded |
-| `GATEWAY_URL` | HTTP URL of the host gateway (local Docker only — used for credential fetch and shutdown) |
-| `SHUTDOWN_SECRET` | Unique per-run secret for the anti-exfiltration kill switch (local Docker only) |
-
-Credentials are injected in one of three ways depending on the runtime:
-
-| Runtime | Strategy | How it works |
-|---------|----------|--------------|
-| Local Docker | Volume mount | Files staged to a temp dir, mounted read-only at `/credentials/<type>/<instance>/<field>` |
-| Cloud Run | Gateway fetch | Container fetches credentials from `GATEWAY_URL/credentials/<secret>` on startup |
-| ECS Fargate | Env vars | Secrets Manager values injected as `AL_SECRET_<type>__<instance>__<field>` env vars |
-
-The container tries each strategy in order: volume mount, env vars, gateway. The first one that has data wins.
-
-### Startup sequence
-
-1. **Set working directory** — `chdir("/tmp")`
-2. **Start self-termination timer** — kills the process with exit code 124 if `TIMEOUT_SECONDS` is exceeded
-3. **Parse config** — reads `AGENT_CONFIG`, extracts `ACTIONS.md` content
-4. **Load credentials** — from volume, env vars, or gateway (see table above)
-5. **Inject env vars from credentials:**
-   - `GITHUB_TOKEN` / `GH_TOKEN` from `github_token` credential
-   - `SENTRY_AUTH_TOKEN` from `sentry_token` credential
-   - `GIT_SSH_COMMAND` pointing to the mounted SSH key from `git_ssh` credential
-   - `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` / `GIT_COMMITTER_NAME` / `GIT_COMMITTER_EMAIL` from `git_ssh` credential
-   - Git HTTPS credential helper configured if `GITHUB_TOKEN` is set
-6. **Create pi-coding-agent session** — initializes the LLM model, tools, and settings
-7. **Send prompt** — delivers the pre-built prompt to the session
-
-### Agent session
-
-The prompt is sent to the LLM with rate-limit retry (up to 5 attempts with exponential backoff, 30s to 5min). The LLM runs autonomously — reading files, executing commands, making API calls — until it finishes or hits an error.
-
-**Unrecoverable error detection:** The container watches for repeated auth/permission failures (e.g. "bad credentials", "permission denied", "resource not accessible by personal access token"). After 3 such errors, it aborts early rather than burning through retries.
-
-### Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success — agent completed its work |
-| 1 | Error — missing config, credential failure, unrecoverable errors, or uncaught exception |
-| 124 | Timeout — `TIMEOUT_SECONDS` exceeded, container self-terminated |
-
-### Log protocol
-
-The container communicates with the scheduler via structured JSON lines on stdout. This is how the scheduler tracks progress, surfaces errors in the TUI, and writes log files.
-
-**Structured log lines** have the format:
-
-```json
-{"_log": true, "level": "info", "msg": "bash", "cmd": "git clone ...", "ts": 1234567890}
-```
-
-The `_log: true` field distinguishes structured logs from plain text output. The scheduler parses these and forwards them to the logger at the appropriate level.
-
-| Field | Description |
-|-------|-------------|
-| `_log` | Always `true` — marker for structured log lines |
-| `level` | `"debug"`, `"info"`, `"warn"`, or `"error"` |
-| `msg` | Log message (e.g. `"bash"`, `"tool error"`, `"credentials loaded from volume"`) |
-| `ts` | Unix timestamp in milliseconds |
-| `...` | Additional fields vary by message (e.g. `cmd`, `tool`, `error`, `result`) |
-
-Key log messages emitted during a run:
-
-| Message | Level | When |
-|---------|-------|------|
-| `"container starting"` | info | Boot, includes `agentName` and `modelId` |
-| `"credentials loaded from ..."` | info | After credential loading (`volume`, `env vars`, or `gateway`) |
-| `"SSH key configured for git"` | info | After SSH key setup |
-| `"creating agent session"` | info | Before LLM session creation |
-| `"session created, sending prompt"` | info | Prompt delivery |
-| `"bash"` | info | Every bash tool call, with `cmd` field |
-| `"tool error"` | error | Failed tool call, with `tool`, `cmd`, and `result` fields |
-| `"rate limited, retrying prompt"` | warn | Rate limit hit, with `attempt` and `delayMs` |
-| `"run completed"` | info | Agent finished successfully |
-| `"no work to do"` | info | Agent found nothing to act on |
-| `"container timeout reached, self-terminating"` | error | Timeout exceeded |
-
-**Signal commands:**
-
-The container has signal commands installed at `/tmp/bin/` that write to `$AL_SIGNAL_DIR`:
-
-| Command | Description |
-|---------|-------------|
-| `al-rerun` | Request an immediate rerun to drain remaining backlog. Without this, the scheduler treats the run as complete and waits for the next scheduled tick. |
-| `al-status "<text>"` | Status update shown in the TUI. Example: `al-status "reviewing PR #42"` |
-| `al-return "<value>"` | Return a value to the calling agent. Used when this agent was invoked via `al-call`. |
-| `al-exit [code]` | Terminate with an exit code indicating an unrecoverable error. Defaults to 15. |
-
-**Agent-to-agent calls:**
-
-Agents can call other agents and retrieve structured results using shell commands injected into the container:
-
-- **`al-call <agent>`** — Call another agent. Pass context via stdin, get back a JSON response with a `callId`.
-- **`al-check <callId>`** — Check the status of a call (never blocks). Returns `{"status":"pending|running|completed|error", ...}`.
-- **`al-wait <callId> [callId...] [--timeout N]`** — Wait for one or more calls to complete (polls every 5s, default timeout 900s).
-
-Example:
-```sh
-CALL_ID=$(echo "Review PR #42 on acme/app" | al-call reviewer | jq -r .callId)
-# ... do other work ...
-RESULT=$(al-wait "$CALL_ID" --timeout 600)
-echo "$RESULT" | jq ".\"$CALL_ID\".returnValue"
-```
-
-The called agent receives an `<agent-call>` block with the caller name and context. To return a value, the called agent uses the `al-return` command:
-```
-al-return "PR looks good. Approved with minor suggestions."
-```
-
-Rules:
-- An agent cannot call itself (self-calls are rejected)
-- If all runners for the target agent are busy, the call is queued (up to `workQueueSize` limit in global config, default: 100)
-- Call chains are allowed (agent A calls B, B calls C) up to a configurable depth limit (`maxCallDepth` in `config.toml`, default: 3)
-- Called runs do not re-run — they respond to the single call
-- These commands require the gateway; they return errors if `GATEWAY_URL` is not set
-
-Any stdout line that is not valid JSON with `_log: true` is treated as plain agent output (the LLM's final text response).
-
-## Base image
-
-The base image (`al-agent:latest`) is built automatically from the Action Llama package and includes the minimum needed for any agent:
-
-| Package | Why |
-|---------|-----|
-| `node:20-slim` | Runs the container entry point and pi-coding-agent SDK |
-| `git` | Clone repos, create branches, push commits |
-| `curl` | API calls (Sentry, arbitrary HTTP), anti-exfiltration shutdown |
-| `ca-certificates` | HTTPS for git, curl, npm |
-| `openssh-client` | SSH for `GIT_SSH_COMMAND` — git clone/push over SSH |
-
-The base image also copies the compiled Action Llama application (`dist/`) and installs its npm dependencies. The entry point is `node /app/dist/agents/container-entry.js`.
-
-## Project base image
-
-The project `Dockerfile` (at the project root) lets you customize the base image for **all** agents in the project. It is created by `al new` and checked into git:
-
-```
-my-project/
-  Dockerfile              <-- project base image (shared by all agents)
-  config.toml
-  dev/
-    agent-config.toml
-    ACTIONS.md
-  reviewer/
-    agent-config.toml
-    ACTIONS.md
-```
-
-By default, the project Dockerfile is a bare `FROM al-agent:latest` with no customizations. In this state, it is skipped entirely — agents build directly on `al-agent:latest` with no overhead.
-
-To customize, add `RUN`, `ENV`, or other instructions:
-
-```dockerfile
-FROM al-agent:latest
-
-# Install tools shared by all agents
-RUN apk add --no-cache python3 py3-pip github-cli
-
-# Set shared environment variables
-ENV MY_ORG=acme
-```
-
-When the project Dockerfile has customizations beyond the bare `FROM`, the build pipeline creates an intermediate image (`al-project-base:latest`) that all per-agent images layer on top of.
-
-### Image build order
-
-```
-al-agent:latest            ← Action Llama package (automatic)
-    │
-    ▼
-al-project-base:latest     ← project Dockerfile (if customized)
-    │
-    ▼
-al-<agent>:latest          ← per-agent Dockerfile (if present)
-```
-
-If the project Dockerfile is unmodified, the middle layer is skipped.
-
-## Custom agent images
-
-Agents that need extra tools **beyond** what the project base provides can add a `Dockerfile` to their own directory:
-
-```
-my-project/
-  Dockerfile              <-- project base (shared tools)
-  dev/
-    agent-config.toml
-    ACTIONS.md
-    Dockerfile            <-- custom image for this agent only
-  reviewer/
-    agent-config.toml
-    ACTIONS.md
-                          <-- no Dockerfile, uses project base
-```
-
-### Extending the base image
-
-Use `FROM al-agent:latest` and add what you need. The build pipeline automatically rewrites the `FROM` line to point at the correct base (either `al-project-base:latest` or the cloud registry URI). Switch to `root` to install packages, then back to `node`:
-
-```dockerfile
-FROM al-agent:latest
-
-USER root
-RUN apk add --no-cache github-cli
-USER node
-```
-
-This is a thin layer on top of the base — fast to build and shares most of the image.
-
-**Tip:** If multiple agents need the same tool, put it in the project `Dockerfile` instead of duplicating it across agent Dockerfiles.
-
-Common additions:
-
-```dockerfile
-# GitHub CLI (for gh issue list, gh pr create, etc.)
-RUN apk add --no-cache github-cli
-
-# Python (for agents that run Python scripts)
-RUN apk add --no-cache python3 py3-pip
-
-# jq (for JSON processing in bash) — already in the base image
-# RUN apk add --no-cache jq
-```
-
-### Writing a standalone Dockerfile
-
-If you need full control, you can write a Dockerfile from scratch. It must:
-
-1. Include Node.js 20+
-2. Copy the application code from the base image or install it
-3. Set `ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]`
-4. Use uid 1000 (`USER node` on node images) for compatibility with the container launcher
-
-Example standalone Dockerfile:
-
-```dockerfile
-FROM node:20-slim
-
-# Install your tools
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    git curl ca-certificates openssh-client gh jq python3 \
-    && rm -rf /var/lib/apt/lists/*
-
-# Copy app from the base image (avoids rebuilding from source)
-COPY --from=al-agent:latest /app /app
-WORKDIR /app
-
-USER node
-ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]
-```
-
-The key requirement is that `/app/dist/agents/container-entry.js` exists and can run. The entry point reads `AGENT_CONFIG`, `PROMPT`, `GATEWAY_URL`, and `SHUTDOWN_SECRET` from environment variables, and credentials from `/credentials/`.
-
-### Build behavior
-
-- The base image (`al-agent:latest`) is only built if it doesn't exist yet
-- The project base image (`al-project-base:latest`) is rebuilt on every `al start` if the project Dockerfile has customizations
-- Agent images are named `al-<agent-name>:latest` (e.g. `al-dev:latest`) and are rebuilt on every `al start` to pick up Dockerfile changes
-- The build context is the Action Llama package root (not the project directory), so `COPY` paths in per-agent Dockerfiles reference the package's `dist/`, `package.json`, etc.
-
-## Configuration
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `local.image` | `"al-agent:latest"` | Base Docker image name |
-| `local.memory` | `"4g"` | Memory limit per container |
-| `local.cpus` | `2` | CPU limit per container |
-| `local.timeout` | `3600` | Max container runtime in seconds |
-
-For Cloud Run configuration, see [Cloud Run docs](cloud-run.md). For ECS Fargate configuration, see [ECS docs](ecs.md).
-
-## Container filesystem layout
-
-| Path | Mode | Contents |
-|------|------|----------|
-| `/app` | read-only | Action Llama application + node_modules |
-| `/credentials` | read-only | Mounted credential files (`/<type>/<instance>/<field>`) |
-| `/tmp` | read-write (tmpfs, 2GB) | Agent working directory — repos, scratch files, SSH keys |
-
-## Troubleshooting
-
-**"Docker is not running"** — Start Docker Desktop or the Docker daemon before running `al start`.
-
-**Base image build fails** — Run `docker build -t al-agent:latest -f docker/Dockerfile .` from the Action Llama package directory to see the full build output.
-
-**Project base image build fails** — Check that the project `Dockerfile` starts with `FROM al-agent:latest` and that any `apk add` packages are spelled correctly. The base image uses Alpine Linux.
-
-**Agent image build fails** — Check that your agent's `Dockerfile` starts with `FROM al-agent:latest` (the build pipeline rewrites this to the correct base) and that any package install commands are correct.
-
-**Container exits immediately** — Check `al logs <agent>` for the error. Common causes: missing credentials, missing `ACTIONS.md`, invalid model config.