agentbox-sdk 0.1.319 → 0.1.323

package/dist/agents/index.d.ts

@@ -1,5 +1,5 @@
-import { o as AgentProviderName, h as AgentOptions, t as AgentRunConfig, s as AgentRun, r as AgentResult, a3 as RawAgentEvent, b as AgentAttachRequest, y as AttachedRun, aa as SetupLayout } from '../types-DG4J_zMT.js';
-export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, z as ClaudeCodeHookConfig, B as ClaudeCodeHookEvent, D as ClaudeCodeHookHandler, E as ClaudeCodeHookMatcherGroup, F as ClaudeCodeHooksConfig, G as ClaudeCodeProviderOptions, H as CodexAgentOptions, I as CodexCommandHook, J as CodexHookEvent, K as CodexHookMatcherGroup, L as CodexHooksConfig, M as CodexProviderOptions, N as DataContent, O as EmbeddedSkillConfig, P as FilePart, Q as ImagePart, X as OpenCodeAgentOptions, Y as OpenCodePluginConfig, Z as OpenCodePluginEvent, _ as OpenCodePluginHookConfig, $ as OpenCodeProviderOptions, a0 as OpenRouterPlugin, a5 as RepoSkillConfig, ac as TextPart, ag as UserContent, ah as UserContentPart } from '../types-DG4J_zMT.js';
+import { o as AgentProviderName, h as AgentOptions, t as AgentRunConfig, s as AgentRun, r as AgentResult, a3 as RawAgentEvent, b as AgentAttachRequest, y as AttachedRun, aa as SetupLayout } from '../types-t01PuLUJ.js';
+export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, z as ClaudeCodeHookConfig, B as ClaudeCodeHookEvent, D as ClaudeCodeHookHandler, E as ClaudeCodeHookMatcherGroup, F as ClaudeCodeHooksConfig, G as ClaudeCodeProviderOptions, H as CodexAgentOptions, I as CodexCommandHook, J as CodexHookEvent, K as CodexHookMatcherGroup, L as CodexHooksConfig, M as CodexProviderOptions, N as DataContent, O as EmbeddedSkillConfig, P as FilePart, Q as ImagePart, X as OpenCodeAgentOptions, Y as OpenCodePluginConfig, Z as OpenCodePluginEvent, _ as OpenCodePluginHookConfig, $ as OpenCodeProviderOptions, a0 as OpenRouterPlugin, a5 as RepoSkillConfig, ac as TextPart, ag as UserContent, ah as UserContentPart } from '../types-t01PuLUJ.js';
 import { S as Sandbox } from '../Sandbox-DcKAU-E3.js';
 export { AgentProvider } from '../enums.js';
 import 'e2b';
@@ -42,6 +42,23 @@ declare class Agent<P extends AgentProviderName = AgentProviderName> {
      * work.
      */
     setup(): Promise<void>;
+    /**
+     * Stop the long-lived provider CLI server booted by {@link Agent.setup}
+     * (claude-code relay daemon, codex app-server, opencode `serve`).
+     *
+     * agentbox NEVER kills a running server on its own — not on run
+     * completion, not on `abort()`, and not when {@link Agent.setup} detects
+     * a changed config/credential set. This method is the single, explicit,
+     * developer-driven teardown. Call it to free a server's resources, or to
+     * apply a changed config: after `killServer()` the next {@link setup}
+     * cold-starts a fresh server with the new configuration.
+     *
+     * Best-effort and idempotent: a no-op when no server is running, or when
+     * the provider has no shared server for the current mode (host-mode
+     * claude-code runs the SDK in-process; local codex spawns a fresh
+     * app-server per run, torn down with the run).
+     */
+    killServer(): Promise<void>;
     stream(runConfig: AgentRunConfig): AgentRun;
     run(runConfig: AgentRunConfig): Promise<AgentResult>;
     rawEvents(runConfig: AgentRunConfig): AsyncIterable<RawAgentEvent>;

package/dist/agents/index.js

@@ -2,7 +2,7 @@ import {
   Agent,
   agentboxRoot,
   getAgentLayout
-} from "../chunk-2IHQY3WC.js";
+} from "../chunk-XONT46YC.js";
 import "../chunk-775FIGGL.js";
 import {
   AGENT_RESERVED_PORTS,

package/dist/{chunk-HYHLKO3L.js → chunk-TUBBWIOM.js}

@@ -251,9 +251,33 @@ function resolveSandboxResources(resources) {
 }
 
 // src/sandboxes/providers/daytona.ts
+var STARTABLE_STATES = /* @__PURE__ */ new Set(["stopped", "archived"]);
+var TERMINAL_STATES = /* @__PURE__ */ new Set([
+  "error",
+  "build_failed",
+  "destroyed",
+  "destroying"
+]);
+var ATTACH_SETTLE_TIMEOUT_MS = 12e4;
+var ATTACH_POLL_INTERVAL_MS = 2e3;
+function isStateChangeInProgressError(err) {
+  const e = err;
+  if (!e) return false;
+  return e.statusCode === 409 || e.name === "DaytonaConflictError" || /state change in progress/i.test(e.message ?? "");
+}
 var DaytonaSandboxAdapter = class extends SandboxAdapter {
   client;
   sandbox;
+  /**
+   * Per-sandbox preview access token, captured from `getPreviewLink`.
+   * Daytona's preview proxy now requires this token to reach a sandbox's
+   * ports: unauthenticated requests get 307-redirected to an Auth0 login
+   * (which surfaces as a 307 on WebSocket upgrades and a 404 on plain GETs).
+   * The token is sandbox-level and stable across ports, so caching the most
+   * recent one is sufficient — every consumer calls `getPreviewLink` to build
+   * the URL right before reading `previewHeaders`. See {@link previewHeaders}.
+   */
+  previewToken;
   constructor(options) {
     super(options);
     this.client = new Daytona({
@@ -282,20 +306,54 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
       throw new Error(`Daytona sandbox ${id} not found`);
     }
     this.sandbox = existing;
-    const state = existing.state ?? "unknown";
-    const isWarm = state === "started";
-    if (!isWarm) {
-      await existing.start();
+    this.isWarmFlag = existing.state === "started";
+    await this.ensureStarted(existing);
+  }
+  /**
+   * Bring a sandbox to the `started` state, tolerating in-flight transitions.
+   *
+   * `start()` only works from a resting state (`stopped`/`archived`); calling
+   * it while the sandbox is creating/starting/restoring/snapshotting/etc. — or
+   * racing another caller that's already starting it — makes Daytona 409 with
+   * "Sandbox state change in progress". So we poll: start from a resting
+   * state, wait out a transition, fail fast on a terminal state, and treat a
+   * 409 as "someone else is mid-transition" and keep waiting.
+   */
+  async ensureStarted(sandbox) {
+    let current = sandbox;
+    const deadline = Date.now() + ATTACH_SETTLE_TIMEOUT_MS;
+    for (; ; ) {
+      const state = current.state ?? "unknown";
+      if (state === "started") return;
+      if (TERMINAL_STATES.has(state)) {
+        throw new Error(
+          `Daytona sandbox ${current.id} is in a terminal state: ${state}`
+        );
+      }
+      if (STARTABLE_STATES.has(state)) {
+        try {
+          await current.start();
+          return;
+        } catch (err) {
+          if (!isStateChangeInProgressError(err)) throw err;
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for Daytona sandbox ${current.id} to start (state=${state})`
+        );
+      }
+      await sleep(ATTACH_POLL_INTERVAL_MS);
+      current = await this.client.get(current.id);
+      this.sandbox = current;
     }
-    this.isWarmFlag = isWarm;
   }
   async provision() {
     const existing = await this.findMatchingSandbox();
     if (existing) {
       this.sandbox = existing;
-      const isWarm = existing.state === "started";
-      await existing.start();
-      this.isWarmFlag = isWarm;
+      this.isWarmFlag = existing.state === "started";
+      await this.ensureStarted(existing);
       return;
     }
     const labels = this.getLabels();
@@ -494,12 +552,26 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
   }
   async openPort(port) {
     this.requireProvisioned();
-    await this.requireSandbox().getPreviewLink(port);
+    const preview = await this.requireSandbox().getPreviewLink(port);
+    this.previewToken = preview.token;
+  }
+  /**
+   * Headers callers must attach to HTTP/WebSocket requests against this
+   * sandbox's preview URLs. Daytona private sandboxes gate their preview
+   * proxy behind `x-daytona-preview-token`; without it the proxy 307-redirects
+   * to Auth0, which breaks every provider (claude-code `/start` 404, codex WS
+   * "307", opencode `/session` 404). The token is captured lazily from
+   * `getPreviewLink`/`openPort`, both of which every consumer calls to build
+   * the URL immediately before reading these headers.
+   */
+  get previewHeaders() {
+    return this.previewToken ? { "x-daytona-preview-token": this.previewToken } : {};
   }
   async getPreviewLink(port) {
     this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const preview = await sandbox.getPreviewLink(port);
+    this.previewToken = preview.token;
     return preview.url;
   }
   async uploadFile(content, targetPath) {

package/dist/{chunk-2IHQY3WC.js → chunk-XONT46YC.js}

@@ -1244,16 +1244,23 @@ async function preflightSetup(target, setupId, daemon) {
   );
 }
 async function markSetupComplete(target, setupId) {
-  await time(
-    debugSetup,
-    `markSetupComplete ${target.provider}`,
-    () => target.runCommand(
-      [
-        `mkdir -p ${shellQuote(target.layout.rootDir)}`,
-        `printf '%s' ${shellQuote(setupId)} > ${shellQuote(path5.posix.join(target.layout.rootDir, SETUP_ID_FILENAME))}`
-      ].join(" && ")
-    )
-  );
+  await time(debugSetup, `markSetupComplete ${target.provider}`, async () => {
+    const setupIdFile = path5.posix.join(
+      target.layout.rootDir,
+      SETUP_ID_FILENAME
+    );
+    const result = await target.uploadAndRun(
+      [{ path: setupIdFile, content: setupId }],
+      "true"
+    );
+    if (result.exitCode !== 0) {
+      const detail = result.combinedOutput?.trim();
+      throw new Error(
+        `markSetupComplete failed (${result.exitCode})${detail ? `
+${detail}` : ""}`
+      );
+    }
+  });
 }
 function buildInstallScript(rootDir, installCommandsByKey) {
   const commandsB64 = Buffer.from(
@@ -1641,6 +1648,8 @@ var DAEMON_PORT = 43180;
 var DAEMON_PATH = "/tmp/agentbox/claude-code/daemon.mjs";
 var DAEMON_LOG_PATH = "/tmp/agentbox/claude-code/daemon.log";
 var DAEMON_PID_PATH = "/tmp/agentbox/claude-code/daemon.pid";
+var DAEMON_READY_TIMEOUT_MS = 3e4;
+var DAEMON_READY_POLL_INTERVAL_MS = 250;
 function claudeConfigDir(options) {
   return path8.join(
     agentboxRoot(AgentProvider.ClaudeCode, Boolean(options.sandbox)),
@@ -2078,16 +2087,44 @@ async function ensureClaudeCodeDaemonUncached(options, env) {
         `Could not start claude-code daemon: ${launch.stderr || launch.combinedOutput || "(no output)"}`
       );
     }
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let lastProbe = "";
+    while (Date.now() < deadline) {
+      const ready = await sandbox.run(
+        `curl -fsS --max-time 1 http://127.0.0.1:${DAEMON_PORT}/__version 2>/dev/null`,
+        { cwd: options.cwd, timeoutMs: 1e4 }
+      );
+      lastProbe = ready.combinedOutput.trim();
+      if (ready.exitCode === 0 && lastProbe === DAEMON_PROTOCOL_VERSION) {
+        return;
+      }
+      await sleep(DAEMON_READY_POLL_INTERVAL_MS);
+    }
+    const logTail = await sandbox.run(`tail -n 20 ${shellQuote(DAEMON_LOG_PATH)} 2>/dev/null`, {
+      cwd: options.cwd
+    }).catch(() => void 0);
+    throw new Error(
+      `claude-code daemon did not become ready within ${DAEMON_READY_TIMEOUT_MS}ms` + (lastProbe ? ` (last /__version response: ${lastProbe})` : "") + (logTail?.combinedOutput ? `
+${logTail.combinedOutput}` : "")
+    );
   });
 }
 var DAEMON_FIRST_REQUEST_RETRY_BUDGET_MS = 3e4;
 var DAEMON_FIRST_REQUEST_RETRY_INTERVAL_MS = 250;
+var TRANSIENT_PROXY_STATUSES = /* @__PURE__ */ new Set([404, 502, 503, 504]);
 async function fetchWithDaemonRetry(input, init) {
   const deadline = Date.now() + DAEMON_FIRST_REQUEST_RETRY_BUDGET_MS;
   let lastError;
+  let lastResponse;
   while (Date.now() < deadline) {
     try {
-      return await fetch(input, init);
+      const response = await fetch(input, init);
+      if (TRANSIENT_PROXY_STATUSES.has(response.status)) {
+        lastResponse = response;
+        await sleep(DAEMON_FIRST_REQUEST_RETRY_INTERVAL_MS);
+        continue;
+      }
+      return response;
     } catch (error) {
       lastError = error;
       const aborted = error?.name === "AbortError";
@@ -2097,6 +2134,9 @@ async function fetchWithDaemonRetry(input, init) {
       await sleep(DAEMON_FIRST_REQUEST_RETRY_INTERVAL_MS);
     }
   }
+  if (lastResponse) {
+    return lastResponse;
+  }
   throw lastError ?? new Error("claude-code daemon request timed out");
 }
 async function* parseNdjsonStream(body) {
@@ -2141,6 +2181,24 @@ var ClaudeCodeAgentAdapter = class {
    * match what we'd produce, we skip the artifact upload AND the daemon
    * boot entirely.
    */
+  /**
+   * Explicit, developer-invoked teardown of the in-sandbox claude-code
+   * relay daemon (see {@link AgentProviderAdapter.killServer}). agentbox
+   * never calls this on its own. Best-effort and idempotent: a no-op when
+   * the daemon isn't running or no sandbox is configured. After it returns
+   * the next `setup()` re-spawns the daemon (its `/__version` probe fails).
+   */
+  async killServer(request) {
+    const sandbox = request.options.sandbox;
+    if (!sandbox) return;
+    await sandbox.run(
+      [
+        `if [ -f ${shellQuote(DAEMON_PID_PATH)} ]; then kill -TERM "$(cat ${shellQuote(DAEMON_PID_PATH)})" 2>/dev/null || true; rm -f ${shellQuote(DAEMON_PID_PATH)}; fi`,
+        `fuser -k -n tcp ${DAEMON_PORT} 2>/dev/null || true`
+      ].join("; "),
+      { cwd: request.options.cwd, timeoutMs: 1e4 }
+    ).catch(() => void 0);
+  }
   async setup(request) {
     await time(debugClaude, "claude-code setup()", async () => {
       const options = request.options;
@@ -3533,10 +3591,34 @@ async function buildCodexInputItems(options, inputParts) {
   );
   return inputItems;
 }
+async function killCodexAppServer(request) {
+  const { options } = request;
+  const sandbox = options.sandbox;
+  if (!sandbox) return;
+  const sharedTarget = await createSetupTarget(
+    request.provider,
+    REMOTE_CODEX_APP_SERVER_ID,
+    options
+  );
+  const pidFilePath = path9.posix.join(
+    sharedTarget.layout.rootDir,
+    "codex-app-server.pid"
+  );
+  await sandbox.run(
+    [
+      `if [ -f ${shellQuote(pidFilePath)} ]; then kill "$(cat ${shellQuote(pidFilePath)})" 2>/dev/null || true; rm -f ${shellQuote(pidFilePath)}; fi`,
+      `fuser -k -n tcp ${REMOTE_CODEX_APP_SERVER_PORT} 2>/dev/null || true`
+    ].join("; "),
+    { cwd: options.cwd, timeoutMs: 1e4 }
+  ).catch(() => void 0);
+}
 var CodexAgentAdapter = class {
   async setup(request) {
     await setupCodex(request);
   }
+  async killServer(request) {
+    await killCodexAppServer(request);
+  }
   async execute(request, sink) {
     const executeStartedAt = Date.now();
     debugCodex("execute() start runId=%s", request.runId);
@@ -4112,6 +4194,12 @@ async function ensureSandboxOpenCodeServer(request) {
       debugOpencode("opencode setup() preflight hit \u2014 skipping");
       return;
     }
+    if (await isSandboxOpenCodeServerHealthy(sandbox, options.cwd, port)) {
+      debugOpencode(
+        "opencode server already running but setup drifted \u2014 reusing it without restart; call agent.killServer() to apply the new config"
+      );
+      return;
+    }
     const commonEnv = {
       OPENCODE_CONFIG: configPath,
       OPENCODE_CONFIG_DIR: target.layout.opencodeDir,
@@ -4147,42 +4235,79 @@ async function ensureSandboxOpenCodeServer(request) {
         `disown 2>/dev/null || true`
       ].join(" ")})`
     ].join(" && ");
-    await killSandboxOpenCodeServer(sandbox, pidFilePath, options.cwd, port);
-    const launchResult = await time(
+    const OPENCODE_MAX_LAUNCH_ATTEMPTS = 4;
+    const OPENCODE_RELAUNCH_BACKOFF_MS = 1e3;
+    const readyDeadline = Date.now() + SANDBOX_OPENCODE_READY_TIMEOUT_MS;
+    const pidAlive = `kill -0 "$(cat ${shellQuote(pidFilePath)} 2>/dev/null)" 2>/dev/null`;
+    let lastLog = "";
+    const becameReady = await time(
       debugOpencode,
-      "spawn opencode serve",
-      () => sandbox.run(launchCommand, {
-        cwd: options.cwd,
-        env: serveEnv,
-        timeoutMs: 2e4
-      })
-    );
-    if (launchResult.exitCode !== 0) {
-      await target.cleanup().catch(() => void 0);
-      throw new Error(
-        `Could not start OpenCode server: ${launchResult.combinedOutput || launchResult.stderr}`
-      );
-    }
-    await time(debugOpencode, "poll opencode until ready", async () => {
-      const readyDeadline = Date.now() + SANDBOX_OPENCODE_READY_TIMEOUT_MS;
-      let attempt = 0;
-      while (Date.now() < readyDeadline) {
-        attempt++;
-        const probe = await sandbox.run(
-          `curl -fsS http://127.0.0.1:${port}/global/health >/dev/null 2>&1`,
-          { cwd: options.cwd, timeoutMs: 5e3 }
-        );
-        if (probe.exitCode === 0) {
-          debugOpencode("ready after %d probe attempt(s)", attempt);
-          return;
+      "launch + poll opencode until ready",
+      async () => {
+        for (let attempt = 1; attempt <= OPENCODE_MAX_LAUNCH_ATTEMPTS && Date.now() < readyDeadline; attempt++) {
+          await killSandboxOpenCodeServer(
+            sandbox,
+            pidFilePath,
+            options.cwd,
+            port
+          );
+          const launchResult = await sandbox.run(launchCommand, {
+            cwd: options.cwd,
+            env: serveEnv,
+            timeoutMs: 4e4
+          });
+          if (launchResult.exitCode !== 0) {
+            await target.cleanup().catch(() => void 0);
+            throw new Error(
+              `Could not start OpenCode server: ${launchResult.combinedOutput || launchResult.stderr}`
+            );
+          }
+          while (Date.now() < readyDeadline) {
+            const probe = await sandbox.run(
+              `curl -fsS http://127.0.0.1:${port}/global/health >/dev/null 2>&1`,
+              { cwd: options.cwd, timeoutMs: 5e3 }
+            );
+            if (probe.exitCode === 0) {
+              debugOpencode("ready on attempt %d", attempt);
+              return true;
+            }
+            const alive = await sandbox.run(pidAlive, {
+              cwd: options.cwd,
+              timeoutMs: 5e3
+            });
+            if (alive.exitCode !== 0) {
+              lastLog = (await sandbox.run(`tail -n 40 ${shellQuote(logFilePath)} 2>/dev/null`, {
+                cwd: options.cwd
+              }).catch(() => void 0))?.combinedOutput?.trim() ?? lastLog;
+              debugOpencode(
+                "opencode died on attempt %d/%d; relaunching. log:\n%s",
+                attempt,
+                OPENCODE_MAX_LAUNCH_ATTEMPTS,
+                lastLog
+              );
+              break;
+            }
+            await sleep(500);
+          }
+          if (Date.now() >= readyDeadline) break;
+          await sleep(OPENCODE_RELAUNCH_BACKOFF_MS);
         }
-        await sleep(500);
+        return false;
+      }
+    );
+    if (!becameReady) {
+      if (!lastLog) {
+        lastLog = (await sandbox.run(`tail -n 40 ${shellQuote(logFilePath)} 2>/dev/null`, {
+          cwd: options.cwd
+        }).catch(() => void 0))?.combinedOutput?.trim() ?? "";
       }
       await target.cleanup().catch(() => void 0);
       throw new Error(
-        `OpenCode server did not become ready within ${SANDBOX_OPENCODE_READY_TIMEOUT_MS}ms.`
+        `OpenCode server did not become ready within ${SANDBOX_OPENCODE_READY_TIMEOUT_MS}ms.` + (lastLog ? `
+opencode log:
+${lastLog}` : "")
       );
-    });
+    }
     await markSetupComplete(target, setupId);
   });
 }
@@ -4234,7 +4359,13 @@ async function ensureLocalOpenCodeServer(request) {
     debugOpencode("local opencode server up-to-date \u2014 reusing");
     return;
   }
-  debugOpencode("local opencode server drifted/absent \u2014 (re)spawning");
+  if (await isLocalOpenCodeServerHealthy()) {
+    debugOpencode(
+      "local opencode server already running but setup drifted \u2014 reusing it without restart; call agent.killServer() to apply the new config"
+    );
+    return;
+  }
+  debugOpencode("local opencode server absent \u2014 spawning");
   await applyDifferentialSetup(target, allArtifacts, installCommands);
   await killLocalOpenCodeServer();
   spawnCommand({
@@ -4267,6 +4398,45 @@ async function setupOpenCode(request) {
   }
   await ensureLocalOpenCodeServer(request);
 }
+async function isSandboxOpenCodeServerHealthy(sandbox, cwd, port) {
+  const probe = await sandbox.run(
+    `curl -fsS --max-time 2 http://127.0.0.1:${port}/global/health >/dev/null 2>&1`,
+    { cwd, timeoutMs: 5e3 }
+  ).catch(() => void 0);
+  return probe?.exitCode === 0;
+}
+async function isLocalOpenCodeServerHealthy() {
+  try {
+    const res = await fetch(
+      `http://127.0.0.1:${LOCAL_OPENCODE_PORT}/global/health`
+    );
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function killOpenCodeServer(request) {
+  const { options } = request;
+  if (options.sandbox) {
+    const target = await createSetupTarget(
+      request.provider,
+      SHARED_OPENCODE_TARGET_ID,
+      options
+    );
+    const pidFilePath = path10.posix.join(
+      target.layout.rootDir,
+      "opencode-serve.pid"
+    );
+    await killSandboxOpenCodeServer(
+      options.sandbox,
+      pidFilePath,
+      options.cwd,
+      SANDBOX_OPENCODE_PORT
+    );
+    return;
+  }
+  await killLocalOpenCodeServer();
+}
 async function buildOpenCodeRuntime(options) {
   if (options.sandbox) {
     const sandbox = options.sandbox;
@@ -4288,6 +4458,9 @@ var OpenCodeAgentAdapter = class {
   async setup(request) {
     await setupOpenCode(request);
   }
+  async killServer(request) {
+    await killOpenCodeServer(request);
+  }
   async execute(request, sink) {
     const executeStartedAt = Date.now();
     debugOpencode("execute() start runId=%s", request.runId);
@@ -5276,6 +5449,30 @@ var Agent = class {
       throw error;
     }
   }
+  /**
+   * Stop the long-lived provider CLI server booted by {@link Agent.setup}
+   * (claude-code relay daemon, codex app-server, opencode `serve`).
+   *
+   * agentbox NEVER kills a running server on its own — not on run
+   * completion, not on `abort()`, and not when {@link Agent.setup} detects
+   * a changed config/credential set. This method is the single, explicit,
+   * developer-driven teardown. Call it to free a server's resources, or to
+   * apply a changed config: after `killServer()` the next {@link setup}
+   * cold-starts a fresh server with the new configuration.
+   *
+   * Best-effort and idempotent: a no-op when no server is running, or when
+   * the provider has no shared server for the current mode (host-mode
+   * claude-code runs the SDK in-process; local codex spawns a fresh
+   * app-server per run, torn down with the run).
+   */
+  async killServer() {
+    debugAgent("killServer() provider=%s", this.provider);
+    await this.adapter.killServer({
+      provider: this.provider,
+      options: this.options
+    });
+    this.setupPromise = void 0;
+  }
   stream(runConfig) {
     if (runConfig.resumeSessionId && runConfig.forkSessionId) {
       throw new Error(

package/dist/events/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AISDKEvent, R as MessageCompletedEvent, S as MessageInjectedEvent, T as MessageStartedEvent, U as NormalizedAgentEvent, V as NormalizedAgentEventBase, W as NormalizedAgentEventType, a1 as PermissionRequestedEvent, a2 as PermissionResolvedEvent, a3 as RawAgentEvent, a4 as ReasoningDeltaEvent, a6 as RunCancelledEvent, a7 as RunCompletedEvent, a8 as RunErrorEvent, a9 as RunStartedEvent, ab as TextDeltaEvent, ad as ToolCallCompletedEvent, ae as ToolCallDeltaEvent, af as ToolCallStartedEvent, ai as createNormalizedEvent, aj as normalizeRawAgentEvent, ak as toAISDKEvent, al as toAISDKStream } from '../types-DG4J_zMT.js';
+export { A as AISDKEvent, R as MessageCompletedEvent, S as MessageInjectedEvent, T as MessageStartedEvent, U as NormalizedAgentEvent, V as NormalizedAgentEventBase, W as NormalizedAgentEventType, a1 as PermissionRequestedEvent, a2 as PermissionResolvedEvent, a3 as RawAgentEvent, a4 as ReasoningDeltaEvent, a6 as RunCancelledEvent, a7 as RunCompletedEvent, a8 as RunErrorEvent, a9 as RunStartedEvent, ab as TextDeltaEvent, ad as ToolCallCompletedEvent, ae as ToolCallDeltaEvent, af as ToolCallStartedEvent, ai as createNormalizedEvent, aj as normalizeRawAgentEvent, ak as toAISDKEvent, al as toAISDKStream } from '../types-t01PuLUJ.js';
 import { AgentProvider } from '../enums.js';
 import '../Sandbox-DcKAU-E3.js';
 import 'e2b';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AISDKEvent, a as AgentApprovalMode, b as AgentAttachRequest, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, h as AgentOptions, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, o as AgentProviderName, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, r as AgentResult, s as AgentRun, t as AgentRunConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, y as AttachedRun, C as ClaudeCodeAgentOptions, z as ClaudeCodeHookConfig, B as ClaudeCodeHookEvent, D as ClaudeCodeHookHandler, E as ClaudeCodeHookMatcherGroup, F as ClaudeCodeHooksConfig, G as ClaudeCodeProviderOptions, H as CodexAgentOptions, I as CodexCommandHook, J as CodexHookEvent, K as CodexHookMatcherGroup, L as CodexHooksConfig, M as CodexProviderOptions, N as DataContent, O as EmbeddedSkillConfig, P as FilePart, Q as ImagePart, R as MessageCompletedEvent, S as MessageInjectedEvent, T as MessageStartedEvent, U as NormalizedAgentEvent, V as NormalizedAgentEventBase, W as NormalizedAgentEventType, X as OpenCodeAgentOptions, Y as OpenCodePluginConfig, Z as OpenCodePluginEvent, _ as OpenCodePluginHookConfig, $ as OpenCodeProviderOptions, a0 as OpenRouterPlugin, a1 as PermissionRequestedEvent, a2 as PermissionResolvedEvent, a3 as RawAgentEvent, a4 as ReasoningDeltaEvent, a5 as RepoSkillConfig, a6 as RunCancelledEvent, a7 as RunCompletedEvent, a8 as RunErrorEvent, a9 as RunStartedEvent, aa as SetupLayout, ab as TextDeltaEvent, ac as TextPart, ad as ToolCallCompletedEvent, ae as ToolCallDeltaEvent, af as ToolCallStartedEvent, ag as UserContent, ah as UserContentPart, ai as createNormalizedEvent, aj as normalizeRawAgentEvent, ak as toAISDKEvent, al as toAISDKStream } from './types-DG4J_zMT.js';
+export { A as AISDKEvent, a as AgentApprovalMode, b as AgentAttachRequest, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, h as AgentOptions, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, o as AgentProviderName, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, r as AgentResult, s as AgentRun, t as AgentRunConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, y as AttachedRun, C as ClaudeCodeAgentOptions, z as ClaudeCodeHookConfig, B as ClaudeCodeHookEvent, D as ClaudeCodeHookHandler, E as ClaudeCodeHookMatcherGroup, F as ClaudeCodeHooksConfig, G as ClaudeCodeProviderOptions, H as CodexAgentOptions, I as CodexCommandHook, J as CodexHookEvent, K as CodexHookMatcherGroup, L as CodexHooksConfig, M as CodexProviderOptions, N as DataContent, O as EmbeddedSkillConfig, P as FilePart, Q as ImagePart, R as MessageCompletedEvent, S as MessageInjectedEvent, T as MessageStartedEvent, U as NormalizedAgentEvent, V as NormalizedAgentEventBase, W as NormalizedAgentEventType, X as OpenCodeAgentOptions, Y as OpenCodePluginConfig, Z as OpenCodePluginEvent, _ as OpenCodePluginHookConfig, $ as OpenCodeProviderOptions, a0 as OpenRouterPlugin, a1 as PermissionRequestedEvent, a2 as PermissionResolvedEvent, a3 as RawAgentEvent, a4 as ReasoningDeltaEvent, a5 as RepoSkillConfig, a6 as RunCancelledEvent, a7 as RunCompletedEvent, a8 as RunErrorEvent, a9 as RunStartedEvent, aa as SetupLayout, ab as TextDeltaEvent, ac as TextPart, ad as ToolCallCompletedEvent, ae as ToolCallDeltaEvent, af as ToolCallStartedEvent, ag as UserContent, ah as UserContentPart, ai as createNormalizedEvent, aj as normalizeRawAgentEvent, ak as toAISDKEvent, al as toAISDKStream } from './types-t01PuLUJ.js';
 export { AGENT_RESERVED_PORTS, Agent, agentboxRoot, collectAllAgentReservedPorts, getAgentLayout } from './agents/index.js';
 export { A as AsyncCommandHandle, C as CommandEvent, a as CommandOptions, b as CommandResult, D as DaytonaProviderOptions, c as DaytonaSandboxOptions, E as E2bProviderOptions, d as E2bSandboxOptions, G as GitCloneOptions, L as LocalDockerProviderOptions, e as LocalDockerSandboxOptions, M as ModalProviderOptions, f as ModalSandboxOptions, S as Sandbox, g as SandboxDescriptor, h as SandboxListOptions, i as SandboxOptions, j as SandboxOptionsBase, k as SandboxOptionsMap, l as SandboxProviderName, m as SandboxRaw, n as SandboxRawMap, o as SandboxResourceSpec, T as TarballEntry, V as VercelGitSource, p as VercelProviderOptions, q as VercelSandboxOptions } from './Sandbox-DcKAU-E3.js';
 export { SandboxAdapter, buildGitCloneCommand } from './sandboxes/index.js';

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   Agent,
   agentboxRoot,
   getAgentLayout
-} from "./chunk-2IHQY3WC.js";
+} from "./chunk-XONT46YC.js";
 import {
   ProviderLogAssembler,
   createNormalizedEvent,
@@ -14,7 +14,7 @@ import {
   Sandbox,
   SandboxAdapter,
   buildGitCloneCommand
-} from "./chunk-HYHLKO3L.js";
+} from "./chunk-TUBBWIOM.js";
 import {
   AGENT_RESERVED_PORTS,
   collectAllAgentReservedPorts

package/dist/sandboxes/index.js

@@ -2,7 +2,7 @@ import {
   Sandbox,
   SandboxAdapter,
   buildGitCloneCommand
-} from "../chunk-HYHLKO3L.js";
+} from "../chunk-TUBBWIOM.js";
 import "../chunk-AVXJMCBC.js";
 import "../chunk-NSJM57Z4.js";
 import {

package/dist/{types-DG4J_zMT.d.ts → types-t01PuLUJ.d.ts}

@@ -599,6 +599,22 @@ interface AgentProviderAdapter<P extends AgentProviderName = AgentProviderName>
      * is already listening.
      */
     setup(request: AgentSetupRequest<P>): Promise<void>;
+    /**
+     * Stop the long-lived provider CLI server that {@link setup} boots
+     * (claude-code relay daemon, codex app-server, opencode `serve`).
+     *
+     * agentbox NEVER calls this on its own — not on run completion, not on
+     * abort, and not when {@link setup} sees a changed config/credential
+     * set. It exists purely so a developer can explicitly tear a server
+     * down (to reclaim resources, or to force the changed config to apply
+     * on the next cold {@link setup}).
+     *
+     * Best-effort and idempotent: a no-op when nothing is running, or when
+     * the provider has no shared server for the current mode (host-mode
+     * claude-code runs the SDK in-process; local codex spawns a fresh
+     * app-server per run).
+     */
+    killServer(request: AgentSetupRequest<P>): Promise<void>;
     execute(request: AgentExecutionRequest<P>, sink: AgentRunSink): Promise<() => Promise<void> | void>;
     /**
      * Stateless abort. Dial the in-sandbox provider server, issue the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentbox-sdk",
-  "version": "0.1.319",
+  "version": "0.1.323",
   "description": "Swappable coding agents and sandbox providers for Bun and TypeScript.",
   "license": "MIT",
   "repository": {