typeclaw 0.28.2 → 0.29.0

package/src/tui/index.ts

@@ -1,13 +1,25 @@
-import { Editor, Key, Markdown, matchesKey, ProcessTerminal, type Terminal, Text, TUI } from '@mariozechner/pi-tui'
+import {
+  Editor,
+  Key,
+  Loader,
+  Markdown,
+  matchesKey,
+  ProcessTerminal,
+  type Terminal,
+  Text,
+  TUI,
+} from '@mariozechner/pi-tui'
 
 import { parseCommand } from '@/commands'
 
+import { formatBanner } from './banner'
 import { createClient as createClientDefault, type Client } from './client'
 import {
+  formatAssistantHeader,
   formatQueuePanel,
-  formatTimestamp,
   formatToolEnd,
   formatToolStart,
+  formatUsageSummary,
   formatUserPromptHistory,
   withTimestamp,
 } from './format'
@@ -118,29 +130,58 @@ export function createTui({
     if (handshake === null) return { reason: 'connectFailed' }
 
     const { sessionId, serverVersion } = handshake
-    status.setText(colors.dim(`session: ${sessionId}`))
+    // The banner card already carries session id, version, and url, so it
+    // supersedes the old one-line session status in place (status is child[0],
+    // pinned above all scrollback).
+    status.setText(formatBanner({ sessionId, displayUrl, ...(serverVersion !== undefined ? { serverVersion } : {}) }))
     tui.requestRender()
 
     const editor = new Editor(tui, editorTheme, { paddingX: 0 })
+    const statusBar = new Text('', 0, 0)
     let replyInFlight = false
     let onReplyDone: (() => void) | null = null
     let currentAssistant: Markdown | null = null
     let currentAssistantText = ''
     let queuePanel: Text | null = null
+    let thinkingLoader: Loader | null = null
+    let reloadLoader: Loader | null = null
+    let restartLoader: Loader | null = null
+    let usageLabel: string | null = null
+    let connectionLabel = 'connected'
+
+    const shortSessionId = sessionId.length > 14 ? `${sessionId.slice(0, 14)}…` : sessionId
+    const refreshStatusBar = () => {
+      const parts = [
+        colors.dim(connectionLabel),
+        colors.dim(`session ${shortSessionId}`),
+        serverVersion !== undefined ? colors.dim(`v${serverVersion}`) : null,
+        usageLabel !== null ? colors.accent(usageLabel) : null,
+      ].filter((part): part is string => part !== null)
+      statusBar.setText(parts.join(colors.dim('  ·  ')))
+    }
+    refreshStatusBar()
 
     // Pi-tui's Container.addChild appends to the end of the children array.
-    // The editor must remain the LAST child at all times so it stays pinned
-    // to the bottom of the viewport, with chat history scrolling above it.
-    // The queue panel, when present, sits immediately ABOVE the editor (so
-    // the layout is [...history, queuePanel?, editor]). Any new history entry
-    // is inserted by stripping the queue panel + editor from the tail,
-    // appending the entry, then re-appending them in order.
-    const appendHistory = (component: Text | Markdown) => {
+    // The bottom tail is pinned as [...history, queuePanel?, editor, statusBar]:
+    // the editor stays above the persistent status bar, and the queue panel,
+    // when present, sits just above the editor. Any new history entry is
+    // inserted by stripping that tail, appending the entry, then re-appending
+    // the tail in order so nothing ever renders below the status bar.
+    const reattachTail = () => {
+      if (queuePanel) tui.addChild(queuePanel)
+      tui.addChild(editor)
+      tui.addChild(statusBar)
+    }
+    const detachTail = () => {
       if (queuePanel) tui.removeChild(queuePanel)
       tui.removeChild(editor)
+      tui.removeChild(statusBar)
+    }
+
+    const appendHistory = (component: Text | Markdown) => {
+      detachTail()
       tui.addChild(component)
-      if (queuePanel) tui.addChild(queuePanel)
-      tui.addChild(editor)
+      reattachTail()
     }
 
     const updateQueuePanel = (pending: ReadonlyArray<{ id: string; text: string; ts: number }>) => {
@@ -156,14 +197,36 @@ export function createTui({
       if (queuePanel) {
         queuePanel.setText(text)
       } else {
-        queuePanel = new Text(text, 0, 0)
         tui.removeChild(editor)
+        tui.removeChild(statusBar)
+        queuePanel = new Text(text, 0, 0)
         tui.addChild(queuePanel)
         tui.addChild(editor)
+        tui.addChild(statusBar)
       }
       tui.requestRender()
     }
 
+    const showThinking = () => {
+      if (thinkingLoader !== null) return
+      const loader = new Loader(tui, colors.accent, colors.dim, 'thinking…')
+      thinkingLoader = loader
+      appendHistory(loader)
+      loader.start()
+      tui.requestRender()
+    }
+    const hideThinking = () => {
+      if (thinkingLoader === null) return
+      thinkingLoader.stop()
+      tui.removeChild(thinkingLoader)
+      thinkingLoader = null
+    }
+    const stopAllLoaders = () => {
+      thinkingLoader?.stop()
+      reloadLoader?.stop()
+      restartLoader?.stop()
+    }
+
     // Reset between text segments so a new Markdown block is created after
     // any non-text event (tool calls). Otherwise text_delta after a tool call
     // would append to the previous Markdown and visually push the tool lines
@@ -174,19 +237,20 @@ export function createTui({
     }
 
     const finishAssistantTurn = () => {
+      hideThinking()
       sealAssistantBlock()
       replyInFlight = false
       onReplyDone?.()
       onReplyDone = null
     }
 
-    // A Markdown block can't carry an ANSI timestamp prefix (it'd be parsed as
-    // markdown), so the assistant turn's timestamp is a separate dim Text line
-    // emitted just above the block when it's first created — stamped with the
-    // first delta's server `ts`.
+    // A Markdown block can't carry an ANSI header prefix (it'd be parsed as
+    // markdown), so the assistant turn's boxed header (label + timestamp) is a
+    // separate Text line emitted just above the block when it's first created —
+    // stamped with the first delta's server `ts`.
     const ensureAssistantBlock = (ts: number | undefined): Markdown => {
       if (currentAssistant) return currentAssistant
-      appendHistory(new Text(formatTimestamp(ts), 0, 0))
+      appendHistory(new Text(formatAssistantHeader(ts), 0, 0))
       const md = new Markdown('', 0, 0, markdownTheme)
       currentAssistant = md
       currentAssistantText = ''
@@ -198,10 +262,12 @@ export function createTui({
       switch (msg.type) {
         case 'prompt_started': {
           appendHistory(new Text(withTimestamp(msg.ts, formatUserPromptHistory(msg.text)), 0, 0))
+          if (replyInFlight) showThinking()
           tui.requestRender()
           break
         }
         case 'text_delta': {
+          hideThinking()
           const block = ensureAssistantBlock(msg.ts)
           currentAssistantText += msg.delta
           block.setText(currentAssistantText)
@@ -209,6 +275,7 @@ export function createTui({
           break
         }
         case 'tool_start': {
+          hideThinking()
           sealAssistantBlock()
           appendHistory(new Text(withTimestamp(msg.ts, formatToolStart(msg.name, msg.args)), 0, 0))
           tui.requestRender()
@@ -223,6 +290,10 @@ export function createTui({
           break
         }
         case 'done': {
+          if (msg.usage !== undefined) {
+            usageLabel = formatUsageSummary(msg.usage)
+            refreshStatusBar()
+          }
           finishAssistantTurn()
           tui.requestRender()
           break
@@ -238,6 +309,11 @@ export function createTui({
           break
         }
         case 'reload_result': {
+          if (reloadLoader !== null) {
+            reloadLoader.stop()
+            tui.removeChild(reloadLoader)
+            reloadLoader = null
+          }
           for (const result of msg.results) {
             const text = result.ok
               ? `${colors.green('●')} ${colors.bold(`[${result.scope}]`)} ${result.summary}`
@@ -248,6 +324,11 @@ export function createTui({
           break
         }
         case 'restart_result': {
+          if (restartLoader !== null) {
+            restartLoader.stop()
+            tui.removeChild(restartLoader)
+            restartLoader = null
+          }
           const text =
             msg.status === 'accepted'
               ? colors.green(colors.dim(msg.message ?? 'restart scheduled; reconnecting when the new container is up'))
@@ -271,6 +352,9 @@ export function createTui({
     }
 
     client.onClose(() => {
+      stopAllLoaders()
+      connectionLabel = 'disconnected'
+      refreshStatusBar()
       appendHistory(new Text(colors.dim('disconnected'), 0, 0))
       tui.requestRender()
       // A user-initiated detach/exit already closed the WS deliberately and
@@ -293,14 +377,27 @@ export function createTui({
       }
       if (command === 'reload') {
         client.send({ type: 'reload' })
-        appendHistory(new Text(colors.dim('reloading...'), 0, 0))
+        if (reloadLoader === null) {
+          const loader = new Loader(tui, colors.accent, colors.dim, 'reloading…')
+          reloadLoader = loader
+          appendHistory(loader)
+          loader.start()
+        }
         tui.requestRender()
         return true
       }
       client.send({ type: 'restart' })
-      appendHistory(
-        new Text(colors.yellow(colors.dim('restart requested... reconnecting when the new container is up')), 0, 0),
-      )
+      if (restartLoader === null) {
+        const loader = new Loader(
+          tui,
+          colors.yellow,
+          colors.dim,
+          'restart requested… reconnecting when the new container is up',
+        )
+        restartLoader = loader
+        appendHistory(loader)
+        loader.start()
+      }
       tui.requestRender()
       return true
     }
@@ -322,6 +419,7 @@ export function createTui({
     // settles 'lostConnection'. settle() is idempotent, so the first call wins —
     // settling the deliberate outcome first keeps the later onClose a no-op.
     const teardown = (): void => {
+      stopAllLoaders()
       tui.stop()
       client.close()
     }
@@ -365,6 +463,7 @@ export function createTui({
       void send(text)
     }
     tui.addChild(editor)
+    tui.addChild(statusBar)
     tui.setFocus(editor)
     tui.requestRender()
 

package/src/tui/theme.ts

@@ -1,6 +1,7 @@
 import type { EditorTheme, MarkdownTheme } from '@mariozechner/pi-tui'
 
 const wrap = (code: string) => (text: string) => `\x1b[${code}m${text}\x1b[0m`
+const wrapRgb = (r: number, g: number, b: number) => (text: string) => `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`
 
 const dim = wrap('2')
 const bold = wrap('1')
@@ -9,8 +10,32 @@ const green = wrap('32')
 const yellow = wrap('33')
 const cyan = wrap('36')
 const gray = wrap('90')
+const brightGreen = wrap('92')
+const brightCyan = wrap('96')
+const brightMagenta = wrap('95')
 
-export const colors = { dim, bold, red, green, yellow, cyan, gray }
+// Sampled from the typeey mascot. True navy (#182A5B) is too dark to read on
+// dark terminals, so `accent` is a lifted cornflower of the same hue; amber is
+// the mascot's beak/feet highlight.
+const cornflower = wrapRgb(0x5b, 0x7f, 0xd4)
+const amber = wrapRgb(0xe7, 0x8f, 0x37)
+const accent = cornflower
+
+export const colors = {
+  dim,
+  bold,
+  red,
+  green,
+  yellow,
+  cyan,
+  gray,
+  brightGreen,
+  brightCyan,
+  brightMagenta,
+  cornflower,
+  amber,
+  accent,
+}
 
 export const editorTheme: EditorTheme = {
   borderColor: dim,

package/src/tunnels/providers/cloudflare-named.ts

@@ -2,6 +2,7 @@ import type { Unsubscribe } from '@/stream'
 
 import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
 import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+import { isBinaryNotFound, MISSING_BINARY_DETAIL } from './cloudflared-binary'
 
 const DEFAULT_BINARY = 'cloudflared'
 const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
@@ -79,10 +80,20 @@ export function createCloudflareNamedProvider(options: CloudflareNamedProviderOp
 
     state.status = 'starting'
     state.detail = 'starting cloudflared'
-    const spawned = Bun.spawn([binary, 'tunnel', '--no-autoupdate', 'run', '--token', token], {
-      stdout: 'ignore',
-      stderr: 'pipe',
-    })
+    let spawned: Bun.Subprocess<'ignore', 'ignore', 'pipe'>
+    try {
+      spawned = Bun.spawn([binary, 'tunnel', '--no-autoupdate', 'run', '--token', token], {
+        stdout: 'ignore',
+        stderr: 'pipe',
+      })
+    } catch (err) {
+      if (isBinaryNotFound(err)) {
+        state.status = 'permanently-failed'
+        state.detail = MISSING_BINARY_DETAIL
+        return
+      }
+      throw err
+    }
     proc = spawned
 
     // Mark healthy on the FIRST stderr line. cloudflared with a valid token

package/src/tunnels/providers/cloudflare-quick.ts

@@ -3,6 +3,7 @@ import type { Unsubscribe } from '@/stream'
 import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
 import { extractQuickTunnelUrl } from '../quick-url-parser'
 import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+import { isBinaryNotFound, MISSING_BINARY_DETAIL } from './cloudflared-binary'
 
 const DEFAULT_BINARY = 'cloudflared'
 const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
@@ -61,10 +62,20 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
     attemptEmittedUrl = false
     state.status = 'starting'
     state.detail = 'starting cloudflared'
-    const spawned = Bun.spawn(
-      [binary, 'tunnel', '--url', `http://127.0.0.1:${upstreamPort}`, '--no-autoupdate', '--metrics', '127.0.0.1:0'],
-      { stdout: 'ignore', stderr: 'pipe' },
-    )
+    let spawned: Bun.Subprocess<'ignore', 'ignore', 'pipe'>
+    try {
+      spawned = Bun.spawn(
+        [binary, 'tunnel', '--url', `http://127.0.0.1:${upstreamPort}`, '--no-autoupdate', '--metrics', '127.0.0.1:0'],
+        { stdout: 'ignore', stderr: 'pipe' },
+      )
+    } catch (err) {
+      if (isBinaryNotFound(err)) {
+        state.status = 'permanently-failed'
+        state.detail = MISSING_BINARY_DETAIL
+        return
+      }
+      throw err
+    }
     proc = spawned
 
     void pumpStderr(spawned.stderr, logs, (line) => {

package/src/tunnels/providers/cloudflared-binary.ts

@@ -0,0 +1,11 @@
+// Bun.spawn throws synchronously with `code === 'ENOENT'` when the binary is
+// absent from $PATH. Both Cloudflare providers translate that into a
+// permanently-failed state instead of letting the raw spawn error bubble up
+// as a generic "start failed" log — the actionable fix is enabling
+// docker.file.cloudflared and rebuilding, not waiting through restart backoff.
+export const MISSING_BINARY_DETAIL =
+  'cloudflared binary not found in image; set docker.file.cloudflared: true in typeclaw.json and run typeclaw restart'
+
+export function isBinaryNotFound(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as { code?: unknown }).code === 'ENOENT'
+}

package/typeclaw.schema.json

@@ -1121,8 +1121,8 @@
           "gh": true,
           "python": true,
           "tmux": true,
-          "cjkFonts": true,
-          "cloudflared": true,
+          "cjkFonts": "auto",
+          "cloudflared": false,
           "xvfb": true,
           "claudeCode": false,
           "codexCli": false,
@@ -1137,8 +1137,8 @@
             "gh": true,
             "python": true,
             "tmux": true,
-            "cjkFonts": true,
-            "cloudflared": true,
+            "cjkFonts": "auto",
+            "cloudflared": false,
             "xvfb": true,
             "claudeCode": false,
             "codexCli": false,
@@ -1187,11 +1187,19 @@
               ]
             },
             "cjkFonts": {
-              "default": true,
-              "type": "boolean"
+              "default": "auto",
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "string",
+                  "const": "auto"
+                }
+              ]
             },
             "cloudflared": {
-              "default": true,
+              "default": false,
               "type": "boolean"
             },
             "xvfb": {