@desplega.ai/agent-swarm 1.78.1 → 1.79.0

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/pages/SKILL.md

@@ -0,0 +1,274 @@
+# Pages — DB-backed Static Artifacts
+
+DB-backed static content (HTML or JSON) served by the API directly. Cheap,
+versioned, share-able by URL. The lighter-weight cousin of `artifacts` —
+no PM2, no tunnels, no port allocation, no `services` registry row.
+
+> **Capability gate**: the `create_page` MCP tool is only available when the
+> agent's `CAPABILITIES` env var includes `pages`
+> (e.g. `CAPABILITIES=core,task-pool,pages`). If the tool is missing from
+> your MCP list, this is why.
+
+## When to use Pages vs Artifacts
+
+| You need… | Use |
+|---|---|
+| A static HTML report / dashboard | **Pages** |
+| A JSON status payload + a few buttons that call swarm APIs | **Pages** (`contentType: 'application/json'`) |
+| To share an output via a URL with no server logic | **Pages** |
+| Custom routes, websockets, server-side logic | **Artifacts** (`plugin/skills/artifacts/skill.md`) |
+| File uploads or per-request computation | **Artifacts** |
+
+Rule of thumb: if the content is a snapshot (you can write the full HTML/JSON
+in a single call), use pages. If the content is a *running program*, use
+artifacts.
+
+## Quick Start
+
+### Public HTML report
+```jsonc
+// Tool call: create_page
+{
+  "title": "Q2 Status Report",
+  "description": "Roll-up of in-flight tasks across the swarm",
+  "contentType": "text/html",
+  "authMode": "public",
+  "body": "<!doctype html><html><body><h1>Q2 Status</h1>...</body></html>"
+}
+// → { id, version: 1, app_url, api_url }
+```
+
+Share `app_url` (the SPA route) for the general case; share `api_url` for a
+no-SPA-required direct link.
+
+### Authed JSON dashboard
+```jsonc
+// Tool call: create_page
+{
+  "title": "Agent Inbox",
+  "description": "Live tasks for me",
+  "contentType": "application/json",
+  "authMode": "authed",
+  "body": "{\"$schema\":\"...\",\"type\":\"page\",\"children\":[{\"type\":\"text\",\"value\":\"Hello\"},{\"type\":\"button\",\"label\":\"Refresh\",\"action\":{\"swarm.call\":{\"method\":\"GET\",\"endpoint\":\"/api/tasks?status=in_progress\"}}}]}"
+}
+// → { id, version: 1, app_url, api_url }
+```
+
+`authed` pages require a viewer to be signed in to the SPA (or to mint a
+page-session cookie via the launch endpoint) before the page can call the
+swarm API.
+
+## Auth Modes
+
+| Mode | URL behavior | When to use |
+|---|---|---|
+| `public` | No gate. Anyone with the URL sees the content. Browser SDK calls **return 401** (no viewer identity → no API access). | Static reports, marketing pages, anything safe to share externally. |
+| `authed` | SPA `app_url` works for any signed-in dashboard user. Direct `api_url` requires a `page_session` cookie (mint via `POST /api/pages/:id/launch`). Browser SDK calls run as the viewing user. | Per-team dashboards, JSON pages with action buttons. |
+| `password` | `?key=<password>` or HTTP Basic on `/p/:id` unlocks. Once unlocked, behaves like `authed` (cookie minted, SDK calls run as viewer's identity). | Pages shared with non-swarm users (clients, contractors). |
+
+> Password unlock has to happen on `/p/:id` directly (the API origin) because
+> the password isn't sent to the SPA. Sharing an `app_url` for a `password`
+> page works but the SPA will redirect the iframe through `/p/:id` for the
+> Basic prompt.
+
+## URL Shapes
+
+| URL | Shape | Notes |
+|---|---|---|
+| `app_url` | `${APP_URL}/pages/:id` | SPA route. Renders HTML in a sandboxed iframe, JSON via `@json-render/react`. Default share target. |
+| `app_url` (full mode) | `${APP_URL}/pages/:id?mode=full` | Same SPA route, maximized — hides the SPA sidebar/header so the page body gets the full viewport. Slim header with title + Exit-Full button. Useful for embeds + standalone dashboards. |
+| `api_url` | `${MCP_BASE_URL}/p/:id` | Direct API render. HTML inlines and serves; JSON 302-redirects to `app_url`. Useful for no-SPA-required links. |
+
+`${APP_URL}` is the SPA origin (e.g. `https://app.agent-swarm.dev` in prod).
+`${MCP_BASE_URL}` is the API origin (e.g. `https://api.desplega.agent-swarm.dev`
+in prod). Both are surfaced as env vars to your agent — never hardcode hosts;
+read them from `process.env`.
+
+**Default**: share `app_url`. Append `?mode=full` when the recipient should
+see ONLY the page (no surrounding swarm chrome). Use `api_url` only when you
+specifically need a link that bypasses the SPA (e.g. embedding in Slack,
+where the unfurl preview only follows the API origin).
+
+## Versioning
+
+Every overwrite (update via `update_page` or `PUT /api/pages/:id`) snapshots
+the **pre-update** state into `page_versions` and writes the new state to the
+parent row. The wire `version` field is a monotonically-increasing
+"edit counter" — version 1 is the initial create.
+
+| Operation | Endpoint | Returns |
+|---|---|---|
+| List versions | `GET /api/pages/:id/versions` | `{ versions: PageVersion[] }` newest first |
+| Read a version | `GET /api/pages/:id/versions/:version` | Single snapshot |
+
+Snapshots are full body copies — keep this in mind for large pages (the
+per-version body cap is 5 MiB).
+
+## Browser SDK
+
+Every HTML page automatically gets `window.SwarmSDK` (the class) and
+`window.swarmSdk` (a ready-to-use singleton) injected. The SDK routes through
+the `/@swarm/api/*` proxy, which resolves the `page_session` cookie to a user
+identity and forwards with proper auth headers server-side — your page never
+sees or handles tokens.
+
+The SDK is **domain-grouped**. Each domain exposes idiomatic CRUD-ish methods
+that map 1:1 to the public REST API documented at
+[**docs.agent-swarm.dev/docs/api-reference**](https://docs.agent-swarm.dev/docs/api-reference).
+
+| Domain | Methods | Maps to |
+|---|---|---|
+| `swarmSdk.tasks` | `create(body)`, `list(filters?)`, `get(id)`, `storeProgress(id, data)` | `/api/tasks*` |
+| `swarmSdk.agents` | `list()`, `get(id)` | `/api/agents*` |
+| `swarmSdk.events` | `create(body)`, `list(filters?)`, `batch(body)`, `counts(filters?)` | `/api/events*` |
+| `swarmSdk.memory` | `search(body)`, `list(filters?)`, `get(id)`, `rate(body)` | `/api/memory*` |
+| `swarmSdk.repos` | `list()`, `get(id)`, `create(body)`, `update(id, body)`, `delete(id)` | `/api/repos*` |
+| `swarmSdk.schedules` | `list()`, `get(id)`, `create(body)`, `update(id, body)`, `delete(id)`, `run(id)` | `/api/schedules*` |
+| `swarmSdk.approvalRequests` | `list(filters?)`, `get(id)`, `create(body)`, `respond(id, body)` | `/api/approval-requests*` |
+
+Inline usage:
+
+```html
+<script>
+  // Singleton is ready immediately — no `new SwarmSDK()` needed.
+  const tasks = await window.swarmSdk.tasks.list({ status: 'in_progress' });
+  const agents = await window.swarmSdk.agents.list();
+
+  // Create an event from a button click
+  document.querySelector('#log-btn').onclick = async () => {
+    await window.swarmSdk.events.create({ name: 'page.button.clicked', payload: { at: Date.now() } });
+  };
+
+  // Approve / reject an approval request
+  await window.swarmSdk.approvalRequests.respond(reqId, { decision: 'approved' });
+</script>
+```
+
+Every method returns the parsed JSON response. Errors throw with `.status`
+and `.response` attached to the `Error` object so callers can branch on the
+HTTP status.
+
+> **`public` pages cannot call authed endpoints.** No cookie is minted on a
+> public page load → SDK calls 401. If your page needs to call swarm APIs,
+> use `authed` (or `password`).
+
+### Full signature
+
+This is the entire surface — copy it into your page if you want autocomplete
+hints in an editor. The runtime version is auto-injected; you don't need to
+include this in the page source.
+
+```js
+class SwarmSDK {
+  tasks: {
+    create(body)                       // POST /api/tasks
+    list(filters?)                     // GET  /api/tasks
+    get(id)                            // GET  /api/tasks/:id
+    storeProgress(id, data)            // POST /api/tasks/:id/progress
+  }
+  agents: {
+    list()                             // GET  /api/agents
+    get(id)                            // GET  /api/agents/:id
+  }
+  events: {
+    create(body)                       // POST /api/events
+    list(filters?)                     // GET  /api/events
+    batch(body)                        // POST /api/events/batch
+    counts(filters?)                   // GET  /api/events/counts
+  }
+  memory: {
+    search(body)                       // POST /api/memory/search
+    list(filters?)                     // GET  /api/memory/list
+    get(id)                            // GET  /api/memory/:id
+    rate(body)                         // POST /api/memory/rate
+  }
+  repos: {
+    list()                             // GET  /api/repos
+    get(id)                            // GET  /api/repos/:id
+    create(body)                       // POST /api/repos
+    update(id, body)                   // PUT  /api/repos/:id
+    delete(id)                         // DELETE /api/repos/:id
+  }
+  schedules: {
+    list()                             // GET  /api/schedules
+    get(id)                            // GET  /api/schedules/:id
+    create(body)                       // POST /api/schedules
+    update(id, body)                   // PUT  /api/schedules/:id
+    delete(id)                         // DELETE /api/schedules/:id
+    run(id)                            // POST /api/schedules/:id/run
+  }
+  approvalRequests: {
+    list(filters?)                     // GET  /api/approval-requests
+    get(id)                            // GET  /api/approval-requests/:id
+    create(body)                       // POST /api/approval-requests
+    respond(id, body)                  // POST /api/approval-requests/:id/respond
+  }
+}
+```
+
+For the full list of fields each endpoint accepts/returns, see
+[**docs.agent-swarm.dev/docs/api-reference**](https://docs.agent-swarm.dev/docs/api-reference).
+The SDK is a thin domain wrapper — anything documented there is reachable.
+
+## JSON Renderer
+
+JSON pages are rendered via [`@json-render/react`](https://json-render.dev)
+with a custom `swarm.call` action handler. Action shape:
+
+```jsonc
+{
+  "type": "button",
+  "label": "Reassign",
+  "action": {
+    "swarm.call": {
+      "method": "POST",
+      "endpoint": "/api/tasks/abc/reassign",
+      "body": { "agentId": "xyz" }
+    }
+  }
+}
+```
+
+`swarm.call` dispatches through the SPA's bearer (for `app_url` loads) or
+the page-session cookie (for direct `api_url` loads). The endpoint must be
+a valid swarm API path — there is no allowlist, but the viewer's identity
+bounds what the call can do.
+
+See the `@json-render/core` docs for the supported node types (`text`,
+`button`, `input`, `card`, etc.).
+
+## Security & Blast Radius
+
+- Declared actions on `authed` / `password` pages run with the **viewer's**
+  identity, not the page author's. A button that says "Delete all tasks"
+  will delete the viewer's tasks if the viewer clicks it.
+- Treat agent-generated HTML / JSON like trusted code — the agent already
+  has equivalent MCP access, so a malicious page is no worse than a
+  malicious tool call. But: don't ship pages to **external** users (via
+  `password`) without reviewing the body first.
+- HTML pages render inside a sandboxed iframe with
+  `sandbox="allow-scripts allow-forms allow-same-origin"`. This limits
+  some attack surface (no top-level navigation, no pointer-lock) but the
+  page still has full access to the SwarmSDK if cookies are present.
+- All page bodies pass through `scrubSecrets` at the egress boundary
+  (`/p/:id`, `/p/:id.json`, listing endpoint) — accidental secrets in
+  the body get masked at serve time, not at write time. Don't rely on
+  scrubbing as a security boundary — keep secrets out of bodies.
+
+## Limits
+
+- **Body size**: 5 MiB per version (HTML or JSON). Bumping requires careful
+  thought about SQLite write-amplification — full bodies are snapshotted on
+  every update.
+- **TTL**: none. Pages persist until explicitly deleted via `DELETE
+  /api/pages/:id` (or the SPA listing UI when it gains a delete affordance).
+- **Per-agent quota**: none in v1. Be considerate.
+- **Slug uniqueness**: scoped to `(agentId, slug)`. Two agents can both
+  have a `status-report` page without colliding.
+
+## See Also
+
+- `plugin/skills/artifacts/skill.md` — full custom Hono apps with PM2 +
+  tunneled subdomain. Use for interactive servers, not static content.
+- `runbooks/secret-scrubbing.md` — egress scrubbing details.
+- SPA listing: `${UI_URL}/pages`.

package/src/artifact-sdk/browser-sdk.ts

@@ -1,29 +1,114 @@
-// This is a string template that gets served as JavaScript to the browser
+// Browser-side Swarm SDK injected into agent-served HTML pages.
+//
+// Exposes a domain-grouped API on `window.SwarmSDK` (class) and a ready-to-use
+// singleton `window.swarmSdk`. All calls route through the `/@swarm/api/*`
+// proxy, which strips the page-session cookie and forwards to `/api/*` with
+// a server-side bearer + agent-id. From the page's perspective, the SDK is
+// authenticated automatically — no token handling on the client.
+//
+// Domains exposed:
+//   - tasks            create, list, get, storeProgress
+//   - agents           list, get
+//   - events           create, list, batch, counts
+//   - memory           search, list, get, rate
+//   - repos            list, get, create, update, delete
+//   - schedules        list, get, create, update, delete, run
+//   - approvalRequests list, get, create, respond
+//
+// Full HTTP API reference: https://docs.agent-swarm.dev/docs/api-reference
 export const BROWSER_SDK_JS = `
 class SwarmSDK {
   constructor() {
-    this._configPromise = fetch('/@swarm/config').then(r => r.json());
-  }
+    this._configPromise = fetch('/@swarm/config').then(r => r.json()).catch(() => null);
 
-  async createTask(opts) { return this._post('/@swarm/api/tasks', opts); }
-  async getTasks(filters) { return this._get('/@swarm/api/tasks?' + new URLSearchParams(filters)); }
-  async getTaskDetails(id) { return this._get('/@swarm/api/tasks/' + id); }
-  async storeProgress(taskId, data) { return this._post('/@swarm/api/tasks/' + taskId + '/progress', data); }
-  async postMessage(opts) { return this._post('/@swarm/api/messages', opts); }
-  async readMessages(opts) { return this._get('/@swarm/api/messages?' + new URLSearchParams(opts)); }
-  async getSwarm() { return this._get('/@swarm/api/agents'); }
-  async listServices() { return this._get('/@swarm/api/services'); }
-  async slackReply(opts) { return this._post('/@swarm/api/slack/reply', opts); }
-
-  async _post(url, body) {
-    const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
-    return res.json();
-  }
-  async _get(url) {
-    const res = await fetch(url);
-    return res.json();
+    const base = '/@swarm/api';
+    const call = async (method, path, body) => {
+      const init = { method };
+      if (body !== undefined) {
+        init.headers = { 'Content-Type': 'application/json' };
+        init.body = JSON.stringify(body);
+      }
+      const res = await fetch(base + path, init);
+      const text = await res.text();
+      let parsed = null;
+      if (text) {
+        try { parsed = JSON.parse(text); } catch { parsed = text; }
+      }
+      if (!res.ok) {
+        const err = new Error('SwarmSDK ' + method + ' ' + path + ': ' + res.status);
+        err.status = res.status;
+        err.response = parsed;
+        throw err;
+      }
+      return parsed;
+    };
+    const qs = (obj) => {
+      if (!obj) return '';
+      const p = new URLSearchParams();
+      for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined || v === null) continue;
+        p.set(k, String(v));
+      }
+      const s = p.toString();
+      return s ? '?' + s : '';
+    };
+    const enc = encodeURIComponent;
+
+    this.tasks = {
+      create: (body) => call('POST', '/tasks', body),
+      list: (filters) => call('GET', '/tasks' + qs(filters)),
+      get: (id) => call('GET', '/tasks/' + enc(id)),
+      storeProgress: (id, data) => call('POST', '/tasks/' + enc(id) + '/progress', data),
+    };
+
+    this.agents = {
+      list: () => call('GET', '/agents'),
+      get: (id) => call('GET', '/agents/' + enc(id)),
+    };
+
+    this.events = {
+      create: (body) => call('POST', '/events', body),
+      list: (filters) => call('GET', '/events' + qs(filters)),
+      batch: (body) => call('POST', '/events/batch', body),
+      counts: (filters) => call('GET', '/events/counts' + qs(filters)),
+    };
+
+    this.memory = {
+      search: (body) => call('POST', '/memory/search', body),
+      list: (filters) => call('GET', '/memory/list' + qs(filters)),
+      get: (id) => call('GET', '/memory/' + enc(id)),
+      rate: (body) => call('POST', '/memory/rate', body),
+    };
+
+    this.repos = {
+      list: () => call('GET', '/repos'),
+      get: (id) => call('GET', '/repos/' + enc(id)),
+      create: (body) => call('POST', '/repos', body),
+      update: (id, body) => call('PUT', '/repos/' + enc(id), body),
+      delete: (id) => call('DELETE', '/repos/' + enc(id)),
+    };
+
+    this.schedules = {
+      list: () => call('GET', '/schedules'),
+      get: (id) => call('GET', '/schedules/' + enc(id)),
+      create: (body) => call('POST', '/schedules', body),
+      update: (id, body) => call('PUT', '/schedules/' + enc(id), body),
+      delete: (id) => call('DELETE', '/schedules/' + enc(id)),
+      run: (id) => call('POST', '/schedules/' + enc(id) + '/run'),
+    };
+
+    this.approvalRequests = {
+      list: (filters) => call('GET', '/approval-requests' + qs(filters)),
+      get: (id) => call('GET', '/approval-requests/' + enc(id)),
+      create: (body) => call('POST', '/approval-requests', body),
+      respond: (id, body) => call('POST', '/approval-requests/' + enc(id) + '/respond', body),
+    };
   }
 }
 
+// Expose BOTH the class (for \`new SwarmSDK()\`) AND a ready-to-use singleton
+// on \`window.swarmSdk\` so pages can call e.g. \`window.swarmSdk.agents.list()\`
+// directly without instantiating.
 window.SwarmSDK = SwarmSDK;
+window.swarmSdk = new SwarmSDK();
 `;