typeclaw 0.28.2 → 0.29.0

package/src/server/index.ts

@@ -184,6 +184,10 @@ type SessionState = {
   // not re-target this session's lifecycle hooks.
   runtimeSnapshot: PluginRuntimeState | null
   unsubTurnOutcome: Unsubscribe | null
+  // Latest turn's usage, captured from `message_end` by forwardSessionEvents and
+  // read at the `done` send site (which lives outside that subscriber). Reset at
+  // each turn start so a turn with no usage event sends a plain `done`.
+  lastUsage: { input: number; output: number; totalTokens: number; cost: number } | null
   dispose: () => Promise<void>
 }
 
@@ -520,6 +524,7 @@ export function createServer({
               activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
               unsubTurnOutcome: null,
+              lastUsage: null,
               dispose,
             }
             sessionStates.set(ws, state)
@@ -533,7 +538,7 @@ export function createServer({
             }
 
             liveSessionRegistry?.register({ sessionId: sessionFileId, session })
-            forwardSessionEvents(ws, session, logger, sessionFileId)
+            forwardSessionEvents(ws, state, logger, sessionFileId)
 
             if (stream) {
               state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
@@ -759,9 +764,10 @@ export function createServer({
                 origin: state.origin,
               })
             }
+            state.lastUsage = null
             try {
               await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${msg.text}`)
-              send(ws, { type: 'done' })
+              send(ws, doneMessage(state))
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err)
               logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
@@ -859,10 +865,10 @@ function isWebSocketUpgrade(req: Request): boolean {
   return req.headers.get('upgrade')?.toLowerCase() === 'websocket'
 }
 
-function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogger, sessionFileId: string): void {
+function forwardSessionEvents(ws: Ws, state: SessionState, logger: ServerLogger, sessionFileId: string): void {
   const toolStartedAt = new Map<string, number>()
 
-  session.subscribe((event) => {
+  state.session.subscribe((event) => {
     switch (event.type) {
       case 'message_update':
         if (event.assistantMessageEvent.type === 'text_delta') {
@@ -877,6 +883,7 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
         // because no text deltas were ever emitted, which looks like a freeze.
         // The server's existing try/catch around `session.prompt()` only
         // catches throws, so it never sees these.
+        state.lastUsage = readDoneUsage(event.message)
         forwardAssistantError(ws, event.message, logger, sessionFileId)
         break
       case 'tool_execution_start':
@@ -1048,9 +1055,10 @@ async function drain(
       }
 
       await fireTurnStart(item.text)
+      state.lastUsage = null
       try {
         await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
-        send(ws, { type: 'done' })
+        send(ws, doneMessage(state))
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
         logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
@@ -1445,6 +1453,17 @@ function buildMessageEndPayload(sessionId: string, message: unknown): InspectFra
   return payload
 }
 
+function doneMessage(state: SessionState): ServerMessage {
+  return state.lastUsage === null ? { type: 'done' } : { type: 'done', usage: state.lastUsage }
+}
+
+function readDoneUsage(message: unknown): { input: number; output: number; totalTokens: number; cost: number } | null {
+  if (typeof message !== 'object' || message === null) return null
+  const usage = readMessageUsage((message as Record<string, unknown>).usage)
+  if (usage === null) return null
+  return { input: usage.input, output: usage.output, totalTokens: usage.totalTokens, cost: usage.cost }
+}
+
 function readMessageUsage(
   value: unknown,
 ): { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number; cost: number } | null {

package/src/shared/host-locale.ts

@@ -0,0 +1,27 @@
+const CJK_LANGUAGE_PREFIXES = ['ja', 'ko', 'zh'] as const
+
+function languageTagIsCjk(tag: string): boolean {
+  const primary = tag.toLowerCase().replace(/_/g, '-').split('-')[0] ?? ''
+  return CJK_LANGUAGE_PREFIXES.some((prefix) => primary === prefix)
+}
+
+// True when the HOST's locale is Chinese/Japanese/Korean. POSIX precedence:
+// LC_ALL overrides LC_CTYPE overrides LANG. Values look like `ja_JP.UTF-8`,
+// `ko_KR`, `zh-Hans`. `C`/`POSIX`/empty fall through to Intl, which on macOS
+// (where these env vars are usually unset) reports the user's system locale.
+// Returns false if nothing resolves — the conservative choice, since the
+// caller uses this to decide whether to add the ~89MB CJK font package.
+export function hostLocaleIsCjk(): boolean {
+  for (const envVar of ['LC_ALL', 'LC_CTYPE', 'LANG']) {
+    const value = process.env[envVar]
+    if (value === undefined || value === '') continue
+    if (value === 'C' || value === 'POSIX') return false
+    return languageTagIsCjk(value)
+  }
+  try {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale
+    return locale !== undefined && locale !== '' && languageTagIsCjk(locale)
+  } catch {
+    return false
+  }
+}

package/src/shared/protocol.ts

@@ -223,7 +223,7 @@ export type ServerMessage =
       durationMs: number
       ts?: number
     }
-  | { type: 'done'; ts?: number }
+  | { type: 'done'; ts?: number; usage?: { input: number; output: number; totalTokens: number; cost: number } }
   | { type: 'error'; message: string; ts?: number }
   | { type: 'reload_result'; results: ReloadResultPayload[] }
   | { type: 'restart_result'; status: 'accepted' | 'failed'; message?: string; error?: string }

package/src/shared/wordmark.ts

@@ -0,0 +1,19 @@
+// Single source of truth for the "typeclaw" wordmark so the TUI banner and the
+// init CLI render the same art instead of drifting apart. This module is
+// color-agnostic: each consumer applies its own coloring layer (the TUI emits
+// raw truecolor; init gates color behind NO_COLOR/TTY), so the art here carries
+// zero escape sequences.
+
+// ANSI Shadow "typeclaw". Trailing whitespace is significant for alignment.
+export const WORDMARK_LINES: readonly string[] = [
+  '████████╗██╗   ██╗██████╗ ███████╗ ██████╗██╗      █████╗ ██╗    ██╗',
+  '╚══██╔══╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔════╝██║     ██╔══██╗██║    ██║',
+  '   ██║    ╚████╔╝ ██████╔╝█████╗  ██║     ██║     ███████║██║ █╗ ██║',
+  '   ██║     ╚██╔╝  ██╔═══╝ ██╔══╝  ██║     ██║     ██╔══██║██║███╗██║',
+  '   ██║      ██║   ██║     ███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝',
+  '   ╚═╝      ╚═╝   ╚═╝     ╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝ ',
+]
+
+export const WORDMARK_WIDTH: number = Math.max(...WORDMARK_LINES.map((line) => line.length))
+
+export const COMPACT_WORDMARK = 'typeclaw'

package/src/skills/typeclaw-config/SKILL.md

@@ -39,18 +39,18 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
 
 `typeclaw.json` is a single JSON object with these fields:
 
-| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                    |
-| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                                                                                                                                                       |
-| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                                                                                                                                                   |
-| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                                                                                                                                                      |
-| `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
-| `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                                                                                                                                                |
+| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                       |
+| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                                                                                                                                                          |
+| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                                                                                                                                                      |
+| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                                                                                                                                                         |
+| `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
+| `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                                                                                                                                                   |
 
 > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
 
@@ -223,32 +223,32 @@ The agent folder's directory name (`basename(agentDir)`) is **always** an implic
 
 ### Match semantics
 
-- **Substring** match against the inbound text. `"봉봉"` matches `"봉봉아 cron"`, `"봉봉씨 안녕"`, `"누가 봉봉을 불러"`, all of them. Korean particles aren't stripped — substring is enough because the bot name appears at the start of every particled form.
-- **Case-insensitive** via `toLocaleLowerCase()` on both sides. `"Bongbong"` in the alias list matches `"BONGBONG"`, `"bongbong"`, `"BongBong"`.
+- **Substring** match against the inbound text. `"토토"` matches `"토토아 cron"`, `"토토씨 안녕"`, `"누가 토토을 불러"`, all of them. Korean particles aren't stripped — substring is enough because the bot name appears at the start of every particled form.
+- **Case-insensitive** via `toLocaleLowerCase()` on both sides. `"Toto"` in the alias list matches `"TOTO"`, `"toto"`, `"ToTo"`.
 - **No word-boundary detection.** A short or generic alias like `"bot"` will match every message containing `"robot"` or `"bottom"`. Pick distinctive names — the operator owns curation.
 
 ### Engagement priority
 
-The alias path runs **after** explicit triggers (mention/reply/dm) and the sticky check. So a message with both an `<@id>` mention and an alias substring engages once, normally. A message with only the alias substring engages on the alias path. The alias path is **NOT suppressed by `mentionsOthers`**: addressing two bots in one message (`"봉봉아 펭펭아 둘 다 봐"`) engages both bots — each on their own alias.
+The alias path runs **after** explicit triggers (mention/reply/dm) and the sticky check. So a message with both an `<@id>` mention and an alias substring engages once, normally. A message with only the alias substring engages on the alias path. The alias path is **NOT suppressed by `mentionsOthers`**: addressing two bots in one message (`"토토아 라라아 둘 다 봐"`) engages both bots — each on their own alias.
 
-There's also a symmetric **peer-name suppressor**: if the message contains a peer bot's observed display name (from `participants[]`, populated as peers speak in the channel) and **does not** contain any of this agent's aliases, the solo-human fallback is suppressed and the agent observes. This is what makes `"펭펭아 cron 좀"` in a 1-human-multi-bot channel correctly observe instead of all bots replying. First-time addressing of a never-seen peer slips through; the suppressor catches it after the peer's first message.
+There's also a symmetric **peer-name suppressor**: if the message contains a peer bot's observed display name (from `participants[]`, populated as peers speak in the channel) and **does not** contain any of this agent's aliases, the solo-human fallback is suppressed and the agent observes. This is what makes `"라라아 cron 좀"` in a 1-human-multi-bot channel correctly observe instead of all bots replying. First-time addressing of a never-seen peer slips through; the suppressor catches it after the peer's first message.
 
 ### Example
 
 ```json
 {
-  "alias": ["bongbong", "봉봉"]
+  "alias": ["toto", "토토"]
 }
 ```
 
-The agent in folder `봉봉/` already answers to `"봉봉"` from the dir name. This adds the Latin transliteration so users can also write `"Hey bongbong, deploy?"`.
+The agent in folder `토토/` already answers to `"토토"` from the dir name. This adds the Latin transliteration so users can also write `"Hey toto, deploy?"`.
 
 ### When the user asks "respond to my casual nickname for you" / "I want to call you X"
 
 1. **Read `typeclaw.json`.**
 2. **If `alias` exists**, append the new name (preserve existing entries; dedupe trivially — the runtime also dedupes).
 3. **If `alias` is absent**, create it as `["<new name>"]`.
-4. **You don't need to add the dir name** unless the new name IS a variation of the dir name itself (e.g. dir is `bongbong` and the user wants `Bongbong` casing — the implicit dir alias matches case-insensitively, so this isn't needed either).
+4. **You don't need to add the dir name** unless the new name IS a variation of the dir name itself (e.g. dir is `toto` and the user wants `Toto` casing — the implicit dir alias matches case-insensitively, so this isn't needed either).
 5. **Trim whitespace** before adding. The schema rejects empty/whitespace-only entries; the runtime trims surrounding whitespace from valid entries.
 6. **Write, commit**: "Edited `alias` — live-reloadable. Run `reload` to pick up the change without restart."
 
@@ -348,18 +348,18 @@ The `docker.file` block has two layers of customization:
 
 ### Fields
 
-| Field         | Required | Type              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tmux`        | no       | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `gh`          | no       | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `python`      | no       | boolean           | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                           |
-| `ffmpeg`      | no       | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `cjkFonts`    | no       | boolean           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                                                                                                                                                                       |
-| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. Boolean-only — pinning is owned by the typeclaw release.                                                                                                                                                                                                                                                                            |
-| `xvfb`        | no       | boolean           | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                             |
-| `claudeCode`  | no       | boolean           | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs.         |
-| `codexCli`    | no       | boolean           | Default `false`. `true` runs `bun install -g @openai/codex` in a dedicated layer (after `claudeCode`, before the entrypoint shim) and pre-writes `~/.codex/hooks.json` registering `SessionStart` + `Stop` hooks so the operator can detect turn boundaries the same way as Claude Code (sentinel files, `.session-id` discovery). Not apt: no version-pin variant. Codex CLI has NO theme picker so no onboarding seed is needed, but auth (`codex login` or `OPENAI_API_KEY`) and the per-project trust dialog are still required at runtime — handled by the `typeclaw-codex-cli` skill. |
-| `append`      | no       | array of strings  | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Field         | Required | Type                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tmux`        | no       | boolean \| string   | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `gh`          | no       | boolean \| string   | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `python`      | no       | boolean             | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                                   |
+| `ffmpeg`      | no       | boolean \| string   | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cjkFonts`    | no       | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes).                                                         |
+| `cloudflared` | no       | boolean             | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release. |
+| `xvfb`        | no       | boolean             | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                                     |
+| `claudeCode`  | no       | boolean             | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs.                 |
+| `codexCli`    | no       | boolean             | Default `false`. `true` runs `bun install -g @openai/codex` in a dedicated layer (after `claudeCode`, before the entrypoint shim) and pre-writes `~/.codex/hooks.json` registering `SessionStart` + `Stop` hooks so the operator can detect turn boundaries the same way as Claude Code (sentinel files, `.session-id` discovery). Not apt: no version-pin variant. Codex CLI has NO theme picker so no onboarding seed is needed, but auth (`codex login` or `OPENAI_API_KEY`) and the per-project trust dialog are still required at runtime — handled by the `typeclaw-codex-cli` skill.         |
+| `append`      | no       | array of strings    | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
 
@@ -631,7 +631,7 @@ Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitign
 - `channels.<adapter>.allow` (legacy) is silently ignored on parse and NOT translated to `roles.member.match`. Define `roles.member.match[]` directly. See the `typeclaw-permissions` skill.
 - If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
 - If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
-- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python`, `cjkFonts`, `cloudflared`, `claudeCode`, and `codexCli` are boolean only
+- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, and `codexCli` are boolean only
 - No unknown top-level keys you invented — keys outside the well-known ten are interpreted as **plugin config blocks** and only do something if a plugin owns them. Inventing one means the user thinks it took effect and it did not.
 
 ## Things you must not do

package/src/skills/typeclaw-kaomoji/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-kaomoji
-description: Load this skill when your `SOUL.md` (or the current conversation) calls for a warm, cute, adorable, playful, or affectionate tone — or when the user explicitly mentions kaomojis, 카오모지, ASCII emoticons, or asks you to "feel more like a person and less like a chatbot." TypeClaw's name puns on "Type" — typed emoticons fit. Triggers include the words "cute", "adorable", "warm", "playful", "soft", "cozy", "친근하게", "귀엽게", "다정하게", "카오모지", or any signal that the user is tired of generic AI emoji slop (🚀✨🎉) and wants real texture in your voice. This skill gives you a curated palette and the rule for using it: prefer kaomojis over generic emojis, but mix freely — kaomojis lead, emojis still allowed, neither is mandatory.
+description: Load this skill when your `SOUL.md` (or the current conversation) calls for a warm, cute, adorable, playful, or affectionate tone — or when the user explicitly mentions kaomojis, emoticons, or asks you to "feel more like a person and less like a chatbot." TypeClaw's name puns on "Type" — typed emoticons fit. Triggers include any-language requests for a "cute", "adorable", "warm", "playful", "soft", or "cozy" tone, or the word for kaomoji/emoticon in the user's language (e.g. English "kaomoji"/"emoticon", Korean "카오모지"/"친근하게"/"귀엽게"/"다정하게", Japanese "顔文字"/"かわいく", Chinese "颜文字"/"可爱", Spanish "emoticono"/"tierno"), or any signal that the user is tired of generic AI emoji slop (🚀✨🎉) and wants real texture in your voice. This skill gives you a curated palette and the rule for using it: prefer kaomojis over generic emojis, but mix freely — kaomojis lead, emojis still allowed, neither is mandatory.
 ---
 
 # typeclaw-kaomoji
@@ -111,6 +111,6 @@ These match common engineering moments — handy when you're in the middle of a
 - ❌ `(╬ Ò﹏Ó)` over a typo — register too strong for the moment.
 - ❌ Kaomoji in a commit message — wrong surface.
 
-## Korean / bilingual notes
+## Multilingual / bilingual notes
 
-Many of these read especially naturally in Korean conversation, where kaomojis are still in daily use (KakaoTalk, Discord, Twitter). If your user writes in Korean, leaning kaomoji-heavy is a clear win over generic emoji. If they write in English, dial back to roughly one per turn so it stays a personality note rather than a tic.
+Many of these read especially naturally in East Asian conversation (Korean, Japanese, Chinese), where kaomojis/顔文字/颜文字 are still in daily use on chat apps (KakaoTalk, LINE, Discord, Twitter/X). If your user writes in one of those languages, leaning kaomoji-heavy is a clear win over generic emoji. In languages where kaomojis are less common (e.g. most Latin-script chat), dial back to roughly one per turn so it stays a personality note rather than a tic. The rule is about the user's culture and tone, not any single language.

package/src/skills/typeclaw-tunnels/SKILL.md

@@ -111,7 +111,9 @@ Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to w
 
 ### `cloudflared` is not installed
 
-Both Cloudflare providers (`cloudflare-quick` and `cloudflare-named`) require `docker.file.cloudflared: true`. If it is missing, `typeclaw tunnel add` writes it automatically; otherwise add it to `typeclaw.json` by hand and run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+`docker.file.cloudflared` defaults to `false`, so a fresh image ships without the `cloudflared` binary. Both Cloudflare providers (`cloudflare-quick` and `cloudflare-named`) require `docker.file.cloudflared: true`. `typeclaw tunnel add` and `typeclaw channel add github` (with a Cloudflare provider) write it automatically; a hand-edited `typeclaw.json` must set it explicitly. After setting it, run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+
+If a tunnel is configured but the binary is missing, the tunnel goes **`permanently-failed`** and `typeclaw tunnel status` shows the detail `cloudflared binary not found in image; set docker.file.cloudflared: true in typeclaw.json and run typeclaw restart` — fix it the same way.
 
 ### Named tunnel says "permanently-failed" with `tokenEnv` in the detail
 

package/src/tui/banner.ts

@@ -0,0 +1,19 @@
+import { WORDMARK_LINES } from '@/shared/wordmark'
+
+import { colors } from './theme'
+
+export type BannerInfo = {
+  sessionId: string
+  serverVersion?: string
+  displayUrl: string
+}
+
+export function formatBanner({ sessionId, serverVersion, displayUrl }: BannerInfo): string {
+  const logo = WORDMARK_LINES.map((line) => colors.accent(line)).join('\n')
+  const version = serverVersion === undefined ? '' : colors.dim(` v${serverVersion}`)
+  const card = [
+    `${colors.accent('●')} ${colors.bold('session')}${version}  ${colors.dim(sessionId)}`,
+    `${colors.dim('  ')}${colors.dim(displayUrl)}`,
+  ].join('\n')
+  return `${logo}\n\n${card}`
+}

package/src/tui/format.ts

@@ -37,6 +37,40 @@ export function withTimestamp(ts: number | undefined, body: string): string {
   return `${formatTimestamp(ts)} ${body}`
 }
 
+// Open-box top rule for an assistant turn. Only a header (no closing rule) so
+// the look survives streaming Markdown whose end is unknown at render time.
+export function formatAssistantHeader(ts: number | undefined): string {
+  const clock = plainTimestamp(ts)
+  const label = `╭─ typeclaw · ${clock} `
+  return colors.accent(`${label}${'─'.repeat(ASSISTANT_HEADER_RULE_WIDTH)}`)
+}
+
+const ASSISTANT_HEADER_RULE_WIDTH = 8
+
+function plainTimestamp(ts: number | undefined): string {
+  if (ts === undefined || ts === 0) return '--:--:--'
+  const d = new Date(ts)
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  const ss = String(d.getSeconds()).padStart(2, '0')
+  return `${hh}:${mm}:${ss}`
+}
+
+export function formatTokenCount(tokens: number): string {
+  if (tokens < 1000) return `${tokens}`
+  const k = tokens / 1000
+  const value = k < 100 ? k.toFixed(1) : String(Math.round(k))
+  return `${value.endsWith('.0') ? value.slice(0, -2) : value}k`
+}
+
+export function formatCost(cost: number): string {
+  return `$${cost.toFixed(4)}`
+}
+
+export function formatUsageSummary(usage: { totalTokens: number; cost: number }): string {
+  return `⚡ ${formatTokenCount(usage.totalTokens)} tok · ${formatCost(usage.cost)}`
+}
+
 function stripHiddenBlocks(text: string): string {
   return text.replace(/<hatching>[\s\S]*?<\/hatching>\s*/g, '').trimStart()
 }