@huynle/hub 0.0.0-stage → 0.6.0

package/src/status.ts

@@ -0,0 +1,232 @@
+// Live status of a voice session and the subagent sessions it spawns, built from OpenCode events.
+
+export type SessionState = "idle" | "working" | "blocked" | "error"
+
+export interface Blocker {
+  readonly kind: "permission" | "form"
+  readonly id: string
+  readonly summary: string
+  /** form: asked by the agent's question tool (metadata.kind "question"). */
+  readonly question?: true
+  /** form: its fields, bounded, so a phone can render and answer it. */
+  readonly fields?: readonly FormFieldSpec[]
+}
+
+export interface FormOptionSpec {
+  readonly value: string
+  readonly label: string
+  readonly description?: string
+}
+
+/** One field of an OpenCode form (FormField), with only what a client needs to render and validate it. */
+export interface FormFieldSpec {
+  readonly key: string
+  readonly type: "string" | "number" | "integer" | "boolean" | "multiselect" | "external"
+  readonly title?: string
+  readonly description?: string
+  readonly required?: boolean
+  readonly options?: readonly FormOptionSpec[]
+  /** string/multiselect with options: free text allowed besides the options. */
+  readonly custom?: boolean
+  readonly placeholder?: string
+  readonly default?: string | number | boolean | readonly string[]
+  readonly minimum?: number
+  readonly maximum?: number
+  readonly minLength?: number
+  readonly maxLength?: number
+  readonly minItems?: number
+  readonly maxItems?: number
+  readonly format?: string
+  readonly pattern?: string
+  /** external: a link the user follows. */
+  readonly url?: string
+  /** Shown only when these conditions on other fields hold. */
+  readonly when?: ReadonlyArray<{ readonly key: string; readonly op: "eq" | "neq"; readonly value: string | number | boolean }>
+}
+
+export const FORM_MAX_FIELDS = 20
+export const FORM_MAX_OPTIONS = 50
+const FORM_TEXT_MAX = 2000
+const FORM_LABEL_MAX = 300
+const FIELD_TYPES = new Set<FormFieldSpec["type"]>(["string", "number", "integer", "boolean", "multiselect", "external"])
+
+const text = (v: unknown, max: number) => (typeof v === "string" && v ? v.slice(0, max) : undefined)
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
+
+function optionSpec(raw: any): FormOptionSpec | undefined {
+  const value = text(raw?.value, FORM_LABEL_MAX)
+  if (value === undefined) return undefined
+  const description = text(raw.description, FORM_TEXT_MAX)
+  return { value, label: text(raw.label, FORM_LABEL_MAX) ?? value, ...(description ? { description } : {}) }
+}
+
+/** The renderable part of an OpenCode form field; undefined for fields a client cannot show. */
+export function formFieldSpec(raw: any): FormFieldSpec | undefined {
+  const key = text(raw?.key, FORM_LABEL_MAX)
+  if (!key || !FIELD_TYPES.has(raw.type)) return undefined
+  const out: Record<string, unknown> = { key, type: raw.type }
+  for (const name of ["title", "placeholder", "format", "pattern"] as const) if (text(raw[name], FORM_LABEL_MAX)) out[name] = text(raw[name], FORM_LABEL_MAX)
+  if (text(raw.description, FORM_TEXT_MAX)) out.description = text(raw.description, FORM_TEXT_MAX)
+  if (raw.type === "external") {
+    const url = text(raw.url, FORM_TEXT_MAX)
+    if (!url || !/^https?:\/\//.test(url)) return undefined
+    out.url = url
+  }
+  if (raw.required === true) out.required = true
+  if (raw.custom === true) out.custom = true
+  if (Array.isArray(raw.options)) {
+    const options = raw.options.slice(0, FORM_MAX_OPTIONS).map(optionSpec).filter(Boolean)
+    if (options.length) out.options = options
+  }
+  for (const name of ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"] as const) if (num(raw[name]) !== undefined) out[name] = raw[name]
+  const d = raw.default
+  if (typeof d === "boolean" || num(d) !== undefined) out.default = d
+  else if (typeof d === "string") out.default = d.slice(0, FORM_TEXT_MAX)
+  else if (Array.isArray(d)) out.default = d.filter((x: unknown) => typeof x === "string").slice(0, FORM_MAX_OPTIONS)
+  if (Array.isArray(raw.when)) {
+    const when = raw.when
+      .filter((w: any) => typeof w?.key === "string" && (w.op === "eq" || w.op === "neq") && ["string", "number", "boolean"].includes(typeof w.value))
+      .slice(0, 10)
+      .map((w: any) => ({ key: w.key, op: w.op, value: w.value }))
+    if (when.length) out.when = when
+  }
+  return out as unknown as FormFieldSpec
+}
+
+/** A form.created event's form as a blocker. */
+function formBlocker(form: any): Blocker {
+  const fields = Array.isArray(form.fields) ? form.fields.map(formFieldSpec).filter(Boolean).slice(0, FORM_MAX_FIELDS) : []
+  return {
+    kind: "form",
+    id: form.id,
+    summary: typeof form.title === "string" && form.title ? form.title.slice(0, FORM_LABEL_MAX) : "question",
+    ...(form.metadata?.kind === "question" ? { question: true as const } : {}),
+    ...(fields.length ? { fields } : {}),
+  }
+}
+
+export interface SessionStatus {
+  readonly id: string
+  readonly parentID?: string
+  readonly title: string
+  readonly state: SessionState
+  readonly detail?: string
+  readonly blockers: ReadonlyArray<Blocker>
+}
+
+interface Entry {
+  id: string
+  parentID?: string
+  title: string
+  running: boolean
+  error?: string
+  blockers: Blocker[]
+}
+
+interface EventLike {
+  readonly type: string
+  readonly data?: unknown
+}
+
+export class StatusBoard {
+  private readonly sessions = new Map<string, Entry>()
+
+  constructor(rootID: string, title: string) {
+    this.sessions.set(rootID, { id: rootID, title, running: false, blockers: [] })
+  }
+
+  /** Applies an event. Returns true when the visible status changed. */
+  observe(event: EventLike): boolean {
+    const data = (event.data ?? {}) as Record<string, any>
+    switch (event.type) {
+      case "session.created": {
+        if (typeof data.parentID !== "string" || !this.sessions.has(data.parentID)) return false
+        this.sessions.set(data.sessionID, {
+          id: data.sessionID,
+          parentID: data.parentID,
+          title: data.title ?? data.agent ?? data.slug ?? "subagent",
+          running: false,
+          blockers: [],
+        })
+        return true
+      }
+      case "session.renamed":
+        return this.update(data.sessionID, (entry) => (entry.title = data.title))
+      case "session.deleted":
+        return this.sessions.delete(data.sessionID)
+      case "session.execution.started":
+        return this.update(data.sessionID, (entry) => {
+          entry.running = true
+          entry.error = undefined
+        })
+      case "session.execution.succeeded":
+      case "session.execution.interrupted":
+        return this.update(data.sessionID, (entry) => (entry.running = false))
+      case "session.execution.failed":
+        return this.update(data.sessionID, (entry) => {
+          entry.running = false
+          entry.error = String(data.error?.message ?? "failed")
+        })
+      case "permission.asked":
+        return this.update(data.sessionID, (entry) => {
+          if (entry.blockers.some((b) => b.id === data.id)) return
+          entry.blockers.push({
+            kind: "permission",
+            id: data.id,
+            summary: [data.action, (data.resources ?? []).join(", ")].filter(Boolean).join(": "),
+          })
+        })
+      case "permission.replied":
+        return this.unblock(data.sessionID, data.requestID)
+      case "form.created":
+        return this.update(data.form?.sessionID, (entry) => {
+          if (entry.blockers.some((b) => b.id === data.form.id)) return
+          entry.blockers.push(formBlocker(data.form))
+        })
+      case "form.replied":
+      case "form.cancelled":
+        return this.unblock(data.sessionID, data.id)
+      default:
+        return false
+    }
+  }
+
+  get(id: string): SessionStatus | undefined {
+    const entry = this.sessions.get(id)
+    return entry && view(entry)
+  }
+
+  ids(): string[] {
+    return [...this.sessions.keys()]
+  }
+
+  snapshot(): { sessions: SessionStatus[] } {
+    return { sessions: [...this.sessions.values()].map(view) }
+  }
+
+  private update(id: unknown, change: (entry: Entry) => void): boolean {
+    const entry = typeof id === "string" ? this.sessions.get(id) : undefined
+    if (!entry) return false
+    change(entry)
+    return true
+  }
+
+  private unblock(sessionID: unknown, blockerID: unknown): boolean {
+    return this.update(sessionID, (entry) => {
+      entry.blockers = entry.blockers.filter((blocker) => blocker.id !== blockerID)
+    })
+  }
+}
+
+function view(entry: Entry): SessionStatus {
+  const state: SessionState =
+    entry.blockers.length > 0 ? "blocked" : entry.error ? "error" : entry.running ? "working" : "idle"
+  return {
+    id: entry.id,
+    ...(entry.parentID ? { parentID: entry.parentID } : {}),
+    title: entry.title,
+    state,
+    ...(entry.error && state === "error" ? { detail: entry.error } : {}),
+    blockers: entry.blockers.map((blocker) => structuredClone(blocker)),
+  }
+}

package/src/tui-commands.ts

@@ -0,0 +1,53 @@
+// Hub's TUI slash commands, one entry per feature. /hub configures this harness's connection to the hub;
+// every other entry is a feature (/voice today). To add a feature, write its flow in its own module
+// (like src/voice-command.ts) and add one HubCommand to the list src/tui.ts passes to hubCommands().
+
+/** The palette group of every Hub command. */
+export const COMMAND_GROUP = "Hub"
+/** Command IDs are `hub.<id>`, the plugin's namespace. */
+export const COMMAND_PREFIX = "hub."
+
+export interface HubCommand {
+  /** Unique within Hub; the command ID is `hub.<id>`. */
+  readonly id: string
+  /** The slash command, without the "/". */
+  readonly slash: string
+  /** Shown in the command palette after "Hub: ". */
+  readonly title: string
+  readonly run: () => Promise<unknown>
+}
+
+/** The shape OpenCode's keymap layer takes for one command. */
+export interface KeymapCommand {
+  readonly id: string
+  readonly title: string
+  readonly group: string
+  readonly palette: true
+  readonly slash: { readonly name: string }
+  readonly run: () => void
+}
+
+/**
+ * Keymap commands for the given features. Throws on a duplicate ID or slash name (a programming error).
+ * A failing run is reported through `onError` (a toast), never thrown into the TUI.
+ */
+export function hubCommands(features: readonly HubCommand[], onError: (cause: unknown) => void): KeymapCommand[] {
+  const ids = new Set<string>()
+  const names = new Set<string>()
+  return features.map((feature) => {
+    if (ids.has(feature.id)) throw new Error(`duplicate Hub command id "${feature.id}"`)
+    if (names.has(feature.slash)) throw new Error(`duplicate Hub slash command "/${feature.slash}"`)
+    ids.add(feature.id)
+    names.add(feature.slash)
+    return {
+      id: `${COMMAND_PREFIX}${feature.id}`,
+      title: `${COMMAND_GROUP}: ${feature.title}`,
+      group: COMMAND_GROUP,
+      palette: true,
+      slash: { name: feature.slash },
+      run: () => {
+        void feature.run().catch(onError)
+      },
+    }
+  })
+}

package/src/tui-forms.ts

@@ -0,0 +1,77 @@
+// TUI side of form (question) replies from the hub: a standalone server started by this TUI cannot call its
+// own HTTP API (its password stays with the TUI), so its spoke queues the replies and the TUI long-polls
+// RPC hub.formActions and carries them out with its client. See Spoke.formActions.
+
+export type RelayedFormAction =
+  | { readonly sessionID: string; readonly formID: string; readonly answer: Record<string, unknown> }
+  | { readonly sessionID: string; readonly formID: string; readonly cancel: true }
+
+export interface FormRelayOptions {
+  /** RPC hub.formActions: waits up to `waitMs` for queued replies. */
+  readonly poll: (waitMs: number) => Promise<{ actions?: readonly unknown[] }>
+  /** Carries one out (client.session.form.reply / cancel). Errors are logged and skipped. */
+  readonly apply: (action: RelayedFormAction) => Promise<unknown>
+  readonly waitMs?: number
+  /** Pause after a failed poll (no spoke, older server, disconnected). */
+  readonly retryMs?: number
+}
+
+function action(raw: unknown): RelayedFormAction | undefined {
+  const a = raw as Record<string, unknown> | null
+  if (!a || typeof a.sessionID !== "string" || typeof a.formID !== "string") return undefined
+  if (a.cancel === true) return { sessionID: a.sessionID, formID: a.formID, cancel: true }
+  if (typeof a.answer === "object" && a.answer !== null && !Array.isArray(a.answer)) {
+    return { sessionID: a.sessionID, formID: a.formID, answer: a.answer as Record<string, unknown> }
+  }
+  return undefined
+}
+
+export class FormRelay {
+  private running = false
+  private wake?: () => void
+
+  constructor(private readonly options: FormRelayOptions) {}
+
+  /** Polls until stop(); resolves when stopped. */
+  async start(): Promise<void> {
+    if (this.running) return
+    this.running = true
+    while (this.running) {
+      let actions: readonly unknown[] = []
+      try {
+        actions = (await this.options.poll(this.options.waitMs ?? 20_000)).actions ?? []
+      } catch {
+        await this.sleep(this.options.retryMs ?? 10_000)
+        continue
+      }
+      for (const raw of actions) {
+        const next = action(raw)
+        if (!next) continue
+        try {
+          await this.options.apply(next)
+        } catch (cause) {
+          console.error("[hub] could not answer a question from the hub", cause instanceof Error ? cause.message : cause)
+        }
+      }
+    }
+  }
+
+  stop(): void {
+    this.running = false
+    this.wake?.()
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(done, ms)
+      ;(timer as { unref?: () => void }).unref?.()
+      const self = this
+      function done() {
+        clearTimeout(timer)
+        self.wake = undefined
+        resolve()
+      }
+      this.wake = done
+    })
+  }
+}

package/src/tui-presence.ts

@@ -0,0 +1,75 @@
+// TUI presence: the TUI tells its server-side spoke which sessions it shows (the current route's root
+// session and its open tabs) over RPC voice.presence, on change (the route is polled every 2 s) and every
+// 15 s, so the phone can list them as open. See docs/session-view.md.
+
+export const PRESENCE_POLL_MS = 2000
+export const PRESENCE_HEARTBEAT_MS = 15_000
+
+/** The root of the session the route shows, plus the open tabs (root sessions), deduplicated. */
+export function shownSessions(input: {
+  route: { type: string; sessionID?: string }
+  root: (sessionID: string) => string
+  tabs?: readonly string[]
+}): string[] {
+  const out = new Set<string>()
+  const current = input.route.type === "session" ? input.route.sessionID : undefined
+  if (current) {
+    let root = current
+    try {
+      root = input.root(current) || current
+    } catch {
+      // not synced yet: the session itself
+    }
+    out.add(root)
+  }
+  for (const id of input.tabs ?? []) if (id) out.add(id)
+  return [...out]
+}
+
+export interface PresenceReporterOptions {
+  /** The sessions shown right now. */
+  readonly read: () => readonly string[]
+  /** Reports them (errors are ignored: the next tick retries). */
+  readonly send: (sessionIDs: readonly string[]) => Promise<unknown>
+  readonly pollMs?: number
+  readonly heartbeatMs?: number
+}
+
+export class PresenceReporter {
+  private timers: Array<ReturnType<typeof setInterval>> = []
+  private last?: string
+
+  constructor(private readonly options: PresenceReporterOptions) {}
+
+  start(): void {
+    if (this.timers.length) return
+    this.tick(true)
+    this.every(this.options.pollMs ?? PRESENCE_POLL_MS, () => this.tick(false))
+    this.every(this.options.heartbeatMs ?? PRESENCE_HEARTBEAT_MS, () => this.tick(true))
+  }
+
+  stop(): void {
+    for (const timer of this.timers) clearInterval(timer)
+    this.timers = []
+  }
+
+  /** Reads now and reports when changed (or always, for the heartbeat). */
+  tick(always = false): void {
+    let ids: readonly string[]
+    try {
+      ids = this.options.read()
+    } catch {
+      return
+    }
+    const key = [...ids].sort().join(" ")
+    if (!always && key === this.last) return
+    this.last = key
+    this.options.send(ids).catch(() => {})
+  }
+
+  private every(ms: number, run: () => void): void {
+    const timer = setInterval(run, ms)
+    ;(timer as { unref?: () => void }).unref?.()
+    this.timers.push(timer)
+  }
+}