pilotswarm-sdk 0.3.2 → 0.4.0

package/api/src/http-api-transport.js

@@ -0,0 +1,342 @@
+import { ApiClient } from "./api-client.js";
+
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+
+function unsupported(name, hint) {
+    return () => {
+        throw new Error(`${name} is not available on this client${hint ? ` (${hint})` : ""}`);
+    };
+}
+
+/**
+ * The shared-UI transport surface (what `pilotswarm/ui-core` consumes) over
+ * the PilotSwarm Web API. Used by the browser portal and by the TUI's API
+ * mode; both inject their environment-specific conveniences (artifact
+ * save-to-disk / browser download, open-in-app) via `options.host`.
+ */
+export class HttpApiTransport {
+    constructor(options = {}) {
+        this.api = options.api instanceof ApiClient ? options.api : new ApiClient(options);
+        this.bootstrap = null;
+        const host = options.host || {};
+        if (host.saveArtifactDownload) this.saveArtifactDownload = host.saveArtifactDownload.bind(null, this);
+        else this.saveArtifactDownload = unsupported("saveArtifactDownload", "no host download handler");
+        if (host.uploadArtifactFromPath) this.uploadArtifactFromPath = host.uploadArtifactFromPath.bind(null, this);
+        if (host.openPathInDefaultApp) this.openPathInDefaultApp = host.openPathInDefaultApp;
+        if (host.openUrlInDefaultBrowser) this.openUrlInDefaultBrowser = host.openUrlInDefaultBrowser;
+        this.artifactExportDirectory = host.artifactExportDirectory || null;
+    }
+
+    async start() {
+        await this.api.start();
+        this.bootstrap = await this.api.getBootstrap();
+    }
+
+    async stop() {
+        await this.api.stop();
+    }
+
+    // ── Bootstrap-backed getters ────────────────────────────────────────
+
+    getWorkerCount() {
+        return this.bootstrap?.workerCount ?? null;
+    }
+
+    getLogConfig() {
+        return this.bootstrap?.logConfig || null;
+    }
+
+    getModelsByProvider() {
+        return this.bootstrap?.modelsByProvider || [];
+    }
+
+    getDefaultModel() {
+        return this.bootstrap?.defaultModel || null;
+    }
+
+    getAuthContext() {
+        return this.bootstrap?.auth || {
+            principal: null,
+            authorization: { allowed: false, role: null, reason: "Auth context unavailable", matchedGroups: [] },
+        };
+    }
+
+    async listCreatableAgents() {
+        return this.bootstrap?.creatableAgents || this.api.call("listCreatableAgents");
+    }
+
+    getSessionCreationPolicy() {
+        return this.bootstrap?.sessionCreationPolicy || null;
+    }
+
+    // ── Sessions ────────────────────────────────────────────────────────
+
+    async listSessions() {
+        return this.api.call("listSessions");
+    }
+
+    async listSessionsPage(opts = {}) {
+        return this.api.call("listSessionsPage", {
+            limit: opts?.limit,
+            cursor: opts?.cursor ?? undefined,
+            includeDeleted: opts?.includeDeleted,
+        });
+    }
+
+    async getSession(sessionId) {
+        return this.api.call("getSession", { sessionId });
+    }
+
+    async createSession(options = {}) {
+        return this.api.call("createSession", options);
+    }
+
+    async createSessionForAgent(agentName, options = {}) {
+        return this.api.call("createSessionForAgent", { agentName, ...options });
+    }
+
+    async deleteSession(sessionId) {
+        return this.api.call("deleteSession", { sessionId });
+    }
+
+    async renameSession(sessionId, title) {
+        return this.api.call("renameSession", { sessionId, title });
+    }
+
+    async cancelSession(sessionId) {
+        return this.api.call("cancelSession", { sessionId });
+    }
+
+    async completeSession(sessionId, reason) {
+        return this.api.call("completeSession", { sessionId, reason });
+    }
+
+    async restartSystemSession(agentIdOrSessionId, options = {}) {
+        return this.api.call("restartSystemSession", { agentIdOrSessionId, options });
+    }
+
+    async setSessionModel(sessionId, options = {}) {
+        return this.api.call("setSessionModel", { sessionId, options });
+    }
+
+    async stopSessionTurn(sessionId, options = {}) {
+        return this.api.call("stopSessionTurn", { sessionId, options });
+    }
+
+    // ── Messaging ───────────────────────────────────────────────────────
+
+    async sendMessage(sessionId, prompt, options = {}) {
+        return this.api.call("sendMessage", { sessionId, prompt, options });
+    }
+
+    async sendAnswer(sessionId, answer) {
+        return this.api.call("sendAnswer", { sessionId, answer });
+    }
+
+    async cancelPendingMessage(sessionId, clientMessageIds) {
+        return this.api.call("cancelPendingMessage", { sessionId, clientMessageIds });
+    }
+
+    // ── Session groups ──────────────────────────────────────────────────
+
+    async listSessionGroups() {
+        return this.api.call("listSessionGroups");
+    }
+
+    async createSessionGroup(input) {
+        return this.api.call("createSessionGroup", { input });
+    }
+
+    async updateSessionGroup(groupId, patch) {
+        return this.api.call("updateSessionGroup", { groupId, patch });
+    }
+
+    async assignSessionsToGroup(groupId, sessionIds) {
+        return this.api.call("assignSessionsToGroup", { groupId, sessionIds });
+    }
+
+    async moveSessionsToGroup(groupId, sessionIds) {
+        return this.api.call("moveSessionsToGroup", { groupId: groupId ?? null, sessionIds });
+    }
+
+    async deleteSessionGroup(groupId) {
+        return this.api.call("deleteSessionGroup", { groupId });
+    }
+
+    async cancelSessionGroup(groupId, reason) {
+        return this.api.call("cancelSessionGroup", { groupId, reason });
+    }
+
+    async completeSessionGroup(groupId, options = {}) {
+        return this.api.call("completeSessionGroup", { groupId, options });
+    }
+
+    async getChildOutcome(childSessionId) {
+        return this.api.call("getChildOutcome", { childSessionId });
+    }
+
+    async listChildOutcomes(parentSessionId) {
+        return this.api.call("listChildOutcomes", { parentSessionId });
+    }
+
+    // ── Stats / telemetry ───────────────────────────────────────────────
+
+    async getOrchestrationStats(sessionId) {
+        return this.api.call("getOrchestrationStats", { sessionId });
+    }
+
+    async getSessionMetricSummary(sessionId) {
+        return this.api.call("getSessionMetricSummary", { sessionId });
+    }
+
+    async getSessionTokensByModel(sessionId) {
+        return this.api.call("getSessionTokensByModel", { sessionId });
+    }
+
+    async getSessionTreeStats(sessionId) {
+        return this.api.call("getSessionTreeStats", { sessionId });
+    }
+
+    async getFleetStats(opts) {
+        return this.api.call("getFleetStats", {
+            includeDeleted: opts?.includeDeleted,
+            since: toIso(opts?.since),
+        });
+    }
+
+    async getUserStats(opts) {
+        return this.api.call("getUserStats", {
+            includeDeleted: opts?.includeDeleted,
+            since: toIso(opts?.since),
+        });
+    }
+
+    async getTopEventEmitters(opts = {}) {
+        return this.api.call("getTopEventEmitters", {
+            since: toIso(opts?.since),
+            limit: opts?.limit,
+        });
+    }
+
+    async getSessionSkillUsage(sessionId, opts) {
+        return this.api.call("getSessionSkillUsage", { sessionId, since: toIso(opts?.since) });
+    }
+
+    async getSessionTreeSkillUsage(sessionId, opts) {
+        return this.api.call("getSessionTreeSkillUsage", { sessionId, since: toIso(opts?.since) });
+    }
+
+    async getFleetSkillUsage(opts) {
+        return this.api.call("getFleetSkillUsage", {
+            includeDeleted: opts?.includeDeleted,
+            since: toIso(opts?.since),
+        });
+    }
+
+    async getFleetRetrievalUsage(opts) {
+        return this.api.call("getFleetRetrievalUsage", {
+            includeDeleted: opts?.includeDeleted,
+            since: toIso(opts?.since),
+        });
+    }
+
+    async getSessionFactsStats(sessionId) {
+        return this.api.call("getSessionFactsStats", { sessionId });
+    }
+
+    async getSessionTreeFactsStats(sessionId) {
+        return this.api.call("getSessionTreeFactsStats", { sessionId });
+    }
+
+    async getSharedFactsStats() {
+        return this.api.call("getSharedFactsStats");
+    }
+
+    async getFactsTombstoneStats(opts = {}) {
+        return this.api.call("getFactsTombstoneStats", { ttlSeconds: opts.ttlSeconds });
+    }
+
+    async pruneDeletedSummaries(olderThan) {
+        return this.api.call("pruneDeletedSummaries", { olderThan: toIso(olderThan) });
+    }
+
+    // ── User profile ────────────────────────────────────────────────────
+
+    async getCurrentUserProfile() {
+        return this.api.call("getCurrentUserProfile");
+    }
+
+    async setCurrentUserProfileSettings({ settings } = {}) {
+        return this.api.call("setCurrentUserProfileSettings", {
+            settings: settings && typeof settings === "object" && !Array.isArray(settings) ? settings : {},
+        });
+    }
+
+    async setCurrentUserGitHubCopilotKey({ key } = {}) {
+        return this.api.call("setCurrentUserGitHubCopilotKey", {
+            key: typeof key === "string" ? key : null,
+        });
+    }
+
+    // ── Models ──────────────────────────────────────────────────────────
+
+    async listModels() {
+        return this.api.call("listModels");
+    }
+
+    // ── Events / history ────────────────────────────────────────────────
+
+    async getSessionEvents(sessionId, afterSeq, limit) {
+        return this.api.call("getSessionEvents", { sessionId, afterSeq, limit });
+    }
+
+    async getSessionEventsBefore(sessionId, beforeSeq, limit) {
+        return this.api.call("getSessionEventsBefore", { sessionId, beforeSeq, limit });
+    }
+
+    async getExecutionHistory(sessionId, executionId) {
+        return this.api.call("getExecutionHistory", { sessionId, executionId });
+    }
+
+    async exportExecutionHistory(sessionId) {
+        return this.api.call("exportExecutionHistory", { sessionId });
+    }
+
+    // ── Artifacts ───────────────────────────────────────────────────────
+
+    async listArtifacts(sessionId) {
+        return this.api.call("listArtifacts", { sessionId });
+    }
+
+    async getArtifactMetadata(sessionId, filename) {
+        return this.api.call("getArtifactMetadata", { sessionId, filename });
+    }
+
+    async deleteArtifact(sessionId, filename) {
+        return this.api.call("deleteArtifact", { sessionId, filename });
+    }
+
+    async downloadArtifact(sessionId, filename) {
+        return this.api.call("downloadArtifact", { sessionId, filename });
+    }
+
+    async uploadArtifactContent(sessionId, filename, content, contentType, contentEncoding) {
+        return this.api.call("uploadArtifact", { sessionId, filename, content, contentType, contentEncoding });
+    }
+
+    getArtifactExportDirectory() {
+        return this.artifactExportDirectory || "Downloads";
+    }
+
+    // ── Streaming ───────────────────────────────────────────────────────
+
+    subscribeSession(sessionId, handler) {
+        return this.api.subscribeSession(sessionId, handler);
+    }
+
+    startLogTail(handler) {
+        return this.api.subscribeLogs(handler);
+    }
+}

package/api/src/protocol.js

@@ -0,0 +1,230 @@
+/**
+ * The PilotSwarm Web API protocol: one table describing every JSON operation
+ * under `/api/v1`, plus the WebSocket vocabulary and the error envelope.
+ *
+ * This table is the single source of truth for the contract. The portal
+ * server generates its Express routes from it, `ApiClient` builds requests
+ * from it, and `docs/api/reference.md` documents it. Operation names are
+ * exactly the method names of the portal runtime dispatcher
+ * (`packages/app/web/runtime.js`), which stays the single behavior point.
+ *
+ * Param placement (`in`):
+ *   - "path"  — URL path segment (`:name` in the template)
+ *   - "query" — query string; `type` drives server-side coercion
+ *   - "body"  — JSON request body field
+ * Param types: "string" (default) | "number" | "boolean" | "json".
+ * "json" query params carry JSON-encoded values (e.g. the paging cursor).
+ */
+
+export const API_PREFIX = "/api/v1";
+export const API_VERSION = 1;
+
+/** WebSocket endpoint path (auth: Bearer header or ["access_token", <token>] subprotocol). */
+export const WS_PATH = "/api/v1/ws";
+
+/** WebSocket message vocabulary (same as the legacy /portal-ws, minus theme). */
+export const WS_CLIENT_MESSAGES = ["subscribeSession", "unsubscribeSession", "subscribeLogs", "unsubscribeLogs"];
+export const WS_SERVER_MESSAGES = ["ready", "subscribedSession", "sessionEvent", "subscribedLogs", "logEntry", "error"];
+
+/** Error code used when an SDK web-mode method has no API equivalent. */
+export const WEB_MODE_UNSUPPORTED = "WEB_MODE_UNSUPPORTED";
+
+const path = (name) => ({ in: "path", name });
+const query = (type = "string") => ({ in: "query", type });
+const body = () => ({ in: "body" });
+
+/**
+ * @type {Array<{
+ *   name: string,
+ *   method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE",
+ *   path: string,
+ *   params?: Record<string, { in: "path"|"query"|"body", name?: string, type?: string }>,
+ *   summary: string,
+ * }>}
+ */
+export const OPERATIONS = [
+    // ── Sessions (client surface) ───────────────────────────────────────
+    { name: "listSessions", method: "GET", path: "/sessions", summary: "List session summaries." },
+    { name: "createSession", method: "POST", path: "/sessions", params: { model: body(), reasoningEffort: body(), groupId: body() }, summary: "Create a session. Owner is the authenticated principal." },
+    { name: "createSessionForAgent", method: "POST", path: "/sessions/for-agent", params: { agentName: body(), model: body(), reasoningEffort: body(), title: body(), splash: body(), initialPrompt: body(), groupId: body() }, summary: "Create a session bound to a named agent." },
+    { name: "getSession", method: "GET", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Get one session view (live orchestration status)." },
+    { name: "deleteSession", method: "DELETE", path: "/sessions/:sessionId", params: { sessionId: path("sessionId") }, summary: "Cancel and soft-delete a session." },
+    { name: "sendMessage", method: "POST", path: "/sessions/:sessionId/messages", params: { sessionId: path("sessionId"), prompt: body(), options: body() }, summary: "Send a prompt (options: { enqueueOnly?, clientMessageIds? })." },
+    { name: "sendAnswer", method: "POST", path: "/sessions/:sessionId/answers", params: { sessionId: path("sessionId"), answer: body() }, summary: "Answer a pending input-required question." },
+    { name: "sendSessionEvent", method: "POST", path: "/sessions/:sessionId/events", params: { sessionId: path("sessionId"), eventName: body(), data: body() }, summary: "Send a custom event into the session." },
+    { name: "cancelPendingMessage", method: "POST", path: "/sessions/:sessionId/cancel-pending", params: { sessionId: path("sessionId"), clientMessageIds: body() }, summary: "Cancel queued messages by client message ids." },
+
+    // ── Session artifacts (JSON surface; binary download is a bespoke route) ──
+    { name: "listArtifacts", method: "GET", path: "/sessions/:sessionId/artifacts", params: { sessionId: path("sessionId") }, summary: "List artifacts for a session." },
+    { name: "getArtifactMetadata", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/meta", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact metadata." },
+    { name: "downloadArtifact", method: "GET", path: "/sessions/:sessionId/artifacts/:filename/text", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Artifact content as text (JSON envelope). Binary: GET …/download." },
+    { name: "uploadArtifact", method: "PUT", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename"), content: body(), contentType: body(), contentEncoding: body() }, summary: "Upload artifact content (base64 for binary; 2 MB JSON limit)." },
+    { name: "deleteArtifact", method: "DELETE", path: "/sessions/:sessionId/artifacts/:filename", params: { sessionId: path("sessionId"), filename: path("filename") }, summary: "Delete an artifact." },
+
+    // ── Management: sessions ────────────────────────────────────────────
+    { name: "listSessionsPage", method: "GET", path: "/management/sessions", params: { limit: query("number"), cursor: query("json"), includeDeleted: query("boolean") }, summary: "Keyset-paginated session listing." },
+    { name: "renameSession", method: "PATCH", path: "/management/sessions/:sessionId", params: { sessionId: path("sessionId"), title: body() }, summary: "Rename a session." },
+    { name: "cancelSession", method: "POST", path: "/management/sessions/:sessionId/cancel", params: { sessionId: path("sessionId") }, summary: "Cancel a session." },
+    { name: "completeSession", method: "POST", path: "/management/sessions/:sessionId/complete", params: { sessionId: path("sessionId"), reason: body() }, summary: "Mark a session completed." },
+    { name: "stopSessionTurn", method: "POST", path: "/management/sessions/:sessionId/stop-turn", params: { sessionId: path("sessionId"), options: body() }, summary: "Abort the in-flight turn." },
+    { name: "setSessionModel", method: "POST", path: "/management/sessions/:sessionId/model", params: { sessionId: path("sessionId"), options: body() }, summary: "Switch the session model ({ model, reasoningEffort? })." },
+    { name: "restartSystemSession", method: "POST", path: "/management/sessions/:agentIdOrSessionId/restart-system", params: { agentIdOrSessionId: path("agentIdOrSessionId"), options: body() }, summary: "Restart a system session (complete | terminate | hard_delete)." },
+    { name: "exportExecutionHistory", method: "POST", path: "/management/sessions/:sessionId/export-execution-history", params: { sessionId: path("sessionId") }, summary: "Export execution history to an artifact; returns artifact meta." },
+    { name: "getSessionStatus", method: "GET", path: "/management/sessions/:sessionId/status", params: { sessionId: path("sessionId") }, summary: "Live custom status + orchestration status." },
+    { name: "waitForStatusChange", method: "GET", path: "/management/sessions/:sessionId/status/wait", params: { sessionId: path("sessionId"), afterVersion: query("number"), timeoutMs: query("number") }, summary: "Long-poll for a status version change (server-capped timeout)." },
+    { name: "getLatestResponse", method: "GET", path: "/management/sessions/:sessionId/latest-response", params: { sessionId: path("sessionId") }, summary: "Latest turn response payload, if any." },
+    { name: "getOrchestrationStats", method: "GET", path: "/management/sessions/:sessionId/orchestration-stats", params: { sessionId: path("sessionId") }, summary: "Orchestration runtime stats." },
+    { name: "getExecutionHistory", method: "GET", path: "/management/sessions/:sessionId/execution-history", params: { sessionId: path("sessionId"), executionId: query("number") }, summary: "Raw execution history events." },
+    { name: "getSessionEvents", method: "GET", path: "/management/sessions/:sessionId/events", params: { sessionId: path("sessionId"), afterSeq: query("number"), limit: query("number") }, summary: "Session events after a sequence number (reconnect catch-up)." },
+    { name: "getSessionEventsBefore", method: "GET", path: "/management/sessions/:sessionId/events-before", params: { sessionId: path("sessionId"), beforeSeq: query("number"), limit: query("number") }, summary: "Older session events for history paging." },
+    { name: "getSessionMetricSummary", method: "GET", path: "/management/sessions/:sessionId/metric-summary", params: { sessionId: path("sessionId") }, summary: "Per-session metric summary." },
+    { name: "getSessionTokensByModel", method: "GET", path: "/management/sessions/:sessionId/tokens-by-model", params: { sessionId: path("sessionId") }, summary: "Token totals grouped by model." },
+    { name: "getSessionTreeStats", method: "GET", path: "/management/sessions/:sessionId/tree-stats", params: { sessionId: path("sessionId") }, summary: "Stats rolled up across the spawn tree." },
+    { name: "getSessionSkillUsage", method: "GET", path: "/management/sessions/:sessionId/skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage for one session." },
+    { name: "getSessionTreeSkillUsage", method: "GET", path: "/management/sessions/:sessionId/tree-skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage across the spawn tree." },
+    { name: "getSessionFactsStats", method: "GET", path: "/management/sessions/:sessionId/facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats for one session." },
+    { name: "getSessionTreeFactsStats", method: "GET", path: "/management/sessions/:sessionId/tree-facts-stats", params: { sessionId: path("sessionId") }, summary: "Facts stats across the spawn tree." },
+    { name: "listChildOutcomes", method: "GET", path: "/management/sessions/:parentSessionId/child-outcomes", params: { parentSessionId: path("parentSessionId") }, summary: "Child outcomes recorded under a parent session." },
+    { name: "getChildOutcome", method: "GET", path: "/management/child-outcomes/:childSessionId", params: { childSessionId: path("childSessionId") }, summary: "One child outcome." },
+
+    // ── Management: session groups ──────────────────────────────────────
+    { name: "listSessionGroups", method: "GET", path: "/management/session-groups", summary: "List session groups." },
+    { name: "createSessionGroup", method: "POST", path: "/management/session-groups", params: { input: body() }, summary: "Create a session group." },
+    { name: "updateSessionGroup", method: "PATCH", path: "/management/session-groups/:groupId", params: { groupId: path("groupId"), patch: body() }, summary: "Update group title/description." },
+    { name: "deleteSessionGroup", method: "DELETE", path: "/management/session-groups/:groupId", params: { groupId: path("groupId") }, summary: "Delete an empty session group." },
+    { name: "assignSessionsToGroup", method: "POST", path: "/management/session-groups/:groupId/assign", params: { groupId: path("groupId"), sessionIds: body() }, summary: "Assign sessions to a group." },
+    { name: "cancelSessionGroup", method: "POST", path: "/management/session-groups/:groupId/cancel", params: { groupId: path("groupId"), reason: body() }, summary: "Cancel all sessions in a group." },
+    { name: "completeSessionGroup", method: "POST", path: "/management/session-groups/:groupId/complete", params: { groupId: path("groupId"), options: body() }, summary: "Complete all sessions in a group." },
+    { name: "moveSessionsToGroup", method: "POST", path: "/management/session-groups/move", params: { groupId: body(), sessionIds: body() }, summary: "Move sessions between groups (groupId null = ungroup)." },
+
+    // ── Management: fleet / users / facts / events ──────────────────────
+    { name: "getFleetStats", method: "GET", path: "/management/fleet/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide stats." },
+    { name: "getFleetSkillUsage", method: "GET", path: "/management/fleet/skill-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide skill usage." },
+    { name: "getFleetRetrievalUsage", method: "GET", path: "/management/fleet/retrieval-usage", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Fleet-wide retrieval usage." },
+    { name: "getUserStats", method: "GET", path: "/management/users/stats", params: { since: query("string"), includeDeleted: query("boolean") }, summary: "Per-user stats." },
+    { name: "getSharedFactsStats", method: "GET", path: "/management/facts/shared-stats", summary: "Shared facts stats." },
+    { name: "getFactsTombstoneStats", method: "GET", path: "/management/facts/tombstone-stats", params: { ttlSeconds: query("number") }, summary: "Soft-deleted facts awaiting reconciliation." },
+    { name: "getTopEventEmitters", method: "GET", path: "/management/events/top-emitters", params: { since: query("string"), limit: query("number") }, summary: "Noisiest event emitters since a date." },
+    { name: "pruneDeletedSummaries", method: "POST", path: "/management/summaries/prune-deleted", params: { olderThan: body() }, summary: "Prune summaries of deleted sessions." },
+
+    // ── Facts data-plane (Tier 1: any admitted caller) ──────────────────
+    { name: "factsCapabilities", method: "GET", path: "/facts/capabilities", summary: "Store capabilities: { search, embedder, graph } — the remote isEnhancedFactStore/isGraphStore." },
+    { name: "readFacts", method: "GET", path: "/facts", params: { keyPattern: query("string"), scopeKeys: query("json"), tags: query("json"), sessionId: query("string"), agentId: query("string"), limit: query("number"), scope: query("string") }, summary: "Read facts (ReadFactsQuery params)." },
+    { name: "storeFact", method: "POST", path: "/facts", params: { input: body() }, summary: "Store a fact or facts (StoreFactInput | StoreFactInput[])." },
+    { name: "deleteFact", method: "POST", path: "/facts/delete", params: { input: body() }, summary: "Delete a fact / pattern (DeleteFactInput). POST because DELETE bodies are unreliable." },
+    { name: "searchFacts", method: "POST", path: "/facts/search", params: { query: body(), opts: body() }, summary: "Retrieval over facts (lexical | semantic | hybrid). [enhanced]" },
+    { name: "similarFacts", method: "POST", path: "/facts/similar", params: { scopeKey: body(), opts: body() }, summary: "Semantic nearest-neighbours of a known fact. [enhanced]" },
+
+    // ── Facts operational (Tier 2: admin) ───────────────────────────────
+    { name: "getEmbedderStatus", method: "GET", path: "/facts/embedder", summary: "Durable embedder status. [enhanced]" },
+    { name: "startFactsEmbedder", method: "POST", path: "/facts/embedder/start", params: { intervalSeconds: body(), batch: body() }, admin: true, summary: "Start the durable embedder loop. [enhanced, admin]" },
+    { name: "stopFactsEmbedder", method: "POST", path: "/facts/embedder/stop", params: { reason: body() }, admin: true, summary: "Stop the durable embedder loop. [enhanced, admin]" },
+    { name: "forcePurgeFacts", method: "POST", path: "/facts/purge", params: { input: body() }, admin: true, summary: "Force-purge soft-deleted facts (ForcePurgeFactsInput). [admin]" },
+
+    // ── Graph data-plane (Tier 1: any admitted caller) ──────────────────
+    { name: "searchGraphNodes", method: "POST", path: "/graph/nodes/search", params: { query: body() }, summary: "Search graph nodes (GraphNodeQuery)." },
+    { name: "searchGraphEdges", method: "POST", path: "/graph/edges/search", params: { query: body() }, summary: "Search graph edges (GraphEdgeQuery)." },
+    { name: "graphNeighbourhood", method: "POST", path: "/graph/neighbourhood", params: { nodeKey: body(), depth: body(), namespace: body() }, summary: "Expand a subgraph around a node." },
+    { name: "upsertGraphNode", method: "POST", path: "/graph/nodes", params: { input: body() }, summary: "Upsert a graph node (GraphNodeInput)." },
+    { name: "upsertGraphEdge", method: "POST", path: "/graph/edges", params: { input: body() }, summary: "Upsert a graph edge (GraphEdgeInput)." },
+    { name: "deleteGraphNode", method: "POST", path: "/graph/nodes/delete", params: { nodeKey: body(), namespace: body() }, summary: "Delete a graph node." },
+    { name: "deleteGraphEdge", method: "POST", path: "/graph/edges/delete", params: { fromKey: body(), toKey: body(), predicateKey: body(), namespace: body() }, summary: "Delete a graph edge." },
+    { name: "graphStats", method: "GET", path: "/graph/stats", params: { namespace: query("string") }, summary: "Graph node/edge counts." },
+    { name: "listGraphNamespaces", method: "GET", path: "/graph/namespaces", params: { prefix: query("string"), includeArchived: query("boolean"), includeDetails: query("boolean") }, summary: "List graph namespaces (corpora)." },
+    { name: "getGraphNamespace", method: "GET", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, summary: "One graph namespace descriptor." },
+
+    // ── Graph operational (Tier 2: admin) ───────────────────────────────
+    { name: "upsertGraphNamespace", method: "POST", path: "/graph/namespaces", params: { input: body() }, admin: true, summary: "Register/update a graph namespace. [admin]" },
+    { name: "deleteGraphNamespace", method: "DELETE", path: "/graph/namespaces/:namespace", params: { namespace: path("namespace") }, admin: true, summary: "Delete a graph namespace and its data. [admin]" },
+
+    // ── Models / agents / policy ────────────────────────────────────────
+    { name: "listModels", method: "GET", path: "/models", summary: "All available models." },
+    { name: "getModelsByProvider", method: "GET", path: "/models/by-provider", summary: "Models grouped by provider." },
+    { name: "getDefaultModel", method: "GET", path: "/models/default", summary: "The deployment default model." },
+    { name: "listCreatableAgents", method: "GET", path: "/agents", summary: "Agents sessions can be created for." },
+    { name: "getSessionCreationPolicy", method: "GET", path: "/session-creation-policy", summary: "Session creation policy." },
+
+    // ── Current user profile ────────────────────────────────────────────
+    { name: "getCurrentUserProfile", method: "GET", path: "/me/profile", summary: "Profile of the authenticated principal." },
+    { name: "setCurrentUserProfileSettings", method: "PATCH", path: "/me/profile/settings", params: { settings: body() }, summary: "Replace profile settings." },
+    { name: "setCurrentUserGitHubCopilotKey", method: "PUT", path: "/me/github-copilot-key", params: { key: body() }, summary: "Set (or clear with null) the per-user GitHub Copilot key." },
+
+    // ── System ──────────────────────────────────────────────────────────
+    { name: "getLogConfig", method: "GET", path: "/system/log-config", summary: "Log tail availability." },
+    { name: "getWorkerCount", method: "GET", path: "/system/workers", summary: "Live worker count." },
+];
+
+const OPERATIONS_BY_NAME = new Map(OPERATIONS.map((op) => [op.name, op]));
+
+export function getOperation(name) {
+    return OPERATIONS_BY_NAME.get(name) || null;
+}
+
+/**
+ * Build the HTTP request for an operation from an rpc-shaped params object
+ * (the exact shapes the legacy /api/rpc dispatcher accepts).
+ *
+ * @returns {{ method: string, path: string, query: URLSearchParams, body: object|null }}
+ */
+export function buildOperationRequest(name, params = {}) {
+    const op = getOperation(name);
+    if (!op) throw new Error(`Unknown API operation: ${name}`);
+    const safeParams = params && typeof params === "object" ? params : {};
+
+    let resolvedPath = op.path;
+    const queryParams = new URLSearchParams();
+    let bodyPayload = null;
+
+    for (const [key, spec] of Object.entries(op.params || {})) {
+        const value = safeParams[key];
+        if (spec.in === "path") {
+            const raw = value == null ? "" : String(value);
+            if (!raw) throw new Error(`API operation ${name} requires param '${key}'`);
+            resolvedPath = resolvedPath.replace(`:${spec.name || key}`, encodeURIComponent(raw));
+        } else if (spec.in === "query") {
+            if (value === undefined || value === null) continue;
+            queryParams.set(key, spec.type === "json" ? JSON.stringify(value) : String(value));
+        } else {
+            if (value === undefined) continue;
+            if (!bodyPayload) bodyPayload = {};
+            bodyPayload[key] = value;
+        }
+    }
+
+    if (resolvedPath.includes("/:")) {
+        throw new Error(`API operation ${name} is missing required path params (${op.path})`);
+    }
+    return { method: op.method, path: `${API_PREFIX}${resolvedPath}`, query: queryParams, body: bodyPayload };
+}
+
+/** Coerce a query-string value per the declared param type (server side). */
+export function coerceQueryValue(value, type) {
+    if (value === undefined || value === null) return undefined;
+    if (type === "number") {
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : undefined;
+    }
+    if (type === "boolean") return value === "true" || value === true;
+    if (type === "json") {
+        try {
+            return JSON.parse(String(value));
+        } catch {
+            throw Object.assign(new Error("Malformed JSON query parameter"), { code: "INVALID_REQUEST" });
+        }
+    }
+    return String(value);
+}
+
+/** Path for the raw (streaming) artifact download route. */
+export function artifactDownloadPath(sessionId, filename) {
+    return `${API_PREFIX}/sessions/${encodeURIComponent(String(sessionId || ""))}/artifacts/${encodeURIComponent(String(filename || ""))}/download`;
+}
+
+export class ApiError extends Error {
+    constructor(message, { code = "INTERNAL_ERROR", status = 500 } = {}) {
+        super(message);
+        this.name = "ApiError";
+        this.code = code;
+        this.status = status;
+    }
+}

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { PilotSwarmClientOptions, ManagedSessionConfig, PilotSwarmSessionInfo, UserInputHandler, SessionOwnerInfo } from "./types.js";
 import type { SessionCatalog, SessionEvent } from "./cms.js";
+import { type PilotSwarmWebOptions } from "./web/api-connection.js";
 /**
  * PilotSwarmClient — pure client-side session handle.
  *
@@ -35,7 +36,7 @@ export declare class PilotSwarmClient {
     private get _sessionPolicy();
     /** Allowed agent names (set via config from worker). */
     private get _allowedAgentNames();
-    constructor(options: PilotSwarmClientOptions);
+    constructor(options: PilotSwarmClientOptions | PilotSwarmWebOptions);
     createSession(config?: ManagedSessionConfig & {
         sessionId?: string;
         onUserInputRequest?: UserInputHandler;

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -3,6 +3,8 @@ import { DURABLE_SESSION_LATEST_VERSION, DURABLE_SESSION_ORCHESTRATION_NAME, } f
 import { resolveStorageConfig } from "./storage-config.js";
 import { getDuroxideStorageProvider, getRuntimeStorageProvider } from "./storage-providers.js";
 import { deriveStatusFromCmsAndRuntime, shouldSyncCompletedStatus, shouldSyncFailedStatus } from "./session-status.js";
+import { assertUnambiguousProvider, isWebOptions } from "./web/api-connection.js";
+import { WebPilotSwarmClient } from "./web/web-client.js";
 // duroxide is CommonJS — use createRequire for ESM compatibility
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
@@ -60,6 +62,13 @@ export class PilotSwarmClient {
         return this.config.allowedAgentNames ?? [];
     }
     constructor(options) {
+        assertUnambiguousProvider(options, "PilotSwarmClient");
+        if (isWebOptions(options)) {
+            // Web mode — the supported public mode: talk to a deployment's
+            // Web API instead of the datastore. The returned object carries
+            // the same session-handle programming model (WebPilotSwarmClient).
+            return new WebPilotSwarmClient(options);
+        }
         this.config = {
             ...options,
             waitThreshold: options.waitThreshold ?? 30,