pi-app-server 0.1.0

package/dist/session-manager.js

@@ -0,0 +1,1010 @@
+import {
+  createAgentSession
+} from "@mariozechner/pi-coding-agent";
+import {
+  getCommandDependsOn,
+  getCommandId,
+  getCommandIdempotencyKey,
+  getCommandIfSessionVersion,
+  getCommandType,
+  getSessionId
+} from "./types.js";
+import { routeSessionCommand } from "./command-router.js";
+import {
+  routeServerCommand,
+  executeLLMCommand,
+  executeBashCommand
+} from "./server-command-handlers.js";
+import { ExtensionUIManager } from "./extension-ui.js";
+import { createServerUIContext } from "./server-ui-context.js";
+import { validateCommand, formatValidationErrors } from "./validation.js";
+import { ResourceGovernor, DEFAULT_CONFIG } from "./resource-governor.js";
+import {
+  CommandReplayStore,
+  SYNTHETIC_ID_PREFIX
+} from "./command-replay-store.js";
+import { SessionVersionStore } from "./session-version-store.js";
+import { CommandExecutionEngine } from "./command-execution-engine.js";
+import { SessionLockManager } from "./session-lock-manager.js";
+import { SessionStore } from "./session-store.js";
+import { CircuitBreakerManager } from "./circuit-breaker.js";
+import { BashCircuitBreaker } from "./bash-circuit-breaker.js";
+const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60 * 1e3;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30 * 1e3;
+const SHORT_COMMAND_TIMEOUT_MS = 30 * 1e3;
+const DEPENDENCY_WAIT_TIMEOUT_MS = 30 * 1e3;
+const SANITIZED_NPM_ENV_KEYS = ["npm_config_prefix", "NPM_CONFIG_PREFIX"];
+class PiSessionManager {
+  sessions = /* @__PURE__ */ new Map();
+  sessionCreatedAt = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Set();
+  unsubscribers = /* @__PURE__ */ new Map();
+  governor;
+  /** Command replay and idempotency store. */
+  replayStore;
+  /** Session version store. */
+  versionStore;
+  /** Command execution engine. */
+  executionEngine;
+  /** Session ID lock manager for preventing create/delete races. */
+  lockManager;
+  /** Session metadata store for persistence across restarts (ADR-0007). */
+  sessionStore;
+  /** Circuit breaker for LLM providers (ADR-0010). */
+  circuitBreakers;
+  /** Circuit breaker for bash commands. */
+  bashCircuitBreaker;
+  // Shutdown state (single source of truth - server.ts delegates to this)
+  isShuttingDown = false;
+  inFlightCommands = /* @__PURE__ */ new Set();
+  // Periodic cleanup timers
+  sessionExpirationTimer = null;
+  defaultCommandTimeoutMs;
+  shortCommandTimeoutMs;
+  dependencyWaitTimeoutMs;
+  // Extension UI request tracking
+  extensionUI = new ExtensionUIManager(
+    (sessionId, event) => this.broadcastEvent(sessionId, event)
+  );
+  /** Optional memory metrics provider (set by server for ADR-0016) */
+  memoryMetricsProvider = null;
+  constructor(governor, options = {}) {
+    this.governor = governor ?? new ResourceGovernor(DEFAULT_CONFIG);
+    this.defaultCommandTimeoutMs = typeof options.defaultCommandTimeoutMs === "number" && options.defaultCommandTimeoutMs > 0 ? options.defaultCommandTimeoutMs : DEFAULT_COMMAND_TIMEOUT_MS;
+    this.shortCommandTimeoutMs = typeof options.shortCommandTimeoutMs === "number" && options.shortCommandTimeoutMs > 0 ? options.shortCommandTimeoutMs : SHORT_COMMAND_TIMEOUT_MS;
+    this.dependencyWaitTimeoutMs = typeof options.dependencyWaitTimeoutMs === "number" && options.dependencyWaitTimeoutMs > 0 ? options.dependencyWaitTimeoutMs : DEPENDENCY_WAIT_TIMEOUT_MS;
+    this.replayStore = new CommandReplayStore({
+      idempotencyTtlMs: options.idempotencyTtlMs
+    });
+    this.versionStore = new SessionVersionStore();
+    this.executionEngine = new CommandExecutionEngine(
+      this.replayStore,
+      this.versionStore,
+      this,
+      // SessionResolver - the NEXUS seam
+      {
+        defaultCommandTimeoutMs: this.defaultCommandTimeoutMs,
+        shortCommandTimeoutMs: this.shortCommandTimeoutMs,
+        dependencyWaitTimeoutMs: this.dependencyWaitTimeoutMs
+      }
+    );
+    this.lockManager = new SessionLockManager();
+    this.sessionStore = new SessionStore({
+      serverVersion: options.serverVersion
+    });
+    this.circuitBreakers = new CircuitBreakerManager(options.circuitBreakerConfig);
+    this.bashCircuitBreaker = new BashCircuitBreaker(options.bashCircuitBreakerConfig);
+  }
+  /**
+   * Get the resource governor for external checks (e.g., message size).
+   */
+  getGovernor() {
+    return this.governor;
+  }
+  /**
+   * Get the circuit breaker manager for external access (e.g., admin operations).
+   */
+  getCircuitBreakers() {
+    return this.circuitBreakers;
+  }
+  /**
+   * Get the bash circuit breaker for external access.
+   */
+  getBashCircuitBreaker() {
+    return this.bashCircuitBreaker;
+  }
+  // ==========================================================================
+  // SHUTDOWN MANAGEMENT
+  // ==========================================================================
+  /**
+   * Check if the server is shutting down.
+   */
+  isInShutdown() {
+    return this.isShuttingDown;
+  }
+  /**
+   * Set the memory metrics provider for ADR-0016 metrics system.
+   * Called by PiServer to provide access to MemorySink metrics.
+   */
+  setMemoryMetricsProvider(provider) {
+    this.memoryMetricsProvider = provider;
+  }
+  /**
+   * Initiate graceful shutdown.
+   * - Stops accepting new commands
+   * - Broadcasts shutdown notification to all clients
+   * - Returns promise that resolves when all in-flight commands complete or timeout
+   *
+   * Idempotent: calling multiple times returns the same result.
+   */
+  async initiateShutdown(timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    }
+    if (this.isShuttingDown) {
+      const remaining = this.inFlightCommands.size;
+      return { drained: 0, timedOut: remaining > 0 };
+    }
+    this.isShuttingDown = true;
+    const shutdownEvent = {
+      type: "server_shutdown",
+      data: { reason: "graceful_shutdown", timeoutMs }
+    };
+    this.broadcast(JSON.stringify(shutdownEvent));
+    const inFlightCount = this.inFlightCommands.size;
+    if (inFlightCount === 0) {
+      return { drained: 0, timedOut: false };
+    }
+    const snapshot = [...this.inFlightCommands];
+    const drainPromise = Promise.allSettled(snapshot);
+    const timeoutPromise = new Promise((resolve) => {
+      setTimeout(() => {
+        const stillPending = snapshot.filter((p) => this.inFlightCommands.has(p)).length;
+        const drained = inFlightCount - stillPending;
+        resolve({ drained, timedOut: true });
+      }, timeoutMs);
+    });
+    const drainResult = new Promise((resolve) => {
+      drainPromise.then(() => {
+        resolve({ drained: inFlightCount, timedOut: false });
+      });
+    });
+    return Promise.race([drainResult, timeoutPromise]);
+  }
+  /**
+   * Dispose all sessions. Call after shutdown drain completes.
+   */
+  disposeAllSessions() {
+    let disposed = 0;
+    let failed = 0;
+    const sessionIds = [...this.sessions.keys()];
+    for (const sessionId of sessionIds) {
+      try {
+        const session = this.sessions.get(sessionId);
+        this.sessions.delete(sessionId);
+        this.sessionCreatedAt.delete(sessionId);
+        const unsubscribe = this.unsubscribers.get(sessionId);
+        if (unsubscribe) {
+          this.unsubscribers.delete(sessionId);
+          try {
+            unsubscribe();
+          } catch {
+          }
+        }
+        if (session) {
+          try {
+            session.dispose();
+            disposed++;
+          } catch {
+            failed++;
+          }
+        }
+      } catch {
+        failed++;
+      }
+    }
+    this.versionStore.clear();
+    this.executionEngine.clear();
+    this.replayStore.clear();
+    this.lockManager.clear();
+    this.governor.cleanupStaleData(/* @__PURE__ */ new Set());
+    return { disposed, failed };
+  }
+  /**
+   * Get count of in-flight commands.
+   */
+  getInFlightCount() {
+    return this.inFlightCommands.size;
+  }
+  /**
+   * Register an in-flight command promise for shutdown draining.
+   */
+  registerInFlightCommand(promise) {
+    this.inFlightCommands.add(promise);
+    const cleanup = () => {
+      this.inFlightCommands.delete(promise);
+    };
+    promise.then(cleanup, cleanup);
+  }
+  broadcastCommandLifecycle(phase, data) {
+    const event = {
+      type: phase,
+      data
+    };
+    this.broadcast(JSON.stringify(event));
+  }
+  // ==========================================================================
+  // SESSION LIFECYCLE
+  // ==========================================================================
+  async createSession(sessionId, cwd) {
+    const sessionIdError = this.governor.validateSessionId(sessionId);
+    if (sessionIdError) {
+      throw new Error(sessionIdError);
+    }
+    if (cwd) {
+      const cwdError = this.governor.validateCwd(cwd);
+      if (cwdError) {
+        throw new Error(cwdError);
+      }
+    }
+    const lock = await this.lockManager.acquire(sessionId, "createSession");
+    try {
+      if (this.sessions.has(sessionId)) {
+        throw new Error(`Session ${sessionId} already exists`);
+      }
+      if (!this.governor.tryReserveSessionSlot()) {
+        throw new Error(
+          `Session limit reached (${this.governor.getConfig().maxSessions} sessions)`
+        );
+      }
+      try {
+        const { session } = await this.createAgentSessionWithSanitizedNpmEnv({
+          cwd: cwd ?? process.cwd()
+        });
+        await session.bindExtensions({
+          uiContext: createServerUIContext(
+            sessionId,
+            this.extensionUI,
+            (sid, event) => this.broadcastEvent(sid, event)
+          )
+        });
+        if (this.sessions.has(sessionId)) {
+          session.dispose();
+          throw new Error(`Session ${sessionId} already exists`);
+        }
+        this.sessions.set(sessionId, session);
+        this.sessionCreatedAt.set(sessionId, /* @__PURE__ */ new Date());
+        this.versionStore.initialize(sessionId);
+        this.governor.recordHeartbeat(sessionId);
+        const unsubscribe = session.subscribe((event) => {
+          this.broadcastEvent(sessionId, event);
+        });
+        this.unsubscribers.set(sessionId, unsubscribe);
+        const sessionInfo = this.getSessionInfo(sessionId);
+        if (!session.sessionFile) {
+          throw new Error("Session created without session file - cannot persist");
+        }
+        await this.sessionStore.save({
+          sessionId,
+          sessionFile: session.sessionFile,
+          cwd: cwd ?? process.cwd(),
+          createdAt: sessionInfo.createdAt,
+          modelId: session.model?.id
+        });
+        return sessionInfo;
+      } catch (error) {
+        this.governor.releaseSessionSlot();
+        throw error;
+      }
+    } finally {
+      lock.release();
+    }
+  }
+  async deleteSession(sessionId) {
+    const lock = await this.lockManager.acquire(sessionId, "deleteSession");
+    try {
+      const session = this.sessions.get(sessionId);
+      if (!session) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+      this.extensionUI.cancelSessionRequests(sessionId);
+      this.sessions.delete(sessionId);
+      this.sessionCreatedAt.delete(sessionId);
+      this.versionStore.delete(sessionId);
+      this.governor.unregisterSession(sessionId);
+      this.governor.cleanupStaleData(new Set(this.sessions.keys()));
+      const unsubscribe = this.unsubscribers.get(sessionId);
+      if (unsubscribe) {
+        this.unsubscribers.delete(sessionId);
+        try {
+          unsubscribe();
+        } catch (error) {
+          console.error(`[deleteSession] Failed to unsubscribe:`, error);
+        }
+      }
+      try {
+        session.dispose();
+      } catch (error) {
+        console.error(`[deleteSession] Failed to dispose session:`, error);
+      }
+      for (const subscriber of this.subscribers) {
+        subscriber.subscribedSessions.delete(sessionId);
+      }
+      await this.sessionStore.delete(sessionId);
+    } finally {
+      lock.release();
+    }
+  }
+  getSession(sessionId) {
+    return this.sessions.get(sessionId);
+  }
+  getSessionInfo(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return void 0;
+    const createdAt = this.sessionCreatedAt.get(sessionId);
+    if (!createdAt) {
+      console.error(`[getSessionInfo] Missing createdAt for session ${sessionId}`);
+      return void 0;
+    }
+    return {
+      sessionId,
+      sessionName: session.sessionName,
+      sessionFile: session.sessionFile,
+      model: session.model,
+      thinkingLevel: session.thinkingLevel,
+      isStreaming: session.isStreaming,
+      messageCount: session.messages.length,
+      createdAt: createdAt.toISOString()
+    };
+  }
+  listSessions() {
+    const infos = [];
+    for (const sessionId of this.sessions.keys()) {
+      const info = this.getSessionInfo(sessionId);
+      if (info) infos.push(info);
+    }
+    return infos;
+  }
+  // ==========================================================================
+  // SESSION PERSISTENCE (ADR-0007)
+  // ==========================================================================
+  /**
+   * List stored sessions that can be loaded.
+   * These are sessions that existed in previous server runs OR discovered on disk.
+   */
+  async listStoredSessions() {
+    return this.sessionStore.listAllSessions();
+  }
+  /**
+   * Load a session from a stored session file.
+   * Creates a new in-memory session that reads from the existing session file.
+   */
+  async loadSession(sessionId, sessionPath) {
+    const sessionIdError = this.governor.validateSessionId(sessionId);
+    if (sessionIdError) {
+      throw new Error(sessionIdError);
+    }
+    const lock = await this.lockManager.acquire(sessionId, "loadSession");
+    try {
+      if (this.sessions.has(sessionId)) {
+        throw new Error(`Session ${sessionId} already exists`);
+      }
+      if (!this.governor.tryReserveSessionSlot()) {
+        throw new Error(
+          `Session limit reached (${this.governor.getConfig().maxSessions} sessions)`
+        );
+      }
+      try {
+        const { session } = await this.createAgentSessionWithSanitizedNpmEnv({
+          cwd: process.cwd()
+        });
+        const switched = await session.switchSession(sessionPath);
+        if (!switched) {
+          session.dispose();
+          throw new Error(`Failed to load session from ${sessionPath}`);
+        }
+        await session.bindExtensions({
+          uiContext: createServerUIContext(
+            sessionId,
+            this.extensionUI,
+            (sid, event) => this.broadcastEvent(sid, event)
+          )
+        });
+        if (this.sessions.has(sessionId)) {
+          session.dispose();
+          throw new Error(`Session ${sessionId} already exists`);
+        }
+        this.sessions.set(sessionId, session);
+        this.sessionCreatedAt.set(sessionId, /* @__PURE__ */ new Date());
+        this.versionStore.initialize(sessionId);
+        this.governor.recordHeartbeat(sessionId);
+        const unsubscribe = session.subscribe((event) => {
+          this.broadcastEvent(sessionId, event);
+        });
+        this.unsubscribers.set(sessionId, unsubscribe);
+        const sessionInfo = this.getSessionInfo(sessionId);
+        if (!session.sessionFile) {
+          throw new Error("Session loaded without session file - cannot persist metadata");
+        }
+        await this.sessionStore.save({
+          sessionId,
+          sessionFile: session.sessionFile,
+          cwd: process.cwd(),
+          createdAt: sessionInfo.createdAt,
+          modelId: session.model?.id
+        });
+        return sessionInfo;
+      } catch (error) {
+        this.governor.releaseSessionSlot();
+        throw error;
+      }
+    } finally {
+      lock.release();
+    }
+  }
+  /**
+   * Get the session store for direct access (e.g., cleanup).
+   */
+  getSessionStore() {
+    return this.sessionStore;
+  }
+  /**
+   * Start periodic cleanup of orphaned session metadata and expired sessions.
+   * @param intervalMs Cleanup interval in milliseconds (default: 1 hour)
+   */
+  startSessionCleanup(intervalMs) {
+    this.sessionStore.startPeriodicCleanup(intervalMs);
+    this.startSessionExpirationCheck(intervalMs);
+  }
+  /**
+   * Stop periodic cleanup.
+   */
+  stopSessionCleanup() {
+    this.sessionStore.stopPeriodicCleanup();
+    this.stopSessionExpirationCheck();
+  }
+  /**
+   * Run a one-time cleanup of orphaned session metadata and expired sessions.
+   */
+  async cleanupSessions() {
+    await this.cleanupExpiredSessions();
+    return this.sessionStore.cleanup();
+  }
+  /**
+   * Start periodic check for expired sessions (maxSessionLifetimeMs).
+   */
+  startSessionExpirationCheck(intervalMs = 36e5) {
+    if (this.sessionExpirationTimer) {
+      return;
+    }
+    this.sessionExpirationTimer = setInterval(() => {
+      this.cleanupExpiredSessions().catch((error) => {
+        console.error("[SessionManager] Session expiration cleanup failed:", error);
+      });
+    }, intervalMs);
+    if (this.sessionExpirationTimer.unref) {
+      this.sessionExpirationTimer.unref();
+    }
+  }
+  /**
+   * Stop periodic session expiration check.
+   */
+  stopSessionExpirationCheck() {
+    if (this.sessionExpirationTimer) {
+      clearInterval(this.sessionExpirationTimer);
+      this.sessionExpirationTimer = null;
+    }
+  }
+  /**
+   * Clean up sessions that have exceeded maxSessionLifetimeMs.
+   * Also cleans up stale circuit breakers for unused providers.
+   */
+  async cleanupExpiredSessions() {
+    const expiredIds = this.governor.getExpiredSessions();
+    for (const sessionId of expiredIds) {
+      try {
+        console.error(`[SessionManager] Deleting expired session: ${sessionId}`);
+        await this.deleteSession(sessionId);
+      } catch (error) {
+        console.error(`[SessionManager] Failed to delete expired session ${sessionId}:`, error);
+      }
+    }
+    const staleBreakersRemoved = this.circuitBreakers.cleanupStaleBreakers();
+    if (staleBreakersRemoved > 0) {
+      console.error(`[SessionManager] Cleaned up ${staleBreakersRemoved} stale circuit breakers`);
+    }
+    const staleBashBreakersRemoved = this.bashCircuitBreaker.cleanupStale();
+    if (staleBashBreakersRemoved > 0) {
+      console.error(
+        `[SessionManager] Cleaned up ${staleBashBreakersRemoved} stale bash circuit breakers`
+      );
+    }
+  }
+  // ==========================================================================
+  // SUBSCRIBER MANAGEMENT
+  // ==========================================================================
+  addSubscriber(subscriber) {
+    this.subscribers.add(subscriber);
+  }
+  removeSubscriber(subscriber) {
+    this.subscribers.delete(subscriber);
+  }
+  subscribeToSession(subscriber, sessionId) {
+    if (!this.sessions.has(sessionId)) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+    subscriber.subscribedSessions.add(sessionId);
+  }
+  unsubscribeFromSession(subscriber, sessionId) {
+    subscriber.subscribedSessions.delete(sessionId);
+  }
+  // ==========================================================================
+  // EVENT BROADCAST
+  // ==========================================================================
+  broadcastEvent(sessionId, event) {
+    const rpcEvent = {
+      type: "event",
+      sessionId,
+      event
+    };
+    let data;
+    try {
+      data = JSON.stringify(rpcEvent);
+    } catch (error) {
+      console.error(`[broadcastEvent] JSON serialization failed:`, error);
+      return;
+    }
+    const snapshot = [...this.subscribers];
+    for (const subscriber of snapshot) {
+      if (subscriber.subscribedSessions.has(sessionId)) {
+        try {
+          subscriber.send(data);
+        } catch (error) {
+          console.error(`[broadcastEvent] Failed to send to subscriber:`, error);
+        }
+      }
+    }
+  }
+  broadcast(data) {
+    const snapshot = [...this.subscribers];
+    for (const subscriber of snapshot) {
+      try {
+        subscriber.send(data);
+      } catch (error) {
+        console.error(`[broadcast] Failed to send to subscriber:`, error);
+      }
+    }
+  }
+  // ==========================================================================
+  // COMMAND EXECUTION CONTEXT
+  // ==========================================================================
+  /**
+   * Create the command execution context for server command handlers.
+   * This is the NEXUS seam - provides everything handlers need without
+   * direct coupling to SessionManager internals.
+   */
+  createCommandContext() {
+    return {
+      getSession: (sessionId) => this.sessions.get(sessionId),
+      getSessionInfo: (sessionId) => this.getSessionInfo(sessionId),
+      listSessions: () => this.listSessions(),
+      createSession: (sessionId, cwd) => this.createSession(sessionId, cwd),
+      deleteSession: (sessionId) => this.deleteSession(sessionId),
+      loadSession: (sessionId, sessionPath) => this.loadSession(sessionId, sessionPath),
+      listStoredSessions: () => this.listStoredSessions(),
+      getMetrics: () => this.buildMetricsResponse(),
+      getMemoryMetrics: () => this.memoryMetricsProvider?.(),
+      getHealth: () => this.buildHealthResponse(),
+      handleUIResponse: (command) => this.extensionUI.handleUIResponse({
+        id: command.id,
+        sessionId: command.sessionId,
+        type: "extension_ui_response",
+        requestId: command.requestId,
+        response: command.response
+      }),
+      routeSessionCommand: (session, command, getSessionInfo) => routeSessionCommand(session, command, getSessionInfo),
+      generateSessionId: () => this.generateSessionId(),
+      recordHeartbeat: (sessionId) => this.governor.recordHeartbeat(sessionId),
+      getCircuitBreakers: () => ({
+        hasOpenCircuit: () => this.circuitBreakers.hasOpenCircuit(),
+        getBreaker: (provider) => {
+          const breaker = this.circuitBreakers.getBreaker(provider);
+          return {
+            canExecute: () => breaker.canExecute(),
+            recordSuccess: (elapsedMs) => breaker.recordSuccess(elapsedMs),
+            recordFailure: (type) => breaker.recordFailure(type)
+          };
+        }
+      }),
+      getBashCircuitBreaker: () => ({
+        canExecute: (sessionId) => this.bashCircuitBreaker.canExecute(sessionId),
+        recordSuccess: (sessionId) => this.bashCircuitBreaker.recordSuccess(sessionId),
+        recordTimeout: (sessionId) => this.bashCircuitBreaker.recordTimeout(sessionId),
+        recordSpawnError: (sessionId) => this.bashCircuitBreaker.recordSpawnError(sessionId),
+        hasOpenCircuit: () => this.bashCircuitBreaker.hasOpenCircuit(),
+        getMetrics: () => this.bashCircuitBreaker.getMetrics()
+      }),
+      getDefaultCommandTimeoutMs: () => this.defaultCommandTimeoutMs
+    };
+  }
+  /**
+   * Build the metrics response (extracted for handler use).
+   */
+  buildMetricsResponse() {
+    const governorMetrics = this.governor.getMetrics();
+    const replayStats = this.replayStore.getStats();
+    const versionStats = this.versionStore.getStats();
+    const executionStats = this.executionEngine.getStats();
+    const lockStats = this.lockManager.getStats();
+    const extensionUIStats = this.extensionUI.getStats();
+    const circuitBreakerMetrics = this.circuitBreakers.getAllMetrics();
+    const bashCircuitBreakerMetrics = this.bashCircuitBreaker.getMetrics();
+    const sessionStoreStats = {
+      metadataResetCount: this.sessionStore.getMetadataResetCount()
+    };
+    return {
+      type: "response",
+      command: "get_metrics",
+      success: true,
+      data: {
+        ...governorMetrics,
+        stores: {
+          replay: replayStats,
+          version: versionStats,
+          execution: executionStats,
+          lock: lockStats,
+          extensionUI: extensionUIStats,
+          sessionStore: sessionStoreStats
+        },
+        circuitBreakers: circuitBreakerMetrics,
+        bashCircuitBreaker: bashCircuitBreakerMetrics
+      }
+    };
+  }
+  /**
+   * Build the health check response (extracted for handler use).
+   */
+  buildHealthResponse() {
+    const health = this.governor.isHealthy();
+    const hasOpenCircuit = this.circuitBreakers.hasOpenCircuit();
+    const hasOpenBashCircuit = this.bashCircuitBreaker.hasOpenCircuit();
+    const issues = [...health.issues];
+    if (hasOpenCircuit) {
+      issues.push("One or more LLM provider circuits are open");
+    }
+    if (hasOpenBashCircuit) {
+      issues.push("Bash command circuit breaker is open");
+    }
+    return {
+      type: "response",
+      command: "health_check",
+      success: true,
+      data: {
+        ...health,
+        hasOpenCircuit,
+        hasOpenBashCircuit,
+        issues
+      }
+    };
+  }
+  // ==========================================================================
+  // COMMAND EXECUTION
+  // ==========================================================================
+  async executeCommand(command) {
+    const id = getCommandId(command);
+    const commandType = getCommandType(command);
+    const sessionId = getSessionId(command);
+    const commandId = this.replayStore.getOrCreateCommandId(command);
+    const dependsOn = getCommandDependsOn(command) ?? [];
+    const ifSessionVersion = getCommandIfSessionVersion(command);
+    const idempotencyKey = getCommandIdempotencyKey(command);
+    const laneKey = this.executionEngine.getLaneKey(command);
+    const fingerprint = this.replayStore.getCommandFingerprint(command);
+    if (this.isShuttingDown) {
+      return {
+        id,
+        type: "response",
+        command: commandType ?? "unknown",
+        success: false,
+        error: "Server is shutting down"
+      };
+    }
+    const validationErrors = validateCommand(command);
+    if (validationErrors.length > 0) {
+      return {
+        id,
+        type: "response",
+        command: commandType ?? "unknown",
+        success: false,
+        error: `Validation failed: ${formatValidationErrors(validationErrors)}`
+      };
+    }
+    this.replayStore.cleanupIdempotencyCache();
+    this.broadcastCommandLifecycle("command_accepted", {
+      commandId,
+      commandType,
+      sessionId,
+      dependsOn,
+      ifSessionVersion,
+      idempotencyKey
+    });
+    const finalizeResponse = (response2) => {
+      this.broadcastCommandLifecycle("command_finished", {
+        commandId,
+        commandType,
+        sessionId,
+        dependsOn,
+        ifSessionVersion,
+        idempotencyKey,
+        success: response2.success,
+        error: response2.success ? void 0 : response2.error,
+        sessionVersion: response2.sessionVersion,
+        replayed: response2.replayed
+      });
+      return response2;
+    };
+    const replayCheck = this.replayStore.checkReplay(command, fingerprint);
+    if (replayCheck.kind === "conflict") {
+      return finalizeResponse(replayCheck.response);
+    }
+    if (replayCheck.kind === "replay_cached") {
+      return finalizeResponse(replayCheck.response);
+    }
+    if (replayCheck.kind === "replay_inflight") {
+      const replayed = await replayCheck.promise;
+      return finalizeResponse(replayed);
+    }
+    const rateLimitKey = sessionId ?? "_server_";
+    const rateLimitResult = this.governor.canExecuteCommand(rateLimitKey);
+    if (!rateLimitResult.allowed) {
+      return finalizeResponse({
+        id,
+        type: "response",
+        command: commandType,
+        success: false,
+        error: rateLimitResult.reason
+      });
+    }
+    if (commandType === "extension_ui_response" && sessionId) {
+      const extRateLimitResult = this.governor.canExecuteExtensionUIResponse(sessionId);
+      if (!extRateLimitResult.allowed) {
+        return finalizeResponse({
+          id,
+          type: "response",
+          command: commandType,
+          success: false,
+          error: extRateLimitResult.reason
+        });
+      }
+    }
+    const isExplicitId = typeof id === "string" && !id.startsWith(SYNTHETIC_ID_PREFIX);
+    if (isExplicitId && !this.replayStore.canRegisterInFlight(id)) {
+      return finalizeResponse({
+        id,
+        type: "response",
+        command: commandType,
+        success: false,
+        error: "Server busy - too many concurrent commands. Please retry."
+      });
+    }
+    const commandExecution = this.executionEngine.runOnLane(
+      laneKey,
+      async () => {
+        this.broadcastCommandLifecycle("command_started", {
+          commandId,
+          commandType,
+          sessionId,
+          dependsOn,
+          ifSessionVersion,
+          idempotencyKey
+        });
+        if (dependsOn.includes(commandId)) {
+          return {
+            id,
+            type: "response",
+            command: commandType,
+            success: false,
+            error: `Command '${commandId}' cannot depend on itself`
+          };
+        }
+        if (dependsOn.length > 0) {
+          const dependencyResult = await this.executionEngine.awaitDependencies(dependsOn, laneKey);
+          if (!dependencyResult.ok) {
+            return {
+              id,
+              type: "response",
+              command: commandType,
+              success: false,
+              error: dependencyResult.error
+            };
+          }
+        }
+        if (sessionId !== void 0 && ifSessionVersion !== void 0) {
+          const versionError = this.executionEngine.checkSessionVersion(
+            sessionId,
+            ifSessionVersion,
+            commandType
+          );
+          if (versionError) {
+            return {
+              id,
+              type: "response",
+              command: commandType,
+              success: false,
+              error: versionError.error
+            };
+          }
+        }
+        const rawResponse = await this.executeCommandInternal(command, id, commandType);
+        return this.versionStore.applyVersion(command, rawResponse);
+      }
+    );
+    let inFlightRecord;
+    if (id) {
+      inFlightRecord = {
+        commandType,
+        laneKey,
+        fingerprint,
+        promise: commandExecution
+      };
+      const registered = this.replayStore.registerInFlight(id, inFlightRecord);
+      if (!registered) {
+        return finalizeResponse({
+          id,
+          type: "response",
+          command: commandType,
+          success: false,
+          error: "Server busy - too many concurrent commands. Please retry."
+        });
+      }
+    }
+    this.registerInFlightCommand(commandExecution);
+    let response;
+    try {
+      response = await this.executionEngine.executeWithTimeout(
+        commandType,
+        commandExecution,
+        command
+      );
+    } catch (error) {
+      response = {
+        id,
+        type: "response",
+        command: commandType,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        timedOut: true
+        // Mark as timeout for debugging
+      };
+    }
+    if (isExplicitId) {
+      try {
+        this.replayStore.storeCommandOutcome({
+          commandId: id,
+          commandType,
+          laneKey,
+          fingerprint,
+          success: response.success,
+          error: response.success ? void 0 : response.error,
+          response,
+          sessionVersion: response.sessionVersion,
+          finishedAt: Date.now()
+        });
+      } catch (outcomeError) {
+        console.error(`[executeCommand] Failed to store command outcome for ${id}:`, outcomeError);
+      }
+      if (this.replayStore.getInFlight(id) === inFlightRecord) {
+        this.replayStore.unregisterInFlight(id, inFlightRecord);
+      }
+    } else if (id && this.replayStore.getInFlight(id) === inFlightRecord) {
+      this.replayStore.unregisterInFlight(id, inFlightRecord);
+    }
+    if (idempotencyKey) {
+      this.replayStore.cacheIdempotencyResult({
+        command,
+        idempotencyKey,
+        commandType,
+        fingerprint,
+        response
+      });
+    }
+    return finalizeResponse(response);
+  }
+  /**
+   * Internal command execution (called after tracking and rate limiting).
+   * Routes to server command handlers or session command handlers.
+   */
+  async executeCommandInternal(command, id, commandType) {
+    const failResponse = (error, responseCommand = commandType) => {
+      return {
+        id,
+        type: "response",
+        command: responseCommand,
+        success: false,
+        error
+      };
+    };
+    try {
+      const context = this.createCommandContext();
+      const serverResponse = routeServerCommand(command, context);
+      if (serverResponse !== void 0) {
+        const resolved = await Promise.resolve(serverResponse);
+        return { ...resolved, id };
+      }
+      const cmdSessionId = getSessionId(command);
+      const session = this.sessions.get(cmdSessionId);
+      if (!session) {
+        return failResponse(`Session ${cmdSessionId} not found`);
+      }
+      this.governor.recordHeartbeat(cmdSessionId);
+      const llmResponse = await executeLLMCommand(command, session, context);
+      if (llmResponse !== void 0) {
+        if (!llmResponse.success) {
+          return { ...llmResponse, id };
+        }
+        return llmResponse;
+      }
+      const bashResponse = await executeBashCommand(command, session, context);
+      if (bashResponse !== void 0) {
+        if (!bashResponse.success) {
+          return { ...bashResponse, id };
+        }
+        return bashResponse;
+      }
+      const routed = routeSessionCommand(session, command, (sid) => this.getSessionInfo(sid));
+      if (routed === void 0) {
+        return failResponse(`Unknown command type: ${commandType}`);
+      }
+      const response = await Promise.resolve(routed);
+      if (!response.success) {
+        return failResponse(response.error ?? "Unknown error", response.command);
+      }
+      return response;
+    } catch (error) {
+      return failResponse(error instanceof Error ? error.message : String(error));
+    }
+  }
+  // ==========================================================================
+  // UTILITIES
+  // ==========================================================================
+  /**
+   * Create an AgentSession while sanitizing npm prefix env leakage from npm scripts.
+   *
+   * npm sets npm_config_prefix for child processes. If inherited here,
+   * pi-coding-agent's global package installation can be redirected into the
+   * current project (e.g. ./lib/node_modules), causing flaky session creation.
+   */
+  async createAgentSessionWithSanitizedNpmEnv(options) {
+    const snapshots = SANITIZED_NPM_ENV_KEYS.map((key) => ({
+      key,
+      had: Object.hasOwn(process.env, key),
+      value: process.env[key]
+    }));
+    for (const snapshot of snapshots) {
+      if (snapshot.had) {
+        delete process.env[snapshot.key];
+      }
+    }
+    try {
+      return await createAgentSession(options);
+    } finally {
+      for (const snapshot of snapshots) {
+        if (!snapshot.had) continue;
+        if (snapshot.value === void 0) {
+          delete process.env[snapshot.key];
+        } else {
+          process.env[snapshot.key] = snapshot.value;
+        }
+      }
+    }
+  }
+  generateSessionId() {
+    const timestamp = Date.now().toString(36);
+    const random = crypto.randomUUID().split("-")[0];
+    return `session-${timestamp}-${random}`;
+  }
+}
+export {
+  PiSessionManager
+};
+//# sourceMappingURL=session-manager.js.map