dsh-engramory 0.2.5 → 0.2.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Beijing Tinqiao Technology Co., Ltd.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Beijing Tinqiao Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,134 +1,154 @@
-[English](README.md) | [简体中文](README.zh-CN.md)
-
-# dsh-engramory
-
-[![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
-
-<sub>`C2` is the level `manifest.bundle.patch` puts every mountable dsh plugin at (74.6% of the scanned ecosystem); it is the only flag on this card — no `exec`, `eval`, install script, outbound domain, or environment read.</sub>
-
-Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
-plain markdown notes you can open with anything, one store shared across every host you
-use, and an index cap that is a **real refusal** rather than a request. (If the store
-lives inside a project's git repo it must be git-ignored — memories carry machine-local
-detail; see SKILL.md §1. A *dedicated private* repo for the store itself is fine.)
-
-Part of [Engramory](https://github.com/tinqiao-oss/engramory).
-
-## Why a plugin, when an `AGENTS.md` block already works
-
-The block does carry the discipline, and for recall that is enough. Two things it cannot
-do:
-
-**The cap becomes deterministic.** Engramory keeps its index under 200 lines / 25 KB
-because the index loads every session and everything past the cap silently stops being
-recalled. On most hosts that limit is rules plus a checker the agent has to remember to
-run. dsh exposes `ctx.tools.guard()` — a synchronous, **monotonic** refusal: once a guard
-returns a reason, no later listener can turn it back into an allow. So here the limit is
-enforced, not requested. Use **0.2.1 or later**: 0.2.0 shipped before profile installs
-worked upstream and carried an `inject` declaration this Cordis does not accept — it
-installed but never activated (issue #8). Outside Claude Code, dsh is the first host with
-the shim actually written (a few others expose equivalent pre-write seams — see
-PORTING.md — but have no shim yet).
-
-**The protocol arrives with the plugin.** The skill is registered at runtime through
-dsh's skill registry — via a reactive `ctx.inject(['skills'], …)` child, so a profile
-without a registry still gets the cap and one whose registry activates late still gets
-the skill — which means it does not depend on landing files in one of the five skill
-roots dsh scans, a path that is easy to get subtly wrong and fails silently when you do.
-
-## Install
-
-```sh
-dsh plugin --profile <name> add dsh-engramory
-```
-
-That is the whole install. The package ships a `dsh.bundle` manifest pointing at its own
-`cordis.patch.yml`, so the row is inserted into the profile's plugin tree for you — no
-hand-editing. To change a default, patch the EXISTING row by id in your profile's own
-patch layer — do **not** use a second `- insert:` (insert always appends, so you would
-end up with two engramory rows and the original caps still enforced):
-
-```yaml
-- id: engramory
-  config:
-    indexName: MEMORY.md
-    maxLines: 200
-    maxBytes: 25600
-```
-
-A patch replaces the targeted row's whole `config`, so list every key you mean to keep.
-
-For the store itself and the always-on block, use the installer in the Engramory repo
-(`python tools/engramory_init.py dsh --install-skill`). This plugin enforces the cap and
-supplies the protocol; it does not create the store.
-
-## Configuration
-
-| Field | Default | Meaning |
-|---|---|---|
-| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked). An empty or non-string value falls back to the default. Nothing else is inspected. |
-| `maxLines` | `200` | Hard line cap. Non-positive or non-finite values fall back to the default. |
-| `maxBytes` | `25600` | Hard UTF-8 byte cap (25 KB). |
-| `indexPath` | unset | Absolute path of the ONE index to guard. Without it the guard matches on basename alone, so an unrelated `MEMORY.md` in another project is gated too; set this and only that exact file is. Compared by identity (symlinks and `..` resolved; case-folded on Windows only), and a path that does not exist yet still has its first write guarded. |
-| `registerSkill` | `true` | Set `false` to keep the cap but skip the runtime skill. |
-| `skill` | built-in | Replace the skill body with your own markdown. |
-
-## What the guard actually does
-
-| Call | Decision |
-|---|---|
-| `write` (or `str_replace_editor` `create`) ending within caps | allow |
-| `write`/`create` that GROWS the index past a cap | **deny**, naming the numbers and what to compact |
-| `write`/`create` that SHRINKS or keeps an over-cap index | allow — incremental compaction (210 → 205 → 198) must stay possible |
-| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write |
-| Unsimulable partial (e.g. `insert`) on an over-cap index | **deny**, telling the agent a shrinking whole-file write passes |
-| Unsimulable partial on a healthy index | allow |
-| `read`, `view`, or any unknown tool | allow — recall must never be blocked, even over cap |
-| Any write to any other file | allow — not the guard's business |
-| Missing/unreadable current index on a whole-file write | treated as EMPTY (mirrors the Python guard) — a within-caps write passes, an over-cap first write is refused |
-| Missing/unreadable index on a partial edit | allow — a guard must never block work over a path it cannot read |
-| Malformed execution (no arguments, non-string path/content) | allow — not recognisably a write |
-
-The deny rule mirrors `hooks/engramory_index_guard.py` exactly: refuse only a result
-that is over a cap AND grew past the current file. The line count ignores a trailing
-newline, so an index sitting exactly at the cap stays writable.
-
-## Known limits
-
-- **An unsimulable partial that crosses the cap from under it is not caught.** `insert`
-  and friends do not carry the resulting text. The breach is caught by the next
-  whole-file write, or by `engramory_check.py`. What is guaranteed: an already-over
-  index cannot be grown further, and a shrinking write always passes.
-- **The tool roster follows dsh's documented tool-fs contract** (`write`/`edit` with
-  `file_path`, `str_replace_editor` with `path`) and is deliberately conservative:
-  unknown tools pass.
-- **0.2.0 never activated; 0.2.1 is the first version that runs.** While the rc.6
-  preview bug blocked all third-party profile installs upstream, the only coverage a
-  plugin could have was mocks — and 0.2.0's mock hid two activation bugs: an
-  older-Cordis `{ required, optional }` inject shape (read as waiting for services
-  literally named `required`/`optional`, pending forever) and a bare `ctx.skills` read
-  of an undeclared service (throws under Cordis' reflective context). The first field
-  install caught both the moment installs became possible (issue #8). 0.2.1 fixes them,
-  verified end to end on a live dsh 0.1.0-rc.7 web profile (0.2.0 reproduces the boot
-  failure byte for byte; 0.2.1 boots and serves) and against the vendored
-  `@deepseek-ai/cordis` resolver (activation with, without, and with a late-mounted
-  skill registry). The test mock now mirrors the reflective-context access rules, and
-  the guard's decision table stays covered by `node --test` (28 cases, run in
-  Engramory's CI).
-- **Checked against the dsh you are likely running, not only the one it was written
-  on.** `tests/dsh_e2e/run.py` in the Engramory repo installs a dsh release into a
-  throwaway prefix, adds this plugin with `dsh plugin add`, and drives one headless
-  task against a scripted stand-in for the DeepSeek API: a 260-line write and an edit
-  past the cap must come back refused by this guard with nothing reaching the disk, a
-  small write must land byte for byte, the skill must be advertised, every tool dsh
-  offers must already be classified (a new one could write past the cap), and removal
-  must leave a profile that still boots. The releases it passed on are listed in
-  `package.json` under `dsh.compatibility.dshReleases`; a unit test rejects a
-  `compatible` there without a recorded run of the same plugin version and code.
-- dsh is a developer preview and its plugin API can change. This plugin deliberately
-  touches only `ctx.tools.guard()` and a reactive `ctx.inject(['skills'], …)` child
-  that registers the skill, so it stays cheap to fix.
-
-## License
-
-MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# dsh-engramory
+
+[![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
+
+<sub>`C2` is the level `manifest.bundle.patch` puts every mountable dsh plugin at (74.6% of the scanned ecosystem); it is the only flag on this card — no `exec`, `eval`, install script, outbound domain, or environment read.</sub>
+
+Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
+plain markdown notes you can open with anything, one store shared across every host you
+use, and an index cap that is a **real refusal** rather than a request. (If the store
+lives inside a project's git repo it must be git-ignored — memories carry machine-local
+detail; see SKILL.md §1. A *dedicated private* repo for the store itself is fine.)
+
+Part of [Engramory](https://github.com/tinqiao-oss/engramory).
+
+## Why a plugin, when an `AGENTS.md` block already works
+
+The block does carry the discipline, and for recall that is enough. Two things it cannot
+do:
+
+**The cap becomes deterministic.** Engramory keeps its index under 200 lines / 25 KB
+because the index loads every session and everything past the cap silently stops being
+recalled. On most hosts that limit is rules plus a checker the agent has to remember to
+run. dsh exposes `ctx.tools.guard()` — a synchronous, **monotonic** refusal: once a guard
+returns a reason, no later listener can turn it back into an allow. So here the limit is
+enforced, not requested. Use **0.2.7 or later**: 0.2.0 shipped before profile installs
+worked upstream and carried an `inject` declaration this Cordis does not accept — it
+installed but never activated (issue #8) — and up to 0.2.5 an edit could slip past the
+cap on a CRLF index, or on dsh 0.2 through a relative path after a cd, and up to 0.2.6
+through a symlink under another name — or a FIFO named like the index could hang the host
+(#20, #21; see Known limits). Outside Claude Code, dsh is the first host with
+the shim actually written (a few others expose equivalent pre-write seams — see
+PORTING.md — but have no shim yet).
+
+**The protocol arrives with the plugin.** The skill is registered at runtime through
+dsh's skill registry — via a reactive `ctx.inject(['skills'], …)` child, so a profile
+without a registry still gets the cap and one whose registry activates late still gets
+the skill — which means it does not depend on landing files in one of the five skill
+roots dsh scans, a path that is easy to get subtly wrong and fails silently when you do.
+
+## Install
+
+```sh
+dsh plugin --profile <name> add dsh-engramory
+```
+
+That is the whole install. The package ships a `dsh.bundle` manifest pointing at its own
+`cordis.patch.yml`, so the row is inserted into the profile's plugin tree for you — no
+hand-editing. To change a default, patch the EXISTING row by id in your profile's own
+patch layer — do **not** use a second `- insert:` (insert always appends, so you would
+end up with two engramory rows and the original caps still enforced):
+
+```yaml
+- id: engramory
+  config:
+    indexName: MEMORY.md
+    maxLines: 200
+    maxBytes: 25600
+```
+
+A patch replaces the targeted row's whole `config`, so list every key you mean to keep.
+
+For the store itself and the always-on block, use the installer in the Engramory repo
+(`python tools/engramory_init.py dsh --install-skill`). This plugin enforces the cap and
+supplies the protocol; it does not create the store.
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked) — the name a write is called by, or the name of the file it lands on, so a symlink under another name is caught too. An empty or non-string value falls back to the default. |
+| `maxLines` | `200` | Hard line cap. Non-positive or non-finite values fall back to the default. |
+| `maxBytes` | `25600` | Hard UTF-8 byte cap (25 KB). |
+| `indexPath` | unset | Absolute path of the ONE index to guard. Without it the guard matches on basename alone, so an unrelated `MEMORY.md` in another project is gated too; set this and only that exact file is. Compared by identity — the file the write lands on, whatever it is called (symlinks and `..` resolved; case-folded on Windows only) — and a path that does not exist yet still has its first write guarded. |
+| `registerSkill` | `true` | Set `false` to keep the cap but skip the runtime skill. |
+| `skill` | built-in | Replace the skill body with your own markdown. |
+
+## What the guard actually does
+
+| Call | Decision |
+|---|---|
+| `write` (or `str_replace_editor` `create`) ending within caps | allow |
+| `write`/`create` that GROWS the index past a cap | **deny**, naming the numbers and what to compact |
+| `write`/`create` that SHRINKS or keeps an over-cap index | allow — incremental compaction (210 → 205 → 198) must stay possible |
+| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write — sized before it is built, so a `replace_all` whose result would be too long to build is refused by its size alone |
+| Unsimulable partial (e.g. `insert`) on an over-cap index | **deny**, telling the agent a shrinking whole-file write passes |
+| Unsimulable partial on a healthy index | allow |
+| `read`, `view`, or any unknown tool | allow — recall must never be blocked, even over cap |
+| Any write to any other file | allow — not the guard's business |
+| Missing/unreadable current index on a whole-file write | treated as EMPTY (mirrors the Python guard) — a within-caps write passes, an over-cap first write is refused |
+| Missing/unreadable index on a partial edit | allow — a guard must never block work over a path it cannot read |
+| A FIFO, device, or directory under the index's name | never read — counts as unreadable (a read there would hang or flood the host, which runs guards on its main thread) |
+| An index past the read limit (1 MiB, or 4× `maxBytes`, at most 16 MiB) | not read whole: a whole-file write is judged on bytes against the filesystem's size (every shrink passes; its line count is unknown, so lines are not capped there), and an edit passes unmeasured, as on an unreadable index |
+| Malformed execution (no arguments, non-string path/content) | allow — not recognisably a write |
+
+The deny rule mirrors `hooks/engramory_index_guard.py` exactly: refuse only a result
+that is over a cap AND grew past the current file. The line count ignores a trailing
+newline, so an index sitting exactly at the cap stays writable.
+
+## Known limits
+
+- **An unsimulable partial that crosses the cap from under it is not caught.** `insert`
+  and friends do not carry the resulting text. The breach is caught by the next
+  whole-file write, or by `engramory_check.py`. What is guaranteed: an already-over
+  index cannot be grown further, and a shrinking write always passes.
+- **The tool roster follows dsh's documented tool-fs contract** (`write`/`edit` with
+  `file_path`, `str_replace_editor` with `path`) and is deliberately conservative:
+  unknown tools pass.
+- **0.2.0 never activated; 0.2.1 is the first version that runs.** While the rc.6
+  preview bug blocked all third-party profile installs upstream, the only coverage a
+  plugin could have was mocks — and 0.2.0's mock hid two activation bugs: an
+  older-Cordis `{ required, optional }` inject shape (read as waiting for services
+  literally named `required`/`optional`, pending forever) and a bare `ctx.skills` read
+  of an undeclared service (throws under Cordis' reflective context). The first field
+  install caught both the moment installs became possible (issue #8). 0.2.1 fixes them,
+  verified end to end on a live dsh 0.1.0-rc.7 web profile (0.2.0 reproduces the boot
+  failure byte for byte; 0.2.1 boots and serves) and against the vendored
+  `@deepseek-ai/cordis` resolver (activation with, without, and with a late-mounted
+  skill registry). The test mock now mirrors the reflective-context access rules, and
+  the guard's decision table stays covered by `node --test` (47 cases, run in
+  Engramory's CI).
+- **A relative path is measured where dsh writes it.** dsh 0.2 gives every session its
+  own working directory (moved by its `working_directory` tool) and resolves a
+  relative `file_path` against that. Up to 0.2.5 the guard resolved against the
+  process's cwd instead, so after a cd an edit of a bare `MEMORY.md` read no current
+  file and went through unmeasured — on dsh 0.2.1-rc.2 it grew the index to 253
+  lines. 0.2.6 reads the session's directory from dsh's `workingDirectory` service
+  when the profile has one, and falls back to the process's cwd when it does not
+  (every 0.1.x release).
+- **A CRLF index is edited the way dsh edits it.** dsh matches an edit on
+  LF-normalised text and writes the result back in the file's own line endings. Up
+  to 0.2.5 the guard matched the raw bytes, so on a CRLF `MEMORY.md` — the usual
+  shape on Windows — an LF `old_string` looked absent, the edit was predicted to
+  change nothing, and dsh applied it. 0.2.6 normalises the same way and sizes a CRLF
+  index in CRLF bytes.
+- **Checked against the dsh you are likely running, not only the one it was written
+  on.** `tests/dsh_e2e/run.py` in the Engramory repo installs a dsh release into a
+  throwaway prefix, adds this plugin with `dsh plugin add`, and drives one headless
+  task against a scripted stand-in for the DeepSeek API: a 260-line write and an edit
+  past the cap must come back refused by this guard with nothing reaching the disk, a
+  small write must land byte for byte, the skill must be advertised, every tool dsh
+  offers must already be classified (a new one could write past the cap), and removal
+  must leave a profile that still boots. The releases it passed on are listed in
+  `package.json` under `dsh.compatibility.dshReleases`; a unit test rejects a
+  `compatible` there without a recorded run of the same plugin version and code.
+- dsh is a developer preview and its plugin API can change. This plugin deliberately
+  touches only `ctx.tools.guard()` and two reactive `ctx.inject()` children — one
+  registers the skill, one reads each session's working directory — so it stays cheap
+  to fix.
+
+## License
+
+MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).