@action-llama/action-llama 0.12.2 → 0.13.1

package/docs/agent-config-reference.md

@@ -1,313 +0,0 @@
-# agent-config.toml Reference
-
-Each agent has an `agent-config.toml` file in its directory. The agent name is derived from the directory name and should not be included in the config.
-
-## Full Annotated Example
-
-```toml
-# Required: credential types the agent needs at runtime
-# Instance is resolved automatically: agents/<name>/ first, then default/
-credentials = ["github_token", "git_ssh", "sentry_token"]
-
-# Optional: cron schedule (standard cron syntax)
-# Agent must have at least one of: schedule, webhooks
-schedule = "*/5 * * * *"
-
-# Optional: number of concurrent runs allowed (default: 1)
-# When scale > 1, use LOCK/UNLOCK in your actions to coordinate
-# and prevent instances from working on the same resource.
-scale = 2
-
-# Optional: max runtime in seconds (default: falls back to [local].timeout, then 900)
-# On AWS ECS, agents with timeout <= 900 automatically route to Lambda
-# for faster cold starts (~1-2s vs ~30-60s on Fargate). Agents with
-# timeout > 900 run on ECS Fargate.
-timeout = 600
-
-# Required: LLM model configuration
-[model]
-provider = "anthropic"                    # LLM provider: anthropic, openai, groq, google, xai, mistral, openrouter, or custom
-model = "claude-sonnet-4-20250514"        # Model ID (e.g., claude-sonnet-4-20250514, gpt-4o, gemini-2.0-flash-exp)
-thinkingLevel = "medium"                  # Optional: off | minimal | low | medium | high | xhigh (for models with reasoning support)
-authType = "api_key"                      # api_key | oauth_token | pi_auth
-
-# Optional: webhook triggers (instead of or in addition to schedule)
-# Each source references a named webhook defined in the project's config.toml
-[[webhooks]]
-source = "my-github"                      # Required: references [webhooks.my-github] in config.toml
-repos = ["acme/app"]                      # Filter to specific repos (optional)
-events = ["issues"]                       # GitHub event types (optional)
-actions = ["labeled"]                     # GitHub event actions (optional)
-labels = ["agent"]                        # Only trigger on issues with these labels (optional)
-
-[[webhooks]]
-source = "my-sentry"                      # Required: references [webhooks.my-sentry] in config.toml
-resources = ["error", "event_alert"]      # Sentry resource types (optional)
-
-# Optional: preflight steps — run before the LLM session starts
-# Each step runs a built-in provider to stage data the agent will reference
-[[preflight]]
-provider = "git-clone"                    # Clone a repo into the workspace
-required = true                           # If true (default), abort if this step fails
-[preflight.params]
-repo = "acme/app"                         # Short "owner/repo" or full URL
-dest = "/tmp/repo"
-depth = 1                                 # Optional: shallow clone
-
-[[preflight]]
-provider = "http"                         # Fetch a URL and write the response to a file
-required = false                          # Optional step — warn and continue on failure
-[preflight.params]
-url = "https://api.internal/v1/flags"
-output = "/tmp/context/flags.json"
-headers = { Authorization = "Bearer ${INTERNAL_TOKEN}" }
-
-[[preflight]]
-provider = "shell"                        # Run a shell command
-[preflight.params]
-command = "gh issue list --repo acme/app --label P1 --json number,title,body --limit 20"
-output = "/tmp/context/issues.json"       # Optional: capture stdout to file
-
-# Optional: custom parameters injected into the agent prompt
-[params]
-repos = ["acme/app", "acme/api"]
-triggerLabel = "agent"
-assignee = "bot-user"
-sentryOrg = "acme"
-sentryProjects = ["web-app", "api"]
-```
-
-## Field Reference
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `credentials` | string[] | Yes | Credential refs as `"type:instance"` needed at runtime |
-| `schedule` | string | No* | Cron expression for polling |
-| `scale` | number | No | Number of concurrent runs allowed (default: 1). Set to `0` to disable the agent. Use lock skills in your actions to coordinate instances. See [Resource Locks](agents.md#resource-locks). |
-| `timeout` | number | No | Max runtime in seconds. Falls back to `[local].timeout` in project config, then `900`. On AWS ECS, agents with timeout <= 900 auto-route to Lambda for faster startup. See [Timeout](#timeout). |
-| `model` | table | No | LLM model configuration (falls back to `[model]` in project `config.toml`) |
-| `model.provider` | string | Yes* | LLM provider ("anthropic", "openai", "groq", "google", "xai", "mistral", "openrouter", or "custom") |
-| `model.model` | string | Yes* | Model ID |
-| `model.thinkingLevel` | string | No | Thinking budget level: off, minimal, low, medium, high, xhigh. Only relevant for Claude Sonnet/Opus. Omit for other models. |
-| `model.authType` | string | Yes* | Auth method for the provider |
-| `webhooks` | array | No* | Array of webhook trigger objects |
-| `preflight` | array | No | Array of preflight steps that run before the LLM session. See [Preflight](#preflight). |
-| `params` | table | No | Custom key-value params for the agent prompt |
-
-*At least one of `schedule` or `webhooks` is required (unless `scale = 0`). *Required within `[model]` if the agent defines its own model block (otherwise inherits from project `config.toml`).
-
-## Scale
-
-The `scale` field controls how many instances of an agent can run concurrently. This is useful for agents that handle high-volume workloads or when you want to process multiple tasks simultaneously.
-
-- **Default**: 1 (only one instance can run at a time)
-- **Minimum**: 0 (disables the agent — no runners, cron jobs, or webhook bindings are created)
-- **Maximum**: No hard limit, but consider system resources and model API rate limits
-
-### How it works
-
-1. **Scheduled runs**: If a cron trigger fires but all agent instances are busy, the scheduled run is skipped with a warning
-2. **Webhook events**: If a webhook arrives but all instances are busy, the event is queued (up to `workQueueSize` limit in global config, default: 100)
-3. **Agent calls**: If one agent calls another but all target instances are busy, the call is queued in the same work queue and processed when a runner frees up
-
-### Example use cases
-
-- **Dev agent** with `scale = 3`: Handle multiple GitHub issues simultaneously
-- **Review agent** with `scale = 2`: Review multiple PRs in parallel
-- **Monitoring agent** with `scale = 1`: Ensure only one instance processes alerts at a time
-- **Disabled agent** with `scale = 0`: Keep the config in the project but don't run it
-
-### Resource considerations
-
-Each parallel instance:
-- Uses separate Docker containers (in Docker mode)
-- Has independent logging streams
-- May consume LLM API quota concurrently
-- Uses system memory and CPU
-
-## Timeout
-
-The `timeout` field controls the maximum runtime for an agent invocation. When the timeout expires, the container is terminated.
-
-**Resolution order:** `agent-config.toml timeout` -> `config.toml [local].timeout` -> `900` (default)
-
-This means you can set a project-wide default in `[local].timeout` and override it per-agent.
-
-### Automatic Lambda routing (AWS ECS)
-
-When using `cloud.provider = "ecs"`, agents are automatically routed to the most efficient AWS compute service based on their effective timeout:
-
-| Effective timeout | Runtime | Cold start | Cost |
-|---|---|---|---|
-| **<= 900s** (15 min) | **AWS Lambda** | ~1-2s | Lower (pay per 100ms) |
-| **> 900s** | **ECS Fargate** | ~30-60s | Higher (pay per second, 1-min minimum) |
-
-This routing is automatic — you don't need to configure anything beyond setting the timeout. Both runtimes use the same ECR images (built via CodeBuild) and the same Secrets Manager credentials.
-
-**Why Lambda is faster:** Lambda keeps your container image warm in a pre-provisioned execution environment. When a function is invoked, Lambda can start executing in 1-2 seconds. ECS Fargate, by contrast, must provision a new VM, pull the container image, and start the container — which takes 30-60 seconds.
-
-**When to use a short timeout:** If your agent typically finishes in under 15 minutes (e.g., responding to a webhook, triaging an issue, reviewing a small PR), set `timeout = 600` or similar. The agent gets faster startup and lower cost on AWS. If an agent needs more than 15 minutes (e.g., large refactoring tasks, long-running monitoring loops), use a longer timeout and it will route to ECS Fargate automatically.
-
-### Lambda IAM roles
-
-When `al doctor -c` runs, it automatically creates Lambda execution roles (`al-{agentName}-lambda-role`) for agents whose effective timeout is <= 900s. These roles include permissions for Secrets Manager access, CloudWatch Logs, and ECR image pull. You can override the role with `cloud.lambdaRoleArn` in `config.toml`.
-
-### Examples
-
-```toml
-# Fast webhook responder — routes to Lambda on AWS
-timeout = 300       # 5 minutes
-
-# Medium-length task — still fits Lambda
-timeout = 900       # 15 minutes (Lambda max)
-
-# Long-running agent — routes to ECS Fargate
-timeout = 3600      # 1 hour
-
-# Omit timeout — uses [local].timeout or defaults to 900s
-# (routes to Lambda on AWS since 900 <= 900)
-```
-
-## Preflight
-
-Preflight steps run mechanical data-staging tasks after credentials are loaded but before the LLM session starts. They fetch data, clone repos, or run commands to prepare the workspace so the agent starts with everything it needs — instead of spending tokens fetching context at runtime.
-
-### How it works
-
-1. Steps run **sequentially** in the order they appear in `agent-config.toml`
-2. Steps run **inside the container** (or host process in `--no-docker` mode) after credential/env setup
-3. Providers write files to disk — your ACTIONS.md references the staged files
-4. Environment variable interpolation is supported: `${VAR_NAME}` in string params is resolved against `process.env` (which already has credentials injected)
-
-### Step fields
-
-Each `[[preflight]]` entry has these fields:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | Provider name: `shell`, `http`, or `git-clone` |
-| `required` | boolean | No | If `true` (default), the agent aborts on failure. If `false`, logs a warning and continues. |
-| `params` | table | Yes | Provider-specific parameters (see below) |
-
-### Built-in providers
-
-#### `shell`
-
-Runs a command via `/bin/sh`. Optionally captures stdout to a file.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `command` | string | Yes | Shell command to execute |
-| `output` | string | No | File path to write stdout to. Parent directories are created automatically. |
-
-```toml
-[[preflight]]
-provider = "shell"
-[preflight.params]
-command = "gh issue list --repo acme/app --label P1 --json number,title,body --limit 20"
-output = "/tmp/context/issues.json"
-```
-
-#### `http`
-
-Fetches a URL and writes the response body to a file.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `url` | string | Yes | URL to fetch |
-| `output` | string | Yes | File path to write the response body |
-| `method` | string | No | HTTP method (default: `GET`) |
-| `headers` | table | No | HTTP headers as key-value pairs |
-| `body` | string | No | Request body (for POST/PUT) |
-
-```toml
-[[preflight]]
-provider = "http"
-required = false
-[preflight.params]
-url = "https://api.internal/v1/feature-flags"
-output = "/tmp/context/flags.json"
-headers = { Authorization = "Bearer ${INTERNAL_TOKEN}" }
-```
-
-#### `git-clone`
-
-Clones a git repository. Short `"owner/repo"` names are expanded to `git@github.com:owner/repo.git`; full URLs are passed through. Git credentials (SSH key, HTTPS token) are already configured from the agent's credentials.
-
-| Param | Type | Required | Description |
-|-------|------|----------|-------------|
-| `repo` | string | Yes | Repository: `"owner/repo"` or full URL |
-| `dest` | string | Yes | Local path to clone into |
-| `branch` | string | No | Branch to check out |
-| `depth` | number | No | Shallow clone depth (e.g., `1`) |
-
-```toml
-[[preflight]]
-provider = "git-clone"
-[preflight.params]
-repo = "acme/app"
-dest = "/tmp/repo"
-branch = "main"
-depth = 1
-```
-
-### Referencing staged files in ACTIONS.md
-
-Preflight writes files to disk — your ACTIONS.md tells the LLM what's there:
-
-```markdown
-## Context
-- The repo is cloned at `/tmp/repo`
-- Open P1 issues are at `/tmp/context/issues.json`
-- Feature flags (if available) are at `/tmp/context/flags.json`
-```
-
-### Notes
-
-- The `shell` provider is the escape hatch — anything a built-in provider doesn't cover can be expressed as a shell command
-- There is no per-step timeout — steps are bounded by the container-level timeout
-- Environment variables set inside `shell` child processes do not propagate back to the agent's `process.env`
-
-## Webhook Trigger Fields
-
-Each `[[webhooks]]` entry has the following fields:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `source` | string | Yes | Name of a webhook source from the project's `config.toml` (e.g. `"my-github"`) |
-
-All filter fields below are optional. Omit all of them to trigger on everything from that source.
-
-### GitHub filter fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `repos` | string[] | Filter to specific repos |
-| `events` | string[] | Event types: issues, pull_request, push, etc. |
-| `actions` | string[] | Event actions: opened, labeled, closed, etc. |
-| `labels` | string[] | Only trigger when issue/PR has these labels |
-| `assignee` | string | Only trigger when assigned to this user |
-| `author` | string | Only trigger for this author |
-| `branches` | string[] | Only trigger for these branches |
-
-### Sentry filter fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `resources` | string[] | Resource types: event_alert, metric_alert, issue, error, comment |
-
-## Model Configuration
-
-The `[model]` section is optional — agents inherit the default model from the project's `config.toml`. Only add `[model]` to an agent config if you want to override the default for that specific agent.
-
-See [Models](models.md) for all supported providers, model IDs, auth types, thinking levels, and credential setup.
-
-## Cloud Runtimes
-
-### Cloud Run (GCP)
-
-When using Cloud Run mode (`cloud.provider = "cloud-run"` in `config.toml`), each agent automatically gets a per-agent service account (`al-{agentName}@{gcpProject}.iam.gserviceaccount.com`) that only has access to the credentials listed in that agent's `credentials` array. Run `al doctor -c` to create the service accounts and IAM bindings. See [Cloud Run docs](cloud-run.md) for details.
-
-### ECS Fargate (AWS)
-
-When using ECS mode (`cloud.provider = "ecs"` in `config.toml`), each agent automatically uses a per-agent IAM task role (`al-{agentName}-task-role`) that only has access to the credentials listed in that agent's `credentials` array. The task role ARN is derived from the ECR repository's account ID. See [ECS docs](ecs.md) for setup instructions including how to create the per-agent task roles.

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