@huynle/hub 0.0.0-stage → 0.6.0

package/src/tui.ts

@@ -0,0 +1,479 @@
+import { spawn } from "node:child_process"
+import { Plugin } from "@opencode/plugin/tui"
+import { isLoopbackURL } from "./loopback"
+import { HubRpc } from "./rpc"
+import { localServerFor, modeFor, needsSetup, parseServerInput, setupOptions, type SetupChoice } from "./setup"
+import { hubCommands } from "./tui-commands"
+import { FormRelay } from "./tui-forms"
+import { PresenceReporter, shownSessions } from "./tui-presence"
+import { startVoice } from "./voice-command"
+
+// Hub's TUI plugin. /hub configures this harness's hub connection; the other commands are features (see
+// src/tui-commands.ts to add one).
+// /hub: the hub connection — first-run setup (a hub on this computer, or your own hub), then one dialog for
+// the server, its connection and approval, what this machine shares, pairing phones and opening the hub.
+// /voice: no menu — connect (setting up first when needed), share this session, and open it in the browser
+// with Voice mode starting (src/voice-command.ts). Links are shown here, never posted into the session, so
+// they do not reach the model. Decisions live in src/setup.ts and src/voice-command.ts (tested).
+
+type Mode = "off" | "always" | "session"
+interface Status {
+  server: string
+  mode: Mode
+  enrolled: boolean
+  connection: "off" | "connecting" | "connected" | "revoked" | "error"
+  lastError?: string
+  sessionExposed?: boolean
+  conversation?: boolean
+  enrollment?: "pending" | "approved" | "denied" | "expired" | "error"
+  machineName: string
+  /** Why the local hub could not be started. */
+  localHub?: string
+}
+
+interface Enrolled {
+  userCode: string
+  approveURL: string
+  autoApproved?: boolean
+  localHub?: "started" | "running" | "busy"
+}
+
+type Choice = "ui" | "start" | "approval" | "send" | "conversation" | "toggle" | "mode" | "pair" | "server"
+
+const MODE_LABEL: Record<Mode, string> = { always: "Always", session: "This session only", off: "Off" }
+
+const HUB_LOG = "~/.local/state/hub/hub.log"
+const host = (server: string) => server.replace(/^https?:\/\//, "")
+
+function describeStatus(status: Status): string {
+  const where = host(status.server)
+  const state = !status.enrolled
+    ? `not connected to ${where}`
+    : status.connection === "connected"
+      ? `connected to ${status.server}`
+      : status.connection === "connecting"
+        ? `connecting to ${where}…`
+        : status.connection === "revoked"
+          ? `revoked by ${where}`
+          : status.connection === "error"
+            ? `cannot reach ${where}`
+            : `${where}`
+  return `Hub · ${state} · mode: ${MODE_LABEL[status.mode]}`
+}
+
+export default Plugin.define({
+  id: "hub.tui",
+  setup(context) {
+    const hub = context.client.rpc(HubRpc) as unknown as Record<string, (input: unknown, options: unknown) => Promise<unknown>>
+    const call = async <T>(method: string, input: Record<string, unknown> = {}) =>
+      (await hub[method]!(input, { location: context.location ?? context.data.location.default() })) as T
+    const toast = (message: string, variant: "info" | "success" | "warning" | "error" = "info") =>
+      context.ui.toast.show({ title: "Hub", message, variant })
+    const currentSession = () => {
+      const route = context.ui.router.current() as { type: string; sessionID?: string }
+      return route.type === "session" ? route.sessionID : undefined
+    }
+    const status = (sessionID = currentSession()) => call<Status>("status", sessionID ? { sessionID } : {})
+
+    /** Polls status until `done` holds; undefined when the time runs out. */
+    const waitFor = async (done: (s: Status) => boolean, ms: number, every = 300) => {
+      const end = Date.now() + ms
+      while (Date.now() < end) {
+        const s = await status().catch(() => undefined)
+        if (s && done(s)) return s
+        await Bun.sleep(every)
+      }
+      return undefined
+    }
+
+    /** Opens a one-time sign-in link in the browser; shows it when no browser could be opened. */
+    const showLink = async (url: string, what: string) => {
+      const opened = openURL(url)
+      const copied = copyToClipboard(url)
+      if (opened) return toast(`Opened ${what} in your browser${copied ? " (link copied)" : ""}`, "success")
+      await context.ui.dialog.alert({ title: "Hub", message: `Open this link${copied ? " (copied)" : ""}:\n\n${url}\n\nKeep it private.` })
+    }
+
+    /** Connects to the configured hub (starting a local one when nothing answers) and waits for it. */
+    const ensureConnected = async (sessionID?: string): Promise<Status> => {
+      let s = await status(sessionID)
+      if (s.connection === "connected") return s
+      if (!s.enrolled) throw new Error("This machine is not connected to a hub yet. Run /hub to set it up.")
+      if (s.mode === "off") throw new Error("Sharing is off for this machine. Run /hub → Mode first.")
+      if (isLoopbackURL(s.server)) {
+        const { status: started } = await call<{ status: string }>("startLocalHub")
+        if (started === "started") toast(`Started the local hub (log: ${HUB_LOG})`)
+      }
+      toast(`Connecting to ${host(s.server)}…`)
+      if (!(await waitFor((x) => x.connection === "connected", 20_000))) {
+        s = await status(sessionID)
+        throw new Error(`Could not connect to ${s.server}${s.localHub ? `: ${s.localHub}` : s.lastError ? `: ${s.lastError}` : ""}`)
+      }
+      return status(sessionID)
+    }
+
+    /**
+     * The hub page (the session's when it is shared, else the home page). A local hub is started first
+     * when nothing answers; the hub lands on speech setup while no speech provider is usable.
+     */
+    const openUI = async (sessionID?: string) => {
+      const s = await ensureConnected(sessionID)
+      const shared = sessionID && s.sessionExposed ? sessionID : undefined
+      const { url } = await call<{ url: string }>("openLink", shared ? { sessionID: shared } : {})
+      await showLink(url, "the hub")
+    }
+
+    const sendToPhone = async (sessionID: string) => {
+      const { notified } = await call<{ notified: number }>("handoff", { sessionID })
+      if (notified > 0) toast(`Notified ${notified} device${notified === 1 ? "" : "s"}`, "success")
+      else toast("No phone is paired yet. Use /hub → Pair a phone first.", "warning")
+    }
+
+    const toggleConversation = async (sessionID: string, s: Status) => {
+      const on = !s.conversation
+      const { agent } = await call<{ agent: string }>("conversation", { sessionID, on })
+      if (!on) return toast(`Conversation mode off (agent: ${agent})`, "success")
+      const connected = s.connection === "connected"
+      const go = await context.ui.dialog.confirm({
+        title: "Conversation mode on",
+        message:
+          `This session now runs the ${agent} agent: short spoken replies, real work handed to background subagents. ` +
+          `Open this session on your phone to talk${connected ? "" : " once this machine is connected"}.`,
+        label: { confirm: connected ? "Send to phone" : "OK", cancel: "Later" },
+      })
+      if (go && connected) await sendToPhone(sessionID)
+    }
+
+    /** Sets the mode; "This session only" switches the current session on. Returns a note for the toast. */
+    const applyMode = async (mode: Mode) => {
+      await call("setMode", { mode })
+      const sessionID = currentSession()
+      if (mode === "session" && sessionID) await call("setSession", { sessionID, on: true })
+      return mode === "session" && sessionID ? " (this session is on)" : ""
+    }
+
+    const chooseMode = async (s: Status, title = "Which sessions can the hub see?") => {
+      const mode = await context.ui.dialog.select<Mode>({
+        title,
+        current: s.mode === "off" ? "always" : s.mode,
+        options: [
+          { title: "Always", value: "always", description: "Every session in this OpenCode process" },
+          { title: "This session only", value: "session", description: "Only sessions you switch on with /hub" },
+          { title: "Off", value: "off", description: "Disconnect this process from the hub" },
+        ],
+      })
+      if (!mode || mode === s.mode) return
+      const note = await applyMode(mode)
+      toast(`Hub mode: ${MODE_LABEL[mode]}${note}`, "success")
+    }
+
+    const pairPhone = async () => {
+      const { code, url, expiresAt } = await call<{ code: string; url: string; expiresAt: number }>("pairCode")
+      const minutes = Math.max(1, Math.round((expiresAt - Date.now()) / 60_000))
+      copyToClipboard(url)
+      await context.ui.dialog.alert({
+        title: "Pair a phone",
+        message: `On your phone, open:\n\n${url}\n\nand enter the code ${code} (valid ~${minutes} min).`,
+      })
+    }
+
+    /** Waits in the background for the server's decision, then asks which sessions to share. */
+    const watchEnrollment = async () => {
+      const failed = (s: Status) => s.enrollment === "denied" || s.enrollment === "expired" || s.enrollment === "error"
+      const done = await waitFor((s) => failed(s) || s.enrolled, 15 * 60_000, 2000)
+      if (!done) return
+      if (failed(done)) return toast(`Approval ${done.enrollment}. Run /hub to try again.`, "error")
+      if (done.mode !== "off") return toast(`Approved by ${host(done.server)}. The hub is set up.`, "success")
+      toast(`Approved by ${host(done.server)}.`, "success")
+      await chooseMode(done, "Approved. Which sessions can the hub see?")
+      const after = await status().catch(() => undefined)
+      if (after && after.mode !== "off") toast("The hub is set up. /voice talks to this session; /hub → Open hub in browser.", "success")
+    }
+
+    /** Device-code approval: open the approve page, say what to look for, and watch for the result. */
+    const awaitApproval = async (enrolled: Enrolled, s: Status) => {
+      const opened = openURL(enrolled.approveURL)
+      copyToClipboard(enrolled.approveURL)
+      void watchEnrollment()
+      toast(`Approve "${s.machineName}" (code ${enrolled.userCode}) in the browser`)
+      await context.ui.dialog.alert({
+        title: `Approve "${s.machineName}"`,
+        message:
+          `${opened ? "Opened in your browser" : "Open"}:\n\n${enrolled.approveURL}\n\n` +
+          `Check the code ${enrolled.userCode} and approve. A browser that is not paired with ${host(s.server)} yet asks for a ` +
+          `pairing code first: /hub → Pair a phone on a connected computer, or the code in the hub's log for the very first device. ` +
+          `You'll get a notice here once it is approved.`,
+      })
+    }
+
+    // ---------- first-run setup ----------
+
+    /** A hub on this computer: start it, enroll (a fresh local hub approves at once), share, open the page. */
+    const setupLocal = async (s: Status, choice: SetupChoice, open = true) => {
+      const server = localServerFor(s.server)
+      if (server !== s.server) await call("setServer", { server })
+      toast("Starting the local hub…")
+      const enrolled = await call<Enrolled>("enroll")
+      if (enrolled.localHub === "started") toast(`Started the local hub (log: ${HUB_LOG})`)
+      if (!enrolled.autoApproved) {
+        // This hub already knows other machines or devices: approve it like a remote server.
+        await applyMode(modeFor(choice))
+        return awaitApproval(enrolled, { ...s, server })
+      }
+      if (!(await waitFor((x) => x.enrolled, 15_000))) {
+        throw new Error(`The local hub approved this machine, but it did not connect. See ${HUB_LOG}`)
+      }
+      const note = await applyMode(modeFor(choice))
+      toast(`Connected to the local hub · mode: ${MODE_LABEL[modeFor(choice)]}${note}`, "success")
+      if (open) await openUI(currentSession())
+    }
+
+    /** Your own hub: check that it answers, save it, enroll, approve in the browser, then pick a mode. */
+    const setupRemote = async (s: Status, server: string) => {
+      const health = await call<{ ok: boolean; version?: string; error?: string }>("checkServer", { server })
+      if (!health.ok) {
+        await context.ui.dialog.alert({ title: "Hub not reachable", message: health.error ?? `Could not reach ${server}` })
+        return
+      }
+      if (server !== s.server) await call("setServer", { server })
+      const enrolled = await call<Enrolled>("enroll")
+      await awaitApproval(enrolled, { ...s, server })
+    }
+
+    const promptServer = async (s: Status): Promise<string | undefined> => {
+      let value = isLoopbackURL(s.server) ? "" : s.server
+      for (;;) {
+        const raw = await context.ui.dialog.prompt({
+          title: "Hub URL",
+          description: "The address of a hub you or your team host. Changing it disconnects this machine from the current server.",
+          value,
+          placeholder: "https://hub.example.com",
+        })
+        if (raw === undefined || raw === null) return undefined
+        const parsed = parseServerInput(raw)
+        if (parsed.ok) return parsed.url
+        toast(parsed.error, "error")
+        value = raw
+      }
+    }
+
+    /** First-run setup; `open: false` leaves opening the browser to the caller (/voice). */
+    const runSetup = async (s: Status, { open = true }: { open?: boolean } = {}) => {
+      const choice = await context.ui.dialog.select<SetupChoice>({
+        title: s.enrolled && s.connection === "revoked" ? `Set up Hub · revoked by ${host(s.server)}` : "Set up Hub",
+        options: setupOptions(s).map((o) => ({ title: o.title, value: o.value, description: o.description })),
+      })
+      switch (choice) {
+        case "local":
+        case "local-session":
+          return setupLocal(s, choice, open)
+        case "configured":
+          return setupRemote(s, s.server)
+        case "remote": {
+          const server = await promptServer(s)
+          if (server) await setupRemote(s, server)
+          return
+        }
+      }
+    }
+
+    // ---------- regular menu ----------
+
+    /** Server: keep it, type another hub URL (checked before switching), or use a hub on this computer. */
+    const changeServer = async (s: Status) => {
+      const pick = await context.ui.dialog.select<"current" | "url" | "local" | "setup">({
+        title: `Hub: ${s.server}`,
+        current: "current",
+        options: [
+          { title: `Keep ${host(s.server)}`, value: "current", description: "No change" },
+          { title: "Change server URL…", value: "url", description: "A hub you or your team host; checked before switching (disconnects this machine from the current one)" },
+          ...(isLoopbackURL(s.server)
+            ? []
+            : [{ title: "Use a hub on this computer", value: "local" as const, description: "Starts a local hub and connects to it (disconnects this machine from the current one)" }]),
+          { title: "Set up again…", value: "setup", description: "The first-run choices: this computer or another hub" },
+        ],
+      })
+      switch (pick) {
+        case "url": {
+          const server = await promptServer(s)
+          if (server) await setupRemote(s, server)
+          return
+        }
+        case "local":
+          return setupLocal(s, "local")
+        case "setup":
+          return runSetup({ ...s, enrolled: false })
+      }
+    }
+
+    const approvalLabel = (s: Status) =>
+      s.connection === "revoked"
+        ? "revoked"
+        : s.enrolled
+          ? "approved"
+          : s.enrollment === "pending"
+            ? "waiting for approval"
+            : s.enrollment
+              ? s.enrollment
+              : "not approved"
+
+    /** /hub: the hub connection. */
+    const open = async () => {
+      const sessionID = currentSession()
+      const s = await status(sessionID)
+      if (needsSetup(s) && s.enrollment !== "pending") return runSetup(s)
+      const connected = s.connection === "connected"
+      const local = isLoopbackURL(s.server)
+      const options: Array<{ title: string; value: Choice; description?: string }> = []
+
+      options.push({ title: `Server: ${s.server}`, value: "server", description: "Change the server URL, or use a hub on this computer" })
+      if (local && !connected && s.enrolled && s.mode !== "off") {
+        options.push({ title: "Start local hub", value: "start", description: "Start the hub on this computer and connect" })
+      }
+      options.push({
+        title: `This machine (${s.machineName}): ${approvalLabel(s)}`,
+        value: "approval",
+        description: s.enrolled ? "Approved by the hub" : "Approve this machine in the hub's web page",
+      })
+      options.push({ title: `Mode: ${MODE_LABEL[s.mode]}`, value: "mode", description: "Always / This session only / Off" })
+      if (s.mode === "session" && sessionID) {
+        options.push({
+          title: `This session: ${s.sessionExposed ? "on" : "off"}`,
+          value: "toggle",
+          description: s.sessionExposed ? "Stop sharing this session with the hub" : "Share this session with the hub",
+        })
+      }
+      if (connected) options.push({ title: "Pair a phone", value: "pair", description: "Show a pairing code for a new device" })
+      if (s.mode !== "off" && (connected || local) && s.enrolled) {
+        options.push({ title: "Open hub in browser", value: "ui", description: "Every session, plus settings (speech provider and keys)" })
+      }
+      if (connected && sessionID && s.sessionExposed) {
+        options.push({ title: "Send to phone", value: "send", description: "Notify your paired phones about this session" })
+        options.push({
+          title: `Conversation mode: ${s.conversation ? "on" : "off"}`,
+          value: "conversation",
+          description: s.conversation
+            ? "Switch this session back to its previous agent"
+            : "Voice orchestrator for this session (/voice also opens it in the browser)",
+        })
+      }
+
+      let title = describeStatus(s)
+      if (s.connection === "error" && s.localHub) title += ` (local hub: ${s.localHub})`
+      else if (s.connection === "error" && s.lastError) title += ` (${s.lastError})`
+      else if (s.mode === "off") title += " · choose a mode to start"
+      else if (connected && sessionID && !s.sessionExposed) title += " · this session is not shared"
+
+      const choice = await context.ui.dialog.select<Choice>({ title, options })
+      switch (choice) {
+        case "server":
+          return changeServer(s)
+        case "start": {
+          await ensureConnected(sessionID)
+          return toast(`Connected to ${host(s.server)}`, "success")
+        }
+        case "approval":
+          if (s.enrolled && s.connection !== "revoked") return toast(`This machine is approved by ${host(s.server)}`, "success")
+          if (s.enrollment === "pending") return toast("Waiting for approval in the hub's web page. You'll get a notice here.", "info")
+          return runSetup(s)
+        case "mode":
+          return chooseMode(s)
+        case "toggle":
+          await call("setSession", { sessionID, on: !s.sessionExposed })
+          return toast(`This session is ${s.sessionExposed ? "no longer shared" : "shared"} with the hub`, "success")
+        case "pair":
+          return pairPhone()
+        case "ui":
+          return openUI(sessionID)
+        case "send":
+          return sendToPhone(sessionID!)
+        case "conversation":
+          return toggleConversation(sessionID!, s)
+      }
+    }
+
+    /** /voice: no menu; connect (set up first when needed), share this session, open it with Voice mode on. */
+    const voice = () =>
+      startVoice({
+        sessionID: currentSession,
+        status: (sessionID) => status(sessionID),
+        setup: (s) => runSetup(s as Status, { open: false }),
+        chooseMode: (s) => chooseMode(s as Status, "Which sessions can the hub see?"),
+        connect: (s) => ensureConnected(currentSession()).then((x) => x ?? s),
+        expose: async (sessionID) => {
+          await call("setSession", { sessionID, on: true })
+        },
+        openLink: (sessionID, voice) => call<{ url: string }>("openLink", { sessionID, voice }),
+        showLink,
+        toast,
+      })
+
+    // Presence: tell the server-side spoke which sessions this TUI shows, so the phone lists them as open.
+    const reporter = `tui_${Math.random().toString(36).slice(2, 12)}`
+    const presence = new PresenceReporter({
+      read: () =>
+        shownSessions({
+          route: context.ui.router.current() as { type: string; sessionID?: string },
+          root: (id) => context.data.session.root(id),
+          tabs: context.ui.tabs.enabled() ? context.ui.tabs.list().map((t) => t.sessionID) : [],
+        }),
+      send: (sessionIDs) => call("presence", { sessionIDs: [...sessionIDs], reporter }),
+    })
+    presence.start()
+
+    // Questions answered on the hub that this TUI's (standalone) server cannot answer itself.
+    const forms = new FormRelay({
+      poll: (waitMs) => call<{ actions: unknown[] }>("formActions", { waitMs }),
+      apply: (action) =>
+        "cancel" in action
+          ? context.client.session.form.cancel({ sessionID: action.sessionID, formID: action.formID })
+          : context.client.session.form.reply({ sessionID: action.sessionID, formID: action.formID, answer: action.answer as Record<string, string | number | boolean | string[]> }),
+    })
+    void forms.start()
+
+    // One entry per command; a new /<feature> is one more entry (src/tui-commands.ts).
+    const commands = hubCommands(
+      [
+        { id: "open", slash: "hub", title: "server, connection, sharing and phones", run: open },
+        { id: "voice", slash: "voice", title: "talk to this session (Voice mode in the browser)", run: voice },
+      ],
+      (cause) => toast(errorMessage(cause), "error"),
+    )
+    context.keymap.layer(() => ({ mode: "global", commands }))
+    return () => {
+      presence.stop()
+      forms.stop()
+    }
+  },
+})
+
+// RPC failures arrive as plain objects ({ type, message, data }), not Error instances.
+function errorMessage(cause: unknown): string {
+  if (cause && typeof cause === "object" && "message" in cause && typeof cause.message === "string") return cause.message
+  return String(cause)
+}
+
+function openURL(url: string): boolean {
+  const command = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : process.platform === "win32" ? "explorer" : undefined
+  if (!command) return false
+  try {
+    const child = spawn(command, [url], { stdio: "ignore", detached: true })
+    child.on("error", () => {})
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+function copyToClipboard(text: string): boolean {
+  if (process.platform !== "darwin") return false
+  try {
+    const child = spawn("pbcopy", { stdio: ["pipe", "ignore", "ignore"] })
+    child.on("error", () => {})
+    child.stdin.end(text)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/turns.ts

@@ -0,0 +1,94 @@
+// Tracks when a prompt we submitted has been fully handled.
+//
+// OpenCode reports a prompt's lifecycle as: session.inbox.delivered { inboxID } followed by
+// session.execution.{succeeded|failed|interrupted} for that session. session.wait() can return
+// before delivery, so it cannot be used to wait for the reply.
+
+export type TurnResult =
+  | { outcome: "succeeded" }
+  | { outcome: "failed" | "interrupted"; message: string }
+  | { outcome: "timeout" }
+
+interface EventLike {
+  readonly type: string
+  readonly data?: unknown
+}
+
+const ENDINGS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
+
+export class TurnTracker {
+  private readonly pending = new Map<string, Set<string>>()
+  private readonly finished = new Map<string, TurnResult>()
+  private readonly waiters = new Map<string, Set<(result: TurnResult) => void>>()
+  private readonly historyLimit: number
+
+  constructor(options: { historyLimit?: number } = {}) {
+    this.historyLimit = options.historyLimit ?? 200
+  }
+
+  observe(event: EventLike): void {
+    const data = (event.data ?? {}) as Record<string, unknown>
+    const sessionID = typeof data.sessionID === "string" ? data.sessionID : undefined
+    if (!sessionID) return
+
+    if (event.type === "session.inbox.delivered" && typeof data.inboxID === "string") {
+      const ids = this.pending.get(sessionID) ?? new Set<string>()
+      ids.add(data.inboxID)
+      this.pending.set(sessionID, ids)
+      return
+    }
+
+    if (!ENDINGS.has(event.type)) return
+    const ids = this.pending.get(sessionID)
+    if (!ids) return
+    this.pending.delete(sessionID)
+    const result = resultOf(event.type, data)
+    for (const id of ids) this.finish(id, result)
+  }
+
+  wait(inboxID: string, options: { timeoutMs?: number } = {}): Promise<TurnResult> {
+    const done = this.finished.get(inboxID)
+    if (done) return Promise.resolve(done)
+    return new Promise((resolve) => {
+      const waiters = this.waiters.get(inboxID) ?? new Set()
+      const timer =
+        options.timeoutMs === undefined
+          ? undefined
+          : setTimeout(() => {
+              waiters.delete(settle)
+              resolve({ outcome: "timeout" })
+            }, options.timeoutMs)
+      const settle = (result: TurnResult) => {
+        if (timer) clearTimeout(timer)
+        resolve(result)
+      }
+      waiters.add(settle)
+      this.waiters.set(inboxID, waiters)
+    })
+  }
+
+  finishedCount(): number {
+    return this.finished.size
+  }
+
+  private finish(inboxID: string, result: TurnResult): void {
+    this.finished.set(inboxID, result)
+    while (this.finished.size > this.historyLimit) {
+      const oldest = this.finished.keys().next().value
+      if (oldest === undefined) break
+      this.finished.delete(oldest)
+    }
+    const waiters = this.waiters.get(inboxID)
+    this.waiters.delete(inboxID)
+    for (const settle of waiters ?? []) settle(result)
+  }
+}
+
+function resultOf(type: string, data: Record<string, unknown>): TurnResult {
+  if (type === "session.execution.succeeded") return { outcome: "succeeded" }
+  if (type === "session.execution.interrupted") {
+    return { outcome: "interrupted", message: String(data.reason ?? "interrupted") }
+  }
+  const error = data.error as { message?: unknown } | undefined
+  return { outcome: "failed", message: String(error?.message ?? "execution failed") }
+}

package/src/voice-command.ts

@@ -0,0 +1,65 @@
+// /voice: no menu. Makes sure the hub is set up and connected (running the /hub setup first when it is not),
+// shares the session on screen for Voice, and opens it in the browser with Voice mode starting
+// (`/s/<id>?voice=1` through a one-time sign-in link). The TUI (src/tui.ts) supplies the dialogs and RPCs.
+import { needsSetup, type Mode } from "./setup"
+
+/** The parts of hub.status the flow reads. */
+export interface VoiceStatus {
+  readonly server: string
+  readonly mode: Mode
+  readonly enrolled: boolean
+  readonly connection: "off" | "connecting" | "connected" | "revoked" | "error"
+  readonly sessionExposed?: boolean
+  readonly localHub?: string
+  readonly lastError?: string
+}
+
+export interface VoiceCommandDeps {
+  /** The session on screen. */
+  sessionID(): string | undefined
+  status(sessionID: string): Promise<VoiceStatus>
+  /** The /hub first-run setup (without opening the browser); resolves when the user finished or left it. */
+  setup(status: VoiceStatus): Promise<void>
+  /** /hub → Mode, for a machine whose sharing is off. */
+  chooseMode(status: VoiceStatus): Promise<void>
+  /** Connects (starting a local hub when needed) and waits; throws with the reason when it can't. */
+  connect(status: VoiceStatus): Promise<VoiceStatus>
+  /** Shares the session for Voice (this session on). */
+  expose(sessionID: string): Promise<void>
+  openLink(sessionID: string, voice: true): Promise<{ url: string }>
+  /** Opens the link in the browser (and says so), or shows it. */
+  showLink(url: string, what: string): Promise<void>
+  toast(message: string, variant: "info" | "success" | "warning" | "error"): void
+}
+
+export type VoiceOutcome = "opened" | "no-session" | "not-set-up" | "off"
+
+export async function startVoice(deps: VoiceCommandDeps): Promise<VoiceOutcome> {
+  const sessionID = deps.sessionID()
+  if (!sessionID) {
+    deps.toast("Open a session first, then run /voice to talk to it in the browser.", "warning")
+    return "no-session"
+  }
+  let s = await deps.status(sessionID)
+  if (needsSetup(s)) {
+    await deps.setup(s)
+    s = await deps.status(sessionID)
+    if (needsSetup(s)) {
+      deps.toast("Finish setting up the hub (approve this machine if asked), then run /voice again.", "warning")
+      return "not-set-up"
+    }
+  }
+  if (s.mode === "off") {
+    await deps.chooseMode(s)
+    s = await deps.status(sessionID)
+    if (s.mode === "off") {
+      deps.toast("Sharing with the hub is off for this machine. Choose a mode in /hub, then run /voice again.", "warning")
+      return "off"
+    }
+  }
+  if (s.connection !== "connected") s = await deps.connect(s)
+  if (!s.sessionExposed) await deps.expose(sessionID)
+  const { url } = await deps.openLink(sessionID, true)
+  await deps.showLink(url, "Voice mode for this session")
+  return "opened"
+}

package/tui.ts

@@ -0,0 +1,2 @@
+// OpenCode resolves a local plugin directory's TUI entry as <dir>/tui.
+export { default } from "./src/tui.ts"