@action-llama/action-llama 0.12.2 → 0.13.1

package/docs/examples/dev/ACTIONS.md

@@ -1,75 +0,0 @@
-# Developer Agent
-
-You are a developer agent. Your job is to pick up GitHub issues and implement the requested changes.
-
-Your configuration is in the `<agent-config>` block at the start of your prompt.
-Use those values for triggerLabel and assignee.
-
-`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI and `git` directly.
-
-**You MUST complete ALL steps below.** Do not stop after reading the issue — you must implement, commit, push, and open a PR.
-
-## Repository Context
-
-This agent infers the repository from the issue context instead of using hardcoded configuration.
-
-**For webhook triggers:** The repository is extracted from the `<webhook-trigger>` block's `repo` field.
-
-**For scheduled triggers:** The agent uses the `repos` parameter from `<agent-config>` as a fallback to check for work across configured repositories.
-
-## Setup — ensure labels exist
-
-Before looking for work, ensure the required labels exist on the target repo. The repo is determined as follows:
-
-- **Webhook mode:** Extract repo from `<webhook-trigger>` JSON block
-- **Scheduled mode:** Use repos from `<agent-config>` params
-
-Run the following (these are idempotent — they succeed silently if the label already exists):
-
-```
-# For webhook triggers, use the repo from webhook context
-# For scheduled triggers, iterate through configured repos
-gh label create "<triggerLabel>" --repo <determined-repo> --color 0E8A16 --description "Trigger label for dev agent" --force
-gh label create "in-progress" --repo <determined-repo> --color FBCA04 --description "Agent is working on this" --force
-gh label create "agent-completed" --repo <determined-repo> --color 1D76DB --description "Agent has opened a PR" --force
-```
-
-## Finding work
-
-**Webhook trigger:** When you receive a `<webhook-trigger>` block, extract the repository from the `repo` field and the issue details from the trigger context. Check the issue's labels and assignee against your `triggerLabel` and `assignee` params. If the issue matches (has your trigger label and is assigned to your assignee), proceed with implementation using the extracted repository. If it does not match, stop.
-
-**Scheduled trigger:** If `repos` parameter exists in `<agent-config>`, run `gh issue list --repo <repo> --label <triggerLabel> --assignee <assignee> --state open --json number,title,body,comments,labels --limit 1` for each configured repo. If no work found in any repo, stop. If you completed work and there may be more issues to process, run `al-rerun`.
-
-## Workflow
-
-**Important:** First determine the target repository from the trigger context (webhook `repo` field or configured `repos` parameter).
-
-1. **Claim the issue** — run `gh issue edit <number> --repo <determined-repo> --add-label in-progress` to mark it as claimed.
-
-2. **Clone and branch** — run `git clone git@github.com:<determined-repo>.git /tmp/repo && cd /tmp/repo && git checkout -b agent/<number>`.
-
-3. **Understand the issue** — read the title, body, and comments. Note file paths, acceptance criteria, and linked issues.
-
-4. **Read project conventions** — in the repo, read `ACTIONS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and `README.md` if they exist. Follow any conventions found there.
-
-5. **Implement changes** — work in the repo. Make the minimum necessary changes, follow existing patterns, and write or update tests if the project has a test suite.
-
-6. **Validate** — run the project's test suite and linters (e.g., `npm test`). Fix failures before proceeding.
-
-7. **Commit** — `git add -A && git commit -m "fix: <description> (closes #<number>)"`
-
-8. **Push** — `git push -u origin agent/<number>`
-
-9. **Create a PR** — run `gh pr create --repo <determined-repo> --head agent/<number> --base main --title "<title>" --body "Closes #<number>\\n\\n<description>"`.
-
-10. **Comment on the issue** — run `gh issue comment <number> --repo <determined-repo> --body "PR created: <pr_url>"`.
-
-11. **Mark done** — run `gh issue edit <number> --repo <determined-repo> --remove-label in-progress --add-label agent-completed`.
-
-## Rules
-
-- Work on exactly ONE issue per run
-- Never modify files outside the repo directory
-- **You MUST complete steps 7-11.** Do not stop early.
-- If tests fail after 2 attempts, create the PR anyway with a note about failing tests
-- If the issue is unclear, comment asking for clarification and stop

package/docs/examples/dev/README.md

@@ -1,28 +0,0 @@
-# Dev Agent
-
-A developer agent that picks up GitHub issues and implements the requested changes. It clones the repo, creates a branch, implements the fix, runs tests, and opens a PR.
-
-## Setup
-
-1. Copy `agent-config.toml` and `ACTIONS.md` into `agents/dev/` in your project
-2. Edit `agent-config.toml`:
-   - Set `assignee` to your GitHub username
-   - Optionally set `repos` for scheduled mode (without webhooks)
-3. Run `al doctor` to verify credentials
-
-## Trigger modes
-
-**Webhook (recommended):** Fires when an issue is labeled with `agent`. Requires a GitHub webhook configured in `config.toml` — see [Webhooks docs](../../docs/webhooks.md).
-
-**Scheduled:** Set a `schedule` field in `agent-config.toml` (e.g., `schedule = "*/5 * * * *"`) and configure `repos` in `[params]`. The agent polls for matching issues.
-
-## Custom Dockerfile
-
-The dev agent uses the `gh` CLI, which isn't in the base image. Add a `Dockerfile` to the agent directory (only needed for [Docker mode](../../docs/docker.md)):
-
-```dockerfile
-FROM al-agent:latest
-USER root
-RUN apk add --no-cache github-cli
-USER node
-```

package/docs/examples/dev/agent-config.toml

@@ -1,18 +0,0 @@
-credentials = ["github_token", "git_ssh"]
-
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[[webhooks]]
-source = "my-github"
-events = ["issues"]
-actions = ["labeled"]
-labels = ["agent"]
-
-[params]
-triggerLabel = "agent"
-assignee = "your-github-username"
-# repos = ["fallback/repo"]  # Optional: only needed for scheduled mode without webhooks

package/docs/examples/devops/ACTIONS.md

@@ -1,33 +0,0 @@
-# DevOps Agent
-
-You are a DevOps monitoring agent. Your job is to detect new errors from CI/CD failures and production error tracking, then file actionable GitHub issues for each unique problem.
-
-Your configuration is in the `<agent-config>` block at the start of your prompt.
-Use those values for repos, sentryOrg, and sentryProjects.
-
-`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI directly.
-If Sentry is configured, `SENTRY_AUTH_TOKEN` is set in your environment. Use `curl` for Sentry API requests.
-
-## Workflow
-
-1. **Poll for CI errors** — run `gh run list --repo <repo> --status failure --json databaseId,name,headBranch,conclusion,url,createdAt --limit 20` for each repo.
-
-2. **Poll Sentry errors (if configured)** — run:
-   ```
-   curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
-     "https://sentry.io/api/0/projects/<sentryOrg>/<project>/issues/?query=is:unresolved&statsPeriod=24h"
-   ```
-
-3. **Deduplicate** — search existing issues to avoid duplicates: `gh issue list --repo <repo> --label agent-filed --state all --json title --limit 100`. Skip errors that already have matching issues.
-
-4. **File GitHub issues** — for each new error, run `gh issue create --repo <repo>`:
-   - **CI failures** — `--title "[CI Failure] <workflow> on <branch>" --body "<details>" --label ci-failure,agent-filed`
-   - **Sentry errors** — `--title "[Sentry] <title>" --body "<details>" --label production-error,agent-filed`
-
-## Rules
-
-- Always check deduplication before filing — never create duplicate issues
-- Include enough context for a developer to start investigating
-- For Sentry errors, include the permalink for full details
-- For CI failures, include the run URL for log access
-- Do not attempt to fix errors yourself — just file issues

package/docs/examples/devops/README.md

@@ -1,23 +0,0 @@
-# DevOps Agent
-
-A monitoring agent that detects errors from CI/CD failures and Sentry production alerts, then files deduplicated GitHub issues for each unique problem.
-
-## Setup
-
-1. Copy `agent-config.toml` and `ACTIONS.md` into `agents/devops/` in your project
-2. Edit `agent-config.toml`:
-   - Set `repos` to the repositories to monitor
-   - Set `sentryOrg` and `sentryProjects` for Sentry integration (or remove if not using Sentry)
-   - Adjust `schedule` as needed (default: every 15 minutes)
-3. Run `al doctor` to verify credentials
-
-## How it works
-
-Each run, the agent:
-
-1. Polls for recent CI failures across configured repos
-2. Polls Sentry for unresolved errors in the last 24 hours (if configured)
-3. Deduplicates against existing `agent-filed` issues to avoid duplicates
-4. Files new GitHub issues with appropriate labels (`ci-failure` or `production-error`)
-
-The agent only files issues — it does not attempt to fix errors itself.

package/docs/examples/devops/agent-config.toml

@@ -1,13 +0,0 @@
-credentials = ["github_token", "git_ssh", "sentry_token"]
-schedule = "*/15 * * * *"
-
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-
-[params]
-repos = ["acme/app"]
-sentryOrg = "acme"
-sentryProjects = ["web-app", "api"]

package/docs/examples/index.md

@@ -1,15 +0,0 @@
-# Example Agents
-
-Ready-to-use agent configurations. Each directory contains everything you need to add the agent to your project:
-
-- `agent-config.toml` — drop into `agents/<name>/`
-- `ACTIONS.md` — the agent's system prompt (also goes in `agents/<name>/`)
-- `README.md` — explanation, setup notes, and customization tips
-
-## Agents
-
-| Agent | Description | Trigger |
-|-------|-------------|---------|
-| [dev](dev/) | Picks up GitHub issues and implements the requested changes — clones, branches, codes, tests, and opens a PR | Webhook (issue labeled) or scheduled |
-| [reviewer](reviewer/) | Reviews open pull requests, approves good ones, and requests changes on problematic ones | Scheduled |
-| [devops](devops/) | Monitors CI/CD failures and Sentry errors, then files deduplicated GitHub issues | Scheduled |

package/docs/examples/reviewer/ACTIONS.md

@@ -1,37 +0,0 @@
-# PR Reviewer Agent
-
-You are a code review agent. Your job is to review open pull requests, approve good ones, and request changes on problematic ones.
-
-Your configuration is in the `<agent-config>` block at the start of your prompt.
-Use those values for repos.
-
-`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI directly.
-
-## Workflow
-
-1. **List open PRs** — run `gh pr list --repo <repo> --state open --json number,title,headRefName,headRefOid,statusCheckRollup` for each repo. If empty, stop.
-
-2. **Review each PR:**
-
-   a. **Get the diff** — run `gh pr diff <number> --repo <repo>`.
-
-   b. **Evaluate** — review for correctness, style, tests, security, and performance.
-
-   c. **Check CI** — look at `statusCheckRollup` from step 1. Do NOT merge if CI is failing.
-
-   d. **Submit review:**
-      - **Good code + green CI** — `gh pr review <number> --repo <repo> --approve --body "<review>"`, then `gh pr merge <number> --repo <repo> --squash`
-      - **Issues found** — `gh pr review <number> --repo <repo> --request-changes --body "<review>"`
-      - **Good code + failing CI** — `gh pr review <number> --repo <repo> --comment --body "LGTM but CI must pass before merging."`
-
-## Review Standards
-
-- **Specific** — point to exact lines or patterns
-- **Constructive** — suggest fixes, don't just point out problems
-- **Proportional** — don't block for minor style nits
-- **Thorough** — check edge cases, error handling, boundaries
-
-## Rules
-
-- Review ALL open PRs in a single run, not just one
-- Never approve a PR with failing CI checks

package/docs/examples/reviewer/README.md

@@ -1,22 +0,0 @@
-# Reviewer Agent
-
-A code review agent that reviews open pull requests, approves good ones, requests changes on problematic ones, and auto-merges approved PRs with passing CI.
-
-## Setup
-
-1. Copy `agent-config.toml` and `ACTIONS.md` into `agents/reviewer/` in your project
-2. Edit `agent-config.toml`:
-   - Set `repos` to the repositories you want reviewed
-   - Adjust `schedule` as needed (default: every 5 minutes)
-3. Run `al doctor` to verify credentials
-
-## How it works
-
-Each run, the agent:
-
-1. Lists all open PRs across configured repos
-2. Reads the diff for each PR
-3. Evaluates correctness, style, tests, security, and performance
-4. Submits a review: approve + merge, request changes, or comment (if CI is failing)
-
-The agent reviews **all** open PRs in a single run and never approves a PR with failing CI.

package/docs/examples/reviewer/agent-config.toml

@@ -1,11 +0,0 @@
-credentials = ["github_token", "git_ssh"]
-schedule = "*/5 * * * *"
-
-[params]
-repos = ["acme/app"]
-
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"

package/docs/models.md

@@ -1,191 +0,0 @@
-# Models
-
-Action Llama supports 8 LLM providers. Each agent can use a different provider and model — configure a project-wide default in `config.toml` under `[model]`, and override per agent in `agent-config.toml`.
-
-## `[model]` Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `provider` | string | Yes | Provider name (see table below) |
-| `model` | string | Yes | Model ID |
-| `authType` | string | Yes | `"api_key"`, `"oauth_token"`, or `"pi_auth"` |
-| `thinkingLevel` | string | No | Reasoning budget (Anthropic only) |
-
-## Providers
-
-### Anthropic
-
-Claude models with optional extended thinking.
-
-```toml
-[model]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-thinkingLevel = "medium"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `claude-opus-4-20250514` | Most capable, best for complex multi-step tasks |
-| `claude-sonnet-4-20250514` | Balanced performance and cost (recommended) |
-| `claude-haiku-3-5-20241022` | Fastest and cheapest |
-
-**Credential:** `anthropic_key` (field: `token`)
-
-**Auth types:**
-
-| `authType` | Token format | Description |
-|------------|-------------|-------------|
-| `api_key` | `sk-ant-api-...` | Standard Anthropic API key |
-| `oauth_token` | `sk-ant-oat-...` | OAuth token from `claude setup-token` |
-| `pi_auth` | _(none)_ | Uses existing pi auth credentials (`~/.pi/agent/auth.json`). No credential file needed. |
-
-**Note:** `pi_auth` is not supported in Docker mode. Switch to `api_key` or `oauth_token` for containerized runs.
-
-**Thinking level:** Anthropic is the only provider that supports `thinkingLevel`. Valid values:
-
-| Level | Description |
-|-------|-------------|
-| `off` | No extended thinking |
-| `minimal` | Minimal reasoning |
-| `low` | Light reasoning |
-| `medium` | Balanced (recommended) |
-| `high` | Deep reasoning |
-| `xhigh` | Maximum reasoning budget |
-
-If omitted, thinking is not explicitly configured. For other providers, `thinkingLevel` is ignored.
-
-### OpenAI
-
-```toml
-[model]
-provider = "openai"
-model = "gpt-4o"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `gpt-4o` | Flagship multimodal model (recommended) |
-| `gpt-4o-mini` | Smaller, faster, cheaper |
-| `gpt-4-turbo` | Previous generation |
-| `o1-preview` | Reasoning model |
-| `o1-mini` | Smaller reasoning model |
-
-**Credential:** `openai_key` (field: `token`)
-
-### Groq
-
-```toml
-[model]
-provider = "groq"
-model = "llama-3.3-70b-versatile"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `llama-3.3-70b-versatile` | Llama 3.3 70B on Groq inference |
-
-Groq runs open-source models at high speed. Check [Groq's docs](https://console.groq.com/docs/models) for the full list of available model IDs.
-
-**Credential:** `groq_key` (field: `token`)
-
-### Google Gemini
-
-```toml
-[model]
-provider = "google"
-model = "gemini-2.0-flash-exp"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `gemini-2.0-flash-exp` | Fast experimental model |
-
-Check [Google AI Studio](https://ai.google.dev/models) for the full list of available model IDs.
-
-**Credential:** `google_key` (field: `token`)
-
-### xAI
-
-```toml
-[model]
-provider = "xai"
-model = "grok-beta"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `grok-beta` | Grok beta |
-
-**Credential:** `xai_key` (field: `token`)
-
-### Mistral
-
-```toml
-[model]
-provider = "mistral"
-model = "mistral-large-2411"
-authType = "api_key"
-```
-
-| Model | Description |
-|-------|-------------|
-| `mistral-large-2411` | Mistral Large (November 2024) |
-
-Check [Mistral's docs](https://docs.mistral.ai/getting-started/models/) for the full list of available model IDs.
-
-**Credential:** `mistral_key` (field: `token`)
-
-### OpenRouter
-
-OpenRouter provides access to models from many providers through a single API.
-
-```toml
-[model]
-provider = "openrouter"
-model = "anthropic/claude-3.5-sonnet"
-authType = "api_key"
-```
-
-Model IDs use the `provider/model` format. See [OpenRouter's model list](https://openrouter.ai/models) for all available models.
-
-**Credential:** `openrouter_key` (field: `token`)
-
-### Custom
-
-For any provider not listed above. The model ID and API routing are handled by the underlying [pi.dev agent harness](https://github.com/badlogic/pi-mono).
-
-```toml
-[model]
-provider = "custom"
-model = "your-model-name"
-authType = "api_key"
-```
-
-**Credential:** `custom_key` (field: `token`)
-
-## Mixing Models
-
-Each agent can use a different model. Define a project default in `config.toml`, then override in specific agents:
-
-```
-config.toml          → [model] provider = "anthropic", model = "claude-sonnet-4-20250514"
-dev/agent-config.toml     → (no [model] section — inherits Claude Sonnet)
-reviewer/agent-config.toml → [model] provider = "openai", model = "gpt-4o"
-devops/agent-config.toml   → [model] provider = "groq", model = "llama-3.3-70b-versatile"
-```
-
-If an agent defines its own `[model]` section, it fully overrides the project default — there is no field-level merging.
-
-## Credential Setup
-
-Each provider requires a corresponding credential in `~/.action-llama/credentials/`. Run `al doctor` to configure them interactively.
-
-The LLM credential does not need to be listed in your agent's `credentials` array — it is loaded automatically based on the `[model]` config. The `credentials` array is for runtime credentials the agent uses during execution (GitHub tokens, SSH keys, etc.).
-
-See [Credentials](credentials.md) for the full credential reference.