pilotswarm 0.5.28 → 0.5.30

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

@@ -17,6 +17,14 @@ import {
     ATTACHMENT_MAX_BYTES,
     ATTACHMENTS_MAX_COUNT,
     ATTACHMENTS_MAX_TOTAL_BYTES,
+    PgSessionCatalog,
+    publishAgentPackageDir,
+    deleteAgentPackageEverywhere,
+    fetchAgentPackageTarGz,
+    readAgentPackageTarGz,
+    listBundledAgentNames,
+    normalizeAgentName,
+    AgentPackageValidationError,
 } from "pilotswarm-sdk";
 import { startEmbeddedWorkers, stopEmbeddedWorkers } from "./embedded-workers.js";
 import { getPluginDirsFromEnv } from "./plugin-config.js";
@@ -604,7 +612,10 @@ export class NodeSdkTransport {
             this.client ? this.client.stop() : Promise.resolve(),
             this.mgmt.stop(),
             stopEmbeddedWorkers(this.workers),
+            this._agentPkgCatalog ? this._agentPkgCatalog.close() : Promise.resolve(),
         ]);
+        this._agentPkgCatalog = null;
+        this._agentPkgCatalogPromise = null;
         this.client = null;
     }
 
@@ -623,6 +634,374 @@ export class NodeSdkTransport {
         return loadSessionCreationMetadataFromPluginDirs(getPluginDirsFromEnv());
     }
 
+    async listCreatableAgents(viewer = null, isAdmin = true) {
+        const baked = this.creatableAgents.map((agent) => ({ ...agent, source: "builtin" }));
+        const registry = await this._listRegistryCreatableAgents(viewer, isAdmin);
+        // Baked agents are deployment code — they win a (normalized) name
+        // collision; the colliding registry entry is dropped, matching the
+        // validator that refuses such packages going forward.
+        const taken = new Set(baked.map((agent) => normalizeAgentName(agent.name)));
+        const merged = [...baked];
+        for (const entry of registry) {
+            if (taken.has(normalizeAgentName(entry.name))) {
+                // Baked wins by design — but never silently: the package's
+                // agent is unreachable until it renames.
+                console.warn(`[transport] package agent "${entry.name}" (${entry.packageName}) collides with a baked agent and is hidden from the catalog`);
+                continue;
+            }
+            taken.add(normalizeAgentName(entry.name));
+            merged.push(entry);
+        }
+        return merged;
+    }
+
+    /** Registry package agents as creatable-agent entries, viewer-scoped. */
+    async _listRegistryCreatableAgents(viewer, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) return [];
+        try {
+            const packages = await ctx.catalog.listAgentPackages(
+                viewer ? { provider: viewer.provider, subject: viewer.subject } : null,
+                Boolean(isAdmin),
+            );
+            // Ownership is decided HERE, where the viewer's identity is known.
+            // An ADMIN sees every user's user-scoped packages, so "scope is
+            // user" does not mean "mine" — grouping on scope alone filed other
+            // people's agents onto the caller's shelf. Sending a boolean rather
+            // than the owner's identifiers keeps the catalog from telling every
+            // caller who installed what. No viewer at all (single-user or
+            // auth-disabled) means any user-scoped package is the caller's.
+            const principalKey = (principal) => (principal?.provider && principal?.subject
+                ? `${principal.provider}:${principal.subject}`.toLowerCase()
+                : null);
+            const viewerKey = principalKey(viewer);
+            const entries = [];
+            for (const pkg of packages) {
+                if (!pkg.enabled || !pkg.active) continue;
+                const ownerKey = principalKey(pkg.owner);
+                const mine = pkg.scope === "user" && (viewerKey === null || ownerKey === viewerKey);
+                const agents = Array.isArray(pkg.active.manifest?.agents) ? pkg.active.manifest.agents : [];
+                for (const agent of agents) {
+                    if (!agent?.name) continue;
+                    entries.push({
+                        name: agent.name,
+                        title: agent.title || undefined,
+                        description: agent.description || undefined,
+                        tools: Array.isArray(agent.tools) ? agent.tools : undefined,
+                        // Carried so a PACKAGE agent presents itself like a
+                        // baked one: the picker sends these with the create
+                        // call, so without them a package agent could neither
+                        // self-start (initialPrompt) nor show its own splash.
+                        splash: typeof agent.splash === "string" && agent.splash.trim() ? agent.splash : undefined,
+                        splashMobile: typeof agent.splashMobile === "string" && agent.splashMobile.trim() ? agent.splashMobile : undefined,
+                        initialPrompt: typeof agent.initialPrompt === "string" && agent.initialPrompt.trim() ? agent.initialPrompt : undefined,
+                        source: "package",
+                        packageName: pkg.name,
+                        packageSemver: pkg.active.semver,
+                        scope: pkg.scope,
+                        mine,
+                        ownerLabel: pkg.createdBy || pkg.owner?.subject || null,
+                    });
+                }
+            }
+            return entries;
+        } catch (err) {
+            console.warn(`[transport] agent-package catalog unavailable: ${err?.message || err}`);
+            return [];
+        }
+    }
+
+    /**
+     * Enforce user-scope visibility at create time and admit package agents
+     * into the client's live allowlist. Baked agents pass through untouched.
+     */
+    async _authorizePackageAgentCreate(agentName, owner, isAdmin) {
+        const normalized = normalizeAgentName(agentName);
+        const baked = this.creatableAgents.find((agent) => normalizeAgentName(agent.name) === normalized);
+        if (baked) return baked.name;
+        const registry = await this._listRegistryCreatableAgents(owner, isAdmin);
+        const match = registry.find((entry) => normalizeAgentName(entry.name) === normalized);
+        if (!match) {
+            // Either the agent doesn't exist or it is a user-scope package the
+            // caller can't see — same answer either way (no existence oracle).
+            const err = new Error(`agent "${agentName}" is not available to you`);
+            err.code = "FORBIDDEN";
+            throw err;
+        }
+        // Client holds this.allowedAgentNames BY REFERENCE (live getter) —
+        // pushing here makes the delegated create pass client validation.
+        if (this.allowedAgentNames.length > 0 && !this.allowedAgentNames.includes(match.name)) {
+            this.allowedAgentNames.push(match.name);
+        }
+        return match.name;
+    }
+
+    /**
+     * Lazy direct-store registry context; null in pure web/client setups AND
+     * on init failure. A failed init is NEVER cached — the portal boots
+     * alongside 8 workers all polling the migration advisory lock, and one
+     * transient contention loss must not permanently reduce the catalog to
+     * baked agents (observed live: a cached rejection made every later
+     * listCreatableAgents union silently registry-less until pod restart).
+     */
+    async _agentPackagesContext() {
+        if (!this.store || !this.artifactStore) return null;
+        if (this._agentPkgCatalog) {
+            return { catalog: this._agentPkgCatalog, artifactStore: this.artifactStore };
+        }
+        try {
+            this._agentPkgCatalogPromise ??= (async () => {
+                const catalog = await PgSessionCatalog.create(this.store, process.env.PILOTSWARM_CMS_SCHEMA || undefined, {
+                    ...(this.useManagedIdentity !== undefined ? { useManagedIdentity: this.useManagedIdentity } : {}),
+                    ...(this.aadDbUser ? { aadUser: this.aadDbUser } : {}),
+                });
+                await catalog.initialize();
+                this._agentPkgCatalog = catalog;
+                return catalog;
+            })();
+            await this._agentPkgCatalogPromise;
+        } catch (err) {
+            this._agentPkgCatalogPromise = null;
+            console.warn(`[transport] agent-package registry init failed (will retry on next call): ${err?.message || err}`);
+            return null;
+        }
+        return { catalog: this._agentPkgCatalog, artifactStore: this.artifactStore };
+    }
+
+    _requirePrincipal(owner, isAdmin) {
+        if (owner) return { provider: owner.provider, subject: owner.subject };
+        if (isAdmin) return null;   // anonymous deployments: admin-equivalent
+        const err = new Error("agent-package operations require an authenticated principal");
+        err.code = "FORBIDDEN";
+        throw err;
+    }
+
+    _createdByLabel(owner) {
+        return owner?.email || owner?.displayName || (owner ? `${owner.provider}:${owner.subject}` : "system");
+    }
+
+    /**
+     * The registry raises typed failures as MESSAGE PREFIXES
+     * (AGENT_PACKAGE_FORBIDDEN: …). Attach the matching error.code so the
+     * router maps them to 403/404/409 instead of a generic 500 — without
+     * this, "you don't own this package" reaches the browser as
+     * "Internal server error".
+     */
+    async _mapAgentPackageErrors(run) {
+        try {
+            return await run();
+        } catch (error) {
+            const message = String(error?.message || "");
+            if (!error?.code) {
+                if (/AGENT_(?:PACKAGE|SOURCE)_[A-Z_]*FORBIDDEN/.test(message)) error.code = "FORBIDDEN";
+                else if (/AGENT_(?:PACKAGE|SOURCE)_[A-Z_]*NOT_FOUND/.test(message)) error.code = "NOT_FOUND";
+                else if (/AGENT_PACKAGE_(?:SEMVER_CONFLICT|SCOPE_MISMATCH)/.test(message)) error.code = "CONFLICT";
+                else if (/AGENT_PACKAGE_BAD_SCOPE/.test(message)) error.code = "INVALID_REQUEST";
+            }
+            throw error;
+        }
+    }
+
+    // ── Agent packages: registry CRUD (portal ops surface) ──────
+
+    async listAgentPackages(owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) return [];
+        return ctx.catalog.listAgentPackages(this._requirePrincipal(owner, isAdmin), Boolean(isAdmin));
+    }
+
+    async getAgentPackage(name, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) return null;
+        return ctx.catalog.getAgentPackage(name, this._requirePrincipal(owner, isAdmin), Boolean(isAdmin));
+    }
+
+
+
+
+
+    async listAgentWorkerState() {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) return [];
+        return ctx.catalog.listAgentWorkerState();
+    }
+
+    async listWorkers() {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) return [];
+        return ctx.catalog.listWorkers();
+    }
+
+    async setAgentPackageScope(name, scope, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        await this._mapAgentPackageErrors(() => ctx.catalog.setAgentPackageScope(name, scope === "shared" ? "shared" : "user",
+            this._requirePrincipal(owner, isAdmin), Boolean(isAdmin)));
+        return { ok: true };
+    }
+
+    async setAgentPackageEnabled(name, enabled, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        await this._mapAgentPackageErrors(() => ctx.catalog.setAgentPackageEnabled(name, Boolean(enabled),
+            this._requirePrincipal(owner, isAdmin), Boolean(isAdmin)));
+        return { ok: true };
+    }
+
+    async pinAgentPackageVersion(name, semver, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        await this._mapAgentPackageErrors(() => ctx.catalog.pinAgentPackageVersion(name, String(semver || ""),
+            this._requirePrincipal(owner, isAdmin), Boolean(isAdmin)));
+        return { ok: true };
+    }
+
+    async deleteAgentPackage(name, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        await this._mapAgentPackageErrors(() => deleteAgentPackageEverywhere(ctx, name, this._requirePrincipal(owner, isAdmin), Boolean(isAdmin)));
+        this._agentPkgTarCache?.clear?.();
+        return { ok: true };
+    }
+
+    /** Inline-files upload → the one publish pipeline. ≤ 2 MB decoded. */
+    async uploadAgentPackage(files, scope, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        const principal = this._requirePrincipal(owner, isAdmin);
+        if (!Array.isArray(files) || files.length === 0) {
+            throw new Error("upload requires files: [{ path, contentBase64 }]");
+        }
+        if (files.length > 2000) throw new Error("upload exceeds 2000 files");
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ps-agent-upload-"));
+        try {
+            let total = 0;
+            for (const file of files) {
+                const rel = String(file?.path || "");
+                if (!rel || rel.startsWith("/") || rel.includes("\\") || rel.split("/").some((p) => p === "..")) {
+                    throw new Error(`upload file path is not a safe relative path: ${rel}`);
+                }
+                const bytes = Buffer.from(String(file?.contentBase64 || ""), "base64");
+                total += bytes.length;
+                if (total > 2 * 1024 * 1024) throw new Error("upload exceeds the 2 MB envelope — use a repo/url source or the CLI for larger packages");
+                const target = path.resolve(tmp, rel);
+                if (target !== tmp && !target.startsWith(tmp + path.sep)) {
+                    throw new Error(`upload file path escapes the package root: ${rel}`);
+                }
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, bytes);
+            }
+            const outcome = await this._mapAgentPackageErrors(() => publishAgentPackageDir(ctx, {
+                dir: tmp,
+                scope: scope === "shared" ? "shared" : "user",
+                owner: principal,
+                createdBy: this._createdByLabel(owner),
+                isAdmin: Boolean(isAdmin),
+                validate: { reservedAgentNames: this._reservedAgentNames() },
+            }));
+            const { manifest: _m, ...summary } = outcome;
+            return summary;
+        } catch (err) {
+            if (err instanceof AgentPackageValidationError) {
+                const wrapped = new Error(err.message);
+                wrapped.code = "VALIDATION_FAILED";
+                wrapped.validation = err.validation;
+                throw wrapped;
+            }
+            throw err;
+        } finally {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+
+    _reservedAgentNames() {
+        if (!this._reservedNamesCache) {
+            const bundled = (() => { try { return listBundledAgentNames(); } catch { return []; } })();
+            if (bundled.length === 0) {
+                // System agent names (sweeper, resourcemgr, …) live ONLY here —
+                // an empty list means packages could shadow them silently.
+                console.warn("[transport] listBundledAgentNames returned nothing — bundled plugins/ missing from the SDK install? Reserved-name validation is degraded.");
+            }
+            this._reservedNamesCache = [
+                ...bundled,
+                ...this.creatableAgents.map((agent) => agent.name),
+            ];
+        }
+        return this._reservedNamesCache;
+    }
+
+    // ── Agent packages: workspace viewer (tree + file preview) ──
+
+    async _agentPackageEntries(name, semver, owner, isAdmin) {
+        const ctx = await this._agentPackagesContext();
+        if (!ctx) throw new Error("agent packages are not available on this deployment");
+        const detail = await ctx.catalog.getAgentPackage(name, this._requirePrincipal(owner, isAdmin), Boolean(isAdmin));
+        if (!detail) throw Object.assign(new Error(`package "${name}" not found`), { code: "NOT_FOUND" });
+        const version = semver
+            ? detail.versions.find((v) => v.semver === semver)
+            : detail.versions.find((v) => v.versionId === detail.activeVersionId) ?? detail.versions[0];
+        if (!version) throw Object.assign(new Error(`package "${name}" has no ${semver ? `version ${semver}` : "versions"}`), { code: "NOT_FOUND" });
+        const cacheKey = `${name}@${version.semver}.${version.sha256.slice(0, 12)}`;
+        this._agentPkgTarCache ??= new Map();
+        let entries = this._agentPkgTarCache.get(cacheKey);
+        if (!entries) {
+            const targz = await this._mapAgentPackageErrors(
+                () => fetchAgentPackageTarGz(ctx.artifactStore, version.artifactFilename, version.sha256),
+            );
+            entries = readAgentPackageTarGz(targz);
+            this._agentPkgTarCache.set(cacheKey, entries);
+            // Bound by BYTES (the real resource), not just entry count.
+            const bytesOf = (list) => list.reduce((sum, e) => sum + e.body.length, 0);
+            let totalBytes = 0;
+            for (const cached of this._agentPkgTarCache.values()) totalBytes += bytesOf(cached);
+            while ((totalBytes > 64 * 1024 * 1024 || this._agentPkgTarCache.size > 6)
+                   && this._agentPkgTarCache.size > 1) {
+                const oldest = this._agentPkgTarCache.keys().next().value;
+                totalBytes -= bytesOf(this._agentPkgTarCache.get(oldest));
+                this._agentPkgTarCache.delete(oldest);
+            }
+        }
+        return { entries, version };
+    }
+
+    async getAgentPackageTree(name, semver, owner, isAdmin) {
+        const { entries, version } = await this._agentPackageEntries(name, semver, owner, isAdmin);
+        const dirs = new Set();
+        const files = [];
+        for (const entry of entries) {
+            files.push({ path: entry.name, size: entry.body.length });
+            const parts = entry.name.split("/");
+            for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/"));
+        }
+        files.sort((a, b) => (a.path < b.path ? -1 : 1));
+        return {
+            name,
+            semver: version.semver,
+            sha256: version.sha256,
+            dirs: [...dirs].sort(),
+            files,
+        };
+    }
+
+    async getAgentPackageFile(name, semver, filePath, owner, isAdmin) {
+        const { entries, version } = await this._agentPackageEntries(name, semver, owner, isAdmin);
+        const rel = String(filePath || "");
+        const entry = entries.find((candidate) => candidate.name === rel);
+        if (!entry) throw Object.assign(new Error(`"${rel}" is not in ${name}@${version.semver}`), { code: "NOT_FOUND" });
+        const MAX_PREVIEW = 256 * 1024;
+        const body = entry.body.subarray(0, MAX_PREVIEW);
+        const isBinary = body.includes(0);
+        return {
+            name,
+            semver: version.semver,
+            path: rel,
+            size: entry.body.length,
+            truncated: entry.body.length > MAX_PREVIEW,
+            encoding: isBinary ? "base64" : "utf8",
+            content: isBinary ? body.toString("base64") : body.toString("utf8"),
+        };
+    }
+
     getWorkerCount() {
         return this.workers.length || (this.mode === "remote" ? 0 : parseInt(process.env.WORKERS || "4", 10));
     }
@@ -1080,9 +1459,14 @@ export class NodeSdkTransport {
         return { sessionId: session.sessionId, model: effectiveModel, reasoningEffort: reasoningEffort || undefined, contextTier: contextTier || undefined };
     }
 
-    async createSessionForAgent(agentName, { model, reasoningEffort, contextTier, title, splash, splashMobile, initialPrompt, owner, groupId, visibility } = {}) {
+    async createSessionForAgent(agentName, { model, reasoningEffort, contextTier, title, splash, splashMobile, initialPrompt, owner, isAdmin, groupId, visibility } = {}) {
+        // Registry (package) agents are not in the static baked allowlist —
+        // resolve the union, enforce user-scope ownership, then delegate the
+        // CANONICAL catalog name (the client's allowlist and the CMS row use
+        // exact names; only the worker resolver is fuzzy).
+        const canonicalName = await this._authorizePackageAgentCreate(agentName, owner ?? null, isAdmin ?? false);
         const effectiveModel = await this.assertSessionModelCreatable({ model, owner });
-        const session = await this.client.createSessionForAgent(agentName, {
+        const session = await this.client.createSessionForAgent(canonicalName, {
             ...(effectiveModel ? { model: effectiveModel } : {}),
             ...(reasoningEffort ? { reasoningEffort } : {}),
             ...(contextTier ? { contextTier } : {}),
@@ -1103,9 +1487,6 @@ export class NodeSdkTransport {
         };
     }
 
-    listCreatableAgents() {
-        return [...this.creatableAgents];
-    }
 
     getSessionCreationPolicy() {
         return this.sessionPolicy;

package/tui/src/plugin-config.js

@@ -176,6 +176,15 @@ export function resolvePortalConfigBundleFromPluginDirs(pluginDirs = []) {
             loadingMessage: "Preparing your workspace",
             loadingCopy: "Connecting the shared workspace and live session feeds...",
         },
+        // Where "how do I build an agent package?" points. A layered
+        // deployment ships its OWN guide - the base instructions plus the
+        // skills, tools and MCP servers that exist only on that fleet - so
+        // this is config, not a constant. Public repo by default because the
+        // link is meant to be handed to a coding assistant, which cannot
+        // reach an intranet-only portal.
+        docs: {
+            agentPackageGuideUrl: "https://github.com/affandar/PilotSwarm/blob/main/docs/building-agent-packages.md",
+        },
         auth: {
             provider: null,
             providers: {},
@@ -193,6 +202,7 @@ export function resolvePortalConfigBundleFromPluginDirs(pluginDirs = []) {
         const portal = getObject(pluginMeta?.portal);
         const portalBranding = getObject(portal.branding);
         const portalUi = getObject(portal.ui);
+        const portalDocs = getObject(portal.docs);
         const portalAuth = getObject(portal.auth);
         const tui = getObject(pluginMeta?.tui);
 
@@ -250,6 +260,13 @@ export function resolvePortalConfigBundleFromPluginDirs(pluginDirs = []) {
                     loadingMessage: firstNonEmptyString(portalUi.loadingMessage, portal.loadingMessage, defaults.ui.loadingMessage) || defaults.ui.loadingMessage,
                     loadingCopy: firstNonEmptyString(portalUi.loadingCopy, portal.loadingCopy, defaults.ui.loadingCopy) || defaults.ui.loadingCopy,
                 },
+                docs: {
+                    agentPackageGuideUrl: firstNonEmptyString(
+                        portalDocs.agentPackageGuideUrl,
+                        portal.agentPackageGuideUrl,
+                        defaults.docs.agentPackageGuideUrl,
+                    ) || defaults.docs.agentPackageGuideUrl,
+                },
                 auth: {
                     provider: firstNonEmptyString(portalAuth.provider, portal.provider),
                     providers: getObject(portalAuth.providers),

package/ui/core/src/commands.js

@@ -89,6 +89,13 @@ export const UI_COMMANDS = {
     OPEN_ADMIN_CONSOLE: "openAdminConsole",
     CLOSE_ADMIN_CONSOLE: "closeAdminConsole",
     ADMIN_REFRESH_PROFILE: "adminRefreshProfile",
+    ADMIN_SHOW_GHCP: "adminShowGhcp",
+    ADMIN_SHOW_PACKAGES: "adminShowPackages",
+    ADMIN_SHOW_WORKERS: "adminShowWorkers",
+    ADMIN_WORKERS_REFRESH: "adminWorkersRefresh",
+    ADMIN_PACKAGES_REFRESH: "adminPackagesRefresh",
+    ADMIN_PACKAGES_NEXT: "adminPackagesNext",
+    ADMIN_PACKAGES_PREV: "adminPackagesPrev",
     ADMIN_BEGIN_EDIT_GHCP_KEY: "adminBeginEditGhcpKey",
     ADMIN_CANCEL_EDIT_GHCP_KEY: "adminCancelEditGhcpKey",
     ADMIN_SAVE_GHCP_KEY: "adminSaveGhcpKey",