threadwire 0.1.12 → 0.1.14

package/scripts/verify-package.js

@@ -24,9 +24,11 @@ const EXPECTED_FILES = [
   "bin/isolated-runtime.js",
   "bin/kimi-model-broker.js",
   "bin/model-broker.js",
+  "docs/capacity-admission.md",
   "docs/card-10520-plan.md",
   "docs/container-runtime.md",
   "docs/delegated-result-protocol.md",
+  "docs/development-container.md",
   "docs/evidence-artifacts.md",
   "docs/isolated-provider-runtime.md",
   "package.json",
@@ -50,6 +52,7 @@ const EXPECTED_FILES = [
   "src/isolated-runtime.js",
   "src/isolated-state.js",
   "src/isolated-worker.js",
+  "src/jsonl-record-spool.js",
   "src/kimi-model-broker-policy.js",
   "src/kimi-model-broker.js",
   "src/kimi-oauth-store.js",
@@ -66,6 +69,9 @@ const EXPECTED_FILES = [
   "src/providers/index.js",
   "src/providers/kimi.js",
   "src/providers/opencode.js",
+  "src/provider-capacity-codex.js",
+  "src/provider-capacity-kimi.js",
+  "src/provider-capacity.js",
   "src/relay.js",
   "src/relay-write.js",
   "src/run-worker.js",
@@ -79,9 +85,7 @@ const EXPECTED_FILES = [
   "src/telegram-webhook.js",
   "src/threadwire-binding.js",
   "src/types.js",
-  "src/worker-control.js",
-  "src/workspace-profile.js",
-  "threadwire.workspace-profiles.json"
+  "src/worker-control.js"
 ]
 
 /** @returns {Promise<void>} */
@@ -125,6 +129,7 @@ async function main() {
       "--help"
     ], {env: npmEnvironment, maxBuffer: 10 * 1024 * 1024})
     assert.match(helpOutput, /^Usage: threadwire run /u)
+    assert.match(helpOutput, /threadwire capacity /u)
 
     await assert.rejects(
       execFileAsync("npm", [

package/src/absolute-deadline.js

@@ -2,7 +2,11 @@
 /* eslint-disable jsdoc/require-jsdoc */
 
 export class AbsoluteDeadline {
-  constructor(expiresAt, {signal, request, response, now = Date.now, timeoutMessage = "Operation timeout", disconnectMessage = "Caller disconnected"} = {}) {
+  /**
+   * @param {number | undefined} expiresAt
+   * @param {{signal?: AbortSignal, request?: import("node:http").IncomingMessage, response?: import("node:http").ServerResponse, now?: () => number, timeoutMessage?: string, disconnectMessage?: string, destroyRequestOnAbort?: boolean}} [options]
+   */
+  constructor(expiresAt, {signal, request, response, now = Date.now, timeoutMessage = "Operation timeout", disconnectMessage = "Caller disconnected", destroyRequestOnAbort = true} = {}) {
     if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= now())) throw new Error(timeoutMessage)
     this.expiresAt = expiresAt
     this.now = now
@@ -27,13 +31,12 @@ export class AbsoluteDeadline {
     response?.once?.("close", this.abortResponse)
     this.socket?.once?.("close", this.abortSocket)
     this.timer = expiresAt === undefined ? undefined : setTimeout(() => this.controller.abort(new Error(timeoutMessage)), Math.max(1, expiresAt - now()))
-    this.signal.addEventListener("abort", () => request?.destroy?.(this.signal.reason), {once: true})
+    if (destroyRequestOnAbort) this.signal.addEventListener("abort", () => request?.destroy?.(this.signal.reason), {once: true})
     if (request?.aborted || (response?.destroyed && !response.writableEnded)) this.abortRequest()
   }
   remaining() {
     this.throwIfAborted()
     if (this.expiresAt === undefined) return undefined
-    if (this.expiresAt === undefined) return undefined
     const remaining = this.expiresAt - this.now()
     if (remaining <= 0) {
       this.controller.abort(new Error(this.timeoutMessage))

package/src/activity-log.js

@@ -3,9 +3,6 @@
 import {closeSync, openSync, writeSync} from "node:fs"
 
 const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
-const PROFILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u
-const REVISION_PATTERN = /^[0-9a-f]{40}$/u
-const SOURCE_IDENTITY_PATTERN = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/u
 
 export class ActivityLog {
   /** @param {string} path */
@@ -14,16 +11,6 @@ export class ActivityLog {
     this.closed = false
   }
 
-  /** @param {string} profile @param {string} repositoryRoot @param {string} revision @param {string} sourceIdentity */
-  recordWorkspace(profile, repositoryRoot, revision, sourceIdentity) {
-    if (!PROFILE_PATTERN.test(profile)) throw new Error("Workspace profile is invalid")
-    if (typeof repositoryRoot !== "string" || repositoryRoot.length === 0) throw new Error("Workspace repository root is invalid")
-    if (!REVISION_PATTERN.test(revision) || !SOURCE_IDENTITY_PATTERN.test(sourceIdentity)) {
-      throw new Error("Workspace provenance is invalid")
-    }
-    this.write({type: "workspace-selected", profile, repositoryRoot, revision, sourceIdentity})
-  }
-
   /** @param {"codex" | "claude" | "kimi" | "opencode"} provider @param {number} pid */
   recordStarted(provider, pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Provider child PID is unavailable")
@@ -42,7 +29,7 @@ export class ActivityLog {
     closeSync(this.fileDescriptor)
   }
 
-  /** @param {{type: "workspace-selected", profile: string, repositoryRoot: string, revision: string, sourceIdentity: string} | {type: "provider-started", provider: "codex" | "claude" | "kimi" | "opencode", pid: number} | {type: "session-available", provider: "codex" | "claude" | "kimi" | "opencode", sessionId: string}} fact */
+  /** @param {{type: "provider-started", provider: "codex" | "claude" | "kimi" | "opencode", pid: number} | {type: "session-available", provider: "codex" | "claude" | "kimi" | "opencode", sessionId: string}} fact */
   write(fact) {
     if (this.closed) throw new Error("Activity log is closed")
     writeSync(this.fileDescriptor, `${JSON.stringify(fact)}\n`)

package/src/cli.js

@@ -11,20 +11,26 @@ import {runWorker} from "./run-worker.js"
 import {ActivityLog} from "./activity-log.js"
 import {DelegatedResultAdmission, validateContinuationHandle} from "./delegated-result-admission.js"
 import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
-import {resolveWorkspaceProfile} from "./workspace-profile.js"
 import {WorkerControl} from "./worker-control.js"
 import {EvidenceStore} from "./evidence-store.js"
 import {ContextBudgetMetrics} from "./context-budget-metrics.js"
-import {isolatedRuntimeClientFromEnvironment, kimiIsolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js"
-import {parseTrustedThreadwireBinding} from "./threadwire-binding.js"
-import {kimiSessionEnvelopeId} from "./providers/kimi.js"
+import {isolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js"
 import {validateRelayWriteProviderArguments} from "./relay-write.js"
 import {abortable} from "./absolute-deadline.js"
 import {NormalizedOutput} from "./normalized-output.js"
+import {
+  CAPACITY_PROVIDERS,
+  DEFAULT_CAPACITY_TIMEOUT_MS,
+  DEFAULT_LONG_RESERVE_PERCENT,
+  DEFAULT_SHORT_RESERVE_PERCENT,
+  createCapacityProbe,
+  selectProvider
+} from "./provider-capacity.js"
+import {probeCodexCapacity} from "./provider-capacity-codex.js"
+import {probeKimiCapacity} from "./provider-capacity-kimi.js"
 
 const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id>
   [--process-number <positive-integer>] [--cwd <directory>]
-  [--workspace-profile <name>]
   [--relay-write]
   [--tool-messages] [--max-output-length <positive-integer>]
   [--resume-session <provider-session-id>] [--transcript <normalized-jsonl-path>]
@@ -32,10 +38,15 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   [--prompt <text> | --prompt-file <path> | stdin]
   [-- <provider arguments...>]
        threadwire evidence read --handle <opaque-handle>
-  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)`
+  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)
+       threadwire capacity [--provider <codex|kimi>]...
+  [--short-reserve-percent <0-100>] [--long-reserve-percent <0-100>]
+  [--timeout-ms <positive-integer>]`
 
-/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, workspaceProfile?: string, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
 /** @typedef {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
+/** @typedef {{capacity: true, providers: import("./provider-capacity.js").CapacityProvider[], shortReservePercent: number, longReservePercent: number, timeoutMs: number}} CapacityParsedArguments */
+/** @typedef {{probe: (provider: import("./provider-capacity.js").CapacityProvider, timeoutMs?: number) => Promise<import("./provider-capacity.js").CapacityCandidate>}} CapacityProbeDependency */
 /**
  * @typedef {{
  *   env?: NodeJS.ProcessEnv,
@@ -47,9 +58,9 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
  *   evidenceStore?: EvidenceStore,
  *   evidenceOwnerScope?: {destinationId: string, runId: string},
  *   workerControlOptions?: Pick<ConstructorParameters<typeof WorkerControl>[0], "queueOptions">,
- *   workspaceProfileOperations?: import("./workspace-profile.js").WorkspaceProfileOperations,
- *   isolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "run">,
- *   kimiIsolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "run">
+ *   isolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "startRun">,
+ *   capacityProbe?: CapacityProbeDependency,
+ *   now?: () => number
  * }} MainDependencies
  */
 
@@ -63,7 +74,6 @@ export function parseArguments(arguments_) {
   const providerArguments = separator < 0 ? [] : arguments_.slice(separator + 1)
   /** @type {Partial<ParsedArguments>} */
   const parsed = {providerArguments, cwd: process.cwd(), toolMessages: false, relayWrite: false}
-  let cwdProvided = false
   let transcriptProvided = false
   for (let index = 0; index < ownArguments.length;) {
     const option = ownArguments[index]
@@ -86,8 +96,7 @@ export function parseArguments(arguments_) {
     else if (option === "--target") parsed.target = value
     else if (option === "--cwd") {
       parsed.cwd = resolve(value)
-      cwdProvided = true
-    } else if (option === "--workspace-profile") parsed.workspaceProfile = value
+    } else if (option === "--workspace-profile") throw new Error("--workspace-profile is no longer supported; use --cwd")
     else if (option === "--prompt") parsed.prompt = value
     else if (option === "--prompt-file") parsed.promptFile = resolve(value)
     else if (option === "--process-number") parsed.processNumber = positiveInteger(value, "--process-number")
@@ -108,14 +117,9 @@ export function parseArguments(arguments_) {
   }
   if (!parsed.target) throw new Error("--target is required")
   if (parsed.prompt !== undefined && parsed.promptFile !== undefined) throw new Error("Use exactly one prompt source")
-  if (parsed.workspaceProfile !== undefined && cwdProvided) {
-    throw new Error("--cwd and --workspace-profile are mutually exclusive")
-  }
   if (parsed.transcript !== undefined && parsed.transcript === parsed.activityLog) {
     throw new Error("--transcript and --activity-log must resolve to different paths")
   }
-  if (parsed.relayWrite && parsed.workspaceProfile === undefined) throw new Error("--relay-write requires --workspace-profile")
-  if (parsed.provider === "kimi" && parsed.workspaceProfile === undefined) throw new Error("Kimi requires --workspace-profile")
   if (parsed.relayWrite && parsed.provider !== "codex") throw new Error("--relay-write is only supported for codex")
   return /** @type {ParsedArguments} */ (parsed)
 }
@@ -148,6 +152,71 @@ function parseEvidenceArguments(arguments_) {
   return {evidenceRead: true, request}
 }
 
+/** @param {string[]} arguments_ @returns {CapacityParsedArguments | {help: true}} */
+function parseCapacityArguments(arguments_) {
+  if (arguments_.includes("--help") || arguments_.includes("-h")) return {help: true}
+  /** @type {import("./provider-capacity.js").CapacityProvider[]} */
+  const providers = []
+  let shortReservePercent = DEFAULT_SHORT_RESERVE_PERCENT
+  let longReservePercent = DEFAULT_LONG_RESERVE_PERCENT
+  let timeoutMs = DEFAULT_CAPACITY_TIMEOUT_MS
+  /** @type {Set<string>} */
+  const seen = new Set()
+  for (let index = 1; index < arguments_.length; index += 2) {
+    const option = arguments_[index]
+    const value = arguments_[index + 1]
+    if (!option || value === undefined) throw new Error(HELP)
+    if (option !== "--provider") {
+      if (seen.has(option)) throw new Error(`Duplicate capacity option: ${option}`)
+      seen.add(option)
+    }
+    if (option === "--provider") {
+      if (!CAPACITY_PROVIDERS.includes(/** @type {import("./provider-capacity.js").CapacityProvider} */ (value))) {
+        throw new Error(`--provider must be one of: ${CAPACITY_PROVIDERS.join(", ")}`)
+      }
+      const provider = /** @type {import("./provider-capacity.js").CapacityProvider} */ (value)
+      if (providers.includes(provider)) throw new Error(`Duplicate capacity provider: ${value}`)
+      providers.push(provider)
+    } else if (option === "--short-reserve-percent") shortReservePercent = reservePercent(value, option)
+    else if (option === "--long-reserve-percent") longReservePercent = reservePercent(value, option)
+    else if (option === "--timeout-ms") timeoutMs = positiveInteger(value, option)
+    else throw new Error(HELP)
+  }
+  return {
+    capacity: true,
+    providers: providers.length === 0 ? [...CAPACITY_PROVIDERS] : providers,
+    shortReservePercent,
+    longReservePercent,
+    timeoutMs
+  }
+}
+
+/**
+ * The real probe never rejects (it converts failures into candidates); this
+ * guard keeps any probe implementation from leaking an unexpected error into
+ * output by degrading to a fixed, credential-free candidate.
+ * @param {CapacityProbeDependency} probe
+ * @param {import("./provider-capacity.js").CapacityProvider} provider
+ * @param {number} timeoutMs
+ * @returns {Promise<import("./provider-capacity.js").CapacityCandidate>}
+ */
+async function probeCapacityCandidate(probe, provider, timeoutMs) {
+  try {
+    return await probe.probe(provider, timeoutMs)
+  } catch {
+    return {provider, status: "unavailable", error: "Capacity probe failed"}
+  }
+}
+
+/** @param {string} value @param {string} option */
+function reservePercent(value, option) {
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number > 100) {
+    throw new Error(`${option} must be an integer between 0 and 100`)
+  }
+  return number
+}
+
 /** @param {string} value @param {boolean} zeroStart */
 function rangePair(value, zeroStart) {
   const match = /^(\d+):(\d+)$/u.exec(value)
@@ -175,11 +244,41 @@ export async function main(arguments_, dependencies = {}) {
   /** @type {DelegatedResultAdmission | undefined} */
   let runAdmission
   try {
-    const parsed = arguments_[0] === "evidence" ? parseEvidenceArguments(arguments_) : parseArguments(arguments_)
+    const parsed = arguments_[0] === "evidence"
+      ? parseEvidenceArguments(arguments_)
+      : arguments_[0] === "capacity" ? parseCapacityArguments(arguments_) : parseArguments(arguments_)
     if ("help" in parsed) {
       if (!validateOnly) output.write(`${HELP}\n`)
       return 0
     }
+    if ("capacity" in parsed) {
+      if (validateOnly) return 0
+      const probe = dependencies.capacityProbe ?? createCapacityProbe({
+        env: sourceEnvironment,
+        probes: {
+          codex: ({env, timeoutMs}) => probeCodexCapacity({env, timeoutMs}),
+          kimi: ({env, timeoutMs}) => probeKimiCapacity({env, timeoutMs})
+        }
+      })
+      /** @type {import("./provider-capacity.js").CapacityCandidate[]} */
+      const candidates = []
+      for (const provider of parsed.providers) {
+        candidates.push(await probeCapacityCandidate(probe, provider, parsed.timeoutMs))
+      }
+      const {selection, rejected} = selectProvider(candidates, {
+        shortReservePercent: parsed.shortReservePercent,
+        longReservePercent: parsed.longReservePercent
+      })
+      output.write(`${JSON.stringify({
+        version: 1,
+        generatedAt: new Date((dependencies.now ?? Date.now)()).toISOString(),
+        reserves: {shortPercent: parsed.shortReservePercent, longPercent: parsed.longReservePercent},
+        candidates,
+        rejected,
+        selection
+      })}\n`)
+      return selection === null ? 2 : 0
+    }
     if ("evidenceRead" in parsed) {
       const root = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (!root) throw new Error("THREADWIRE_EVIDENCE_ROOT is required")
@@ -200,35 +299,17 @@ export async function main(arguments_, dependencies = {}) {
     runAdmission = normalizedOutput === undefined ? undefined : new DelegatedResultAdmission({output: normalizedOutput, metrics})
     const target = parseTelegramTarget(parsed.target)
     if (parsed.relayWrite) validateRelayWriteProviderArguments(parsed.providerArguments)
-    const kimiBinding = parsed.provider === "kimi"
-      ? parseTrustedThreadwireBinding(sourceEnvironment.THREADWIRE_KIMI_TASK_BINDING)
-      : undefined
-    const resolvedWorkspace = parsed.workspaceProfile === undefined
-      ? undefined
-      : await resolveWorkspaceProfile(
-        {
-          provider: /** @type {"codex" | "claude" | "kimi" | "opencode"} */ (parsed.provider), profile: parsed.workspaceProfile,
-          ...(kimiBinding === undefined ? {} : {binding: kimiBinding})
-        },
-        dependencies.workspaceProfileOperations
-      )
     if (validateOnly) return 0
-    const usesIsolatedRuntime = parsed.relayWrite || parsed.provider === "kimi"
+    const usesIsolatedRuntime = parsed.relayWrite
     const isolatedRuntimeClient = usesIsolatedRuntime
-      ? parsed.provider === "kimi"
-        ? dependencies.kimiIsolatedRuntimeClient ?? kimiIsolatedRuntimeClientFromEnvironment(sourceEnvironment)
-        : dependencies.isolatedRuntimeClient ?? isolatedRuntimeClientFromEnvironment(sourceEnvironment)
+      ? dependencies.isolatedRuntimeClient ?? isolatedRuntimeClientFromEnvironment(sourceEnvironment)
       : undefined
     const isolatedPreflight = usesIsolatedRuntime
       ? await /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).preflight({
         provider: parsed.provider,
-        profile: /** @type {string} */ (parsed.workspaceProfile),
-        ...(parsed.provider === "kimi"
-          ? {binding: kimiBinding}
-          : {
-            repositoryRoot: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).repositoryRoot,
-            cwd: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).cwd
-          }),
+        profile: "explicit-cwd",
+        repositoryRoot: parsed.cwd,
+        cwd: parsed.cwd,
         providerArguments: parsed.providerArguments,
         ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession})
       })
@@ -268,18 +349,18 @@ export async function main(arguments_, dependencies = {}) {
         await boundedLaunch(evidence.append("prompt", promptEvidence), launchDeadline)
         evidencePayloadBytes += Buffer.byteLength(promptEvidence, "utf8")
       }
-      const providerEnvironment = buildProviderEnvironment(environment)
+      const providerEnvironment = buildProviderEnvironment(environment, {
+        provider: parsed.provider,
+        isolated: usesIsolatedRuntime
+      })
       const provider = createProvider(
         parsed.provider,
         parsed.providerArguments,
         prompt,
         parsed.resumeSession,
-        usesIsolatedRuntime ? {} : providerEnvironment
+        providerEnvironment
       )
       if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
-      if (parsed.workspaceProfile !== undefined) {
-        if (resolvedWorkspace === undefined) throw new Error("Workspace profile resolution failed")
-      }
       const token = environment.THREADWIRE_TELEGRAM_BOT_TOKEN
       if (!token) throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
       const transport = (dependencies.transportFactory ?? createFetchTransport)(token, undefined, parseTelegramRequestTimeoutMs(environment))
@@ -292,21 +373,16 @@ export async function main(arguments_, dependencies = {}) {
         metrics
       })
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
-      if (activity && resolvedWorkspace) {
-        activity.recordWorkspace(
-          resolvedWorkspace.profile,
-          resolvedWorkspace.repositoryRoot,
-          resolvedWorkspace.revision,
-          resolvedWorkspace.sourceIdentity
-        )
-      }
       /** @type {import("./run-worker.js").RunWorkerOptions} */
       const workerOptions = {
         executable: provider.executable,
         arguments: provider.arguments,
-        cwd: resolvedWorkspace?.cwd ?? parsed.cwd,
+        cwd: parsed.cwd,
         environment: providerEnvironment,
+        provider: provider.name,
         parse: provider.parse,
+        ...(provider.completion === undefined ? {} : {completion: provider.completion}),
+        ...(launchDeadline === undefined ? {} : {signal: launchDeadline.signal}),
         onEvent: (event) => {
           validateNormalizedWorkerEvent(event)
           if (event.type !== "text-delta") {
@@ -320,7 +396,7 @@ export async function main(arguments_, dependencies = {}) {
         },
         onRecord: (record) => {
           metrics.recordParsedProviderRecord("provider_stdout")
-          const id = parsed.provider === "kimi" ? kimiSessionEnvelopeId(record) : provider.sessionId(record)
+          const id = provider.sessionId(record)
           if (id !== undefined) {
             admission.setContinuationHandle(id)
             activity?.recordSession(provider.name, id)
@@ -339,8 +415,9 @@ export async function main(arguments_, dependencies = {}) {
           return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
         }
       }
-      const exitCode = usesIsolatedRuntime
-        ? await /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).run({
+      let exitCode
+      if (usesIsolatedRuntime) {
+        const isolatedRun = /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).startRun({
           preflightId: /** @type {{preflightId: string}} */ (isolatedPreflight).preflightId,
           prompt,
           providerArguments: parsed.providerArguments,
@@ -351,7 +428,15 @@ export async function main(arguments_, dependencies = {}) {
           ...(parsed.provider === "kimi" || workerOptions.onStderrChunk === undefined ? {} : {onStderrChunk: workerOptions.onStderrChunk}),
           ...(launchDeadline === undefined ? {} : {deadline: launchDeadline})
         })
-        : await (dependencies.workerRunner ?? runWorker)(workerOptions)
+        try {
+          exitCode = await abortable(isolatedRun.completion, launchDeadline?.signal)
+        } catch (error) {
+          await isolatedRun.cancel(error instanceof Error ? error : new Error("Isolated runtime run failed"))
+          throw error
+        }
+      } else {
+        exitCode = await (dependencies.workerRunner ?? runWorker)(workerOptions)
+      }
       await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
     } finally {

package/src/docker-api.js

@@ -172,6 +172,14 @@ export class DockerApi {
     })
   }
   inspectContainer(id, options) { return this.request("GET", `/containers/${encodeURIComponent(id)}/json`, undefined, false, options) }
+  async stopContainer(id, graceSeconds, options) {
+    if (!Number.isSafeInteger(graceSeconds) || graceSeconds <= 0) throw new Error("Docker stop grace must be a positive safe integer")
+    return await this.request("POST", `/containers/${encodeURIComponent(id)}/stop?t=${graceSeconds}`, undefined, false, options)
+  }
+  async killContainer(id, signal, options) {
+    if (typeof signal !== "string" || !/^[A-Z][A-Z0-9]{0,15}$/u.test(signal)) throw new Error("Docker kill signal is invalid")
+    return await this.request("POST", `/containers/${encodeURIComponent(id)}/kill?signal=${encodeURIComponent(signal)}`, undefined, false, options)
+  }
   removeContainer(id, options) { return this.request("DELETE", `/containers/${encodeURIComponent(id)}?force=1&v=1`, undefined, false, options) }
   createVolume(name, labels = {}, options) {
     return this.request("POST", "/volumes/create", {Name: name, Labels: labels}, false, options)

package/src/isolated-runtime-client.js

@@ -5,14 +5,16 @@ import {AbsoluteDeadline, deadlineAfter, abortable, readResponseCapped} from "./
 
 const MAX_RESPONSE_BYTES = 2_097_152
 const MAX_RAW_OUTPUT_BYTES = 1_048_576
+const DEFAULT_CLEANUP_TIMEOUT_MS = 10_000
 
 export class IsolatedRuntimeClient {
-  /** @param {{url: string, controlToken: string, timeoutMs?: number | string, fetchImplementation?: typeof fetch}} options */
+  /** @param {{url: string, controlToken: string, timeoutMs?: number | string, cleanupTimeoutMs?: number | string, fetchImplementation?: typeof fetch}} options */
   constructor(options) {
     this.url = normalizedUrl(options.url)
     this.controlToken = nonempty(options.controlToken, "isolated runtime control token")
     this.fetch = options.fetchImplementation ?? fetch
     this.timeoutMs = optionalDuration(options.timeoutMs)
+    this.cleanupTimeoutMs = optionalDuration(options.cleanupTimeoutMs) ?? DEFAULT_CLEANUP_TIMEOUT_MS
   }
 
   /**
@@ -79,6 +81,113 @@ export class IsolatedRuntimeClient {
     }
   }
 
+  /**
+   * Start a container-backed run whose request side remains open as the
+   * cancellation channel. Closing that side asks the runtime to stop its exact
+   * worker container while leaving the response available for terminal cleanup
+   * confirmation.
+   * @param {{
+   *   preflightId: string, prompt: string, providerArguments: string[],
+   *   resumeSession?: string,
+   *   signal?: AbortSignal,
+   *   deadline?: import("./absolute-deadline.js").AbsoluteDeadline,
+   *   onEvent: (event: import("./types.js").WorkerEvent) => unknown | Promise<unknown>,
+   *   onRecord?: (record: unknown) => unknown | Promise<unknown>,
+   *   onStdoutChunk?: (chunk: Buffer) => unknown | Promise<unknown>,
+   *   onStderrChunk?: (chunk: Buffer) => unknown | Promise<unknown>
+   * }} options
+   */
+  startRun(options) {
+    const deadline = options.deadline ?? (this.timeoutMs === undefined ? undefined : deadlineAfter(this.timeoutMs, {signal: options.signal, timeoutMessage: "Isolated runtime launch timeout"}))
+    const operation = deadline ?? new AbsoluteDeadline(undefined, {signal: options.signal, timeoutMessage: "Isolated runtime launch timeout"})
+    const requestController = new AbortController()
+    /** @type {ReadableStreamDefaultController<Uint8Array>} */
+    let bodyController
+    let bodyClosed = false
+    const body = new ReadableStream({
+      start(controller) {
+        bodyController = controller
+        controller.enqueue(new TextEncoder().encode(`${JSON.stringify({
+          preflightId: options.preflightId,
+          prompt: options.prompt,
+          providerArguments: options.providerArguments,
+          ...(options.resumeSession === undefined ? {} : {resumeSession: options.resumeSession})
+        })}\n`))
+      }
+    })
+    const closeRequest = () => {
+      if (bodyClosed) return
+      bodyClosed = true
+      bodyController.close()
+    }
+    /** @type {Error | undefined} */
+    let consumerError
+    /** @type {(error: Error) => void} */
+    let rejectConsumer
+    const consumerFailure = new Promise((_resolve, reject) => { rejectConsumer = reject })
+    const transportCompletion = (async () => {
+      const response = await this.fetch(`${this.url}/run`, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          authorization: `Bearer ${this.controlToken}`,
+          "content-type": "application/x-ndjson",
+          connection: "close",
+          "x-threadwire-run-lifecycle": "1",
+          ...(operation.expiresAt === undefined ? {} : {"x-threadwire-launch-deadline": String(operation.expiresAt)})
+        },
+        body,
+        duplex: "half",
+        signal: requestController.signal
+      })
+      if (!response.ok) {
+        const bytes = await readResponseCapped(response, MAX_RESPONSE_BYTES, requestController.signal)
+        throw new Error(safeRemoteError(bytes))
+      }
+      return consumeRunStream(response, options, {
+        signal: requestController.signal,
+        onConsumerError(error) {
+          if (consumerError !== undefined) return
+          consumerError = error
+          rejectConsumer(error)
+        }
+      })
+    })()
+    const runCompletion = Promise.race([transportCompletion, consumerFailure])
+    /** @type {Promise<void> | undefined} */
+    let cancellation
+    const cancel = (reason = new Error("Isolated runtime run cancelled")) => {
+      if (cancellation !== undefined) return cancellation
+      closeRequest()
+      const cleanup = deadlineAfter(this.cleanupTimeoutMs, {timeoutMessage: "Isolated runtime cleanup confirmation timeout"})
+      cancellation = (async () => {
+        try {
+          await abortable(transportCompletion, cleanup.signal)
+        } catch (error) {
+          requestController.abort(reason)
+          throw new Error("Isolated runtime cleanup could not be confirmed", {cause: error})
+        } finally {
+          cleanup.close()
+        }
+      })()
+      return cancellation
+    }
+    const completion = (async () => {
+      try {
+        return await abortable(runCompletion, operation.signal)
+      } catch (error) {
+        if (operation.signal.aborted || error === consumerError) {
+          await cancel(error instanceof Error ? error : new Error("Isolated runtime run failed"))
+        }
+        throw error
+      } finally {
+        closeRequest()
+        if (options.deadline === undefined) operation.close()
+      }
+    })()
+    return {completion, cancel}
+  }
+
   /** @param {string} path @param {unknown} body */
   async request(path, body, deadline) {
     const signal = deadline.signal
@@ -121,6 +230,17 @@ async function consumeRunStream(response, options, operation) {
   let rawBytes = 0
   /** @type {number | undefined} */
   let terminal
+  let consumerFailed = false
+  const invokeConsumer = async (callback) => {
+    if (consumerFailed) return
+    try {
+      await abortable(callback(), operation.signal)
+    } catch (error) {
+      if (operation.onConsumerError === undefined) throw error
+      consumerFailed = true
+      operation.onConsumerError(error instanceof Error ? error : new Error("Isolated runtime consumer failed"))
+    }
+  }
   const consume = async (line) => {
     if (line.length === 0 || terminal !== undefined) throw new Error("Isolated runtime emitted an invalid response")
     let frame
@@ -136,13 +256,13 @@ async function consumeRunStream(response, options, operation) {
       rawBytes += data.length
       if (rawBytes > MAX_RAW_OUTPUT_BYTES) throw new Error("Isolated runtime emitted an invalid response")
       const callback = frame.channel === "stdout" ? options.onStdoutChunk : options.onStderrChunk
-      await abortable(callback?.(data), operation.signal)
+      if (callback !== undefined) await invokeConsumer(() => callback(data))
       return
     }
     if (frame.type === "record") {
       if (Object.keys(frame).sort().join(",") !== "record,type") throw new Error("Isolated runtime emitted an invalid response")
-      await abortable(options.onRecord?.(frame.record), operation.signal)
-      if (isWorkerEventEnvelope(frame.record)) await abortable(options.onEvent(frame.record.event), operation.signal)
+      if (options.onRecord !== undefined) await invokeConsumer(() => options.onRecord(frame.record))
+      if (isWorkerEventEnvelope(frame.record)) await invokeConsumer(() => options.onEvent(frame.record.event))
       return
     }
     if (frame.type === "terminal" && Object.keys(frame).sort().join(",") === "exitCode,type" && Number.isSafeInteger(frame.exitCode)) {