threadwire 0.1.5 → 0.1.6

package/src/telegram-ingress/config.js

@@ -3,6 +3,7 @@
 import {DEFAULT_TELEGRAM_REQUEST_TIMEOUT_MS, MAX_TIMER_DELAY_MS} from "../notifiers/fetch-transport.js"
 import {open as nodeOpen} from "node:fs/promises"
 import {constants as fsConstants} from "node:fs"
+import {isAbsolute, normalize, parse, relative} from "node:path"
 
 const TELEGRAM_ID_PATTERN = /^-?[1-9]\d*$/u
 const DEFAULT_PORT = 8787
@@ -10,6 +11,7 @@ const DEFAULT_HOST = "127.0.0.1"
 const DEFAULT_MAX_CONCURRENT_WORKERS = 4
 const DEFAULT_UPDATE_ID_CAPACITY = 10_000
 const DEFAULT_UPDATE_ID_TTL_MS = 86_400_000
+const DEFAULT_EVIDENCE_ROOT = "/var/lib/threadwire/evidence"
 export const MIN_WEBHOOK_SECRET_LENGTH = 32
 const MAX_SECRET_FILE_BYTES = 65_536
 const FILE_BACKED_SETTINGS = [
@@ -34,25 +36,90 @@ export async function resolveFileBackedSettings(source, names, operations = {})
     const file = environment[fileName]
     if (value !== undefined && file !== undefined) throw new Error(`${name} and ${fileName} must not both be set`)
     if (file === undefined) continue
-    let handle
     try {
-      handle = await (operations.open ?? nodeOpen)(file, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW)
-      const stats = await handle.stat()
-      if (!stats.isFile() || stats.size > MAX_SECRET_FILE_BYTES) throw new Error("invalid setting file")
-      const buffer = Buffer.alloc(MAX_SECRET_FILE_BYTES + 1)
-      const {bytesRead} = await handle.read(buffer, 0, buffer.length, 0)
-      if (bytesRead > MAX_SECRET_FILE_BYTES) throw new Error("invalid setting file")
-      environment[name] = buffer.subarray(0, bytesRead).toString("utf8").trim()
+      environment[name] = await readSecureSettingFile(file, operations)
     } catch {
       throw new Error(`${fileName} could not be read`)
-    } finally {
-      await handle?.close().catch(() => {})
     }
     delete environment[fileName]
   }
   return environment
 }
 
+/**
+ * Read one bounded regular secret file without following a final symlink.
+ * @param {string} file
+ * @param {{open?: (path: string, flags: number) => Promise<import("node:fs/promises").FileHandle>}} [operations]
+ */
+export async function readSecureSettingFile(file, operations = {}) {
+  if (!isAbsolute(file) || normalize(file) !== file || relative(parse(file).root, file).split("/").includes("..")) {
+    throw new Error("invalid setting file")
+  }
+  const openImpl = operations.open ?? nodeOpen
+  /** @type {import("node:fs/promises").FileHandle[]} */
+  const directories = []
+  let handle
+  try {
+    if (operations.open === undefined) {
+      let directory = await openImpl(parse(file).root, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW)
+      directories.push(directory)
+      for (const component of relative(parse(file).root, file).split("/").slice(0, -1)) {
+        const stats = await directory.stat()
+        if (!stats.isDirectory() || !trustedDirectory(stats)) throw new Error("invalid setting file")
+        directory = await openImpl(`/proc/self/fd/${directory.fd}/${component}`, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW)
+        directories.push(directory)
+      }
+      const parentStats = await directory.stat()
+      if (!parentStats.isDirectory() || !trustedDirectory(parentStats)) throw new Error("invalid setting file")
+      const name = relative(parse(file).root, file).split("/").at(-1)
+      handle = await openImpl(`/proc/self/fd/${directory.fd}/${name}`, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW)
+    } else {
+      handle = await openImpl(file, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW)
+    }
+    const stats = await handle.stat()
+    if (!stats.isFile() || stats.nlink !== 1 || stats.size > MAX_SECRET_FILE_BYTES || !trustedSecretFile(stats)) throw new Error("invalid setting file")
+    const buffer = Buffer.alloc(MAX_SECRET_FILE_BYTES + 1)
+    const {bytesRead} = await handle.read(buffer, 0, buffer.length, 0)
+    if (bytesRead > MAX_SECRET_FILE_BYTES) throw new Error("invalid setting file")
+    const value = buffer.subarray(0, bytesRead).toString("utf8").trim()
+    if (value.length === 0) throw new Error("invalid setting file")
+    return value
+  } finally {
+    await handle?.close().catch(() => {})
+    await Promise.all(directories.map((directory) => directory.close().catch(() => {})))
+  }
+}
+
+/** @param {import("node:fs").Stats} stats */
+function trustedDirectory(stats) {
+  const mode = stats.mode & 0o7777
+  return (stats.uid === 0 || stats.uid === process.getuid?.())
+    && ((mode & 0o022) === 0 || (stats.uid === 0 && (mode & 0o1000) !== 0))
+}
+
+/** @param {import("node:fs").Stats} stats */
+function trustedSecretFile(stats) {
+  const mode = stats.mode & 0o777
+  if (stats.uid === 0) return (mode & 0o222) === 0
+  return stats.uid === process.getuid?.() && (mode & 0o077) === 0
+}
+
+/** @param {NodeJS.ProcessEnv} environment */
+export async function collectEvidenceRedactions(environment) {
+  const redactions = []
+  for (const [key, value] of Object.entries(environment)) {
+    if (value === undefined) continue
+    if (/(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)_FILE$/u.test(key)) {
+      if (value.length >= 4) redactions.push(value)
+      const secret = await readSecureSettingFile(value)
+      if (secret.length >= 4) redactions.push(secret)
+    } else if (/(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)$/u.test(key) && value.length >= 4) {
+      redactions.push(value)
+    }
+  }
+  return redactions
+}
+
 /**
  * Resolve every supported ingress setting from a literal or bounded file.
  * @param {NodeJS.ProcessEnv} source
@@ -75,6 +142,7 @@ export async function resolveIngressEnvironment(source, operations = {}) {
  *   telegramRequestTimeoutMs: number,
  *   updateIdCapacity: number,
  *   updateIdTtlMs: number
+ *   evidenceRoot?: string
  * }} IngressConfig
  */
 
@@ -109,6 +177,7 @@ export function parseIngressConfig(environment) {
     "THREADWIRE_UPDATE_ID_TTL_MS",
     DEFAULT_UPDATE_ID_TTL_MS
   )
+  const evidenceRoot = parseEvidenceRoot(environment.THREADWIRE_EVIDENCE_ROOT)
   return {
     botToken,
     webhookSecret,
@@ -120,10 +189,18 @@ export function parseIngressConfig(environment) {
     toolMessages,
     telegramRequestTimeoutMs,
     updateIdCapacity,
-    updateIdTtlMs
+    updateIdTtlMs,
+    evidenceRoot
   }
 }
 
+/** @param {string | undefined} value */
+function parseEvidenceRoot(value) {
+  const root = value ?? DEFAULT_EVIDENCE_ROOT
+  if (!isAbsolute(root) || normalize(root) !== root) throw new Error("THREADWIRE_EVIDENCE_ROOT must be a normalized absolute path")
+  return root
+}
+
 /** @param {NodeJS.ProcessEnv} environment */
 export function parseTelegramRequestTimeoutMs(environment) {
   const timeoutMs = parsePositiveSafeInteger(
@@ -165,6 +242,7 @@ function isIngressSecretKey(key) {
     key === "THREADWIRE_WEBHOOK_PORT" ||
     key === "THREADWIRE_WEBHOOK_HOST" ||
     key === "THREADWIRE_MAX_CONCURRENT_WORKERS" ||
+    key === "THREADWIRE_EVIDENCE_ROOT" ||
     key === "THREADWIRE_TOOL_MESSAGES" ||
     key === "THREADWIRE_TELEGRAM_REQUEST_TIMEOUT_MS" ||
     key === "THREADWIRE_UPDATE_ID_CAPACITY" ||

package/src/telegram-ingress/core.js

@@ -1,30 +1,34 @@
 // @ts-check
 
-import {createHash, timingSafeEqual} from "node:crypto"
+import {createHash, randomUUID, timingSafeEqual} from "node:crypto"
+import {evidenceTelegramDestination} from "../evidence-store.js"
 import {NoticeQueue} from "../notice-queue.js"
 import {createFetchTransport} from "../notifiers/fetch-transport.js"
 import {createTelegramSender} from "../notifiers/telegram.js"
 import {createProvider} from "../providers/index.js"
 import {Relay} from "../relay.js"
 import {runWorker} from "../run-worker.js"
+import {WorkerControl} from "../worker-control.js"
 import {resolveWorkspaceProfile} from "../workspace-profile.js"
-import {buildProviderEnvironment} from "./config.js"
-import {parseCodeCommand} from "./command.js"
+import {buildProviderEnvironment, collectEvidenceRedactions} from "./config.js"
+import {parseCodeCommand, parseEvidenceCommand} from "./command.js"
 
 /**
  * @typedef {{platform: "telegram", chatId: string, threadId: number | null}} TelegramTarget
- * @typedef {{provider: "codex" | "claude" | "opencode", prompt: string, target: TelegramTarget}} AcceptedJob
+ * @typedef {{provider: "codex" | "claude" | "opencode", prompt: string, target: TelegramTarget, senderId: string} | {type: "evidence", request: unknown, target: TelegramTarget, senderId: string}} AcceptedJob
  * @typedef {{
  *   createProvider?: typeof createProvider,
  *   createFetchTransport?: typeof createFetchTransport,
  *   createTelegramSender?: typeof createTelegramSender,
  *   runWorker?: typeof runWorker,
+ *   WorkerControl?: typeof WorkerControl,
  *   NoticeQueue?: typeof NoticeQueue,
  *   Relay?: typeof Relay,
  *   processNumber?: number,
  *   providerEnvironment?: NodeJS.ProcessEnv,
  *   workspaceProfileOperations?: import("../workspace-profile.js").WorkspaceProfileOperations,
  *   activity?: Pick<import("../activity-log.js").ActivityLog, "recordWorkspace" | "recordStarted" | "recordSession" | "close">,
+ *   evidenceStore?: import("../evidence-store.js").EvidenceStore,
  *   onWorkerFailure?: (message: string) => void,
  *   onWorkerSettled?: () => void
  * }} IngressDependencies
@@ -55,11 +59,12 @@ export function interpretUpdate(update, config) {
   if (!isRecord(update)) return null
   const message = update.message
   if (!isRecord(message)) return null
+  if ([
+    "forward_origin", "forward_from", "forward_from_chat", "forward_signature",
+    "forward_sender_name", "is_automatic_forward"
+  ].some((field) => Object.prototype.hasOwnProperty.call(message, field))) return null
   if (typeof message.text !== "string") return null
 
-  const command = parseCodeCommand(message.text)
-  if (!command) return null
-
   const chatId = telegramIdString(isRecord(message.chat) ? message.chat.id : undefined)
   if (chatId === null || !config.allowedChatIds.has(chatId)) return null
 
@@ -69,7 +74,11 @@ export function interpretUpdate(update, config) {
   const target = deriveTarget(chatId, message.message_thread_id)
   if (target === null) return null
 
-  return {provider: command.provider, prompt: command.prompt, target}
+  const command = parseCodeCommand(message.text)
+  if (command) return {provider: command.provider, prompt: command.prompt, target, senderId}
+  const evidence = parseEvidenceCommand(message.text)
+  if (evidence) return {type: "evidence", request: evidence, target, senderId}
+  return null
 }
 
 /**
@@ -83,10 +92,12 @@ export function interpretUpdate(update, config) {
  * @returns {Promise<void>}
  */
 export async function dispatchWorker(job, config, dependencies = {}) {
+  if ("type" in job) throw new Error("Worker dispatch requires a worker job")
   const createProviderImpl = dependencies.createProvider ?? createProvider
   const createFetchTransportImpl = dependencies.createFetchTransport ?? createFetchTransport
   const createTelegramSenderImpl = dependencies.createTelegramSender ?? createTelegramSender
   const runWorkerImpl = dependencies.runWorker ?? runWorker
+  const WorkerControlImpl = dependencies.WorkerControl ?? WorkerControl
   const NoticeQueueImpl = dependencies.NoticeQueue ?? NoticeQueue
   const RelayImpl = dependencies.Relay ?? Relay
   const processNumber = dependencies.processNumber ?? process.pid
@@ -106,111 +117,172 @@ export async function dispatchWorker(job, config, dependencies = {}) {
   )
   const transport = createFetchTransportImpl(config.botToken, undefined, config.telegramRequestTimeoutMs)
   const sender = createTelegramSenderImpl(job.target, transport)
-  const queue = new NoticeQueueImpl({sender})
-  const relay = new RelayImpl({queue, processNumber, toolMessages: config.toolMessages ?? false})
-
-  /** @type {{resolve: () => void, reject: (error: Error) => void, settled: boolean}} */
-  const spawnGate = {
-    settled: false,
-    resolve() {},
-    reject() {}
-  }
-  const spawned = new Promise((resolve, reject) => {
-    spawnGate.resolve = () => {
-      if (spawnGate.settled) return
-      spawnGate.settled = true
-      resolve(undefined)
-    }
-    spawnGate.reject = (error) => {
-      if (spawnGate.settled) return
-      spawnGate.settled = true
-      reject(error)
-    }
+  const control = new WorkerControlImpl({
+    sender,
+    processNumber,
+    toolMessages: config.toolMessages ?? false,
+    NoticeQueueClass: NoticeQueueImpl,
+    RelayClass: RelayImpl
+  })
+  const evidenceOwner = dependencies.evidenceStore?.createOwnerScope({
+    destinationId: evidenceTelegramDestination(job.target, job.senderId),
+    runId: randomUUID()
+  })
+  const evidence = evidenceOwner === undefined ? undefined : await dependencies.evidenceStore?.createArtifact(evidenceOwner, {
+    contentType: "text/plain; charset=utf-8",
+    redactions: await collectEvidenceRedactions(dependencies.providerEnvironment ?? {})
   })
+  let evidenceTransferred = false
+  try {
+    await evidence?.append("prompt", `prompt\n${job.prompt}\nprovider-stream\n`)
 
-  /** @param {unknown} error */
-  const reportBackgroundFailure = (error) => {
-    const failure = error instanceof Error ? error : new Error(safeFailureMessage(error))
-    try {
-      dependencies.onWorkerFailure?.(safeFailureMessage(failure))
-    } catch {
-      /* Observer errors must not become unhandled rejections. */
+    /** @type {{resolve: () => void, reject: (error: Error) => void, settled: boolean}} */
+    const spawnGate = {
+      settled: false,
+      resolve() {},
+      reject() {}
     }
-  }
+    const spawned = new Promise((resolve, reject) => {
+      spawnGate.resolve = () => {
+        if (spawnGate.settled) return
+        spawnGate.settled = true
+        resolve(undefined)
+      }
+      spawnGate.reject = (error) => {
+        if (spawnGate.settled) return
+        spawnGate.settled = true
+        reject(error)
+      }
+    })
 
-  const notifySettled = () => {
-    try {
-      dependencies.onWorkerSettled?.()
-    } catch {
+    /** @param {unknown} error */
+    const reportBackgroundFailure = (error) => {
+      const failure = error instanceof Error ? error : new Error(safeFailureMessage(error))
+      try {
+        dependencies.onWorkerFailure?.(safeFailureMessage(failure))
+      } catch {
       /* Observer errors must not become unhandled rejections. */
+      }
     }
-  }
 
-  const running = runWorkerImpl({
-    executable: provider.executable,
-    arguments: provider.arguments,
-    cwd: workspace.cwd,
-    environment: providerEnvironment,
-    parse: provider.parse,
-    onEvent: (event) => relay.accept(event),
-    onSpawn: (pid) => {
-      if (pid !== undefined) dependencies.activity?.recordStarted(provider.name, pid)
-      spawnGate.resolve()
-    },
-    onRecord: (record) => {
-      const id = provider.sessionId(record)
-      if (id !== undefined) dependencies.activity?.recordSession(provider.name, id)
+    const notifySettled = () => {
+      try {
+        dependencies.onWorkerSettled?.()
+      } catch {
+      /* Observer errors must not become unhandled rejections. */
+      }
     }
-  })
 
-  // Detached observer: never resolves the spawn gate from process exit — only
-  // from onSpawn. Pre-spawn failure rejects the gate; post-spawn failure is
-  // reported. Always notify settlement so concurrency slots are released.
-  void (async () => {
-    try {
+    const running = runWorkerImpl({
+      executable: provider.executable,
+      arguments: provider.arguments,
+      cwd: workspace.cwd,
+      environment: providerEnvironment,
+      parse: provider.parse,
+      onEvent: async (event) => control.accept(event),
+      onSpawn: (pid) => {
+        if (pid !== undefined) dependencies.activity?.recordStarted(provider.name, pid)
+        spawnGate.resolve()
+      },
+      onRecord: async (record) => {
+        const id = provider.sessionId(record)
+        if (id !== undefined) dependencies.activity?.recordSession(provider.name, id)
+      },
+      onStdoutChunk: (chunk) => evidence?.append("provider-stdout", chunk),
+      onStderrChunk: (chunk) => evidence?.append("provider-stderr", chunk)
+    })
+
+    // Detached observer: never resolves the spawn gate from process exit — only
+    // from onSpawn. Pre-spawn failure rejects the gate; post-spawn failure is
+    // reported. Always notify settlement so concurrency slots are released.
+    evidenceTransferred = true
+    void (async () => {
       try {
-        await running
-      } catch (error) {
-        const failure = error instanceof Error ? error : new Error(safeFailureMessage(error))
-        if (spawnGate.settled) {
-          reportBackgroundFailure(failure)
-        } else {
-          spawnGate.reject(failure)
-        }
         try {
-          await relay.close()
-        } catch {
+          await running
+        } catch (error) {
+          const failure = error instanceof Error ? error : new Error(safeFailureMessage(error))
+          if (spawnGate.settled) {
+            reportBackgroundFailure(failure)
+          } else {
+            spawnGate.reject(failure)
+          }
+          try {
+            await control.close()
+          } catch {
           /* Best-effort close after worker failure. */
+          }
+          return
         }
-        return
-      }
 
-      try {
-        await relay.close()
+        try {
+          await control.close()
+        } catch (error) {
+          if (spawnGate.settled) {
+            reportBackgroundFailure(error)
+          } else {
+            spawnGate.reject(error instanceof Error ? error : new Error(safeFailureMessage(error)))
+          }
+          return
+        }
+
+        if (!spawnGate.settled) {
+          spawnGate.reject(new Error("Worker exited before spawn was observed"))
+        }
       } catch (error) {
         if (spawnGate.settled) {
           reportBackgroundFailure(error)
         } else {
           spawnGate.reject(error instanceof Error ? error : new Error(safeFailureMessage(error)))
         }
-        return
+      } finally {
+        if (evidence !== undefined) {
+          try {
+            await evidence.finalize()
+            await sender.send(`Evidence: ${evidence.handle}`)
+          } catch (error) {
+            await evidence.abort()
+            reportBackgroundFailure(error)
+          }
+        }
+        notifySettled()
       }
+    })()
 
-      if (!spawnGate.settled) {
-        spawnGate.reject(new Error("Worker exited before spawn was observed"))
-      }
-    } catch (error) {
-      if (spawnGate.settled) {
-        reportBackgroundFailure(error)
-      } else {
-        spawnGate.reject(error instanceof Error ? error : new Error(safeFailureMessage(error)))
-      }
-    } finally {
-      notifySettled()
-    }
-  })()
+    await spawned
+  } finally {
+    if (!evidenceTransferred) await evidence?.abort()
+  }
+}
 
-  await spawned
+/** @param {Extract<AcceptedJob, {type: "evidence"}>} job @param {{botToken: string, telegramRequestTimeoutMs?: number}} config @param {IngressDependencies} dependencies */
+export async function dispatchEvidenceRead(job, config, dependencies) {
+  if (!dependencies.evidenceStore) throw new Error("Evidence retrieval is unavailable")
+  const transport = (dependencies.createFetchTransport ?? createFetchTransport)(config.botToken, undefined, config.telegramRequestTimeoutMs)
+  const sender = (dependencies.createTelegramSender ?? createTelegramSender)(job.target, transport)
+  const result = await dependencies.evidenceStore.readTelegram({...job.target, senderId: job.senderId}, job.request)
+  const label = result.encoding === "base64"
+    ? `Evidence (${result.contentType}, base64, truncated):\n`
+    : `Evidence (${result.contentType}, redacted, truncated):\n`
+  const boundedData = telegramEvidenceText(result.data, Math.max(0, 3_000 - Buffer.byteLength(label)))
+  await sender.send({
+    text: result.encoding === "base64"
+      ? `Evidence (${result.contentType}, base64${boundedData.truncated ? ", truncated" : ""}):\n${boundedData.text}`
+      : `Evidence (${result.contentType}${result.redacted ? ", redacted" : ""}${result.truncated || boundedData.truncated ? ", truncated" : ""}):\n${boundedData.text}`
+  })
+}
+
+/** @param {string} value @param {number} maxBytes */
+function telegramEvidenceText(value, maxBytes) {
+  let text = ""
+  let bytes = 0
+  for (const character of value) {
+    const width = Buffer.byteLength(character, "utf8")
+    if (bytes + width > maxBytes) return {text, truncated: true}
+    text += character
+    bytes += width
+  }
+  return {text, truncated: false}
 }
 
 /** @param {string} chatId @param {unknown} threadId @returns {TelegramTarget | null} */

package/src/telegram-ingress/http.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import {createConcurrencyLimiter} from "./concurrency.js"
-import {dispatchWorker, interpretUpdate, secretsEqual} from "./core.js"
+import {dispatchEvidenceRead, dispatchWorker, interpretUpdate, secretsEqual} from "./core.js"
 import {createUpdateGuard, parseUpdateId} from "./update-guard.js"
 import {WorkspaceProviderMismatchError} from "../workspace-profile.js"
 
@@ -112,6 +112,22 @@ async function handleRequest(request, response, config, dependencies) {
       return
     }
 
+    if ("type" in job) {
+      try {
+        await dispatchEvidenceRead(job, {
+          botToken: config.botToken,
+          telegramRequestTimeoutMs: config.telegramRequestTimeoutMs
+        }, dependencies)
+        dependencies.updateGuard.complete(updateId)
+        send(response, 200)
+      } catch (error) {
+        dependencies.updateGuard.release(updateId)
+        dependencies.onOperationalError?.(error instanceof Error ? error.message : "Evidence retrieval failed")
+        send(response, 500)
+      }
+      return
+    }
+
     if (!dependencies.concurrency.tryAcquire()) {
       dependencies.updateGuard.release(updateId)
       send(response, 503)

package/src/telegram-webhook.js

@@ -2,6 +2,7 @@
 
 import {createServer} from "node:http"
 import {ActivityLog} from "./activity-log.js"
+import {EvidenceStore} from "./evidence-store.js"
 import {buildProviderEnvironment, parseIngressConfig, resolveIngressEnvironment} from "./telegram-ingress/config.js"
 import {createWebhookHandler} from "./telegram-ingress/http.js"
 
@@ -15,6 +16,7 @@ import {createWebhookHandler} from "./telegram-ingress/http.js"
  *   onWorkerFailure?: (message: string) => void,
  *   providerEnvironment?: NodeJS.ProcessEnv,
  *   activity?: Pick<ActivityLog, "recordWorkspace" | "recordStarted" | "recordSession" | "close">,
+ *   evidenceStore?: EvidenceStore,
  *   handlerDependencies?: import("./telegram-ingress/http.js").WebhookDependencies
  * }} [options]
  * @returns {Promise<{server: import("node:http").Server, config: import("./telegram-ingress/config.js").IngressConfig, handler: (request: import("node:http").IncomingMessage, response: import("node:http").ServerResponse) => void}>}
@@ -33,15 +35,29 @@ export async function startTelegramWebhook(options = {}) {
     options.providerEnvironment ?? environment
   )
   const activity = options.activity ?? options.handlerDependencies?.activity ?? new ActivityLog("/var/lib/threadwire/activity/threadwire.jsonl")
+  const evidenceStore = options.evidenceStore ?? options.handlerDependencies?.evidenceStore ?? await EvidenceStore.open({
+    root: config.evidenceRoot ?? "/var/lib/threadwire/evidence"
+  })
 
   const handler = createWebhookHandler(config, {
     ...options.handlerDependencies,
     activity,
+    evidenceStore,
     providerEnvironment,
     onOperationalError,
     onWorkerFailure
   })
   const server = createServerImpl(handler)
+  if (options.evidenceStore === undefined && options.handlerDependencies?.evidenceStore === undefined) {
+    const cleanupTimer = setInterval(() => {
+      void evidenceStore.cleanup().catch((error) => onOperationalError(error instanceof Error ? error.message : "Evidence cleanup failed"))
+    }, 60 * 60 * 1000)
+    cleanupTimer.unref()
+    server.once("close", () => {
+      clearInterval(cleanupTimer)
+      void evidenceStore.close()
+    })
+  }
 
   if (options.listen) {
     await options.listen(server, config.port, config.host)

package/src/types.js

@@ -7,8 +7,8 @@
  * @typedef {{type: "diagnostic", level: "warning" | "error", summary: string}} DiagnosticEvent
  * @typedef {TextDeltaEvent | ToolEvent | LifecycleEvent | DiagnosticEvent} WorkerEvent
  * @typedef {{platform: "telegram", chatId: string, threadId: number | null}} TelegramTarget
- * @typedef {{text: string, format?: "javascript-code", label?: string, batchSeparator?: string}} TextNotice
- * @typedef {{activity: {key: string, phase: "started" | "finished"}, text: string, parseMode?: "HTML"}} ActivityNotice
+ * @typedef {{text: string, format?: "javascript-code", label?: string, batchSeparator?: string, metricClass?: string}} TextNotice
+ * @typedef {{activity: {key: string, phase: "started" | "finished"}, text: string, parseMode?: "HTML", metricClass?: string}} ActivityNotice
  * @typedef {TextNotice | ActivityNotice} RenderedNotice
  * @typedef {{text: string, parseMode?: "HTML"}} OutgoingMessage
  * @typedef {{messageId: number}} SentMessage