@action-llama/action-llama 0.12.2 → 0.13.1

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.

package/docs/commands.md

@@ -1,286 +0,0 @@
-# CLI Commands
-
-## `al new <name>`
-
-Creates a new Action Llama project. Runs interactive setup to configure credentials and LLM defaults.
-
-```bash
-npx @action-llama/action-llama new my-project
-```
-
-Creates:
-- `my-project/package.json` — with `@action-llama/action-llama` dependency
-- `my-project/.gitignore`
-- `my-project/.workspace/` — runtime state directory
-- Credential files in `~/.action-llama/credentials/`
-
-After setup, create agents by following [Creating Agents](creating-agents.md).
-
-## `al doctor`
-
-Checks all agent credentials and interactively prompts for any that are missing. Discovers agents in the project, collects their credential requirements (plus any webhook secret credentials), and ensures each one exists on disk. Also generates a gateway API key if one doesn't exist yet (used for dashboard and CLI authentication).
-
-Additionally validates webhook trigger field configurations to catch common errors like:
-- Using `repository` instead of `repos`
-- Misspelled field names
-- Invalid field types
-
-This helps catch configuration mistakes early and ensures webhook triggers are properly configured.
-
-```bash
-al doctor -p .
-al doctor -p ./my-project
-al doctor -c               # Also push creds to cloud + reconcile IAM
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Push credentials to cloud and create per-agent IAM resources |
-
-### `al doctor -c`
-
-In cloud mode, `al doctor` additionally:
-1. Pushes all local credentials to the cloud secret manager configured in `[cloud]`
-2. Creates per-agent IAM resources (service accounts for Cloud Run, task roles for ECS)
-3. Grants each agent access to only its declared secrets
-
-**Cloud Run** (`cloud.provider = "cloud-run"`):
-
-For each agent, it:
-1. Creates `al-{agentName}@{gcpProject}.iam.gserviceaccount.com`
-2. Grants `secretmanager.secretAccessor` on that agent's declared credentials
-3. Grants `iam.serviceAccountUser` for Cloud Run execution
-
-Requires `gcloud` CLI with project admin permissions. See [Cloud Run docs](cloud-run.md) for full setup.
-
-**ECS Fargate** (`cloud.provider = "ecs"`):
-
-For each agent, it:
-1. Creates IAM role `al-{agentName}-task-role`
-2. Attaches an inline policy granting `secretsmanager:GetSecretValue` on that agent's declared credentials
-
-Requires AWS CLI with IAM admin permissions. See [ECS docs](ecs.md) for full setup.
-
-**VPS** (`cloud.provider = "vps"`):
-
-Pushes all local credentials to the VPS filesystem over SSH. No IAM roles — SSH access implies full access. See [VPS docs](vps-deployment.md) for full setup.
-
-**Re-run after adding agents:** Whenever you add a new agent to your project, re-run `al doctor -c` to create IAM resources for the new agent (Cloud Run/ECS) or push credentials (VPS). Without this, the new agent won't have access to its credentials at runtime.
-
-## `al creds ls`
-
-Lists all stored credentials grouped by type, showing field names but not values.
-
-```bash
-al creds ls
-```
-
-Example output:
-
-```
-  Anthropic API Key (anthropic_key)
-    anthropic_key  (token)
-
-  GitHub Token (github_token)
-    github_token  (token)
-
-  GitHub Webhook Secret (github_webhook_secret)
-    github_webhook_secret:myapp  (secret)
-    github_webhook_secret:staging  (secret)
-```
-
-Default instances are shown without the `:default` suffix.
-
-## `al creds add <ref>`
-
-Add or update a credential. Runs the interactive prompter with validation for the credential type.
-
-```bash
-al creds add github_token              # adds github_token:default
-al creds add github_webhook_secret:myapp
-al creds add git_ssh:prod
-```
-
-The `<ref>` format is `type` or `type:instance`. If no instance is specified, defaults to `default`. If the credential already exists, you'll be prompted to update it.
-
-## `al creds rm <ref>`
-
-Remove a credential from disk.
-
-```bash
-al creds rm github_token               # removes github_token:default
-al creds rm github_webhook_secret:myapp
-```
-
-Removes all field files for the credential instance. If the type directory becomes empty, it is also removed.
-
-## `al setup cloud`
-
-Interactive wizard for configuring cloud infrastructure. Prompts for provider selection and provider-specific fields, writes `[cloud]` to config.toml, pushes credentials, and provisions IAM — all in one shot.
-
-If an existing `[cloud]` config is found, you'll be prompted to tear down the old infrastructure first.
-
-```bash
-al setup cloud -p .
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-## `al teardown cloud`
-
-Deletes per-agent IAM resources (service accounts for Cloud Run, task roles for ECS), stops containers and cleans up credentials (VPS), and removes the `[cloud]` section from config.toml.
-
-```bash
-al teardown cloud -p .
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-## `al run <agent>`
-
-Manually triggers a single agent run. The agent runs once and the process exits when it completes. Useful for testing, debugging, or one-off runs without starting the full scheduler.
-
-```bash
-al run dev -p .
-al run reviewer -p ./my-project
-al run dev -c                 # Run on cloud
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Run on cloud infrastructure |
-
-## `al start`
-
-Starts the scheduler. Runs all agents on their configured schedules and listens for webhooks.
-
-```bash
-al start -p .
-al start -p ./my-project
-al start -c                   # Run on cloud
-al start -w                   # Enable web dashboard
-al start -e                   # VPS deployment: expose gateway publicly
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Run on cloud infrastructure |
-| `-w, --web-ui` | Enable web dashboard (see [Web Dashboard](web-dashboard.md)) |
-| `-e, --expose` | Bind gateway to `0.0.0.0` (public) while keeping local-mode features |
-| `-H, --headless` | Non-interactive mode (no TUI, no credential prompts) |
-
-## `al stat`
-
-Shows status of all discovered agents in the project.
-
-```bash
-al stat -p .
-al stat -c                    # Show cloud status
-```
-
-Displays each agent's schedule, credentials, and webhook configuration.
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Show cloud infrastructure status |
-
-## `al logs <agent>`
-
-View log files for a specific agent.
-
-```bash
-al logs dev -p .
-al logs dev -n 100          # Show last 100 entries
-al logs dev -f              # Follow/tail mode
-al logs dev -d 2025-01-15   # Specific date
-al logs dev -c              # Cloud logs
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-n, --lines <N>` | Number of log entries (default: 50) |
-| `-f, --follow` | Tail mode — watch for new entries |
-| `-d, --date <YYYY-MM-DD>` | View a specific date's log file |
-| `-c, --cloud` | View cloud logs (Cloud Logging / CloudWatch) |
-
-## `al pause [name]`
-
-Pause the scheduler or a single agent. Without a name, pauses the entire scheduler — all cron jobs stop firing. With a name, pauses that agent — its cron job stops firing and webhook events are ignored. In-flight runs continue until they finish. Requires the gateway.
-
-```bash
-al pause                              # Pause the scheduler
-al pause dev                          # Pause a single agent
-al pause reviewer -p ./my-project
-al pause dev -c                       # Pause via cloud gateway
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Forward pause request to the cloud-deployed scheduler's gateway |
-
-## `al resume [name]`
-
-Resume the scheduler or a single agent. Without a name, resumes the entire scheduler. With a name, resumes that agent — its cron job resumes firing and webhooks are accepted again.
-
-```bash
-al resume                             # Resume the scheduler
-al resume dev                         # Resume a single agent
-al resume reviewer -p ./my-project
-al resume dev -c                      # Resume via cloud gateway
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Forward resume request to the cloud-deployed scheduler's gateway |
-
-## `al kill <target>`
-
-Kill an agent (all running instances) or a single instance by ID. Tries the target as an agent name first; if not found, falls back to instance ID. This does **not** pause the agent — if it has a schedule, a new run will start at the next cron tick. To fully stop an agent, pause it first, then kill.
-
-```bash
-al kill dev                           # Kill all instances of an agent
-al kill my-agent-abc123               # Kill a single instance by ID
-al kill dev -p ./my-project
-al kill dev -c                        # Kill cloud tasks directly
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Kill cloud tasks directly via ECS StopTask / Cloud Run cancel APIs |
-
-## `al chat`
-
-Open an interactive console. Without an agent name, opens the project-level console for creating and managing agents. With an agent name, opens an interactive session scoped to that agent's environment — credentials are loaded and injected as environment variables (e.g. `GITHUB_TOKEN`, `GIT_SSH_COMMAND`), and the working directory is set to the agent's directory.
-
-```bash
-al chat                # project-level console
-al chat dev            # interactive session with dev agent's credentials
-al chat dev -c         # same, but credentials from cloud secrets manager
-```
-
-| Option | Description |
-|--------|-------------|
-| `[agent]` | Agent name — loads its credentials and environment |
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-c, --cloud` | Load credentials from cloud secrets manager |
-
-When running in agent mode, the command probes the gateway and warns if it is not reachable:
-
-```
-⚠ No gateway detected at http://localhost:8080. Resource locks, agent calls, and signals are unavailable.
-  Start the scheduler with `al start -g` to enable these features.
-```
-
-The agent's ACTIONS.md is loaded as reference context but is **not** auto-executed — you drive the session interactively.