better-dsh 0.2.3 → 0.2.4

package/docs/specs/lsp/spec.md

@@ -0,0 +1,121 @@
+# lsp Specification
+
+## Purpose
+`lsp` 是**双模**语言服务能力：passive push 模（插件订阅 dsh 文件事件流，替 agent 向 per-session LSP server 子进程做 `didOpen/didChange/didSave` 文本同步，缓存 server 推回的 `publishDiagnostics`）+ proactive tool 模（agent 经 `dvc://lsp` 主动要 `diagnostics`/`format`/`definition` 等）。工作单位 = agent session（cwd 即 workspace root 候选）；**每 session 每语言一个 server 子进程**，不跨 session 共享。生命周期三级供给，类比 repl kernel：host start 零重物、session-start 登记零子进程、首用 lazy spawn。
+
+## Requirements
+
+### Requirement: Root-marker probing (lspMarker)
+Server availability and project-root determination SHALL follow the per-language marker table（`pyrightconfig.json`/`pyproject.toml`、`tsconfig.json`/`jsconfig.json`、`Cargo.toml`、`go.mod` …配置驱动，不发明 `lsp.json`）——编辑器侧工程惯例，非 LSP 协议标准。Marker 缺席不阻断：server 仍可 spawn，root 退化为 mutation 文件所在目录。
+
+#### Scenario: Marker present
+- **WHEN** a session's cwd contains a language marker file and the language's server is locally available
+- **THEN** the manager resolves project root to the marker's directory and reports availability for that language
+
+#### Scenario: Marker absent
+- **WHEN** no marker exists for the mutated file's language
+- **THEN** availability is `unknown`, not `unavailable` — the gate below still offers opt-in
+
+### Requirement: Gated notice with explicit per-session opt-in (on/off)
+The manager at session start SHALL check local availability of each language server in its table（Python/TypeScript 为必备，缺失即安装；Rust/Go 保留 nag 检测，server 缺失时按需安装）. When a session performs file mutations (edit/write 落盘) in a language with availability `available` or `unknown` and the session gate is `unasked`, the tool result MAY append the availability notice (lsp 可用，`dvc://lsp` 开/关) **at most 10 times per session**（防刷屏上限）. Both `on` and `off` are PER-SESSION state — the manager handles everything, and SHALL write NO repo artifact or marker file in either direction（无 `.dashr/lsp.json`，无任何落盘偏好）.
+
+#### Scenario: Mutation nag capped
+- **WHEN** the agent edits `.py` files repeatedly in a session with gate `unasked`
+- **THEN** at most 10 tool results carry the notice; afterwards mutations stay silent until the gate is decided
+
+#### Scenario: Explicit on (per session)
+- **WHEN** the agent sets `dvc://lsp` on
+- **THEN** the session gate becomes `on` and the manager warm-starts the language server; nothing is written to the repo
+
+#### Scenario: Explicit off (per session)
+- **WHEN** the agent sets `dvc://lsp` off
+- **THEN** the gate becomes `off`, no server spawns, the notice is muted for the session, and no repo marker is written
+
+### Requirement: Must-have servers installed, niche on demand
+At session start the manager SHALL verify Python and TypeScript servers and INSTALL a missing one (pip/npm, pinned, fail-soft — 安装失败降级为该语言 `unavailable`)；Rust/Go servers SHALL NOT be installed proactively — they stay in the nag-detection table and install only when the agent turns lsp on for that language.
+
+#### Scenario: Missing pyright on a fresh host
+- **WHEN** a session starts and no Python language server is installed
+- **THEN** the manager installs it in the background and reports availability `available` once done（安装期间 `unknown`，nag 照常）
+
+#### Scenario: Rust opted in on demand
+- **WHEN** the agent sets lsp on in a session touching Rust files and rust-analyzer is absent
+- **THEN** the manager installs rust-analyzer then spawns it — never before the opt-in
+
+### Requirement: Lazy spawn, session lifetime
+Server subprocesses SHALL spawn lazily on first post-on use, one subprocess per (session, language), registered under the agent's own tool effect so agent dispose unwinds them via `shutdown`+`exit`; an idle timeout reclaims servers of still-live sessions.
+
+#### Scenario: Per-session isolation
+- **WHEN** two sessions work in different cwd/repo simultaneously
+- **THEN** each owns independent server subprocesses with its own workspace root and document mirrors
+
+### Requirement: Text synchronization is post-hoc, never intercepting
+The plugin SHALL feed document sync (`didOpen`/`didChange` full-text + `didSave`) from AFTER-THE-FACT dsh events only — `tools/post-execute` on successful read/edit/write, mirroring the exact landed content（EXACT content, didSave freshness, span guard）— and SHALL NOT intercept, wrap, or delay any dsh read/write/edit flow. The version ledger follows the host fs observation policy's read-before-edit accounts; no second version book is kept.
+
+#### Scenario: Landed content is the mirror
+- **WHEN** an edit lands and lsp is on for that language
+- **THEN** the server receives a full-text `didChange` + `didSave` with the exact written content before diagnostics are requested, so line numbers match what the model just wrote
+
+### Requirement: Dual-mode results
+Proactive mode (`dvc://lsp` write: `diagnostics`/`format`/`definition`/…) and passive mode (cached `publishDiagnostics` attached to tool results, e.g. hashline edit 的 post-edit summary，经注入回调而非模块内依赖) SHALL both be served from the same session manager. Every failure — no server, gate off, cold-start noise — SHALL read as "no feedback": a serverless mutation is byte-identical to stock behavior.
+
+#### Scenario: Diagnostics ride the edit result
+- **WHEN** lsp is on, an edit lands, and the server answers diagnostics
+- **THEN** the edit's tool result carries the diagnostics summary; when the server is absent or slow, the result is unchanged
+
+### Requirement: Spin-up latency is absorbed, never blocking
+Server cold-start（spawn + `initialize` + 首轮索引）SHALL be handled by three means: (1) **warm-start at opt-in** — gate on 即后台 spawn，不等首个请求; (2) **fire-and-attach** — diagnostics 请求带超时，超时/未就绪读作"no feedback"，server 稍后推回的 `publishDiagnostics` 缓存并附到**下一个** mutation 的 tool result（延迟附挂，不丢不阻塞）; (3) **read 预热** — session 内首个某语言文件 read 即提前 `didOpen`，使首个 edit 命中已初始化的 server. The mutation path SHALL NEVER wait on server readiness — worst case is a summary arriving one tool call late.
+
+#### Scenario: First edit on a cold server
+- **WHEN** the gate turns on and the very next mutation hits an uninitialized server
+- **THEN** the edit result carries no diagnostics (no feedback), and when the server finishes indexing the diagnostics attach to the next mutation's result
+
+#### Scenario: Read pre-warms
+- **WHEN** the agent reads a `.ts` file before editing it and lsp gate is on for TypeScript
+- **THEN** the read triggers `didOpen` and server initialization, so the subsequent edit usually gets same-call diagnostics
+
+### Requirement: Orthogonality and injection boundaries
+The lsp capability SHALL be a self-contained module: no url-schemes/hashline imports; per-feature attachments (edit-result diagnostics, availability notices) arrive as injected callbacks from composition roots. Host start SHALL NOT probe markers or spawn processes — all discovery is per-session, on demand.
+
+#### Scenario: Host boot cost
+- **WHEN** the host starts with the lsp capability mounted
+- **THEN** no subprocess spawns, no marker probing runs, and nothing on the boot path can fail because of lsp
+
+## Surface syntax (`dvc://lsp`)
+
+The dvc contract is uniform: **bare read = roster, `<device>` read = doc/status, `<device>` write = action dispatch**. Gate state is per-session — the write dispatcher injects the calling agent's session id automatically; agents never type it.
+
+Read-vs-write follows GET/PUT semantics — **reads never mutate, writes always do**:
+
+- `read dvc://lsp` — the device doc: actions, args, current contract.
+- `read dvc://lsp/status` — the calling session's gate (session injected from the read env; no session → an explicit pointer note).
+- `read dvc://lsp/diagnostics?file=<path>&all=1` — fan-out query (read-only; spawning a lazily-managed server is the side effect of asking, not a mutation).
+- `read dvc://lsp/definition?file=&line=&character=|&symbol=` (also `references`, `hover`) — position queries, 1-based.
+- `write dvc://lsp` `{"action":"on"}` / `{"action":"off"}` — per-session gate decision; ack describes the effect. No repo artifact in either direction.
+- `write dvc://lsp` `{"action":"reload"}` — restart the server (config re-read).
+- `write dvc://lsp` `{"action":"rename",...}` / `{"action":"code_actions",...,"apply":N}` / `{"action":"format","file":...}` — workspace-mutating operations.
+
+The write surface retains `status` for symmetry with the session-injected dispatcher, but the read form is canonical for all queries. Path-mutation forms (`dvc://lsp/on`) are NOT part of the contract: mutation never rides a read URL.
+
+### Requirement: Session transport is out-of-band
+The per-session gate addressing SHALL ride the dvc write dispatcher's `execute(args, { session })` context — NOT the args payload — so devices with strict argument validators (browser) are unaffected; the lsp device reads `ctx.session` with a legacy in-args fallback for direct callers. The read surface receives the calling session through the resolver env the same way (`dvc://lsp/status` returns the calling session's gate).
+
+#### Scenario: Strict-validator device unaffected
+- **WHEN** the model writes `dvc://browser` with `{"action":"open","url":…}` from a session
+- **THEN** the browser device's validator sees only its declared fields and the action executes (the session rides the dispatcher's out-of-band ctx)
+
+#### Scenario: Status read is session-aware
+- **WHEN** the model turns lsp on and then reads `dvc://lsp/status` from the same session
+- **THEN** the status reports that session's gate (`"gate":"on"`)
+
+## OMP parity progress
+
+The device vendored a trimmed upstream oh-my-pi (`packages/coding-agent/src/lsp`) surface; parity is being completed in stages, each keeping the module boundary (nothing imports hash-edit/ast/url-schemes internals):
+
+1. ✅ `rename` / `code_actions` / `reload` actions (apply/preview WorkspaceEdit over `changes` + `documentChanges`; code action apply by index; reload = shutdown + evict).
+2. ✅ Workspace-wide diagnostics (`{"action":"diagnostics","file":"*"}` — aggregate cached publishDiagnostics across all live servers, per-file E/W counts) + `documentDiagnostic` pull for servers advertising `diagnosticProvider` (pull wins over last push on the saved path).
+3. ✅ Per-file fan-out: `{"action":"diagnostics","file":...,"all":true}` queries every registered server covering the file and merges results tagged per server (single-coverage falls through to the primary path).
+4. ✅ `symbol` / `symbol#N` position resolution on definition/references/rename/hover (word-bounded exact first, case-insensitive fallback, structured `LSP_SYMBOL_NOT_FOUND`; explicit `character` wins).
+5. ✅ Must-have installer: registry `installServer()` runs the package-manager command (npm/pip/go/rustup, 5 min timeout, fail-soft) for missing python/ts/js primaries once per session at first nag; niche languages stay install-on-opt-in.
+
+All five stages are in-tree; residual deltas vs upstream (lspmux, deferred-diagnostics ledger, writethrough editor integration) are IDE-side facilities without a dsh counterpart and are tracked as out of scope by the lsp spec's post-hoc sync ruling.

package/docs/specs/mobile-layout/spec.md

@@ -0,0 +1,108 @@
+# mobile-layout Specification
+
+## Purpose
+better-dsh 的移动端布局与输入契约：窄视口侧栏轨 0（注入 CSS 覆盖，桌面档零影响）、三条件滑动手势（边缘带 × 距离 × 速率，纯函数可测）、iOS focus 自动放大抑制 zoomGuard（browser=viewport meta token 改写 / standalone=16px 字号地板双形态，`'off'` 逃生门），全部随插件发布、config 门控（`mobile.enabled` / `mobile.breakpoint` / `mobile.zoomGuard`）。
+
+## Requirements
+
+### Requirement: iOS focus auto-zoom suppression on narrow viewports
+
+The plugin's host half SHALL suppress the iOS Safari focus-triggered auto-zoom with **display-mode-dependent behavior**:
+
+- **Browser context** (not standalone): rewrite the page's viewport meta (appending `maximum-scale=1` and `user-scalable=no`) inside the injected head boot script — before any application bundle can focus an input — with the v0.2.4 machinery (double gate iOS-class UA AND narrow viewport, breakpoint re-evaluation, provisional/reconcile single-meta invariant, early-load re-evaluation ladder, idempotent merge, byte-level restore). Real-device datum (2026-09-03): in-browser iOS Safari ignores `user-scalable=no` for pinch, so pinch zoom remains available in this mode.
+- **Standalone context** (`(display-mode: standalone)` media query matches OR `navigator.standalone === true`): the plugin SHALL NOT touch the viewport meta at all (no rewrite, no provisional, no listeners, no timers — real-device datum: standalone iOS honors `user-scalable=no` and pinch would break), and SHALL instead inject a static style element (`id="ios-zoom-font-floor"`, carrying the plugin's style-claim attributes) with `@media (max-width: {breakpoint-0.02}px){ input,textarea,select,[contenteditable="true"]{ font-size:16px !important } }`, which suppresses the focus auto-zoom by the font-size mechanism.
+
+Both branches SHALL be config-gated via `mobile.zoomGuard` (`'meta'` default = auto dual-mode behavior; `'off'` emits neither branch on any platform). Non-iOS browsers and wide viewports SHALL observe stock behavior in both display modes.
+
+#### Scenario: iOS narrow focus does not zoom
+
+- **WHEN** an input, select, checkbox, or contenteditable receives focus on an iOS-class browser below the breakpoint with `zoomGuard: 'meta'`
+- **THEN** no auto-zoom occurs in either display mode: browser mode suppresses it via the rewritten viewport meta, standalone mode via the 16px font-floor style
+
+#### Scenario: Rewrite lands before first possible focus
+
+- **WHEN** the head boot script executes during page load in browser (non-standalone) display mode
+- **THEN** the viewport meta rewrite is applied synchronously before any application bundle materializes, so no zoom flash can occur on an early auto-focus
+
+#### Scenario: Browser mode rewrites meta (unchanged from v0.2.4)
+
+- **WHEN** an iOS-class browser below the breakpoint loads in a non-standalone display mode with `zoomGuard: 'meta'`
+- **THEN** the viewport meta carries `maximum-scale=1, user-scalable=no` (single meta, idempotent, restorable) and no font-floor style is injected
+
+#### Scenario: Standalone mode never touches the viewport meta
+
+- **WHEN** an iOS-class browser below the breakpoint loads with display-mode standalone (matched via media query or `navigator.standalone`) and `zoomGuard: 'meta'`
+- **THEN** the viewport meta is byte-identical to stock, no provisional meta is created, no resize/MQ listeners or re-evaluation timers are armed, and the `ios-zoom-font-floor` style element is present with the 16px floor rules scoped to the configured breakpoint
+
+#### Scenario: Standalone pinch zoom is preserved
+
+- **WHEN** the user pinch-zooms in standalone display mode with the guard active
+- **THEN** the viewport meta contains no zoom-restricting tokens (pinch is engine-available; suppression relies solely on the font-size floor)
+
+#### Scenario: Font floor suppresses the focus zoom in standalone
+
+- **WHEN** an input, textarea, select, or `[contenteditable="true"]` element receives focus in standalone mode below the breakpoint
+- **THEN** its computed font-size is at least 16px and no auto-zoom occurs
+
+#### Scenario: Non-iOS touch browsers unaffected
+
+- **WHEN** the page loads on a non-iOS touch browser (e.g. Android Chrome) below the breakpoint, in either display mode
+- **THEN** the viewport meta is not rewritten and no font-floor style is injected (Android never focus-zooms; the iOS gate avoids `maximum-scale` side effects there)
+
+#### Scenario: Breakpoint crossing re-evaluates
+
+- **WHEN** the viewport crosses the breakpoint after load (rotation, split-screen) in browser display mode
+- **THEN** the rewrite is applied on entering the narrow band and the stock meta content is restored on leaving it; in standalone mode the font-floor style's media query naturally stops matching above the breakpoint (no JS re-evaluation exists there)
+
+#### Scenario: Desktop and wide viewports unaffected
+
+- **WHEN** the page loads on a desktop browser, a non-iOS browser, or at/above the breakpoint (either display mode)
+- **THEN** the viewport meta is stock and no font-floor style is injected (the floor's media query does not match above the breakpoint)
+
+#### Scenario: Config off restores stock behavior
+
+- **WHEN** `mobile.zoomGuard` is `'off'`
+- **THEN** neither the meta machinery nor the font-floor style exists in any display mode
+
+#### Scenario: Idempotent evaluation
+
+- **WHEN** the browser-mode re-evaluation runs multiple times within one state (load, resize storms, repeated crossings)
+- **THEN** the meta content does not accumulate duplicate tokens or regress (standalone mode arms no re-evaluation machinery at all)
+
+### Requirement: Sidebar occupies zero width on narrow viewports
+
+The plugin's client half SHALL hide the sidebar rail (zero-width column track) on narrow viewports via injected static CSS (media query + semantic attribute selectors, `!important` over the inline grid template), aligned with the upstream CSS-first layout paradigm and WITHOUT JavaScript geometry measurement; desktop-class rendering SHALL remain identical to the unpatched product, and the feature SHALL ship with the plugin, config-gated (`mobile.enabled`, default on).
+
+#### Scenario: Mobile viewport hides the rail
+
+- **WHEN** the page renders at a mobile-class viewport width below the configured breakpoint with the feature enabled
+- **THEN** the sidebar column track is zero width and the conversation area spans the frame
+
+#### Scenario: Desktop unaffected
+
+- **WHEN** the page renders at or above the breakpoint
+- **THEN** layout behavior is identical to the unpatched product
+
+#### Scenario: Degradation is benign
+
+- **WHEN** upstream DOM/attribute changes break the CSS override
+- **THEN** the layout falls back to the native rail rendering without errors or blank areas
+
+### Requirement: Three-condition swipe recognition
+
+Swipe recognition SHALL require all three of: gesture origin within the edge band, displacement at or above the distance threshold, and average velocity at or above the velocity threshold; slow press-drag gestures (text selection and similar) SHALL NOT trigger a swipe, and a recognized swipe SHALL toggle the sidebar via the layout service (`ctx.layout.toggleSidebar()`, narrow-viewport semantics), with the velocity/distance predicates implemented as pure functions under unit test.
+
+#### Scenario: Slow text-selection drag does not toggle
+
+- **WHEN** a pointer press-drag covers the distance threshold at sub-threshold velocity (e.g. selecting text to copy)
+- **THEN** no sidebar toggle occurs
+
+#### Scenario: Fast swipe toggles
+
+- **WHEN** a pointer gesture starts in the edge band, exceeds the distance threshold, and meets the velocity threshold
+- **THEN** the sidebar overlay state toggles (narrowExpanded flips)
+
+#### Scenario: Interactive-element origins are ignored
+
+- **WHEN** a gesture begins on an interactive element (link, button, input)
+- **THEN** no swipe recognition runs for that gesture

package/docs/specs/model-failover/spec.md

@@ -0,0 +1,20 @@
+# model-failover Specification
+
+## Purpose
+TBD - created by archiving change 2026-09-02-model-failover-settings-surface. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Model Failover surface in General settings
+
+The plugin SHALL register a Model Failover row into the Settings > General page via the `settings.general.item` slot, exposing the failover pair (primary/secondary model selectors) with persisted configuration, wherever the plugin's client bundle is built and loaded — including the source-level test instance — and the row SHALL remain functional across upstream settings-slot contract evolutions covered by the alignment process.
+
+#### Scenario: Row renders in the source-level test instance
+
+- **WHEN** the Dev/Test 1 instance starts with the plugin's client bundle built and the user opens Settings > General
+- **THEN** the Model Failover row with both model selectors is visible and its selections persist across instance restarts
+
+#### Scenario: Failover engages on primary failure
+
+- **WHEN** a turn's primary model request fails and a secondary model is configured in the row
+- **THEN** the host-side per-turn waterfall retries via the configured secondary and the outcome is observable in the session

package/docs/specs/preact-ui-shell/spec.md

@@ -0,0 +1,22 @@
+# preact-ui-shell Specification
+
+## Purpose
+为测试线（test-line）的 `apps/web` shell 提供构建期 React 家族到 `preact/compat` 的 vite alias patch：上游 ui-* 插件 bundle 的 `require("react")` 零改动获得 Preact 实例，shell 体积随之显著缩减。该 patch 仅限测试线 checkout，随 tag 切换重放；是否随插件包发布 dist 由 ship 决策另行裁决、暂缓。
+
+### Requirement: Preact-shell build for the web UI
+The test-line harness build SHALL support building the web shell (`apps/web`) with the React family aliased to `preact/compat` (including `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`, `react-dom/client` subpaths) via a build-time vite alias, so the platform module seed materializes Preact instances and every upstream client plugin bundle's `require("react")` receives Preact with zero upstream component edits. The alias SHALL be a monorepo-local build patch (documented, re-applied on tag switches), never an upstream source fork.
+
+#### Scenario: Shell serves the UI with Preact
+- **WHEN** the test-line instance is rebuilt with the alias patch and a browser loads the served UI
+- **THEN** the full upstream UI corpus mounts (sidebar/workspace/settings/chat), the session reports zero `pageerror` and zero `console.error`, and the shell bundle contains no `react-dom` production banner while carrying `preact` identity
+
+#### Scenario: Size regression is measured, not assumed
+- **WHEN** the alias build completes
+- **THEN** the shell `index` chunk (where the React family rides) is measured against the stock build and the delta recorded in the change report
+
+### Requirement: Test-line-only scope pending a ship decision
+The alias patch lives in the harness checkout only. The published plugin package (`@pgmi-builds/better-dsh`) SHALL NOT silently fork the web-UI serve surface: shipping a Preact-built frontend dist through the plugin (web-runtime override rows) is a separate decision gated on the prod host version upgrade, because a shipped dist freezes the UI corpus at the fork point.
+
+#### Scenario: Plugin publish content unchanged by this change
+- **WHEN** the next plugin alpha is published after this change
+- **THEN** the Preact enhancement is not part of the published artifact; the report records the ship-in-plugin option (dist + override rows) and its corpus-freeze trade-off as a pending decision tied to the prod host upgrade

package/docs/specs/repl-dispatch-resilience/spec.md

@@ -0,0 +1,21 @@
+# repl-dispatch-resilience Specification
+
+## Purpose
+REPL（`eval` cell）子分派的韧性契约：分派层的任何错误——调度器缺失、工具体抛错、取消——都必须 settle 为 cell 可见的 `ToolCallError` 结果，绝不外泄为 unhandled rejection 或使宿主进程崩溃。生产组合必须把带 `TOOL_RUNTIME_SCHEDULER` symbol 的原生 `ToolRuntime` 实例解析给插件，测试组合与生产组合之间不得存在环境差异导致的静默行为分裂。
+
+## Requirements
+
+### Requirement: Dispatch errors settle as visible ToolCallError
+The system SHALL resolve the plugin's tools service to the native `ToolRuntime` instance carrying the `TOOL_RUNTIME_SCHEDULER` symbol in the production composition, so REPL sub-dispatches execute through the same staged scheduler as the agent loop and return real tool results to the cell. The symbol this plugin imports SHALL be identical (`===`) to the one keying the mounted instance — a second dsh-tools module copy reachable from the deployed plugin (e.g. stray nested `@deepseek-ai` symlinks) breaks that identity and is a deployment defect (2026-09-02 corrected root cause; the plain `runtimeCtx.tools` read is the sanctioned resolution path). A mount whose tools service genuinely lacks the symbol SHALL be treated as a loud, diagnosable configuration failure — the error names the plugin's own `dsh-tools` resolution path — rather than a silent runtime crash, and that loud failure SHALL be the abnormal fallback, not the normal production state.
+
+#### Scenario: Production mount carries the scheduler symbol
+- **WHEN** the DASHR plugin mounts in the production composition and a cell dispatches a real tool call
+- **THEN** the dispatch executes through `registry[TOOL_RUNTIME_SCHEDULER]` and returns the tool result to the cell without crashing the daemon
+
+#### Scenario: Legitimate cell tool call returns its real result
+- **WHEN** a cell dispatches a legitimate tool call (e.g. `tool.read({ path })`) in a live session after the fix
+- **THEN** the cell receives the tool's actual result, not the `TOOL_RUNTIME_SCHEDULER` loud error
+
+#### Scenario: Regression probes pass after the fix
+- **WHEN** the four probe cells from the diagnosis matrix (`tool.subagent` background:false, `tool.subagent` background:true, `tool.bash` background:true, `tool.read`) run in a live session after the fix
+- **THEN** all four return a real result (or a visible `ToolCallError` where the call is legitimately invalid) instead of truncating, and the journal contains no new daemon crash

package/docs/specs/skill/spec.md

@@ -0,0 +1,58 @@
+# skill Specification
+
+## Purpose
+
+Let the model address skill bodies and internal skill resources via `skill://` URLs, with discovery tied to the same workspace source that advertises skills, and replace the skill tool's body-loading role on the REPL surface.
+
+## Requirements
+
+### Requirement: Skill body addressing
+The system SHALL let read accept `skill://<name>` and return that skill's SKILL.md body in full text (no default truncation; only explicit selectors page).
+
+#### Scenario: Reading an existing skill
+- **WHEN** the model reads `skill://<registered skill name>`
+- **THEN** the system returns the skill's body text in full
+
+#### Scenario: Reading an unknown skill
+- **WHEN** the model reads `skill://<unregistered name>`
+- **THEN** the system returns the structured `URL_SKILL_NOT_FOUND` error ("unknown or no longer available")
+
+### Requirement: Skill internal resource addressing
+The system SHALL let read accept `skill://<name>/<path>` and return the named file inside the skill's resource directory, loaded through the sandboxed filesystem (same containment/audit rules as host reads). A skill without a filesystem resource directory returns `URL_SKILL_NO_RESOURCE_BASE`; a subpath escaping the directory returns `URL_SKILL_RESOURCE_ESCAPE`.
+
+#### Scenario: Reading a referenced skill file
+- **WHEN** the model reads `skill://foo/references/x.md`
+- **THEN** the system returns the content of `references/x.md` inside foo's resource directory
+
+#### Scenario: Resource path escapes the skill directory
+- **WHEN** the model reads `skill://foo/../../etc/passwd`
+- **THEN** the system returns the structured `URL_SKILL_RESOURCE_ESCAPE` error and reads nothing
+
+### Requirement: Workspace-cwd-sensitive discovery
+The system SHALL pass the calling agent's session cwd (`{cwd: agent.session.header.cwd}`) to every skill-registry lookup — the same source `dsh-tool-skill` uses to render `<available_skills>` — so `skill://` can address exactly the skills the catalog advertises for the current workspace.
+
+#### Scenario: Skill visible in the current workspace
+- **WHEN** the model reads `skill://foo` from a session whose cwd is inside a project root that provides foo
+- **THEN** the lookup succeeds and the body resolves
+
+#### Scenario: Skill outside the workspace is unknown
+- **WHEN** a skill's project roots do not cover the session cwd
+- **THEN** the lookup misses and the system returns `URL_SKILL_NOT_FOUND`, matching what `<available_skills>` advertised
+
+### Requirement: Path-backed search view
+The system SHALL expose the handler's `resolvePath`: `skill://<name>` maps to the skill's resource-directory root and `skill://<name>/<subpath>` to the joined file (same escape guard), letting grep/glob search the real files; unmappable URLs (unknown skill, non-directory resource base, escaping subpath) resolve to `undefined` so callers fall back to text resolution with its structured error.
+
+#### Scenario: grep searches the skill's real directory
+- **WHEN** the model greps a `skill://foo` URL
+- **THEN** the search runs natively over foo's on-disk resource directory
+
+### Requirement: Skill tool masked on the REPL surface only
+The system SHALL mask the upstream `skill` tool presentation-only (ADR-0002): it disappears from the REPL `tool.*` binding names and the dashr tool-catalog section, while the host-layer native `skill` tool stays registered and executable and the `<available_skills>` discovery catalog is retained.
+
+#### Scenario: Skill absent from the REPL surface
+- **WHEN** the model inspects the kernel tool bindings or the tool-catalog text
+- **THEN** neither contains `skill`, and `skill://` URLs remain the addressing path for skill content
+
+#### Scenario: Host-native skill tool survives
+- **WHEN** any host-plane consumer dispatches the native `skill` tool directly
+- **THEN** the tool remains registered and executable — the mask touched only presentation surfaces

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