@itookit/dsht 0.3.4 → 0.3.8

package/README.i18n.yaml

@@ -1,3 +1,3 @@
 # Git blob hashes of the reviewed bilingual pair.
-README.md: fea06c629ad8eb11b815d375d3bbcf4fc5451dd3
-README.zh.md: f9209f005a9c78bd2db19e0c1bbb59a6603ad7e9
+README.md: ce72e2f65a0834f3c58925ab907a5ad39653eca1
+README.zh.md: 432aea7bb61f908845055aa06a1779156ad33258

package/README.md

@@ -166,7 +166,7 @@ npm start
 
 Both paths read the same `DSH_URL` and `DSH_TOKEN` variables.
 
-Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in, and appears only while the host does not already have it; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Creating a session requires a selected workspace.
+Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in, and appears only while the host does not already have it; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Starting inside a registered workspace directory selects that workspace instead of showing the picker, with `←` in the session list switching to another; a session id passed on the command line still opens directly. Creating a session requires a selected workspace.
 
 On first login, authentication exchanges the token at `GET /` and saves the cookie per HTTP origin. Later starts, including list commands, reuse that cookie without a token. The store uses `$XDG_STATE_HOME/dsht/auth`, or `~/.local/state/dsht/auth` when unset; `--auth-dir` or `DSHT_AUTH_DIR` overrides it. POSIX directories use 0700 and cookie files use 0600; Windows uses the account directory's inherited access controls. Launch tokens are never saved.
 
@@ -297,7 +297,8 @@ In `/ws` and `/resume` pickers, every row reports one of three user-visible stat
 
 `/search` matches literal text case-insensitively in conversation messages, including older pages; tool-only rows are excluded. Search scans up to 80 messages per request, discards each temporary page, and retains at most 200 short matches, including folded reasoning. A truncated result asks you to refine the query. Opening a match loads a separate page around its sequence; `/latest` releases that window. Esc or Ctrl+C cancels the search. A rare or absent term still requires scanning the full history over HTTP; there is no server-side full-text index for this command. `/history` lists your own prompts from the loaded pages. Record sequences are the numbers shown by these pickers. `/ssearch` and `/wsearch` call `session/search`, which searches current user/assistant message content and returns at most 20 sessions, snippets, and a truncation flag; it exposes neither a result cursor nor matching record sequences. Workspace filtering happens after that global limit, so a truncated workspace result can omit matches. The UI warns when results are incomplete; refine the query. Selecting a session loads its history and offers matching messages for the jump. These operations use HTTP and never scan the host configuration directory.
 
-↑/↓ or Ctrl+P/N recalls previously submitted prompts and slash commands without sending them; Enter submits the recalled text. A reading panel that fits the screen leaves the arrows with this history, a panel that has to scroll takes them for itself, and Ctrl+P/N reach the history from any panel. Moving past the newest entry restores the unsent draft. Editing recalled text starts a new draft. Recall keeps up to 200 entries and approximately 256 KiB of text for the selected session. Opening or restoring a session seeds recall from its already-loaded User messages; switching sessions releases the previous recall buffer. It does not fetch older pages or write a separate history file. Consecutive duplicates are merged, oversized entries are skipped, and question or approval answers are excluded. Question options and completion menus keep arrow navigation; workspace/session lists use arrows when the composer is empty, with Ctrl+P/N available for recall.
+↑/↓ or Ctrl+P/N recalls previously submitted prompts and slash commands without sending them; Enter submits the recalled text. A reading panel that fits the screen leaves the arrows with this history, a panel that has to scroll takes them for itself, and Ctrl+P/N reach the history from any panel. Moving past the newest entry restores the unsent draft. Editing recalled text starts a new draft, and switching sessions clears an unsent one. Recall keeps the selected session's user prompts — up to 2,000 entries and approximately 512 KiB of text — and never writes a separate history file; switching sessions releases them. It folds those prompts from the session records as they arrive, so it covers prompts from before this client connected rather than only the window that happened to load. Opening a session also walks the earlier history in the background, keeping only prompts rather than loading those pages into the conversation, so the whole session's prompt list is available from the start. Reaching its oldest retained prompt first refills from the already-loaded conversation at no request cost, and only then fetches the page before the window, inside one bounded loop that skips tool-only pages so the key cannot stall; the fetched page also stays in the conversation above the composer. Eviction therefore bounds memory without deciding reachability: an evicted prompt is either still loaded or still on the host. Consecutive duplicates are merged, oversized entries are skipped, and question or approval answers are excluded. Question options and completion menus keep arrow navigation; workspace/session lists use arrows when the composer is empty, with Ctrl+P/N available for recall.
+`!command` runs that command on the machine this client is on — not on the host the agent works in — and prints the command and its output inline in the conversation, where it stays in place and scrolls away with the history; nothing is sent to the model and nothing is written to disk. Output is capped at 200 lines and 64 KiB per command, only the last 20 commands are kept, and the number of dropped lines is stated in the block. One command runs at a time; Esc, or Ctrl+C on an empty prompt, stops it by killing its whole process group, so pipelines and background children die with it; a command that needs a terminal of its own, such as `vim`, cannot work. `--no-shell` or `DSHT_NO_SHELL=1` disables the prefix.
 
 Within each User group, only the first assistant prose or reasoning message shows an Assistant heading. Later messages and live output reuse that heading across tool results and Context messages. A newly loaded history window starts its own visible group; message sequences, tool status, search, and reasoning expansion remain independent.
 
@@ -426,7 +427,7 @@ This repository publishes one public package, `@itookit/dsht`, from the `mushuan
 
 | Field | Value |
 | --- | --- |
-| Name and version | `@itookit/dsht` `0.3.4` |
+| Name and version | `@itookit/dsht` `0.3.8` |
 | Executable | `dsht`, or `npx @itookit/dsht` without installing |
 | Library entries | `@itookit/dsht` and `@itookit/dsht/auth` |
 | Author | lizlok@gmail.com |

package/README.zh.md

@@ -166,7 +166,7 @@ npm start
 
 两种方式读取相同的 `DSH_URL` 和 `DSH_TOKEN` 变量。
 
-使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录，只在服务端尚未注册它时出现；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。新建会话前必须选择工作区。
+使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录，只在服务端尚未注册它时出现；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。在已注册的工作区目录里启动时，直接选中该工作区而不再显示选择器（会话列表里的 `←` 仍可切到别的工作区）；命令行给出会话 ID 时依旧直接打开。新建会话前必须选择工作区。
 
 首次登录通过 `GET /` 兑换 token，并按 HTTP origin 保存 cookie。后续启动和列表命令自动复用 cookie，无需再次提供 token。默认目录为 `$XDG_STATE_HOME/dsht/auth`，未设置时使用 `~/.local/state/dsht/auth`；可通过 `--auth-dir` 或 `DSHT_AUTH_DIR` 覆盖。POSIX 下目录权限为 0700、cookie 文件为 0600；Windows 使用账户目录继承的访问控制。启动 token 永不保存。
 
@@ -297,7 +297,8 @@ Enter 提交消息：代理处于 Working 时自动作为下一个 step 的转
 
 `/search` 对对话消息进行不区分大小写的字面文本匹配，包含旧页，排除纯工具行。搜索每次请求最多 80 条消息，扫描后释放临时页，只保留最多 200 条简短命中摘要，包含折叠的思考；结果截断时提示缩小查询范围。选择命中项只加载其序号附近的独立页面，`/latest` 释放该窗口。Esc 或 Ctrl+C 可取消搜索。稀有词或无匹配查询仍需通过 HTTP 扫描全部历史，此命令尚无服务端全文索引。`/history` 只列出已加载页面中自己的提示词，选择器显示的数字就是记录序号。`/ssearch` 与 `/wsearch` 调用 `session/search`，服务端搜索当前用户／助手消息内容，最多返回 20 个会话、摘要和截断标记，没有结果分页游标或命中记录序号。工作区筛选在全局数量限制之后进行，因此截断时可能漏掉工作区内的匹配会话；界面会提示结果不完整，可缩小查询范围。选择会话后加载其历史，再选择匹配消息跳转。所有操作均通过 HTTP 完成，不扫描服务端配置目录。
 
-↑/↓ 或 Ctrl+P/N 回填之前提交的提示词和 slash 命令，按 Enter 才提交。一屏放得下的阅读面板会把方向键留给该历史，需要滚动的面板才接管方向键，而 Ctrl+P/N 在任何面板打开时都能回填。向下越过最新记录时恢复未发送草稿；编辑回填内容后开始新的草稿。历史按当前会话保留，最多 200 条、约 256 KiB 文本。打开或恢复会话时，从已加载的 User 消息初始化回填；切换会话释放旧缓存。不额外拉取历史页，也不写入独立历史文件。连续重复输入合并，超大输入跳过，提问和审批回答不记入历史。提问选项与补全菜单优先使用箭头；工作区／会话列表在输入框为空时使用箭头选择，可用 Ctrl+P/N 调出输入历史。
+↑/↓ 或 Ctrl+P/N 回填之前提交的提示词和 slash 命令，按 Enter 才提交。一屏放得下的阅读面板会把方向键留给该历史，需要滚动的面板才接管方向键，而 Ctrl+P/N 在任何面板打开时都能回填。向下越过最新记录时恢复未发送草稿；编辑回填内容后开始新的草稿，切换会话会清空未发送的草稿。回填按当前会话保留其 user prompt，最多 2,000 条、约 512 KiB 文本，且不写入独立历史文件；切换会话即释放。它在记录到达时增量折叠这些提示词，因此覆盖本客户端连接之前的提示词，而不只是碰巧加载的那个窗口。打开会话后它还会在后台把更早的历史翻一遍，只提取提示词、不把这些页读进上方对话，因此从会话开始就持有整个会话的提示词列表。走到索引里最旧一条时，先用已加载的对话补回被预算淘汰的提示词，这一步不发请求；只有窗口也用尽才取回窗口之前的一页，并在同一次有界循环里跳过整页没有 User 消息的页，因此按键不会被工具页卡住；取回的那页也会留在输入框上方的对话里。于是淘汰只约束内存、不决定可达性：被淘汰的提示词要么仍在窗口内，要么仍在宿主上。连续重复输入合并，超大输入跳过，提问和审批回答不记入历史。提问选项与补全菜单优先使用箭头；工作区／会话列表在输入框为空时使用箭头选择，可用 Ctrl+P/N 调出输入历史。
+`!命令` 在这台运行客户端的机器上执行——不是 agent 所在的宿主——并把命令行与输出内联打印在对话里、留在它发生的位置随历史一起滚走；不会发给模型，也不写入磁盘。每条命令的输出上限为 200 行与 64 KiB，只保留最近 20 条命令，被丢弃的行数会在块内注明。同一时刻只运行一条命令；Esc（或输入框为空时 Ctrl+C）会终止其整个进程组来停止它，因此管道与后台子进程一起结束；需要独占终端的命令（如 `vim`）无法工作。`--no-shell` 或 `DSHT_NO_SHELL=1` 关闭该前缀。
 
 每条 User 消息之后，只在第一段助手正文或思考前显示 Assistant 标题；后续消息及流式输出沿用分组，工具结果和 Context 消息不重置分组。当前加载的历史窗口从自身起点建立可见分组，消息序号、工具状态、搜索和思考展开仍各自保留。
 
@@ -426,7 +427,7 @@ Slash 命令在选择器和对话输入框中均可使用。输入 `/` 会显示
 
 | 字段 | 值 |
 | --- | --- |
-| 名称与版本 | `@itookit/dsht` `0.3.4` |
+| 名称与版本 | `@itookit/dsht` `0.3.8` |
 | 可执行命令 | `dsht`，不安装时用 `npx @itookit/dsht` |
 | 库入口 | `@itookit/dsht` 和 `@itookit/dsht/auth` |
 | 作者 | lizlok\@gmail.com |

package/dist/cli/dsht.js

@@ -26,6 +26,7 @@ With no command, choose a workspace and session interactively.
   --history-mb <n>      Soft history payload budget in MiB (default 16)
   --memory-log <path>   Append runtime memory samples; a failing log stops itself
   --no-memory-log       Disable the runtime memory log (default: enabled)
+  --no-shell            Disable ! local commands (DSHT_NO_SHELL=1)
   --json               Print machine-readable list output
   --help               Show this help
 
@@ -33,6 +34,7 @@ The default host is http://127.0.0.1:3080.
 First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
 Cookies are saved per server origin and reused on later starts. Tokens are never saved.
 /cost shows the session and today CNY estimates.
+!command runs on this machine, not on the host, and prints its output in the transcript.
 DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
 The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
 prices.json overrides the shipped rates and is seeded on first use; every scan re-decides the
@@ -47,7 +49,7 @@ async function main() {
             url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
             'history-records': { type: 'string' }, 'history-mb': { type: 'string' },
             workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
-            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' },
+            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' }, 'no-shell': { type: 'boolean' },
         } });
     if (values.help) {
         process.stdout.write(HELP);
@@ -93,7 +95,8 @@ async function main() {
     await costs.load();
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
-    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']));
+    const shellEnabled = !values['no-shell'] && process.env.DSHT_NO_SHELL !== '1';
+    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']), undefined, shellEnabled);
     const app = mount(controller);
     const terminate = () => app.unmount();
     process.once('SIGTERM', terminate);

package/dist/controller/controller.d.ts

@@ -11,7 +11,10 @@ import { CostController } from '../cost/controller.ts';
 import { ConnectionController, type ConnectionListener } from './connection.ts';
 import { MemoryLog } from './memory-log.ts';
 import { type ControllerStore, type State } from '../state.ts';
+import { ShellController } from '../shell/index.ts';
 import type { HistorySearch, RemovalTarget } from '../session/types.ts';
+import type { ComposerState, InteractionState, ModelState, OptionState, PanelState, ReferenceState, ViewState } from '../session/info.ts';
+import type { Reasoning } from '../session/history.ts';
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
@@ -36,17 +39,23 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly cost: CostController | undefined;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     readonly memoryLog: MemoryLog | undefined;
+    /** Local `!` commands, run on this machine and shown inline in the transcript. */
+    readonly shell: ShellController;
     private readonly observers;
     private selector;
     constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits, memoryLogPath?: string | undefined, 
     /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory?: string);
+    localDirectory?: string, 
+    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
+    shellEnabled?: boolean);
     /** React-compatible state subscription. */
     subscribe: (listener: () => void) => (() => void);
     /** Snapshot identity changes only when the controller publishes. */
     snapshot: () => State;
     /** Current projection store; replaced at each connection generation. */
     get telemetry(): Telemetry;
+    /** Record of the selected session; the one strong owner lives in `State.session`. */
+    get record(): Transcript;
     /** @returns The current selector generation. */
     selection(): number;
     /** Advance the selector generation when the selected workspace or session changes. */
@@ -141,10 +150,113 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @returns True when the caller may exit.
      */
     interrupt(force?: boolean): Promise<boolean>;
+    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
+    get sessionCostText(): string;
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
     pinHistory(pinned: boolean): void;
+    /** Recall one step through the selected session's prompt index; never touches the network.
+     * @param direction - Negative for older input, positive for newer input.
+     * @param current - Composer content before recall began, restored at the newest position.
+     * @returns The recalled prompt, or the unsent draft.
+     */
+    recall(direction: -1 | 1, current: string): string;
+    /** Remember a locally submitted command, which never becomes a durable session record.
+     * @param value - Submitted command text.
+     */
+    recordRecall(value: string): void;
+    /** Leave recall navigation because the composer was edited or replaced. */
+    resetRecall(): void;
+    /** Whether recall is parked on the oldest prompt the session retains. */
+    get recallAtOldest(): boolean;
+    /** How many prompts the selected session retains for recall. */
+    get recallLength(): number;
+    /** Whether an older prompt is reachable, in the loaded window or on the host. */
+    get recallHasOlder(): boolean;
+    /** Recover older prompts from the loaded window before spending a page request.
+     * @returns Whether any older prompt was recovered.
+     */
+    refillRecall(): boolean;
+    /** Composer draft, caret and parked draft of the selected session. */
+    get composer(): ComposerState;
+    /** Replace the composer text and caret.
+     * @param draft - New text.
+     * @param cursor - Caret column; defaults to the end of the text.
+     */
+    setComposer(draft: string, cursor?: number): void;
+    /** Move the caret without changing the text.
+     * @param cursor - Caret column.
+     */
+    setComposerCursor(cursor: number): void;
+    /** Move a non-empty draft aside while a dialog owns the keyboard. */
+    parkComposer(): void;
+    /** Give a parked draft back once no dialog needs the keyboard. */
+    restoreComposer(): void;
+    /** How the selected session's record is being read right now. */
+    get view(): ViewState;
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
+    setViewWindow(window?: Transcript): void;
+    /** Move the reader's position inside the displayed record.
+     * @param scroll - Rows scrolled back from the live end.
+     */
+    setScroll(scroll: number): void;
+    /** Replace the set of expanded reasoning blocks.
+     * @param folds - Sequences to expand beyond the default fold.
+     */
+    setFolds(folds: ReadonlySet<number>): void;
+    /** Set the fold mode of the live attempt's completed reasoning.
+     * @param reasoning - `row` to fold, `full` to keep the streamed text.
+     */
+    setLiveReasoning(reasoning: Reasoning): void;
+    /** Local answer state for the selected session's pending waterfalls. */
+    get interaction(): InteractionState;
+    /** Replace the partly collected answers, keyed by waterfall event id.
+     * @param answers - Answers collected so far, by event id.
+     */
+    setAnswers(answers: Record<string, ObjectValue[]>): void;
+    /** Replace the pending question's option keyboard state.
+     * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
+     */
+    setOption(option?: OptionState): void;
+    /** Replace the pending approval's selected row.
+     * @param approval - Selected approval row; undefined clears the highlight.
+     */
+    setApproval(approval?: InteractionState['approval']): void;
+    /** Composer-adjacent `@` reference menu state. */
+    get reference(): ReferenceState;
+    /** Highlight one row of the open reference menu.
+     * @param index - Row index into the current matches.
+     */
+    setReferenceIndex(index: number): void;
+    /** Remember the draft that dismissed the reference menu.
+     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
+     */
+    setReferenceDismissed(draft?: string): void;
+    /** Panels the selected session has open. */
+    get panels(): PanelState;
+    /** Show or hide the reasoning panel.
+     * @param open - Whether `/think` is open.
+     */
+    openThoughts(open: boolean): void;
+    /** Show or hide the pending-input panel.
+     * @param open - Whether `/queue` is open.
+     */
+    openQueue(open: boolean): void;
+    /** Show the model dialog at one step, or close it.
+     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
+     */
+    setModelPanel(model?: ModelState): void;
+    /** Show the history or content-search dialog, or close it.
+     * @param history - Query, content-search mode and matches; undefined closes the dialog.
+     */
+    setHistoryPanel(history?: PanelState['history']): void;
+    /** Show the host session-search results, or close them.
+     * @param search - Query, results and truncation flag; undefined closes the dialog.
+     */
+    setSearchPanel(search?: PanelState['search']): void;
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */

package/dist/controller/controller.js

@@ -8,10 +8,25 @@ import { markdownCacheStats } from "../session/markdown.js";
 import { SessionController } from "../session/controller.js";
 import { CatalogController } from "../catalog/controller.js";
 import { CostController } from "../cost/controller.js";
+import { costText } from "../cost/ledger.js";
 import { ConnectionController } from "./connection.js";
 import { MemoryLog } from "./memory-log.js";
 import { clearReactMeasures, measureCount } from "./perf-measures.js";
 import { initialState } from "../state.js";
+import { ShellController } from "../shell/index.js";
+/** Environment for a local `!` command: this client's variables without its credentials.
+ *
+ * `DSH_URL` is removed as well as the token, because the URL form the README documents can carry a
+ * token in its query string. Commands therefore run with the operator's environment, not this
+ * client's session.
+ * @returns A copy of the environment safe to hand to a child process.
+ */
+function shellEnv() {
+    const env = { ...process.env };
+    delete env.DSH_TOKEN;
+    delete env.DSH_URL;
+    return env;
+}
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
@@ -35,11 +50,15 @@ export class Controller {
     cost;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     memoryLog;
+    /** Local `!` commands, run on this machine and shown inline in the transcript. */
+    shell;
     observers = new Set();
     selector = 0;
     constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath, 
     /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory = process.cwd()) {
+    localDirectory = process.cwd(), 
+    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
+    shellEnabled = true) {
         this.base = base;
         this.initialSession = initialSession;
         this.costs = costs;
@@ -49,6 +68,12 @@ export class Controller {
         const options = { base, token, initialSession, makeClient, authenticate };
         this.connection = new ConnectionController(this, options, this);
         this.session = new SessionController(this, this.connection, this.connection, historyLimits);
+        this.shell = new ShellController({
+            publish: () => this.update({}),
+            cwd: () => this.localDirectory,
+            env: () => shellEnv(),
+            anchor: () => this.state.session.record.readThrough,
+        }, shellEnabled);
         this.catalog = new CatalogController(this, this.connection);
         if (costs)
             this.cost = new CostController(costs, {
@@ -56,6 +81,10 @@ export class Controller {
                 online: () => this.state.online,
                 signal: () => this.connection.signal(),
                 publish: () => this.update({}),
+                // The scan already reads every session's whole history; handing its pages to the session
+                // domain lets the prompt cache pick them up, so one open does not pay for a second walk.
+                scanPage: (sessionId, records) => this.session.rememberScanPage(sessionId, records),
+                scanDone: sessionId => this.session.rememberScanDone(sessionId),
             });
         if (memoryLogPath !== undefined)
             this.memoryLog = new MemoryLog(memoryLogPath, () => this.memorySample());
@@ -69,6 +98,8 @@ export class Controller {
     snapshot = () => this.state;
     /** Current projection store; replaced at each connection generation. */
     get telemetry() { return this.connection.telemetry; }
+    /** Record of the selected session; the one strong owner lives in `State.session`. */
+    get record() { return this.state.session.record; }
     /** @returns The current selector generation. */
     selection() { return this.selector; }
     /** Advance the selector generation when the selected workspace or session changes. */
@@ -88,6 +119,7 @@ export class Controller {
     start() { this.connection.start(); this.memoryLog?.start(); }
     /** Cancel retries and HTTP, close the socket, and release session and catalog work. */
     async stop() {
+        await this.shell.stop();
         await this.connection.stop();
         await this.session.settle();
         await this.catalog.settle();
@@ -137,7 +169,7 @@ export class Controller {
      */
     memorySample() {
         const memory = process.memoryUsage();
-        const transcript = this.state.transcript;
+        const transcript = this.state.session.record;
         const ledger = this.costs?.summary();
         const layout = layoutStats(transcript);
         const markdown = markdownCacheStats();
@@ -189,6 +221,11 @@ export class Controller {
         this.update({ online: true, status: 'Connected', error: '', pending: [] });
         const screen = this.state.screen;
         await this.session.showPicker(screen === 'sessions' ? 'sessions' : 'workspaces');
+        // Starting inside a registered workspace's directory already answers the first question, so the
+        // reader lands on that workspace's sessions instead of a list they would pick from by hand.
+        if (screen !== 'sessions' && !this.initialSession && this.session.adoptLocalWorkspace(this.localDirectory) !== undefined) {
+            this.update({ status: 'Workspace from this directory · ← to switch' });
+        }
         const sessionId = this.state.sessionId ?? this.initialSession;
         if (sessionId && (screen === 'chat' || this.initialSession && !this.state.sessionId))
             await this.session.selectSession(sessionId);
@@ -251,10 +288,116 @@ export class Controller {
      * @returns True when the caller may exit.
      */
     interrupt(force = false) { return this.session.interrupt(force); }
+    /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
+    get sessionCostText() {
+        const sessionId = this.state.sessionId;
+        return this.costs?.hasSession(sessionId) ? costText(this.costs.total(sessionId)) : '?';
+    }
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
     pinHistory(pinned) { this.session.pinHistory(pinned); }
+    /** Recall one step through the selected session's prompt index; never touches the network.
+     * @param direction - Negative for older input, positive for newer input.
+     * @param current - Composer content before recall began, restored at the newest position.
+     * @returns The recalled prompt, or the unsent draft.
+     */
+    recall(direction, current) { return this.session.recall(direction, current); }
+    /** Remember a locally submitted command, which never becomes a durable session record.
+     * @param value - Submitted command text.
+     */
+    recordRecall(value) { this.session.recordRecall(value); }
+    /** Leave recall navigation because the composer was edited or replaced. */
+    resetRecall() { this.session.resetRecall(); }
+    /** Whether recall is parked on the oldest prompt the session retains. */
+    get recallAtOldest() { return this.session.recallAtOldest; }
+    /** How many prompts the selected session retains for recall. */
+    get recallLength() { return this.session.recallLength; }
+    /** Whether an older prompt is reachable, in the loaded window or on the host. */
+    get recallHasOlder() { return this.session.recallHasOlder; }
+    /** Recover older prompts from the loaded window before spending a page request.
+     * @returns Whether any older prompt was recovered.
+     */
+    refillRecall() { return this.session.refillRecall(); }
+    /** Composer draft, caret and parked draft of the selected session. */
+    get composer() { return this.session.composer; }
+    /** Replace the composer text and caret.
+     * @param draft - New text.
+     * @param cursor - Caret column; defaults to the end of the text.
+     */
+    setComposer(draft, cursor) { this.session.setComposer(draft, cursor); }
+    /** Move the caret without changing the text.
+     * @param cursor - Caret column.
+     */
+    setComposerCursor(cursor) { this.session.setComposerCursor(cursor); }
+    /** Move a non-empty draft aside while a dialog owns the keyboard. */
+    parkComposer() { this.session.parkComposer(); }
+    /** Give a parked draft back once no dialog needs the keyboard. */
+    restoreComposer() { this.session.restoreComposer(); }
+    /** How the selected session's record is being read right now. */
+    get view() { return this.session.view; }
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
+    setViewWindow(window) { this.session.setViewWindow(window); }
+    /** Move the reader's position inside the displayed record.
+     * @param scroll - Rows scrolled back from the live end.
+     */
+    setScroll(scroll) { this.session.setScroll(scroll); }
+    /** Replace the set of expanded reasoning blocks.
+     * @param folds - Sequences to expand beyond the default fold.
+     */
+    setFolds(folds) { this.session.setFolds(folds); }
+    /** Set the fold mode of the live attempt's completed reasoning.
+     * @param reasoning - `row` to fold, `full` to keep the streamed text.
+     */
+    setLiveReasoning(reasoning) { this.session.setLiveReasoning(reasoning); }
+    /** Local answer state for the selected session's pending waterfalls. */
+    get interaction() { return this.session.interaction; }
+    /** Replace the partly collected answers, keyed by waterfall event id.
+     * @param answers - Answers collected so far, by event id.
+     */
+    setAnswers(answers) { this.session.setAnswers(answers); }
+    /** Replace the pending question's option keyboard state.
+     * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
+     */
+    setOption(option) { this.session.setOption(option); }
+    /** Replace the pending approval's selected row.
+     * @param approval - Selected approval row; undefined clears the highlight.
+     */
+    setApproval(approval) { this.session.setApproval(approval); }
+    /** Composer-adjacent `@` reference menu state. */
+    get reference() { return this.session.reference; }
+    /** Highlight one row of the open reference menu.
+     * @param index - Row index into the current matches.
+     */
+    setReferenceIndex(index) { this.session.setReferenceIndex(index); }
+    /** Remember the draft that dismissed the reference menu.
+     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
+     */
+    setReferenceDismissed(draft) { this.session.setReferenceDismissed(draft); }
+    /** Panels the selected session has open. */
+    get panels() { return this.session.panels; }
+    /** Show or hide the reasoning panel.
+     * @param open - Whether `/think` is open.
+     */
+    openThoughts(open) { this.session.openThoughts(open); }
+    /** Show or hide the pending-input panel.
+     * @param open - Whether `/queue` is open.
+     */
+    openQueue(open) { this.session.openQueue(open); }
+    /** Show the model dialog at one step, or close it.
+     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
+     */
+    setModelPanel(model) { this.session.setModelPanel(model); }
+    /** Show the history or content-search dialog, or close it.
+     * @param history - Query, content-search mode and matches; undefined closes the dialog.
+     */
+    setHistoryPanel(history) { this.session.setHistoryPanel(history); }
+    /** Show the host session-search results, or close them.
+     * @param search - Query, results and truncation flag; undefined closes the dialog.
+     */
+    setSearchPanel(search) { this.session.setSearchPanel(search); }
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */

package/dist/cost/controller.d.ts

@@ -1,5 +1,6 @@
 /** Periodic billing scans; the ledger outlives any single connection generation. */
 import type { Client } from '../transport/client.ts';
+import { type Json } from '../transport/wire.ts';
 import type { CostLedger } from './ledger.ts';
 /** Host access a scan needs; supplied by the controller facade. */
 export interface CostHost {
@@ -11,6 +12,10 @@ export interface CostHost {
     signal(): AbortSignal;
     /** Re-publish controller state after the ledger changes. */
     publish(): void;
+    /** Hand one already-read history page to another consumer, which owns what it does with it. */
+    scanPage?(sessionId: string, records: readonly Json[]): void;
+    /** Report that a session's history was read to its beginning. */
+    scanDone?(sessionId: string): void;
 }
 /** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
 export declare class CostController {

package/dist/cost/controller.js

@@ -77,7 +77,8 @@ export class CostController {
                     if (!session.running && typeof session.updatedAt === 'number' && this.updates.get(sessionId) === session.updatedAt)
                         continue;
                     try {
-                        const history = await sessionCostHistory(client, session, combined, () => { pages++; });
+                        const history = await sessionCostHistory(client, session, combined, () => { pages++; }, records => this.host.scanPage?.(sessionId, records));
+                        this.host.scanDone?.(sessionId);
                         scanned++;
                         events += history.events.length;
                         await ledger.replace(sessionId, history.cursor, history.events);

package/dist/cost/scanner.d.ts

@@ -1,6 +1,6 @@
 /** Address and page one session's complete billing history over the host connection. */
 import { type Client } from '../transport/client.ts';
-import { type ObjectValue } from '../transport/wire.ts';
+import { type Json, type ObjectValue } from '../transport/wire.ts';
 /** Wire addresses for one `session/list` row, in the order the cost scan should try them.
  *
  * A subagent child is reachable only under its durable parent, and the list row omits the delivery
@@ -14,9 +14,11 @@ export declare function costAddresses(session: ObjectValue): ObjectValue[];
  * @param session - One row from the host session list.
  * @param signal - Cancels paging without cancelling any agent work.
  * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @param onRecords - Hands each page's raw records to the caller, which owns any further reading of
+ *   them; the billing fold itself keeps only the minimal events below.
  * @returns Opening cursor and the minimal billing events behind it.
  */
-export declare function sessionCostHistory(client: Client, session: ObjectValue, signal: AbortSignal, onPage?: () => void): Promise<{
+export declare function sessionCostHistory(client: Client, session: ObjectValue, signal: AbortSignal, onPage?: () => void, onRecords?: (records: readonly Json[]) => void): Promise<{
     cursor: number;
     events: ObjectValue[];
 }>;

package/dist/cost/scanner.js

@@ -24,13 +24,15 @@ export function costAddresses(session) {
  * @param session - One row from the host session list.
  * @param signal - Cancels paging without cancelling any agent work.
  * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @param onRecords - Hands each page's raw records to the caller, which owns any further reading of
+ *   them; the billing fold itself keeps only the minimal events below.
  * @returns Opening cursor and the minimal billing events behind it.
  */
-export async function sessionCostHistory(client, session, signal, onPage) {
+export async function sessionCostHistory(client, session, signal, onPage, onRecords) {
     let lastError;
     for (const address of costAddresses(session)) {
         try {
-            return await readCostHistory(client, address, signal, onPage);
+            return await readCostHistory(client, address, signal, onPage, onRecords);
         }
         catch (error) {
             lastError = error;
@@ -42,7 +44,7 @@ export async function sessionCostHistory(client, session, signal, onPage) {
     throw lastError;
 }
 /** Page one addressed session's history into the billing events the ledger folds. */
-async function readCostHistory(client, address, signal, onPage) {
+async function readCostHistory(client, address, signal, onPage, onRecords) {
     onPage?.();
     const snapshot = await new Promise((resolve, reject) => {
         let sub;
@@ -77,6 +79,7 @@ async function readCostHistory(client, address, signal, onPage) {
     while (true) {
         signal.throwIfAborted();
         const records = array(page.records);
+        onRecords?.(records);
         events.push(...costRecords(records));
         if (!page.hasMore)
             break;