@action-llama/action-llama 0.13.0 → 0.13.2

package/docs/agents.md

@@ -1,256 +0,0 @@
-# Agents
-
-An agent is a directory inside your project that contains instructions and configuration for an autonomous LLM session. Each run is self-contained: the agent wakes up (on a schedule or webhook), executes its task, and shuts down.
-
-## Structure
-
-```
-my-agent/
-  agent-config.toml    # Required — credentials, model, schedule, webhooks, params
-  ACTIONS.md          # Required — system prompt (the agent's instructions)
-  Dockerfile           # Optional — custom Docker image for this agent
-```
-
-The directory name becomes the agent name. No registration is needed — the scheduler discovers agents by scanning for directories that contain an `agent-config.toml`.
-
-## `agent-config.toml`
-
-Declares what the agent needs to run: which credentials to mount, which model to use, when to trigger, and any custom parameters.
-
-```toml
-credentials = ["github_token", "git_ssh"]
-schedule = "*/5 * * * *"
-
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[[webhooks]]
-source = "my-github"
-events = ["issues"]
-actions = ["labeled"]
-labels = ["agent"]
-
-[params]
-repos = ["acme/app"]
-triggerLabel = "agent"
-```
-
-Key points:
-
-- **`credentials`** — list of credential refs (`"type:instance"`) the agent needs at runtime. These are mounted into the container and injected as environment variables. See [Credentials](credentials.md).
-- **`schedule`** and/or **`webhooks`** — at least one trigger is required. Agents can have both.
-- **`[model]`** — optional. If omitted, the agent inherits the default model from the project's `config.toml`. See [Models](models.md).
-- **`[params]`** — optional key-value pairs injected into the agent's prompt as an `<agent-config>` JSON block. Use these for repo names, label names, org identifiers, or anything else your ACTIONS.md references.
-
-See [agent-config.toml Reference](agent-config-reference.md) for the full field reference.
-
-## `ACTIONS.md`
-
-The system prompt that defines the agent's behavior. This is the most important file — it tells the LLM what to do, step by step.
-
-Write it as direct instructions to the model:
-
-```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. **Check for work** — ...
-2. **Do the work** — ...
-3. **Report results** — ...
-
-## Rules
-
-- If you did work and there may be more, run `al-rerun`
-- ...
-```
-
-### How it's used at runtime
-
-The ACTIONS.md is set as the LLM's system prompt. The scheduler then sends a user-message prompt assembled from several blocks:
-
-1. **`<agent-config>`** — JSON of the `[params]` table from `agent-config.toml`
-2. **`<credential-context>`** — describes which environment variables and tools are available (e.g. `GITHUB_TOKEN`, `git`, `gh`, SSH config)
-3. **Trigger context** (one of):
-   - *Scheduled run:* "You are running on a schedule. Check for new work and act on anything you find."
-   - *Manual run:* "You have been triggered manually. Check for new work and act on anything you find."
-   - *Webhook:* `<webhook-trigger>` block with the full event payload (source, event, action, repo, etc.)
-   - *Agent call:* `<agent-call>` block with the caller agent name and context
-
-Your ACTIONS.md should reference `<agent-config>` for parameter values and handle both scheduled and webhook triggers if the agent uses both.
-
-### Language skills
-
-Before the ACTIONS.md runs, the agent receives a preamble that teaches it a set of **language skills** — shorthand operations the actions can reference naturally. The preamble explains the underlying mechanics (curl commands, env vars) so agent authors never need to think about them.
-
-Skills currently taught to agents:
-
-| Category | Skills | Description |
-|----------|--------|-------------|
-| **Signals** | `al-rerun`, `al-status`, `al-return`, `al-exit` | Shell commands for signaling the scheduler. See [Signals](#signals). |
-| **Calls** | `al-call`, `al-check`, `al-wait` | Agent-to-agent calls with return values. See [Agent calls](#agent-calls). |
-| **Locks** | `LOCK(...)`, `UNLOCK(...)`, `HEARTBEAT(...)` | Resource locking for parallel coordination. See [Resource locks](#resource-locks). |
-| **Credentials** | `GITHUB_TOKEN`, `gh`, `git`, etc. | Credential access and tool usage. See [Credentials](credentials.md). |
-
-Agent authors write the shorthand naturally (e.g. `LOCK("github issue acme/app#42")`). The agent learns what it means from the preamble — no need to document curl commands or API endpoints in your actions.
-
-### Signals
-
-The agent uses shell commands to signal the scheduler:
-
-| Command | Effect |
-|---------|--------|
-| `al-rerun` | Tells the scheduler the agent did work and wants to be re-run immediately to drain remaining backlog. |
-| `al-status "<text>"` | Status update shown in the TUI (e.g. `al-status "reviewing PR #42"`). |
-| `al-return "<value>"` | Returns a value to the calling agent when invoked via `al-call`. |
-| `al-exit [code]` | Terminates the agent with an exit code indicating an unrecoverable error. |
-
-### Agent calls
-
-Agents running in Docker mode can call other agents and retrieve their results using shell commands:
-
-- **`al-call <agent>`** — Call another agent. Pass context via stdin. Returns `{"ok":true,"callId":"..."}`.
-- **`al-check <callId>`** — Non-blocking status check. Returns `{"status":"pending|running|completed|error", ...}`.
-- **`al-wait <callId> [...] [--timeout N]`** — Wait for calls to complete (default timeout: 900s).
-
-Calls are non-blocking: fire multiple calls, continue working, then collect results with `al-wait`. If the target agent's runners are all busy, the call is queued until one frees up. Self-calls are rejected; call depth is bounded by `maxCallDepth`.
-
-## Runtime lifecycle
-
-Each agent run is an isolated, short-lived container. Here's what happens from trigger to exit:
-
-1. **Trigger fires** — a cron tick, webhook event, manual `al run`, or `al-call` from another agent.
-2. **Container launches** — a fresh container starts with credentials and config passed via environment variables and volume mounts.
-3. **Credentials are loaded** — the entry point reads credential files from `/credentials/<type>/<instance>/<field>` (local Docker and Cloud Run) or from `AL_SECRET_*` environment variables (ECS). Key credentials are injected as env vars the LLM can use directly: `GITHUB_TOKEN`, `GH_TOKEN`, `SENTRY_AUTH_TOKEN`, `GIT_SSH_COMMAND`, git author identity, etc.
-4. **LLM session starts** — the model is initialized and receives two inputs:
-   - **System prompt:** the contents of `ACTIONS.md`
-   - **User prompt:** `<agent-config>` (params JSON) + `<credential-context>` (available env vars, tools, and security policy) + trigger context (schedule, webhook payload, or agent call)
-5. **Agent runs autonomously** — the LLM executes tools (bash, file I/O, API calls) until it finishes or hits an error. Rate-limited API calls are retried automatically (up to 5 attempts with exponential backoff).
-6. **Error detection** — the container watches for repeated auth/permission failures (e.g. "bad credentials", "permission denied"). After 3 such errors, it aborts early.
-7. **Signals are processed** — the agent uses `al-rerun`, `al-status`, `al-return`, and `al-exit` commands to write signal files. The scheduler reads them after the session ends.
-8. **Container exits** — exit code 0 (success), 1 (error), or 124 (timeout). Any held locks are released automatically. The scheduler logs the result and the container is removed.
-
-### Timeout
-
-Each container has a self-termination timer controlled by `local.timeout` in `config.toml` (default: 3600 seconds / 1 hour). If the timer fires, the process exits with code 124. This is a hard kill — there is no graceful shutdown.
-
-### Reruns
-
-When a scheduled agent runs `al-rerun`, the scheduler immediately re-runs it. This continues until the agent completes without `al-rerun` (no more work), hits an error, or reaches the `maxReruns` limit (default: 10, configurable in `config.toml`). This lets an agent drain its work queue without waiting for the next cron tick.
-
-Webhook-triggered and agent-called runs do not re-run — they respond to a single event.
-
-See [Docker docs](docker.md) for the full container reference including the startup sequence, log protocol, filesystem layout, and exit codes.
-
-## Resource locks
-
-When you set `scale > 1` on an agent, multiple instances run concurrently. Without coordination, two instances might pick up the same GitHub issue, review the same PR, or deploy the same service at the same time. Resource locks prevent this.
-
-Locks are managed by the scheduler and available to all agents running in Docker mode. Each lock is identified by a **resource key** — for example, `LOCK("github issue acme/app#42")`.
-
-### How it works
-
-1. Before working on a shared resource, the agent calls `LOCK("resource key")`.
-2. If the lock is free, the agent gets it and proceeds.
-3. If another instance already holds the lock, the agent gets back the holder's name and skips that resource.
-4. When done, the agent calls `UNLOCK("resource key")`.
-
-The agent learns the lock API from a preamble injected before the actions run. Agent authors just write the shorthand — no need to think about HTTP endpoints or authentication.
-
-### Operations
-
-| Operation | Description |
-|-----------|-------------|
-| `LOCK(resourceKey)` | Acquire an exclusive lock on a resource. Fails if another instance holds it. |
-| `UNLOCK(resourceKey)` | Release a lock. Only the holder can release. |
-| `HEARTBEAT(resourceKey)` | Reset the TTL on a held lock. Use during long-running work to prevent expiry. |
-
-### One lock at a time
-
-Each agent instance can hold **at most one lock**. This keeps the model simple — the agent locks a resource, does the work, unlocks, then moves to the next item. If it tries to acquire a second lock without releasing the first, the request is rejected with a clear error message.
-
-### Timeout (TTL)
-
-Locks expire automatically after **30 minutes** by default. This prevents deadlocks if an agent crashes or hangs without releasing its lock. The timeout is configurable via `gateway.lockTimeout` in `config.toml` (value in seconds).
-
-For work that takes longer than the timeout, use `HEARTBEAT` to extend the TTL. Each heartbeat resets the clock to another full TTL period. If the agent forgets to heartbeat and the lock expires, another instance can claim it.
-
-### Authentication
-
-Each container gets a unique per-run secret (the same one used for the shutdown API). Lock requests are authenticated with this secret, so only the container that acquired a lock can release or heartbeat it. There is no way for one agent instance to release another's lock — it must wait for the TTL to expire.
-
-### Auto-release on exit
-
-When a container exits — whether it finishes successfully, hits an error, or times out — all of its locks are released automatically by the scheduler. You don't need to worry about cleanup in error paths.
-
-### Example agents
-
-```markdown
-## Workflow
-
-1. List open issues labeled "agent" in repos from `<agent-config>`
-2. For each issue:
-   - LOCK("github issue owner/repo#123")
-   - If the lock fails, skip this issue — another instance is handling it
-   - Clone the repo, create a branch, implement the fix
-   - Open a PR and link it to the issue
-   - UNLOCK("github issue owner/repo#123")
-3. If you completed work and there may be more issues, run `al-rerun`
-```
-
-### Resource key conventions
-
-Use descriptive, unique keys:
-
-| Resource key | Example |
-|-------------|---------|
-| `github issue owner/repo#number` | `LOCK("github issue acme/app#42")` |
-| `github pr owner/repo#number` | `LOCK("github pr acme/app#17")` |
-| `deploy service-name` | `LOCK("deploy api-prod")` |
-
-### Configuration
-
-| Setting | Location | Default | Description |
-|---------|----------|---------|-------------|
-| `gateway.lockTimeout` | `config.toml` | `1800` (30 min) | Default TTL for locks in seconds |
-
-## `Dockerfile` (optional)
-
-The base Docker image includes Node.js, git, curl, and openssh. If your agent needs additional tools, add a `Dockerfile` to the agent directory:
-
-```dockerfile
-FROM al-agent:latest
-USER root
-RUN apk add --no-cache github-cli jq python3
-USER node
-```
-
-Agents without a Dockerfile use the base image directly.
-
-See [Docker docs](docker.md) for the full container reference including the base image contents, filesystem layout, and how to write standalone Dockerfiles.
-
-## Examples
-
-| Agent | Description |
-|-------|-------------|
-| [Dev Agent](examples/dev/) | Picks up GitHub issues and implements changes |
-| [Reviewer Agent](examples/reviewer/) | Reviews and merges open pull requests |
-| [DevOps Agent](examples/devops/) | Monitors CI failures and Sentry errors, files issues |
-
-## See also
-
-- [Creating Agents](creating-agents.md) — step-by-step setup guide
-- [agent-config.toml Reference](agent-config-reference.md) — all config fields
-- [Models](models.md) — supported LLM providers and model IDs
-- [Credentials](credentials.md) — credential types and storage
-- [Webhooks](webhooks.md) — webhook setup and filter fields
-- [Docker](docker.md) — container isolation and custom images

package/docs/cloud-run.md

@@ -1,173 +0,0 @@
-# Cloud Run Mode
-
-Run agents as Cloud Run Jobs on GCP instead of local Docker containers. Agents get the same isolation guarantees with the added benefits of serverless scaling, managed infrastructure, and per-agent secret isolation via IAM.
-
-## Prerequisites
-
-- GCP project with Cloud Run, Secret Manager, Artifact Registry, and Cloud Build APIs enabled
-- `gcloud` CLI authenticated (`gcloud auth login`)
-
-Local Docker is **not required** — images are built using Cloud Build.
-
-## Configuration
-
-In your project's `config.toml`:
-
-```toml
-[cloud]
-provider = "cloud-run"
-gcpProject = "my-gcp-project"
-region = "us-central1"
-artifactRegistry = "us-central1-docker.pkg.dev/my-gcp-project/al-images"
-serviceAccount = "al-runner@my-gcp-project.iam.gserviceaccount.com"
-# secretPrefix = "action-llama"   # optional, default: "action-llama"
-```
-
-| Key | Required | Description |
-|-----|----------|-------------|
-| `cloud.provider` | Yes | Set to `"cloud-run"` |
-| `cloud.gcpProject` | Yes | GCP project ID |
-| `cloud.region` | Yes | Cloud Run region (e.g. `us-central1`) |
-| `cloud.artifactRegistry` | Yes | Full Artifact Registry repo path |
-| `cloud.serviceAccount` | No | Runtime SA (for job creation). Per-agent SAs are used for job execution. |
-| `cloud.secretPrefix` | No | GSM secret name prefix (default: `"action-llama"`) |
-
-Local Docker settings (`[local]`) control resource limits:
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `local.memory` | `"4Gi"` | Memory per job |
-| `local.cpus` | `2` | CPUs per job |
-| `local.timeout` | `3600` | Max execution time in seconds |
-
-## Quick Setup
-
-The fastest way to get started:
-
-```bash
-al setup cloud -p .
-```
-
-This interactive wizard prompts for all required fields, writes the `[cloud]` config, pushes credentials, and provisions IAM in one step.
-
-## Manual Setup
-
-### 1. Enable GCP APIs
-
-```bash
-gcloud services enable \
-  run.googleapis.com \
-  secretmanager.googleapis.com \
-  artifactregistry.googleapis.com \
-  --project my-gcp-project
-```
-
-### 2. Create an Artifact Registry repository
-
-```bash
-gcloud artifacts repositories create al-images \
-  --repository-format=docker \
-  --location=us-central1 \
-  --project my-gcp-project
-```
-
-### 3. Configure Docker for Artifact Registry
-
-```bash
-gcloud auth configure-docker us-central1-docker.pkg.dev
-```
-
-### 4. Push credentials and create per-agent service accounts
-
-```bash
-al doctor -c -p .
-```
-
-This pushes all local credentials to Google Secret Manager, then creates a service account for each agent (`al-{agentName}@{project}.iam.gserviceaccount.com`) and grants it `secretmanager.secretAccessor` on only the secrets that agent needs.
-
-> **Re-run after adding agents:** Whenever you add a new agent to your project, re-run `al doctor -c` to create the service account for the new agent. Without this, the new agent will fail to access its credentials at runtime.
-
-### 5. Start
-
-```bash
-al start -c -p .
-```
-
-The scheduler will:
-1. Build agent images locally
-2. Push them to Artifact Registry
-3. Create/update Cloud Run jobs with GSM secret volume mounts
-4. Execute jobs on schedule or webhook trigger
-5. Stream logs from Cloud Logging
-
-## Cloud Build
-
-When running in Cloud Run mode, images are built using [Cloud Build](https://cloud.google.com/build) instead of local Docker. This means you don't need Docker installed on your machine or CI server — Cloud Build handles building and pushing to Artifact Registry in one step.
-
-Enable the Cloud Build API:
-
-```bash
-gcloud services enable cloudbuild.googleapis.com --project my-gcp-project
-```
-
-The scheduler automatically uses `gcloud builds submit` when the cloud provider is `cloud-run`. No additional configuration is needed.
-
-## How it works
-
-### Image lifecycle
-
-Images are built using Cloud Build and pushed to Artifact Registry. Each agent gets its own image tag (`al-{agentName}:latest`). The build happens on every `al start -c` to ensure the latest code is deployed. Cloud Build handles caching automatically.
-
-### Secret mounting
-
-Cloud Run mounts secrets from Google Secret Manager as files at `/credentials/<type>/<instance>/<field>` — the same layout as local Docker mode. The container entry point reads credentials from this path identically in both modes.
-
-Secret names follow the convention: `{prefix}--{type}--{instance}--{field}` (e.g. `action-llama--github_token--default--token`).
-
-### Per-agent service accounts
-
-Each agent runs as its own GCP service account:
-
-```
-al-dev@my-project.iam.gserviceaccount.com      → github_token, git_ssh, anthropic_key
-al-reviewer@my-project.iam.gserviceaccount.com  → github_token, git_ssh, anthropic_key
-al-devops@my-project.iam.gserviceaccount.com    → github_token, sentry_token, anthropic_key
-```
-
-Each SA only has `secretmanager.secretAccessor` on its declared secrets. Even if an agent container is compromised and accesses the GCP metadata server to obtain the SA's token, it can only read its own secrets.
-
-Run `al doctor -c` to create these SAs and IAM bindings automatically.
-
-### Gateway
-
-The gateway is **not required** for Cloud Run mode. Containers get their credentials via native GSM mounts (not the gateway's HTTP endpoint), and Cloud Run handles execution timeouts natively (no kill switch needed). The gateway still starts if you have webhooks configured, since webhooks are received by the scheduler process.
-
-### Log streaming
-
-Logs are streamed from Cloud Logging by polling. There is a ~5-15 second ingestion delay inherent to Cloud Logging. The TUI displays a warning about this delay when running in Cloud Run mode.
-
-## Comparison with local Docker
-
-| Aspect | Local Docker | Cloud Run |
-|--------|-------------|-----------|
-| Where containers run | Your machine | GCP |
-| Credential delivery | Volume mount from temp dir | GSM secret volume mount |
-| Secret isolation | Mount-level (same trust boundary) | IAM-enforced per-agent SAs |
-| Gateway needed | Yes (kill switch, cred serving) | No (optional for webhooks) |
-| Log latency | Real-time | ~5-15s delay |
-| Scaling | Limited by host resources | Serverless, managed |
-| Cost | Free (your hardware) | Pay per execution |
-
-## Troubleshooting
-
-**"Cloud Run runtime requires cloud.gcpProject..."** — Ensure all required fields are set in `config.toml` under `[cloud]`.
-
-**"Failed to get GCP access token"** — Run `gcloud auth application-default login` or set `GCP_SERVICE_ACCOUNT_KEY` env var.
-
-**"Failed to push image"** — Run `gcloud auth configure-docker <region>-docker.pkg.dev` to configure Docker for Artifact Registry.
-
-**"Failed to create Cloud Run job"** — Check that Cloud Run API is enabled and the runtime SA has `run.jobs.create` permission.
-
-**Logs are delayed** — This is expected. Cloud Logging has a ~5-15 second ingestion delay. The TUI shows a warning when running in Cloud Run mode.
-
-**Agent can't access secrets** — Run `al doctor -c` to create per-agent SAs and IAM bindings. Verify with `gcloud secrets get-iam-policy <secret-name> --project <project>`.

package/docs/cloud.md

@@ -1,98 +0,0 @@
-# Cloud
-
-Running `al start` on your laptop works for development, but for production you want agents running 24/7 on managed infrastructure — no laptop required, automatic restarts, and IAM-enforced secret isolation so a compromised agent can only access its own credentials.
-
-Action Llama supports three cloud providers. All use the same project structure and agent configs — the only difference is the `[cloud]` section in `config.toml`.
-
-## Quick start
-
-```bash
-al setup cloud -p .   # Interactive wizard: pick provider, configure, push creds, provision IAM
-al start -c -p .     # Start on cloud
-```
-
-## Providers
-
-### GCP (Cloud Run Jobs)
-
-Agents run as serverless Cloud Run Jobs. Images are built with Cloud Build (no local Docker needed). Credentials are stored in Google Secret Manager and mounted as files natively by Cloud Run.
-
-```toml
-[cloud]
-provider = "cloud-run"
-gcpProject = "my-gcp-project"
-region = "us-central1"
-artifactRegistry = "us-central1-docker.pkg.dev/my-gcp-project/al-images"
-serviceAccount = "al-runner@my-gcp-project.iam.gserviceaccount.com"
-```
-
-```bash
-al doctor -c    # Push creds + create per-agent service accounts
-al start -c     # Start on Cloud Run
-```
-
-If you add a new agent later, re-run `al doctor -c` to create its service account and IAM bindings.
-
-See [Cloud Run docs](cloud-run.md) for prerequisites, full setup walkthrough, and troubleshooting.
-
-### AWS (ECS Fargate)
-
-Agents run as ECS Fargate tasks. Images are built locally and pushed to ECR. Credentials are stored in AWS Secrets Manager and injected as environment variables by ECS.
-
-```toml
-[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"]
-```
-
-```bash
-al doctor -c    # Push creds + create per-agent IAM task roles
-al start -c     # Start on ECS Fargate
-```
-
-If you add a new agent later, re-run `al doctor -c` to create its task role and IAM policy.
-
-See [ECS docs](ecs.md) for prerequisites, full setup walkthrough, and troubleshooting.
-
-### VPS (SSH + Docker)
-
-Agents run on any VPS or server you can SSH into. Images are built directly on the server via `tar | ssh docker build` — no container registry needed. Credentials are stored on the VPS filesystem over SSH.
-
-```toml
-[cloud]
-provider = "vps"
-host = "your-vps-ip"
-```
-
-```bash
-al doctor -c    # Push creds to VPS via SSH
-al start -c     # Start on VPS
-```
-
-Setup supports three paths:
-- **Connect to an existing server** — any provider, any server with Docker installed
-- **Provision a new Vultr VPS** — automated instance creation with cloud-init Docker install
-- **Provision a new Hetzner VPS** — automated server creation with cloud-init Docker install
-
-See [VPS docs](vps-deployment.md) for full setup.
-
-## Provider comparison
-
-| | GCP Cloud Run | AWS ECS (Fargate + Lambda) | VPS (SSH + Docker) |
-|---|---|---|---|
-| Image builds | Cloud Build (no local Docker) | CodeBuild (no local Docker) | `tar \| ssh docker build` (on VPS) |
-| Credential store | Google Secret Manager | AWS Secrets Manager | Filesystem on VPS (over SSH) |
-| Credential delivery | File mount (native) | Env var injection | Volume mount |
-| Secret isolation | Per-agent service accounts | Per-agent IAM task/Lambda roles | SSH access = full access |
-| Setup command | `al doctor -c` | `al doctor -c` | `al doctor -c` |
-| Log latency | ~5-15s (Cloud Logging) | ~5-10s (CloudWatch) | Real-time (SSH) |
-| Cold start | ~10-30s | ~1-2s (Lambda, timeout<=900s) / ~30-60s (Fargate) | ~1-2s |
-| Cost | Pay-per-run | Pay-per-run | Fixed monthly ($5-24/mo) |
-| IAM reconciliation | Per-agent service accounts | Per-agent IAM roles | No-op |
-
-On AWS, agents with `timeout <= 900` automatically route to Lambda for faster cold starts. Agents with longer timeouts use ECS Fargate. See [ECS docs](ecs.md#per-agent-timeout-and-lambda-routing) for details.