threadwire 0.1.15 → 0.1.18

package/src/delegated-result-admission.js

@@ -105,6 +105,19 @@ export class DelegatedResultAdmission {
     return this.createEnvelope(terminal)
   }
 
+  /** @param {{state: TerminalState, exitCode: number}} terminal */
+  createProviderResult(terminal) {
+    const result = this.createEnvelope(terminal)
+    const assistantContent = truncateBoundedString(sanitizeOutput(this.conclusion), CONCLUSION_LIMIT)
+    return {
+      version: 1,
+      type: "provider_result",
+      providerState: terminal.state === "completed" ? "provider_completed" : "provider_failed",
+      ...(assistantContent === undefined ? {} : {assistantContent}),
+      result
+    }
+  }
+
   /** @param {AdmissionReference} reference */
   addReference(reference) {
     this.references = /** @type {AdmissionReference[]} */ (optionalReferences([...this.references, reference]) ?? [])

package/src/evidence-store.js

@@ -30,6 +30,9 @@ const DEFAULT_LIMITS = Object.freeze({
   retentionMs: 7 * 24 * 60 * 60 * 1000
 })
 const TEXT_CONTENT_TYPES = new Set(["application/json", "application/x-ndjson"])
+const DELIVERY_STATES = new Set([
+  "delivery_pending", "delivery_succeeded", "delivery_failed", "delivery_not_requested"
+])
 
 export class EvidenceAccessError extends Error {
   constructor() {
@@ -80,8 +83,6 @@ export class EvidenceStore {
     this.capabilities = new Map()
     /** @type {WeakSet<object>} */
     this.scopes = new WeakSet()
-    /** @type {Map<string, Set<string>>} */
-    this.redactions = new Map()
     /** @type {Map<string, number>} */
     this.activeReaders = new Map()
     this.storeBytes = baseBytes
@@ -177,7 +178,7 @@ export class EvidenceStore {
 
   /**
    * @param {{destinationId: string, runId: string}} owner
-   * @param {{contentType: string, redactions?: string[]}} options
+   * @param {{contentType: string, redactions?: string[], delivery?: EvidenceDelivery}} options
    */
   async createArtifact(owner, options) {
     this.assertScope(owner)
@@ -186,13 +187,15 @@ export class EvidenceStore {
     const id = randomBytes(32).toString("base64url")
     const handle = `evidence_${randomBytes(32).toString("base64url")}`
     const now = this.clock()
+    const delivery = options.delivery === undefined ? undefined : validateDelivery(options.delivery)
     const metadata = /** @type {EvidenceMetadata} */ ({
       version: 2, id, state: "pending", owner: {...owner}, contentType,
       capabilityHash: capabilityHash(handle),
       policyVersion: 1, framingVersion: 1,
       redactionPolicy: {algorithm: "aes-256-gcm", nonce: "", ciphertext: "", tag: ""},
       payloadCommitment: "A".repeat(43),
-      bytes: 0, storedBytes: 0, lines: 0, events: 0, createdAt: now, expiresAt: now + this.limits.retentionMs
+      bytes: 0, storedBytes: 0, lines: 0, events: 0, createdAt: now, expiresAt: now + this.limits.retentionMs,
+      ...(delivery === undefined ? {} : {delivery})
     })
     metadata.redactionPolicy = encryptRedactions(handle, redactions, metadata)
     const overheadBytes = durableArtifactReservation(metadata)
@@ -230,11 +233,10 @@ export class EvidenceStore {
     if (!file) throw new Error("Evidence pending payload is unavailable")
     this.artifacts.set(id, metadata)
     this.capabilities.set(metadata.capabilityHash, id)
-    this.redactions.set(id, new Set(redactions))
     return new EvidenceWriter(this, metadata, file, handle, finishOperation, redactions, owner)
   }
 
-  /** @param {object} owner @param {unknown} request */
+  /** @param {object} owner @param {unknown} request @returns {Promise<EvidenceReadResult>} */
   async read(owner, request) {
     this.assertScope(owner)
     const validated = validateEvidenceReadRequest(request, this.limits)
@@ -284,14 +286,16 @@ export class EvidenceStore {
           data: binary.toString("base64"),
           encoding: "base64",
           redacted,
-          truncated: truncated || binary.length < selected.length
+          truncated: truncated || binary.length < selected.length,
+          ...deliveryResult(metadata)
         }, this.limits.maxReadBytes)
       }
       return fitSerializedResult({
         contentType: metadata.contentType,
         data: decodeUtf8(selected),
         redacted,
-        truncated
+        truncated,
+        ...deliveryResult(metadata)
       }, this.limits.maxReadBytes)
     } finally {
       const readers = (this.activeReaders.get(id) ?? 1) - 1
@@ -301,7 +305,7 @@ export class EvidenceStore {
     }
   }
 
-  /** @param {unknown} request */
+  /** @param {unknown} request @returns {Promise<EvidenceReadResult>} */
   async readBearer(request) {
     const validated = validateEvidenceReadRequest(request, this.limits)
     const id = this.lookupCapability(validated.handle)
@@ -317,7 +321,44 @@ export class EvidenceStore {
     }
   }
 
-  /** @param {{chatId: string, threadId: number | null, senderId: string}} requester @param {unknown} request */
+  /** @param {object} owner @param {string} handle @param {"delivery_succeeded" | "delivery_failed"} state */
+  recordDelivery(owner, handle, state) {
+    const finish = this.beginOperation()
+    return this.enqueueMaintenance(() => this.recordDeliveryOnce(owner, handle, state)).finally(finish)
+  }
+
+  /** @param {object} owner @param {string} handle @param {"delivery_succeeded" | "delivery_failed"} state */
+  async recordDeliveryOnce(owner, handle, state) {
+    await this.assertRootIdentity()
+    this.assertScope(owner)
+    if (state !== "delivery_succeeded" && state !== "delivery_failed") throw new Error("Invalid terminal delivery state")
+    const id = this.lookupCapability(handle)
+    if (!id) throw new EvidenceAccessError()
+    const metadata = this.artifacts.get(id)
+    if (!metadata || metadata.state !== "ready" || !sameOwner(metadata.owner, owner) || metadata.delivery === undefined) {
+      throw new EvidenceAccessError()
+    }
+    if (metadata.delivery.state !== "delivery_pending") throw new Error("Evidence delivery state is already terminal")
+    const redactions = decryptRedactions(handle, metadata.redactionPolicy, metadata)
+    const updated = /** @type {EvidenceMetadata} */ ({
+      ...metadata,
+      delivery: {identity: metadata.delivery.identity, state}
+    })
+    updated.reservedBytes = durableArtifactReservation(updated)
+    updated.redactionPolicy = encryptRedactions(handle, redactions, updated)
+    const reservationDelta = updated.reservedBytes - metadata.reservedBytes
+    if (reservationDelta > 0) this.reserve(metadata.owner.runId, reservationDelta, 0)
+    try {
+      await atomicJson(this.root, `${id}${META_SUFFIX}`, updated)
+    } catch (error) {
+      if (reservationDelta > 0) this.reserve(metadata.owner.runId, -reservationDelta, 0)
+      throw error
+    }
+    if (reservationDelta < 0) this.reserve(metadata.owner.runId, reservationDelta, 0)
+    this.artifacts.set(id, updated)
+  }
+
+  /** @param {{chatId: string, threadId: number | null, senderId: string}} requester @param {unknown} request @returns {Promise<EvidenceReadResult>} */
   async readTelegram(requester, request) {
     const validated = validateEvidenceReadRequest(request, this.limits)
     const id = this.lookupCapability(validated.handle)
@@ -352,7 +393,6 @@ export class EvidenceStore {
       this.capabilities.delete(metadata.capabilityHash)
       this.release(metadata)
       this.artifactSlots -= 1
-      this.redactions.delete(id)
     }
   }
 
@@ -379,7 +419,6 @@ export class EvidenceStore {
     this.capabilities.delete(metadata.capabilityHash)
     this.release(metadata)
     this.artifactSlots -= 1
-    this.redactions.delete(id)
   }
 
   /** @template T @param {() => Promise<T>} operation @returns {Promise<T>} */
@@ -435,7 +474,6 @@ export class EvidenceStore {
         this.artifactSlots += 1
         this.artifacts.set(id, metadata)
         this.capabilities.set(metadata.capabilityHash, id)
-        this.redactions.set(id, new Set(this.runtimeRedactions))
       } catch {
         await Promise.all([...files].map((suffix) => safeUnlink(this.path(id, suffix))))
       }
@@ -601,7 +639,6 @@ class EvidenceWriter {
       this.store.artifactSlots -= 1
       this.store.artifacts.delete(this.metadata.id)
       this.store.capabilities.delete(this.metadata.capabilityHash)
-      this.store.redactions.delete(this.metadata.id)
       await safeUnlink(this.store.path(this.metadata.id, PENDING_SUFFIX))
       await safeUnlink(this.store.path(this.metadata.id, PAYLOAD_SUFFIX))
       await safeUnlink(this.store.path(this.metadata.id, META_SUFFIX))
@@ -632,7 +669,6 @@ class EvidenceWriter {
     this.store.artifactSlots -= 1
     this.store.artifacts.delete(this.metadata.id)
     this.store.capabilities.delete(this.metadata.capabilityHash)
-    this.store.redactions.delete(this.metadata.id)
     await safeUnlink(this.store.path(this.metadata.id, PENDING_SUFFIX))
     await safeUnlink(this.store.path(this.metadata.id, META_SUFFIX))
     await syncDirectory(this.store.root)
@@ -875,7 +911,7 @@ function utf8Prefix(buffer, limit) {
   return buffer.subarray(0, limit)
 }
 
-/** @param {{contentType: string, data: string, encoding?: string, redacted: boolean, truncated: boolean}} result @param {number} limit */
+/** @param {EvidenceReadResult} result @param {number} limit @returns {EvidenceReadResult} */
 function fitSerializedResult(result, limit) {
   if (Buffer.byteLength(`${JSON.stringify(result)}\n`) <= limit) return result
   let bytes = Buffer.from(result.data, "utf8")
@@ -1313,14 +1349,16 @@ function decryptRedactions(handle, policy, metadata) {
 
 /** @param {EvidenceMetadata} metadata */
 function redactionAad(metadata) {
-  return Buffer.from(JSON.stringify([
+  const values = [
     "threadwire-evidence-policy", metadata.policyVersion, metadata.version, metadata.framingVersion, metadata.id,
     metadata.state,
     metadata.capabilityHash, metadata.owner.destinationId, metadata.owner.runId,
     metadata.contentType, metadata.createdAt, metadata.expiresAt,
     metadata.bytes, metadata.storedBytes, metadata.reservedBytes,
     metadata.lines, metadata.events, metadata.payloadCommitment
-  ]), "utf8")
+  ]
+  if (metadata.delivery !== undefined) values.push(metadata.delivery.identity, metadata.delivery.state)
+  return Buffer.from(JSON.stringify(values), "utf8")
 }
 
 /** @param {EvidenceMetadata} metadata */
@@ -1374,6 +1412,22 @@ function validateRedactions(values) {
   return values
 }
 
+/** @param {unknown} value @returns {EvidenceDelivery} */
+function validateDelivery(value) {
+  if (
+    !plainObject(value) || !exactDataKeys(value, ["identity", "state"])
+    || typeof value.identity !== "string"
+    || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value.identity)
+    || typeof value.state !== "string" || !DELIVERY_STATES.has(value.state)
+  ) throw new Error("Invalid evidence delivery metadata")
+  return /** @type {EvidenceDelivery} */ ({identity: value.identity, state: value.state})
+}
+
+/** @param {EvidenceMetadata} metadata */
+function deliveryResult(metadata) {
+  return metadata.delivery === undefined ? {} : {delivery: {...metadata.delivery}}
+}
+
 /** @param {Record<string, unknown>} left @param {object} right */
 function sameOwner(left, right) {
   return left.destinationId === /** @type {{destinationId?: unknown}} */ (right).destinationId
@@ -1382,11 +1436,13 @@ function sameOwner(left, right) {
 
 /** @param {unknown} value @param {string} id @param {EvidenceLimits} limits */
 function validMetadata(value, id, limits) {
+  const metadataKeys = [
+    "version", "policyVersion", "framingVersion", "id", "state", "owner", "contentType", "capabilityHash",
+    "redactionPolicy", "payloadCommitment", "bytes", "storedBytes", "reservedBytes", "lines", "events", "createdAt", "expiresAt"
+  ]
+  if (plainObject(value) && value.delivery !== undefined) metadataKeys.push("delivery")
   return plainObject(value) && value.version === 2 && value.id === id && value.state === "ready"
-    && exactKeys(value, [
-      "version", "policyVersion", "framingVersion", "id", "state", "owner", "contentType", "capabilityHash",
-      "redactionPolicy", "payloadCommitment", "bytes", "storedBytes", "reservedBytes", "lines", "events", "createdAt", "expiresAt"
-    ])
+    && exactKeys(value, metadataKeys)
     && value.policyVersion === 1 && value.framingVersion === 1
     && plainObject(value.owner) && typeof value.owner.destinationId === "string" && validIdentity(value.owner.destinationId)
     && typeof value.owner.runId === "string" && validIdentity(value.owner.runId)
@@ -1404,6 +1460,17 @@ function validMetadata(value, id, limits) {
     && typeof value.events === "number" && nonnegative(value.events) && value.events <= limits.maxArtifactEvents
     && typeof value.createdAt === "number" && typeof value.expiresAt === "number"
     && nonnegative(value.createdAt) && positive(value.expiresAt) && value.createdAt < value.expiresAt
+    && (value.delivery === undefined || validDelivery(value.delivery))
+}
+
+/** @param {unknown} value */
+function validDelivery(value) {
+  try {
+    validateDelivery(value)
+    return true
+  } catch {
+    return false
+  }
 }
 
 /** @param {unknown} value */
@@ -1455,8 +1522,11 @@ function validateLimits(limits) {
  * owner: {destinationId: string, runId: string}, contentType: string,
  * capabilityHash: string,
  * redactionPolicy: {algorithm: "aes-256-gcm", nonce: string, ciphertext: string, tag: string}, payloadCommitment: string,
- * bytes: number, storedBytes: number, reservedBytes: number, lines: number, events: number, createdAt: number, expiresAt: number
+ * bytes: number, storedBytes: number, reservedBytes: number, lines: number, events: number, createdAt: number, expiresAt: number,
+ * delivery?: EvidenceDelivery
  * }} EvidenceMetadata
+ * @typedef {{identity: string, state: "delivery_pending" | "delivery_succeeded" | "delivery_failed" | "delivery_not_requested"}} EvidenceDelivery
+ * @typedef {{contentType: string, data: string, encoding?: string, redacted: boolean, truncated: boolean, delivery?: EvidenceDelivery}} EvidenceReadResult
  * @typedef {{
  * handle: string,
  * bytes?: {offset: number, limit: number},

package/src/provider-capacity-codex.js

@@ -1,10 +1,9 @@
 // @ts-check
 
 import {spawn} from "node:child_process"
-import {providerExecutable} from "./providers/executable.js"
+import {codexExecutable} from "./providers/executable.js"
 import {CapacityProbeError, DEFAULT_CAPACITY_TIMEOUT_MS, normalizeCodexRateLimits} from "./provider-capacity.js"
 
-const DEFAULT_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
 const MAX_LINE_BYTES = 65_536
 const MAX_LINES = 1_024
 
@@ -16,6 +15,8 @@ const MAX_LINES = 1_024
  * failures classify with fixed, credential-free messages.
  * @param {{
  *   env?: NodeJS.ProcessEnv,
+ *   executable?: string | undefined,
+ *   executableResolution?: Parameters<typeof codexExecutable>[1],
  *   spawnImplementation?: typeof spawn | undefined,
  *   timeoutMs?: number
  * }} options
@@ -25,7 +26,7 @@ export async function probeCodexCapacity(options) {
   const environment = options.env ?? process.env
   const spawnImplementation = options.spawnImplementation ?? spawn
   const timeoutMs = options.timeoutMs ?? DEFAULT_CAPACITY_TIMEOUT_MS
-  const executable = providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment)
+  const executable = options.executable ?? codexExecutable(environment, options.executableResolution)
   const result = await appServerExchange(spawnImplementation, executable, environment, timeoutMs)
   return normalizeCodexRateLimits(result)
 }

package/src/providers/codex.js

@@ -1,16 +1,20 @@
 // @ts-check
 
-import {providerExecutable} from "./executable.js"
+import {codexExecutable} from "./executable.js"
 
-const DEFAULT_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
-
-/** @param {string[]} providerArguments @param {string} prompt @param {string | undefined} [resumeSession] */
-export function buildCodexCommand(providerArguments, prompt, resumeSession, environment = process.env) {
+/**
+ * @param {string[]} providerArguments
+ * @param {string} prompt
+ * @param {string | undefined} [resumeSession]
+ * @param {NodeJS.ProcessEnv} [environment]
+ * @param {Parameters<typeof codexExecutable>[1]} [executableResolution]
+ */
+export function buildCodexCommand(providerArguments, prompt, resumeSession, environment = process.env, executableResolution = {}) {
   rejectOwnedArguments(providerArguments)
   const arguments_ = resumeSession === undefined
     ? ["exec", "--json", ...providerArguments, prompt]
     : ["exec", "resume", "--json", ...providerArguments, resumeSession, prompt]
-  return {executable: providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment), arguments: arguments_}
+  return {executable: codexExecutable(environment, executableResolution), arguments: arguments_}
 }
 
 /** @param {string[]} arguments_ */

package/src/providers/executable.js

@@ -1,10 +1,18 @@
 // @ts-check
 
+import {accessSync, constants, realpathSync, statSync} from "node:fs"
+import {resolve} from "node:path"
+
+const CODEX_STRUCTURAL_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
+const CODEX_FRONT_DOOR_EXECUTABLES = new Set(["/opt/data/bin/codex"])
+
+/** @typedef {(path: string) => boolean} ExecutableProbe */
+/** @typedef {{canonicalize?: ((path: string) => string) | undefined, cwd?: string | undefined, isExecutable?: ExecutableProbe | undefined, warn?: ((warning: string) => void) | undefined}} ExecutableResolutionOptions */
+
 /**
  * Resolve the terminal provider executable Threadwire spawns. The default is the
- * structurally separate libexec adapter (never the /opt/data/bin front-door), so
- * relaying can never recurse. A non-empty environment override supports staged
- * cutover and rollback (for example, pointing back at the previous shim path).
+ * real provider CLI. A non-empty environment override supports staged cutover
+ * and rollback, but only when the override path exists and is executable.
  * @param {string} overrideVariable
  * @param {string} defaultPath
  * @param {NodeJS.ProcessEnv} [environment]
@@ -12,5 +20,85 @@
  */
 export function providerExecutable(overrideVariable, defaultPath, environment = process.env) {
   const override = environment[overrideVariable]
-  return override !== undefined && override.length > 0 ? override : defaultPath
+  if (override !== undefined && override.length > 0) {
+    try {
+      accessSync(override, constants.X_OK)
+      if (!statSync(override).isFile()) {
+        console.error(`threadwire: ${overrideVariable}=${override} is a directory, falling back to ${defaultPath}`)
+        return defaultPath
+      }
+      return override
+    } catch {
+      console.error(`threadwire: ${overrideVariable}=${override} is not executable, falling back to ${defaultPath}`)
+    }
+  }
+  return defaultPath
+}
+
+/**
+ * Resolve Codex without consulting a bare command through spawn. A valid
+ * override wins, followed by the structural adapter and then executable PATH
+ * candidates in Unix lookup order. Known Threadwire front doors are skipped so
+ * a normal direct-CLI lookup cannot recurse into Threadwire.
+ * @param {NodeJS.ProcessEnv} [environment]
+ * @param {ExecutableResolutionOptions} [options]
+ * @returns {string}
+ */
+export function codexExecutable(environment = process.env, options = {}) {
+  const isExecutable = options.isExecutable ?? executableFile
+  const warning = options.warn ?? console.error
+  const canonicalize = options.canonicalize ?? realpathSync
+  const cwd = options.cwd ?? process.cwd()
+  const override = environment.THREADWIRE_CODEX_BIN
+  if (override !== undefined && override.length > 0 && isExecutable(override)) return override
+
+  const fallback = discoveredCodexExecutable(environment, cwd, isExecutable, canonicalize) ?? CODEX_STRUCTURAL_EXECUTABLE
+  if (override !== undefined && override.length > 0) {
+    warning(`threadwire: THREADWIRE_CODEX_BIN=${override} is not executable, falling back to ${fallback}`)
+  }
+  return fallback
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} environment
+ * @param {string} cwd
+ * @param {ExecutableProbe} isExecutable
+ * @param {(path: string) => string} canonicalize
+ * @returns {string | undefined}
+ */
+function discoveredCodexExecutable(environment, cwd, isExecutable, canonicalize) {
+  if (isExecutable(CODEX_STRUCTURAL_EXECUTABLE)) return CODEX_STRUCTURAL_EXECUTABLE
+  if (environment.PATH === undefined) return undefined
+  for (const directory of environment.PATH.split(":")) {
+    const candidate = resolve(cwd, directory, "codex")
+    if (CODEX_FRONT_DOOR_EXECUTABLES.has(candidate)) continue
+    const canonicalPath = canonicalExecutable(candidate, isExecutable, canonicalize)
+    if (canonicalPath !== undefined && !CODEX_FRONT_DOOR_EXECUTABLES.has(canonicalPath)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * @param {string} path
+ * @param {ExecutableProbe} isExecutable
+ * @param {(path: string) => string} canonicalize
+ * @returns {string | undefined}
+ */
+function canonicalExecutable(path, isExecutable, canonicalize) {
+  if (!isExecutable(path)) return undefined
+  try {
+    return canonicalize(path)
+  } catch {
+    return undefined
+  }
+}
+
+/** @type {ExecutableProbe} */
+function executableFile(path) {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
 }

package/src/providers/index.js

@@ -13,10 +13,10 @@ import {buildOpenCodeCommand, createOpenCodeParser, createOpenCodeSessionId} fro
 /** @type {readonly ["codex", "claude", "kimi", "opencode"]} */
 export const PROVIDERS = ["codex", "claude", "kimi", "opencode"]
 
-/** @param {string} name @param {string[]} providerArguments @param {string} prompt @param {string | undefined} resumeSession @param {NodeJS.ProcessEnv} [environment] @returns {Provider} */
-export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env) {
+/** @param {string} name @param {string[]} providerArguments @param {string} prompt @param {string | undefined} resumeSession @param {NodeJS.ProcessEnv} [environment] @param {Parameters<typeof buildCodexCommand>[4]} [codexExecutableResolution] @returns {Provider} */
+export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env, codexExecutableResolution = {}) {
   if (name === "codex") {
-    const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment)
+    const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment, codexExecutableResolution)
     return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId, health: extractProviderHealth}
   }
   if (name === "claude") {