pilotswarm-sdk 0.2.0 → 0.2.2

package/dist/session-proxy.js

@@ -387,6 +387,7 @@ export function createSessionProxy(ctx, sessionId, affinityKey, config) {
                 ...(turnMeta?.parentSessionId ? { parentSessionId: turnMeta.parentSessionId } : {}),
                 ...(turnMeta?.nestingLevel != null ? { nestingLevel: turnMeta.nestingLevel } : {}),
                 ...(turnMeta?.requiredTool ? { requiredTool: turnMeta.requiredTool } : {}),
+                ...(turnMeta?.cycleOrigin ? { cycleOrigin: turnMeta.cycleOrigin } : {}),
                 ...(turnMeta?.retryCount != null ? { retryCount: turnMeta.retryCount } : {}),
                 ...(turnMeta?.clientMessageIds && turnMeta.clientMessageIds.length > 0
                     ? { clientMessageIds: turnMeta.clientMessageIds }
@@ -427,6 +428,47 @@ export function buildRunTurnConfig(inputConfig, hostname, fallbackAgentIdentity)
     }
     return runConfig;
 }
+/**
+ * Derive the app-assigned HARVESTER role from the bound agent definition
+ * (enhancedfactstore 07 §1.5 / P4 review BLOCKER#2).
+ *
+ * The harvester role is a property of the AGENT, not of a session: it is
+ * resolved from the worker's static, loaded agent definitions every turn by
+ * matching the session's resolved identity (agentIdentity / boundAgentName)
+ * against each agent's CANONICAL identifier (id / name). Because the agent list
+ * is static worker configuration, this is deterministic and replay-safe.
+ *
+ * Deriving it here (rather than trusting a persisted `isHarvester`) means the
+ * role can NEVER be inherited from a parent session or smuggled in via a stale
+ * serialized config — a child only becomes a harvester if its OWN bound agent
+ * declares `harvester: true`. System agents (e.g. facts-manager) that should be
+ * harvester-capable get the tools through the SessionManager gating, not here.
+ *
+ * SECURITY (P5 review BLOCKER#2): `title` is display metadata, NOT an
+ * authorization key — matching on it would let a non-harvester whose title
+ * normalizes to a harvester's identity receive the privileged crawl queue
+ * (`facts_read_uncrawled` / `facts_mark_crawled`, which read facts across ALL
+ * scopes). We match only `id` / `name`, and we FAIL CLOSED on ambiguity: when
+ * more than one loaded agent resolves to the same normalized identity, the
+ * privileged role is granted only if EVERY one of them declares `harvester`.
+ */
+export function resolveHarvesterRole(identity, boundAgentName, userAgents, systemAgents) {
+    const norm = (v) => (v || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+    const target = norm(identity) || norm(boundAgentName);
+    if (!target)
+        return false;
+    const agents = [...(userAgents ?? []), ...(systemAgents ?? [])];
+    // Canonical identifiers ONLY — never `title`.
+    const matches = agents.filter((a) => {
+        const candidates = [a.id, a.name].map(norm).filter(Boolean);
+        return candidates.includes(target);
+    });
+    if (matches.length === 0)
+        return false;
+    // Fail closed on a normalized-id/name collision: do not let an ambiguous
+    // match between a harvester and a non-harvester escalate to the role.
+    return matches.every((a) => a.harvester === true);
+}
 // ─── SessionManagerProxy ─────────────────────────────────────────
 // The orchestration's view of the SessionManager singleton.
 // Operations that don't require session affinity.
@@ -532,6 +574,24 @@ userAgents,
 factStore, 
 /** Worker node identifier — written on every CMS event for worker tracking. */
 workerNodeId) {
+    // Shared config for every activity-layer internal PilotSwarmClient /
+    // PilotSwarmManagementClient. Carries the FULL facts/CMS target (07 P3) so
+    // these clients resolve the SAME store as the worker — otherwise
+    // parent-triggered deleteSession / cleanup / reads would hit the wrong DB
+    // when facts live on an enhanced (HorizonDB) store.
+    const internalClientConfig = () => ({
+        store: storeUrl,
+        ...(clientConfig?.storageConfig != null && { storageConfig: clientConfig.storageConfig }),
+        cmsSchema,
+        ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
+        ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
+        ...(clientConfig?.cmsFactsDatabaseUrl != null && { cmsFactsDatabaseUrl: clientConfig.cmsFactsDatabaseUrl }),
+        ...(clientConfig?.enhancedFactsDatabaseUrl != null && { enhancedFactsDatabaseUrl: clientConfig.enhancedFactsDatabaseUrl }),
+        ...(clientConfig?.factsProvider != null && { factsProvider: clientConfig.factsProvider }),
+        ...(clientConfig?.enhancedFactsSchema != null && { enhancedFactsSchema: clientConfig.enhancedFactsSchema }),
+        ...(clientConfig?.useManagedIdentity != null && { useManagedIdentity: clientConfig.useManagedIdentity }),
+        ...(clientConfig?.aadDbUser != null && { aadDbUser: clientConfig.aadDbUser }),
+    });
     // ── runTurn ──────────────────────────────────────────────
     runtime.registerActivity("runTurn", async (activityCtx, input) => {
         activityCtx.traceInfo(`[runTurn] session=${input.sessionId}`);
@@ -555,6 +615,7 @@ workerNodeId) {
                 "pilotswarm.has_parent_session": Boolean(input.parentSessionId),
                 ...(input.parentSessionId ? { "pilotswarm.parent_session_id": input.parentSessionId } : {}),
                 ...(input.requiredTool ? { "pilotswarm.required_tool": input.requiredTool } : {}),
+                ...(input.cycleOrigin ? { "pilotswarm.cycle_origin": input.cycleOrigin } : {}),
                 ...(input.config.model ? { "pilotswarm.model": input.config.model } : {}),
                 ...(input.config.reasoningEffort ? { "pilotswarm.reasoning_effort": input.config.reasoningEffort } : {}),
                 ...(workerNodeId ? { "pilotswarm.worker_node_id": workerNodeId } : {}),
@@ -571,6 +632,12 @@ workerNodeId) {
             fallbackAgentIdentity = row?.agentId ?? undefined;
         }
         const runConfig = buildRunTurnConfig(input.config, hostname, fallbackAgentIdentity);
+        // Derive the app-assigned harvester role authoritatively from the bound
+        // agent definition EVERY turn (enhancedfactstore 07 §1.5 / BLOCKER#2).
+        // It is a property of the agent, resolved from static worker config, so
+        // it survives hydration, is replay-safe, and can never be inherited from
+        // a parent or trusted from a stale serialized config.
+        runConfig.isHarvester = resolveHarvesterRole(runConfig.agentIdentity, runConfig.boundAgentName, userAgents, systemAgents);
         const trace = activityTrace(activityCtx, "runTurn");
         const failForMissingState = async (message) => {
             if (catalog) {
@@ -653,12 +720,7 @@ workerNodeId) {
                     if (!storeUrl)
                         throw new Error("No storeUrl — cannot create PilotSwarmClient");
                     inlineSdkClientPromise = (async () => {
-                        const startedClient = new PilotSwarmClient({
-                            store: storeUrl,
-                            cmsSchema,
-                            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-                            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-                        });
+                        const startedClient = new PilotSwarmClient(internalClientConfig());
                         await startedClient.start();
                         inlineSdkClient = startedClient;
                         return startedClient;
@@ -819,7 +881,7 @@ workerNodeId) {
                             // still apply. The parent is responsible for closing
                             // each instance with complete_agent / cancel_agent /
                             // delete_agent when it no longer needs the child.
-                            const { boundAgentName: _parentBoundAgentName, promptLayering: _parentPromptLayering, ...parentConfig } = input.config;
+                            const { boundAgentName: _parentBoundAgentName, promptLayering: _parentPromptLayering, isHarvester: _parentIsHarvester, ...parentConfig } = input.config;
                             const childConfig = {
                                 ...parentConfig,
                                 ...(agentModel ? { model: agentModel } : {}),
@@ -1353,6 +1415,7 @@ workerNodeId) {
                         modelSummary: sessionManager.getModelSummary(),
                         bootstrap: input.bootstrap,
                         requiredTool: input.requiredTool,
+                        cycleOrigin: input.cycleOrigin,
                         controlToolBridge,
                     });
                 };
@@ -1977,10 +2040,7 @@ workerNodeId) {
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
         const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
+            ...internalClientConfig(),
             traceWriter: (message) => trace(message),
         });
         try {
@@ -2101,12 +2161,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[sendToSession] session=${input.sessionId} msg="${input.message.slice(0, 60)}"`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const info = await sdkClient._getSessionInfo(input.sessionId);
@@ -2136,12 +2191,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[sendCommandToSession] session=${input.sessionId} cmd=${input.command?.cmd}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const orchestrationId = `session-${input.sessionId}`;
@@ -2158,12 +2208,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[getSessionStatus] session=${input.sessionId}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const info = await sdkClient._getSessionInfo(input.sessionId);
@@ -2186,12 +2231,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[getOrchestrationStats] session=${input.sessionId}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmManagementClient");
-        const managementClient = new PilotSwarmManagementClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const managementClient = new PilotSwarmManagementClient(internalClientConfig());
         try {
             await managementClient.start();
             return await managementClient.getOrchestrationStats(input.sessionId);
@@ -2206,12 +2246,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[listSessions]`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const sessions = (await sdkClient.listSessions()).filter((session) => matchesSessionOwnerFilters(session, input));
@@ -2236,12 +2271,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[listChildSessions] parent=${input.parentSessionId}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const sessions = await sdkClient.listSessions();
@@ -2310,12 +2340,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[cancelSession] session=${input.sessionId} reason=${input.reason ?? "none"}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             const orchestrationId = `session-${input.sessionId}`;
@@ -2343,12 +2368,7 @@ workerNodeId) {
         activityCtx.traceInfo(`[deleteSession] session=${input.sessionId} reason=${input.reason ?? "none"}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
-        const sdkClient = new PilotSwarmClient({
-            store: storeUrl,
-            cmsSchema,
-            ...(clientConfig?.duroxideSchema != null && { duroxideSchema: clientConfig.duroxideSchema }),
-            ...(clientConfig?.factsSchema != null && { factsSchema: clientConfig.factsSchema }),
-        });
+        const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
             // This does both: CMS soft-delete + duroxide cancel