@songtonyli/dsh-cli 0.1.51 → 0.1.52

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -26,7 +26,7 @@ workspace and no build step. Native packages that ship one build per platform
26
26
  ripgrep, the PTY backend's addons, sharp, koffi, and the Landlock launcher — are
27
27
  ordinary optional dependencies, so npm resolves the right one for your machine.
28
28
 
29
- Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.51; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.52; `dsh --version`
30
30
  also reports the harness build the package was assembled from.
31
31
 
32
32
  ## License
package/bin/dsh.mjs CHANGED
@@ -18,7 +18,7 @@ const argv = process.argv.slice(2)
18
18
  // version this package publishes. Reporting only one of the two would make an
19
19
  // ordinary `npm install @songtonyli/dsh-cli@x` look like it installed something else.
20
20
  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
21
- console.log('@songtonyli/dsh-cli 0.1.51 (deepseek-harness 0.1.7-rc.2)')
21
+ console.log('@songtonyli/dsh-cli 0.1.52 (deepseek-harness 0.1.7-rc.2)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -48,8 +48,8 @@
48
48
  "micromark-util-sanitize-uri": "^2.0.1",
49
49
  "simple-icons": "16.31.0",
50
50
  "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
51
- "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
52
51
  "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
52
+ "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
53
53
  "@deepseek-ai/cordis": "~4.0.4"
54
54
  },
55
55
  "files": [
@@ -167,7 +167,7 @@ window.__ModuleLoader__.load({
167
167
  const SCROLLBAR_LINGER_MS = 2e3;
168
168
  /** Format complete-build metadata for the local brand badge. */
169
169
  function localBuildVersion() {
170
- return `0.1.7-rc.2-d4ad074` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
170
+ return `0.1.7-rc.2-95cfb10` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
171
171
  }
172
172
  /** Each panel row subscribes only to its own selection state. */
173
173
  function PanelRow({ id, label, wide, usePanelInfo, selectPanel, renderSlot }) {
@@ -21,11 +21,14 @@
21
21
  en: be0e9f07314547a5
22
22
  zh: e55e8e668b3f703f
23
23
  /deepseek-ai-dsh-tui-app/use-this-package/the-screen:
24
- en: 28704cd17ca6b37d
25
- zh: c091d14b798acccd
24
+ en: 16087917fa08726c
25
+ zh: e45dec9a0fa09642
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
- en: 86ee3c54b190bcb4
28
- zh: c6f3fcc741afaca4
27
+ en: 2e7932b9fb296b74
28
+ zh: df3a5d5ab3e21f04
29
+ /deepseek-ai-dsh-tui-app/use-this-package/background-tool-calls:
30
+ en: 322ae3c6d76383ec
31
+ zh: 8c38eee4b57ed8dd
29
32
  /deepseek-ai-dsh-tui-app/use-this-package/subscription-sign-in:
30
33
  en: 7c1b0e685a3a9415
31
34
  zh: 49f3bdc3e99d6259
@@ -36,8 +39,8 @@
36
39
  en: 23ba736da2686f52
37
40
  zh: d30ce253dd934750
38
41
  /deepseek-ai-dsh-tui-app/use-this-package/configuration:
39
- en: de84f025363b07e4
40
- zh: 5004b1a0758c58ed
42
+ en: 6f3968bd43059ee2
43
+ zh: 522aebc38fe8fc18
41
44
  /deepseek-ai-dsh-tui-app/understand-the-implementation:
42
45
  en: f124d406565fef39
43
46
  zh: 90344b5eec319cad
@@ -51,8 +54,8 @@
51
54
  en: 142f04bf29e981dd
52
55
  zh: a1689297b06c9ca6
53
56
  /deepseek-ai-dsh-tui-app/understand-the-implementation/source-map:
54
- en: f6bd9e5b67b3652f
55
- zh: cef041b9a91b245b
57
+ en: d4b312aec290d553
58
+ zh: 99e69009c981cc7d
56
59
  /deepseek-ai-dsh-tui-app/understand-the-implementation/invariant-ownership:
57
60
  en: 0ddf6de8928026d5
58
61
  zh: 24feedcbb9e9d676
@@ -77,6 +80,21 @@
77
80
  /deepseek-ai-dsh-tui-app/model-experience/user-typed-shell-command/kv-cache-effect:
78
81
  en: 5b83189b640899dd
79
82
  zh: 232c1ef2f192bd4c
83
+ /deepseek-ai-dsh-tui-app/model-experience/background-tool-call:
84
+ en: 325019794223c5fa
85
+ zh: 7ea0055b28d10846
86
+ /deepseek-ai-dsh-tui-app/model-experience/background-tool-call/what-the-model-sees:
87
+ en: 014cef57bd1e994e
88
+ zh: 1b5df1ceaa4830ed
89
+ /deepseek-ai-dsh-tui-app/model-experience/background-tool-call/what-the-model-sees/moved-call-result:
90
+ en: 434507f4855ece52
91
+ zh: 3df40dcea19a8b52
92
+ /deepseek-ai-dsh-tui-app/model-experience/background-tool-call/token-effect:
93
+ en: fdec4eeeee7c6335
94
+ zh: a900f1ef88e85179
95
+ /deepseek-ai-dsh-tui-app/model-experience/background-tool-call/kv-cache-effect:
96
+ en: 8a5bab15e1637c6a
97
+ zh: e1075bfdb6952fdc
80
98
  /deepseek-ai-dsh-tui-app/model-experience/side-agent:
81
99
  en: 1c67a481715ccab3
82
100
  zh: cb1ee722aa3b9201
@@ -90,8 +108,8 @@
90
108
  en: 1dadc4a2f1560eaa
91
109
  zh: dc4697c269bc16b9
92
110
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work:
93
- en: 6c5c2264668d24f7
94
- zh: 025b0085b347b04d
111
+ en: 768f55ebb0a75616
112
+ zh: c512d13f4b3763e8
95
113
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work/dev-note:
96
114
  en: 5629c6159cec997f
97
115
  zh: 17f2d7e1f96da7f1
@@ -60,7 +60,7 @@ The subagent panel is drawn while a subagent session under the bound one is resi
60
60
 
61
61
  ### Keys and commands
62
62
 
63
- The conversation, input, subagent panel, and status bar form the vertical arrow-key walk: `Down` at the newest section, `Up` on the subagent panel's first row, and `Up` on the status bar with no subagent panel drawn all land at the caret. The follow-ups list sits above the input; `Shift+Up` enters it while it is drawn, and it joins the `Tab` walk. The activity board sits between follow-ups and the input and is not a focus region. While a region other than the editor has the keyboard, `Tab` and `Shift+Tab` walk the regions that are drawn, wrapping at both ends; in the editor, `Tab` takes the offered completion and `Shift+Tab` opens the reasoning-effort picker. A printable key pressed in any of them returns to the input and types there, so a sentence started while reading lands where it was aimed; `Space` in the conversation is the one exception, and folds the marked tool card or context block. `Ctrl+G`, `Ctrl+O`, `Ctrl+T`, `Ctrl+P`, and `Ctrl+L` mean the same thing in every one of those regions, and `Ctrl+C` and `Ctrl+D` return the keyboard to the input before they act. A prompt and the reader own their whole key stream instead, and answer `Ctrl+C` by giving the keyboard back.
63
+ The conversation, input, subagent panel, and status bar form the vertical arrow-key walk: `Down` at the newest section, `Up` on the subagent panel's first row, and `Up` on the status bar with no subagent panel drawn all land at the caret. The follow-ups list sits above the input; `Shift+Up` enters it while it is drawn, and it joins the `Tab` walk. The activity board sits between follow-ups and the input and is not a focus region. While a region other than the editor has the keyboard, `Tab` and `Shift+Tab` walk the regions that are drawn, wrapping at both ends; in the editor, `Tab` takes the offered completion and `Shift+Tab` opens the reasoning-effort picker. A printable key pressed in any of them returns to the input and types there, so a sentence started while reading lands where it was aimed; `Space` in the conversation is the one exception, and folds the marked tool card or context block. `Ctrl+G`, `Ctrl+O`, `Ctrl+B`, `Ctrl+T`, `Ctrl+P`, and `Ctrl+L` mean the same thing in every one of those regions, and `Ctrl+C` and `Ctrl+D` return the keyboard to the input before they act. A prompt and the reader own their whole key stream instead, and answer `Ctrl+C` by giving the keyboard back.
64
64
 
65
65
  While the input has the keyboard:
66
66
 
@@ -79,6 +79,7 @@ While the input has the keyboard:
79
79
  | `Ctrl+G` | Read the conversation full screen, on its newest section |
80
80
  | `Ctrl+O` | Expand or collapse every tool card and context row |
81
81
  | `Ctrl+T` | Browse the agent's todo list, the same list `/todos` opens |
82
+ | `Ctrl+B` | While a turn runs, move its running tool calls to background jobs so the agent keeps working; outside a turn the editor moves the caret left |
82
83
  | `Ctrl+P` | Return from a subagent view to the session it was entered from, or end a `/btw` side agent, like `/parent` |
83
84
  | `Ctrl+L` | Redraw the whole screen from scratch |
84
85
  | `?` | On an empty input, list the commands and keys, like `/help`; inside a draft it is typed |
@@ -191,6 +192,7 @@ Typing `/` at the start of the editor completes the terminal's own commands and
191
192
  | `/changes [turn]` | Browse the files the latest turn changed, or turn `turn`, with their line counts; `Enter` opens one file's turn-start to turn-end comparison |
192
193
  | `/subagents` | Browse the subagent sessions under this session; `Enter` opens a readable one as a subagent view and an unreadable one's details |
193
194
  | `/parent` | Return from a subagent view to the session it was entered from, or end a `/btw` side agent, like `Ctrl+P` |
195
+ | `/jobs` | Browse this session's background jobs, the calls moved with `Ctrl+B` and the jobs the agent started, with status and elapsed time; `Enter` shows one job's status and output tail, and `Ctrl+K` stops the highlighted job |
194
196
  | `/settings [ns [path value]]` | List namespaces, show one, or set one field; `/settings reset <ns>` restores defaults |
195
197
  | `/plugins` | The composed plugins with enablement and lifecycle phase; `/plugins bundles` lists the profile's bundles, `/plugins enable <id>` and `/plugins disable <id>` switch a plugin entry or a bundle, `/plugins add <spec>` installs a bundle, `/plugins remove <name>` removes one |
196
198
  | `/tools` | Expand or collapse every tool card and context row, like `Ctrl+O` |
@@ -204,6 +206,10 @@ Every picker the terminal opens — `/model`'s model and reasoning-effort lists,
204
206
 
205
207
  `/todos`, the `todo` status-bar segment, and the unreadable rows of `/subagents` share one list-then-details interaction: the picker lists the entries, `Enter` opens the highlighted entry as a read-only page, `Up` / `Down` and `PageUp` / `PageDown` scroll that page, and `Enter`, `Esc`, or `Left` returns to the list on the entry just read, so walking several entries costs no retyped command; `Esc` at the list returns to the editor. An entry whose details cannot be read says so on its page instead of closing the list.
206
208
 
209
+ ### Background tool calls
210
+
211
+ While the running turn waits on a tool call, the working spinner ends in `· Ctrl+B background`. `Ctrl+B` hands every such call of the bound Agent to the job registry as a `tool-<n>` job and answers the call at once with a result that names the job, so the turn goes on while the call keeps running. The card settles on an accent `◇` row, `◇ moved to the background as tool-1 · /jobs lists it`, which a resumed session draws the same way. While any job of the session runs, one dim line above the input lists them, as in `◇ 2 in background · tool-1 bash npm test 1m04s · bash-3 sleep 20 12s · /jobs`, and the live refresh advances their elapsed times. A shell call's own process job belongs to that call and is listed only once it outlives the call. When a job settles, a transient line names it, such as `◇ tool-1 completed · bash npm test · agent notified`, and `dsh-tool-jobs` delivers the completion notice: a busy agent reads it at its next step, and an idle one wakes. `/jobs` browses every job of the session: `Enter` shows its status, label, start, and the tail of its output, including a moved shell call's live process output, and `Ctrl+K` stops the highlighted job, which the agent is told about. Stopping the turn with `Esc` also stops the calls moved out of that turn, because the tool runtime ties every call to its turn; the stop notice counts them, and their jobs settle `killed` without waking the agent.
212
+
207
213
  ### Subscription sign-in
208
214
 
209
215
  `/login` stores a subscription credential but does not activate a dormant model route. Configure the catalog route first, then use its full credential key; for example, run `/settings llm-pi-ai providers.openai-codex {}` and then `/login llm-pi-ai/openai-codex`. Cursor is already registered: `/login llm-cursor/cursor`. A marked authorization page opens in the local default browser while its URL remains in the transcript as a fallback. SSH launches, hosts without a desktop, `--no-open`, and opener failures leave the manual URL and device-code paths available instead.
@@ -304,6 +310,8 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
304
310
  | [`src/footer.ts`](src/footer.ts) | The status bar: the ordered segments, each segment's detail rows, the unfocused line built from both ends, and the focused sliding window |
305
311
  | [`src/subagent-panel.ts`](src/subagent-panel.ts) | The live subagent panel: one descendant listing plus sampled live facts become its rows, the unfocused summary line, and the focused listing |
306
312
  | [`src/queue-panel.ts`](src/queue-panel.ts) | The follow-ups list: pending-row glyphs, hanging wrap, and the enter-steer legend |
313
+ | [`src/background.ts`](src/background.ts) | `Ctrl+B`: the `tools/execute` wrapper that tracks root calls, moves them to `tool` jobs, recognizes a shell call's own process job, and holds the jobs of a stopped turn |
314
+ | [`src/jobs-panel.ts`](src/jobs-panel.ts) | The background-jobs line above the editor, the `/jobs` rows and detail page, and the settlement line |
307
315
  | [`src/activity-board.ts`](src/activity-board.ts) | The activity board: todo glyphs, the completed scratch-out, the row cap, and the one-line descendant summary |
308
316
  | [`src/catalog.ts`](src/catalog.ts) | Rows for `/settings`, `/plugins`, `/subagents`, `/deliverables`, `/changes`, and `/outline`, and the `/plugins` management verbs |
309
317
  | [`src/view-banner.ts`](src/view-banner.ts) | The line above the input that names an open subagent view or `/btw` side agent and the key back |
@@ -311,6 +319,9 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
311
319
  | [`cordis.patch.yml`](cordis.patch.yml) | The terminal patch over `dsh-base` |
312
320
  | — | No runtime invariant companion is published; the app registers listeners on one Agent and holds no mutable relation another observer could contradict. |
313
321
  | [`tests/app.spec.ts`](tests/app.spec.ts) | Rendering, keys, commands, the stop arm, the follow-ups rows above the editor, the activity board, and both seams over a fake terminal |
322
+ | [`tests/background.spec.ts`](tests/background.spec.ts) | `Ctrl+B` over the real tool runtime, job registry, and job tools: the spinner hint, the moved result and card, the jobs line, `/jobs` output and `Ctrl+K`, completion notices, refusal, failure, and the turn stop |
323
+ | [`tests/background-tracking.spec.ts`](tests/background-tracking.spec.ts) | Which calls the wrapper tracks, which jobs count as a call's own, and the moved-result text |
324
+ | [`tests/jobs-panel.spec.ts`](tests/jobs-panel.spec.ts) | The jobs line, `/jobs` rows, detail page, and settlement line as text |
314
325
  | [`tests/activity-board.spec.ts`](tests/activity-board.spec.ts) | Activity-board glyphs, the completed scratch-out, the row cap, and the descendant line |
315
326
  | [`tests/keys.spec.ts`](tests/keys.spec.ts) | What each region claims for a key, the legend steps, and the text one press types |
316
327
  | [`tests/editor.spec.ts`](tests/editor.spec.ts) | The terminal caret, `Shift+Left` / `Shift+Right` word navigation, and `!` / `!!` draft colour against pi-tui's editor behavior |
@@ -386,6 +397,26 @@ Conditional and retained: each `!` notice stays in conversation history for late
386
397
 
387
398
  Append-only conversation growth after the reusable request prefix. The notice does not change the system prompt or tool catalog. A `/model` switch starts a new request series exactly as it does from the browser.
388
399
 
400
+ ### Background tool call
401
+
402
+ #### What the model sees
403
+
404
+ A call the user moves with `Ctrl+B` gets an error result right away with this fixed text, `<id>` being the job's `tool-<n>` id. The error flag is required because the tool runtime validates every successful result against the tool's own output schema. When the job settles, `dsh-tool-jobs` sends its ordinary completion notice unless the model already collected the job, and `job_output` returns the call's text result. A job stopped because its turn was stopped sends no notice.
405
+
406
+ ##### Moved call result
407
+
408
+ ```markdown
409
+ The user moved this call to the background. It keeps running as job <id>. You are notified when it finishes; read its result with job_output, or stop it with job_kill. Continue with steps that do not depend on it.
410
+ ```
411
+
412
+ #### Token effect
413
+
414
+ Conditional and retained: the fixed result replaces the call's own result in history, and the completion notice and the `job_output` read that carries the call's result are added later.
415
+
416
+ #### KV Cache effect
417
+
418
+ Append-only conversation growth after the reusable request prefix. Moving a call does not change the system prompt or tool catalog.
419
+
389
420
  ### Side agent
390
421
 
391
422
  #### What the model sees
@@ -424,6 +455,7 @@ These limits describe the terminal surface as shipped; they are not a general CL
424
455
  - **The terminal's own caret can flicker** — the editor draws no caret of its own and the app turns the terminal cursor on, which pi-tui then moves across the lines it repaints; a terminal that does not honor the synchronized-output sequences pi-tui wraps a frame in can show that movement.
425
456
  - **Runs through the `dsh` launcher** — starting the profile another way fails at startup, because only the launcher can request the process exit.
426
457
  - **A `/btw` side agent is read-only by tool name and sandbox** — `btwTools` must name only tools that read, because the side agent shares the workspace with the working agent; a command tool can read anything the `read-only` sandbox mode allows, and without a confining command executor command tools are hidden. It inherits only what the working session has logged: reply text still streaming is absent. Its log is stored like a subagent session's and hidden from `/resume` and `/sessions`, and Web has no `/btw`.
458
+ - **A moved call stays tied to its turn and returns text** — the tool runtime fuses the turn's signal into every call, so `Esc` on the turn that dispatched a call stops it even after `Ctrl+B`; a job result is a string, so other content blocks of the call's result are named as `[image omitted]` and the like; and moving needs `ctx.jobs` with `dsh-tool-jobs`, which the base profile composes.
427
459
  - **`!` is one-shot and not a TTY** — each line is a fresh `ctx.shell.run`; there is no persistent shell or interactive program. The Web composer does not intercept `!`. An optional first prompt on the command line is always a user message.
428
460
 
429
461
  <a id="dev-note"></a>
@@ -60,7 +60,7 @@ dsh tui --no-open # print sign-in URLs without opening a
60
60
 
61
61
  ### 按键与命令
62
62
 
63
- 对话记录、编辑器、子 agent 面板与状态栏构成垂直方向键走查:在最新小节上按 `Down`、在子 agent 面板第一行上按 `Up`、在没有绘制子 agent 面板时于状态栏上按 `Up`,都会落到光标处。follow-ups 列表位于输入框上方;绘制该列表时,`Shift+Up` 会进入它,它也加入 `Tab` 走查。activity board 位于 follow-ups 与输入之间,不是焦点区域。编辑器以外的区域持有键盘时,`Tab` 与 `Shift+Tab` 走遍已绘制的各区域,并在两端环绕;在编辑器中,`Tab` 采用给出的补全,`Shift+Tab` 打开推理强度选择器。在其中任何一个区域按下可打印键都会回到编辑器并在那里输入,因此在阅读时开始写的句子会落在它所指向的地方;对话记录中的 `Space` 是唯一的例外,它折叠被标记的工具卡片或上下文块。`Ctrl+G`、`Ctrl+O`、`Ctrl+T`、`Ctrl+P` 与 `Ctrl+L` 在这些区域中含义完全相同,而 `Ctrl+C` 与 `Ctrl+D` 会先把键盘交还编辑器再行动。提示与阅读器则各自持有整条按键流,并以交还键盘的方式应答 `Ctrl+C`。
63
+ 对话记录、编辑器、子 agent 面板与状态栏构成垂直方向键走查:在最新小节上按 `Down`、在子 agent 面板第一行上按 `Up`、在没有绘制子 agent 面板时于状态栏上按 `Up`,都会落到光标处。follow-ups 列表位于输入框上方;绘制该列表时,`Shift+Up` 会进入它,它也加入 `Tab` 走查。activity board 位于 follow-ups 与输入之间,不是焦点区域。编辑器以外的区域持有键盘时,`Tab` 与 `Shift+Tab` 走遍已绘制的各区域,并在两端环绕;在编辑器中,`Tab` 采用给出的补全,`Shift+Tab` 打开推理强度选择器。在其中任何一个区域按下可打印键都会回到编辑器并在那里输入,因此在阅读时开始写的句子会落在它所指向的地方;对话记录中的 `Space` 是唯一的例外,它折叠被标记的工具卡片或上下文块。`Ctrl+G`、`Ctrl+O`、`Ctrl+B`、`Ctrl+T`、`Ctrl+P` 与 `Ctrl+L` 在这些区域中含义完全相同,而 `Ctrl+C` 与 `Ctrl+D` 会先把键盘交还编辑器再行动。提示与阅读器则各自持有整条按键流,并以交还键盘的方式应答 `Ctrl+C`。
64
64
 
65
65
  编辑器持有键盘时:
66
66
 
@@ -79,6 +79,7 @@ dsh tui --no-open # print sign-in URLs without opening a
79
79
  | `Ctrl+G` | 整屏读出对话记录,停在其最新小节 |
80
80
  | `Ctrl+O` | 展开或折叠所有工具卡片与上下文行 |
81
81
  | `Ctrl+T` | 浏览 agent 的 todo 列表,与 `/todos` 打开的是同一个列表 |
82
+ | `Ctrl+B` | 轮次运行期间,把它正在运行的工具调用移为后台作业,让 agent 继续工作;轮次之外由编辑器把光标左移 |
82
83
  | `Ctrl+P` | 从子 agent 视图返回进入它之前的会话,或结束 `/btw` 旁路 agent,与 `/parent` 相同 |
83
84
  | `Ctrl+L` | 从头重绘整个屏幕 |
84
85
  | `?` | 输入为空时列出命令与按键,与 `/help` 相同;在草稿中则作为文字输入 |
@@ -191,6 +192,7 @@ follow-ups 面板持有键盘时:
191
192
  | `/changes [turn]` | 浏览最近一轮(或第 `turn` 轮)改动的文件及其行数;`Enter` 打开某个文件从轮次开始到结束的对比 |
192
193
  | `/subagents` | 浏览本会话之下的子 agent 会话;`Enter` 把可读的会话作为子 agent 视图打开,对无法读取的会话则打开其详情 |
193
194
  | `/parent` | 从子 agent 视图返回进入它之前的会话,或结束 `/btw` 旁路 agent,与 `Ctrl+P` 相同 |
195
+ | `/jobs` | 浏览本会话的后台作业,即用 `Ctrl+B` 移走的调用与 agent 启动的作业,附带状态与耗时;`Enter` 显示一个作业的状态与输出末尾,`Ctrl+K` 停止高亮的作业 |
194
196
  | `/settings [ns [path value]]` | 列出命名空间、显示某一个或设置某个字段;`/settings reset <ns>` 恢复默认 |
195
197
  | `/plugins` | 已组合的插件及其启用状态与生命周期阶段;`/plugins bundles` 列出 profile 的组合包,`/plugins enable <id>` 与 `/plugins disable <id>` 切换某个插件条目或组合包,`/plugins add <spec>` 安装组合包,`/plugins remove <name>` 移除组合包 |
196
198
  | `/tools` | 像 `Ctrl+O` 一样展开或折叠所有工具卡片与上下文行 |
@@ -204,6 +206,10 @@ follow-ups 面板持有键盘时:
204
206
 
205
207
  `/todos`、状态栏的 `todo` 分段与 `/subagents` 中无法读取的行共用同一套先列表、后详情的交互:选择器列出各条目,`Enter` 把高亮条目作为只读页面打开,`Up` / `Down` 与 `PageUp` / `PageDown` 滚动该页面,`Enter`、`Esc` 或 `Left` 返回列表并停在刚读过的条目上,因此连续查看多个条目无需重新输入命令;在列表上按 `Esc` 返回编辑器。详情无法读取的条目会在其页面上说明原因,而不会关闭列表。
206
208
 
209
+ ### 后台工具调用
210
+
211
+ 运行中的轮次等待某个工具调用时,工作旋转指示以 `· Ctrl+B background` 结尾。`Ctrl+B` 把绑定 Agent 的每个此类调用作为 `tool-<n>` 作业交给作业注册表,并立即以一个写明该作业的结果应答该调用,因此轮次继续推进,而调用仍在运行。卡片停在一行强调色的 `◇` 上,即 `◇ moved to the background as tool-1 · /jobs lists it`,恢复的会话也以同样方式绘制它。只要会话有作业在运行,输入框上方就有一行暗色文字列出它们,例如 `◇ 2 in background · tool-1 bash npm test 1m04s · bash-3 sleep 20 12s · /jobs`,实时刷新会推进各自的耗时。shell 调用自己的进程作业属于该调用,只有在它比调用活得更久之后才会被列出。作业结束时,一行临时提示会写明它,例如 `◇ tool-1 completed · bash npm test · agent notified`,`dsh-tool-jobs` 则投递完成通知:忙碌的 agent 在下一步读到它,空闲的 agent 被唤醒。`/jobs` 浏览本会话的所有作业:`Enter` 显示其状态、标签、开始时间与输出末尾,包括被移走的 shell 调用的实时进程输出;`Ctrl+K` 停止高亮的作业,agent 会得知这一点。用 `Esc` 停止轮次也会停止从该轮次移出的调用,因为工具运行时把每个调用绑定到它的轮次;停止通知会计出它们的数量,它们的作业以 `killed` 结束且不会唤醒 agent。
212
+
207
213
  ### 订阅登录
208
214
 
209
215
  `/login` 只存储订阅凭据,不会激活休眠的模型路由。先配置 catalog 路由,再使用完整的凭据键;例如先运行 `/settings llm-pi-ai providers.openai-codex {}`,再运行 `/login llm-pi-ai/openai-codex`。Cursor 已经注册:`/login llm-cursor/cursor`。被标记的授权页面会在本地默认浏览器中打开,其 URL 同时保留在对话记录中作为后备。SSH 启动、无桌面的宿主、`--no-open` 以及打开器失败时,手动 URL 与设备码路径仍然可用。
@@ -304,6 +310,8 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
304
310
  | [`src/footer.ts`](src/footer.ts) | 状态栏:有序的各分段、每个分段的详情行、未聚焦时由两端向内构建的一行,以及聚焦时的滑动窗口 |
305
311
  | [`src/subagent-panel.ts`](src/subagent-panel.ts) | 实时子 agent 面板:一次后代列表加上采样到的实时事实构成其各行、未聚焦时的摘要行,以及聚焦时的列表 |
306
312
  | [`src/queue-panel.ts`](src/queue-panel.ts) | follow-ups 列表:待处理行符号、悬挂换行与 enter-steer 图例 |
313
+ | [`src/background.ts`](src/background.ts) | `Ctrl+B`:跟踪根调用的 `tools/execute` 包装器,把调用移为 `tool` 作业、识别 shell 调用自己的进程作业,并保持被停止轮次的作业 |
314
+ | [`src/jobs-panel.ts`](src/jobs-panel.ts) | 编辑器上方的后台作业行、`/jobs` 的行与详情页,以及作业结束提示行 |
307
315
  | [`src/activity-board.ts`](src/activity-board.ts) | activity board:todo 状态符号、已完成内容划掉、行数上限,以及一行后代摘要 |
308
316
  | [`src/catalog.ts`](src/catalog.ts) | `/settings`、`/plugins`、`/subagents`、`/deliverables`、`/changes` 与 `/outline` 的行,以及 `/plugins` 的管理动作 |
309
317
  | [`src/view-banner.ts`](src/view-banner.ts) | 输入框上方标明已打开的子 agent 视图或 `/btw` 旁路 agent 及返回按键的一行 |
@@ -311,6 +319,9 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
311
319
  | [`cordis.patch.yml`](cordis.patch.yml) | 基于 `dsh-base` 的终端 patch |
312
320
  | — | 不发布运行时不变量伴随模块;应用只在一个 Agent 上注册监听器,不持有其他观察者可能与之矛盾的可变关系。 |
313
321
  | [`tests/app.spec.ts`](tests/app.spec.ts) | 基于伪终端的渲染、按键、命令、停止装填、编辑器上方的 follow-ups 行、activity board 与两个接缝 |
322
+ | [`tests/background.spec.ts`](tests/background.spec.ts) | 基于真实工具运行时、作业注册表与作业工具的 `Ctrl+B`:旋转指示提示、被移走的结果与卡片、作业行、`/jobs` 输出与 `Ctrl+K`、完成通知、拒绝、失败与轮次停止 |
323
+ | [`tests/background-tracking.spec.ts`](tests/background-tracking.spec.ts) | 包装器跟踪哪些调用、哪些作业算作调用自己的作业,以及被移走结果的文本 |
324
+ | [`tests/jobs-panel.spec.ts`](tests/jobs-panel.spec.ts) | 作业行、`/jobs` 的行、详情页与作业结束提示行的文本 |
314
325
  | [`tests/activity-board.spec.ts`](tests/activity-board.spec.ts) | activity board 的状态符号、已完成划掉、行数上限与后代行 |
315
326
  | [`tests/keys.spec.ts`](tests/keys.spec.ts) | 每个区域为一个按键认领什么、按键提示的各级,以及一次按键输入的文字 |
316
327
  | [`tests/editor.spec.ts`](tests/editor.spec.ts) | 对照 pi-tui 编辑器行为验证终端光标、`Shift+Left` / `Shift+Right` 词导航,以及 `!` / `!!` 草稿着色 |
@@ -386,6 +397,26 @@ The user ran `<command>` in the terminal.
386
397
 
387
398
  在可复用的请求前缀之后只做追加式增长。该通知不改变系统提示或工具目录。`/model` 切换像在浏览器中一样开始新的请求序列。
388
399
 
400
+ ### 后台工具调用
401
+
402
+ #### 模型看到什么
403
+
404
+ 用户用 `Ctrl+B` 移走的调用会立即得到一个带以下固定文本的错误结果,其中 `<id>` 是该作业的 `tool-<n>` id。之所以需要错误标记,是因为工具运行时会按工具自身的输出 schema 校验每个成功结果。作业结束时,除非模型已经收取了该作业,`dsh-tool-jobs` 会发送它的普通完成通知,`job_output` 则返回该调用的文本结果。因其轮次被停止而停止的作业不发送通知。
405
+
406
+ ##### 被移走调用的结果
407
+
408
+ ```markdown
409
+ The user moved this call to the background. It keeps running as job <id>. You are notified when it finishes; read its result with job_output, or stop it with job_kill. Continue with steps that do not depend on it.
410
+ ```
411
+
412
+ #### Token 影响
413
+
414
+ 有条件且会保留:固定结果在历史中取代该调用自己的结果,之后再加入完成通知,以及携带该调用结果的 `job_output` 读取。
415
+
416
+ #### KV Cache 影响
417
+
418
+ 在可复用的请求前缀之后只追加对话内容。移走调用不会改变系统提示或工具目录。
419
+
389
420
  ### 旁路 agent
390
421
 
391
422
  #### 模型看到什么
@@ -424,6 +455,7 @@ The user ran `<command>` in the terminal.
424
455
  - **终端自身的光标可能闪烁**——编辑器不绘制自己的光标,应用打开终端光标,而 pi-tui 会在其重绘的各行之间移动它;不支持 pi-tui 为一帧包裹的同步输出序列的终端可能显示出这种移动。
425
456
  - **通过 `dsh` 启动器运行**——以其他方式启动该 profile 会在启动时失败,因为只有启动器能请求进程退出。
426
457
  - **`/btw` 旁路 agent 靠工具名称与沙箱保持只读**——`btwTools` 只能列出读取类工具,因为旁路 agent 与工作 agent 共享工作区;命令工具可以读取 `read-only` 沙箱模式允许的任何内容,而没有会约束命令的执行器时命令工具会被隐藏。它只继承工作会话已记录的内容:仍在流式输出的回复文本不在其中。它的日志像子 agent 会话一样被存储,并在 `/resume` 与 `/sessions` 中隐藏,Web 没有 `/btw`。
458
+ - **被移走的调用仍绑定其轮次并返回文本**——工具运行时把轮次的信号融合进每个调用,因此即便按过 `Ctrl+B`,在派发该调用的轮次上按 `Esc` 仍会停止它;作业结果是字符串,因此调用结果中的其他内容块会被写成 `[image omitted]` 之类;移走调用需要 `ctx.jobs` 与 `dsh-tool-jobs`,base profile 已组合二者。
427
459
  - **`!` 是一次性的,也不是 TTY**——每一行都是一次新的 `ctx.shell.run`;没有持久 shell,也不能跑交互式程序。Web 编辑器不拦截 `!`。命令行上的可选首条提示始终是用户消息。
428
460
 
429
461
  <a id="dev-note"></a>
@@ -293,62 +293,6 @@ function cursorTo(row) {
293
293
  return `\u001b[${String(row + 1)};1H`;
294
294
  }
295
295
  //#endregion
296
- //#region lib/types/attach.js
297
- /**
298
- * `/attach`: read a local file and admit it into the attachment store as the
299
- * image or file block the next prompt carries, the way the browser composer
300
- * uploads a dropped file.
301
- * @module @deepseek-ai/dsh-tui-app/attach
302
- */
303
- /** Image media types by file extension; every other extension attaches as a file. */
304
- const IMAGE_MEDIA_TYPES = {
305
- ".png": "image/png",
306
- ".jpg": "image/jpeg",
307
- ".jpeg": "image/jpeg",
308
- ".webp": "image/webp",
309
- ".gif": "image/gif"
310
- };
311
- /**
312
- * Read `path` (relative to `cwd`) and store it.
313
- * @param store - the composed attachment store.
314
- * @param cwd - the directory relative paths resolve against.
315
- * @param path - the file to attach.
316
- * @returns the pending attachment.
317
- * @throws when the file cannot be read or the store rejects it.
318
- */
319
- async function attachLocalFile(store, cwd, path) {
320
- const absolute = resolve(cwd, path);
321
- const name = basename(absolute);
322
- const data = new Uint8Array(await readFile(absolute));
323
- const mediaType = IMAGE_MEDIA_TYPES[extname(absolute).toLowerCase()];
324
- if (mediaType !== void 0) {
325
- const [ref] = await store.saveImages([{
326
- data,
327
- mediaType,
328
- name
329
- }]);
330
- /* v8 ignore next -- saveImages returns one ref per input */
331
- if (ref === void 0) throw new Error(`the attachment store returned no reference for ${name}`);
332
- return {
333
- name,
334
- block: {
335
- type: "image",
336
- attachment: ref
337
- }
338
- };
339
- }
340
- return {
341
- name,
342
- block: {
343
- type: "file",
344
- attachment: await store.saveFile({
345
- data,
346
- name
347
- })
348
- }
349
- };
350
- }
351
- //#endregion
352
296
  //#region lib/types/diff.js
353
297
  /**
354
298
  * Line diff for tool cards: a longest-common-subsequence alignment of old and
@@ -972,6 +916,474 @@ function foldMarker(hidden, opens) {
972
916
  return `… ${String(hidden)} more row${hidden === 1 ? "" : "s"} · ${FOLD_KEYS[opens]}`;
973
917
  }
974
918
  //#endregion
919
+ //#region lib/types/background.js
920
+ /**
921
+ * `Ctrl+B`: move the bound Agent's running tool calls to the background.
922
+ *
923
+ * A `tools/execute` around-wrapper tracks every root call an Agent dispatches
924
+ * while a job registry is composed. Moving a call registers a `tool` job in
925
+ * `ctx.jobs` whose settlement is the tool body's own outcome, and answers the
926
+ * call at once with a result that names the job, so the turn continues while
927
+ * the body keeps running. The registry and `dsh-tool-jobs` then own the rest:
928
+ * the completion notice reaches the owning Agent, `job_output` reads the
929
+ * result, and `job_kill` stops the body through the wrapper's own signal.
930
+ *
931
+ * The registry fuses the caller's signal into every body, so stopping the
932
+ * turn that dispatched a moved call still stops that call. {@link
933
+ * ToolBackgrounder.holdStopped} keeps such a settlement from waking the Agent
934
+ * the user just stopped.
935
+ * @module @deepseek-ai/dsh-tui-app/background
936
+ */
937
+ /** The text a moved call's result opens with; the job id follows it. */
938
+ const MOVED_PREFIX = "The user moved this call to the background. It keeps running as job ";
939
+ /** Matches a moved call's result text and captures the job id. */
940
+ const MOVED_PATTERN = /^The user moved this call to the background\. It keeps running as job (\S+?)\./u;
941
+ /** Detail of a moved call that stopped because the turn that dispatched it was stopped. */
942
+ const STOPPED_WITH_TURN = "stopped with the turn that called it";
943
+ /**
944
+ * Bound of the registry wait that holds a stopped call's job: the longest
945
+ * delay a Node timer takes (2^31 - 1 ms, about 24.8 days). The wait ends when
946
+ * the job settles, which the abort that stopped the turn brings about; the
947
+ * bound only has to outlast that.
948
+ */
949
+ const HOLD_WAIT_MS = 2147483647;
950
+ /**
951
+ * The model-facing result of a call the user moved to the background.
952
+ * @param id - the job that took the call over.
953
+ * @returns the result text: the job id, how its outcome arrives, and how to stop it.
954
+ */
955
+ function movedResultText(id) {
956
+ return `${MOVED_PREFIX}${id}. You are notified when it finishes; read its result with job_output, or stop it with job_kill. Continue with steps that do not depend on it.`;
957
+ }
958
+ /**
959
+ * The job a moved call's logged result names, so a replayed log draws the
960
+ * card the live session drew.
961
+ * @param content - the logged result content.
962
+ * @returns the job id, or undefined for every other result.
963
+ */
964
+ function movedJobId(content) {
965
+ const first = content[0];
966
+ if (content.length !== 1 || first?.type !== "text") return void 0;
967
+ return MOVED_PATTERN.exec(first.text)?.[1];
968
+ }
969
+ /**
970
+ * The text of a tool result as a job result: text blocks as they are, and a
971
+ * placeholder naming each other block, which a string result cannot carry.
972
+ * @param content - the result content.
973
+ * @returns the joined text.
974
+ */
975
+ function resultText(content) {
976
+ return content.map((block) => block.type === "text" ? block.text : `[${block.type} omitted]`).join("\n");
977
+ }
978
+ /**
979
+ * Tracks root tool calls and moves them to the job registry on request.
980
+ * One instance serves one terminal application.
981
+ */
982
+ var ToolBackgrounder = class {
983
+ options;
984
+ /** Tracked calls whose body has not settled, in dispatch order. */
985
+ calls = /* @__PURE__ */ new Map();
986
+ /** Jobs a body registered for itself while it ran, for as long as the body runs. */
987
+ innerJobs = /* @__PURE__ */ new Set();
988
+ /** The job a moved call's body registered for itself, by the moved call's job. */
989
+ outputs = /* @__PURE__ */ new Map();
990
+ constructor(options) {
991
+ this.options = options;
992
+ }
993
+ /**
994
+ * The `tools/execute` listener body. A nested call, a call without an
995
+ * Agent, and every call while no registry is composed pass straight
996
+ * through. A tracked call returns the body's own outcome, or the moved
997
+ * result as soon as {@link moveAll} hands it to the registry.
998
+ * @param exec - the call about to dispatch.
999
+ * @param next - the rest of the around-dispatch chain and the body.
1000
+ * @returns the call's outcome.
1001
+ */
1002
+ async around(exec, next) {
1003
+ const agent = exec.agent;
1004
+ if (agent === void 0 || exec.parent !== void 0 || this.options.jobs() === void 0) return next();
1005
+ keepSignalWritable(exec);
1006
+ const outer = exec.signal;
1007
+ const stop = new AbortController();
1008
+ exec.signal = AbortSignal.any([outer, stop.signal]);
1009
+ const moved = Promise.withResolvers();
1010
+ const settled = Promise.withResolvers();
1011
+ const body = settled.promise;
1012
+ const call = {
1013
+ callId: exec.callId,
1014
+ name: exec.name,
1015
+ agent,
1016
+ arguments: exec.arguments,
1017
+ outer,
1018
+ stop,
1019
+ body,
1020
+ answer: moved.resolve
1021
+ };
1022
+ this.calls.set(call.callId, call);
1023
+ this.options.changed();
1024
+ (async () => next())().then(settled.resolve, settled.reject);
1025
+ const restore = () => {
1026
+ exec.signal = outer;
1027
+ this.calls.delete(call.callId);
1028
+ if (call.inner !== void 0) this.innerJobs.delete(call.inner);
1029
+ this.options.changed();
1030
+ };
1031
+ body.then(restore, restore);
1032
+ return Promise.race([body, moved.promise]);
1033
+ }
1034
+ /**
1035
+ * The calls of one Agent still running in the foreground.
1036
+ * @param agent - the Agent whose calls to list.
1037
+ * @returns the calls in dispatch order.
1038
+ */
1039
+ running(agent) {
1040
+ return this.foreground(agent);
1041
+ }
1042
+ /**
1043
+ * Move every foreground call of one Agent to the registry. A call the
1044
+ * registry refuses keeps running in the foreground.
1045
+ * @param jobs - the composed job registry.
1046
+ * @param agent - the Agent whose calls to move.
1047
+ * @param label - the one-line job label for a call.
1048
+ * @returns the moved calls and the refusals.
1049
+ */
1050
+ moveAll(jobs, agent, label) {
1051
+ const report = {
1052
+ moved: [],
1053
+ refused: []
1054
+ };
1055
+ for (const call of this.foreground(agent)) {
1056
+ let id;
1057
+ try {
1058
+ id = jobs.start({
1059
+ kind: "tool",
1060
+ label: label(call),
1061
+ owner: agent.id,
1062
+ run: (handle) => ({
1063
+ cancel: (reason) => {
1064
+ call.stop.abort(reason);
1065
+ },
1066
+ done: call.body.then((result) => this.outcome(call, handle, result), (error) => ({
1067
+ status: "failed",
1068
+ detail: describeFailure(error)
1069
+ }))
1070
+ })
1071
+ });
1072
+ } catch (error) {
1073
+ report.refused.push(`${call.name}: ${describeFailure(error)}`);
1074
+ continue;
1075
+ }
1076
+ call.job = id;
1077
+ if (call.inner !== void 0) this.outputs.set(id, call.inner);
1078
+ const text = movedResultText(id);
1079
+ call.answer({
1080
+ isError: true,
1081
+ error: { message: text },
1082
+ content: [{
1083
+ type: "text",
1084
+ text
1085
+ }]
1086
+ });
1087
+ report.moved.push({
1088
+ callId: call.callId,
1089
+ name: call.name,
1090
+ id
1091
+ });
1092
+ }
1093
+ if (report.moved.length > 0) this.options.changed();
1094
+ return report;
1095
+ }
1096
+ /**
1097
+ * Keep the jobs of moved calls whose dispatching turn was just stopped from
1098
+ * waking their Agent: a live registry wait makes their settlement count as
1099
+ * delivered, so `dsh-tool-jobs` sends no completion notice. Call it right
1100
+ * after cancelling the Agent, before the bodies observe the abort.
1101
+ * @param jobs - the composed job registry.
1102
+ * @param agent - the Agent whose turn was stopped.
1103
+ * @returns how many moved calls stop with the turn.
1104
+ */
1105
+ holdStopped(jobs, agent) {
1106
+ let held = 0;
1107
+ for (const call of this.calls.values()) {
1108
+ if (call.agent !== agent || call.job === void 0 || !call.outer.aborted) continue;
1109
+ held += 1;
1110
+ jobs.wait(call.job, HOLD_WAIT_MS, agent.id).catch(ignoreGone);
1111
+ }
1112
+ return held;
1113
+ }
1114
+ /**
1115
+ * Follow one registry event. A job registered while a tracked body of the
1116
+ * same owner runs, of the body's own tool kind and with its command as the
1117
+ * label when it has one, is that body's own job, which is not background
1118
+ * work of its own. A removed job is no longer anyone's output.
1119
+ * @param event - the registry event.
1120
+ */
1121
+ observe(event) {
1122
+ if (event.type === "removed") {
1123
+ const removed = event.job.id;
1124
+ this.outputs = new Map([...this.outputs].filter(([, inner]) => inner !== removed));
1125
+ return;
1126
+ }
1127
+ if (event.type !== "registered") return;
1128
+ const { job } = event;
1129
+ const call = [...this.calls.values()].find((candidate) => candidate.inner === void 0 && candidate.agent.id === job.owner && candidate.name === job.kind && (commandOf(candidate.arguments) ?? job.label) === job.label);
1130
+ if (call === void 0) return;
1131
+ call.inner = job.id;
1132
+ this.innerJobs.add(job.id);
1133
+ if (call.job !== void 0) this.outputs.set(call.job, job.id);
1134
+ }
1135
+ /**
1136
+ * Whether a job is a tracked body's own, which the terminal does not list
1137
+ * as background work while that body runs.
1138
+ * @param id - the job to test.
1139
+ * @returns true while the body that registered it runs.
1140
+ */
1141
+ isInner(id) {
1142
+ return this.innerJobs.has(id);
1143
+ }
1144
+ /**
1145
+ * The job whose output ring shows a job's live output: the job its moved
1146
+ * body registered for itself while that job is still registered, else the
1147
+ * job itself.
1148
+ * @param id - the job the user opened.
1149
+ * @returns the job to read output from.
1150
+ */
1151
+ outputOf(id) {
1152
+ return this.outputs.get(id) ?? id;
1153
+ }
1154
+ /**
1155
+ * The tracked calls of one Agent not yet moved.
1156
+ * @param agent - the Agent whose calls to list.
1157
+ * @returns the calls in dispatch order.
1158
+ */
1159
+ foreground(agent) {
1160
+ return [...this.calls.values()].filter((call) => call.agent === agent && call.job === void 0);
1161
+ }
1162
+ /**
1163
+ * The terminal outcome of a moved call. The result text also goes on the
1164
+ * ring's `log` channel, which observers read and the model's own read skips.
1165
+ * @param call - the moved call.
1166
+ * @param handle - the job's producer face.
1167
+ * @param result - the body's normalized outcome.
1168
+ * @returns the job outcome.
1169
+ */
1170
+ outcome(call, handle, result) {
1171
+ const text = resultText(result.content);
1172
+ if (text !== "") handle.append(text, { channel: "log" });
1173
+ if (!result.isError) return {
1174
+ status: "completed",
1175
+ ...text === "" ? {} : { result: text }
1176
+ };
1177
+ if (call.stop.signal.aborted) return { status: "killed" };
1178
+ if (call.outer.aborted) return {
1179
+ status: "killed",
1180
+ detail: STOPPED_WITH_TURN
1181
+ };
1182
+ return {
1183
+ status: "failed",
1184
+ detail: result.error.message.replace(/\n[\s\S]*$/u, ""),
1185
+ result: text
1186
+ };
1187
+ }
1188
+ };
1189
+ /**
1190
+ * Replace the execution's `signal` data property with an accessor pair over
1191
+ * the same value. The registry freezes the execution when the call's result
1192
+ * commits, which makes a data property read-only; a moved body is still
1193
+ * running then, and both this wrapper and the registry restore the signal
1194
+ * when it settles. An accessor keeps those writes legal after the freeze.
1195
+ * @param exec - the call about to dispatch.
1196
+ */
1197
+ function keepSignalWritable(exec) {
1198
+ let current = exec.signal;
1199
+ Object.defineProperty(exec, "signal", {
1200
+ get: () => current,
1201
+ set: (signal) => {
1202
+ current = signal;
1203
+ },
1204
+ enumerable: true
1205
+ });
1206
+ }
1207
+ /**
1208
+ * The `command` argument of a shell-style call.
1209
+ * @param args - the call's parsed arguments.
1210
+ * @returns the command, or undefined when the arguments carry none.
1211
+ */
1212
+ function commandOf(args) {
1213
+ if (typeof args !== "object" || args === null || !("command" in args)) return void 0;
1214
+ return typeof args.command === "string" ? args.command : void 0;
1215
+ }
1216
+ /**
1217
+ * Drop the rejection of a hold's registry wait. A wait on a live job its
1218
+ * owner holds rejects only once the job left the registry, and then nothing
1219
+ * is left to hold.
1220
+ * @param _gone - the rejection.
1221
+ */
1222
+ /* v8 ignore next -- a live owned job settles before it can leave the registry */
1223
+ function ignoreGone(_gone) {}
1224
+ /** What separates two facts on one line. */
1225
+ const SEPARATOR$5 = " · ";
1226
+ /** The key the running spinner names while a foreground call can be moved. */
1227
+ const BACKGROUND_KEY_HINT = "Ctrl+B background";
1228
+ /** What the `/jobs` picker says between its heading and its rows. */
1229
+ const JOBS_PICKER_HINT = "Enter shows the output · Ctrl+K stops the highlighted job";
1230
+ /**
1231
+ * Whether a job is still running or stopping.
1232
+ * @param job - the job.
1233
+ * @returns true until the job settles.
1234
+ */
1235
+ function isLive(job) {
1236
+ return job.status === "running" || job.status === "stopping";
1237
+ }
1238
+ /**
1239
+ * How long a job has run: until now while live, until it settled otherwise.
1240
+ * @param job - the job.
1241
+ * @param now - the wall clock.
1242
+ * @returns the formatted elapsed time.
1243
+ */
1244
+ function jobElapsed(job, now) {
1245
+ return formatElapsed((job.finishedAt ?? now) - job.startedAt);
1246
+ }
1247
+ /**
1248
+ * The one line drawn above the editor while a background job runs: the live
1249
+ * count, each job's id, label, and elapsed time, and the command that lists
1250
+ * them, cut to the width.
1251
+ * @param jobs - the bound session's background jobs, in registration order.
1252
+ * @param render - the palette, the wall clock, and the columns the line fits.
1253
+ * @returns the dim line, or the empty string while no job runs.
1254
+ */
1255
+ function renderJobsLine(jobs, render) {
1256
+ const live = jobs.filter(isLive);
1257
+ if (live.length === 0) return "";
1258
+ const { palette } = render;
1259
+ const text = [`${String(live.length)} in background`, ...live.map((job) => `${job.id} ${oneLine(job.label)} ${jobElapsed(job, render.now)}`)].join(SEPARATOR$5);
1260
+ const tail = `${SEPARATOR$5}/jobs`;
1261
+ const room = Math.max(1, render.width - 2 - tail.length);
1262
+ return `${palette.accent("◇")} ${palette.dim(`${truncateToWidth(text, room, "…")}${tail}`)}`;
1263
+ }
1264
+ /**
1265
+ * One `/jobs` picker row.
1266
+ * @param job - the job.
1267
+ * @param now - the wall clock.
1268
+ * @returns the id as the label, and status, elapsed time, and job label as the description.
1269
+ */
1270
+ function jobChoice(job, now) {
1271
+ return {
1272
+ value: job.id,
1273
+ label: job.id,
1274
+ description: [
1275
+ job.status,
1276
+ jobElapsed(job, now),
1277
+ oneLine(job.label)
1278
+ ].join(SEPARATOR$5)
1279
+ };
1280
+ }
1281
+ /**
1282
+ * The detail page of one job: its status line, label, start, and the tail
1283
+ * of its retained output.
1284
+ * @param job - the job.
1285
+ * @param chunks - the retained output chunks, in offset order.
1286
+ * @param now - the wall clock.
1287
+ * @returns the page rows.
1288
+ */
1289
+ function jobDetailRows(job, chunks, now) {
1290
+ const rows = [
1291
+ [
1292
+ job.status,
1293
+ ...job.detail === void 0 ? [] : [job.detail],
1294
+ jobElapsed(job, now)
1295
+ ].join(SEPARATOR$5),
1296
+ job.label,
1297
+ `started ${formatTimestamp(job.startedAt)} UTC`
1298
+ ];
1299
+ if (job.progress !== void 0) rows.push(job.progress);
1300
+ const output = chunks.map((chunk) => chunk.text).join("").replace(/\n$/u, "");
1301
+ if (output === "") {
1302
+ rows.push("", isLive(job) ? "no output yet" : "no output");
1303
+ return rows;
1304
+ }
1305
+ const lines = output.split("\n");
1306
+ const kept = lines.slice(-200);
1307
+ rows.push("", kept.length < lines.length ? `output · last ${String(kept.length)} of ${String(lines.length)} lines` : "output");
1308
+ rows.push(...kept);
1309
+ return rows;
1310
+ }
1311
+ /**
1312
+ * The transient line one settlement shows.
1313
+ * @param job - the settled job.
1314
+ * @param notified - whether a completion notice goes to the Agent.
1315
+ * @returns the line.
1316
+ */
1317
+ function settledToast(job, notified) {
1318
+ const parts = [`◇ ${job.id} ${job.status}`, oneLine(job.label)];
1319
+ if (notified) parts.push("agent notified");
1320
+ return parts.join(SEPARATOR$5);
1321
+ }
1322
+ /**
1323
+ * A label on one line.
1324
+ * @param label - the job label, which a command can spread over lines.
1325
+ * @returns the label with each line break as one space.
1326
+ */
1327
+ function oneLine(label) {
1328
+ return label.replace(/\s*\n\s*/gu, " ");
1329
+ }
1330
+ //#endregion
1331
+ //#region lib/types/attach.js
1332
+ /**
1333
+ * `/attach`: read a local file and admit it into the attachment store as the
1334
+ * image or file block the next prompt carries, the way the browser composer
1335
+ * uploads a dropped file.
1336
+ * @module @deepseek-ai/dsh-tui-app/attach
1337
+ */
1338
+ /** Image media types by file extension; every other extension attaches as a file. */
1339
+ const IMAGE_MEDIA_TYPES = {
1340
+ ".png": "image/png",
1341
+ ".jpg": "image/jpeg",
1342
+ ".jpeg": "image/jpeg",
1343
+ ".webp": "image/webp",
1344
+ ".gif": "image/gif"
1345
+ };
1346
+ /**
1347
+ * Read `path` (relative to `cwd`) and store it.
1348
+ * @param store - the composed attachment store.
1349
+ * @param cwd - the directory relative paths resolve against.
1350
+ * @param path - the file to attach.
1351
+ * @returns the pending attachment.
1352
+ * @throws when the file cannot be read or the store rejects it.
1353
+ */
1354
+ async function attachLocalFile(store, cwd, path) {
1355
+ const absolute = resolve(cwd, path);
1356
+ const name = basename(absolute);
1357
+ const data = new Uint8Array(await readFile(absolute));
1358
+ const mediaType = IMAGE_MEDIA_TYPES[extname(absolute).toLowerCase()];
1359
+ if (mediaType !== void 0) {
1360
+ const [ref] = await store.saveImages([{
1361
+ data,
1362
+ mediaType,
1363
+ name
1364
+ }]);
1365
+ /* v8 ignore next -- saveImages returns one ref per input */
1366
+ if (ref === void 0) throw new Error(`the attachment store returned no reference for ${name}`);
1367
+ return {
1368
+ name,
1369
+ block: {
1370
+ type: "image",
1371
+ attachment: ref
1372
+ }
1373
+ };
1374
+ }
1375
+ return {
1376
+ name,
1377
+ block: {
1378
+ type: "file",
1379
+ attachment: await store.saveFile({
1380
+ data,
1381
+ name
1382
+ })
1383
+ }
1384
+ };
1385
+ }
1386
+ //#endregion
975
1387
  //#region lib/types/catalog.js
976
1388
  /**
977
1389
  * Terminal rows for the browser's settings, plugins, subagents, deliverables,
@@ -3871,6 +4283,19 @@ var ToolBlock = class {
3871
4283
  this.measured = false;
3872
4284
  }
3873
4285
  /**
4286
+ * Settle the card as moved to the background: the glyph takes the accent
4287
+ * colour and the body ends on `lines` instead of a result.
4288
+ * @param lines - the rows naming the job that took the call over.
4289
+ */
4290
+ setBackground(lines) {
4291
+ this.resultLines = lines;
4292
+ this.resultCode = void 0;
4293
+ this.resultDiff = void 0;
4294
+ this.status = "background";
4295
+ this.revision += 1;
4296
+ this.measured = false;
4297
+ }
4298
+ /**
3874
4299
  * Unroll the card's rows on the application's frame tick instead of drawing
3875
4300
  * them all in one frame: now, and again whenever a call or a result makes
3876
4301
  * the card grow.
@@ -4022,11 +4447,18 @@ var ToolBlock = class {
4022
4447
  }
4023
4448
  /**
4024
4449
  * The colour of this card's status glyph.
4025
- * @returns warning while running, success once done, error once failed.
4450
+ * @returns warning while running, success once done, error once failed, accent once moved to the background.
4026
4451
  */
4027
4452
  statusStyle() {
4028
4453
  const palette = this.theme.palette;
4029
- return this.status === "running" ? palette.warning : this.status === "done" ? palette.success : palette.error;
4454
+ switch (this.status) {
4455
+ case "running": return palette.warning;
4456
+ case "done": return palette.success;
4457
+ case "error": return palette.error;
4458
+ case "background": return palette.accent;
4459
+ /* v8 ignore next 2 -- closed-union exhaustiveness guard */
4460
+ default: return assertNever(this.status, "tool card status");
4461
+ }
4030
4462
  }
4031
4463
  /**
4032
4464
  * The one row a folded subagent card draws, led by the status-coloured
@@ -4048,7 +4480,7 @@ var ToolBlock = class {
4048
4480
  return truncateToWidth(`${palette.warning("◆")} ${name}${description}${meta}`, width, "…");
4049
4481
  }
4050
4482
  const started = this.status === "done" && this.resultLines[0]?.startsWith("started ") === true;
4051
- const tag = this.status === "error" ? palette.error("[failed]") : started ? palette.dim("[started]") : palette.success("[done]");
4483
+ const tag = this.status === "error" ? palette.error("[failed]") : this.status === "background" ? palette.accent("[background]") : started ? palette.dim("[started]") : palette.success("[done]");
4052
4484
  const cut = truncateToWidth(`${started ? palette.dim("◆") : this.statusStyle()("◆")} ${palette.dim(facts.description === "" ? this.toolName : facts.description)}${meta}`, Math.max(1, width - visibleWidth(tag) - 1), "…");
4053
4485
  return truncateToWidth(`${cut}${" ".repeat(Math.max(1, width - visibleWidth(cut) - visibleWidth(tag)))}${tag}`, width, "…");
4054
4486
  }
@@ -5712,6 +6144,7 @@ const KEY_LINES = {
5712
6144
  "While follow-ups wait: ↑ on an empty input edits the newest · Shift+↑ selects one",
5713
6145
  "Ctrl+O folds every tool card and context row",
5714
6146
  "Ctrl+T todos · Ctrl+P parent session · Ctrl+L redraw · ? keys",
6147
+ "Ctrl+B moves running tool calls to the background · /jobs lists them",
5715
6148
  "Esc arms the stop · Esc again stops the turn",
5716
6149
  "Ctrl+C clears the input, twice quits · Ctrl+D quits an empty input"
5717
6150
  ],
@@ -5731,8 +6164,9 @@ const OPEN = { kind: "open" };
5731
6164
  /**
5732
6165
  * What one key press means where the keyboard is.
5733
6166
  *
5734
- * `Escape`, `Ctrl+O`, `Ctrl+G`, `Ctrl+T`, `Ctrl+P`, and `Ctrl+L` mean the
5735
- * same thing everywhere and are answered first. Everything else is the region's own.
6167
+ * `Escape`, `Ctrl+O`, `Ctrl+G`, `Ctrl+B`, `Ctrl+T`, `Ctrl+P`, and `Ctrl+L`
6168
+ * mean the same thing everywhere and are answered first. Everything else is
6169
+ * the region's own.
5736
6170
  * @param region - the region holding the keyboard.
5737
6171
  * @param data - the raw key bytes.
5738
6172
  * @returns the action to apply, or undefined when this region claims nothing
@@ -5743,6 +6177,7 @@ function resolveKey(region, data) {
5743
6177
  if (matchesKey(data, "escape")) return ESCAPE;
5744
6178
  if (matchesKey(data, "ctrl+o")) return FOLD_ALL;
5745
6179
  if (matchesKey(data, "ctrl+g")) return READER;
6180
+ if (matchesKey(data, "ctrl+b")) return { kind: "background" };
5746
6181
  if (matchesKey(data, "ctrl+t")) return { kind: "todos" };
5747
6182
  if (matchesKey(data, "ctrl+p")) return { kind: "parent" };
5748
6183
  if (matchesKey(data, "ctrl+l")) return { kind: "redraw" };
@@ -7744,6 +8179,8 @@ var PickPrompt = class extends ListPrompt {
7744
8179
  visible;
7745
8180
  /** What `Ctrl+S` does with the highlighted row, when the caller gave it a meaning. */
7746
8181
  onSave;
8182
+ /** What `Ctrl+K` does with the highlighted row, when the caller gave it a meaning. */
8183
+ onStop;
7747
8184
  constructor(palette, title, items, options = {}) {
7748
8185
  const rows = items.map((item) => ({ ...item }));
7749
8186
  const inForce = items.findIndex((item) => item.value === options.current);
@@ -7758,6 +8195,7 @@ var PickPrompt = class extends ListPrompt {
7758
8195
  this.inForce = inForce;
7759
8196
  this.visible = markedRows;
7760
8197
  this.onSave = options.onSave;
8198
+ this.onStop = options.onStop;
7761
8199
  if (inForce > 0) this.highlight(inForce);
7762
8200
  }
7763
8201
  /**
@@ -7787,10 +8225,10 @@ var PickPrompt = class extends ListPrompt {
7787
8225
  this.setQuery("");
7788
8226
  return;
7789
8227
  }
7790
- if (matchesKey(data, "ctrl+s")) {
8228
+ if (matchesKey(data, "ctrl+s") || matchesKey(data, "ctrl+k")) {
7791
8229
  const row = this.selected();
7792
8230
  const item = row === null ? void 0 : this.items.find((candidate) => candidate.value === row.value);
7793
- if (item !== void 0) this.onSave?.(item);
8231
+ if (item !== void 0) (matchesKey(data, "ctrl+s") ? this.onSave : this.onStop)?.(item);
7794
8232
  return;
7795
8233
  }
7796
8234
  const typed = typedText(data);
@@ -10519,10 +10957,12 @@ var ToastPane = class {
10519
10957
  * turns keystrokes into agent input, answers the approval and user-questions
10520
10958
  * seams for that Agent, and switches between sessions through its host. Above
10521
10959
  * the editor it draws an activity board of the open turn's todos and the
10522
- * latest descendant line. Under the editor it keeps two docked regions the
10523
- * keyboard can take over — the subagent panel and the status bar — and one
10524
- * repeating tick advances their elapsed counters and re-reads a stale
10525
- * subagent listing. A second tick, at its own period, brightens streamed
10960
+ * latest descendant line, and a live line while background jobs run; `Ctrl+B`
10961
+ * moves the running tool calls to those jobs (`./background.ts`). Under the
10962
+ * editor it keeps two docked regions the keyboard can take over — the
10963
+ * subagent panel and the status bar — and one repeating tick advances their
10964
+ * elapsed counters and the jobs line's, and re-reads a stale subagent
10965
+ * listing. A second tick, at its own period, brightens streamed
10526
10966
  * reply text and floats out reasoning, tool cards, and activity-board rows
10527
10967
  * that just landed, each only as far up the frame as the renderer repaints
10528
10968
  * without discarding the terminal's scrollback (`./screen.ts`).
@@ -10738,6 +11178,10 @@ const LOCAL_COMMANDS = [
10738
11178
  name: "subagents",
10739
11179
  description: "Browse the subagent sessions under this session (Enter opens one as a live session view)"
10740
11180
  },
11181
+ {
11182
+ name: "jobs",
11183
+ description: "Browse this session's background jobs (Enter shows the output, Ctrl+K stops one; Ctrl+B moves running tool calls here)"
11184
+ },
10741
11185
  {
10742
11186
  name: "parent",
10743
11187
  description: "Return from a subagent view or a /btw side agent to the session it was opened from"
@@ -10782,6 +11226,19 @@ const LOCAL_COMMAND_NAMES = new Set(LOCAL_COMMANDS.map((command) => command.name
10782
11226
  function isSubscriptionMethod(method) {
10783
11227
  return method.id !== "api-key";
10784
11228
  }
11229
+ /** Shown when `Ctrl+B` or `/jobs` is used and this composition has no `ctx.jobs`. */
11230
+ const JOBS_MISSING = "background jobs need a job registry in this composition";
11231
+ /**
11232
+ * Columns of a moved call's card headline its job label keeps. The label
11233
+ * reaches the model in the completion notice, so it names the call without
11234
+ * carrying a whole command. A presentation choice of this terminal surface,
11235
+ * not a deployment setting.
11236
+ */
11237
+ const JOB_LABEL_COLUMNS = 120;
11238
+ /** Why a job the user stopped from `/jobs` was killed, as the model reads it. */
11239
+ const USER_STOP_REASON = "stopped by the user";
11240
+ /** Shown when `Ctrl+B` is pressed while the turn runs no tool call. */
11241
+ const NOTHING_TO_BACKGROUND = "no tool call is running · Ctrl+B moves a running call to the background";
10785
11242
  /** Shown when `!` is submitted and this composition has no `ctx.shell`. */
10786
11243
  const SHELL_MISSING = "! needs a shell executor in this composition";
10787
11244
  /** Shown when a second `!` is submitted while one is still running. */
@@ -10849,6 +11306,14 @@ var TuiApp = class {
10849
11306
  queueDraft;
10850
11307
  /** Suppresses the empty-queue focus handoff during a synchronous inbox transfer. */
10851
11308
  transferringQueue = false;
11309
+ /** Holds {@link jobsLine} exactly while a background job of the bound session runs. */
11310
+ jobsSlot = new Container();
11311
+ /** The live background-jobs line above the editor. */
11312
+ jobsLine;
11313
+ /** The bound session's background jobs at the last read, in registration order. */
11314
+ backgroundJobs = [];
11315
+ /** Tracks root tool calls and moves them to background jobs on `Ctrl+B`. */
11316
+ backgrounder;
10852
11317
  /** Holds {@link panel} exactly while the bound session has subagent rows. */
10853
11318
  panelSlot = new Container();
10854
11319
  /** The terminal's alternate screen, which the reader draws on; see {@link AlternateScreen}. */
@@ -11070,6 +11535,13 @@ var TuiApp = class {
11070
11535
  };
11071
11536
  this.queue = new Text("", 0, 0);
11072
11537
  this.activity = new Text("", 0, 0);
11538
+ this.jobsLine = new Text("", 0, 0);
11539
+ this.backgrounder = new ToolBackgrounder({
11540
+ jobs: () => deps.ctx.get("jobs"),
11541
+ changed: () => {
11542
+ this.onForegroundCallsChanged();
11543
+ }
11544
+ });
11073
11545
  this.panel = new Text("", 0, 0);
11074
11546
  this.banner = new ViewBanner(palette);
11075
11547
  this.footer = new FooterBar(() => ({
@@ -11096,6 +11568,7 @@ var TuiApp = class {
11096
11568
  this.inspector,
11097
11569
  this.queueSlot,
11098
11570
  this.activitySlot,
11571
+ this.jobsSlot,
11099
11572
  this.banner,
11100
11573
  this.editor,
11101
11574
  this.panelSlot,
@@ -11158,7 +11631,11 @@ var TuiApp = class {
11158
11631
  }), ctx.on("user-questions/request", (request, next) => {
11159
11632
  if (!this.claimPrompt(request.agent)) return next();
11160
11633
  return this.askQuestions(request.questions, request.signal);
11161
- }), this.tui.addInputListener((data) => this.onKey(data)));
11634
+ }), ctx.on("tools/execute", (exec, next) => this.backgrounder.around(exec, next)), this.tui.addInputListener((data) => this.onKey(data)));
11635
+ const jobs = ctx.get("jobs");
11636
+ if (jobs !== void 0) this.disposers.push(jobs.events.subscribe({ owners: "all" }, (event) => {
11637
+ this.onJobEvent(event);
11638
+ }));
11162
11639
  const projections = ctx.get("sessionProjections");
11163
11640
  if (projections !== void 0) this.disposers.push(projections.onChanged((session) => {
11164
11641
  if (session === this.agent.session) this.refreshFooter();
@@ -11288,6 +11765,7 @@ var TuiApp = class {
11288
11765
  this.refreshQueue();
11289
11766
  this.refreshFooter();
11290
11767
  this.refreshSubagentPanel();
11768
+ this.refreshJobs();
11291
11769
  this.reconcileSubagents();
11292
11770
  }
11293
11771
  /**
@@ -11883,7 +12361,8 @@ var TuiApp = class {
11883
12361
  * one runs at a time, and a stopped app runs none.
11884
12362
  */
11885
12363
  updateTicker() {
11886
- if (!this.stopped && (this.turnStartedAt !== void 0 || this.subagentsStale || this.panelView.ticking)) {
12364
+ const jobsTicking = this.backgroundJobs.some(isLive);
12365
+ if (!this.stopped && (this.turnStartedAt !== void 0 || this.subagentsStale || this.panelView.ticking || jobsTicking)) {
11887
12366
  this.ticker ??= this.deps.tick(() => {
11888
12367
  this.onTick();
11889
12368
  }, this.deps.liveRefreshMs);
@@ -11898,6 +12377,7 @@ var TuiApp = class {
11898
12377
  onTick() {
11899
12378
  if (this.subagentsStale) this.reconcileSubagents();
11900
12379
  this.refreshSubagentPanel();
12380
+ if (this.backgroundJobs.some(isLive)) this.refreshJobs();
11901
12381
  if (this.turnStartedAt !== void 0) this.refreshFooter();
11902
12382
  }
11903
12383
  statusFacts() {
@@ -12010,6 +12490,137 @@ var TuiApp = class {
12010
12490
  return [describeFailure(error)];
12011
12491
  }
12012
12492
  }
12493
+ /** Redraw what follows the foreground calls: the spinner's key hint and the jobs line. */
12494
+ onForegroundCallsChanged() {
12495
+ this.refreshLoader();
12496
+ this.refreshJobs();
12497
+ }
12498
+ /**
12499
+ * Follow one job-registry event: the backgrounder learns which jobs belong
12500
+ * to a running call, the jobs line follows the bound session's jobs, and a
12501
+ * settlement of one of them shows a transient line.
12502
+ * @param event - the registry event.
12503
+ */
12504
+ onJobEvent(event) {
12505
+ this.backgrounder.observe(event);
12506
+ if (event.type === "output") return;
12507
+ const { job } = event;
12508
+ if (job.owner !== void 0 && job.owner !== this.agent.session.id) return;
12509
+ this.refreshJobs();
12510
+ if (event.type !== "settled" || event.cause === "teardown" || this.backgrounder.isInner(job.id)) return;
12511
+ this.showToast(settledToast(job, !event.awaited && event.cause === "producer"));
12512
+ }
12513
+ /**
12514
+ * Re-read the bound session's background jobs and redraw the live line
12515
+ * above the editor. A job a running call registered for itself is that
12516
+ * call's own work, not background work, and is left out while it runs.
12517
+ */
12518
+ refreshJobs() {
12519
+ const jobs = this.deps.ctx.get("jobs");
12520
+ this.backgroundJobs = jobs === void 0 ? [] : jobs.list(this.agent.session.id).filter((job) => !this.backgrounder.isInner(job.id));
12521
+ const text = renderJobsLine(this.backgroundJobs, {
12522
+ palette: this.deps.palette,
12523
+ now: this.deps.now(),
12524
+ width: this.contentWidth()
12525
+ });
12526
+ const mounted = this.jobsSlot.children.length > 0;
12527
+ if (text === "") {
12528
+ if (mounted) this.jobsSlot.removeChild(this.jobsLine);
12529
+ } else {
12530
+ if (!mounted) this.jobsSlot.addChild(this.jobsLine);
12531
+ this.jobsLine.setText(text);
12532
+ }
12533
+ this.updateTicker();
12534
+ this.tui.requestRender();
12535
+ }
12536
+ /**
12537
+ * Answer `Ctrl+B` during a turn: move every foreground call of the bound
12538
+ * Agent to a background job and say what moved.
12539
+ */
12540
+ moveToBackground() {
12541
+ const jobs = this.deps.ctx.get("jobs");
12542
+ if (jobs === void 0) {
12543
+ this.showToast(JOBS_MISSING);
12544
+ return;
12545
+ }
12546
+ const report = this.backgrounder.moveAll(jobs, this.agent, (call) => this.jobLabel(call));
12547
+ for (const refusal of report.refused) this.notice(`could not move ${refusal} to the background`, "error");
12548
+ const [first] = report.moved;
12549
+ if (first === void 0) {
12550
+ if (report.refused.length === 0) this.showToast(NOTHING_TO_BACKGROUND);
12551
+ return;
12552
+ }
12553
+ this.showToast(report.moved.length === 1 ? `◇ ${first.name} moved to the background as ${first.id} · /jobs lists it` : `◇ ${String(report.moved.length)} calls moved to the background · /jobs lists them`);
12554
+ }
12555
+ /**
12556
+ * The job label of a moved call: the tool name and its card headline on one line.
12557
+ * @param call - the call being moved.
12558
+ * @returns the label, cut to {@link JOB_LABEL_COLUMNS} columns.
12559
+ */
12560
+ jobLabel(call) {
12561
+ const title = this.toolBlocks.get(call.callId)?.title.split("\n", 1)[0] ?? "";
12562
+ return truncateToWidth(title === "" ? call.name : `${call.name} ${title}`, JOB_LABEL_COLUMNS, "…");
12563
+ }
12564
+ /**
12565
+ * Walk the bound session's background jobs: one row per job, `Enter` shows
12566
+ * its status and output, and `Ctrl+K` stops the highlighted one. The rows
12567
+ * are read again each time the list opens, so a return from a detail page
12568
+ * shows the statuses as they are now.
12569
+ */
12570
+ async browseJobs() {
12571
+ const jobs = this.deps.ctx.get("jobs");
12572
+ if (jobs === void 0) {
12573
+ this.notice(JOBS_MISSING, "error");
12574
+ return;
12575
+ }
12576
+ let visited;
12577
+ for (;;) {
12578
+ this.refreshJobs();
12579
+ const views = this.backgroundJobs;
12580
+ if (views.length === 0) {
12581
+ this.notice("no background jobs in this session · Ctrl+B moves a running tool call here");
12582
+ return;
12583
+ }
12584
+ const now = this.deps.now();
12585
+ const picked = await this.showModal(new PickPrompt(this.deps.palette, "Background jobs", views.map((view) => jobChoice(view, now)), {
12586
+ body: [JOBS_PICKER_HINT],
12587
+ ...visited === void 0 ? {} : { current: visited },
12588
+ onStop: (item) => {
12589
+ const view = views.find((candidate) => candidate.id === item.value);
12590
+ /* v8 ignore next -- the picker answers with one of the rows it was handed */
12591
+ if (view !== void 0) this.stopJob(jobs, view);
12592
+ }
12593
+ }));
12594
+ if (picked === void 0) return;
12595
+ const view = views.find((candidate) => candidate.id === picked.value);
12596
+ /* v8 ignore next -- the picker settles with one of the rows it was handed */
12597
+ if (view === void 0) return;
12598
+ visited = view.id;
12599
+ await this.showModal(new DetailPrompt(this.deps.palette, `Job ${view.id}`, this.jobDetail(jobs, view)));
12600
+ }
12601
+ }
12602
+ /**
12603
+ * The detail page of one job, read fresh: its status and the tail of the
12604
+ * output its body writes, which for a moved shell call is the shell's own
12605
+ * process job.
12606
+ * @param jobs - the registry the list was read from.
12607
+ * @param listed - the job as the list showed it.
12608
+ * @returns the page rows.
12609
+ */
12610
+ jobDetail(jobs, listed) {
12611
+ const owner = this.agent.session.id;
12612
+ const view = jobs.get(listed.id, owner);
12613
+ return jobDetailRows(view, jobs.readAt(this.backgrounder.outputOf(view.id), 0, owner).chunks, this.deps.now());
12614
+ }
12615
+ /**
12616
+ * Stop one job from `/jobs` and say whether anything was still running.
12617
+ * @param jobs - the registry the list was read from.
12618
+ * @param view - the highlighted job.
12619
+ */
12620
+ stopJob(jobs, view) {
12621
+ const outcome = jobs.kill(view.id, this.agent.session.id, USER_STOP_REASON);
12622
+ this.showToast(outcome === "requested" ? `stopping ${view.id}` : `${view.id} already finished`);
12623
+ }
12013
12624
  /**
12014
12625
  * Walk the agent's todo list: one row per item, and entering a row shows
12015
12626
  * that item in full with its position, the list's counts by status, and the
@@ -12306,6 +12917,10 @@ var TuiApp = class {
12306
12917
  }
12307
12918
  this.dispatchCommand("/effort");
12308
12919
  return { consume: true };
12920
+ case "background":
12921
+ if (this.agent.status !== "running") return this.focus === "editor" ? void 0 : { consume: true };
12922
+ this.moveToBackground();
12923
+ return { consume: true };
12309
12924
  case "todos":
12310
12925
  this.focusEditor();
12311
12926
  this.dispatchCommand("/todos");
@@ -12367,8 +12982,13 @@ var TuiApp = class {
12367
12982
  }
12368
12983
  this.disarmStop();
12369
12984
  this.agent.cancel({ kind: "user" }, { keepInbox: true });
12985
+ const jobs = this.deps.ctx.get("jobs");
12986
+ const moved = jobs === void 0 ? 0 : this.backgrounder.holdStopped(jobs, this.agent);
12370
12987
  const queued = this.agent.inbox.nextTurn.length + this.agent.inbox.nextStep.length;
12371
- this.notice(queued === 0 ? "stopping the turn…" : `stopping the turn… ${String(queued)} queued message(s) stay queued`);
12988
+ const facts = ["stopping the turn…"];
12989
+ if (queued > 0) facts.push(`${String(queued)} queued message(s) stay queued`);
12990
+ if (moved > 0) facts.push(`${String(moved)} background call(s) from this turn stop with it`);
12991
+ this.notice(facts.join(" "));
12372
12992
  return { consume: true };
12373
12993
  }
12374
12994
  /** Start the window in which an `Escape` reaching the editor does nothing at all. */
@@ -13241,6 +13861,9 @@ var TuiApp = class {
13241
13861
  case "parent":
13242
13862
  await this.leaveSubagent();
13243
13863
  return;
13864
+ case "jobs":
13865
+ await this.browseJobs();
13866
+ return;
13244
13867
  case "settings":
13245
13868
  await this.settings(argument);
13246
13869
  return;
@@ -14298,8 +14921,11 @@ var TuiApp = class {
14298
14921
  const block = this.toolBlocks.get(result.toolCallId);
14299
14922
  if (block === void 0) break;
14300
14923
  const isError = result.isError === true;
14301
- const body = toolResultBody(this.presentResult(block.name, this.toolArguments.get(result.toolCallId), result.content, isError, event.data.meta), result.content);
14302
- block.setResult(body.lines, isError, body.code, body.diff);
14924
+ const moved = isError ? movedJobId(result.content) : void 0;
14925
+ if (moved === void 0) {
14926
+ const body = toolResultBody(this.presentResult(block.name, this.toolArguments.get(result.toolCallId), result.content, isError, event.data.meta), result.content);
14927
+ block.setResult(body.lines, isError, body.code, body.diff);
14928
+ } else block.setBackground([`◇ moved to the background as ${moved} · /jobs lists it`]);
14303
14929
  this.spinners.delete(block);
14304
14930
  this.updateSpinTicker();
14305
14931
  this.fadeBlock((fade) => {
@@ -14519,10 +15145,16 @@ var TuiApp = class {
14519
15145
  const rest = message.slice(activity.length);
14520
15146
  return `${shimmer(palette, activity, this.deps.now())}${rest === "" ? "" : palette.dim(rest)}`;
14521
15147
  }
14522
- /** Draw the spinner label plus the current call's ↑send ↓receive suffix. */
15148
+ /**
15149
+ * Draw the spinner label plus the current call's ↑send ↓receive suffix,
15150
+ * and the key that moves a foreground call to the background while one runs.
15151
+ */
14523
15152
  refreshLoader() {
15153
+ const parts = [this.loaderActivity];
14524
15154
  const suffix = formatLiveUsage(this.liveUsage);
14525
- this.loader.setMessage(suffix === "" ? this.loaderActivity : `${this.loaderActivity} ${suffix}`);
15155
+ if (suffix !== "") parts.push(suffix);
15156
+ if (this.backgrounder.running(this.agent).length > 0) parts.push(`· ${BACKGROUND_KEY_HINT}`);
15157
+ this.loader.setMessage(parts.join(" "));
14526
15158
  }
14527
15159
  /**
14528
15160
  * Label the spinner for a tool-call delta before its card is paced.
@@ -75,6 +75,7 @@
75
75
  "@deepseek-ai/dsh-commands": "0.1.7-rc.2",
76
76
  "@deepseek-ai/dsh-compaction": "0.1.7-rc.2",
77
77
  "@deepseek-ai/dsh-goal": "0.1.7-rc.2",
78
+ "@deepseek-ai/dsh-jobs": "0.1.7-rc.2",
78
79
  "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
79
80
  "@deepseek-ai/dsh-llm-retry": "0.1.7-rc.2",
80
81
  "@deepseek-ai/dsh-permission-presets": "0.1.7-rc.2",
@@ -105,6 +106,8 @@
105
106
  "@deepseek-ai/dsh-commands": "0.1.7-rc.2",
106
107
  "@deepseek-ai/dsh-compaction": "0.1.7-rc.2",
107
108
  "@deepseek-ai/dsh-goal": "0.1.7-rc.2",
109
+ "@deepseek-ai/dsh-jobs": "0.1.7-rc.2",
110
+ "@deepseek-ai/dsh-jobs-local": "0.1.7-rc.2",
108
111
  "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
109
112
  "@deepseek-ai/dsh-llm-retry": "0.1.7-rc.2",
110
113
  "@deepseek-ai/dsh-permission-presets": "0.1.7-rc.2",
@@ -121,6 +124,7 @@
121
124
  "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
122
125
  "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
123
126
  "@deepseek-ai/dsh-token-meter": "0.1.7-rc.2",
127
+ "@deepseek-ai/dsh-tool-jobs": "0.1.7-rc.2",
124
128
  "@deepseek-ai/dsh-tool-todo": "0.1.7-rc.2",
125
129
  "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
126
130
  "@deepseek-ai/dsh-user-approval": "0.1.7-rc.2",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songtonyli/dsh-cli",
3
- "version": "0.1.51",
3
+ "version": "0.1.52",
4
4
  "description": "The dsh terminal agent: an interactive TUI over the DeepSeek Harness, with its whole Node runtime bundled in one install.",
5
5
  "license": "MIT",
6
6
  "type": "module",