agentbox-sdk 0.1.322 → 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-ZK5PDWOI.js";
+} from "../chunk-XONT46YC.js";
 import "../chunk-775FIGGL.js";
 import {
   AGENT_RESERVED_PORTS,

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

@@ -251,6 +251,20 @@ 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;
@@ -292,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();

package/dist/{chunk-ZK5PDWOI.js → chunk-XONT46YC.js}

@@ -2181,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;
@@ -3573,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);
@@ -4152,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,
@@ -4311,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({
@@ -4344,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;
@@ -4365,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);
@@ -5353,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-ZK5PDWOI.js";
+} from "./chunk-XONT46YC.js";
 import {
   ProviderLogAssembler,
   createNormalizedEvent,
@@ -14,7 +14,7 @@ import {
   Sandbox,
   SandboxAdapter,
   buildGitCloneCommand
-} from "./chunk-T4AS2WEF.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-T4AS2WEF.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.322",
+  "version": "0.1.323",
   "description": "Swappable coding agents and sandbox providers for Bun and TypeScript.",
   "license": "MIT",
   "repository": {