threadwire 0.1.5 → 0.1.8

package/src/context-budget-metrics.js

@@ -0,0 +1,180 @@
+// @ts-check
+
+export const METRIC_COUNTER_LIMIT = 2_147_483_647
+export const CONTEXT_GROWTH_METADATA_ALLOWANCE_BYTES = 256
+
+const RAW_CLASSES = ["provider_stdout", "provider_stderr"]
+const REJECTED_CLASSES = ["provider_stream", "stderr", "lifecycle_progress", "diagnostic_progress", "tool_progress"]
+const PROGRESS_CLASSES = ["assistant", "lifecycle", "diagnostic", "tool"]
+const ENVELOPE_FIELDS = [
+  "version", "type", "state", "exitCode", "conclusion", "blocker", "decisionRequest",
+  "continuationHandle", "artifactHandles", "references", "validationSummary"
+]
+
+export class ContextBudgetMetrics {
+  constructor() {
+    this.streamBytes = 0
+    this.streamChunks = 0
+    this.streamBytesByClass = counters(RAW_CLASSES)
+    this.streamChunksByClass = counters(RAW_CLASSES)
+    this.parsedRecords = 0
+    this.parsedRecordsByClass = counters(RAW_CLASSES)
+    this.rejectedBytes = counters(REJECTED_CLASSES)
+    this.rejectedEvents = counters(REJECTED_CLASSES)
+    this.progress = progressCounters()
+    this.artifactBytes = 0
+    this.artifactHandles = 0
+    this.admittedBytes = 0
+    this.admittedTokens = 0
+    this.admittedEnvelopeFields = counters(ENVELOPE_FIELDS)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordRawChildChunk(metricClass, bytes) {
+    addClass(this.streamBytesByClass, metricClass, bytes)
+    addClass(this.streamChunksByClass, metricClass, 1)
+    this.streamBytes = saturatingAdd(this.streamBytes, bytes)
+    this.streamChunks = saturatingAdd(this.streamChunks, 1)
+  }
+
+  /** Backward-compatible name for callers outside the package. @param {string} metricClass @param {number} bytes */
+  recordRawChildEvent(metricClass, bytes) {
+    this.recordRawChildChunk(metricClass, bytes)
+  }
+
+  /** @param {string} metricClass @param {number} [records] */
+  recordParsedProviderRecord(metricClass, records = 1) {
+    addClass(this.parsedRecordsByClass, metricClass, records)
+    this.parsedRecords = saturatingAdd(this.parsedRecords, records)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordRejected(metricClass, bytes) {
+    addClass(this.rejectedBytes, metricClass, bytes)
+    addClass(this.rejectedEvents, metricClass, 1)
+  }
+
+  /** @param {string} metricClass @param {number} bytes */
+  recordProgress(metricClass, bytes, outcome = "delivered") {
+    if (!Object.prototype.hasOwnProperty.call(this.progress, outcome)) throw new Error("Invalid context progress outcome")
+    const target = this.progress[outcome]
+    if (target === undefined) throw new Error("Invalid context progress outcome")
+    addClass(target.bytesByClass, metricClass, bytes)
+    addClass(target.eventsByClass, metricClass, 1)
+    target.bytes = saturatingAdd(target.bytes, bytes)
+    target.events = saturatingAdd(target.events, 1)
+  }
+
+  /** @param {number} bytes @param {number} handles */
+  recordArtifact(bytes, handles) {
+    this.artifactBytes = saturatingAdd(this.artifactBytes, bytes)
+    this.artifactHandles = saturatingAdd(this.artifactHandles, handles)
+  }
+
+  /**
+   * Set the final logical payload size for an artifact containing this snapshot.
+   * The returned fixed point includes the snapshot's own newline-terminated bytes.
+   * @param {number} bytesBeforeMetrics @param {number} handles
+   */
+  projectSelfInclusiveArtifact(bytesBeforeMetrics, handles) {
+    const base = bounded(bytesBeforeMetrics)
+    this.artifactHandles = bounded(handles)
+    this.artifactBytes = base
+    for (let iteration = 0; iteration < 16; iteration += 1) {
+      const projected = saturatingAdd(base, Buffer.byteLength(`${JSON.stringify(this.snapshot())}\n`, "utf8"))
+      if (projected === this.artifactBytes) return projected
+      this.artifactBytes = projected
+    }
+    throw new Error("Context metrics artifact projection did not converge")
+  }
+
+  clearArtifact() {
+    this.artifactBytes = 0
+    this.artifactHandles = 0
+  }
+
+  /** @param {Record<string, unknown>} envelope */
+  recordAdmission(envelope) {
+    const serialized = `${JSON.stringify(envelope)}\n`
+    this.admittedBytes = bounded(Buffer.byteLength(serialized, "utf8"))
+    this.admittedTokens = bounded(Math.ceil(this.admittedBytes / 4))
+    for (const field of ENVELOPE_FIELDS) {
+      if (!Object.prototype.hasOwnProperty.call(envelope, field)) continue
+      this.admittedEnvelopeFields[field] = bounded(Buffer.byteLength(JSON.stringify(envelope[field]), "utf8"))
+    }
+  }
+
+  snapshot() {
+    return {
+      version: 1,
+      units: {bytes: "utf8", tokens: "estimated_ceiling_bytes_div_4", events: "count"},
+      rawChild: {
+        streamBytes: this.streamBytes,
+        streamChunks: this.streamChunks,
+        streamBytesByClass: {...this.streamBytesByClass},
+        streamChunksByClass: {...this.streamChunksByClass},
+        parsedRecords: this.parsedRecords,
+        parsedRecordsByClass: {...this.parsedRecordsByClass}
+      },
+      admitted: {bytes: this.admittedBytes, estimatedTokens: this.admittedTokens},
+      rejected: {bytesByClass: {...this.rejectedBytes}, eventsByClass: {...this.rejectedEvents}},
+      artifacts: {bytes: this.artifactBytes, handles: this.artifactHandles},
+      progress: Object.fromEntries(Object.entries(this.progress).map(([outcome, values]) => [
+        outcome,
+        {bytes: values.bytes, events: values.events, bytesByClass: {...values.bytesByClass}, eventsByClass: {...values.eventsByClass}}
+      ])),
+      admittedEnvelopeFields: {...this.admittedEnvelopeFields},
+      parentContextDeltaBytes: this.admittedBytes
+    }
+  }
+
+  conciseDiagnostic() {
+    return {
+      version: 1,
+      rawBytes: this.streamBytes,
+      rawChunks: this.streamChunks,
+      parsedRecords: this.parsedRecords,
+      admittedBytes: this.admittedBytes,
+      rejectedBytes: sumCounters(this.rejectedBytes),
+      artifactBytes: this.artifactBytes,
+      artifactHandles: this.artifactHandles,
+      progressEvents: this.progress.delivered?.events ?? 0,
+      parentContextDeltaBytes: this.admittedBytes
+    }
+  }
+}
+
+/** @returns {Record<string, {bytes: number, events: number, bytesByClass: Record<string, number>, eventsByClass: Record<string, number>}>} */
+function progressCounters() {
+  return Object.fromEntries(["attempted", "suppressed", "coalesced", "delivered"].map((outcome) => [
+    outcome,
+    {bytes: 0, events: 0, bytesByClass: counters(PROGRESS_CLASSES), eventsByClass: counters(PROGRESS_CLASSES)}
+  ]))
+}
+
+/** @param {string[]} classes */
+function counters(classes) {
+  return Object.fromEntries(classes.map((metricClass) => [metricClass, 0]))
+}
+
+/** @param {Record<string, number>} target @param {string} metricClass @param {number} increment */
+function addClass(target, metricClass, increment) {
+  if (!Object.prototype.hasOwnProperty.call(target, metricClass)) throw new Error("Invalid context metric class")
+  target[metricClass] = saturatingAdd(target[metricClass] ?? 0, increment)
+}
+
+/** @param {number} current @param {number} increment */
+function saturatingAdd(current, increment) {
+  return Math.min(METRIC_COUNTER_LIMIT, current + bounded(increment))
+}
+
+/** @param {number} value */
+function bounded(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid context metric counter")
+  return Math.min(value, METRIC_COUNTER_LIMIT)
+}
+
+/** @param {Record<string, number>} values */
+function sumCounters(values) {
+  return Object.values(values).reduce((total, value) => saturatingAdd(total, value), 0)
+}

package/src/delegated-result-admission.js

@@ -0,0 +1,377 @@
+// @ts-check
+
+import {types as utilTypes} from "node:util"
+import {sanitizeOutput} from "./relay.js"
+
+export const CONCLUSION_LIMIT = 16_384
+export const BLOCKER_LIMIT = 1_024
+export const DECISION_REQUEST_LIMIT = 1_024
+export const CONTINUATION_HANDLE_LIMIT = 512
+export const ARTIFACT_HANDLE_LIMIT = 512
+export const REFERENCE_VALUE_LIMIT = 2_048
+export const VALIDATION_SUMMARY_LIMIT = 2_048
+export const MAX_ARTIFACT_HANDLES = 16
+export const MAX_REFERENCES = 16
+export const MAX_ENVELOPE_BYTES = 98_304
+const MAX_VALIDATION_BUDGET = 256
+
+const CANDIDATE_FIELDS = new Set([
+  "state",
+  "exitCode",
+  "conclusion",
+  "blocker",
+  "decisionRequest",
+  "continuationHandle",
+  "artifactHandles",
+  "references",
+  "validationSummary"
+])
+const STATES = new Set(["completed", "failed", "blocked", "needs_decision"])
+
+/**
+ * @typedef {"completed" | "failed" | "blocked" | "needs_decision"} TerminalState
+ * @typedef {{kind: "commit" | "url", value: string}} AdmissionReference
+ * @typedef {{
+ *   state: TerminalState,
+ *   exitCode: number,
+ *   conclusion?: string,
+ *   blocker?: string,
+ *   decisionRequest?: string,
+ *   continuationHandle?: string,
+ *   artifactHandles?: string[],
+ *   references?: AdmissionReference[],
+ *   validationSummary?: string
+ * }} DelegatedResultCandidate
+ */
+
+export class DelegatedResultAdmission {
+  /** @param {{output: {write: (chunk: string) => unknown}, metrics?: import("./context-budget-metrics.js").ContextBudgetMetrics}} options */
+  constructor(options) {
+    this.output = options.output
+    this.metrics = options.metrics
+    this.conclusion = ""
+    this.conclusionTruncated = false
+    /** @type {string | undefined} */
+    this.continuationHandle = undefined
+    /** @type {string[]} */
+    this.artifactHandles = []
+    /** @type {AdmissionReference[]} */
+    this.references = []
+    this.completed = false
+  }
+
+  /** @param {string} text */
+  appendConclusion(text) {
+    if (typeof text !== "string") throw new Error("Conclusion text must be a string")
+    if (this.conclusionTruncated) return
+    text = wellFormedString(text)
+    const remaining = CONCLUSION_LIMIT - Array.from(this.conclusion).length
+    const characters = Array.from(text)
+    if (characters.length <= remaining) this.conclusion += text
+    else {
+      this.conclusion += characters.slice(0, Math.max(0, remaining - 1)).join("") + "…"
+      this.conclusionTruncated = true
+    }
+  }
+
+  /** @param {unknown} event */
+  acceptConclusionEvent(event) {
+    if (!isPlainObject(event) || !hasExactEnumerableFields(event, ["type", "text", "streamId"])) {
+      throw new Error("Invalid admitted conclusion event")
+    }
+    if (event.type !== "text-delta" || typeof event.text !== "string" || typeof event.streamId !== "string") {
+      throw new Error("Invalid admitted conclusion event")
+    }
+    this.appendConclusion(event.text)
+  }
+
+  /** @param {string} handle */
+  setContinuationHandle(handle) {
+    this.continuationHandle = validateContinuationHandle(handle)
+  }
+
+  /** @param {string} handle */
+  addArtifactHandle(handle) {
+    this.artifactHandles = optionalArtifactHandles([...this.artifactHandles, handle]) ?? []
+  }
+
+  /** @param {string} handle */
+  removeArtifactHandle(handle) {
+    this.artifactHandles = this.artifactHandles.filter((candidate) => candidate !== handle)
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  preview(terminal) {
+    return this.createEnvelope(terminal)
+  }
+
+  /** @param {AdmissionReference} reference */
+  addReference(reference) {
+    this.references = /** @type {AdmissionReference[]} */ (optionalReferences([...this.references, reference]) ?? [])
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  complete(terminal) {
+    if (this.completed) throw new Error("Delegated result already completed")
+    const envelope = this.createEnvelope(terminal)
+    this.completed = true
+    this.metrics?.recordAdmission(envelope)
+    this.output.write(`${JSON.stringify(envelope)}\n`)
+  }
+
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  createEnvelope(terminal) {
+    const safeConclusion = truncateBoundedString(sanitizeOutput(this.conclusion), CONCLUSION_LIMIT)
+    return createDelegatedResultEnvelope({
+      ...terminal,
+      ...(terminal.state !== "completed" || safeConclusion === undefined ? {} : {conclusion: safeConclusion}),
+      ...(this.continuationHandle === undefined ? {} : {continuationHandle: this.continuationHandle}),
+      ...(this.artifactHandles.length === 0 ? {} : {artifactHandles: this.artifactHandles}),
+      ...(this.references.length === 0 ? {} : {references: this.references})
+    })
+  }
+}
+
+/** @param {unknown} candidate */
+export function createDelegatedResultEnvelope(candidate) {
+  const clonedCandidate = cloneTopLevelCandidate(candidate)
+  for (const field of Reflect.ownKeys(clonedCandidate)) {
+    if (typeof field !== "string" || !CANDIDATE_FIELDS.has(field) || !Object.prototype.propertyIsEnumerable.call(clonedCandidate, field)) {
+      throw new Error(`Unknown delegated result candidate field: ${String(field)}`)
+    }
+  }
+  if (typeof clonedCandidate.state !== "string" || !STATES.has(clonedCandidate.state)) {
+    throw new Error("Invalid delegated result terminal state")
+  }
+  if (!Number.isSafeInteger(clonedCandidate.exitCode) || /** @type {number} */ (clonedCandidate.exitCode) < 0) {
+    throw new Error("Invalid delegated result exitCode")
+  }
+  const conclusion = optionalBoundedString(clonedCandidate.conclusion, "conclusion", CONCLUSION_LIMIT)
+  const blocker = optionalBoundedString(clonedCandidate.blocker, "blocker", BLOCKER_LIMIT)
+  const decisionRequest = optionalBoundedString(clonedCandidate.decisionRequest, "decisionRequest", DECISION_REQUEST_LIMIT)
+  const continuationHandle = clonedCandidate.continuationHandle === undefined ? undefined : validateContinuationHandle(clonedCandidate.continuationHandle)
+  const validationSummary = optionalBoundedString(clonedCandidate.validationSummary, "validationSummary", VALIDATION_SUMMARY_LIMIT)
+  const artifactHandles = optionalArtifactHandles(clonedCandidate.artifactHandles)
+  const references = optionalReferences(clonedCandidate.references)
+
+  const envelope = {
+    version: 1,
+    type: "delegated_result",
+    state: /** @type {TerminalState} */ (clonedCandidate.state),
+    exitCode: /** @type {number} */ (clonedCandidate.exitCode),
+    ...(conclusion === undefined ? {} : {conclusion}),
+    ...(blocker === undefined ? {} : {blocker}),
+    ...(decisionRequest === undefined ? {} : {decisionRequest}),
+    ...(continuationHandle === undefined ? {} : {continuationHandle}),
+    ...(artifactHandles === undefined ? {} : {artifactHandles}),
+    ...(references === undefined ? {} : {references}),
+    ...(validationSummary === undefined ? {} : {validationSummary})
+  }
+  if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > MAX_ENVELOPE_BYTES) {
+    throw new Error("Delegated result candidate exceeds the envelope byte limit")
+  }
+  return envelope
+}
+
+/** @param {unknown} value @param {string} field @param {number} limit */
+function optionalBoundedString(value, field, limit) {
+  return value === undefined ? undefined : boundedString(value, field, limit)
+}
+
+/** @param {unknown} value @param {string} field @param {number} limit */
+function boundedString(value, field, limit) {
+  if (typeof value !== "string" || value.length === 0 || wellFormedString(value) !== value || Array.from(value).length > limit) {
+    throw new Error(`Invalid delegated result ${field}`)
+  }
+  return value
+}
+
+/** @param {string | undefined} value @param {number} limit */
+function truncateBoundedString(value, limit) {
+  if (value === undefined) return undefined
+  const characters = Array.from(value)
+  if (characters.length <= limit) return value
+  if (limit <= 1) return "…"
+  return `${characters.slice(0, limit - 1).join("")}…`
+}
+
+/** @param {unknown} value */
+export function validateContinuationHandle(value) {
+  const handle = boundedString(value, "continuationHandle", CONTINUATION_HANDLE_LIMIT)
+  if (
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)*$/u.test(handle)
+    || /^(?:data|file|ftp|ftps|http|https|javascript|mailto|sftp|ssh|urn|ws|wss):/iu.test(handle)
+  ) {
+    throw new Error("Invalid delegated result continuationHandle")
+  }
+  return handle
+}
+
+/** @param {unknown} value */
+function optionalArtifactHandles(value) {
+  if (value === undefined) return undefined
+  return validateClosedArray(value, "artifactHandles", MAX_ARTIFACT_HANDLES).map((item) => artifactHandle(item))
+}
+
+/** @param {unknown} value */
+function artifactHandle(value) {
+  const handle = boundedString(value, "artifactHandles", ARTIFACT_HANDLE_LIMIT)
+  if (!/^\/?[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u.test(handle)) {
+    throw new Error("Invalid delegated result artifactHandles")
+  }
+  const components = handle.split("/").filter((component) => component.length > 0)
+  if (components.some((component) => component === "." || component === "..")) {
+    throw new Error("Invalid delegated result artifactHandles")
+  }
+  return handle
+}
+
+/** @param {unknown} value */
+function optionalReferences(value) {
+  if (value === undefined) return undefined
+  return validateClosedArray(value, "references", MAX_REFERENCES).map((reference) => {
+    if (!isPlainObject(reference) || !hasExactEnumerableFields(reference, ["kind", "value"])) {
+      throw new Error("Invalid delegated result reference")
+    }
+    if (reference.kind !== "commit" && reference.kind !== "url") throw new Error("Invalid delegated result reference kind")
+    const referenceValue = boundedString(reference.value, "references", REFERENCE_VALUE_LIMIT)
+    if (reference.kind === "commit" && !/^[0-9a-f]{7,64}$/iu.test(referenceValue)) {
+      throw new Error("Invalid delegated result commit reference")
+    }
+    if (reference.kind === "url") validateUrlReference(referenceValue)
+    return {kind: reference.kind, value: referenceValue}
+  })
+}
+
+/**
+ * @param {unknown} value
+ * @param {"artifactHandles" | "references"} field
+ * @param {number} limit
+ * @returns {unknown[]}
+ */
+function validateClosedArray(value, field, limit) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > limit) {
+    throw new Error(`Invalid delegated result ${field}`)
+  }
+  const keys = Reflect.ownKeys(value)
+  if (keys.length !== value.length + 1) throw new Error(`Invalid delegated result ${field}`)
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+    if (!descriptor || !("value" in descriptor) || descriptor.enumerable !== true) {
+      throw new Error(`Invalid delegated result ${field}`)
+    }
+  }
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length")
+  if (
+    !lengthDescriptor
+    || !("value" in lengthDescriptor)
+    || lengthDescriptor.value !== value.length
+    || lengthDescriptor.enumerable !== false
+  ) throw new Error(`Invalid delegated result ${field}`)
+  if (keys.some((key) => (
+    key !== "length"
+    && (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/u.test(key) || Number(key) >= value.length)
+  ))) throw new Error(`Invalid delegated result ${field}`)
+  return value
+}
+
+/** @param {string} value */
+function validateUrlReference(value) {
+  if (Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0
+    return codePoint <= 31 || codePoint === 127 || /\s/u.test(character)
+  })) throw new Error("Invalid delegated result URL reference")
+  let parsed
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new Error("Invalid delegated result URL reference")
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new Error("Invalid delegated result URL reference")
+  }
+}
+
+/** @param {unknown} candidate @returns {DelegatedResultCandidate} */
+function cloneTopLevelCandidate(candidate) {
+  if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new Error("Delegated result candidate must be a plain object")
+  }
+  if (utilTypes.isProxy(candidate)) throw new Error("Delegated result candidate must not be a proxy")
+  if (!isPlainObject(candidate)) throw new Error("Delegated result candidate must be a plain object")
+  return /** @type {DelegatedResultCandidate} */ (cloneWithinBudget(candidate, {remaining: MAX_VALIDATION_BUDGET, seen: new WeakSet()}))
+}
+
+/**
+ * @param {unknown} value
+ * @param {{remaining: number, seen: WeakSet<object>}} state
+ * @returns {unknown}
+ */
+function cloneWithinBudget(value, state) {
+  state.remaining -= 1
+  if (state.remaining < 0) throw new Error("Delegated result candidate exceeds the validation budget")
+  if (value === null || typeof value !== "object") return value
+  if (utilTypes.isProxy(value)) throw new Error("Delegated result candidate must not contain proxy values")
+  if (!Array.isArray(value) && !isPlainObject(value)) return value
+  if (state.seen.has(value)) throw new Error("Delegated result candidate must not contain cycles")
+  state.seen.add(value)
+  try {
+    return cloneConcreteContainer(value, state)
+  } finally {
+    state.seen.delete(value)
+  }
+}
+
+/**
+ * @param {Record<PropertyKey, unknown> | unknown[]} value
+ * @param {{remaining: number, seen: WeakSet<object>}} state
+ */
+function cloneConcreteContainer(value, state) {
+  const clone = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value))
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (!descriptor) continue
+    if ("get" in descriptor || "set" in descriptor) {
+      throw new Error("Delegated result candidate must not contain accessor descriptors")
+    }
+    Object.defineProperty(clone, key, {
+      ...descriptor,
+      value: Array.isArray(value) && key === "length" ? descriptor.value : cloneWithinBudget(descriptor.value, state)
+    })
+  }
+  return clone
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} expected */
+function hasExactEnumerableFields(value, expected) {
+  const fields = Reflect.ownKeys(value)
+  return fields.length === expected.length && fields.every((field) => (
+    typeof field === "string"
+    && expected.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
+}
+
+/** @param {string} value */
+function wellFormedString(value) {
+  let result = ""
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index)
+    if (codeUnit >= 0xD800 && codeUnit <= 0xDBFF) {
+      const next = value.charCodeAt(index + 1)
+      if (next >= 0xDC00 && next <= 0xDFFF) {
+        result += value.slice(index, index + 2)
+        index += 1
+      } else result += "\uFFFD"
+    } else if (codeUnit >= 0xDC00 && codeUnit <= 0xDFFF) result += "\uFFFD"
+    else result += value.slice(index, index + 1)
+  }
+  return result
+}

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}
+}