@action-llama/action-llama 0.12.2 → 0.13.1

package/docs/config-reference.md

@@ -1,241 +0,0 @@
-# config.toml Reference
-
-The project-level `config.toml` lives at the root of your Action Llama project. All sections and fields are optional — sensible defaults are used for anything you omit. If the file doesn't exist at all, an empty config is assumed.
-
-## Full Annotated Example
-
-```toml
-# Default model for all agents (agents can override in their own agent-config.toml)
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-# Local Docker container settings
-[local]
-image = "al-agent:latest"   # Base image name (default: "al-agent:latest")
-memory = "4g"               # Memory limit per container (default: "4g")
-cpus = 2                    # CPU limit per container (default: 2)
-timeout = 900               # Default max container runtime in seconds (default: 900, overridable per-agent)
-
-# Cloud provider config (optional — only needed for `al start -c`)
-[cloud]
-provider = "cloud-run"      # "cloud-run", "ecs", or "vps"
-# ... provider-specific fields (see below)
-
-# Gateway HTTP server settings
-[gateway]
-port = 8080                 # Gateway port (default: 8080)
-lockTimeout = 1800          # Lock TTL in seconds (default: 1800 / 30 minutes)
-
-# Webhook sources — named webhook endpoints with provider type and credential
-[webhooks.my-github]
-type = "github"
-credential = "MyOrg"              # credential instance for HMAC validation
-
-# Scheduler settings
-maxReruns = 10              # Max consecutive reruns for successful agent runs (default: 10)
-maxCallDepth = 3            # Max depth for agent-to-agent call chains (default: 3)
-workQueueSize = 100         # Max queued work items (webhooks + calls) per agent (default: 100)
-```
-
-## Field Reference
-
-### Top-level fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `maxReruns` | number | `10` | Maximum consecutive reruns when an agent requests a rerun via `al-rerun` before stopping |
-| `maxCallDepth` | number | `3` | Maximum depth for agent-to-agent call chains (A calls B calls C = depth 2) |
-| `workQueueSize` | number | `100` | Maximum queued work items (webhook events + agent calls) per agent when all runners are busy |
-
-### `[model]` — Default LLM
-
-Default model configuration inherited by all agents that don't define their own `[model]` section in `agent-config.toml`.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | LLM provider: `"anthropic"`, `"openai"`, `"groq"`, `"google"`, `"xai"`, `"mistral"`, `"openrouter"`, or `"custom"` |
-| `model` | string | Yes | Model ID (e.g. `"claude-sonnet-4-20250514"`, `"gpt-4o"`, `"gemini-2.0-flash-exp"`) |
-| `authType` | string | Yes | Auth method: `"api_key"`, `"oauth_token"`, or `"pi_auth"` |
-| `thinkingLevel` | string | No | Thinking budget: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`. Only applies to Anthropic models with reasoning support. Ignored for other providers. |
-
-See [Models](models.md) for all supported providers, model IDs, auth types, and thinking levels.
-
-### `[local]` — Docker Container Settings
-
-Controls local Docker container isolation. These settings also apply as resource limits for Cloud Run jobs and ECS Fargate tasks.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `image` | string | `"al-agent:latest"` | Base Docker image name |
-| `memory` | string | `"4g"` | Memory limit per container (e.g. `"4g"`, `"8g"`, `"4096"` for ECS in MiB) |
-| `cpus` | number | `2` | CPU limit per container |
-| `timeout` | number | `900` | Default max container runtime in seconds. Individual agents can override this with `timeout` in their `agent-config.toml`. On AWS ECS, agents with effective timeout <= 900s automatically route to Lambda for faster cold starts. See [agent timeout docs](agent-config-reference.md#timeout). |
-
-### `[cloud]` — Cloud Provider
-
-Only needed when running agents on cloud infrastructure with `al start -c`. Configure using `al setup cloud` (interactive wizard) or manually.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | `"cloud-run"` (GCP), `"ecs"` (AWS), or `"vps"` (SSH + Docker) |
-
-#### Cloud Run fields (`provider = "cloud-run"`)
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `gcpProject` | string | Yes | — | GCP project ID |
-| `region` | string | Yes | — | Cloud Run region (e.g. `"us-central1"`) |
-| `artifactRegistry` | string | Yes | — | Full Artifact Registry repo path (e.g. `"us-central1-docker.pkg.dev/my-project/al-images"`) |
-| `serviceAccount` | string | No | — | Runtime service account for job creation. Per-agent SAs are used for execution. |
-| `secretPrefix` | string | No | `"action-llama"` | Google Secret Manager name prefix |
-
-See [Cloud Run docs](cloud-run.md) for full setup.
-
-#### ECS Fargate fields (`provider = "ecs"`)
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `awsRegion` | string | Yes | — | AWS region (e.g. `"us-east-1"`) |
-| `ecsCluster` | string | Yes | — | ECS cluster name or ARN |
-| `ecrRepository` | string | Yes | — | Full ECR repository URI (e.g. `"123456789012.dkr.ecr.us-east-1.amazonaws.com/al-images"`) |
-| `executionRoleArn` | string | Yes | — | IAM role ARN for task execution (ECR pull + CloudWatch Logs) |
-| `taskRoleArn` | string | Yes | — | Default IAM task role ARN (Secrets Manager access) |
-| `subnets` | string[] | Yes | — | VPC subnet IDs for Fargate tasks |
-| `securityGroups` | string[] | No | — | Security group IDs for Fargate tasks |
-| `awsSecretPrefix` | string | No | `"action-llama"` | AWS Secrets Manager name prefix |
-| `buildBucket` | string | No | auto-created | S3 bucket for CodeBuild source uploads |
-| `lambdaRoleArn` | string | No | auto-derived | Lambda execution role ARN. If omitted, per-agent roles (`al-{agentName}-lambda-role`) are derived automatically. |
-| `lambdaSubnets` | string[] | No | — | VPC subnet IDs for Lambda functions (only needed if Lambda must access VPC resources) |
-| `lambdaSecurityGroups` | string[] | No | — | Security group IDs for Lambda functions (only needed with `lambdaSubnets`) |
-
-See [ECS docs](ecs.md) for full setup.
-
-#### VPS fields (`provider = "vps"`)
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `host` | string | Yes | — | Server IP address or hostname |
-| `sshUser` | string | No | `"root"` | SSH username |
-| `sshPort` | number | No | `22` | SSH port |
-| `sshKeyPath` | string | No | `"~/.ssh/id_rsa"` | Path to SSH private key |
-| `vultrInstanceId` | string | No | — | Vultr instance ID (set automatically if provisioned via `al setup cloud`) |
-| `vultrRegion` | string | No | — | Vultr region (set automatically if provisioned via `al setup cloud`) |
-
-See [VPS docs](vps-deployment.md) for full setup.
-
-### `[gateway]` — HTTP Server
-
-The gateway starts automatically when Docker mode or webhooks are enabled. It handles health checks, webhook reception, credential serving (local Docker only), resource locking, and the shutdown kill switch.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `port` | number | `8080` | Port for the gateway HTTP server |
-| `lockTimeout` | number | `1800` | Default lock TTL in seconds. Locks expire automatically after this duration unless refreshed via heartbeat. |
-
-### `[webhooks.*]` — Webhook Sources
-
-Named webhook sources that agents can reference in their `[[webhooks]]` triggers. Each source defines a provider type and an optional credential for signature validation.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | string | Yes | Provider type: `"github"` or `"sentry"` |
-| `credential` | string | No | Credential instance name for HMAC signature validation (e.g. `"MyOrg"` maps to `github_webhook_secret:MyOrg`). Omit for unsigned webhooks. |
-
-```toml
-[webhooks.my-github]
-type = "github"
-credential = "MyOrg"              # uses github_webhook_secret:MyOrg for HMAC validation
-
-[webhooks.my-sentry]
-type = "sentry"
-credential = "SentryProd"         # uses sentry_client_secret:SentryProd
-
-[webhooks.unsigned-github]
-type = "github"                   # no credential — accepts unsigned webhooks
-```
-
-Agents reference these sources by name in their `agent-config.toml`:
-
-```toml
-[[webhooks]]
-source = "my-github"
-events = ["issues"]
-```
-
-## Minimal Examples
-
-### Anthropic with Docker (typical dev setup)
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-```
-
-Everything else uses defaults: Docker enabled, 4GB memory, 2 CPUs, 15min timeout, gateway on port 8080.
-
-### Cloud Run production
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[local]
-memory = "8g"
-cpus = 4
-timeout = 7200
-
-[cloud]
-provider = "cloud-run"
-gcpProject = "my-gcp-project"
-region = "us-central1"
-artifactRegistry = "us-central1-docker.pkg.dev/my-gcp-project/al-images"
-
-[gateway]
-port = 3000
-```
-
-### ECS Fargate production
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[cloud]
-provider = "ecs"
-awsRegion = "us-east-1"
-ecsCluster = "al-cluster"
-ecrRepository = "123456789012.dkr.ecr.us-east-1.amazonaws.com/al-images"
-executionRoleArn = "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
-taskRoleArn = "arn:aws:iam::123456789012:role/al-default-task-role"
-subnets = ["subnet-abc123"]
-
-maxReruns = 5
-maxCallDepth = 2
-```
-
-### VPS production
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[cloud]
-provider = "vps"
-host = "5.6.7.8"
-sshUser = "root"
-```

package/docs/creating-agents.md

@@ -1,147 +0,0 @@
-# Creating Agents
-
-This guide walks you through creating an Action Llama agent from scratch.
-
-## Prerequisites
-
-- An Action Llama project (created with `al new <name>`)
-- Credentials configured in `~/.action-llama/credentials/` (see [Credentials](credentials.md))
-
-## Steps
-
-### 1. Create the agent directory
-
-Inside your project directory, create a folder for your agent under the `agents/` directory:
-
-```bash
-mkdir -p agents/my-agent
-```
-
-### 2. Write `agent-config.toml`
-
-Create `agents/my-agent/agent-config.toml`:
-
-```toml
-credentials = ["github_token", "git_ssh"]
-schedule = "*/5 * * * *"
-
-[params]
-repos = ["your-org/your-repo"]
-
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-```
-
-Supported providers: `anthropic`, `openai`, `groq`, `google`, `xai`, `mistral`, `openrouter`, `custom`. See [agent-config.toml Reference](agent-config-reference.md) for all available fields and provider examples.
-
-### 3. Write `ACTIONS.md`
-
-Create `agents/my-agent/ACTIONS.md` — this is the system prompt that defines your agent's behavior:
-
-```markdown
-# My Agent
-
-You are an automation agent. Your job is to ...
-
-Your configuration is in the `<agent-config>` block at the start of your prompt.
-
-`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI and `git` directly.
-
-## Workflow
-
-1. **Step one** — ...
-2. **Step two** — ...
-
-## Rules
-
-- ...
-```
-
-The ACTIONS.md is injected as the agent's system prompt at runtime. Write it as instructions to the LLM.
-
-### 4. (Optional) Add preflight steps
-
-If your agent needs external context (repo contents, API data, issue lists), add `[[preflight]]` steps to `agent-config.toml`. Preflight runs after credentials are loaded but before the LLM session starts, so the agent begins with everything it needs:
-
-```toml
-[[preflight]]
-provider = "git-clone"
-[preflight.params]
-repo = "your-org/your-repo"
-dest = "/tmp/repo"
-depth = 1
-
-[[preflight]]
-provider = "shell"
-[preflight.params]
-command = "gh issue list --repo your-org/your-repo --label bug --json number,title --limit 20"
-output = "/tmp/context/issues.json"
-```
-
-Then reference the staged files in your ACTIONS.md:
-
-```markdown
-## Context
-- The repo is cloned at `/tmp/repo`
-- Open bug issues are at `/tmp/context/issues.json`
-```
-
-See [Preflight](agent-config-reference.md#preflight) for the full reference.
-
-### 5. Verify with `al stat`
-
-```bash
-al stat -p .
-```
-
-This should show your agent with its schedule and credentials.
-
-### 6. Run with `al start`
-
-```bash
-al start -p .
-```
-
-Your agent will run on its configured schedule and/or respond to webhooks.
-
-### 7. (Optional) Customize the project Dockerfile
-
-Every project has a `Dockerfile` at the root (created by `al new`) that defines the shared base image for all agents. If your agents need extra system packages, edit it:
-
-```dockerfile
-FROM al-agent:latest
-
-# Shared tools for all agents
-RUN apk add --no-cache github-cli python3
-```
-
-If only one specific agent needs extra tools, add a `Dockerfile` to that agent's directory instead:
-
-```dockerfile
-FROM al-agent:latest
-USER root
-RUN apk add --no-cache github-cli
-USER node
-```
-
-See [Docker docs](docker.md) for the full reference.
-
-### 8. (Cloud only) Re-run `al doctor -c`
-
-If you're running agents on cloud infrastructure, re-run `al doctor -c` after adding a new agent. This creates the per-agent IAM resources (service account for Cloud Run, task role for ECS) and grants the new agent access to its declared secrets.
-
-```bash
-al doctor -c -p .
-```
-
-Without this step, the new agent will fail to access its credentials at runtime.
-
-## Tips
-
-- Agent name is derived from the directory name — no need to put it in the config
-- Use `al-rerun` in your ACTIONS.md to tell the agent to run `al-rerun` when it did work and there may be more in the backlog
-- Params in the config are injected into the agent prompt as an `<agent-config>` XML block
-- See [Examples](examples/index.md) for complete working agents

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"`). The instance is resolved automatically: agent-specific (`<agentName>`) first, then `default` as fallback.
-
-## 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"` — the instance is resolved automatically (agent-specific first, then `default`). To explicitly reference another agent's credential, use the cross-agent syntax: `"botty/git_ssh"`.
-
-## 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.