threadwire 0.1.5 → 0.1.8

package/src/worker-control.js

@@ -0,0 +1,294 @@
+// @ts-check
+
+import {NoticeQueue} from "./notice-queue.js"
+import {Relay} from "./relay.js"
+
+export class WorkerControl {
+  /**
+   * @param {{
+   *   sender: import("./types.js").NoticeSender,
+   *   processNumber: number,
+   *   toolMessages?: boolean,
+   *   maxOutputLength?: number,
+   *   sentenceLatencyMs?: number,
+   *   maxAssistantBufferLength?: number,
+   *   setTimer?: (callback: () => void, milliseconds: number) => unknown,
+   *   clearTimer?: (handle: unknown) => void,
+   *   NoticeQueueClass?: typeof NoticeQueue,
+   *   RelayClass?: typeof Relay,
+   *   metrics?: import("./context-budget-metrics.js").ContextBudgetMetrics,
+   *   queueOptions?: Omit<ConstructorParameters<typeof NoticeQueue>[0], "sender" | "onDelivered">
+   * }} options
+   */
+  constructor(options) {
+    this.processLabel = `[P${options.processNumber}]`
+    this.metrics = options.metrics
+    this.toolMessages = options.toolMessages ?? false
+    this.saturationText = `${this.processLabel} Notifier saturated; coalescing progress updates.`
+    this.failure = undefined
+    this.saturated = false
+    this.saturationNoticeSent = false
+    this.coalescedNotice = undefined
+    /** @type {import("./types.js").RenderedNotice[]} */
+    this.renderedNotices = []
+    /** @type {Array<() => void>} */
+    this.availabilityWaiters = []
+    /** @type {Promise<void>} */
+    this.operation = Promise.resolve()
+    /** @type {Promise<void> | undefined} */
+    this.finalizePromise = undefined
+    /** @type {Promise<void> | undefined} */
+    this.closePromise = undefined
+    const sender = {
+      /** @param {string | import("./types.js").OutgoingMessage} message */
+      send: async (message) => {
+        const sent = await options.sender.send(message)
+        this.noteAvailability()
+        return sent
+      },
+      ...(options.sender.edit === undefined
+        ? {}
+        : {
+          /** @param {number} messageId @param {string | import("./types.js").OutgoingMessage} message */
+          edit: async (messageId, message) => {
+            await options.sender.edit?.(messageId, message)
+            this.noteAvailability()
+          }
+        })
+    }
+    const NoticeQueueClass = options.NoticeQueueClass ?? NoticeQueue
+    const RelayClass = options.RelayClass ?? Relay
+    this.queue = new NoticeQueueClass({
+      sender,
+      ...(options.queueOptions ?? {}),
+      onDelivered: (metricClass, bytes) => this.metrics?.recordProgress(metricClass, bytes, "delivered")
+    })
+    this.maxCoalescedBytes = this.queue.maxPendingBytes
+    const relayQueue = {
+      maxLength: this.queue.maxLength,
+      enqueue: /** @param {import("./types.js").RenderedNotice} notice */ (notice) => {
+        this.renderedNotices.push(notice)
+        this.scheduleBackgroundFlush()
+      },
+      close: async () => this.finalizeInternal()
+    }
+    this.relay = new RelayClass({
+      queue: /** @type {import("./notice-queue.js").NoticeQueue} */ (/** @type {unknown} */ (relayQueue)),
+      processNumber: options.processNumber,
+      ...(options.toolMessages === undefined ? {} : {toolMessages: options.toolMessages}),
+      ...(options.maxOutputLength === undefined ? {} : {maxOutputLength: options.maxOutputLength}),
+      ...(options.sentenceLatencyMs === undefined ? {} : {sentenceLatencyMs: options.sentenceLatencyMs}),
+      ...(options.maxAssistantBufferLength === undefined ? {} : {maxAssistantBufferLength: options.maxAssistantBufferLength}),
+      ...(options.setTimer === undefined ? {} : {setTimer: options.setTimer}),
+      ...(options.clearTimer === undefined ? {} : {clearTimer: options.clearTimer})
+    })
+  }
+
+  /** @param {import("./types.js").WorkerEvent} event */
+  accept(event) {
+    const metricClass = event.type === "text-delta" ? "assistant" : event.type
+    const bytes = Buffer.byteLength(JSON.stringify(event), "utf8")
+    this.metrics?.recordProgress(metricClass, bytes, "attempted")
+    if (event.type === "tool" && !this.toolMessages) this.metrics?.recordProgress("tool", bytes, "suppressed")
+    return this.enqueueOperation(async () => {
+      this.ensureHealthy()
+      this.relay.accept(event)
+      await this.flushLoop(false)
+      this.ensureHealthy()
+    })
+  }
+
+  close() {
+    if (!this.closePromise) {
+      this.closePromise = this.enqueueOperation(async () => {
+        await this.relay.close()
+      })
+    }
+    return this.closePromise
+  }
+
+  noteAvailability() {
+    this.signalAvailability()
+    if (this.failure || this.finalizePromise || this.queue.failure || this.queue.closed) return
+    this.scheduleBackgroundFlush()
+  }
+
+  scheduleBackgroundFlush() {
+    void this.enqueueOperation(async () => {
+      await this.flushLoop(false)
+    }).catch((error) => {
+      this.failure = toError(error)
+    })
+  }
+
+  /** @param {() => Promise<void>} operation */
+  enqueueOperation(operation) {
+    const next = this.operation.then(operation, operation)
+    this.operation = next.catch(() => {})
+    return next
+  }
+
+  async finalizeInternal() {
+    if (!this.finalizePromise) {
+      this.finalizePromise = (async () => {
+        await this.flushLoop(true)
+        await this.queue.close()
+        if (this.failure) throw this.failure
+      })()
+    }
+    return this.finalizePromise
+  }
+
+  /** @param {boolean} drainAll */
+  async flushLoop(drainAll) {
+    while (true) {
+      this.ensureHealthy()
+      if (this.tryFlushSaturationNotice()) continue
+      if (this.renderedNotices.length > 0) {
+        const notice = this.renderedNotices[0]
+        if (!notice) return
+        if (isCoalescibleAssistantProgress(notice, this.processLabel)) {
+          this.renderedNotices.shift()
+          if (this.canResumeHealthyProgress() && this.tryEnqueue(notice)) {
+            this.clearSaturation()
+            continue
+          }
+          if (!this.saturated && this.tryEnqueue(notice)) continue
+          this.saturated = true
+          this.metrics?.recordProgress("assistant", Buffer.byteLength(notice.text, "utf8"), "coalesced")
+          this.coalescedNotice = mergeCoalescedNotice(this.coalescedNotice, notice, this.maxCoalescedBytes)
+          continue
+        }
+        if (this.tryEnqueue(notice)) {
+          this.renderedNotices.shift()
+          continue
+        }
+        await this.waitForAvailability()
+        continue
+      }
+      if (this.saturated && !this.saturationNoticeSent) {
+        if (!drainAll) return
+        await this.waitForAvailability()
+        continue
+      }
+      if (this.coalescedNotice !== undefined) {
+        if (this.tryEnqueue(this.coalescedNotice)) {
+          this.coalescedNotice = undefined
+          this.clearSaturation()
+          continue
+        }
+        if (!drainAll) return
+        await this.waitForAvailability()
+        continue
+      }
+      return
+    }
+  }
+
+  tryFlushSaturationNotice() {
+    if (!this.saturated || this.saturationNoticeSent) return false
+    const notice = {text: this.saturationText, label: `${this.processLabel} `}
+    if (!this.tryEnqueue(notice)) return false
+    this.saturationNoticeSent = true
+    return true
+  }
+
+  canResumeHealthyProgress() {
+    return this.saturated && this.coalescedNotice === undefined && this.saturationNoticeSent
+  }
+
+  clearSaturation() {
+    this.saturated = false
+    this.saturationNoticeSent = false
+  }
+
+  /** @param {import("./types.js").RenderedNotice} notice */
+  tryEnqueue(notice) {
+    const noticeBytes = Buffer.byteLength(notice.text, "utf8")
+    if (noticeBytes > this.queue.maxPendingBytes) {
+      this.queue.enqueue(notice)
+      return true
+    }
+    if (this.queue.pendingNoticeCount >= this.queue.maxPendingNotices) return false
+    if (this.queue.pendingBytes + noticeBytes > this.queue.maxPendingBytes) return false
+    this.queue.enqueue(notice)
+    return true
+  }
+
+  async waitForAvailability() {
+    this.ensureHealthy()
+    if (!this.queue.processing) return
+    await Promise.race([
+      this.queue.work ?? Promise.resolve(),
+      new Promise((resolve) => { this.availabilityWaiters.push(() => resolve(undefined)) })
+    ])
+  }
+
+  signalAvailability() {
+    const waiters = this.availabilityWaiters.splice(0)
+    for (const resolve of waiters) resolve()
+  }
+
+  ensureHealthy() {
+    if (this.failure) throw this.failure
+    if (this.queue.failure) throw this.queue.failure
+    if (this.queue.closed) throw new Error("Notice queue is closed")
+  }
+}
+
+/**
+ * @param {import("./types.js").RenderedNotice} notice
+ * @param {string} processLabel
+ */
+function isCoalescibleAssistantProgress(notice, processLabel) {
+  return !("activity" in notice) && notice.format === undefined && notice.label === `${processLabel} Assistant: `
+}
+
+/**
+ * @param {import("./types.js").TextNotice | undefined} current
+ * @param {import("./types.js").TextNotice} incoming
+ * @param {number} maxBytes
+ * @returns {import("./types.js").TextNotice}
+ */
+function mergeCoalescedNotice(current, incoming, maxBytes) {
+  const next = trimAssistantNotice(incoming, maxBytes)
+  if (
+    current === undefined
+    || current.format !== incoming.format
+    || current.label !== incoming.label
+    || current.batchSeparator !== incoming.batchSeparator
+  ) return next
+  const combined = {...current, text: `${current.text}${incoming.text}`}
+  if (Buffer.byteLength(combined.text, "utf8") <= maxBytes) return combined
+  return next
+}
+
+/** @param {import("./types.js").TextNotice} notice @param {number} maxBytes */
+function trimAssistantNotice(notice, maxBytes) {
+  if (Buffer.byteLength(notice.text, "utf8") <= maxBytes) return notice
+  const label = notice.label ?? ""
+  const body = notice.text.startsWith(label) ? notice.text.slice(label.length) : notice.text
+  const available = Math.max(0, maxBytes - Buffer.byteLength(label, "utf8"))
+  return {...notice, text: `${label}${takeUtf8Prefix(body, available)}`}
+}
+
+/** @param {string} text @param {number} maxBytes */
+function takeUtf8Prefix(text, maxBytes) {
+  let end = 0
+  let bytes = 0
+  while (end < text.length) {
+    const codePoint = text.codePointAt(end)
+    if (codePoint === undefined) break
+    const character = String.fromCodePoint(codePoint)
+    const nextBytes = Buffer.byteLength(character, "utf8")
+    if (bytes + nextBytes > maxBytes) break
+    bytes += nextBytes
+    end += character.length
+  }
+  return text.slice(0, end)
+}
+
+/** @param {unknown} error */
+function toError(error) {
+  return error instanceof Error ? error : new Error("Worker control failed")
+}

package/src/hermes-protocol.js

@@ -1,126 +0,0 @@
-// @ts-check
-
-import {redactSecrets, sanitizeControl, sanitizeOutput} from "./relay.js"
-
-export const MAX_ASSISTANT_TEXT_LENGTH = 16_384
-export const MAX_TOOL_NAME_LENGTH = 128
-export const MAX_TOOL_DETAIL_LENGTH = 1_024
-export const MAX_TOOL_OUTPUT_LENGTH = 4_096
-export const MAX_PROGRESS_RECORDS = 64
-
-/**
- * Low-volume, caller-facing JSONL projection of normalized worker events.
- * Text deltas are retained only for the terminal result; raw provider records
- * never enter this component.
- */
-export class HermesProtocol {
-  /** @param {{output: NodeJS.WritableStream}} options */
-  constructor(options) {
-    this.output = options.output
-    this.progressRecords = 0
-    this.assistantText = ""
-    this.assistantTextTruncated = false
-    /** @type {Set<string>} */
-    this.transitions = new Set()
-    /** @type {Set<string>} */
-    this.lifecyclePhases = new Set()
-    /** @type {Map<string, {name: string, detail?: string}>} */
-    this.activeTools = new Map()
-  }
-
-  /** @param {import("./types.js").WorkerEvent} event */
-  accept(event) {
-    if (event.type === "text-delta") {
-      this.appendAssistantText(event.text)
-      return
-    }
-    if (this.progressRecords >= MAX_PROGRESS_RECORDS) return
-    if (event.type === "lifecycle") {
-      if (this.lifecyclePhases.has(event.phase)) return
-      this.lifecyclePhases.add(event.phase)
-      this.emit({type: lifecycleType(event.phase), summary: safeSingleLine(event.summary, 512)})
-      return
-    }
-    if (event.type === "diagnostic") {
-      this.emit({type: "diagnostic", level: event.level, summary: safeSingleLine(event.summary, 512)})
-      return
-    }
-    const transition = `${event.key}\0${event.phase}`
-    if (this.transitions.has(transition)) return
-    this.transitions.add(transition)
-    const current = this.activeTools.get(event.key)
-    const name = (current?.name ?? safeSingleLine(event.name, MAX_TOOL_NAME_LENGTH)) || "(tool)"
-    const incomingDetail = safeOptionalSingleLine(event.detail, MAX_TOOL_DETAIL_LENGTH)
-    const detail = current?.detail ?? incomingDetail
-    if (event.phase === "started") this.activeTools.set(event.key, {name, ...(detail === undefined ? {} : {detail})})
-    else this.activeTools.delete(event.key)
-    const output = event.phase === "finished" ? safeOptionalOutput(event.output, MAX_TOOL_OUTPUT_LENGTH) : undefined
-    this.emit({
-      type: event.phase === "started" ? "tool_started" : "tool_finished",
-      name,
-      ...(detail === undefined ? {} : {detail}),
-      ...(output === undefined ? {} : {output})
-    })
-  }
-
-  /** @param {number} exitCode */
-  complete(exitCode) {
-    const assistantText = safeOptionalOutput(this.assistantText, MAX_ASSISTANT_TEXT_LENGTH, this.assistantTextTruncated)
-    this.write({type: "completed", exitCode, ...(assistantText === undefined ? {} : {assistantText})})
-  }
-
-  /** @param {string} text */
-  appendAssistantText(text) {
-    if (this.assistantTextTruncated) return
-    const remaining = MAX_ASSISTANT_TEXT_LENGTH - Array.from(this.assistantText).length
-    const characters = Array.from(text)
-    if (characters.length <= remaining) this.assistantText += text
-    else {
-      this.assistantText += characters.slice(0, Math.max(0, remaining - 1)).join("") + "…"
-      this.assistantTextTruncated = true
-    }
-  }
-
-  /** @param {Record<string, unknown>} record */
-  emit(record) {
-    this.progressRecords += 1
-    this.write(record)
-  }
-
-  /** @param {Record<string, unknown>} record */
-  write(record) {
-    this.output.write(`${JSON.stringify(record)}\n`)
-  }
-}
-
-/** @param {"started" | "completed" | "failed"} phase */
-function lifecycleType(phase) {
-  return phase === "started" ? "worker_started" : phase === "failed" ? "worker_failed" : "worker_completed"
-}
-
-/** @param {string} text @param {number} limit */
-function safeSingleLine(text, limit) {
-  return limitText(redactSecrets(sanitizeControl(text)), limit)
-}
-
-/** @param {string | undefined} text @param {number} limit */
-function safeOptionalSingleLine(text, limit) {
-  if (text === undefined) return undefined
-  const safe = safeSingleLine(text, limit)
-  return safe.trim().length === 0 ? undefined : safe
-}
-
-/** @param {string | undefined} text @param {number} limit @param {boolean} [alreadyTruncated] */
-function safeOptionalOutput(text, limit, alreadyTruncated = false) {
-  if (text === undefined) return undefined
-  const safe = sanitizeOutput(text)
-  if (safe === undefined) return undefined
-  return alreadyTruncated ? safe : limitText(safe, limit)
-}
-
-/** @param {string} text @param {number} limit */
-function limitText(text, limit) {
-  const characters = Array.from(text)
-  if (characters.length <= limit) return text
-  return `${characters.slice(0, limit - 1).join("")}…`
-}