herm-tui 1.0.0-dev.1

package/src/utils/gateway-client.ts

@@ -0,0 +1,253 @@
+// Stdio JSON-RPC 2.0 client for tui_gateway. Spawns the gateway as a child
+// process and speaks newline-delimited JSON on stdin/stdout.
+
+import { EventEmitter } from "events"
+import { homedir } from "os"
+import { resolve, delimiter } from "path"
+import { existsSync } from "fs"
+import type { GatewayEvent } from "./gateway-types"
+
+const LOG_MAX = 200
+const LOG_PREVIEW = 240
+const STARTUP_MS = 15_000
+const REQUEST_MS = 120_000
+
+/** Locate the hermes-agent source tree (gateway + hermes_cli live here).
+ *  Default: ~/.hermes/hermes-agent (where `hermes update` installs it).
+ *  Override with HERMES_AGENT_ROOT for dev clones / exotic layouts. */
+export function hermesAgentRoot(): string {
+  if (process.env.HERMES_AGENT_ROOT) return process.env.HERMES_AGENT_ROOT
+  const home = process.env.HOME || homedir()
+  return `${home}/.hermes/hermes-agent`
+}
+
+type Pending = {
+  resolve: (v: unknown) => void
+  reject: (e: Error) => void
+}
+
+function python(root: string): string {
+  const env = process.env.HERMES_PYTHON?.trim()
+  if (env) return env
+
+  const venv = process.env.VIRTUAL_ENV?.trim()
+  const paths = [
+    venv && resolve(venv, "bin/python"),
+    resolve(root, "venv/bin/python"),
+    resolve(root, "venv/bin/python3"),
+    resolve(root, ".venv/bin/python"),
+    resolve(root, ".venv/bin/python3"),
+  ]
+  return paths.find(p => p && existsSync(p)) || "python3"
+}
+
+function asEvent(v: unknown): GatewayEvent | null {
+  if (v && typeof v === "object" && !Array.isArray(v) && typeof (v as { type?: unknown }).type === "string")
+    return v as GatewayEvent
+  return null
+}
+
+// Read lines from a ReadableStream (Bun subprocess stdout/stderr)
+async function lines(stream: ReadableStream<Uint8Array>, cb: (line: string) => void) {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buf = ""
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buf += decoder.decode(value, { stream: true })
+      const parts = buf.split("\n")
+      buf = parts.pop() || ""
+      for (const line of parts) {
+        if (line) cb(line)
+      }
+    }
+    // Flush remaining
+    if (buf.trim()) cb(buf)
+  } catch {
+    // Stream closed
+  }
+}
+
+export class GatewayClient extends EventEmitter {
+  private proc: ReturnType<typeof Bun.spawn> | null = null
+  private id = 0
+  private logs: string[] = []
+  private pending = new Map<string, Pending>()
+  private buf: GatewayEvent[] = []
+  private exit: number | null | undefined
+  private ok = false
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private sub = false
+
+  private root(): string { return hermesAgentRoot() }
+
+  private push(ev: GatewayEvent) {
+    if (ev.type === "gateway.ready") {
+      this.ok = true
+      if (this.timer) { clearTimeout(this.timer); this.timer = null }
+    }
+    if (this.sub) return void this.emit("event", ev)
+    this.buf.push(ev)
+  }
+
+  private log(line: string) {
+    if (this.logs.push(line) > LOG_MAX) this.logs.splice(0, this.logs.length - LOG_MAX)
+  }
+
+  private dispatch(msg: Record<string, unknown>) {
+    const id = msg.id as string | undefined
+    const p = id ? this.pending.get(id) : undefined
+
+    if (p) {
+      this.pending.delete(id!)
+      if (msg.error) {
+        const err = msg.error as { message?: unknown }
+        p.reject(new Error(typeof err?.message === "string" ? err.message : "request failed"))
+      } else {
+        p.resolve(msg.result)
+      }
+      return
+    }
+
+    if (msg.method === "event") {
+      const ev = asEvent(msg.params)
+      if (ev) this.push(ev)
+    }
+  }
+
+  private fail(err: Error) {
+    for (const p of this.pending.values()) p.reject(err)
+    this.pending.clear()
+  }
+
+  start() {
+    const root = this.root()
+    const bin = python(root)
+    const cwd = process.env.HERMES_CWD || root
+    const env = { ...process.env } as Record<string, string>
+    const pp = env.PYTHONPATH?.trim()
+    env.PYTHONPATH = pp ? `${root}${delimiter}${pp}` : root
+
+    // Reset state
+    this.ok = false
+    this.buf = []
+    this.exit = undefined
+
+    if (this.proc) {
+      try { this.proc.kill() } catch {}
+    }
+
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = setTimeout(() => {
+      if (this.ok) return
+      this.log(`[startup] timed out (python=${bin}, cwd=${cwd})`)
+      this.push({ type: "gateway.start_timeout", payload: { cwd, python: bin } })
+    }, STARTUP_MS)
+
+    const proc = Bun.spawn(["sh", "-c", `exec ${bin} -m tui_gateway.entry`], {
+      cwd,
+      env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    this.proc = proc
+
+    // Read stdout lines — Bun returns ReadableStream
+    if (this.proc.stdout) {
+      lines(this.proc.stdout as ReadableStream<Uint8Array>, raw => {
+        try {
+          this.dispatch(JSON.parse(raw))
+        } catch {
+          const preview = raw.trim().slice(0, LOG_PREVIEW) || "(empty)"
+          this.log(`[protocol] malformed: ${preview}`)
+          this.push({ type: "gateway.protocol_error", payload: { preview } })
+        }
+      })
+    }
+
+    // Read stderr lines
+    if (this.proc.stderr) {
+      lines(this.proc.stderr as ReadableStream<Uint8Array>, raw => {
+        const line = raw.trim()
+        if (!line) return
+        this.log(line)
+        this.push({ type: "gateway.stderr", payload: { line } })
+      })
+    }
+
+    // Handle exit — guard against a superseded proc (restart kills the
+    // old one, whose exit handler must not touch the new proc's state).
+    proc.exited.then(code => {
+      if (this.proc !== proc) return
+      if (this.timer) { clearTimeout(this.timer); this.timer = null }
+      this.fail(new Error(`gateway exited${code === null ? "" : ` (${code})`}`))
+      if (this.sub) this.emit("exit", code)
+      else this.exit = code
+    })
+  }
+
+  drain() {
+    if (this.sub) return
+    this.sub = true
+    for (const ev of this.buf.splice(0)) this.emit("event", ev)
+    if (this.exit !== undefined) {
+      const code = this.exit
+      this.exit = undefined
+      this.emit("exit", code)
+    }
+  }
+
+  tail(n = 20): string {
+    return this.logs.slice(-Math.max(1, n)).join("\n")
+  }
+
+  private sid = ""
+
+  /** Set the active session id; auto-injected into subsequent requests. */
+  setSession(sid: string) {
+    this.sid = sid
+  }
+
+  request<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    if (!this.proc || this.proc.exitCode !== null) this.start()
+
+    const stdin = this.proc?.stdin
+    if (!stdin || typeof stdin === "number") return Promise.reject(new Error("gateway not running"))
+
+    const rid = `r${++this.id}`
+    const writer = stdin as { write(data: string | Uint8Array): number }
+    const merged = this.sid && params.session_id === undefined
+      ? { session_id: this.sid, ...params }
+      : params
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        if (this.pending.delete(rid)) reject(new Error(`timeout: ${method}`))
+      }, REQUEST_MS)
+
+      this.pending.set(rid, {
+        reject: e => { clearTimeout(timeout); reject(e) },
+        resolve: v => { clearTimeout(timeout); resolve(v as T) },
+      })
+
+      try {
+        writer.write(JSON.stringify({ jsonrpc: "2.0", id: rid, method, params: merged }) + "\n")
+      } catch (e) {
+        clearTimeout(timeout)
+        this.pending.delete(rid)
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+  }
+
+  kill() {
+    this.proc?.kill()
+  }
+
+  get ready(): boolean {
+    return this.ok
+  }
+}

package/src/utils/gateway-types.ts

@@ -0,0 +1,282 @@
+// Typed events and RPC responses for the tui_gateway JSON-RPC protocol.
+
+import type { Usage } from "../types/message"
+
+// ── Events (server → client) ────────────────────────────────────────
+
+export type GatewayEvent =
+  | { type: "gateway.ready"; payload?: { skin?: GatewaySkin } }
+  | { type: "gateway.stderr"; payload: { line: string } }
+  | { type: "gateway.start_timeout"; payload?: { cwd?: string; python?: string } }
+  | { type: "gateway.protocol_error"; payload?: { preview?: string } }
+  | { type: "session.info"; payload: SessionInfo }
+  | { type: "skin.changed"; payload?: GatewaySkin }
+  | { type: "message.start"; payload?: undefined }
+  | { type: "message.delta"; payload?: { text?: string; rendered?: string } }
+  | { type: "message.complete"; payload?: { text?: string | null; rendered?: string; reasoning?: string; status?: "complete" | "error" | "interrupted"; usage?: Usage } }
+  | { type: "thinking.delta"; payload?: { text?: string } }
+  | { type: "reasoning.delta"; payload?: { text?: string } }
+  | { type: "reasoning.available"; payload?: { text?: string } }
+  | { type: "status.update"; payload?: { text?: string; kind?: string } }
+  | { type: "tool.start"; payload: { tool_id: string; name?: string; context?: string } }
+  | { type: "tool.progress"; payload: { name?: string; preview?: string } }
+  | { type: "tool.generating"; payload: { name?: string } }
+  | { type: "tool.complete"; payload: { tool_id: string; name?: string; summary?: string; error?: string; inline_diff?: string } }
+  | { type: "clarify.request"; payload: { request_id: string; question: string; choices: string[] | null } }
+  | { type: "approval.request"; payload: { command: string; description: string } }
+  | { type: "sudo.request"; payload: { request_id: string } }
+  | { type: "secret.request"; payload: { request_id: string; prompt: string; env_var: string } }
+  | { type: "background.complete"; payload: { task_id: string; text: string } }
+  | { type: "review.summary"; payload?: { text?: string } }
+  | { type: "btw.complete"; payload: { text: string } }
+  | { type: "browser.progress"; payload?: { message?: string; level?: "info" | "error" } }
+  | { type: "subagent.start"; payload: SubagentPayload }
+  | { type: "subagent.thinking"; payload: SubagentPayload }
+  | { type: "subagent.tool"; payload: SubagentPayload }
+  | { type: "subagent.progress"; payload: SubagentPayload }
+  | { type: "subagent.complete"; payload: SubagentPayload }
+  | { type: "error"; payload?: { message?: string } }
+
+export type SubagentPayload = {
+  task_index: number
+  goal: string
+  task_count?: number
+  status?: "running" | "completed" | "failed" | "interrupted"
+  text?: string
+  tool_name?: string
+  tool_preview?: string
+  summary?: string
+  duration_seconds?: number
+  // Spawn-tree identity (upstream delegate_tool threads these through
+  // every subagent.* event). All optional — absence falls back to flat
+  // task_index keying.
+  subagent_id?: string
+  parent_id?: string
+  depth?: number
+  model?: string
+  tool_count?: number
+  toolsets?: string[]
+  // Rollups on subagent.complete
+  input_tokens?: number
+  output_tokens?: number
+  reasoning_tokens?: number
+  api_calls?: number
+  cost_usd?: number
+  files_read?: string[]
+  files_written?: string[]
+  output_tail?: Array<{ tool: string; preview: string; is_error?: boolean }>
+}
+
+// delegation.status response — list_active_subagents() snapshot plus
+// scheduler flags. Records are a copy of the live registry minus the
+// agent handle.
+export type DelegationRecord = {
+  subagent_id: string
+  parent_id?: string | null
+  depth: number
+  goal: string
+  model?: string
+  started_at?: number
+  tool_count?: number
+  status?: string
+}
+
+export type DelegationStatus = {
+  active: DelegationRecord[]
+  paused: boolean
+  max_spawn_depth: number
+  max_concurrent_children: number
+}
+
+// spawn_tree.list index entries + spawn_tree.load payload
+export type SpawnTreeEntry = {
+  path: string
+  session_id: string
+  label: string
+  count: number
+  started_at?: number | null
+  finished_at: number
+}
+
+export type SpawnTreeSnapshot = {
+  session_id?: string
+  label?: string
+  started_at?: number | null
+  finished_at?: number
+  subagents: SpawnSubagent[]
+}
+
+// Persisted per-subagent record — the shape we save, and the shape
+// spawn_tree.load round-trips. A completed SubagentPayload superset.
+export type SpawnSubagent = {
+  subagent_id: string
+  parent_id?: string | null
+  depth: number
+  goal: string
+  model?: string
+  started_at: number
+  finished_at?: number
+  tool_count: number
+  status: "running" | "completed" | "failed" | "interrupted"
+  input_tokens?: number
+  output_tokens?: number
+  cost_usd?: number
+  trail?: Array<{ name: string; preview?: string }>
+}
+
+export type GatewaySkin = {
+  name?: string
+  colors?: Record<string, string>
+  branding?: Record<string, string>
+  banner_hero?: string
+  banner_logo?: string
+  tool_prefix?: string
+  help_header?: string
+}
+
+export type McpServer = {
+  name: string
+  transport: string
+  tools: number
+  connected: boolean
+  error?: string
+}
+
+export type SessionInfo = {
+  model?: string
+  cwd?: string
+  session_id?: string
+  tools?: Record<string, string[]>
+  skills?: Record<string, string[]>
+  version?: string
+  /**
+   * Wire usage payload for the current session. Server builds this via
+   * `_get_usage(agent)` (tui_gateway/server.py:826), which extends the
+   * base Usage with ctx/compression fields when a ContextCompressor is
+   * attached — so `compressions`/`context_used`/`context_max`/
+   * `context_percent` may be present. Intersection type keeps both
+   * shapes satisfied.
+   */
+  usage?: Usage & {
+    context_used?: number
+    context_max?: number
+    context_percent?: number
+    compressions?: number
+  }
+  context_max?: number
+  context_used?: number
+  credential_warning?: string
+  mcp_servers?: McpServer[]
+  /** hermes-agent version string (e.g. "1.14.2-dev+abc123") */
+  release_date?: string
+  /** commits behind origin/main; null = unknown, 0 = up to date */
+  update_behind?: number | null
+  /** platform-appropriate update invocation */
+  update_command?: string
+}
+
+// ── RPC responses ───────────────────────────────────────────────────
+
+export type SessionCreateResponse = {
+  session_id: string
+  info?: SessionInfo & { credential_warning?: string }
+}
+
+export type SessionResumeResponse = {
+  session_id: string
+  resumed?: string
+  messages: TranscriptMessage[]
+  message_count?: number
+  info?: SessionInfo
+}
+
+export type SessionListItem = {
+  id: string
+  title: string
+  preview: string
+  message_count: number
+  started_at: number
+  source?: string
+}
+
+export type SessionListResponse = {
+  sessions?: SessionListItem[]
+}
+
+export type SessionUsageResponse = {
+  model?: string
+  calls?: number
+  input?: number
+  output?: number
+  total?: number
+  cache_read?: number
+  cache_write?: number
+  cost_usd?: number
+  cost_status?: "estimated" | "exact"
+  context_used?: number
+  context_max?: number
+  context_percent?: number
+  compressions?: number
+}
+
+/** Content part inside a multimodal user turn — upstream stores the raw
+ *  OpenAI content list for native-mode image routing. We only care about
+ *  flattening the text fragments back into a string for render. */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string } }
+  | { type: string }
+
+export type TranscriptMessage = {
+  role: "user" | "assistant" | "system" | "tool"
+  /** Either a plain string (text-mode, assistant, system) or a list of
+   *  OpenAI content parts (native-mode user turns with attached images). */
+  text?: string | ContentPart[]
+  name?: string
+  context?: string
+}
+
+export type CommandsCatalogResponse = {
+  categories?: Array<{ name: string; pairs?: [string, string][] }>
+  pairs?: [string, string][]
+  canon?: Record<string, string>
+  sub?: Record<string, string[]>
+  skill_count?: number
+  warning?: string
+}
+
+export type ConfigSetResponse = {
+  value?: string
+  info?: SessionInfo
+  warning?: string
+  history_reset?: boolean
+}
+
+export type ModelOptionsResponse = {
+  provider?: string
+  model?: string
+  providers?: {
+    slug: string
+    name: string
+    models?: string[]
+    total_models?: number
+    is_current?: boolean
+    warning?: string
+  }[]
+}
+
+export type ImageAttachResponse = {
+  attached: boolean
+  path?: string
+  count?: number
+  name?: string
+  width?: number
+  height?: number
+  token_estimate?: number
+  message?: string
+}
+
+export type DropDetectResponse =
+  | { matched: false }
+  | ({ matched: true; is_image: true; text: string } & Omit<ImageAttachResponse, "attached" | "message">)
+  | { matched: true; is_image: false; path: string; name: string; text: string }

package/src/utils/git.ts

@@ -0,0 +1,57 @@
+// Git branch for the sidebar. One-shot resolve + fs.watch on
+// `<gitdir>/HEAD` so checkout/switch is picked up without polling.
+// Ink's equivalent polls every 15s; the watcher is strictly cheaper
+// and fires exactly on the event that matters.
+
+import { useEffect, useState } from "react"
+import { watch, type FSWatcher } from "node:fs"
+
+const TIMEOUT = 500
+
+async function git(cwd: string, ...args: string[]): Promise<string | null> {
+  const p = Bun.spawn(["git", "-C", cwd, ...args], { stdout: "pipe", stderr: "ignore" })
+  const t = setTimeout(() => p.kill(), TIMEOUT)
+  const out = await new Response(p.stdout).text()
+  clearTimeout(t)
+  return (await p.exited) === 0 ? out.trim() : null
+}
+
+/** Branch name for `cwd`, or null when not in a repo / detached HEAD. */
+export async function branch(cwd: string): Promise<string | null> {
+  const b = await git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
+  return !b || b === "HEAD" ? null : b
+}
+
+/** Absolute .git dir for `cwd` (handles worktrees via git's own resolver). */
+export async function gitdir(cwd: string): Promise<string | null> {
+  return git(cwd, "rev-parse", "--absolute-git-dir")
+}
+
+export function useGitBranch(cwd: string | undefined): string | null {
+  const [val, set] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!cwd) { set(null); return }
+    let dead = false
+    let w: FSWatcher | undefined
+    const read = () => branch(cwd).then(b => { if (!dead) set(b) })
+    void read()
+    // HEAD is rewritten (not edited in-place) on checkout — watch the
+    // parent dir and filter on basename so rename-into-place fires.
+    gitdir(cwd).then(dir => {
+      if (dead || !dir) return
+      try {
+        w = watch(dir, { persistent: false }, (_ev, f) => {
+          if (f === "HEAD") void read()
+        })
+      } catch { /* unwatchable fs */ }
+    })
+    return () => { dead = true; w?.close() }
+  }, [cwd])
+
+  return val
+}
+
+/** Right-ellipsise keeping the discriminating tail (feature/foo → …e/foo). */
+export const rtrunc = (s: string, max: number) =>
+  s.length <= max ? s : "…" + s.slice(-(max - 1))