@roj-ai/sdk 0.1.35 → 0.2.1

package/dist/core/sessions/session-manager.js

@@ -8,15 +8,19 @@
  */
 import { join } from 'node:path';
 import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '../../core/agents/agent-roles.js';
+import { parseAgentWakeKey, parsePluginWakeKey } from '../../core/wake-key.js';
 import { generateAgentId } from '../../core/agents/schema.js';
 import { agentEvents } from '../../core/agents/state.js';
 import { PresetErrors, SessionErrors, ValidationErrors } from '../../core/errors.js';
 import { withSessionId } from '../../core/events/test-helpers.js';
+import { DEFAULT_PLUGIN_ORDER } from '../../core/plugins/plugin-builder.js';
+import { AGENT_CALLER } from '../../core/plugins/plugin-builder.js';
 import { knownDefinitionNames, unknownOverrideTargets } from '../../core/preset/overrides.js';
-import { generateSessionId } from '../../core/sessions/schema.js';
+import { generateSessionId, isValidSessionId, SessionId } from '../../core/sessions/schema.js';
 import { checkRecoveryNeeded, isSessionCreatedEvent, reconstructSessionState, sessionEvents } from '../../core/sessions/state.js';
-import { FileLogger } from '../../lib/logger/file.js';
+import { createSessionLogger } from '../../lib/logger/session-log.js';
 import { TeeLogger } from '../../lib/logger/tee.js';
+import { isLiveScheduler } from '../../platform/index.js';
 import { Err, Ok } from '../../lib/utils/result.js';
 import { getAgentUnconsumedMailbox, selectMailboxState } from '../../plugins/mailbox/query.js';
 import { selectSessionStats } from '../../plugins/session-stats/index.js';
@@ -24,6 +28,7 @@ import { createApplyEvent } from './apply-event.js';
 import { rewriteEventsForFork } from './fork-utils.js';
 import { SessionStore } from './session-store.js';
 import { Session } from './session.js';
+import { SessionRuntimeActivityController } from './runtime-activity.js';
 // ============================================================================
 // Errors
 // ============================================================================
@@ -39,13 +44,18 @@ class SessionLoadError extends Error {
         this.name = 'SessionLoadError';
     }
 }
+// Both parking causes map to `evicted`: the session survives and the next access rebuilds its runtime.
+const RUNTIME_DISPOSAL_CLOSE_REASON = {
+    idle: 'evicted',
+    disposed: 'evicted',
+    closed: 'closed',
+    shutdown: 'shutdown',
+};
 /**
  * SessionManager manages session lifecycle and caching.
  */
 export class SessionManager {
     sessions = new Map();
-    /** Unsubscribe functions for session event listeners, keyed by sessionId */
-    sessionListenerCleanup = new Map();
     /** Manager-level methods collected from plugin definitions across all presets */
     managerMethods;
     eventStore;
@@ -58,12 +68,24 @@ export class SessionManager {
     dataFileStore;
     onUserOutput;
     preprocessorRegistry;
+    uploadArchiveLimits;
+    resourceArchiveLimits;
     llmLogger;
     portPool;
     pidRegistry;
     platform;
     systemPlugins;
+    sessionIdleTimeoutMs;
+    evictionSweepTimer;
+    cacheHits = 0;
+    cacheMisses = 0;
+    cacheEvictions = 0;
+    /** Set by shutdown(). Also fences wakes: one armed before it must not reload a session after it. */
+    shuttingDown = false;
     constructor(options) {
+        if (options.sessionIdleTimeoutMs !== undefined && (!Number.isSafeInteger(options.sessionIdleTimeoutMs) || options.sessionIdleTimeoutMs < 0)) {
+            throw new Error(`Invalid sessionIdleTimeoutMs: ${options.sessionIdleTimeoutMs}`);
+        }
         this.eventStore = options.eventStore;
         this.llmProvider = options.llmProvider;
         this.llmProviders = options.llmProviders ?? new Map();
@@ -74,21 +96,111 @@ export class SessionManager {
         this.dataFileStore = options.dataFileStore;
         this.onUserOutput = options.onUserOutput;
         this.preprocessorRegistry = options.preprocessorRegistry;
+        this.uploadArchiveLimits = options.uploadArchiveLimits;
+        this.resourceArchiveLimits = options.resourceArchiveLimits;
         this.llmLogger = options.llmLogger;
         this.portPool = options.portPool;
         this.pidRegistry = options.pidRegistry;
         this.platform = options.platform;
         this.systemPlugins = options.systemPlugins ?? [];
+        this.sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? 0;
         this.managerMethods = this.collectManagerMethods();
+        if (this.sessionIdleTimeoutMs > 0) {
+            const sweepIntervalMs = Math.min(this.sessionIdleTimeoutMs, 60_000);
+            this.evictionSweepTimer = setInterval(() => {
+                void this.evictIdleSessions();
+            }, sweepIntervalMs);
+            this.evictionSweepTimer.unref();
+        }
+        // A live scheduler has nowhere else to deliver. Hosts that wake out-of-band
+        // (a Durable Object alarm) call dispatchWake() from their own handler.
+        const scheduler = this.platform.scheduler;
+        if (isLiveScheduler(scheduler)) {
+            scheduler.onWake(async (key) => {
+                try {
+                    await this.dispatchWake(key);
+                }
+                catch (error) {
+                    this.logger.error('Scheduler wake dispatch failed', error instanceof Error ? error : new Error(String(error)), { key });
+                }
+            });
+        }
     }
     /** Expose platform adapters (used by Session for building contexts). */
     getPlatform() {
         return this.platform;
     }
+    /**
+     * Deliver a scheduler wake that has come due.
+     *
+     * The host's entry point back into the SDK — on Cloudflare, called from
+     * `alarm()` in an isolate that never armed the wake. SessionManager owns it
+     * because it is the only thing that can turn a session id back into a live
+     * session, so the key alone is enough input.
+     *
+     * Two vocabularies route here: `agent:` wakes re-enter the agent loop,
+     * `plugin:` wakes call a plugin method. Anything else is a quiet no-op, and so
+     * is a key naming a session, agent or plugin that is gone — wakes outlive what
+     * they point at. Only genuinely unexpected failures (event store IO) throw, so
+     * a host that retries alarms retries those and only those.
+     */
+    async dispatchWake(key) {
+        const agentWake = parseAgentWakeKey(key);
+        if (agentWake) {
+            await this.withWakeTarget(key, agentWake.sessionId, async (session) => {
+                await session.getAgent(agentWake.agentId)?.deliverWake(agentWake.kind);
+            });
+            return;
+        }
+        const pluginWake = parsePluginWakeKey(key);
+        if (pluginWake) {
+            await this.withWakeTarget(key, pluginWake.sessionId, async (session) => {
+                const result = await session.callPluginMethod(`${pluginWake.pluginName}.${pluginWake.method}`, pluginWake.agentId === undefined ? {} : { agentId: pluginWake.agentId }, pluginWake.agentId, AGENT_CALLER);
+                // A preset that no longer registers the plugin lands here, same as a
+                // missing agent does: the wake points at something that is gone.
+                if (!result.ok)
+                    this.logger.debug('Scheduler wake method rejected', { key, error: result.error.type });
+            });
+            return;
+        }
+        this.logger.debug('Ignoring unrecognized scheduler wake key', { key });
+    }
+    /** Run `deliver` against the session a due wake names, under a runtime lease. */
+    async withWakeTarget(key, sessionId, deliver) {
+        // Nothing armed before shutdown may load a session back in afterwards.
+        if (this.shuttingDown)
+            return;
+        // Nor may a wake that lands mid-teardown rebuild what is being torn down —
+        // getSession() would wait out the unload and reload. onSessionReady re-arms.
+        const resident = this.sessions.get(sessionId);
+        if (resident && (resident.state === 'evicting' || resident.activity.getSnapshot().state !== 'ready'))
+            return;
+        const sessionResult = await this.getSession(sessionId);
+        if (!sessionResult.ok) {
+            this.logger.debug('Scheduler wake for a session that no longer loads', { key, error: sessionResult.error.type });
+            return;
+        }
+        const session = sessionResult.value;
+        // A closed session's log is sealed; re-entering it would only fail to write.
+        if (session.state.status === 'closed')
+            return;
+        // Lease the delivery, not the delay before it — an idle session stays evictable while it waits.
+        const release = session.tryAcquireRuntimeLease(`wake:${key}`);
+        if (!release)
+            return;
+        try {
+            await deliver(session);
+        }
+        finally {
+            release();
+        }
+    }
     /**
      * Create a new session with the given preset.
      */
     async createSession(presetId, options) {
+        if (this.shuttingDown)
+            return Err(ValidationErrors.invalid('Session manager is shutting down'));
         const preset = this.presets.get(presetId);
         if (!preset) {
             return Err(PresetErrors.notFound(presetId));
@@ -99,7 +211,12 @@ export class SessionManager {
                 return Err(ValidationErrors.invalid(`Unknown agent definitions in overrides: ${unknown.join(', ')}. Preset '${presetId}' defines: ${knownDefinitionNames(preset).join(', ')}`));
             }
         }
-        const sessionId = options?.sessionId ? options.sessionId : generateSessionId();
+        // Validate before anything derives a path from it — the id reaches join() for the
+        // session dir, the event log and the file logger, and path.join collapses `..`.
+        if (options?.sessionId !== undefined && !isValidSessionId(options.sessionId)) {
+            return Err(ValidationErrors.invalid(`Invalid session id: ${JSON.stringify(options.sessionId)}`));
+        }
+        const sessionId = options?.sessionId ? SessionId(options.sessionId) : generateSessionId();
         // First orchestrator gets seq 1
         const orchestratorId = generateAgentId(ORCHESTRATOR_ROLE, 1);
         // Resolve workspaceDir: API input overrides preset default
@@ -145,21 +262,45 @@ export class SessionManager {
                 orchestratorId,
             })));
         }
-        // Write events to event store
-        await this.eventStore.appendBatch(sessionId, events);
-        // Build plugins and composed reducer so plugin state slices are applied
-        const plugins = this.buildPlugins(preset);
-        const composedReducer = createApplyEvent(plugins);
-        // Reconstruct state with composed reducer (includes plugin state slices)
-        const state = reconstructSessionState(events, composedReducer);
-        if (!state) {
-            return Err(ValidationErrors.invalid('Failed to reconstruct session'));
-        }
-        // Create store and session (initPluginContexts + onSessionReady hooks run inside)
-        const store = new SessionStore(sessionId, this.eventStore, state, composedReducer);
-        const session = await this.createSessionInstance(store, preset, plugins);
-        // Cache session (wrap in resolved promise for consistency)
-        this.sessions.set(sessionId, Promise.resolve(session));
+        if (this.sessions.has(sessionId))
+            return Err(SessionErrors.alreadyExists(String(sessionId)));
+        const activity = new SessionRuntimeActivityController();
+        let entry;
+        const creationPromise = Promise.resolve().then(async () => {
+            if (await this.eventStore.exists(sessionId))
+                throw new SessionLoadError(SessionErrors.alreadyExists(String(sessionId)));
+            await this.eventStore.appendBatch(sessionId, events);
+            const plugins = this.buildPlugins(preset);
+            const composedReducer = createApplyEvent(plugins);
+            const state = reconstructSessionState(events, composedReducer);
+            if (!state)
+                throw new SessionLoadError(ValidationErrors.invalid('Failed to reconstruct session'));
+            const store = new SessionStore(sessionId, this.eventStore, state, composedReducer);
+            return this.createSessionInstance(store, preset, plugins, entry);
+        });
+        entry = {
+            state: 'loading',
+            promise: creationPromise,
+            activity,
+            lastAccessAt: performance.now(),
+        };
+        this.sessions.set(sessionId, entry);
+        let session;
+        try {
+            session = await creationPromise;
+            if (this.sessions.get(sessionId) === entry && entry.state === 'loading') {
+                entry.state = 'ready';
+                entry.lastAccessAt = performance.now();
+            }
+        }
+        catch (error) {
+            if (this.sessions.get(sessionId) === entry)
+                this.sessions.delete(sessionId);
+            entry.listenerCleanup?.();
+            if (error instanceof SessionLoadError)
+                return Err(error.domainError);
+            throw error;
+        }
         this.logger.info('Session created', {
             sessionId,
             presetId,
@@ -172,8 +313,12 @@ export class SessionManager {
      * The forked session gets a copy of all events up to the fork point.
      */
     async forkSession(sourceSessionId, eventIndex) {
+        if (this.shuttingDown)
+            return Err(ValidationErrors.invalid('Session manager is shutting down'));
         // Load source events
         const sourceEvents = await this.eventStore.load(sourceSessionId);
+        if (this.shuttingDown)
+            return Err(ValidationErrors.invalid('Session manager is shutting down'));
         if (sourceEvents.length === 0) {
             return Err(SessionErrors.notFound(String(sourceSessionId)));
         }
@@ -210,32 +355,48 @@ export class SessionManager {
                 return event;
             });
         }
-        // Write forked events to event store
-        await this.eventStore.appendBatch(newSessionId, forkedEvents);
-        // Build plugins and composed reducer so plugin state slices are applied
-        const plugins = this.buildPlugins(preset);
-        const composedReducer = createApplyEvent(plugins);
-        // Reconstruct state with composed reducer (includes plugin state slices)
-        const state = reconstructSessionState(forkedEvents, composedReducer);
-        if (!state) {
-            return Err(ValidationErrors.invalid('Failed to reconstruct forked session'));
-        }
-        // Create store
-        const store = new SessionStore(newSessionId, this.eventStore, state, composedReducer);
-        // Normalize stuck agents via session_restarted event
-        const recoveryData = checkRecoveryNeeded(state);
-        if (recoveryData) {
-            await store.emit(withSessionId(newSessionId, sessionEvents.create('session_restarted', {
-                resetAgentIds: recoveryData.resetAgentIds,
-                clearedToolAgentIds: recoveryData.clearedToolAgentIds,
-            })));
+        const activity = new SessionRuntimeActivityController();
+        let entry;
+        const forkPromise = Promise.resolve().then(async () => {
+            await this.eventStore.appendBatch(newSessionId, forkedEvents);
+            const plugins = this.buildPlugins(preset);
+            const composedReducer = createApplyEvent(plugins);
+            const state = reconstructSessionState(forkedEvents, composedReducer);
+            if (!state)
+                throw new SessionLoadError(ValidationErrors.invalid('Failed to reconstruct forked session'));
+            const store = new SessionStore(newSessionId, this.eventStore, state, composedReducer);
+            const recoveryData = checkRecoveryNeeded(state);
+            if (recoveryData) {
+                await store.emit(withSessionId(newSessionId, sessionEvents.create('session_restarted', {
+                    resetAgentIds: recoveryData.resetAgentIds,
+                    clearedToolAgentIds: recoveryData.clearedToolAgentIds,
+                })));
+            }
+            return this.createSessionInstance(store, preset, plugins, entry);
+        });
+        entry = {
+            state: 'loading',
+            promise: forkPromise,
+            activity,
+            lastAccessAt: performance.now(),
+        };
+        this.sessions.set(newSessionId, entry);
+        let session;
+        try {
+            session = await forkPromise;
+            if (this.sessions.get(newSessionId) === entry && entry.state === 'loading')
+                entry.state = 'ready';
+        }
+        catch (error) {
+            if (this.sessions.get(newSessionId) === entry)
+                this.sessions.delete(newSessionId);
+            entry.listenerCleanup?.();
+            if (error instanceof SessionLoadError)
+                return Err(error.domainError);
+            throw error;
         }
-        // Create session instance (auto-start services run via onSessionReady)
-        const session = await this.createSessionInstance(store, preset, plugins);
         // Check for pending agents
         session.checkPendingAgents();
-        // Cache session
-        this.sessions.set(newSessionId, Promise.resolve(session));
         this.logger.info('Session forked', {
             sourceSessionId,
             newSessionId,
@@ -247,39 +408,62 @@ export class SessionManager {
      * Get a session by ID - from cache or load from event store.
      */
     async getSession(sessionId) {
-        // Check cache first
-        const cached = this.sessions.get(sessionId);
-        if (cached) {
+        while (true) {
+            if (this.shuttingDown)
+                return Err(ValidationErrors.invalid('Session manager is shutting down'));
+            let entry = this.sessions.get(sessionId);
+            if (entry?.state === 'evicting') {
+                await entry.unloadPromise;
+                continue;
+            }
+            if (entry?.state === 'ready' && entry.activity.getSnapshot().state !== 'ready') {
+                const session = await entry.promise;
+                await this.beginCacheEntryDisposal(sessionId, entry, session, 'disposed');
+                continue;
+            }
+            if (entry) {
+                this.cacheHits++;
+                entry.lastAccessAt = performance.now();
+            }
+            else {
+                this.cacheMisses++;
+                const activity = new SessionRuntimeActivityController();
+                let loadingEntry;
+                const promise = Promise.resolve().then(() => this.loadSession(sessionId, loadingEntry));
+                loadingEntry = {
+                    state: 'loading',
+                    activity,
+                    lastAccessAt: performance.now(),
+                    promise,
+                };
+                entry = loadingEntry;
+                this.sessions.set(sessionId, entry);
+            }
             try {
-                return Ok(await cached);
+                const session = await entry.promise;
+                if (this.sessions.get(sessionId) === entry && entry.state === 'loading') {
+                    if (session.state.status === 'closed')
+                        this.sessions.delete(sessionId);
+                    else {
+                        entry.state = 'ready';
+                        entry.lastAccessAt = performance.now();
+                    }
+                }
+                return Ok(session);
             }
             catch (error) {
-                // Previous load failed, remove from cache and try again
-                this.sessions.delete(sessionId);
-                if (error instanceof SessionLoadError) {
+                if (this.sessions.get(sessionId) === entry)
+                    this.sessions.delete(sessionId);
+                if (error instanceof SessionLoadError)
                     return Err(error.domainError);
-                }
                 throw error;
             }
         }
-        // Store promise immediately to prevent concurrent loads
-        const loadPromise = this.loadSession(sessionId);
-        this.sessions.set(sessionId, loadPromise);
-        try {
-            return Ok(await loadPromise);
-        }
-        catch (error) {
-            this.sessions.delete(sessionId);
-            if (error instanceof SessionLoadError) {
-                return Err(error.domainError);
-            }
-            throw error;
-        }
     }
     /**
      * Internal session loading - throws SessionLoadError on domain errors.
      */
-    async loadSession(sessionId) {
+    async loadSession(sessionId, entry) {
         // We need to peek at events first to determine the preset, so we can build plugins
         // and compose the reducer before loading the store
         const events = await this.eventStore.load(sessionId);
@@ -298,18 +482,16 @@ export class SessionManager {
         const plugins = this.buildPlugins(preset);
         const composedReducer = createApplyEvent(plugins);
         // Load store with composed reducer
-        const store = await SessionStore.load(sessionId, this.eventStore, composedReducer);
+        const store = await SessionStore.fromEvents(sessionId, this.eventStore, events, composedReducer);
         if (!store) {
             throw new SessionLoadError(SessionErrors.notFound(String(sessionId)));
         }
         const state = store.getState();
         // Don't cache closed sessions
         if (state.status === 'closed') {
-            // Remove from cache since we don't cache closed sessions
-            this.sessions.delete(sessionId);
             // Skip onSessionReady hooks — closed sessions are immutable, firing hooks
             // would emit events to a sealed event log on every read / restart.
-            return await this.createSessionInstance(store, preset, plugins, { skipReadyHooks: true });
+            return await this.createSessionInstance(store, preset, plugins, entry, { skipReadyHooks: true });
         }
         // Check if recovery is needed after restart
         const recoveryData = checkRecoveryNeeded(state);
@@ -325,7 +507,7 @@ export class SessionManager {
             });
         }
         // Create session (auto-start services run via onSessionReady)
-        const session = await this.createSessionInstance(store, preset, plugins);
+        const session = await this.createSessionInstance(store, preset, plugins, entry);
         // Check for pending agents
         session.checkPendingAgents();
         return session;
@@ -338,10 +520,48 @@ export class SessionManager {
      * @param agentId - Agent ID (optional — some methods don't operate on a specific agent)
      */
     async callPluginMethod(sessionId, method, input, agentId, caller) {
-        const sessionResult = await this.getSession(sessionId);
-        if (!sessionResult.ok)
-            return sessionResult;
-        return sessionResult.value.callPluginMethod(method, input, agentId, caller);
+        return this.withSessionLease(sessionId, `request:${method}`, (session) => (session.callPluginMethod(method, input, agentId, caller)));
+    }
+    /** Run an operation while atomically keeping the selected runtime resident. */
+    async withSessionLease(sessionId, reason, operation) {
+        const acquired = await this.acquireSessionLease(sessionId, reason);
+        if (!acquired.ok)
+            return acquired;
+        try {
+            return await operation(acquired.value.session);
+        }
+        finally {
+            acquired.value.release();
+        }
+    }
+    /** Atomically look up a runtime and acquire a caller-managed lease on it. */
+    async acquireSessionLease(sessionId, reason) {
+        while (true) {
+            const sessionResult = await this.getSession(sessionId);
+            if (!sessionResult.ok)
+                return sessionResult;
+            const entry = this.sessions.get(sessionId);
+            if (!entry)
+                return Ok({ session: sessionResult.value, release: () => { } });
+            const release = entry.activity.tryAcquire(reason);
+            if (!release) {
+                if (entry.unloadPromise)
+                    await entry.unloadPromise;
+                continue;
+            }
+            entry.lastAccessAt = performance.now();
+            let released = false;
+            return Ok({
+                session: sessionResult.value,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    entry.lastAccessAt = performance.now();
+                    release();
+                },
+            });
+        }
     }
     /**
      * Call a manager-level plugin method.
@@ -415,14 +635,16 @@ export class SessionManager {
         let pendingAgents = 0;
         let processingAgents = 0;
         let lastActivityAt = null;
-        // Wait for all sessions, ignoring failures
-        const sessions = await Promise.all(Array.from(this.sessions.values()).map((p) => p.catch(() => null)));
+        const metadataResult = await this.eventStore.listSessionsWithMetadata();
+        const openMetadata = metadataResult.sessions.filter((metadata) => metadata.status !== 'closed');
+        // Wait for resident sessions, ignoring failed and evicting loads.
+        const sessions = await Promise.all(Array.from(this.sessions.values())
+            .filter((entry) => entry.state !== 'evicting')
+            .map((entry) => entry.promise.catch(() => null)));
         // Filter out closed sessions — they do not contribute to activity
         const openSessions = sessions.filter((s) => s !== null && s.state.status !== 'closed');
-        // Fetch metadata only for open sessions
-        const metadataResults = await Promise.all(openSessions.map((s) => this.eventStore.getMetadata(s.state.id).catch(() => null)));
-        for (const metadata of metadataResults) {
-            if (metadata?.lastActivityAt) {
+        for (const metadata of openMetadata) {
+            if (metadata.lastActivityAt) {
                 if (lastActivityAt === null
                     || metadata.lastActivityAt > lastActivityAt) {
                     lastActivityAt = metadata.lastActivityAt;
@@ -430,6 +652,7 @@ export class SessionManager {
             }
         }
         const sessionStats = [];
+        const loadedById = new Map(openSessions.map((session) => [session.id, session]));
         for (const session of openSessions) {
             for (const [agentId, agentState] of session.state.agents) {
                 if (agentState.status === 'pending') {
@@ -443,15 +666,19 @@ export class SessionManager {
                     processingAgents++;
                 }
             }
+        }
+        for (const metadata of openMetadata) {
+            const loaded = loadedById.get(metadata.sessionId);
             sessionStats.push({
-                id: session.state.id,
-                presetId: session.state.presetId,
-                status: session.state.status,
-                metrics: selectSessionStats(session.state),
+                id: metadata.sessionId,
+                presetId: metadata.presetId,
+                status: loaded?.state.status ?? metadata.status,
+                metrics: loaded ? selectSessionStats(loaded.state) : statsFromMetadata(metadata),
             });
         }
         return {
-            sessionCount: openSessions.length,
+            sessionCount: openMetadata.length,
+            loadedSessionCount: openSessions.length,
             pendingAgents,
             processingAgents,
             lastActivityAt,
@@ -462,31 +689,75 @@ export class SessionManager {
      * Shutdown - clean up all sessions.
      */
     async shutdown() {
-        // Wait for all sessions, ignoring failures
-        const sessions = await Promise.all(Array.from(this.sessions.values()).map((p) => p.catch(() => null)));
-        for (const session of sessions) {
-            if (session) {
-                session.shutdown();
+        this.shuttingDown = true;
+        if (this.evictionSweepTimer)
+            clearInterval(this.evictionSweepTimer);
+        await Promise.all([...this.sessions].map(async ([sessionId, entry]) => {
+            try {
+                const session = await entry.promise;
+                await this.beginCacheEntryDisposal(sessionId, entry, session, 'shutdown');
             }
-        }
+            catch (error) {
+                entry.listenerCleanup?.();
+                entry.listenerCleanup = undefined;
+                this.logger.error('Failed to dispose session during shutdown', error instanceof Error ? error : new Error(String(error)), { sessionId });
+            }
+        }));
         this.sessions.clear();
-        for (const cleanup of this.sessionListenerCleanup.values()) {
-            cleanup();
-        }
-        this.sessionListenerCleanup.clear();
         this.logger.info('SessionManager shutdown complete');
     }
+    /** Narrow runtime-cache diagnostics for lifecycle tests and operational logs. */
+    getRuntimeCacheStats() {
+        return {
+            hits: this.cacheHits,
+            misses: this.cacheMisses,
+            evictions: this.cacheEvictions,
+            loadedSessionCount: this.sessions.size,
+            sessions: [...this.sessions].map(([id, entry]) => {
+                const activity = entry.activity.getSnapshot();
+                return {
+                    id,
+                    state: entry.state,
+                    lastAccessAt: Math.max(entry.lastAccessAt, activity.lastActivityAt),
+                    activeLeaseCount: activity.activeCount,
+                    leaseReasons: activity.reasons,
+                };
+            }),
+        };
+    }
+    /**
+     * Sessions whose runtime is already resident and ready.
+     *
+     * Deliberately does not load, and does not refresh `lastAccessAt` — a passive
+     * reader must not keep a runtime alive or resurrect an evicted one. Use this
+     * over `getSession()` for read-only sweeps across sessions.
+     */
+    async listResidentSessions() {
+        const entries = [...this.sessions].filter(([, entry]) => entry.state === 'ready');
+        const sessions = await Promise.all(entries.map(async ([sessionId, entry]) => {
+            const session = await entry.promise.catch(() => null);
+            // Re-check: the entry can start evicting while we await the resolved promise.
+            if (!session || this.sessions.get(sessionId) !== entry || entry.state !== 'ready')
+                return null;
+            return session;
+        }));
+        return sessions.filter((session) => session !== null);
+    }
     // ============================================================================
     // Private methods
     // ============================================================================
     /**
-     * Build ConfiguredPlugin[] for a session.
+     * Build ConfiguredPlugin[] for a session, in hook order.
      *
      * Iterates all system-registered plugins. For each:
      * 1. Check if preset has explicit SessionPluginConfig → use that config
      * 2. If not, try auto-deriving infrastructure config (agents, uploads, services)
      * 3. If no config at all → call .create() with no args (void config)
      * 4. Check isSessionEnabled — skip plugin if not enabled
+     *
+     * The result is sorted by each plugin's declared `.order()` — the precedence
+     * between plugins that both want the same hook, since most agent hooks stop
+     * at the first non-null result.
      */
     buildPlugins(preset) {
         // Build a lookup from preset Sessionplugins
@@ -546,7 +817,8 @@ export class SessionManager {
                 }
             }
         }
-        return plugins;
+        // Stable, so plugins that declare no order keep their registration order.
+        return plugins.sort((a, b) => (a.order ?? DEFAULT_PLUGIN_ORDER) - (b.order ?? DEFAULT_PLUGIN_ORDER));
     }
     /**
      * Build infrastructure-derived plugin configs from preset data.
@@ -569,7 +841,11 @@ export class SessionManager {
         configs.set('uploads', {
             dataFileStore: this.dataFileStore,
             preprocessorRegistry: this.preprocessorRegistry,
+            archiveLimits: this.uploadArchiveLimits,
         });
+        if (this.resourceArchiveLimits) {
+            configs.set('resources', { archiveLimits: this.resourceArchiveLimits });
+        }
         // services plugin — collect services from all agent definitions
         const allAgentConfigs = [preset.orchestrator, ...(preset.communicator ? [preset.communicator] : []), ...preset.agents];
         const servicesByType = new Map();
@@ -592,15 +868,11 @@ export class SessionManager {
      *   which must remain immutable: running hooks would emit session_handler_* events
      *   to a sealed event log on every introspection / restart cycle.
      */
-    async createSessionInstance(store, preset, plugins, opts = {}) {
-        // Only register cache eviction listener for active sessions (not closed)
-        if (store.getState().status !== 'closed') {
-            this.registerSessionEventListener(store.sessionId, store);
-        }
+    async createSessionInstance(store, preset, plugins, entry, opts = {}) {
         const sessionDir = this.getSessionDir(store.sessionId);
         const sessionLogger = new TeeLogger([
             this.logger.child({ sessionId: store.sessionId }),
-            new FileLogger(join(sessionDir, 'session.log'), this.platform.fs, { sessionId: String(store.sessionId) }),
+            createSessionLogger(this.platform, String(store.sessionId), join(sessionDir, 'session.log')),
         ]);
         // Create session
         const session = new Session({
@@ -616,20 +888,31 @@ export class SessionManager {
             eventStore: this.eventStore,
             llmLogger: this.llmLogger,
             platform: this.platform,
+            runtimeActivity: entry.activity,
+            registerReopenedSession: (reopenedSession) => this.registerReopenedSession(reopenedSession, entry.activity),
         });
+        // Only register cache eviction listener for active sessions (not closed)
+        if (store.getState().status !== 'closed') {
+            this.registerSessionEventListener(store.sessionId, store, session, entry);
+        }
         // Ensure session and workspace directories exist before plugins run
         await this.platform.fs.mkdir(sessionDir, { recursive: true });
         const workspaceDir = store.getState().workspaceDir;
         if (workspaceDir) {
             await this.platform.fs.mkdir(workspaceDir, { recursive: true });
         }
-        // Initialize plugin contexts (calls createContext for each plugin).
-        // Safe for closed sessions — createContext is pure local setup, no event emit.
-        await session.initPluginContexts();
-        // Call onSessionReady hooks with full context.
-        // Skipped for closed sessions to preserve event log immutability.
-        if (!opts.skipReadyHooks) {
-            await session.callSessionReadyHooks();
+        try {
+            // Safe for closed sessions — createContext is pure local setup, no event emit.
+            await session.initPluginContexts();
+            // Skipped for closed sessions to preserve event log immutability.
+            if (!opts.skipReadyHooks)
+                await session.callSessionReadyHooks();
+        }
+        catch (error) {
+            await session.dispose('evicted');
+            entry.listenerCleanup?.();
+            entry.listenerCleanup = undefined;
+            throw error;
         }
         return session;
     }
@@ -653,20 +936,136 @@ export class SessionManager {
      * Cleans up any previous listener for this sessionId (from a prior load)
      * to prevent duplicate listeners firing on old stores.
      */
-    registerSessionEventListener(sessionId, store) {
-        const prevCleanup = this.sessionListenerCleanup.get(sessionId);
-        if (prevCleanup)
-            prevCleanup();
+    registerSessionEventListener(sessionId, store, session, entry) {
+        entry.listenerCleanup?.();
         const unsubscribe = store.onEvent((event) => {
-            if (event.type === 'session_closed' || event.type === 'session_reopened') {
-                this.sessions.delete(sessionId);
-                this.sessionListenerCleanup.delete(sessionId);
+            if (event.type === 'session_closed') {
+                if (this.sessions.get(sessionId) === entry)
+                    this.beginCacheEntryDisposal(sessionId, entry, session, 'closed');
+                else
+                    void session.dispose('closed');
+            }
+            else if (event.type === 'session_reopened') {
+                if (this.sessions.get(sessionId) === entry)
+                    this.sessions.delete(sessionId);
+                unsubscribe();
+                entry.listenerCleanup = undefined;
             }
         });
-        this.sessionListenerCleanup.set(sessionId, unsubscribe);
+        entry.listenerCleanup = unsubscribe;
+    }
+    registerReopenedSession(session, activity) {
+        if (this.shuttingDown)
+            return Err(ValidationErrors.invalid('Session manager is shutting down'));
+        if (activity.getSnapshot().state !== 'ready')
+            return Ok(undefined);
+        if (this.sessions.has(session.id))
+            return Err(SessionErrors.alreadyExists(String(session.id)));
+        const deferred = Promise.withResolvers();
+        void deferred.promise.catch(() => { });
+        const entry = {
+            state: 'loading',
+            promise: deferred.promise,
+            activity,
+            lastAccessAt: performance.now(),
+        };
+        this.sessions.set(session.id, entry);
+        return Ok({
+            complete: async () => {
+                if (this.sessions.get(session.id) !== entry) {
+                    throw new Error(`Reopened session lost cache ownership: ${session.id}`);
+                }
+                this.registerSessionEventListener(session.id, session.store, session, entry);
+                try {
+                    await session.callSessionReadyHooks();
+                    session.checkPendingAgents();
+                    if (this.sessions.get(session.id) !== entry || entry.state !== 'loading' || activity.getSnapshot().state !== 'ready') {
+                        throw new Error(`Reopened session became unavailable during ready hooks: ${session.id}`);
+                    }
+                    entry.state = 'ready';
+                    entry.lastAccessAt = performance.now();
+                    deferred.resolve(session);
+                }
+                catch (error) {
+                    if (this.sessions.get(session.id) === entry)
+                        this.sessions.delete(session.id);
+                    entry.listenerCleanup?.();
+                    entry.listenerCleanup = undefined;
+                    deferred.reject(error);
+                    await session.dispose('evicted');
+                    throw error;
+                }
+            },
+            abort: (error) => {
+                if (this.sessions.get(session.id) === entry)
+                    this.sessions.delete(session.id);
+                entry.listenerCleanup?.();
+                entry.listenerCleanup = undefined;
+                deferred.reject(error);
+            },
+        });
+    }
+    async evictIdleSessions() {
+        if (this.sessionIdleTimeoutMs === 0)
+            return;
+        const now = performance.now();
+        const disposals = [];
+        for (const [sessionId, entry] of this.sessions) {
+            if (entry.state !== 'ready')
+                continue;
+            const activity = entry.activity.getSnapshot();
+            if (now - Math.max(entry.lastAccessAt, activity.lastActivityAt) < this.sessionIdleTimeoutMs)
+                continue;
+            if (!entry.activity.tryBeginUnload())
+                continue;
+            const session = await entry.promise;
+            disposals.push(this.beginCacheEntryDisposal(sessionId, entry, session, 'idle'));
+        }
+        await Promise.all(disposals);
+    }
+    beginCacheEntryDisposal(sessionId, entry, session, reason) {
+        if (entry.unloadPromise)
+            return entry.unloadPromise;
+        entry.state = 'evicting';
+        entry.activity.beginForcedUnload();
+        entry.unloadPromise = session.dispose(RUNTIME_DISPOSAL_CLOSE_REASON[reason])
+            .catch((error) => {
+            this.logger.error('Failed to dispose session runtime', error instanceof Error ? error : new Error(String(error)), { sessionId, reason });
+        })
+            .finally(() => {
+            if (this.sessions.get(sessionId) === entry)
+                this.sessions.delete(sessionId);
+            entry.listenerCleanup?.();
+            entry.listenerCleanup = undefined;
+            if (reason === 'idle')
+                this.cacheEvictions++;
+            this.logger.debug('Session runtime evicted', { sessionId, reason });
+        });
+        return entry.unloadPromise;
     }
     getSessionDir(sessionId) {
         return join(this.basePath, 'sessions', String(sessionId));
     }
 }
+function statsFromMetadata(metadata) {
+    return {
+        totalTokens: metadata.metrics?.totalTokens ?? 0,
+        promptTokens: metadata.metrics?.inputTokens ?? 0,
+        completionTokens: metadata.metrics?.outputTokens ?? 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        totalCost: metadata.metrics?.totalCost ?? 0,
+        llmCalls: metadata.metrics?.totalLLMCalls ?? 0,
+        llmErrors: 0,
+        toolCalls: metadata.metrics?.totalToolCalls ?? 0,
+        toolErrors: 0,
+        userMessages: metadata.metrics?.totalMessages ?? 0,
+        compactions: 0,
+        agentCount: metadata.metrics?.totalAgents ?? 0,
+        firstEventAt: metadata.createdAt,
+        lastEventAt: metadata.lastActivityAt,
+        byProvider: {},
+        byAgent: {},
+    };
+}
 //# sourceMappingURL=session-manager.js.map