feat(cli): add one-shot user commands - #3210
Conversation
📝 WalkthroughSummaryThis PR adds Codex-style The implementation extends the existing Runtime Resource, session-driver, transcript, and client-inspection paths. It does not create a separate command execution system. User commands use The solution is the smallest coherent path shown by the diff. It reuses shell-run resources and existing update handling. The added race handling is necessary because terminal updates can arrive before the local transcript card exists. The new protocol validation and caller checks are necessary to enforce command bounds and access restrictions. Complexity delta
No test or implementation area is clearly removable without weakening regression coverage. The total maintenance complexity increases, but the increase is justified by the new user-command behavior, access boundary, protocol validation, and race-replay requirements. ValidationThe reported validation includes package builds, CLI, Runtime, and Runtime Host suites, formatting, lint, and diff checks. Additional tests cover command routing, no-agent-turn behavior, transcript projection, raced update replay, caller restrictions, client inspection, protocol bounds, and Runtime Host launch parameters. The final check status remains subject to independent verification. Review-relevant risks
The person performing the merge must review the final diff. A maintainer makes the final determination. WalkthroughThe PR adds ChangesOne-shot user command flow
Estimated code review effort: 4 (Complex) | ~45 minutes Merge Risk: 🔵 Low · up to The PR adds one-shot user commands, but completed commands can currently produce an extra background-task notice in addition to their local result card. This creates bounded duplicate or misleading TUI output; the change is otherwise mergeable with explicit owner follow-up to suppress that notice and cover the behavior with a test. Suggested reviewers: Sequence Diagram(s)sequenceDiagram
participant TUI
participant SessionDriver
participant RuntimeHost
participant Runtime
TUI->>SessionDriver: runUserCommand(command)
SessionDriver->>RuntimeHost: runtime.resource.start(command)
RuntimeHost->>Runtime: create user-visible shell run
Runtime-->>RuntimeHost: snapshot and shell-run update
RuntimeHost-->>SessionDriver: command result and raced update
SessionDriver-->>TUI: local transcript card data
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
PR Summary by QodoAdd Runtime Host-backed one-shot user commands to the TUI
AI Description
Diagram
High-Level Assessment
Files changed (16)
|
Code Review by Qodo
1. Reconnect erases command cards
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
76f6a88 to
313edbb
Compare
me2seeks
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/runtime/src/shell-run-contract.ts (1)
74-75: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReuse the canonical visibility type.
Use
ShellRunVisibilityfrompackages/core/src/shell-run.tshere. The literal union duplicates the persisted visibility authority. A later visibility change can otherwise create a contract mismatch.Disposition: optional.
As per path instructions, consolidate duplicated authority and reuse the closest existing seam.
Source: Path instructions
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ab21c065-4510-4f86-b3a6-a9717fa3999f
📒 Files selected for processing (16)
packages/cli/src/__tests__/pi-transcript.test.tspackages/cli/src/__tests__/pi-tui-runner.test.tspackages/cli/src/__tests__/runtime-host-session-driver.test.tspackages/cli/src/pi-transcript.tspackages/cli/src/pi-tui-runner.tspackages/cli/src/runtime-host-session-driver.tspackages/cli/src/session-driver.tspackages/cli/src/tui-primary-guidance.tspackages/core/src/shell-run.tspackages/runtime-host/src/__tests__/runtime-resource-coordinator.test.tspackages/runtime-host/src/__tests__/runtime-resource-protocol.test.tspackages/runtime-host/src/protocol/runtime-resource.tspackages/runtime-host/src/server/runtime-resource-coordinator.tspackages/runtime/src/__tests__/shell-run-manager.test.tspackages/runtime/src/shell-run-contract.tspackages/runtime/src/shell-run-manager.ts
Included review availability: Your plan includes up to 3 reviews per rolling hour; 0 remain after this review.
|
Code review by qodo was updated up to the latest commit 313edbb |
Astro-Han
left a comment
Astro-Han
left a comment
There was a problem hiding this comment.
The core direction is sound: Runtime Host remains the sole execution and resource-lifecycle authority, and the CLI adds only a local projection. I found three concrete lifecycle/projection gaps that should be addressed before merge: commands have no cancellation or close-time cleanup, reconnect discards their only UI projection, and terminal updates reuse the model-background-task notice. The smallest design is to keep Runtime Host authoritative while having the CLI retain active user-command refs, stop them through the existing client-owned resource API, and reconstruct their cards from user-visible resource snapshots after reconnect.
AI-assisted review: Codex coordinated two independent reviewer passes and an OpenCode Go DeepSeek V4 Flash high-effort adversarial pass. I verified these findings against exact head 313edbbcf18f961714c116ebb21669f313e299cb, the relevant call paths, and current CI. No local tests were run in this review.
中文审查
整体方向正确：执行权和资源生命周期仍由 Runtime Host 统一负责，CLI 只增加本地投影。当前有三个需要修复的具体缺口：用户命令没有取消或退出清理路径；重连会删除唯一的 UI 卡片；终态更新会错误复用模型后台任务通知。最小方案是不新增执行权，而是让 CLI 保存活跃 user-command ref，通过已有 client-owned resource stop API 清理，并在重连后从用户可见资源快照重建卡片。
本次为 AI 辅助审查：Codex 协调两轮独立 reviewer 审查及 OpenCode Go DeepSeek V4 Flash high 对抗性复核，并核验了精确 head、相关调用链和当前 CI。本轮未运行本地测试。
|
This PR adds a new user-visible TUI flow. Could you please add a screenshot showing a ! command in the idle TUI and the resulting User command card, including its completed output state? One annotated screenshot is fine. Thanks! Posted by Codex on behalf of Astro-Han. |
|
Added the requested screenshot to the PR body. It shows an idle |
313edbb to
2c65cc5
Compare
Astro-Han
left a comment
Astro-Han
left a comment
There was a problem hiding this comment.
The current-head rereview confirms that the prior teardown, same-session reconnect, and duplicate-settlement findings are fixed. The actual terminal capture also matches the current UX: completed user commands are expanded by default and the bare ! hint is visible. All six commits carry Generated-by: Codex, and the PR body discloses the substantive scope.
One nonduplicate session-transition P2 remains below. Exact-head CI has not run yet because the Apache Actions lanes are still queued/unavailable, so this head is not merge-ready independently of the finding.
AI-assisted review by OpenAI Codex. I verified the range-diff from the previously reviewed head, lifecycle and projection paths, existing threads, current screenshot, provenance, and live check state.
中文
当前 head 已修复上一轮的退出清理、同 Session 重连和重复终态通知问题；真实终端截图也与当前 UX 一致。6 个提交均保留 Generated-by: Codex，PR body 的 AI 披露完整。
下面仍有一个新的 Session 切换 P2。当前 exact-head CI 还没有实际运行，因此即使不考虑 finding，也尚不可合并。
本次由 OpenAI Codex 辅助，已核对上一轮 head 的 range-diff、生命周期与投影路径、已有线程、截图、来源披露和实时检查状态。
3225392 to
787ad6a
Compare
Astro-Han
left a comment
Astro-Han
left a comment
There was a problem hiding this comment.
COMMENT. One P1 that I think blocks the merge, plus four smaller findings and a contract question.
Scope note first: I reviewed this at 787ad6aae, after the rebase and the fix(cli): stop user commands before leaving their Session commit. The start-barrier and stop-generation machinery in stopUserCommands is a real improvement over the previous head, and the two threads I opened earlier — cancellation/teardown at runtime-resource-coordinator.ts:352 and stop-on-session-change at runtime-host-session-driver.ts:355 — are both genuinely addressed. Two of the findings below are residuals of those fixes rather than repeats of them.
The P1 is the compatibility epoch. This PR widens runtime.resource.start's input to accept command and leaves RUNTIME_HOST_COMPATIBILITY_EPOCH at 27, which is what main has, so a new CLI and an old remote Runtime Host still shake hands and then fail on the first ! command. Details inline. The same PR also adds visibility to the durable ShellRunRecord (packages/core/src/shell-run.ts:117, key set at :305), which an older binary reading the same workspace operational-state DB rejects as a malformed field — and listSessionShellRuns maps over the whole session, so one such row takes out that session's entire shell-run projection. Same root cause, same fix.
Two things I could not confirm and am not filing:
- The close path.
beginClose(pi-tui-runner.ts:695-704) firesvoid input.driver.stop().catch(() => {})and returns, so/exitwith a running!sleep 3600does not await theruntime.resource.stopbefore the caller tears the connection down, andbeginCloseskipsdriver.stop()entirely wheninterruptRequestedis already set. Against a managed host that leaves the command running and holding amaxLiveShellRunsslot. I am reasonably confident this is real but I could not construct the failure end to end at this head, so I am recording it as an observation on the existing teardown thread rather than as a numbered finding. - Whether
runtime.resource.startbeing inREMOTE_OWNER_OPERATION_GRANTSis a privilege change. I do not think it is — a remote owner could already start the login-shell PTY, acquire a controller and type anything into it — but the new surface is non-interactive and scriptable, which is a different exposure profile. An explicit "no new privilege" line in the PR body would settle it.
Test gaps, none of which I am giving a P level:
runtime-resource-coordinator.test.ts'sstarts a one-shot user command in pipes without exposing it to the modelasserts only theShellRunBashInputhanded to a fakerunBackgroundBash; the harness'sreadRuntimeResourcehas no visibility gate, so the test cannot prove non-exposure. The real coverage is inshell-run-manager.test.ts; the name overclaims.stops a running user command before switching Sessions (#3210)asserts that aruntime.resource.stopexists in the request log, not that it preceded the identity change — which is the actual claim.UserCommandDriverinpi-tui-runner.test.tsreturnsstatus: 'completed'fromrunUserCommand, so the running-to-terminal card transition is never exercised in the runner suite.- The PR body's "removes
/shell" is stale: neither/shellnoropenInteractiveShellexists onmainor in this diff.
biome format is clean on every changed TS file at this head.
AI disclosure: this review was assisted by Claude (Opus), which performed the initial code search and cross-checking. Every finding published here I re-derived myself against the source at 787ad6aae, and I dropped the ones I could not confirm at that head — the two observations above are marked as such rather than filed.
Generated-by: Codex
Generated-by: Codex
Show localized privacy and Ctrl+O guidance while the editor contains only the user-command prefix. Generated-by: Codex
Keep the inline guidance concise while separating input, privacy, and output expansion. Generated-by: Codex
Keep privacy details in help and show only immediate editor actions inline. Generated-by: Codex
Reserve Ctrl+O for model tool cards and show user-invoked command output by default. Generated-by: Codex
Session switches (/session, rewind) and /new replace the transcript, which dropped the only projection of a running user-owned command and disabled its Ctrl+C stop affordance while the command kept running invisibly. Await the start-barrier-aware stop path in switchSession before changing Session identity, and trigger the same synchronous generation bump in startNewSession so in-flight starts self-stop. Add running-command → switch and running-command → /new regressions. Generated-by: Codex
…rt input - Bump RUNTIME_HOST_COMPATIBILITY_EPOCH to 29: runtime.resource.start now accepts an optional one-shot command and the durable Shell Run record carries visibility, so a pre-widening peer must be refused at admission instead of failing on the first ! command. - switchSession awaits stopUserCommands before the durable cwd relocation, so a rejecting stop aborts the switch with nothing committed rather than stranding a half-switched Session. - driver.stop() stops user commands best-effort so a rejecting runtime.resource.stop is never reported as a failed turn interrupt. - A rejected Ctrl+C user-command stop disarms the capture so the next press returns to the exit chord instead of being swallowed forever. - Same-session reconnect re-inserts preserved user-command cards at their chronological position instead of the transcript tail. - Scope visibility: "user" to command-carrying starts; the Desktop interactive login shell keeps its prior model-visible behavior. Generated-by: Maka
d7552f7 to
a87fc52
Compare
|
Rebased onto current main; new head
Everything else from the 2026-08-20 11:31 review is unchanged from 中文说明已 rebase 到最新 main；epoch 因 main 占用 28 而推进到 29，gate 测试改为相对断言，tip 提交补上合规的 Generated-by trailer。本地套件全绿。11:31 review 的全部修复保持不变，等待重新 review。 |
2 participants
Summary
Adds a Codex-style
!<command>interaction to the idle TUI. It runs one command through Runtime Host in the current Session workspace, keeps the TUI rendering, and shows the result as a local user-command card. It does not create an agent turn. User-command output is expanded by default;Ctrl+Oremains the toggle for model tool cards.Runtime boundary. Runtime Host remains the execution and resource-lifecycle authority. Only one-shot
!<command>resources are stored withvisibility: "user"; Runtime rejects model reads of those resources with the same non-disclosing not-found result used for inaccessible resources. The Desktop-owned interactive login shell carries nocommandand keeps its prior model-visible behavior. Client resource projections can still display the command output.Protocol compatibility.
runtime.resource.startnow accepts an optional one-shotcommand, and the durable Shell Run record carriesvisibility.RUNTIME_HOST_COMPATIBILITY_EPOCHmoves to 28 so a pre-widening peer is refused at admission instead of failing on the first!command.Privilege.
runtime.resource.startwas already inREMOTE_OWNER_OPERATION_GRANTSfor the interactive login shell; this PR adds no new grant. The new command-carrying surface reuses the existing owner grant — no new privilege.Ordering boundary. The CLI starts observing the resource before
runtime.resource.start, merges updates by revision, and applies a terminal update that arrived before the local card was created. There is no second executor or CLI-owned shell lifecycle.Fixes #3209
中文说明（实现与架构边界）
TUI 空闲时输入
!<command>会由 Runtime Host 在当前 Session 工作目录执行一次命令。TUI 不会暂停渲染，也不会接管交互式 PTY。命令结果以仅本地的“User command”卡片展示，不创建 agent turn。用户命令输出默认展开；Ctrl+O继续只控制模型工具卡片。运行时边界。 Runtime Host 继续拥有命令执行、资源生命周期和 Session 工作目录。只有一次性
!<command>资源标记为visibility: "user"：Runtime 会拒绝模型通过资源引用读取它，并使用非披露的 not-found 结果；Desktop 的交互登录 shell 不携带command，保持原有的模型可见行为。客户端资源投影仍可展示输出。协议兼容。
runtime.resource.start新增可选的一次性command字段，持久化的 Shell Run 记录新增visibility。RUNTIME_HOST_COMPATIBILITY_EPOCH升至 28，旧版本对端会在准入阶段被拒绝，而不是在第一条!命令上失败。权限。
runtime.resource.start本就在REMOTE_OWNER_OPERATION_GRANTS中（交互登录 shell 已在使用）；此 PR 不新增任何授权，新表面复用既有 owner 权限。顺序边界。 CLI 在发起资源前开始观察同一命令资源，按 revision 合并更新，并在创建卡片后回放已经到达的终态更新。因此快速命令不会因“先完成、后建卡”而丢失输出。此 PR 不新增第二个执行器，不改变模型 Bash 的权限或上下文语义。
Verification
maka-agentCLI suite passed.@maka/core,@maka/runtime,@maka/runtime-host, andmaka-agent.git diff --check.!<command>routing, default-expanded user-command output,Ctrl+Oisolation from user-command cards, pre-card terminal-update replay, Runtime model-read rejection ofvisibility: "user"resources, client inspection, protocol bounds, epoch-28 gating of the widened start input, stop-before-switch aborting without a durable relocation, turn-interrupt isolation from user-command stop failures, Ctrl+C exit-chord recovery after a rejected stop, chronological re-insertion of preserved cards on reconnect, and transcript projection.AI use
Select exactly one:
Tool(s) and scope: Codex prepared the implementation, tests, Issue, and PR description. The human contributor reviews the diff and remains responsible for submission, correctness, provenance, and licensing.
Checklist
Does this PR entail a change in behavior?
Visual evidence
Live terminal capture from exact feature head
ecfa72feb: completed user commands show their real output expanded by default, without pressingCtrl+O, while a bare!shows the localized inline prompt. The capture uses the local Runtime Host and Chinese TUI locale.基于功能分支精确 head
ecfa72feb的真实终端截图：用户命令完成后无需按Ctrl+O即默认展开真实输出；输入裸!时同时显示本地化提示。截图使用本地 Runtime Host 和中文 TUI。