@huynle/hub 0.0.0-stage → 0.6.0

package/src/rpc.ts

@@ -0,0 +1,98 @@
+import { Rpc } from "@opencode/plugin/rpc"
+
+// Server-side methods the /hub dialog calls. All of them act on this machine's spoke.
+// RPC id "hub"; opencode-voice (<= 0.4) used "voice". The TUI and server plugins ship together in this
+// package, so they always agree; the server also registers the same methods under the legacy id
+// (VoiceRpc) for any other client still built against opencode-voice.
+
+const obj = (properties: Record<string, unknown>, required: string[] = []) =>
+  ({ type: "object", properties, required, additionalProperties: false }) as const
+
+const str = { type: "string" } as const
+const bool = { type: "boolean" } as const
+const num = { type: "number" } as const
+const empty = obj({})
+const errorData = { type: "object" } as const
+
+/**
+ * not_connected: no live connection · invalid: bad input · unreachable: server could not be reached ·
+ * unavailable: spoke not running in this process · server_error: the hub refused the request.
+ */
+const errors = {
+  not_connected: errorData,
+  invalid: errorData,
+  unreachable: errorData,
+  unavailable: errorData,
+  server_error: errorData,
+} as const
+
+const methods = {
+  status: {
+    input: obj({ sessionID: str }),
+    output: {
+      type: "object",
+      properties: {
+        server: str,
+        mode: { type: "string", enum: ["off", "always", "session"] },
+        enrolled: bool,
+        connection: { type: "string", enum: ["off", "connecting", "connected", "revoked", "error"] },
+        lastError: str,
+        sessionExposed: bool,
+        conversation: bool,
+        enrollment: { type: "string", enum: ["pending", "approved", "denied", "expired", "error"] },
+        machineName: str,
+        kind: { type: "string", enum: ["service", "standalone"] },
+        localHub: str,
+      },
+      required: ["server", "mode", "enrolled", "connection", "machineName", "kind"],
+      additionalProperties: false,
+    },
+    errors,
+  },
+  setServer: { input: obj({ server: str }, ["server"]), output: empty, errors },
+  /** GET <server>/healthz from this machine: reachable and a Hub? */
+  checkServer: { input: obj({ server: str }, ["server"]), output: obj({ ok: bool, version: str, error: str }, ["ok"]), errors },
+  /** Start the local hub for the configured loopback server now (Open hub). */
+  startLocalHub: { input: empty, output: obj({ status: { type: "string", enum: ["started", "running", "busy"] } }, ["status"]), errors },
+  enroll: {
+    input: empty,
+    output: obj(
+      { userCode: str, approveURL: str, autoApproved: bool, localHub: { type: "string", enum: ["started", "running", "busy"] } },
+      ["userCode", "approveURL"],
+    ),
+    errors,
+  },
+  setMode: { input: obj({ mode: { type: "string", enum: ["off", "always", "session"] } }, ["mode"]), output: empty, errors },
+  setSession: { input: obj({ sessionID: str, on: bool }, ["sessionID", "on"]), output: empty, errors },
+  pairCode: { input: empty, output: obj({ code: str, url: str, expiresAt: num }, ["code", "url", "expiresAt"]), errors },
+  handoff: { input: obj({ sessionID: str }, ["sessionID"]), output: obj({ notified: num }, ["notified"]), errors },
+  /** One-time sign-in link: the session's page, or the home page without sessionID. */
+  /** voice: land on the session with Voice mode starting (`/s/<id>?voice=1`). */
+  openLink: { input: obj({ sessionID: str, voice: bool }), output: obj({ url: str }, ["url"]), errors },
+  /**
+   * TUI presence: the sessions this TUI shows (route root and open tabs), sent on change and every 15 s.
+   * `reporter` identifies the TUI; each report replaces its previous one.
+   */
+  presence: {
+    input: obj({ sessionIDs: { type: "array", items: str, maxItems: 200 }, reporter: str }, ["sessionIDs"]),
+    output: empty,
+    errors,
+  },
+  /**
+   * Form (question) replies from the hub this server cannot make itself (a standalone server started by a
+   * TUI): the TUI polls, carries them out with its client, and the server sees form.replied. Waits up to
+   * `waitMs` (at most 25 s) for one.
+   */
+  formActions: {
+    input: obj({ waitMs: num }),
+    output: obj({ actions: { type: "array", items: { type: "object" } } }, ["actions"]),
+    errors,
+  },
+  /** Conversation mode for a session in this process (same path as the server's "conversation" op). */
+  conversation: { input: obj({ sessionID: str, on: bool }, ["sessionID", "on"]), output: obj({ agent: str }, ["agent"]), errors },
+} as const
+
+export const HubRpc = Rpc.define({ id: "hub", methods, events: {} })
+
+/** @deprecated The opencode-voice RPC id ("voice"); same methods as HubRpc. */
+export const VoiceRpc = Rpc.define({ id: "voice", methods, events: {} })

package/src/setup.ts

@@ -0,0 +1,124 @@
+// First-run setup for /hub: whether to show it, which options in which order, the server URL the user
+// types, and whether that server answers like a Hub. Pure decisions; src/tui.ts renders them.
+import { DEFAULT_SERVER, type Mode } from "./config"
+import { isLoopbackURL } from "./loopback"
+
+export type { Mode }
+
+/** The parts of voice.status that setup depends on. */
+export interface SetupStatus {
+  readonly server: string
+  readonly enrolled: boolean
+  readonly connection: "off" | "connecting" | "connected" | "revoked" | "error"
+  readonly mode: Mode
+}
+
+/**
+ * configured: connect to the (remote) server already in the config · local / local-session: a hub on this
+ * computer, sharing every session / only sessions switched on · remote: type a server URL · later: close.
+ */
+export type SetupChoice = "configured" | "local" | "local-session" | "remote" | "later"
+
+export interface SetupOption {
+  readonly value: SetupChoice
+  readonly title: string
+  readonly description: string
+}
+
+export type Parsed = { readonly ok: true; readonly url: string } | { readonly ok: false; readonly error: string }
+export type Health = { readonly ok: true; readonly version?: string } | { readonly ok: false; readonly error: string }
+
+/** Setup instead of the regular menu: this machine has no token for its server, or the server revoked it. */
+export function needsSetup(status: SetupStatus): boolean {
+  return !status.enrolled || status.connection === "revoked"
+}
+
+const hostOf = (server: string) => server.replace(/^https?:\/\//, "")
+
+export function setupOptions(status: SetupStatus): SetupOption[] {
+  const remote = !isLoopbackURL(status.server)
+  const revoked = status.enrolled && status.connection === "revoked"
+  const options: SetupOption[] = []
+  if (remote) {
+    options.push({
+      value: "configured",
+      title: `Connect to ${hostOf(status.server)}`,
+      description: revoked
+        ? "This machine was revoked there; ask to be approved again"
+        : "Your hub: approve this machine in its web page, then open your sessions from any device",
+    })
+  }
+  options.push(
+    {
+      value: "local",
+      title: "On this computer (local — nothing to install)",
+      description: "Starts a hub here (nothing to install), shares every session, and opens it in your browser",
+    },
+    {
+      value: "local-session",
+      title: "On this computer, only sessions I choose",
+      description: "Same local hub; share a session with /hub → This session",
+    },
+    {
+      value: "remote",
+      title: remote ? "Connect to a different hub…" : "Connect to a hub…",
+      description: "A hub you or your team host, e.g. https://hub.example.com (needed for phones away from this computer)",
+    },
+    { value: "later", title: "Not now", description: "Run /hub again any time" },
+  )
+  return options
+}
+
+/** The local hub's URL: a loopback http server already configured (custom port), else the default. */
+export function localServerFor(server: string): string {
+  return isLoopbackURL(server) && server.startsWith("http:") ? server : DEFAULT_SERVER
+}
+
+/** Every session by default; only chosen sessions for the secondary local choice. */
+export function modeFor(choice: SetupChoice): Mode {
+  return choice === "local-session" ? "session" : "always"
+}
+
+/** A server URL as typed: http(s) only, a bare host means https; no credentials, query or fragment. */
+export function parseServerInput(raw: string): Parsed {
+  const text = raw.trim()
+  if (!text) return { ok: false, error: "Enter the hub's address, e.g. https://hub.example.com" }
+  if (/\s/.test(text)) return { ok: false, error: "The address cannot contain spaces" }
+  const withScheme = /^[a-z][a-z0-9+.-]*:/i.test(text) ? text : `https://${text}`
+  let url: URL
+  try {
+    url = new URL(withScheme)
+  } catch {
+    return { ok: false, error: `Not a valid address: ${text}` }
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return { ok: false, error: "Use an http:// or https:// address" }
+  if (!url.hostname) return { ok: false, error: `Not a valid address: ${text}` }
+  if (url.username || url.password) return { ok: false, error: "Leave user names and passwords out of the address" }
+  if (url.search || url.hash || withScheme.includes("#") || withScheme.includes("?")) {
+    return { ok: false, error: "Use the server's base address, without ? or #" }
+  }
+  return { ok: true, url: `${url.origin}${url.pathname}`.replace(/\/+$/, "") }
+}
+
+/** GET <server>/healthz: reachable and answering like a Hub ({ok: true}). */
+export async function checkServer(
+  server: string,
+  options: { fetch?: typeof globalThis.fetch; timeoutMs?: number } = {},
+): Promise<Health> {
+  const doFetch = options.fetch ?? globalThis.fetch
+  let res: Response
+  try {
+    res = await doFetch(`${server}/healthz`, { redirect: "manual", signal: AbortSignal.timeout(options.timeoutMs ?? 8000) })
+  } catch (cause) {
+    return { ok: false, error: `Could not reach ${server}: ${cause instanceof Error ? cause.message : String(cause)}` }
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      error: `${server}/healthz answered HTTP ${res.status}. If a login proxy protects the server, leave /healthz and /spoke/* reachable.`,
+    }
+  }
+  const body = (await res.json().catch(() => undefined)) as { ok?: unknown; version?: unknown } | undefined
+  if (body?.ok !== true) return { ok: false, error: `${server} answered, but it is not a Hub` }
+  return { ok: true, ...(typeof body.version === "string" ? { version: body.version } : {}) }
+}

package/src/speakable.ts

@@ -0,0 +1,35 @@
+/** 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
+    .replace(/```[\s\S]*?```/g, "\n(code omitted)\n")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/https?:\/\/\S+/g, "a link")
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/(\*\*|__)(.*?)\1/g, "$2")
+    .replace(/(^|[\s(])[*_]([^*_\n]+)[*_](?=[\s).,!?:;]|$)/g, "$1$2")
+    .split("\n")
+    .map((line) =>
+      line
+        .replace(/^\s*#{1,6}\s+(.*?)\s*$/, (_m, heading: string) => (/[.!?:]$/.test(heading) ? heading : `${heading}.`))
+        .replace(/^\s*(?:[-*+]|\d+[.)])\s+(.*)$/, "\u0000$1")
+        .trim(),
+    )
+    .filter(Boolean)
+
+  let spoken = ""
+  for (const line of lines) {
+    if (line.startsWith("\u0000")) {
+      const item = line.slice(1)
+      spoken += spoken && !/[.!?:]$/.test(spoken) ? `. ${item}` : ` ${item}`
+    } else spoken += ` ${line}`
+  }
+  spoken = spoken.replace(/\s+/g, " ").trim()
+  return cap(spoken, max)
+}
+
+function cap(text: string, max: number): string {
+  if (text.length <= max) return text
+  const cut = text.slice(0, max)
+  const space = cut.lastIndexOf(" ")
+  return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`
+}

package/src/spoke/client.ts

@@ -0,0 +1,272 @@
+// The spoke's single outbound WebSocket to the central server: hello/welcome handshake, request/
+// response correlation in both directions, and reconnect with jittered exponential backoff.
+import {
+  encode,
+  MAX_FRAME,
+  parseServerMessage,
+  PROTOCOL_VERSION,
+  type Hello,
+  type ResultFor,
+  type ServerRequest,
+  type SpokeMessage,
+  type SpokeRequest,
+  type Welcome,
+} from "../protocol"
+
+export type ConnectionState = "off" | "connecting" | "connected" | "revoked" | "error"
+
+export interface Backoff {
+  readonly minMs: number
+  readonly maxMs: number
+  readonly random?: () => number
+}
+
+/** Minimal WebSocket surface used here (Bun's WebSocket accepts `{ headers }` as a 2nd argument). */
+export interface SocketLike {
+  readonly readyState: number
+  onopen: ((ev: unknown) => void) | null
+  onmessage: ((ev: { data: unknown }) => void) | null
+  onclose: ((ev: { code?: number; reason?: string }) => void) | null
+  onerror: ((ev: unknown) => void) | null
+  send(data: string): void
+  close(code?: number, reason?: string): void
+}
+
+export interface ConnectionOptions {
+  readonly server: string
+  readonly token: string
+  /** Hello fields, computed per attempt so mode/directory are current. */
+  readonly hello: () => Omit<Hello, "t" | "v">
+  /** Executes a server request; a thrown error becomes `{ ok: false, error }`. */
+  readonly handle: (req: ServerRequest) => Promise<unknown>
+  readonly onWelcome?: (welcome: Welcome) => void
+  readonly onState?: (state: ConnectionState, error?: string) => void
+  readonly backoff?: Backoff
+  readonly requestTimeoutMs?: number
+  readonly socket?: (url: string, headers: Record<string, string>) => SocketLike
+}
+
+export function backoffDelay(attempt: number, backoff: Backoff): number {
+  const base = Math.min(backoff.maxMs, backoff.minMs * 2 ** Math.min(attempt, 30))
+  const random = (backoff.random ?? Math.random)()
+  return Math.round(base * (0.5 + 0.5 * random))
+}
+
+export function wsURL(server: string): string {
+  return `${server.replace(/\/+$/, "").replace(/^http/, "ws")}/spoke/ws`
+}
+
+const defaultSocket = (url: string, headers: Record<string, string>): SocketLike =>
+  new (WebSocket as unknown as new (url: string, options: { headers: Record<string, string> }) => SocketLike)(url, { headers })
+
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+
+interface Pending {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export class SpokeConnection {
+  state: ConnectionState = "off"
+  lastError?: string
+  publicURL?: string
+  machineID?: string
+
+  private socket?: SocketLike
+  private welcomed = false
+  private stopped = true
+  private attempt = 0
+  private retry?: ReturnType<typeof setTimeout>
+  private nextID = 0
+  private readonly pending = new Map<string, Pending>()
+  private readonly backoff: Backoff
+
+  constructor(private readonly options: ConnectionOptions) {
+    this.backoff = options.backoff ?? { minMs: 1000, maxMs: 60_000 }
+  }
+
+  start(): void {
+    if (!this.stopped) return
+    this.stopped = false
+    this.open()
+  }
+
+  stop(): void {
+    this.stopped = true
+    clearTimeout(this.retry)
+    this.drop(1000, "stop")
+    this.failPending("disconnected")
+    this.setState("off")
+  }
+
+  /** Reconnects at once (e.g. after a local hub was started) instead of waiting out the backoff. */
+  retryNow(): void {
+    if (this.stopped || this.state === "connected" || this.state === "revoked" || this.socket) return
+    clearTimeout(this.retry)
+    this.attempt = 0
+    this.open()
+  }
+
+  /** Sends a frame once the server has welcomed us. Returns false when it could not be sent. */
+  send(frame: SpokeMessage): boolean {
+    if (!this.socket || !this.welcomed || this.socket.readyState !== 1) return false
+    try {
+      let text = encode(frame)
+      if (text.length > MAX_FRAME) {
+        // The hub drops the connection on an oversize frame; answer a request with an error instead.
+        if (frame.t !== "res") return false
+        text = encode({ t: "res", id: frame.id, ok: false, error: `Result too large to send (${text.length} characters, limit ${MAX_FRAME})` })
+      }
+      this.socket.send(text)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  request<R extends SpokeRequest>(req: R): Promise<ResultFor[R["op"]]> {
+    const id = `s${++this.nextID}`
+    return new Promise((resolve, reject) => {
+      if (this.state !== "connected") return reject(new Error("Not connected to the hub"))
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error("The hub timed out"))
+      }, this.options.requestTimeoutMs ?? 15_000)
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer })
+      if (!this.send({ t: "req", id, req })) {
+        clearTimeout(timer)
+        this.pending.delete(id)
+        reject(new Error("Not connected to the hub"))
+      }
+    })
+  }
+
+  private open(): void {
+    if (this.stopped) return
+    this.setState(this.state === "error" ? "error" : "connecting")
+    let socket: SocketLike
+    try {
+      socket = (this.options.socket ?? defaultSocket)(wsURL(this.options.server), {
+        Authorization: `Bearer ${this.options.token}`,
+      })
+    } catch (cause) {
+      this.fail(message(cause))
+      return
+    }
+    this.socket = socket
+    this.welcomed = false
+    socket.onopen = () => {
+      try {
+        socket.send(encode({ t: "hello", v: PROTOCOL_VERSION, ...this.options.hello() }))
+      } catch (cause) {
+        this.lastError = message(cause)
+      }
+    }
+    socket.onmessage = (ev) => this.receive(ev.data)
+    socket.onerror = () => {
+      this.lastError = this.welcomed ? "Connection error" : "Could not connect to the hub"
+    }
+    socket.onclose = (ev) => {
+      if (this.socket !== socket) return
+      this.socket = undefined
+      const wasWelcomed = this.welcomed
+      this.welcomed = false
+      this.failPending("disconnected")
+      if (this.stopped || this.state === "revoked") return
+      this.fail(wasWelcomed ? `Connection closed${ev.reason ? `: ${ev.reason}` : ""}` : (this.lastError ?? "Could not connect"))
+    }
+  }
+
+  private receive(data: unknown): void {
+    const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? Buffer.from(data).toString("utf8") : String(data)
+    const frame = parseServerMessage(text)
+    if (!frame) return
+    switch (frame.t) {
+      case "welcome":
+        this.welcomed = true
+        this.attempt = 0
+        this.publicURL = frame.publicURL
+        this.machineID = frame.machineID
+        this.lastError = undefined
+        this.setState("connected")
+        try {
+          this.options.onWelcome?.(frame)
+        } catch (cause) {
+          console.error("[hub] welcome handler failed", cause)
+        }
+        return
+      case "bye":
+        if (frame.reason === "revoked") {
+          this.stopped = true
+          clearTimeout(this.retry)
+          this.lastError = "This machine was revoked on the hub"
+          this.setState("revoked")
+          this.drop(1000, "revoked")
+          this.failPending("revoked")
+        }
+        return
+      case "res": {
+        const pending = this.pending.get(frame.id)
+        if (!pending) return
+        this.pending.delete(frame.id)
+        clearTimeout(pending.timer)
+        if (frame.ok) pending.resolve(frame.result)
+        else pending.reject(new Error(frame.error ?? "Request failed"))
+        return
+      }
+      case "req":
+        void this.answer(frame.id, frame.req)
+        return
+    }
+  }
+
+  private async answer(id: string, req: ServerRequest): Promise<void> {
+    let reply: SpokeMessage
+    try {
+      reply = { t: "res", id, ok: true, result: await this.options.handle(req) }
+    } catch (cause) {
+      reply = { t: "res", id, ok: false, error: message(cause) }
+    }
+    this.send(reply)
+  }
+
+  private fail(error: string): void {
+    this.lastError = error
+    this.setState("error")
+    if (this.stopped) return
+    clearTimeout(this.retry)
+    this.retry = setTimeout(() => this.open(), backoffDelay(this.attempt++, this.backoff))
+  }
+
+  private drop(code: number, reason: string): void {
+    const socket = this.socket
+    this.socket = undefined
+    this.welcomed = false
+    if (!socket) return
+    socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null
+    try {
+      socket.close(code, reason)
+    } catch {
+      // already closed
+    }
+  }
+
+  private failPending(reason: string): void {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error(`Hub ${reason}`))
+      this.pending.delete(id)
+    }
+  }
+
+  private setState(state: ConnectionState): void {
+    if (state === this.state) return
+    this.state = state
+    try {
+      this.options.onState?.(state, this.lastError)
+    } catch {
+      // observers must not break the connection
+    }
+  }
+}

package/src/spoke/conversation.ts

@@ -0,0 +1,93 @@
+// Conversation mode: the session's main agent becomes a voice orchestrator that answers in short
+// spoken sentences and hands real work to background subagents. The plugin registers it as the
+// primary agent "voice"; the delegate agent comes from the per-machine config and is added per
+// request, so changing it needs no agent reload.
+
+export const VOICE_AGENT = "voice"
+
+/** metadata.source of the prompts the hub sends. opencode-hub (0.5) wrote "opencode-hub", opencode-voice (<= 0.4) "opencode-voice". */
+export const PROMPT_SOURCE = "hub"
+const PROMPT_SOURCES: readonly unknown[] = [PROMPT_SOURCE, "opencode-hub", "opencode-voice"]
+/** True for prompt metadata written by the hub, under either name. */
+export const isHubPrompt = (metadata: unknown): boolean =>
+  typeof metadata === "object" && metadata !== null && PROMPT_SOURCES.includes((metadata as { source?: unknown }).source)
+
+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:
+- 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.
+
+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.
+- Answer quick questions directly.
+- Always say something before you start working, so the user hears that you got it. Write your spoken acknowledgement first, then call tools: for example "Got it, I'm starting a subagent to fix the failing test." The user can see tool activity on their phone, but they need to hear that you're on it.
+
+How to work:
+- Answer directly, or make at most two quick, low-risk tool calls yourself. Brain reads or writes, status checks and simple lookups belong on this direct path. If the work grows beyond two calls, acknowledge that and delegate it.
+- Delegate multi-step work. A routine worker handles deterministic MCP work, short research and routine checks on your fast model. A complex worker handles coding, debugging, architecture, risky operations or work requiring substantial judgment on the full work model named below.
+- Call the subagent tool with the delegate agent named in the note below (use "general" if none is named), background: true, and a complete, self-contained prompt with the goal, relevant context, constraints, and what to report back. Require that the worker's final assistant message must contain only one or two plain-spoken sentences that can be read directly to the user. Put technical detail in tool output or progress before that final message.
+- Never run a subagent in the foreground (always pass background: true): a foreground subagent blocks the conversation and the user cannot talk to you until it ends.
+- New user messages can arrive while work is running; treat them as steering. For a correction, status request or related follow-up on the same active task, continue its subagent with the existing sessionID. Start a fresh worker after that task completes or for an unrelated task.
+- When the user asks how it's going, give a one-sentence progress update from what you know.
+- Successful worker results are spoken directly. Do not repeat a completed worker's result. Speak again only if the worker failed, the user must decide something, or a warning or next step genuinely needs explanation.
+- If the user says stop, cancel or never mind, stop: start no new work and confirm briefly.`
+
+export function delegateNote(subagent: string): string {
+  return `Delegate agent on this machine: when you call the subagent tool, use agent "${subagent}" and always set background: true. Require its final assistant message to contain only one or two plain-spoken sentences for direct speech.`
+}
+
+/**
+ * In conversation mode the session talks on a fast model. Routine workers inherit it; the voice agent
+ * passes the remembered work model explicitly only for complex work.
+ */
+export function workModelNote(workModel: string): string {
+  return `For a routine worker, omit model so it inherits your fast model. For a complex worker, set model: "${workModel}". Complex means coding, debugging, architecture, risky operations or work requiring substantial judgment.`
+}
+
+/** System parts the context hook adds: the delegate note for the voice agent, the whole prompt when conversation mode runs on another agent. */
+export function orchestratorParts(input: { agent: string; conversation: boolean; subagent: string; workModel?: string }): string[] {
+  const notes = [delegateNote(input.subagent), ...(input.workModel ? [workModelNote(input.workModel)] : [])]
+  if (input.agent === VOICE_AGENT) return notes
+  if (input.conversation) return [ORCHESTRATOR_PROMPT, ...notes]
+  return []
+}
+
+interface AgentLike {
+  name: string
+  description?: string
+  system?: string
+  mode: "subagent" | "primary" | "all"
+  hidden: boolean
+  permissions: unknown[]
+}
+
+export interface AgentEditorLike {
+  get(id: string): AgentLike | undefined
+  update(id: string, update: (agent: AgentLike) => void): void
+}
+
+const DEFAULT_AGENT = "build"
+
+/**
+ * Adds the "voice" agent (the editor's update() upserts). It inherits the default agent's
+ * permissions so the user's rules still apply. A "voice" agent the user defined is left alone.
+ */
+export function defineVoiceAgent(editor: AgentEditorLike): void {
+  if (editor.get(VOICE_AGENT)) return
+  const base = editor.get(DEFAULT_AGENT)
+  editor.update(VOICE_AGENT, (agent) => {
+    agent.name = "Voice"
+    agent.description = VOICE_AGENT_DESCRIPTION
+    agent.mode = "primary"
+    agent.hidden = false
+    agent.system = ORCHESTRATOR_PROMPT
+    if (base) agent.permissions = structuredClone(base.permissions)
+  })
+}