threadwire 0.1.25 → 0.1.27

package/src/isolated-worker.js

@@ -1,7 +1,8 @@
 // @ts-check
 
-import {isAbsolute, normalize} from "node:path"
+import {isAbsolute, join, normalize} from "node:path"
 import {parseThreadwireBinding} from "./threadwire-binding.js"
+import {applyMutationPolicyDefaults} from "./mutation-policy.js"
 
 const DIGEST_IMAGE = /^(?:[^@\s]+@)?sha256:[0-9a-f]{64}$/u
 const SAFE_VALUE = /^[^\0\r\n]+$/u
@@ -18,6 +19,7 @@ const MAX_PROMPT_LENGTH = 524_288
  *   resumeSession?: string,
  *   brokerUrl?: string
  *   worktreeVolume?: {name: string, subpath: string}
+ *   gitOverlayVolume?: {name: string}
  *   workingDirectory: string,
  *   providerArguments: string[],
  *   model?: string,
@@ -29,7 +31,8 @@ const MAX_PROMPT_LENGTH = 524_288
  *   namespace?: string
  *   runId?: string
  *   taskHash?: string
- *   runSeal?: string
+ *   runSeal?: string,
+ *   mutationPolicy?: import("./mutation-policy.js").MutationPolicy
  * }} WorkerSpecOptions
  */
 
@@ -48,6 +51,9 @@ export function buildWorkerContainerSpec(options) {
   if (!validPrompt(options.prompt)) throw new Error("Worker prompt is invalid")
   if (options.resumeSession !== undefined && !SAFE_VALUE.test(options.resumeSession)) throw new Error("Worker resume session is invalid")
   if (!isAbsolute(options.workingDirectory) || !withinWorktree(options.workingDirectory)) throw new Error("Worker cwd is invalid")
+  const policy = applyMutationPolicyDefaults(options.mutationPolicy)
+  const worktreeReadOnly = !policy.worktreeEdit
+  const gitOverlayReadOnly = policy.worktreeEdit && !policy.commit
   const commonEnvironment = [
     "HOME=/home/worker",
     "TMPDIR=/tmp",
@@ -62,23 +68,44 @@ export function buildWorkerContainerSpec(options) {
     `OPENAI_BASE_URL=${options.brokerUrl ?? "http://model-broker:8789/v1"}`,
     `OPENAI_API_KEY=${options.brokerToken}`,
     `CODEX_API_KEY=${options.brokerToken}`,
-    `THREADWIRE_CODEX_ARGUMENTS=${JSON.stringify(options.providerArguments)}`
+    `THREADWIRE_CODEX_ARGUMENTS=${JSON.stringify(options.providerArguments)}`,
+    ...(gitOverlayReadOnly ? ["THREADWIRE_GIT_OVERLAY_READ_ONLY=true"] : [])
   ]
   const worktreeMount = options.worktreeVolume === undefined
     ? {
       Type: "bind",
       Source: options.worktree,
       Target: "/worktree",
-      ReadOnly: false,
+      ReadOnly: worktreeReadOnly,
       BindOptions: {Propagation: "rprivate"}
     }
     : {
       Type: "volume",
       Source: options.worktreeVolume.name,
       Target: "/worktree",
-      ReadOnly: false,
+      ReadOnly: worktreeReadOnly,
       VolumeOptions: {Subpath: options.worktreeVolume.subpath}
     }
+  const mounts = [worktreeMount, {Type: "volume", Source: options.stateVolume, Target: "/home/worker", ReadOnly: false}]
+  if (gitOverlayReadOnly) {
+    if (options.worktreeVolume === undefined) {
+      mounts.push({
+        Type: "bind",
+        Source: join(options.worktree, ".git"),
+        Target: "/worktree/.git",
+        ReadOnly: true,
+        BindOptions: {Propagation: "rprivate"}
+      })
+    } else {
+      if (options.gitOverlayVolume === undefined) throw new Error("Git metadata volume is required for read-only overlay in volume mode")
+      mounts.push({
+        Type: "volume",
+        Source: options.gitOverlayVolume.name,
+        Target: "/worktree/.git",
+        ReadOnly: true
+      })
+    }
+  }
   return {
     Image: options.image,
     Labels: {
@@ -101,10 +128,7 @@ export function buildWorkerContainerSpec(options) {
     NetworkDisabled: false,
     HostConfig: {
       AutoRemove: false,
-      Mounts: [
-        worktreeMount,
-        {Type: "volume", Source: options.stateVolume, Target: "/home/worker", ReadOnly: false}
-      ],
+      Mounts: mounts,
       CapDrop: ["ALL"],
       NetworkMode: options.networkName,
       ReadonlyRootfs: true,
@@ -151,6 +175,12 @@ export function buildKimiWorkerContainerSpec(options) {
   const user = `${binding.runtime.uid}:${binding.runtime.gid}`
   const uid = binding.runtime.uid
   const gid = binding.runtime.gid
+  const policy = applyMutationPolicyDefaults(options.mutationPolicy)
+  // Kimi source is a single named volume and the entrypoint rejects any nested
+  // mount beneath it. The only filesystem boundary that prevents git metadata
+  // mutation is a read-only source mount, so denying commits also makes the
+  // source read-only; callers that need edits must allow both edit and commit.
+  const effectiveSourceReadOnly = binding.source.readOnly || !policy.worktreeEdit || !policy.commit
   const environment = [
     "PATH=/usr/local/bin:/usr/bin:/bin",
     "NODE_VERSION=",
@@ -165,7 +195,7 @@ export function buildKimiWorkerContainerSpec(options) {
     `THREADWIRE_SOURCE_TARGET=${binding.source.target}`,
     `THREADWIRE_CONTEXT_TARGET=${binding.context.target}`,
     `THREADWIRE_TASK_ID=${binding.taskId}`,
-    `THREADWIRE_SOURCE_READ_ONLY=${binding.source.readOnly}`,
+    `THREADWIRE_SOURCE_READ_ONLY=${effectiveSourceReadOnly}`,
     `THREADWIRE_EXPECTED_REVISION=${binding.source.revision}`,
     `THREADWIRE_CONTEXT_MANIFEST_DIGEST=${binding.context.digests.manifest}`,
     `THREADWIRE_CONTEXT_CONTENT_DIGEST=${binding.context.digests.content}`,
@@ -183,7 +213,7 @@ export function buildKimiWorkerContainerSpec(options) {
     HostConfig: {
       ...workerHostConfig(options.networkName, uid, gid),
       Mounts: [
-        {Type: "volume", Source: binding.source.volume, Target: binding.source.target, ReadOnly: binding.source.readOnly},
+        {Type: "volume", Source: binding.source.volume, Target: binding.source.target, ReadOnly: effectiveSourceReadOnly},
         {Type: "volume", Source: binding.context.volume, Target: binding.context.target, ReadOnly: true},
         {Type: "volume", Source: options.stateVolume, Target: "/state", ReadOnly: false}
       ]
@@ -191,6 +221,104 @@ export function buildKimiWorkerContainerSpec(options) {
   }
 }
 
+/**
+ * Build an offline, credential-free helper container that snapshots a Kimi
+ * source volume using the runtime image's git snapshot script. The helper has
+ * no network, no secrets, and mounts only the source volume read-only. It runs
+ * as the binding's runtime identity so it can read the source volume.
+ * @param {{image: string, sourceVolume: string, sourceTarget: string, name: string, labels: Record<string, string>, uid: number, gid: number}} options
+ */
+export function buildKimiSourceSnapshotSpec(options) {
+  if (!DIGEST_IMAGE.test(options.image)) throw new Error("Snapshot image must use an immutable digest")
+  if (!SAFE_VALUE.test(options.sourceVolume)) throw new Error("Snapshot source volume is invalid")
+  if (!SAFE_VALUE.test(options.sourceTarget)) throw new Error("Snapshot source target is invalid")
+  if (!SAFE_VALUE.test(options.name)) throw new Error("Snapshot name is invalid")
+  if (!plainStringRecord(options.labels)) throw new Error("Snapshot labels are invalid")
+  if (!Number.isSafeInteger(options.uid) || options.uid < 1) throw new Error("Snapshot uid is invalid")
+  if (!Number.isSafeInteger(options.gid) || options.gid < 1) throw new Error("Snapshot gid is invalid")
+  return {
+    Image: options.image,
+    Labels: {...options.labels},
+    Entrypoint: ["node"],
+    Cmd: ["/opt/threadwire/docker/kimi-source-snapshot.mjs", options.sourceTarget],
+    Env: [
+      "HOME=/tmp",
+      "PATH=/usr/local/bin:/usr/bin:/bin"
+    ],
+    WorkingDir: "/tmp",
+    User: `${options.uid}:${options.gid}`,
+    NetworkDisabled: true,
+    HostConfig: {
+      AutoRemove: false,
+      Mounts: [
+        {Type: "volume", Source: options.sourceVolume, Target: options.sourceTarget, ReadOnly: true}
+      ],
+      CapDrop: ["ALL"],
+      NetworkMode: "none",
+      ReadonlyRootfs: true,
+      SecurityOpt: ["no-new-privileges"],
+      PidsLimit: 32,
+      Memory: 268_435_456,
+      NanoCpus: 500_000_000,
+      Tmpfs: {"/tmp": `rw,noexec,nosuid,nodev,size=33554432,uid=${options.uid},gid=${options.gid}`},
+      Ulimits: [
+        {Name: "nofile", Soft: 256, Hard: 256},
+        {Name: "core", Soft: 0, Hard: 0},
+        {Name: "fsize", Soft: 67_108_864, Hard: 67_108_864}
+      ]
+    }
+  }
+}
+
+/**
+ * Build an offline, credential-free helper container that copies a Codex
+ * worktree's .git metadata into a per-run Docker volume. The helper mounts only
+ * the source worktree volume read-only (at the exact subpath) and the target
+ * git-metadata volume read-write. It has no network and carries no credentials.
+ * @param {{image: string, sourceVolume: string, sourceSubpath: string, targetVolume: string, name: string, labels: Record<string, string>}} options
+ */
+export function buildGitMetadataSnapshotSpec(options) {
+  if (!DIGEST_IMAGE.test(options.image)) throw new Error("Git metadata snapshot image must use an immutable digest")
+  if (!SAFE_VALUE.test(options.sourceVolume)) throw new Error("Git metadata snapshot source volume is invalid")
+  if (!SAFE_VALUE.test(options.sourceSubpath)) throw new Error("Git metadata snapshot source subpath is invalid")
+  if (!SAFE_VALUE.test(options.targetVolume)) throw new Error("Git metadata snapshot target volume is invalid")
+  if (!SAFE_VALUE.test(options.name)) throw new Error("Git metadata snapshot name is invalid")
+  if (!plainStringRecord(options.labels)) throw new Error("Git metadata snapshot labels are invalid")
+  return {
+    Image: options.image,
+    Labels: {...options.labels},
+    Entrypoint: ["node"],
+    Cmd: ["/opt/threadwire/docker/git-metadata-snapshot.mjs", "/source", "/git-metadata"],
+    Env: [
+      "HOME=/tmp",
+      "PATH=/usr/local/bin:/usr/bin:/bin"
+    ],
+    WorkingDir: "/tmp",
+    User: "0:0",
+    NetworkDisabled: true,
+    HostConfig: {
+      AutoRemove: false,
+      Mounts: [
+        {Type: "volume", Source: options.sourceVolume, Target: "/source", ReadOnly: true, VolumeOptions: {Subpath: options.sourceSubpath}},
+        {Type: "volume", Source: options.targetVolume, Target: "/git-metadata", ReadOnly: false}
+      ],
+      CapDrop: ["ALL"],
+      NetworkMode: "none",
+      ReadonlyRootfs: true,
+      SecurityOpt: ["no-new-privileges"],
+      PidsLimit: 32,
+      Memory: 268_435_456,
+      NanoCpus: 500_000_000,
+      Tmpfs: {"/tmp": "rw,noexec,nosuid,nodev,size=33554432,uid=0,gid=0"},
+      Ulimits: [
+        {Name: "nofile", Soft: 256, Hard: 256},
+        {Name: "core", Soft: 0, Hard: 0},
+        {Name: "fsize", Soft: 67_108_864, Hard: 67_108_864}
+      ]
+    }
+  }
+}
+
 /**
  * A credential-free, offline validator run before a Kimi broker grant exists.
  * @param {{image: string, binding: unknown, labels: Record<string, string>}} options

package/src/model-broker-policy.js

@@ -11,8 +11,19 @@ const ALLOWED_HEADERS = new Set([
   "x-stainless-arch", "x-stainless-lang", "x-stainless-os",
   "x-stainless-package-version", "x-stainless-runtime",
   "x-stainless-runtime-version", "x-stainless-retry-count", "x-stainless-timeout",
-  "x-stainless-async", "originator", "conversation_id", "session_id",
-  "version", "x-codex-turn-metadata"
+  "x-stainless-async", "originator", "conversation_id", "session_id", "session-id",
+  "version", "x-codex-turn-metadata",
+  // Codex CLI Responses API headers observed from @openai/codex 0.147.0. These are replayed
+  // to the upstream OpenAI endpoint only when present; the broker still authorizes the
+  // capability token and validates the body.
+  "openai-beta", "openai-organization", "openai-project",
+  "thread-id", "thread_id",
+  "x-client-request-id",
+  "x-codex-beta-features",
+  "x-codex-installation-id", "x-codex-routing-hint", "x-codex-turn-state",
+  "x-codex-parent-thread-id", "x-codex-window-id",
+  "x-openai-memgen-request", "x-openai-subagent",
+  "x-responsesapi-include-timing-metrics", "x-openai-internal-codex-responses-lite"
 ])
 
 /** @param {{now?: () => number, random?: (bytes: number) => Buffer}} [options] */
@@ -84,7 +95,7 @@ const RESPONSE_KEYS = new Set([
   "model", "input", "instructions", "stream", "tools", "tool_choice",
   "parallel_tool_calls", "previous_response_id", "reasoning", "store",
   "include", "metadata", "max_output_tokens", "temperature", "top_p", "truncation",
-  "prompt_cache_key"
+  "prompt_cache_key", "client_metadata"
 ])
 
 /** @param {Buffer} body @param {string} allowedModel */

package/src/model-broker.js

@@ -29,6 +29,7 @@ export async function startModelBroker(options = {}) {
   /** @type {Map<string, {controller: AbortController, timer: NodeJS.Timeout, sockets: Set<import("node:net").Socket>}>} */
   const grantRuntimes = new Map()
   const fetchImplementation = options.fetchImplementation ?? fetch
+  const diagnosticEnabled = /^(?:1|true)$/iu.test(environment.THREADWIRE_MODEL_BROKER_DIAGNOSTIC ?? "")
   const revokeGrant = async (token) => {
     grants.revoke(token)
     const runtime = grantRuntimes.get(token)
@@ -62,7 +63,7 @@ export async function startModelBroker(options = {}) {
         const listener = createServer((workerRequest, workerResponse) => {
           proxyWorkerRequest(workerRequest, workerResponse, {
             grants, token, grant, credential: () => credential, upstream, fetchImplementation,
-            signal: controller.signal
+            signal: controller.signal, diagnosticEnabled
           }).catch((error) => {
             if (workerResponse.destroyed) return
             process.stderr.write(`threadwire-model-broker: ${error instanceof Error ? error.message : "request failed"}\n`)
@@ -187,18 +188,27 @@ async function proxyWorkerRequest(request, response, options) {
   delete policyHeaders.host
   delete policyHeaders.connection
   delete policyHeaders["transfer-encoding"]
-  validateBrokerRequest({method: request.method, path: request.url, headers: policyHeaders})
-  const suppliedToken = bearerToken(request.headers.authorization)
-  if (suppliedToken !== options.token) throw new Error("Broker grant token mismatch")
-  const grant = options.grants.authorize(suppliedToken, {
-    provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
-  })
-  const body = await readBody(request, options.signal)
-  throwIfAborted(options.signal)
-  options.grants.authorize(suppliedToken, {
-    provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
-  })
-  validateResponsesBody(body, grant.model)
+  /** @type {Buffer | undefined} */
+  let body
+  try {
+    validateBrokerRequest({method: request.method, path: request.url, headers: policyHeaders})
+    const suppliedToken = bearerToken(request.headers.authorization)
+    if (suppliedToken !== options.token) throw new Error("Broker grant token mismatch")
+    const grant = options.grants.authorize(suppliedToken, {
+      provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
+    })
+    body = await readBody(request, options.signal)
+    throwIfAborted(options.signal)
+    options.grants.authorize(suppliedToken, {
+      provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
+    })
+    validateResponsesBody(body, grant.model)
+  } catch (error) {
+    if (options.diagnosticEnabled) {
+      emitBrokerDiagnostic(request.method ?? "", request.url ?? "", policyHeaders, body)
+    }
+    throw error
+  }
   throwIfAborted(options.signal)
   const upstreamResponse = await abortable(options.fetchImplementation(new URL("/v1/responses", options.upstream), {
     method: "POST",
@@ -312,6 +322,33 @@ function isClientError(error) {
   return error instanceof Error && /denied|grant|Invalid request|capacity/u.test(error.message)
 }
 
+/**
+ * @param {string} method
+ * @param {string} path
+ * @param {Record<string, unknown>} headers
+ * @param {Buffer | undefined} body
+ */
+function emitBrokerDiagnostic(method, path, headers, body) {
+  const redacted = {
+    method,
+    path,
+    headers: Object.keys(headers).map((header) => header.toLowerCase()).sort(),
+    keys: body === undefined ? [] : topLevelJsonKeys(body.toString("utf8"))
+  }
+  process.stderr.write(`threadwire-model-broker: diagnostic: ${JSON.stringify(redacted)}\n`)
+}
+
+/** @param {string} text */
+function topLevelJsonKeys(text) {
+  try {
+    const value = JSON.parse(text)
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) return Object.keys(value).sort()
+  } catch {
+    // ignore malformed body
+  }
+  return []
+}
+
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }

package/src/mutation-policy.js

@@ -0,0 +1,65 @@
+// @ts-check
+
+/**
+ * Per-run worker mutation capability policy.
+ *
+ * The four capabilities are orthogonal:
+ * - worktreeEdit: modify files in the checked-out worktree
+ * - commit: create local git commits (requires mutating .git metadata)
+ * - push: send refs/objects to a remote git repository
+ * - githubWrite: mutate GitHub state via the GitHub CLI or API
+ *
+ * Omitting a capability is not default-deny: callers that do not supply a
+ * policy retain existing behavior (all capabilities allowed). The security
+ * outcome comes from callers explicitly supplying `false` for a capability.
+ */
+
+/** @typedef {{worktreeEdit: boolean, commit: boolean, push: boolean, githubWrite: boolean}} MutationPolicy */
+
+export const MUTATION_CAPABILITIES = /** @type {const} */ (["worktreeEdit", "commit", "push", "githubWrite"])
+
+/**
+ * Parse a JSON-encoded mutation policy with a closed schema.
+ * Unknown fields and non-boolean values are rejected.
+ * @param {string | undefined} value
+ * @returns {MutationPolicy | undefined}
+ */
+export function parseMutationPolicy(value) {
+  if (value === undefined) return undefined
+  let parsed
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    throw new Error("Invalid mutation policy JSON")
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Mutation policy must be an object")
+  }
+  for (const key of Object.keys(parsed)) {
+    if (!MUTATION_CAPABILITIES.includes(/** @type {typeof MUTATION_CAPABILITIES[number]} */ (key))) {
+      throw new Error(`Unknown mutation policy field: ${key}`)
+    }
+  }
+  const policy = applyMutationPolicyDefaults(/** @type {Partial<MutationPolicy>} */ (parsed))
+  for (const capability of MUTATION_CAPABILITIES) {
+    if (typeof policy[capability] !== "boolean") {
+      throw new Error(`Mutation policy ${capability} must be a boolean`)
+    }
+  }
+  return policy
+}
+
+/**
+ * Fill omitted capabilities with the existing-behavior default (allowed).
+ * Does not mutate the input object.
+ * @param {Partial<MutationPolicy> | undefined} value
+ * @returns {MutationPolicy}
+ */
+export function applyMutationPolicyDefaults(value) {
+  return {
+    worktreeEdit: value?.worktreeEdit ?? true,
+    commit: value?.commit ?? true,
+    push: value?.push ?? true,
+    githubWrite: value?.githubWrite ?? true
+  }
+}