@huynle/hub 0.6.0 → 0.7.1

package/packages/preset/src/main.ts

@@ -0,0 +1,195 @@
+// `hub preset <list | check | run>`: the preset spoke's command line.
+//   list                        the official presets
+//   check <name|file>           validate a preset (presetProblem); exit 1 when it is not valid
+//   run <name|file> [options] [-- harness args…]
+//       starts the preset's command (an argv, never through a shell) in a new tmux pane and connects it to the hub
+//       as a preset spoke (evidence screen) until the pane ends or Ctrl-C/SIGTERM (which leaves the harness running).
+//       --socket <name>   the private tmux server (`tmux -L <name>`, default hub-preset): the user's own tmux server
+//                         is never touched, unless
+//       --current         a new window in the tmux session this runs in ($TMUX), only when asked
+//       --cwd <dir>       the harness's directory (default the current one)
+//       --resume <id>     resume a native session (the preset's resumeFlag)
+//       --no-hub          only start the pane and report it (no hub connection; no enrolment needed)
+// The native session ID is reported as the spoke knows it: passed on the command line or resumed ("reported, not
+// observed"), or read off the screen once it shows.
+import path from "node:path"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import { configPath } from "../../../src/config.ts"
+import pkg from "../package.json" with { type: "json" }
+import { findPreset, OFFICIAL_PRESETS } from "./presets.ts"
+import { PresetSpoke } from "./spoke.ts"
+import { tmuxBackend, tmuxRunner, type TerminalBackend, type TmuxRunner } from "./tmux.ts"
+
+export interface PresetIo {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly home: string
+  /** The working directory (default process.cwd()). */
+  readonly cwd?: string
+  stdout(s: string): void
+  stderr(s: string): void
+  /** Ends `run` (main.ts aborts it on SIGINT/SIGTERM). */
+  readonly signal?: AbortSignal
+  /** Runs tmux (default the `tmux` on PATH). */
+  readonly tmux?: TmuxRunner
+  readonly newID?: () => string
+  /** How often the pane is sampled (default the spoke's). */
+  readonly sampleMs?: number
+}
+
+export const PRESET_USAGE = `Usage: hub preset list
+       hub preset check <name|file>
+       hub preset run <name|file> [--socket <name> | --current] [--cwd <dir>] [--resume <id>] [--no-hub] [-- harness args…]`
+
+export const DEFAULT_SOCKET = "hub-preset"
+
+interface RunArgs {
+  readonly ref: string
+  readonly socket?: string
+  readonly current: boolean
+  readonly cwd?: string
+  readonly resume?: string
+  readonly noHub: boolean
+  readonly args: string[]
+}
+
+function parseRun(argv: readonly string[]): RunArgs | { error: string } {
+  const dash = argv.indexOf("--")
+  const own = dash >= 0 ? argv.slice(0, dash) : [...argv]
+  const args = dash >= 0 ? argv.slice(dash + 1) : []
+  let ref: string | undefined
+  const values: Record<string, string> = {}
+  const flags = new Set<string>()
+  for (let i = 0; i < own.length; i++) {
+    const arg = own[i]!
+    if (arg === "--socket" || arg === "--cwd" || arg === "--resume") {
+      const value = own[++i]
+      if (value === undefined || value.startsWith("--")) return { error: `${arg} needs a value` }
+      values[arg] = value
+    } else if (arg === "--current" || arg === "--no-hub") flags.add(arg)
+    else if (arg.startsWith("-")) return { error: `unknown option ${arg} (harness arguments go after --)` }
+    else if (ref === undefined) ref = arg
+    else return { error: `unexpected ${JSON.stringify(arg)} (harness arguments go after --)` }
+  }
+  if (ref === undefined) return { error: "run needs a preset name or file" }
+  if (flags.has("--current") && values["--socket"] !== undefined) return { error: "--current and --socket exclude each other" }
+  return {
+    ref,
+    current: flags.has("--current"),
+    noHub: flags.has("--no-hub"),
+    args,
+    ...(values["--socket"] !== undefined ? { socket: values["--socket"] } : {}),
+    ...(values["--cwd"] !== undefined ? { cwd: values["--cwd"] } : {}),
+    ...(values["--resume"] !== undefined ? { resume: values["--resume"] } : {}),
+  }
+}
+
+const message = (e: unknown) => (e instanceof Error ? e.message : String(e))
+
+async function run(argv: readonly string[], io: PresetIo): Promise<number> {
+  const parsed = parseRun(argv)
+  if ("error" in parsed) {
+    io.stderr(`hub preset: ${parsed.error}\n${PRESET_USAGE}\n`)
+    return 2
+  }
+  const cwd = io.cwd ?? process.cwd()
+  const found = findPreset(parsed.ref, { cwd })
+  if ("error" in found) {
+    io.stderr(`hub preset: ${found.error}\n`)
+    return 1
+  }
+  const preset = found.preset
+  if (parsed.resume !== undefined && !preset.resumeFlag) {
+    io.stderr(`hub preset: the ${preset.name} preset cannot resume a session (it has no resumeFlag)\n`)
+    return 1
+  }
+  let backend: TerminalBackend
+  try {
+    backend = tmuxBackend({
+      ...(parsed.current ? { current: true } : { socket: parsed.socket ?? DEFAULT_SOCKET }),
+      env: io.env,
+      run: io.tmux ?? tmuxRunner("tmux", io.env as NodeJS.ProcessEnv),
+    })
+  } catch (cause) {
+    io.stderr(`hub preset: ${message(cause)}\n`)
+    return 1
+  }
+  const credentials = parsed.noHub ? undefined : readSpokeCredentials(io.env, io.home)
+  if (!parsed.noHub && !credentials) {
+    io.stderr(`hub preset: this machine is not enrolled with a hub (no machine token in ${configPath(io.env, io.home)}); use --no-hub to only start the pane\n`)
+    return 1
+  }
+  const log = (line: string) => io.stderr(`[hub preset] ${line}\n`)
+  const spoke = new PresetSpoke({
+    preset,
+    backend,
+    server: credentials?.server ?? "http://127.0.0.1:1",
+    token: credentials?.token ?? "",
+    pluginVersion: pkg.version,
+    directory: cwd,
+    ...(io.newID ? { newID: io.newID } : {}),
+    ...(io.sampleMs !== undefined ? { sampleMs: io.sampleMs } : {}),
+    log,
+    onState: (state, error) => log(`hub connection ${state}${error ? `: ${error}` : ""}`),
+  })
+  if (credentials) spoke.start()
+  let launched
+  try {
+    launched = await spoke.launch({ cwd: parsed.cwd ? path.resolve(cwd, parsed.cwd) : cwd, args: parsed.args, ...(parsed.resume !== undefined ? { resume: parsed.resume } : {}) })
+  } catch (cause) {
+    spoke.stop()
+    io.stderr(`hub preset: ${message(cause)}\n`)
+    return 1
+  }
+  const where = parsed.current ? "the current tmux session" : `tmux session ${launched.pane.session} on socket ${parsed.socket ?? DEFAULT_SOCKET}`
+  const native = launched.nativeID
+    ? `${launched.nativeID.id} (${launched.nativeID.how})`
+    : preset.nativeID.source === "screen"
+      ? "not seen yet (read off the screen when it shows)"
+      : `none (the ${preset.name} preset has no session IDs)`
+  const lines = [
+    `started ${preset.name} in ${where}${parsed.current ? ` (window ${launched.pane.window})` : ""}, pane ${launched.pane.target}`,
+    credentials ? `session: ${launched.sessionID} (evidence screen: hub messages are pasted, never confirmed)` : "not connected to a hub (--no-hub): the pane runs on its own",
+    `native ID: ${native}`,
+    `attach: ${launched.attach}`,
+  ]
+  io.stdout(`${lines.join("\n")}\n`)
+  if (!credentials) return 0
+
+  const outcome = await new Promise<"ended" | "signal">((resolve) => {
+    spoke.onEnd((id) => id === launched.sessionID && resolve("ended"))
+    if (io.signal?.aborted) return resolve("signal")
+    io.signal?.addEventListener("abort", () => resolve("signal"), { once: true })
+  })
+  spoke.stop()
+  io.stdout(outcome === "ended" ? `${preset.name} ended (its pane is gone)\n` : `disconnected from the hub; ${preset.name} is still running in its pane (attach: ${launched.attach})\n`)
+  return 0
+}
+
+export async function presetMain(argv: readonly string[], io: PresetIo): Promise<number> {
+  const [command, ...rest] = argv
+  switch (command) {
+    case "list": {
+      const width = Math.max(...OFFICIAL_PRESETS.map((p) => p.name.length))
+      io.stdout(`${OFFICIAL_PRESETS.map((p) => `${p.name.padEnd(width)}  ${p.description ?? ""}`.trimEnd()).join("\n")}\n`)
+      return 0
+    }
+    case "check": {
+      if (rest.length !== 1) {
+        io.stderr(`hub preset: check needs one preset name or file\n${PRESET_USAGE}\n`)
+        return 2
+      }
+      const found = findPreset(rest[0]!, { cwd: io.cwd ?? process.cwd() })
+      if ("error" in found) {
+        io.stderr(`hub preset: ${found.error}\n`)
+        return 1
+      }
+      io.stdout(`${found.preset.name}: a valid preset (${found.source === "official" ? "official" : found.source})\n`)
+      return 0
+    }
+    case "run":
+      return run(rest, io)
+    default:
+      io.stderr(`${PRESET_USAGE}\n`)
+      return 2
+  }
+}

package/packages/preset/src/presets.ts

@@ -0,0 +1,87 @@
+// Presets (design §1.2 preset tier): the official ones shipped in presets/ (data only, imported statically so the CLI
+// bundle carries them), finding one by name or file, the argv a launch runs and the native ID read off the screen.
+// A preset is validated with the protocol's presetProblem before anything uses it; nothing here runs a shell.
+import { readFileSync } from "node:fs"
+import path from "node:path"
+import { presetProblem, type HarnessPreset } from "../../protocol/src/index.ts"
+import aider from "../presets/aider.json" with { type: "json" }
+import goose from "../presets/goose.json" with { type: "json" }
+
+/** Longest native ID taken from a screen (UTF-8 bytes; spoke-sdk MAX_NATIVE_BYTES, so it maps to a hub ID). */
+export const SCREEN_ID_MAX_BYTES = 98
+
+function official(raw: unknown): HarnessPreset {
+  const problem = presetProblem(raw)
+  if (problem) throw new Error(`Official preset ${JSON.stringify((raw as { name?: unknown })?.name)} is invalid: ${problem}`)
+  return raw as HarnessPreset
+}
+
+export const OFFICIAL_PRESETS: readonly HarnessPreset[] = [official(aider), official(goose)]
+
+export type FoundPreset = { readonly preset: HarnessPreset; readonly source: "official" | string } | { readonly error: string }
+
+/** Whether `ref` names a file rather than an official preset. */
+const isPath = (ref: string) => ref.includes("/") || ref.includes(path.sep) || ref.endsWith(".json")
+
+/** An official preset by name, or a preset file (a ref with a slash or ending in .json, relative to cwd), validated. */
+export function findPreset(ref: string, options: { readonly cwd: string }): FoundPreset {
+  if (!isPath(ref)) {
+    const preset = OFFICIAL_PRESETS.find((p) => p.name === ref)
+    if (preset) return { preset, source: "official" }
+    return { error: `no official preset ${JSON.stringify(ref)} (official: ${OFFICIAL_PRESETS.map((p) => p.name).join(", ")}; give a file path for your own)` }
+  }
+  const file = path.resolve(options.cwd, ref)
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (cause) {
+    return { error: `cannot read ${file}: ${(cause as NodeJS.ErrnoException).code ?? String(cause)}` }
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return { error: `${file} is not JSON` }
+  }
+  const problem = presetProblem(raw)
+  return problem ? { error: `${file} is not a valid preset: ${problem}` } : { preset: raw as HarnessPreset, source: file }
+}
+
+export interface LaunchArgvOptions {
+  /** Extra arguments for the harness (after the preset's own). */
+  readonly args?: readonly string[]
+  /** Resume this native session ID (needs the preset's resumeFlag). */
+  readonly resume?: string
+  /** A fresh native ID, for presets whose ID the hub passes on the command line (source argv). */
+  readonly newID: () => string
+}
+
+/** Control characters (a NUL would cut an argv element short; line breaks have no place in one). */
+const CONTROL = /[\u0000-\u001f\u007f]/
+
+/**
+ * The argv a launch runs (never through a shell) and the native session ID, when the hub knows it at launch: the one
+ * it passes (source argv) or resumes. A screen ID is only known once it shows (nativeIDFromScreen).
+ */
+export function launchArgv(preset: HarnessPreset, options: LaunchArgvOptions): { argv: string[]; nativeID: string | undefined } {
+  const args = [...(options.args ?? [])]
+  for (const arg of args) if (CONTROL.test(arg)) throw new Error(`Argument ${JSON.stringify(arg)} contains control characters`)
+  if (options.resume !== undefined) {
+    if (!preset.resumeFlag) throw new Error(`The ${preset.name} preset cannot resume a session (it has no resumeFlag)`)
+    if (options.resume === "" || CONTROL.test(options.resume)) throw new Error("The session ID to resume must be printable text")
+    return { argv: [...preset.command, preset.resumeFlag, options.resume, ...args], nativeID: options.resume }
+  }
+  if (preset.nativeID.source === "argv") {
+    const id = options.newID()
+    return { argv: [...preset.command, preset.nativeID.flag, id, ...args], nativeID: id }
+  }
+  return { argv: [...preset.command, ...args], nativeID: undefined }
+}
+
+/** The native session ID on `screen` (the first capture group of the preset's pattern), for source screen only. */
+export function nativeIDFromScreen(preset: HarnessPreset, screen: string): string | undefined {
+  if (preset.nativeID.source !== "screen") return undefined
+  const id = new RegExp(preset.nativeID.pattern).exec(screen)?.[1]
+  if (!id || Buffer.byteLength(id) > SCREEN_ID_MAX_BYTES || CONTROL.test(id)) return undefined
+  return id
+}

package/packages/preset/src/spoke.ts

@@ -0,0 +1,251 @@
+// The preset spoke (design §1.2 preset tier, decision fx04e42c point 6): a harness without a spoke of its own,
+// described by a data-only preset and driven through a terminal pane (TerminalBackend: tmux). Built on HarnessSpoke.
+//
+// It announces only what a pasted terminal can do, and claims no more than it sees (evidence "screen"):
+// - turn: the text is pasted into the pane and submitted; the hub is answered at once with outcome "timeout" and no
+//   reply (the spoke cannot see the harness take the prompt nor finish it: unconfirmed, never "succeeded");
+// - deliver: a hub message (wake) is pasted and submitted once per messageID and answered "queued"; without wake it
+//   is "retained" (nothing is typed into the user's input line) and pasted ahead of the session's next turn or
+//   message; a prompt (hubPrompt) goes in its provenance envelope;
+// - interrupt and stop: Ctrl-C, only when the backend can send keys;
+// - never permission, form or steer (a terminal paste can answer neither a dialog nor a running turn reliably);
+// - never an event: no activity, and above all no idle, is inferred from the screen (the hub never treats screen
+//   evidence as idle anyway). The screen is only sampled for the harness's native session ID (source screen) and the
+//   pane's liveness: the session ends with its pane.
+//
+// Session IDs: each launch gets a fresh UUID, its hub ID is hubSessionID("pr", uuid). For a preset whose native ID is
+// passed on the command line (source argv) that UUID is the native ID: reported, not observed (the spoke never sees
+// the harness use it).
+import { randomUUID } from "node:crypto"
+import path from "node:path"
+import type { HarnessPreset, SessionInfo } from "../../protocol/src/index.ts"
+import { deliverText, HarnessSpoke, hubSessionID, type Admission, type DeliverRequest, type HarnessSpokeOptions, type OpHandlers } from "../../spoke-sdk/src/index.ts"
+import { launchArgv, nativeIDFromScreen } from "./presets.ts"
+import type { TerminalBackend, TerminalPane } from "./tmux.ts"
+
+/** The hub session ID namespace of preset sessions (ses_pr…). */
+export const PRESET_SESSION_NAMESPACE = "pr"
+export const SAMPLE_MS = 2000
+/** Lines of screen searched for a native ID. */
+export const CAPTURE_LINES = 200
+
+export interface NativeID {
+  readonly id: string
+  /** How the spoke knows it: "read off the screen", or "reported, not observed (…)" when the hub passed it. */
+  readonly how: string
+}
+
+export interface PresetSpokeOptions {
+  readonly preset: HarnessPreset
+  readonly backend: TerminalBackend
+  readonly server: string
+  /** The machine token (never logged). */
+  readonly token: string
+  readonly pluginVersion: string
+  /** The spoke's directory (its hello). */
+  readonly directory: string
+  /** The harness's version, when known (default ""). */
+  readonly harnessVersion?: string
+  readonly newID?: () => string
+  readonly now?: () => number
+  readonly sampleMs?: number
+  readonly log?: (line: string) => void
+  readonly socket?: HarnessSpokeOptions["socket"]
+  readonly backoff?: HarnessSpokeOptions["backoff"]
+  readonly onState?: HarnessSpokeOptions["onState"]
+}
+
+export interface LaunchOptions {
+  readonly cwd: string
+  readonly args?: readonly string[]
+  /** Resume this native session ID (the preset's resumeFlag). */
+  readonly resume?: string
+  readonly env?: Readonly<Record<string, string>>
+}
+
+export interface Launched {
+  readonly sessionID: string
+  readonly pane: TerminalPane
+  readonly nativeID?: NativeID
+  /** How to look at the pane. */
+  readonly attach: string
+}
+
+interface Session {
+  readonly id: string
+  readonly pane: TerminalPane
+  nativeID?: NativeID
+  /** Hub messages admitted without waking, pasted ahead of the next submit. */
+  readonly retained: Array<{ readonly messageID: string; readonly text: string }>
+  /** Pastes into one pane run one after another. */
+  chain: Promise<unknown>
+}
+
+const unsafeName = /[^A-Za-z0-9_-]/g
+
+export class PresetSpoke {
+  readonly spoke: HarnessSpoke
+  readonly preset: HarnessPreset
+  readonly evidence = "screen" as const
+
+  readonly #backend: TerminalBackend
+  readonly #sessions = new Map<string, Session>()
+  readonly #newID: () => string
+  readonly #now: () => number
+  readonly #sampleMs: number
+  readonly #log: (line: string) => void
+  readonly #ended = new Set<(sessionID: string) => void>()
+  #timer: ReturnType<typeof setInterval> | undefined
+  #sampling = false
+
+  constructor(options: PresetSpokeOptions) {
+    this.preset = options.preset
+    this.#backend = options.backend
+    this.#newID = options.newID ?? randomUUID
+    this.#now = options.now ?? Date.now
+    this.#sampleMs = options.sampleMs ?? SAMPLE_MS
+    this.#log = options.log ?? (() => {})
+    const handlers: OpHandlers = {
+      turn: async (req) => {
+        if (req.images?.length) throw new Error(`The ${this.preset.name} preset spoke pastes text into a terminal: it cannot send images`)
+        await this.#submit(this.#session(req.sessionID), req.text)
+        return { outcome: "timeout", reply: "" }
+      },
+      ...(this.#backend.canSendKeys
+        ? {
+            interrupt: async (req: { sessionID: string }) => (await this.#interrupt(req.sessionID), {}),
+            stop: async (req: { sessionID: string }) => (await this.#interrupt(req.sessionID), { stopped: [req.sessionID] }),
+          }
+        : {}),
+    }
+    this.spoke = new HarnessSpoke({
+      server: options.server,
+      token: options.token,
+      harness: options.preset.name,
+      harnessVersion: options.harnessVersion ?? "",
+      evidence: "screen",
+      pluginVersion: options.pluginVersion,
+      directory: options.directory,
+      kind: "standalone",
+      mode: "always",
+      handlers,
+      deliver: (req) => this.#deliver(req),
+      features: ["hubPrompt"],
+      ...(options.socket ? { socket: options.socket } : {}),
+      ...(options.backoff ? { backoff: options.backoff } : {}),
+      ...(options.onState ? { onState: options.onState } : {}),
+    })
+  }
+
+  /** Connects to the hub and samples the panes now and then. */
+  start(): void {
+    this.spoke.start()
+    if (this.#timer || this.#sampleMs <= 0) return
+    this.#timer = setInterval(() => void this.sample(), this.#sampleMs)
+    this.#timer.unref?.()
+  }
+
+  stop(): void {
+    if (this.#timer) clearInterval(this.#timer)
+    this.#timer = undefined
+    this.spoke.stop()
+  }
+
+  /** Starts the preset's harness in a new pane and reports it as a session. */
+  async launch(options: LaunchOptions): Promise<Launched> {
+    const uuid = this.#newID()
+    const { argv, nativeID } = launchArgv(this.preset, { ...(options.args ? { args: options.args } : {}), ...(options.resume !== undefined ? { resume: options.resume } : {}), newID: () => uuid })
+    const name = `hub-${this.preset.name.replace(unsafeName, "_")}-${uuid.replace(unsafeName, "").slice(0, 8)}`
+    const pane = await this.#backend.launch({ argv, cwd: options.cwd, name, ...(options.env ? { env: options.env } : {}) })
+    const id = hubSessionID(PRESET_SESSION_NAMESPACE, uuid)
+    const known: NativeID | undefined =
+      nativeID === undefined
+        ? undefined
+        : options.resume !== undefined
+          ? { id: nativeID, how: `reported, not observed (resumed with ${this.preset.resumeFlag})` }
+          : { id: nativeID, how: `reported, not observed (passed with ${(this.preset.nativeID as { flag: string }).flag})` }
+    this.#sessions.set(id, { id, pane, ...(known ? { nativeID: known } : {}), retained: [], chain: Promise.resolve() })
+    const info: SessionInfo = { id, title: `${this.preset.name} · ${path.basename(options.cwd) || options.cwd}`, directory: options.cwd, updated: this.#now(), owned: true, open: true }
+    this.spoke.upsertSession(info)
+    return { sessionID: id, pane, ...(known ? { nativeID: known } : {}), attach: this.#backend.attachHint(pane) }
+  }
+
+  /** The session's native ID, when known. */
+  nativeID(sessionID: string): NativeID | undefined {
+    return this.#sessions.get(sessionID)?.nativeID
+  }
+
+  pane(sessionID: string): TerminalPane | undefined {
+    return this.#sessions.get(sessionID)?.pane
+  }
+
+  /** Calls `listener` with each session that ended (its pane is gone). */
+  onEnd(listener: (sessionID: string) => void): void {
+    this.#ended.add(listener)
+  }
+
+  /** One sampling round: ends sessions whose pane is gone, reads native IDs off the screen. Never sends an event. */
+  async sample(): Promise<void> {
+    if (this.#sampling) return
+    this.#sampling = true
+    try {
+      for (const session of [...this.#sessions.values()]) {
+        if (!(await this.#backend.alive(session.pane).catch(() => false))) {
+          this.#end(session.id)
+          continue
+        }
+        this.spoke.touch(session.id)
+        if (session.nativeID || this.preset.nativeID.source !== "screen") continue
+        const screen = await this.#backend.capture(session.pane, CAPTURE_LINES).catch(() => "")
+        const id = nativeIDFromScreen(this.preset, screen)
+        if (id) {
+          session.nativeID = { id, how: "read off the screen" }
+          this.#log(`session ${session.id}: native ID ${id} (read off the screen)`)
+        }
+      }
+    } finally {
+      this.#sampling = false
+    }
+  }
+
+  #end(sessionID: string): void {
+    if (!this.#sessions.delete(sessionID)) return
+    this.spoke.endSession(sessionID)
+    for (const listener of this.#ended) listener(sessionID)
+  }
+
+  #session(sessionID: string): Session {
+    const session = this.#sessions.get(sessionID)
+    if (!session) throw new Error(`Unknown session ${sessionID}`)
+    return session
+  }
+
+  /** Pastes the retained messages and `text`, then Enter; one paste at a time per pane. */
+  #submit(session: Session, text: string): Promise<void> {
+    const run = session.chain.then(async () => {
+      const ahead = session.retained.splice(0).map((m) => m.text)
+      await this.#backend.paste(session.pane, [...ahead, text].join("\n\n"), { submit: true })
+    })
+    session.chain = run.catch(() => {})
+    return run
+  }
+
+  async #deliver(req: DeliverRequest): Promise<Admission> {
+    const session = this.#session(req.sessionID)
+    const text = deliverText(req)
+    if (!req.wake) {
+      session.retained.push({ messageID: req.messageID, text })
+      return { result: { delivered: "retained" }, resumed: false }
+    }
+    // A retry that wakes a message first retained: it goes now, not again later.
+    const at = session.retained.findIndex((m) => m.messageID === req.messageID)
+    if (at >= 0) session.retained.splice(at, 1)
+    await this.#submit(session, text)
+    return { result: { delivered: "queued" }, resumed: true }
+  }
+
+  async #interrupt(sessionID: string): Promise<void> {
+    await this.#backend.interrupt(this.#session(sessionID).pane)
+  }
+}
+