pilotswarm-sdk 0.5.63 → 0.5.65

package/dist/worker.js

@@ -1,10 +1,14 @@
+import { AGENT_HANDOFF_CAPABILITY } from "./activity-routing.js";
+import { resolveNativeSubagents } from "./native-subagents.js";
+import { FeatureFlagCache } from "./feature-flag-cache.js";
 import { SessionManager, packageAgentKey, agentOwnerKey } from "./session-manager.js";
 import { loadAdminScope, ADMIN_SCOPE_POLICY_VERSION } from "../api/src/admin-scope.js";
 import { createSessionBlobStore } from "./blob-store.js";
 import { FilesystemArtifactStore, FilesystemSessionStore } from "./session-store.js";
 import { registerActivities } from "./session-proxy.js";
 import { DURABLE_SESSION_ORCHESTRATION_NAME, DURABLE_SESSION_ORCHESTRATION_REGISTRY, } from "./orchestration-registry.js";
-import { PgSessionCatalog } from "./cms.js";
+import { PgSessionCatalog, resolveEffectiveSpawnOwner } from "./cms.js";
+import { createAgentDiscoveryTool } from "./agent-discovery.js";
 import { loadAgentFiles, validateAgentDefinition } from "./agent-loader.js";
 import { clipDescription, composeDeclaredSkillsPrompt, loadSkillsSync } from "./skills.js";
 import { resolveSystemAgentSessionPlans, startSystemAgents } from "./system-agents.js";
@@ -20,8 +24,8 @@ import { createSweeperTools } from "./sweeper-tools.js";
 import { createResourceManagerTools } from "./resourcemgr-tools.js";
 import { composeSystemPrompt, mergePromptSections } from "./prompt-layering.js";
 import { buildSchemaIdentifier } from "./prompt-layers.js";
-import { DEFAULT_TURN_TIMEOUT_MS } from "./managed-session.js";
-import { defineTool } from "@github/copilot-sdk";
+import { DEFAULT_TURN_TIMEOUT_MS, ManagedSession } from "./managed-session.js";
+import { findReservedPackageToolName } from "./reserved-tool-names.js";
 import { installAgentPackages, loadAgentPackageTools } from "./agent-package-installer.js";
 import fs from "node:fs";
 import os from "node:os";
@@ -183,6 +187,9 @@ export class PilotSwarmWorker {
     /** Mtime watcher that re-loads model_providers.json on file change. */
     _modelProvidersReloader = null;
     _modelProvidersReloadTimer = null;
+    /** Close admission when drain begins; _started stays true until teardown ends. */
+    _providerReconciliationEnabled = false;
+    _providerReconciliation = null;
     /** Embedded PilotSwarm framework prompt. */
     _frameworkBasePrompt = null;
     /** Tool names declared by the embedded PilotSwarm framework default agent. */
@@ -234,6 +241,8 @@ export class PilotSwarmWorker {
     _eventLoopHist = null;
     /** Last refresh failure — carried in heartbeat state until a clean pass. */
     _agentPackagesRefreshError = null;
+    _featureFlags = null;
+    _registryReporting = false;
     constructor(options) {
         this.config = {
             ...options,
@@ -297,6 +306,7 @@ export class PilotSwarmWorker {
             appDefaultDescriptor: this._appDefaultDescriptor ?? undefined,
             skillDirectories: this._loadedSkillDirs,
             customAgents: this._loadedAgents,
+            nativeSubagents: resolveNativeSubagents(options.nativeSubagents),
             // The `load_skill` catalog, BY REFERENCE (cleared and refilled
             // in place on reload): deployment + shared-package skills.
             skills: this._loadableSkills,
@@ -317,12 +327,34 @@ export class PilotSwarmWorker {
             turnInactivityTimeoutMs: options.turnInactivityTimeoutMs,
         }, effectiveSessionStateDir);
         this.sessionManager.setModelProvidersRefresher(() => this._refreshProviderRegistry());
+    }
+    _startProviderPolling() {
+        this._providerReconciliationEnabled = true;
         // Poll for model_providers.json changes (30s, unref'd so it never
         // holds the process open). On reload, swap the worker's registry AND
         // the SessionManager's — new sessions and per-turn model resolution
         // pick up the fresh catalog immediately.
-        if (this._modelProvidersReloader?.path || this._modelProviders) {
+        if (!this._modelProvidersReloadTimer && (this._modelProvidersReloader?.path || this._modelProviders)) {
             this._modelProvidersReloadTimer = setInterval(() => {
+                this._reconcileProvidersAndSystemAgents(true);
+            }, 30_000);
+            this._modelProvidersReloadTimer.unref?.();
+        }
+    }
+    _stopProviderPolling() {
+        this._providerReconciliationEnabled = false;
+        if (this._modelProvidersReloadTimer) {
+            clearInterval(this._modelProvidersReloadTimer);
+            this._modelProvidersReloadTimer = null;
+        }
+    }
+    _reconcileProvidersAndSystemAgents(refreshProviders) {
+        // Initial bootstrap and periodic reconciliation share one task. A slow
+        // catalog must not accumulate overlapping refreshes or agent starts.
+        if (!this._providerReconciliationEnabled || this._providerReconciliation)
+            return;
+        this._providerReconciliation = (async () => {
+            if (refreshProviders) {
                 if (this._modelProvidersReloader?.checkAndReload()) {
                     this._modelProviders = this._modelProvidersReloader.current;
                     this._modelProviderTypes = this._modelProvidersReloader.types;
@@ -333,12 +365,13 @@ export class PilotSwarmWorker {
                 // catalog is re-read on the same tick as the file. Without
                 // it a provider somebody just added would resolve no
                 // credential until the worker restarted.
-                void this._refreshProviderRegistry()
-                    .then(() => this._startSystemAgents())
-                    .catch((err) => console.warn(`[PilotSwarmWorker] provider/system reconciliation failed: ${String(err?.message ?? err)}`));
-            }, 30_000);
-            this._modelProvidersReloadTimer.unref?.();
-        }
+                await this._refreshProviderRegistry();
+            }
+            if (this._providerReconciliationEnabled)
+                await this._startSystemAgents();
+        })()
+            .catch((err) => console.warn(`[PilotSwarmWorker] provider/system reconciliation failed: ${String(err?.message ?? err)}`))
+            .finally(() => { this._providerReconciliation = null; });
     }
     /**
      * Rebuild what the SessionManager resolves models against: the TYPES
@@ -539,6 +572,11 @@ export class PilotSwarmWorker {
                 throw new Error(`CMS initialization failed after ${attempts} attempts — refusing to run a degraded worker without catalog-gated tools: ${String(lastErr?.message ?? lastErr)}`);
             }
         }
+        if (this._catalog?.features) {
+            this._featureFlags = new FeatureFlagCache(this._catalog.features);
+            this.sessionManager.setFeatureFlagCache(this._featureFlags);
+            await this._featureFlags.pollRevisionsAndRefresh();
+        }
         // ── Provider budgets: the one-time deployment seed ──────────────
         //
         // A fresh cluster holds no providers, and the credentials in the
@@ -658,6 +696,7 @@ export class PilotSwarmWorker {
         const inspectClient = new Client(this._provider);
         this.sessionManager.setDuroxideClient(inspectClient);
         const runtimeOptions = {
+            workerTagFilter: { defaultAnd: [AGENT_HANDOFF_CAPABILITY] },
             orchestrationConcurrency,
             workerConcurrency,
             dispatcherPollIntervalMs: 10,
@@ -739,65 +778,18 @@ export class PilotSwarmWorker {
             });
             this.registerTools(rmTools);
         }
-        // ps_list_agents tool — exposes user-creatable agents by default.
-        // NOTE: prefixed with `ps_` to avoid collision with the Copilot SDK's
-        // built-in `list_agents` tool (introduced in @github/copilot 1.0.32),
-        // which lists live background-agent task instances rather than blueprints.
-        const listAgentsTool = defineTool("ps_list_agents", {
-            description: "List all available agent BLUEPRINTS (definitions loaded from .agent.md files). " +
-                "By default this returns only user-creatable named agents. " +
-                "Worker-managed system agents are hidden from the default list because they are NOT valid spawn_agent targets. " +
-                "Pass systemOnly=true only when you need to inspect system-agent definitions for diagnostics. " +
-                "Use this to discover what agents CAN be spawned. To check status of sub-agents you ALREADY spawned, use check_agents instead. " +
-                "IMPORTANT: Do NOT call this unless you actually need to spawn an agent and don't know its name. " +
-                "Seeing an agent in this list does NOT mean you should spawn it.",
-            parameters: {
-                type: "object",
-                properties: {
-                    systemOnly: {
-                        type: "boolean",
-                        description: "If true, only return system agents. Default: false",
-                    },
-                    creatableOnly: {
-                        type: "boolean",
-                        description: "If true, only return user-creatable (non-system) agents. This matches the default behavior.",
-                    },
-                },
-            },
-            handler: async (args) => {
-                const allAgents = [
-                    ...this._loadedAgents.map(a => ({
-                        name: a.name,
-                        namespace: a.namespace || "custom",
-                        qualifiedName: `${a.namespace || "custom"}:${a.name}`,
-                        description: a.description || null,
-                        tools: a.tools || [],
-                        skills: a.skills || [],
-                        system: false,
-                        creatable: true,
-                        id: null,
-                        parent: null,
-                    })),
-                    ...this._loadedSystemAgents.map(a => ({
-                        name: a.name,
-                        namespace: a.namespace || "pilotswarm",
-                        qualifiedName: `${a.namespace || "pilotswarm"}:${a.name}`,
-                        description: a.description || null,
-                        tools: a.tools || [],
-                        system: true,
-                        creatable: false,
-                        id: a.id || null,
-                        parent: a.parent || null,
-                    })),
-                ];
-                let filtered = allAgents.filter(a => !a.system);
-                if (args.systemOnly) {
-                    filtered = allAgents.filter(a => a.system);
-                }
-                else if (args.creatableOnly) {
-                    filtered = allAgents.filter(a => !a.system);
-                }
-                return JSON.stringify({ agents: filtered, total: filtered.length }, null, 2);
+        // ps_ avoids the Copilot CLI's native list_agents task-status tool.
+        // Listing uses the same owner and copy resolution as spawn_agent.
+        const listAgentsTool = createAgentDiscoveryTool({
+            // Same identities/owners/order as the raw spawn definitions,
+            // with MCP references already reduced to their admitted grants.
+            getUserAgents: () => this._loadedAgents,
+            getSystemAgents: () => this._loadedSystemAgents,
+            getCallerOwnerKey: async (sessionId) => {
+                if (!this._catalog || !sessionId)
+                    return null;
+                const owner = await resolveEffectiveSpawnOwner((id) => this._catalog.getSession(id), sessionId);
+                return owner?.provider && owner?.subject ? `${owner.provider}\u0001${owner.subject}` : null;
             },
         });
         this.registerTools([listAgentsTool]);
@@ -805,6 +797,7 @@ export class PilotSwarmWorker {
             console.error("[PilotSwarmWorker] Runtime error:", err);
         });
         this._started = true;
+        this._startProviderPolling();
         // Autonomous eviction clock (lifecycle protocol §3.4): local session
         // state is a cache. Sessions idle past the hold window + margin are
         // reclaimed locally (committed → delete; legacy → dehydrate) with no
@@ -825,24 +818,18 @@ export class PilotSwarmWorker {
             }, Math.min(evictAfterMs, 300_000));
             this._evictionTimer.unref?.();
         }
-        // Agent-package epoch poll (model-providers-reloader pattern): one
-        // single-row SELECT per interval; a changed epoch triggers the full
-        // install + in-place swap. 0 disables.
-        if (this._agentPackagesCacheDir && this._agentPackagesRefreshMs > 0) {
-            this._agentPackagesTimer = setInterval(() => {
-                void this.refreshAgentPackages();
-            }, this._agentPackagesRefreshMs);
-            this._agentPackagesTimer.unref?.();
-        }
+        // One configuration timer for every CMS worker. Zero still disables
+        // package refresh, but cannot disable feature-policy convergence.
+        this._startConfigurationPolling();
         await new Promise(r => setTimeout(r, 200));
         // Auto-start system agents defined in plugins (idempotent), but do not
         // block worker.start() on the bootstrap race. The TUI should become
         // interactive even if first-run system-agent startup is slow.
-        void this._startSystemAgents().catch((err) => {
-            console.warn(`[PilotSwarmWorker] background system agent startup failed: ${err?.message ?? err}`);
-        });
+        // Provider routing was refreshed above, before the runtime started.
+        this._reconcileProvidersAndSystemAgents(false);
     }
     async stop() {
+        this._stopProviderPolling();
         if (this._evictionTimer) {
             clearInterval(this._evictionTimer);
             this._evictionTimer = null;
@@ -851,6 +838,7 @@ export class PilotSwarmWorker {
             clearInterval(this._agentPackagesTimer);
             this._agentPackagesTimer = null;
         }
+        await this._featureFlags?.stop();
         if (this._eventLoopHist) {
             this._eventLoopHist.disable();
             this._eventLoopHist = null;
@@ -863,6 +851,9 @@ export class PilotSwarmWorker {
             await this.runtime.shutdown(shutdownTimeoutMs);
             this.runtime = null;
         }
+        // Stop fetching first, then let any already-admitted bootstrap finish
+        // while the catalog/provider it uses are still open.
+        await this._providerReconciliation;
         await this.sessionManager.shutdown();
         if (this._catalog) {
             try {
@@ -910,6 +901,7 @@ export class PilotSwarmWorker {
      *      lock timeout.
      */
     async gracefulShutdown() {
+        this._stopProviderPolling();
         const rawDrainMs = Number.parseInt(process.env.PILOTSWARM_WORKER_SHUTDOWN_TIMEOUT_MS || "", 10);
         const drainBudgetMs = Number.isFinite(rawDrainMs) && rawDrainMs >= 0 ? rawDrainMs : 60_000;
         // Advertise draining before the runtime drain so operators see the
@@ -1009,10 +1001,28 @@ export class PilotSwarmWorker {
      * a broken package degrades to "packages unchanged/quarantined", never
      * to a dead worker.
      *
-     * Hot-swap semantics (existing runtime behavior, relied on, not added):
-     * prompts re-read per turn, tool HANDLERS re-register per turn, tool
-     * DECLARATIONS and MCP configs reach the CLI only on cold create/resume.
+     * SessionManager adopts one package snapshot per turn. Handler-only changes
+     * re-register in place; changed prompts, declarations or MCP grants recreate
+     * the warm CLI handle at the next turn boundary.
      */
+    _startConfigurationPolling() {
+        if (!this._catalog || this._agentPackagesTimer)
+            return;
+        void this._reportAgentWorkerState();
+        this._agentPackagesTimer = setInterval(() => {
+            void this.refreshWorkerConfiguration();
+        }, this._agentPackagesRefreshMs > 0 ? this._agentPackagesRefreshMs : 20_000);
+        this._agentPackagesTimer.unref?.();
+    }
+    async refreshWorkerConfiguration() {
+        await Promise.allSettled([
+            (async () => {
+                await this._featureFlags?.pollRevisionsAndRefresh();
+                await this._reportAgentWorkerState();
+            })(),
+            this._agentPackagesRefreshMs > 0 ? this.refreshAgentPackages() : Promise.resolve(),
+        ]);
+    }
     async refreshAgentPackages(opts = {}) {
         if (!this._agentPackagesCacheDir || !this._catalog || !this.artifactStore)
             return;
@@ -1046,6 +1056,15 @@ export class PilotSwarmWorker {
                     continue;
                 try {
                     const tools = await loadAgentPackageTools(pkg, { workerNodeId: this.config.workerNodeId });
+                    const collision = findReservedPackageToolName(tools.map((tool) => String(tool?.name || "")), [
+                        ...ManagedSession.systemToolDefs().map((tool) => String(tool.name)),
+                        ...ManagedSession.subAgentToolDefs().map((tool) => String(tool.name)),
+                        ...this._frameworkBaseToolNames,
+                        ...this._appDefaultToolNames,
+                    ], this.toolRegistry.keys());
+                    if (collision) {
+                        throw new Error(`package tool "${collision}" conflicts with a reserved platform or deployment tool`);
+                    }
                     const ownMap = new Map();
                     for (const tool of tools) {
                         packageTools.set(tool.name, tool);
@@ -1146,7 +1165,7 @@ export class PilotSwarmWorker {
             sdkVersion,
             authz: { adminScope: loadAdminScope(), policyVersion: ADMIN_SCOPE_POLICY_VERSION },
             orchestrationVersions: DURABLE_SESSION_ORCHESTRATION_REGISTRY.map((r) => r.version),
-            consumes: this._agentPackagesCacheDir ? ["agent-packages"] : [],
+            consumes: [...(this._agentPackagesCacheDir ? ["agent-packages"] : []), "feature-flags"],
             capabilities: {
                 blobStore: Boolean(this.blobStore),
                 enhancedFacts: Boolean(this.factStore && isEnhancedFactStore(this.factStore)),
@@ -1191,8 +1210,9 @@ export class PilotSwarmWorker {
      * actuated domains are inert by protocol. Never throws.
      */
     async _reportAgentWorkerState() {
-        if (!this._catalog)
+        if (!this._catalog || this._registryReporting)
             return;
+        this._registryReporting = true;
         try {
             await this._catalog.workerHeartbeat({
                 workerNodeId: this._registryWorkerId,
@@ -1202,6 +1222,8 @@ export class PilotSwarmWorker {
                 info: this._buildRegistrarInfo(),
                 health: this._collectWorkerHealth(),
                 state: {
+                    "feature-flags": { ...this._featureFlags?.state,
+                        nativeCapability: resolveNativeSubagents(this.config.nativeSubagents) },
                     "agent-packages": {
                         epoch: this._agentPackagesEpoch,
                         installed: this._agentPackagesInstalled,
@@ -1213,6 +1235,9 @@ export class PilotSwarmWorker {
         catch (error) {
             console.warn(`[PilotSwarmWorker] worker-registry heartbeat failed: ${error?.message ?? error}`);
         }
+        finally {
+            this._registryReporting = false;
+        }
     }
     _loadPlugins() {
         // ── Tier 1: SDK system plugins (always loaded) ───────────────
@@ -1290,7 +1315,7 @@ export class PilotSwarmWorker {
             const { mcpServers: _refs, inheritDefaultMcpServers: _inherit, ...rest } = agent;
             const mcpKey = agent.packageId
                 ? packageAgentKey(agent.packageId, agent.name)
-                : agent.name;
+                : agent.namespace ? `${agent.namespace}:${agent.name}` : agent.name;
             return {
                 ...rest,
                 // The agent's OWN prompt (skills already composed in), never
@@ -1301,8 +1326,8 @@ export class PilotSwarmWorker {
                     appDefault: this._appDefaultPrompt,
                     activeAgentPrompt: agent.prompt,
                 }) ?? agent.prompt,
-                // mcpKey is the qualified key for a package agent, the bare
-                // name for a deployment/inline one — the only keys registered.
+                // MCP uses the exact same copy as the authored prompt, even
+                // when two static namespaces declare the same agent name.
                 ...(this._agentMcpServers[mcpKey]
                     ? { mcpServers: this._agentMcpServers[mcpKey] }
                     : {}),
@@ -1448,19 +1473,11 @@ export class PilotSwarmWorker {
             console.warn(`[PilotSwarmWorker] Direct worker-config mcpServers (${this._directConfigMcpNames.join(", ")}) ` +
                 `apply to every session (legacy). Prefer per-agent frontmatter declarations or tagging catalog servers "default": true.`);
         }
-        // Per-agent maps. Agents merge by name with later definitions
-        // overriding earlier ones (same contract as prompt resolution), so
-        // ALWAYS assign: a later definition with no MCP declarations must
-        // clear a shadowed definition's grants, never inherit them.
-        //
-        // A PACKAGE agent registers ONLY under a package-qualified key, never
-        // the bare name. With scope shadowing two copies share the bare name,
-        // and a bare-name entry is last-write-wins — a session resolving one
-        // copy could read the other's grants (or a user package could strip a
-        // deployment agent's grants fleet-wide). The bare name is therefore
-        // reserved for deployment/inline agents, which have no packageId; the
-        // session-manager reads the qualified key for package copies and the
-        // bare key only for non-package agents.
+        // Published agents use package-qualified keys. Static definitions use
+        // namespace-qualified keys; the bare alias retains the first static
+        // definition, matching the prompt lookup's deployment default. Never
+        // let a same-name package or another namespace replace these grants.
+        const assignedStaticKeys = new Set();
         for (const agent of [...this._rawLoadedAgents, ...this._loadedSystemAgents]) {
             const resolved = {};
             if (agent.inheritDefaultMcpServers === true) {
@@ -1472,14 +1489,21 @@ export class PilotSwarmWorker {
                 packageId: agent.packageId ?? null,
                 packageScope: agent.packageScope ?? null,
             });
-            const key = agent.packageId
-                ? packageAgentKey(agent.packageId, agent.name)
-                : agent.name;
-            if (Object.keys(resolved).length > 0) {
-                this._agentMcpServers[key] = resolved;
-            }
-            else {
-                delete this._agentMcpServers[key];
+            const packageId = agent.packageId;
+            const keys = packageId
+                ? [packageAgentKey(packageId, agent.name)]
+                : [...new Set([agent.name, ...(agent.namespace ? [`${agent.namespace}:${agent.name}`] : [])])];
+            for (const key of keys) {
+                if (!packageId && assignedStaticKeys.has(key))
+                    continue;
+                if (!packageId)
+                    assignedStaticKeys.add(key);
+                if (Object.keys(resolved).length > 0) {
+                    this._agentMcpServers[key] = resolved;
+                }
+                else {
+                    delete this._agentMcpServers[key];
+                }
             }
         }
     }
@@ -1634,6 +1658,7 @@ export class PilotSwarmWorker {
             const winner = [...agents].sort((a, b) => rank(a) - rank(b))[0];
             const copyOf = (agent) => ({
                 prompt: agent.prompt,
+                toolNames: [...(agent.tools ?? [])],
                 kind: agent.promptLayerKind ?? "app-agent",
                 descriptor: agent.layerDescriptor,
                 ...(agent.packageId ? {
@@ -1646,6 +1671,19 @@ export class PilotSwarmWorker {
                 ...copyOf(winner),
                 ...(agents.length > 1 ? { copies: agents.map(copyOf) } : {}),
             };
+            // Persisted static bindings use this exact namespace key. The
+            // alias carries the composed prompt, declarations and descriptor
+            // of that copy, never the bare-name winner from another namespace.
+            const assignedAliases = new Set();
+            for (const agent of agents) {
+                if (agent.packageId || !agent.namespace)
+                    continue;
+                const key = `${agent.namespace}:${agent.name}`;
+                if (assignedAliases.has(key))
+                    continue;
+                assignedAliases.add(key);
+                this._agentPromptLookup[key] = copyOf(agent);
+            }
             if (agents.length > 1) {
                 console.warn(`[PilotSwarmWorker] agent name "${name}" is served by ${agents.length} loaded copies `
                     + `(${agents.map((a) => a.packageId ? `${a.packageScope ?? "shared"} package` : "deployment").join(", ")}); `
@@ -1887,6 +1925,8 @@ export class PilotSwarmWorker {
         }
         const overrideByAgent = new Map(overrides.map((override) => [override.agentId, override]));
         for (const plan of resolveSystemAgentSessionPlans(this._loadedSystemAgents)) {
+            if (!this._providerReconciliationEnabled)
+                return;
             const override = overrideByAgent.get(plan.agent.id);
             const route = override ?? systemDefault;
             if (!route.model || !this._modelProviders?.hasModel(route.model)) {