threadwire 0.1.14 → 0.1.17

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

@@ -16,6 +16,7 @@ const MAX_LINES = 1_024
  * failures classify with fixed, credential-free messages.
  * @param {{
  *   env?: NodeJS.ProcessEnv,
+ *   executable?: string | undefined,
  *   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 ?? providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment)
   const result = await appServerExchange(spawnImplementation, executable, environment, timeoutMs)
   return normalizeCodexRateLimits(result)
 }

package/src/providers/executable.js

@@ -1,10 +1,11 @@
 // @ts-check
 
+import {accessSync, constants, statSync} from "node:fs"
+
 /**
  * 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 +13,17 @@
  */
 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
 }

package/src/providers/index.js

@@ -6,7 +6,8 @@ import {buildKimiCommand, createKimiCompletion, createKimiParser, createKimiSess
 import {buildOpenCodeCommand, createOpenCodeParser, createOpenCodeSessionId} from "./opencode.js"
 
 /**
- * @typedef {{name: "codex" | "claude" | "kimi" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined, completion?: (record: unknown) => boolean}} Provider
+ * @typedef {{disposition: "retrying" | "blocked", category: "authentication" | "permission" | "rate-limit" | "quota" | "billing" | "model" | "network" | "protocol" | "unknown", retryAfterMs?: number}} ProviderHealth
+ * @typedef {{name: "codex" | "claude" | "kimi" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined, health: (record: unknown) => ProviderHealth | undefined, completion?: (record: unknown) => boolean}} Provider
  */
 
 /** @type {readonly ["codex", "claude", "kimi", "opencode"]} */
@@ -16,19 +17,122 @@ export const PROVIDERS = ["codex", "claude", "kimi", "opencode"]
 export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env) {
   if (name === "codex") {
     const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId}
+    return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId, health: extractProviderHealth}
   }
   if (name === "claude") {
     const command = buildClaudeCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "claude", parse: createClaudeParser(), sessionId: claudeSessionId}
+    return {...command, name: "claude", parse: createClaudeParser(), sessionId: claudeSessionId, health: extractProviderHealth}
   }
   if (name === "opencode") {
     const command = buildOpenCodeCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "opencode", parse: createOpenCodeParser(), sessionId: createOpenCodeSessionId()}
+    return {...command, name: "opencode", parse: createOpenCodeParser(), sessionId: createOpenCodeSessionId(), health: extractProviderHealth}
   }
   if (name === "kimi") {
     const command = buildKimiCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "kimi", parse: createKimiParser(), sessionId: createKimiSessionId(), completion: createKimiCompletion()}
+    return {...command, name: "kimi", parse: createKimiParser(), sessionId: createKimiSessionId(), completion: createKimiCompletion(), health: extractProviderHealth}
   }
   throw new Error(`--provider must be one of: ${PROVIDERS.join(", ")}`)
 }
+
+/**
+ * Extract safe provider health information from a structured provider record.
+ * Inspects only an explicit small list of safe containers — the top-level
+ * record and known nested `error`, `part`, `part.error`, or `*.data` objects —
+ * never traverses arbitrarily nested objects and never regexes raw message
+ * text. Generic HTTP 429 → retrying rate-limit. Structured
+ * exceeded_current_quota_error / insufficient_quota / insufficient_balance →
+ * blocked quota/billing. If no structured fields are exposed — common when a
+ * provider protocol suppresses upstream error details — no health fact is
+ * written and the run status remains running/unknown; Hermes must perform an
+ * independent bounded provider probe.
+ * @param {unknown} record
+ * @returns {ProviderHealth | undefined}
+ */
+export function extractProviderHealth(record) {
+  if (!isRecord(record)) return undefined
+
+  // Explicit containers to inspect: top-level record, record.error, record.part,
+  // record.part.error. Only these bounded paths; never recursive traversal.
+  const containers = [record]
+  if (isRecord(record.error)) containers.push(record.error)
+  if (isRecord(record.part)) {
+    containers.push(record.part)
+    if (isRecord(record.part.error)) containers.push(record.part.error)
+  }
+
+  for (const container of containers) {
+    const health = extractFromContainer(container)
+    if (health !== undefined) return health
+  }
+
+  return undefined
+}
+
+/**
+ * Inspect one safe container for structured health fields.
+ * @param {Record<string, unknown>} container
+ * @returns {ProviderHealth | undefined}
+ */
+function extractFromContainer(container) {
+  // Inspect structured data sub-object when present.
+  if (isRecord(container.data)) return extractFromContainer(container.data)
+
+  const httpStatus = container.http_status ?? container.httpStatus ?? container.status_code ?? container.statusCode
+  if (typeof httpStatus === "number" && Number.isSafeInteger(httpStatus)) {
+    if (httpStatus === 429) {
+      const retryAfterMs = safeRetryMs(container.retryAfterMs ?? container.retry_after_ms)
+      return {disposition: "retrying", category: "rate-limit", ...(retryAfterMs === undefined ? {} : {retryAfterMs})}
+    }
+    if (httpStatus >= 500 && httpStatus < 600) {
+      return {disposition: "retrying", category: "unknown"}
+    }
+  }
+
+  const code = container.code ?? container.error_code ?? container.errorCode ?? container.error_type ?? container.errorType
+  if (typeof code === "string") {
+    if (code === "exceeded_current_quota_error" || code === "insufficient_quota" || code === "quota_exceeded") {
+      return {disposition: "blocked", category: "quota"}
+    }
+    if (code === "insufficient_balance" || code === "billing_error" || code === "payment_required") {
+      return {disposition: "blocked", category: "billing"}
+    }
+    if (code === "invalid_api_key" || code === "unauthorized" || code === "auth_error" || code === "authentication_error") {
+      return {disposition: "blocked", category: "authentication"}
+    }
+    if (code === "forbidden" || code === "permission_denied") {
+      return {disposition: "blocked", category: "permission"}
+    }
+    if (code === "model_not_found" || code === "invalid_model" || code === "model_unavailable") {
+      return {disposition: "blocked", category: "model"}
+    }
+  }
+
+  if (container.insufficient_quota === true || container.quota_exceeded === true) {
+    return {disposition: "blocked", category: "quota"}
+  }
+  if (container.insufficient_balance === true) {
+    return {disposition: "blocked", category: "billing"}
+  }
+
+  return undefined
+}
+
+/**
+ * Extract a safe retry duration in milliseconds. Only explicit millisecond
+ * fields (retryAfterMs, retry_after_ms) are used; ambiguous short fields such
+ * as retry_after (seconds) are never interpreted as milliseconds.
+ * @param {unknown} value
+ */
+function safeRetryMs(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return value
+  if (typeof value === "string" && /^\d+$/u.test(value)) {
+    const parsed = Number(value)
+    if (Number.isSafeInteger(parsed) && parsed > 0) return parsed
+  }
+  return undefined
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}