threadwire 0.1.13 → 0.1.14

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)) {

package/src/isolated-runtime.js

@@ -29,6 +29,7 @@ const GRANT_LEASE_MS = 60_000
 const GRANT_LEASE_MAX_MS = 3_600_000
 const PREFLIGHT_TIMEOUT_MS = 30_000
 const MAX_RAW_OUTPUT_BYTES = 1_048_576
+const WORKER_STOP_GRACE_SECONDS = 3
 
 /** @param {{environment?: NodeJS.ProcessEnv, docker?: DockerApi, fetchImplementation?: typeof fetch, now?: () => number}} [options] */
 export async function startIsolatedRuntime(options = {}) {
@@ -160,21 +161,32 @@ export async function startIsolatedRuntime(options = {}) {
         const releaseIncoming = incomingRequests.acquire("run")
         const bodyOperation = new AbsoluteDeadline(Date.now() + preflightTimeoutMs, {signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime operation timed out"})
         let body
+        let runLifecycle
         try {
-          body = parseRun(await readJson(request, MAX_RUN_BYTES, bodyOperation.signal))
+          if (request.headers["x-threadwire-run-lifecycle"] === "1") {
+            runLifecycle = await readRunLifecycle(request, MAX_RUN_BYTES, bodyOperation.signal)
+            body = parseRun(runLifecycle.value)
+          } else {
+            body = parseRun(await readJson(request, MAX_RUN_BYTES, bodyOperation.signal))
+          }
         } finally {
           bodyOperation.close()
           releaseIncoming()
         }
         const preflight = preflights.consume(body.preflightId)
         if (!preflight) throw new ClientError("Isolated runtime preflight expired")
+        const operationSignal = runLifecycle === undefined
+          ? shutdown.signal
+          : AbortSignal.any([shutdown.signal, runLifecycle.signal])
         const operation = new AbsoluteDeadline(minimumDeadline(preflight.launchDeadlineAt,
           requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)), {
-          signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime launch timed out", disconnectMessage: "Isolated runtime caller disconnected"
+          signal: operationSignal, request, response, timeoutMessage: "Isolated runtime launch timed out", disconnectMessage: "Isolated runtime caller disconnected",
+          destroyRequestOnAbort: runLifecycle === undefined
         })
         const task = taskIdentity(preflight)
         let releaseRun
         let releaseLineage
+        let retainLineage = false
         try {
           releaseRun = activeRuns.acquire(task)
           releaseLineage = activeLineages.acquire(preflight.state.lineage)
@@ -188,6 +200,7 @@ export async function startIsolatedRuntime(options = {}) {
             if (!response.headersSent) response.writeHead(200, {"content-type": "application/x-ndjson"})
             if (!response.write(`${JSON.stringify(frame)}\n`)) await abortable(once(response, "drain"), operation.signal)
           }
+          if (runLifecycle !== undefined && !response.headersSent) response.writeHead(200, {"content-type": "application/x-ndjson"})
           const result = await runIsolatedWorker({
             docker, workerImage, brokerUrl, brokerAdminToken, brokerContainer, relayImage, relayWorkerUrl,
             fetchImplementation, preflight, ...body, task, now, stateRegistry, sessionTtlMs, operation, grantLeaseMs,
@@ -197,9 +210,13 @@ export async function startIsolatedRuntime(options = {}) {
           for (const chunk of result.rawChunks) await writeFrame({type: "chunk", ...chunk})
           await writeFrame({type: "terminal", exitCode: result.exitCode})
           response.end()
+        } catch (error) {
+          if (error instanceof ContainerCleanupConfirmationError) retainLineage = true
+          throw error
         } finally {
           operation.close()
-          releaseLineage?.()
+          runLifecycle?.close()
+          if (!retainLineage) releaseLineage?.()
           releaseRun?.()
           void collectState()
         }
@@ -209,7 +226,9 @@ export async function startIsolatedRuntime(options = {}) {
       response.end()
     } catch (error) {
       if (response.headersSent) {
-        if (!response.writableEnded && !response.destroyed) response.end(`${JSON.stringify({type: "terminal", exitCode: 1})}\n`)
+        if (!response.writableEnded && !response.destroyed) {
+          response.end(error instanceof ContainerCleanupConfirmationError ? undefined : `${JSON.stringify({type: "terminal", exitCode: 1})}\n`)
+        }
         return
       }
       sendJson(response, error instanceof ClientError ? 400 : 503, {
@@ -367,6 +386,9 @@ export async function runIsolatedWorker(options) {
   let grantRenewalTimer
   let runTracked = false
   let runStage = "state"
+  let workerResult
+  let runError
+  let cleanupFailure
   const operation = options.operation
   const worktreeSubpath = options.worktreeVolume === undefined
     ? ""
@@ -632,10 +654,10 @@ export async function runIsolatedWorker(options) {
         throw error
       }
     }
-    return result
+    workerResult = result
   } catch (error) {
     process.stderr.write(`threadwire-runtime: isolated run failed at ${runStage}\n`)
-    throw error
+    runError = error
   } finally {
     let resourcesRemoved = true
     if (grantRenewalTimer !== undefined) clearInterval(grantRenewalTimer)
@@ -658,10 +680,17 @@ export async function runIsolatedWorker(options) {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: validator cleanup failed\n")
     })
-    if (containerId !== undefined) await cleanupDocker(() => options.docker.removeContainer(containerId, cleanupOptions())).catch(() => {
-      resourcesRemoved = false
-      process.stderr.write("threadwire-isolated-runtime: worker cleanup failed\n")
-    })
+    if (containerId !== undefined) {
+      try {
+        await stopAndRemoveWorkerContainer(options.docker, containerId, cleanupOptions())
+      } catch (error) {
+        resourcesRemoved = false
+        cleanupFailure = error instanceof ContainerCleanupConfirmationError
+          ? error
+          : new ContainerCleanupConfirmationError({cause: error})
+        process.stderr.write("threadwire-isolated-runtime: worker cleanup failed\n")
+      }
+    }
     if (relayId !== undefined) await cleanupDocker(() => options.docker.removeContainer(relayId, cleanupOptions())).catch(() => {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: relay cleanup failed\n")
@@ -677,16 +706,43 @@ export async function runIsolatedWorker(options) {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: egress network cleanup failed\n")
     })
-    if (freshState && !keepFreshState) await cleanupDocker(() => options.docker.removeVolume(state.volume, cleanupOptions())).catch(() => { resourcesRemoved = false })
+    if (freshState && !keepFreshState && resourcesRemoved) await cleanupDocker(() => options.docker.removeVolume(state.volume, cleanupOptions())).catch(() => { resourcesRemoved = false })
     if (runTracked && resourcesRemoved) await options.stateRegistry.completeRun(runId, cleanupOperation.signal).catch(() => {})
     emergencyCleanup?.close()
   }
+  if (cleanupFailure !== undefined) throw cleanupFailure
+  if (runError !== undefined) throw runError
+  return workerResult
 }
 
 async function cleanupDocker(operation) {
   return operation()
 }
 
+async function stopAndRemoveWorkerContainer(docker, containerId, requestOptions) {
+  let inspection = await docker.inspectContainer(containerId, requestOptions)
+  if (typeof inspection?.State?.Running !== "boolean") throw new Error("Worker container state unavailable")
+  if (inspection.State.Running) {
+    await docker.stopContainer(containerId, WORKER_STOP_GRACE_SECONDS, requestOptions)
+    inspection = await docker.inspectContainer(containerId, requestOptions)
+    if (typeof inspection?.State?.Running !== "boolean") throw new Error("Worker container state unavailable")
+    if (inspection.State.Running) {
+      await docker.killContainer(containerId, "KILL", requestOptions)
+      inspection = await docker.inspectContainer(containerId, requestOptions)
+      if (inspection?.State?.Running !== false) throw new ContainerCleanupConfirmationError()
+    }
+  }
+  await docker.removeContainer(containerId, requestOptions)
+}
+
+class ContainerCleanupConfirmationError extends Error {
+  /** @param {{cause?: unknown}} [options] */
+  constructor(options = {}) {
+    super("Worker container cleanup could not be confirmed", options)
+    this.name = "ContainerCleanupConfirmationError"
+  }
+}
+
 export async function prepareStateVolume(docker, state, fresh, requestOptions) {
   if (fresh) await docker.createVolume(state.volume, state.labels, requestOptions)
   const volume = await docker.inspectVolume(state.volume, requestOptions).catch(() => undefined)
@@ -1069,6 +1125,84 @@ async function readJson(request, capacity, signal) {
   }
 }
 
+function readRunLifecycle(request, capacity, signal) {
+  const cancellation = new AbortController()
+  /** @type {Buffer[]} */
+  const chunks = []
+  let bytes = 0
+  let parsed = false
+  let settled = false
+  const cancel = (reason) => cancellation.abort(reason instanceof Error ? reason : new Error("Isolated runtime caller cancelled"))
+  const close = () => {
+    request.off("data", onData)
+    request.off("end", onEnd)
+    request.off("aborted", onAborted)
+    request.off("error", onError)
+    signal?.removeEventListener("abort", onSignal)
+  }
+  /** @type {(value: {value: unknown, signal: AbortSignal, close: () => void}) => void} */
+  let resolveLifecycle
+  /** @type {(error: Error) => void} */
+  let rejectLifecycle
+  const fail = (error) => {
+    if (parsed) {
+      cancel(error)
+      return
+    }
+    if (settled) return
+    settled = true
+    close()
+    rejectLifecycle(error)
+  }
+  const onData = (chunk) => {
+    if (parsed) {
+      fail(new ClientError("Invalid request"))
+      return
+    }
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    bytes += buffer.length
+    if (bytes > capacity) {
+      fail(new ClientError("Request exceeded capacity"))
+      return
+    }
+    chunks.push(buffer)
+    const combined = Buffer.concat(chunks, bytes)
+    const newline = combined.indexOf(0x0a)
+    if (newline < 0) return
+    if (newline !== combined.length - 1) {
+      fail(new ClientError("Invalid request"))
+      return
+    }
+    let value
+    try {
+      value = JSON.parse(combined.subarray(0, newline).toString("utf8"))
+    } catch {
+      fail(new ClientError("Invalid request"))
+      return
+    }
+    parsed = true
+    settled = true
+    resolveLifecycle({value, signal: cancellation.signal, close})
+  }
+  const onEnd = () => parsed
+    ? cancel(new Error("Isolated runtime caller cancelled"))
+    : fail(new ClientError("Invalid request"))
+  const onAborted = () => fail(new Error("Isolated runtime caller disconnected"))
+  const onError = (error) => fail(error)
+  const onSignal = () => fail(signal.reason instanceof Error ? signal.reason : new Error("Isolated runtime operation aborted"))
+  const lifecycle = new Promise((resolve, reject) => {
+    resolveLifecycle = resolve
+    rejectLifecycle = reject
+  })
+  request.on("data", onData)
+  request.once("end", onEnd)
+  request.once("aborted", onAborted)
+  request.once("error", onError)
+  if (signal?.aborted) onSignal()
+  else signal?.addEventListener("abort", onSignal, {once: true})
+  return lifecycle
+}
+
 function requireControl(value, expected) {
   if (value !== `Bearer ${expected}`) throw new ClientError("Request denied")
 }

package/src/jsonl-record-spool.js

@@ -0,0 +1,178 @@
+// @ts-check
+
+import {closeSync, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, writeSync} from "node:fs"
+import {tmpdir} from "node:os"
+import {isAbsolute, join, normalize} from "node:path"
+
+/**
+ * Single-owner byte-oriented spool for one worker's pending JSONL record.
+ *
+ * Worker stdout is consumed as raw bytes. A pending record (bytes not yet
+ * terminated by `\n`) is kept in bounded memory while it stays below
+ * `memoryBytes`; beyond that threshold it spills exactly once to one private
+ * run-scoped file, writing every byte segment exactly once. Newline scanning
+ * happens on raw bytes: `0x0a` can never appear inside a multibyte UTF-8
+ * sequence, so newline boundaries are preserved across arbitrary chunk splits
+ * and completed records always decode as well-formed UTF-8.
+ *
+ * `maxBytes` is a separate absolute pending-record cap: unterminated or
+ * malformed output can never consume unbounded memory, disk, or JSON.parse
+ * allocation. `close()` is idempotent and removes every spool artifact; the
+ * owner calls it on every settlement path.
+ */
+export class JsonlRecordSpool {
+  /** @param {{memoryBytes: number, maxBytes: number, directory?: string}} options */
+  constructor(options) {
+    this.memoryBytes = positiveSafeInteger(options.memoryBytes, "memoryBytes")
+    this.maxBytes = positiveSafeInteger(options.maxBytes, "maxBytes")
+    const directory = options.directory ?? tmpdir()
+    if (!isAbsolute(directory) || normalize(directory) !== directory) throw new Error("directory must be a normalized absolute path")
+    this.directory = directory
+    /** @type {Buffer[]} */
+    this.segments = []
+    this.pendingBytes = 0
+    /** @type {{fd: number, path: string} | null} */
+    this.file = null
+    /** @type {string | null} */
+    this.ownedDirectory = null
+    this.closed = false
+  }
+
+  /**
+   * Consume one stdout chunk and yield each completed record in order, decoded
+   * as UTF-8 without the terminating newline. Scanning advances only as the
+   * owner consumes records, so terminal protocol completion can leave trailing
+   * bytes in the same chunk untouched.
+   * @param {Buffer} chunk
+   * @returns {Generator<string>}
+   * @yields {string}
+   */
+  *push(chunk) {
+    if (this.closed) throw new Error("JSONL record spool is closed")
+    let segmentStart = 0
+    for (let index = 0; index < chunk.length; index += 1) {
+      if (chunk[index] !== 0x0a) continue
+      const record = this.completeRecord(chunk.subarray(segmentStart, index))
+      segmentStart = index + 1
+      try {
+        yield record
+      } finally {
+        this.removeOwnedDirectory()
+      }
+    }
+    if (segmentStart < chunk.length) this.append(chunk.subarray(segmentStart))
+  }
+
+  /**
+   * End of stream: return the pending record ("" when none) and release it.
+   * @returns {string}
+   */
+  end() {
+    if (this.closed || this.pendingBytes === 0) return ""
+    let record
+    if (this.file === null) {
+      record = Buffer.concat(this.segments, this.pendingBytes).toString("utf8")
+      this.segments = []
+    } else {
+      const file = this.file
+      this.file = null
+      closeSync(file.fd)
+      record = readFileSync(file.path, "utf8")
+      unlinkSync(file.path)
+      this.removeOwnedDirectory()
+    }
+    this.pendingBytes = 0
+    return record
+  }
+
+  /** Idempotent: close the spool file and remove every run-scoped artifact. */
+  close() {
+    if (this.closed) return
+    this.closed = true
+    this.segments = []
+    const file = this.file
+    this.file = null
+    if (file !== null) {
+      closeSync(file.fd)
+      rmSync(file.path, {force: true})
+    }
+    this.removeOwnedDirectory()
+  }
+
+  /**
+   * Finish one record: combine the pending bytes with the final segment and
+   * decode exactly once. A spilled record is closed, read back, and unlinked;
+   * the next oversized record spills into a freshly created file, so at most
+   * one private file ever exists for the run.
+   * @param {Buffer} finalSegment @returns {string}
+   */
+  completeRecord(finalSegment) {
+    const recordBytes = this.pendingBytes + finalSegment.length
+    if (recordBytes > this.maxBytes) throw new StdoutRecordTooLargeError()
+    if (this.file === null && recordBytes <= this.memoryBytes) {
+      const record = this.pendingBytes === 0
+        ? finalSegment.toString("utf8")
+        : Buffer.concat([...this.segments, finalSegment], recordBytes).toString("utf8")
+      this.segments = []
+      this.pendingBytes = 0
+      return record
+    }
+    if (this.file === null) this.append(finalSegment)
+    else {
+      this.pendingBytes = recordBytes
+      writeSync(this.file.fd, finalSegment)
+    }
+    const file = this.file
+    if (file === null) throw new Error("JSONL record spool file is unavailable")
+    this.file = null
+    closeSync(file.fd)
+    const record = readFileSync(file.path, "utf8")
+    unlinkSync(file.path)
+    this.pendingBytes = 0
+    return record
+  }
+
+  /** @param {Buffer} segment */
+  append(segment) {
+    this.pendingBytes += segment.length
+    if (this.pendingBytes > this.maxBytes) throw new StdoutRecordTooLargeError()
+    if (this.file !== null) {
+      writeSync(this.file.fd, segment)
+      return
+    }
+    if (this.pendingBytes <= this.memoryBytes) {
+      this.segments.push(segment)
+      return
+    }
+    // First threshold crossing: create the private run-scoped file and write
+    // each buffered segment exactly once, in order.
+    this.ownedDirectory = mkdtempSync(join(this.directory, "threadwire-record-"))
+    const path = join(this.ownedDirectory, "pending-record")
+    const fd = openSync(path, "wx", 0o600)
+    this.file = {fd, path}
+    for (const buffered of this.segments) writeSync(fd, buffered)
+    this.segments = []
+    writeSync(fd, segment)
+  }
+
+  /** Remove the current record's private spill directory, if one exists. */
+  removeOwnedDirectory() {
+    const directory = this.ownedDirectory
+    if (directory === null) return
+    rmSync(directory, {recursive: true, force: true})
+    this.ownedDirectory = null
+  }
+}
+
+export class StdoutRecordTooLargeError extends Error {
+  constructor() {
+    super("Worker stdout record exceeded the configured byte capacity")
+    this.name = "StdoutRecordTooLargeError"
+  }
+}
+
+/** @param {number} value @param {string} name */
+function positiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive safe integer`)
+  return value
+}

package/src/kimi-oauth-store.js

@@ -7,6 +7,7 @@ import {dirname, isAbsolute, join} from "node:path"
 
 const MAX_CREDENTIAL_BYTES = 65_536
 const MAX_TOKEN_BYTES = 8_192
+const CURRENT_TOKEN_SAFETY_MARGIN_SECONDS = 30
 const CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098"
 const TOKEN_URL = "https://auth.kimi.com/api/oauth/token"
 const EXACT_KEYS = ["access_token", "expires_at", "expires_in", "refresh_token", "scope", "token_type"]
@@ -117,6 +118,19 @@ export async function openKimiOAuthStore(options) {
       refreshInFlight = operation
       return operation
     },
+    /**
+     * Non-mutating read for observational callers: returns the already-loaded
+     * access token only when it stays valid beyond a fixed 30-second safety
+     * margin. It never fetches, refreshes, persists, renames, chmods, or
+     * tombstones; logged-out credentials fail with the fixed needs-login error
+     * and expired or near-expiry credentials fail with the fixed
+     * refresh-required error.
+     */
+    async getCurrentAccessToken() {
+      if (credential.access_token.length === 0) throw needsLogin()
+      if (credential.expires_at - now() <= CURRENT_TOKEN_SAFETY_MARGIN_SECONDS) throw refreshRequired()
+      return credential.access_token
+    },
     async health() {
       return credential.access_token.length === 0
         ? {ready: false, needsLogin: true}
@@ -263,5 +277,7 @@ function record(value) { return typeof value === "object" && value !== null && !
 function unavailable() { return new Error("Kimi OAuth credential file is unavailable") }
 /** @returns {Error} */
 function needsLogin() { return new Error("Kimi OAuth credential was rejected; re-login required") }
+/** @returns {Error} */
+function refreshRequired() { return new Error("Kimi OAuth credential requires refresh") }
 /** @param {unknown} [cause] @returns {Error} */
 function refreshUnavailable(cause) { return new Error("Kimi OAuth refresh is unavailable", cause === undefined ? undefined : {cause}) }