@particle-academy/agent-integrations 0.6.0 → 0.6.2

package/README.md

@@ -158,7 +158,20 @@ For an end-to-end runnable, see the sandbox demo at `/whiteboard-agent` (added i
 
 ## External agent via relay
 
-The relay is host-implemented — this package only defines the JSON envelope. See `docs/relay-protocol.md`.
+External MCP agents (Claude Code, Cursor, Claude Desktop, custom clients)
+reach a browser-hosted `MicroMcpServer` via a relay broker. The relay just
+shuttles JSON-RPC frames — it doesn't run tools or hold state.
+
+**Three ways to wire one up:**
+
+- **`docs/agent-hookable-demos.md`** — full end-to-end workflow (browser →
+  relay → external agent), including a complete drop-in **Laravel 10+**
+  reference implementation (~200 LOC controller + routes + CSRF entry).
+- **`docs/relay-server.md`** — the bundled Node relay (`agent-integrations-relay`
+  bin, `createNodeRelay()` factory, Dockerfile). Use this when your site is
+  not a Laravel/Rails/PHP app and you want a one-command deploy.
+- **`docs/relay-protocol.md`** — the on-the-wire JSON envelope, with notes on
+  the three transports the protocol supports (Reverb, WebRTC, SSE+POST).
 
 Pattern (Reverb):
 

package/docs/agent-hookable-demos.md

@@ -0,0 +1,402 @@
+# Building agent-hookable demos on your site
+
+End-to-end workflow for shipping a public-facing UI surface where visitors can
+hand control to an MCP agent (Claude Code, Cursor, Claude Desktop, custom)
+in real time. The piece you implement varies by site stack; the wire protocol
+doesn't.
+
+## The architecture, plainly
+
+```
+   ┌────────────────────────┐         ┌──────────────────────┐
+   │ Visitor's browser tab  │         │  External agent      │
+   │ ──────────────────     │         │  (Claude Code, etc.) │
+   │  React app             │         └────────┬─────────────┘
+   │  MicroMcpServer        │                  │
+   │  (tools touch the      │                  │ HTTP POST + SSE
+   │   live UI surface)     │                  │
+   └──────────┬─────────────┘                  │
+              │                                │
+              │   SSE stream                   │
+              │ + HTTP POST                    │
+              ▼                                ▼
+        ┌──────────────────────────────────────┐
+        │           Relay broker               │
+        │  ──────────────                      │
+        │  - Holds session→token mapping       │
+        │  - Fans frames between subscribers   │
+        │  - In-memory queues + sliding TTL    │
+        │  - No tool logic, no state           │
+        └──────────────────────────────────────┘
+```
+
+Three pieces. You write zero of them yourself if you follow this guide:
+
+1. **The browser-side MCP server.** Already shipped: `MicroMcpServer` + bridges +
+   `SseRelayTransport` from this package.
+
+2. **The relay broker.** *Pick one.* Either the bundled Node server (see
+   [relay-server.md](./relay-server.md)) or a same-stack reference
+   implementation (see § "Same-stack relays" below — currently includes a
+   complete Laravel controller).
+
+3. **The agent's client.** Out of your control — visitors paste your session
+   URL into whatever MCP client they already use.
+
+## End-user UX
+
+This is what visitors actually experience. Every demo follows the same shape:
+
+1. Visitor opens `https://your-site.example/demos/some-surface`.
+2. Surface is interactive on its own — clicking around works, the in-page
+   `MicroMcpServer` is already running.
+3. Visitor clicks **Start share**.
+4. The page mints a per-session token, registers it with the relay, and shows
+   a copyable share URL.
+5. Visitor pastes the URL into their MCP client (`.mcp.json` for Claude Code,
+   Cursor's MCP settings, etc.). The client connects to the relay.
+6. Agent calls tools → tools mutate the host page's React state → visitor
+   watches the surface change in real time. Optional: agent cursor + tool-call
+   feed render alongside.
+7. **Stop share** tears the session down.
+
+## Browser-side wiring (any site)
+
+```tsx
+import {
+  MicroMcpServer,
+  attachInProcess,
+  attachSseRelay,
+  createSessionDescriptor,
+  buildShareUrl,
+  textResult,
+} from "@particle-academy/agent-integrations";
+
+// Once per page mount:
+const server = new MicroMcpServer({
+  info: { name: "your-demo", version: "0.1.0" },
+});
+
+server.registerTool(
+  { name: "your_tool", description: "...", inputSchema: { /* JSON Schema */ } },
+  async (args) => {
+    // Touch React state, return a CallToolResult
+    return textResult("ok");
+  },
+);
+
+attachInProcess(server); // lets in-page UI also call tools
+
+// When the user clicks "Start share":
+async function startShare(relayBaseUrl: string) {
+  const desc = createSessionDescriptor();
+  await fetch(`${relayBaseUrl}/register`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ session: desc.id, token: desc.token }),
+  });
+  attachSseRelay(server, {
+    baseUrl: relayBaseUrl,
+    sessionId: desc.id,
+    token: desc.token,
+  });
+  const url = buildShareUrl(window.location.origin + relayBaseUrl, desc);
+  // Show `url` to the user in a copy-able UI
+}
+```
+
+The components that bundle this pattern out of the box:
+
+- `<SharedWhiteboard>` (subpath `./components/shared-whiteboard`) — whiteboard
+  + share controls + agent panel + presence cursor in one drop-in.
+- The pa-ux-sandbox repo has reference React components for composer, sheets,
+  flow, code-editor surfaces under `resources/js/react-demos/pages/*Agent*.tsx`.
+
+## Relay broker — pick one
+
+### Option A: bundled Node server (recommended for non-PHP hosts)
+
+`@particle-academy/agent-integrations@^0.6.0` ships a complete Node HTTP
+implementation, exposed three ways: standalone CLI, embeddable factory, and
+Dockerfile. **Full docs:** [relay-server.md](./relay-server.md).
+
+```bash
+npx -p @particle-academy/agent-integrations agent-integrations-relay --port 8787
+```
+
+Point your demo's `relayBaseUrl` at this server's origin and you're done.
+
+### Option B: same-stack reference implementation
+
+If your site already runs Laravel/Rails/Django/etc., implementing the relay
+in the same stack avoids the operational cost of a separate Node process. The
+wire protocol is small (~5 endpoints); a port is ~200 LOC.
+
+A complete **Laravel 10+** reference follows. It's framework-agnostic in
+intent — adapt the route registration and cache binding to your framework's
+conventions; the logic is the same shape everywhere.
+
+#### Laravel reference implementation
+
+**1. Controller** — drop into `app/Http/Controllers/McpRelayController.php`:
+
+```php
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class McpRelayController extends Controller
+{
+    private const TTL_SECONDS = 14400; // 4h — refreshed on every authenticated touch.
+    private const POLL_INTERVAL_MS = 200;
+
+    public function register(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'session' => ['required', 'string', 'regex:/^[A-Za-z0-9_-]{4,64}$/'],
+            'token'   => ['required', 'string', 'min:16', 'max:128'],
+        ]);
+        Cache::put($this->tokenKey($data['session']), hash('sha256', $data['token']), self::TTL_SECONDS);
+        return response()->json(['ok' => true]);
+    }
+
+    public function unregister(Request $request, string $session): JsonResponse
+    {
+        if (! $this->validateToken($session, (string) $request->query('token'))) {
+            return response()->json(['error' => 'invalid_token'], 401);
+        }
+        Cache::forget($this->tokenKey($session));
+        return response()->json(['ok' => true]);
+    }
+
+    public function inbox(Request $request, string $session): JsonResponse
+    {
+        if (! $this->validateToken($session, (string) $request->query('token'))) {
+            return response()->json(['error' => 'invalid_token'], 401);
+        }
+        $payload = $request->getContent();
+        if ($payload === '' || ! str_contains($payload, '"jsonrpc"')) {
+            return response()->json(['error' => 'invalid_frame'], 400);
+        }
+        $this->fanOut($session, 'inbound', $payload);
+        return response()->json(['ok' => true]);
+    }
+
+    public function outbox(Request $request, string $session): JsonResponse
+    {
+        if (! $this->validateToken($session, (string) $request->query('token'))) {
+            return response()->json(['error' => 'invalid_token'], 401);
+        }
+        $payload = $request->getContent();
+        if ($payload === '' || ! str_contains($payload, '"jsonrpc"')) {
+            return response()->json(['error' => 'invalid_frame'], 400);
+        }
+        $this->fanOut($session, 'outbound', $payload);
+        return response()->json(['ok' => true]);
+    }
+
+    public function events(Request $request, string $session): StreamedResponse
+    {
+        $token = (string) $request->query('token');
+        if (! $this->validateToken($session, $token)) {
+            return response()->stream(
+                fn () => print "event: error\ndata: invalid_token\n\n",
+                401,
+                ['content-type' => 'text/event-stream'],
+            );
+        }
+        $direction = $request->query('direction', 'inbound') === 'outbound' ? 'outbound' : 'inbound';
+        $subscriberId = bin2hex(random_bytes(8));
+
+        return response()->stream(function () use ($session, $direction, $subscriberId) {
+            @set_time_limit(0);
+            @ini_set('output_buffering', 'off');
+            @ini_set('zlib.output_compression', '0');
+
+            $key = $this->queueKey($session, $direction, $subscriberId);
+            $subsKey = $this->subscribersKey($session, $direction);
+            $subs = Cache::get($subsKey, []);
+            $subs[$subscriberId] = time();
+            Cache::put($subsKey, $subs, self::TTL_SECONDS);
+
+            if ($direction === 'outbound') {
+                $this->fanOut($session, 'inbound', json_encode([
+                    'jsonrpc' => '2.0',
+                    'method'  => 'notifications/peer_joined',
+                    'params'  => ['subscriberId' => $subscriberId, 'ts' => time() * 1000],
+                ]));
+            }
+
+            echo "retry: 2000\n\n";
+            $this->flush();
+
+            $lastBeat = time();
+            while (! connection_aborted()) {
+                $frames = Cache::pull($key, []);
+                foreach ($frames as $frame) {
+                    echo "event: mcp\ndata: {$frame}\n\n";
+                }
+                if (! empty($frames)) {
+                    $this->flush();
+                }
+                if ((time() - $lastBeat) >= 15) {
+                    echo ": keepalive\n\n";
+                    $this->flush();
+                    $lastBeat = time();
+                }
+                usleep(self::POLL_INTERVAL_MS * 1000);
+            }
+
+            $subs = Cache::get($subsKey, []);
+            unset($subs[$subscriberId]);
+            Cache::put($subsKey, $subs, self::TTL_SECONDS);
+            Cache::forget($key);
+
+            if ($direction === 'outbound') {
+                $this->fanOut($session, 'inbound', json_encode([
+                    'jsonrpc' => '2.0',
+                    'method'  => 'notifications/peer_left',
+                    'params'  => ['subscriberId' => $subscriberId, 'ts' => time() * 1000],
+                ]));
+            }
+        }, 200, [
+            'content-type'    => 'text/event-stream',
+            'cache-control'   => 'no-cache',
+            'x-accel-buffering' => 'no',
+        ]);
+    }
+
+    private function fanOut(string $session, string $direction, string $payload): void
+    {
+        $subsKey = $this->subscribersKey($session, $direction);
+        $subs = Cache::get($subsKey, []);
+        foreach (array_keys($subs) as $subscriberId) {
+            $key = $this->queueKey($session, $direction, $subscriberId);
+            $existing = Cache::get($key, []);
+            $existing[] = $payload;
+            Cache::put($key, $existing, self::TTL_SECONDS);
+        }
+        Cache::put($subsKey, $subs, self::TTL_SECONDS);
+    }
+
+    private function validateToken(string $session, string $token): bool
+    {
+        if ($session === '' || $token === '') return false;
+        $key = $this->tokenKey($session);
+        $stored = Cache::get($key);
+        if ($stored === null) return false;
+        if (! hash_equals((string) $stored, hash('sha256', $token))) return false;
+        Cache::put($key, $stored, self::TTL_SECONDS);
+        return true;
+    }
+
+    private function tokenKey(string $session): string
+    {
+        return "mcp-relay:token:{$session}";
+    }
+
+    private function subscribersKey(string $session, string $direction): string
+    {
+        return "mcp-relay:subs:{$session}:{$direction}";
+    }
+
+    private function queueKey(string $session, string $direction, string $subscriberId): string
+    {
+        return "mcp-relay:queue:{$session}:{$direction}:{$subscriberId}";
+    }
+
+    private function flush(): void
+    {
+        if (function_exists('ob_get_level') && ob_get_level() > 0) {
+            @ob_flush();
+        }
+        @flush();
+    }
+}
+```
+
+**2. Routes** — `routes/web.php`:
+
+```php
+Route::post('/mcp-relay/register',              [McpRelayController::class, 'register']);
+Route::post('/mcp-relay/{session}/unregister',  [McpRelayController::class, 'unregister']);
+Route::post('/mcp-relay/{session}/inbox',       [McpRelayController::class, 'inbox']);
+Route::post('/mcp-relay/{session}/outbox',      [McpRelayController::class, 'outbox']);
+Route::get ('/mcp-relay/{session}/events',      [McpRelayController::class, 'events']);
+```
+
+**3. CSRF exemption** — `bootstrap/app.php` (Laravel 11+):
+
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->validateCsrfTokens(except: [
+        'mcp-relay/*',
+    ]);
+})
+```
+
+(Laravel 10: add to `VerifyCsrfToken::$except` in `app/Http/Middleware/`.)
+
+**4. Operational notes**
+
+- Storage uses the default cache driver — `file` works for single-server
+  setups, but for any production deploy use `redis` so the broker survives
+  PHP-FPM worker recycles and load-balances correctly across processes.
+- The SSE `events()` action holds a long-lived HTTP connection. Confirm your
+  proxy / PHP-FPM timeouts allow this:
+  - Nginx: `proxy_read_timeout` ≥ 6h, `proxy_buffering off` for SSE
+  - PHP-FPM: `request_terminate_timeout = 0` or `>= 4h`
+- The 15-second keepalive ping (`: keepalive\n\n`) prevents most proxies from
+  killing idle connections. Validate after deploy.
+- This implementation handles ~50 concurrent sessions on a single Laravel
+  worker. For more, run multiple workers behind a load balancer with a
+  redis cache backend.
+
+### Option C: implement in another stack
+
+Same protocol, same five endpoints, same wire format. Reference the Laravel
+controller above and the [relay-protocol.md](./relay-protocol.md) wire spec.
+For Rails: `ActionController::Live` for SSE + `Rails.cache` for storage. For
+Django: `StreamingHttpResponse` + `django.core.cache`. For Express/Fastify:
+just use the bundled `createNodeRelay()` factory from this package.
+
+## Choosing between A and B
+
+| You want… | Pick |
+|---|---|
+| Add a couple of demos to an existing Laravel app | **B (Laravel)** — no new infrastructure |
+| Demo site is static / no backend yet | **A (Node)** — `agent-integrations-relay` container |
+| Multiple Fancy UI demos across multiple sites | **A**, deployed once at a central origin |
+| Already running Rails/Django/etc. | **C** — port the Laravel reference |
+| Edge / serverless | **A** with `createNodeRelay` adapted to your runtime, or bring your own `RelayBroker` + `Store` |
+
+The browser-side code doesn't change between options. The relay broker URL is
+the only difference.
+
+## Worked example — the particle.academy site
+
+The marketing site for this kit hosts two agent-hookable demos at
+`/ui/demos/composer` and `/ui/demos/agent-presence`. Stack: Laravel 12 +
+Livewire + Tailwind v4, plus a React island for the demo surfaces. The relay
+runs in-app via Option B (the Laravel reference above lives at
+`app/Http/Controllers/McpRelayController.php` in the
+[Particle-Academy/website](https://github.com/Particle-Academy/website) repo).
+
+The pattern there matches this doc exactly: a controlled React component
+mounts via `data-fancy-demo` placeholders; `MicroMcpServer` registers
+composer/whiteboard tools that touch local state; clicking *Start share*
+hits the relay's `/register` and opens an SSE subscription. Visitors paste
+the resulting URL into their MCP client and the demo becomes agent-driven.
+
+## See also
+
+- [relay-protocol.md](./relay-protocol.md) — the wire format, including the
+  three transports the protocol supports (Reverb, WebRTC, SSE+POST)
+- [relay-server.md](./relay-server.md) — the bundled Node relay
+- [`SharedWhiteboard`](../src/components/SharedWhiteboard/SharedWhiteboard.tsx) —
+  source for a fully-composed agent-hookable surface, useful as a template

package/docs/relay-server.md

@@ -75,12 +75,232 @@ docker build -t agent-integrations-relay .
 docker run -p 8787:8787 agent-integrations-relay
 ```
 
-Deploy targets that just want a container:
+## Deployment recipes
+
+The relay is a tiny stateless Node HTTP server. Any platform that can host a
+long-running Node process works. Pick whichever matches the rest of your
+infrastructure — verification steps are at the bottom of each recipe.
+
+### Laravel Forge (Node site or daemon)
+
+Forge supports both Node sites and standalone daemons, either fits.
+
+**Option A — Forge "Static" site running Node:**
+
+1. In Forge, create a new site on your server. Set **Project Type** to
+   *Static / Node*. Web directory: `/public` (unused — we'll serve from the
+   relay port).
+2. Add a domain (e.g. `relay.particle.academy`) and an LE SSL cert.
+3. Connect the site to a deploy repo — point it at this package's git URL or
+   a thin wrapper repo containing just:
+   ```
+   .
+   ├── package.json   (just "scripts": { "start": "agent-integrations-relay --port 8787" }
+   │                   and "dependencies": { "@particle-academy/agent-integrations": "^0.6.1" })
+   └── README.md
+   ```
+4. Deploy script:
+   ```bash
+   cd $FORGE_SITE_PATH
+   npm install --omit=dev
+   ```
+5. In **Daemons** (sidebar), add:
+   - **Command:** `npx agent-integrations-relay --port 8787 --cors https://your-site.example`
+   - **Directory:** `$FORGE_SITE_PATH`
+   - **User:** `forge`
+   Daemon auto-restarts on crash.
+6. In the site's **Nginx config**, replace the upstream block with:
+   ```nginx
+   location / {
+       proxy_pass http://127.0.0.1:8787;
+       proxy_http_version 1.1;
+       proxy_set_header Host $host;
+       proxy_set_header X-Real-IP $remote_addr;
+
+       # SSE needs these — otherwise the stream is buffered and never reaches the agent.
+       proxy_buffering off;
+       proxy_cache off;
+       proxy_read_timeout 6h;
+       proxy_send_timeout 6h;
+       chunked_transfer_encoding on;
+   }
+   ```
+7. Restart Nginx via the Forge UI button or `sudo nginx -s reload`.
+
+**Option B — daemon alongside an existing Laravel app on the same server:**
+
+If you'd rather not give it its own subdomain, run it as a Forge daemon on
+an internal port and proxy from an existing site's Nginx config:
+
+```nginx
+# Inside an existing Forge Laravel site
+location /mcp-relay/ {
+    proxy_pass http://127.0.0.1:8787/;
+    proxy_http_version 1.1;
+    proxy_buffering off;
+    proxy_read_timeout 6h;
+    chunked_transfer_encoding on;
+}
+```
+
+**Verify:**
+
+```bash
+curl https://relay.particle.academy/                  # → {"ok":true,"service":"…"}
+curl -X POST -H 'content-type: application/json' \
+  -d '{"session":"smoke-001","token":"abcdef0123456789abcdef0123456789"}' \
+  https://relay.particle.academy/register             # → {"ok":true}
+```
+
+### Fly.io
+
+```bash
+git clone https://github.com/Particle-Academy/agent-integrations
+cd agent-integrations
+npm install && npm run build
+docker build -t agent-integrations-relay .
+
+# Init + deploy (first time only):
+fly launch \
+  --name relay-particle-academy \
+  --no-deploy \
+  --copy-config \
+  --image agent-integrations-relay \
+  --internal-port 8787 \
+  --region iad
+fly deploy
+```
+
+Public URL prints at the end, e.g. `https://relay-particle-academy.fly.dev`.
+
+### Railway
+
+```bash
+# Commit the Dockerfile to your relay repo, then:
+railway login
+railway init
+railway up
+```
+
+In the Railway dashboard, enable a public domain on the service; copy the
+generated `*.up.railway.app` URL.
+
+### Render
+
+1. New → **Web Service**
+2. Connect a git repo containing the Dockerfile
+3. Runtime: **Docker**
+4. Port: `8787`
+5. Add `Header: Cache-Control: no-cache` on the service so Render's CDN
+   doesn't buffer SSE
+
+### Google Cloud Run
+
+```bash
+gcloud builds submit --tag gcr.io/$PROJECT/agent-integrations-relay
+gcloud run deploy agent-integrations-relay \
+  --image gcr.io/$PROJECT/agent-integrations-relay \
+  --port 8787 \
+  --allow-unauthenticated \
+  --min-instances 1 \
+  --timeout 3600
+```
+
+Cloud Run's default request timeout is 60s — bump it via `--timeout 3600`
+(max 3600s on managed Cloud Run) so SSE streams aren't cut off. For longer
+sessions, use **Cloud Run for Anthos / GKE** or a Compute Engine VM.
+
+### Bare server (systemd)
+
+If the relay is going on a VM you already own, `systemd`:
+
+```ini
+# /etc/systemd/system/mcp-relay.service
+[Unit]
+Description=MCP relay broker
+After=network.target
+
+[Service]
+Type=simple
+User=relay
+WorkingDirectory=/opt/relay
+ExecStart=/usr/bin/npx agent-integrations-relay --port 8787 --cors https://your-site.example
+Restart=on-failure
+RestartSec=5
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcp-relay
+sudo systemctl status mcp-relay
+```
+
+Front with Nginx using the same SSE-friendly proxy block as the Forge
+recipe.
+
+## Smoke testing any deploy
+
+After you have a public URL, regardless of host:
+
+```bash
+RELAY=https://relay.example.com
+
+# 1. Health
+curl $RELAY/
+
+# 2. Register a session
+curl -X POST -H 'content-type: application/json' \
+  -d '{"session":"smoke-001","token":"abcdef0123456789abcdef0123456789"}' \
+  $RELAY/register
+
+# 3. POST a frame
+curl -X POST -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
+  "$RELAY/smoke-001/inbox?token=abcdef0123456789abcdef0123456789"
+
+# 4. SSE stream — should hang open + emit keepalive comments every 15s
+curl -N "$RELAY/smoke-001/events?token=abcdef0123456789abcdef0123456789&direction=inbound"
+```
+
+If `curl -N` returns immediately, your proxy is buffering. Re-check
+`proxy_buffering off` (Nginx) or the equivalent on your edge.
+
+## Hooking into your demo site
+
+Set the relay base URL in your demo's environment. For a Laravel host (like
+particle.academy):
+
+```env
+# .env on the demo site
+MCP_RELAY_BASE_URL=https://relay.particle.academy
+```
+
+Bind it to a config and read it from your Livewire/Blade layer:
+
+```php
+// config/mcp.php
+return [
+    'relay_base_url' => env('MCP_RELAY_BASE_URL', ''),
+];
+```
+
+Then pass it to the React mount placeholder:
+
+```blade
+<div
+    data-fancy-demo="composer"
+    data-relay-base="{{ config('mcp.relay_base_url') }}"
+></div>
+```
 
-- **Fly.io:** `fly launch --image agent-integrations-relay --internal-port 8787`
-- **Railway:** `railway up` after committing the Dockerfile
-- **Render:** point a Web Service at the Dockerfile, expose 8787
-- **Cloud Run:** `gcloud run deploy --image agent-integrations-relay --port 8787 --allow-unauthenticated`
+The React side reads `node.dataset.relayBase`, passes it to the demo
+component, and the component uses it for `attachSseRelay({ baseUrl: ... })`.
+See [agent-hookable-demos.md](./agent-hookable-demos.md) for the
+end-to-end pattern.
 
 ## Wire protocol
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/agent-integrations",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "MCP-driven agent presence in collab sessions: per-session micro-MCP server, pluggable bridges to fancy-* packages, and agent UX components (panel + on-canvas cursor).",
   "repository": {
     "type": "git",