@huynle/hub 0.8.7 → 0.9.1

package/src/spoke/spoke.ts

@@ -36,9 +36,11 @@ import { extractReply } from "../reply"
 import { copiesHubIdentity, forkIdentityNote, notAUserMessage, opError, REVERT_BUSY, REVERT_END_BUSY, revertPreview, revertSummary, userContent, userIndex, visibleMessages, withStagedAt } from "./fork-revert"
 import { TurnTracker } from "../turns"
 import { TimelineCache, boundedTimelinePart, newestPage, timelineFile, timelineItems } from "./timeline"
+import { MediaCache, timelineMedia, type MediaMessages } from "./media"
+import { BundleCache, previewBundle } from "./preview-bundle"
 import { CodedError, SpokeConnection, type Backoff, type ConnectionState } from "./client"
-import { PROMPT_SOURCE, VOICE_AGENT } from "./conversation"
-import { DeliveryLedger, deferredWhileBusy, deliverMetadata, deliverText, harnessMessageID, InboxOrigins, planDelivery, QUIET_WHILE_BUSY, REVERT_STAGED } from "./deliver"
+import { isHubPrompt, PROMPT_SOURCE, VOICE_AGENT } from "./conversation"
+import { DeliveryLedger, deferredWhileBusy, deliverDescription, deliverMetadata, deliverText, harnessMessageID, InboxOrigins, planDelivery, QUIET_WHILE_BUSY, REVERT_STAGED } from "./deliver"
 import { pollEnrollment, startEnrollment } from "./enroll"
 import { HerdrWatcher, openInHerdr, type HerdrRunner } from "./herdr"
 import type { LocalHubResult } from "./localhub"
@@ -51,6 +53,7 @@ import { CONCIERGE_AGENT } from "../../packages/protocol/src/concierge.ts"
 import { changeStats, contextUsage, filePatch, mcpServers } from "./summary"
 import { browserSessions, eventSessionID, isExposed, isReported, SessionTracker, shouldForward, type EventLike, type SessionDetails } from "./tracker"
 import { renderTaskBoard, TaskBoard } from "./taskboard"
+import { FRONT_TITLE_PREFIX, frontTitle, relayDelivery, trimText, VOICE_FRONT_AGENT, VoiceFronts } from "./voice-front"
 import { watchConfig, type ConfigWatcher } from "./watch"
 
 export type SpokeErrorName = "not_connected" | "not_enrolled" | "invalid" | "unreachable"
@@ -103,9 +106,10 @@ export interface SpokeHost {
   /**
    * Admits text as a synthetic user message (OpenCode's session.synthetic): the model sees only `text`; the
    * prompt hook does not run. `id` (msg_…) makes it idempotent; `resume: false` admits without waking.
+   * `description`: the one-line notice the TUI shows for it (the model does not see it).
    * Absent: this OpenCode cannot take hub messages (no "deliver" feature).
    */
-  synthetic?(input: { sessionID: string; id: string; text: string; metadata: Record<string, unknown>; delivery: DeliveryMode; resume: boolean }): Promise<{ id?: string }>
+  synthetic?(input: { sessionID: string; id: string; text: string; description?: string; metadata: Record<string, unknown>; delivery: DeliveryMode; resume: boolean }): Promise<{ id?: string }>
   context(sessionID: string): Promise<ReadonlyArray<unknown>>
   listModels?(): Promise<ReadonlyArray<unknown>>
   getSession(sessionID: string): Promise<HostSession>
@@ -155,8 +159,10 @@ export interface SpokeHost {
    */
   /** `signal` aborts when the spoke abandons the listing because it timed out (listingTimeoutMs): stop asking the server. */
   listRecent?(options?: { days: number; max: number; include: readonly string[]; signal?: AbortSignal }): Promise<Array<{ id: string } & SessionDetails>>
-  /** Creates a session in a directory (service processes only). */
+  /** Creates a session in a directory (the create op: service processes only; voice fronts: any process). */
   createSession?(input: { directory: string; title?: string }): Promise<{ id: string }>
+  /** Deletes a session (OpenCode's session.remove); a voice front when its conversation ends. */
+  removeSession?(sessionID: string): Promise<unknown>
   /** MCP servers and their status for a directory (raw OpenCode McpServer list). */
   mcpList?(directory: string): Promise<ReadonlyArray<unknown>>
   /** Working-tree changes of a directory (raw OpenCode FileDiffInfo list); undefined when nothing can read that directory. */
@@ -181,6 +187,11 @@ export interface SpokeHost {
   revertClear?(sessionID: string): Promise<unknown>
   /** Makes a staged revert permanent (session.revert.commit). Absent with the two above: no "revert". */
   revertCommit?(sessionID: string): Promise<unknown>
+  /**
+   * (S4 M2) An item of OpenCode's media store (`media:<sha256>` URIs of tool output), read from the own server;
+   * undefined when it has none or cannot be reached. Absent: media: items are not served.
+   */
+  fetchMedia?(hash: string): Promise<{ bytes: Uint8Array; mime?: string } | undefined>
 }
 
 /** A session's pending forms and permission requests as OpenCode lists them (raw, see SpokeHost.pending). */
@@ -262,6 +273,8 @@ export interface SpokeOptions {
    * spoke never enrols, starts a local hub or reads Herdr.
    */
   readonly launch?: LaunchConfig
+  /** Voice-front wakes within this window are merged into one (default 1.5 s). */
+  readonly frontMergeMs?: number
 }
 
 export type EnrollmentState = "pending" | "approved" | "denied" | "expired" | "error"
@@ -362,6 +375,10 @@ export class Spoke {
   private readonly turns = new TurnTracker()
   /** Timeline rows of sessions being paged through (30 s, dropped on any event of the session). */
   private readonly timelines = new TimelineCache()
+  /** (S4 M2) Decoded timeline images, so later chunks do not read the history again; dropped on any revert. */
+  private readonly media = new MediaCache()
+  /** (Session media §3 4b) Walked HTML preview bundles, for the chunks of their larger files. */
+  private readonly bundles = new BundleCache()
   /** Per session: a counter of revert events (a staged event's late read must not undo a later one). */
   private readonly revertSeq = new Map<string, number>()
   private readonly voiceTurns = new Map<string, number>()
@@ -385,6 +402,30 @@ export class Spoke {
   /** Session → callbacks waiting for its next session.renamed event (autoName). */
   private readonly renameWaiters = new Map<string, Set<(title: string) => void>>()
   private conversationChain: Promise<unknown> = Promise.resolve()
+  /** (feature "voiceFront") Main sessions ↔ their hidden voice-front sessions, and what each front knows of its main. */
+  readonly fronts: VoiceFronts
+  /** Fronts whose deletion failed: forgotten as fronts and never reported again. */
+  private readonly retiredFronts = new Set<string>()
+  /**
+   * Front creations under way, and the sessions they made that are not linked yet: OpenCode announces a new session
+   * before create() returns, so until linked, a "Voice: " session (or the made one) is left out of snapshots.
+   */
+  private frontsCreating = 0
+  /**
+   * Main → its front that failed (an execution error): no longer linked or woken, still reported hidden, deleted on
+   * off. `frontFallbacks`: mains whose front failed or vanished; the hub talks to them directly, as voice turns.
+   */
+  private readonly failedFronts = new Map<string, string>()
+  /**
+   * "Voice: " sessions this process has not linked, by what a check found (see checkVoiceTitled): "checking" and
+   * "hidden" are not reported, "user" is reported as usual, "front" (on the voice-front agent: another process's
+   * front, or one an earlier process left) is reported with agent voice-front and no voiceFrontOf: the hub decides
+   * whether it is stale and asks for its removal (removeFront). The spoke never deletes one on its own.
+   */
+  private readonly voiceTitled = new Map<string, "checking" | "user" | "front" | "hidden">()
+  private readonly frontFallbacks = new Set<string>()
+  private readonly unlinkedFronts = new Set<string>()
+  private frontWakes = 0
   private readonly abort = new AbortController()
   private snapshotTimer?: ReturnType<typeof setTimeout>
   /** Sessions the last snapshot sent listed (the hub keeps status only for sessions it was told about). */
@@ -446,6 +487,11 @@ export class Spoke {
   ) {
     this.config = options.launch ? launchVoiceConfig(options.launch, options.machineName) : readConfig(options.configFile, options.machineName)
     this.hub = { pending: false, nextAt: 0, cooldown: options.localHubRetryMs ?? 30_000 }
+    this.fronts = new VoiceFronts({
+      ...(options.frontMergeMs !== undefined ? { mergeMs: options.frontMergeMs } : {}),
+      send: (front, text) => void this.wakeFront(front, text),
+      frontBusy: (front) => this.running.has(front) || this.tracker.isBusy(front),
+    })
     this.contexts = new SessionContexts({
       ...(options.conciergeLockFile ? { lockFile: options.conciergeLockFile } : {}),
       ...(options.conciergeLockReadFiles?.length ? { readLockFiles: options.conciergeLockReadFiles } : {}),
@@ -500,16 +546,76 @@ export class Spoke {
     this.connectionKey = ""
     this.tokens.clear()
     this.actTokens.clear()
+    this.fronts.stop()
   }
 
+  /** A voice-styled turn: a hub /turn asked for it, or the session's voice front failed (the hub talks to it now). */
   isVoiceTurn(sessionID: string): boolean {
-    return (this.voiceTurns.get(sessionID) ?? 0) > 0
+    return (this.voiceTurns.get(sessionID) ?? 0) > 0 || this.frontFallbacks.has(sessionID)
   }
 
+  /** Conversation mode is on: the agent swap (or its context-hook fallback), or a voice front (also a failed one). */
   inConversation(sessionID: string): boolean {
+    return this.conversations.has(sessionID) || this.fronts.frontOf(sessionID) !== undefined || this.frontFallbacks.has(sessionID)
+  }
+
+  /** The session itself is the voice orchestrator (today's agent swap): the context hook adds its parts. */
+  orchestrates(sessionID: string): boolean {
     return this.conversations.has(sessionID)
   }
 
+  /**
+   * voice_main_send: relays the user's request from a voice front to its main session, as the user's (hub-sourced)
+   * prompt. "auto": idle starts a turn, busy steers; "queue" waits behind main's running turn.
+   */
+  async frontSend(callerID: string, input: { text?: unknown; delivery?: unknown }): Promise<{ text: string; inboxID?: string }> {
+    const main = this.fronts.mainOf(callerID)
+    if (!main) return { text: "This session is not a voice front; nothing was sent." }
+    const text = typeof input.text === "string" ? input.text.trim() : ""
+    if (!text) return { text: "Pass the request as text; nothing was sent." }
+    const busy = this.running.has(main) || this.tracker.isBusy(main)
+    const delivery = relayDelivery(input.delivery, busy)
+    const inbox = await this.host.prompt({ sessionID: main, text, delivery, metadata: { source: PROMPT_SOURCE, kind: "voice-front" } })
+    if (delivery === "queue") {
+      this.fronts.queued(main, inbox.id, text)
+      return { text: "Queued for the main session; it runs after its current turn.", inboxID: inbox.id }
+    }
+    return { text: busy ? "Steered into the main session's running turn." : "Sent; the main session started working on it.", inboxID: inbox.id }
+  }
+
+  /** voice_main_stop: interrupts the front's main session and everything running below it (as the stop op). */
+  async frontStop(callerID: string): Promise<{ text: string; stopped: string[] }> {
+    const main = this.fronts.mainOf(callerID)
+    if (!main) return { text: "This session is not a voice front; nothing was stopped.", stopped: [] }
+    this.fronts.stopRequested(main)
+    const { stopped } = await this.stopTree(main)
+    return { text: "Stopped the main session's work.", stopped: [...stopped] }
+  }
+
+  /** The voice front's per-turn note about its main session; undefined for any other session. */
+  frontContext(sessionID: string): string | undefined {
+    const main = this.fronts.mainOf(sessionID)
+    if (!main) return undefined
+    const title = this.tracker.snapshot(Date.now()).find((s) => s.id === main)?.title
+    const workers = this.taskBoard(main)
+    return this.fronts.context(sessionID, { ...(title ? { title } : {}), busy: this.running.has(main) || this.tracker.isBusy(main), ...(workers ? { workers } : {}) })
+  }
+
+  /** A hub update for a front (`<system-update>`): admitted as the hub's (never the user's), steered, waking it. */
+  private async wakeFront(front: string, text: string): Promise<void> {
+    const metadata = { source: PROMPT_SOURCE, kind: "voice-front-update" }
+    try {
+      const synthetic = this.host.synthetic?.bind(this.host)
+      if (synthetic) {
+        const id = harnessMessageID(`voice-front:${front}:${Date.now()}:${++this.frontWakes}`)
+        this.origins.hub(id)
+        await synthetic({ sessionID: front, id, text, metadata: { ...metadata, messageID: id }, delivery: "steer", resume: true })
+      } else await this.host.prompt({ sessionID: front, text, delivery: "steer", metadata })
+    } catch (cause) {
+      console.error("[hub] could not wake the voice front", errorText(cause))
+    }
+  }
+
   /** The agent the voice orchestrator delegates to (per-machine config). */
   /** The model subagents should work on for a session in conversation mode, as "provider/model[#variant]". */
   workModelFor(sessionID: string): string | undefined {
@@ -606,6 +712,10 @@ export class Spoke {
       ...this.openSessions().keys(),
       ...this.tracker.active(),
       ...this.conversations.keys(),
+      ...this.fronts.mainIDs(),
+      ...this.fronts.mainIDs().map((id) => this.fronts.frontOf(id)!),
+      ...this.frontFallbacks,
+      ...this.failedFronts.values(),
       ...(this.config.mode === "session" ? this.config.sessions : []),
     ])
   }
@@ -651,9 +761,9 @@ export class Spoke {
    * orchestrator prompt. Off: restore the previous agent unless the user picked another meanwhile.
    * Calls are serialized so a re-sent "on" cannot race an "off".
    */
-  setConversation(sessionID: string, on: boolean): Promise<ResultFor["conversation"]> {
+  setConversation(sessionID: string, on: boolean, front = false, frontID?: string): Promise<ResultFor["conversation"]> {
     if (!isExposed(this.config, this.tracker, sessionID)) return Promise.reject(new SpokeError("invalid", NOT_SHARED))
-    const run = () => (on ? this.conversationOn(sessionID) : this.conversationOff(sessionID))
+    const run = () => (on ? this.conversationOn(sessionID, front, frontID) : this.conversationOff(sessionID))
     const result = this.conversationChain.then(run, run)
     this.conversationChain = result.catch(() => undefined)
     return result
@@ -915,7 +1025,8 @@ export class Spoke {
         opencodeVersion: this.host.opencodeVersion,
         pluginVersion: this.options.pluginVersion,
         // Hub messages and prompts need OpenCode's synthetic messages.
-        // Fork and revert need OpenCode's own server (the plugin API has neither).
+        // Fork and revert need OpenCode's own server (the plugin API has neither). "voiceFront" is always listed: a
+        // process that cannot create the front answers the conversation op without `front` (today's agent swap).
         features: SPOKE_FEATURES.filter(
           (f) =>
             ((f !== "deliver" && f !== "hubPrompt") || this.host.synthetic !== undefined) &&
@@ -1001,16 +1112,39 @@ export class Spoke {
     }
   }
 
-  private async conversationOn(sessionID: string): Promise<ResultFor["conversation"]> {
-    const entry = this.conversations.get(sessionID)
-    const session = await this.host.getSession(sessionID)
+  private async conversationOn(sessionID: string, front = false, frontID?: string): Promise<ResultFor["conversation"]> {
+    let entry = this.conversations.get(sessionID)
+    let session = await this.host.getSession(sessionID)
     // (CON-04) lockAgent: conversation mode is recorded, but the session keeps its agent and model (the Concierge
-    // never escapes its restricted agent, and the context hook adds no orchestrator parts).
+    // never escapes its restricted agent, and the context hook adds no orchestrator parts). It never gets a front.
     // A session on the concierge agent is locked too (a spoke that restarted before the hub re-sent the context).
     if (this.contexts.locked(sessionID) || session.agent === CONCIERGE_AGENT) {
       this.conversations.set(sessionID, {})
       return { agent: session.agent ?? (await this.defaultAgent()) }
     }
+    // The front failed: the hub talks to main directly and resends on without front (a reconnect). Main keeps its
+    // agent and model; its turns stay voice turns (frontFallbacks) until off.
+    if (!front && this.frontFallbacks.has(sessionID)) return { agent: session.agent ?? (await this.defaultAgent()) }
+    if (front) {
+      const live = this.fronts.frontOf(sessionID)
+      if (live && this.tracker.has(live)) return { agent: session.agent ?? (await this.defaultAgent()), front: { sessionID: live } }
+      // A failed front is replaced (deleted first); the session stops being a fallback.
+      await this.endFront(sessionID)
+      // Moving from the agent swap to a front: main gets its own agent and model back first.
+      if (entry) {
+        await this.conversationOff(sessionID)
+        entry = undefined
+        session = await this.host.getSession(sessionID)
+      }
+      // The hub knows this conversation's front (a resend to a restarted process): re-linked if it still exists.
+      const adopted = frontID ? await this.adoptFront(sessionID, frontID) : undefined
+      if (adopted) return { agent: session.agent ?? (await this.defaultAgent()), front: { sessionID: adopted } }
+      const created = await this.createFront(sessionID, session).catch((cause) => {
+        console.error("[hub] could not start a voice front; using the voice agent", errorText(cause))
+        return undefined
+      })
+      if (created) return { agent: session.agent ?? (await this.defaultAgent()), front: { sessionID: created } }
+    }
     this.rememberModel(sessionID, session.model)
     const current = session.agent
     const models = await this.voiceModelOn(sessionID, session, entry)
@@ -1044,7 +1178,156 @@ export class Spoke {
     return { voiceModel, ...(previousModel ? { previousModel } : {}) }
   }
 
+  /**
+   * Creates main's voice front: a root session in main's directory, titled after it, on the voice-front agent and
+   * the voice model, reported with voiceFrontOf. Throws (after removing a half-made front) when it cannot.
+   */
+  private async createFront(main: string, session: HostSession): Promise<string> {
+    const create = this.host.createSession?.bind(this.host)
+    if (!create) throw new Error("this OpenCode process cannot create sessions")
+    if (!(await this.host.hasAgent(VOICE_FRONT_AGENT))) throw new Error(`no ${VOICE_FRONT_AGENT} agent`)
+    const directory = this.tracker.directoryOf(main) ?? session.location?.directory ?? this.host.directory
+    const title = frontTitle(session.title)
+    this.frontsCreating++
+    let id: string | undefined
+    try {
+      id = (await create({ directory, title })).id
+      this.unlinkedFronts.add(id)
+      try {
+        // Agent first: switching the agent may reset the model.
+        await this.host.switchAgent(id, VOICE_FRONT_AGENT)
+        const voice = this.voiceModelFor(main)
+        if (voice) await this.switchModel(id, voice)
+      } catch (cause) {
+        await this.host.removeSession?.(id).catch(() => undefined)
+        throw cause
+      }
+      this.fronts.link(main, id, await this.lastReply(main))
+    } finally {
+      this.frontsCreating--
+      if (id !== undefined) this.unlinkedFronts.delete(id)
+    }
+    const now = Date.now()
+    const source = this.tracker.snapshot(now).find((s) => s.id === main)
+    this.tracker.observe({ type: "session.created", data: { sessionID: id, title, location: { directory } } }, now)
+    this.tracker.setInfo(id, { title, directory, updated: now, ...(source?.project ? { project: source.project } : {}), ...(source?.projectName ? { projectName: source.projectName } : {}) })
+    this.sendSnapshot()
+    return id
+  }
+
+  /** A session that is (or may be) a front still being created: never reported as an ordinary session. */
+  private frontInMaking(s: { id: string; title?: string }): boolean {
+    if (this.frontMainOf(s.id)) return false
+    return this.unlinkedFronts.has(s.id) || (this.frontsCreating > 0 && (s.title ?? "").startsWith(FRONT_TITLE_PREFIX))
+  }
+
+  /**
+   * A "Voice: " session this process did not link, as checked (checkVoiceTitled): "checking" or "hidden" are held
+   * back from snapshots; "front" and "user" are reported.
+   */
+  private unlinkedFront(s: { id: string; title?: string }): boolean {
+    if (!(s.title ?? "").startsWith(FRONT_TITLE_PREFIX) || this.frontMainOf(s.id)) return false
+    const state = this.voiceTitled.get(s.id)
+    if (state === undefined) void this.checkVoiceTitled(s.id)
+    return state === undefined || state === "checking" || state === "hidden"
+  }
+
+  /** Whether a session this process did not link is a voice front (checked as "front"); see checkVoiceTitled. */
+  private unlinkedVoiceFront(sessionID: string): boolean {
+    return !this.frontMainOf(sessionID) && this.voiceTitled.get(sessionID) === "front"
+  }
+
+  /**
+   * Classifies an unlinked "Voice: " session. A front runs on the voice-front agent (OpenCode's session record names
+   * it): "front". Another agent or the default: "user". If the record cannot be read, a session without any message
+   * from a human (only the hub's prompts) is "hidden" (not reported, never deleted); one with a human's is "user".
+   */
+  private async checkVoiceTitled(sessionID: string): Promise<void> {
+    this.voiceTitled.set(sessionID, "checking")
+    let state: "user" | "front" | "hidden"
+    try {
+      state = (await this.host.getSession(sessionID)).agent === VOICE_FRONT_AGENT ? "front" : "user"
+    } catch {
+      state = await this.host
+        .context(sessionID)
+        .then((messages) => (messages.some((m) => (m as { type?: unknown }).type === "user" && !isHubPrompt((m as { metadata?: unknown }).metadata)) ? "user" : "hidden") as "user" | "hidden")
+        .catch(() => "user" as const)
+    }
+    // Linked meanwhile (a front this process is creating): checked again later if it is ever unlinked.
+    if (this.frontMainOf(sessionID) || this.unlinkedFronts.has(sessionID) || this.frontsCreating > 0) return void this.voiceTitled.delete(sessionID)
+    this.voiceTitled.set(sessionID, state)
+    if (state !== "hidden") this.scheduleSnapshot()
+  }
+
+  /**
+   * Re-links an existing front to main (the hub names it on a resend): only a session on the voice-front agent that
+   * this process has not linked to another session. Undefined when it is gone or no front.
+   */
+  private async adoptFront(main: string, frontID: string): Promise<string | undefined> {
+    if (frontID === main || (this.frontMainOf(frontID) ?? main) !== main) return undefined
+    const info = await this.host.getSession(frontID).catch(() => undefined)
+    if (info?.agent !== VOICE_FRONT_AGENT || (this.frontMainOf(frontID) ?? main) !== main) return undefined
+    this.fronts.link(main, frontID, await this.lastReply(main))
+    this.voiceTitled.delete(frontID)
+    const now = Date.now()
+    if (!this.tracker.has(frontID)) this.tracker.observe({ type: "session.created", data: { sessionID: frontID, title: info.title, location: info.location } }, now)
+    console.warn(`[hub] re-linked the voice front ${frontID} of ${main}`)
+    this.sendSnapshot()
+    return frontID
+  }
+
+  /** Main's latest assistant text, to seed its front's context. */
+  private async lastReply(main: string): Promise<{ lastText?: string }> {
+    const lastText = await this.host
+      .context(main)
+      .then((messages) => contextMessages(messages).filter((m) => m.role === "assistant").at(-1)?.text)
+      .catch(() => undefined)
+    return lastText ? { lastText: trimText(lastText) } : {}
+  }
+
+  /**
+   * removeFront: the hub found a voice front no conversation uses. Deleted only when it is on the voice-front agent
+   * and this process has not linked it (as a front, a failed front, or one being created).
+   */
+  private async removeFront(sessionID: string): Promise<ResultFor["removeFront"]> {
+    if (this.frontMainOf(sessionID) || this.unlinkedFronts.has(sessionID) || !this.host.removeSession) return { removed: false }
+    const agent = await this.host.getSession(sessionID).then((s) => s.agent, () => undefined)
+    if (agent !== VOICE_FRONT_AGENT || this.frontMainOf(sessionID) || this.unlinkedFronts.has(sessionID)) return { removed: false }
+    console.warn(`[hub] deleting a stale voice front the hub found: ${sessionID}`)
+    await this.host.interrupt(sessionID).catch(() => undefined)
+    await this.host.removeSession(sessionID)
+    return { removed: true }
+  }
+
+  /** The model a session's voice runs on: its voice selection, else the machine's voiceModel; undefined: default. */
+  private voiceModelFor(sessionID: string): ModelRef | undefined {
+    const selected = this.modelPrefs.get(sessionID)?.voice
+    if (selected) return { providerID: selected.providerID, id: selected.modelID, ...(selected.variant ? { variant: selected.variant } : {}) }
+    return this.config.voiceModel ? parseModelRef(this.config.voiceModel) : undefined
+  }
+
+  /**
+   * Ends main's voice front: interrupted, then deleted. If it cannot be deleted it is forgotten as a front and never
+   * reported again (OpenCode has no archive call). Main is untouched.
+   */
+  private async endFront(main: string): Promise<void> {
+    const front = this.fronts.unlink(main) ?? this.failedFronts.get(main)
+    this.failedFronts.delete(main)
+    this.frontFallbacks.delete(main)
+    if (!front) return
+    await this.host.interrupt(front).catch(() => undefined)
+    try {
+      if (!this.host.removeSession) throw new Error("this OpenCode process cannot delete sessions")
+      await this.host.removeSession(front)
+    } catch (cause) {
+      console.error("[hub] could not delete a voice front; it is no longer reported", errorText(cause))
+      this.retiredFronts.add(front)
+    }
+    if (this.tracker.observe({ type: "session.deleted", data: { sessionID: front } }, Date.now())) this.sendSnapshot()
+  }
+
   private async conversationOff(sessionID: string): Promise<ResultFor["conversation"]> {
+    await this.endFront(sessionID)
     const entry = this.conversations.get(sessionID)
     this.conversations.delete(sessionID)
     const session = await this.host.getSession(sessionID)
@@ -1145,6 +1428,27 @@ export class Spoke {
         return { detail: boundedTimelinePart(await this.host.context(req.sessionID), req.messageID, req.partID) }
       case "timelineFile":
         return timelineFile(await this.host.context(req.sessionID), req.messageID, req.index) satisfies ResultFor["timelineFile"]
+      case "timelineMedia":
+        return (await timelineMedia({
+          sessionID: req.sessionID,
+          messageID: req.messageID,
+          ref: req.ref,
+          ...(req.offset === undefined ? {} : { offset: req.offset }),
+          cache: this.media,
+          load: () => this.mediaMessages(req.sessionID),
+          directory: this.directoryOf(req.sessionID),
+          ...(this.host.fetchMedia ? { fetchMedia: (hash: string) => this.host.fetchMedia!(hash) } : {}),
+        })) satisfies ResultFor["timelineMedia"]
+      case "previewBundle":
+        return (await previewBundle({
+          sessionID: req.sessionID,
+          messageID: req.messageID,
+          path: req.path,
+          ...(req.bundle === undefined ? {} : { bundle: req.bundle, file: req.file!, offset: req.offset! }),
+          cache: this.bundles,
+          load: () => this.mediaMessages(req.sessionID),
+          directory: this.directoryOf(req.sessionID),
+        })) satisfies ResultFor["previewBundle"]
       case "steer": {
         const voice = isExposed(this.config, this.tracker, req.sessionID)
         if (voice) await this.applyVoiceModel(req.sessionID)
@@ -1162,6 +1466,8 @@ export class Spoke {
         return {}
       case "rename":
         return this.rename(req.sessionID, req.title)
+      case "removeFront":
+        return this.removeFront(req.sessionID)
       case "dismissError":
         this.unheardFailures.delete(req.sessionID)
         return { dismissed: this.tracker.dismissError(req.sessionID) } satisfies ResultFor["dismissError"]
@@ -1177,7 +1483,7 @@ export class Spoke {
         return patch ? { patch } : {}
       }
       case "conversation":
-        return this.setConversation(req.sessionID, req.on)
+        return this.setConversation(req.sessionID, req.on, req.front === true, req.front === true ? req.frontID : undefined)
       case "deliver":
         return this.deliver(req)
       case "sessionContext": {
@@ -1302,6 +1608,8 @@ export class Spoke {
     const staged = await this.host.revertStage!({ sessionID, messageID, files })
     const revert = withStagedAt(revertSummary(staged, messages) ?? revertSummary({ messageID }, messages)!, this.tracker.revertOf(sessionID), Date.now())
     this.timelines.invalidate(sessionID)
+    this.media.invalidate(sessionID)
+    this.bundles.invalidate(sessionID)
     // Sent at once even when OpenCode's staged event already set it (its snapshot may still be debounced).
     this.tracker.setRevert(sessionID, revert)
     this.sendSnapshot()
@@ -1311,6 +1619,8 @@ export class Spoke {
   /** After a restore or commit: no revert is staged; reported at once. */
   private revertDone(sessionID: string): Record<string, never> {
     this.timelines.invalidate(sessionID)
+    this.media.invalidate(sessionID)
+    this.bundles.invalidate(sessionID)
     this.tracker.setRevert(sessionID, undefined)
     this.sendSnapshot()
     return {}
@@ -1321,17 +1631,27 @@ export class Spoke {
    * revert is read from OpenCode's session (so one staged before this process saw it counts) and reported.
    */
   private async shownMessages(sessionID: string): Promise<readonly unknown[]> {
+    return (await this.mediaMessages(sessionID)).shown
+  }
+
+  /**
+   * The session's messages, those a timeline shows (shownMessages) and the message of a committed revert (it and
+   * those after it are gone): what timelineMedia checks a message against.
+   */
+  private async mediaMessages(sessionID: string): Promise<MediaMessages> {
+    const committed = this.tracker.committedOf(sessionID)?.messageID
     const [messages, session] = await Promise.all([
       this.host.context(sessionID),
       this.canRevert() ? this.host.getSession(sessionID).catch(() => undefined) : Promise.resolve(undefined),
     ])
-    if (!this.canRevert()) return messages
+    const base = { all: messages, ...(committed ? { committed } : {}) }
+    if (!this.canRevert()) return { ...base, shown: messages }
     const raw = session ? (session as { revert?: unknown }).revert : undefined
     const known = this.tracker.revertOf(sessionID)
     const read = session ? revertSummary(raw, messages) : known
     const revert = session && read ? withStagedAt(read, known, Date.now()) : read
     if (session && this.tracker.setRevert(sessionID, revert)) this.scheduleSnapshot()
-    return visibleMessages(messages, revert?.messageID)
+    return { ...base, shown: visibleMessages(messages, revert?.messageID) }
   }
 
   /**
@@ -1354,6 +1674,8 @@ export class Spoke {
    * late read only fills in the commit's window start.
    */
   private async observeRevert(event: EventLike, sessionID: string): Promise<void> {
+    this.media.invalidate(sessionID)
+    this.bundles.invalidate(sessionID)
     if (!this.tracker.has(sessionID)) return
     const seq = (this.revertSeq.get(sessionID) ?? 0) + 1
     this.revertSeq.set(sessionID, seq)
@@ -1398,7 +1720,7 @@ export class Spoke {
       const id = harnessMessageID(req.messageID)
       // Marked before sending: OpenCode may report it delivered before the call returns.
       this.origins.hub(id)
-      const admitted = await synthetic({ sessionID: req.sessionID, id, text: deliverText(req), metadata: deliverMetadata(req), delivery: plan.delivery, resume: plan.resume })
+      const admitted = await synthetic({ sessionID: req.sessionID, id, text: deliverText(req), description: deliverDescription(req), metadata: deliverMetadata(req), delivery: plan.delivery, resume: plan.resume })
       this.timelines.invalidate(req.sessionID)
       return { result: { delivered: plan.delivered, inboxID: typeof admitted?.id === "string" && admitted.id ? admitted.id : id }, resumed: plan.resume }
     })
@@ -1605,6 +1927,8 @@ export class Spoke {
   private async applyVoiceModel(sessionID: string): Promise<void> {
     const selected = this.modelPrefs.get(sessionID)?.voice
     const override = this.voiceOverrides.get(sessionID)
+    // A session with a voice front keeps its model: the voice selection is the front's.
+    if (this.fronts.frontOf(sessionID)) return
     if ((!selected && !override) || this.tracker.active().includes(this.tracker.rootOf(sessionID))) return
     const current = await this.currentModel(sessionID)
     const onOverride = override !== undefined && current !== undefined && sameModel(current, override.applied)
@@ -1798,6 +2122,8 @@ export class Spoke {
         this.tokens.delete(sessionID)
         this.actTokens.delete(sessionID)
         this.profiles.forget(sessionID)
+        this.media.invalidate(sessionID)
+        this.bundles.invalidate(sessionID)
       }
       if (event.type === "form.replied" || event.type === "form.cancelled") {
         const formID = (event.data as Record<string, unknown> | undefined)?.id
@@ -1813,6 +2139,7 @@ export class Spoke {
       }
       this.trackAsk(event)
       if (this.tracker.observe(event, Date.now())) this.scheduleSnapshot()
+      this.observeFronts(event, sessionID)
       if (REVERT_EVENTS.has(event.type) && typeof sessionID === "string") void this.observeRevert(event, sessionID)
       if (typeof sessionID === "string") this.profiles.settle(sessionID) // a turn boundary makes a staged profile effective
       if (this.host.listRecent && LISTING_EVENTS.has(event.type) && !(event.data as any)?.parentID) {
@@ -1825,6 +2152,42 @@ export class Spoke {
     }
   }
 
+  /**
+   * Feeds the voice fronts. A deleted main ends its front. A front that fails (as the hub sees it: front_failed) or is
+   * deleted is unlinked, never woken again, and its main falls back to direct voice turns until off.
+   */
+  private observeFronts(event: EventLike, sessionID: unknown): void {
+    this.fronts.observe(event, (id) => this.tracker.rootOf(id))
+    if (typeof sessionID !== "string") return
+    if (event.type === "session.execution.failed") {
+      const main = this.fronts.mainOf(sessionID)
+      if (!main) return
+      this.fronts.unlink(main)
+      this.failedFronts.set(main, sessionID)
+      this.frontFallbacks.add(main)
+      console.warn(`[hub] voice front of ${main} failed; the session talks directly until voice ends`)
+      return
+    }
+    if (event.type !== "session.deleted") return
+    if (this.fronts.frontOf(sessionID) || this.failedFronts.has(sessionID)) void this.endFront(sessionID)
+    const main = this.fronts.mainOf(sessionID)
+    if (main) {
+      this.fronts.unlink(main)
+      this.frontFallbacks.add(main)
+    }
+    for (const [mainID, front] of this.failedFronts) if (front === sessionID) this.failedFronts.delete(mainID)
+    this.retiredFronts.delete(sessionID)
+    this.voiceTitled.delete(sessionID)
+  }
+
+  /** The main session of a front, also of a failed one (still reported hidden until deleted). */
+  private frontMainOf(sessionID: string): string | undefined {
+    const main = this.fronts.mainOf(sessionID)
+    if (main) return main
+    for (const [mainID, front] of this.failedFronts) if (front === sessionID) return mainID
+    return undefined
+  }
+
   /** Sends an OpenCode event to the hub (compact), when connected and the hub may see its session. */
   private forward(event: EventLike): void {
     if (this.connection?.state !== "connected" || (!FORWARDED_EVENTS.has(event.type) && !COMPACTED_EVENTS.has(event.type))) return
@@ -2108,7 +2471,14 @@ export class Spoke {
     if (this.snapshotTimer) clearTimeout(this.snapshotTimer)
     this.snapshotTimer = undefined
     const tui = this.presenceBook.open(Date.now())
-    const sessions = browserSessions(this.config, this.tracker, Date.now(), { terminal: (id) => this.terminal(id, tui) }).map((s) => ({ ...s, ...this.contexts.report(s.id) }))
+    const sessions = browserSessions(this.config, this.tracker, Date.now(), { terminal: (id) => this.terminal(id, tui) })
+      .filter((s) => !this.retiredFronts.has(s.id) && !this.frontInMaking(s) && !this.unlinkedFront(s))
+      .map((s) => {
+        // A voice front is reported with its main (the hub routes through it and never lists it), always exposed.
+        const main = this.frontMainOf(s.id)
+        const front = main ? { voiceFrontOf: main, exposed: true, agent: VOICE_FRONT_AGENT } : this.unlinkedVoiceFront(s.id) ? { agent: VOICE_FRONT_AGENT } : {}
+        return { ...s, ...this.contexts.report(s.id), ...front }
+      })
     this.connection?.send({ t: "sessions", sessions })
     this.announced = new Set(sessions.map((s) => s.id))
     this.resendUnheardFailures()