threadwire 0.1.6 → 0.1.8

package/src/cli.js

@@ -15,18 +15,24 @@ 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} from "./isolated-runtime-client.js"
+import {validateRelayWriteProviderArguments} from "./relay-write.js"
+import {abortable} from "./absolute-deadline.js"
+import {NormalizedOutput} from "./normalized-output.js"
 
 const HELP = `Usage: threadwire run --provider <codex|claude|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>] [--activity-log <local-jsonl-path>]
+  [--resume-session <provider-session-id>] [--transcript <normalized-jsonl-path>]
+  [--activity-log <local-jsonl-path>]
   [--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>)`
 
-/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, workspaceProfile?: string, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @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 {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
 /**
  * @typedef {{
@@ -40,6 +46,7 @@ const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target
  *   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">
  * }} MainDependencies
  */
 
@@ -52,8 +59,9 @@ export function parseArguments(arguments_) {
   const ownArguments = separator < 0 ? arguments_.slice(1) : arguments_.slice(1, separator)
   const providerArguments = separator < 0 ? [] : arguments_.slice(separator + 1)
   /** @type {Partial<ParsedArguments>} */
-  const parsed = {providerArguments, cwd: process.cwd(), toolMessages: false}
+  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]
     if (option === "--tool-messages") {
@@ -61,7 +69,15 @@ export function parseArguments(arguments_) {
       index += 1
       continue
     }
+    if (option === "--relay-write") {
+      parsed.relayWrite = true
+      index += 1
+      continue
+    }
     const value = ownArguments[index + 1]
+    if (option === "--transcript" && (value === undefined || value.startsWith("--"))) {
+      throw new Error("Missing value for --transcript")
+    }
     if (!option || !value) throw new Error(`Missing value for ${option ?? "option"}`)
     if (option === "--provider") parsed.provider = value
     else if (option === "--target") parsed.target = value
@@ -75,7 +91,12 @@ export function parseArguments(arguments_) {
     else if (option === "--max-output-length") parsed.maxOutputLength = positiveInteger(value, "--max-output-length")
     else if (option === "--resume-session") parsed.resumeSession = sessionId(value)
     else if (option === "--activity-log") parsed.activityLog = resolve(value)
-    else throw new Error(`Unknown option: ${option}`)
+    else if (option === "--transcript") {
+      if (transcriptProvided) throw new Error("Duplicate option: --transcript")
+      if (value.includes("\0")) throw new Error("--transcript path is invalid")
+      parsed.transcript = resolve(value)
+      transcriptProvided = true
+    } else throw new Error(`Unknown option: ${option}`)
     index += 2
   }
   if (!parsed.provider) throw new Error("--provider is required")
@@ -87,6 +108,11 @@ export function parseArguments(arguments_) {
   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.relayWrite && parsed.provider !== "codex") throw new Error("--relay-write is only supported for codex")
   return /** @type {ParsedArguments} */ (parsed)
 }
 
@@ -140,6 +166,10 @@ export async function main(arguments_, dependencies = {}) {
   const sourceEnvironment = dependencies.env ?? process.env
   let environment = sourceEnvironment
   const validateOnly = environment.THREADWIRE_VALIDATE_ONLY === "1"
+  /** @type {NormalizedOutput | undefined} */
+  let normalizedOutput
+  /** @type {DelegatedResultAdmission | undefined} */
+  let runAdmission
   try {
     const parsed = arguments_[0] === "evidence" ? parseEvidenceArguments(arguments_) : parseArguments(arguments_)
     if ("help" in parsed) {
@@ -159,7 +189,13 @@ export async function main(arguments_, dependencies = {}) {
         await store.close()
       }
     }
+    if (!validateOnly) {
+      normalizedOutput = new NormalizedOutput(output, parsed.transcript)
+    }
+    const metrics = new ContextBudgetMetrics()
+    runAdmission = normalizedOutput === undefined ? undefined : new DelegatedResultAdmission({output: normalizedOutput, metrics})
     const target = parseTelegramTarget(parsed.target)
+    if (parsed.relayWrite) validateRelayWriteProviderArguments(parsed.providerArguments)
     const resolvedWorkspace = parsed.workspaceProfile === undefined
       ? undefined
       : await resolveWorkspaceProfile(
@@ -167,8 +203,20 @@ export async function main(arguments_, dependencies = {}) {
         dependencies.workspaceProfileOperations
       )
     if (validateOnly) return 0
-    const metrics = new ContextBudgetMetrics()
-    const admission = new DelegatedResultAdmission({output, metrics})
+    const isolatedRuntimeClient = parsed.relayWrite
+      ? dependencies.isolatedRuntimeClient ?? isolatedRuntimeClientFromEnvironment(sourceEnvironment)
+      : undefined
+    const isolatedPreflight = parsed.relayWrite
+      ? await isolatedRuntimeClient?.preflight({
+        provider: parsed.provider,
+        profile: /** @type {string} */ (parsed.workspaceProfile),
+        repositoryRoot: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).repositoryRoot,
+        cwd: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).cwd,
+        providerArguments: parsed.providerArguments,
+        ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession})
+      })
+      : undefined
+    const admission = /** @type {DelegatedResultAdmission} */ (runAdmission)
     let terminalExitCode = 2
     /** @type {unknown} */
     let evidenceError
@@ -179,12 +227,13 @@ export async function main(arguments_, dependencies = {}) {
     /** @type {EvidenceStore | undefined} */
     let ownedEvidenceStore
     let evidencePayloadBytes = 0
+    const launchDeadline = isolatedPreflight?.deadline
     try {
-      environment = await resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"])
-      const prompt = await readPrompt(parsed, dependencies.input ?? stdin)
+      environment = await boundedLaunch(resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"]), launchDeadline)
+      const prompt = await readPrompt(parsed, dependencies.input ?? stdin, launchDeadline?.signal)
       const configuredEvidenceRoot = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (dependencies.evidenceStore === undefined && configuredEvidenceRoot !== undefined) {
-        ownedEvidenceStore = await EvidenceStore.open({root: configuredEvidenceRoot})
+        ownedEvidenceStore = await boundedLaunch(EvidenceStore.open({root: configuredEvidenceRoot}), launchDeadline)
       }
       const evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
       if (evidenceStore !== undefined) {
@@ -194,16 +243,22 @@ export async function main(arguments_, dependencies = {}) {
         })
         evidence = await evidenceStore.createArtifact(evidenceOwner, {
           contentType: "text/plain; charset=utf-8",
-          redactions: await collectEvidenceRedactions(environment)
+          redactions: await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
         })
       }
       if (evidence !== undefined) {
         const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
-        await evidence.append("prompt", promptEvidence)
+        await boundedLaunch(evidence.append("prompt", promptEvidence), launchDeadline)
         evidencePayloadBytes += Buffer.byteLength(promptEvidence, "utf8")
       }
       const providerEnvironment = buildProviderEnvironment(environment)
-      const provider = createProvider(parsed.provider, parsed.providerArguments, prompt, parsed.resumeSession, providerEnvironment)
+      const provider = createProvider(
+        parsed.provider,
+        parsed.providerArguments,
+        prompt,
+        parsed.resumeSession,
+        parsed.relayWrite ? {} : providerEnvironment
+      )
       if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
       if (parsed.workspaceProfile !== undefined) {
         if (resolvedWorkspace === undefined) throw new Error("Workspace profile resolution failed")
@@ -228,7 +283,8 @@ export async function main(arguments_, dependencies = {}) {
           resolvedWorkspace.sourceIdentity
         )
       }
-      const exitCode = await (dependencies.workerRunner ?? runWorker)({
+      /** @type {import("./run-worker.js").RunWorkerOptions} */
+      const workerOptions = {
         executable: provider.executable,
         arguments: provider.arguments,
         cwd: resolvedWorkspace?.cwd ?? parsed.cwd,
@@ -265,8 +321,21 @@ export async function main(arguments_, dependencies = {}) {
           if (evidence === undefined) return undefined
           return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
         }
-      })
-      await control.close()
+      }
+      const exitCode = parsed.relayWrite
+        ? await /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).run({
+          preflightId: /** @type {{preflightId: string}} */ (isolatedPreflight).preflightId,
+          prompt,
+          providerArguments: parsed.providerArguments,
+          ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession}),
+          onEvent: workerOptions.onEvent,
+          onRecord: /** @type {NonNullable<typeof workerOptions.onRecord>} */ (workerOptions.onRecord),
+          ...(workerOptions.onStdoutChunk === undefined ? {} : {onStdoutChunk: workerOptions.onStdoutChunk}),
+          ...(workerOptions.onStderrChunk === undefined ? {} : {onStderrChunk: workerOptions.onStderrChunk}),
+          ...(launchDeadline === undefined ? {} : {deadline: launchDeadline})
+        })
+        : await (dependencies.workerRunner ?? runWorker)(workerOptions)
+      await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
     } finally {
       if (evidence !== undefined) {
@@ -289,13 +358,28 @@ export async function main(arguments_, dependencies = {}) {
       admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
       errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
       activity?.close()
-      await ownedEvidenceStore?.close()
+      await boundedLaunch(ownedEvidenceStore?.close(), launchDeadline).catch(() => {})
+      launchDeadline?.close()
     }
     if (evidenceError !== undefined) throw evidenceError
     return terminalExitCode
   } catch (error) {
-    errorOutput.write(`threadwire: ${safeMessage(error)}\n`)
+    let reportedError = error
+    if (runAdmission !== undefined && !runAdmission.completed) {
+      try {
+        runAdmission.complete({state: "failed", exitCode: 2})
+      } catch (transcriptError) {
+        reportedError = transcriptError
+      }
+    }
+    errorOutput.write(`threadwire: ${safeMessage(reportedError)}\n`)
     return 2
+  } finally {
+    try {
+      normalizedOutput?.close()
+    } catch (error) {
+      errorOutput.write(`threadwire: ${safeMessage(error)}\n`)
+    }
   }
 }
 
@@ -350,21 +434,36 @@ function validateNormalizedWorkerEvent(event) {
   throw new Error("Worker emitted an unknown normalized event kind")
 }
 
-/** @param {ParsedArguments} parsed @param {NodeJS.ReadableStream & {isTTY?: boolean}} input */
-async function readPrompt(parsed, input) {
+/** @param {ParsedArguments} parsed @param {NodeJS.ReadableStream & {isTTY?: boolean}} input @param {AbortSignal | undefined} signal */
+async function readPrompt(parsed, input, signal) {
   let prompt
   if (parsed.prompt !== undefined) prompt = parsed.prompt
-  else if (parsed.promptFile !== undefined) prompt = await readFile(parsed.promptFile, "utf8")
+  else if (parsed.promptFile !== undefined) prompt = await readFile(parsed.promptFile, {encoding: "utf8", signal})
   else {
     if (input.isTTY) throw new Error("A prompt is required via --prompt, --prompt-file, or piped stdin")
     prompt = ""
     input.setEncoding("utf8")
-    for await (const chunk of input) prompt += chunk
+    const abort = () => /** @type {NodeJS.ReadableStream & {destroy?: (error?: unknown) => void}} */ (input).destroy?.(signal?.reason)
+    signal?.addEventListener("abort", abort, {once: true})
+    try {
+      for await (const chunk of input) {
+        if (signal?.aborted) throw signal.reason
+        prompt += chunk
+      }
+    } finally {
+      signal?.removeEventListener("abort", abort)
+    }
   }
   if (prompt.trim().length === 0) throw new Error("Prompt cannot be empty")
   return prompt
 }
 
+/** @param {Promise<unknown> | undefined} promise @param {import("./absolute-deadline.js").AbsoluteDeadline | undefined} deadline */
+function boundedLaunch(promise, deadline) {
+  deadline?.throwIfAborted()
+  return abortable(Promise.resolve(promise), deadline?.signal)
+}
+
 /** @param {unknown} error */
 function safeMessage(error) {
   return error instanceof Error ? error.message : "Unknown error"

package/src/delegated-result-admission.js

@@ -45,7 +45,7 @@ const STATES = new Set(["completed", "failed", "blocked", "needs_decision"])
  */
 
 export class DelegatedResultAdmission {
-  /** @param {{output: NodeJS.WritableStream, metrics?: import("./context-budget-metrics.js").ContextBudgetMetrics}} options */
+  /** @param {{output: {write: (chunk: string) => unknown}, metrics?: import("./context-budget-metrics.js").ContextBudgetMetrics}} options */
   constructor(options) {
     this.output = options.output
     this.metrics = options.metrics

package/src/docker-api.js

@@ -0,0 +1,131 @@
+// @ts-nocheck
+/* eslint-disable jsdoc/require-jsdoc */
+
+import {request as httpRequest} from "node:http"
+
+export class DockerApi {
+  /** @param {{host?: string, requestImplementation?: typeof httpRequest}} [options] */
+  constructor(options = {}) {
+    this.host = options.host ?? process.env.DOCKER_HOST ?? "unix:///var/run/docker.sock"
+    this.requestImplementation = options.requestImplementation ?? httpRequest
+  }
+
+  /** @param {string} method @param {string} path @param {unknown} [body] @param {boolean} [raw] */
+  request(method, path, body, raw = false, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000
+    const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body))
+    const target = dockerTarget(this.host, path)
+    return new Promise((resolve, reject) => {
+      const request = this.requestImplementation({
+        ...target,
+        method,
+        headers: payload === undefined ? {} : {"content-type": "application/json", "content-length": payload.length}
+      }, (response) => {
+        /** @type {Buffer[]} */
+        const chunks = []
+        let bytes = 0
+        response.on("data", (chunk) => {
+          const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+          bytes += buffer.length
+          if (bytes > 8_388_608) {
+            request.destroy(new Error("Docker response exceeded capacity"))
+            return
+          }
+          chunks.push(buffer)
+        })
+        response.on("end", () => {
+          const combined = Buffer.concat(chunks)
+          const content = combined.toString("utf8")
+          const status = response.statusCode ?? 500
+          if (status < 200 || status >= 300) {
+            reject(new Error(`Docker API ${method} ${path} failed (${status})`))
+            return
+          }
+          if (combined.length === 0) {
+            resolve(undefined)
+            return
+          }
+          if (raw) {
+            resolve(combined)
+            return
+          }
+          try {
+            resolve(JSON.parse(content))
+          } catch {
+            resolve(content)
+          }
+        })
+      })
+      request.on("error", reject)
+      const abort = () => request.destroy(options.signal.reason instanceof Error ? options.signal.reason : new Error("Docker request aborted"))
+      if (options.signal?.aborted) abort()
+      else options.signal?.addEventListener("abort", abort, {once: true})
+      const deadline = setTimeout(
+        () => request.destroy(new Error(`Docker API ${method} ${path} timed out`)),
+        timeoutMs
+      )
+      deadline.unref()
+      request.once("close", () => {
+        clearTimeout(deadline)
+        options.signal?.removeEventListener("abort", abort)
+      })
+      if (payload !== undefined) request.end(payload)
+      else request.end()
+    })
+  }
+
+  version(options) { return this.request("GET", "/version", undefined, false, options) }
+  inspectImage(image, options) { return this.request("GET", `/images/${encodeURIComponent(image)}/json`, undefined, false, options) }
+  createNetwork(name, labels = {}, options) {
+    return this.request("POST", "/networks/create", {
+      Name: name,
+      Internal: true,
+      CheckDuplicate: true,
+      EnableIPv6: false,
+      Labels: {"org.threadwire.owner": "isolated-runtime", ...labels}
+    }, false, options)
+  }
+  removeNetwork(id, options) { return this.request("DELETE", `/networks/${encodeURIComponent(id)}`, undefined, false, options) }
+  inspectNetwork(id, options) { return this.request("GET", `/networks/${encodeURIComponent(id)}`, undefined, false, options) }
+  connectNetwork(id, container, aliases = [], options) {
+    return this.request("POST", `/networks/${encodeURIComponent(id)}/connect`, {
+      Container: container,
+      EndpointConfig: {Aliases: aliases}
+    }, false, options)
+  }
+  disconnectNetwork(id, container, options) {
+    return this.request("POST", `/networks/${encodeURIComponent(id)}/disconnect`, {Container: container, Force: true}, false, options)
+  }
+  createContainer(name, spec, options) {
+    return this.request("POST", `/containers/create?name=${encodeURIComponent(name)}`, spec, false, options)
+  }
+  listContainers(labels = {}, all = true, options) {
+    const filters = {label: Object.entries(labels).map(([key, value]) => `${key}=${value}`)}
+    return this.request("GET", `/containers/json?all=${all ? 1 : 0}&filters=${encodeURIComponent(JSON.stringify(filters))}`, undefined, false, options)
+  }
+  listNetworks(labels = {}, options) {
+    const filters = {label: Object.entries(labels).map(([key, value]) => `${key}=${value}`)}
+    return this.request("GET", `/networks?filters=${encodeURIComponent(JSON.stringify(filters))}`, undefined, false, options)
+  }
+  startContainer(id, options) { return this.request("POST", `/containers/${encodeURIComponent(id)}/start`, undefined, false, options) }
+  waitContainer(id, options) { return this.request("POST", `/containers/${encodeURIComponent(id)}/wait?condition=not-running`, undefined, false, options) }
+  logs(id, options) { return this.request("GET", `/containers/${encodeURIComponent(id)}/logs?stdout=1&stderr=1`, undefined, true, options) }
+  inspectContainer(id, options) { return this.request("GET", `/containers/${encodeURIComponent(id)}/json`, 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)
+  }
+  listVolumes(labels = {}, options) {
+    const filters = {label: Object.entries(labels).map(([key, value]) => `${key}=${value}`)}
+    return this.request("GET", `/volumes?filters=${encodeURIComponent(JSON.stringify(filters))}`, undefined, false, options)
+  }
+  inspectVolume(name, options) { return this.request("GET", `/volumes/${encodeURIComponent(name)}`, undefined, false, options) }
+  removeVolume(name, options) { return this.request("DELETE", `/volumes/${encodeURIComponent(name)}?force=0`, undefined, false, options) }
+}
+
+function dockerTarget(host, path) {
+  const url = new URL(host)
+  if (url.protocol === "unix:") return {socketPath: url.pathname, path}
+  if (url.protocol !== "tcp:" && url.protocol !== "http:") throw new Error("DOCKER_HOST must use unix or tcp")
+  return {hostname: url.hostname, port: Number(url.port || "2375"), path}
+}

package/src/isolated-runtime-client.js

@@ -0,0 +1,149 @@
+// @ts-nocheck
+/* eslint-disable jsdoc/require-jsdoc */
+
+import {deadlineAfter, abortable, readResponseCapped} from "./absolute-deadline.js"
+
+const MAX_RESPONSE_BYTES = 2_097_152
+const DEFAULT_TIMEOUT_MS = 3_660_000
+const MAX_RAW_OUTPUT_BYTES = 1_048_576
+
+export class IsolatedRuntimeClient {
+  /** @param {{url: string, controlToken: string, timeoutMs?: 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 = positiveDuration(options.timeoutMs, DEFAULT_TIMEOUT_MS)
+  }
+
+  /**
+   * @param {{provider: string, profile: string, repositoryRoot: string, cwd: string, providerArguments: string[], resumeSession?: string, signal?: AbortSignal, deadline?: import("./absolute-deadline.js").AbsoluteDeadline}} request
+   * @returns {Promise<{preflightId: string, deadline?: import("./absolute-deadline.js").AbsoluteDeadline}>}
+   */
+  async preflight(request) {
+    const deadline = request.deadline ?? deadlineAfter(this.timeoutMs, {signal: request.signal, timeoutMessage: "Isolated runtime launch timeout"})
+    const response = await this.request("/preflight", {...request, launchDeadlineAt: deadline.expiresAt}, deadline)
+    if (response.ok !== true || typeof response.preflightId !== "string") throw new Error("Isolated runtime preflight failed")
+    return {preflightId: response.preflightId, deadline}
+  }
+
+  /**
+   * @param {{
+   *   preflightId: string, prompt: string, providerArguments: string[],
+   *   resumeSession?: string,
+   *   signal?: AbortSignal,
+   *   deadline?: import("./absolute-deadline.js").AbsoluteDeadline,
+   *   onEvent: (event: import("./types.js").WorkerEvent) => void | Promise<void>,
+   *   onRecord?: (record: unknown) => void | Promise<void>,
+   *   onStdoutChunk?: (chunk: Buffer) => void | Promise<void>,
+   *   onStderrChunk?: (chunk: Buffer) => void | Promise<void>
+   * }} options
+   */
+  async run(options) {
+    const deadline = options.deadline ?? deadlineAfter(this.timeoutMs, {signal: options.signal, timeoutMessage: "Isolated runtime launch timeout"})
+    const response = await this.request("/run", {
+      preflightId: options.preflightId,
+      prompt: options.prompt,
+      providerArguments: options.providerArguments,
+      ...(options.resumeSession === undefined ? {} : {resumeSession: options.resumeSession})
+    }, deadline)
+    if (!Array.isArray(response.records) || !Array.isArray(response.rawChunks) || !Number.isSafeInteger(response.exitCode)) throw new Error("Isolated runtime emitted an invalid response")
+    let rawBytes = 0
+    const decoded = response.rawChunks.map((item) => {
+      if (!isRecord(item) || Object.keys(item).sort().join(",") !== "channel,data"
+        || (item.channel !== "stdout" && item.channel !== "stderr") || typeof item.data !== "string"
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(item.data)) {
+        throw new Error("Isolated runtime emitted an invalid response")
+      }
+      const data = Buffer.from(item.data, "base64")
+      rawBytes += data.length
+      if (rawBytes > MAX_RAW_OUTPUT_BYTES) throw new Error("Isolated runtime emitted an invalid response")
+      return {channel: item.channel, data}
+    })
+    for (const chunk of decoded) {
+      deadline.throwIfAborted()
+      const callback = chunk.channel === "stdout" ? options.onStdoutChunk : options.onStderrChunk
+      await abortable(callback?.(chunk.data), deadline.signal)
+    }
+    for (const record of response.records) {
+      deadline.throwIfAborted()
+      await abortable(options.onRecord?.(record), deadline.signal)
+      if (isWorkerEventEnvelope(record)) await abortable(options.onEvent(record.event), deadline.signal)
+    }
+    return /** @type {number} */ (response.exitCode)
+  }
+
+  /** @param {string} path @param {unknown} body */
+  async request(path, body, deadline) {
+    const signal = deadline.signal
+    const response = await abortable(this.fetch(`${this.url}${path}`, {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        authorization: `Bearer ${this.controlToken}`,
+        "content-type": "application/json",
+        connection: "close",
+        "x-threadwire-launch-deadline": String(deadline.expiresAt)
+      },
+      body: JSON.stringify(body),
+      signal
+    }), signal)
+    let bytes
+    try {
+      bytes = await readResponseCapped(response, MAX_RESPONSE_BYTES, signal)
+    } catch (error) {
+      if (error instanceof Error && error.message === "Response exceeded capacity") throw new Error("Isolated runtime response exceeded the configured capacity", {cause: error})
+      throw error
+    }
+    if (!response.ok) throw new Error(safeRemoteError(bytes))
+    try {
+      const value = JSON.parse(bytes.toString("utf8"))
+      if (!isRecord(value)) throw new Error()
+      return value
+    } catch {
+      throw new Error("Isolated runtime emitted an invalid response")
+    }
+  }
+}
+
+function positiveDuration(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!Number.isSafeInteger(number) || number < 1 || number > 604_800_000) throw new Error("Invalid isolated runtime client timeout")
+  return number
+}
+/** @param {NodeJS.ProcessEnv} environment */
+export function isolatedRuntimeClientFromEnvironment(environment) {
+  return new IsolatedRuntimeClient({
+    url: nonempty(environment.THREADWIRE_ISOLATED_RUNTIME_URL, "THREADWIRE_ISOLATED_RUNTIME_URL"),
+    controlToken: nonempty(environment.THREADWIRE_ISOLATED_RUNTIME_CONTROL_TOKEN, "THREADWIRE_ISOLATED_RUNTIME_CONTROL_TOKEN"),
+    timeoutMs: environment.THREADWIRE_ISOLATED_RUNTIME_CLIENT_TIMEOUT_MS
+  })
+}
+
+function normalizedUrl(value) {
+  const url = new URL(value)
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("THREADWIRE_ISOLATED_RUNTIME_URL must use HTTP or HTTPS")
+  url.pathname = url.pathname.replace(/\/+$/u, "")
+  url.search = ""
+  url.hash = ""
+  return url.toString().replace(/\/$/u, "")
+}
+
+function nonempty(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0 || /[\r\n]/u.test(value)) throw new Error(`${name} is required`)
+  return value
+}
+
+function safeRemoteError(bytes) {
+  const text = bytes.toString("utf8").trim()
+  return /^[\x20-\x7e]{1,200}$/u.test(text) ? text : "Isolated runtime request failed"
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isWorkerEventEnvelope(value) {
+  return isRecord(value) && value.type === "worker-event" && isRecord(value.event)
+}