threadwire 0.1.5 → 0.1.6

package/src/notice-queue.js

@@ -4,7 +4,7 @@
  * A single unit of work handed to the transport: either a batched/chunked text
  * message, or a tool-activity message that must be correlated by `activity.key`
  * so its "finished" phase edits the exact Telegram message its "started" sent.
- * @typedef {{message: string | import("./types.js").OutgoingMessage, activity?: {key: string, phase: "started" | "finished"}}} Delivery
+ * @typedef {{message: string | import("./types.js").OutgoingMessage, metricClass?: string, activity?: {key: string, phase: "started" | "finished"}}} Delivery
  */
 
 const DEFAULT_MAX_LENGTH = 3500
@@ -13,10 +13,11 @@ const DEFAULT_MAX_PENDING_BYTES = 262_144
 
 export class NoticeQueue {
   /**
-   * @param {{sender: import("./types.js").NoticeSender, minimumIntervalMs?: number, batchWindowMs?: number, maxLength?: number, maxPendingNotices?: number, maxPendingBytes?: number, sleep?: (milliseconds: number) => Promise<void>, now?: () => number, random?: () => number}} options
+   * @param {{sender: import("./types.js").NoticeSender, onDelivered?: (metricClass: string, bytes: number) => void, minimumIntervalMs?: number, batchWindowMs?: number, maxLength?: number, maxPendingNotices?: number, maxPendingBytes?: number, sleep?: (milliseconds: number) => Promise<void>, now?: () => number, random?: () => number}} options
    */
   constructor(options) {
     this.sender = options.sender
+    this.onDelivered = options.onDelivered
     this.minimumIntervalMs = nonnegativeSafeInteger(options.minimumIntervalMs ?? 1000, "minimumIntervalMs")
     this.batchWindowMs = nonnegativeSafeInteger(options.batchWindowMs ?? 0, "batchWindowMs")
     this.maxLength = positiveSafeInteger(options.maxLength ?? DEFAULT_MAX_LENGTH, "maxLength")
@@ -85,19 +86,19 @@ export class NoticeQueue {
   takeBatch() {
     const first = this.shiftPending()
     if (!first) return {message: ""}
-    if ("activity" in first) return {message: this.capActivity(first), activity: first.activity}
-    if (first.format === "javascript-code") return {message: this.takeCodeBatch(first)}
+    if ("activity" in first) return {message: this.capActivity(first), activity: first.activity, ...metricClass(first)}
+    if (first.format === "javascript-code") return {message: this.takeCodeBatch(first), ...metricClass(first)}
     let text = first.text
     const batchSeparator = first.batchSeparator ?? "\n"
     while (this.pending.length > 0) {
       const next = this.pending[0]
-      if (!next || "activity" in next || next.format !== undefined || next.label !== first.label || (next.batchSeparator ?? "\n") !== batchSeparator) break
+      if (!next || "activity" in next || next.metricClass !== first.metricClass || next.format !== undefined || next.label !== first.label || (next.batchSeparator ?? "\n") !== batchSeparator) break
       const combined = `${text}${batchSeparator}${next.text}`
       if (combined.length > this.maxLength) break
       this.shiftPending()
       text = combined
     }
-    if (text.length <= this.maxLength) return {message: text}
+    if (text.length <= this.maxLength) return {message: text, ...metricClass(first)}
     const label = first.label ?? /^\[P\d+\] /u.exec(text)?.[0] ?? ""
     if (label.length >= this.maxLength) throw new NoticeQueueChunkingError()
     let end = safeChunkEnd(text, this.maxLength)
@@ -110,7 +111,7 @@ export class NoticeQueue {
     if (end <= label.length) throw new NoticeQueueChunkingError()
     const remainder = `${label}${text.slice(remainderStart)}`
     this.unshiftPending({...first, text: remainder})
-    return {message: text.slice(0, end)}
+    return {message: text.slice(0, end), ...metricClass(first)}
   }
 
   /**
@@ -196,10 +197,12 @@ export class NoticeQueue {
   async deliver(delivery) {
     if (delivery.activity === undefined) {
       await this.withRetry(() => this.sender.send(delivery.message))
+      this.noteDelivered(delivery)
       return
     }
     if (delivery.activity.phase === "started") {
       const sent = await this.withRetry(() => this.sender.send(delivery.message))
+      this.noteDelivered(delivery)
       const messageId = deliveredMessageId(sent)
       if (messageId !== undefined) this.activityMessageIds.set(delivery.activity.key, messageId)
       return
@@ -219,11 +222,18 @@ export class NoticeQueue {
     // swallow, so only an unrecoverable edit is dropped.
     try {
       await this.withRetry(() => edit(messageId, delivery.message))
+      this.noteDelivered(delivery)
     } catch {
       // Intentionally non-fatal: a failed completion edit never poisons the queue.
     }
   }
 
+  /** @param {Delivery} delivery */
+  noteDelivered(delivery) {
+    if (delivery.metricClass === undefined) return
+    this.onDelivered?.(delivery.metricClass, Buffer.byteLength(JSON.stringify(delivery.message), "utf8"))
+  }
+
   /** @template T @param {() => Promise<T>} operation @returns {Promise<T>} */
   async withRetry(operation) {
     for (let attempt = 0; attempt < 4; attempt += 1) {
@@ -241,6 +251,11 @@ export class NoticeQueue {
   }
 }
 
+/** @param {import("./types.js").RenderedNotice} notice */
+function metricClass(notice) {
+  return notice.metricClass === undefined ? {} : {metricClass: notice.metricClass}
+}
+
 /** @param {import("./types.js").SentMessage | void} sent @returns {number | undefined} */
 function deliveredMessageId(sent) {
   if (sent !== undefined && Number.isSafeInteger(sent.messageId)) return sent.messageId

package/src/providers/opencode.js

@@ -18,12 +18,11 @@ export function buildOpenCodeCommand(providerArguments, prompt, resumeSession, e
 export function createOpenCodeSessionId() {
   let emitted = false
   return (record) => {
-    if (emitted || !isRecord(record)) return undefined
-    const id = typeof record.sessionID === "string"
-      ? record.sessionID
-      : isRecord(record.part) && typeof record.part.sessionID === "string" ? record.part.sessionID : undefined
-    if (id !== undefined) emitted = true
-    return id
+    if (emitted) return undefined
+    const {sessionId, trusted} = recognizeOpenCodeRecord(record, () => [])
+    if (!trusted || sessionId === undefined) return undefined
+    emitted = true
+    return sessionId
   }
 }
 
@@ -31,29 +30,47 @@ export function createOpenCodeSessionId() {
 export function createOpenCodeParser() {
   let started = false
   const activeToolKeys = new Set()
-  return (record) => filterRepeatedToolStarts(parseOpenCodeRecord(record, () => {
+  return (record) => filterRepeatedToolStarts(recognizeOpenCodeRecord(record, () => {
     if (started) return []
     started = true
     return [{type: "lifecycle", phase: "started", summary: "OpenCode worker started"}]
-  }), activeToolKeys)
+  }).events, activeToolKeys)
 }
 
 /** @param {unknown} record @returns {import("../types.js").WorkerEvent[]} */
 export function parseOpenCodeEvent(record) {
-  return parseOpenCodeRecord(record, () => [{type: "lifecycle", phase: "started", summary: "OpenCode worker started"}])
+  return recognizeOpenCodeRecord(record, () => [{type: "lifecycle", phase: "started", summary: "OpenCode worker started"}]).events
 }
 
-/** @param {unknown} record @param {() => import("../types.js").WorkerEvent[]} start @returns {import("../types.js").WorkerEvent[]} */
-function parseOpenCodeRecord(record, start) {
-  if (!isRecord(record) || typeof record.type !== "string") return []
-  if (record.type === "step_start") return start()
-  if (record.type === "step_finish") return []
-  if (record.type === "error") return [{type: "lifecycle", phase: "failed", summary: "OpenCode worker failed"}]
+/**
+ * @param {unknown} record
+ * @param {() => import("../types.js").WorkerEvent[]} start
+ * @returns {{trusted: boolean, sessionId: string | undefined, events: import("../types.js").WorkerEvent[]}}
+ */
+function recognizeOpenCodeRecord(record, start) {
+  if (!isRecord(record) || typeof record.type !== "string") return {trusted: false, sessionId: undefined, events: []}
+  const part = isRecord(record.part) ? record.part : undefined
+  if (record.type === "step_start" && part?.type === "step-start") {
+    return {trusted: true, sessionId: sessionIdForKnownRecord(record, part), events: start()}
+  }
+  if (record.type === "step_finish" && part?.type === "step-finish") {
+    return {trusted: true, sessionId: sessionIdForKnownRecord(record, part), events: []}
+  }
+  if (record.type === "error" && part?.type === "error") {
+    return {trusted: true, sessionId: sessionIdForKnownRecord(record, part), events: [{type: "lifecycle", phase: "failed", summary: "OpenCode worker failed"}]}
+  }
   if (record.type === "text" && isRecord(record.part) && typeof record.part.text === "string") {
-    return [{type: "text-delta", text: record.part.text, streamId: stringValue(record.part.id, "opencode:assistant")}]
+    return {
+      trusted: true,
+      sessionId: sessionIdForKnownRecord(record, record.part),
+      events: [{type: "text-delta", text: record.part.text, streamId: stringValue(record.part.id, "opencode:assistant")}]
+    }
   }
-  if (record.type === "tool_use" && isRecord(record.part)) return parseTool(record.part)
-  return []
+  if (record.type === "tool_use" && isRecord(record.part)) {
+    const events = parseTool(record.part)
+    if (events.length > 0) return {trusted: true, sessionId: sessionIdForKnownRecord(record, record.part), events}
+  }
+  return {trusted: false, sessionId: undefined, events: []}
 }
 
 /** @param {Record<string, unknown>} part @returns {import("../types.js").WorkerEvent[]} */
@@ -104,6 +121,13 @@ function stringValue(value, fallback) {
   return typeof value === "string" ? value : fallback
 }
 
+/** @param {Record<string, unknown>} record @param {Record<string, unknown> | undefined} [part] */
+function sessionIdForKnownRecord(record, part) {
+  if (typeof record.sessionID === "string") return record.sessionID
+  if (part !== undefined && typeof part.sessionID === "string") return part.sessionID
+  return undefined
+}
+
 /** @param {unknown} value @returns {value is Record<string, unknown>} */
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value)

package/src/relay.js

@@ -45,7 +45,7 @@ export class Relay {
       return
     }
     const text = this.renderActivity(event)
-    if (text) this.queue.enqueue({text, label: `${this.label} `})
+    if (text) this.queue.enqueue({text, label: `${this.label} `, metricClass: event.type})
   }
 
   /**
@@ -60,7 +60,7 @@ export class Relay {
     if (event.phase === "started") {
       const description = this.toolDescription(event)
       this.activeToolDescriptions.set(event.key, {description, hasDetail: event.detail !== undefined && event.detail.length > 0})
-      this.queue.enqueue({activity: {key: event.key, phase: "started"}, text: `🛠 ${this.label} Tool: ${description}`})
+      this.queue.enqueue({activity: {key: event.key, phase: "started"}, text: `🛠 ${this.label} Tool: ${description}`, metricClass: "tool"})
       return
     }
     const stored = this.activeToolDescriptions.get(event.key)
@@ -71,10 +71,10 @@ export class Relay {
     const status = `✅ ${this.label} Tool: ${description}`
     const html = renderCompletedOutput(status, event.output, this.outputMessageLimit())
     if (html === undefined) {
-      this.queue.enqueue({activity: {key: event.key, phase: "finished"}, text: status})
+      this.queue.enqueue({activity: {key: event.key, phase: "finished"}, text: status, metricClass: "tool"})
       return
     }
-    this.queue.enqueue({activity: {key: event.key, phase: "finished"}, text: html, parseMode: "HTML"})
+    this.queue.enqueue({activity: {key: event.key, phase: "finished"}, text: html, parseMode: "HTML", metricClass: "tool"})
   }
 
   /**
@@ -165,10 +165,10 @@ export class Relay {
 
   /** @param {string} text */
   enqueueAssistant(text) {
-    if (this.inJavaScriptFence) this.queue.enqueue({text, format: "javascript-code", label: `${this.label} Assistant:`})
+    if (this.inJavaScriptFence) this.queue.enqueue({text, format: "javascript-code", label: `${this.label} Assistant:`, metricClass: "assistant"})
     else {
       const label = `${this.label} Assistant: `
-      this.queue.enqueue({text: `${label}${text.replaceAll(/(\r\n|[\n\r\u2028\u2029])(?=.)/gu, `$1${label}`)}`, label, batchSeparator: ""})
+      this.queue.enqueue({text: `${label}${text.replaceAll(/(\r\n|[\n\r\u2028\u2029])(?=.)/gu, `$1${label}`)}`, label, batchSeparator: "", metricClass: "assistant"})
     }
   }
 

package/src/run-worker.js

@@ -6,17 +6,25 @@ import {StringDecoder} from "node:string_decoder"
 import {buildProviderEnvironment} from "./telegram-ingress/config.js"
 
 const DEFAULT_MAX_STDOUT_RECORD_BYTES = 1_048_576
+const DEFAULT_TERMINATION_GRACE_PERIOD_MS = 5_000
 
 /**
- * @typedef {{executable: string, arguments: string[], cwd: string, environment?: NodeJS.ProcessEnv, parse: (record: unknown) => import("./types.js").WorkerEvent[], onEvent: (event: import("./types.js").WorkerEvent) => void, onSpawn?: (pid: number) => void, onRecord?: (record: unknown) => void, spawnImplementation?: typeof nodeSpawn, maxStdoutRecordBytes?: number}} RunWorkerOptions
+ * @typedef {{executable: string, arguments: string[], cwd: string, environment?: NodeJS.ProcessEnv, parse: (record: unknown) => import("./types.js").WorkerEvent[], onEvent: (event: import("./types.js").WorkerEvent) => void | Promise<void>, onSpawn?: (pid: number) => void, onRecord?: (record: unknown) => void | Promise<void>, onStdoutChunk?: (chunk: Buffer) => void | Promise<void>, onStderrChunk?: (chunk: Buffer) => void | Promise<void>, spawnImplementation?: typeof nodeSpawn, maxStdoutRecordBytes?: number, terminationGracePeriodMs?: number, setTimer?: (callback: () => void, milliseconds: number) => unknown, clearTimer?: (handle: unknown) => void, platform?: NodeJS.Platform, killProcess?: (pid: number, signal: NodeJS.Signals) => boolean}} RunWorkerOptions
  */
 
 /** @param {RunWorkerOptions} options @returns {Promise<number>} */
 export function runWorker(options) {
   const maxStdoutRecordBytes = positiveSafeInteger(options.maxStdoutRecordBytes ?? DEFAULT_MAX_STDOUT_RECORD_BYTES, "maxStdoutRecordBytes")
+  const terminationGracePeriodMs = positiveSafeInteger(options.terminationGracePeriodMs ?? DEFAULT_TERMINATION_GRACE_PERIOD_MS, "terminationGracePeriodMs")
+  const platform = options.platform ?? process.platform
   const spawnImplementation = options.spawnImplementation ?? nodeSpawn
+  const killProcess = options.killProcess ?? ((pid, signal) => process.kill(pid, signal))
+  const setTimer = options.setTimer ?? ((callback, milliseconds) => setTimeout(callback, milliseconds))
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(/** @type {ReturnType<typeof setTimeout>} */ (handle)))
+  const useDetachedProcessGroup = platform !== "win32"
   const child = spawnImplementation(options.executable, options.arguments, {
     cwd: options.cwd,
+    detached: useDetachedProcessGroup,
     env: childEnvironment(options.environment ?? process.env),
     shell: false,
     stdio: ["ignore", "pipe", "pipe"]
@@ -28,48 +36,124 @@ export function runWorker(options) {
 
   return new Promise((resolve, reject) => {
     let settled = false
+    /** @type {number | null} */
+    let closeCode = null
+    /** @type {NodeJS.Signals | null} */
+    let closeSignal = null
+    let closeSeen = false
+    /** @type {Promise<void>} */
+    let consumer = Promise.resolve()
+    /** @type {Error | null} */
+    let shutdownError = null
+    /** @type {unknown | null} */
+    let terminationTimer = null
+    const processGroupPid = useDetachedProcessGroup && isPositiveSafeInteger(child.pid) ? child.pid : null
     /** @param {NodeJS.Signals} signal */
-    const forwardSignal = (signal) => child.kill(signal)
+    const forwardSignal = (signal) => signalChildTree(child, processGroupPid, signal, killProcess)
     const onInterrupt = () => forwardSignal("SIGINT")
     const onTerminate = () => forwardSignal("SIGTERM")
-    /** @param {Error} error @param {boolean} [terminateChild] */
-    const fail = (error, terminateChild = true) => {
+    const clearTerminationTimer = () => {
+      if (terminationTimer === null) return
+      clearTimer(terminationTimer)
+      terminationTimer = null
+    }
+    const detachForShutdown = () => {
+      child.stdout?.removeListener("data", onStdout)
+      child.stderr?.removeListener("data", onStderr)
+      child.removeListener("spawn", onSpawn)
+      child.removeListener("error", onError)
+      removeSignalHandlers(onInterrupt, onTerminate)
+    }
+    const cleanup = () => {
+      detachForShutdown()
+      clearTerminationTimer()
+      child.removeListener("close", onClose)
+    }
+    /** @param {Error} error */
+    const rejectAndCleanup = (error) => {
       if (settled) return
       settled = true
       cleanup()
-      if (terminateChild) {
-        try { child.kill("SIGTERM") } catch { /* Child may already be gone. */ }
-      }
       reject(error)
     }
+    /** @param {Error} error @param {boolean} [terminateChild] */
+    const fail = (error, terminateChild = true) => {
+      if (settled || shutdownError) return
+      if (!terminateChild) {
+        rejectAndCleanup(error)
+        return
+      }
+      if (closeSeen) {
+        if (processGroupPid === null) {
+          try {
+            forwardSignal("SIGTERM")
+          } catch {
+            /* Child may already be gone. */
+          }
+        }
+        rejectAndCleanup(error)
+        return
+      }
+      shutdownError = error
+      detachForShutdown()
+      try {
+        forwardSignal("SIGTERM")
+      } catch {
+        /* Child may already be gone. */
+      }
+      terminationTimer = setTimer(() => {
+        if (settled || shutdownError === null) return
+        terminationTimer = null
+        try {
+          forwardSignal("SIGKILL")
+        } catch {
+          /* Child may already be gone. */
+        }
+        rejectAndCleanup(shutdownError)
+      }, terminationGracePeriodMs)
+    }
+    /**
+     * @param {() => Promise<void>} task
+     * @param {NodeJS.ReadableStream | undefined} stream
+     */
+    const enqueueConsumer = (task, stream) => {
+      stream?.pause()
+      consumer = consumer
+        .then(async () => {
+          if (settled || shutdownError) return
+          await task()
+        })
+        .then(() => {
+          stream?.resume()
+          if (closeSeen) void finalizeClose()
+        })
+        .catch((error) => {
+          fail(toError(error))
+        })
+    }
     /** @param {Buffer | string} chunk */
     const onStdout = (chunk) => {
-      if (settled) return
-      try {
+      if (settled || shutdownError) return
+      enqueueConsumer(async () => {
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+        await options.onStdoutChunk?.(bytes)
         stdoutRecordBytes = nextRecordByteCount(bytes, stdoutRecordBytes, maxStdoutRecordBytes)
         stdoutBuffer += stdoutDecoder.write(bytes)
-        stdoutBuffer = drainLines(stdoutBuffer, options.parse, options.onEvent, options.onRecord)
-      } catch (error) {
-        fail(toError(error))
-      }
+        stdoutBuffer = await drainLines(stdoutBuffer, options.parse, options.onEvent, options.onRecord)
+      }, child.stdout)
     }
-    const onStderr = () => {
-      if (settled || stderrSeen) return
-      stderrSeen = true
-      try {
-        options.onEvent({type: "diagnostic", level: "warning", summary: "Worker wrote diagnostics to stderr"})
-      } catch (error) {
-        fail(toError(error))
-      }
-    }
-    const cleanup = () => {
-      child.stdout?.removeListener("data", onStdout)
-      child.stderr?.removeListener("data", onStderr)
-      child.removeListener("spawn", onSpawn)
-      child.removeListener("error", onError)
-      child.removeListener("close", onClose)
-      removeSignalHandlers(onInterrupt, onTerminate)
+    /** @param {Buffer | string} chunk */
+    const onStderr = (chunk) => {
+      if (settled || shutdownError) return
+      enqueueConsumer(
+        async () => {
+          await options.onStderrChunk?.(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+          if (stderrSeen) return
+          stderrSeen = true
+          await options.onEvent({type: "diagnostic", level: "warning", summary: "Worker wrote diagnostics to stderr"})
+        },
+        child.stderr
+      )
     }
     /** @param {Error} error */
     const onError = (error) => fail(error, false)
@@ -82,19 +166,36 @@ export function runWorker(options) {
         fail(toError(error))
       }
     }
-    /** @param {number | null} code @param {NodeJS.Signals | null} signal */
-    const onClose = (code, signal) => {
+    const finalizeClose = async () => {
       if (settled) return
+      if (shutdownError) {
+        settled = true
+        cleanup()
+        reject(shutdownError)
+        return
+      }
       try {
+        await consumer
+        if (settled) return
         stdoutBuffer += stdoutDecoder.end()
-        if (stdoutBuffer.trim().length > 0) parseLine(stdoutBuffer, options.parse, options.onEvent, options.onRecord)
+        if (stdoutBuffer.trim().length > 0) await parseLine(stdoutBuffer, options.parse, options.onEvent, options.onRecord)
       } catch (error) {
         fail(toError(error), false)
         return
       }
       settled = true
       cleanup()
-      resolve(code ?? signalExitCode(signal))
+      resolve(closeCode ?? signalExitCode(closeSignal))
+    }
+    /** @param {number | null} code @param {NodeJS.Signals | null} signal */
+    const onClose = (code, signal) => {
+      if (settled) return
+      closeSeen = true
+      removeSignalHandlers(onInterrupt, onTerminate)
+      closeCode = code
+      closeSignal = signal
+      clearTerminationTimer()
+      void finalizeClose()
     }
     child.stdout?.on("data", onStdout)
     child.stderr?.on("data", onStderr)
@@ -125,26 +226,32 @@ export function childEnvironment(environment = process.env) {
 }
 
 /** @param {string} buffer @param {RunWorkerOptions["parse"]} parse @param {RunWorkerOptions["onEvent"]} onEvent @param {RunWorkerOptions["onRecord"]} onRecord */
-function drainLines(buffer, parse, onEvent, onRecord) {
+async function drainLines(buffer, parse, onEvent, onRecord) {
   const lines = buffer.split("\n")
   const tail = lines.pop() ?? ""
-  for (const line of lines) parseLine(line, parse, onEvent, onRecord)
+  for (const line of lines) await parseLine(line, parse, onEvent, onRecord)
   return tail
 }
 
 /** @param {string} line @param {RunWorkerOptions["parse"]} parse @param {RunWorkerOptions["onEvent"]} onEvent @param {RunWorkerOptions["onRecord"]} onRecord */
-function parseLine(line, parse, onEvent, onRecord) {
+async function parseLine(line, parse, onEvent, onRecord) {
   if (line.trim().length === 0) return
+  let record
+  try {
+    record = JSON.parse(line)
+  } catch {
+    await onEvent({type: "diagnostic", level: "warning", summary: "Worker emitted an unreadable event"})
+    return
+  }
+  await onRecord?.(record)
   let events
   try {
-    const record = JSON.parse(line)
-    onRecord?.(record)
     events = parse(record)
   } catch {
-    onEvent({type: "diagnostic", level: "warning", summary: "Worker emitted an unreadable event"})
+    await onEvent({type: "diagnostic", level: "warning", summary: "Worker emitted an unreadable event"})
     return
   }
-  for (const event of events) onEvent(event)
+  for (const event of events) await onEvent(event)
 }
 
 /** @param {NodeJS.Signals | null} signal */
@@ -153,6 +260,17 @@ function signalExitCode(signal) {
   return 128 + (osConstants.signals[signal] ?? 0)
 }
 
+/** @param {unknown} value @returns {value is number} */
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+}
+
+/** @param {ReturnType<typeof nodeSpawn>} child @param {number | null} processGroupPid @param {NodeJS.Signals} signal @param {(pid: number, signal: NodeJS.Signals) => boolean} killProcess */
+function signalChildTree(child, processGroupPid, signal, killProcess) {
+  if (processGroupPid !== null) return killProcess(-processGroupPid, signal)
+  return child.kill(signal)
+}
+
 /** @param {() => void} onInterrupt @param {() => void} onTerminate */
 function removeSignalHandlers(onInterrupt, onTerminate) {
   process.removeListener("SIGINT", onInterrupt)

package/src/telegram-ingress/command.js

@@ -3,6 +3,7 @@
 import {PROVIDERS} from "../providers/index.js"
 
 const COMMAND_PATTERN = /^\/code(?:@[A-Za-z0-9_]+)?\s+(codex|claude|opencode)\s+(\S[\s\S]*)$/u
+const EVIDENCE_PATTERN = /^\/evidence(?:@[A-Za-z0-9_]+)?\s+(evidence_[A-Za-z0-9_-]{43})\s+(bytes|lines)\s+(\d+):(\d+)$/u
 
 /**
  * @typedef {{provider: "codex" | "claude" | "opencode", prompt: string}} CodeCommand
@@ -27,3 +28,18 @@ export function parseCodeCommand(text) {
     prompt
   }
 }
+
+/** @param {string} text */
+export function parseEvidenceCommand(text) {
+  if (typeof text !== "string") return null
+  const match = EVIDENCE_PATTERN.exec(text)
+  if (!match) return null
+  const handle = match[1]
+  const selector = match[2]
+  const start = Number(match[3])
+  const limit = Number(match[4])
+  if (!handle || !Number.isSafeInteger(start) || !Number.isSafeInteger(limit) || limit <= 0) return null
+  if (selector === "bytes" && start >= 0) return {handle, bytes: {offset: start, limit}}
+  if (selector === "lines" && start > 0) return {handle, lines: {start, limit}}
+  return null
+}