@huynle/hub 0.0.0-stage → 0.6.0

package/src/config.ts

@@ -0,0 +1,170 @@
+// Per-machine spoke configuration, shared by every OpenCode process on the machine and edited
+// from the /hub dialog. Holds the machine token, so it is written with mode 0600.
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+import { hubEnv, type Env } from "./env"
+import { APP_DIR, configBase, legacyPaths, migrateFirst } from "./migrate"
+
+export type Mode = "off" | "always" | "session"
+
+export interface VoiceConfig {
+  readonly server: string
+  readonly mode: Mode
+  /** Session IDs exposed when mode is "session". */
+  readonly sessions: readonly string[]
+  readonly machineName: string
+  /** Agent the voice orchestrator delegates work to in conversation mode. */
+  readonly subagent: string
+  /** Start a local hub in the background when the server is loopback and nothing answers (default true). */
+  readonly autoStartLocalHub: boolean
+  /** Read open sessions and workspaces from the Herdr CLI (default true; the service process only). */
+  readonly herdr: boolean
+  /** History window of the session listing: root sessions from the last `days` days, at most `max`. */
+  readonly list: ListWindow
+  /** Fast model the voice agent talks with in conversation mode ("provider/model[#variant]"). */
+  readonly voiceModel?: string
+  /** Model subagents work on; defaults to the session's model before conversation mode. */
+  readonly workModel?: string
+  readonly machineID?: string
+  readonly token?: string
+}
+
+export interface ListWindow {
+  readonly days: number
+  readonly max: number
+}
+
+export const DEFAULT_LIST: ListWindow = Object.freeze({ days: 30, max: 100 })
+const LIST_LIMITS = { days: 365, max: 500 } as const
+
+export const DEFAULT_SERVER = "http://127.0.0.1:4097"
+export const DEFAULT_SUBAGENT = "general"
+const AGENT_ID = /^[A-Za-z0-9_.-]{1,64}$/
+const MODEL_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.:\/-]+(?:#[A-Za-z0-9_.-]+)?$/
+
+export interface ModelRef {
+  readonly providerID: string
+  readonly id: string
+  readonly variant?: string
+}
+
+/** "provider/model[#variant]"; the model ID may itself contain slashes (e.g. openrouter/anthropic/x). */
+export function parseModelRef(value: string): ModelRef | undefined {
+  if (!MODEL_REF.test(value)) return undefined
+  const [ref, variant] = value.split("#") as [string, string | undefined]
+  const slash = ref.indexOf("/")
+  return { providerID: ref.slice(0, slash), id: ref.slice(slash + 1), ...(variant ? { variant } : {}) }
+}
+
+/** OpenCode reports a model selected without a variant as variant "default". */
+export function explicitVariant(ref: ModelRef): string | undefined {
+  return ref.variant && ref.variant !== "default" ? ref.variant : undefined
+}
+
+/** Drops the implicit "default" variant so the ref can be passed back to OpenCode tools. */
+export function plainModelRef(ref: ModelRef): ModelRef {
+  const variant = explicitVariant(ref)
+  return { providerID: ref.providerID, id: ref.id, ...(variant ? { variant } : {}) }
+}
+
+export function formatModelRef(ref: ModelRef): string {
+  const variant = explicitVariant(ref)
+  return `${ref.providerID}/${ref.id}${variant ? `#${variant}` : ""}`
+}
+
+const modelRef = (v: unknown) => (typeof v === "string" && v.length <= 200 && MODEL_REF.test(v) ? v : undefined)
+
+/** $HUB_SPOKE_CONFIG (legacy $OPENCODE_HUB_CONFIG, $OPENCODE_VOICE_CONFIG), else ~/.config/hub/config.json. */
+export function configPath(env: Env = process.env, home: string = homedir()): string {
+  const explicit = hubEnv(env).HUB_SPOKE_CONFIG
+  if (explicit) return explicit
+  return path.join(configBase(env, home), APP_DIR, "config.json")
+}
+
+/**
+ * configPath, after copying the legacy ~/.config/opencode-hub/config.json (else the opencode-voice one) to
+ * the default location on first start (never for an explicit path; the old files are kept).
+ */
+export function prepareConfigPath(env: Env = process.env, home: string = homedir(), log?: (message: string) => void): string {
+  const file = configPath(env, home)
+  if (!hubEnv(env).HUB_SPOKE_CONFIG) {
+    migrateFirst(legacyPaths(configBase(env, home), "config.json"), file, log ? { log } : {})
+  }
+  return file
+}
+
+export function defaults(machineName: string): VoiceConfig {
+  return { server: DEFAULT_SERVER, mode: "off", sessions: [], machineName, subagent: DEFAULT_SUBAGENT, autoStartLocalHub: true, herdr: true, list: { ...DEFAULT_LIST } }
+}
+
+/** Normalizes untrusted JSON into a config, falling back to defaults field by field. */
+export function normalize(raw: unknown, machineName: string): VoiceConfig {
+  const base = defaults(machineName)
+  if (typeof raw !== "object" || raw === null) return base
+  const r = raw as Record<string, unknown>
+  const server = typeof r.server === "string" && /^https?:\/\/[^\s]+$/.test(r.server) ? r.server.replace(/\/+$/, "") : base.server
+  const mode: Mode = r.mode === "always" || r.mode === "session" || r.mode === "off" ? r.mode : base.mode
+  const sessions = Array.isArray(r.sessions) ? [...new Set(r.sessions.filter((s): s is string => typeof s === "string" && s.startsWith("ses")))] : []
+  return {
+    server,
+    mode,
+    sessions,
+    machineName: typeof r.machineName === "string" && r.machineName ? r.machineName : machineName,
+    subagent: typeof r.subagent === "string" && AGENT_ID.test(r.subagent) ? r.subagent : base.subagent,
+    autoStartLocalHub: r.autoStartLocalHub !== false,
+    herdr: r.herdr !== false,
+    list: listWindow(r.list),
+    ...(modelRef(r.voiceModel) ? { voiceModel: modelRef(r.voiceModel) } : {}),
+    ...(modelRef(r.workModel) ? { workModel: modelRef(r.workModel) } : {}),
+    ...(typeof r.machineID === "string" && r.machineID ? { machineID: r.machineID } : {}),
+    ...(typeof r.token === "string" && r.token ? { token: r.token } : {}),
+  }
+}
+
+const inRange = (v: unknown, max: number): v is number => Number.isInteger(v) && (v as number) >= 1 && (v as number) <= max
+
+/** Each field of the history window falls back to its default when missing or out of range. */
+function listWindow(raw: unknown): ListWindow {
+  const r = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {}
+  return {
+    days: inRange(r.days, LIST_LIMITS.days) ? r.days : DEFAULT_LIST.days,
+    max: inRange(r.max, LIST_LIMITS.max) ? r.max : DEFAULT_LIST.max,
+  }
+}
+
+export function readConfig(file: string, machineName: string): VoiceConfig {
+  try {
+    return normalize(JSON.parse(readFileSync(file, "utf8")), machineName)
+  } catch {
+    return defaults(machineName)
+  }
+}
+
+/** Atomic write with 0600 permissions. */
+export function writeConfig(file: string, config: VoiceConfig): void {
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  chmodSync(tmp, 0o600)
+  renameSync(tmp, file)
+}
+
+/** Changing the server URL drops the machine credentials, which belong to the old server. */
+export function withServer(config: VoiceConfig, server: string): VoiceConfig {
+  const next = normalize({ ...config, server }, config.machineName)
+  if (next.server === config.server) return next
+  const { machineID: _id, token: _token, ...rest } = next
+  return rest
+}
+
+export function isExposed(config: VoiceConfig, sessionID: string): boolean {
+  if (config.mode === "always") return true
+  if (config.mode === "session") return config.sessions.includes(sessionID)
+  return false
+}
+
+export function setSession(config: VoiceConfig, sessionID: string, on: boolean): VoiceConfig {
+  const sessions = on ? [...new Set([...config.sessions, sessionID])] : config.sessions.filter((id) => id !== sessionID)
+  return { ...config, sessions }
+}

package/src/env.ts

@@ -0,0 +1,63 @@
+// Environment variables of Hub. The project was called opencode-voice, then opencode-hub: their VOICE_*,
+// OPENCODE_VOICE_* and OPENCODE_HUB_* names are still read as fallbacks (the new HUB_* name wins, then the
+// most recent legacy name), with a one-time deprecation warning per legacy name. Code reads only the new names from hubEnv(env).
+
+export type Env = Readonly<Record<string, string | undefined>>
+
+/** New name → legacy names, most recent first. */
+export const LEGACY_ENV: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  HUB_HOST: ["VOICE_HOST"],
+  HUB_PORT: ["VOICE_PORT"],
+  HUB_PUBLIC_URL: ["VOICE_PUBLIC_URL"],
+  HUB_STATE_DIR: ["VOICE_STATE_DIR"],
+  HUB_CONFIG: ["VOICE_HUB_CONFIG"],
+  HUB_AUTH: ["VOICE_AUTH"],
+  HUB_OIDC_ISSUER: ["VOICE_OIDC_ISSUER"],
+  HUB_OIDC_CLIENT_ID: ["VOICE_OIDC_CLIENT_ID"],
+  HUB_OIDC_CLIENT_SECRET: ["VOICE_OIDC_CLIENT_SECRET"],
+  HUB_OIDC_ALLOWED: ["VOICE_OIDC_ALLOWED"],
+  HUB_OIDC_INSECURE_ISSUER: ["VOICE_OIDC_INSECURE_ISSUER"],
+  HUB_ADMIN_EMAILS: ["VOICE_ADMIN_EMAILS"],
+  HUB_STT_MODEL: ["VOICE_STT_MODEL"],
+  HUB_TTS_MODEL: ["VOICE_TTS_MODEL"],
+  HUB_VOICE: ["VOICE_VOICE"],
+  HUB_MAX_AUDIO_BYTES: ["VOICE_MAX_AUDIO_BYTES"],
+  HUB_MAX_SPEECH_CHARS: ["VOICE_MAX_SPEECH_CHARS"],
+  HUB_TURN_TIMEOUT_MS: ["VOICE_TURN_TIMEOUT_MS"],
+  HUB_VAPID_SUBJECT: ["VOICE_VAPID_SUBJECT"],
+  /** The spoke (plugin) config file: OPENCODE_HUB_CONFIG in 0.5, OPENCODE_VOICE_CONFIG before. */
+  HUB_SPOKE_CONFIG: ["OPENCODE_HUB_CONFIG", "OPENCODE_VOICE_CONFIG"],
+})
+
+export interface HubEnvOptions {
+  /** Where deprecation warnings go (default console.warn with the [hub] prefix). */
+  readonly warn?: (message: string) => void
+  /** Legacy names already warned about (default: once per process). */
+  readonly seen?: Set<string>
+}
+
+const processSeen = new Set<string>()
+const defaultWarn = (message: string) => console.warn(`[hub] warning: ${message}`)
+
+/** A copy of `env` with every unset HUB_* name filled from its legacy name. Never echoes values. */
+export function hubEnv(env: Env = process.env, options: HubEnvOptions = {}): Env {
+  const warn = options.warn ?? defaultWarn
+  const seen = options.seen ?? processSeen
+  const out: Record<string, string | undefined> = { ...env }
+  for (const [name, legacies] of Object.entries(LEGACY_ENV)) {
+    // The name that supplies the value: the new one when set, else the first legacy one set.
+    let winner = env[name] !== undefined ? name : undefined
+    for (const legacy of legacies) {
+      if (env[legacy] === undefined) continue
+      const ignored = winner !== undefined
+      if (!ignored) {
+        winner = legacy
+        out[name] = env[legacy]
+      }
+      if (seen.has(legacy)) continue
+      seen.add(legacy)
+      warn(ignored ? `${legacy} is ignored because ${winner} is set; remove ${legacy}` : `${legacy} is deprecated; rename it to ${name}`)
+    }
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,236 @@
+// Hub server plugin: a thin "spoke" that connects this OpenCode process to the hub. The web
+// console, phones and (optional) Voice speech live on the hub; this side only exposes sessions, forwards
+// their events, and runs remote / voice turns and permission replies on request.
+import { readFileSync } from "node:fs"
+import { hostname } from "node:os"
+import { Plugin } from "@opencode/plugin"
+import { DEFAULT_SUBAGENT, prepareConfigPath } from "./config"
+import { HubRpc, VoiceRpc } from "./rpc"
+import { checkServer, parseServerInput } from "./setup"
+import { defineVoiceAgent, orchestratorParts } from "./spoke/conversation"
+import { herdrRunner } from "./spoke/herdr"
+import { listServiceSessions } from "./spoke/listing"
+import { ensureLocalHub } from "./spoke/localhub"
+import { replyPermission, type PermissionLocation } from "./spoke/locations"
+import { foregroundEndpoint, formOutcome } from "./spoke/own-server"
+import { joinProcess, type Membership } from "./spoke/singleton"
+import { detectKind, Spoke, SpokeError, type FormAction, type SpokeHost } from "./spoke/spoke"
+
+type Context = Parameters<Parameters<typeof Plugin.define>[0]["setup"]>[0]
+
+const VOICE_STYLE =
+  "This message came from a voice conversation and your reply will be read aloud. " +
+  "Answer in at most three short sentences of plain speech: no markdown, code blocks, tables, or lists. " +
+  "Keep using tools as needed; only the final reply must be short."
+
+function pluginVersion(): string {
+  try {
+    return String(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0")
+  } catch {
+    return "0.0.0"
+  }
+}
+
+/**
+ * The most recent root sessions of the local OpenCode service with their workspace (used by the
+ * service's own spoke for the phone's session browser): the history window plus `include`.
+ */
+async function listRecent(options?: { days: number; max: number; include: readonly string[] }) {
+  const { Service } = await import("@opencode/client/service")
+  const { OpenCode } = await import("@opencode/client")
+  const endpoint = await Service.discover()
+  if (!endpoint) return []
+  const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) ?? {} })
+  return listServiceSessions(client, options ?? {})
+}
+
+/** 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")
+  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
+  }
+  const endpoint = foregroundEndpoint(process.argv, process.env)
+  return endpoint ? OpenCode.make({ baseUrl: endpoint.url, headers: { authorization: endpoint.authorization } }) : undefined
+}
+
+/** Answers or cancels a form through the own server's API (the plugin API has no forms). */
+async function replyForm(kind: "service" | "standalone", action: FormAction): Promise<"replied" | "gone" | "unavailable"> {
+  const client = await ownClient(kind).catch(() => undefined)
+  if (!client) return "unavailable"
+  try {
+    if ("cancel" in action) await client.session.form.cancel({ sessionID: action.sessionID, formID: action.formID })
+    else await client.session.form.reply({ sessionID: action.sessionID, formID: action.formID, answer: action.answer as Record<string, string | number | boolean | string[]> })
+    return "replied"
+  } catch (cause) {
+    if (formOutcome(cause) === "gone") return "gone"
+    throw cause
+  }
+}
+
+/** Plugin API results may arrive bare or wrapped as { location, data }. */
+function unwrap<T>(value: unknown, isBare: (v: any) => boolean): T {
+  const v = value as any
+  return (v && !isBare(v) && v.data !== undefined ? v.data : v) as T
+}
+
+/** This instance's location-scoped permission API (OpenCode keeps pending permissions per location). */
+function permissionLocation(ctx: Context): PermissionLocation {
+  const permission = ctx.permission as any
+  return {
+    directory: ctx.location.directory,
+    get: (input) => permission.get(input),
+    reply: (input) => permission.reply(input),
+  }
+}
+
+/** `locations`: the permission APIs of every plugin instance in this process (one per location). */
+function hostFrom(ctx: Context, locations: () => PermissionLocation[], kind: "service" | "standalone"): SpokeHost {
+  const session = ctx.session as any
+  const agent = ctx.agent as any
+  const mcp = (ctx as any).mcp
+  const vcs = (ctx as any).vcs
+  return {
+    directory: ctx.location.directory,
+    opencodeVersion: ctx.app?.version ?? "unknown",
+    events: (signal) => ctx.event.subscribe({ signal }) as AsyncIterable<any>,
+    prompt: (input) => session.prompt(input),
+    context: (sessionID) => session.context({ sessionID }),
+    listModels: async () => unwrap<ReadonlyArray<unknown>>(await (ctx.model as any).list({}), Array.isArray),
+    getSession: async (sessionID) => unwrap(await session.get({ sessionID }), (v) => typeof v.id === "string"),
+    replyPermission: ({ directory, ...input }) => replyPermission(locations(), input, directory),
+    replyForm: (action) => replyForm(kind, action),
+    interrupt: (sessionID) => session.interrupt({ sessionID }),
+    switchAgent: (sessionID, id) => session.switchAgent({ sessionID, agent: id }),
+    switchModel: (sessionID, model) => session.switchModel({ sessionID, model }),
+    hasAgent: async (id) => {
+      try {
+        const info = unwrap<{ id?: string } | undefined>(await agent.get({ agentID: id }), (v) => typeof v.id === "string")
+        return info?.id === id
+      } catch {
+        return false
+      }
+    },
+    defaultAgent: async () => {
+      const list = unwrap<Array<{ id: string; mode?: string; hidden?: boolean }>>(await agent.list({}), Array.isArray)
+      return list?.find((a) => a.mode !== "subagent" && !a.hidden)?.id
+    },
+    listRecent,
+    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) } : {}),
+    ...(vcs?.diff ? { vcsDiff: async (directory: string) => unwrap<ReadonlyArray<unknown>>(await vcs.diff({ mode: "working", location: { directory } }), Array.isArray) } : {}),
+    ...(vcs?.get
+      ? {
+          vcsBranch: async (directory: string) => {
+            const info = unwrap<{ branch?: { current?: string } }>(await vcs.get({ location: { directory } }), (v) => "branch" in v)
+            return typeof info?.branch?.current === "string" ? info.branch.current : undefined
+          },
+        }
+      : {}),
+  }
+}
+
+export default Plugin.define({
+  id: "hub",
+  async setup(ctx) {
+    const kind = detectKind(process.argv)
+    const membership: Membership<Spoke> = joinProcess(
+      (processID) =>
+        new Spoke(hostFrom(ctx, () => membership.locals<PermissionLocation>(), kind), {
+          configFile: prepareConfigPath(),
+          machineName: hostname(),
+          kind,
+          processID,
+          pid: process.pid,
+          pluginVersion: pluginVersion(),
+          // Loopback servers only, and only when autoStartLocalHub is on (see src/spoke/localhub.ts).
+          localHub: (server) => ensureLocalHub(server),
+          // One Herdr reader per machine: the background service's spoke (see src/spoke/herdr.ts).
+          ...(kind === "service" ? { herdr: herdrRunner() } : {}),
+        }),
+      undefined,
+      permissionLocation(ctx),
+    )
+
+    try {
+      await ctx.agent.transform((editor) => defineVoiceAgent(editor as any))
+    } catch (cause) {
+      console.error("[hub] could not register the voice agent", cause)
+    }
+
+    try {
+      await ctx.session.hook("context", (event) => {
+        const spoke = membership.active()
+        if (spoke?.isVoiceTurn(event.sessionID)) event.system.push({ type: "text", text: VOICE_STYLE })
+        const parts = orchestratorParts({
+          agent: event.agent,
+          conversation: spoke?.inConversation(event.sessionID) ?? false,
+          subagent: spoke?.subagent() ?? DEFAULT_SUBAGENT,
+          workModel: spoke?.workModelFor(event.sessionID),
+        })
+        for (const text of parts) event.system.push({ type: "text", text })
+      })
+    } catch (cause) {
+      console.error("[hub] could not register the context hook", cause)
+    }
+
+    const run = async <T>(rpc: { error: (...args: any[]) => any }, action: (spoke: Spoke) => T | Promise<T>) => {
+      const spoke = membership.active()
+      if (!spoke) return rpc.error("unavailable", "The hub spoke is not running in this OpenCode process", {})
+      try {
+        return await action(spoke)
+      } catch (cause) {
+        if (cause instanceof SpokeError) return rpc.error(cause.name, cause.message, {})
+        return rpc.error("server_error", cause instanceof Error ? cause.message : String(cause), {})
+      }
+    }
+    const input = (value: unknown) => (value ?? {}) as Record<string, any>
+
+    const handlers = {
+      status: (value, rpc) => run(rpc, (s) => s.status(input(value).sessionID)),
+      setServer: (value, rpc) => run(rpc, (s) => (s.setServer(String(input(value).server ?? "")), {})),
+      checkServer: async (value, rpc) => {
+        const parsed = parseServerInput(String(input(value).server ?? ""))
+        if (!parsed.ok) return rpc.error("invalid", parsed.error, {})
+        return checkServer(parsed.url)
+      },
+      startLocalHub: (_value, rpc) => run(rpc, (s) => s.startLocalHub()),
+      enroll: (_value, rpc) => run(rpc, (s) => s.enroll()),
+      setMode: (value, rpc) => run(rpc, (s) => (s.setMode(input(value).mode), {})),
+      setSession: (value, rpc) =>
+        run(rpc, (s) => (s.setSession(String(input(value).sessionID ?? ""), Boolean(input(value).on)), {})),
+      pairCode: (_value, rpc) => run(rpc, (s) => s.pairCode()),
+      handoff: (value, rpc) => run(rpc, (s) => s.handoff(String(input(value).sessionID ?? ""))),
+      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))),
+      formActions: (value, rpc) =>
+        run(rpc, (s) => {
+          const { waitMs = 0 } = input(value)
+          if (typeof waitMs !== "number" || !Number.isFinite(waitMs)) throw new SpokeError("invalid", "Expected {waitMs: number}")
+          return s.formActions(Math.max(0, Math.min(waitMs, 25_000))) as Promise<{ actions: Array<Record<string, unknown>> }>
+        }),
+      presence: (value, rpc) =>
+        run(rpc, (s) => {
+          const { sessionIDs, reporter } = input(value)
+          if (!Array.isArray(sessionIDs)) throw new SpokeError("invalid", "Expected {sessionIDs: string[]}")
+          s.presence(sessionIDs.filter((id): id is string => typeof id === "string").slice(0, 200), typeof reporter === "string" ? reporter.slice(0, 100) : undefined)
+          return {}
+        }),
+    } satisfies Parameters<typeof ctx.rpc.register<typeof HubRpc>>[1]
+    // "hub", plus the opencode-voice id "voice" for clients built against the old name (see src/rpc.ts).
+    for (const definition of [HubRpc, VoiceRpc]) {
+      try {
+        await ctx.rpc.register(definition, handlers)
+      } catch (cause) {
+        console.error(`[hub] could not register RPC methods (${definition.id})`, cause)
+      }
+    }
+
+    return () => membership.leave()
+  },
+})

package/src/key.ts

@@ -0,0 +1,17 @@
+export interface KeySources {
+  active(integrationID: string): Promise<unknown>
+  resolve(connection: any): Promise<unknown>
+  env: Readonly<Record<string, string | undefined>>
+}
+
+/** OpenCode's openrouter integration first, then OPENROUTER_API_KEY, then the plugin option. */
+export async function resolveOpenRouterKey(sources: KeySources, optionKey: string | undefined): Promise<string | undefined> {
+  try {
+    const connection = await sources.active("openrouter")
+    if (connection) {
+      const value = (await sources.resolve(connection)) as { type?: unknown; key?: unknown } | undefined
+      if (value?.type === "key" && typeof value.key === "string" && value.key) return value.key
+    }
+  } catch {}
+  return sources.env.OPENROUTER_API_KEY || optionKey || undefined
+}

package/src/loopback.ts

@@ -0,0 +1,41 @@
+// Loopback detection, shared by the hub (CSRF origins for a local hub, first-machine auto-approve) and the
+// spoke (auto-starting a local hub). Only names that can never leave the machine count: localhost,
+// 127.0.0.0/8 and ::1. Request addresses are a hint only, never authentication.
+
+/** Hostnames as they appear in URLs (`[::1]`) or in config (`::1`). */
+export function isLoopbackHost(host: string): boolean {
+  const h = host.trim().toLowerCase().replace(/^\[(.*)\]$/, "$1")
+  if (h === "localhost" || h === "::1") return true
+  const ip = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h)
+  return ip !== null && ip.slice(1).every((part) => Number(part) <= 255)
+}
+
+/** An http(s) URL whose host is loopback. */
+export function isLoopbackURL(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    return (parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopbackHost(parsed.hostname)
+  } catch {
+    return false
+  }
+}
+
+/** A peer address (e.g. Bun's server.requestIP) on loopback, including IPv4-mapped IPv6. */
+export function isLoopbackAddress(ip: string | undefined | null): boolean {
+  if (!ip) return false
+  const address = ip.toLowerCase().replace(/^::ffff:/, "")
+  return address !== "localhost" && isLoopbackHost(address)
+}
+
+const LOOPBACK_NAMES = ["localhost", "127.0.0.1", "[::1]"] as const
+
+/**
+ * Origins a browser may send for this public URL. A loopback public URL is reachable as localhost,
+ * 127.0.0.1 and [::1] (same scheme and port); any other public URL has exactly one origin.
+ */
+export function loopbackOrigins(publicURL: string): Set<string> {
+  const url = new URL(publicURL)
+  if (!isLoopbackHost(url.hostname)) return new Set([url.origin])
+  const port = url.port ? `:${url.port}` : ""
+  return new Set([url.origin, ...LOOPBACK_NAMES.map((name) => `${url.protocol}//${name}${port}`)])
+}

package/src/migrate.ts

@@ -0,0 +1,105 @@
+// One-time migration from the legacy locations to the Hub ones. The project was opencode-voice (<= 0.4),
+// then opencode-hub (0.5), and is now Hub. When the new file or directory is missing, the most recent
+// legacy one that exists (opencode-hub first, then opencode-voice) is copied (file modes kept, e.g. 0600 for tokens)
+// through a temporary sibling that is renamed into place, so a partial copy never looks migrated. The
+// legacy copy is never touched or deleted. Callers skip migration for paths set explicitly by env.
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs"
+import path from "node:path"
+import type { Env } from "./env"
+
+export const APP_DIR = "hub"
+/** Legacy directory names under ~/.config and ~/.local/state, most recent first. */
+export const LEGACY_APP_DIRS: readonly string[] = Object.freeze(["opencode-hub", "opencode-voice"])
+
+/** $XDG_CONFIG_HOME or ~/.config. */
+export const configBase = (env: Env, home: string): string => env.XDG_CONFIG_HOME || path.join(home, ".config")
+/** ~/.local/state. */
+export const stateBase = (home: string): string => path.join(home, ".local", "state")
+
+export type MigrationResult = "migrated" | "none" | "failed"
+
+export interface MigrateOptions {
+  /** One line when something was copied or the copy failed (default console.log / console.warn). */
+  readonly log?: (message: string) => void
+  /** Top-level entry names of a legacy directory not to copy (e.g. a lock file). */
+  readonly skip?: readonly string[]
+}
+
+const exists = (p: string) => existsSync(p) || isLink(p)
+function isLink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function copyEntry(src: string, dst: string, skip: readonly string[] = []): void {
+  const stat = lstatSync(src)
+  if (stat.isDirectory()) {
+    mkdirSync(dst, { mode: 0o700 })
+    for (const name of readdirSync(src)) {
+      if (!skip.includes(name)) copyEntry(path.join(src, name), path.join(dst, name))
+    }
+    chmodSync(dst, stat.mode & 0o7777)
+  } else if (stat.isFile()) {
+    copyFileSync(src, dst)
+    chmodSync(dst, stat.mode & 0o7777)
+  } else if (stat.isSymbolicLink()) {
+    symlinkSync(readlinkSync(src), dst)
+  }
+  // sockets, FIFOs and devices are not state worth copying
+}
+
+/** Copies `legacy` to `target` when only the legacy one exists. Never throws. */
+export function migrateLegacy(legacy: string, target: string, options: MigrateOptions = {}): MigrationResult {
+  if (exists(target) || !exists(legacy)) return "none"
+  const tmp = `${target}.migrating-${process.pid}-${Date.now()}`
+  try {
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 })
+    copyEntry(legacy, tmp, options.skip)
+    try {
+      renameSync(tmp, target)
+    } catch (cause) {
+      // Another process migrated first: theirs stands.
+      if (exists(target)) {
+        rmSync(tmp, { recursive: true, force: true })
+        return "none"
+      }
+      throw cause
+    }
+  } catch (cause) {
+    rmSync(tmp, { recursive: true, force: true })
+    const message = `could not migrate ${legacy} to ${target}: ${cause instanceof Error ? cause.message : cause}`
+    ;(options.log ?? ((m: string) => console.warn(`[hub] warning: ${m}`)))(message)
+    return "failed"
+  }
+  ;(options.log ?? ((m: string) => console.log(`[hub] ${m}`)))(
+    `migrated ${legacy} to ${target} (the project is now Hub; the old copy is kept)`,
+  )
+  return "migrated"
+}
+
+/**
+ * Copies the first existing of `legacies` (most recent first) to `target` when the target is missing.
+ * Never throws; the legacy copies are never touched.
+ */
+export function migrateFirst(legacies: readonly string[], target: string, options: MigrateOptions = {}): MigrationResult {
+  if (exists(target)) return "none"
+  const legacy = legacies.find(exists)
+  return legacy === undefined ? "none" : migrateLegacy(legacy, target, options)
+}
+
+/** The legacy copies of `<base>/<APP_DIR>/<...rest>`, most recent first. */
+export const legacyPaths = (base: string, ...rest: string[]): string[] => LEGACY_APP_DIRS.map((dir) => path.join(base, dir, ...rest))

package/src/openrouter.ts

@@ -0,0 +1,3 @@
+// Compatibility re-exports: the speech providers live in src/central/speech/.
+export { OpenRouter, OpenRouterError, OPENROUTER_BASE_URL, type OpenRouterOptions } from "./central/speech/openrouter"
+export { audioFormat, SpeechError, type SpeechProvider } from "./central/speech/provider"

package/src/options.ts

@@ -0,0 +1,33 @@
+export interface VoiceOptions {
+  readonly host: string
+  readonly port: number
+  /** Base URL used in /hub links when the page is reached through a proxy (e.g. tailscale serve). */
+  readonly publicURL?: string
+  readonly sttModel: string
+  readonly ttsModel: string
+  readonly voice: string
+  /** Fallback when neither the OpenCode openrouter integration nor OPENROUTER_API_KEY is set. */
+  readonly apiKey?: string
+  readonly maxAudioBytes: number
+  readonly maxSpeechChars: number
+  readonly turnTimeoutMs: number
+}
+
+const string = (value: unknown, fallback: string) => (typeof value === "string" && value ? value : fallback)
+const positive = (value: unknown, fallback: number) =>
+  typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback
+
+export function parseOptions(raw: Readonly<Record<string, unknown>>): VoiceOptions {
+  return {
+    host: string(raw.host, "127.0.0.1"),
+    port: positive(raw.port, 4097),
+    ...(typeof raw.publicURL === "string" && raw.publicURL ? { publicURL: raw.publicURL.replace(/\/+$/, "") } : {}),
+    sttModel: string(raw.sttModel, "openai/gpt-4o-mini-transcribe"),
+    ttsModel: string(raw.ttsModel, "microsoft/mai-voice-2.1-flash"),
+    voice: string(raw.voice, "en-US-Harper:MAI-Voice-2.1-Flash"),
+    ...(typeof raw.apiKey === "string" && raw.apiKey ? { apiKey: raw.apiKey } : {}),
+    maxAudioBytes: positive(raw.maxAudioBytes, 10 * 1024 * 1024),
+    maxSpeechChars: positive(raw.maxSpeechChars, 800),
+    turnTimeoutMs: positive(raw.turnTimeoutMs, 10 * 60 * 1000),
+  }
+}