@songtonyli/dsh-cli 0.1.35 → 0.1.36

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.35; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.36; `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.35 (deepseek-harness 0.1.7-alpha.1)')
21
+ console.log('@songtonyli/dsh-cli 0.1.36 (deepseek-harness 0.1.7-alpha.1)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -47,9 +47,9 @@
47
47
  "micromark-extension-gfm": "^3.0.0",
48
48
  "micromark-util-sanitize-uri": "^2.0.1",
49
49
  "simple-icons": "16.31.0",
50
+ "@deepseek-ai/cordis": "^4.0.3",
50
51
  "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1",
51
- "@deepseek-ai/dsh-util-workspace-path": "^0.1.7-alpha.1",
52
- "@deepseek-ai/cordis": "^4.0.3"
52
+ "@deepseek-ai/dsh-util-workspace-path": "^0.1.7-alpha.1"
53
53
  },
54
54
  "files": [
55
55
  "lib/index.js",
@@ -158,7 +158,7 @@ window.__ModuleLoader__.load({
158
158
  const SCROLLBAR_LINGER_MS = 2e3;
159
159
  /** Format complete-build metadata for the local brand badge. */
160
160
  function localBuildVersion() {
161
- return `0.1.7-alpha.1-320dc47` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
161
+ return `0.1.7-alpha.1-cef91e1` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
162
162
  }
163
163
  /** Each panel row subscribes only to its own selection state. */
164
164
  function PanelRow({ id, label, wide, usePanelInfo, selectPanel, renderSlot }) {
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/llm/llm-cursor/README.md
5
- README.md: ebde9246984fdce1e308ddd1f1fe8d4a8bea8a0b
6
- README.zh.md: 6f9e1fba4a59dba6425d31baa6f185e2116a040e
5
+ README.md: fdcaf4a59da59d5321eb4d17e83722ac3556727e
6
+ README.zh.md: 67bbd5e7cd7b6bbcdc2e83de20e381d88713e793
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
9
9
 
10
10
  ## Summary
11
11
 
12
- `@deepseek-ai/dsh-llm-cursor` registers the always-on `cursor` route, signs in with a Cursor subscription through PKCE, and streams each harness step as one unofficial Connect/protobuf HTTP/2 `AgentService/Run`. Settings → Models shows a Cursor card with Sign in; TUI `/login llm-cursor/cursor` lists the same flow. This package can run beside the [DeepSeek](../llm-deepseek/README.md) and [pi-ai](../llm-pi-ai/README.md) adapters.
12
+ `@deepseek-ai/dsh-llm-cursor` registers the always-on `cursor` route, signs in with a Cursor subscription through PKCE, and streams harness steps over unofficial Connect/protobuf HTTP/2 `AgentService/Run` streams; the steps of one turn share a Run while the adapter can resume it. Settings → Models shows a Cursor card with Sign in; TUI `/login llm-cursor/cursor` lists the same flow. This package can run beside the [DeepSeek](../llm-deepseek/README.md) and [pi-ai](../llm-pi-ai/README.md) adapters.
13
13
 
14
14
  ## Table of Contents
15
15
 
@@ -47,6 +47,8 @@ A request selects the route with `provider: cursor`. Model ids pass through; bun
47
47
  | `apiKeyEnv` | `CURSOR_ACCESS_TOKEN` | Credential reference resolved per request before a stored grant or harvest |
48
48
  | `reuseInstalledCursorLogin` | `true` | Whether a request may reuse a Cursor IDE or CLI login already on this machine |
49
49
  | `streamIdleTimeoutMs` | `300,000` | Maximum provider idle time per outstanding stream read |
50
+ | `parkedRunTimeoutMs` | `1,800,000` | How long a Run parked on tool calls waits for their results before it is cancelled |
51
+ | `toolCallSettleMs` | `1,000` | Wait for further parallel tool calls when Cursor has not yet sent the checkpoint that ends the model message |
50
52
  | `retryPolicy` | normal, 5 retries | Provider-owned retry policy executed by `dsh-llm-retry` |
51
53
 
52
54
  The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-llm-cursor) is the exhaustive source for every accepted field and its JSDoc.
@@ -64,9 +66,9 @@ Sign-out is `deleteRecord` on that key. It does not revoke the session at Cursor
64
66
 
65
67
  Request-time token order is: launch-environment `CURSOR_ACCESS_TOKEN`, then the stored OAuth grant (refresh inside `modifyRecord` when near expiry), then optional Keychain / `state.vscdb` harvest when `reuseInstalledCursorLogin` is true. A stored DSH login wins over harvest.
66
68
 
67
- Each DSH model step is a new HTTP/2 Connect `Run` rebuilt from harness history, system prompt, and MCP tool definitions (`providerIdentifier: dsh`, `clientName: dsh`). Cursor's server builds the model prompt from `root_prompt_messages_json`, never renders `conversation_state.turns` into it, and discards a `{"role":"system"}` entry there in favour of its own prompt. The adapter therefore publishes the system prompt as a `<rules>` user prompt message and replays every prior turn as `user`, `assistant`, and `tool` prompt messages, naming historic MCP calls `mcp_dsh_<tool>` as Cursor does; the turn structures ride along for the server's bookkeeping. The request-context answer adds one global Cursor rule telling the model that Cursor's built-in tools return a rejection here and that the `mcp_dsh_` tools are the ones to call.
69
+ A new Run is rebuilt from harness history, system prompt, and MCP tool definitions (`providerIdentifier: dsh`, `clientName: dsh`). Cursor's server builds the model prompt from `root_prompt_messages_json`, never renders `conversation_state.turns` into it, and discards a `{"role":"system"}` entry there in favour of its own prompt. The adapter therefore publishes the system prompt as a `<rules>` user prompt message and replays every prior turn as `user`, `assistant`, and `tool` prompt messages, writing each historic harness tool call as the `CallDynamicTool` call Cursor records for an MCP tool; the turn structures ride along for the server's bookkeeping. A Cursor CLI Run exposes MCP tools to the model only through `GetDynamicTools` and `CallDynamicTool`, so the request-context answer adds one global Cursor rule telling the model that Cursor's built-in tools return a rejection here, that harness tools are called with `CallDynamicTool` in namespace `dsh`, and which tool names exist.
68
70
 
69
- Text, thinking, usage, and MCP tool calls become `StreamChunk`. An MCP tool call finishes the stream so the agent loop can run the tool locally. The next Run replays that in-flight turn with its results and sends a fixed continuation notice as the user message a Run requires; a `resumeAction` is not used because the server restarts the turn from its user message instead of continuing it. A Cursor-native or CLI Pi workspace exec (`read`, `shell`, `piRead`, and kin) is answered with its typed rejection naming the harness tool to call instead, so the Run continues and the model reads the refusal as a tool outcome. A CLI hook is answered with an empty matching response. An MCP-state exec returns the advertised `mcp_dsh_` tools. Any other exec this build cannot type is answered with ExecClientThrow so the Run continues. An exec with no payload still fails the step.
71
+ Text, thinking, usage, and MCP tool calls become `StreamChunk`. MCP tool calls end the step once Cursor sends the checkpoint that follows the model's last parallel call, or after `toolCallSettleMs` without a frame. When the request names a Session and is not a compaction or title request, the Run then parks: the adapter keeps the stream open with a `clientHeartbeat` every five seconds. The next request from that Session resumes it when its history before the last assistant message is unchanged and that message is followed only by the pending calls' results and harness-injected user-role context; the adapter answers each call with `mcpResult` on the same stream, appends such context to the last result, and keeps reading. Any other request, a Run that died while parked, or one older than `parkedRunTimeoutMs` falls back to a new Run that replays the in-flight turn with its results and sends a fixed continuation notice as the user message a Run requires; a `resumeAction` is not used because the server restarts the turn from its user message instead of continuing it. A Cursor-native or CLI Pi workspace exec (`read`, `shell`, `piRead`, and kin) is answered with its typed rejection naming the harness tool to call through `CallDynamicTool`, so the Run continues and the model reads the refusal as a tool outcome; text after a refused exec starts a new text block. A CLI hook is answered with an empty matching response. An MCP-state exec returns the advertised `dsh` tools. Any other exec this build cannot type is answered with ExecClientThrow so the Run continues. An exec with no payload still fails the step.
70
72
 
71
73
  Attribution headers required by `LlmAdapter` go on every HTTP/2 request, with Cursor client headers `x-ghost-mode`, `x-cursor-client-version`, and `x-cursor-client-type`.
72
74
 
@@ -76,6 +78,7 @@ Attribution headers required by `LlmAdapter` go on every HTTP/2 request, with Cu
76
78
  - [Configure models](../../../docs/user/guide/providers.md) — Web and TUI sign-in, including Cursor beside Codex.
77
79
  - [LLM streaming subsystem](../../../docs/subsystems/llm-streaming.md) — `StreamChunk` and the adapter contract.
78
80
  - [Cursor subscription sign-in and native adapter](../../../.agents/notes/implemented/feature/2026-09-18-cursor-subscription-signin-and-adapter.md) — why this is a third adapter family rather than a pi-ai catalog entry.
81
+ - [Park Cursor Runs across tool calls and route harness tools through CallDynamicTool](../../../.agents/notes/implemented/architecture/2026-09-23-cursor-parked-runs-and-dynamic-tools.md) — why a turn stays on one Run and how the model reaches harness tools.
79
82
 
80
83
  <a id="model-experience"></a>
81
84
  ## Model Experience
@@ -84,21 +87,21 @@ Attribution headers required by `LlmAdapter` go on every HTTP/2 request, with Cu
84
87
 
85
88
  #### What the model sees
86
89
 
87
- One rebuilt Cursor `AgentRunRequest` whose `root_prompt_messages_json` carries the model-visible history: the system prompt as a `<rules>` user message, then each prior human turn as a `<user_query>` user message, harness-injected catalogs, snapshots, and notices as separate user messages that are not wrapped in `<user_query>`, assistant messages holding text and `tool-call` parts named `mcp_dsh_<tool>`, and `tool` messages holding the results; thinking is not replayed. The current user action is the human prompt only — a Run has one `userMessageAction`, so skill catalogs and runtime snapshots ride the root prompt instead of joining that action. After locally executed tool calls, the in-flight turn is replayed with its results and the user action is the fixed notice `The results of your tool calls are in the tool messages above. Continue the task.`. The request context carries one global rule stating that Cursor's built-in tools return a rejection and naming the `mcp_dsh_` tools as the ones to call. Images reach the model as the harness's text-only placeholder because the route declares text-only input; no image bytes are sent. Cursor still offers its own built-in tools beside the harness MCP tools.
90
+ A new Cursor `AgentRunRequest` whose `root_prompt_messages_json` carries the model-visible history: the system prompt as a `<rules>` user message, then each prior human turn as a `<user_query>` user message, harness-injected catalogs, snapshots, and notices as separate user messages that are not wrapped in `<user_query>`, assistant messages holding text and `tool-call` parts written as `CallDynamicTool` calls in namespace `dsh`, and `tool` messages holding the results; thinking is not replayed. The current user action is the human prompt only — a Run has one `userMessageAction`, so skill catalogs and runtime snapshots ride the root prompt instead of joining that action. A resumed Run sends no new request: the model reads each tool result as the outcome of its own pending call, with harness context that followed the results appended to the last one. When the Run cannot resume after locally executed tool calls, the in-flight turn is replayed with its results and the user action is the fixed notice `The results of your tool calls are in the tool messages above. This is not a new request: continue the current task from the last tool result. The user has already seen your earlier messages, so do not repeat or rephrase them or restate your plan; write only new information.`. The request context carries one global rule stating that Cursor's built-in tools return a rejection and that harness tools are called with `CallDynamicTool` in namespace `dsh`, followed by the harness tool names. Images reach the model as the harness's text-only placeholder because the route declares text-only input; no image bytes are sent. Cursor still offers its own built-in tools beside the harness MCP tools.
88
91
 
89
92
  #### Token effect
90
93
 
91
- Provider tokenization governs exact input. History is fully rebuilt on every DSH step, so the wire request is the current assembled messages rather than a resumed Cursor conversation. Replayed history travels twice on the wire, as prompt messages and as turn structures, but only the prompt messages reach the model. Cursor reports no prompt usage, so `inputTokens` is an estimate of one token per four characters of rules, replayed prompt messages, action text, and MCP tool definitions; `outputTokens` comes from Cursor's `tokenDelta` events.
94
+ Provider tokenization governs exact input. A new Run carries the current assembled messages; a resumed Run adds only the tool results to the conversation Cursor already holds. Replayed history travels twice on the wire, as prompt messages and as turn structures, but only the prompt messages reach the model. Cursor reports no prompt usage, so `inputTokens` is an estimate of one token per four characters of rules, replayed prompt messages, action text, and MCP tool definitions for the request as a new Run would carry it; `outputTokens` comes from Cursor's `tokenDelta` events.
92
95
 
93
96
  #### KV Cache effect
94
97
 
95
- Each step is an independent Run. A changed system prompt, history, tool schema, or model id produces a new request and does not reuse a Cursor-side conversation prefix.
98
+ The steps of a turn share one Cursor conversation while the Run resumes. A new Run, opened after a changed system prompt, history, tool schema, or model id, or after any fallback, does not reuse a Cursor-side conversation prefix.
96
99
 
97
100
  ### Cursor Run response
98
101
 
99
102
  #### What the model sees
100
103
 
101
- Text deltas, thinking deltas, token usage, and MCP tool calls become harness chunks. An MCP tool call finishes the stream with `tool-calls`. A native or CLI Pi workspace exec is answered with a rejection and the stream continues. A CLI hook or MCP-state exec is answered so the Run stays open. Any other exec this build cannot type is answered with ExecClientThrow and the stream continues. An exec with no payload fails the turn.
104
+ Text deltas, thinking deltas, token usage, and MCP tool calls become harness chunks. MCP tool calls finish the step with `tool-calls` after the model's parallel calls arrive. A native or CLI Pi workspace exec is answered with a rejection and the stream continues. A CLI hook or MCP-state exec is answered so the Run stays open. Any other exec this build cannot type is answered with ExecClientThrow and the stream continues. An exec with no payload fails the turn.
102
105
 
103
106
  #### Token effect
104
107
 
@@ -106,7 +109,7 @@ Generated content affects later inputs only after the loop records it. Output to
106
109
 
107
110
  #### KV Cache effect
108
111
 
109
- Loop-retained response blocks append to the next rebuilt Run. Unrecorded transport frames do not affect later cache identity.
112
+ A resumed Run already holds the model's own output. Loop-retained response blocks append to the next new Run. Unrecorded transport frames do not affect later cache identity.
110
113
 
111
114
  ## Known Limitations and Deferred Work
112
115
 
@@ -115,14 +118,14 @@ Loop-retained response blocks append to the next rebuilt Run. Unrecorded transpo
115
118
  These limits define where the adapter stops. They are current package constraints, not a Cursor product comparison.
116
119
 
117
120
  - **The integration is unofficial** — auth URLs, headers, client version, and `agent.v1` can change without notice and break this adapter.
118
- - **Native Cursor workspace execs are not executed** — `read`, `shell`, CLI Pi tools (`piRead`, `piBash`, and kin), and the same family receive a typed rejection naming the harness tool, so a model that picks one spends a round trip on the refusal before calling the `mcp_dsh_` tool.
121
+ - **Native Cursor workspace execs are not executed** — `read`, `shell`, CLI Pi tools (`piRead`, `piBash`, and kin), and the same family receive a typed rejection naming the harness tool, so a model that picks one spends a round trip on the refusal before calling `CallDynamicTool`.
119
122
  - **CLI control execs do not run Cursor hooks** — hook frames get an empty matching response, MCP-state frames list the advertised `dsh` tools, and any other unnamed exec is answered with ExecClientThrow so the Run continues; none of them execute workspace work.
120
- - **There is no parked HTTP/2 conversation** — each DSH step is a new Run; mid-tool resume on the same Cursor stream is out of scope.
121
- - **Tool results reach the model as replayed prompt messages plus a fixed continuation notice** — Cursor delivers results in-stream natively; the notice is adapter-owned text the human never typed.
123
+ - **A parked Run lives in one process** — it is not journaled, so a restarted process, a human message after the tool results, or any changed history falls back to a new Run rebuilt from history.
124
+ - **A fallback Run delivers tool results as replayed prompt messages plus a fixed continuation notice** — the notice is adapter-owned text the human never typed; a resumed Run delivers injected context inside the last tool result instead of as its own message.
122
125
  - **`GenerateOptions.stop` is unsupported** — the unofficial Run does not map stop sequences.
123
126
  - **Image bytes are not sent** — the route declares text-only input, so every image reaches the model as the harness's text-only placeholder rather than as a Cursor selected image.
124
127
  - **`maxTokens`, `temperature`, and `reasoningEffort` are not mapped** — the Run has no fields for them; effort is chosen through the Cursor model id suffix such as `-high`.
125
- - **Reasoning is not replayed** — Cursor renders no `reasoning` prompt part, so a thinking model re-derives its plan after each locally executed tool call.
128
+ - **Reasoning is not replayed** — Cursor renders no `reasoning` prompt part, so after a fallback a thinking model re-derives its plan; a resumed Run keeps its reasoning.
126
129
  - **Prompt token usage is an estimate** — Cursor reports none, so the TUI context meter shows the adapter's character-based estimate.
127
130
  - **Sign-out does not revoke at Cursor** — it only deletes the local grant; harvest can still satisfy the next request until `reuseInstalledCursorLogin` is false.
128
131
  - **Harvest can bill a different Cursor account** — a stored DSH grant wins; turn harvest off when this machine's IDE login is not the account to use.
@@ -9,7 +9,7 @@ kind: "package-reference"
9
9
 
10
10
  ## 概述
11
11
 
12
- `@deepseek-ai/dsh-llm-cursor` 注册始终在线的 `cursor` 路由,通过 PKCE 用 Cursor 订阅登录,并把 harness 的每一步流式调用做成一次非官方 Connect/protobuf HTTP/2 `AgentService/Run`。设置 → 模型显示带「登录」的 Cursor 卡片;TUI `/login llm-cursor/cursor` 列出同一条 flow。本包可与 [DeepSeek](../llm-deepseek/README.zh.md) 和 [pi-ai](../llm-pi-ai/README.zh.md) 适配器一起挂载。
12
+ `@deepseek-ai/dsh-llm-cursor` 注册始终在线的 `cursor` 路由,通过 PKCE 用 Cursor 订阅登录,并在非官方 Connect/protobuf HTTP/2 `AgentService/Run` 流上流式执行 harness 的各步;在适配器能够恢复时,一个轮次的各步共享一个 Run。设置 → 模型显示带「登录」的 Cursor 卡片;TUI `/login llm-cursor/cursor` 列出同一条 flow。本包可与 [DeepSeek](../llm-deepseek/README.zh.md) 和 [pi-ai](../llm-pi-ai/README.zh.md) 适配器一起挂载。
13
13
 
14
14
  ## 目录
15
15
 
@@ -47,6 +47,8 @@ kind: "package-reference"
47
47
  | `apiKeyEnv` | `CURSOR_ACCESS_TOKEN` | 每次请求先解析的凭据引用,然后才是已存授权或采集 |
48
48
  | `reuseInstalledCursorLogin` | `true` | 请求是否可以复用本机已有的 Cursor IDE 或 CLI 登录 |
49
49
  | `streamIdleTimeoutMs` | `300,000` | 单次未完成的流式读取允许的最长提供方空闲时间 |
50
+ | `parkedRunTimeoutMs` | `1,800,000` | 因工具调用而挂起的 Run 等待其结果的时长,超时即取消 |
51
+ | `toolCallSettleMs` | `1,000` | Cursor 尚未发送结束模型消息的检查点时,等待更多并行工具调用的时长 |
50
52
  | `retryPolicy` | 普通模式,5 次重试 | 由 `dsh-llm-retry` 执行的提供方自有重试策略 |
51
53
 
52
54
  生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-llm-cursor)是每个已接受字段及其 JSDoc 的完整来源。
@@ -64,9 +66,9 @@ TUI:`/login llm-cursor/cursor`。无头不会打开浏览器;导出 `CURSOR_
64
66
 
65
67
  请求时令牌顺序为:启动环境中的 `CURSOR_ACCESS_TOKEN`,然后是已存储的 OAuth 授权(临近过期时在 `modifyRecord` 内刷新),然后在 `reuseInstalledCursorLogin` 为 true 时可选读取钥匙串 / `state.vscdb`。已存储的 DSH 登录优先于采集。
66
68
 
67
- DSH 的每一步模型调用是一次新的 HTTP/2 Connect `Run`,由 harness 历史、系统提示和 MCP 工具定义重建(`providerIdentifier: dsh`,`clientName: dsh`)。Cursor 服务端只从 `root_prompt_messages_json` 构建模型提示,从不把 `conversation_state.turns` 渲染进去,并且会丢弃其中的 `{"role":"system"}` 条目而使用自己的提示。因此适配器把系统提示作为 `<rules>` user 提示消息发布,并把每个先前轮次重放为 `user`、`assistant` 和 `tool` 提示消息,历史 MCP 调用按 Cursor 的命名写成 `mcp_dsh_<tool>`;轮次结构一同发送,供服务端记账。请求上下文的应答额外带一条全局 Cursor 规则,告知模型 Cursor 内建工具在这里会返回拒绝,应调用 `mcp_dsh_` 工具。
69
+ 新的 Run 由 harness 历史、系统提示和 MCP 工具定义重建(`providerIdentifier: dsh`,`clientName: dsh`)。Cursor 服务端只从 `root_prompt_messages_json` 构建模型提示,从不把 `conversation_state.turns` 渲染进去,并且会丢弃其中的 `{"role":"system"}` 条目而使用自己的提示。因此适配器把系统提示作为 `<rules>` user 提示消息发布,并把每个先前轮次重放为 `user`、`assistant` 和 `tool` 提示消息,把每个历史 harness 工具调用写成 Cursor 为 MCP 工具记录的 `CallDynamicTool` 调用;轮次结构一同发送,供服务端记账。Cursor CLI 的 Run 只通过 `GetDynamicTools` 和 `CallDynamicTool` 向模型暴露 MCP 工具,因此请求上下文的应答额外带一条全局 Cursor 规则,告知模型 Cursor 内建工具在这里会返回拒绝、harness 工具以命名空间 `dsh` 中的 `CallDynamicTool` 调用,以及有哪些工具名。
68
70
 
69
- 文本、thinking、用量与 MCP 工具调用变成 `StreamChunk`。一次 MCP 工具调用结束该流,以便 agent loop 在本地跑工具。下一次 Run 重放该进行中的轮次及其结果,并把一条固定的继续提示作为 Run 必需的用户消息发送;不使用 `resumeAction`,因为服务端会从该轮的用户消息重新开始而不是继续。Cursor 原生或 CLI Pi 工作区 exec(`read`、`shell`、`piRead` 及同类)以其类型化的拒绝应答,并指出应改用的 harness 工具,因此 Run 继续进行,模型把该拒绝当作工具结果读取。CLI 钩子以空的匹配响应应答。MCP-state exec 返回已通告的 `mcp_dsh_` 工具。本构建无法类型化的其他 exec 以 ExecClientThrow 应答,以便 Run 继续。没有 payload 的 exec 仍使该步失败。
71
+ 文本、thinking、用量与 MCP 工具调用变成 `StreamChunk`。当 Cursor 发出模型最后一个并行调用之后的检查点,或 `toolCallSettleMs` 内没有新帧时,MCP 工具调用结束该步。若请求带有 Session 且不是压缩或标题请求,该 Run 随后挂起:适配器每五秒发送一次 `clientHeartbeat` 保持流开启。该 Session 的下一次请求在以下条件成立时恢复它:最后一条 assistant 消息之前的历史不变,且该消息之后只有待处理调用的结果以及 harness 注入的 user 角色上下文;适配器在同一条流上以 `mcpResult` 应答每个调用,把这类上下文追加到最后一个结果之后,并继续读取。任何其他请求、挂起期间死亡的 Run,或超过 `parkedRunTimeoutMs` 的 Run,都回退为新的 Run:它重放该进行中的轮次及其结果,并把一条固定的继续提示作为 Run 必需的用户消息发送;不使用 `resumeAction`,因为服务端会从该轮的用户消息重新开始而不是继续。Cursor 原生或 CLI Pi 工作区 exec(`read`、`shell`、`piRead` 及同类)以其类型化的拒绝应答,并指出应通过 `CallDynamicTool` 调用的 harness 工具,因此 Run 继续进行,模型把该拒绝当作工具结果读取;被拒绝的 exec 之后的文本开启新的文本块。CLI 钩子以空的匹配响应应答。MCP-state exec 返回已通告的 `dsh` 工具。本构建无法类型化的其他 exec 以 ExecClientThrow 应答,以便 Run 继续。没有 payload 的 exec 仍使该步失败。
70
72
 
71
73
  `LlmAdapter` 要求的归属头出现在每一次 HTTP/2 请求上,并带有 Cursor 客户端头 `x-ghost-mode`、`x-cursor-client-version` 和 `x-cursor-client-type`。
72
74
 
@@ -76,6 +78,7 @@ DSH 的每一步模型调用是一次新的 HTTP/2 Connect `Run`,由 harness
76
78
  - [配置模型](../../../docs/user/guide/providers.zh.md) — Web 与 TUI 登录,包括与 Codex 并列的 Cursor。
77
79
  - [LLM 流式子系统](../../../docs/subsystems/llm-streaming.zh.md) — `StreamChunk` 与适配器约定。
78
80
  - [Cursor 订阅登录与原生适配器](../../../.agents/notes/implemented/feature/2026-09-18-cursor-subscription-signin-and-adapter.zh.md) — 为何这是第三套适配器族,而不是 pi-ai 目录项。
81
+ - [跨工具调用挂起 Cursor Run,并通过 CallDynamicTool 路由 harness 工具](../../../.agents/notes/implemented/architecture/2026-09-23-cursor-parked-runs-and-dynamic-tools.zh.md) — 为何一个轮次停留在一个 Run 上,以及模型如何到达 harness 工具。
79
82
 
80
83
  <a id="model-experience"></a>
81
84
  ## 模型体验
@@ -84,21 +87,21 @@ DSH 的每一步模型调用是一次新的 HTTP/2 Connect `Run`,由 harness
84
87
 
85
88
  #### 模型看见什么
86
89
 
87
- 一次重建的 Cursor `AgentRunRequest`,其 `root_prompt_messages_json` 承载模型可见的历史:系统提示作为 `<rules>` user 消息,然后每个先前人类轮次作为 `<user_query>` user 消息,harness 注入的目录、快照和通知作为不被 `<user_query>` 包裹的独立 user 消息,assistant 消息承载文本和名为 `mcp_dsh_<tool>` 的 `tool-call` 部分,以及承载结果的 `tool` 消息;thinking 不重放。当前用户动作只有人类提示——一次 Run 只有一个 `userMessageAction`,因此 skill 目录和运行时快照走根提示,而不并入该动作。本地执行工具调用之后,进行中的轮次连同其结果被重放,用户动作是固定提示 `The results of your tool calls are in the tool messages above. Continue the task.`。请求上下文带一条全局规则,声明 Cursor 内建工具会返回拒绝,并指出应调用 `mcp_dsh_` 工具。由于该路由声明只接受文本输入,图片以 harness 的纯文本占位符到达模型;不发送图片字节。Cursor 仍在 harness MCP 工具之外提供自己的内建工具。
90
+ 一次新的 Cursor `AgentRunRequest`,其 `root_prompt_messages_json` 承载模型可见的历史:系统提示作为 `<rules>` user 消息,然后每个先前人类轮次作为 `<user_query>` user 消息,harness 注入的目录、快照和通知作为不被 `<user_query>` 包裹的独立 user 消息,assistant 消息承载文本和写成命名空间 `dsh` 中 `CallDynamicTool` 调用的 `tool-call` 部分,以及承载结果的 `tool` 消息;thinking 不重放。当前用户动作只有人类提示——一次 Run 只有一个 `userMessageAction`,因此 skill 目录和运行时快照走根提示,而不并入该动作。恢复的 Run 不发送新请求:模型把每个工具结果当作自己待处理调用的结果读取,结果之后的 harness 上下文追加到最后一个结果之后。本地执行工具调用之后若 Run 无法恢复,进行中的轮次连同其结果被重放,用户动作是固定提示 `The results of your tool calls are in the tool messages above. This is not a new request: continue the current task from the last tool result. The user has already seen your earlier messages, so do not repeat or rephrase them or restate your plan; write only new information.`。请求上下文带一条全局规则,声明 Cursor 内建工具会返回拒绝、harness 工具以命名空间 `dsh` 中的 `CallDynamicTool` 调用,随后列出 harness 工具名。由于该路由声明只接受文本输入,图片以 harness 的纯文本占位符到达模型;不发送图片字节。Cursor 仍在 harness MCP 工具之外提供自己的内建工具。
88
91
 
89
92
  #### Token 影响
90
93
 
91
- 精确输入由提供方分词决定。历史在 DSH 的每一步完整重建,因此线路上的请求是当前组装好的消息,而不是恢复中的 Cursor 会话。重放的历史在线路上传输两次——作为提示消息和作为轮次结构——但只有提示消息到达模型。Cursor 不报告提示用量,因此 `inputTokens` 是按规则、重放的提示消息、动作文本与 MCP 工具定义每四个字符一个 token 的估算;`outputTokens` 来自 Cursor 的 `tokenDelta` 事件。
94
+ 精确输入由提供方分词决定。新的 Run 承载当前组装好的消息;恢复的 Run 只把工具结果加入 Cursor 已持有的会话。重放的历史在线路上传输两次——作为提示消息和作为轮次结构——但只有提示消息到达模型。Cursor 不报告提示用量,因此 `inputTokens` 是按新 Run 会承载的规则、重放的提示消息、动作文本与 MCP 工具定义每四个字符一个 token 的估算;`outputTokens` 来自 Cursor 的 `tokenDelta` 事件。
92
95
 
93
96
  #### KV Cache 影响
94
97
 
95
- 每一步都是独立的 Run。系统提示、历史、工具 schema 或模型 id 的变化会产生新请求,不会复用 Cursor 一侧的会话前缀。
98
+ 在 Run 恢复期间,一个轮次的各步共享同一个 Cursor 会话。在系统提示、历史、工具 schema 或模型 id 变化之后,或任何回退之后打开的新 Run,不会复用 Cursor 一侧的会话前缀。
96
99
 
97
100
  ### Cursor Run 响应
98
101
 
99
102
  #### 模型看见什么
100
103
 
101
- 文本增量、thinking 增量、token 用量和 MCP 工具调用变成 harness 分片。一次 MCP 工具调用以 `tool-calls` 结束该流。原生或 CLI Pi 工作区 exec 以拒绝应答且流继续。CLI 钩子或 MCP-state exec 被应答以保持 Run 开启。本构建无法类型化的其他 exec 以 ExecClientThrow 应答且流继续。没有 payload 的 exec 使该轮失败。
104
+ 文本增量、thinking 增量、token 用量和 MCP 工具调用变成 harness 分片。模型的并行调用到齐之后,MCP 工具调用以 `tool-calls` 结束该步。原生或 CLI Pi 工作区 exec 以拒绝应答且流继续。CLI 钩子或 MCP-state exec 被应答以保持 Run 开启。本构建无法类型化的其他 exec 以 ExecClientThrow 应答且流继续。没有 payload 的 exec 使该轮失败。
102
105
 
103
106
  #### Token 影响
104
107
 
@@ -106,7 +109,7 @@ DSH 的每一步模型调用是一次新的 HTTP/2 Connect `Run`,由 harness
106
109
 
107
110
  #### KV Cache 影响
108
111
 
109
- loop 保留的响应块追加到下一次重建的 Run。未记录的传输帧不影响之后的缓存身份。
112
+ 恢复的 Run 已持有模型自己的输出。loop 保留的响应块追加到下一次新的 Run。未记录的传输帧不影响之后的缓存身份。
110
113
 
111
114
  ## 已知限制与延后工作
112
115
 
@@ -115,14 +118,14 @@ loop 保留的响应块追加到下一次重建的 Run。未记录的传输帧
115
118
  这些限制划定适配器的停止点。它们是当前的包约束,不是与 Cursor 产品的对比。
116
119
 
117
120
  - **该集成是非官方的** — 认证 URL、头、客户端版本和 `agent.v1` 可能不预先通知就变更并弄坏本适配器。
118
- - **不执行原生 Cursor 工作区 exec** — `read`、`shell`、CLI Pi 工具(`piRead`、`piBash` 及同类)以及同一家族收到指出 harness 工具的类型化拒绝,因此选中它们的模型会在调用 `mcp_dsh_` 工具之前多花一个往返。
121
+ - **不执行原生 Cursor 工作区 exec** — `read`、`shell`、CLI Pi 工具(`piRead`、`piBash` 及同类)以及同一家族收到指出 harness 工具的类型化拒绝,因此选中它们的模型会在调用 `CallDynamicTool` 之前多花一个往返。
119
122
  - **CLI 控制 exec 不运行 Cursor 钩子** — 钩子帧得到空的匹配响应,MCP-state 帧列出已通告的 `dsh` 工具,其他未命名 exec 以 ExecClientThrow 应答以使 Run 继续;它们都不执行工作区工作。
120
- - **没有挂起的 HTTP/2 会话** — DSH 的每一步都是新的 Run;在同一次 Cursor 流上中途恢复工具不在范围内。
121
- - **工具结果以重放的提示消息加一条固定继续提示到达模型** — Cursor 原生是在流内交付结果;该提示是适配器自有的文本,人类从未输入过。
123
+ - **挂起的 Run 只存在于一个进程中** — 它没有 journal,因此进程重启、工具结果之后的人类消息或任何历史变化都会回退为由历史重建的新 Run。
124
+ - **回退的 Run 以重放的提示消息加一条固定继续提示交付工具结果** — 该提示是适配器自有的文本,人类从未输入过;恢复的 Run 把注入上下文放在最后一个工具结果内部交付,而不是作为独立消息。
122
125
  - **不支持 `GenerateOptions.stop`** — 非官方 Run 不映射停止序列。
123
126
  - **不发送图片字节** — 该路由声明只接受文本输入,因此每张图片以 harness 的纯文本占位符到达模型,而不是作为 Cursor 选中图片。
124
127
  - **不映射 `maxTokens`、`temperature` 和 `reasoningEffort`** — Run 没有对应字段;努力程度通过 Cursor 模型 id 后缀(如 `-high`)选择。
125
- - **不重放 reasoning** — Cursor 不渲染 `reasoning` 提示部分,因此 thinking 模型在每次本地执行工具调用之后重新推导计划。
128
+ - **不重放 reasoning** — Cursor 不渲染 `reasoning` 提示部分,因此回退之后 thinking 模型会重新推导计划;恢复的 Run 保留其 reasoning。
126
129
  - **提示 token 用量是估算值** — Cursor 不报告,因此 TUI 上下文计量显示适配器基于字符数的估算。
127
130
  - **退出登录不会在 Cursor 一侧撤销** — 它只删除本地授权;在 `reuseInstalledCursorLogin` 为 false 之前,采集仍可能满足下一次请求。
128
131
  - **采集可能把账记到另一个 Cursor 账户** — 已存储的 DSH 授权优先;当本机 IDE 登录不是要用的账户时请关掉采集。