@desplega.ai/agent-swarm 1.78.1 → 1.79.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.78.1",
+  "version": "1.79.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -104,9 +104,9 @@
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
-    "@mariozechner/pi-agent-core": "^0.73.0",
-    "@mariozechner/pi-ai": "^0.73.0",
-    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@earendil-works/pi-agent-core": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@openai/codex-sdk": "^0.128.0",
     "@opencode-ai/sdk": "^1.14.30",

package/plugin/skills/artifacts/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: artifacts
+description: Serve interactive web content (HTML pages, dashboards, approval flows, static reports, custom Hono apps) to a public URL via localtunnel. Use when the user asks to "create an artifact for X", "host this for me", "make me a tunneled URL", "spin up a web server for X", "publish this report so I can see it", "share this file/page publicly", "expose this dashboard", "give me a live link", or anything that needs a browser-reachable URL pointing at agent-generated content. Wraps the `agent-swarm artifact` CLI plus the `createArtifactServer` SDK; covers static directories, custom Hono apps, daemonization (nohup / PM2), HTTP Basic auth, and the in-page swarm Browser SDK.
+---
+
+# Artifacts — Serving Interactive Web Content
+
+Serve a directory or a Hono app to a public, auth-protected URL via localtunnel. Useful for sharing reports, dashboards, approval flows, or anything else a human needs to look at in a browser.
+
+The CLI is a subcommand of `agent-swarm`. Always invoke as **`agent-swarm artifact <subcommand>`** — there is no top-level `artifact` binary.
+
+## Quick Start
+
+### Static content
+```bash
+# Create your content in a persisted directory
+mkdir -p /workspace/personal/artifacts/my-report
+echo '<h1>My Report</h1>' > /workspace/personal/artifacts/my-report/index.html
+
+# Serve it (auto-assigns a free port, creates tunnel, registers in service registry)
+agent-swarm artifact serve /workspace/personal/artifacts/my-report --name my-report
+# -> Artifact "my-report" live at https://<agentId>-my-report.lt.desplega.ai (port <auto>)
+```
+
+### Programmatic (custom Hono server)
+```typescript
+import { createArtifactServer } from '../artifact-sdk';
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.get('/', (c) => c.html('<h1>Dashboard</h1>'));
+
+const server = createArtifactServer({ name: 'dashboard', app });
+await server.start();
+console.log(`Live at: ${server.url}`);
+```
+
+You can also `agent-swarm artifact serve ./server.ts --name dashboard` if `server.ts` exports a Hono instance as its default export.
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `agent-swarm artifact serve <path> --name <name> [--port <port>] [--no-auth] [--subdomain <sub>]` | Start serving content. `<path>` is a directory (static) or a `.ts`/`.js` file exporting a default Hono app. |
+| `agent-swarm artifact list` | List active artifacts (name, agent, port, URL, status) from the service registry. |
+| `agent-swarm artifact stop <name>` | Stop an artifact: deletes the matching PM2 process and unregisters it from the service registry. See "Known limitation" below for non-PM2 processes. |
+
+Flags accepted by `serve`:
+- `--name <name>` — defaults to the basename of `<path>`. Used for the subdomain and PM2 process name.
+- `--port <port>` — pin to a specific port. Default: auto-assigned ephemeral port.
+- `--no-auth` — disable HTTP Basic auth on the tunnel (DANGEROUS — anyone with the URL can access).
+- `--subdomain <sub>` — override the default `${agentId}-${name}` subdomain.
+
+## Auth & URL Pattern
+
+Tunnels are protected by **HTTP Basic auth** by default:
+- **Username:** `hi` (hardcoded MVP default in `src/artifact-sdk/tunnel.ts`)
+- **Password:** the agent's `API_KEY`
+
+Two equivalent URL forms:
+
+```
+# Plain (browser will prompt for credentials)
+https://<agentId>-<name>.lt.desplega.ai
+
+# Auth-prefilled (works in curl, scripts, and most browsers without a prompt)
+https://hi:<API_KEY>@<agentId>-<name>.lt.desplega.ai
+```
+
+Use `--no-auth` only for genuinely public content. Anyone who learns the subdomain can read it.
+
+## Running it as a daemon
+
+`agent-swarm artifact serve` blocks on a never-resolving promise to stay alive — you cannot inline it in a script that needs to do other work. Pick one of these:
+
+### Option A — `nohup` (quick, throwaway)
+
+Easiest for one-off "host this for the next 10 minutes" cases:
+
+```bash
+mkdir -p /workspace/personal/logs
+nohup agent-swarm artifact serve /workspace/personal/artifacts/my-report \
+  --name my-report \
+  > /workspace/personal/logs/my-report.out 2>&1 &
+echo $! > /workspace/personal/logs/my-report.pid
+
+# Later, kill it manually:
+kill "$(cat /workspace/personal/logs/my-report.pid)"
+```
+
+### Option B — PM2 (recommended for anything you'll come back to)
+
+PM2 gives you auto-restart on crash, a process name, log management, and — crucially — **lets `agent-swarm artifact stop <name>` actually kill it** (see Known limitation below).
+
+```bash
+pm2 start agent-swarm \
+  --name artifact-my-report \
+  -- artifact serve /workspace/personal/artifacts/my-report --name my-report
+
+# Stop it cleanly later:
+agent-swarm artifact stop my-report
+```
+
+The PM2 process name **must** be `artifact-<name>` (matching `--name`) — that's exactly what `artifact stop` looks for.
+
+### Known limitation — `artifact stop` only kills PM2-started processes
+
+Today, `agent-swarm artifact stop <name>` runs `pm2 delete artifact-<name>` and then unregisters the entry from the service registry. If you started the artifact with `nohup` (or `&`, or any non-PM2 launcher), `pm2 delete` silently fails and the actual server keeps running and serving — even though the command prints `Artifact '<name>' stopped.` Tracked as a follow-up bug filed alongside PR #469; until it's fixed:
+
+- Use **PM2** if you want `artifact stop` to actually do its job.
+- For `nohup`/foreground processes, kill the PID yourself (`kill <pid>` or `pkill -f 'artifact serve.*<name>'`) **and then** run `agent-swarm artifact stop <name>` to clear the registry row.
+
+## Multiple Artifacts
+
+Each artifact gets its own port (auto-assigned) and subdomain (`<agentId>-<name>`). You can run several simultaneously — see `examples/multi-artifact.ts`.
+
+## Browser SDK
+
+HTML artifacts can call back into the swarm API via a server-side proxy that injects auth, so browser code never sees the API key:
+
+```html
+<script src="/@swarm/sdk.js"></script>
+<script>
+  const swarm = new SwarmSDK();
+  await swarm.createTask({ task: 'Do something' });
+  const agents = await swarm.getSwarm();
+</script>
+```
+
+### Available SDK Methods
+- `createTask(opts)` — Create a new task
+- `getTasks(filters)` — List tasks with optional filters
+- `getTaskDetails(id)` — Get details for a specific task
+- `storeProgress(taskId, data)` — Update task progress
+- `postMessage(opts)` — Post a message to a channel
+- `readMessages(opts)` — Read messages from a channel
+- `getSwarm()` — Get list of agents
+- `listServices()` — List registered services
+- `slackReply(opts)` — Reply to a Slack thread
+
+## API Proxy
+
+The `/@swarm/api/*` proxy forwards requests to the MCP server with proper authentication headers. This allows browser-side JavaScript to call swarm APIs without exposing credentials.
+
+## Storage
+
+Always store artifact content in persisted directories — the working dir is wiped between sessions:
+- `/workspace/personal/artifacts/` — per-agent, persists across sessions (default)
+- `/workspace/shared/artifacts/` — shared across the swarm
+
+See the `examples/` directory for complete working examples.

package/plugin/skills/artifacts/examples/static-report.sh

@@ -14,4 +14,4 @@ cat > "$ARTIFACT_DIR/index.html" << 'HTML'
 </html>
 HTML
 
-artifact serve "$ARTIFACT_DIR" --name "my-report"
+agent-swarm artifact serve "$ARTIFACT_DIR" --name "my-report"

package/plugin/skills/kv-storage/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: kv-storage
+description: Use the swarm KV store (Redis-like, namespaced) for cross-task / cross-session / per-page state. Auto-scoped to your context (Slack thread / PR / Linear issue / agent / page). Use for counters, cursors, page state. Do NOT use for secrets (`swarm_config`), embedded knowledge (`memory`), or files (`agent-fs`).
+---
+
+# KV Storage
+
+Namespaced key/value store inside the swarm SQLite DB. Auto-scoped to your
+calling context — same string used by `agent_tasks.contextKey`.
+
+> **Capability gate**: the `kv-*` MCP tools are only available when your
+> `CAPABILITIES` includes `kv` (default-on; check `my-agent-info`). The REST
+> endpoints under `/api/kv/*` are always present on the API server.
+
+## When to use KV
+
+| You need… | Use this | Not this |
+|---|---|---|
+| Count something in this Slack thread / PR / Linear issue | **KV** (auto-scoped) | memory / agent-fs |
+| Save a cursor / last-seen state for a recurring schedule | **KV** | swarm_config |
+| Page-internal counter / vote / state across reloads | **KV** via `swarmSdk.kv` | memory |
+| Cross-task state in the same conversation | **KV** (auto-scoped to `task:slack:...`) | parentTaskId only |
+| Secrets, API tokens, OAuth creds | `swarm_config` (encrypted + masked) | **NOT KV** |
+| Cross-session knowledge for this agent ("how do I…") | `memory_search` / `memory-get` | **NOT KV** |
+| Files, binaries, long documents | `agent-fs` | **NOT KV** |
+| Workflow run state | workflow vars (own KV) | **NOT KV** |
+
+Rule of thumb:
+- If a future invocation should *find this without knowing the key* → memory.
+- If a future invocation will *know exactly which key to read* → KV.
+- If it has secrets in it → `swarm_config`.
+- If it's bytes (image, pdf, large doc) → agent-fs.
+
+## Namespacing
+
+Namespace is just a string. It mirrors the `contextKey` schema
+(`src/tasks/context-key.ts`). When you don't pass one, the server resolves it
+from request headers in this order:
+
+1. `X-Page-Id` (only the page-proxy sets this) → `task:page:<id>`
+2. `X-Source-Task-Id` → that task's `contextKey` (e.g. `task:slack:C123:1776...`)
+3. `X-Agent-ID` → `task:agent:<id>` (per-agent scratchpad)
+
+So **inside a session triggered by a Slack thread, KV is automatically scoped
+to that thread** — your sibling tasks (re-runs, retries, follow-ups in the same
+thread) read the same store with no setup. Same for PRs (`task:trackers:github:owner:repo:pr:N`),
+Linear issues (`task:trackers:linear:DES-42`), schedules, workflows.
+
+You can override the namespace explicitly when you need to — see "Explicit
+override" below.
+
+## Quick recipes
+
+### MCP — inside any agent session
+
+```
+kv-set    key="vote-count" value=0 valueType="integer"     # → namespace = task:slack:...
+kv-incr   key="vote-count"                                  # → 1
+kv-incr   key="vote-count" by=5                             # → 6
+kv-get    key="vote-count"                                  # → entry with value=6
+kv-list   prefix="vote-"                                    # → all matching entries
+kv-delete key="vote-count"                                  # → done
+```
+
+`kv-set` defaults to `valueType: 'json'` and JSON-encodes whatever you pass.
+Use `'string'` to skip encoding (good for short tokens, URLs) and
+`'integer'` for counters (required by `kv-incr`).
+
+### REST — humans, scripts, external clients
+
+```bash
+# Header-resolved namespace (recommended for in-session calls)
+curl -H "Authorization: Bearer $API_KEY" \
+     -H "X-Agent-ID: $AGENT_ID" \
+     "$MCP_BASE_URL/api/kv/last-cursor"
+
+# Explicit namespace
+curl -H "Authorization: Bearer $API_KEY" \
+     "$MCP_BASE_URL/api/kv/_/task:trackers:linear:DES-42/last-comment-id"
+
+# PUT a JSON value with a 10-minute TTL
+curl -X PUT -H "Authorization: Bearer $API_KEY" -H "X-Agent-ID: $AGENT_ID" \
+     -H "Content-Type: application/json" \
+     -d '{"value":{"n":42},"valueType":"json","expiresInSec":600}' \
+     "$MCP_BASE_URL/api/kv/snapshot"
+
+# List with a prefix
+curl -H "Authorization: Bearer $API_KEY" -H "X-Agent-ID: $AGENT_ID" \
+     "$MCP_BASE_URL/api/kv?prefix=daily-&limit=50"
+```
+
+### Pages browser SDK — inside an authed page
+
+Page proxy forces the namespace to `task:page:<id>` — no namespace argument is
+exposed. Use it for page-local counters, vote tallies, multi-step form state,
+"remember this number from last refresh" UX:
+
+```js
+// Inside a page's <script> tag
+const count = await swarmSdk.kv.incr('clicks');           // → number-valued entry
+await swarmSdk.kv.set('lastSeen', Date.now());            // → 'json' by default
+const entry = await swarmSdk.kv.get('clicks');            // → { value, valueType, ... } or null
+await swarmSdk.kv.del('clicks');
+const all = await swarmSdk.kv.list({ prefix: 'click', limit: 50 });
+```
+
+Public pages (`authMode: 'public'`) cannot reach `/@swarm/api/*` and so cannot
+use KV. Promote to `authed` or `password` mode if the page needs state.
+
+## Explicit override
+
+Pass `namespace` to read/write somewhere other than your auto-context:
+
+```
+kv-get key="seed" namespace="swarm:experiments"            # ad-hoc namespace
+kv-set key="note" value="hi" namespace="task:agent:OTHER-AGENT-ID"
+# → 403 unless caller is lead
+```
+
+Rules:
+- **Reads:** any authenticated caller can read any namespace.
+- **Writes to `task:agent:<X>`** where X ≠ caller agentId: **403** unless lead.
+- **Writes to `task:page:<X>`** from anywhere except a page-proxy request: **403**.
+- Everything else: writable by any authenticated caller.
+
+## TTL & expiry
+
+Default = **no expiry**. Opt in by passing `expiresInSec`:
+
+```
+kv-set key="lock-token" value="xyz" valueType="string" expiresInSec=60
+```
+
+Expiry is *lazy*: reads on an expired key return null and delete the row;
+`kv-list` filters expired rows out of the SELECT but doesn't delete them
+(keeps cursor pagination stable). No background sweeper — expired rows that
+never get touched stay on disk harmlessly.
+
+## Body cap
+
+2 MiB per value. Over the cap returns 413. If you want to store something
+larger, write it to `agent-fs` and stash the path in KV.
+
+## Gotchas
+
+- **Namespaces ARE contextKey strings.** The same string that lets the swarm
+  find sibling tasks for a PR also indexes KV for that PR.
+- **Reads return `null` for missing AND expired keys** — you can't tell the
+  difference from one call. (If you need to know, list the key.)
+- **INCR collides** if the existing row has `valueType` `'json'` or `'string'`
+  (409 / `KvTypeCollisionError`). Delete and re-create as `'integer'` first,
+  or use a different key.
+- **JSON values round-trip** through `JSON.parse` on read. If you wrote
+  `{a:1}`, you'll get back the object — not the raw string. Use
+  `valueType: 'string'` if you want byte-exact storage.
+- **No CAS / SETNX yet.** Use `kv-incr` for atomic counters; for
+  "claim a token" patterns, set with a short TTL and re-check.
+- **Page SDK has no `namespace` argument.** Pages are always scoped to
+  `task:page:<id>`. Don't try to encode another namespace in the key path —
+  the URL gets rewritten anyway.
+
+## See also
+
+- `src/be/migrations/061_kv_store.sql` — schema (`kv_entries`)
+- `src/http/kv.ts` — REST handler + namespace resolution
+- `src/tools/kv/*` — MCP tool registrars
+- `src/artifact-sdk/browser-sdk.ts` — `swarmSdk.kv` for pages
+- `plugin/skills/pages/SKILL.md` — companion skill for authed pages