better-dsh 0.2.3-e → 0.2.3-g

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/dsh-docs/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
+## Writing rules
+
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
+- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
+
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
+- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Cross-reference with machine-checkable links, never free prose
+
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).

package/dsh-docs/agent-lifecycle.md

@@ -0,0 +1,84 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  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->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected 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->>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
+  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
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+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.
+
+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.
+
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.