pilotswarm-sdk 0.1.28 → 0.1.30

package/dist/agent-loader.d.ts

@@ -50,6 +50,18 @@ export interface AgentConfig {
     namespace?: string;
     /** Internal: identifies which prompt layering path this agent should use. */
     promptLayerKind?: "app-agent" | "app-system-agent" | "pilotswarm-system-agent";
+    /**
+     * Frontmatter schema version. Defaults to 1 when the file omits it. Higher integers
+     * indicate forward-incompatible frontmatter shapes the loader may reject in the future.
+     */
+    schemaVersion?: number;
+    /**
+     * Author-supplied version label for this agent definition. PilotSwarm-authored system
+     * agents use SemVer; app authors may use any meaningful non-empty string.
+     */
+    version?: string;
+    /** Absolute path the agent was loaded from, when known. Used for diagnostics. */
+    sourcePath?: string;
 }
 /**
  * Load all .agent.md files from a directory and convert to CustomAgentConfig[].

package/dist/agent-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../src/agent-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAclF;AAID,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;CAClF;AA+GD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CA+C/D"}
+{"version":3,"file":"agent-loader.d.ts","sourceRoot":"","sources":["../src/agent-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAclF;AAID,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;IAC/E;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAoHD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CA6D/D"}

package/dist/agent-loader.js

@@ -137,6 +137,13 @@ function parseAgentFrontmatter(content) {
             meta.title = value;
         else if (key === "parent")
             meta.parent = value;
+        else if (key === "schemaVersion") {
+            const n = Number(value);
+            if (Number.isFinite(n) && n > 0)
+                meta.schemaVersion = Math.floor(n);
+        }
+        else if (key === "version")
+            meta.version = value;
         else if (key === "tools" && value) {
             // Inline array: tools: [view, grep]
             meta.tools = value.replace(/[\[\]]/g, "").split(",").map(s => s.trim()).filter(Boolean);
@@ -190,6 +197,10 @@ export function loadAgentFiles(agentsDir) {
                 console.warn(`[agent-loader] Skipping ${entry.name}: empty prompt body`);
                 continue;
             }
+            if (meta.schemaVersion !== undefined && meta.schemaVersion !== 1) {
+                console.warn(`[agent-loader] Skipping ${entry.name}: unsupported schemaVersion ${meta.schemaVersion}; expected schemaVersion: 1`);
+                continue;
+            }
             agents.push({
                 name: meta.name,
                 description: meta.description,
@@ -201,7 +212,16 @@ export function loadAgentFiles(agentsDir) {
                 parent: meta.parent,
                 splash: meta.splash,
                 initialPrompt: meta.initialPrompt,
+                schemaVersion: meta.schemaVersion,
+                version: meta.version,
+                sourcePath: filePath,
             });
+            if (meta.schemaVersion === undefined) {
+                console.warn(`[agent-loader] ${entry.name}: missing frontmatter 'schemaVersion'. Defaulting to 1; add 'schemaVersion: 1' to silence this warning.`);
+            }
+            if (!meta.version) {
+                console.warn(`[agent-loader] ${entry.name}: missing frontmatter 'version'. Add 'version: x.y.z' (or any non-empty label) to track agent prompt changes.`);
+            }
         }
         catch (err) {
             console.warn(`[agent-loader] Failed to parse ${entry.name}: ${err.message}`);

package/dist/agent-loader.js.map

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

package/dist/child-notifications.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Child notification policy helpers.
+ *
+ * Implements the decision logic described in the
+ * "Child Contract Notification Policy" proposal:
+ *
+ *   - `wakeOn: "any"`             - wake parent for any child update
+ *   - `wakeOn: "material_change"` - wake parent for material changes only
+ *                                    (default; suppresses clear heartbeats)
+ *   - `wakeOn: "completion"`      - wake parent only on terminal/blocked/error
+ *
+ * `wakeOn` only controls AUTONOMOUS parent wakeups. Explicit parent tools such
+ * as `check_agents` and `wait_for_agents` always reveal child state regardless
+ * of policy.
+ *
+ * This module is intentionally pure and side-effect-free so it is easy to
+ * unit test and safe to call from orchestration helpers.
+ *
+ * @module
+ */
+import type { ChildSessionResult, ChildSessionContract } from "./types.js";
+export type ChildWakePolicy = "any" | "material_change" | "completion";
+export type ChildUpdateClassification = "heartbeat" | "material" | "completion" | "error" | "unknown";
+/** Compact representation of a child update suitable for wake-decision logic. */
+export interface ChildUpdateSnapshot {
+    /** Kind of orchestration update being delivered to the parent. */
+    kind: "completed" | "wait" | "progress" | "error" | "cancelled";
+    /** Last assistant content / summary text emitted by the child. */
+    summary?: string;
+    /** Structured child result if available (final or interim). */
+    result?: Partial<ChildSessionResult>;
+    /** Optional explicit material flag from the child (overrides classifier). */
+    material?: boolean;
+}
+/** Default policy when a contract is missing or unset. */
+export declare const DEFAULT_CHILD_WAKE_POLICY: ChildWakePolicy;
+/** Normalize an arbitrary input value to a valid `ChildWakePolicy`. */
+export declare function normalizeWakeOn(value: unknown): ChildWakePolicy;
+/** Read `wakeOn` off a contract (or a contract-shaped record) safely. */
+export declare function readWakeOn(contract: Partial<ChildSessionContract> | Record<string, unknown> | null | undefined): ChildWakePolicy;
+/**
+ * Conservative no-op classifier.
+ *
+ * Returns true only for clear heartbeat/no-op text. Unknown / arbitrary
+ * natural-language summaries default to material under `material_change`.
+ */
+export declare function isHeartbeatText(text: string | undefined): boolean;
+/** Classify a child update for wake-decision purposes. */
+export declare function classifyChildUpdate(update: ChildUpdateSnapshot): ChildUpdateClassification;
+export interface ParentWakeDecisionInput {
+    update: ChildUpdateSnapshot;
+    contract?: Partial<ChildSessionContract> | Record<string, unknown> | null;
+}
+export interface ParentWakeDecision {
+    wake: boolean;
+    policy: ChildWakePolicy;
+    classification: ChildUpdateClassification;
+    reason: string;
+}
+/**
+ * Decide whether the parent session should be woken for the given child update.
+ *
+ * The conservative rule: when the helper cannot confidently classify an
+ * update as a heartbeat under `material_change`, it wakes the parent
+ * rather than risk silently swallowing important work.
+ */
+export declare function shouldWakeParentForChildUpdate(input: ParentWakeDecisionInput): ParentWakeDecision;
+/**
+ * Evaluate a batch of pending child updates against the parent's active wait.
+ *
+ * Used as the digest-defense guard described in the proposal: a heartbeat-only
+ * batch should not interrupt an active parent cron wait; a mixed batch with
+ * any material update wakes the parent.
+ */
+export declare function shouldWakeParentForChildDigest(updates: Array<ParentWakeDecisionInput>): ParentWakeDecision;
+//# sourceMappingURL=child-notifications.d.ts.map

package/dist/child-notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-notifications.d.ts","sourceRoot":"","sources":["../src/child-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAuB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEhG,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEvE,MAAM,MAAM,yBAAyB,GAC/B,WAAW,GACX,UAAU,GACV,YAAY,GACZ,OAAO,GACP,SAAS,CAAC;AAEhB,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAChC,kEAAkE;IAClE,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;IAChE,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB,EAAE,eAAmC,CAAC;AAI5E,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAS/D;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,CAGhI;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAiCjE;AAWD,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,yBAAyB,CAgC1F;AAED,MAAM,WAAW,uBAAuB;IACpC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7E;AAED,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,EAAE,yBAAyB,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CAoBjG;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,KAAK,CAAC,uBAAuB,CAAC,GAAG,kBAAkB,CAW1G"}

package/dist/child-notifications.js

@@ -0,0 +1,181 @@
+/**
+ * Child notification policy helpers.
+ *
+ * Implements the decision logic described in the
+ * "Child Contract Notification Policy" proposal:
+ *
+ *   - `wakeOn: "any"`             - wake parent for any child update
+ *   - `wakeOn: "material_change"` - wake parent for material changes only
+ *                                    (default; suppresses clear heartbeats)
+ *   - `wakeOn: "completion"`      - wake parent only on terminal/blocked/error
+ *
+ * `wakeOn` only controls AUTONOMOUS parent wakeups. Explicit parent tools such
+ * as `check_agents` and `wait_for_agents` always reveal child state regardless
+ * of policy.
+ *
+ * This module is intentionally pure and side-effect-free so it is easy to
+ * unit test and safe to call from orchestration helpers.
+ *
+ * @module
+ */
+/** Default policy when a contract is missing or unset. */
+export const DEFAULT_CHILD_WAKE_POLICY = "material_change";
+const ALL_POLICIES = new Set(["any", "material_change", "completion"]);
+/** Normalize an arbitrary input value to a valid `ChildWakePolicy`. */
+export function normalizeWakeOn(value) {
+    if (typeof value !== "string")
+        return DEFAULT_CHILD_WAKE_POLICY;
+    const lower = value.trim().toLowerCase();
+    if (ALL_POLICIES.has(lower))
+        return lower;
+    // tolerant aliases
+    if (lower === "always" || lower === "all")
+        return "any";
+    if (lower === "material" || lower === "change")
+        return "material_change";
+    if (lower === "done" || lower === "finished")
+        return "completion";
+    return DEFAULT_CHILD_WAKE_POLICY;
+}
+/** Read `wakeOn` off a contract (or a contract-shaped record) safely. */
+export function readWakeOn(contract) {
+    if (!contract || typeof contract !== "object")
+        return DEFAULT_CHILD_WAKE_POLICY;
+    return normalizeWakeOn(contract["wakeOn"]);
+}
+/**
+ * Conservative no-op classifier.
+ *
+ * Returns true only for clear heartbeat/no-op text. Unknown / arbitrary
+ * natural-language summaries default to material under `material_change`.
+ */
+export function isHeartbeatText(text) {
+    if (!text)
+        return false;
+    const trimmed = text.trim().toLowerCase();
+    if (!trimmed)
+        return true;
+    // Common short heartbeat phrases.
+    const heartbeats = [
+        "no change",
+        "no changes",
+        "no drift",
+        "no new change",
+        "no new changes",
+        "no new reportable change",
+        "no new reportable changes",
+        "no update",
+        "no updates",
+        "nothing to report",
+        "nothing new",
+        "cycle quiet",
+        "quiet cycle",
+        "still watching",
+        "still monitoring",
+        "no material change",
+        "no material changes",
+        "heartbeat",
+        "unchanged",
+        "no_change",
+    ];
+    if (heartbeats.includes(trimmed))
+        return true;
+    // Allow short statements that start with a heartbeat phrase + trailing punctuation.
+    for (const h of heartbeats) {
+        if (trimmed === h + "." || trimmed === h + "!")
+            return true;
+    }
+    return false;
+}
+const TERMINAL_VERDICTS = new Set([
+    "success",
+    "partial",
+    "blocked",
+    "failed",
+    "cancelled",
+    "timed_out",
+]);
+/** Classify a child update for wake-decision purposes. */
+export function classifyChildUpdate(update) {
+    if (update.kind === "error")
+        return "error";
+    // Treat cancelled as completion for routing purposes (parent should know).
+    if (update.kind === "cancelled")
+        return "completion";
+    // Completed turn with a recognized terminal verdict.
+    if (update.kind === "completed") {
+        const verdict = update.result?.verdict;
+        if (verdict && TERMINAL_VERDICTS.has(verdict)) {
+            if (verdict === "blocked" || verdict === "failed" || verdict === "timed_out")
+                return "completion";
+            return "completion";
+        }
+        // Completed turn without a verdict — treat as material so parent sees the summary.
+        return update.material === false && isHeartbeatText(update.summary) ? "heartbeat" : "material";
+    }
+    // Explicit material flag from the child wins.
+    if (update.material === true)
+        return "material";
+    if (update.material === false)
+        return "heartbeat";
+    // Structured verdict hints during a wait/progress turn.
+    const verdictHint = update.result?.verdict;
+    if (typeof verdictHint === "string") {
+        const v = verdictHint.toLowerCase();
+        if (v === "heartbeat" || v === "unchanged" || v === "no_change")
+            return "heartbeat";
+    }
+    // Fall back to text classification.
+    if (isHeartbeatText(update.summary))
+        return "heartbeat";
+    if (!update.summary)
+        return "unknown";
+    return "material";
+}
+/**
+ * Decide whether the parent session should be woken for the given child update.
+ *
+ * The conservative rule: when the helper cannot confidently classify an
+ * update as a heartbeat under `material_change`, it wakes the parent
+ * rather than risk silently swallowing important work.
+ */
+export function shouldWakeParentForChildUpdate(input) {
+    const policy = readWakeOn(input.contract ?? null);
+    const classification = classifyChildUpdate(input.update);
+    if (policy === "any") {
+        return { wake: true, policy, classification, reason: "policy=any" };
+    }
+    if (policy === "completion") {
+        if (classification === "completion" || classification === "error") {
+            return { wake: true, policy, classification, reason: `policy=completion classification=${classification}` };
+        }
+        return { wake: false, policy, classification, reason: `policy=completion classification=${classification}` };
+    }
+    // material_change (default)
+    if (classification === "heartbeat") {
+        return { wake: false, policy, classification, reason: "policy=material_change classification=heartbeat" };
+    }
+    return { wake: true, policy, classification, reason: `policy=material_change classification=${classification}` };
+}
+/**
+ * Evaluate a batch of pending child updates against the parent's active wait.
+ *
+ * Used as the digest-defense guard described in the proposal: a heartbeat-only
+ * batch should not interrupt an active parent cron wait; a mixed batch with
+ * any material update wakes the parent.
+ */
+export function shouldWakeParentForChildDigest(updates) {
+    if (updates.length === 0) {
+        return { wake: false, policy: DEFAULT_CHILD_WAKE_POLICY, classification: "unknown", reason: "empty digest" };
+    }
+    let firstHeartbeat;
+    for (const u of updates) {
+        const d = shouldWakeParentForChildUpdate(u);
+        if (d.wake)
+            return d;
+        if (!firstHeartbeat)
+            firstHeartbeat = d;
+    }
+    return firstHeartbeat;
+}
+//# sourceMappingURL=child-notifications.js.map

package/dist/child-notifications.js.map

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

package/dist/client.d.ts

@@ -49,6 +49,8 @@ export declare class PilotSwarmClient {
         agentId?: string;
         /** Authenticated owner to associate with the new session. */
         owner?: SessionOwnerInfo | null;
+        /** Optional visual session group assignment. */
+        groupId?: string | null;
     }): Promise<PilotSwarmSession>;
     /**
      * Create a session bound to a named agent.
@@ -68,6 +70,7 @@ export declare class PilotSwarmClient {
         splash?: string;
         initialPrompt?: string;
         owner?: SessionOwnerInfo | null;
+        groupId?: string | null;
     }): Promise<PilotSwarmSession>;
     /**
      * Create a system session (e.g. Sweeper Agent).
@@ -183,7 +186,7 @@ export declare class PilotSwarmSession {
     cancelPendingMessage(clientMessageIds: string[]): Promise<void>;
     abort(): Promise<void>;
     destroy(): Promise<void>;
-    /** Get all persisted events for this session from CMS. */
+    /** Get a provider-capped latest page of persisted events from CMS. Use event paging to drain complete history. */
     getMessages(limit?: number): Promise<SessionEvent[]>;
     getInfo(): Promise<PilotSwarmSessionInfo>;
     private _startPolling;

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

@@ -2,6 +2,7 @@ import { RESPONSE_LATEST_KEY, } from "./types.js";
 import { DURABLE_SESSION_LATEST_VERSION, DURABLE_SESSION_ORCHESTRATION_NAME, } from "./orchestration-registry.js";
 import { PgSessionCatalogProvider } from "./cms.js";
 import { createFactStoreForUrl } from "./facts-store.js";
+import { createDuroxidePostgresProvider } from "./duroxide-provider-factory.js";
 import { deriveStatusFromCmsAndRuntime, shouldSyncCompletedStatus, shouldSyncFailedStatus } from "./session-status.js";
 // duroxide is CommonJS — use createRequire for ESM compatibility
 import { createRequire } from "node:module";
@@ -108,6 +109,7 @@ export class PilotSwarmClient {
             reasoningEffort: config?.reasoningEffort,
             parentSessionId: config?.parentSessionId,
             owner: config?.owner ?? null,
+            groupId: config?.groupId ?? null,
         });
         // Track parentSessionId for sub-agent orchestration input
         if (config?.parentSessionId) {
@@ -147,6 +149,7 @@ export class PilotSwarmClient {
             boundAgentName: agentName,
             promptLayering: { kind: "app-agent" },
             owner: opts?.owner ?? null,
+            groupId: opts?.groupId ?? null,
         });
         // Set agent metadata in CMS (agentId + prefixed title)
         const shortId = session.sessionId.slice(0, 8);
@@ -258,6 +261,10 @@ export class PilotSwarmClient {
             isSystem: row.isSystem || undefined,
             agentId: row.agentId ?? undefined,
             splash: row.splash ?? undefined,
+            groupId: row.groupId ?? undefined,
+            shortSummary: row.shortSummary ?? undefined,
+            summaryState: row.summaryState ?? undefined,
+            summaryUpdatedAt: row.summaryUpdatedAt ?? undefined,
         }));
     }
     async deleteSession(sessionId) {
@@ -311,10 +318,13 @@ export class PilotSwarmClient {
         const _trace = this.config.traceWriter ?? (() => { });
         const startedAt = Date.now();
         const trace = (message) => _trace(`[+${Date.now() - startedAt}ms] ${message}`);
-        // CMS + facts may use a passwordless URL (AAD/MI) while duroxide
-        // stays on the password URL. When `useManagedIdentity` is set the
-        // caller is expected to pass `cmsFactsDatabaseUrl` (a passwordless
-        // form). When unset (legacy / local), both pools reuse `store`.
+        // CMS + facts may use a separate URL when running with AAD/MI
+        // (passwordless URL whose `user@` segment is the federated UAMI's
+        // display name). Defaults to `store` for the legacy
+        // connection-string path. The duroxide orchestration store
+        // honours the same MI switch via duroxide-node's native Entra
+        // path; CMS/facts go through the pg-pool factory using
+        // `DefaultAzureCredential`.
         const cmsFactsUrl = this.config.cmsFactsDatabaseUrl ?? store;
         const useMi = this.config.useManagedIdentity ?? false;
         const aadUser = this.config.aadDbUser;
@@ -325,9 +335,9 @@ export class PilotSwarmClient {
         else if (store.startsWith("sqlite://"))
             provider = SqliteProvider.open(store);
         else if (store.startsWith("postgres://") || store.startsWith("postgresql://")) {
-            trace("[client] connectWithSchema start...");
-            provider = await PostgresProvider.connectWithSchema(store, this.config.duroxideSchema ?? DEFAULT_DUROXIDE_SCHEMA);
-            trace("[client] connectWithSchema done");
+            trace("[client] duroxide provider connect start...");
+            provider = await createDuroxidePostgresProvider(PostgresProvider, store, this.config.duroxideSchema ?? DEFAULT_DUROXIDE_SCHEMA, { useManagedIdentity: useMi, aadUser });
+            trace("[client] duroxide provider connect done");
         }
         else {
             throw new Error(`Unsupported store URL: ${store}`);
@@ -545,6 +555,21 @@ export class PilotSwarmClient {
             : null;
         const cronActive = customStatus.cronActive === true;
         const cronInterval = typeof customStatus.cronInterval === "number" ? customStatus.cronInterval : undefined;
+        const cronKind = cronActive && (customStatus.cronKind === "wall-clock" || customStatus.cronKind === "interval")
+            ? customStatus.cronKind
+            : undefined;
+        const cronNextFireAt = cronActive && typeof customStatus.cronNextFireAt === "number"
+            ? customStatus.cronNextFireAt
+            : undefined;
+        const cronTimezone = cronActive && typeof customStatus.cronTimezone === "string"
+            ? customStatus.cronTimezone
+            : undefined;
+        const cronMaxFires = cronActive && typeof customStatus.cronMaxFires === "number"
+            ? customStatus.cronMaxFires
+            : undefined;
+        const cronFiresCompleted = cronActive && typeof customStatus.cronFiresCompleted === "number"
+            ? customStatus.cronFiresCompleted
+            : undefined;
         const status = deriveStatusFromCmsAndRuntime({
             row: cmsRow,
             customStatus,
@@ -607,6 +632,10 @@ export class PilotSwarmClient {
             title: cmsRow?.title ?? undefined,
             agentId: cmsRow?.agentId ?? undefined,
             owner: cmsRow?.owner ?? undefined,
+            groupId: cmsRow?.groupId ?? undefined,
+            shortSummary: cmsRow?.shortSummary ?? undefined,
+            summaryState: cmsRow?.summaryState ?? undefined,
+            summaryUpdatedAt: cmsRow?.summaryUpdatedAt ?? undefined,
             createdAt: cmsRow?.createdAt ?? new Date(),
             updatedAt: cmsRow?.updatedAt ?? new Date(),
             iterations: customStatus.iteration ?? cmsRow?.currentIteration ?? 0,
@@ -625,6 +654,11 @@ export class PilotSwarmClient {
             waitReason: customStatus.waitReason,
             cronActive,
             cronInterval,
+            cronKind,
+            cronNextFireAt,
+            cronTimezone,
+            cronMaxFires,
+            cronFiresCompleted,
             cronReason: typeof customStatus.cronReason === "string" ? customStatus.cronReason : undefined,
             contextUsage: customStatus?.contextUsage && typeof customStatus.contextUsage === "object"
                 ? customStatus.contextUsage
@@ -876,7 +910,7 @@ export class PilotSwarmSession {
         this._stopPolling();
         await this.client.deleteSession(this.sessionId);
     }
-    /** Get all persisted events for this session from CMS. */
+    /** Get a provider-capped latest page of persisted events from CMS. Use event paging to drain complete history. */
     async getMessages(limit) {
         const catalog = this.client._getCatalog();
         return catalog.getSessionEvents(this.sessionId, undefined, limit);