@ash-cloud/ash-ai 0.1.18 → 0.1.20

package/dist/index.cjs

@@ -913,6 +913,32 @@ var init_mcp = __esm({
 });
 
 // src/agent/claude-sdk.ts
+function isStandardMcpServerConfig(config) {
+  if (!config || typeof config !== "object") return false;
+  const candidate = config;
+  if (typeof candidate.command === "string") return true;
+  if (typeof candidate.url === "string") return true;
+  if (candidate.type === "stdio" || candidate.type === "http" || candidate.type === "sse") return true;
+  return false;
+}
+function hasCustomMcpServers(mcpServers) {
+  if (!mcpServers) return false;
+  return Object.values(mcpServers).some((config) => !isStandardMcpServerConfig(config));
+}
+async function* toStreamingPrompt(prompt) {
+  yield {
+    type: "user",
+    message: {
+      role: "user",
+      content: prompt
+    }
+  };
+}
+function normalizePromptForSdk(prompt, mcpServers) {
+  if (typeof prompt !== "string") return prompt;
+  if (!hasCustomMcpServers(mcpServers)) return prompt;
+  return toStreamingPrompt(prompt);
+}
 function convertClaudeMessage(claudeMessage, sessionId) {
   if (claudeMessage.type !== "assistant" || !claudeMessage.message) {
     return null;
@@ -956,16 +982,17 @@ function normalizeMcpServers(mcpServers) {
   if (!mcpServers) return mcpServers;
   return Object.fromEntries(
     Object.entries(mcpServers).map(([name, config]) => {
-      if (!config.auth) {
+      const configWithAuth = config;
+      if (!configWithAuth.auth) {
         return [name, config];
       }
-      const authHeaders = mcpAuthToHeaders(config.auth);
-      const { auth: _auth, ...rest } = config;
+      const authHeaders = mcpAuthToHeaders(configWithAuth.auth);
+      const { auth: _auth, ...rest } = configWithAuth;
       return [name, {
         ...rest,
         headers: {
           ...authHeaders,
-          ...config.headers
+          ...configWithAuth.headers
           // Explicit headers take precedence
         }
       }];
@@ -992,8 +1019,22 @@ var init_claude_sdk = __esm({
       async *query(prompt, options = {}) {
         const model = options.model ?? this.defaultModel;
         if (await this.checkSdkAvailable()) {
-          yield* this.executeRealQuery(prompt, { ...options, model });
+          const normalizedOptions = { ...options, model };
+          if (normalizedOptions.agents) {
+            const allowedTools = normalizedOptions.allowedTools ?? [];
+            if (!allowedTools.includes("Task")) {
+              normalizedOptions.allowedTools = [...allowedTools, "Task"];
+            }
+          }
+          yield* this.executeRealQuery(prompt, normalizedOptions);
         } else {
+          if (typeof prompt !== "string") {
+            yield {
+              type: "error",
+              error: "Streaming prompts require the real Claude Agent SDK to be installed."
+            };
+            return;
+          }
           yield* this.executeSimulatedQuery(prompt, { ...options, model });
         }
       }
@@ -1007,8 +1048,9 @@ var init_claude_sdk = __esm({
         }
         try {
           const { query } = await import('@anthropic-ai/claude-agent-sdk');
+          const normalizedMcpServers = normalizeMcpServers(options.mcpServers);
           const queryOptions = {
-            prompt,
+            prompt: normalizePromptForSdk(prompt, options.mcpServers),
             options: {
               model: options.model,
               allowedTools: options.allowedTools,
@@ -1017,10 +1059,12 @@ var init_claude_sdk = __esm({
               maxTurns: options.maxTurns,
               resume: options.resume,
               forkSession: options.forkSession,
-              mcpServers: options.mcpServers,
+              mcpServers: normalizedMcpServers,
               agents: options.agents,
               hooks: options.hooks,
+              plugins: options.plugins,
               settingSources: options.settingSources,
+              outputFormat: options.outputFormat,
               // Enable streaming partial messages for real-time text deltas
               includePartialMessages: true,
               // Environment variables for the SDK
@@ -1043,7 +1087,8 @@ var init_claude_sdk = __esm({
             if (message.type === "system" && message.subtype === "init") {
               yield {
                 type: "session_init",
-                sessionId: message.session_id
+                sessionId: message.session_id,
+                slashCommands: message.slash_commands
               };
               continue;
             }
@@ -1094,12 +1139,17 @@ var init_claude_sdk = __esm({
               }
             }
             if (message.type === "result") {
+              const usage = message.usage;
+              const hasUsageTokens = !!usage && (usage.input_tokens !== void 0 || usage.output_tokens !== void 0);
+              const totalTokens = hasUsageTokens ? (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0) : message.tokens ? message.tokens.input + message.tokens.output : void 0;
+              const totalCost = usage?.total_cost_usd ?? message.cost ?? message.total_cost_usd;
               yield {
                 type: "complete",
                 sessionId: message.session_id,
                 result: message.result,
-                totalCost: message.cost,
-                totalTokens: message.tokens ? message.tokens.input + message.tokens.output : void 0
+                structured_output: message.structured_output,
+                totalCost,
+                totalTokens
               };
             }
           }
@@ -1107,6 +1157,13 @@ var init_claude_sdk = __esm({
           const errorMessage = error instanceof Error ? error.message : "Unknown error";
           if (errorMessage.includes("Cannot find module") || errorMessage.includes("MODULE_NOT_FOUND")) {
             console.warn("Claude Agent SDK not installed, using simulation mode");
+            if (typeof prompt !== "string") {
+              yield {
+                type: "error",
+                error: "Streaming prompts require the real Claude Agent SDK to be installed."
+              };
+              return;
+            }
             yield* this.executeSimulatedQuery(prompt, options);
           } else {
             yield {
@@ -1284,7 +1341,11 @@ var init_claude_sdk = __esm({
             this.sessionId = msg.session_id;
           }
           if (msg.type === "system" && msg.subtype === "init") {
-            yield { type: "session_init", sessionId: msg.session_id };
+            yield {
+              type: "session_init",
+              sessionId: msg.session_id,
+              slashCommands: msg.slash_commands
+            };
           } else if (msg.type === "assistant" && msg.message) {
             for (const block of msg.message.content) {
               if (block.type === "text") {
@@ -1712,6 +1773,13 @@ function createGeminiBackendExecutor(options) {
     defaultModel: options.model ?? exports.DEFAULT_MODELS.gemini
   });
   return async function* (prompt, queryOptions) {
+    if (typeof prompt !== "string") {
+      yield {
+        type: "error",
+        error: "Gemini backend does not support streaming prompt inputs."
+      };
+      return;
+    }
     const geminiOptions = mapClaudeOptionsToGemini(queryOptions);
     if (queryOptions.signal) {
       geminiOptions.signal = queryOptions.signal;
@@ -1876,6 +1944,11 @@ var init_sandbox_logger = __esm({
     };
   }
 });
+function getClaudeSdkOverrides(config) {
+  const raw = config?.claudeSdkOptions;
+  if (!raw || typeof raw !== "object") return void 0;
+  return raw;
+}
 exports.AgentHarness = void 0;
 var init_harness = __esm({
   "src/agent/harness.ts"() {
@@ -2132,6 +2205,7 @@ var init_harness = __esm({
             yield sessionStartEvent;
             yield* yieldQueuedLogs();
             const assistantContent = [];
+            let structuredOutput;
             let wasAborted = false;
             try {
               logger3.info("execution", "Starting Claude Agent SDK query");
@@ -2222,6 +2296,10 @@ var init_harness = __esm({
                   };
                   writeEvent?.(toolResultEvent);
                   yield toolResultEvent;
+                } else if (event.type === "complete") {
+                  if (event.structured_output !== void 0) {
+                    structuredOutput = event.structured_output;
+                  }
                 }
               }
               if (wasAborted || controller.signal.aborted) {
@@ -2273,7 +2351,8 @@ var init_harness = __esm({
                   [
                     {
                       role: "assistant",
-                      content: assistantContent
+                      content: assistantContent,
+                      ...structuredOutput !== void 0 ? { metadata: { structured_output: structuredOutput } } : {}
                     }
                   ]
                 );
@@ -2394,11 +2473,15 @@ var init_harness = __esm({
       async *executeAgentQuery(session, prompt, options, signal, _logger) {
         const sessionEnvVars = session.metadata?.envVars;
         const sessionStartupScript = session.metadata?.startupScript;
+        const sdkOverrides = getClaudeSdkOverrides(this.config.config);
         const mergedEnvVars = {
           MAX_THINKING_TOKENS: "1024",
           ...this.config.envVars,
           ...sessionEnvVars
         };
+        if (sdkOverrides?.enableFileCheckpointing) {
+          mergedEnvVars.CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING = "1";
+        }
         const hasEnvVars = Object.keys(mergedEnvVars).length > 0;
         const startupScript = sessionStartupScript ?? this.config.startupScript;
         const queryOptions = {
@@ -2407,7 +2490,9 @@ var init_harness = __esm({
           disallowedTools: this.config.disallowedTools,
           permissionMode: this.config.permissionMode,
           maxTurns: this.config.maxTurns,
+          outputFormat: options.outputFormat,
           mcpServers: this.config.mcpServers,
+          settingSources: this.config.settingSources ?? ["project"],
           // Pass the harness session ID for sandbox caching
           harnessSessionId: session.id,
           // Pass environment and startup configuration
@@ -2416,6 +2501,17 @@ var init_harness = __esm({
           // Pass config file URL for cloud-hosted .claude directory (downloaded in sandbox)
           ...this.config.configFileUrl && { configFileUrl: this.config.configFileUrl }
         };
+        if (sdkOverrides) {
+          if (sdkOverrides.hooks) queryOptions.hooks = sdkOverrides.hooks;
+          if (typeof sdkOverrides.enableFileCheckpointing === "boolean") {
+            queryOptions.enableFileCheckpointing = sdkOverrides.enableFileCheckpointing;
+            if (sdkOverrides.enableFileCheckpointing && !sdkOverrides.extraArgs) {
+              queryOptions.extraArgs = { "replay-user-messages": null };
+            }
+          }
+          if (sdkOverrides.extraArgs) queryOptions.extraArgs = sdkOverrides.extraArgs;
+          if (sdkOverrides.permissionMode) queryOptions.permissionMode = sdkOverrides.permissionMode;
+        }
         const sessionApiKey = this.sessionApiKeys.get(session.id);
         if (sessionApiKey) {
           queryOptions.apiKey = sessionApiKey;
@@ -2451,7 +2547,9 @@ ${prompt}`;
         const skillsDir = this.sessionSkillDirs.get(session.id);
         if (skillsDir) {
           queryOptions.cwd = skillsDir;
-          queryOptions.settingSources = ["project"];
+          if (queryOptions.settingSources === void 0) {
+            queryOptions.settingSources = ["project"];
+          }
           if (queryOptions.allowedTools && !queryOptions.allowedTools.includes("Skill")) {
             queryOptions.allowedTools = [...queryOptions.allowedTools, "Skill"];
           }
@@ -2480,6 +2578,7 @@ ${prompt}`;
             await this.sessionManager.updateSession(session.id, {
               sdkSessionId: event.sessionId
             });
+            yield { type: "session_init", sessionId: event.sessionId, slashCommands: event.slashCommands };
           } else if (event.type === "text_delta" && event.delta) {
             yield { type: "text_delta", delta: event.delta };
           } else if (event.type === "thinking_delta" && event.delta) {
@@ -2500,6 +2599,11 @@ ${prompt}`;
               content: event.content,
               isError: event.isError
             };
+          } else if (event.type === "complete") {
+            yield {
+              type: "complete",
+              structured_output: event.structured_output
+            };
           } else if (event.type === "error") {
             throw new Error(event.error ?? "Unknown error from Claude SDK");
           }
@@ -4639,6 +4743,14 @@ echo "[warmup] Warmup complete!"
       lastMaintenanceAt = null;
       metricsCallback;
       startPromise = null;
+      /** Registered warmup specs by tag (e.g. agentId -> spec) */
+      warmupSpecs = /* @__PURE__ */ new Map();
+      /** Tags currently being warmed (prevents duplicate warming of same spec) */
+      warmingTags = /* @__PURE__ */ new Set();
+      /** Max warmup specs to keep (LRU eviction above this) */
+      static MAX_SPECS = 10;
+      /** Timeout for spec setup in ms (prevents hanging S3 pulls / install.sh) */
+      static SPEC_SETUP_TIMEOUT_MS = 12e4;
       /** Consecutive warmup failure count (reset on success) */
       consecutiveFailures = 0;
       /** Timestamp of last warmup attempt — used for backoff */
@@ -4651,7 +4763,7 @@ echo "[warmup] Warmup complete!"
         this.config = {
           minPoolSize: config.minPoolSize ?? parseInt(process.env.SANDBOX_POOL_MIN_SIZE ?? "2"),
           maxPoolSize: config.maxPoolSize ?? parseInt(process.env.SANDBOX_POOL_MAX_SIZE ?? "5"),
-          sandboxTimeout: config.sandboxTimeout ?? parseInt(process.env.SANDBOX_TIMEOUT ?? "900"),
+          sandboxTimeout: config.sandboxTimeout ?? parseInt(process.env.SANDBOX_TIMEOUT ?? "300"),
           expiryThresholdMs: config.expiryThresholdMs ?? parseInt(process.env.SANDBOX_EXPIRY_THRESHOLD_MS ?? "120000"),
           maintenanceIntervalMs: config.maintenanceIntervalMs ?? parseInt(process.env.SANDBOX_POOL_MAINTENANCE_MS ?? "30000"),
           runtime: config.runtime ?? "node22",
@@ -4695,11 +4807,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) => {
@@ -4743,9 +4857,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");
         }
@@ -4755,26 +4871,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;
       }
@@ -4805,11 +4929,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++;
           }
@@ -4824,6 +4951,8 @@ echo "[warmup] Warmup complete!"
           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,
@@ -4838,13 +4967,61 @@ 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 and configHash already exists, only updates priority (skip #7).
+       * Evicts lowest-priority specs when exceeding MAX_SPECS (fix #2).
+       * Triggers replenishment to warm a sandbox for this spec.
+       */
+      registerWarmupSpec(spec) {
+        const existing = this.warmupSpecs.get(spec.tag);
+        if (existing && spec.configHash && existing.configHash === spec.configHash) {
+          existing.priority = spec.priority;
+          return;
+        }
+        const isNew = !existing;
+        this.warmupSpecs.set(spec.tag, spec);
+        if (this.warmupSpecs.size > _SandboxPool.MAX_SPECS) {
+          this.evictLowestPrioritySpecs();
+        }
+        console.log(`[POOL] ${isNew ? "Registered" : "Updated"} warmup spec: ${spec.tag} (priority=${spec.priority}, specs=${this.warmupSpecs.size})`);
+        this.emitMetric("spec_registered", {
+          tag: spec.tag,
+          priority: spec.priority,
+          isNew,
+          totalSpecs: this.warmupSpecs.size,
+          configHash: spec.configHash
+        });
+        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 });
@@ -4938,6 +5115,60 @@ echo "[warmup] Warmup complete!"
               throw new Error(`Warmup failed: ${stderr}`);
             }
           }
+          let warmupTag;
+          let agentSetupComplete = false;
+          let warmupInstallRan = false;
+          let warmupStartupRan = false;
+          if (spec) {
+            this.warmingTags.add(spec.tag);
+            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 {
+              const setupResult = await new Promise((resolve3, reject) => {
+                const timer = setTimeout(
+                  () => reject(new Error(`Spec setup timed out after ${_SandboxPool.SPEC_SETUP_TIMEOUT_MS / 1e3}s`)),
+                  _SandboxPool.SPEC_SETUP_TIMEOUT_MS
+                );
+                spec.setup(sandbox).then((result) => {
+                  clearTimeout(timer);
+                  resolve3(result);
+                }).catch((error) => {
+                  clearTimeout(timer);
+                  reject(error);
+                });
+              });
+              warmupTag = spec.tag;
+              agentSetupComplete = true;
+              if (setupResult && typeof setupResult === "object") {
+                warmupInstallRan = setupResult.installRan === true;
+                warmupStartupRan = setupResult.startupRan === true;
+              }
+              const specDuration = Date.now() - specStartTime;
+              console.log(`[POOL] Spec setup completed for tag=${spec.tag} on sandbox ${sandbox.sandboxId} (${specDuration}ms, install=${warmupInstallRan}, startup=${warmupStartupRan})`);
+              this.emitMetric("spec_setup_completed", {
+                tag: spec.tag,
+                sandboxId: sandbox.sandboxId,
+                durationMs: specDuration,
+                warmupInstallRan,
+                warmupStartupRan
+              });
+            } 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
+              });
+            } finally {
+              this.warmingTags.delete(spec.tag);
+            }
+          }
           const warmupTime = Date.now() - startTime;
           const now = Date.now();
           const pooled = {
@@ -4947,14 +5178,21 @@ echo "[warmup] Warmup complete!"
             expiresAt: now + this.config.sandboxTimeout * 1e3,
             sdkInstalled: true,
             eligible: true,
-            lastHeartbeat: now
+            lastHeartbeat: now,
+            warmupTag,
+            agentSetupComplete,
+            warmupInstallRan,
+            warmupStartupRan
           };
-          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;
@@ -5035,18 +5273,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
@@ -5113,13 +5362,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);
             })
@@ -5130,6 +5382,65 @@ echo "[warmup] Warmup complete!"
         }
         await Promise.all(promises);
       }
+      /**
+       * Decide which specs to apply to new sandboxes during replenishment.
+       * Strategy:
+       * - Always reserve at least 1 slot for generic (fix #3)
+       * - Cover uncovered specs first (highest priority), skipping in-flight tags (fix #4)
+       * - 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 || needed === 0) {
+          return new Array(needed).fill(void 0);
+        }
+        const maxTaggedSlots = Math.max(0, needed - 1);
+        const uncoveredSpecs = [];
+        for (const spec of this.warmupSpecs.values()) {
+          if (this.warmingTags.has(spec.tag)) continue;
+          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 >= maxTaggedSlots) break;
+          assignments.push(spec);
+        }
+        while (assignments.length < needed) {
+          assignments.push(void 0);
+        }
+        return assignments;
+      }
+      /**
+       * Evict lowest-priority specs when over MAX_SPECS capacity (fix #2).
+       */
+      evictLowestPrioritySpecs() {
+        while (this.warmupSpecs.size > _SandboxPool.MAX_SPECS) {
+          let lowestTag;
+          let lowestPriority = Infinity;
+          for (const [tag, spec] of this.warmupSpecs.entries()) {
+            if (spec.priority < lowestPriority) {
+              lowestPriority = spec.priority;
+              lowestTag = tag;
+            }
+          }
+          if (lowestTag) {
+            this.warmupSpecs.delete(lowestTag);
+            console.log(`[POOL] Evicted warmup spec: ${lowestTag} (priority=${lowestPriority}, specs=${this.warmupSpecs.size})`);
+          } else {
+            break;
+          }
+        }
+      }
       /**
        * Destroy a sandbox and clean up
        */
@@ -5361,7 +5672,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');
@@ -5378,6 +5689,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
@@ -5386,41 +5699,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 {
@@ -5441,7 +5719,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 {
@@ -5453,13 +5733,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(
@@ -5469,6 +5753,51 @@ 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 installDone = pooled.warmupInstallRan === true;
+      const startupDone = pooled.warmupStartupRan === true;
+      const agentSetupDone = pooled.agentSetupComplete === true;
+      const now2 = Date.now();
+      const entry2 = {
+        sandbox: pooled.sandbox,
+        sessionId,
+        createdAt: pooled.createdAt,
+        lastUsedAt: now2,
+        sdkInstalled: pooled.sdkInstalled,
+        startupScriptRan: startupDone,
+        installScriptRan: installDone
+      };
+      sandboxCache.set(sessionId, entry2);
+      return {
+        sandbox: pooled.sandbox,
+        sandboxId: pooled.sandboxId,
+        sdkInstalled: pooled.sdkInstalled,
+        startupScriptRan: startupDone,
+        startupScriptHash: void 0,
+        installScriptRan: installDone,
+        installScriptHash: void 0,
+        isNew: false,
+        // Not new - came from pool
+        configFileUrl: void 0,
+        configInstalledAt: agentSetupDone ? now2 : void 0,
+        warmupTag: pooled.warmupTag,
+        agentSetupComplete: pooled.agentSetupComplete,
+        warmupInstallRan: pooled.warmupInstallRan,
+        warmupStartupRan: pooled.warmupStartupRan
+      };
+    } 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;
@@ -5502,7 +5831,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 {
@@ -5512,6 +5842,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
@@ -5551,6 +5883,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;
@@ -5618,6 +5958,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
@@ -5792,6 +6134,13 @@ function createVercelSandboxExecutor(apiKey) {
   };
 }
 async function* executeInSandbox(prompt, apiKey, options) {
+  if (typeof prompt !== "string") {
+    yield {
+      type: "error",
+      error: "Vercel sandbox executor does not support streaming prompt inputs."
+    };
+    return;
+  }
   const sessionId = options.harnessSessionId || `temp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
   try {
     const { sandbox, sdkInstalled, startupScriptRan, startupScriptHash: cachedScriptHash, configFileUrl: cachedConfigUrl } = await getOrCreateSandbox({
@@ -5933,9 +6282,13 @@ async function* executeInSandbox(prompt, apiKey, options) {
       permissionMode: options.permissionMode || "bypassPermissions",
       includePartialMessages: true
     };
+    if (options.settingSources !== void 0) {
+      sdkOptions.settingSources = options.settingSources;
+    } else {
+      sdkOptions.settingSources = ["project"];
+    }
     const hasConfig = options.configFileUrl || cachedConfigUrl;
     if (hasConfig) {
-      sdkOptions.settingSources = ["project"];
       if (options.allowedTools && options.allowedTools.length > 0) {
         const allowedTools = [...options.allowedTools];
         if (!allowedTools.includes("Skill")) {
@@ -5971,12 +6324,47 @@ async function* executeInSandbox(prompt, apiKey, options) {
     if (options.resume) {
       sdkOptions.resume = options.resume;
     }
+    try {
+      const pluginFindResult = await sandbox.runCommand({
+        cmd: "bash",
+        args: [
+          "-c",
+          [
+            'for base in ".claude/plugins" "$HOME/.claude/plugins"; do',
+            '  if [ -d "$base" ]; then',
+            '    find "$base" -type f -path "*/.claude-plugin/plugin.json" -print',
+            "  fi",
+            "done | sed 's#/.claude-plugin/plugin.json$##'"
+          ].join("\n")
+        ]
+      });
+      const rawPluginRoots = (await pluginFindResult.stdout()).trim();
+      const pluginRoots = rawPluginRoots ? rawPluginRoots.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+      const uniquePluginRoots = Array.from(new Set(pluginRoots));
+      if (uniquePluginRoots.length > 0) {
+        sdkOptions.plugins = uniquePluginRoots.map((path15) => ({ type: "local", path: path15 }));
+        console.log("[SANDBOX] Plugins detected:", uniquePluginRoots);
+      }
+    } catch (pluginError) {
+      console.warn("[SANDBOX] Failed to detect plugins:", pluginError);
+    }
     const agentScript = `
 const { query } = require('@anthropic-ai/claude-agent-sdk');
+const fs = require('fs');
 
 const prompt = ${JSON.stringify(prompt)};
 const options = ${JSON.stringify(sdkOptions)};
 
+// Enable subagents if .claude/agents exists (requires Task tool)
+if (fs.existsSync('.claude/agents')) {
+  if (!Array.isArray(options.allowedTools)) {
+    options.allowedTools = [];
+  }
+  if (!options.allowedTools.includes('Task')) {
+    options.allowedTools.push('Task');
+  }
+}
+
 let queryCompleted = false;
 
 async function run() {
@@ -6073,7 +6461,11 @@ SCRIPT_EOF`]
           });
         }
         if (event.type === "system" && event.subtype === "init") {
-          events.push({ type: "session_init", sessionId: event.session_id || "" });
+          events.push({
+            type: "session_init",
+            sessionId: event.session_id || "",
+            slashCommands: event.slash_commands
+          });
         } else if (event.type === "stream_event" && event.event) {
           const streamEvent = event.event;
           if (streamEvent.type === "content_block_delta") {
@@ -6108,12 +6500,16 @@ SCRIPT_EOF`]
             }
           }
         } else if (event.type === "result") {
+          const usage = event.usage;
+          const hasUsageTokens = !!usage && (usage.input_tokens !== void 0 || usage.output_tokens !== void 0);
+          const totalTokens = hasUsageTokens ? (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0) : event.total_tokens ?? (event.tokens ? event.tokens.input + event.tokens.output : void 0);
+          const totalCost = usage?.total_cost_usd ?? event.total_cost_usd ?? event.cost ?? event.total_cost;
           events.push({
             type: "complete",
             sessionId: event.session_id,
             result: event.result,
-            totalCost: event.total_cost_usd,
-            totalTokens: event.total_tokens
+            totalCost,
+            totalTokens
           });
         }
         return events;
@@ -12692,6 +13088,7 @@ __export(schemas_exports, {
   RunAgentRequestSchema: () => RunAgentRequestSchema,
   SendMessageRequestSchema: () => SendMessageRequestSchema,
   SessionEndEventSchema: () => SessionEndEventSchema,
+  SessionInitEventSchema: () => SessionInitEventSchema,
   SessionSchema: () => SessionSchema,
   SessionStartEventSchema: () => SessionStartEventSchema,
   SessionStatusSchema: () => SessionStatusSchema,
@@ -12711,7 +13108,7 @@ __export(schemas_exports, {
   TurnCompleteEventSchema: () => TurnCompleteEventSchema,
   UpdateAgentRequestSchema: () => UpdateAgentRequestSchema
 });
-var ErrorResponseSchema, SuccessResponseSchema, PaginationQuerySchema, OrderQuerySchema, TextContentSchema, ToolUseContentSchema, ToolResultContentSchema, ImageContentSchema, FileContentSchema, MessageContentSchema, MessageSchema, PaginatedMessagesSchema, SessionStatusSchema, SessionSchema, PaginatedSessionsSchema, CreateSessionRequestSchema, SendMessageRequestSchema, ResumeSessionRequestSchema, ListSessionsQuerySchema, AgentStatusSchema, PermissionModeSchema, McpServerConfigSchema, StoredAgentSchema, SimpleAgentSchema, PaginatedAgentsSchema, CreateAgentRequestSchema, UpdateAgentRequestSchema, RunAgentRequestSchema, ListAgentsQuerySchema, GitHubSkillSourceSchema, LocalSkillSourceSchema, SkillSourceSchema, BrowseSkillsRequestSchema, ReadSkillFileRequestSchema, FileEntrySchema, BrowseSkillsResponseSchema, SkillFileContentSchema, ReadSkillFileResponseSchema, SessionStartEventSchema, TextDeltaEventSchema, ThinkingDeltaEventSchema, MessageEventSchema, ToolUseEventSchema, ToolResultEventSchema, SessionEndEventSchema, TurnCompleteEventSchema, StreamErrorEventSchema, HealthResponseSchema;
+var ErrorResponseSchema, SuccessResponseSchema, PaginationQuerySchema, OrderQuerySchema, TextContentSchema, ToolUseContentSchema, ToolResultContentSchema, ImageContentSchema, FileContentSchema, MessageContentSchema, MessageSchema, PaginatedMessagesSchema, SessionStatusSchema, SessionSchema, PaginatedSessionsSchema, CreateSessionRequestSchema, SendMessageRequestSchema, ResumeSessionRequestSchema, ListSessionsQuerySchema, AgentStatusSchema, PermissionModeSchema, McpServerConfigSchema, StoredAgentSchema, SimpleAgentSchema, PaginatedAgentsSchema, CreateAgentRequestSchema, UpdateAgentRequestSchema, RunAgentRequestSchema, ListAgentsQuerySchema, GitHubSkillSourceSchema, LocalSkillSourceSchema, SkillSourceSchema, BrowseSkillsRequestSchema, ReadSkillFileRequestSchema, FileEntrySchema, BrowseSkillsResponseSchema, SkillFileContentSchema, ReadSkillFileResponseSchema, SessionStartEventSchema, SessionInitEventSchema, TextDeltaEventSchema, ThinkingDeltaEventSchema, MessageEventSchema, ToolUseEventSchema, ToolResultEventSchema, SessionEndEventSchema, TurnCompleteEventSchema, StreamErrorEventSchema, HealthResponseSchema;
 var init_schemas = __esm({
   "src/server/openapi/schemas.ts"() {
     init_dist3();
@@ -12937,6 +13334,15 @@ var init_schemas = __esm({
       sessionId: zod.z.string().openapi({ description: "Session ID" }),
       claudeSessionId: zod.z.string().openapi({ description: "Claude SDK session ID" })
     }).openapi("SessionStartEvent");
+    SessionInitEventSchema = zod.z.object({
+      type: zod.z.literal("session_init"),
+      sessionId: zod.z.string().openapi({ description: "Claude SDK session ID" }),
+      slashCommands: zod.z.array(zod.z.object({
+        name: zod.z.string().openapi({ description: "Slash command name" }),
+        description: zod.z.string().optional().openapi({ description: "Slash command description" }),
+        prompt: zod.z.string().optional().openapi({ description: "Slash command prompt" })
+      })).optional().openapi({ description: "Slash commands advertised by the SDK" })
+    }).openapi("SessionInitEvent");
     TextDeltaEventSchema = zod.z.object({
       type: zod.z.literal("text_delta"),
       delta: zod.z.string().openapi({ description: "Text chunk", example: "Hello" })
@@ -13263,6 +13669,7 @@ var init_sessions2 = __esm({
 The stream emits the following event types:
 
 - \`session_start\` - Session started, includes sessionId and sdkSessionId
+- \`session_init\` - Claude SDK session initialized (includes slash commands)
 - \`text_delta\` - Text chunk being generated
 - \`thinking_delta\` - Thinking/reasoning text chunk
 - \`message\` - Complete message saved to storage
@@ -13711,6 +14118,7 @@ This is a convenience endpoint that combines session creation and message sendin
 The stream emits the following event types:
 
 - \`session_start\` - Session started
+- \`session_init\` - Claude SDK session initialized (includes slash commands)
 - \`text_delta\` - Text chunk being generated
 - \`thinking_delta\` - Thinking/reasoning text chunk
 - \`message\` - Complete message saved
@@ -19986,6 +20394,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;