dsh-plugin-dev-kb 1.1.0 → 1.3.0

package/kb/meta/site-pages.txt

@@ -1,184 +1,188 @@
-develop\basic\config.md
-develop\basic\index.md
-develop\basic\publish.md
-develop\basic\tool.md
-develop\cordis-tutorial\01-first-plugin.md
-develop\cordis-tutorial\02-lifecycle-and-effects.md
-develop\cordis-tutorial\03-services.md
-develop\cordis-tutorial\04-events.md
-develop\cordis-tutorial\05-config.md
-develop\cordis-tutorial\06-composition-and-hmr.md
-develop\cordis-tutorial\07-into-the-harness.md
-develop\cordis-tutorial\index.md
-develop\framework\events.md
-develop\framework\index.md
-develop\framework\service.md
-develop\practice\dynamic-cordis.md
-develop\practice\index.md
-develop\practice\llm-adapter.md
-en\develop\basic\config.md
-en\develop\basic\index.md
-en\develop\basic\publish.md
-en\develop\basic\tool.md
-en\develop\cordis-tutorial\01-first-plugin.md
-en\develop\cordis-tutorial\02-lifecycle-and-effects.md
-en\develop\cordis-tutorial\03-services.md
-en\develop\cordis-tutorial\04-events.md
-en\develop\cordis-tutorial\05-config.md
-en\develop\cordis-tutorial\06-composition-and-hmr.md
-en\develop\cordis-tutorial\07-into-the-harness.md
-en\develop\cordis-tutorial\index.md
-en\develop\framework\events.md
-en\develop\framework\index.md
-en\develop\framework\service.md
-en\develop\practice\dynamic-cordis.md
-en\develop\practice\index.md
-en\develop\practice\llm-adapter.md
-en\guide\github-review.md
-en\guide\mcp-memory.md
-en\guide\network-proxy.md
-en\guide\providers.md
-en\guide\python-sdk.md
-en\guide\quickstart.md
-en\guide\schedule.md
-en\index.md
-en\reference\agent-lifecycle.md
-en\reference\api-gateway.md
-en\reference\capability-seams.md
-en\reference\config-catalog.md
-en\reference\cookbook\adding-an-llm-adapter.md
-en\reference\cookbook\adding-a-package.md
-en\reference\cookbook\adding-a-settings-card.md
-en\reference\cookbook\adding-a-tool.md
-en\reference\cookbook\extension-cookbook.md
-en\reference\cordis-api\context.md
-en\reference\cordis-api\events.md
-en\reference\cordis-api\fiber.md
-en\reference\cordis-api\inherited.md
-en\reference\cordis-api\registry.md
-en\reference\cordis-api\service.md
-en\reference\cordis-primer.md
-en\reference\index.md
-en\reference\persistence-catalog.md
-en\reference\subsystems\approval.md
-en\reference\subsystems\client-modules.md
-en\reference\subsystems\code-runtime.md
-en\reference\subsystems\commands.md
-en\reference\subsystems\compaction.md
-en\reference\subsystems\conversation.md
-en\reference\subsystems\core.md
-en\reference\subsystems\credentials.md
-en\reference\subsystems\filesystem.md
-en\reference\subsystems\goal.md
-en\reference\subsystems\index.md
-en\reference\subsystems\invariants.md
-en\reference\subsystems\jobs.md
-en\reference\subsystems\llm-streaming.md
-en\reference\subsystems\lsp.md
-en\reference\subsystems\permission-presets.md
-en\reference\subsystems\persistence.md
-en\reference\subsystems\plan.md
-en\reference\subsystems\sandbox.md
-en\reference\subsystems\schedule.md
-en\reference\subsystems\scope.md
-en\reference\subsystems\session.md
-en\reference\subsystems\session-projection.md
-en\reference\subsystems\session-query.md
-en\reference\subsystems\session-reference.md
-en\reference\subsystems\session-telemetry.md
-en\reference\subsystems\session-title.md
-en\reference\subsystems\settings.md
-en\reference\subsystems\shell.md
-en\reference\subsystems\skills.md
-en\reference\subsystems\slots.md
-en\reference\subsystems\spill.md
-en\reference\subsystems\storage.md
-en\reference\subsystems\subagent.md
-en\reference\subsystems\subprocess.md
-en\reference\subsystems\system-prompt.md
-en\reference\subsystems\terminal.md
-en\reference\subsystems\token-meter.md
-en\reference\subsystems\tools.md
-en\reference\subsystems\typert.md
-en\reference\subsystems\user-questions.md
-en\reference\subsystems\web.md
-en\reference\subsystems\web-client.md
-en\reference\subsystems\web-server.md
-en\reference\subsystems\workflow.md
-en\reference\subsystems\workspace.md
-en\reference\tool-catalog.md
-en\reference\tool-execution-pipeline.md
-guide\github-review.md
-guide\mcp-memory.md
-guide\network-proxy.md
-guide\providers.md
-guide\python-sdk.md
-guide\quickstart.md
-guide\schedule.md
-index.md
-reference\agent-lifecycle.md
-reference\api-gateway.md
-reference\capability-seams.md
-reference\config-catalog.md
-reference\cookbook\adding-an-llm-adapter.md
-reference\cookbook\adding-a-package.md
-reference\cookbook\adding-a-settings-card.md
-reference\cookbook\adding-a-tool.md
-reference\cookbook\extension-cookbook.md
-reference\cordis-api\context.md
-reference\cordis-api\events.md
-reference\cordis-api\fiber.md
-reference\cordis-api\inherited.md
-reference\cordis-api\registry.md
-reference\cordis-api\service.md
-reference\cordis-primer.md
-reference\index.md
-reference\persistence-catalog.md
-reference\subsystems\approval.md
-reference\subsystems\client-modules.md
-reference\subsystems\code-runtime.md
-reference\subsystems\commands.md
-reference\subsystems\compaction.md
-reference\subsystems\conversation.md
-reference\subsystems\core.md
-reference\subsystems\credentials.md
-reference\subsystems\filesystem.md
-reference\subsystems\goal.md
-reference\subsystems\index.md
-reference\subsystems\invariants.md
-reference\subsystems\jobs.md
-reference\subsystems\llm-streaming.md
-reference\subsystems\lsp.md
-reference\subsystems\permission-presets.md
-reference\subsystems\persistence.md
-reference\subsystems\plan.md
-reference\subsystems\sandbox.md
-reference\subsystems\schedule.md
-reference\subsystems\scope.md
-reference\subsystems\session.md
-reference\subsystems\session-projection.md
-reference\subsystems\session-query.md
-reference\subsystems\session-reference.md
-reference\subsystems\session-telemetry.md
-reference\subsystems\session-title.md
-reference\subsystems\settings.md
-reference\subsystems\shell.md
-reference\subsystems\skills.md
-reference\subsystems\slots.md
-reference\subsystems\spill.md
-reference\subsystems\storage.md
-reference\subsystems\subagent.md
-reference\subsystems\subprocess.md
-reference\subsystems\system-prompt.md
-reference\subsystems\terminal.md
-reference\subsystems\token-meter.md
-reference\subsystems\tools.md
-reference\subsystems\typert.md
-reference\subsystems\user-questions.md
-reference\subsystems\web.md
-reference\subsystems\web-client.md
-reference\subsystems\web-server.md
-reference\subsystems\workflow.md
-reference\subsystems\workspace.md
-reference\tool-catalog.md
-reference\tool-execution-pipeline.md
+develop\\basic\\config.md
+develop\\basic\\index.md
+develop\\basic\\publish.md
+develop\\basic\\tool.md
+develop\\cordis-tutorial\\01-first-plugin.md
+develop\\cordis-tutorial\\02-lifecycle-and-effects.md
+develop\\cordis-tutorial\\03-services.md
+develop\\cordis-tutorial\\04-events.md
+develop\\cordis-tutorial\\05-config.md
+develop\\cordis-tutorial\\06-composition-and-hmr.md
+develop\\cordis-tutorial\\07-into-the-harness.md
+develop\\cordis-tutorial\\index.md
+develop\\framework\\events.md
+develop\\framework\\index.md
+develop\\framework\\service.md
+develop\\practice\\dynamic-cordis.md
+develop\\practice\\index.md
+develop\\practice\\llm-adapter.md
+en\\develop\\basic\\config.md
+en\\develop\\basic\\index.md
+en\\develop\\basic\\publish.md
+en\\develop\\basic\\tool.md
+en\\develop\\cordis-tutorial\\01-first-plugin.md
+en\\develop\\cordis-tutorial\\02-lifecycle-and-effects.md
+en\\develop\\cordis-tutorial\\03-services.md
+en\\develop\\cordis-tutorial\\04-events.md
+en\\develop\\cordis-tutorial\\05-config.md
+en\\develop\\cordis-tutorial\\06-composition-and-hmr.md
+en\\develop\\cordis-tutorial\\07-into-the-harness.md
+en\\develop\\cordis-tutorial\\index.md
+en\\develop\\framework\\events.md
+en\\develop\\framework\\index.md
+en\\develop\\framework\\service.md
+en\\develop\\practice\\dynamic-cordis.md
+en\\develop\\practice\\index.md
+en\\develop\\practice\\llm-adapter.md
+en\\guide\\github-review.md
+en\\guide\\mcp-memory.md
+en\\guide\\network-proxy.md
+en\\guide\\providers.md
+en\\guide\\python-sdk.md
+en\\guide\\quickstart.md
+en\\guide\\schedule.md
+en\\index.md
+en\\reference\\agent-lifecycle.md
+en\\reference\\api-gateway.md
+en\\reference\\capability-seams.md
+en\\reference\\config-catalog.md
+en\\reference\\cookbook\\adding-a-package.md
+en\\reference\\cookbook\\adding-a-settings-card.md
+en\\reference\\cookbook\\adding-a-tool.md
+en\\reference\\cookbook\\adding-an-llm-adapter.md
+en\\reference\\cookbook\\extension-cookbook.md
+en\\reference\\cordis-api\\context.md
+en\\reference\\cordis-api\\events.md
+en\\reference\\cordis-api\\fiber.md
+en\\reference\\cordis-api\\inherited.md
+en\\reference\\cordis-api\\registry.md
+en\\reference\\cordis-api\\service.md
+en\\reference\\cordis-primer.md
+en\\reference\\index.md
+en\\reference\\persistence-catalog.md
+en\\reference\\subsystems\\approval.md
+en\\reference\\subsystems\\client-modules.md
+en\\reference\\subsystems\\client-resources.md
+en\\reference\\subsystems\\code-runtime.md
+en\\reference\\subsystems\\commands.md
+en\\reference\\subsystems\\compaction.md
+en\\reference\\subsystems\\conversation.md
+en\\reference\\subsystems\\core.md
+en\\reference\\subsystems\\credentials.md
+en\\reference\\subsystems\\filesystem.md
+en\\reference\\subsystems\\goal.md
+en\\reference\\subsystems\\index.md
+en\\reference\\subsystems\\invariants.md
+en\\reference\\subsystems\\jobs.md
+en\\reference\\subsystems\\llm-streaming.md
+en\\reference\\subsystems\\lsp.md
+en\\reference\\subsystems\\permission-presets.md
+en\\reference\\subsystems\\persistence.md
+en\\reference\\subsystems\\plan.md
+en\\reference\\subsystems\\sandbox.md
+en\\reference\\subsystems\\schedule.md
+en\\reference\\subsystems\\scope.md
+en\\reference\\subsystems\\session-projection.md
+en\\reference\\subsystems\\session-query.md
+en\\reference\\subsystems\\session-reference.md
+en\\reference\\subsystems\\session-telemetry.md
+en\\reference\\subsystems\\session-title.md
+en\\reference\\subsystems\\session.md
+en\\reference\\subsystems\\settings.md
+en\\reference\\subsystems\\shell.md
+en\\reference\\subsystems\\sidebar-right.md
+en\\reference\\subsystems\\skills.md
+en\\reference\\subsystems\\slots.md
+en\\reference\\subsystems\\spill.md
+en\\reference\\subsystems\\storage.md
+en\\reference\\subsystems\\subagent.md
+en\\reference\\subsystems\\subprocess.md
+en\\reference\\subsystems\\system-prompt.md
+en\\reference\\subsystems\\terminal.md
+en\\reference\\subsystems\\token-meter.md
+en\\reference\\subsystems\\tools.md
+en\\reference\\subsystems\\typert.md
+en\\reference\\subsystems\\user-questions.md
+en\\reference\\subsystems\\web-client.md
+en\\reference\\subsystems\\web-server.md
+en\\reference\\subsystems\\web.md
+en\\reference\\subsystems\\workflow.md
+en\\reference\\subsystems\\workspace.md
+en\\reference\\tool-catalog.md
+en\\reference\\tool-execution-pipeline.md
+guide\\github-review.md
+guide\\mcp-memory.md
+guide\\network-proxy.md
+guide\\providers.md
+guide\\python-sdk.md
+guide\\quickstart.md
+guide\\schedule.md
+index.md
+reference\\agent-lifecycle.md
+reference\\api-gateway.md
+reference\\capability-seams.md
+reference\\config-catalog.md
+reference\\cookbook\\adding-a-package.md
+reference\\cookbook\\adding-a-settings-card.md
+reference\\cookbook\\adding-a-tool.md
+reference\\cookbook\\adding-an-llm-adapter.md
+reference\\cookbook\\extension-cookbook.md
+reference\\cordis-api\\context.md
+reference\\cordis-api\\events.md
+reference\\cordis-api\\fiber.md
+reference\\cordis-api\\inherited.md
+reference\\cordis-api\\registry.md
+reference\\cordis-api\\service.md
+reference\\cordis-primer.md
+reference\\index.md
+reference\\persistence-catalog.md
+reference\\subsystems\\approval.md
+reference\\subsystems\\client-modules.md
+reference\\subsystems\\client-resources.md
+reference\\subsystems\\code-runtime.md
+reference\\subsystems\\commands.md
+reference\\subsystems\\compaction.md
+reference\\subsystems\\conversation.md
+reference\\subsystems\\core.md
+reference\\subsystems\\credentials.md
+reference\\subsystems\\filesystem.md
+reference\\subsystems\\goal.md
+reference\\subsystems\\index.md
+reference\\subsystems\\invariants.md
+reference\\subsystems\\jobs.md
+reference\\subsystems\\llm-streaming.md
+reference\\subsystems\\lsp.md
+reference\\subsystems\\permission-presets.md
+reference\\subsystems\\persistence.md
+reference\\subsystems\\plan.md
+reference\\subsystems\\sandbox.md
+reference\\subsystems\\schedule.md
+reference\\subsystems\\scope.md
+reference\\subsystems\\session-projection.md
+reference\\subsystems\\session-query.md
+reference\\subsystems\\session-reference.md
+reference\\subsystems\\session-telemetry.md
+reference\\subsystems\\session-title.md
+reference\\subsystems\\session.md
+reference\\subsystems\\settings.md
+reference\\subsystems\\shell.md
+reference\\subsystems\\sidebar-right.md
+reference\\subsystems\\skills.md
+reference\\subsystems\\slots.md
+reference\\subsystems\\spill.md
+reference\\subsystems\\storage.md
+reference\\subsystems\\subagent.md
+reference\\subsystems\\subprocess.md
+reference\\subsystems\\system-prompt.md
+reference\\subsystems\\terminal.md
+reference\\subsystems\\token-meter.md
+reference\\subsystems\\tools.md
+reference\\subsystems\\typert.md
+reference\\subsystems\\user-questions.md
+reference\\subsystems\\web-client.md
+reference\\subsystems\\web-server.md
+reference\\subsystems\\web.md
+reference\\subsystems\\workflow.md
+reference\\subsystems\\workspace.md
+reference\\tool-catalog.md
+reference\\tool-execution-pipeline.md

package/kb/meta/source.json

@@ -3,11 +3,11 @@
   "source": "官方文档站点 https://deepseek-harness.github.io/deepseek-harness/ （VitePress）",
   "repository": "https://github.com/deepseek-ai/deepseek-harness",
   "branch": "master",
-  "commit": "d347e703908d0406b7a7ef80e3a0e594d86b2215",
-  "fetchedAt": "2026-09-05T10:10:32.663Z",
+  "commit": "aa8262ec091698bae9a6b04773a6b5b06ad4aef2",
+  "fetchedAt": "2026-09-10T06:41:07.124Z",
   "siteBase": "https://deepseek-harness.github.io/deepseek-harness",
-  "publishedMarkdownPages": 184,
-  "siteFiles": 188,
+  "publishedMarkdownPages": 188,
+  "siteFiles": 192,
   "images": 4,
-  "extraFiles": 58
+  "extraFiles": 62
 }

package/kb/meta/topics.md

@@ -30,7 +30,7 @@
 
 ## 7. 打包与发布插件
 - 核心：`site/develop/basic/publish.md`
-- 扩展：`extra/cookbook/adding-a-vendored-package.md`（vendored 包）
+- 扩展：`extra/cookbook/adding-a-vendored-package.md`（vendored 包）、`extra/cookbook/adding-a-session-format-version.md`（新增会话格式版本号）、`extra/session-format-status.md`（会话格式状态）
 
 ## 8. LLM 适配器
 - 核心：`site/develop/practice/llm-adapter.md`、`site/reference/cookbook/adding-an-llm-adapter.md`
@@ -78,6 +78,6 @@
 - 扩展：`site/reference/subsystems/schedule.md`、`extra/subsystems/todo.md`（仓库文档）
 
 ## 检索技巧
-- 全量索引：`meta/search-index.json`（245 个文件的 path/url/title/字符数）
+- 全量索引：`meta/search-index.json`（253 个文件的 path/url/title/字符数）
 - 大文件（config-catalog / tool-catalog / module-graph / subsystems/session 等 ≥100KB）先用 grep 定位关键行，再 read 局部，不要整读
 - 常用检索关键词：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`

package/kb/site/develop/basic/publish.md

@@ -72,7 +72,7 @@ profile 目录包含两个文件：
 - `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
 - `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
 
-profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。
+profile manifest 从不需要手写：`dsh --profile <name> --from-default-profile <template>` 可以从随附应用模板创建 profile，`dsh plugin` 则创建一个以 base 为基础的 profile，并维护其中已安装的 bundle 列表。创建规则以 [CLI（命令行界面）行为参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md#profile-boot)为准；下一节展示插件路径。
 
 ## 安装进 profile
 

package/kb/site/en/develop/basic/publish.md

@@ -72,7 +72,7 @@ A profile directory holds two files:
 - `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list.
 - `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer.
 
-You never write a profile manifest by hand: `dsh plugin` creates and maintains it. The next section shows the result.
+You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create one from a shipped application template, while `dsh plugin` creates a base-backed profile and maintains its installed bundle list. The [CLI behavior reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#profile-boot) owns the creation rules; the next section shows the plugin path.
 
 ## Install into a profile
 

package/kb/site/en/guide/providers.md

@@ -188,5 +188,5 @@ Every switch, its accepted values, and the protocols that take it are listed und
 - **The Effort menu does not appear for a model you entered by hand** — It declares no levels. Add `reasoningEfforts` to the model in `settings.yaml`.
 - **`off` does not stop a DeepSeek model from thinking** — An empty `off` sends no reasoning field at all, and an endpoint that thinks by default keeps thinking. Set `compat.thinkingFormat: deepseek` on the model or the route.
 - **A compat switch is refused as having no value** — A key written with nothing after the colon. Give it a value, or remove the key to keep the installed catalog's.
-- **An image is refused before sending** — The model declares no image modality. Give a custom provider's model `input: [text, image]`; on DeepSeek's own route, select `deepseek-v4-flash-vision-exp`, the model that declares images.
+- **An image is refused before sending** — The model declares no image modality. Give a custom provider's model `input: [text, image]`; on DeepSeek's own route, select an image-capable entry from the configured catalog (`deepseek-flash` by default) and confirm that your gateway serves that model with image input.
 - **The provider rejects a request carrying an image** — The model declares images its endpoint does not actually serve. Remove `image` from whichever list granted it — the model's `input`, or the route's `defaultInput` — then start a new session: the attached image stays in the session log, so the same request repeats until the session moves off it.

package/kb/site/en/guide/python-sdk.md

@@ -131,19 +131,35 @@ The first command initializes the shipped standalone profile. The second forward
 
 Another `profile` is valid when it includes `@deepseek-ai/dsh-sdk-app` or another JSON-RPC server row. Missing server rows, unresolved plugins, and invalid patches fail during startup instead of falling back to another composition.
 
+<a id="opt-in-to-str_replace_editor"></a>
+### Opt in to `str_replace_editor`
+
+The bundled runtime includes `str_replace_editor`, but `sdk-minimal` omits it from the default Cordis tree. To use it, save this configuration as `editor.patch.yml`; `insert` adds both the editor and the filesystem provider that the minimal profile lacks:
+
+```yaml
+- insert:
+    - id: fs-local
+      name: '@deepseek-ai/dsh-fs-local'
+      config:
+        cwd: !!js process.cwd()
+    - id: tool-str-replace-editor
+      name: '@deepseek-ai/dsh-tool-str-replace-editor'
+```
+
+Pass `patches=("/absolute/path/to/editor.patch.yml",)` when constructing `DeepSeekHarness(profile="sdk-minimal", ...)`, or put the patch in `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` for persistent configuration. On the next runtime launch, model requests include `str_replace_editor` beside the persistent shell. The local filesystem provider uses the runtime working directory for relative paths; like the minimal shell, it does not confine access to that directory. For the standard `sdk` profile, insert only the editor row so it uses the existing filesystem provider and policies.
+
 ## Understand the minimal profile
 
 | Property | Value |
 |---|---|
 | System prompt | `DSH_SYSTEM_PROMPT`, falling back to `You are a helpful software engineer assistant.` |
 | Model in `minimal.py` | `--model`, then `DSH_MODEL`, then `deepseek-v4-flash` |
-| Model-facing tools | Persistent `bash` on Linux/macOS or `pwsh` on Windows, plus `str_replace_editor` |
+| Model-facing tool | Persistent `bash` on Linux/macOS or `pwsh` on Windows |
 | Shell timeout | 300 seconds |
-| Editor output limit | 16,000 characters |
 | Runtime context and compaction | Absent |
 | Session persistence | Uncompressed JSONL under `<dsh_home>/sessions` |
 
-The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while settings, managed credentials, telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. It pins `danger-full-access`, so the platform-selected persistent shell and editor can modify any path visible to the runtime; use a disposable checkout or container.
+The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while filesystem tools, settings, managed credentials, telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. It pins `danger-full-access`, so the platform-selected persistent shell can modify any path visible to the runtime; use a disposable checkout or container.
 
 The installed wheel still packages the full `web` profile and frontend assets. Run `dsh web` against an explicit `DSH_HOME` when a Python SDK deployment also needs the browser application; `web` is a separate CLI application and cannot serve a Python SDK client.
 

package/kb/site/en/reference/agent-lifecycle.md

@@ -29,23 +29,30 @@ sequenceDiagram
   Note over Agent,Driver: claim pending next-step input plus one queued prompt
   Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
   Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
   Driver->>Hooks: <code>agent/pre-step</code> waterfall
   Hooks-->>Driver: authoritative reject or enter(messages)
-  alt proposed step rejected or pre-step failed
+  alt proposed step rejected, first batch empty, or pre-step failed
     Driver-->>Driver: claimed batch stays removed, the open turn spends no step
   else enter proposed step
   Driver->>Session: <code>step/start</code>
+  Driver->>Hooks: <code>agent/request</code> waterfall
+  Driver->>LLM: prepareCall(config, signal)
+  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
+  Note over Driver,Session: synchronous admission using the prepared call capability
+  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
   Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
-  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
+  Driver->>Driver: derive and freeze request from the log
+  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
   LLM-->>Driver: StreamChunk*
   Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
   alt final adapter or terminal in-band request failure
     Driver->>Session: <code>assistant/attempt</code>
     Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Session: <code>step/end</code>
     Driver->>Hooks: <code>agent/request-error</code> waterfall
     Hooks-->>Driver: return retry action or preserve the original error
+    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
   else model request succeeded
   Driver->>Session: <code>assistant/message</code>
   Driver-->>SDK: <code>agent/assistant-stream</code> committed end
@@ -79,7 +86,7 @@ sequenceDiagram
 
 The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
 
-`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
+`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery runs within the open step and retries only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative. Each retry prepares its call and reconciles the retained rendered assembly before request derivation, without repeating assembly, pre-step, or user admission.
 
 The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
 

package/kb/site/en/reference/capability-seams.md

@@ -48,6 +48,8 @@ flowchart LR
   pkg_api_settings_controller["api-settings-controller"]
   svc_credentialsController["ctx.credentialsController<br/>Host credential-surface Remote controller"]
   svc_settingsController["ctx.settingsController<br/>Host settings-surface Remote controller"]
+  pkg_api_workspace_files["api-workspace-files"]
+  svc_workspaceFiles["ctx.workspaceFiles<br/>Host workspace file Remote service"]
   pkg_api_workspace_controller["api-workspace-controller"]
   svc_workspaceController["ctx.workspaceController<br/>Host Workspace Remote controller"]
   svc_directoryPickerController["ctx.directoryPickerController<br/>Host directory-picking Remote controller"]
@@ -84,6 +86,8 @@ flowchart LR
   svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
   pkg_workspace["workspace"]
   svc_messageFeedback["ctx.messageFeedback<br/>Lifecycle-bound message feedback"]
+  pkg_command_feedback["command-feedback"]
+  svc_sessionFeedback["ctx.sessionFeedback<br/>Session-level feedback recorder"]
   svc_workspaceRegistry["ctx.workspaceRegistry<br/>Workspace entity registry"]
   svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
@@ -236,6 +240,7 @@ flowchart LR
   pkg_api_settings_controller --> svc_settingsController
   pkg_api_workspace_controller --> svc_directoryPickerController
   pkg_api_workspace_controller --> svc_workspaceController
+  pkg_api_workspace_files --> svc_workspaceFiles
   pkg_attachment --> svc_attachments
   pkg_attachment_local --> svc_attachments
   pkg_authorization --> svc_authorization
@@ -245,6 +250,7 @@ flowchart LR
   pkg_client_modules --> svc_clientModules
   pkg_code_runtime --> svc_codeRuntime
   pkg_code_runtime_worker_thread --> svc_codeRuntime
+  pkg_command_feedback --> svc_sessionFeedback
   pkg_commands --> svc_commands
   pkg_compaction --> svc_compaction
   pkg_compaction_basic --> svc_compaction
@@ -425,7 +431,6 @@ flowchart LR
   svc_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
   svc_storage --> pkg_storage_domain
-  svc_storageDomain --> pkg_message_feedback
   svc_storageDomain --> pkg_workspace
   svc_subagentModelSelection --> pkg_tool_subagent
   svc_subagents --> pkg_tool_ralph
@@ -485,6 +490,7 @@ flowchart LR
 | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/session-controller) | - | - | - | Lists the Session composition's user-invocable skills without activating a cold Agent. |
 | `ctx.credentialsController` | `core` | [`api-settings-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/settings-controller) | - | - | - | Projects the credential-reference seam onto the generated Remote namespace: batch fan-out, view projection, and refusal mapping live here, not on the seam Definition. |
 | `ctx.settingsController` | `core` | [`api-settings-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/settings-controller) | - | - | - | Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition. |
+| `ctx.workspaceFiles` | `core` | [`api-workspace-files`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/workspace-files) | - | - | - | Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session's workspace root, confined by lstat, containment, and a stat re-check. |
 | `ctx.workspaceController` | `core` | [`api-workspace-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/workspace-controller) | - | - | - | Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace. |
 | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/workspace-controller) | - | - | - | Carries the picking seam onto the wire: capability gating, cancellation, and the seam-coded failures a browser directory flow discriminates on. |
 | `ctx.invariants` | `core` | [`invariants`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/runtime-diagnostics/invariants) | - | [`session`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/session), [`agent`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/agent), [`scope`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/scope), [`agent-loop`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
@@ -497,8 +503,9 @@ flowchart LR
 | `ctx.authorization` | `seam` | [`authorization`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/credentials/authorization) | - | [`llm-pi-ai`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/llm/llm-pi-ai) | - | Flows are registered by the plugin that knows how to obtain one credential and keyed by the record they write; the seam owns the conversation and the one-attempt-per-key lifecycle, never the protocol. |
 | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-telemetry) | [`session-telemetry-otel`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage) | [`storage-json`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage-json), [`storage-sqlite`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage-sqlite) | [`storage-domain`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
-| `ctx.storageDomain` | `core` | [`storage-domain`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage-domain) | - | [`workspace`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workspace/workspace), [`message-feedback`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/feedback/message-feedback) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
-| `ctx.messageFeedback` | `core` | [`message-feedback`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/feedback/message-feedback) | - | - | - | Owns local per-assistant-message feedback, lifecycle and target validation, per-item compare-and-set, and the Host unary Remote contract without entering Session history or telemetry. |
+| `ctx.storageDomain` | `core` | [`storage-domain`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/storage/storage-domain) | - | [`workspace`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
+| `ctx.messageFeedback` | `core` | [`message-feedback`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/feedback/message-feedback) | - | - | - | Owns per-assistant-message feedback in the canonical Session log, target validation, per-item compare-and-set, and the Host unary Remote contract. Feedback stays outside model history; log export follows the consumer policy. |
+| `ctx.sessionFeedback` | `core` | [`command-feedback`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/feedback/command-feedback) | - | - | - | Records one Session-level remark with its category as a log-only feedback/record event on a live Session through the Host unary Remote contract; the /feedback command shares the same producer. |
 | `ctx.workspaceRegistry` | `core` | [`workspace`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/workspace/workspace) | - | [`api-workspace-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/workspace-controller), [`api-session-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/session-controller) | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session-query/session-query) | [`session-query-sqlite`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session-query/session-query-sqlite) | [`session-reference`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/context/session-reference), [`tool-session-query`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
 | `ctx.fileReferences` | `seam` | [`file-reference`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/context/file-reference) | [`file-reference-local`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/context/file-reference-local) | [`api-session-controller`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/api/session-controller) | - | The interface returns path-only completion candidates within an Agent cwd; providers own namespace access and ranking without reading file contents. |