@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/dist/core/agent-session-runtime.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { copyFileSync, existsSync, constants as fsConstants, mkdirSync, unlinkSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { SessionManager } from "@caupulican/pi-agent-core/node";
 import { resolvePath } from "../utils/paths.js";
@@ -15,6 +15,35 @@ export class SessionImportFileNotFoundError extends Error {
         this.filePath = filePath;
     }
 }
+/** A teardown or activation failure at the replacement boundary, including rollback outcome. */
+export class SessionReplacementRuntimeError extends Error {
+    phase;
+    recovered;
+    transitionError;
+    recoveryError;
+    constructor(phase, transitionError, recovered, recoveryError) {
+        const transitionMessage = transitionError instanceof Error ? transitionError.message : String(transitionError);
+        super(recovered
+            ? `Session replacement ${phase} failed; the previous session was restored: ${transitionMessage}`
+            : `Session replacement ${phase} failed and the previous session could not be restored safely: ${transitionMessage}`);
+        this.name = "SessionReplacementRuntimeError";
+        this.phase = phase;
+        this.recovered = recovered;
+        this.transitionError = transitionError;
+        this.recoveryError = recoveryError;
+    }
+}
+/** A post-commit extension callback failed; the replacement itself remains the active session. */
+export class SessionReplacementCallbackError extends Error {
+    replacementCommitted = true;
+    callbackError;
+    constructor(callbackError) {
+        const callbackMessage = callbackError instanceof Error ? callbackError.message : String(callbackError);
+        super(`Session replacement completed, but its withSession callback failed: ${callbackMessage}`);
+        this.name = "SessionReplacementCallbackError";
+        this.callbackError = callbackError;
+    }
+}
 function extractUserMessageText(content) {
     if (typeof content === "string") {
         return content;
@@ -27,9 +56,8 @@ function extractUserMessageText(content) {
 /**
  * Owns the current AgentSession plus its cwd-bound services.
  *
- * Session replacement methods tear down the current runtime first, then create
- * and apply the next runtime. If creation fails, the error is propagated to the
- * caller. The caller is responsible for user-facing error handling.
+ * Session replacement methods construct the candidate runtime before retiring
+ * the current one. If preparation fails, the working session remains active.
  */
 export class AgentSessionRuntime {
     rebindSession;
@@ -39,6 +67,17 @@ export class AgentSessionRuntime {
     createRuntime;
     _diagnostics;
     _modelFallbackMessage;
+    _replacementInFlight;
+    _disposeInFlight;
+    _disposeStarted = false;
+    _disposed = false;
+    disposeProgress = {
+        shutdownEventEmitted: false,
+        stoppedResources: new Set(),
+        hostInvalidated: false,
+        sessionDisposed: false,
+    };
+    sessionResources = [];
     constructor(_session, _services, createRuntime, _diagnostics = [], _modelFallbackMessage) {
         this._session = _session;
         this._services = _services;
@@ -61,6 +100,10 @@ export class AgentSessionRuntime {
     get modelFallbackMessage() {
         return this._modelFallbackMessage;
     }
+    /** True from replacement admission until rebind and replacement callbacks have settled. */
+    get isReplacing() {
+        return this._replacementInFlight !== undefined;
+    }
     setRebindSession(rebindSession) {
         this.rebindSession = rebindSession;
     }
@@ -75,6 +118,12 @@ export class AgentSessionRuntime {
     setBeforeSessionInvalidate(beforeSessionInvalidate) {
         this.beforeSessionInvalidate = beforeSessionInvalidate;
     }
+    /** Register a resource whose lifecycle follows the active session (supervisors, watchers). */
+    registerSessionResource(resource) {
+        if (this.sessionResources.includes(resource))
+            return;
+        this.sessionResources.push(resource);
+    }
     async emitBeforeSwitch(reason, targetSessionFile) {
         const runner = this.session.extensionRunner;
         if (!runner.hasHandlers("session_before_switch")) {
@@ -100,13 +149,69 @@ export class AgentSessionRuntime {
         return { cancelled: result?.cancel === true };
     }
     async teardownCurrent(reason, targetSessionFile) {
-        await emitSessionShutdownEvent(this.session.extensionRunner, {
-            type: "session_shutdown",
-            reason,
-            targetSessionFile,
+        const errors = await this.shutdownRuntime(this.session, reason, targetSessionFile, {
+            stopResources: true,
+            invalidateHost: true,
         });
-        this.beforeSessionInvalidate?.();
-        this.session.dispose();
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Session runtime teardown failed.");
+    }
+    async discardPrepared(result) {
+        await result.session.disposeAndWait();
+    }
+    removeCreatedSessionFile(sessionFile) {
+        if (!sessionFile || sessionFile === this.session.sessionFile || !existsSync(sessionFile))
+            return;
+        try {
+            unlinkSync(sessionFile);
+        }
+        catch {
+            // Best-effort rollback of an artifact created solely for the rejected replacement.
+        }
+    }
+    async prepareReplacement(sessionManager, sessionStartEvent) {
+        return this.createRuntime({
+            cwd: sessionManager.getCwd(),
+            agentDir: this.services.agentDir,
+            sessionManager,
+            sessionStartEvent,
+        });
+    }
+    async commitReplacement(result, options) {
+        const previous = this.snapshot();
+        try {
+            await this.teardownCurrent(options.reason, options.targetSessionFile);
+        }
+        catch (transitionError) {
+            const recoveryError = await this.restorePreviousAfterRuntimeFailure(previous, result, options, false);
+            throw new SessionReplacementRuntimeError("teardown", transitionError, recoveryError === undefined, recoveryError);
+        }
+        this.apply(result);
+        try {
+            await this.activateReplacement(options);
+        }
+        catch (activationError) {
+            const recoveryError = await this.restorePreviousAfterRuntimeFailure(previous, result, options, true);
+            throw new SessionReplacementRuntimeError("activation", activationError, recoveryError === undefined, recoveryError);
+        }
+        if (options.withSession) {
+            try {
+                await options.withSession(this.session.createReplacedSessionContext());
+            }
+            catch (callbackError) {
+                throw new SessionReplacementCallbackError(callbackError);
+            }
+        }
+    }
+    snapshot() {
+        return {
+            session: this._session,
+            services: this._services,
+            diagnostics: [...this._diagnostics],
+            ...(this._modelFallbackMessage !== undefined ? { modelFallbackMessage: this._modelFallbackMessage } : {}),
+        };
     }
     apply(result) {
         this._session = result.session;
@@ -114,15 +219,136 @@ export class AgentSessionRuntime {
         this._diagnostics = result.diagnostics;
         this._modelFallbackMessage = result.modelFallbackMessage;
     }
-    async finishSessionReplacement(withSession) {
+    async activateReplacement(options) {
         if (this.rebindSession) {
             await this.rebindSession(this.session);
         }
-        if (withSession) {
-            await withSession(this.session.createReplacedSessionContext());
+        await options.beforeSessionResourcesStart?.(this.session);
+        for (const resource of this.sessionResources)
+            await resource.start(this.session);
+    }
+    async restorePreviousAfterRuntimeFailure(previous, failed, options, candidateActivated) {
+        const cleanupErrors = await this.shutdownRuntime(failed.session, options.reason, previous.session.sessionFile, {
+            stopResources: candidateActivated,
+            invalidateHost: candidateActivated,
+        });
+        // The old AgentSession was disposed at the commit boundary, but its SessionManager remains the
+        // durable reconstruction source. Restore the old snapshot temporarily so rollback-only artifact
+        // cleanup cannot mistake the failed candidate for the active session.
+        this.apply(previous);
+        try {
+            options.onDiscard?.();
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        let restored;
+        try {
+            restored = await this.createRuntime({
+                cwd: previous.services.cwd,
+                agentDir: previous.services.agentDir,
+                sessionManager: previous.session.sessionManager,
+                sessionStartEvent: {
+                    type: "session_start",
+                    reason: "resume",
+                    previousSessionFile: failed.session.sessionFile,
+                },
+            });
+            this.apply(restored);
+            if (this.rebindSession)
+                await this.rebindSession(this.session);
+            for (const resource of this.sessionResources)
+                await resource.start(this.session);
+        }
+        catch (recoveryError) {
+            if (restored) {
+                cleanupErrors.push(...(await this.shutdownRuntime(restored.session, "resume", failed.session.sessionFile, {
+                    stopResources: true,
+                    invalidateHost: true,
+                })));
+            }
+            this.apply(previous);
+            return cleanupErrors.length > 0
+                ? new AggregateError([...cleanupErrors, recoveryError], "Session rollback and cleanup failed.")
+                : recoveryError;
+        }
+        return cleanupErrors.length > 0
+            ? new AggregateError(cleanupErrors, "The previous session was restored, but failed replacement cleanup was incomplete.")
+            : undefined;
+    }
+    async shutdownRuntime(session, reason, targetSessionFile, options) {
+        const errors = [];
+        const progress = options.progress ??
+            {
+                shutdownEventEmitted: false,
+                stoppedResources: new Set(),
+                hostInvalidated: false,
+                sessionDisposed: false,
+            };
+        if (!progress.shutdownEventEmitted) {
+            try {
+                await emitSessionShutdownEvent(session.extensionRunner, {
+                    type: "session_shutdown",
+                    reason,
+                    targetSessionFile,
+                });
+                progress.shutdownEventEmitted = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (options.stopResources) {
+            for (const resource of this.sessionResources) {
+                if (progress.stoppedResources.has(resource))
+                    continue;
+                try {
+                    await resource.stop();
+                    progress.stoppedResources.add(resource);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+        }
+        if (options.invalidateHost && !progress.hostInvalidated) {
+            try {
+                this.beforeSessionInvalidate?.();
+                progress.hostInvalidated = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (!progress.sessionDisposed) {
+            try {
+                await session.disposeAndWait();
+                progress.sessionDisposed = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
         }
+        return errors;
+    }
+    runSessionReplacement(operation) {
+        if (this._disposeStarted) {
+            return Promise.reject(new Error("The session runtime has already been disposed."));
+        }
+        if (this._replacementInFlight) {
+            return Promise.reject(new Error("A session replacement is already in progress."));
+        }
+        const replacement = Promise.resolve().then(operation);
+        this._replacementInFlight = replacement;
+        return replacement.finally(() => {
+            if (this._replacementInFlight === replacement)
+                this._replacementInFlight = undefined;
+        });
     }
     async switchSession(sessionPath, options) {
+        return this.runSessionReplacement(() => this.switchSessionUnserialized(sessionPath, options));
+    }
+    async switchSessionUnserialized(sessionPath, options) {
         const beforeResult = await this.emitBeforeSwitch("resume", sessionPath);
         if (beforeResult.cancelled) {
             return beforeResult;
@@ -130,17 +356,23 @@ export class AgentSessionRuntime {
         const previousSessionFile = this.session.sessionFile;
         const sessionManager = SessionManager.open(sessionPath, this.services.agentDir, undefined, options?.cwdOverride);
         assertSessionCwdExists(sessionManager, this.cwd);
-        await this.teardownCurrent("resume", sessionManager.getSessionFile());
-        this.apply(await this.createRuntime({
-            cwd: sessionManager.getCwd(),
-            agentDir: this.services.agentDir,
-            sessionManager,
-            sessionStartEvent: { type: "session_start", reason: "resume", previousSessionFile },
-        }));
-        await this.finishSessionReplacement(options?.withSession);
+        const prepared = await this.prepareReplacement(sessionManager, {
+            type: "session_start",
+            reason: "resume",
+            previousSessionFile,
+        });
+        await this.commitReplacement(prepared, {
+            reason: "resume",
+            targetSessionFile: sessionManager.getSessionFile(),
+            beforeSessionResourcesStart: options?.beforeSessionResourcesStart,
+            withSession: options?.withSession,
+        });
         return { cancelled: false };
     }
     async newSession(options) {
+        return this.runSessionReplacement(() => this.newSessionUnserialized(options));
+    }
+    async newSessionUnserialized(options) {
         const beforeResult = await this.emitBeforeSwitch("new");
         if (beforeResult.cancelled) {
             return beforeResult;
@@ -151,21 +383,41 @@ export class AgentSessionRuntime {
         if (options?.parentSession) {
             sessionManager.newSession({ parentSession: options.parentSession });
         }
-        await this.teardownCurrent("new", sessionManager.getSessionFile());
-        this.apply(await this.createRuntime({
-            cwd: this.cwd,
-            agentDir: this.services.agentDir,
-            sessionManager,
-            sessionStartEvent: { type: "session_start", reason: "new", previousSessionFile },
-        }));
+        let prepared;
+        try {
+            prepared = await this.prepareReplacement(sessionManager, {
+                type: "session_start",
+                reason: "new",
+                previousSessionFile,
+            });
+        }
+        catch (error) {
+            this.removeCreatedSessionFile(sessionManager.getSessionFile());
+            throw error;
+        }
         if (options?.setup) {
-            await options.setup(this.session.sessionManager);
-            this.session.agent.state.messages = this.session.sessionManager.buildSessionContext().messages;
+            try {
+                await options.setup(prepared.session.sessionManager);
+                prepared.session.agent.state.messages = prepared.session.sessionManager.buildSessionContext().messages;
+            }
+            catch (error) {
+                await this.discardPrepared(prepared);
+                this.removeCreatedSessionFile(sessionManager.getSessionFile());
+                throw error;
+            }
         }
-        await this.finishSessionReplacement(options?.withSession);
+        await this.commitReplacement(prepared, {
+            reason: "new",
+            targetSessionFile: sessionManager.getSessionFile(),
+            withSession: options?.withSession,
+            onDiscard: () => this.removeCreatedSessionFile(sessionManager.getSessionFile()),
+        });
         return { cancelled: false };
     }
     async fork(entryId, options) {
+        return this.runSessionReplacement(() => this.forkUnserialized(entryId, options));
+    }
+    async forkUnserialized(entryId, options) {
         const position = options?.position ?? "before";
         const beforeResult = await this.emitBeforeFork(entryId, { position });
         if (beforeResult.cancelled) {
@@ -197,46 +449,70 @@ export class AgentSessionRuntime {
             if (!targetLeafId) {
                 const sessionManager = SessionManager.create(this.cwd, this.services.agentDir, sessionDir);
                 sessionManager.newSession({ parentSession: currentSessionFile });
-                await this.teardownCurrent("fork", sessionManager.getSessionFile());
-                this.apply(await this.createRuntime({
-                    cwd: this.cwd,
-                    agentDir: this.services.agentDir,
-                    sessionManager,
-                    sessionStartEvent: { type: "session_start", reason: "fork", previousSessionFile },
-                }));
-                await this.finishSessionReplacement(options?.withSession);
+                let prepared;
+                try {
+                    prepared = await this.prepareReplacement(sessionManager, {
+                        type: "session_start",
+                        reason: "fork",
+                        previousSessionFile,
+                    });
+                }
+                catch (error) {
+                    this.removeCreatedSessionFile(sessionManager.getSessionFile());
+                    throw error;
+                }
+                await this.commitReplacement(prepared, {
+                    reason: "fork",
+                    targetSessionFile: sessionManager.getSessionFile(),
+                    withSession: options?.withSession,
+                    onDiscard: () => this.removeCreatedSessionFile(sessionManager.getSessionFile()),
+                });
                 return { cancelled: false, selectedText };
             }
-            const sessionManager = SessionManager.open(currentSessionFile, this.services.agentDir, sessionDir);
-            const forkedSessionPath = sessionManager.createBranchedSession(targetLeafId);
+            const sourceSessionManager = SessionManager.open(currentSessionFile, this.services.agentDir, sessionDir);
+            const sessionManager = sourceSessionManager.createBranchedSessionManager(targetLeafId);
+            const forkedSessionPath = sessionManager.getSessionFile();
             if (!forkedSessionPath) {
                 throw new Error("Failed to create forked session");
             }
-            await this.teardownCurrent("fork", sessionManager.getSessionFile());
-            this.apply(await this.createRuntime({
-                cwd: sessionManager.getCwd(),
-                agentDir: this.services.agentDir,
-                sessionManager,
-                sessionStartEvent: { type: "session_start", reason: "fork", previousSessionFile },
-            }));
-            await this.finishSessionReplacement(options?.withSession);
+            let prepared;
+            try {
+                prepared = await this.prepareReplacement(sessionManager, {
+                    type: "session_start",
+                    reason: "fork",
+                    previousSessionFile,
+                });
+            }
+            catch (error) {
+                this.removeCreatedSessionFile(forkedSessionPath);
+                throw error;
+            }
+            await this.commitReplacement(prepared, {
+                reason: "fork",
+                targetSessionFile: forkedSessionPath,
+                withSession: options?.withSession,
+                onDiscard: () => this.removeCreatedSessionFile(forkedSessionPath),
+            });
             return { cancelled: false, selectedText };
         }
-        const sessionManager = this.session.sessionManager;
+        let sessionManager;
         if (!targetLeafId) {
+            sessionManager = SessionManager.inMemory(this.cwd);
             sessionManager.newSession({ parentSession: this.session.sessionFile });
         }
         else {
-            sessionManager.createBranchedSession(targetLeafId);
+            sessionManager = this.session.sessionManager.createBranchedSessionManager(targetLeafId);
         }
-        await this.teardownCurrent("fork", sessionManager.getSessionFile());
-        this.apply(await this.createRuntime({
-            cwd: this.cwd,
-            agentDir: this.services.agentDir,
-            sessionManager,
-            sessionStartEvent: { type: "session_start", reason: "fork", previousSessionFile },
-        }));
-        await this.finishSessionReplacement(options?.withSession);
+        const prepared = await this.prepareReplacement(sessionManager, {
+            type: "session_start",
+            reason: "fork",
+            previousSessionFile,
+        });
+        await this.commitReplacement(prepared, {
+            reason: "fork",
+            targetSessionFile: sessionManager.getSessionFile(),
+            withSession: options?.withSession,
+        });
         return { cancelled: false, selectedText };
     }
     /**
@@ -247,42 +523,84 @@ export class AgentSessionRuntime {
      * @throws {MissingSessionCwdError} When the imported session cwd cannot be resolved and no override is provided.
      */
     async importFromJsonl(inputPath, cwdOverride) {
+        return this.runSessionReplacement(() => this.importFromJsonlUnserialized(inputPath, cwdOverride));
+    }
+    async importFromJsonlUnserialized(inputPath, cwdOverride) {
         const resolvedPath = resolvePath(inputPath);
         if (!existsSync(resolvedPath)) {
             throw new SessionImportFileNotFoundError(resolvedPath);
         }
         const sessionDir = this.session.sessionManager.getSessionDir();
-        if (!existsSync(sessionDir)) {
-            mkdirSync(sessionDir, { recursive: true });
-        }
         const destinationPath = join(sessionDir, basename(resolvedPath));
         const beforeResult = await this.emitBeforeSwitch("resume", destinationPath);
         if (beforeResult.cancelled) {
             return beforeResult;
         }
         const previousSessionFile = this.session.sessionFile;
+        let copied = false;
         if (resolve(destinationPath) !== resolvedPath) {
-            copyFileSync(resolvedPath, destinationPath);
+            if (!existsSync(sessionDir))
+                mkdirSync(sessionDir, { recursive: true });
+            copyFileSync(resolvedPath, destinationPath, fsConstants.COPYFILE_EXCL);
+            copied = true;
         }
-        const sessionManager = SessionManager.open(destinationPath, this.services.agentDir, sessionDir, cwdOverride);
-        assertSessionCwdExists(sessionManager, this.cwd);
-        await this.teardownCurrent("resume", sessionManager.getSessionFile());
-        this.apply(await this.createRuntime({
-            cwd: sessionManager.getCwd(),
-            agentDir: this.services.agentDir,
-            sessionManager,
-            sessionStartEvent: { type: "session_start", reason: "resume", previousSessionFile },
-        }));
-        await this.finishSessionReplacement();
+        let sessionManager;
+        let prepared;
+        try {
+            sessionManager = SessionManager.open(destinationPath, this.services.agentDir, sessionDir, cwdOverride);
+            assertSessionCwdExists(sessionManager, this.cwd);
+            prepared = await this.prepareReplacement(sessionManager, {
+                type: "session_start",
+                reason: "resume",
+                previousSessionFile,
+            });
+        }
+        catch (error) {
+            if (copied)
+                this.removeCreatedSessionFile(destinationPath);
+            throw error;
+        }
+        await this.commitReplacement(prepared, {
+            reason: "resume",
+            targetSessionFile: sessionManager.getSessionFile(),
+            onDiscard: copied ? () => this.removeCreatedSessionFile(destinationPath) : undefined,
+        });
         return { cancelled: false };
     }
     async dispose() {
-        await emitSessionShutdownEvent(this.session.extensionRunner, {
-            type: "session_shutdown",
-            reason: "quit",
-        });
-        this.beforeSessionInvalidate?.();
-        this.session.dispose();
+        if (this._disposeInFlight)
+            return this._disposeInFlight;
+        if (this._disposed)
+            return;
+        this._disposeStarted = true;
+        const replacement = this._replacementInFlight;
+        const disposal = (async () => {
+            if (replacement) {
+                try {
+                    await replacement;
+                }
+                catch {
+                    // Replacement already reports its own error; dispose whichever runtime it left active.
+                }
+            }
+            const errors = await this.shutdownRuntime(this.session, "quit", undefined, {
+                stopResources: true,
+                invalidateHost: true,
+                progress: this.disposeProgress,
+            });
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw new AggregateError(errors, "Session runtime disposal failed.");
+            this._disposed = true;
+        })();
+        this._disposeInFlight = disposal;
+        try {
+            await disposal;
+        }
+        finally {
+            this._disposeInFlight = undefined;
+        }
     }
 }
 /**