pilotswarm-sdk 0.3.2 → 0.4.0

package/README.md

@@ -14,6 +14,23 @@ Minimal usage:
 import { PilotSwarmClient, PilotSwarmWorker, defineTool } from "pilotswarm-sdk";
 ```
 
+Client apps connect to a deployment's Web API (web mode):
+
+```ts
+const client = new PilotSwarmClient({ apiUrl: "https://portal.example.com" });
+await client.start();
+const session = await client.createSession();
+const reply = await session.sendAndWait("hello");
+```
+
+Pass `getAccessToken` for authenticated deployments; use `PilotSwarmManagementClient({ apiUrl, getAccessToken? })` for management operations. Constructing a client directly with `{ store }` is internal (worker/portal-host embedding and testing) — see the [Web API reference](https://github.com/affandar/PilotSwarm/blob/main/docs/api/reference.md).
+
+Workers are trusted backend components and always attach directly to the store:
+
+```ts
+const worker = new PilotSwarmWorker({ store: process.env.DATABASE_URL });
+```
+
 `pilotswarm-sdk` ships PilotSwarm's embedded framework prompt, framework skills, and management plugins inside the package. App code should provide its own `plugin/` directory and worker-side tool handlers on top of that base.
 
 Artifact note:
@@ -24,9 +41,9 @@ Artifact note:
 
 Common docs:
 
-- SDK apps: `https://github.com/affandar/PilotSwarm/blob/main/docs/sdk/building-apps.md`
-- SDK agents: `https://github.com/affandar/PilotSwarm/blob/main/docs/sdk/building-agents.md`
-- Configuration: `https://github.com/affandar/PilotSwarm/blob/main/docs/configuration.md`
-- Architecture: `https://github.com/affandar/PilotSwarm/blob/main/docs/architecture.md`
+- SDK apps: `https://github.com/affandar/PilotSwarm/blob/main/docs/developer/building/sdk-apps.md`
+- SDK agents: `https://github.com/affandar/PilotSwarm/blob/main/docs/developer/building/sdk-agents.md`
+- Configuration: `https://github.com/affandar/PilotSwarm/blob/main/docs/developer/reference/configuration.md`
+- Architecture: `https://github.com/affandar/PilotSwarm/blob/main/docs/architecture/system.md`
 
 If you want the shipped terminal UI, install `pilotswarm-cli`.

package/api/README.md

@@ -0,0 +1,44 @@
+# pilotswarm-sdk/api
+
+Isomorphic protocol client for the [PilotSwarm Web API](../../docs/api/reference.md)
+(`/api/v1` + `/api/v1/ws`). Runs in browsers and Node (≥22) with zero
+dependencies — `fetch` and `WebSocket` come from the environment and are
+injectable for tests.
+
+This package is the transport layer under everything that talks to a
+PilotSwarm deployment remotely: the browser portal, the TUI's API mode, and
+the SDK's web provider (`new PilotSwarmClient({ apiUrl })`). Most applications
+should use the [SDK](../sdk/README.md) rather than this package directly.
+
+```js
+import { ApiClient } from "pilotswarm-sdk/api";
+
+const api = new ApiClient({
+  apiUrl: "https://portal.example.com",
+  getAccessToken, // optional; omit for no-auth deployments
+});
+
+const session = await api.call("createSession", { model: "anthropic:claude-sonnet-4-6" });
+await api.call("sendMessage", { sessionId: session.sessionId, prompt: "hello" });
+const unsubscribe = api.subscribeSession(session.sessionId, (event) => console.log(event));
+```
+
+## Modules
+
+- `src/protocol.js` — the **operations table**: every JSON operation's name,
+  HTTP method, path template, and parameter placement. This is the single
+  source of truth shared with the portal server (which generates its routes
+  from it) and the API reference doc.
+- `src/api-client.js` — `ApiClient`: request building, `{ ok, result }`
+  envelope handling, 401/403 callbacks, and the `/api/v1/ws` WebSocket with
+  automatic resubscribe + backoff.
+- `src/http-api-transport.js` — `HttpApiTransport`: the shared-UI transport
+  surface (`pilotswarm/ui-core`) over `ApiClient`. Environment conveniences
+  (save-to-disk, open-in-app) are injected by the host (browser portal, TUI).
+
+## Auth
+
+`getAccessToken` is called before every request and WebSocket connect. HTTP
+401/403 invoke `onUnauthorized`/`onForbidden`; WebSocket close codes 4401/4403
+do the same and suppress reconnection. Deployment auth mode is discovered from
+the public `GET /api/v1/auth/config` (`api.getAuthConfig()`).

package/api/index.d.ts

@@ -0,0 +1,86 @@
+/** Typed surface for pilotswarm-sdk/api (implementation is plain ESM JS). */
+
+export declare const API_PREFIX: string;
+export declare const API_VERSION: number;
+export declare const WS_PATH: string;
+export declare const WS_CLIENT_MESSAGES: string[];
+export declare const WS_SERVER_MESSAGES: string[];
+export declare const WEB_MODE_UNSUPPORTED: string;
+
+export interface OperationParamSpec {
+    in: "path" | "query" | "body";
+    name?: string;
+    type?: "string" | "number" | "boolean" | "json";
+}
+
+export interface Operation {
+    name: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    params?: Record<string, OperationParamSpec>;
+    summary: string;
+}
+
+export declare const OPERATIONS: Operation[];
+export declare function getOperation(name: string): Operation | null;
+export declare function buildOperationRequest(name: string, params?: Record<string, unknown>): {
+    method: string;
+    path: string;
+    query: URLSearchParams;
+    body: Record<string, unknown> | null;
+};
+export declare function coerceQueryValue(value: unknown, type?: string): unknown;
+export declare function artifactDownloadPath(sessionId: string, filename: string): string;
+
+export declare class ApiError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, opts?: { code?: string; status?: number });
+}
+
+export interface ApiClientOptions {
+    apiUrl: string;
+    getAccessToken?: () => Promise<string | null>;
+    onUnauthorized?: () => void;
+    onForbidden?: (message: string) => void;
+    fetchImpl?: typeof fetch;
+    WebSocketImpl?: unknown;
+}
+
+export declare class ApiClient {
+    constructor(options: ApiClientOptions);
+    apiUrl: string;
+    call(name: string, params?: Record<string, unknown>): Promise<any>;
+    request(method: string, pathWithQuery: string, opts?: { body?: unknown; headers?: Record<string, string> }): Promise<any>;
+    health(): Promise<any>;
+    getAuthConfig(): Promise<any>;
+    getAuthContext(): Promise<any>;
+    getBootstrap(): Promise<any>;
+    downloadArtifactResponse(sessionId: string, filename: string): Promise<Response>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribeSession(sessionId: string, handler: (event: unknown) => void, onResubscribe?: () => void): () => void;
+    subscribeLogs(handler: (entry: unknown) => void): () => void;
+}
+
+export interface HttpApiTransportHost {
+    saveArtifactDownload?: (transport: HttpApiTransport, sessionId: string, filename: string) => Promise<unknown>;
+    uploadArtifactFromPath?: (transport: HttpApiTransport, sessionId: string, filePath: string) => Promise<unknown>;
+    openPathInDefaultApp?: (targetPath: string) => Promise<unknown>;
+    openUrlInDefaultBrowser?: (targetUrl: string) => Promise<unknown>;
+    artifactExportDirectory?: string;
+}
+
+export interface HttpApiTransportOptions extends ApiClientOptions {
+    api?: ApiClient;
+    host?: HttpApiTransportHost;
+}
+
+export declare class HttpApiTransport {
+    constructor(options: HttpApiTransportOptions);
+    api: ApiClient;
+    bootstrap: any;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    [method: string]: any;
+}

package/api/index.js

@@ -0,0 +1,16 @@
+export {
+    API_PREFIX,
+    API_VERSION,
+    WS_PATH,
+    WS_CLIENT_MESSAGES,
+    WS_SERVER_MESSAGES,
+    WEB_MODE_UNSUPPORTED,
+    OPERATIONS,
+    getOperation,
+    buildOperationRequest,
+    coerceQueryValue,
+    artifactDownloadPath,
+    ApiError,
+} from "./src/protocol.js";
+export { ApiClient } from "./src/api-client.js";
+export { HttpApiTransport } from "./src/http-api-transport.js";

package/api/src/api-client.js

@@ -0,0 +1,363 @@
+import { API_PREFIX, ApiError, WS_PATH, artifactDownloadPath, buildOperationRequest } from "./protocol.js";
+
+const RECONNECT_DELAY_MS = 1500;
+
+function normalizeApiUrl(apiUrl) {
+    const raw = String(apiUrl || "").trim();
+    if (!raw) throw new Error("ApiClient requires an apiUrl");
+    return raw.replace(/\/+$/, "");
+}
+
+function toWebSocketUrl(apiUrl) {
+    const url = new URL(apiUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = `${url.pathname.replace(/\/+$/, "")}${WS_PATH}`;
+    url.search = "";
+    return url.toString();
+}
+
+async function readErrorEnvelope(response) {
+    let message = response.statusText || `HTTP ${response.status}`;
+    let code = response.status === 401 ? "UNAUTHORIZED" : response.status === 403 ? "FORBIDDEN" : "INTERNAL_ERROR";
+    try {
+        const payload = await response.json();
+        const error = payload?.error;
+        if (typeof error === "string" && error) message = error;
+        else if (error && typeof error === "object") {
+            if (error.message) message = error.message;
+            if (error.code) code = error.code;
+        } else if (payload?.message) {
+            message = payload.message;
+        }
+    } catch {}
+    return new ApiError(message, { code, status: response.status });
+}
+
+/**
+ * Typed low-level client for the PilotSwarm Web API.
+ *
+ * Isomorphic: runs in browsers and Node. `fetch` and `WebSocket` come from
+ * the global environment unless injected (`fetchImpl` / `WebSocketImpl`).
+ */
+export class ApiClient {
+    constructor({
+        apiUrl,
+        getAccessToken,
+        onUnauthorized,
+        onForbidden,
+        fetchImpl,
+        WebSocketImpl,
+    } = {}) {
+        this.apiUrl = normalizeApiUrl(apiUrl);
+        this.getAccessToken = typeof getAccessToken === "function" ? getAccessToken : async () => null;
+        this.onUnauthorized = typeof onUnauthorized === "function" ? onUnauthorized : () => {};
+        this.onForbidden = typeof onForbidden === "function" ? onForbidden : () => {};
+        this.fetchImpl = fetchImpl || ((...args) => globalThis.fetch(...args));
+        this.WebSocketImpl = WebSocketImpl || globalThis.WebSocket;
+
+        this.socket = null;
+        this.socketOpenPromise = null;
+        this.reconnectTimer = null;
+        this.stopped = false;
+        this.hasConnected = false;
+        this.sessionSubscribers = new Map();
+        this.sessionResubscribeHandlers = new Map();
+        this.logSubscribers = new Set();
+    }
+
+    // ── HTTP ────────────────────────────────────────────────────────────
+
+    async authHeaders(extra = {}) {
+        const token = await this.getAccessToken();
+        const headers = { ...extra };
+        if (token) headers.authorization = `Bearer ${token}`;
+        return headers;
+    }
+
+    async request(method, pathWithQuery, { body, headers } = {}) {
+        const requestHeaders = await this.authHeaders(headers || {});
+        if (body !== undefined && !requestHeaders["content-type"]) {
+            requestHeaders["content-type"] = "application/json";
+        }
+        const response = await this.fetchImpl(`${this.apiUrl}${pathWithQuery}`, {
+            method,
+            headers: requestHeaders,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (response.status === 401) {
+            this.onUnauthorized();
+            throw await readErrorEnvelope(response);
+        }
+        if (response.status === 403) {
+            const error = await readErrorEnvelope(response);
+            this.onForbidden(error.message || "Forbidden");
+            throw error;
+        }
+        if (!response.ok) {
+            throw await readErrorEnvelope(response);
+        }
+        const payload = await response.json();
+        if (payload && payload.ok === false) {
+            const error = payload.error;
+            throw new ApiError(
+                (typeof error === "object" ? error?.message : error) || "Request failed",
+                { code: (typeof error === "object" && error?.code) || "INTERNAL_ERROR", status: response.status },
+            );
+        }
+        return payload?.result !== undefined ? payload.result : payload;
+    }
+
+    /** Invoke a protocol operation by name with rpc-shaped params. */
+    async call(name, params = {}) {
+        const { method, path, query, body } = buildOperationRequest(name, params);
+        // Avoid URLSearchParams.prototype.size (absent on Safari 16 / iOS 16,
+        // which the portal build targets); toString() is universally supported.
+        const queryString = query.toString();
+        const suffix = queryString ? `?${queryString}` : "";
+        return this.request(method, `${path}${suffix}`, body !== null ? { body } : {});
+    }
+
+    // ── Bespoke (non-table) endpoints ───────────────────────────────────
+
+    async health() {
+        return this.request("GET", `${API_PREFIX}/health`);
+    }
+
+    /** Public: no token required. */
+    async getAuthConfig() {
+        const response = await this.fetchImpl(`${this.apiUrl}${API_PREFIX}/auth/config`, { method: "GET" });
+        if (!response.ok) throw await readErrorEnvelope(response);
+        return response.json();
+    }
+
+    async getAuthContext() {
+        return this.request("GET", `${API_PREFIX}/auth/me`);
+    }
+
+    async getBootstrap() {
+        return this.request("GET", `${API_PREFIX}/bootstrap`);
+    }
+
+    /** Raw artifact download; returns the Response for streaming/blob use. */
+    async downloadArtifactResponse(sessionId, filename) {
+        const headers = await this.authHeaders();
+        const response = await this.fetchImpl(`${this.apiUrl}${artifactDownloadPath(sessionId, filename)}`, {
+            method: "GET",
+            headers,
+        });
+        if (response.status === 401) {
+            this.onUnauthorized();
+            throw await readErrorEnvelope(response);
+        }
+        if (response.status === 403) {
+            const error = await readErrorEnvelope(response);
+            this.onForbidden(error.message || "Forbidden");
+            throw error;
+        }
+        if (!response.ok) throw await readErrorEnvelope(response);
+        return response;
+    }
+
+    // ── WebSocket (session events + log tail) ───────────────────────────
+
+    async start() {
+        this.stopped = false;
+    }
+
+    async stop() {
+        this.stopped = true;
+        this.hasConnected = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.socket) {
+            try {
+                this.socket.close();
+            } catch {}
+        }
+        this.socket = null;
+        this.socketOpenPromise = null;
+        this.sessionSubscribers.clear();
+        this.logSubscribers.clear();
+    }
+
+    scheduleReconnect() {
+        if (this.stopped || this.reconnectTimer) return;
+        if (this.sessionSubscribers.size === 0 && this.logSubscribers.size === 0) return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.ensureSocket().catch(() => {});
+        }, RECONNECT_DELAY_MS);
+    }
+
+    async ensureSocket() {
+        if (this.stopped) return null;
+        const WebSocketImpl = this.WebSocketImpl;
+        if (!WebSocketImpl) throw new Error("No WebSocket implementation available");
+        if (this.socket && this.socket.readyState === WebSocketImpl.OPEN) {
+            return this.socket;
+        }
+        if (this.socketOpenPromise) {
+            return this.socketOpenPromise;
+        }
+
+        this.socketOpenPromise = (async () => {
+            let socket;
+            try {
+                const token = await this.getAccessToken();
+                const socketUrl = toWebSocketUrl(this.apiUrl);
+                socket = token
+                    ? new WebSocketImpl(socketUrl, ["access_token", token])
+                    : new WebSocketImpl(socketUrl);
+            } catch (error) {
+                // getAccessToken rejected or the constructor threw before any
+                // socket exists — no close/error event will fire, so schedule
+                // the retry here or the connection dies permanently.
+                this.socket = null;
+                this.scheduleReconnect();
+                throw error;
+            }
+            this.socket = socket;
+
+            socket.addEventListener("message", (event) => {
+                try {
+                    const message = JSON.parse(String(event.data || ""));
+                    if (message.type === "sessionEvent") {
+                        const handlers = this.sessionSubscribers.get(message.sessionId);
+                        if (handlers) {
+                            for (const handler of handlers) handler(message.event);
+                        }
+                        return;
+                    }
+                    if (message.type === "logEntry") {
+                        for (const handler of this.logSubscribers) handler(message.entry);
+                    }
+                } catch {}
+            });
+
+            socket.addEventListener("close", (event) => {
+                this.socket = null;
+                this.socketOpenPromise = null;
+                if (event.code === 4401) {
+                    this.onUnauthorized();
+                    return;
+                }
+                if (event.code === 4403) {
+                    this.onForbidden(event.reason || "Forbidden");
+                    return;
+                }
+                this.scheduleReconnect();
+            });
+
+            socket.addEventListener("error", () => {
+                this.scheduleReconnect();
+            });
+
+            await new Promise((resolve, reject) => {
+                socket.addEventListener("open", resolve, { once: true });
+                socket.addEventListener("error", () => reject(new Error("WebSocket connection failed")), { once: true });
+                socket.addEventListener("close", (event) => {
+                    if (event.code === 4401) reject(new ApiError("Unauthorized", { code: "UNAUTHORIZED", status: 401 }));
+                    if (event.code === 4403) reject(new ApiError(event.reason || "Forbidden", { code: "FORBIDDEN", status: 403 }));
+                }, { once: true });
+            });
+
+            const isReconnect = this.hasConnected;
+            this.hasConnected = true;
+            this.resubscribeAll(isReconnect);
+            return socket;
+        })();
+
+        try {
+            return await this.socketOpenPromise;
+        } finally {
+            if (!this.socket || this.socket.readyState !== WebSocketImpl.OPEN) {
+                this.socketOpenPromise = null;
+            }
+        }
+    }
+
+    socketSend(message) {
+        if (this.socket && this.socket.readyState === this.WebSocketImpl.OPEN) {
+            this.socket.send(JSON.stringify(message));
+        }
+    }
+
+    resubscribeAll(isReconnect = false) {
+        for (const sessionId of this.sessionSubscribers.keys()) {
+            this.socketSend({ type: "subscribeSession", sessionId });
+            // On a RECONNECT, live delivery resumes but events emitted during
+            // the outage were missed. Signal consumers so they can replay via
+            // events?afterSeq. Not on the first connect — the consumer does its
+            // own initial catch-up then.
+            if (isReconnect) {
+                for (const onResubscribe of this.sessionResubscribeHandlers.get(sessionId) || []) {
+                    try {
+                        onResubscribe();
+                    } catch {}
+                }
+            }
+        }
+        if (this.logSubscribers.size > 0) {
+            this.socketSend({ type: "subscribeLogs" });
+        }
+    }
+
+    /**
+     * Register a subscription and make sure the server knows about it: when
+     * the socket is already open, send the subscribe message directly;
+     * otherwise connect, and resubscribeAll() announces it on open.
+     */
+    announceSubscription(message) {
+        if (this.socket && this.socket.readyState === this.WebSocketImpl?.OPEN) {
+            this.socketSend(message);
+            return;
+        }
+        this.ensureSocket().catch(() => {});
+    }
+
+    /**
+     * Subscribe to a session's events. `onResubscribe` (optional) fires after
+     * every reconnect so the caller can replay events missed during the
+     * outage — WS delivery is an acceleration path; replay is the correctness
+     * mechanism.
+     */
+    subscribeSession(sessionId, handler, onResubscribe) {
+        if (!this.sessionSubscribers.has(sessionId)) {
+            this.sessionSubscribers.set(sessionId, new Set());
+        }
+        const handlers = this.sessionSubscribers.get(sessionId);
+        handlers.add(handler);
+        if (typeof onResubscribe === "function") {
+            if (!this.sessionResubscribeHandlers.has(sessionId)) {
+                this.sessionResubscribeHandlers.set(sessionId, new Set());
+            }
+            this.sessionResubscribeHandlers.get(sessionId).add(onResubscribe);
+        }
+        this.announceSubscription({ type: "subscribeSession", sessionId });
+
+        return () => {
+            handlers.delete(handler);
+            const resubHandlers = this.sessionResubscribeHandlers.get(sessionId);
+            if (resubHandlers && typeof onResubscribe === "function") resubHandlers.delete(onResubscribe);
+            if (handlers.size === 0) {
+                this.sessionSubscribers.delete(sessionId);
+                this.sessionResubscribeHandlers.delete(sessionId);
+                this.socketSend({ type: "unsubscribeSession", sessionId });
+            }
+        };
+    }
+
+    subscribeLogs(handler) {
+        this.logSubscribers.add(handler);
+        this.announceSubscription({ type: "subscribeLogs" });
+
+        return () => {
+            this.logSubscribers.delete(handler);
+            if (this.logSubscribers.size === 0) {
+                this.socketSend({ type: "unsubscribeLogs" });
+            }
+        };
+    }
+}