@action-llama/action-llama 0.13.4 → 0.13.5

package/dist/build-info.json

@@ -1 +1 @@
-{"gitSha":"6b29f4cc"}
+{"gitSha":"36b1771b"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@action-llama/action-llama",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "description": "Automated development agents triggered by cron or webhooks. BYOM — bring your own model.",
   "type": "module",
   "license": "MIT",

package/agent-docs/skills/README.md

@@ -1,15 +0,0 @@
-# Agent Skills Reference
-
-These docs are for **LLMs running as Action Llama agents**. They describe the runtime capabilities available to you during a run.
-
-Skills are organized by category:
-
-| Skill | What it covers |
-|-------|---------------|
-| [Credentials](credentials.md) | Environment variables, tools, and access patterns available from mounted credentials |
-| [Signals](signals.md) | Text signals you emit in your output to communicate with the scheduler |
-| [Resource Locks](resource-locks.md) | `rlock`/`runlock`/`rlock-heartbeat` for coordinating parallel instances |
-| [Calls](calls.md) | `al-call`/`al-check`/`al-wait` for agent-to-agent calls |
-| [Environment](environment.md) | How to determine your trigger type and where to find context variables |
-
-You do not need to memorize the underlying mechanics (curl commands, env var names). Your prompt includes the details at runtime. These docs help you understand what each skill does and when to use it.

package/agent-docs/skills/calls.md

@@ -1,82 +0,0 @@
-# Skill: Agent-to-Agent Calls
-
-Call other agents and retrieve their results. These commands are available in Docker mode only.
-
-## Commands
-
-### `al-call <agent>`
-
-Dispatch a call to another agent. Pass context via stdin.
-
-```
-echo "Review PR #42 on acme/app" | al-call reviewer
-```
-
-**Response:** `{"ok":true,"callId":"<uuid>"}`
-
-**Exit codes:** 0=dispatched, 1=rejected, 3=auth error, 9=missing arg, 5=no gateway, 6=unreachable, 7=unexpected — see [exit code table](#exit-codes)
-
-### `al-check <callId>`
-
-Non-blocking status check on a dispatched call.
-
-```
-al-check "abc-123"
-```
-
-**Response:** `{"status":"pending|running|completed|error","returnValue":"...","errorMessage":"..."}`
-
-**Exit codes:** 0=found, 2=not found, 3=auth error, 9=missing arg, 5=no gateway, 6=unreachable, 7=unexpected — see [exit code table](#exit-codes)
-
-### `al-wait <callId> [...] [--timeout N]`
-
-Block until one or more calls complete. Default timeout: 900 seconds.
-
-```
-al-wait "abc-123" "def-456" --timeout 300
-```
-
-**Response:** JSON object keyed by callId, each value is the call status object.
-
-**Exit codes:** 0=all complete, 9=missing arg, 5=no gateway, 8=timeout — see [exit code table](#exit-codes)
-
-## Patterns
-
-### Fire and wait
-
-```sh
-CALL_ID=$(echo "Review PR #42 on acme/app" | al-call reviewer | jq -r .callId)
-RESULT=$(al-wait "$CALL_ID")
-REVIEW=$(echo "$RESULT" | jq -r ".[\"$CALL_ID\"].returnValue")
-```
-
-### Fan-out
-
-```sh
-ID1=$(echo "Check API tests" | al-call tester | jq -r .callId)
-ID2=$(echo "Check UI tests" | al-call tester | jq -r .callId)
-RESULTS=$(al-wait "$ID1" "$ID2" --timeout 600)
-```
-
-### Handle rejection
-
-```sh
-RESP=$(echo "context" | al-call target-agent)
-EXIT=$?
-if [ "$EXIT" -eq 1 ]; then
-  echo "Call rejected: $(echo "$RESP" | jq -r .reason)"
-elif [ "$EXIT" -ne 0 ]; then
-  echo "Call failed with exit $EXIT"
-fi
-```
-
-## Rules
-
-- An agent cannot call itself
-- If the target is busy, the call is queued until a runner frees up
-- Call chains are limited by `maxCallDepth` in `config.toml` (default: 3)
-- Use `al-return` to send a result back to the calling agent
-
-## Exit Codes
-
-All gateway-calling shell commands share a common exit code scheme. See the [Shell Command Exit Codes](../AGENTS.md#shell-command-exit-codes) section in AGENTS.md for the full table.

package/agent-docs/skills/credentials.md

@@ -1,45 +0,0 @@
-# Skill: Credentials
-
-Credentials are mounted into your container automatically based on your agent's `credentials` array in `agent-config.toml`. You never need to configure, fetch, or manage credentials yourself — they are ready to use when your run starts.
-
-## Environment variables set for you
-
-| Credential type | Env vars / tools available | How to use |
-|----------------|---------------------------|------------|
-| `github_token` | `GITHUB_TOKEN`, `GH_TOKEN` | Use `gh` CLI and `git` directly. Both vars are set to the same value. |
-| `git_ssh` | `GIT_SSH_COMMAND`, `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL` | `git clone`, `git push`, and `git commit` work directly. SSH key is configured automatically. |
-| `sentry_token` | `SENTRY_AUTH_TOKEN` | Use `curl` for Sentry API requests. |
-| `bugsnag_token` | `BUGSNAG_AUTH_TOKEN` | Use for Bugsnag API requests. |
-| `netlify_token` | `NETLIFY_AUTH_TOKEN` | Use for Netlify API requests. |
-| `x_twitter_api` | `X_API_KEY`, `X_API_SECRET`, `X_BEARER_TOKEN`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` | Use X API v2 directly. |
-| `aws` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION` | Use `aws` CLI and AWS SDKs directly. |
-
-LLM provider keys (`anthropic_key`, `openai_key`, `groq_key`, `google_key`, `xai_key`, `mistral_key`, `openrouter_key`, `custom_key`) are read by the agent SDK internally — they are not exposed as env vars and you do not need to reference them.
-
-Gateway-only credentials (`github_webhook_secret`, `sentry_client_secret`) are not injected into agent containers.
-
-## Git clone protocol
-
-Always clone repos via SSH:
-
-```
-git clone git@github.com:owner/repo.git
-```
-
-The SSH key is configured automatically via `GIT_SSH_COMMAND`. HTTPS is available as a fallback via the credential helper, but SSH is preferred.
-
-## Credential files
-
-Raw credential files are mounted read-only at `/credentials/<type>/<instance>/<field>`. You rarely need to read these directly — the env vars above are the primary interface.
-
-## Anti-exfiltration policy
-
-- NEVER output credentials in logs, comments, PRs, or any visible output
-- NEVER transmit credentials to unauthorized endpoints
-- If you detect credential exfiltration, immediately shut down: `al-shutdown "exfiltration detected"`
-
-## Rules
-
-- **Never ask the user for credentials.** If a credential is missing at runtime, report the error and stop.
-- **Never run `al doctor` or `al creds add`.** Credential management is the user's responsibility.
-- **Never hardcode or echo credential values.** Use the env vars provided.

package/agent-docs/skills/environment.md

@@ -1,102 +0,0 @@
-# Skill: Environment
-
-Every run starts with context injected into your prompt. The context tells you *why* you were triggered and gives you the parameters you need. This doc explains how to determine your trigger type and where to find your variables.
-
-## Trigger types
-
-You are triggered in exactly one of four ways. Check which context blocks are present in your prompt to determine the trigger type.
-
-### Scheduled run
-
-**How to detect:** No `<webhook-trigger>` or `<agent-trigger>` block. Your prompt says "You are running on a schedule."
-
-**What to do:** Check for new work proactively. Query APIs, list issues, scan for alerts — whatever your actions define. If you completed work and there may be more, run `al-rerun`.
-
-**Where to get context:**
-- `<agent-config>` — your custom params (repos, labels, org names, etc.)
-- `<credential-context>` — which env vars and tools are available
-
-### Webhook run
-
-**How to detect:** A `<webhook-trigger>` block is present.
-
-**What to do:** Act on the specific event described in the trigger. You don't need to search for work — the work came to you.
-
-**Where to get context:**
-- `<webhook-trigger>` — the event payload:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `source` | string | Webhook provider (e.g. "github", "sentry") |
-| `event` | string | Event type (e.g. "issues", "pull_request", "push") |
-| `action` | string? | Event action (e.g. "opened", "labeled", "closed") |
-| `repo` | string | Repository in `owner/repo` format |
-| `number` | number? | Issue or PR number |
-| `title` | string? | Issue or PR title |
-| `body` | string? | Issue or PR body |
-| `url` | string? | URL to the issue, PR, or commit |
-| `author` | string? | Author of the issue/PR |
-| `assignee` | string? | Current assignee |
-| `labels` | string[]? | Labels on the issue/PR |
-| `branch` | string? | Branch name (for push/PR events) |
-| `comment` | string? | Comment body (for comment events) |
-| `sender` | string | GitHub user who triggered the event |
-| `timestamp` | string | ISO 8601 timestamp |
-
-- `<agent-config>` — your custom params (use to cross-check labels, assignees, etc.)
-
-### Agent-triggered run
-
-**How to detect:** An `<agent-trigger>` block is present.
-
-**What to do:** Act on the request from the source agent. The trigger context tells you what happened and what's expected.
-
-**Where to get context:**
-- `<agent-trigger>` — the trigger payload:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `source` | string | Name of the agent that triggered you |
-| `context` | string | Free-form message from the source agent |
-
-- `<agent-config>` — your custom params
-
-### Manual run
-
-**How to detect:** No trigger blocks. Your prompt says "You have been triggered manually."
-
-**What to do:** Same as a scheduled run — check for work proactively.
-
-## The `<agent-config>` block
-
-Always present. Contains the JSON-serialized `[params]` table from your `agent-config.toml`. This is where agent authors put repo names, label names, org identifiers, and anything else the agent needs.
-
-Example:
-```json
-{"repos":["acme/app"],"triggerLabel":"agent","assignee":"bot-user"}
-```
-
-Your actions should reference these values by name rather than hardcoding them.
-
-## The `<credential-context>` block
-
-Always present. Lists the environment variables and tools available to you based on your mounted credentials. See [Credentials](credentials.md) for the full reference.
-
-## Container filesystem
-
-| Path | Mode | Contents |
-|------|------|----------|
-| `/app` | read-only | Action Llama application + node_modules |
-| `/credentials` | read-only | Mounted credential files |
-| `/workspace` | read-write (tmpfs, 2 GB) | Working directory — clone repos here |
-| `/tmp` | read-write (tmpfs, 512 MB) | Temporary files |
-| `/home/node` | read-write (tmpfs, 64 MB) | User home — `.ssh/` for SSH keys |
-
-## Internal env vars
-
-These are set automatically and used by the `rlock`/`runlock`/`al-shutdown` commands internally. You don't need to reference them directly:
-
-| Var | Purpose |
-|-----|---------|
-| `GATEWAY_URL` | Base URL of the scheduler's HTTP gateway |
-| `SHUTDOWN_SECRET` | Per-run secret for authenticated API calls |

package/agent-docs/skills/resource-locks.md

@@ -1,116 +0,0 @@
-# Skill: Resource Locks
-
-When multiple instances of your agent run in parallel (`scale > 1`), resource locks prevent two instances from working on the same thing (same issue, same PR, same deployment).
-
-Each lock is identified by a **resource key** — a free-form string you choose.
-
-## Commands
-
-### `rlock <resourceKey>`
-
-Acquire an exclusive lock before working on a shared resource.
-
-```
-rlock "github issue acme/app#42"
-```
-
-**Responses:**
-- Acquired: `{"ok":true}` (exit 0)
-- Conflict: `{"ok":false,"holder":"<other-agent>","heldSince":...}` (exit 1) — another instance has it. Skip this resource.
-- Possible deadlock: `{"ok":false,"reason":"possible deadlock: ...","deadlock":true,"cycle":[...]}` (exit 1) — a deadlock cycle was detected. Release your locks and back off. See [Deadlock detection](#deadlock-detection).
-
-**Exit codes:** 0=acquired, 1=conflict, 3=auth error, 9=missing arg, 6=unreachable, 7=unexpected — see [exit code table](../AGENTS.md#shell-command-exit-codes)
-
-### `runlock <resourceKey>`
-
-Release a lock when you're done with the resource.
-
-```
-runlock "github issue acme/app#42"
-```
-
-**Response:** `{"ok":true}` (exit 0)
-
-**Exit codes:** 0=released, 1=conflict (held by another), 2=not found, 3=auth error, 9=missing arg, 6=unreachable, 7=unexpected — see [exit code table](../AGENTS.md#shell-command-exit-codes)
-
-### `rlock-heartbeat <resourceKey>`
-
-Extend the TTL on a lock you hold. Use during long-running work to prevent expiry.
-
-```
-rlock-heartbeat "github issue acme/app#42"
-```
-
-**Response:** `{"ok":true,"expiresAt":...}` (exit 0)
-
-**Exit codes:** 0=extended, 1=conflict (held by another), 2=not found, 3=auth error, 9=missing arg, 6=unreachable, 7=unexpected — see [exit code table](../AGENTS.md#shell-command-exit-codes)
-
-## Resource key conventions
-
-Use descriptive, unique keys that identify the exact resource:
-
-| Pattern | Example |
-|---------|---------|
-| `github issue owner/repo#number` | `rlock "github issue acme/app#42"` |
-| `github pr owner/repo#number` | `rlock "github pr acme/app#17"` |
-| `deploy service-name` | `rlock "deploy api-prod"` |
-
-## Rules
-
-- **Always `rlock` before starting work** on a shared resource (issues, PRs, deployments).
-- **Always `runlock` when done.** Locks are auto-released when your container exits, but explicit unlock is cleaner.
-- **If `rlock` exits non-zero (or returns `{"ok":false,...}`), skip that resource.** Do not wait, retry, or proceed without the lock — move on to the next item.
-- **If `rlock` returns `deadlock: true`, release your locks and back off.** See [Deadlock detection](#deadlock-detection) below.
-- **Use `rlock-heartbeat` during long operations** to keep the lock alive. Each heartbeat resets the TTL.
-- **Locks expire after 30 minutes** by default (configurable via `gateway.lockTimeout` in `config.toml`). If you don't heartbeat and the lock expires, another instance can claim it.
-- When `GATEWAY_URL` is not set (single-instance mode), lock commands return `{"ok":true}` as a no-op (exit 0). When `GATEWAY_URL` is set but the gateway is unreachable, lock commands exit 6 — you must not proceed.
-
-## Multiple locks
-
-You can hold multiple locks simultaneously. This is useful when your workflow requires coordinating across several resources:
-
-```
-rlock "github issue acme/app#42"
-rlock "deploy api-prod"
-# ... work that needs both the issue and the deployment slot ...
-runlock "deploy api-prod"
-runlock "github issue acme/app#42"
-```
-
-Release each lock as soon as you no longer need it. Holding locks longer than necessary increases the chance of contention and deadlocks.
-
-## Deadlock detection
-
-When multiple agents each hold a lock the other needs, a **deadlock** can occur. The scheduler detects these cycles automatically.
-
-**Example:**
-- Agent A holds lock on `issue #1`, tries to acquire `issue #2` (held by Agent B)
-- Agent B holds lock on `issue #2`, tries to acquire `issue #1` (held by Agent A)
-- Neither can proceed — deadlock
-
-When a cycle is detected, `rlock` returns exit 1 with:
-
-```json
-{"ok":false,"reason":"possible deadlock: agent-a → issue #2 → agent-b → issue #1 → agent-a","deadlock":true,"cycle":["agent-a","issue #2","agent-b","issue #1"]}
-```
-
-**What to do when you see `deadlock: true`:**
-
-1. Release one or more of your currently held locks (`runlock`)
-2. Move on to other work, or wait briefly before retrying
-3. The other agent(s) will be able to proceed once you release
-
-The `cycle` array describes the chain: `[holderA, resourceX, holderB, resourceY, ...]`. Check the JSON output for the `deadlock` field to distinguish deadlocks from regular contention.
-
-## Example workflow
-
-```
-1. List open issues labeled "agent"
-2. For each issue:
-   - rlock "github issue acme/app#42"
-   - If ok is false and deadlock is true, runlock any held locks and retry later
-   - If ok is false, skip — another instance is handling it
-   - Clone, branch, implement, push, open PR
-   - runlock "github issue acme/app#42"
-3. If you completed work and there may be more issues, run `al-rerun`
-```

package/agent-docs/skills/signals.md

@@ -1,98 +0,0 @@
-# Skill: Signals
-
-Use signal commands to communicate with the scheduler and trigger actions. These commands write signal files to `$AL_SIGNAL_DIR` and optionally POST to the gateway for real-time TUI updates.
-
-## Commands
-
-**`al-rerun`** — Request an immediate rerun after completing work.
-
-```
-al-rerun
-```
-
-**When to use:** When you completed work (e.g. processed an issue, merged a PR) and there may be additional items in the backlog. The scheduler will immediately re-run you (up to `maxReruns` times) to drain remaining work.
-
-**When NOT to use:** If you found no work to do, or if you completed work but the backlog is empty. Simply end without calling `al-rerun` and the scheduler will wait for the next scheduled run.
-
-**Default behavior:** Without `al-rerun`, the scheduler treats your run as complete and does not rerun. This is the safe default — errors, rate limits, and empty runs won't trigger unwanted reruns.
-
-## `al-status "<text>"`
-
-Updates your status displayed in the TUI and logs. Exits 4 if no text argument is provided.
-
-```
-al-status "reviewing PR #42"
-al-status "deploying api-prod"
-al-status "waiting for CI checks"
-```
-
-**When to use:** At natural milestones during your work — starting a new phase, switching tasks, or waiting on something. Helps the operator see what you're doing in real time.
-
-**Format:** Provide the status text as a quoted argument. Keep it short and descriptive.
-
-## `al-return`
-
-Returns a value to the calling agent when you were invoked via `al-call`.
-
-```
-al-return "PR looks good. Approved with minor suggestions."
-```
-
-For multiline results, pipe via stdin:
-
-```
-cat <<'EOF' | al-return
-PR looks good. Approved with minor suggestions:
-- Line 42: consider using a const instead of let
-- Line 89: missing error handling for the API call
-EOF
-```
-
-**When to use:** When you were called by another agent (you'll see an `<agent-call>` block in your prompt) and need to send back a result. Pass your return value as an argument or pipe it via stdin.
-
-**Rules:**
-- If you call `al-return` multiple times, the last value wins
-- If you were not called by another agent, `al-return` is a no-op
-- Call chains are bounded by `maxCallDepth` (default: 3) to prevent infinite loops
-
-## `al-exit [code]`
-
-Terminates the agent with an optional exit code, indicating an unrecoverable error or intentional abort.
-
-```
-al-exit 10    # GitHub token is invalid or expired
-al-exit 11    # Permission denied accessing repository
-al-exit 15    # Unrecoverable error in build system
-al-exit       # Defaults to 15 (unrecoverable error)
-```
-
-**When to use:** When encountering errors that cannot be resolved by retrying — authentication failures, permission issues, invalid configuration, or when you need to abort due to user request or safety concerns.
-
-**Format:** Pass the exit code as an argument, or omit for code 15 (unrecoverable error).
-
-**Standard exit codes:**
-- `10` — Authentication/credentials failure
-- `11` — Permission/access denied
-- `12` — Rate limit exceeded
-- `13` — Configuration error
-- `14` — Missing dependency or service error
-- `15` — Generic unrecoverable error (default)
-- `16` — User-requested abort
-
-**Behavior:** The agent terminates with the specified exit code. The scheduler will not retry automatically.
-
-**When NOT to use:** For transient errors (network timeouts, temporary rate limits) or normal completion. Use normal error handling or simply complete the run instead.
-
-## Responses
-
-All signal commands return JSON responses:
-- Success: `{"ok":true}`
-- Error: `{"ok":false,"error":"<message>"}`
-
-## Multiple signals
-
-You can use multiple signal commands in one run. For example, you might run several `al-status` updates as you work, then `al-return` with your result, and `al-rerun` if there's more work to do.
-
-## Graceful degradation
-
-Commands gracefully degrade when `GATEWAY_URL` is not set — signal files are always written, but real-time TUI updates only work when a gateway is available. This allows agents to work in both containerized and host environments.