pilotswarm-sdk 0.4.1 → 0.5.0

package/dist/session-lifecycle.js

@@ -0,0 +1,257 @@
+/**
+ * runTurn preamble/postamble for the session lifecycle protocol
+ * (docs/proposals/session-lifecycle-protocol.md §3.2–3.3).
+ *
+ * The whole lifecycle lives inside the single runTurn activity (principle
+ * P5 — no other session activity depends on landing where a previous one
+ * did):
+ *
+ *   preamble  p1. turn sentinel present → local dir untrusted → resolve from store
+ *             p2. marker == expected AND the dir has a usable layout → warm
+ *                 start (zero store I/O); else hydrate; store bearing this
+ *                 turn's own turnKey → already-committed recovery (restore,
+ *                 never replay); store AHEAD of expected under a foreign
+ *                 turnKey → loud failure (zombie-duplicate fence)
+ *             p3. (caller) write the turn sentinel just before the body
+ *   postamble c1. write .ps-turn-commit.json {turnKey, result} into the dir
+ *             c2. CAS-commit the tar (store.commitSnapshot); alreadyCommitted
+ *                 → restore the winner's snapshot + result (§3.2 r1–r3)
+ *             c3. write the local version marker
+ *             c4. clear the turn sentinel
+ *
+ * The CAS base is the PREAMBLE-RESOLVED version. Rebasing is allowed only
+ * when the store is BEHIND the orchestration's expectation (store restored
+ * from an older backup — self-healing); a store AHEAD of the expectation
+ * under a foreign turnKey means this attempt is a stale zombie duplicate
+ * and must fail loudly instead of re-applying its turn.
+ *
+ * @internal
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { faultPoint } from "./fault-injection.js";
+import { SnapshotConflictError, clearTurnSentinel, readSnapshotMarker, readTurnCommitFile, readTurnSentinel, writeSnapshotMarker, writeTurnCommitFile, } from "./snapshot-protocol.js";
+const COMMIT_TRANSIENT_RETRIES = 3;
+// Tunable so fault-injection tests don't pay real backoff delays.
+const COMMIT_RETRY_BASE_DELAY_MS = Number.parseInt(process.env.PILOTSWARM_COMMIT_RETRY_DELAY_MS ?? "", 10) || 1_000;
+function sessionDirOf(ctx) {
+    return path.join(ctx.sessionStateDir, ctx.sessionId);
+}
+/**
+ * A marker alone is not proof the dir survived intact (a crashed recursive
+ * delete removes files in arbitrary order and can leave the marker while
+ * the session files are gone). Require the SDK's layout anchor before
+ * trusting local files without consulting the store.
+ */
+function hasUsableSessionLayout(sessionDir) {
+    return fs.existsSync(path.join(sessionDir, "workspace.yaml"));
+}
+function markerFromHydrate(sessionDir, hydrated) {
+    writeSnapshotMarker(sessionDir, {
+        version: hydrated.version,
+        ...(hydrated.turnKey ? { turnKey: hydrated.turnKey } : {}),
+        ...(hydrated.contentHash ? { contentHash: hydrated.contentHash } : {}),
+    });
+}
+/** Restore the committed snapshot and return the stored result (§3.2 r1–r3). */
+async function recoverAlreadyCommitted(ctx) {
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    const commitFile = readTurnCommitFile(sessionDir);
+    if (commitFile && commitFile.turnKey === ctx.turnKey) {
+        ctx.trace(`session=${ctx.sessionId} already-committed recovery: store at v${hydrated.version} ` +
+            `under this turnKey; returning stored result without re-running the turn`);
+        return { kind: "already-committed", version: hydrated.version, result: commitFile.result };
+    }
+    // Snapshot claims our turnKey but carries no readable committed result —
+    // degrade to a hydrated re-run (duplicate execution beats a wrong result).
+    ctx.trace(`session=${ctx.sessionId} store bears this turnKey (v${hydrated.version}) but the ` +
+        `turn-commit file is missing/unreadable; degrading to hydrated re-run`);
+    return { kind: "hydrated", baseVersion: hydrated.version, storeBehindExpected: false };
+}
+async function resolveFromStore(ctx) {
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    const storeBehindExpected = hydrated.version < ctx.expectedVersion;
+    if (storeBehindExpected) {
+        ctx.trace(`session=${ctx.sessionId} store snapshot v${hydrated.version} is BEHIND the orchestration's ` +
+            `expected v${ctx.expectedVersion} (store restored from backup?); proceeding from stored state`);
+    }
+    return { kind: "hydrated", baseVersion: hydrated.version, storeBehindExpected };
+}
+/**
+ * Preamble (p1/p2). Runs under the per-session run-turn lock, before
+ * getOrCreate. On return the local dir is in exactly one of these states:
+ * trusted at `baseVersion` (warm/hydrated), absent (fresh), or restored at
+ * the committed version (already-committed — the caller returns the stored
+ * result without running the body).
+ */
+export async function runTurnPreamble(ctx) {
+    const sessionDir = sessionDirOf(ctx);
+    const sentinel = readTurnSentinel(sessionDir);
+    const marker = readSnapshotMarker(sessionDir);
+    const localDirExists = fs.existsSync(sessionDir);
+    const localDirUsable = localDirExists && hasUsableSessionLayout(sessionDir);
+    // p2 fast path: trusted local files at exactly the expected version.
+    // Requires the layout anchor — a marker orphaned by a torn delete must
+    // not be trusted (the store may hold a perfect copy).
+    if (!sentinel && marker && marker.version === ctx.expectedVersion && localDirUsable) {
+        return { kind: "warm", baseVersion: marker.version };
+    }
+    if (sentinel) {
+        ctx.trace(`session=${ctx.sessionId} turn sentinel present (started ${sentinel.startedAt || "unknown"}); ` +
+            `local dir untrusted, resolving from store`);
+    }
+    // Legacy warm continuity: the orchestration has never recorded a commit
+    // (expected 0) and the dir is clean but unmarked — typically a
+    // 1.0.56-era warm session that just migrated onto the new protocol.
+    // Trust it ONLY after confirming the store doesn't hold a versioned
+    // chain (a crash inside already-committed recovery of turn 1 leaves
+    // exactly this local shape while the store already has v1).
+    if (!sentinel && !marker && ctx.expectedVersion === 0 && localDirUsable) {
+        const probe0 = await ctx.store.probeSnapshot(ctx.sessionId);
+        if (!probe0.exists || probe0.legacy) {
+            return { kind: "warm", baseVersion: 0 };
+        }
+        if (probe0.turnKey && probe0.turnKey === ctx.turnKey) {
+            return recoverAlreadyCommitted(ctx);
+        }
+        ctx.trace(`session=${ctx.sessionId} unmarked local dir but the store holds versioned v${probe0.version}; ` +
+            `resolving from store`);
+        return resolveFromStore(ctx);
+    }
+    // Local is untrusted (dirty sentinel) or stale (marker mismatch/absent):
+    // resolve from the store.
+    const probe = await ctx.store.probeSnapshot(ctx.sessionId);
+    if (!probe.exists) {
+        // Nothing stored. A clean, usable dir is still the best data
+        // available — trust it over a fresh replay.
+        if (!sentinel && localDirUsable) {
+            ctx.trace(`session=${ctx.sessionId} store empty but clean local dir exists ` +
+                `(marker=${marker?.version ?? "none"} expected=${ctx.expectedVersion}); using local files`);
+            return { kind: "warm", baseVersion: marker?.version ?? 0 };
+        }
+        // Dirty or unusable local + empty store → fresh; lossy iff turns had
+        // been committed before (W3 in the protocol doc).
+        await ctx.dropWarmSession();
+        fs.rmSync(sessionDir, { recursive: true, force: true });
+        return { kind: "fresh", baseVersion: 0, lossy: ctx.expectedVersion > 0 };
+    }
+    // Already-committed recovery: the store bears this very turn's turnKey —
+    // the previous attempt crashed after its CAS landed (or a racing
+    // duplicate attempt already won). Restore, never replay.
+    if (probe.turnKey && probe.turnKey === ctx.turnKey) {
+        return recoverAlreadyCommitted(ctx);
+    }
+    // Zombie-duplicate fence: the store is AHEAD of what this attempt was
+    // scheduled against, under a DIFFERENT turn's key. A later turn already
+    // committed — re-running this one would silently double-apply it (and
+    // its rebased CAS would succeed). Fail loudly; duroxide's retry/poison
+    // machinery surfaces it instead of corrupting the chain.
+    if (ctx.expectedVersion > 0 && probe.version > ctx.expectedVersion) {
+        throw new SnapshotConflictError(ctx.sessionId, ctx.expectedVersion, probe.version, probe.turnKey);
+    }
+    // Normal resolve: hydrate exactly what the store holds (equal to
+    // expected after a migration/crash, or behind after a store restore).
+    return resolveFromStore(ctx);
+}
+/**
+ * Last-resort recovery when getOrCreate fails on missing/lost local state
+ * DESPITE the preamble's resolution (e.g. the SDK refused to resume from
+ * intact-looking files): restore the committed snapshot if one exists.
+ * Returns the hydrated version, or null when the store holds nothing —
+ * only then may the caller fall back to the lossy fresh replay, whose
+ * store-deleting reset is a no-op against an empty store.
+ */
+export async function attemptStoreRecovery(ctx) {
+    const probe = await ctx.store.probeSnapshot(ctx.sessionId);
+    if (!probe.exists)
+        return null;
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    return hydrated.version;
+}
+/**
+ * Postamble (c1–c4). Runs under the per-session run-turn lock after the
+ * body produced `result`. Transient store failures retry in place; a CAS
+ * conflict (foreign writer) always throws — the activity must fail loudly.
+ * An `alreadyCommitted` CAS outcome (a racing duplicate of this same turn
+ * won) triggers restore-not-replay: the winner's snapshot and result are
+ * adopted, discarding this attempt's divergent local state.
+ */
+export async function runTurnCommit(ctx, baseVersion, result) {
+    const sessionDir = sessionDirOf(ctx);
+    writeTurnCommitFile(sessionDir, ctx.turnKey, result);
+    faultPoint("turn.commit.before-cas");
+    let lastError;
+    for (let attempt = 1; attempt <= COMMIT_TRANSIENT_RETRIES; attempt++) {
+        try {
+            const committed = await ctx.store.commitSnapshot(ctx.sessionId, {
+                baseVersion,
+                turnKey: ctx.turnKey,
+            });
+            faultPoint("turn.commit.after-cas");
+            if (committed.alreadyCommitted) {
+                // §3.2 restore-not-replay: a racing attempt of this same
+                // turn committed first. Its snapshot is the durable lineage;
+                // this attempt's local files diverge and must be replaced.
+                ctx.trace(`session=${ctx.sessionId} commit found this turn already committed at ` +
+                    `v${committed.version} by a racing attempt; restoring the committed state`);
+                await ctx.dropWarmSession();
+                const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+                markerFromHydrate(sessionDir, hydrated);
+                clearTurnSentinel(sessionDir);
+                const commitFile = readTurnCommitFile(sessionDir);
+                return {
+                    version: committed.version,
+                    contentHash: hydrated.contentHash ?? committed.contentHash,
+                    ...(hydrated.sizeBytes != null ? { sizeBytes: hydrated.sizeBytes } : {}),
+                    ...(hydrated.rawSizeBytes != null ? { rawSizeBytes: hydrated.rawSizeBytes } : {}),
+                    alreadyCommitted: true,
+                    ...(commitFile && commitFile.turnKey === ctx.turnKey
+                        ? { storedResult: commitFile.result }
+                        : {}),
+                };
+            }
+            writeSnapshotMarker(sessionDir, {
+                version: committed.version,
+                turnKey: ctx.turnKey,
+                contentHash: committed.contentHash,
+            });
+            faultPoint("turn.commit.after-marker");
+            clearTurnSentinel(sessionDir);
+            faultPoint("turn.commit.after-sentinel-clear");
+            return {
+                version: committed.version,
+                contentHash: committed.contentHash,
+                ...(committed.sizeBytes != null ? { sizeBytes: committed.sizeBytes } : {}),
+                ...(committed.rawSizeBytes != null ? { rawSizeBytes: committed.rawSizeBytes } : {}),
+                alreadyCommitted: false,
+            };
+        }
+        catch (error) {
+            if (error instanceof SnapshotConflictError)
+                throw error;
+            lastError = error;
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.trace(`session=${ctx.sessionId} turn commit attempt ${attempt}/${COMMIT_TRANSIENT_RETRIES} ` +
+                `failed: ${message}`);
+            if (attempt < COMMIT_TRANSIENT_RETRIES) {
+                await new Promise((resolve) => setTimeout(resolve, COMMIT_RETRY_BASE_DELAY_MS * attempt));
+            }
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Turn commit failed for ${ctx.sessionId}: ${String(lastError)}`);
+}
+//# sourceMappingURL=session-lifecycle.js.map

package/dist/session-lifecycle.js.map

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

package/dist/session-manager.d.ts

@@ -123,6 +123,8 @@ export declare class SessionManager {
     private _getLineageSessionIds;
     /** Per-session critical sections; protects the SDK session handle and local session.db. */
     private sessionLocks;
+    /** Last local activity per session — feeds the autonomous eviction clock. */
+    private sessionLastTouchedAt;
     constructor(githubToken?: string | undefined, sessionStore?: SessionStateStore | null, workerDefaults?: WorkerDefaults, sessionStateDir?: string);
     /** Store full config (with tools/hooks) for a session. Called by PilotSwarmClient. */
     setConfig(sessionId: string, config: ManagedSessionConfig): void;
@@ -192,6 +194,16 @@ export declare class SessionManager {
     withRunTurnLock<T>(sessionId: string, operation: string, fn: () => Promise<T>, options?: {
         trace?: SessionTraceWriter;
     }): Promise<T>;
+    /**
+     * Autonomous eviction sweep (lifecycle protocol §3.4): local session
+     * state is a cache. A session idle past `evictAfterMs` is reclaimed
+     * without telling anyone — sessions with a committed snapshot marker
+     * are simply destroyed + deleted (the store already holds their state;
+     * the next runTurn self-validates and hydrates); unmarked (legacy)
+     * sessions are dehydrated the old way so their only copy is preserved.
+     * Returns the number of sessions reclaimed.
+     */
+    sweepIdleSessions(evictAfterMs: number): Promise<number>;
     /**
      * Stop-turn interrupt primitive: abort the warm session's in-flight turn.
      *
@@ -223,6 +235,15 @@ export declare class SessionManager {
     private _getOrCreateUnlocked;
     /** Get a session by ID (null if not in memory on this node). */
     get(sessionId: string): ManagedSession | null;
+    /** Root directory holding per-session state dirs. */
+    getSessionStateDir(): string;
+    /**
+     * Destroy the in-memory ManagedSession only — disk state untouched.
+     * Used by the lifecycle preamble before overwriting local files with a
+     * hydrated snapshot (a warm session bound to the old files must not
+     * survive the swap). Caller holds the per-session run-turn lock.
+     */
+    dropWarmSession(sessionId: string): Promise<void>;
     /**
      * Dehydrate a session: snapshot to the session store, release in-memory state.
      *

package/dist/session-manager.d.ts.map

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

package/dist/session-manager.js

@@ -9,6 +9,7 @@ import { buildKnowledgePromptBlocks, loadKnowledgeIndexFromFactStore, buildEnhan
 import { composeStructuredSystemMessage, extractPromptContent, mergePromptSections } from "./prompt-layering.js";
 import { buildPromptLayersEventPayload } from "./prompt-layers.js";
 import { approvePermissionForSession } from "./permissions.js";
+import { readSnapshotMarker, supportsVersionedSnapshots } from "./snapshot-protocol.js";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
@@ -148,6 +149,8 @@ export class SessionManager {
     _getLineageSessionIds = null;
     /** Per-session critical sections; protects the SDK session handle and local session.db. */
     sessionLocks = new Map();
+    /** Last local activity per session — feeds the autonomous eviction clock. */
+    sessionLastTouchedAt = new Map();
     constructor(githubToken, sessionStore, workerDefaults, sessionStateDir) {
         this.githubToken = githubToken;
         this.sessionStore = sessionStore ?? null;
@@ -433,7 +436,119 @@ export class SessionManager {
         }
     }
     async withRunTurnLock(sessionId, operation, fn, options) {
-        return this._withSessionLock(sessionId, operation, fn, options);
+        this.sessionLastTouchedAt.set(sessionId, Date.now());
+        try {
+            return await this._withSessionLock(sessionId, operation, fn, options);
+        }
+        finally {
+            this.sessionLastTouchedAt.set(sessionId, Date.now());
+        }
+    }
+    /**
+     * Autonomous eviction sweep (lifecycle protocol §3.4): local session
+     * state is a cache. A session idle past `evictAfterMs` is reclaimed
+     * without telling anyone — sessions with a committed snapshot marker
+     * are simply destroyed + deleted (the store already holds their state;
+     * the next runTurn self-validates and hydrates); unmarked (legacy)
+     * sessions are dehydrated the old way so their only copy is preserved.
+     * Returns the number of sessions reclaimed.
+     */
+    async sweepIdleSessions(evictAfterMs) {
+        if (!(evictAfterMs > 0))
+            return 0;
+        const now = Date.now();
+        // Only sessions THIS manager has actually served since boot are
+        // eviction candidates. Stranger dirs on disk (leftovers from a
+        // previous container life, or another embedded worker sharing the
+        // sessionStateDir) must never be pushed to the store — a stale dir
+        // dehydrated over a newer snapshot silently rolls the session back.
+        const candidates = new Set([
+            ...this.sessions.keys(),
+            ...this.sessionLastTouchedAt.keys(),
+        ]);
+        let reclaimed = 0;
+        for (const sessionId of candidates) {
+            if (this.sessionLocks.has(sessionId))
+                continue; // busy — never race a turn
+            const sessionDir = path.join(this.sessionStateDir, sessionId);
+            const lastTouched = this.sessionLastTouchedAt.get(sessionId);
+            if (lastTouched == null || now - lastTouched < evictAfterMs)
+                continue;
+            try {
+                await this._withSessionLock(sessionId, "eviction", async () => {
+                    // Re-check under the lock — a turn may have landed.
+                    const touched = this.sessionLastTouchedAt.get(sessionId);
+                    if (touched != null && Date.now() - touched < evictAfterMs)
+                        return;
+                    const dirExists = fs.existsSync(sessionDir);
+                    const committedMarker = dirExists ? readSnapshotMarker(sessionDir) : null;
+                    const existing = this.sessions.get(sessionId);
+                    if (existing) {
+                        try {
+                            await existing.destroy();
+                        }
+                        catch { }
+                        this.sessions.delete(sessionId);
+                    }
+                    if (!dirExists) {
+                        this.sessionLastTouchedAt.delete(sessionId);
+                        reclaimed++;
+                        return;
+                    }
+                    if (committedMarker) {
+                        // Committed snapshot in the store — pure local delete.
+                        fs.rmSync(sessionDir, { recursive: true, force: true });
+                        emitSessionManagerTrace(sessionId, `evicted (committed at v${committedMarker.version}); local cache reclaimed`);
+                    }
+                    else if (this.sessionStore) {
+                        // Unmarked dir. If the store already holds a VERSIONED
+                        // chain for this session, the local files are a stale
+                        // cache at best — reclaim without writing (a legacy
+                        // dehydrate would destroy the CAS metadata and could
+                        // roll the session back).
+                        const versioned = supportsVersionedSnapshots(this.sessionStore)
+                            ? await this.sessionStore.probeSnapshot(sessionId).catch(() => null)
+                            : null;
+                        if (versioned?.exists && !versioned.legacy) {
+                            fs.rmSync(sessionDir, { recursive: true, force: true });
+                            emitSessionManagerTrace(sessionId, `evicted (store versioned at v${versioned.version}); stale unmarked cache reclaimed`);
+                        }
+                        else {
+                            // Legacy session: its local files may be the only copy.
+                            await this._dehydrateUnlocked(sessionId, "eviction");
+                            emitSessionManagerTrace(sessionId, "evicted via legacy dehydrate (no committed marker)");
+                        }
+                    }
+                    else {
+                        return; // no store — leave local state alone
+                    }
+                    this.sessionLastTouchedAt.delete(sessionId);
+                    this.sessionClientKeys.delete(sessionId);
+                    reclaimed++;
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[SessionManager] eviction sweep skipped ${sessionId}: ${message}`);
+            }
+        }
+        // Reap crash-orphaned hydrate temp roots (finally blocks don't run
+        // on SIGKILL). They are dot-prefixed and never legitimate sessions.
+        try {
+            for (const entry of fs.readdirSync(this.sessionStateDir, { withFileTypes: true })) {
+                if (!entry.isDirectory() || !entry.name.startsWith(".ps-hydrate-"))
+                    continue;
+                const orphan = path.join(this.sessionStateDir, entry.name);
+                try {
+                    if (now - fs.statSync(orphan).mtimeMs > 3_600_000) {
+                        fs.rmSync(orphan, { recursive: true, force: true });
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return reclaimed;
     }
     /**
      * Stop-turn interrupt primitive: abort the warm session's in-flight turn.
@@ -508,6 +623,7 @@ export class SessionManager {
         return this._getOrCreateUnlocked(sessionId, serializableConfig, options);
     }
     async _getOrCreateUnlocked(sessionId, serializableConfig, options) {
+        this.sessionLastTouchedAt.set(sessionId, Date.now());
         const turnIndex = options?.turnIndex;
         const trace = options?.trace;
         const inheritedToolNames = Array.from(new Set([
@@ -838,6 +954,26 @@ export class SessionManager {
     get(sessionId) {
         return this.sessions.get(sessionId) ?? null;
     }
+    /** Root directory holding per-session state dirs. */
+    getSessionStateDir() {
+        return this.sessionStateDir;
+    }
+    /**
+     * Destroy the in-memory ManagedSession only — disk state untouched.
+     * Used by the lifecycle preamble before overwriting local files with a
+     * hydrated snapshot (a warm session bound to the old files must not
+     * survive the swap). Caller holds the per-session run-turn lock.
+     */
+    async dropWarmSession(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (!existing)
+            return;
+        try {
+            await existing.destroy();
+        }
+        catch { }
+        this.sessions.delete(sessionId);
+    }
     /**
      * Dehydrate a session: snapshot to the session store, release in-memory state.
      *