pilotswarm 0.0.1 → 0.4.0

package/web/README.md

@@ -0,0 +1,198 @@
+# pilotswarm-web
+
+Web portal for PilotSwarm — browser-based durable agent orchestration UI.
+
+Full feature parity with the TUI: session management, real-time chat, agent
+splash screens (ASCII art), sequence diagrams, node maps, worker logs,
+binary-safe artifact downloads, metadata-aware browser previews, and keyboard shortcuts.
+
+The portal server also hosts the versioned [PilotSwarm Web API](../../docs/api/reference.md)
+(`/api/v1` HTTP + `/api/v1/ws` WebSocket) — see [Web API](#web-api) below.
+
+## Quick Start
+
+```bash
+# Install
+npm install pilotswarm-web
+
+# Run (starts server + serves React app)
+npx pilotswarm-web --env .env.remote
+npx pilotswarm-web --env .env.remote --plugin ./plugin
+
+# Development (Vite HMR)
+cd packages/app/web
+npm run dev              # React app at http://localhost:5173
+node server.js           # API server at http://localhost:3001
+```
+
+## Portal Customization
+
+The web portal reads app-facing customization from `plugin.json` in your app
+plugin directory. Pass the plugin path with `--plugin` or set `PLUGIN_DIRS`
+so the portal process can see the same metadata the TUI and worker use.
+
+Supported keys:
+
+```json
+{
+  "tui": {
+    "title": "DevOps Command Center",
+    "splashFile": "./tui-splash.txt"
+  },
+  "portal": {
+    "branding": {
+      "title": "DevOps Command Center",
+      "pageTitle": "DevOps Command Center Portal",
+      "splashFile": "./tui-splash.txt",
+      "logoFile": "./assets/logo.svg",
+      "faviconFile": "./assets/favicon.png"
+    },
+    "ui": {
+      "loadingMessage": "Preparing the DevOps workspace",
+      "loadingCopy": "Connecting dashboards, session feeds, and orchestration state..."
+    },
+    "auth": {
+      "provider": "entra",
+      "signInTitle": "Sign in to DevOps Command Center",
+      "signInMessage": "Use your organization's identity provider to open the shared operations workspace.",
+      "signInLabel": "Sign In"
+    }
+  }
+}
+```
+
+Notes:
+
+- Preferred schema is nested: `portal.branding`, `portal.ui`, and `portal.auth`.
+- Flat legacy keys such as `portal.title` and `portal.loadingMessage` are still accepted for backwards compatibility.
+- `portal.auth.provider` selects the active auth provider when the deployment does not override it with `PORTAL_AUTH_PROVIDER`.
+- `branding.logoFile` is used on the loading splash, sign-in card, and signed-in header.
+- If `branding.faviconFile` is omitted, the browser tab icon reuses `branding.logoFile`.
+- Keep logo assets inside the plugin directory so the portal image can package and serve them alongside `plugin.json`.
+
+Fallback order:
+
+- `portal.branding.*` / `portal.ui.*` / `portal.auth.*`
+- flat `portal.*`
+- `tui.title` / `tui.splash` / `tui.splashFile`
+- built-in `PilotSwarm` defaults
+
+Named-agent creation in the portal comes from the same plugin metadata surface.
+If the portal process cannot see your plugin directory, the web UI falls back
+to generic sessions even when the worker supports named agents.
+
+Artifact behavior:
+
+- text artifacts still preview inline in the browser workspace
+- binary artifacts render as a download-only card in the browser workspace
+- downloads preserve the stored content type and raw bytes
+
+## Auth Add-Ons
+
+Portal authentication is provider-based.
+
+- Default: `none`
+- Built-in optional provider: `entra`
+- AuthZ is common across providers and currently supports Phase 1 group-based admission control
+
+Enable Entra ID with env vars:
+
+```bash
+PORTAL_AUTH_PROVIDER=entra
+PORTAL_AUTH_ENTRA_TENANT_ID=<tenant-id>
+PORTAL_AUTH_ENTRA_CLIENT_ID=<client-id>
+PORTAL_AUTHZ_ADMIN_GROUPS=admin1@contoso.com,admin2@contoso.com
+PORTAL_AUTHZ_USER_GROUPS=user1@contoso.com,user2@contoso.com
+```
+
+Notes:
+
+- `PORTAL_AUTHZ_ADMIN_GROUPS` and `PORTAL_AUTHZ_USER_GROUPS` are currently comma-delimited email allowlists despite the historical variable names.
+- `PORTAL_AUTHZ_DEFAULT_ROLE` defaults to `none` (deny-by-default since v0.1.33). If no admin/user groups are configured and the JWT carries no role claim, a signed-in user is **denied** at the portal layer. Set `PORTAL_AUTHZ_DEFAULT_ROLE=user` to restore the legacy "any tenant user gets `user`" open posture (sandbox stamps only).
+- `admin` and `user` have the same portal permissions today; the allowlists act as an admission gate and role assignment surface.
+
+### App Roles (Recommended For IT-Managed Tenants)
+
+When the Entra app registration defines `admin` and `user` app roles
+and assigns them, the portal decides admission from the JWT `roles`
+claim — the role assignment in Entra **is** the allowlist for this
+posture. The portal matches the claim by case-insensitive equality
+against the canonical values `admin` and `user`; there is no override
+env var. With deny-by-default (the default since v0.1.33), unassigned
+signed-in users are denied at the portal layer.
+
+The email-allowlist path (`PORTAL_AUTHZ_ADMIN_GROUPS` /
+`PORTAL_AUTHZ_USER_GROUPS`) is bypassed entirely when the JWT carries
+a `roles[]` claim — use it only for stamps that do not use
+`-CreateAppRoles`. Flipping `appRoleAssignmentRequired=true` on the
+Enterprise Application adds an Entra-side gate as well; it is optional
+and carries a restricted-tenant caveat (AADSTS90094 admin-consent
+prompts). See
+[`../../docs/portal-entra-app-roles.md`](../../docs/developer/deploy/entra-app-roles.md)
+for the full operator runbook.
+
+The portal core no longer assumes Entra specifically. New providers can plug
+into the same browser/server provider interfaces, while sharing the same common
+authz layer.
+
+## Web API
+
+The portal server also hosts the versioned PilotSwarm Web API — same process,
+same port (3001):
+
+- **HTTP `/api/v1`** — routes generated from the `pilotswarm-sdk/api`
+  operations table (`packages/sdk/api/src/protocol.js`, the contract source
+  of truth) and dispatched through the existing runtime dispatcher — the same
+  one the legacy `/api/rpc` uses, so the two surfaces cannot drift.
+- **WebSocket `/api/v1/ws`** — session event and log streaming.
+- **Auth** — reuses the portal's provider-based auth; the same `PORTAL_AUTH_*`
+  and `PORTAL_AUTHZ_*` env vars apply, no separate configuration.
+- Errors use the `{ ok: false, error: { code, message } }` envelope.
+
+See [`docs/api/reference.md`](../../docs/api/reference.md) for the full API
+reference.
+
+The legacy `/api/rpc` and `/portal-ws` endpoints remain mounted for a
+deprecation window; new integrations must use `/api/v1`.
+
+## Architecture
+
+```
+Browser (React + Vite)
+  │
+  └── BrowserPortalTransport (extends HttpApiTransport)
+        │
+        ├── HTTP ──────► /api/v1      ─┐
+        │                              ├─ Portal Server (Express + ws)
+        └── WebSocket ─► /api/v1/ws   ─┘
+                             │
+                             ├── PilotSwarmClient
+                             ├── PilotSwarmManagementClient
+                             └── PilotSwarmWorker (embedded or remote)
+```
+
+The browser UI talks `/api/v1` itself via `BrowserPortalTransport`, which
+extends `HttpApiTransport` from `pilotswarm-sdk/api` — the same client
+surface external integrations use.
+
+Same public API boundary as the TUI — only `PilotSwarmClient`,
+`PilotSwarmManagementClient`, and `PilotSwarmWorker` APIs. No internal
+module imports.
+
+## Package Relationship
+
+```
+pilotswarm             (the app package; this dir is its web/ tree)
+  ├── pilotswarm/host  (shared node/runtime host glue, tui/src/portal.js)
+  │   └── pilotswarm-sdk
+  ├── pilotswarm/ui-core, pilotswarm/ui-react (internal UI layers)
+  ├── express
+  ├── ws
+  ├── react, react-dom
+  └── vite             (devDependency)
+```
+
+`pilotswarm-web` now consumes a small supported portal-facing surface from
+`pilotswarm-cli` rather than importing monorepo-relative source files. That
+keeps the publishable package graph explicit and lets the portal reuse the same
+Node transport and plugin-config behavior as the TUI.

package/web/api/router.js

@@ -0,0 +1,196 @@
+import express from "express";
+import path from "node:path";
+import { API_VERSION, OPERATIONS, coerceQueryValue } from "pilotswarm-sdk/api";
+import { getAuthConfig } from "../auth.js";
+import { getPublicAuthContext } from "../auth/authz/engine.js";
+
+/**
+ * The versioned Web API router (`/api/v1`).
+ *
+ * Every JSON operation is generated from the pilotswarm-sdk/api
+ * operations table and delegates to `runtime.call(name, params, req.auth)` —
+ * the same dispatcher the legacy `/api/rpc` uses, so the two surfaces cannot
+ * drift. Only health/auth/bootstrap and the binary artifact download are
+ * hand-written routes.
+ *
+ * Error envelope: `{ ok: false, error: { code, message } }`.
+ */
+
+const ERROR_STATUS_BY_CODE = {
+    INVALID_REQUEST: 400,
+    PORTAL_AUTH_REQUIRED: 401,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    // Capability mismatches: the deployment's store doesn't support the op.
+    FACTS_ENHANCED_UNSUPPORTED: 409,
+    GRAPH_UNSUPPORTED: 409,
+    PAYLOAD_TOO_LARGE: 413,
+};
+
+// Domain/lifecycle errors the runtime throws with actionable, non-sensitive
+// messages. These are client errors (their message is the whole value), so
+// they keep their text; everything else that reaches 500 is treated as an
+// unexpected fault and gets a generic message.
+const CLIENT_ERROR_MESSAGE = /must be|is required|cannot be|Unsupported|is not started|terminal orchestration|cannot accept new messages|not found|already|Unknown model|does not support reasoning effort/i;
+
+function statusForError(error) {
+    const byCode = ERROR_STATUS_BY_CODE[error?.code];
+    if (byCode) return byCode;
+    if (Number.isInteger(error?.status) && error.status >= 400 && error.status <= 599) return error.status;
+    const message = String(error?.message || "");
+    if (/is not started|terminal orchestration|cannot accept new messages|already/i.test(message)) return 409;
+    if (CLIENT_ERROR_MESSAGE.test(message)) return 400;
+    return 500;
+}
+
+function sendError(res, error, fallbackStatus) {
+    const status = fallbackStatus || statusForError(error);
+    const code = error?.code || (status === 404 ? "NOT_FOUND" : status === 400 ? "INVALID_REQUEST" : status === 413 ? "PAYLOAD_TOO_LARGE" : "INTERNAL_ERROR");
+    // 500s are unexpected server faults; their raw messages can leak
+    // connection strings, file paths, or stack detail. Send a generic
+    // message and keep the code for correlation. Client-facing errors
+    // (4xx: validation, not-found, auth, lifecycle conflicts) keep their
+    // message because it is actionable and non-sensitive.
+    const message = status >= 500 ? "Internal server error" : (error?.message || String(error));
+    res.status(status).json({ ok: false, error: { code, message } });
+}
+
+// Session/child id path params must look like ids — never a path fragment.
+// This is the trust boundary for the filesystem artifact store, which builds
+// paths from these values; anything with a separator or ".." is rejected here
+// before it can reach a sink. (Group ids are validated the same way.)
+const ID_PARAM_KEYS = new Set(["sessionId", "parentSessionId", "childSessionId", "agentIdOrSessionId", "groupId"]);
+const SAFE_ID = /^[\w:.-]{1,200}$/;
+
+function assertSafeIdParams(op, params) {
+    for (const key of Object.keys(op.params || {})) {
+        if (!ID_PARAM_KEYS.has(key)) continue;
+        const value = params[key];
+        if (value == null) continue;
+        if (!SAFE_ID.test(String(value)) || String(value).includes("..")) {
+            throw Object.assign(new Error(`Invalid ${key}`), { code: "INVALID_REQUEST" });
+        }
+    }
+}
+
+// A caller is privileged (admin) when the validated token carries the admin
+// role, OR the deployment is no-auth (role "anonymous" — no-auth means a
+// trusted/private deployment with full access, consistent with the rest of
+// the API's binary admission model).
+function isAdminAuth(auth) {
+    const role = auth?.authorization?.role;
+    return role === "admin" || role === "anonymous";
+}
+
+function collectParams(op, req) {
+    const params = {};
+    for (const [key, spec] of Object.entries(op.params || {})) {
+        if (spec.in === "path") {
+            params[key] = req.params[spec.name || key];
+        } else if (spec.in === "query") {
+            const value = coerceQueryValue(req.query[key], spec.type);
+            if (value !== undefined) params[key] = value;
+        } else if (req.body && Object.prototype.hasOwnProperty.call(req.body, key)) {
+            params[key] = req.body[key];
+        }
+    }
+    return params;
+}
+
+export function createApiRouter({ runtime, requireAuth }) {
+    const router = express.Router();
+
+    // ── Public routes ───────────────────────────────────────────────────
+    router.get("/health", (_req, res) => {
+        res.json({ ok: true, started: runtime.started, mode: runtime.mode, apiVersion: API_VERSION });
+    });
+
+    router.get("/auth/config", async (req, res) => {
+        try {
+            res.json(await getAuthConfig(req));
+        } catch (error) {
+            sendError(res, error);
+        }
+    });
+
+    // ── Authenticated routes ────────────────────────────────────────────
+    router.use(requireAuth);
+
+    router.get("/auth/me", (req, res) => {
+        res.json({ ok: true, ...getPublicAuthContext(req.auth) });
+    });
+
+    router.get("/bootstrap", async (req, res) => {
+        try {
+            const bootstrap = await runtime.getBootstrap();
+            res.json({ ok: true, ...bootstrap, apiVersion: API_VERSION, auth: getPublicAuthContext(req.auth) });
+        } catch (error) {
+            sendError(res, error);
+        }
+    });
+
+    // Binary artifact download (streams; not part of the JSON envelope).
+    router.get("/sessions/:sessionId/artifacts/:filename/download", async (req, res) => {
+        if (!SAFE_ID.test(String(req.params.sessionId)) || String(req.params.sessionId).includes("..")) {
+            sendError(res, Object.assign(new Error("Invalid sessionId"), { code: "INVALID_REQUEST" }), 400);
+            return;
+        }
+        try {
+            const artifact = await runtime.downloadArtifactBinary(req.params.sessionId, req.params.filename);
+            res.setHeader("content-type", String(artifact?.contentType || "application/octet-stream"));
+            res.setHeader("content-disposition", `attachment; filename="${path.basename(req.params.filename)}"`);
+            res.send(artifact.body);
+        } catch (error) {
+            sendError(res, error, 404);
+        }
+    });
+
+    // ── Generated operation routes ──────────────────────────────────────
+    for (const op of OPERATIONS) {
+        const expressPath = op.path.replace(/:([\w]+)/g, ":$1");
+        router[op.method.toLowerCase()](expressPath, async (req, res) => {
+            try {
+                // Tier-2 operational ops require the admin role. This is the
+                // API's only per-route role check; every other op shares the
+                // binary admission gate (requireAuth above).
+                if (op.admin && !isAdminAuth(req.auth)) {
+                    sendError(res, Object.assign(new Error("This operation requires the admin role."), { code: "FORBIDDEN" }), 403);
+                    return;
+                }
+                const params = collectParams(op, req);
+                assertSafeIdParams(op, params);
+                const result = await runtime.call(op.name, params, req.auth);
+                res.json({ ok: true, result: result === undefined ? null : result });
+            } catch (error) {
+                sendError(res, error);
+            }
+        });
+    }
+
+    // ── Envelope 404 for unknown API paths ──────────────────────────────
+    router.use((req, res) => {
+        res.status(404).json({
+            ok: false,
+            error: { code: "NOT_FOUND", message: `Unknown API route: ${req.method} ${req.baseUrl}${req.path}` },
+        });
+    });
+
+    // ── Error middleware: body-parser failures (oversized/malformed JSON)
+    // reach here as thrown errors rather than route rejections; map them to
+    // the same envelope instead of Express's default HTML error page.
+    router.use((error, _req, res, _next) => {
+        if (res.headersSent) return;
+        if (error?.type === "entity.too.large") {
+            sendError(res, Object.assign(new Error("Request body too large"), { code: "PAYLOAD_TOO_LARGE" }), 413);
+            return;
+        }
+        if (error?.type === "entity.parse.failed" || error instanceof SyntaxError) {
+            sendError(res, Object.assign(new Error("Malformed JSON body"), { code: "INVALID_REQUEST" }), 400);
+            return;
+        }
+        sendError(res, error);
+    });
+
+    return router;
+}

package/web/api/ws.js

@@ -0,0 +1,152 @@
+import { WebSocketServer } from "ws";
+import { authenticateToken, extractToken } from "../auth.js";
+
+/**
+ * The Web API streaming endpoint: session events and the live log tail.
+ *
+ * One connection handler serves both `/api/v1/ws` (the product API) and the
+ * legacy `/portal-ws` (which additionally answers the portal-only `theme`
+ * message). Vocabulary:
+ *   client -> server: subscribeSession | unsubscribeSession | subscribeLogs | unsubscribeLogs
+ *   server -> client: ready | subscribedSession | sessionEvent | subscribedLogs | logEntry | error
+ *
+ * Delivery here is an acceleration path — correctness comes from event
+ * replay via GET /api/v1/management/sessions/:id/events?afterSeq=… after a
+ * reconnect.
+ */
+
+function isSafeThemeId(value) {
+    return /^[\w-]+$/u.test(String(value || ""));
+}
+
+export function createConnectionHandler(runtime, { allowThemeMessages = false } = {}) {
+    return async function handleConnection(ws, req) {
+        const auth = await authenticateToken(extractToken(req), req);
+        if (!auth.ok) {
+            ws.close(auth.status === 403 ? 4403 : 4401, auth.error || (auth.status === 403 ? "Forbidden" : "Unauthorized"));
+            return;
+        }
+
+        const sessionSubscriptions = new Map();
+        let logUnsubscribe = null;
+
+        const send = (message) => {
+            if (ws.readyState === ws.OPEN) {
+                ws.send(JSON.stringify(message));
+            }
+        };
+
+        send({ type: "ready" });
+
+        ws.on("message", async (raw) => {
+            let message;
+            try {
+                message = JSON.parse(String(raw));
+            } catch {
+                return;
+            }
+
+            const type = String(message?.type || "");
+            if (type === "subscribeSession") {
+                const sessionId = String(message?.sessionId || "").trim();
+                if (!sessionId || sessionSubscriptions.has(sessionId)) return;
+                try {
+                    await runtime.start();
+                    const unsubscribe = runtime.subscribeSession(sessionId, (event) => {
+                        send({ type: "sessionEvent", sessionId, event });
+                    });
+                    sessionSubscriptions.set(sessionId, unsubscribe);
+                    send({ type: "subscribedSession", sessionId });
+                } catch (error) {
+                    send({ type: "error", scope: "session", sessionId, error: error?.message || String(error) });
+                }
+                return;
+            }
+
+            if (type === "unsubscribeSession") {
+                const sessionId = String(message?.sessionId || "").trim();
+                const unsubscribe = sessionSubscriptions.get(sessionId);
+                if (unsubscribe) {
+                    unsubscribe();
+                    sessionSubscriptions.delete(sessionId);
+                }
+                return;
+            }
+
+            if (type === "subscribeLogs") {
+                if (logUnsubscribe) return;
+                try {
+                    await runtime.start();
+                    logUnsubscribe = runtime.startLogTail((entry) => {
+                        send({ type: "logEntry", entry });
+                    });
+                    send({ type: "subscribedLogs" });
+                } catch (error) {
+                    send({ type: "error", scope: "logs", error: error?.message || String(error) });
+                }
+                return;
+            }
+
+            if (type === "unsubscribeLogs") {
+                if (logUnsubscribe) {
+                    logUnsubscribe();
+                    logUnsubscribe = null;
+                }
+                return;
+            }
+
+            if (allowThemeMessages && type === "theme" && isSafeThemeId(message?.themeId)) {
+                send({ type: "themeAck", themeId: message.themeId });
+            }
+        });
+
+        ws.on("close", () => {
+            for (const unsubscribe of sessionSubscriptions.values()) {
+                try {
+                    unsubscribe();
+                } catch {}
+            }
+            sessionSubscriptions.clear();
+            if (logUnsubscribe) {
+                try {
+                    logUnsubscribe();
+                } catch {}
+                logUnsubscribe = null;
+            }
+        });
+    };
+}
+
+/**
+ * Mount WebSocket endpoints on the shared HTTP server.
+ *
+ * Multiple path-bound WebSocketServers cannot share one HTTP server (each
+ * competes for the 'upgrade' event), so this routes upgrades manually with
+ * noServer-mode servers — one per endpoint.
+ *
+ * @param {import("node:http").Server} server
+ * @param {object} runtime
+ * @param {Array<{ path: string, allowThemeMessages?: boolean }>} endpoints
+ * @returns {WebSocketServer[]}
+ */
+export function attachWebSockets(server, runtime, endpoints) {
+    const byPath = new Map(endpoints.map(({ path, allowThemeMessages = false }) => {
+        const wss = new WebSocketServer({ noServer: true });
+        wss.on("connection", createConnectionHandler(runtime, { allowThemeMessages }));
+        return [path, wss];
+    }));
+
+    server.on("upgrade", (req, socket, head) => {
+        const { pathname } = new URL(req.url || "/", "http://localhost");
+        const wss = byPath.get(pathname);
+        if (!wss) {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit("connection", ws, req);
+        });
+    });
+
+    return [...byPath.values()];
+}