@action-llama/action-llama 0.6.0 → 0.6.1

package/AGENTS.md

@@ -407,6 +407,16 @@ maxTriggerDepth = 3   # max depth for agent-to-agent trigger chains (default: 3)
 
 Webhook-triggered and agent-triggered runs do not re-run — they respond to a single event.
 
+## Skills Reference
+
+Agents have access to runtime skills — capabilities taught via a preamble before the playbook runs. Each skill is documented for LLM consumption:
+
+- [Skills Overview](skills/README.md)
+- [Credentials](skills/credentials.md) — env vars, tools, and access patterns from mounted credentials
+- [Signals](skills/signals.md) — `[SILENT]`, `[STATUS]`, `[TRIGGER]` output signals
+- [Resource Locks](skills/resource-locks.md) — `LOCK`, `UNLOCK`, `HEARTBEAT` for parallel coordination
+- [Environment](skills/environment.md) — trigger types, context blocks, container filesystem
+
 ## Further Documentation
 
 Full documentation is available on GitHub:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@action-llama/action-llama",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Automated development agents triggered by cron or webhooks. BYOM — bring your own model.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "docker",
+    "skills",
     "AGENTS.md",
     "README.md",
     "LICENSE"

package/skills/README.md

@@ -0,0 +1,14 @@
+# 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) | Coordination primitives for avoiding duplicate work across parallel instances |
+| [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/skills/credentials.md

@@ -0,0 +1,50 @@
+# 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:
+  ```
+  curl -s -X POST $GATEWAY_URL/shutdown \
+    -H 'Content-Type: application/json' \
+    -d '{"secret":"'$SHUTDOWN_SECRET'","reason":"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/skills/environment.md

@@ -0,0 +1,102 @@
+# 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 playbook defines. If there's nothing to do, respond with `[SILENT]`.
+
+**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 playbook 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 playbook 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 lock/shutdown APIs. You don't need to set them, but you use them in curl commands:
+
+| Var | Purpose |
+|-----|---------|
+| `GATEWAY_URL` | Base URL of the scheduler's HTTP gateway |
+| `SHUTDOWN_SECRET` | Per-run secret for authenticated API calls (locks, shutdown) |

package/skills/resource-locks.md

@@ -0,0 +1,77 @@
+# 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).
+
+Locks are only available in Docker mode. Each lock is identified by a **resource key** — a free-form string you choose.
+
+## Operations
+
+### LOCK(resourceKey)
+
+Acquire an exclusive lock before working on a shared resource.
+
+```
+curl -s -X POST $GATEWAY_URL/locks/acquire \
+  -H 'Content-Type: application/json' \
+  -d '{"secret":"'$SHUTDOWN_SECRET'","resourceKey":"<resourceKey>"}'
+```
+
+**Responses:**
+- Acquired: `{"ok":true,"resourceKey":"..."}`
+- Conflict: `{"ok":false,"holder":"<other-agent>","heldSince":...}` (HTTP 409) — another instance has it. Skip this resource.
+- Already holding another lock: `{"ok":false,"reason":"already holding lock on ..."}` (HTTP 409) — release your current lock first.
+
+### UNLOCK(resourceKey)
+
+Release a lock when you're done with the resource.
+
+```
+curl -s -X POST $GATEWAY_URL/locks/release \
+  -H 'Content-Type: application/json' \
+  -d '{"secret":"'$SHUTDOWN_SECRET'","resourceKey":"<resourceKey>"}'
+```
+
+**Response:** `{"ok":true}`
+
+### HEARTBEAT(resourceKey)
+
+Extend the TTL on a lock you hold. Use during long-running work to prevent expiry.
+
+```
+curl -s -X POST $GATEWAY_URL/locks/heartbeat \
+  -H 'Content-Type: application/json' \
+  -d '{"secret":"'$SHUTDOWN_SECRET'","resourceKey":"<resourceKey>"}'
+```
+
+**Response:** `{"ok":true,"expiresAt":...}`
+
+## Resource key conventions
+
+Use descriptive, unique keys that identify the exact resource:
+
+| Pattern | 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")` |
+
+## Rules
+
+- **One lock at a time.** You can hold at most one lock. UNLOCK before acquiring a different resource.
+- **Always LOCK before starting work** on a shared resource (issues, PRs, deployments).
+- **Always UNLOCK when done.** Locks are auto-released when your container exits, but explicit unlock is cleaner.
+- **If a LOCK fails, skip that resource.** Do not wait or retry — move on to the next item.
+- **Use 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.
+
+## Example workflow
+
+```
+1. List open issues labeled "agent"
+2. For each issue:
+   - LOCK("github issue acme/app#42")
+   - If the lock fails, skip — another instance is handling it
+   - Clone, branch, implement, push, open PR
+   - UNLOCK("github issue acme/app#42")
+3. If no issues to work on, respond with [SILENT]
+```

package/skills/signals.md

@@ -0,0 +1,54 @@
+# Skill: Signals
+
+Signals are text patterns you emit in your output. The scheduler scans your output for these patterns and acts on them. They are your only communication channel back to the scheduler.
+
+## `[SILENT]`
+
+Tells the scheduler you found no work to do.
+
+```
+[SILENT]
+```
+
+**When to use:** When you check for work (issues, PRs, alerts) and find nothing actionable. This is how the scheduler knows you're idle — it logs "no work to do" and skips further processing of your output.
+
+**Effect on reruns:** On scheduled runs, a `[SILENT]` response stops the rerun loop. Without it, the scheduler assumes you did productive work and immediately re-runs you (up to `maxReruns` times). Always emit `[SILENT]` when there's nothing to do.
+
+## `[STATUS: <text>]`
+
+Sends a status update to the TUI and logs.
+
+```
+[STATUS: reviewing PR #42]
+[STATUS: deploying api-prod]
+[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:** The text between `[STATUS:` and `]` is extracted verbatim. Keep it short and descriptive.
+
+## `[TRIGGER: <agent>]...[/TRIGGER]`
+
+Triggers another agent with context you provide.
+
+```
+[TRIGGER: reviewer]
+I just opened PR #42 on acme/app. Please review it.
+URL: https://github.com/acme/app/pull/42
+[/TRIGGER]
+```
+
+**When to use:** When your work creates something another agent should act on — e.g. a dev agent opens a PR and wants a reviewer agent to review it.
+
+**Format:** The opening tag must be on its own line: `[TRIGGER: <agent-name>]`. The closing tag must also be on its own line: `[/TRIGGER]`. Everything between them becomes the context passed to the target agent.
+
+**Rules:**
+- You cannot trigger yourself — self-triggers are silently skipped
+- If the target agent doesn't exist or is busy, the trigger is skipped
+- Trigger chains are bounded by `maxTriggerDepth` (default: 3) to prevent infinite loops
+- The target agent receives your context in an `<agent-trigger>` block with your agent name as the `source`
+
+## Multiple signals
+
+You can emit multiple signals in one run. For example, you might emit several `[STATUS]` updates as you work, then a `[TRIGGER]` at the end. `[SILENT]` should only appear alone — if you did work, don't emit `[SILENT]`.