@huynle/hub 0.8.6 → 0.9.0

package/src/central/unfurl-parse.ts

@@ -0,0 +1,313 @@
+// The link-preview parser of GET /api/media/unfurl (design §4, task RF3). The hub reads at most the first 512 KiB of
+// a page and keeps only plain text: the title (og:title > twitter:title > <title>), the description (og:description
+// > twitter:description > meta description), the site name (og:site_name) and one preview image URL (og:image >
+// twitter:image). No DOM: a small tolerant scanner, linear in the page's length also on hostile input (every search
+// moves forward; an unterminated comment, quote, script or tag ends the scan), test/central-unfurl-perf.test.ts
+// holds the budgets. Comments, CDATA, doctype/processing instructions and the raw text of script, style and similar
+// elements are skipped, so markup inside them never counts. Text is entity-decoded once (no double decoding),
+// control and bidi-override characters are dropped, whitespace is collapsed, and each field is capped
+// (UNFURL_TEXT_LIMITS) with an ellipsis. The image is resolved against the page's final URL (after redirects) and kept
+// only when the safe fetcher could request it (http/https, default port, no userinfo; see fetcher.checkURL).
+import { checkURL } from "./fetcher"
+
+export interface UnfurlMeta {
+  readonly title?: string
+  readonly description?: string
+  readonly siteName?: string
+  readonly image?: string
+}
+
+/** Characters (UTF-16 units, never splitting a pair) kept per field, the ellipsis included. */
+export const UNFURL_TEXT_LIMITS = { title: 200, description: 300, siteName: 100 } as const
+
+// ---------- charset ----------
+
+const decoderFor = (label: string | undefined): TextDecoder | undefined => {
+  if (!label) return undefined
+  try {
+    return new TextDecoder(label.trim().toLowerCase())
+  } catch {
+    return undefined
+  }
+}
+
+/** The text of a page's bytes: a BOM, else the Content-Type charset, else a <meta> charset in the first 1024 bytes,
+ * else UTF-8. An unknown charset reads as UTF-8; a <meta> naming UTF-16 does too (the HTML rule). */
+export function decodeHtml(bytes: Uint8Array, contentType: string | null): string {
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return new TextDecoder("utf-8").decode(bytes)
+  if (bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder("utf-16be").decode(bytes)
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) return new TextDecoder("utf-16le").decode(bytes)
+  const header = /charset\s*=\s*["']?\s*([^\s;"']+)/i.exec(contentType ?? "")?.[1]
+  let decoder = decoderFor(header)
+  if (!decoder) {
+    let head = ""
+    for (let i = 0; i < Math.min(bytes.length, 1024); i++) head += String.fromCharCode(bytes[i]!)
+    const meta = /<meta[^>]*?charset\s*=\s*["']?\s*([A-Za-z0-9._:-]+)/i.exec(head)?.[1]
+    decoder = meta && /^utf-?16/i.test(meta) ? undefined : decoderFor(meta)
+  }
+  return (decoder ?? new TextDecoder("utf-8")).decode(bytes)
+}
+
+// ---------- text ----------
+
+/** Latin-1 entity names, U+00A0 to U+00FF in order. */
+const LATIN1 =
+  "nbsp iexcl cent pound curren yen brvbar sect uml copy ordf laquo not shy reg macr deg plusmn sup2 sup3 acute micro para middot cedil sup1 ordm raquo frac14 frac12 frac34 iquest Agrave Aacute Acirc Atilde Auml Aring AElig Ccedil Egrave Eacute Ecirc Euml Igrave Iacute Icirc Iuml ETH Ntilde Ograve Oacute Ocirc Otilde Ouml times Oslash Ugrave Uacute Ucirc Uuml Yacute THORN szlig agrave aacute acirc atilde auml aring aelig ccedil egrave eacute ecirc euml igrave iacute icirc iuml eth ntilde ograve oacute ocirc otilde ouml divide oslash ugrave uacute ucirc uuml yacute thorn yuml".split(" ")
+
+const NAMED: Record<string, string> = {
+  ...Object.fromEntries(LATIN1.map((name, i) => [name, String.fromCharCode(0xa0 + i)])),
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  hellip: "…",
+  mdash: "—",
+  ndash: "–",
+  lsquo: "‘",
+  rsquo: "’",
+  sbquo: "‚",
+  ldquo: "“",
+  rdquo: "”",
+  bdquo: "„",
+  lsaquo: "‹",
+  rsaquo: "›",
+  bull: "•",
+  trade: "™",
+  euro: "€",
+  dagger: "†",
+  Dagger: "‡",
+  permil: "‰",
+  prime: "′",
+  Prime: "″",
+  larr: "←",
+  rarr: "→",
+  uarr: "↑",
+  darr: "↓",
+  harr: "↔",
+  ensp: " ",
+  emsp: " ",
+  thinsp: " ",
+  zwnj: "\u200c",
+  zwj: "\u200d",
+  OElig: "Œ",
+  oelig: "œ",
+  Scaron: "Š",
+  scaron: "š",
+  Yuml: "Ÿ",
+  fnof: "ƒ",
+  circ: "ˆ",
+  tilde: "˜",
+}
+
+const ENTITY = /&(?:#(\d{1,8});?|#[xX]([0-9a-fA-F]{1,8});?|([A-Za-z][A-Za-z0-9]{1,31});)/g
+
+const codePoint = (n: number) => (n === 0 || n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff) ? "\uFFFD" : String.fromCodePoint(n))
+
+/** Character references decoded once: `&amp;lt;` is `&lt;`. Unknown names stay as written. */
+function decodeEntities(text: string): string {
+  if (!text.includes("&")) return text
+  return text.replace(ENTITY, (whole, dec: string | undefined, hex: string | undefined, name: string | undefined) => {
+    if (dec !== undefined) return codePoint(Number(dec))
+    if (hex !== undefined) return codePoint(parseInt(hex, 16))
+    return NAMED[name!] ?? whole
+  })
+}
+
+/** C0/C1 controls (whitespace ones become spaces below) and the bidi embedding, override and isolate characters. */
+const CONTROL = /[\u0000-\u0008\u000b\u000e-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g
+const SPACE = /\s+/g
+
+/** At most `max` UTF-16 units, an ellipsis ending a cut one, never half a surrogate pair. */
+function cap(text: string, max: number): string {
+  if (text.length <= max) return text
+  let cut = max - 1
+  const last = text.charCodeAt(cut - 1)
+  if (last >= 0xd800 && last <= 0xdbff) cut--
+  return `${text.slice(0, cut).trimEnd()}…`
+}
+
+/** Plain text of a field: entities decoded, controls dropped, whitespace collapsed, capped; undefined when empty. */
+function clean(raw: string, max: number): string | undefined {
+  const text = decodeEntities(raw).replace(CONTROL, "").replace(SPACE, " ").trim()
+  return text ? cap(text, max) : undefined
+}
+
+/** The image URL a preview may show: resolved against the page, fetchable by the safe fetcher; else undefined. */
+function imageURL(raw: string, base: URL): string | undefined {
+  const value = decodeEntities(raw).replace(CONTROL, "").trim()
+  if (!value) return undefined
+  try {
+    return checkURL(new URL(value, base)).href
+  } catch {
+    return undefined
+  }
+}
+
+// ---------- scanner ----------
+
+/** Elements whose content is raw text up to their end tag (markup inside never counts). */
+const RAW_TEXT = new Set(["script", "style", "textarea", "xmp", "iframe", "noembed", "noframes"])
+
+const isSpace = (c: number) => c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d
+const isLetter = (c: number) => (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a)
+const isNameChar = (c: number) => isLetter(c) || (c >= 0x30 && c <= 0x39) || c === 0x2d || c === 0x3a || c === 0x5f
+
+/** The first match of `</name` (any case, then a delimiter or the end) at or after `from`, or -1. */
+const END_TAGS = new Map<string, RegExp>()
+function endTag(html: string, name: string, from: number): number {
+  let re = END_TAGS.get(name)
+  if (!re) END_TAGS.set(name, (re = new RegExp(`</${name}(?=[\\s/>]|$)`, "gi")))
+  re.lastIndex = from
+  return re.exec(html)?.index ?? -1
+}
+
+/**
+ * A start tag's attributes from `at` (just after its name) up to its `>`: the index after it and, with `collect`, the
+ * attributes (lowercased names, the first of a name wins). Undefined when the tag never ends (an unterminated quote
+ * included): the scan stops there.
+ */
+function scanAttributes(html: string, at: number, collect: boolean): { end: number; attrs?: Map<string, string> } | undefined {
+  const n = html.length
+  const attrs = collect ? new Map<string, string>() : undefined
+  let i = at
+  while (i < n) {
+    const c = html.charCodeAt(i)
+    if (c === 0x3e) return { end: i + 1, attrs }
+    if (isSpace(c) || c === 0x2f) {
+      i++
+      continue
+    }
+    const start = i
+    i++ // the first character is part of the name, even "=" (HTML's rule)
+    while (i < n) {
+      const d = html.charCodeAt(i)
+      if (isSpace(d) || d === 0x2f || d === 0x3e || d === 0x3d) break
+      i++
+    }
+    const name = collect ? html.slice(start, i).toLowerCase() : ""
+    while (i < n && isSpace(html.charCodeAt(i))) i++
+    let value = ""
+    if (html.charCodeAt(i) === 0x3d) {
+      i++
+      while (i < n && isSpace(html.charCodeAt(i))) i++
+      const q = html.charCodeAt(i)
+      if (q === 0x22 || q === 0x27) {
+        const close = html.indexOf(q === 0x22 ? '"' : "'", i + 1)
+        if (close < 0) return undefined
+        value = collect ? html.slice(i + 1, close) : ""
+        i = close + 1
+      } else {
+        const from = i
+        while (i < n && !isSpace(html.charCodeAt(i)) && html.charCodeAt(i) !== 0x3e) i++
+        value = collect ? html.slice(from, i) : ""
+      }
+    }
+    if (attrs && !attrs.has(name)) attrs.set(name, value)
+  }
+  return undefined
+}
+
+type TextKey = "og:title" | "twitter:title" | "title" | "og:description" | "twitter:description" | "description" | "og:site_name"
+
+const TEXT_KEYS: Record<string, { key: TextKey; max: number }> = {
+  "og:title": { key: "og:title", max: UNFURL_TEXT_LIMITS.title },
+  "twitter:title": { key: "twitter:title", max: UNFURL_TEXT_LIMITS.title },
+  "og:description": { key: "og:description", max: UNFURL_TEXT_LIMITS.description },
+  "twitter:description": { key: "twitter:description", max: UNFURL_TEXT_LIMITS.description },
+  description: { key: "description", max: UNFURL_TEXT_LIMITS.description },
+  "og:site_name": { key: "og:site_name", max: UNFURL_TEXT_LIMITS.siteName },
+}
+
+const IMAGE_KEYS: Record<string, "og" | "twitter"> = {
+  "og:image": "og",
+  "og:image:url": "og",
+  "og:image:secure_url": "og",
+  "twitter:image": "twitter",
+  "twitter:image:src": "twitter",
+}
+
+/** Image candidates (og:image, twitter:image, …) a page may offer before the rest are ignored. */
+const MAX_IMAGE_TRIES = 64
+
+/** The preview of a page's (decoded) HTML; `base` is the page's final URL. */
+export function parseUnfurl(html: string, base: URL): UnfurlMeta {
+  const text = new Map<TextKey, string>()
+  const images: { og?: string; twitter?: string } = {}
+  // Unusable image candidates are skipped, but only up to a bound, so a page of them costs no more URL parsing.
+  let imageTries = 0
+  let seenTitle = false
+  const n = html.length
+
+  const meta = (attrs: Map<string, string>) => {
+    const content = attrs.get("content")
+    if (content === undefined) return
+    for (const which of ["property", "name"]) {
+      const key = attrs.get(which)?.trim().toLowerCase()
+      if (!key) continue
+      const field = TEXT_KEYS[key]
+      if (field && !text.has(field.key)) {
+        const value = clean(content, field.max)
+        if (value !== undefined) text.set(field.key, value)
+      }
+      const image = IMAGE_KEYS[key]
+      if (image && images[image] === undefined && imageTries < MAX_IMAGE_TRIES) {
+        imageTries++
+        const url = imageURL(content, base)
+        if (url !== undefined) images[image] = url
+      }
+    }
+  }
+
+  let i = 0
+  while (i < n) {
+    const lt = html.indexOf("<", i)
+    if (lt < 0) break
+    const next = html.charCodeAt(lt + 1)
+    if (next === 0x21 /* ! */) {
+      const [open, close] = html.startsWith("<!--", lt) ? ["<!--", "-->"] : html.startsWith("<![CDATA[", lt) ? ["<![CDATA[", "]]>"] : ["<!", ">"]
+      const end = html.indexOf(close, lt + open.length)
+      if (end < 0) break
+      i = end + close.length
+      continue
+    }
+    if (next === 0x3f /* ? */ || next === 0x2f /* / */) {
+      const end = html.indexOf(">", lt + 2)
+      if (end < 0) break
+      i = end + 1
+      continue
+    }
+    if (!isLetter(next)) {
+      i = lt + 1
+      continue
+    }
+    let j = lt + 2
+    while (j < n && isNameChar(html.charCodeAt(j))) j++
+    const name = html.slice(lt + 1, j).toLowerCase()
+    const tag = scanAttributes(html, j, name === "meta")
+    if (!tag) break
+    i = tag.end
+    if (name === "meta") meta(tag.attrs!)
+    else if (name === "title" || RAW_TEXT.has(name)) {
+      const close = endTag(html, name, i)
+      if (name === "title" && !seenTitle) {
+        seenTitle = true
+        const value = clean(html.slice(i, close < 0 ? n : close), UNFURL_TEXT_LIMITS.title)
+        if (value !== undefined) text.set("title", value)
+      }
+      if (close < 0) break
+      i = close
+    }
+  }
+
+  const title = text.get("og:title") ?? text.get("twitter:title") ?? text.get("title")
+  const description = text.get("og:description") ?? text.get("twitter:description") ?? text.get("description")
+  const siteName = text.get("og:site_name")
+  const image = images.og ?? images.twitter
+  return {
+    ...(title !== undefined ? { title } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(siteName !== undefined ? { siteName } : {}),
+    ...(image !== undefined ? { image } : {}),
+  }
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { jobFromInfo, type JobInfo } from "./protocol"
 import { checkServer, parseServerInput } from "./setup"
 import { defineVoiceAgent, orchestratorParts, STOP_TOOL, STOP_TOOL_DESCRIPTION } from "./spoke/conversation"
 import { defineConciergeAgent } from "./spoke/concierge-agent"
+import { defineVoiceFrontAgent, FRONT_SEND_DESCRIPTION, FRONT_SEND_TOOL, FRONT_STOP_DESCRIPTION, FRONT_STOP_TOOL, FRONT_TOOLS, VOICE_FRONT_AGENT } from "./spoke/voice-front"
 
 import { CONCIERGE_AGENT, CONCIERGE_TOOLS } from "../packages/protocol/src/concierge.ts"
 import { defaultHubBinDir, envInjector, hubBinDir, ShellCorrelator, stripInheritedHubEnv } from "./spoke/env-inject"
@@ -28,7 +29,7 @@ import { nodeConfigPath, readWorkspaceRoots } from "./spoke/node-roots"
 import { PromptReferences } from "./spoke/prompt-refs"
 import { PROFILE_TOOL, PROFILE_TOOL_DESCRIPTION, PROFILE_TOOL_INPUT } from "./spoke/profile-apply"
 import { listedNames, namesReader, replyPermission, serverNames, vcsReader, type PermissionLocation, type VcsReader } from "./spoke/locations"
-import { foregroundEndpoint, formOutcome } from "./spoke/own-server"
+import { fetchOwnMedia, foregroundEndpoint, formOutcome } from "./spoke/own-server"
 import { joinProcess, type Membership } from "./spoke/singleton"
 import { applySessionContext, sortTools } from "./spoke/session-context"
 import { detectKind, Spoke, SpokeError, type FormAction, type SpokeHost } from "./spoke/spoke"
@@ -90,16 +91,22 @@ async function listRecent(kind: "service" | "standalone", scope: () => string[],
 /** This process can list sessions: the background service, or a foreground `opencode serve` that knows its password. */
 const canList = (kind: "service" | "standalone") => kind === "service" || foregroundEndpoint(process.argv, process.env) !== undefined
 
-/** A client for this process's own OpenCode server, when it can be reached (see src/spoke/own-server.ts). */
-async function ownClient(kind: "service" | "standalone") {
-  const { OpenCode } = await import("@opencode/client")
+/** URL and auth headers of this process's own OpenCode server, when it can be reached (see src/spoke/own-server.ts). */
+async function ownEndpoint(kind: "service" | "standalone"): Promise<{ url: string; headers: Record<string, string> } | undefined> {
   if (kind === "service") {
     const { Service } = await import("@opencode/client/service")
     const endpoint = await Service.discover()
-    return endpoint ? OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) ?? {} }) : undefined
+    return endpoint ? { url: endpoint.url, headers: Service.headers(endpoint) ?? {} } : undefined
   }
   const endpoint = foregroundEndpoint(process.argv, process.env)
-  return endpoint ? OpenCode.make({ baseUrl: endpoint.url, headers: { authorization: endpoint.authorization } }) : undefined
+  return endpoint ? { url: endpoint.url, headers: { authorization: endpoint.authorization } } : undefined
+}
+
+/** A client for this process's own OpenCode server, when it can be reached (see src/spoke/own-server.ts). */
+async function ownClient(kind: "service" | "standalone") {
+  const { OpenCode } = await import("@opencode/client")
+  const endpoint = await ownEndpoint(kind)
+  return endpoint ? OpenCode.make({ baseUrl: endpoint.url, headers: endpoint.headers }) : undefined
 }
 
 /** The own server's client, or an error saying it cannot be reached. */
@@ -288,8 +295,11 @@ function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "se
           revertStage: async (input: { sessionID: string; messageID: string; files: boolean }) => (await requireOwnClient(kind)).session.revert.stage(input),
           revertClear: async (sessionID: string) => (await requireOwnClient(kind)).session.revert.clear({ sessionID }),
           revertCommit: async (sessionID: string) => (await requireOwnClient(kind)).session.revert.commit({ sessionID }),
+          // (S4 M2) media:<sha256> tool output for timelineMedia; none when the server cannot be reached.
+          fetchMedia: async (hash: string) => fetchOwnMedia(await ownEndpoint(kind).catch(() => undefined), hash),
         }
       : {}),
+    removeSession: (sessionID) => session.remove({ sessionID }),
     createSession: async ({ directory, title }) =>
       unwrap<{ id: string }>(await session.create({ location: { directory }, ...(title ? { title } : {}) }), (v) => typeof v.id === "string"),
     ...(mcp?.list ? { mcpList: async (directory: string) => unwrap<ReadonlyArray<unknown>>(await mcp.list({ location: { directory } }), Array.isArray) } : {}),
@@ -379,6 +389,7 @@ export default definePlugin({
         ctx.agent.transform((editor) => {
           defineVoiceAgent(editor as any)
           defineConciergeAgent(editor as any)
+          defineVoiceFrontAgent(editor as any)
         }),
       ),
       attempt("register the context hook", () =>
@@ -391,7 +402,8 @@ export default definePlugin({
           if (!locked && spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
           const parts = locked ? [] : orchestratorParts({
             agent: event.agent,
-            conversation: spoke?.inConversation(event.sessionID) ?? false,
+            // A session with a voice front is left alone: only today's agent swap makes it the orchestrator.
+            conversation: spoke?.orchestrates(event.sessionID) ?? false,
             subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
             workModel: spoke?.workModelFor(event.sessionID),
             taskBoard: spoke?.taskBoard(event.sessionID),
@@ -406,6 +418,17 @@ export default definePlugin({
           if (event.tools) spoke?.contexts.filterTools(event.sessionID, event.tools as Record<string, unknown>)
           // The concierge agent keeps exactly CONCIERGE_TOOLS even without a hub context (a spoke that restarted before
           // the hub re-sent it): OpenCode 2.2.3 offers `skill` whatever the agent's rules say.
+          // (voice front) The front hears about its main session each turn, and keeps only its two relay tools. No
+          // other session ever sees them; a voice-front agent session that is no linked front (a spoke that restarted,
+          // or a failed front) keeps no tools at all.
+          const frontNote = spoke?.frontContext(event.sessionID)
+          // After the conversation, as the Concierge's board (V-01: the prompt cache survives the note's changes).
+          if (frontNote) applySessionContext(event as any, [], [frontNote])
+          if (event.tools) {
+            const keep = (name: string) => (frontNote ? (FRONT_TOOLS as readonly string[]).includes(name) : event.agent !== VOICE_FRONT_AGENT && !(FRONT_TOOLS as readonly string[]).includes(name))
+            for (const name of Object.keys(event.tools)) if (!keep(name)) delete event.tools[name]
+            if (frontNote) sortTools(event.tools as Record<string, unknown>)
+          }
           if (event.tools && event.agent === CONCIERGE_AGENT) {
             for (const name of Object.keys(event.tools)) if (!(CONCIERGE_TOOLS as readonly string[]).includes(name)) delete event.tools[name]
             sortTools(event.tools as Record<string, unknown>)
@@ -436,6 +459,43 @@ export default definePlugin({
           }),
         ),
       ),
+      // The voice front relays the user's request to its main session, or stops it (src/spoke/voice-front.ts).
+      attempt("register the voice front tools", () =>
+        (ctx as any).tool?.transform?.((editor: any) => {
+          editor.add({
+            name: FRONT_SEND_TOOL,
+            description: FRONT_SEND_DESCRIPTION,
+            input: {
+              type: "object",
+              properties: {
+                text: { type: "string", description: "The user's request for the main session, as a clear instruction." },
+                delivery: { type: "string", enum: ["auto", "steer", "queue"], description: 'auto (default), steer (join main\'s running turn) or queue (after main\'s current turn).' },
+              },
+              required: ["text"],
+              additionalProperties: false,
+            },
+            options: { codemode: false },
+            execute: async (value: unknown, context: { sessionID: string }) => {
+              const spoke = membership.active()
+              if (!spoke) return { content: "The hub is not running in this OpenCode process; nothing was sent." }
+              const { text, inboxID } = await spoke.frontSend(context.sessionID, (value ?? {}) as Record<string, unknown>)
+              return { content: text, ...(inboxID ? { metadata: { inboxID } } : {}) }
+            },
+          })
+          editor.add({
+            name: FRONT_STOP_TOOL,
+            description: FRONT_STOP_DESCRIPTION,
+            input: { type: "object", properties: {}, additionalProperties: false },
+            options: { codemode: false },
+            execute: async (_value: unknown, context: { sessionID: string }) => {
+              const spoke = membership.active()
+              if (!spoke) return { content: "The hub is not running in this OpenCode process; nothing was stopped." }
+              const { text, stopped } = await spoke.frontStop(context.sessionID)
+              return { content: text, metadata: { stopped } }
+            },
+          })
+        }),
+      ),
       // Agents message and ask other sessions as themselves (the session's own hub token; src/spoke/hub-tool.ts).
       attempt("register the hub tool", () =>
         (ctx as any).tool?.transform?.((editor: any) =>
@@ -504,7 +564,7 @@ export default definePlugin({
       openLink: (value, rpc) =>
         run(rpc, (s) => s.openLink(input(value).sessionID ? String(input(value).sessionID) : undefined, input(value).voice === true)),
       conversation: (value, rpc) =>
-        run(rpc, (s) => s.setConversation(String(input(value).sessionID ?? ""), Boolean(input(value).on))),
+        run(rpc, (s) => s.setConversation(String(input(value).sessionID ?? ""), Boolean(input(value).on), input(value).front === true)),
       formActions: (value, rpc) =>
         run(rpc, (s) => {
           const { waitMs = 0 } = input(value)

package/src/speakable.ts

@@ -1,6 +1,38 @@
+const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})\s*([^\s`]*)/
+const FENCE_CLOSE = /^\s*(`{3,}|~{3,})\s*$/
+/** The console's rule (web/src/lib/mermaid.ts isMermaidLang): exactly mermaid or mmd, any case. */
+const isDiagramLang = (lang: string) => /^(?:mermaid|mmd)$/i.test(lang)
+
+/**
+ * Mermaid fences (``` or ~~~, closed or still open) become the line "a diagram": the console draws them, so their
+ * source is never read aloud. Other fences are left as they are. Kept in step with web/src/lib/mermaid.ts
+ * speakDiagrams (the browser's copy for Voice).
+ */
+export function speakDiagrams(text: string): string {
+  const out: string[] = []
+  let fence: { marker: string; diagram: boolean } | undefined
+  for (const line of text.split("\n")) {
+    if (fence) {
+      const close = FENCE_CLOSE.exec(line)
+      const closes = !!close && close[1]![0] === fence.marker[0] && close[1]!.length >= fence.marker.length
+      if (!fence.diagram) out.push(line)
+      if (closes) fence = undefined
+      continue
+    }
+    const open = FENCE_OPEN.exec(line)
+    if (open) {
+      fence = { marker: open[1]!, diagram: isDiagramLang(open[2]!) }
+      out.push(fence.diagram ? "a diagram" : line)
+      continue
+    }
+    out.push(line)
+  }
+  return out.join("\n")
+}
+
 /** Turns an agent reply into text that sounds natural when read aloud, capped at `max` characters. */
 export function speakable(text: string, max = Infinity): string {
-  const lines = text
+  const lines = speakDiagrams(text)
     .replace(/```[\s\S]*?```/g, "\n(code omitted)\n")
     .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
     .replace(/https?:\/\/\S+/g, "a link")

package/src/spoke/conversation.ts

@@ -11,14 +11,17 @@ export { PROMPT_SOURCE, isHubPrompt } from "../../packages/spoke-sdk/src/prompt-
 export const VOICE_AGENT_DESCRIPTION =
   "Voice front-end: short spoken replies; delegates real work to background subagents. Used by Hub conversation mode."
 
-export const ORCHESTRATOR_PROMPT = `You are a voice agent: the voice front-end of an OpenCode session. The user is talking to you hands-free from their phone. Everything they send is a live speech-to-text transcript, and everything you write is read aloud to them.
-
-Understanding speech:
+/** How to read a live speech transcript (shared by the voice agent and the voice front). */
+export const SPEECH_RULES = `Understanding speech:
 - Transcripts contain recognition errors, filler words, false starts and half sentences. Infer the intent; don't comment on the wording.
 - The user thinks out loud. Their speech is cut at pauses, so one thought can arrive as several consecutive messages, and a message can end mid-sentence. Read your recent messages from the user together as one evolving request.
 - The user corrects themselves ("no wait", "actually", "I mean", "scratch that", or simply restating it differently). The latest version wins. If you already started work based on the earlier version, redirect or stop it.
 - If a message is only a fragment and the intent isn't clear yet, don't start any work: reply with at most a few words, like "Go on." or "I'm listening.", and wait for the rest.
-- If something is genuinely ambiguous after the user has finished, ask one short question instead of guessing.
+- If something is genuinely ambiguous after the user has finished, ask one short question instead of guessing.`
+
+export const ORCHESTRATOR_PROMPT = `You are a voice agent: the voice front-end of an OpenCode session. The user is talking to you hands-free from their phone. Everything they send is a live speech-to-text transcript, and everything you write is read aloud to them.
+
+${SPEECH_RULES}
 
 How to reply:
 - Speak in one or two short sentences of plain speech. No markdown, lists, tables, code, file paths or URLs unless the user asks for them.

package/src/spoke/deliver.ts

@@ -7,7 +7,9 @@
 // "prompt") gets its provenance envelope here, from the hub's meta, and is the hub's in the inbox (never a human turn).
 import { createHash } from "node:crypto"
 import type { DeliverMeta, Delivered, DeliveryMode } from "../protocol"
+import { sanitizeLabel } from "../../packages/sdk/src/index.ts"
 import { PROMPT_SOURCE } from "./conversation"
+import { messageBody } from "./timeline"
 
 export interface DeliveryPlan {
   /** How OpenCode admits it into a busy session: after the running turn (queue) or into it (steer). */
@@ -75,6 +77,23 @@ export function deliverMetadata(req: { readonly messageID: string; readonly meta
   return { source: PROMPT_SOURCE, messageID: req.messageID, kind, from, to, ...(replyTo !== undefined ? { replyTo } : {}), ...(grant !== undefined ? { grant } : {}) }
 }
 
+/** The longest notice OpenCode shows for a delivered message, in characters. */
+const DESCRIPTION_MAX = 160
+
+/**
+ * The description of a delivered message: the one-line notice the OpenCode TUI shows for a synthetic message (it
+ * never shows the text, so without it a hub message is invisible there; the model never sees it). The kind, the
+ * sender and the start of the body: `hub · ask from @api: Which release order?`.
+ */
+export function deliverDescription(req: { readonly messageID: string; readonly text: string; readonly meta: DeliverMeta }): string {
+  const { kind } = req.meta
+  const body = kind === "prompt" ? req.text : kind === "primer" ? req.text.replace(/^\[hub\]\s*/i, "") : messageBody(req.text, req.messageID)
+  const heading = kind === "primer" ? "hub · primer" : `hub · ${kind} from ${sanitizeLabel(req.meta.from)}`
+  const snippet = sanitizeLabel(body, Number.MAX_SAFE_INTEGER)
+  const chars = Array.from(snippet ? `${heading}: ${snippet}` : heading)
+  return chars.length <= DESCRIPTION_MAX ? chars.join("") : `${chars.slice(0, DESCRIPTION_MAX - 1).join("").trimEnd()}…`
+}
+
 /**
  * The refusal of any hub message to a session with a staged revert (admitting it would commit the revert): the hub
  * keeps it pending and sends it again once the revert is restored or committed (decision 3q94ez94).