threadwire 0.1.5 → 0.1.8

package/src/cli.js

@@ -1,28 +1,39 @@
 // @ts-check
 
 import {readFile} from "node:fs/promises"
-import {resolve} from "node:path"
+import {randomUUID} from "node:crypto"
+import {isAbsolute, 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 {NoticeQueue} from "./notice-queue.js"
 import {createProvider, PROVIDERS} from "./providers/index.js"
-import {Relay} from "./relay.js"
 import {runWorker} from "./run-worker.js"
 import {ActivityLog} from "./activity-log.js"
-import {HermesProtocol} from "./hermes-protocol.js"
-import {buildProviderEnvironment, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
+import {DelegatedResultAdmission, validateContinuationHandle} from "./delegated-result-admission.js"
+import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
 import {resolveWorkspaceProfile} from "./workspace-profile.js"
+import {WorkerControl} from "./worker-control.js"
+import {EvidenceStore} from "./evidence-store.js"
+import {ContextBudgetMetrics} from "./context-budget-metrics.js"
+import {isolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js"
+import {validateRelayWriteProviderArguments} from "./relay-write.js"
+import {abortable} from "./absolute-deadline.js"
+import {NormalizedOutput} from "./normalized-output.js"
 
 const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id>
   [--process-number <positive-integer>] [--cwd <directory>]
   [--workspace-profile <name>]
+  [--relay-write]
   [--tool-messages] [--max-output-length <positive-integer>]
-  [--resume-session <provider-session-id>] [--activity-log <local-jsonl-path>]
+  [--resume-session <provider-session-id>] [--transcript <normalized-jsonl-path>]
+  [--activity-log <local-jsonl-path>]
   [--prompt <text> | --prompt-file <path> | stdin]
-  [-- <provider arguments...>]`
+  [-- <provider arguments...>]
+       threadwire evidence read --handle <opaque-handle>
+  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)`
 
-/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, workspaceProfile?: string, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, workspaceProfile?: string, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @typedef {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
 /**
  * @typedef {{
  *   env?: NodeJS.ProcessEnv,
@@ -31,7 +42,11 @@ const HELP = `Usage: threadwire run --provider <codex|claude|opencode> --target
  *   errorOutput?: NodeJS.WritableStream,
  *   transportFactory?: typeof createFetchTransport,
  *   workerRunner?: typeof runWorker,
+ *   evidenceStore?: EvidenceStore,
+ *   evidenceOwnerScope?: {destinationId: string, runId: string},
+ *   workerControlOptions?: Pick<ConstructorParameters<typeof WorkerControl>[0], "queueOptions">,
  *   workspaceProfileOperations?: import("./workspace-profile.js").WorkspaceProfileOperations
+ *   isolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "run">
  * }} MainDependencies
  */
 
@@ -44,8 +59,9 @@ export function parseArguments(arguments_) {
   const ownArguments = separator < 0 ? arguments_.slice(1) : arguments_.slice(1, separator)
   const providerArguments = separator < 0 ? [] : arguments_.slice(separator + 1)
   /** @type {Partial<ParsedArguments>} */
-  const parsed = {providerArguments, cwd: process.cwd(), toolMessages: false}
+  const parsed = {providerArguments, cwd: process.cwd(), toolMessages: false, relayWrite: false}
   let cwdProvided = false
+  let transcriptProvided = false
   for (let index = 0; index < ownArguments.length;) {
     const option = ownArguments[index]
     if (option === "--tool-messages") {
@@ -53,7 +69,15 @@ export function parseArguments(arguments_) {
       index += 1
       continue
     }
+    if (option === "--relay-write") {
+      parsed.relayWrite = true
+      index += 1
+      continue
+    }
     const value = ownArguments[index + 1]
+    if (option === "--transcript" && (value === undefined || value.startsWith("--"))) {
+      throw new Error("Missing value for --transcript")
+    }
     if (!option || !value) throw new Error(`Missing value for ${option ?? "option"}`)
     if (option === "--provider") parsed.provider = value
     else if (option === "--target") parsed.target = value
@@ -67,7 +91,12 @@ export function parseArguments(arguments_) {
     else if (option === "--max-output-length") parsed.maxOutputLength = positiveInteger(value, "--max-output-length")
     else if (option === "--resume-session") parsed.resumeSession = sessionId(value)
     else if (option === "--activity-log") parsed.activityLog = resolve(value)
-    else throw new Error(`Unknown option: ${option}`)
+    else if (option === "--transcript") {
+      if (transcriptProvided) throw new Error("Duplicate option: --transcript")
+      if (value.includes("\0")) throw new Error("--transcript path is invalid")
+      parsed.transcript = resolve(value)
+      transcriptProvided = true
+    } else throw new Error(`Unknown option: ${option}`)
     index += 2
   }
   if (!parsed.provider) throw new Error("--provider is required")
@@ -79,9 +108,54 @@ export function parseArguments(arguments_) {
   if (parsed.workspaceProfile !== undefined && cwdProvided) {
     throw new Error("--cwd and --workspace-profile are mutually exclusive")
   }
+  if (parsed.transcript !== undefined && parsed.transcript === parsed.activityLog) {
+    throw new Error("--transcript and --activity-log must resolve to different paths")
+  }
+  if (parsed.relayWrite && parsed.workspaceProfile === undefined) throw new Error("--relay-write requires --workspace-profile")
+  if (parsed.relayWrite && parsed.provider !== "codex") throw new Error("--relay-write is only supported for codex")
   return /** @type {ParsedArguments} */ (parsed)
 }
 
+/** @param {string[]} arguments_ @returns {EvidenceParsedArguments} */
+function parseEvidenceArguments(arguments_) {
+  if (arguments_[1] !== "read") throw new Error(HELP)
+  /** @type {Record<string, string>} */
+  const options = {}
+  for (let index = 2; index < arguments_.length; index += 2) {
+    const name = arguments_[index]
+    const value = arguments_[index + 1]
+    if (!name || !value || !["--handle", "--bytes", "--lines", "--query", "--context-bytes"].includes(name)) throw new Error(HELP)
+    if (options[name] !== undefined) throw new Error(`Duplicate evidence option: ${name}`)
+    options[name] = value
+  }
+  const handle = options["--handle"]
+  if (!handle) throw new Error("--handle is required")
+  const selectors = ["--bytes", "--lines", "--query"].filter((name) => options[name] !== undefined)
+  if (selectors.length !== 1) throw new Error("Exactly one bounded evidence selector is required")
+  let request
+  if (options["--bytes"]) request = {handle, bytes: rangePair(options["--bytes"], true)}
+  else if (options["--lines"]) request = {handle, lines: rangePair(options["--lines"], false)}
+  else {
+    const context = options["--context-bytes"]
+    if (!context) throw new Error("--context-bytes is required with --query")
+    request = {handle, query: {literal: options["--query"], limit: 1, contextBytes: positiveInteger(context, "--context-bytes")}}
+  }
+  if (options["--query"] === undefined && options["--context-bytes"] !== undefined) throw new Error("--context-bytes requires --query")
+  return {evidenceRead: true, request}
+}
+
+/** @param {string} value @param {boolean} zeroStart */
+function rangePair(value, zeroStart) {
+  const match = /^(\d+):(\d+)$/u.exec(value)
+  if (!match) throw new Error("Evidence range must be <start>:<limit>")
+  const start = Number(match[1])
+  const limit = Number(match[2])
+  if (!Number.isSafeInteger(start) || (!zeroStart && start < 1) || (zeroStart && start < 0) || !Number.isSafeInteger(limit) || limit < 1) {
+    throw new Error("Evidence range must contain bounded safe integers")
+  }
+  return zeroStart ? {offset: start, limit} : {start, limit}
+}
+
 /**
  * @param {string[]} arguments_
  * @param {MainDependencies} [dependencies]
@@ -92,13 +166,36 @@ export async function main(arguments_, dependencies = {}) {
   const sourceEnvironment = dependencies.env ?? process.env
   let environment = sourceEnvironment
   const validateOnly = environment.THREADWIRE_VALIDATE_ONLY === "1"
+  /** @type {NormalizedOutput | undefined} */
+  let normalizedOutput
+  /** @type {DelegatedResultAdmission | undefined} */
+  let runAdmission
   try {
-    const parsed = parseArguments(arguments_)
+    const parsed = arguments_[0] === "evidence" ? parseEvidenceArguments(arguments_) : parseArguments(arguments_)
     if ("help" in parsed) {
       if (!validateOnly) output.write(`${HELP}\n`)
       return 0
     }
+    if ("evidenceRead" in parsed) {
+      const root = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
+      if (!root) throw new Error("THREADWIRE_EVIDENCE_ROOT is required")
+      if (validateOnly) return 0
+      const store = await EvidenceStore.open({root})
+      try {
+        const result = await store.readBearer(parsed.request)
+        output.write(`${JSON.stringify(result)}\n`)
+        return 0
+      } finally {
+        await store.close()
+      }
+    }
+    if (!validateOnly) {
+      normalizedOutput = new NormalizedOutput(output, parsed.transcript)
+    }
+    const metrics = new ContextBudgetMetrics()
+    runAdmission = normalizedOutput === undefined ? undefined : new DelegatedResultAdmission({output: normalizedOutput, metrics})
     const target = parseTelegramTarget(parsed.target)
+    if (parsed.relayWrite) validateRelayWriteProviderArguments(parsed.providerArguments)
     const resolvedWorkspace = parsed.workspaceProfile === undefined
       ? undefined
       : await resolveWorkspaceProfile(
@@ -106,35 +203,76 @@ export async function main(arguments_, dependencies = {}) {
         dependencies.workspaceProfileOperations
       )
     if (validateOnly) return 0
-    environment = await resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"])
-    const hermes = new HermesProtocol({output})
+    const isolatedRuntimeClient = parsed.relayWrite
+      ? dependencies.isolatedRuntimeClient ?? isolatedRuntimeClientFromEnvironment(sourceEnvironment)
+      : undefined
+    const isolatedPreflight = parsed.relayWrite
+      ? await isolatedRuntimeClient?.preflight({
+        provider: parsed.provider,
+        profile: /** @type {string} */ (parsed.workspaceProfile),
+        repositoryRoot: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).repositoryRoot,
+        cwd: /** @type {import("./workspace-profile.js").ResolvedWorkspaceProfile} */ (resolvedWorkspace).cwd,
+        providerArguments: parsed.providerArguments,
+        ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession})
+      })
+      : undefined
+    const admission = /** @type {DelegatedResultAdmission} */ (runAdmission)
     let terminalExitCode = 2
+    /** @type {unknown} */
+    let evidenceError
     /** @type {ActivityLog | undefined} */
     let activity
+    /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
+    let evidence
+    /** @type {EvidenceStore | undefined} */
+    let ownedEvidenceStore
+    let evidencePayloadBytes = 0
+    const launchDeadline = isolatedPreflight?.deadline
     try {
-      const prompt = await readPrompt(parsed, dependencies.input ?? stdin)
+      environment = await boundedLaunch(resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"]), launchDeadline)
+      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
+      if (evidenceStore !== undefined) {
+        const evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
+          destinationId: `${target.chatId}:${target.threadId ?? "dm"}`,
+          runId: randomUUID()
+        })
+        evidence = await evidenceStore.createArtifact(evidenceOwner, {
+          contentType: "text/plain; charset=utf-8",
+          redactions: await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
+        })
+      }
+      if (evidence !== undefined) {
+        const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
+        await boundedLaunch(evidence.append("prompt", promptEvidence), launchDeadline)
+        evidencePayloadBytes += Buffer.byteLength(promptEvidence, "utf8")
+      }
       const providerEnvironment = buildProviderEnvironment(environment)
-      const provider = createProvider(parsed.provider, parsed.providerArguments, prompt, parsed.resumeSession, providerEnvironment)
+      const provider = createProvider(
+        parsed.provider,
+        parsed.providerArguments,
+        prompt,
+        parsed.resumeSession,
+        parsed.relayWrite ? {} : providerEnvironment
+      )
+      if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
       if (parsed.workspaceProfile !== undefined) {
         if (resolvedWorkspace === undefined) throw new Error("Workspace profile resolution failed")
-        hermes.write({
-          type: "execution_environment",
-          profile: resolvedWorkspace.profile,
-          environment: "container",
-          repositoryPath: resolvedWorkspace.cwd,
-          revision: resolvedWorkspace.revision,
-          sourceIdentity: resolvedWorkspace.sourceIdentity
-        })
       }
       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 queue = new NoticeQueue({sender: createTelegramSender(target, transport)})
-      const relay = new Relay({
-        queue,
+      const control = new WorkerControl({
+        sender: createTelegramSender(target, transport),
         processNumber: parsed.processNumber ?? process.pid,
         toolMessages: parsed.toolMessages,
-        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength})
+        ...(dependencies.workerControlOptions ?? {}),
+        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
+        metrics
       })
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
       if (activity && resolvedWorkspace) {
@@ -145,52 +283,187 @@ export async function main(arguments_, dependencies = {}) {
           resolvedWorkspace.sourceIdentity
         )
       }
-      const exitCode = await (dependencies.workerRunner ?? runWorker)({
+      /** @type {import("./run-worker.js").RunWorkerOptions} */
+      const workerOptions = {
         executable: provider.executable,
         arguments: provider.arguments,
         cwd: resolvedWorkspace?.cwd ?? parsed.cwd,
         environment: providerEnvironment,
         parse: provider.parse,
         onEvent: (event) => {
-          relay.accept(event)
-          hermes.accept(event)
+          validateNormalizedWorkerEvent(event)
+          if (event.type !== "text-delta") {
+            metrics.recordRejected(`${event.type}_progress`, Buffer.byteLength(JSON.stringify(event), "utf8"))
+          }
+          acceptAdmissionEvent(admission, event)
+          return control.accept(event)
         },
         onSpawn: (pid) => {
           if (activity && pid !== undefined) activity.recordStarted(provider.name, pid)
         },
         onRecord: (record) => {
+          metrics.recordParsedProviderRecord("provider_stdout")
           const id = provider.sessionId(record)
-          if (id !== undefined) activity?.recordSession(provider.name, id)
+          if (id !== undefined) {
+            admission.setContinuationHandle(id)
+            activity?.recordSession(provider.name, id)
+          }
+        },
+        onStdoutChunk: (chunk) => {
+          metrics.recordRawChildChunk("provider_stdout", chunk.length)
+          metrics.recordRejected("provider_stream", chunk.length)
+          if (evidence === undefined) return undefined
+          return evidence.append("provider-stdout", chunk).then(() => { evidencePayloadBytes += chunk.length })
+        },
+        onStderrChunk: (chunk) => {
+          metrics.recordRawChildChunk("provider_stderr", chunk.length)
+          metrics.recordRejected("stderr", chunk.length)
+          if (evidence === undefined) return undefined
+          return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
         }
-      })
-      await relay.close()
+      }
+      const exitCode = parsed.relayWrite
+        ? await /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).run({
+          preflightId: /** @type {{preflightId: string}} */ (isolatedPreflight).preflightId,
+          prompt,
+          providerArguments: parsed.providerArguments,
+          ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession}),
+          onEvent: workerOptions.onEvent,
+          onRecord: /** @type {NonNullable<typeof workerOptions.onRecord>} */ (workerOptions.onRecord),
+          ...(workerOptions.onStdoutChunk === undefined ? {} : {onStdoutChunk: workerOptions.onStdoutChunk}),
+          ...(workerOptions.onStderrChunk === undefined ? {} : {onStderrChunk: workerOptions.onStderrChunk}),
+          ...(launchDeadline === undefined ? {} : {deadline: launchDeadline})
+        })
+        : await (dependencies.workerRunner ?? runWorker)(workerOptions)
+      await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
-      return exitCode
     } finally {
-      hermes.complete(terminalExitCode)
+      if (evidence !== undefined) {
+        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)
+          await evidence.append("context-metrics", `${JSON.stringify(metrics.snapshot())}\n`)
+          const artifact = await evidence.finalize()
+          assertArtifactProjection(artifact.bytes, projectedArtifactBytes)
+        } catch (error) {
+          await evidence.abort()
+          admission.removeArtifactHandle(evidence.handle)
+          metrics.clearArtifact()
+          terminalExitCode = 2
+          evidenceError = error
+        }
+      }
+      admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
+      errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
       activity?.close()
+      await boundedLaunch(ownedEvidenceStore?.close(), launchDeadline).catch(() => {})
+      launchDeadline?.close()
     }
+    if (evidenceError !== undefined) throw evidenceError
+    return terminalExitCode
   } catch (error) {
-    errorOutput.write(`threadwire: ${safeMessage(error)}\n`)
+    let reportedError = error
+    if (runAdmission !== undefined && !runAdmission.completed) {
+      try {
+        runAdmission.complete({state: "failed", exitCode: 2})
+      } catch (transcriptError) {
+        reportedError = transcriptError
+      }
+    }
+    errorOutput.write(`threadwire: ${safeMessage(reportedError)}\n`)
     return 2
+  } finally {
+    try {
+      normalizedOutput?.close()
+    } catch (error) {
+      errorOutput.write(`threadwire: ${safeMessage(error)}\n`)
+    }
   }
 }
 
-/** @param {ParsedArguments} parsed @param {NodeJS.ReadableStream & {isTTY?: boolean}} input */
-async function readPrompt(parsed, input) {
+/** @param {string | undefined} value */
+function evidenceRoot(value) {
+  if (value === undefined) return undefined
+  if (!isAbsolute(value) || normalize(value) !== value) throw new Error("THREADWIRE_EVIDENCE_ROOT must be a normalized absolute path")
+  return value
+}
+
+/** @param {number} actual @param {number} projected */
+function assertArtifactProjection(actual, projected) {
+  if (actual !== projected) throw new Error("Context metrics artifact projection mismatch")
+}
+
+/** @param {DelegatedResultAdmission} admission @param {import("./types.js").WorkerEvent} event */
+function acceptAdmissionEvent(admission, event) {
+  if (event.type === "text-delta") admission.acceptConclusionEvent(event)
+}
+
+/** @param {unknown} event */
+function validateNormalizedWorkerEvent(event) {
+  if (!isPlainObject(event) || typeof event.type !== "string") {
+    throw new Error("invalid normalized worker event")
+  }
+  if (event.type === "text-delta") {
+    if (!hasExactEnumerableFields(event, ["type", "text", "streamId"]) || typeof event.text !== "string" || typeof event.streamId !== "string") {
+      throw new Error("invalid normalized worker event")
+    }
+    return
+  }
+  if (event.type === "lifecycle") {
+    if (
+      !hasExactEnumerableFields(event, ["type", "phase", "summary"])
+      || (event.phase !== "started" && event.phase !== "completed" && event.phase !== "failed")
+      || typeof event.summary !== "string"
+    ) throw new Error("invalid normalized worker event")
+    return
+  }
+  if (event.type === "diagnostic") {
+    if (
+      !hasExactEnumerableFields(event, ["type", "level", "summary"])
+      || (event.level !== "warning" && event.level !== "error")
+      || typeof event.summary !== "string"
+    ) throw new Error("invalid normalized worker event")
+    return
+  }
+  if (event.type === "tool") {
+    if (!isToolEventShape(event)) throw new Error("invalid normalized worker event")
+    return
+  }
+  throw new Error("Worker emitted an unknown normalized event kind")
+}
+
+/** @param {ParsedArguments} parsed @param {NodeJS.ReadableStream & {isTTY?: boolean}} input @param {AbortSignal | undefined} signal */
+async function readPrompt(parsed, input, signal) {
   let prompt
   if (parsed.prompt !== undefined) prompt = parsed.prompt
-  else if (parsed.promptFile !== undefined) prompt = await readFile(parsed.promptFile, "utf8")
+  else if (parsed.promptFile !== undefined) prompt = await readFile(parsed.promptFile, {encoding: "utf8", signal})
   else {
     if (input.isTTY) throw new Error("A prompt is required via --prompt, --prompt-file, or piped stdin")
     prompt = ""
     input.setEncoding("utf8")
-    for await (const chunk of input) prompt += chunk
+    const abort = () => /** @type {NodeJS.ReadableStream & {destroy?: (error?: unknown) => void}} */ (input).destroy?.(signal?.reason)
+    signal?.addEventListener("abort", abort, {once: true})
+    try {
+      for await (const chunk of input) {
+        if (signal?.aborted) throw signal.reason
+        prompt += chunk
+      }
+    } finally {
+      signal?.removeEventListener("abort", abort)
+    }
   }
   if (prompt.trim().length === 0) throw new Error("Prompt cannot be empty")
   return prompt
 }
 
+/** @param {Promise<unknown> | undefined} promise @param {import("./absolute-deadline.js").AbsoluteDeadline | undefined} deadline */
+function boundedLaunch(promise, deadline) {
+  deadline?.throwIfAborted()
+  return abortable(Promise.resolve(promise), deadline?.signal)
+}
+
 /** @param {unknown} error */
 function safeMessage(error) {
   return error instanceof Error ? error.message : "Unknown error"
@@ -207,6 +480,53 @@ function positiveInteger(value, option) {
 
 /** @param {string} value */
 function sessionId(value) {
-  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u.test(value)) throw new Error("--resume-session must be a valid provider session ID")
-  return value
+  try {
+    return validateContinuationHandle(value)
+  } catch {
+    throw new Error("--resume-session must be a valid provider session ID")
+  }
+}
+
+/** @param {Record<string, unknown>} event */
+function isToolEventShape(event) {
+  const allowed = event.phase === "finished"
+    ? ["type", "phase", "name", "key", "detail", "output"]
+    : ["type", "phase", "name", "key", "detail"]
+  if (
+    !hasOnlyAllowedEnumerableFields(event, allowed, ["type", "phase", "name", "key"])
+    || (event.phase !== "started" && event.phase !== "finished")
+    || typeof event.name !== "string"
+    || typeof event.key !== "string"
+    || (event.detail !== undefined && typeof event.detail !== "string")
+    || (event.output !== undefined && typeof event.output !== "string")
+  ) return false
+  if (event.phase === "started" && event.output !== undefined) return false
+  return true
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} expected */
+function hasExactEnumerableFields(value, expected) {
+  const fields = Reflect.ownKeys(value)
+  return fields.length === expected.length && fields.every((field) => (
+    typeof field === "string"
+    && expected.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} allowed @param {string[]} required */
+function hasOnlyAllowedEnumerableFields(value, allowed, required) {
+  const fields = Reflect.ownKeys(value)
+  return required.every((field) => Object.prototype.propertyIsEnumerable.call(value, field)) && fields.every((field) => (
+    typeof field === "string"
+    && allowed.includes(field)
+    && Object.prototype.propertyIsEnumerable.call(value, field)
+  ))
 }