@ash-cloud/ash-ai 0.1.16 → 0.1.18

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var zod = require('zod');
 var child_process = require('child_process');
+var events = require('events');
 var nanoid = require('nanoid');
 var fs = require('fs/promises');
 var path4 = require('path');
@@ -107,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();
@@ -232,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
+    };
   }
 });
 
@@ -384,6 +393,85 @@ var init_errors = __esm({
   }
 });
 
+// src/relay/stream-event-writer.ts
+exports.StreamEventWriter = void 0;
+var init_stream_event_writer = __esm({
+  "src/relay/stream-event-writer.ts"() {
+    exports.StreamEventWriter = class {
+      storage;
+      sessionId;
+      emitter;
+      flushIntervalMs;
+      maxBatchChars;
+      // Text delta batching state
+      pendingDelta = "";
+      pendingDeltaCount = 0;
+      flushTimer = null;
+      closed = false;
+      constructor(options) {
+        this.storage = options.storage;
+        this.sessionId = options.sessionId;
+        this.emitter = options.emitter;
+        this.flushIntervalMs = options.flushIntervalMs ?? 100;
+        this.maxBatchChars = options.maxBatchChars ?? 500;
+      }
+      /**
+       * Write a stream event. Text deltas are batched; all other events are written immediately.
+       */
+      async write(event) {
+        if (this.closed) return;
+        if (this.emitter) {
+          this.emitter.emit("event", event);
+        }
+        if (event.type === "text_delta") {
+          this.pendingDelta += event.delta;
+          this.pendingDeltaCount++;
+          if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => this.flush(), this.flushIntervalMs);
+          }
+          if (this.pendingDelta.length >= this.maxBatchChars) {
+            await this.flush();
+          }
+        } else {
+          await this.flush();
+          await this.writeToStorage([{ eventType: event.type, payload: event, batchCount: 1 }]);
+        }
+      }
+      /**
+       * Flush any pending text_delta events to storage as a single batched event.
+       */
+      async flush() {
+        if (this.flushTimer) {
+          clearTimeout(this.flushTimer);
+          this.flushTimer = null;
+        }
+        if (this.pendingDelta.length === 0) return;
+        const batchedEvent = {
+          type: "text_delta",
+          delta: this.pendingDelta
+        };
+        const batchCount = this.pendingDeltaCount;
+        this.pendingDelta = "";
+        this.pendingDeltaCount = 0;
+        await this.writeToStorage([{ eventType: "text_delta", payload: batchedEvent, batchCount }]);
+      }
+      /**
+       * Close the writer, flushing any remaining events.
+       */
+      async close() {
+        await this.flush();
+        this.closed = true;
+        if (this.emitter) {
+          this.emitter.emit("done");
+        }
+      }
+      async writeToStorage(events) {
+        return this.storage.appendEvents(this.sessionId, events);
+      }
+    };
+  }
+});
+
 // src/session/manager.ts
 exports.SessionManager = void 0;
 var init_manager = __esm({
@@ -1788,11 +1876,10 @@ var init_sandbox_logger = __esm({
     };
   }
 });
-
-// src/agent/harness.ts
 exports.AgentHarness = void 0;
 var init_harness = __esm({
   "src/agent/harness.ts"() {
+    init_stream_event_writer();
     init_manager();
     init_claude_sdk();
     init_backend();
@@ -1809,6 +1896,8 @@ var init_harness = __esm({
       sessionSkillDirs = /* @__PURE__ */ new Map();
       /** Tracks active executions by session ID for stop/interrupt capability */
       activeExecutions = /* @__PURE__ */ new Map();
+      /** EventEmitters for same-process SSE relay fast-path, keyed by session ID */
+      sessionEmitters = /* @__PURE__ */ new Map();
       constructor(config) {
         this.name = config.name;
         this.config = config;
@@ -1956,6 +2045,20 @@ var init_harness = __esm({
       getSessionManager() {
         return this.sessionManager;
       }
+      /**
+       * Get the stream event storage (if configured)
+       */
+      getStreamEventStorage() {
+        return this.config.streamEventStorage;
+      }
+      /**
+       * Get the EventEmitter for a session's stream events.
+       * Used by the relay endpoint for same-process fast-path.
+       * Returns undefined if no active execution or no streamEventStorage configured.
+       */
+      getSessionEmitter(sessionId) {
+        return this.sessionEmitters.get(sessionId);
+      }
       async ensureInitialized() {
         if (!this.initialized) {
           await this.initialize();
@@ -1970,9 +2073,24 @@ var init_harness = __esm({
           async *send(prompt, options = {}) {
             const controller = new AbortController();
             self.activeExecutions.set(session.id, controller);
+            let writer;
+            let emitter;
+            if (self.config.streamEventStorage) {
+              emitter = new events.EventEmitter();
+              self.sessionEmitters.set(session.id, emitter);
+              writer = new exports.StreamEventWriter({
+                storage: self.config.streamEventStorage,
+                sessionId: session.id,
+                emitter
+              });
+            }
             if (options.signal) {
               options.signal.addEventListener("abort", () => controller.abort(), { once: true });
             }
+            const writeEvent = writer ? (event) => {
+              writer.write(event).catch(() => {
+              });
+            } : void 0;
             let partialTextContent = "";
             const sandboxLogs = [];
             const logQueue = [];
@@ -1986,7 +2104,9 @@ var init_harness = __esm({
             const yieldQueuedLogs = async function* () {
               while (logQueue.length > 0) {
                 const entry = logQueue.shift();
-                yield { type: "sandbox_log", entry };
+                const event = { type: "sandbox_log", entry };
+                writeEvent?.(event);
+                yield event;
               }
             };
             logger3.info("execution", `Starting execution for session ${session.id}`);
@@ -2003,11 +2123,13 @@ var init_harness = __esm({
             if (self.hooks.onMessage && savedUserMessage) {
               await self.hooks.onMessage(savedUserMessage);
             }
-            yield {
+            const sessionStartEvent = {
               type: "session_start",
               sessionId: session.id,
               sdkSessionId: session.sdkSessionId ?? ""
             };
+            writeEvent?.(sessionStartEvent);
+            yield sessionStartEvent;
             yield* yieldQueuedLogs();
             const assistantContent = [];
             let wasAborted = false;
@@ -2028,22 +2150,26 @@ var init_harness = __esm({
                 }
                 if (event.type === "text_delta" && event.delta) {
                   partialTextContent += event.delta;
-                  yield {
+                  const textDeltaEvent = {
                     type: "text_delta",
                     delta: event.delta
                   };
+                  writeEvent?.(textDeltaEvent);
+                  yield textDeltaEvent;
                 } else if (event.type === "thinking_delta" && event.delta) {
-                  yield {
+                  const thinkingEvent = {
                     type: "thinking_delta",
                     delta: event.delta
                   };
+                  writeEvent?.(thinkingEvent);
+                  yield thinkingEvent;
                 } else if (event.type === "text") {
                   const textContent = {
                     type: "text",
                     text: event.text
                   };
                   assistantContent.push(textContent);
-                  yield {
+                  const messageEvent = {
                     type: "message",
                     message: {
                       id: "",
@@ -2053,6 +2179,8 @@ var init_harness = __esm({
                       createdAt: /* @__PURE__ */ new Date()
                     }
                   };
+                  writeEvent?.(messageEvent);
+                  yield messageEvent;
                 } else if (event.type === "tool_use") {
                   logger3.debug("execution", `Tool use: ${event.name}`, { toolId: event.id });
                   const toolContent = {
@@ -2062,12 +2190,14 @@ var init_harness = __esm({
                     input: event.input
                   };
                   assistantContent.push(toolContent);
-                  yield {
+                  const toolUseEvent = {
                     type: "tool_use",
                     id: event.id,
                     name: event.name,
                     input: event.input
                   };
+                  writeEvent?.(toolUseEvent);
+                  yield toolUseEvent;
                   yield* yieldQueuedLogs();
                   if (self.hooks.onToolUse) {
                     await self.hooks.onToolUse(event.name, event.input, null);
@@ -2084,12 +2214,14 @@ var init_harness = __esm({
                     isError: event.isError
                   };
                   assistantContent.push(resultContent);
-                  yield {
+                  const toolResultEvent = {
                     type: "tool_result",
                     toolUseId: event.toolUseId,
                     content: event.content,
                     isError: event.isError
                   };
+                  writeEvent?.(toolResultEvent);
+                  yield toolResultEvent;
                 }
               }
               if (wasAborted || controller.signal.aborted) {
@@ -2118,19 +2250,23 @@ var init_harness = __esm({
                   }
                 });
                 yield* yieldQueuedLogs();
-                yield {
+                const stoppedEvent = {
                   type: "session_stopped",
                   sessionId: session.id,
                   reason: "user_requested",
                   partialContent: partialTextContent || void 0
                 };
+                writeEvent?.(stoppedEvent);
+                yield stoppedEvent;
                 return;
               }
               logger3.info("execution", "Execution completed successfully");
-              yield {
+              const turnCompleteEvent = {
                 type: "turn_complete",
                 sessionId: session.id
               };
+              writeEvent?.(turnCompleteEvent);
+              yield turnCompleteEvent;
               if (assistantContent.length > 0) {
                 const savedAssistantMessages = await self.sessionManager.saveMessages(
                   session.id,
@@ -2154,11 +2290,13 @@ var init_harness = __esm({
                 }
               });
               yield* yieldQueuedLogs();
-              yield {
+              const sessionEndEvent = {
                 type: "session_end",
                 sessionId: session.id,
                 status: "completed"
               };
+              writeEvent?.(sessionEndEvent);
+              yield sessionEndEvent;
               if (self.hooks.onSessionEnd) {
                 const updatedSession = await self.sessionManager.getSession(session.id);
                 if (updatedSession) {
@@ -2189,12 +2327,14 @@ var init_harness = __esm({
                   }
                 });
                 yield* yieldQueuedLogs();
-                yield {
+                const catchStoppedEvent = {
                   type: "session_stopped",
                   sessionId: session.id,
                   reason: "user_requested",
                   partialContent: partialTextContent || void 0
                 };
+                writeEvent?.(catchStoppedEvent);
+                yield catchStoppedEvent;
               } else {
                 logger3.error("execution", `Execution error: ${errorMessage}`);
                 await self.sessionManager.updateSession(session.id, {
@@ -2212,13 +2352,19 @@ var init_harness = __esm({
                     await self.hooks.onError(error, updatedSession);
                   }
                 }
-                yield {
+                const errorEvent = {
                   type: "error",
                   error: errorMessage
                 };
+                writeEvent?.(errorEvent);
+                yield errorEvent;
               }
             } finally {
               self.activeExecutions.delete(session.id);
+              if (writer) {
+                await writer.close();
+              }
+              self.sessionEmitters.delete(session.id);
             }
           },
           async getSession() {
@@ -2457,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) => {
@@ -2722,12 +2873,88 @@ var init_queue_memory = __esm({
     };
   }
 });
+exports.MemoryStreamEventStorage = void 0;
+var init_stream_event_memory = __esm({
+  "src/storage/stream-event-memory.ts"() {
+    exports.MemoryStreamEventStorage = class {
+      events = /* @__PURE__ */ new Map();
+      nextSequence = /* @__PURE__ */ new Map();
+      async initialize() {
+      }
+      async close() {
+        this.events.clear();
+        this.nextSequence.clear();
+      }
+      async appendEvents(sessionId, events) {
+        if (!this.events.has(sessionId)) {
+          this.events.set(sessionId, []);
+        }
+        const sessionEvents2 = this.events.get(sessionId);
+        let seq = this.nextSequence.get(sessionId) ?? 0;
+        const stored = [];
+        for (const event of events) {
+          seq += 1;
+          const storedEvent = {
+            id: nanoid.nanoid(),
+            sessionId,
+            sequence: seq,
+            eventType: event.eventType,
+            payload: event.payload,
+            batchCount: event.batchCount ?? 1,
+            createdAt: /* @__PURE__ */ new Date()
+          };
+          sessionEvents2.push(storedEvent);
+          stored.push(storedEvent);
+        }
+        this.nextSequence.set(sessionId, seq);
+        return stored;
+      }
+      async readEvents(sessionId, options) {
+        const sessionEvents2 = this.events.get(sessionId) ?? [];
+        let result = sessionEvents2;
+        if (options?.afterSequence !== void 0) {
+          result = result.filter((e) => e.sequence > options.afterSequence);
+        }
+        if (options?.limit !== void 0) {
+          result = result.slice(0, options.limit);
+        }
+        return result;
+      }
+      async getLatestSequence(sessionId) {
+        return this.nextSequence.get(sessionId) ?? 0;
+      }
+      async deleteSessionEvents(sessionId) {
+        this.events.delete(sessionId);
+        this.nextSequence.delete(sessionId);
+      }
+      async cleanupOldEvents(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let deleted = 0;
+        for (const [sessionId, sessionEvents2] of this.events) {
+          const before = sessionEvents2.length;
+          const remaining = sessionEvents2.filter(
+            (e) => e.createdAt.getTime() >= cutoff
+          );
+          deleted += before - remaining.length;
+          if (remaining.length === 0) {
+            this.events.delete(sessionId);
+            this.nextSequence.delete(sessionId);
+          } else {
+            this.events.set(sessionId, remaining);
+          }
+        }
+        return deleted;
+      }
+    };
+  }
+});
 
 // src/storage/index.ts
 var init_storage = __esm({
   "src/storage/index.ts"() {
     init_memory();
     init_queue_memory();
+    init_stream_event_memory();
   }
 });
 
@@ -4312,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()) {
@@ -4403,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();
@@ -4412,6 +4639,14 @@ echo "[warmup] Warmup complete!"
       lastMaintenanceAt = null;
       metricsCallback;
       startPromise = null;
+      /** 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"),
@@ -4587,6 +4822,8 @@ echo "[warmup] Warmup complete!"
           warming: this.warmingInProgress.size,
           running: this.running,
           lastMaintenanceAt: this.lastMaintenanceAt,
+          consecutiveFailures: this.consecutiveFailures,
+          warmupSuspended: this.consecutiveFailures >= _SandboxPool.MAX_CONSECUTIVE_FAILURES,
           config: {
             minPoolSize: this.config.minPoolSize,
             maxPoolSize: this.config.maxPoolSize,
@@ -4612,6 +4849,7 @@ echo "[warmup] Warmup complete!"
         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');
@@ -4712,6 +4950,7 @@ echo "[warmup] Warmup complete!"
             lastHeartbeat: now
           };
           console.log(`[POOL] Warmup completed for ${sandbox.sandboxId} (took ${warmupTime}ms)${useTarball ? " [tarball]" : ""}`);
+          this.consecutiveFailures = 0;
           this.emitMetric("warmup_completed", {
             sandboxId: pooled.sandboxId,
             warmupTimeMs: warmupTime,
@@ -4721,10 +4960,20 @@ echo "[warmup] Warmup complete!"
           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 {
@@ -4832,9 +5081,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;
@@ -5182,10 +5452,11 @@ async function getOrCreateSandbox(options) {
           startupScriptRan: true,
           // Assume ran for reconnected sandboxes
           startupScriptHash: void 0,
+          // Unknown — caller should not re-run based on hash mismatch alone
           isNew: false,
           configFileUrl: void 0,
-          configInstalledAt: void 0
-          // We don't know when config was installed on reconnected sandboxes
+          configInstalledAt: now2
+          // Assume config was installed — prevents unnecessary re-install on reconnection
         };
       } else {
         console.log("[SANDBOX] Reconnected sandbox failed health check, will create new");
@@ -5571,7 +5842,8 @@ async function* executeInSandbox(prompt, apiKey, options) {
       markSdkInstalled(sessionId);
     }
     const currentScriptHash = hashStartupScript(options.startupScript);
-    const needsStartupScript = options.startupScript && (!startupScriptRan || currentScriptHash !== cachedScriptHash);
+    const scriptHashChanged = cachedScriptHash !== void 0 && currentScriptHash !== cachedScriptHash;
+    const needsStartupScript = options.startupScript && (!startupScriptRan || scriptHashChanged);
     if (needsStartupScript) {
       console.log("[SANDBOX] Running startup script...");
       const startupStartTime = Date.now();
@@ -5705,11 +5977,18 @@ const { query } = require('@anthropic-ai/claude-agent-sdk');
 const prompt = ${JSON.stringify(prompt)};
 const options = ${JSON.stringify(sdkOptions)};
 
+let queryCompleted = false;
+
 async function run() {
   try {
     for await (const message of query({ prompt, options })) {
       console.log(JSON.stringify(message));
     }
+    queryCompleted = true;
+    // Exit cleanly immediately after query completes.
+    // MCP server cleanup (e.g. Playwright browser shutdown) can trigger
+    // unhandled rejections after the query is done, causing spurious exit code 1.
+    process.exit(0);
   } catch (error) {
     const errorInfo = {
       type: 'error',
@@ -5725,6 +6004,11 @@ async function run() {
 }
 
 process.on('unhandledRejection', (reason) => {
+  // Ignore rejections from MCP server cleanup after query has completed
+  if (queryCompleted) {
+    process.exit(0);
+    return;
+  }
   const errorInfo = {
     type: 'error',
     error: reason instanceof Error ? reason.message : String(reason),
@@ -5735,6 +6019,11 @@ process.on('unhandledRejection', (reason) => {
 });
 
 process.on('uncaughtException', (error) => {
+  // Ignore exceptions from MCP server cleanup after query has completed
+  if (queryCompleted) {
+    process.exit(0);
+    return;
+  }
   const errorInfo = {
     type: 'error',
     error: error.message || 'Unknown error',
@@ -5921,6 +6210,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"() {
@@ -6575,6 +6943,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)";
@@ -6617,12 +7010,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;
@@ -6637,6 +7036,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";
@@ -6671,6 +7074,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)
@@ -6807,22 +7276,48 @@ var init_sandbox_file_sync = __esm({
         }
       }
       /**
-       * Send a file sync event webhook
+       * Send a file sync event webhook.
+       * Strips raw Buffer content (previousContent/newContent) and replaces with a
+       * 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 {
+            downloadUrl = await this.fileStore.getSignedUrl(sessionId, event.canonicalPath);
+          } catch {
+          }
+        }
+        const webhookEvent = {
+          operation: event.operation,
+          source: event.source,
+          canonicalPath: event.canonicalPath,
+          basePath: event.basePath,
+          sandboxPath: event.sandboxPath,
+          fileSize: event.fileSize,
+          success: event.success,
+          error: event.error,
+          downloadUrl
+        };
         const payload = {
           event: "file_sync",
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
           sessionId,
           metadata: this.webhookConfig?.metadata,
-          fileSyncEvent: event
+          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(),
@@ -6830,7 +7325,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
@@ -7494,6 +7989,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
@@ -9103,6 +9603,135 @@ var init_utils = __esm({
     init_sandbox_logger();
   }
 });
+
+// src/relay/stream-event-relay.ts
+async function* streamEventRelay(options) {
+  const {
+    storage,
+    sessionId,
+    afterSequence = 0,
+    emitter,
+    pollIntervalMs = 100,
+    heartbeatIntervalMs = 15e3,
+    signal
+  } = options;
+  let lastSequence = afterSequence;
+  let done = false;
+  const catchUpEvents = await storage.readEvents(sessionId, {
+    afterSequence: lastSequence,
+    limit: 1e4
+  });
+  for (const stored of catchUpEvents) {
+    if (signal?.aborted || done) return;
+    lastSequence = stored.sequence;
+    yield stored.payload;
+    if (TERMINAL_EVENT_TYPES.has(stored.eventType)) {
+      done = true;
+      return;
+    }
+  }
+  if (signal?.aborted) return;
+  if (emitter) {
+    yield* relayFromEmitter(emitter, signal, heartbeatIntervalMs);
+  } else {
+    yield* relayByPolling(storage, sessionId, lastSequence, pollIntervalMs, heartbeatIntervalMs, signal);
+  }
+}
+async function* relayFromEmitter(emitter, signal, heartbeatIntervalMs = 15e3) {
+  const queue = [];
+  let resolve3 = null;
+  const onEvent = (event) => {
+    queue.push(event);
+    if (resolve3) {
+      resolve3();
+      resolve3 = null;
+    }
+  };
+  const onDone = () => {
+    queue.push("done");
+    if (resolve3) {
+      resolve3();
+      resolve3 = null;
+    }
+  };
+  emitter.on("event", onEvent);
+  emitter.on("done", onDone);
+  const heartbeatTimer = setInterval(() => {
+    if (resolve3) {
+      resolve3();
+      resolve3 = null;
+    }
+  }, heartbeatIntervalMs);
+  try {
+    while (!signal?.aborted) {
+      while (queue.length > 0) {
+        const item = queue.shift();
+        if (item === "done") return;
+        yield item;
+        if (TERMINAL_EVENT_TYPES.has(item.type)) return;
+      }
+      await new Promise((r) => {
+        resolve3 = r;
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            resolve3 = null;
+            r();
+          }, { once: true });
+        }
+      });
+    }
+  } finally {
+    clearInterval(heartbeatTimer);
+    emitter.off("event", onEvent);
+    emitter.off("done", onDone);
+  }
+}
+async function* relayByPolling(storage, sessionId, startSequence, pollIntervalMs, heartbeatIntervalMs, signal) {
+  let lastSequence = startSequence;
+  while (!signal?.aborted) {
+    const events = await storage.readEvents(sessionId, {
+      afterSequence: lastSequence,
+      limit: 100
+    });
+    for (const stored of events) {
+      if (signal?.aborted) return;
+      lastSequence = stored.sequence;
+      yield stored.payload;
+      if (TERMINAL_EVENT_TYPES.has(stored.eventType)) {
+        return;
+      }
+    }
+    if (events.length === 0) {
+      await new Promise((r) => {
+        const timer = setTimeout(r, pollIntervalMs);
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            r();
+          }, { once: true });
+        }
+      });
+    }
+  }
+}
+var TERMINAL_EVENT_TYPES;
+var init_stream_event_relay = __esm({
+  "src/relay/stream-event-relay.ts"() {
+    TERMINAL_EVENT_TYPES = /* @__PURE__ */ new Set([
+      "session_end",
+      "error",
+      "session_stopped"
+    ]);
+  }
+});
+
+// src/relay/index.ts
+var init_relay = __esm({
+  "src/relay/index.ts"() {
+    init_stream_event_writer();
+    init_stream_event_relay();
+  }
+});
 function broadcastToSession(sessionId, event) {
   const subscribers = sessionSubscribers.get(sessionId);
   if (subscribers && subscribers.size > 0) {
@@ -9235,6 +9864,8 @@ function createSessionsRouter(options) {
       agentName: session.agentName,
       startedAt: /* @__PURE__ */ new Date()
     });
+    const hasStreamEventStorage = !!agent.getStreamEventStorage();
+    let sendSequenceCounter = 0;
     return streaming.streamSSE(c, async (stream) => {
       try {
         for await (const event of activeSession.send(data.prompt, {
@@ -9246,7 +9877,9 @@ function createSessionsRouter(options) {
           if (controller.signal.aborted) {
             break;
           }
+          sendSequenceCounter++;
           await stream.writeSSE({
+            ...hasStreamEventStorage ? { id: String(sendSequenceCounter) } : {},
             event: event.type,
             data: JSON.stringify(event)
           });
@@ -9429,11 +10062,129 @@ 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");
+    const afterSequence = afterParam ? parseInt(afterParam, 10) : 0;
+    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);
+    }
+    return streaming.streamSSE(c, async (stream) => {
+      const abortController = new AbortController();
+      c.req.raw.signal.addEventListener("abort", () => {
+        abortController.abort();
+      });
+      const heartbeatInterval = setInterval(async () => {
+        try {
+          await stream.writeSSE({
+            event: "heartbeat",
+            data: JSON.stringify({ type: "heartbeat", timestamp: Date.now() })
+          });
+        } catch {
+          clearInterval(heartbeatInterval);
+        }
+      }, 15e3);
+      let sequenceCounter = afterSequence;
+      try {
+        const sessionEmitter = agent.getSessionEmitter(sessionId);
+        const relay = streamEventRelay({
+          storage: streamEventStorage,
+          sessionId,
+          afterSequence,
+          emitter: sessionEmitter,
+          signal: abortController.signal
+        });
+        for await (const event of relay) {
+          if (abortController.signal.aborted) break;
+          sequenceCounter++;
+          await stream.writeSSE({
+            id: String(sequenceCounter),
+            event: event.type,
+            data: JSON.stringify(event)
+          });
+        }
+      } catch (error) {
+        if (!abortController.signal.aborted) {
+          await stream.writeSSE({
+            event: "error",
+            data: JSON.stringify({
+              type: "error",
+              error: error instanceof Error ? error.message : "Unknown error"
+            })
+          });
+        }
+      } finally {
+        clearInterval(heartbeatInterval);
+      }
+    });
+  });
   return router;
 }
 var createSessionSchema, fileAttachmentSchema, sendMessageSchema, updateEnvSchema, listSessionsSchema, activeStreams, sessionSubscribers;
 var init_sessions = __esm({
   "src/server/routes/sessions.ts"() {
+    init_stream_event_relay();
     createSessionSchema = zod.z.object({
       agentName: zod.z.string(),
       metadata: zod.z.record(zod.z.unknown()).optional(),
@@ -10047,7 +10798,8 @@ function createHarnessServer(config) {
     basePath = "/api",
     middleware = [],
     hooks = {},
-    queue: queueConfig = {}
+    queue: queueConfig = {},
+    sandbox: sandboxConfig
   } = config;
   let agentsNeedReload = false;
   const sessionManager = new exports.SessionManager(storage);
@@ -10198,7 +10950,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();
@@ -10212,12 +10964,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();
       }
@@ -10239,6 +10999,7 @@ var init_server = __esm({
     init_agents();
     init_skills2();
     init_queue2();
+    init_sandbox_pool();
   }
 });
 
@@ -13160,7 +13921,8 @@ function createOpenAPIServer(config) {
     basePath = "/api",
     middleware = [],
     hooks = {},
-    docs = {}
+    docs = {},
+    sandbox: sandboxConfig
   } = config;
   const {
     enabled: docsEnabled = true,
@@ -13335,7 +14097,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();
@@ -13345,11 +14107,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();
       }
@@ -13381,6 +14151,7 @@ var init_server2 = __esm({
     init_sessions2();
     init_agents2();
     init_skills3();
+    init_sandbox_pool();
   }
 });
 
@@ -16145,6 +16916,7 @@ __export(schema_exports, {
   configDeployments: () => configDeployments,
   configDeploymentsRelations: () => configDeploymentsRelations,
   eventCategoryEnum: () => eventCategoryEnum,
+  eventSourceEnum: () => eventSourceEnum,
   messageRoleEnum: () => messageRoleEnum,
   messages: () => messages,
   messagesRelations: () => messagesRelations,
@@ -16154,9 +16926,11 @@ __export(schema_exports, {
   sessionEventsRelations: () => sessionEventsRelations,
   sessionStatusEnum: () => sessionStatusEnum,
   sessions: () => sessions,
-  sessionsRelations: () => sessionsRelations
+  sessionsRelations: () => sessionsRelations,
+  streamEvents: () => streamEvents,
+  streamEventsRelations: () => streamEventsRelations
 });
-var sessionStatusEnum, messageRoleEnum, agentStatusEnum, agentBackendEnum, queueItemStatusEnum, configDeploymentStatusEnum, configDeploymentTriggerEnum, eventCategoryEnum, sessions, messages, attachments, agents, queueItems, configDeployments, sessionEvents, sessionsRelations, sessionEventsRelations, messagesRelations, attachmentsRelations, configDeploymentsRelations, 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", [
@@ -16198,6 +16972,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
@@ -16388,6 +17170,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()
@@ -16397,6 +17181,21 @@ var init_schema = __esm({
         pgCore.index("idx_session_events_category").on(table.sessionId, table.category)
       ]
     );
+    streamEvents = pgCore.pgTable(
+      "stream_events",
+      {
+        id: pgCore.uuid("id").defaultRandom().primaryKey(),
+        sessionId: pgCore.uuid("session_id").notNull().references(() => sessions.id, { onDelete: "cascade" }),
+        sequence: pgCore.integer("sequence").notNull(),
+        eventType: pgCore.text("event_type").notNull(),
+        payload: pgCore.jsonb("payload").notNull().$type(),
+        batchCount: pgCore.integer("batch_count").default(1).notNull(),
+        createdAt: pgCore.timestamp("created_at", { withTimezone: true }).defaultNow().notNull()
+      },
+      (table) => [
+        pgCore.index("idx_stream_events_session_seq").on(table.sessionId, table.sequence)
+      ]
+    );
     sessionsRelations = drizzleOrm.relations(sessions, ({ one, many }) => ({
       parentSession: one(sessions, {
         fields: [sessions.parentSessionId],
@@ -16407,7 +17206,8 @@ var init_schema = __esm({
         relationName: "parentSession"
       }),
       messages: many(messages),
-      events: many(sessionEvents)
+      events: many(sessionEvents),
+      streamEvents: many(streamEvents)
     }));
     sessionEventsRelations = drizzleOrm.relations(sessionEvents, ({ one }) => ({
       session: one(sessions, {
@@ -16434,6 +17234,12 @@ var init_schema = __esm({
         references: [agents.id]
       })
     }));
+    streamEventsRelations = drizzleOrm.relations(streamEvents, ({ one }) => ({
+      session: one(sessions, {
+        fields: [streamEvents.sessionId],
+        references: [sessions.id]
+      })
+    }));
     agentsRelations = drizzleOrm.relations(agents, ({ many }) => ({
       configDeployments: many(configDeployments)
     }));
@@ -16621,6 +17427,20 @@ var init_storage2 = __esm({
     `);
         await this.db.execute(drizzleOrm.sql`
       ALTER TABLE agents ADD COLUMN IF NOT EXISTS backend agent_backend DEFAULT 'claude' NOT NULL;
+    `);
+        await this.db.execute(drizzleOrm.sql`
+      CREATE TABLE IF NOT EXISTS stream_events (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        sequence INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        payload JSONB NOT NULL,
+        batch_count INTEGER NOT NULL DEFAULT 1,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+        await this.db.execute(drizzleOrm.sql`
+      CREATE INDEX IF NOT EXISTS idx_stream_events_session_seq ON stream_events(session_id, sequence);
     `);
       }
       /**
@@ -16813,6 +17633,20 @@ var init_storage2 = __esm({
     `);
         await this.db.execute(drizzleOrm.sql`
       CREATE INDEX IF NOT EXISTS idx_queue_items_pending ON queue_items(agent_name, session_id, status, priority, created_at);
+    `);
+        await this.db.execute(drizzleOrm.sql`
+      CREATE TABLE IF NOT EXISTS stream_events (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        sequence INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        payload JSONB NOT NULL,
+        batch_count INTEGER NOT NULL DEFAULT 1,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+        await this.db.execute(drizzleOrm.sql`
+      CREATE INDEX IF NOT EXISTS idx_stream_events_session_seq ON stream_events(session_id, sequence);
     `);
         await this.db.execute(drizzleOrm.sql`
       DO $$ BEGIN
@@ -16930,6 +17764,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;
@@ -17203,6 +18042,56 @@ var init_storage2 = __esm({
         return rows.map((row) => this.rowToAgent(row));
       }
       // ============================================================================
+      // Stream Events (SSE Relay)
+      // ============================================================================
+      async appendEvents(sessionId, events) {
+        if (events.length === 0) return [];
+        const [maxSeqResult] = await this.db.select({ maxSeq: drizzleOrm.sql`COALESCE(MAX(${streamEvents.sequence}), 0)` }).from(streamEvents).where(drizzleOrm.eq(streamEvents.sessionId, sessionId));
+        let nextSeq = (maxSeqResult?.maxSeq ?? 0) + 1;
+        const rows = await this.db.insert(streamEvents).values(
+          events.map((event) => ({
+            sessionId,
+            sequence: nextSeq++,
+            eventType: event.eventType,
+            payload: event.payload,
+            batchCount: event.batchCount ?? 1
+          }))
+        ).returning();
+        return rows.map((row) => this.rowToStoredStreamEvent(row));
+      }
+      async readEvents(sessionId, options) {
+        const conditions = [drizzleOrm.eq(streamEvents.sessionId, sessionId)];
+        if (options?.afterSequence !== void 0) {
+          conditions.push(drizzleOrm.sql`${streamEvents.sequence} > ${options.afterSequence}`);
+        }
+        const limit = options?.limit ?? 1e3;
+        const rows = await this.db.select().from(streamEvents).where(drizzleOrm.and(...conditions)).orderBy(drizzleOrm.asc(streamEvents.sequence)).limit(limit);
+        return rows.map((row) => this.rowToStoredStreamEvent(row));
+      }
+      async getLatestSequence(sessionId) {
+        const [result] = await this.db.select({ maxSeq: drizzleOrm.sql`COALESCE(MAX(${streamEvents.sequence}), 0)` }).from(streamEvents).where(drizzleOrm.eq(streamEvents.sessionId, sessionId));
+        return result?.maxSeq ?? 0;
+      }
+      async deleteSessionEvents(sessionId) {
+        await this.db.delete(streamEvents).where(drizzleOrm.eq(streamEvents.sessionId, sessionId));
+      }
+      async cleanupOldEvents(maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs);
+        const result = await this.db.delete(streamEvents).where(drizzleOrm.sql`${streamEvents.createdAt} < ${cutoff.toISOString()}`);
+        return result.rowCount ?? 0;
+      }
+      rowToStoredStreamEvent(row) {
+        return {
+          id: row.id,
+          sessionId: row.sessionId,
+          sequence: row.sequence,
+          eventType: row.eventType,
+          payload: row.payload,
+          batchCount: row.batchCount,
+          createdAt: row.createdAt
+        };
+      }
+      // ============================================================================
       // Database Access (for extensions)
       // ============================================================================
       /**
@@ -17601,6 +18490,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);
@@ -17958,6 +18850,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,
@@ -17980,6 +18873,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,
@@ -18006,6 +18900,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})`
@@ -18038,6 +18935,72 @@ var init_storage3 = __esm({
         }
         return data ? data.sequence_number + 1 : 1;
       }
+      // ============================================================================
+      // Stream Events (SSE Relay)
+      // ============================================================================
+      async appendEvents(sessionId, events) {
+        if (events.length === 0) return [];
+        const { data: maxSeqData } = await this.client.from("stream_events").select("sequence").eq("session_id", sessionId).order("sequence", { ascending: false }).limit(1).single();
+        let nextSeq = maxSeqData ? maxSeqData.sequence + 1 : 1;
+        const { data, error } = await this.client.from("stream_events").insert(
+          events.map((event) => ({
+            session_id: sessionId,
+            sequence: nextSeq++,
+            event_type: event.eventType,
+            payload: event.payload,
+            batch_count: event.batchCount ?? 1
+          }))
+        ).select();
+        if (error) {
+          throw new Error(`Failed to append stream events: ${error.message}`);
+        }
+        return data.map((row) => this.rowToStoredStreamEvent(row));
+      }
+      async readEvents(sessionId, options) {
+        let query = this.client.from("stream_events").select("*").eq("session_id", sessionId);
+        if (options?.afterSequence !== void 0) {
+          query = query.gt("sequence", options.afterSequence);
+        }
+        const limit = options?.limit ?? 1e3;
+        query = query.order("sequence", { ascending: true }).limit(limit);
+        const { data, error } = await query;
+        if (error) {
+          throw new Error(`Failed to read stream events: ${error.message}`);
+        }
+        return data.map((row) => this.rowToStoredStreamEvent(row));
+      }
+      async getLatestSequence(sessionId) {
+        const { data, error } = await this.client.from("stream_events").select("sequence").eq("session_id", sessionId).order("sequence", { ascending: false }).limit(1).single();
+        if (error && error.code !== "PGRST116") {
+          throw new Error(`Failed to get latest sequence: ${error.message}`);
+        }
+        return data ? data.sequence : 0;
+      }
+      async deleteStreamEvents(sessionId) {
+        const { error } = await this.client.from("stream_events").delete().eq("session_id", sessionId);
+        if (error) {
+          throw new Error(`Failed to delete stream events: ${error.message}`);
+        }
+      }
+      async cleanupOldEvents(maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
+        const { data, error } = await this.client.from("stream_events").delete().lt("created_at", cutoff).select("id");
+        if (error) {
+          throw new Error(`Failed to cleanup old stream events: ${error.message}`);
+        }
+        return data?.length ?? 0;
+      }
+      rowToStoredStreamEvent(row) {
+        return {
+          id: row.id,
+          sessionId: row.session_id,
+          sequence: row.sequence,
+          eventType: row.event_type,
+          payload: row.payload,
+          batchCount: row.batch_count,
+          createdAt: new Date(row.created_at)
+        };
+      }
     };
   }
 });
@@ -18276,7 +19239,8 @@ var init_storage4 = __esm({
               limit: options?.limit,
               offset: options?.offset,
               agentName: options?.agentName,
-              status: options?.status
+              status: options?.status,
+              resourceId: options?.resourceId
             }
           }
         );
@@ -18870,6 +19834,7 @@ var init_src = __esm({
     init_credentials();
     init_skills();
     init_utils();
+    init_relay();
     init_server();
     init_server2();
     init_schemas();
@@ -19046,7 +20011,9 @@ exports.shouldUseSandbox = shouldUseSandbox;
 exports.shutdownSandboxPool = shutdownSandboxPool;
 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