@ash-cloud/ash-ai 0.1.17 → 0.1.19

package/dist/index.cjs

@@ -108,7 +108,7 @@ var init_normalized = __esm({
   "src/types/normalized.ts"() {
   }
 });
-exports.SessionStatus = void 0; exports.AgentStatus = void 0; exports.MessageRole = void 0; exports.messageContentSchema = void 0; exports.messageSchema = void 0; exports.sessionSchema = void 0; exports.attachmentSchema = void 0; exports.DEFAULT_SANDBOX_PROVIDER_CONFIG = void 0; exports.StreamEventType = void 0; exports.QueueItemStatus = void 0; exports.EventCategory = void 0;
+exports.SessionStatus = void 0; exports.AgentStatus = void 0; exports.MessageRole = void 0; exports.messageContentSchema = void 0; exports.messageSchema = void 0; exports.sessionSchema = void 0; exports.attachmentSchema = void 0; exports.DEFAULT_SANDBOX_PROVIDER_CONFIG = void 0; exports.StreamEventType = void 0; exports.QueueItemStatus = void 0; exports.EventCategory = void 0; exports.EventSource = void 0;
 var init_types = __esm({
   "src/types/index.ts"() {
     init_normalized();
@@ -233,6 +233,14 @@ var init_types = __esm({
       WEBHOOK: "webhook"
       // webhook_delivery, webhook_failure (outbound webhook events)
     };
+    exports.EventSource = {
+      AGENT: "agent",
+      // Directly from the agent SDK
+      SYSTEM: "system",
+      // Generated by execution layer (lifecycle, user input)
+      DERIVED: "derived"
+      // Transformed/aggregated from agent events
+    };
   }
 });
 
@@ -2595,6 +2603,11 @@ var init_memory = __esm({
         if (options.status) {
           sessions2 = sessions2.filter((s) => s.status === options.status);
         }
+        if (options.resourceId) {
+          sessions2 = sessions2.filter(
+            (s) => s.metadata && s.metadata["resourceId"] === options.resourceId
+          );
+        }
         const orderBy = options.orderBy ?? "createdAt";
         const order = options.order ?? "desc";
         sessions2.sort((a, b) => {
@@ -4526,13 +4539,13 @@ function getSandboxPool() {
   return globalPool;
 }
 function isPoolEnabled() {
-  if (!process.env.VERCEL) {
-    return false;
-  }
   if (process.env.SANDBOX_POOL_ENABLED === "false") {
     return false;
   }
-  return true;
+  if (process.env.SANDBOX_POOL_ENABLED === "true") {
+    return true;
+  }
+  return !!process.env.VERCEL;
 }
 async function ensureSandboxPoolInitialized() {
   if (globalPool && globalPool.isRunning()) {
@@ -4617,7 +4630,7 @@ node -e "require('@anthropic-ai/claude-agent-sdk'); console.log('[warmup] SDK ve
 
 echo "[warmup] Warmup complete!"
 `;
-    exports.SandboxPool = class {
+    exports.SandboxPool = class _SandboxPool {
       config;
       pool = /* @__PURE__ */ new Map();
       warmingInProgress = /* @__PURE__ */ new Set();
@@ -4626,6 +4639,16 @@ echo "[warmup] Warmup complete!"
       lastMaintenanceAt = null;
       metricsCallback;
       startPromise = null;
+      /** Registered warmup specs by tag (e.g. agentId -> spec) */
+      warmupSpecs = /* @__PURE__ */ new Map();
+      /** Consecutive warmup failure count (reset on success) */
+      consecutiveFailures = 0;
+      /** Timestamp of last warmup attempt — used for backoff */
+      lastWarmupAttemptAt = 0;
+      /** Max consecutive failures before stopping attempts entirely until manual restart */
+      static MAX_CONSECUTIVE_FAILURES = 10;
+      /** Base backoff delay in ms (doubles each failure: 30s, 60s, 120s, 240s…) */
+      static BACKOFF_BASE_MS = 3e4;
       constructor(config = {}) {
         this.config = {
           minPoolSize: config.minPoolSize ?? parseInt(process.env.SANDBOX_POOL_MIN_SIZE ?? "2"),
@@ -4674,11 +4697,13 @@ echo "[warmup] Warmup complete!"
         if (this.maintenanceIntervalId.unref) {
           this.maintenanceIntervalId.unref();
         }
+        const initialSpecs = this.selectSpecsForReplenishment(this.config.minPoolSize);
         console.log(`[POOL] Spawning ${this.config.minPoolSize} initial sandbox(es)...`);
         const warmupPromises = [];
         for (let i = 0; i < this.config.minPoolSize; i++) {
+          const spec = initialSpecs[i];
           warmupPromises.push(
-            this.warmSandbox().then((sandbox) => {
+            this.warmSandbox(spec).then((sandbox) => {
               this.pool.set(sandbox.sandboxId, sandbox);
               console.log(`[POOL] Initial sandbox ready: ${sandbox.sandboxId}`);
             }).catch((error) => {
@@ -4722,9 +4747,11 @@ echo "[warmup] Warmup complete!"
       }
       /**
        * Acquire a pre-warmed sandbox for a session.
+       * If preferTag is provided, tries to find a sandbox warmed for that tag first.
+       * Falls back to a generic (untagged) sandbox if no tag match is found.
        * If no eligible sandbox is available, creates one on-demand.
        */
-      async acquire(sessionId) {
+      async acquire(sessionId, preferTag) {
         if (!this.running) {
           throw new Error("Sandbox pool is not running");
         }
@@ -4734,26 +4761,34 @@ echo "[warmup] Warmup complete!"
             return pooled;
           }
         }
-        const available = this.getAvailableSandbox();
+        const available = this.getAvailableSandbox(preferTag);
         if (available) {
           available.assignedTo = sessionId;
-          console.log(`[POOL] Acquired sandbox ${available.sandboxId} for session ${sessionId}`);
+          const tagInfo = available.warmupTag ? ` [tag=${available.warmupTag}, agentSetupComplete=${available.agentSetupComplete}]` : " [generic]";
+          console.log(`[POOL] Acquired sandbox ${available.sandboxId} for session ${sessionId}${tagInfo}`);
           this.emitMetric("sandbox_assigned", {
             sandboxId: available.sandboxId,
             sessionId,
-            poolAvailable: this.getAvailableCount()
+            poolAvailable: this.getAvailableCount(),
+            warmupTag: available.warmupTag,
+            agentSetupComplete: available.agentSetupComplete,
+            preferTag
           });
           this.triggerReplenishment();
           return available;
         }
-        console.log(`[POOL] No available sandbox, creating on-demand for session ${sessionId}...`);
-        const sandbox = await this.warmSandbox();
+        const spec = preferTag ? this.warmupSpecs.get(preferTag) : void 0;
+        console.log(`[POOL] No available sandbox, creating on-demand for session ${sessionId}${spec ? ` [spec=${preferTag}]` : ""}...`);
+        const sandbox = await this.warmSandbox(spec);
         sandbox.assignedTo = sessionId;
         this.pool.set(sandbox.sandboxId, sandbox);
         this.emitMetric("sandbox_assigned", {
           sandboxId: sandbox.sandboxId,
           sessionId,
-          onDemand: true
+          onDemand: true,
+          warmupTag: sandbox.warmupTag,
+          agentSetupComplete: sandbox.agentSetupComplete,
+          preferTag
         });
         return sandbox;
       }
@@ -4784,11 +4819,14 @@ echo "[warmup] Warmup complete!"
         let available = 0;
         let assigned = 0;
         let ineligible = 0;
+        const availableByTag = {};
         for (const pooled of this.pool.values()) {
           if (pooled.assignedTo) {
             assigned++;
           } else if (pooled.eligible) {
             available++;
+            const tagKey = pooled.warmupTag || "generic";
+            availableByTag[tagKey] = (availableByTag[tagKey] || 0) + 1;
           } else {
             ineligible++;
           }
@@ -4801,6 +4839,10 @@ echo "[warmup] Warmup complete!"
           warming: this.warmingInProgress.size,
           running: this.running,
           lastMaintenanceAt: this.lastMaintenanceAt,
+          consecutiveFailures: this.consecutiveFailures,
+          warmupSuspended: this.consecutiveFailures >= _SandboxPool.MAX_CONSECUTIVE_FAILURES,
+          registeredSpecs: this.warmupSpecs.size,
+          availableByTag,
           config: {
             minPoolSize: this.config.minPoolSize,
             maxPoolSize: this.config.maxPoolSize,
@@ -4815,17 +4857,56 @@ echo "[warmup] Warmup complete!"
       onMetrics(callback) {
         this.metricsCallback = callback;
       }
+      /**
+       * Register a warmup spec so the pool can pre-warm agent-specific sandboxes.
+       * If a spec with the same tag already exists, it is replaced.
+       * Triggers replenishment to warm a sandbox for this spec.
+       */
+      registerWarmupSpec(spec) {
+        const isNew = !this.warmupSpecs.has(spec.tag);
+        this.warmupSpecs.set(spec.tag, spec);
+        console.log(`[POOL] ${isNew ? "Registered" : "Updated"} warmup spec: ${spec.tag} (priority=${spec.priority})`);
+        this.emitMetric("spec_registered", {
+          tag: spec.tag,
+          priority: spec.priority,
+          isNew,
+          totalSpecs: this.warmupSpecs.size
+        });
+        if (this.running) {
+          this.triggerReplenishment();
+        }
+      }
+      /**
+       * Remove a warmup spec. Existing tagged sandboxes remain but won't be replaced.
+       */
+      unregisterWarmupSpec(tag) {
+        this.warmupSpecs.delete(tag);
+        console.log(`[POOL] Unregistered warmup spec: ${tag}`);
+      }
+      /**
+       * Update the priority of a warmup spec (e.g. for MRU tracking).
+       * Higher priority = more likely to get a warm sandbox during replenishment.
+       */
+      updateSpecPriority(tag, priority) {
+        const spec = this.warmupSpecs.get(tag);
+        if (spec) {
+          spec.priority = priority;
+        }
+      }
       // ===========================================================================
       // PRIVATE METHODS
       // ===========================================================================
       /**
-       * Create and warm a new sandbox
+       * Create and warm a new sandbox.
+       * If a spec is provided, runs the spec's setup function after SDK installation.
+       * On spec setup failure, the sandbox remains generic (graceful degradation).
        */
-      async warmSandbox() {
+      async warmSandbox(spec) {
         const warmupId = `warming-${Date.now()}-${Math.random().toString(36).slice(2)}`;
         this.warmingInProgress.add(warmupId);
         this.emitMetric("warmup_started", { warmupId });
         const startTime = Date.now();
+        this.lastWarmupAttemptAt = startTime;
         const useTarball = !!this.config.baseTarballUrl;
         try {
           const { Sandbox } = await import('@vercel/sandbox');
@@ -4914,6 +4995,37 @@ echo "[warmup] Warmup complete!"
               throw new Error(`Warmup failed: ${stderr}`);
             }
           }
+          let warmupTag;
+          let agentSetupComplete = false;
+          if (spec) {
+            console.log(`[POOL] Running spec setup for tag=${spec.tag} on sandbox ${sandbox.sandboxId}...`);
+            this.emitMetric("spec_setup_started", { tag: spec.tag, sandboxId: sandbox.sandboxId });
+            const specStartTime = Date.now();
+            try {
+              await spec.setup(sandbox);
+              warmupTag = spec.tag;
+              agentSetupComplete = true;
+              const specDuration = Date.now() - specStartTime;
+              console.log(`[POOL] Spec setup completed for tag=${spec.tag} on sandbox ${sandbox.sandboxId} (${specDuration}ms)`);
+              this.emitMetric("spec_setup_completed", {
+                tag: spec.tag,
+                sandboxId: sandbox.sandboxId,
+                durationMs: specDuration
+              });
+            } catch (specError) {
+              const specDuration = Date.now() - specStartTime;
+              const specErrorMessage = specError instanceof Error ? specError.message : "Unknown";
+              console.warn(
+                `[POOL] Spec setup failed for tag=${spec.tag} on sandbox ${sandbox.sandboxId} (${specDuration}ms): ${specErrorMessage}. Sandbox stays generic.`
+              );
+              this.emitMetric("spec_setup_failed", {
+                tag: spec.tag,
+                sandboxId: sandbox.sandboxId,
+                durationMs: specDuration,
+                error: specErrorMessage
+              });
+            }
+          }
           const warmupTime = Date.now() - startTime;
           const now = Date.now();
           const pooled = {
@@ -4923,22 +5035,38 @@ echo "[warmup] Warmup complete!"
             expiresAt: now + this.config.sandboxTimeout * 1e3,
             sdkInstalled: true,
             eligible: true,
-            lastHeartbeat: now
+            lastHeartbeat: now,
+            warmupTag,
+            agentSetupComplete
           };
-          console.log(`[POOL] Warmup completed for ${sandbox.sandboxId} (took ${warmupTime}ms)${useTarball ? " [tarball]" : ""}`);
+          const tagInfo = warmupTag ? ` [tag=${warmupTag}]` : "";
+          console.log(`[POOL] Warmup completed for ${sandbox.sandboxId} (took ${warmupTime}ms)${useTarball ? " [tarball]" : ""}${tagInfo}`);
+          this.consecutiveFailures = 0;
           this.emitMetric("warmup_completed", {
             sandboxId: pooled.sandboxId,
             warmupTimeMs: warmupTime,
-            usedTarball: useTarball
+            usedTarball: useTarball,
+            warmupTag,
+            agentSetupComplete
           });
           this.emitMetric("sandbox_created", { sandboxId: pooled.sandboxId });
           return pooled;
         } catch (error) {
           const warmupTime = Date.now() - startTime;
+          this.consecutiveFailures++;
+          const errorMessage = error instanceof Error ? error.message : "Unknown";
+          if (this.consecutiveFailures === 1) {
+            console.error(`[POOL] Warmup failed: ${errorMessage}`);
+          } else {
+            console.error(
+              `[POOL] Warmup failed (${this.consecutiveFailures} consecutive). Next attempt in ${Math.min(_SandboxPool.BACKOFF_BASE_MS * Math.pow(2, this.consecutiveFailures - 1), 3e5) / 1e3}s. Error: ${errorMessage}`
+            );
+          }
           this.emitMetric("warmup_failed", {
-            error: error instanceof Error ? error.message : "Unknown",
+            error: errorMessage,
             warmupTimeMs: warmupTime,
-            usedTarball: useTarball
+            usedTarball: useTarball,
+            consecutiveFailures: this.consecutiveFailures
           });
           throw error;
         } finally {
@@ -5000,18 +5128,29 @@ echo "[warmup] Warmup complete!"
         }
       }
       /**
-       * Get an available eligible sandbox for assignment
+       * Get an available eligible sandbox for assignment.
+       * If preferTag is provided:
+       * - First tries to find a sandbox tagged for that specific agent
+       * - Falls back to a generic (untagged) sandbox
+       * - Tagged sandboxes for OTHER agents are NOT used as fallback (reserved)
        */
-      getAvailableSandbox() {
-        let best = null;
+      getAvailableSandbox(preferTag) {
+        let bestTagged = null;
+        let bestGeneric = null;
         for (const pooled of this.pool.values()) {
           if (!pooled.assignedTo && pooled.eligible) {
-            if (!best || pooled.expiresAt > best.expiresAt) {
-              best = pooled;
+            if (preferTag && pooled.warmupTag === preferTag) {
+              if (!bestTagged || pooled.expiresAt > bestTagged.expiresAt) {
+                bestTagged = pooled;
+              }
+            } else if (!pooled.warmupTag) {
+              if (!bestGeneric || pooled.expiresAt > bestGeneric.expiresAt) {
+                bestGeneric = pooled;
+              }
             }
           }
         }
-        return best;
+        return bestTagged || bestGeneric;
       }
       /**
        * Get count of available sandboxes
@@ -5046,9 +5185,30 @@ echo "[warmup] Warmup complete!"
         });
       }
       /**
-       * Replenish pool if below min size
+       * Replenish pool if below min size.
+       * Applies exponential backoff when warmups keep failing to avoid
+       * a tight failure loop that wastes resources and floods metrics.
        */
       async replenishPool() {
+        if (this.consecutiveFailures >= _SandboxPool.MAX_CONSECUTIVE_FAILURES) {
+          if (Math.random() < 0.2) {
+            console.warn(
+              `[POOL] Warmup suspended after ${this.consecutiveFailures} consecutive failures. Check SANDBOX_BASE_TARBALL_URL or Vercel API status. Pool will retry on next acquire().`
+            );
+          }
+          return;
+        }
+        if (this.consecutiveFailures > 0) {
+          const backoffMs = Math.min(
+            _SandboxPool.BACKOFF_BASE_MS * Math.pow(2, this.consecutiveFailures - 1),
+            5 * 6e4
+            // Cap at 5 minutes
+          );
+          const timeSinceLastAttempt = Date.now() - this.lastWarmupAttemptAt;
+          if (timeSinceLastAttempt < backoffMs) {
+            return;
+          }
+        }
         const eligibleCount = this.getEligibleCount();
         const warmingCount = this.warmingInProgress.size;
         const totalProjected = eligibleCount + warmingCount;
@@ -5057,13 +5217,16 @@ echo "[warmup] Warmup complete!"
           this.config.maxPoolSize - this.pool.size - warmingCount
         );
         if (needed <= 0) return;
+        const specAssignments = this.selectSpecsForReplenishment(needed);
         console.log(`[POOL] Spawning ${needed} sandbox(es) to maintain pool...`);
         const promises = [];
         for (let i = 0; i < needed; i++) {
+          const spec = specAssignments[i];
           promises.push(
-            this.warmSandbox().then((sandbox) => {
+            this.warmSandbox(spec).then((sandbox) => {
               this.pool.set(sandbox.sandboxId, sandbox);
-              console.log(`[POOL] Replenishment sandbox ready: ${sandbox.sandboxId}`);
+              const tagInfo = sandbox.warmupTag ? ` [tag=${sandbox.warmupTag}]` : "";
+              console.log(`[POOL] Replenishment sandbox ready: ${sandbox.sandboxId}${tagInfo}`);
             }).catch((error) => {
               console.error("[POOL] Failed to warm replenishment sandbox:", error);
             })
@@ -5074,6 +5237,39 @@ echo "[warmup] Warmup complete!"
         }
         await Promise.all(promises);
       }
+      /**
+       * Decide which specs to apply to new sandboxes during replenishment.
+       * Strategy: cover uncovered specs first (highest priority), then fill remaining as generic.
+       * Returns an array of length `needed`, where each element is a spec or undefined (generic).
+       */
+      selectSpecsForReplenishment(needed) {
+        if (this.warmupSpecs.size === 0) {
+          return new Array(needed).fill(void 0);
+        }
+        const uncoveredSpecs = [];
+        for (const spec of this.warmupSpecs.values()) {
+          let hasCoverage = false;
+          for (const pooled of this.pool.values()) {
+            if (pooled.warmupTag === spec.tag && pooled.eligible && !pooled.assignedTo) {
+              hasCoverage = true;
+              break;
+            }
+          }
+          if (!hasCoverage) {
+            uncoveredSpecs.push(spec);
+          }
+        }
+        uncoveredSpecs.sort((a, b) => b.priority - a.priority);
+        const assignments = [];
+        for (const spec of uncoveredSpecs) {
+          if (assignments.length >= needed) break;
+          assignments.push(spec);
+        }
+        while (assignments.length < needed) {
+          assignments.push(void 0);
+        }
+        return assignments;
+      }
       /**
        * Destroy a sandbox and clean up
        */
@@ -5305,7 +5501,7 @@ function removeExpiredSandbox(sessionId) {
   }
 }
 async function getOrCreateSandbox(options) {
-  const { sessionId, runtime = "node22", timeout = 300, vcpus = 4, existingSandboxId } = options;
+  const { sessionId, runtime = "node22", timeout = 300, vcpus = 4, existingSandboxId, preferTag } = options;
   ensureCleanupRunning();
   ensureHeartbeatRunning();
   const { Sandbox } = await import('@vercel/sandbox');
@@ -5322,6 +5518,8 @@ async function getOrCreateSandbox(options) {
         sdkInstalled: cached.sdkInstalled,
         startupScriptRan: cached.startupScriptRan,
         startupScriptHash: cached.startupScriptHash,
+        installScriptRan: cached.installScriptRan,
+        installScriptHash: cached.installScriptHash,
         isNew: false,
         configFileUrl: cached.configFileUrl,
         configInstalledAt: cached.configInstalledAt
@@ -5330,41 +5528,6 @@ async function getOrCreateSandbox(options) {
     console.log("[SANDBOX] Cached sandbox has expired (HTTP 410 or similar), creating new sandbox");
     removeExpiredSandbox(sessionId);
   }
-  const pool = await ensureSandboxPoolInitialized();
-  if (pool && pool.isRunning()) {
-    try {
-      console.log("[SANDBOX] Attempting to acquire from pre-warmed pool...");
-      const pooled = await pool.acquire(sessionId);
-      console.log("[SANDBOX] Acquired pre-warmed sandbox:", pooled.sandboxId);
-      const now2 = Date.now();
-      const entry2 = {
-        sandbox: pooled.sandbox,
-        sessionId,
-        createdAt: pooled.createdAt,
-        lastUsedAt: now2,
-        sdkInstalled: pooled.sdkInstalled,
-        startupScriptRan: false
-        // User script hasn't run yet
-      };
-      sandboxCache.set(sessionId, entry2);
-      return {
-        sandbox: pooled.sandbox,
-        sandboxId: pooled.sandboxId,
-        sdkInstalled: pooled.sdkInstalled,
-        startupScriptRan: false,
-        startupScriptHash: void 0,
-        isNew: false,
-        // Not new - came from pool
-        configFileUrl: void 0,
-        configInstalledAt: void 0
-      };
-    } catch (error) {
-      console.warn(
-        "[SANDBOX] Failed to acquire from pool, falling back to on-demand creation:",
-        error instanceof Error ? error.message : "Unknown error"
-      );
-    }
-  }
   if (existingSandboxId) {
     console.log("[SANDBOX] Attempting to reconnect to existing sandbox:", existingSandboxId);
     try {
@@ -5385,7 +5548,9 @@ async function getOrCreateSandbox(options) {
           // We assume SDK is installed since this is an existing sandbox
           // The caller can verify and re-mark if needed
           sdkInstalled: true,
-          startupScriptRan: true
+          startupScriptRan: true,
+          installScriptRan: true
+          // Assume ran for reconnected sandboxes
         };
         sandboxCache.set(sessionId, entry2);
         return {
@@ -5397,13 +5562,17 @@ async function getOrCreateSandbox(options) {
           // Assume ran for reconnected sandboxes
           startupScriptHash: void 0,
           // Unknown — caller should not re-run based on hash mismatch alone
+          installScriptRan: true,
+          // Assume ran for reconnected sandboxes
+          installScriptHash: void 0,
+          // Unknown — same logic as startup script
           isNew: false,
           configFileUrl: void 0,
           configInstalledAt: now2
           // Assume config was installed — prevents unnecessary re-install on reconnection
         };
       } else {
-        console.log("[SANDBOX] Reconnected sandbox failed health check, will create new");
+        console.log("[SANDBOX] Reconnected sandbox failed health check, will try pool or create new");
       }
     } catch (error) {
       console.log(
@@ -5413,6 +5582,47 @@ async function getOrCreateSandbox(options) {
       );
     }
   }
+  const pool = await ensureSandboxPoolInitialized();
+  if (pool && pool.isRunning()) {
+    try {
+      console.log(`[SANDBOX] Attempting to acquire from pre-warmed pool...${preferTag ? ` [preferTag=${preferTag}]` : ""}`);
+      const pooled = await pool.acquire(sessionId, preferTag);
+      const tagInfo = pooled.warmupTag ? ` [tag=${pooled.warmupTag}, agentSetup=${pooled.agentSetupComplete}]` : "";
+      console.log(`[SANDBOX] Acquired pre-warmed sandbox: ${pooled.sandboxId}${tagInfo}`);
+      const agentSetupDone = pooled.agentSetupComplete === true;
+      const now2 = Date.now();
+      const entry2 = {
+        sandbox: pooled.sandbox,
+        sessionId,
+        createdAt: pooled.createdAt,
+        lastUsedAt: now2,
+        sdkInstalled: pooled.sdkInstalled,
+        startupScriptRan: agentSetupDone,
+        installScriptRan: agentSetupDone
+      };
+      sandboxCache.set(sessionId, entry2);
+      return {
+        sandbox: pooled.sandbox,
+        sandboxId: pooled.sandboxId,
+        sdkInstalled: pooled.sdkInstalled,
+        startupScriptRan: agentSetupDone,
+        startupScriptHash: void 0,
+        installScriptRan: agentSetupDone,
+        installScriptHash: void 0,
+        isNew: false,
+        // Not new - came from pool
+        configFileUrl: void 0,
+        configInstalledAt: agentSetupDone ? now2 : void 0,
+        warmupTag: pooled.warmupTag,
+        agentSetupComplete: pooled.agentSetupComplete
+      };
+    } catch (error) {
+      console.warn(
+        "[SANDBOX] Failed to acquire from pool, falling back to on-demand creation:",
+        error instanceof Error ? error.message : "Unknown error"
+      );
+    }
+  }
   console.log("[SANDBOX] Creating new sandbox for session:", sessionId);
   const baseTarballUrl = process.env.SANDBOX_BASE_TARBALL_URL;
   const useTarball = !!baseTarballUrl;
@@ -5446,7 +5656,8 @@ async function getOrCreateSandbox(options) {
     lastUsedAt: now,
     // If we used tarball, SDK is pre-installed
     sdkInstalled: useTarball,
-    startupScriptRan: false
+    startupScriptRan: false,
+    installScriptRan: false
   };
   sandboxCache.set(sessionId, entry);
   return {
@@ -5456,6 +5667,8 @@ async function getOrCreateSandbox(options) {
     sdkInstalled: useTarball,
     startupScriptRan: false,
     startupScriptHash: void 0,
+    installScriptRan: false,
+    installScriptHash: void 0,
     isNew: true,
     configFileUrl: void 0,
     configInstalledAt: void 0
@@ -5495,6 +5708,14 @@ function markStartupScriptRan(sessionId, scriptHash) {
     cached.lastUsedAt = Date.now();
   }
 }
+function markInstallScriptRan(sessionId, scriptHash) {
+  const cached = sandboxCache.get(sessionId);
+  if (cached) {
+    cached.installScriptRan = true;
+    cached.installScriptHash = scriptHash;
+    cached.lastUsedAt = Date.now();
+  }
+}
 function needsStartupScriptRerun(sessionId, newScript) {
   const cached = sandboxCache.get(sessionId);
   if (!cached) return true;
@@ -5562,6 +5783,8 @@ function getCachedSandbox(sessionId) {
     sdkInstalled: cached.sdkInstalled,
     startupScriptRan: cached.startupScriptRan,
     startupScriptHash: cached.startupScriptHash,
+    installScriptRan: cached.installScriptRan,
+    installScriptHash: cached.installScriptHash,
     isNew: false,
     configFileUrl: cached.configFileUrl,
     configInstalledAt: cached.configInstalledAt
@@ -6154,6 +6377,85 @@ SCRIPT_EOF`]
     }
   }
 }
+async function warmSandboxForSession(options) {
+  const {
+    sessionId,
+    runtime = "node22",
+    timeout = 600,
+    vcpus = 4,
+    startupScript,
+    configFileUrl,
+    envVars = {}
+  } = options;
+  console.log(`[WARM] Pre-warming sandbox for session: ${sessionId}`);
+  const startTime = Date.now();
+  const result = await getOrCreateSandbox({
+    sessionId,
+    runtime,
+    timeout,
+    vcpus
+  });
+  const { sandbox, sdkInstalled } = result;
+  if (!sdkInstalled) {
+    console.log("[WARM] Installing SDK...");
+    await sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", "which jq || (sudo dnf install -y jq 2>/dev/null || sudo apt-get update && sudo apt-get install -y jq 2>/dev/null || sudo apk add jq 2>/dev/null) || true"]
+    });
+    await sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", "which ffmpeg || (sudo dnf install -y ffmpeg 2>/dev/null || sudo apt-get update && sudo apt-get install -y ffmpeg 2>/dev/null || sudo apk add ffmpeg 2>/dev/null) || true"]
+    });
+    const sdkResult = await sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", "npm init -y && npm install @anthropic-ai/claude-agent-sdk"],
+      env: envVars
+    });
+    if (sdkResult.exitCode !== 0) {
+      const stderr = await sdkResult.stderr();
+      throw new Error(`Failed to install Claude Agent SDK during warmup: ${stderr}`);
+    }
+    markSdkInstalled(sessionId);
+  }
+  if (startupScript) {
+    console.log("[WARM] Running startup script...");
+    const scriptResult = await sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", startupScript],
+      env: envVars
+    });
+    if (scriptResult.exitCode !== 0) {
+      const stderr = await scriptResult.stderr();
+      throw new Error(`Startup script failed during warmup: ${stderr}`);
+    }
+    markStartupScriptRan(sessionId, hashStartupScript(startupScript));
+  }
+  if (configFileUrl) {
+    console.log("[WARM] Installing config from:", configFileUrl);
+    const configScript = `
+      set -e
+      curl -sSL --fail "${configFileUrl}" -o /tmp/config.zip
+      unzip -o /tmp/config.zip -d .
+      rm -f /tmp/config.zip
+    `;
+    const configResult = await sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", configScript],
+      env: envVars
+    });
+    if (configResult.exitCode !== 0) {
+      const stderr = await configResult.stderr();
+      throw new Error(`Config installation failed during warmup: ${stderr}`);
+    }
+    markConfigInstalled(sessionId, configFileUrl);
+  }
+  const duration = Date.now() - startTime;
+  console.log(`[WARM] Sandbox pre-warmed for session ${sessionId} in ${duration}ms (sandbox: ${result.sandboxId})`);
+  return {
+    sandboxId: result.sandboxId,
+    ready: true
+  };
+}
 var sandboxCache, DEFAULT_IDLE_TTL, CLEANUP_INTERVAL, HEARTBEAT_INTERVAL, cleanupIntervalId, heartbeatIntervalId, GLOBAL_HEARTBEAT_KEY, heartbeatListeners;
 var init_vercel_sandbox_executor = __esm({
   "src/runtime/vercel-sandbox-executor.ts"() {
@@ -6808,6 +7110,31 @@ WATCHER_EOF`;
     globalInSandboxManager = null;
   }
 });
+function matchGlob(pattern, filePath) {
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const normalizedPattern = pattern.replace(/\\/g, "/");
+  let regexStr = "";
+  let i = 0;
+  while (i < normalizedPattern.length) {
+    if (normalizedPattern[i] === "*" && normalizedPattern[i + 1] === "*") {
+      if (normalizedPattern[i + 2] === "/") {
+        regexStr += "(?:.*/)?";
+        i += 3;
+      } else {
+        regexStr += ".*";
+        i += 2;
+      }
+    } else if (normalizedPattern[i] === "*") {
+      regexStr += "[^/]*";
+      i += 1;
+    } else {
+      const ch = normalizedPattern[i];
+      regexStr += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      i += 1;
+    }
+  }
+  return new RegExp(`^${regexStr}$`).test(normalizedPath);
+}
 function extractErrorMessage(error) {
   if (error === null || error === void 0) {
     return "Unknown error (null/undefined)";
@@ -6850,12 +7177,18 @@ function extractErrorMessage(error) {
 function createSandboxFileSync(options) {
   return new exports.SandboxFileSync(options);
 }
-exports.SandboxFileSync = void 0;
+var DEFAULT_WEBHOOK_IGNORE; exports.SandboxFileSync = void 0;
 var init_sandbox_file_sync = __esm({
   "src/runtime/sandbox-file-sync.ts"() {
     init_sandbox_file_watcher();
     init_in_sandbox_watcher();
     init_types();
+    DEFAULT_WEBHOOK_IGNORE = [
+      "**/agent-runner.js",
+      "**/agent-runner.cjs",
+      "**/.file-watcher.js",
+      "**/.file-watcher-output.log"
+    ];
     exports.SandboxFileSync = class {
       fileStore;
       sandboxBasePath;
@@ -6870,6 +7203,10 @@ var init_sandbox_file_sync = __esm({
       fileChangeSubscribers = /* @__PURE__ */ new Set();
       // Sequence number cache per session (for event storage)
       sequenceNumbers = /* @__PURE__ */ new Map();
+      // Webhook batching state
+      batchTimer = null;
+      batchQueue = /* @__PURE__ */ new Map();
+      // keyed by file path for dedup
       constructor(options) {
         this.fileStore = options.fileStore;
         this.sandboxBasePath = options.sandboxBasePath ?? ".claude/files";
@@ -6904,6 +7241,72 @@ var init_sandbox_file_sync = __esm({
        */
       removeWebhook() {
         this.webhookConfig = void 0;
+        if (this.batchTimer) {
+          clearTimeout(this.batchTimer);
+          this.batchTimer = null;
+        }
+        this.batchQueue.clear();
+      }
+      /**
+       * Check if a file path should be excluded from webhook notifications.
+       * Tests against DEFAULT_WEBHOOK_IGNORE patterns and any user-configured ignorePaths.
+       */
+      shouldIgnorePath(filePath) {
+        if (!filePath) return false;
+        const userPatterns = this.webhookConfig?.ignorePaths ?? [];
+        const allPatterns = [...DEFAULT_WEBHOOK_IGNORE, ...userPatterns];
+        return allPatterns.some((pattern) => matchGlob(pattern, filePath));
+      }
+      /**
+       * Route a webhook payload through batching (if configured) or send immediately.
+       * When batchWindowMs is set, payloads are queued and deduplicated by file path.
+       */
+      enqueueOrSendWebhook(payload, sessionId) {
+        const batchWindowMs = this.webhookConfig?.batchWindowMs;
+        if (!batchWindowMs || batchWindowMs <= 0) {
+          this.sendWebhook(payload, sessionId);
+          return;
+        }
+        const filePath = payload.fileSyncEvent?.canonicalPath ?? payload.fileChangeEvent?.relativePath ?? `_unknown_${Date.now()}`;
+        this.batchQueue.set(filePath, payload);
+        if (this.batchTimer) {
+          clearTimeout(this.batchTimer);
+        }
+        this.batchTimer = setTimeout(() => {
+          this.flushWebhookBatch(sessionId);
+        }, batchWindowMs);
+      }
+      /**
+       * Flush all queued webhook payloads as a single batch request.
+       */
+      async flushWebhookBatch(sessionId) {
+        this.batchTimer = null;
+        if (this.batchQueue.size === 0) return;
+        const payloads = Array.from(this.batchQueue.values());
+        this.batchQueue.clear();
+        const fileSyncEvents = [];
+        const fileChangeEvents = [];
+        let batchSessionId = sessionId ?? "";
+        for (const p of payloads) {
+          if (!batchSessionId) {
+            batchSessionId = p.sessionId;
+          }
+          if (p.fileSyncEvent) {
+            fileSyncEvents.push(p.fileSyncEvent);
+          }
+          if (p.fileChangeEvent) {
+            fileChangeEvents.push(p.fileChangeEvent);
+          }
+        }
+        const batchPayload = {
+          event: "file_sync_batch",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          sessionId: batchSessionId,
+          metadata: this.webhookConfig?.metadata,
+          fileSyncEvents,
+          fileChangeEvents
+        };
+        await this.sendWebhook(batchPayload, sessionId);
       }
       /**
        * Extract hostname from URL for display (security - don't expose full URL)
@@ -7045,6 +7448,9 @@ var init_sandbox_file_sync = __esm({
        * pre-signed S3 download URL when the file exists in storage.
        */
       async sendFileSyncWebhook(sessionId, event) {
+        if (this.shouldIgnorePath(event.canonicalPath)) {
+          return;
+        }
         let downloadUrl;
         if (event.success && event.canonicalPath && !event.operation.startsWith("deleted")) {
           try {
@@ -7070,12 +7476,15 @@ var init_sandbox_file_sync = __esm({
           metadata: this.webhookConfig?.metadata,
           fileSyncEvent: webhookEvent
         };
-        await this.sendWebhook(payload, sessionId);
+        this.enqueueOrSendWebhook(payload, sessionId);
       }
       /**
        * Send a file change event webhook (from watcher)
        */
       async sendFileChangeWebhook(event) {
+        if (this.shouldIgnorePath(event.relativePath)) {
+          return;
+        }
         const payload = {
           event: "file_change",
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -7083,7 +7492,7 @@ var init_sandbox_file_sync = __esm({
           metadata: this.webhookConfig?.metadata,
           fileChangeEvent: event
         };
-        await this.sendWebhook(payload, event.sessionId);
+        this.enqueueOrSendWebhook(payload, event.sessionId);
       }
       /**
        * Get the next sequence number for a session
@@ -7747,6 +8156,11 @@ var init_sandbox_file_sync = __esm({
         await Promise.all([...inSandboxPromises, ...localPromises]);
         this.inSandboxWatchers.clear();
         this.localWatchers.clear();
+        if (this.batchTimer) {
+          clearTimeout(this.batchTimer);
+          this.batchTimer = null;
+          await this.flushWebhookBatch();
+        }
       }
       /**
        * Get watching status for all sessions
@@ -9815,6 +10229,58 @@ function createSessionsRouter(options) {
       }
     });
   });
+  router.get("/:sessionId/stream-events", async (c) => {
+    const sessionId = c.req.param("sessionId");
+    const afterSequence = Math.max(0, parseInt(c.req.query("afterSequence") || "0", 10) || 0);
+    const limit = Math.min(Math.max(1, parseInt(c.req.query("limit") || "100", 10) || 100), 1e3);
+    const waitMs = Math.min(Math.max(0, parseInt(c.req.query("waitMs") || "0", 10) || 0), 3e4);
+    const session = await sessionManager.getSession(sessionId);
+    if (!session) {
+      return c.json({ error: "Session not found" }, 404);
+    }
+    const agent = agents2.get(session.agentName);
+    if (!agent) {
+      return c.json({ error: `Agent not found: ${session.agentName}` }, 404);
+    }
+    const streamEventStorage = agent.getStreamEventStorage();
+    if (!streamEventStorage) {
+      return c.json({ error: "Stream event storage not configured" }, 501);
+    }
+    let events = await streamEventStorage.readEvents(sessionId, {
+      afterSequence,
+      limit
+    });
+    if (events.length === 0 && waitMs > 0) {
+      const deadline = Date.now() + waitMs;
+      const pollInterval = 200;
+      while (Date.now() < deadline) {
+        events = await streamEventStorage.readEvents(sessionId, {
+          afterSequence,
+          limit
+        });
+        if (events.length > 0) break;
+        const currentSession = await sessionManager.getSession(sessionId);
+        if (currentSession && ["completed", "error", "stopped"].includes(currentSession.status)) {
+          break;
+        }
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
+      }
+    }
+    const nextCursor = events.length > 0 ? Math.max(...events.map((e) => e.sequence)) : afterSequence;
+    return c.json({
+      events: events.map((e) => ({
+        id: e.id,
+        sequence: e.sequence,
+        eventType: e.eventType,
+        payload: e.payload,
+        batchCount: e.batchCount,
+        createdAt: e.createdAt.toISOString()
+      })),
+      nextCursor,
+      hasMore: events.length === limit,
+      sessionStatus: session.status
+    });
+  });
   router.get("/:sessionId/stream", async (c) => {
     const sessionId = c.req.param("sessionId");
     const afterParam = c.req.query("after");
@@ -10499,7 +10965,8 @@ function createHarnessServer(config) {
     basePath = "/api",
     middleware = [],
     hooks = {},
-    queue: queueConfig = {}
+    queue: queueConfig = {},
+    sandbox: sandboxConfig
   } = config;
   let agentsNeedReload = false;
   const sessionManager = new exports.SessionManager(storage);
@@ -10650,7 +11117,7 @@ function createHarnessServer(config) {
       return agentStorage.getActiveAgents();
     },
     /**
-     * Initialize storage, agents, and start queue processor
+     * Initialize storage, agents, start queue processor, and optionally init sandbox pool
      */
     async initialize() {
       await storage.initialize();
@@ -10664,12 +11131,20 @@ function createHarnessServer(config) {
         await agent.initialize();
       }
       queueProcessor?.start();
+      if (sandboxConfig?.pool && sandboxConfig.autoInitPool !== false) {
+        try {
+          await initializeSandboxPool(sandboxConfig.pool);
+        } catch (error) {
+          console.error("[SERVER] Failed to initialize sandbox pool:", error instanceof Error ? error.message : error);
+        }
+      }
     },
     /**
-     * Close storage, agents, and stop queue processor
+     * Close storage, agents, stop queue processor, and shutdown sandbox pool
      */
     async close() {
       queueProcessor?.stop();
+      await shutdownSandboxPool();
       for (const agent of agents2.values()) {
         await agent.close();
       }
@@ -10691,6 +11166,7 @@ var init_server = __esm({
     init_agents();
     init_skills2();
     init_queue2();
+    init_sandbox_pool();
   }
 });
 
@@ -13612,7 +14088,8 @@ function createOpenAPIServer(config) {
     basePath = "/api",
     middleware = [],
     hooks = {},
-    docs = {}
+    docs = {},
+    sandbox: sandboxConfig
   } = config;
   const {
     enabled: docsEnabled = true,
@@ -13787,7 +14264,7 @@ Authentication is handled by the hosting application. This API does not enforce
       return agentStorage.getActiveAgents();
     },
     /**
-     * Initialize storage and agents
+     * Initialize storage, agents, and optionally init sandbox pool
      */
     async initialize() {
       await storage.initialize();
@@ -13797,11 +14274,19 @@ Authentication is handled by the hosting application. This API does not enforce
       for (const agent of agents2.values()) {
         await agent.initialize();
       }
+      if (sandboxConfig?.pool && sandboxConfig.autoInitPool !== false) {
+        try {
+          await initializeSandboxPool(sandboxConfig.pool);
+        } catch (error) {
+          console.error("[SERVER] Failed to initialize sandbox pool:", error instanceof Error ? error.message : error);
+        }
+      }
     },
     /**
-     * Close storage and agents
+     * Close storage, agents, and shutdown sandbox pool
      */
     async close() {
+      await shutdownSandboxPool();
       for (const agent of agents2.values()) {
         await agent.close();
       }
@@ -13833,6 +14318,7 @@ var init_server2 = __esm({
     init_sessions2();
     init_agents2();
     init_skills3();
+    init_sandbox_pool();
   }
 });
 
@@ -16597,6 +17083,7 @@ __export(schema_exports, {
   configDeployments: () => configDeployments,
   configDeploymentsRelations: () => configDeploymentsRelations,
   eventCategoryEnum: () => eventCategoryEnum,
+  eventSourceEnum: () => eventSourceEnum,
   messageRoleEnum: () => messageRoleEnum,
   messages: () => messages,
   messagesRelations: () => messagesRelations,
@@ -16610,7 +17097,7 @@ __export(schema_exports, {
   streamEvents: () => streamEvents,
   streamEventsRelations: () => streamEventsRelations
 });
-var sessionStatusEnum, messageRoleEnum, agentStatusEnum, agentBackendEnum, queueItemStatusEnum, configDeploymentStatusEnum, configDeploymentTriggerEnum, eventCategoryEnum, sessions, messages, attachments, agents, queueItems, configDeployments, sessionEvents, streamEvents, sessionsRelations, sessionEventsRelations, messagesRelations, attachmentsRelations, configDeploymentsRelations, streamEventsRelations, agentsRelations;
+var sessionStatusEnum, messageRoleEnum, agentStatusEnum, agentBackendEnum, queueItemStatusEnum, configDeploymentStatusEnum, configDeploymentTriggerEnum, eventSourceEnum, eventCategoryEnum, sessions, messages, attachments, agents, queueItems, configDeployments, sessionEvents, streamEvents, sessionsRelations, sessionEventsRelations, messagesRelations, attachmentsRelations, configDeploymentsRelations, streamEventsRelations, agentsRelations;
 var init_schema = __esm({
   "src/storage-postgres/schema.ts"() {
     sessionStatusEnum = pgCore.pgEnum("session_status", [
@@ -16652,6 +17139,14 @@ var init_schema = __esm({
       "initial",
       "rollback"
     ]);
+    eventSourceEnum = pgCore.pgEnum("event_source", [
+      "agent",
+      // Directly from the agent SDK
+      "system",
+      // Generated by execution layer (lifecycle, user input)
+      "derived"
+      // Transformed/aggregated from agent events
+    ]);
     eventCategoryEnum = pgCore.pgEnum("event_category", [
       "lifecycle",
       // session_start, session_end, turn_complete
@@ -16842,6 +17337,8 @@ var init_schema = __esm({
         // Aggregation fields (for text_stream events)
         isAggregated: pgCore.boolean("is_aggregated").default(false),
         aggregatedCount: pgCore.integer("aggregated_count"),
+        // Event source tagging
+        eventSource: eventSourceEnum("event_source").notNull().default("agent"),
         // Ordering
         sequenceNumber: pgCore.integer("sequence_number").notNull(),
         createdAt: pgCore.timestamp("created_at", { withTimezone: true }).defaultNow().notNull()
@@ -17434,6 +17931,11 @@ var init_storage2 = __esm({
             drizzleOrm.eq(sessions.status, options.status)
           );
         }
+        if (options.resourceId) {
+          conditions.push(
+            drizzleOrm.sql`${sessions.metadata}->>'resourceId' = ${options.resourceId}`
+          );
+        }
         const orderColumn = options.orderBy === "updatedAt" ? sessions.updatedAt : sessions.createdAt;
         const orderFn = options.order === "asc" ? drizzleOrm.asc : drizzleOrm.desc;
         const limit = options.limit ?? 50;
@@ -18155,6 +18657,9 @@ var init_storage3 = __esm({
         if (options.status) {
           query = query.eq("status", options.status);
         }
+        if (options.resourceId) {
+          query = query.eq("metadata->>resourceId", options.resourceId);
+        }
         const orderColumn = options.orderBy === "updatedAt" ? "updated_at" : "created_at";
         const ascending = options.order === "asc";
         query = query.order(orderColumn, { ascending }).range(offset, offset + limit - 1);
@@ -18512,6 +19017,7 @@ var init_storage3 = __esm({
           sessionId: row.session_id,
           eventType: row.event_type,
           category: row.category,
+          eventSource: row.event_source,
           startedAt: new Date(row.started_at),
           endedAt: row.ended_at ? new Date(row.ended_at) : void 0,
           durationMs: row.duration_ms ?? void 0,
@@ -18534,6 +19040,7 @@ var init_storage3 = __esm({
             session_id: sessionId,
             event_type: event.eventType,
             category: event.category,
+            event_source: event.eventSource || "agent",
             started_at: event.startedAt.toISOString(),
             ended_at: event.endedAt?.toISOString() ?? null,
             duration_ms: event.durationMs ?? null,
@@ -18560,6 +19067,9 @@ var init_storage3 = __esm({
         if (options.eventType) {
           query = query.eq("event_type", options.eventType);
         }
+        if (options.eventSource) {
+          query = query.eq("event_source", options.eventSource);
+        }
         if (options.filePath) {
           query = query.or(
             `event_data->>filePath.eq.${options.filePath},event_data->>canonicalPath.eq.${options.filePath},and(category.eq.tool,tool_name.in.(Read,Write,Edit),event_data->input->>file_path.eq.${options.filePath})`
@@ -18896,7 +19406,8 @@ var init_storage4 = __esm({
               limit: options?.limit,
               offset: options?.offset,
               agentName: options?.agentName,
-              status: options?.status
+              status: options?.status,
+              resourceId: options?.resourceId
             }
           }
         );
@@ -19642,6 +20153,7 @@ exports.loadWorkspaceState = loadWorkspaceState;
 exports.mapClaudeOptionsToGemini = mapClaudeOptionsToGemini;
 exports.mapToolToActionType = mapToolToActionType;
 exports.markConfigInstalled = markConfigInstalled;
+exports.markInstallScriptRan = markInstallScriptRan;
 exports.markSdkInstalled = markSdkInstalled;
 exports.markStartupScriptRan = markStartupScriptRan;
 exports.mcpAuthToHeaders = mcpAuthToHeaders;
@@ -19669,6 +20181,7 @@ exports.sseMcpWithAuth = sseMcpWithAuth;
 exports.startServer = startServer;
 exports.streamEventRelay = streamEventRelay;
 exports.updateToolCallWithResult = updateToolCallWithResult;
+exports.warmSandboxForSession = warmSandboxForSession;
 exports.writeFileToSandbox = writeFileToSandbox;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map