threadwire 0.1.14 → 0.1.17

package/src/activity-log.js

@@ -4,11 +4,38 @@ import {closeSync, openSync, writeSync} from "node:fs"
 
 const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
 
+const ACTIVITY_KINDS = new Set(["delta", "tool", "lifecycle"])
+const HEALTH_DISPOSITIONS = new Set(["retrying", "blocked"])
+const HEALTH_CATEGORIES = new Set([
+  "authentication", "permission", "rate-limit", "quota", "billing",
+  "model", "network", "protocol", "unknown"
+])
+const TERMINAL_STATES = new Set(["completed", "failed", "cancelled"])
+
+const SIGNAL_CANCELLED_EXIT_CODES = new Set([130, 143])
+
+const ACTIVITY_THROTTLE_MS = 5000
+
 export class ActivityLog {
-  /** @param {string} path */
-  constructor(path) {
+  /**
+   * @param {string} path
+   * @param {{now?: () => number}} [options]
+   */
+  constructor(path, options = {}) {
     this.fileDescriptor = openSync(path, "a", 0o600)
     this.closed = false
+    this.now = options.now ?? (() => Date.now())
+    this.terminalWritten = false
+    /** @type {string | null} */
+    this.lastHealthFingerprint = null
+    this.lastActivityAt = -ACTIVITY_THROTTLE_MS
+    this.activityCount = 0
+  }
+
+  /** @param {number} pid */
+  recordController(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Controller PID is unavailable")
+    this.write({type: "controller-started", pid})
   }
 
   /** @param {"codex" | "claude" | "kimi" | "opencode"} provider @param {number} pid */
@@ -23,15 +50,76 @@ export class ActivityLog {
     this.write({type: "session-available", provider, sessionId})
   }
 
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {"delta" | "tool" | "lifecycle"} kind
+   */
+  recordActivity(provider, kind) {
+    if (!ACTIVITY_KINDS.has(kind)) throw new Error(`Unknown activity kind: ${kind}`)
+    const now = this.now()
+    if (now - this.lastActivityAt < ACTIVITY_THROTTLE_MS) return
+    this.lastActivityAt = now
+    this.activityCount += 1
+    this.write({type: "activity", provider, kind})
+  }
+
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {{disposition: "retrying" | "blocked", category: "authentication" | "permission" | "rate-limit" | "quota" | "billing" | "model" | "network" | "protocol" | "unknown", retryAfterMs?: number}} health
+   */
+  recordHealth(provider, health) {
+    if (!HEALTH_DISPOSITIONS.has(health.disposition)) throw new Error("Unknown health disposition")
+    if (!HEALTH_CATEGORIES.has(health.category)) throw new Error("Unknown health category")
+    if (health.retryAfterMs !== undefined) {
+      if (!Number.isSafeInteger(health.retryAfterMs) || health.retryAfterMs <= 0) throw new Error("retryAfterMs must be a positive safe integer")
+      if (health.disposition !== "retrying") throw new Error("retryAfterMs is only valid for retrying disposition")
+    }
+    const fingerprint = `${health.disposition}\0${health.category}\0${health.retryAfterMs ?? ""}`
+    if (fingerprint === this.lastHealthFingerprint) return
+    this.lastHealthFingerprint = fingerprint
+    /** @type {{type: string, provider: string, disposition: string, category: string, retryAfterMs?: number}} */
+    const fact = {type: "health", provider, disposition: health.disposition, category: health.category}
+    if (health.retryAfterMs !== undefined) fact.retryAfterMs = health.retryAfterMs
+    this.write(fact)
+  }
+
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {"completed" | "failed" | "cancelled"} state
+   * @param {number} exitCode
+   */
+  recordTerminal(provider, state, exitCode) {
+    if (this.terminalWritten) return
+    if (!TERMINAL_STATES.has(state)) throw new Error("Unknown terminal state")
+    if (!Number.isSafeInteger(exitCode) || exitCode < 0 || exitCode > 255) throw new Error("exitCode must be an integer between 0 and 255")
+    this.terminalWritten = true
+    this.write({type: "terminal", provider, state, exitCode})
+  }
+
   close() {
     if (this.closed) return
     this.closed = true
     closeSync(this.fileDescriptor)
   }
 
-  /** @param {{type: "provider-started", provider: "codex" | "claude" | "kimi" | "opencode", pid: number} | {type: "session-available", provider: "codex" | "claude" | "kimi" | "opencode", sessionId: string}} fact */
+  /**
+   * @param {Record<string, unknown>} fact
+   */
   write(fact) {
     if (this.closed) throw new Error("Activity log is closed")
+    fact.at = this.now()
     writeSync(this.fileDescriptor, `${JSON.stringify(fact)}\n`)
   }
 }
+
+/**
+ * Classify a terminal exit code. Known signal-derived codes (130 = SIGINT,
+ * 143 = SIGTERM) map to cancelled; all others map to completed (0) or failed
+ * (nonzero). This is the only place that picks the terminal state constant.
+ * @param {number} exitCode
+ * @returns {"completed" | "failed" | "cancelled"}
+ */
+export function terminalState(exitCode) {
+  if (SIGNAL_CANCELLED_EXIT_CODES.has(exitCode)) return "cancelled"
+  return exitCode === 0 ? "completed" : "failed"
+}

package/src/cli.js

@@ -1,14 +1,15 @@
 // @ts-check
 
-import {readFile} from "node:fs/promises"
+import {lstat, readFile, readlink, realpath} from "node:fs/promises"
 import {randomUUID} from "node:crypto"
-import {isAbsolute, normalize, resolve} from "node:path"
+import {basename, dirname, isAbsolute, join, normalize, resolve} from "node:path"
 import {stdin, stderr, stdout} from "node:process"
 import {createFetchTransport} from "./notifiers/fetch-transport.js"
 import {createTelegramSender, parseTelegramTarget} from "./notifiers/telegram.js"
 import {createProvider, PROVIDERS} from "./providers/index.js"
 import {runWorker} from "./run-worker.js"
-import {ActivityLog} from "./activity-log.js"
+import {ActivityLog, terminalState} from "./activity-log.js"
+import {computeStatus, parseStatusArguments, readActivityLog} from "./activity-log-status.js"
 import {DelegatedResultAdmission, validateContinuationHandle} from "./delegated-result-admission.js"
 import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
 import {WorkerControl} from "./worker-control.js"
@@ -29,7 +30,7 @@ import {
 import {probeCodexCapacity} from "./provider-capacity-codex.js"
 import {probeKimiCapacity} from "./provider-capacity-kimi.js"
 
-const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id>
+const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id> | file:<absolute-path>
   [--process-number <positive-integer>] [--cwd <directory>]
   [--relay-write]
   [--tool-messages] [--max-output-length <positive-integer>]
@@ -41,7 +42,9 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)
        threadwire capacity [--provider <codex|kimi>]...
   [--short-reserve-percent <0-100>] [--long-reserve-percent <0-100>]
-  [--timeout-ms <positive-integer>]`
+  [--timeout-ms <positive-integer>]
+       threadwire status --activity-log <absolute-path>
+  (Emits one closed versioned JSON status document from the activity log.)`
 
 /** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
 /** @typedef {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
@@ -244,6 +247,16 @@ export async function main(arguments_, dependencies = {}) {
   /** @type {DelegatedResultAdmission | undefined} */
   let runAdmission
   try {
+    if (arguments_[0] === "status") {
+      const statusParsed = parseStatusArguments(arguments_)
+      if (validateOnly) return 0
+      const records = await readActivityLog(statusParsed.activityLog)
+      const status = computeStatus(records, {
+        ...(dependencies.now === undefined ? {} : {now: dependencies.now})
+      })
+      output.write(`${JSON.stringify(status)}\n`)
+      return 0
+    }
     const parsed = arguments_[0] === "evidence"
       ? parseEvidenceArguments(arguments_)
       : arguments_[0] === "capacity" ? parseCapacityArguments(arguments_) : parseArguments(arguments_)
@@ -292,12 +305,20 @@ export async function main(arguments_, dependencies = {}) {
         await store.close()
       }
     }
-    if (!validateOnly) {
-      normalizedOutput = new NormalizedOutput(output, parsed.transcript)
+    const destination = parseDeliveryTarget(parsed.target)
+    if (destination.type === "file" && parsed.transcript !== undefined) {
+      throw new Error("--transcript cannot be combined with a file target")
     }
+    const transcriptPath = destination.type === "file" ? destination.path : parsed.transcript
+    if (
+      transcriptPath !== undefined && parsed.activityLog !== undefined
+      && await canonicalFilesystemPath(transcriptPath) === await canonicalFilesystemPath(parsed.activityLog)
+    ) {
+      throw new Error("Result and activity log paths must resolve to different filesystem paths")
+    }
+    if (!validateOnly) normalizedOutput = new NormalizedOutput(output, transcriptPath)
     const metrics = new ContextBudgetMetrics()
     runAdmission = normalizedOutput === undefined ? undefined : new DelegatedResultAdmission({output: normalizedOutput, metrics})
-    const target = parseTelegramTarget(parsed.target)
     if (parsed.relayWrite) validateRelayWriteProviderArguments(parsed.providerArguments)
     if (validateOnly) return 0
     const usesIsolatedRuntime = parsed.relayWrite
@@ -322,27 +343,63 @@ export async function main(arguments_, dependencies = {}) {
     let activity
     /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
     let evidence
+    /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
+    let resultEvidence
     /** @type {EvidenceStore | undefined} */
     let ownedEvidenceStore
+    /** @type {EvidenceStore | undefined} */
+    let evidenceStore
+    /** @type {{destinationId: string, runId: string} | undefined} */
+    let evidenceOwner
+    /** @type {WorkerControl | undefined} */
+    let control
+    /** @type {unknown} */
+    let deliveryError
+    let resultEvidenceFinalized = false
     let evidencePayloadBytes = 0
+    let resultEvidenceBytes = 0
+    const deliveryIdentity = randomUUID()
     const launchDeadline = isolatedPreflight?.deadline
     try {
-      environment = await boundedLaunch(resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"]), launchDeadline)
+      environment = await boundedLaunch(resolveFileBackedSettings(
+        sourceEnvironment,
+        destination.type === "telegram" ? ["THREADWIRE_TELEGRAM_BOT_TOKEN"] : []
+      ), launchDeadline)
+      if (destination.type === "telegram" && !environment.THREADWIRE_TELEGRAM_BOT_TOKEN) {
+        throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
+      }
       const prompt = await readPrompt(parsed, dependencies.input ?? stdin, launchDeadline?.signal)
       const configuredEvidenceRoot = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (dependencies.evidenceStore === undefined && configuredEvidenceRoot !== undefined) {
         ownedEvidenceStore = await boundedLaunch(EvidenceStore.open({root: configuredEvidenceRoot}), launchDeadline)
       }
-      const evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
+      evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
       if (evidenceStore !== undefined) {
-        const evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
-          destinationId: `${target.chatId}:${target.threadId ?? "dm"}`,
-          runId: randomUUID()
+        evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
+          destinationId: destination.type === "telegram"
+            ? `${destination.target.chatId}:${destination.target.threadId ?? "dm"}`
+            : "file",
+          runId: deliveryIdentity
         })
+        const redactions = await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
         evidence = await evidenceStore.createArtifact(evidenceOwner, {
           contentType: "text/plain; charset=utf-8",
-          redactions: await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
+          redactions
         })
+        try {
+          resultEvidence = await evidenceStore.createArtifact(evidenceOwner, {
+            contentType: "application/json",
+            redactions,
+            delivery: {
+              identity: deliveryIdentity,
+              state: destination.type === "telegram" ? "delivery_pending" : "delivery_not_requested"
+            }
+          })
+        } catch (error) {
+          await evidence.abort()
+          evidence = undefined
+          throw error
+        }
       }
       if (evidence !== undefined) {
         const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
@@ -361,18 +418,23 @@ export async function main(arguments_, dependencies = {}) {
         providerEnvironment
       )
       if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
-      const token = environment.THREADWIRE_TELEGRAM_BOT_TOKEN
-      if (!token) throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
-      const transport = (dependencies.transportFactory ?? createFetchTransport)(token, undefined, parseTelegramRequestTimeoutMs(environment))
-      const control = new WorkerControl({
-        sender: createTelegramSender(target, transport),
-        processNumber: parsed.processNumber ?? process.pid,
-        toolMessages: parsed.toolMessages,
-        ...(dependencies.workerControlOptions ?? {}),
-        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
-        metrics
-      })
+      if (destination.type === "telegram") {
+        const transport = (dependencies.transportFactory ?? createFetchTransport)(
+          /** @type {string} */ (environment.THREADWIRE_TELEGRAM_BOT_TOKEN),
+          undefined,
+          parseTelegramRequestTimeoutMs(environment)
+        )
+        control = new WorkerControl({
+          sender: createTelegramSender(destination.target, transport),
+          processNumber: parsed.processNumber ?? process.pid,
+          toolMessages: parsed.toolMessages,
+          ...(dependencies.workerControlOptions ?? {}),
+          ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
+          metrics
+        })
+      }
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
+      activity?.recordController(process.pid)
       /** @type {import("./run-worker.js").RunWorkerOptions} */
       const workerOptions = {
         executable: provider.executable,
@@ -383,13 +445,22 @@ export async function main(arguments_, dependencies = {}) {
         parse: provider.parse,
         ...(provider.completion === undefined ? {} : {completion: provider.completion}),
         ...(launchDeadline === undefined ? {} : {signal: launchDeadline.signal}),
-        onEvent: (event) => {
+        onEvent: async (event) => {
           validateNormalizedWorkerEvent(event)
           if (event.type !== "text-delta") {
             metrics.recordRejected(`${event.type}_progress`, Buffer.byteLength(JSON.stringify(event), "utf8"))
           }
+          if (event.type === "text-delta") activity?.recordActivity(provider.name, "delta")
+          else if (event.type === "tool") activity?.recordActivity(provider.name, "tool")
+          else if (event.type === "lifecycle") activity?.recordActivity(provider.name, "lifecycle")
           acceptAdmissionEvent(admission, event)
-          return control.accept(event)
+          if (control !== undefined) {
+            try {
+              await control.accept(event)
+            } catch (error) {
+              deliveryError ??= error
+            }
+          }
         },
         onSpawn: (pid) => {
           if (activity && pid !== undefined) activity.recordStarted(provider.name, pid)
@@ -401,6 +472,8 @@ export async function main(arguments_, dependencies = {}) {
             admission.setContinuationHandle(id)
             activity?.recordSession(provider.name, id)
           }
+          const health = provider.health(record)
+          if (health !== undefined) activity?.recordHealth(provider.name, health)
         },
         onStdoutChunk: (chunk) => {
           metrics.recordRawChildChunk("provider_stdout", chunk.length)
@@ -437,33 +510,83 @@ export async function main(arguments_, dependencies = {}) {
       } else {
         exitCode = await (dependencies.workerRunner ?? runWorker)(workerOptions)
       }
-      await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
     } finally {
-      if (evidence !== undefined) {
+      const terminal = {state: /** @type {"completed" | "failed"} */ (terminalExitCode === 0 ? "completed" : "failed"), exitCode: terminalExitCode}
+      if (evidence !== undefined && resultEvidence !== undefined) {
+        try {
+          admission.addArtifactHandle(resultEvidence.handle)
+          const providerResult = admission.createProviderResult(terminal)
+          const serializedProviderResult = `${JSON.stringify(providerResult)}\n`
+          await resultEvidence.append("provider-result", serializedProviderResult)
+          const resultArtifact = await resultEvidence.finalize()
+          resultEvidenceBytes = resultArtifact.bytes
+          resultEvidenceFinalized = true
+        } catch (error) {
+          await evidence.abort()
+          await resultEvidence.abort()
+          admission.removeArtifactHandle(resultEvidence.handle)
+          metrics.clearArtifact()
+          terminalExitCode = 2
+          evidenceError = error
+        }
+      } else {
+        await evidence?.abort()
+        await resultEvidence?.abort()
+      }
+      if (control !== undefined) {
+        try {
+          await boundedLaunch(control.close(), launchDeadline)
+        } catch (error) {
+          deliveryError ??= error
+        }
+      }
+      if (evidence !== undefined && resultEvidenceFinalized) {
+        admission.addArtifactHandle(evidence.handle)
         try {
-          admission.addArtifactHandle(evidence.handle)
-          const terminal = {state: /** @type {"completed" | "failed"} */ (terminalExitCode === 0 ? "completed" : "failed"), exitCode: terminalExitCode}
           metrics.recordAdmission(admission.preview(terminal))
-          const projectedArtifactBytes = metrics.projectSelfInclusiveArtifact(evidencePayloadBytes, 1)
+          const projectedArtifactBytes = metrics.projectSelfInclusiveArtifact(
+            evidencePayloadBytes + resultEvidenceBytes,
+            2
+          )
           await evidence.append("context-metrics", `${JSON.stringify(metrics.snapshot())}\n`)
           const artifact = await evidence.finalize()
-          assertArtifactProjection(artifact.bytes, projectedArtifactBytes)
+          assertArtifactProjection(artifact.bytes + resultEvidenceBytes, projectedArtifactBytes)
         } catch (error) {
-          await evidence.abort()
           admission.removeArtifactHandle(evidence.handle)
+          await evidence.abort()
           metrics.clearArtifact()
-          terminalExitCode = 2
-          evidenceError = error
+          metrics.recordArtifact(resultEvidenceBytes, 1)
+          evidenceError ??= error
         }
+      } else if (resultEvidenceFinalized) {
+        metrics.recordArtifact(resultEvidenceBytes, 1)
       }
       admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
+      if (
+        destination.type === "telegram" && resultEvidenceFinalized
+        && evidenceStore !== undefined && evidenceOwner !== undefined && resultEvidence !== undefined
+      ) {
+        try {
+          await evidenceStore.recordDelivery(
+            evidenceOwner,
+            resultEvidence.handle,
+            control !== undefined && deliveryError === undefined ? "delivery_succeeded" : "delivery_failed"
+          )
+        } catch (error) {
+          evidenceError ??= error
+        }
+      }
       errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
-      activity?.close()
+      if (activity !== undefined) {
+        activity.recordTerminal(/** @type {"codex" | "claude" | "kimi" | "opencode"} */ (parsed.provider), terminalState(terminalExitCode), terminalExitCode)
+        activity.close()
+      }
       await boundedLaunch(ownedEvidenceStore?.close(), launchDeadline).catch(() => {})
       launchDeadline?.close()
     }
     if (evidenceError !== undefined) throw evidenceError
+    if (deliveryError !== undefined) throw deliveryError
     return terminalExitCode
   } catch (error) {
     let reportedError = error
@@ -485,6 +608,44 @@ export async function main(arguments_, dependencies = {}) {
   }
 }
 
+/** @param {string} value @returns {{type: "telegram", target: import("./types.js").TelegramTarget} | {type: "file", path: string}} */
+function parseDeliveryTarget(value) {
+  if (!value.startsWith("file:")) return {type: "telegram", target: parseTelegramTarget(value)}
+  const path = value.slice("file:".length)
+  if (!isAbsolute(path) || normalize(path) !== path || path.includes("\0") || path === "/") {
+    throw new Error("File target must contain a normalized absolute file path")
+  }
+  return {type: "file", path}
+}
+
+/** @param {string} path @param {Set<string>} [seen] @returns {Promise<string>} */
+async function canonicalFilesystemPath(path, seen = new Set()) {
+  if (seen.has(path)) throw new Error("Result or activity log path contains a filesystem alias cycle")
+  seen.add(path)
+  try {
+    return await realpath(path)
+  } catch (error) {
+    if (!missingPath(error)) throw error
+  }
+  try {
+    const metadata = await lstat(path)
+    if (metadata.isSymbolicLink()) {
+      return canonicalFilesystemPath(resolve(dirname(path), await readlink(path)), seen)
+    }
+  } catch (error) {
+    if (!missingPath(error)) throw error
+  }
+  const parent = dirname(path)
+  if (parent === path) return path
+  return join(await canonicalFilesystemPath(parent, seen), basename(path))
+}
+
+/** @param {unknown} error */
+function missingPath(error) {
+  return typeof error === "object" && error !== null
+    && /** @type {{code?: unknown}} */ (error).code === "ENOENT"
+}
+
 /** @param {string | undefined} value */
 function evidenceRoot(value) {
   if (value === undefined) return undefined

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]) ?? [])