herm-tui 1.0.0-dev.1

package/src/app/useAtRefPopover.ts

@@ -0,0 +1,99 @@
+// @-ref completion for the composer. Triggers when the word under the
+// cursor starts with `@` (and we're not in slash mode). A fixed keyword
+// set (diff/staged/git:N/url:/folder:) is defined client-side and
+// prepended to whatever the gateway's `complete.path` returns — the
+// gateway still handles path completion for `@file:…` / `@folder:…`
+// (and maps bare `@<path>` → `@file:` / `@folder:`).
+//
+// Expansion itself happens server-side in `prompt.submit`; this hook
+// only drives the popover UI and text insertion.
+
+import { useEffect, useRef, useState } from "react"
+import { useGateway, useGatewayReady } from "./gateway"
+
+export type AtRefItem = {
+  readonly text: string
+  readonly display: string
+  readonly meta: string
+}
+
+// Fixed hermes @-keywords. Shown above file results; `text` is what
+// gets inserted (trailing `:` keeps the popover open for further input).
+export const KEYWORDS: ReadonlyArray<AtRefItem> = [
+  { text: "@diff",    display: "@diff",          meta: "working-tree diff" },
+  { text: "@staged",  display: "@staged",        meta: "staged changes" },
+  { text: "@git:1",   display: "@git:1",         meta: "last 1 commit" },
+  { text: "@git:3",   display: "@git:3",         meta: "last 3 commits" },
+  { text: "@git:5",   display: "@git:5",         meta: "last 5 commits" },
+  { text: "@url:",    display: "@url:<…>",       meta: "fetch a URL" },
+  { text: "@folder:", display: "@folder:<path>", meta: "recurse directory" },
+]
+
+// Keywords whose text strictly extends `word` (case-insensitive).
+// Exact matches are dropped so e.g. accepting `@url:` closes the
+// popover and `@folder:` hands off cleanly to path completion.
+export function match(word: string): AtRefItem[] {
+  const q = word.toLowerCase()
+  return KEYWORDS.filter(k => k.text.toLowerCase().startsWith(q) && k.text !== word)
+}
+
+// Find the @-word the caret is at the end of. Returns {word, start}
+// or null when not applicable. Bails on slash-command input so the
+// two popovers never contend.
+export function atWordAt(input: string): { word: string; start: number } | null {
+  if (input.startsWith("/")) return null
+  const end = input.length
+  let i = end
+  while (i > 0 && !/\s/.test(input[i - 1])) i--
+  if (i >= end || input[i] !== "@") return null
+  return { word: input.slice(i, end), start: i }
+}
+
+export function useAtRefPopover(input: string) {
+  const gw = useGateway()
+  const ready = useGatewayReady()
+  const [items, setItems] = useState<AtRefItem[]>([])
+  const [cursor, setCursor] = useState(0)
+  const seq = useRef(0)
+  const dismissed = useRef<string | null>(null)
+
+  const spot = atWordAt(input)
+
+  useEffect(() => {
+    if (!spot || !ready) { setItems([]); setCursor(0); return }
+    if (dismissed.current === spot.word) return
+    dismissed.current = null
+    const me = ++seq.current
+    const fixed = match(spot.word)
+    const t = setTimeout(() => {
+      gw.request<{ items: AtRefItem[] }>("complete.path", { word: spot.word })
+        .then(r => {
+          if (seq.current !== me) return
+          const seen = new Set(fixed.map(k => k.text))
+          setItems([...fixed, ...(r.items ?? []).filter(i => !seen.has(i.text))])
+          setCursor(0)
+        })
+        .catch(() => { if (seq.current === me) { setItems(fixed); setCursor(0) } })
+    }, 120)
+    return () => clearTimeout(t)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [spot?.word, ready, gw])
+
+  const open = spot !== null && items.length > 0
+
+  const accept = (src: string, idx = cursor): string | null => {
+    const at = atWordAt(src)
+    const it = items[idx]
+    if (!at || !it) return null
+    const trail = it.text.endsWith(":") || it.text.endsWith("/") ? "" : " "
+    return src.slice(0, at.start) + it.text + trail + src.slice(at.start + at.word.length)
+  }
+
+  const dismiss = () => {
+    seq.current++
+    dismissed.current = spot?.word ?? null
+    setItems([])
+  }
+
+  return { open, items, cursor, setCursor, accept, dismiss }
+}

package/src/app/useInputHistory.ts

@@ -0,0 +1,66 @@
+// Up/down history for composer input.
+// Persisted under the herm config dir (typically ~/.hermes/herm/history).
+
+import { useState, useRef, useCallback } from "react"
+import { join } from "path"
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "fs"
+import { configDir } from "../utils/paths"
+
+const MAX = 500
+
+const file = () => join(configDir(), "history")
+
+// In-memory order is newest-first (index 0 = most recent); on-disk is
+// append-only newest-last, so load() reverses.
+function load() {
+  const FILE = file()
+  if (!existsSync(FILE)) return []
+  return readFileSync(FILE, "utf-8").split("\n").filter(Boolean)
+    .map(l => l.replace(/\0/g, "\n")).slice(-MAX).reverse()
+}
+
+function enc(s: string) { return s.replace(/\n/g, "\0") }
+
+export function useInputHistory(input: string, setInput: (v: string) => void) {
+  const hist = useRef<string[]>(null)
+  if (hist.current === null) hist.current = load()
+  const [, bump] = useState(0)
+  const idx = useRef(-1)
+  const stash = useRef("")
+
+  const push = useCallback((msg: string) => {
+    idx.current = -1
+    stash.current = ""
+    const h = hist.current!
+    if (msg === h[0]) return
+    h.unshift(msg)
+    const DIR = configDir()
+    const FILE = file()
+    if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true })
+    if (h.length > MAX) {
+      h.length = MAX
+      writeFileSync(FILE, [...h].reverse().map(enc).join("\n") + "\n", "utf-8")
+    } else {
+      appendFileSync(FILE, enc(msg) + "\n", "utf-8")
+    }
+    bump(n => n + 1)
+  }, [])
+
+  const up = useCallback(() => {
+    const h = hist.current!
+    if (h.length === 0) return
+    if (idx.current === -1) stash.current = input
+    const next = Math.min(idx.current + 1, h.length - 1)
+    idx.current = next
+    setInput(h[next])
+  }, [input, setInput])
+
+  const down = useCallback(() => {
+    if (idx.current === -1) return
+    const next = idx.current - 1
+    idx.current = next
+    setInput(next === -1 ? stash.current : hist.current![next])
+  }, [setInput])
+
+  return { push, up, down }
+}

package/src/app/useSession.ts

@@ -0,0 +1,102 @@
+// Session lifecycle: create, resume, switch, interrupt, branch, compress, undo.
+
+import { useMemo, useCallback } from "react"
+import * as preferences from "../utils/preferences"
+import * as sdb from "../utils/sessions-db"
+import { useGateway } from "./gateway"
+import { transcriptToMessages } from "./turnReducer"
+import type { Launch } from "./launch"
+import type { SessionResumeResponse, SessionCreateResponse } from "../utils/gateway-types"
+import type { Message } from "../types/message"
+
+/** session.compress response shape — see upstream fc7f55f49. */
+export type CompressResult = {
+  status?: "compressed" | "skipped"
+  removed?: number
+  before_messages?: number
+  after_messages?: number
+  before_tokens?: number
+  after_tokens?: number
+  summary?: {
+    noop?: boolean
+    headline?: string
+    token_line?: string
+    note?: string | null
+  }
+}
+
+type Booted = { id: string; messages: Message[]; note?: string }
+
+type SessionOps = {
+  /** Establish the initial session per launch intent. */
+  boot: (launch: Launch) => Promise<Booted>
+  create: () => Promise<string>
+  resume: (sid: string) => Promise<{ id: string; messages: Message[] }>
+  interrupt: () => Promise<void>
+  branch: (name?: string) => Promise<string | null>
+  compress: () => Promise<CompressResult | null>
+  undo: () => Promise<void>
+}
+
+export function useSession(): SessionOps {
+  const gw = useGateway()
+
+  const resume = useCallback(async (sid: string) => {
+    const res = await gw.request<SessionResumeResponse>("session.resume", { session_id: sid })
+    const id = res.session_id
+    gw.setSession(id)
+    preferences.set("lastSessionId", res.resumed ?? sid)
+    const messages = res.messages?.length ? transcriptToMessages(res.messages) : []
+    return { id, messages }
+  }, [gw])
+
+  const create = useCallback(async () => {
+    const res = await gw.request<SessionCreateResponse>("session.create", {})
+    gw.setSession(res.session_id)
+    return res.session_id
+  }, [gw])
+
+  const boot = useCallback(async (launch: Launch): Promise<Booted> => {
+    const fresh = async (note?: string) => ({ id: await create(), messages: [], note })
+
+    if (launch.mode === "resume") {
+      const target = launch.sid ?? sdb.lastReal()?.id
+      if (!target) return fresh("no prior session to resume — starting fresh")
+      try { return await resume(target) }
+      catch { return fresh(`resume ${target} failed — starting fresh`) }
+    }
+
+    // mode:"new" — reuse our own abandoned empty stub instead of
+    // creating another row every launch.
+    const last = preferences.get("lastSessionId")
+    if (last && sdb.byId(last)?.message_count === 0) {
+      try { return await resume(last) } catch { /* fall through */ }
+    }
+    return fresh()
+  }, [create, resume])
+
+  const interrupt = useCallback(async () => {
+    try { await gw.request("session.interrupt") } catch {}
+  }, [gw])
+
+  const branch = useCallback(async (name?: string) => {
+    try {
+      const res = await gw.request<{ session_id?: string }>("session.branch", name ? { name } : {})
+      return res.session_id ?? null
+    } catch { return null }
+  }, [gw])
+
+  const compress = useCallback(async (): Promise<CompressResult | null> => {
+    try { return await gw.request<CompressResult>("session.compress") }
+    catch { return null }
+  }, [gw])
+
+  const undo = useCallback(async () => {
+    try { await gw.request("session.undo") } catch {}
+  }, [gw])
+
+  return useMemo(
+    () => ({ boot, create, resume, interrupt, branch, compress, undo }),
+    [boot, create, resume, interrupt, branch, compress, undo],
+  )
+}

package/src/app/useSlashCommands.ts

@@ -0,0 +1,70 @@
+// Slash command catalog + live completion over RPC. Falls back to
+// LOCAL_COMMANDS when the gateway catalog is unavailable.
+//
+// Wire shape (tui_gateway/server.py @method("commands.catalog")):
+//   pairs:      [["/new", "desc"], ...]            — flat, includes skills + quick_commands
+//   categories: [{name, pairs: [["/new","…"],…]}]  — registry cmds only, grouped
+//   sub:        {"/reasoning": ["low","medium",…]} — subcommand completions
+//   canon:      {"/reset": "/new", …}              — alias → canonical (both slashed)
+// All names carry a leading "/"; herm stores them bare.
+
+import { useCallback, useEffect, useState } from "react"
+import { useGateway, useGatewayReady } from "./gateway"
+import {
+  LOCAL_COMMANDS,
+  LOCAL_NAMES,
+  sort,
+  type SlashCommand,
+} from "../commands/slash"
+import type { CommandsCatalogResponse } from "../utils/gateway-types"
+
+const bare = (s: string) => (s[0] === "/" ? s.slice(1) : s)
+
+export function useSlashCommands() {
+  const gw = useGateway()
+  const ready = useGatewayReady()
+  const [cmds, setCmds] = useState<ReadonlyArray<SlashCommand>>(LOCAL_COMMANDS)
+
+  const fetch = useCallback(async () => {
+    const res = await gw.request<CommandsCatalogResponse>("commands.catalog")
+      .catch(() => null)
+    if (!res) { setCmds(LOCAL_COMMANDS); return }
+
+    // name → category (from categories[].pairs, slashed)
+    const cat = new Map<string, string>()
+    for (const g of res.categories ?? [])
+      for (const [n] of g.pairs ?? []) cat.set(bare(n), g.name)
+
+    // canonical → aliases[] (invert canon)
+    const alias = new Map<string, string[]>()
+    for (const [a, c] of Object.entries(res.canon ?? {})) {
+      const k = bare(c), v = bare(a)
+      if (k === v) continue
+      ;(alias.get(k) ?? alias.set(k, []).get(k)!).push(v)
+    }
+
+    const sub = new Map(Object.entries(res.sub ?? {}).map(([k, v]) => [bare(k), v]))
+
+    const remote: SlashCommand[] = (res.pairs ?? []).map(([raw, desc]) => {
+      const name = bare(raw)
+      return {
+        name,
+        description: desc,
+        category: cat.get(name) ?? (name.includes(":") ? "Skills" : "Command"),
+        aliases: alias.get(name) ?? [],
+        argsHint: "",
+        subcommands: sub.get(name) ?? [],
+        source: "command" as const,
+        target: LOCAL_NAMES.has(name) ? ("local" as const) : ("gateway" as const),
+      }
+    })
+
+    const seen = new Set(remote.map(c => c.name))
+    const locals = LOCAL_COMMANDS.filter(c => !seen.has(c.name))
+    setCmds(sort([...locals, ...remote]))
+  }, [gw])
+
+  useEffect(() => { if (ready) void fetch() }, [ready, fetch])
+
+  return { cmds, refresh: fetch }
+}

package/src/app/useSlashPopover.ts

@@ -0,0 +1,48 @@
+// Popover filtering and ghost text for the slash-command composer.
+
+import { useMemo, useEffect, useState } from "react"
+import { matchSub, type SlashCommand } from "../commands/slash"
+import { score } from "../utils/fuzzy"
+
+function best(q: string, cmd: SlashCommand) {
+  return cmd.aliases.reduce((m, a) => Math.max(m, score(q, a)), score(q, cmd.name))
+}
+
+export function rank(list: ReadonlyArray<SlashCommand>, q: string): SlashCommand[] {
+  if (!q) return [...list]
+  return list
+    .map(cmd => ({ cmd, s: best(q, cmd) }))
+    .filter(r => r.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .map(r => r.cmd)
+}
+
+export function useSlashPopover(input: string, cmds: ReadonlyArray<SlashCommand>) {
+  const [cursor, setCursor] = useState(0)
+
+  const popover = useMemo(() => {
+    const subs = matchSub(cmds, input)
+    if (subs) return subs
+    const m = input.match(/^\/(\S*)$/)
+    return m ? rank(cmds, m[1]) : null
+  }, [input, cmds])
+
+  // Reset cursor when input changes
+  useEffect(() => { setCursor(c => c === 0 ? c : 0) }, [input])
+
+  const ghost = useMemo(() => {
+    if (!popover || popover.length === 0) return ""
+    const best = popover[Math.min(cursor, popover.length - 1)]
+    if (!best || best.name.includes(" ")) return ""
+    const m = input.match(/^\/(\S*)$/)
+    if (!m) return ""
+    const typed = m[1]
+    if (typed.length < 2) return ""
+    if (!best.name.toLowerCase().startsWith(typed.toLowerCase())) return ""
+    return best.name.slice(typed.length)
+  }, [input, popover, cursor])
+
+  const open = popover !== null && popover.length > 0
+
+  return { popover, cursor, setCursor, ghost, open }
+}