feat(tui): animate terminal title while agent is busy - #2238
Conversation
Prefix the terminal title with a spinner while a turn is streaming or compacting, so progress stays visible on the terminal tab even when the window is unfocused. The style is chosen once via KIMI_TITLE_SPINNER (moon by default; also sparkle, braille, orbit, pulse, line, hourglass, a state-mapped phase, and off to disable).
🦋 Changeset detectedLatest commit: e9d4666 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f51f495936
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| private syncTerminalTitleSpinner(): void { | ||
| const busy = this.state.appState.streamingPhase !== 'idle' || this.state.appState.isCompacting; |
There was a problem hiding this comment.
This block makes KimiTUI own environment resolution, timer lifecycle, frame selection, and title rendering even though the behavior is self-contained and independently testable. Move this state machine into a controller with observable title/timer tests, leaving the coordinator responsible only for syncing and disposing it.
AGENTS.md reference: apps/kimi-code/AGENTS.md:L38-L39
Useful? React with 👍 / 👎.
| this.tasksBrowserController.close(); | ||
| this.btwPanelController.clear(); | ||
| this.stopActivitySpinner(); | ||
| this.stopTerminalTitleSpinner(); |
There was a problem hiding this comment.
When double Ctrl-D or SIGTERM invokes stop() while a turn or compaction is active, this only clears the interval and leaves its last animated frame as the terminal title. Neither TUI.stop() nor ProcessTerminal.stop() replaces the title, so terminals whose shells do not set their own prompt title continue to display a stale busy indicator after Kimi exits; write the static title before terminal teardown.
Useful? React with 👍 / 👎.
| readonly interval: number; | ||
| } | ||
|
|
||
| export const TITLE_SPINNER_ENV = 'KIMI_TITLE_SPINNER'; |
There was a problem hiding this comment.
The repository's English and Chinese environment-variable references present themselves as the complete list of runtime variables, but KIMI_TITLE_SPINNER and its supported values appear only in the implementation and this release changeset. Once the release entry is no longer prominent, users cannot discover how to select a style or disable the new default animation; add the variable and accepted values to both mirrored configuration/env-vars.md pages.
Useful? React with 👍 / 👎.
| const id = raw?.trim().toLowerCase(); | ||
| if (id === OFF_TITLE_SPINNER_ID) return OFF_TITLE_SPINNER_ID; | ||
| if (id === PHASE_TITLE_SPINNER_ID) return PHASE_TITLE_SPINNER_ID; | ||
| if (id !== undefined && id in TITLE_SPINNER_STYLES) return id; |
There was a problem hiding this comment.
When KIMI_TITLE_SPINNER is set to an inherited object key such as constructor, toString, or __proto__, the in check accepts it as a valid style instead of falling back to moon. On the first busy transition, the inherited function/object has no frames, so frameTerminalTitle() throws and crashes the TUI; use an own-property check or a null-prototype registry.
Useful? React with 👍 / 👎.
Address review feedback on MoonshotAI#2238: - Move the title animation state machine (style resolution, timer, frame selection, rendering) out of KimiTUI into TerminalTitleSpinnerController; the coordinator now only syncs and disposes it. - Restore the static title on dispose so a busy indicator is not left behind when exiting mid-turn (Ctrl-D / SIGTERM). - Guard the spinner registry with an own-property check so inherited keys (constructor, toString, ...) fall back to the default instead of crashing. - Document KIMI_TITLE_SPINNER in the EN/ZH env-vars references.
|
感谢审查！四条建议已在 a33e03c 中全部处理：
验证：typecheck、oxlint 通过；单元测试与相关集成测试（221 例）全部通过。 |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a33e03cb7e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `KIMI_MODEL_THINKING_KEEP` | 保留思考透传；在 `kimi` 上以 `thinking.keep` 发送，在 `anthropic`（Claude 以及 Kimi 的 Anthropic 兼容模式）上以 `context_management` 的 `clear_thinking_20251015` 编辑发送（开启 keep 会让 Anthropic 请求走 beta Messages API）；覆盖 `[thinking] keep`（其默认值为 `"all"`）；仅在 Thinking 开启时注入 | API 接受的值，如 `all`；传入关值（`false`/`0`/`no`/`off`/`none`/`null`）可禁用 | | ||
| | `KIMI_CODE_NO_AUTO_UPDATE` | 完全禁用更新预检——不检查、不后台安装、不提示。同时兼容旧名 `KIMI_CLI_NO_AUTO_UPDATE` | 真值：`1`/`true`/`yes`/`on` | | ||
| | `KIMI_DISABLE_CRON` | 禁用定时任务工具（`CronCreate` 拒绝新计划，已有任务不触发） | `1` 表示禁用 | | ||
| | `KIMI_TITLE_SPINNER` | agent 忙碌时让终端标题动起来，使工作状态在终端标签页上可见；空闲时恢复静态标题 | `moon`（默认）、`sparkle`、`braille`、`orbit`、`pulse`、`line`、`hourglass`、`phase`（显示 streaming 相位而非旋转）、`off`（不动画）；未知值回退到 `moon` | |
There was a problem hiding this comment.
For Chinese readers, this new row spells the repository-defined Chinese term as lowercase agent; the documentation term table requires Agent in Chinese, so capitalize it to keep terminology consistent across the locale.
AGENTS.md reference: docs/AGENTS.md:L69-L69
Useful? React with 👍 / 👎.
| setTitle: (label) => this.state.terminal.setTitle(label), | ||
| staticTitle: () => { | ||
| const trimmed = this.state.appState.sessionTitle?.trim() ?? ''; | ||
| return trimmed.length > 0 ? trimmed.slice(0, MAX_TERMINAL_TITLE_LENGTH) : PRODUCT_NAME; |
There was a problem hiding this comment.
When a session title already reaches MAX_TERMINAL_TITLE_LENGTH (32), this callback returns all 32 characters and frameTitle() or phaseTitle() then prepends a glyph and space, producing a title longer than the repository's stated bound. Reserve space for the prefix or truncate the final composed title so long session names do not defeat the readability cap while busy.
Useful? React with 👍 / 👎.
| this.timer ??= setInterval(() => { | ||
| this.frame = (this.frame + 1) % style.frames.length; | ||
| this.host.setTitle(this.frameTitle(style)); | ||
| }, style.interval); |
There was a problem hiding this comment.
When a KimiTUI test leaves the app busy, this referenced interval outlives the test because the shared makeDriver() fixture in kimi-tui-message-flow.test.ts creates drivers while its afterEach never calls stop() or titleSpinner.dispose(); for example, the reload test starts a request and then directly mutates streamingPhase, bypassing spinner synchronization. As the suite progresses, these timers retain each driver and continuously write OSC titles, accumulating work and polluting test output, so register fixture teardown or disable the spinner in the suite environment.
Useful? React with 👍 / 👎.
- Use the required capitalized Agent spelling in the zh env-vars doc. - Keep composed spinner and phase titles within MAX_TERMINAL_TITLE_LENGTH so long session titles do not defeat the readability cap while busy. - Guard PHASE_TITLE_GLYPHS with an own-property check, matching the spinner registry hardening. - Dispose title-spinner timers in the message-flow test fixture and silence setTitle writes so intervals and OSC output do not leak across tests.
|
第二轮审查意见已在 70e0c0c 中处理：
另外顺手加固了 验证：spinner 相关 18 个测试、message-flow 162 个测试、其余 4 个 KimiTUI 套件 104 个测试全部通过， |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 70e0c0c024
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| return title.length > MAX_TERMINAL_TITLE_LENGTH | ||
| ? title.slice(0, MAX_TERMINAL_TITLE_LENGTH) | ||
| : title; |
There was a problem hiding this comment.
When the composed title crosses the cap immediately inside a surrogate pair—for example, the line style with a title of 29 ASCII characters followed by an emoji—slice(0, 32) retains only the emoji's high surrogate, so the terminal tab displays a replacement character instead of the intended title. Truncate on a Unicode code-point or grapheme boundary while reserving room for the spinner prefix.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
已在 a0152d8 修复：fitTitle() 截断时用 codePointAt 检查切点，若跨越边界的码点大于 U+FFFF（即 surrogate pair 被切半）就回退一个单元；补了 emoji 正好落在截断边界的回归测试。静态标题路径的 slice 保持上游既有行为不变。
fitTitle() sliced on raw UTF-16 units, so a composed title crossing the cap inside a surrogate pair (e.g. an emoji right at the boundary) kept a lone high surrogate and rendered as a replacement character on the terminal tab. Back up one unit when the code point at the cut straddles the cap; regression test covers the emoji-at-boundary case.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0152d8719
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `KIMI_MODEL_THINKING_KEEP` | 保留思考透传；在 `kimi` 上以 `thinking.keep` 发送，在 `anthropic`（Claude 以及 Kimi 的 Anthropic 兼容模式）上以 `context_management` 的 `clear_thinking_20251015` 编辑发送（开启 keep 会让 Anthropic 请求走 beta Messages API）；覆盖 `[thinking] keep`（其默认值为 `"all"`）；仅在 Thinking 开启时注入 | API 接受的值，如 `all`；传入关值（`false`/`0`/`no`/`off`/`none`/`null`）可禁用 | | ||
| | `KIMI_CODE_NO_AUTO_UPDATE` | 完全禁用更新预检——不检查、不后台安装、不提示。同时兼容旧名 `KIMI_CLI_NO_AUTO_UPDATE` | 真值：`1`/`true`/`yes`/`on` | | ||
| | `KIMI_DISABLE_CRON` | 禁用定时任务工具（`CronCreate` 拒绝新计划，已有任务不触发） | `1` 表示禁用 | | ||
| | `KIMI_TITLE_SPINNER` | Agent 忙碌时让终端标题动起来，使工作状态在终端标签页上可见；空闲时恢复静态标题 | `moon`（默认）、`sparkle`、`braille`、`orbit`、`pulse`、`line`、`hourglass`、`phase`（显示 streaming 相位而非旋转）、`off`（不动画）；未知值回退到 `moon` | |
There was a problem hiding this comment.
streaming phase label
For Chinese readers selecting phase, the phrase streaming 相位 introduces an untranslated technical term that is not explained anywhere on this page. Replace it with a clear Chinese description such as 流式输出阶段, or add a first-use gloss, as required by the documentation jargon rule in docs/AGENTS.md.
AGENTS.md reference: docs/AGENTS.md:L44-L44
Useful? React with 👍 / 👎.
Replace the untranslated `streaming 相位` phrase with 流式输出阶段 per the jargon rule in docs/AGENTS.md.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 64d2a4b310
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const codePoint = title.codePointAt(end - 1); | ||
| if (codePoint !== undefined && codePoint > 0xffff) end -= 1; | ||
| return title.slice(0, end); |
There was a problem hiding this comment.
When an animated title crosses the cap inside a multi-code-point grapheme, this check preserves individual surrogate pairs but still splits the displayed character. For example, a 28-character ASCII prefix followed by 🇨🇳 is exactly 32 UTF-16 units as a static title; adding the spinner causes slice(0, 32) to retain only 🇨, so the flag changes or renders incorrectly. Fresh evidence beyond the earlier surrogate-pair report is that complete code points can still form one grapheme; truncate using grapheme boundaries rather than only detecting a straddling surrogate pair.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
已在 e9d4666 修复：改用 Intl.Segmenter（grapheme 粒度）按字位簇边界截断，多码点字符（旗帜、ZWJ 序列）整体丢弃而非切半——与仓库里 goal-queue-manager / session-picker 等 TUI 组件的既有写法一致；补了旗帜 emoji 落在截断边界的回归测试。
The surrogate-pair check kept individual pairs intact but still split multi-code-point graphemes (flags, ZWJ sequences) straddling the cap, rendering half a flag on the terminal tab. Truncate with a shared Intl.Segmenter grapheme iterator — the same idiom other TUI components use — so over-long clusters are dropped whole; regression test covers a flag emoji at the boundary.
1 participant
相关 Issue
Implements #1885
提交后才发现 @ColorC 已在 #1885 中更早、更完整地提出了相同需求（含参考补丁与 Claude Code 先例）。本 PR 可作为 #1885 的一个完整实现供讨论；不使用自动关闭关键字，关闭与否留给维护者决定。我此前另开的 #2239 与之重复，已标记为重复并关闭。
问题
当 agent 在后台长时间工作（多轮 goal、大型重构、跑测试）时，如果终端窗口不在前台，用户无法只凭终端标签页判断它"还在干活"还是"已经完成 / 卡住"。当前终端标题只显示静态会话标题，缺少一个轻量的工作状态指示。
改动内容
在 agent 忙碌期间（turn 流式输出或上下文压缩时），给终端标题加上一个转动的图形前缀，让用户即使不看窗口、只瞥一眼终端标签页也能知道 agent 正在工作；空闲时自动恢复为原来的静态标题。
设计遵循三个原则：
apps/kimi-code/src/tui/constant/title-spinners.ts，每个样式是注册表里一条独立记录，增删任一样式互不影响；kimi-tui.ts只负责定时器编排。setTitle()（OSC 0）与会话标题逻辑，原有静态标题行为完整保留；只在setAppState已有的busyChanged分支和关闭清理处各新增一个调用点。setInterval，且仅在忙碌时运行，每次 tick 只向 stdout 写一小段转义序列。phase样式直接由 streaming phase 推导图形、完全不开定时器；off则完全不改变现有行为。样式通过环境变量
KIMI_TITLE_SPINNER选择（启动时解析一次）：moon（默认）sparklebrailleorbitpulselinehourglassphaseoff验证
test/tui/constant/title-spinners.test.ts（样式解析与注册表不变量，7 个用例全部通过）。pnpm --filter @moonshot-ai/kimi-code run typecheck通过。oxlint --type-aware对新增 / 修改文件 0 警告 0 错误。editor-keyboard-image-paste因本机 CPU 争用偶发超时，单独运行稳定通过，与本改动无关）。Checklist
gen-changesets（新增一个 patch changeset）。KIMI_TITLE_SPINNER的使用说明可作为后续独立 PR 补充。