better-dsh 0.2.3 → 0.2.4-b

package/docs/specs/tool-surface/spec.md

@@ -0,0 +1,222 @@
+# tool-surface Specification
+
+## Purpose
+DASHR 的模型表面（model surface）契约：哪些工具出现在 registry 投影（LLM-client 协议 tools 数组、REPL 绑定）里。核心原则——掩码作用于 tool registry（被替代了呈现面的原生工具全部 visible=false）；REPL 绑定对 registry 可见集做机械/透明的自动桥接（零名单维护）；被掩工具的能力保留靠三桥 service 层直调（`agent` spawn/fork、`agent_message` 消息+中断、`agent_workflow` 编排），不靠 registry 豁免。全部 REPL 指引（cell 语义、调用形、非 flat 名例外、`subagent` 别名注记）只经由 `eval` 工具的 wire description 承载——system prompt 中不存在任何 DASHR 渲染的工具目录或 control-prompt section。
+
+## Requirements
+
+### Requirement: Registry masking of replaced-presentation native tools
+
+The system SHALL remove the native tools whose presentation surface DASHR replaces（`skill`、上游 `send_message`、`report`、`list_agents`、delegation 家族 `subagent_fork`/`interrupt_agent`/`workflow`/`ralph`）from the agent's tool registry projection via an agent-scope registry restriction —— wire tools array 与 REPL bindings 同源于该 projection，移除因此均匀生效。`subagent` is deliberately NOT masked：它在每个表面保持可见，且 **`eval` 工具的 description** 注记它是 `agent` delegation tool（统一 agent-spawn 入口）的别名。The restriction MUST NOT touch the registered tool definitions themselves；DASHR preserves each masked tool's native capability at the tool-bridge level（not by registry exemption）：`agent` spawns/forks subagents、`agent_message` 经 host-plane service 层传递 child-downlink/parent-uplink/interrupt、`agent_workflow` 把 script/rfc 透传给 CAPTURED native workflow/ralph definitions（workflowEngine service 是 preset delegation realm 的 entry-local 服务，任何外部 ctx 不可见——native execute closures 从内部解析）；`agent://` 取代 `list_agents`、`read skill://` 取代 `skill`。
+
+#### Scenario: Masked tool absent from every model-facing surface
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** the wire tools array 与 the REPL bindings 均不含 masked 名，对 masked 名的调用返回 `UNKNOWN_TOOL`
+
+#### Scenario: subagent stays visible as an annotated alias
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** `subagent` remains present on the wire tools array 与 the REPL bindings，且 `eval` 工具 description 注明它是 `agent` delegation tool 的别名
+
+#### Scenario: Masked capability preserved through the bridge
+
+- **WHEN** the model sends a child-downlink, parent-uplink, or interrupt through the `agent_message` bridge
+- **THEN** the service layer executes it with native delivery semantics (user-role next-turn delivery, `messageId` confirmation) and native authorization (direct-child-only lineage, ancestor authority for interrupt)
+
+#### Scenario: DASHR's own wrappers unaffected
+
+- **WHEN** the agent-scope restriction denies a native name that a DASHR wrapper shadows on the agent's own layer
+- **THEN** the wrapper (`read`/`write`/`grep`/`glob`, `agent`/`agent_message`/`agent_workflow`) remains visible and callable on every surface
+
+### Requirement: Delegation bridges are registry tools
+
+The system SHALL register the delegation bridges（`agent`、`agent_message`、`agent_workflow`）as real tools in the tool registry（与 `eval` transport 同一 host registration 层），runtime argument validation inside their execute、structured `{ error }` return values（bad input 不抛异常）。Registry projection 是**两个**模型表面的 single source：wire tools array 与 REPL `tool.*` bindings（经 mechanical auto-bridge）。两个表面 SHALL 每个 session name-by-name 相等（以 mechanical binding rule 的 flat-name 限定为界）；唯一允许的例外是 `eval` 本身排除在 binding set 之外（self-call prevention）。
+
+#### Scenario: Bridge callable directly on the wire
+
+- **WHEN** the model sends a direct tool call `agent` with `{ description, prompt }` (no cell)
+- **THEN** the call dispatches through the normal kernel pipeline and returns the same result shape the REPL binding returns, with the same audit events as any registry tool
+
+#### Scenario: Three-surface name equality
+
+- **WHEN** a DASHR session starts
+- **THEN** 目录表面已随「Catalog section presents REPL bridge instructions」的 REMOVED 撤销，原三表面等式收敛为两表面：the wire tools array 与 the REPL binding names 在 flat-name 规则内 equal as sets，excepting only `eval`
+
+#### Scenario: No dual-source drift
+
+- **WHEN** a bridge's parameter surface changes
+- **THEN** the wire schema 与 REPL binding 一起变化，因为两者都派生自同一注册 schema
+
+### Requirement: eval transport description matches runtime semantics
+
+The system SHALL state the eval transport's top-level semantics truthfully in **the `eval` tool's model-facing description（唯一的 REPL 指引载体）**：top-level `await` works —— kernel 以 `PyCF_ALLOW_TOP_LEVEL_AWAIT` 编译 cell 并运行 module coroutine；top-level `return` is a SyntaxError（cell 运行于 module scope，globals = locals）。The description SHALL NOT claim top-level `return` is accepted.
+
+#### Scenario: Description promises only what the kernel does
+
+- **WHEN** the model reads the `eval` tool description
+- **THEN** the text states that top-level `await` works，states that top-level `return` is a SyntaxError（module-scope cell），and contains no claim that top-level `return` is accepted
+
+#### Scenario: Top-level return stays rejected
+
+- **WHEN** a cell contains a top-level `return`
+- **THEN** the kernel rejects it with a SyntaxError, matching the description
+
+### Requirement: eval description is the single REPL guidance source
+
+The system SHALL carry ALL REPL guidance in the `eval` tool's wire description —— cell 语义、直调 vs 进 cell 的判据、非 flat 名例外、`subagent` 别名注记、**置于 description 末尾**的 mechanical bridge 调用形 —— 内容从**插件源码中的 Markdown 文件**加载、注册工具时作为 `description` 生效；system prompt 中 SHALL NOT 存在任何 DASHR 渲染的工具目录或 control-prompt section。桥接指引 SHALL 只陈述**一个**统一调用形、一句话说清：`await tool.<name>(argsObject)`，argsObject = 该工具 wire JSON-Schema 参数对象写成的 Python dict 字面量（同字段名、单个位置参数、不用 kwargs），唯一系统性语法差异为 `true`/`false`/`null` → `True`/`False`/`None`；SHALL NOT 渲染 per-tool 签名表，且 SHALL NOT 对桥接调用的返回值形态作任何陈述（不写"不保证形状/需试错"类措辞）。描述中的桥接示例 SHALL 使用与被引工具 wire schema 一致的参数名。
+
+#### Scenario: System prompt carries no DASHR catalog or control section
+
+- **WHEN** an agent session renders its system prompt
+- **THEN** 没有 DASHR 来源的 section 枚举 per-tool 签名，也没有独立的 control-prompt section 教 cell 范式；全部 REPL 指引只经由 `eval` description 到达模型
+
+#### Scenario: Description loads from the source Markdown
+
+- **WHEN** the plugin registers the `eval` tool
+- **THEN** 其 wire description 等于包内 Markdown 指引文件的内容——编辑该文件即改变模型可见的 description
+
+#### Scenario: One bridge call form, one syntax delta
+
+- **WHEN** the model reads the bridge instructions in the `eval` description
+- **THEN** it sees the single positional-args-object call form 与 `True`/`False`/`None` 大小写映射，and no per-tool signature table or output-shape caveat（无任何"不保证形态/试错"措辞）
+
+#### Scenario: Examples match wire parameter names
+
+- **WHEN** the description shows a bridge example for `read`
+- **THEN** 参数键与 `read` 的 wire schema 一致（如 `path`），而非其它工具的键名
+
+#### Scenario: Guidance lives and dies with the tool
+
+- **WHEN** a session's scope excludes the `eval` tool
+- **THEN** 任何地方都不渲染 REPL 指引（指引即工具自身的 description）；`eval` 在场时指引必然在场
+
+#### Scenario: Alias annotation present
+
+- **WHEN** the model reads the `eval` description
+- **THEN** it states that `subagent` is an alias of the `agent` delegation tool，两者经同一 runtime delegate
+
+#### Scenario: Non-flat exception present
+
+- **WHEN** the model reads the `eval` description
+- **THEN** it states that 含非标识符字符（如连字符）的工具名没有 `tool.<name>` member，必须以 direct tool call 调用
+
+### Requirement: Masking failures surface loudly
+
+The system SHALL surface a structured error, not a silent skip, when restricting any masked tool name fails at session start；application 完成后 mask SHALL verify 每个 masked 名在 **the wire tools array 与 the REPL bindings** 中均不存在。
+
+#### Scenario: A masked name's restriction errors and the session reports it
+
+- **WHEN** applying the mask, a single masked name's registry restriction throws
+- **THEN** the session surfaces the failure as a structured error naming the masked tool, and the name does not silently remain on any model-facing surface
+
+#### Scenario: Masked names absent after successful application
+
+- **WHEN** an agent session starts under DASHR with a healthy registry
+- **THEN** the wire tools array 与 the REPL bindings contain none of the masked names（`skill`、`send_message`、`report`、`list_agents`、`subagent_fork`、`interrupt_agent`、`workflow`、`ralph`），and a call naming a masked tool returns `UNKNOWN_TOOL`
+
+### Requirement: REPL bindings bridge the visible registry mechanically
+The system SHALL install REPL bindings by automatic, transparent conversion of every flat-bindable name in the registry's visible set at session start — no manual allowlist or denylist; masked names are naturally absent because the binding source and the masking act on the same projection. Non-flat names SHALL be skipped — a name is non-flat when it contains characters outside `[A-Za-z0-9_]` (e.g. hyphens); a `__` infix alone is a legal identifier and does not by itself make a name non-flat — and the bridge instructions SHALL state the name-shape limitation without enumerating affected tools.
+
+#### Scenario: A newly registered host tool appears in the REPL without list edits
+- **WHEN** the host registers a new flat-named tool after a DASHR upgrade
+- **THEN** the next agent session exposes it as `tool.<name>` with no DASHR source change
+
+#### Scenario: Non-flat MCP names documented, not listed
+- **WHEN** an MCP tool named `mcp__server__tool-name` is registered
+- **THEN** no binding is created for it, and the bridge instructions explain the name-shape limitation
+
+#### Scenario: Double-underscore infix alone stays bindable
+- **WHEN** a tool named `mcp__server__tool` (identifier characters only, no hyphen) is registered
+- **THEN** the name is flat-bindable (`'mcp__server__tool'.isidentifier()` is true) and appears as `tool.<name>` unless separately masked
+
+### Requirement: llm_completion tool
+The system SHALL provide an `llm_completion` tool: a one-shot, stateless LLM call — no tools, no conversation history, no agent creation. Inputs: `{ prompt, system?, maxTokens? }`; output: the model's text. The call SHALL be attributed to the calling agent's session through the normal tool-call audit (the host's auxiliary-purpose enum is closed and carries no completion class), SHALL honor the caller's abort signal, and SHALL resolve its model route from the calling agent's current model selection, and SHALL answer a structured error value — never a silent fallback route — when no selection is available. A finish other than a clean stop, or any tool-call block in the output, SHALL produce a structured error value, not a thrown exception.
+
+#### Scenario: Zero-spawn judge step inside a cell
+- **WHEN** a cell calls `await tool.llm_completion({ prompt: "<judge prompt>", system: "<rubric>" })`
+- **THEN** the value returned is the model's text; no subagent is spawned, no session besides the caller's is created, and the call is auditable under its own purpose
+
+#### Scenario: Model route follows the caller
+- **WHEN** the calling agent's selected model differs from the host default
+- **THEN** the completion runs on the caller's selection
+
+#### Scenario: Degraded finish is a structured error
+- **WHEN** the completion hits maxTokens or aborts
+- **THEN** the tool returns `{ error: <description> }` rather than throwing
+
+### Requirement: REPL tool namespace introspection
+The system SHALL make the REPL `tool` namespace introspectable: `dir(tool)` returns the sorted list of bound tool names — exactly the names callable as `tool.<name>(argsObject)`. The underlying injected mapping (e.g. `__dashr_injected__`) remains unchanged for compatibility; `dir()` is the documented introspection surface.
+
+#### Scenario: dir(tool) lists the binding set
+- **WHEN** a cell runs `dir(tool)`
+- **THEN** the returned list equals the sorted set of names bound in the `tool` namespace for that run (dunder members aside), including the delegation bridges and `llm_completion`
+
+### Requirement: Hashline edit family registered on the agent's own layer
+
+The system SHALL register the vendored hashline edit family on each agent's own scope layer at session start — `edit` (hash-anchored ordered edit tuples, shadowing the preset's built-in edit by nearest-layer resolution, no mask entry needed) and `undo_last_edit` (revert of the most recent hashline edit) — alongside the URL-aware read/write/grep/glob wrappers, unwinding with the agent. The write tool SHALL remain the upstream full-file write with its native confirmation envelope: no hook SHALL append a hashline preview to write results, and the hashline guidance SHALL NOT promise post-write anchors (the model MAY edit directly using anchors derived from the content it just wrote, or read first). The hashline guidance sections SHALL shadow the preset's built-in tool guidance on the same layer (compiled defaults when no agentPresets service or a failing override — never a failed install).
+
+#### Scenario: A hash-anchored edit lands and is reversible
+
+- **WHEN** the model calls `edit` with anchored edit tuples on a file whose current content matches the anchors
+- **THEN** the edit applies atomically (drift-checked against current content), and a subsequent `undo_last_edit` reverts it
+
+#### Scenario: A write result stays upstream-native
+
+- **WHEN** the model calls `write` and it succeeds
+- **THEN** the result content is the upstream confirmation envelope with no auto-read/anchor section appended, and no read is required before the next anchored `edit` on that file
+
+#### Scenario: The shadow replaces the built-in edit without masking
+
+- **WHEN** an agent session starts under DASHR
+- **THEN** the `edit` the model sees is the hashline tool (own-layer shadow), the preset's built-in edit is unreachable for that agent, and no deny-list entry names `edit`
+
+### Requirement: Lsp feedback rides edit results
+The system SHALL attach the same write-feedback diagnostics contract to successful edits: after a landed `edit` with an explicit path, the result content carries the diagnostics summary computed from the exact landed content (didSave freshness, timeout degradation, span guard — the `dvc` write-feedback requirement's terms apply verbatim). Anchor-only edits (path inferred from anchors) and non-edit tools pass through untouched; the write tool's feedback stays with its wrapper (no double pull).
+
+#### Scenario: An edit that introduces a type error reports it
+- **WHEN** an edit lands content introducing a type error in a file with a language server and its check completes within the budget
+- **THEN** the edit result text carries the diagnostics summary for the exact landed content
+
+### Requirement: Hashline edit verification is content-anchored
+
+The system SHALL verify each edit tuple's anchors against the CURRENT file content before consulting any ledger: an anchor SHALL be accepted when its hash locates a unique, consistently pairable position in the current canonical line hashes; the served ledger SHALL be advisory (echo/undo attribution) and keyed by canonical absolute path with no session identity, so anchors survive session-tree forks and continuation without a re-read. Genuine drift SHALL still fail closed with nothing written, batch atomicity SHALL be unchanged, and a multi-tuple batch failure SHALL instruct reading the file once and resubmitting the whole batch.
+
+#### Scenario: An edit across a forked session lands without a re-read
+
+- **WHEN** a file is written or read in one session node, the conversation continues in a forked node (new session identity), and the model submits anchored edit tuples derived from that earlier content
+- **THEN** the edit applies without any intervening `read`, because verification matched current content
+
+#### Scenario: A drifted line still fails closed
+
+- **WHEN** an anchor's hash no longer exists in the current file (content changed or line removed externally)
+- **THEN** the tuple is rejected with a drift error stating the content changed and a read is needed, and nothing is written
+
+#### Scenario: An ambiguous anchor falls back before failing
+
+- **WHEN** an anchor's hash occurs at multiple current positions and the served ledger cannot disambiguate the span
+- **THEN** the tuple is rejected with nothing written, and the error names the ambiguity
+
+#### Scenario: Multi-tuple failure copy is actionable
+
+- **WHEN** any tuple in a multi-tuple batch fails verification
+- **THEN** the batch aborts with zero writes and the error instructs reading the file once, then resubmitting the whole batch
+
+### Requirement: Hashline store centralized under DSH_HOME
+
+The hashline store SHALL live at a single location — `$DSH_HOME/storages/dsh-better-edit/hash-store.sqlite` — for tool calls, previews, and tests alike, resolved through the harness home resolver so `DSH_HOME` isolates deployments; no per-workspace dot-directory SHALL be created. The served table SHALL be keyed by canonical absolute path (no session column), the 7-day TTL prune SHALL be retained, and the store schema version SHALL bump with a rebuild-on-mismatch gate that drops and recreates legacy session-keyed served tables.
+
+#### Scenario: No dot-directory is created
+
+- **WHEN** hashline tools run inside any workspace
+- **THEN** state lands in the centralized store and no `<workspace>/.dsh_better_edit/` directory is created
+
+#### Scenario: DSH_HOME isolates deployments
+
+- **WHEN** the harness runs with a test `DSH_HOME` (e.g. the 4999 line)
+- **THEN** its hashline store is a separate file under that home and never touches the production store
+
+#### Scenario: Legacy session-keyed served tables rebuild
+
+- **WHEN** the store opens with a schema version below the current one, or a served table still carrying a `session_id` column
+- **THEN** the served table is dropped and recreated with the path-keyed schema, and the version marker is updated

package/docs/specs/url-schema/spec.md

@@ -0,0 +1,148 @@
+# url-schema Specification
+
+## Purpose
+
+Give DASHR one uniform URL resource-addressing layer: read/write/grep/glob accept `scheme://` URLs, route by scheme to a handler, apply one selector syntax uniformly, and keep non-URL behavior byte-identical to the native tools via delegation.
+
+## Requirements
+
+### Requirement: FS-shaped tools accept and route scheme URLs
+The scheme registry SHALL be owned by the `dsh-url-schemes` cordis service (renamed from `dsh-url-schema`), which SHALL contain the `UrlResolver` and scheme handlers only (no tool registrations inside the service). The URL-aware read/write/grep/glob tools SHALL be tool-layer consumers. read SHALL accept `scheme://` URLs and resolve them end-to-end through the scheme registry; grep/glob SHALL translate or materialize the resource for the native search; write SHALL dispatch to a structured per-scheme write channel (all rejected this wave).
+
+#### Scenario: Reading a registered scheme
+- **WHEN** the model calls read with a registered scheme URL (e.g. `skill://foo`)
+- **THEN** the system returns the handler-resolved content with the selector applied, not a filesystem read
+
+#### Scenario: Reading an unregistered scheme
+- **WHEN** the model calls read with a URL whose scheme has no registered handler (including `history://` — no special case exists)
+- **THEN** the system returns the structured `URL_UNREGISTERED_SCHEME` error listing the registered schemes
+
+#### Scenario: URL without a scheme prefix
+- **WHEN** a resolver-layer caller passes a string without `scheme://`
+- **THEN** the system returns the structured `URL_NO_SCHEME` error
+
+### Requirement: `dsh://docs` serves the vendored upstream official docs
+`dsh://docs` SHALL serve the shipped upstream official harness documentation corpus (`dsh-docs/`, vendored from the `deepseek-ai/deepseek-harness` repo `docs/`), not the DASHR repository's working notes. Resolution order: explicit `docsDir` → packaged `dsh-docs/` → packaged `docs/` → repo-root `docs/` (walk-up probes `dsh-docs` before `docs` at every level).
+
+#### Scenario: Docs index lists the official corpus
+- **WHEN** the model reads `dsh://docs`
+- **THEN** the index enumerates the upstream official docs tree (`agent-lifecycle.md`, `api-gateway.md`, `architecture.md`, …)
+
+### Requirement: Bare `skill://` lists the available skills
+A bare `skill://` URL (no skill name) SHALL render the cwd-scoped skill catalog from the registry's `list` face — one line per winning summary (`skill://<name> — <description>`, plus `(use when: …)` when `whenToUse` is present) — using the same discovery rule as a name lookup. An empty catalog SHALL answer explicitly, never with an error.
+
+#### Scenario: Bare skill list
+- **WHEN** the model reads `skill://` with no skill name
+- **THEN** the tool result contains the count header and per-skill lines, cwd-scoped exactly like `skill://<name>` resolution
+
+#### Scenario: Empty catalog
+- **WHEN** no skill is available in the workspace scope
+- **THEN** the result reads "No skills available in this workspace scope." — not a `URL_SKILL_NOT_FOUND` error
+
+### Requirement: Delegation shells preserve native non-URL behavior
+The system SHALL implement read/write/grep/glob as delegation shells over the definition registered under the same semantic name at capture time, captured once per agent via `ctx.tools.get(name, agent)` strictly before the wrappers register on the agent's own scope layer (`read` included — its captured delegate MAY be another feature's wrapper). Non-URL inputs SHALL be forwarded verbatim to `captured.execute(args, exec)`, preserving the native write-intent policy gate, sandbox resolution, ripgrep search semantics, and any outer-layer behavior already present. The shells SHALL honor per-feature config gates `Config = { urlSchemes?: boolean = true, hashline?: boolean = true }` from the patch-line `config:` block: with `urlSchemes: false`, scheme paths SHALL fall through to the captured definition (native failure semantics are honest); with `hashline: false`, file reads SHALL delegate without hashline anchoring.
+
+#### Scenario: Ordinary write keeps the policy gate
+- **WHEN** the model writes to an ordinary file path
+- **THEN** the call runs through the captured native write definition — the write-intent policy gate, sandbox resolution, and observation events behave exactly as before the URL schema existed
+
+#### Scenario: Ordinary grep/glob keep ripgrep semantics
+- **WHEN** the model greps or globs over ordinary paths
+- **THEN** the call delegates to the captured native definition with args untouched, returning native-shaped results
+
+#### Scenario: Missing native delegate fails loudly
+- **WHEN** a host did not deploy the native write/grep/glob and the corresponding wrapper is invoked on a non-URL input
+- **THEN** the system returns the structured `NATIVE_WRITE_UNAVAILABLE` / `NATIVE_GREP_UNAVAILABLE` / `NATIVE_GLOB_UNAVAILABLE` error instead of reimplementing the tool
+
+#### Scenario: Capture happens before registration
+- **WHEN** an agent session starts and the URL-aware tools are installed
+- **THEN** the definitions under `read`/`write`/`grep`/`glob` are captured strictly before any wrapper registers on that agent's scope layer, so the captured reference is the pre-existing tool rather than the wrapper (no self-recursion)
+
+#### Scenario: URL capability disabled by gate
+- **WHEN** the patch line sets `urlSchemes: false` and the model reads `ctx://session`
+- **THEN** the wrapper delegates to the captured read definition and the native failure surfaces
+
+### Requirement: URL search reuses the native engine
+The system SHALL run grep/glob over URL-addressed resources through the native search engine: path-backed schemes (a handler-implemented `resolvePath` mapping the URL to a real disk location — `skill://` today) have the URL translated to the disk path before delegating; content-backed schemes (agent, ctx, `dsh://config`, http, …) have the resolved text materialized into a fresh RAM-backed tempfs directory (`/dev/shm` when available and writable; falling back to the OS temp dir when unavailable or when a single materialization exceeds 8 MiB) which is removed afterwards whatever the outcome.
+
+#### Scenario: Searching a path-backed resource
+- **WHEN** the model greps a `skill://name` URL
+- **THEN** the URL is translated to the skill's real disk path and only the search root is rewritten before the native grep runs
+
+#### Scenario: Searching a content-backed resource
+- **WHEN** the model greps a content-backed URL (e.g. `ctx://model`)
+- **THEN** the resolved text is written into a fresh temp dir under `/dev/shm` (or the OS temp dir on fallback) as `content.txt`, the native grep searches it, and the temp dir is removed whether the search succeeds or fails
+
+#### Scenario: Listing a URL resource
+- **WHEN** the model calls glob with a URL in `pattern`
+- **THEN** a path-backed scheme globs the resource's real disk directory natively, and a content-backed scheme returns the resolved text's non-empty lines as the listing without a native call
+
+#### Scenario: Glob metacharacters in a URL pattern
+- **WHEN** the glob pattern is a URL carrying glob metacharacters (e.g. `skill://grp/*`, `skill://grp/**/*.md`)
+- **THEN** the pattern splits at the first metacharacter (`*?[`): the URL part resolves via `resolvePath` and the tail is the rooted glob pattern applied WITHIN the resource's real disk directory — the raw metachar-containing string is never handed to the native engine as a literal path
+
+#### Scenario: Grep match paths report URL addressing
+- **WHEN** a grep over a path-backed URL returns matches
+- **THEN** match paths are rewritten back to the URL form (`skill://grp/SKILL.md`), both for absolute paths under the disk root and for native-relative paths — the model never sees internal disk locations
+
+#### Scenario: Fallback to the OS temp dir
+- **WHEN** `/dev/shm` is unavailable or the content exceeds 8 MiB
+- **THEN** materialization falls back to the OS temp dir and the search still completes
+
+### Requirement: URL writes are rejected per scheme
+The system SHALL reject every `scheme://` write with a scheme-specific structured error: `dvc://` → `DVC_NO_DEVICE` (no device mounted), `ctx://` → `URL_READ_ONLY` (curated read-only snapshot), any other registered scheme → `URL_WRITE_UNSUPPORTED`, unregistered scheme → `URL_UNREGISTERED_SCHEME`.
+
+#### Scenario: Writing to a read-only scheme
+- **WHEN** the model writes to `ctx://model`
+- **THEN** the system returns the structured `URL_READ_ONLY` error explaining the scheme is a read-only snapshot
+
+#### Scenario: Writing to the device placeholder
+- **WHEN** the model writes to `dvc://<device>`
+- **THEN** the system returns the structured `DVC_NO_DEVICE` error (no devices mounted to route the write to)
+
+### Requirement: Unified selector syntax
+The system SHALL parse selectors once (`:N-M` comma-lists, `:raw`, `:path/…`, `?q=`) and apply them uniformly to every handler's full text after resolution. Handlers return full text with no default line truncation; only explicit selectors page. Malformed selectors return the structured `URL_BAD_SELECTOR` error.
+
+#### Scenario: Scheme URL with a line range
+- **WHEN** the model reads `skill://foo:50-100`
+- **THEN** the system resolves the full skill body and returns lines 50–100, exactly as it would slice a plain file
+
+#### Scenario: JSON path and query selectors
+- **WHEN** the resolved text is JSON and the URL carries `:path/a.b` or `?q=a.b`
+- **THEN** the system navigates the JSON by dot-path; for non-JSON text `?q=` keeps the lines containing the query string
+
+### Requirement: Read delegation shapes args to the delegate and coerces output
+The URL-aware read wrapper SHALL accept both `path` and `file_path` (aliased); when delegating a non-scheme path it SHALL shape args to the delegate's DECLARED parameters (`file_path` for the host-native read, `path` for hashline; opaque schemas forwarded verbatim — no keys added an unknown validator might reject) and SHALL coerce a non-string delegate result to the wrapper's string output (JSON serialization), since the wrapper declares the string face for every branch.
+
+#### Scenario: Host-native delegate receives file_path
+- **WHEN** a file path is delegated to a delegate whose schema declares `file_path`
+- **THEN** the delegate receives `file_path` (the `path` key removed) and its structured result is serialized into the wrapper's string output
+
+#### Scenario: Hashline delegate receives path
+- **WHEN** a file path is delegated to the hashline read (schema declares `path`)
+- **THEN** the delegate receives `path` only and the anchored text returns verbatim
+
+### Requirement: read's file branch stays vendored hashline
+The system SHALL keep the ordinary-file branch of read on the vendored hashline pipeline (HASH│content anchors plus the snapshot store the vendored edit tools depend on), reading through the sandboxed filesystem and the fs observation policy gate — read delegates to no native definition.
+
+#### Scenario: Plain file read returns hashline anchors
+- **WHEN** the model reads an ordinary file path
+- **THEN** the system returns hashline-anchored lines via the vendored pipeline and records the observation with the fs policy gate, so follow-up edit calls see the version just read
+
+### Requirement: Read chassis with ordered transforms
+The `read` tool registration SHALL be owned by a single chassis inside `dsh-url-schemes`: an ordered transform chain (URL transform, hashline anchor transform, …) with a terminal delegate to the captured read definition. Additional read-side features SHALL register transforms into the chassis rather than registering competing `read` definitions (same-layer same-name registration is a registry error); a read-interested feature SHALL fall back to its own minimal wrapper only when the chassis is absent.
+
+#### Scenario: Transforms compose deterministically
+- **WHEN** both the URL transform and the hashline anchor transform are registered and the model reads a filesystem path
+- **THEN** the path flows URL transform (no match) → anchor transform (anchors applied) → captured native read
+
+### Requirement: General syntax guidance section
+The service SHALL render a gated `url-schema:general` system-prompt section whose text is loaded once at module load from the package-root `url-schemes-instruction.md` (the owner-maintained instruction file; shipped via the package.json `files` array — an unlisted file is omitted from the published package and the module-load `readFileSync` fails plugin boot, the 0.2.3-d ENOENT lesson) (shipped via the package.json `files` array — an unlisted file is omitted from the published package and the module-load `readFileSync` fails plugin boot, the 0.2.3-d ENOENT lesson). The section is the SINGLE surfacing point of the URL scheme set to the model: the read/grep/glob/write tool descriptions SHALL carry NO `scheme://` mentions, so the model cannot believe only some tools accept URLs. The section text is the OWNER-MAINTAINED file rendered verbatim (2026-09-12 ruling: the file is hand-edited, not generated) and SHALL cover at minimum: the general URL grammar (`scheme://<path>[:selector]`); all six schemes (`skill://`, `agent://`, `dsh://`, `ctx://`, `dvc://`, `http(s)://`) with first-level resource coverage per scheme; the selector set including the composite `:raw:N-M` clause; and bulk-read guidance. The section renders only while the URL capability is enabled.
+
+#### Scenario: Gated disclosure
+- **WHEN** the URL capability is enabled and an agent session starts
+- **THEN** the system prompt contains the section text loaded from `url-schemes-instruction.md` with the grammar, selector, and scheme coverage
+
+#### Scenario: Tool descriptions stay scheme-silent
+- **WHEN** the model inspects any read/grep/glob/write tool description on the wire
+- **THEN** no description carries a `scheme://` mention — the `url-schema:general` section is the only place the scheme set is surfaced

package/docs/specs/web-trust-fence/spec.md

@@ -0,0 +1,43 @@
+# web-trust-fence Specification
+
+## Purpose
+better-dsh 的 /api 信任栅栏随发契约（替代 prod 手改 patch）：bundle patch 整行重述 `connection` 行，`trustedHosts` = `DSH_TRUSTED_HOSTS` env 条目 + 上游 webRuntime 权威拼接（env 缺省时行为与原装行等价、零侵入）；host 半 boot script 的 isLoopback 腿——页面 origin 命中 `trustedPageAuthorities` 时置 `window.__DSH_TRANSPORT__ = { ownsHost: true }`（空列表不注入）。
+
+## Requirements
+
+### Requirement: Plugin-shipped fence authorities
+
+The plugin's bundle patch layer SHALL override the `connection` loader row by id, restating the row's full shape, with `config.trustedHosts` computed as the concatenation of `DSH_TRUSTED_HOSTS` environment entries (whitespace-separated) and the upstream `webRuntime`-derived authorities; with the environment variable unset or empty the resulting composition SHALL be byte-equivalent in behavior to the unpatched upstream row (inert by default).
+
+#### Scenario: Env-derived authority passes the fence
+
+- **WHEN** the daemon runs with `DSH_TRUSTED_HOSTS=host.example` and a browser reaches `/api` with `Host: host.example` and same-origin markers
+- **THEN** the request passes the Host/Origin trust fence (no 403 from the fence) and the Settings > Models provider directory loads from that authority
+
+#### Scenario: Inert without the environment variable
+
+- **WHEN** the daemon runs without `DSH_TRUSTED_HOSTS`
+- **THEN** the fence accepts exactly the authorities the unpatched upstream composition would (loopback, LAN literals on all-interface binds, `--trusted-host` extras)
+
+#### Scenario: Malformed entry fails loud at load
+
+- **WHEN** `DSH_TRUSTED_HOSTS` contains an entry that is not a bare canonical `host[:port]` authority
+- **THEN** plugin load fails loudly via the upstream `assertTrustedAuthority` validation instead of silently widening or narrowing the fence
+
+### Requirement: Upgrade-safe replacement of the hand patch
+
+The plugin SHALL NOT require source-level edits to vendored `@deepseek-ai/*` files for fence behavior; the alpha.3 hand patch (`isLoopbackHostname` widening in `dsh-client-connection` index.js and client bundle) SHALL be retirable on alpha.5+ by this capability alone, and the row-override shape SHALL be tracked as an upstream-alignment checklist item (diff `packages/bundle/web-app/cordis.patch.yml`'s `connection` row each alignment round).
+
+#### Scenario: Upstream row drift is detected at alignment time
+
+- **WHEN** an upstream release changes the `connection` row's keys (name, inject, or config shape)
+- **THEN** the alignment-round checklist surfaces the drift before the stale restated row ships
+
+### Requirement: User layer keeps precedence
+
+A user's own profile or home `cordis.patch.yml` override of the `connection` row SHALL take precedence over the plugin's bundle layer, preserving the upstream layering contract.
+
+#### Scenario: User override wins
+
+- **WHEN** the user's profile patch restates the `connection` row
+- **THEN** the user's row applies, not the plugin's

package/docs/upstream-dsh-0.1.5-rc.2-report.md

@@ -0,0 +1,156 @@
+# upstream dsh npm 版本对账：prod 0.1.3-alpha.2 → 0.1.5-rc.2
+
+> 生成时间：2026-09-10（本地时区）
+> 数据源：npm registry（`@deepseek-ai/dsh`）元数据 + `upstream/deepseek-harness` git tag 对账
+> 目标：回答「npm 上比 prod 更高的版本是什么、diff 有多大、对 prod 意味着什么」
+
+---
+
+## 〇、一句话结论
+
+prod 当前跑 **`@deepseek-ai/dsh@0.1.3-alpha.2`**。npm 上比它高的版本是整条 **0.1.5 线**（`alpha.1 / alpha.2 / rc.1 / rc.2`，**0.1.4 从未发布，直接跳号**）。最高版本是 **`0.1.5-rc.2`**（挂在 `next` dist-tag，而 `latest` 还停在 `0.1.5-rc.1`）。
+
+这条 0.1.5 线是**大版本级聚合**：846 commits、3170 文件、约 10.4 万行新增。核心是 **Session 格式 v3 重写**（会话持久化契约变更，对 prod 是**破坏性升级，不可 drop-in**），外加 Electron 桌面打包、Sidebar/dockkit 重构、文件交付「present」工具、图渲染预览、模型默认值切换（DeepSeek V41 Flash）等一批功能。**升级 prod 前必须按 AGENTS.md §一/§二 走对齐轮，不能只换版本号。**
+
+---
+
+## 一、版本全景
+
+npm registry 当前 dist-tags：
+
+| dist-tag | 指向版本 |
+|---|---|
+| `latest` | 0.1.5-rc.1 |
+| `next` | **0.1.5-rc.2**（最高） |
+| `alpha` | 0.1.5-alpha.2 |
+
+比 prod（0.1.3-alpha.2）更高的版本，按发布顺序：
+
+| 版本 | npm 发布时间 (UTC) | dist-tag |
+|---|---|---|
+| 0.1.5-alpha.1 | 2026-09-08 15:57 | — |
+| 0.1.5-alpha.2 | 2026-09-09 14:41 | `alpha` |
+| 0.1.5-rc.1 | 2026-09-10 03:12 | `latest` |
+| **0.1.5-rc.2** | **2026-09-10 14:57** | `next` |
+
+> 注意点：`latest` 并不指向最高版本（rc.1 vs rc.2）；「最高版本」= `next` 上的 **0.1.5-rc.2**。0.1.4 未在 npm 出现过。
+
+对应 git tag（本地 `upstream/deepseek-harness`，已 fetch）：
+
+```
+dsh-v0.1.3-alpha.2  2026-09-07 19:45 +0800   ← prod 当前
+dsh-v0.1.5-alpha.1  2026-09-08 23:25 +0800
+dsh-v0.1.5-alpha.2  2026-09-09 22:13 +0800
+dsh-v0.1.5-rc.1     2026-09-10 09:36 +0800
+dsh-v0.1.5-rc.2     2026-09-10 21:50 +0800
+```
+
+---
+
+## 二、diff 规模
+
+`dsh-v0.1.3-alpha.2 .. dsh-v0.1.5-rc.2`：
+
+| 指标 | 值 |
+|---|---|
+| commits | **846** |
+| 文件 | 3170 changed |
+| 行 | +103,990 / −17,687 |
+| 源码侧（排除 snapshots/tests） | 2474 文件，+68,818 / −13,973 |
+
+分段 commit 分布：
+
+| 区间 | commits |
+|---|---|
+| 0.1.3-alpha.2 → 0.1.5-alpha.1 | 563（大头，聚合了 Session V3 与一堆 feature） |
+| 0.1.5-alpha.1 → 0.1.5-alpha.2 | 262 |
+| 0.1.5-alpha.2 → 0.1.5-rc.1 | 17 |
+| 0.1.5-rc.1 → 0.1.5-rc.2 | 4（收尾/backport） |
+
+---
+
+## 三、依赖面变化（对 prod 直接可见）
+
+prod 0.1.3-alpha.2 有 **71 个 dependencies**，0.1.5-rc.2 有 **72 个**。差异：
+
+1. **新增运行期包 `@deepseek-ai/dsh-tool-present`**（`packages/fs/tool-present`）——新「present」工具：把 agent 产出的文件以不可变交付卡片（download card）呈现，是文件交付特性的宿主半。
+2. `apps/cli` devDeps 新增 `@deepseek-ai/dsh-agent-loop`、`@deepseek-ai/dsh-agent-loop-testkit`（内部，不影响 prod 运行面）。
+3. 新增 client 包 `ui-deliverables`（`PresentRow` / `PresentedFileCard` / `present-open`），属 web shell 交付卡片 UI。
+4. 其余全部 `@deepseek-ai/*` 依赖整体从 `^0.1.3-alpha.2` 抬到 `^0.1.5-rc.2`（同版本号齐步，无个别漂移）。
+5. 底层 `cordis` / `schemastery` / `commander` / `js-yaml` 等版本**未变**（`cordis ^4.0.2`、`schemastery ^3.18.2` 等，与 0.1.3-alpha.2 相同）。
+
+---
+
+## 四、主要变更主题（按 prod 相关度排序）
+
+### 1. Session 格式 v3 重写（⚠ 破坏性，最高风险）
+`session-log-v3` 工作线，是本次最大的变更块。要点：
+
+- 会话身份 **V2 → V3 迁移**（`feat(session): add identity V2-to-V3 migration and writer skeleton`）。
+- system prompt 表示为 **surface node zero**（`refactor(session): represent the system prompt as surface node zero`）。
+- **canonical envelopes**、PTC durable vocabulary、in-history system prompt 表示、JSONL 跨进程写所有权（lease）。
+- 大量 `session.v3.jsonl` 快照与 V2/V3 迁移覆盖面单测。
+
+> **对 prod 的含义**：会话持久化契约改变。上一轮（0.1.3-alpha.2 对齐）已实测：上游 tag diff 会打到 `session-persistence-omp.ts` / `replay.ts` / store 的 handle+lease 契约（见 2026-09-08 对齐报告）。**0.1.5 的 V3 比 0.1.3 的 V2 更进一步，破坏面更大**，`better-dsh` / `omp-web` 这类桥接会话数据的插件必须重新对齐，不能 drop-in。
+
+### 2. Electron 桌面打包（对 3080 web 无直接作用）
+Windows/macOS/Linux 构建、mac 签名+公证、Windows 签名、auto-update、IPC 性能优化。纯桌面宿主线，与本机 `dsh web`（3080）部署无关，但意味着上游发布面从此多一个桌面产物。
+
+### 3. Sidebar / dockkit 重构
+- `dockkit` 可逆停靠引擎、pointer 交互。
+- 全局 sidebar panel、tab 导航、live tab 标题 + 文件类型图标、末 tab 关闭规则、响应式右栏、全屏 shell。
+- session-log 控制移入 header「更多」菜单。
+
+### 4. 文件交付「present」工具 + 文档预览
+- 新 `dsh-tool-present` 包：不可变文件交付下载卡片、artifact 卡原生文件动作、workspace 文件操作。
+- 可扩展文档预览、文本预览分页 tab、文件类型图标集、`ui-deliverables` client 卡。
+- `feat(fs)`：bounded byte-range reads（fs-local / fs-e2b）、dual-face 文件 API。
+
+### 5. 图表 / Markdown 预览
+Chat 代码块内预览 Mermaid / Graphviz / SVG / HTML fence，适配应用主题。
+
+### 6. LLM 模型默认值切换（⚠ 影响 prod 行为）
+- Chat Completions 默认切到 **DeepSeek V41 Flash**（`feat(llm): default Chat Completions to DeepSeek V41 Flash`）。
+- 保留 V4 模型、恢复 V4 Flash Vision Exp catalog 条目。
+> prod 若升级，默认模型会跟着变；需确认是否期望。
+
+### 7. Feedback 对话框
+`/feedback` 与 Dislike 统一为一个带分类的对话框 + toast。
+
+### 8. Subagent catalog
+记录并观察 parent-owned child catalog（子代理目录）。
+
+### 9. native system / node-addon-system
+包族改名 `node-addon-system`，预编译 Node-API flock、Landlock capability 子路径。**新增原生依赖面，升级安装需留意 prod 机上的原生构建/预编译匹配**（本机已有一处 zeromq allowBuilds 特例，见 AGENTS.md §二）。
+
+### 10. minimal profile 行为调整
+- `str_replace_editor` 从 minimal profiles 移除。
+- persistent bash 输出与 one-shot shell 契约对齐。
+> 只影响 minimal profile，不影响 prod `web` profile 的默认工具集。
+
+### 11. 其它
+- CLI：从 shipped 模板创建 profile。
+- skills：Playwright 视频录制 GIF。
+- 内部 CI/审查自动化（weighted PR approval、review owner 排名等）——与 prod 运行无关。
+
+---
+
+## 五、对 prod 升级的风险评估（简要）
+
+| 风险项 | 级别 | 说明 |
+|---|---|---|
+| Session V3 格式迁移 | 🔴 高 | 会话持久化契约变更；`better-dsh`/`omp-web` 会话桥接面需重新对齐，先例（0.1.3 V2）已证实非 drop-in |
+| 模型默认切 V41 Flash | 🟠 中 | 默认行为变化，需 user 确认是否接受 |
+| 新原生依赖（node-addon-system） | 🟡 中低 | 安装面原生构建/预编译匹配；本机 pnpm strictDepBuilds/allowBuilds 需复核 |
+| 新工具 `dsh-tool-present` | 🟡 中低 | 新工具进入 agent 运行时，需确认与现有工具/插件无 id 冲突 |
+| Sidebar/dockkit UI 重构 | 🟢 低（功能面） | 纯增量 UI，但 better-dsh 的 mobile 手势/侧栏 patch 需复测是否仍对齐 |
+| Electron 桌面 | ⚪ 无关 | 不影响 web 部署 |
+
+---
+
+## 六、建议
+
+1. 本次**只做对账、不做升级**：0.1.5 是聚合大版本，且含 Session V3 破坏性契约变更，不能当「换版本号」处理。
+2. 若后续要升级，按 AGENTS.md §一/§二走 **Dev/Test 1（4999 源码级）对齐轮**：切 `dsh-v0.1.5-rc.2` → 重放三处本地 patch（storeDir / unrun devDep / resolveRepositoryRoot）→ install/build → 插件契约对齐（重点 `session-persistence-omp.ts`/`replay.ts`/store 的 V3 handle+lease）→ tsc/单测 → 4999 第一人称实测 → 报告落 `docs/50_test-reports/` → user 确认 → 才动 prod 3080。
+3. 升级目标版本**首选 `0.1.5-rc.2`（`next`）而非 `latest`（rc.1）**，因为 rc.2 才是最高版本；但 rc 阶段仍建议等上游正式 stable 后再定。
+4. 升级前单独确认模型默认值（V41 Flash）是否要在 prod 生效。