pilotswarm 0.5.11 → 0.5.13

package/README.md

@@ -7,22 +7,236 @@ surface of a [PilotSwarm](https://github.com/affandar/pilotswarm) deployment:
 |---|---|
 | `pilotswarm` | Terminal UI. `pilotswarm remote --api-url <portal-url>` attaches to any deployment (auto Entra sign-in); `pilotswarm local` runs an embedded dev stack. `pilotswarm-cli` is an alias. |
 | `pilotswarm-web` | The portal server: hosts the browser UI **and** the deployment's Web API (`/api/v1` + `/api/v1/ws`) — the single integration surface every client rides. |
-| `pilotswarm-mcp` | MCP server exposing PilotSwarm sessions/facts/models to Claude Desktop, Cursor, or any MCP client. `--api-url <portal-url>` is the supported mode. |
+| `pilotswarm-mcp` | MCP server exposing PilotSwarm sessions/facts/models to Claude Code, Claude Desktop, Copilot CLI, VS Code, Cursor, or any MCP client. |
+
+Requires **Node 24+**. Everything below assumes you already have a deployment's
+portal URL — that URL is the only thing you need to configure.
+
+---
+
+## Quickstart
+
+### 1. Install
 
 ```bash
 npm install -g pilotswarm
+```
+
+(Or skip the install and prefix every command with `npx -p pilotswarm`.)
+
+### 2. Sign in to a deployment
+
+```bash
+pilotswarm auth login --api-url https://portal.example.com
+```
+
+This opens your browser for Entra sign-in and caches the token under
+`~/.config/pilotswarm/auth/<origin>.json`. **Every surface in this package —
+the TUI and the MCP server — reads that same cache**, so you sign in once per
+deployment, not once per client.
 
-# attach the TUI to a deployment — the URL is the only credential you need
+If the deployment has auth disabled, the command simply tells you so and there
+is nothing to do.
+
+```bash
+pilotswarm auth status --api-url https://portal.example.com   # who am I, is the token still good
+pilotswarm auth logout --api-url https://portal.example.com   # drop cached tokens for that origin
+```
+
+On a headless box (no browser), add `--device-code` to use the device-code flow
+instead — but note many corporate tenants block device code via Conditional
+Access.
+
+### 3. Run the TUI
+
+```bash
 pilotswarm remote --api-url https://portal.example.com
+```
 
-# host a portal (needs worker-side env: DATABASE_URL etc.)
-pilotswarm-web --plugin ./plugin
+The `remote` positional is required — `--api-url` without it is an error,
+because bare `pilotswarm` means *local* mode. You can drop the flag entirely by
+setting `PILOTSWARM_API_URL`, or by putting it in a `.env.remote` file next to
+you (remote mode auto-loads `.env.remote`; local mode auto-loads `.env`):
+
+```bash
+export PILOTSWARM_API_URL=https://portal.example.com
+pilotswarm remote
+```
+
+Step 2 is optional in practice: the TUI runs the same sign-in lazily on start
+if no cached token is found. Running `auth login` first just gets the browser
+dance out of the way before the full-screen UI takes over your terminal, and it
+is what makes the MCP servers below work without any further setup.
+
+Useful TUI flags: `-m, --model <name>` (initial model), `-p, --plugin <dir>`
+(plugin directory), `-e, --env <file>` (env file), `-h, --help`.
+
+---
+
+## Connect your AI assistant (MCP)
+
+`pilotswarm-mcp` is a local, stdio MCP server: your assistant spawns it as a
+child process, and it calls the deployment's Web API **as you**, reusing the
+token cached by `pilotswarm auth login`. Nothing extra is deployed, and no
+secret goes into the config file — just the URL.
+
+```
+MCP host (Claude Code / Claude Desktop / Copilot CLI / VS Code)
+   └─ spawns → pilotswarm-mcp (local, stdio)
+                  └─ HTTPS → https://portal.example.com/api/v1
+                             (your identity; your role decides your tool surface)
+```
+
+Your Entra app role gates the surface: admin-only tools (embedder start/stop,
+`facts_admin`, `restart_system_session`, graph-namespace writes) register only
+for admin credentials.
+
+### Claude Code
+
+```bash
+claude mcp add pilotswarm -- npx -y -p pilotswarm pilotswarm-mcp \
+  --api-url https://portal.example.com
+```
+
+Or check a `.mcp.json` into the project root so your whole team gets it:
+
+```json
+{
+  "mcpServers": {
+    "pilotswarm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "pilotswarm", "pilotswarm-mcp",
+               "--api-url", "https://portal.example.com"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then restart the
+app:
 
-# expose a deployment to an MCP client
-pilotswarm-mcp --api-url https://portal.example.com
+```json
+{
+  "mcpServers": {
+    "pilotswarm": {
+      "command": "npx",
+      "args": ["-y", "-p", "pilotswarm", "pilotswarm-mcp",
+               "--api-url", "https://portal.example.com"]
+    }
+  }
+}
 ```
 
-Library surfaces (used by the shipped UIs; importable for custom hosts):
+### GitHub Copilot CLI
+
+Write `.copilot/mcp-config.json` in the repo (or `~/.copilot/mcp-config.json`
+to have it everywhere):
+
+```json
+{
+  "mcpServers": {
+    "pilotswarm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "pilotswarm", "pilotswarm-mcp",
+               "--api-url", "https://portal.example.com"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add `.vscode/mcp.json` to the workspace — note the key is `servers`, not
+`mcpServers`. The server then shows up in agent mode's tool picker:
+
+```json
+{
+  "servers": {
+    "pilotswarm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "pilotswarm", "pilotswarm-mcp",
+               "--api-url", "https://portal.example.com"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Same shape as Claude Desktop, in `~/.cursor/mcp.json` (or **Settings → MCP**).
+
+### Check that it worked
+
+Ask your assistant to call `get_capabilities`. You should get back
+`mode: "web"`, your `admin` flag, and the deployment's facts/graph flags. Then
+`list_sessions` for a fleet view, and `create_session` → `send_and_wait` to
+drive one.
+
+If it fails to start, run the same command by hand — the error is much easier
+to read outside the MCP host:
+
+```bash
+npx -y -p pilotswarm pilotswarm-mcp --api-url https://portal.example.com --log-level info
+```
+
+The usual cause is a missing or expired token: re-run
+`pilotswarm auth login --api-url <url>`.
+
+### Non-interactive credentials (CI, service principals, containers)
+
+There is no browser to sign in with, so hand the server a bearer token
+directly:
+
+```bash
+PILOTSWARM_API_TOKEN=<token> npx -y -p pilotswarm pilotswarm-mcp \
+  --api-url https://portal.example.com
+```
+
+### Remote / shared MCP over HTTP
+
+For a shared endpoint rather than a per-user child process, run the server with
+the HTTP transport and a bearer key clients must present:
+
+```bash
+PILOTSWARM_MCP_KEY=your-secret-key npx -y -p pilotswarm pilotswarm-mcp \
+  --transport http --port 3100 --api-url https://portal.example.com
+```
+
+Clients then point at `http://your-host:3100/mcp` with an
+`Authorization: Bearer ${PILOTSWARM_MCP_KEY}` header. Read the
+[security model](https://github.com/affandar/pilotswarm/blob/main/packages/app/mcp/README.md#security-model)
+before exposing this beyond localhost: the key is shared, and every client
+behind it has the full scope of the deployment.
+
+Full tool catalog, resources, and every flag:
+[MCP server README](https://github.com/affandar/pilotswarm/blob/main/packages/app/mcp/README.md).
+
+---
+
+## Other surfaces
+
+**Run everything locally** (embedded workers, no deployment, no auth) — the fast
+way to try PilotSwarm or develop a plugin:
+
+```bash
+pilotswarm local            # bare `pilotswarm` does the same
+pilotswarm local -p ./plugin -n 4
+```
+
+**Host a portal** — serves the browser UI and the Web API that every client
+above rides on. Needs worker-side env (`DATABASE_URL`, model providers, …):
+
+```bash
+pilotswarm-web --plugin ./plugin
+```
+
+**Library surfaces** (used by the shipped UIs; importable for custom hosts):
 
 - `pilotswarm/ui-core` — framework-free UI controller/state/selectors
 - `pilotswarm/ui-react` — the shared React composition (Ink + DOM)
@@ -33,7 +247,10 @@ Building an app or service instead of a UI? You want
 [`pilotswarm-sdk`](https://www.npmjs.com/package/pilotswarm-sdk) — including
 its zero-dependency wire client at `pilotswarm-sdk/api`.
 
+---
+
 Docs: [Quick Start](https://github.com/affandar/pilotswarm/blob/main/docs/quickstart/docker.md) ·
 [User Guide](https://github.com/affandar/pilotswarm/blob/main/docs/user-guide/README.md) ·
+[MCP Setup](https://github.com/affandar/pilotswarm/blob/main/docs/user-guide/mcp-local-setup.md) ·
 [Web API Reference](https://github.com/affandar/pilotswarm/blob/main/docs/api/reference.md) ·
 [Architecture / Layering](https://github.com/affandar/pilotswarm/blob/main/docs/architecture/layering.md)

package/mcp/README.md

@@ -39,7 +39,7 @@ Each client below shows both **Stdio** (local, recommended) and **HTTP** (remote
 
 ### GitHub Copilot CLI
 
-Add to your `.mcp.json` (project root or `~/.copilot/`):
+Add to `.copilot/mcp-config.json` (repo-scoped) or `~/.copilot/mcp-config.json` (global):
 
 **Stdio (local):**
 

package/mcp/dist/src/tools/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/tools/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,QAmG1E"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/tools/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,QAyK1E"}

package/mcp/dist/src/tools/artifacts.js

@@ -26,23 +26,31 @@ export function registerArtifactTools(server, ctx) {
     }));
     server.registerTool("get_artifact", {
         title: "Get Artifact",
-        description: "Fetch a session artifact. include controls what comes back: 'meta' (metadata), 'text' (content as "
-            + "text — for text artifacts). Binary artifacts: use the download_url returned in meta.",
+        description: "Fetch a session artifact. include controls what comes back: 'meta' (metadata with sha256), 'text' "
+            + "(content as text — for text artifacts), 'base64' (content base64-encoded — for binary artifacts, "
+            + "bounded by max_bytes). Large binaries: use the download_url returned with meta.",
         inputSchema: {
             session_id: sessionIdShape().describe("The session owning the artifact"),
             filename: z.string().min(1).describe("Artifact filename"),
-            include: z.array(z.enum(["meta", "text"])).optional().describe("What to fetch (default ['meta'])"),
+            include: z.array(z.enum(["meta", "text", "base64"])).optional().describe("What to fetch (default ['meta'])"),
+            max_bytes: z.number().optional().describe("Byte cap for include 'base64' (default 256KB, max 1MB)"),
         },
-    }, withToolErrors(async ({ session_id, filename, include }) => {
+    }, withToolErrors(async ({ session_id, filename, include, max_bytes }) => {
         const wants = new Set(include ?? ["meta"]);
         const result = { session_id, filename };
+        let meta;
+        try {
+            meta = await api.call("getArtifactMetadata", { sessionId: session_id, filename });
+        }
+        catch (err) {
+            return errorResult(err instanceof Error ? err.message : String(err), { session_id, filename });
+        }
+        if (!meta) {
+            // Loud not-found: no fabricated download_url for files that don't exist.
+            return errorResult(`Artifact not found: ${filename} in session ${session_id}`, { session_id, filename });
+        }
         if (wants.has("meta")) {
-            try {
-                result.meta = await api.call("getArtifactMetadata", { sessionId: session_id, filename });
-            }
-            catch (err) {
-                return errorResult(err instanceof Error ? err.message : String(err), { session_id, filename });
-            }
+            result.meta = meta;
             // Authenticated binary download route (bespoke, streams).
             result.download_url = `/api/v1/sessions/${session_id}/artifacts/${encodeURIComponent(filename)}/download`;
         }
@@ -55,6 +63,17 @@ export function registerArtifactTools(server, ctx) {
                 result.text_error = err instanceof Error ? err.message : String(err);
             }
         }
+        if (wants.has("base64")) {
+            try {
+                const read = await api.call("readArtifactBase64", { sessionId: session_id, filename, maxBytes: max_bytes });
+                result.base64 = read?.base64;
+                result.truncated = read?.truncated;
+            }
+            catch (err) {
+                result.base64 = null;
+                result.base64_error = err instanceof Error ? err.message : String(err);
+            }
+        }
         return jsonResult(result);
     }));
     server.registerTool("upload_artifact", {
@@ -78,6 +97,43 @@ export function registerArtifactTools(server, ctx) {
         });
         return jsonResult({ uploaded: true, meta });
     }));
+    server.registerTool("copy_artifact", {
+        title: "Copy Artifact",
+        description: "Server-side copy of an artifact between sessions — bytes never leave the store. "
+            + "Optionally verify the copy against an expected SHA-256.",
+        inputSchema: {
+            from_session_id: sessionIdShape().describe("Session that owns the source artifact"),
+            from_filename: z.string().min(1).describe("Source artifact filename"),
+            to_session_id: sessionIdShape().describe("Destination session"),
+            to_filename: z.string().optional().describe("Destination filename (defaults to the source name)"),
+            expected_sha256: z.string().optional().describe("Fail (and delete the copy) if the copied bytes hash differently"),
+        },
+    }, withToolErrors(async ({ from_session_id, from_filename, to_session_id, to_filename, expected_sha256 }) => {
+        const meta = await api.call("copyArtifact", {
+            fromSessionId: from_session_id,
+            fromFilename: from_filename,
+            toSessionId: to_session_id,
+            toFilename: to_filename,
+        });
+        if (expected_sha256 && meta?.sha256 !== expected_sha256) {
+            await api.call("deleteArtifact", { sessionId: to_session_id, filename: meta?.filename ?? to_filename ?? from_filename });
+            return errorResult(`SHA_MISMATCH: copied bytes hash ${meta?.sha256}, expected ${expected_sha256}. The copy was deleted.`, { from_session_id, from_filename });
+        }
+        return jsonResult({ copied: true, meta });
+    }));
+    server.registerTool("pin_artifact", {
+        title: "Pin Artifact",
+        description: "Pin (or unpin) an artifact so it survives session cleanup — use for deliverables that must "
+            + "outlive their producing session.",
+        inputSchema: {
+            session_id: sessionIdShape().describe("The session owning the artifact"),
+            filename: z.string().min(1).describe("Artifact filename"),
+            pinned: z.boolean().optional().describe("true to pin (default), false to unpin"),
+        },
+    }, withToolErrors(async ({ session_id, filename, pinned }) => {
+        const meta = await api.call("setArtifactPinned", { sessionId: session_id, filename, pinned: pinned !== false });
+        return jsonResult({ pinned: pinned !== false, meta });
+    }));
     server.registerTool("delete_artifact", {
         title: "Delete Artifact",
         description: "Delete an artifact from a session.",

package/mcp/dist/src/tools/artifacts.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../src/tools/artifacts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../src/tools/artifacts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pilotswarm",
-    "version": "0.5.11",
+    "version": "0.5.13",
     "description": "PilotSwarm application package: terminal UI, browser portal + Web API server, and MCP server — one install, three bins.",
     "type": "module",
     "license": "MIT",
@@ -77,7 +77,7 @@
         "hono": "^4.12.10",
         "ink": "^6.8.0",
         "jose": "^6.2.2",
-        "pilotswarm-sdk": "^0.5.11",
+        "pilotswarm-sdk": "^0.5.13",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
         "ws": "^8.18.2"

package/tui/src/node-sdk-transport.js

@@ -1152,10 +1152,43 @@ export class NodeSdkTransport {
 
     async getArtifactMetadata(sessionId, filename) {
         if (!this.artifactStore || !sessionId || !filename) return null;
+        if (typeof this.artifactStore.statArtifact === "function") {
+            return this.artifactStore.statArtifact(sessionId, filename);
+        }
         const artifacts = await this.artifactStore.listArtifacts(sessionId);
         return (artifacts || []).find((artifact) => artifact?.filename === filename) || null;
     }
 
+    async copyArtifact(fromSessionId, fromFilename, toSessionId, toFilename) {
+        if (!this.artifactStore) {
+            throw new Error("Artifact store is not available for this transport.");
+        }
+        return this.artifactStore.copyArtifact(fromSessionId, fromFilename, toSessionId, toFilename);
+    }
+
+    async setArtifactPinned(sessionId, filename, pinned) {
+        if (!this.artifactStore) {
+            throw new Error("Artifact store is not available for this transport.");
+        }
+        return this.artifactStore.setArtifactPinned(sessionId, filename, pinned === true);
+    }
+
+    /** Base64 inline read for the MCP surface — JSON-safe, size-guarded. */
+    async readArtifactBase64(sessionId, filename, maxBytes) {
+        if (!this.artifactStore) {
+            throw new Error("Artifact store is not available for this transport.");
+        }
+        const cap = Math.min(Math.max(1, Math.floor(maxBytes || 262144)), 1048576);
+        const result = await this.artifactStore.downloadArtifact(sessionId, filename);
+        const slice = result.body.subarray(0, cap);
+        const { body: _body, ...meta } = result;
+        return {
+            ...meta,
+            base64: slice.toString("base64"),
+            truncated: slice.length < result.body.length,
+        };
+    }
+
     async deleteArtifact(sessionId, filename) {
         if (!this.artifactStore) {
             throw new Error("Artifact store is not available for this transport.");
@@ -1195,16 +1228,22 @@ export class NodeSdkTransport {
         }
 
         const filename = path.basename(resolvedPath);
-        const content = await fs.promises.readFile(resolvedPath);
         const contentType = guessArtifactContentType(filename);
-        await this.artifactStore.uploadArtifact(sessionId, filename, content, contentType);
+        let meta;
+        if (typeof this.artifactStore.uploadArtifactFromFile === "function") {
+            meta = await this.artifactStore.uploadArtifactFromFile(sessionId, filename, resolvedPath, contentType, { source: "user" });
+        } else {
+            const content = await fs.promises.readFile(resolvedPath);
+            meta = await this.artifactStore.uploadArtifact(sessionId, filename, content, contentType);
+        }
 
         return {
             sessionId,
             filename,
             resolvedPath,
-            sizeBytes: content.length,
+            sizeBytes: meta?.sizeBytes ?? stat.size,
             contentType,
+            ...(meta?.sha256 ? { sha256: meta.sha256 } : {}),
         };
     }
 
@@ -1837,7 +1876,7 @@ function createArtifactStore() {
         const reason = err?.message || String(err);
         throw new Error(
             `Azure Blob Storage is configured but cannot be initialized (reason: ${reason}). ` +
-            `Either fix the configuration or unset AZURE_STORAGE_CONNECTION_STRING / PILOTSWARM_USE_MANAGED_IDENTITY to fall back to the local filesystem artifact store.`,
+            `Either fix the configuration or unset AZURE_STORAGE_CONNECTION_STRING / PILOTSWARM_BLOB_USE_MANAGED_IDENTITY / PILOTSWARM_USE_MANAGED_IDENTITY / AZURE_STORAGE_ACCOUNT_URL to fall back to the local filesystem artifact store.`,
         );
     }