@desplega.ai/agent-swarm 1.85.0 → 1.87.0

package/templates/skills/sprite-cli/content.md

@@ -0,0 +1,133 @@
+# sprite-cli
+
+`sprite` is a CLI for [sprites.dev](https://sprites.dev) — ephemeral Linux sandboxes backed by Fly.io firecracker microVMs. Use them when you need to run docker, docker-compose, postgres, redis, or anything else the host swarm container won't let you do.
+
+## When to use this
+
+- You need to test a `docker run …` or `docker compose up …` flow.
+- You need a real postgres / redis / rabbitmq for an integration test.
+- You want to try an `apt-get install` of something you don't want polluting the swarm container.
+- You need to fetch + execute untrusted code (sandboxed network egress is OK; egress to swarm internals is not).
+
+If you can do it directly in the swarm container (lint, type-check, unit test, code search), don't reach for sprite — it's slower and uses paid resources.
+
+## Installation
+
+The CLI is auto-installed at container start for agents whose setup script includes the install snippet (see "Setup script snippet" below).
+
+Manual install:
+```bash
+curl -fsSL https://sprites.dev/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"   # CLI lands in ~/.local/bin
+```
+
+## Authentication
+
+The org token is stored in swarm config as `SPRITES_API_KEY` (global, secret). Setup scripts read `$SPRITES_API_KEY` from the env.
+
+```bash
+sprite auth setup --token "$SPRITES_API_KEY"
+```
+
+Token format is `<org>/<account_id>/<token_id>/<secret>`. The first segment is the org (`desplega`).
+
+## Core commands
+
+| Command | What it does |
+|---|---|
+| `sprite create <name>` | Create a sprite (~1s). |
+| `sprite list` | List your sprites. |
+| `sprite exec -s <name> -- <cmd>` | Run a command in the sprite. |
+| `sprite exec -s <name> -- bash -c "…"` | Run a multi-statement shell snippet. |
+| `sprite console -s <name>` | Open an interactive shell. |
+| `sprite destroy <name> --force` | Tear down. **Always do this when done.** |
+| `sprite proxy <port>` | Forward a remote sprite port to your local machine (rarely useful from within a swarm container; prefer curl from inside the sprite). |
+
+Flags: every command takes `-s <sprite>` (or sets a default via `sprite use`). `-o <org>` overrides the org if you have multiple.
+
+## Sandbox baseline (as of 2026-05-07)
+
+- Ubuntu 25.10 (Questing Quokka), kernel 6.12.x-fly (firecracker microVM)
+- Non-root `sprite` user (uid 1001), passwordless `sudo`
+- No docker, no `/var/run/docker.sock`, no container runtime preinstalled
+- No systemd / init — `service` and `systemctl` won't work; start daemons manually with `sudo <daemon> &` or `nohup`
+- Kernel sysctls are mostly read-only (e.g. `vm.mmap_min_addr` writes fail — these warnings are harmless)
+
+## Recipe: docker inside a sprite
+
+```bash
+sprite create dock
+sprite exec -s dock -- bash -c '
+  set -e
+  sudo apt-get update -qq
+  sudo apt-get install -y docker.io docker-compose-v2
+  sudo dockerd > /tmp/dockerd.log 2>&1 &
+  # wait for daemon
+  for i in {1..15}; do sudo docker ps >/dev/null 2>&1 && break; sleep 1; done
+  sudo docker run --rm hello-world
+'
+```
+
+Notes:
+- `invoke-rc.d` and `policy-rc.d denied` warnings during `apt-get install` are harmless — they come from missing systemd; the binaries install fine.
+- The `sprite` user is **not** in the docker group by default, so prefix every docker call with `sudo`. (You can `sudo usermod -aG docker sprite` and start a new shell, but for one-off scripts `sudo` is simpler.)
+- `dockerd` binds to `/var/run/docker.sock`. If you need it on a TCP port, pass `-H tcp://0.0.0.0:2375` (only inside the sprite — this is not exposed to the public internet).
+
+## Recipe: docker compose
+
+```bash
+sprite exec -s dock -- bash -c '
+  cat > /tmp/compose.yml <<YAML
+services:
+  pg:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_PASSWORD: dev
+    ports: ["5432:5432"]
+YAML
+  sudo docker compose -f /tmp/compose.yml up -d
+  # wait for healthy
+  for i in {1..30}; do sudo docker exec $(sudo docker compose -f /tmp/compose.yml ps -q pg) pg_isready -U postgres >/dev/null 2>&1 && break; sleep 1; done
+  sudo docker exec $(sudo docker compose -f /tmp/compose.yml ps -q pg) psql -U postgres -c "select version();"
+  sudo docker compose -f /tmp/compose.yml down -v
+'
+```
+
+Use `docker compose` (v2 plugin) — `docker-compose` (legacy v1) is not installed.
+
+## Cleanup discipline (mandatory)
+
+Sprites are paid resources. **Always destroy them.** Pattern:
+
+```bash
+sprite create test-$$
+trap "sprite destroy test-$$ --force" EXIT INT TERM
+# … work …
+```
+
+If a script crashes, `sprite list` shows what's still up. Sweep with `sprite list -o desplega` and destroy anything you don't recognize.
+
+## Setup script snippet
+
+Drop this into an agent's setup script to auto-install + auth on container boot:
+
+```bash
+# Sprite CLI — sandboxes for docker/postgres/etc.
+if [ ! -x "$HOME/.local/bin/sprite" ]; then
+  curl -fsSL https://sprites.dev/install.sh | sh -s -- 2>/dev/null || true
+fi
+if [ -n "$SPRITES_API_KEY" ] && [ -x "$HOME/.local/bin/sprite" ]; then
+  "$HOME/.local/bin/sprite" auth setup --token "$SPRITES_API_KEY" 2>/dev/null || true
+fi
+# Make sprite findable in non-login shells
+grep -q '/.local/bin' "$HOME/.bashrc" 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
+```
+
+## Common gotchas
+
+- **PATH:** the installer drops the binary in `~/.local/bin`. Non-login bash shells often miss it. Always export PATH or use the absolute path.
+- **No keyring:** the CLI warns "No system keyring available. Storing secrets unencrypted in ~/.sprites/keyring/". This is expected in a container; the file is mode 600 and only readable by the agent user.
+- **Daemon survival:** `sprite exec` runs in a fresh subshell. A daemon backgrounded with `&` survives the exec call (sprites use a shared init), but if you want to be safe use `nohup`. To stop it, `sprite exec -s … -- sudo pkill <daemon>`.
+- **Port forwarding:** ports inside the sprite are not exposed to your swarm container. Curl from *inside* the sprite (`sprite exec -s … -- curl localhost:5432`) — not from your container.
+- **Don't leak secrets:** treat the sprite as an untrusted host. Don't put production tokens in there.
+

package/templates/skills/turso-interaction/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "turso-interaction",
+  "displayName": "Turso / LibSQL Interaction",
+  "slug": "turso-interaction",
+  "title": "Turso / LibSQL Interaction",
+  "description": "Safely inspect and update LibSQL databases from agent workflows.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["TURSO_DATABASE_URL"],
+  "runAllSeedersCandidate": false,
+  "tags": ["database", "libsql", "turso"]
+}

package/templates/skills/turso-interaction/content.md

@@ -0,0 +1,192 @@
+# Turso Interaction
+
+## The two-token model (READ THIS FIRST)
+
+Turso has two separate auth planes — they do NOT cross over.
+
+| Token type | Where it works | Stored in swarm config as | Signature | Expiry |
+|---|---|---|---|---|
+| **Platform JWT** (management plane) | `api.turso.tech/v1/*` — list orgs, list DBs, mint DB tokens, group/db CRUD; also what the `turso` CLI uses | `TURSO_API_TOKEN` | Clerk-issued RS256 | ~7 days — Clerk rotates it |
+| **DB token** (data plane) | `https://<db-host>/v2/pipeline` — SELECT/INSERT/etc. against a specific DB | `TURSO_DB_TOKEN` (content-state), `TURSO_X_POSTS_DB_TOKEN` (x-posts), etc. | EdDSA | non-expiring (mint with `--expiration none`) or per-token TTL |
+
+Using the **platform JWT against `/v2/pipeline` returns `HTTP 401 "invalid JWT token: can't be decoded with any of the existing keys"`** on every DB — that's by design, not a bug. If you see that error, you reached for the wrong token. Use the DB-specific one.
+
+The platform JWT *can*, however, **mint** a DB token for any DB (see "Mint a DB token via API" below) — that's how you bootstrap access to a DB whose token isn't stored in config.
+
+## Swarm config inventory (current)
+
+Always fetch with `get-config includeSecrets=true`. As of 2026-05-12:
+
+| Key | Plane | Scope | Notes |
+|---|---|---|---|
+| `TURSO_API_TOKEN` | Platform | global | Clerk JWT. Expires ~weekly. When expired, daily-blocker-digest surfaces it and Taras refreshes via Turso dashboard. |
+| `TURSO_DB_TOKEN` | Data (content-state) | global | EdDSA, non-expiring. Used with `TURSO_DB_URL` for `/v2/pipeline`. |
+| `TURSO_DB_URL` | Data (content-state) | global | `https://content-state-desplega.aws-eu-west-1.turso.io` (HTTPS form — required for HTTP API). |
+| `TURSO_X_POSTS_DB_TOKEN` | Data (x-posts) | global | EdDSA, non-expiring. |
+| `TURSO_X_POSTS_DB_URL` | Data (x-posts) | global | `libsql://x-posts-desplega.aws-eu-west-1.turso.io` — **swap `libsql://` → `https://` before hitting `/v2/pipeline`**. |
+
+`dummy-test-db` has no stored DB token. Mint one via the API on demand (recipe below).
+
+## Querying via HTTP API `/v2/pipeline` (the workflow path)
+
+Workflow script nodes hit the DB over HTTP. This is the pattern to use anywhere outside the CLI.
+
+```bash
+curl -s -X POST "$DB_URL/v2/pipeline" \
+  -H "Authorization: Bearer $DB_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "requests": [
+      {"type":"execute","stmt":{"sql":"SELECT name FROM sqlite_master WHERE type='\''table'\''"}},
+      {"type":"close"}
+    ]
+  }'
+```
+
+Response shape (success):
+```json
+{"results":[{"type":"ok","response":{"type":"execute","result":{"cols":[{"name":"name","decltype":"TEXT"}],"rows":[[{"type":"text","value":"posts"}]]}}}, {"type":"ok","response":{"type":"close"}}]}
+```
+
+Always include `{"type":"close"}` as the last request. Use parameterized statements (`stmt.args`) for user-supplied values, not string-built SQL.
+
+**URL form**: `/v2/pipeline` only accepts `https://`. If a config key holds the `libsql://` form, rewrite the scheme:
+```bash
+URL="${TURSO_X_POSTS_DB_URL/libsql:\/\//https:\/\/}"
+```
+
+## Mint a DB token via the platform API
+
+When a DB has no stored token (e.g., `dummy-test-db`), mint one with the platform JWT:
+
+```bash
+DB=dummy-test-db
+DB_TOKEN=$(curl -s -X POST \
+  "https://api.turso.tech/v1/organizations/desplega/databases/$DB/auth/tokens?authorization=read-only" \
+  -H "Authorization: Bearer $TURSO_API_TOKEN" | jq -r '.jwt')
+```
+
+`authorization` can be `read-only` or `full-access`. Add `?expiration=1d` (or `7d`, `never`) to control TTL.
+
+## CLI installation
+
+```bash
+curl -sSfL https://get.tur.so/install.sh | bash
+export PATH="$HOME/.turso:$PATH"
+```
+
+The binary lives at `~/.turso/turso`. PATH must be exported in the same session.
+
+## CLI authentication
+
+The CLI uses the **platform JWT**, not a DB token:
+
+```bash
+turso config set token "$TURSO_API_TOKEN"
+turso org switch desplega
+turso db list   # verify
+```
+
+Do NOT use `turso auth login` — it needs a browser. Always feed the config token in.
+
+If `turso db list` returns 401, the platform JWT has expired — refresh `TURSO_API_TOKEN` in swarm config (Taras owns this; surface via blocker digest).
+
+## CLI database operations
+
+```bash
+turso db create <name>                       # default group, aws-eu-west-1
+turso db list
+turso db show <name>                         # URL, region, size
+turso db shell <name>                        # interactive
+turso db shell <name> "SELECT * FROM t;"     # one-shot
+turso db shell <name> < dump.sql             # pipe file
+turso db destroy <name>                      # !!!
+```
+
+## CLI DB-token generation
+
+```bash
+turso db tokens create <name>                       # default TTL
+turso db tokens create <name> --expiration none     # non-expiring (what we store in config)
+turso db tokens create <name> --read-only           # SELECT-only
+```
+
+After generating, write back to swarm config with `set-config` (mark `isSecret=true`).
+
+## Seeding a Turso DB from local SQLite
+
+```bash
+sqlite3 local.db .dump > dump.sql
+turso db create <name>
+turso db shell <name> < dump.sql
+```
+
+## Connection-URL pattern
+
+```
+libsql://<db-name>-<org>.aws-eu-west-1.turso.io   # for libsql:// clients
+https://<db-name>-<org>.aws-eu-west-1.turso.io    # for HTTP API /v2/pipeline
+```
+
+Same host, two schemes. Some config keys store the libsql form, some the https form — normalize before use.
+
+## Key databases (org = desplega)
+
+| Database | HTTPS URL | Token config key | Used by |
+|---|---|---|---|
+| `content-state` | `https://content-state-desplega.aws-eu-west-1.turso.io` | `TURSO_DB_TOKEN` | Content workflows (`content_history`, `image_prompt_history`, `refresh_history`, `repo_patterns`, `workflow_executions`) |
+| `x-posts` | `https://x-posts-desplega.aws-eu-west-1.turso.io` | `TURSO_X_POSTS_DB_TOKEN` | X/Twitter post tracking + meme cooldown (`posts` table) |
+| `dummy-test-db` | `https://dummy-test-db-desplega.aws-eu-west-1.turso.io` | — (mint via API) | Test fixture (`users` table) |
+
+## Groups
+
+```bash
+turso group list
+turso group create <name> --location <location>
+```
+
+Default group: `default` in `aws-eu-west-1`.
+
+## Local development
+
+```bash
+turso dev    # starts a local LibSQL server
+```
+
+## Full bootstrap from scratch
+
+```bash
+curl -sSfL https://get.tur.so/install.sh | bash
+export PATH="$HOME/.turso:$PATH"
+# Fetch TURSO_API_TOKEN via get-config includeSecrets=true
+turso config set token "$TURSO_API_TOKEN"
+turso org switch desplega
+turso db list
+```
+
+## Health-check recipe (verify all 3 DBs in <30s)
+
+```bash
+# Platform plane
+curl -s -H "Authorization: Bearer $TURSO_API_TOKEN" \
+  https://api.turso.tech/v1/organizations/desplega/databases | jq '[.databases[].Name]'
+
+# Data plane — one /v2/pipeline call per DB
+for pair in "$TURSO_DB_URL|$TURSO_DB_TOKEN" "https://x-posts-desplega.aws-eu-west-1.turso.io|$TURSO_X_POSTS_DB_TOKEN"; do
+  url="${pair%|*}"; tok="${pair#*|}"
+  curl -s -X POST "$url/v2/pipeline" -H "Authorization: Bearer $tok" \
+    -H "Content-Type: application/json" \
+    -d '{"requests":[{"type":"execute","stmt":{"sql":"SELECT 1"}},{"type":"close"}]}' \
+    | jq -c '.results[0]'
+done
+```
+
+If either plane returns 401, treat as a blocker — surface in HEARTBEAT.md, do not retry silently.
+
+## When tokens expire / get rotated
+
+- **`TURSO_API_TOKEN` expired** → CLI breaks, can't mint new DB tokens, `api.turso.tech` returns 401. Existing DB tokens keep working (data plane is independent). Action: Taras rotates via Turso dashboard, updates config.
+- **A DB token expired/revoked** → that specific DB returns 401 on `/v2/pipeline`. Other DBs unaffected. Action: mint a new one (CLI or platform API), update the corresponding config key.
+
+Don't conflate the two failure modes. The blocker-digest writer should name the exact key that needs rotation.
+

package/templates/skills/workflow-iterate/config.json

@@ -0,0 +1,18 @@
+{
+  "kind": "skill",
+  "name": "workflow-iterate",
+  "displayName": "Workflow Iteration",
+  "slug": "workflow-iterate",
+  "title": "Workflow Iteration",
+  "description": "A procedure for improving workflows through small tested revisions.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "tags": [
+    "workflows",
+    "authoring",
+    "qa"
+  ],
+  "must": true
+}