From 87899ae16129946b4825b658e11b1ef7fb3168cd Mon Sep 17 00:00:00 2001 From: Turtle Date: Wed, 22 Jul 2026 10:55:19 +0800 Subject: [PATCH] feat(workspace-context): load all instruction candidates, dedup by trimmed content, follow symlinks Squashes feat/instruction-load-all-dedup and feat/allow-instruction-symlink. --- .../feature/2026-06-24-workspace-context.md | 6 +- ...7-21-follow-instruction-symlinks.i18n.yaml | 6 + .../2026-07-21-follow-instruction-symlinks.md | 31 ++ ...26-07-21-follow-instruction-symlinks.zh.md | 31 ++ ...07-21-instruction-load-all-dedup.i18n.yaml | 6 + .../2026-07-21-instruction-load-all-dedup.md | 37 ++ ...026-07-21-instruction-load-all-dedup.zh.md | 37 ++ ...-07-21-local-instruction-overlay.i18n.yaml | 4 +- .../2026-07-21-local-instruction-overlay.md | 10 +- ...2026-07-21-local-instruction-overlay.zh.md | 10 +- .../workspace/AGENTS.canonical.md | 1 + .../workspace-context/workspace/AGENTS.md | 2 +- .../workspace/nested/AGENTS.canonical.md | 1 + .../workspace/nested/AGENTS.md | 2 +- packages/context/workspace-context/README.md | 20 +- .../context/workspace-context/src/config.ts | 10 +- .../context/workspace-context/src/digest.ts | 12 + .../context/workspace-context/src/files.ts | 171 +++---- .../context/workspace-context/src/render.ts | 72 +-- .../context/workspace-context/src/state.ts | 96 ++-- .../tests/workspace-context.spec.ts | 463 +++++++++++------- 21 files changed, 685 insertions(+), 343 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.md create mode 100644 .agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.zh.md create mode 100644 .agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.md create mode 100644 .agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.zh.md create mode 100644 examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.canonical.md mode change 100644 => 120000 examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md create mode 100644 examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.canonical.md mode change 100644 => 120000 examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md index 54767cf46d..3bcb0c2bea 100644 --- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md +++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md @@ -14,7 +14,7 @@ The lifecycle has two distinct classes of content. The initial applicable chain The implementation lives in `packages/context/workspace-context` as `@deepseek-ai/dsh-workspace-context`. It is a request-context extension, not a core service or a filesystem backend. `@deepseek-ai/dsh-agent-core` mounts it for both product front doors and forwards its config. The plugin consumes `agent/session-prefix`, `tools/post-execute`, and the optional `ctx.fs` capability. -The plugin does not statically inject `fs`. Providerless product trees therefore boot normally and the plugin no-ops until a filesystem provider exists. All production reads go through that provider. Candidate probes call `lstat` before `resolve`, so a repository-owned final-component symlink is rejected rather than followed outside the workspace. The session-prefix signal and dynamic tool execution signal propagate through resolution, metadata probes, and streaming reads, so cancellation does not wait for an unrelated filesystem scan. Once `lstat` identifies a regular-file winner, a provider exception or disagreement during resolve/stat is classified as unavailable: it is neither interpreted as a deletion nor allowed to fall through to a lower-priority candidate. +The plugin does not statically inject `fs`. Providerless product trees therefore boot normally and the plugin no-ops until a filesystem provider exists. All production reads go through that provider. Candidate probes resolve each path and stat the result, so a final-component symlink is followed to its target: a link to a regular file loads, while a missing path or a non-file target is a confirmed absence. Following repository-owned links across the trust boundary is a deliberate reversal of the original no-follow probe; the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns that decision and its residual risk. The session-prefix signal and dynamic tool execution signal propagate through resolution, metadata probes, and streaming reads, so cancellation does not wait for an unrelated filesystem scan. A resolve or stat exception is classified as unavailable: it skips only that candidate and is never interpreted as the deletion of an already-loaded scope. ### File Names And Precedence @@ -46,7 +46,7 @@ Shell commands are not discovery triggers. Local bash calls start fresh shells, ### Duplicate Suppression And Change Detection -Every dynamic workspace context event stores versioned metadata with `{ action, scope, path, previousPath?, digest? }`, where `digest` is SHA-1 over the loaded content. The model-facing prompt has no HTML comments, hidden markers, or headings that are parsed back into state. +Every dynamic workspace context event stores versioned metadata with `{ action, scope, path, digest? }`, where `digest` is SHA-1 over the loaded content. The model-facing prompt has no HTML comments, hidden markers, or headings that are parsed back into state. At reconciliation time the plugin scans plugin-owned `context/message` events and derives the latest state for each visible scope. A short per-session pending map begins only after the immutable top-level `tools/result` proves an `additionalContexts` entry survived every post-execute listener, then covers the interval before the loop appends that context to the log. Each entry records the open `{ turn, step }`: an equal durable `context/message` at or after its sequence boundary confirms and removes it, while a matching `step/end` arriving first means the loop discarded its context buffer, so the plugin removes both the pending entry and its version-cache fast path. A nested Code Mode result stages its changes under the parent's opaque execution token so repeated sub-dispatches in one run do not duplicate them; the parent result rolls that provisional state back and commits only contexts retained by outer policy. @@ -78,7 +78,7 @@ There is intentionally no watcher. Detection occurs at the next successful struc Workspace guidance is isolated per session and shared by both product front doors and every tool presentation mode. Initial instructions benefit from stable prefix caching, while nested and changed content remains durable and replayable. The generic session/agent context contract carries JSON metadata propagated through prompt-submit and post-tool `additionalContexts` arrays without flattening entries. -Repository text remains untrusted input. Lower-authority user-role framing, explicit precedence language, delimiter escaping, and symlink rejection reduce risk but do not eliminate prompt injection. Permission and sandbox layers treat workspace files as data rather than authority. +Repository text remains untrusted input. Lower-authority user-role framing, explicit precedence language, and delimiter escaping reduce risk but do not eliminate prompt injection. Following a candidate symlink to its target widens that surface to off-tree content, so the permission and sandbox layers that confine `ctx.fs` to trusted roots are the boundary that treats workspace files as data rather than authority (the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns the residual risk). The system is event-driven rather than watch-driven. Edits are not visible at the exact filesystem mutation instant unless that mutation goes through a structured tool; externally changed files are noticed on the next successful structured touch or resume. This keeps the design deterministic and provider-neutral. diff --git a/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.i18n.yaml new file mode 100644 index 0000000000..6d66a58813 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-21-follow-instruction-symlinks.md: 49b02c38fb49241f5941dc3431c43f031fb7193e +2026-07-21-follow-instruction-symlinks.zh.md: ba47325dde30cea899b2e038221f841bdfa2f1c6 diff --git a/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.md b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.md new file mode 100644 index 0000000000..49b02c38fb --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.md @@ -0,0 +1,31 @@ +# Agent Note: Follow symlinked instruction files + +Status: implemented + +English | [中文](2026-07-21-follow-instruction-symlinks.zh.md) + +## Problem + +The [workspace-context plugin](2026-06-24-workspace-context.md) probed each instruction candidate with `ctx.fs.lstat` before resolving, rejecting any final-component symlink so a repository-owned link could not point instruction loading at content outside the workspace. That no-follow invariant blocked a deliberate, supported setup: a user who symlinks `$DSH_HOME/AGENTS.md` — or a project `AGENTS.md` — to a canonical instruction file kept elsewhere, sharing one house-style file across tools and homes, saw the link silently ignored. It also forced content dedup to treat the ubiquitous `CLAUDE.md → AGENTS.md` mirror as a special skipped case rather than an ordinary duplicate. The repository owner asked to follow symlinked instruction files unconditionally across every scope, accepting the residual trust-boundary risk recorded below. + +## Decision + +Instruction discovery no longer inspects the final component with `lstat`. Every candidate — the user-global `$DSH_HOME/AGENTS.md`, each base candidate, and each local-overlay candidate — is resolved and its resolved target is stat-ed, at baseline composition and at each `tools/post-execute` reconciliation alike. A symlink whose target is a regular file loads that target's content; a resolved non-file target (including a link to a directory) is a confirmed absence that removes the scope like a missing file; a `resolve` or `stat` exception is classified as temporarily unavailable and never removes an already-loaded scope. `nodeStatFile` calls `stat` (host path) and `fsStatFile` calls `resolve` then `stat` (provider path); neither calls `lstat`. + +A followed symlink is an ordinary file for every downstream step. It participates in per-directory content dedup ([load-all + dedup note](2026-07-21-instruction-load-all-dedup.md)), so a `CLAUDE.md` that symlinks its sibling `AGENTS.md` now resolves to identical content and collapses like any byte-identical real duplicate instead of being skipped as a special case. + +### Trust boundary and residual risk + +Following repository-owned links crosses the plugin's trust boundary: a cloned, untrusted repository can carry an `AGENTS.md` whose symlink target is any file the process can read, surfacing off-tree content as workspace guidance. That content enters only as a lower-authority user-role prefix framed by the system-reminder pattern; it never overrides system, developer, or direct user instructions, and it is treated as data, not authority. The mitigating boundary is the filesystem layer, not this plugin: confine `ctx.fs` with the `dsh-fs-policy` gate or an OS sandbox ([cross-family fs sandbox](2026-07-14-cross-family-fs-sandbox.md)) when a deployment loads untrusted repositories. This is an explicit, owner-accepted trade-off, not an oversight. + +## Alternatives considered + +**Keep the `lstat` no-follow invariant.** Rejected by the repository owner: it blocks the supported symlink-to-canonical-file setup and forces the symlink-mirror case to be a skipped special case rather than a plain duplicate. The read-authority boundary it approximated belongs in the filesystem policy and sandbox layer, which contains the same risk more precisely. + +**Follow only the user-global `$DSH_HOME` candidate and keep no-follow for project files.** Rejected: the owner asked for uniform behavior across every scope, and a split rule is harder to reason about than one consistently applied policy plus a documented boundary. A project the user chose to open is not meaningfully more trusted than the user's own home. + +**Follow symlinks but reject targets that resolve outside the project root.** Rejected: it reintroduces a partial trust boundary in the wrong layer — path geometry rather than read authority — breaks the legitimate `$DSH_HOME`-to-elsewhere case, and duplicates containment the filesystem policy gate already owns. + +## Consequences + +A symlinked instruction file is now loaded and rendered like its target, enabling shared canonical instruction files across tools and homes, and the `CLAUDE.md → AGENTS.md` mirror deduplicates through content instead of being skipped. The plugin no longer depends on `ctx.fs.lstat` for instruction loading; a resolved non-file is a confirmed absence and only a provider exception is temporarily unavailable. The trust boundary moves out of this plugin into the filesystem policy and sandbox layers, which must confine `ctx.fs` when a deployment loads untrusted repositories. The [workspace-context note](2026-06-24-workspace-context.md) and the package README carry the same follow behavior and residual-risk statement. diff --git a/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.zh.md b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.zh.md new file mode 100644 index 0000000000..ba47325dde --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-follow-instruction-symlinks.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 跟随符号链接指向的指令文件 + +Status: implemented + +[English](2026-07-21-follow-instruction-symlinks.md) | 中文 + +## 问题 + +[workspace-context 插件](2026-06-24-workspace-context.md)在解析前用 `ctx.fs.lstat` 探测每个指令候选，拒绝任何末段的符号链接，从而使仓库自有的链接无法把指令加载指向工作区之外的内容。这条「不跟随」不变式挡住了一个有意为之、且受支持的配置：用户若把 `$DSH_HOME/AGENTS.md`（或某个项目的 `AGENTS.md`）符号链接到别处保存的一个规范指令文件，以便在多个工具与多个 home 之间共享同一份规范文件，就会看到该链接被悄悄忽略。它还迫使内容去重把无处不在的 `CLAUDE.md → AGENTS.md` 镜像当作一个被跳过的特例来处理，而非一个普通的重复文件。仓库所有者要求在每个 scope 上无条件跟随符号链接指向的指令文件，并接受下文记录的残余信任边界风险。 + +## 决策 + +指令发现不再用 `lstat` 检查末段。每个候选（用户全局的 `$DSH_HOME/AGENTS.md`、每个基础候选，以及每个本地覆盖候选）都会被解析，并对其解析后的目标做 stat，基线组合时与每一轮 `tools/post-execute` 协调时一视同仁。一个目标为常规文件的符号链接会加载该目标的内容；一个解析后的非文件目标（包括指向目录的链接）是被确认的缺失，会像缺失文件一样移除该 scope；一个 `resolve` 或 `stat` 异常被归类为暂时不可用，且从不移除已加载的 scope。`nodeStatFile` 调用 `stat`（宿主路径），`fsStatFile` 先 `resolve` 再 `stat`（提供方路径）；两者都不调用 `lstat`。 + +一个被跟随的符号链接对下游每一步都是普通文件。它参与按目录的内容去重（[加载全部并去重 note](2026-07-21-instruction-load-all-dedup.md)），因此一个符号链接指向其同级 `AGENTS.md` 的 `CLAUDE.md` 现在会解析到相同内容，并像任何逐字节相同的真实副本一样被合并，而不再作为特例被跳过。 + +### 信任边界与残余风险 + +跟随仓库自有的链接会越过插件的信任边界：一个被克隆的、不受信任的仓库可以携带一个 `AGENTS.md`，其符号链接目标是该进程能读取的任意文件，从而把树外内容作为工作区指导暴露出来。该内容仅作为一条被 system-reminder 模式框定的、较低权限的 user 角色前缀进入；它绝不覆盖 system、developer 或用户的直接指令，并被当作数据而非权限对待。起缓解作用的边界在文件系统层，而非本插件：在部署加载不受信任的仓库时，用 `dsh-fs-policy` 门或一个操作系统沙箱（[跨家族 fs 沙箱](2026-07-14-cross-family-fs-sandbox.md)）约束 `ctx.fs`。这是一个明确的、由所有者接受的取舍，而非疏漏。 + +## 备选方案 + +**保留 `lstat` 的「不跟随」不变式。** 被仓库所有者否决：它挡住了受支持的「符号链接到规范文件」配置，并迫使符号链接镜像场景成为一个被跳过的特例而非普通重复。它所近似的读取权限边界属于文件系统策略与沙箱层，那里能更精确地遏制同一风险。 + +**只跟随用户全局的 `$DSH_HOME` 候选，项目文件保持不跟随。** 否决：所有者要求在每个 scope 上行为一致，而一条分裂的规则比一条一致应用的策略加一条有文档记录的边界更难推理。用户选择打开的项目并不比用户自己的 home 更值得信任。 + +**跟随符号链接，但拒绝解析到项目根之外的目标。** 否决：这会在错误的层（路径几何而非读取权限）重新引入一条局部的信任边界，破坏合理的「`$DSH_HOME` 指向别处」场景，并重复文件系统策略门已经拥有的遏制。 + +## 影响 + +一个符号链接指向的指令文件现在会像其目标一样被加载和渲染，从而支持在多个工具与多个 home 之间共享规范指令文件，而 `CLAUDE.md → AGENTS.md` 镜像会通过内容去重而非被跳过。指令加载不再依赖 `ctx.fs.lstat`；一个解析后的非文件是被确认的缺失，只有提供方异常才是暂时不可用。信任边界从本插件移出，进入文件系统策略与沙箱层。当部署加载不受信任的仓库时，它们必须约束 `ctx.fs`。[workspace-context note](2026-06-24-workspace-context.md) 与包（package） README 承载相同的跟随行为与残余风险声明。 diff --git a/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.i18n.yaml new file mode 100644 index 0000000000..a9ac0bc6c3 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write +2026-07-21-instruction-load-all-dedup.md: 4e895b0b7f14600adeaf8742e68eab088e3d6d24 +2026-07-21-instruction-load-all-dedup.zh.md: e27c2d2ad6e6fd291dc3344aab6ff96806fe405f diff --git a/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.md b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.md new file mode 100644 index 0000000000..4e895b0b7f --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.md @@ -0,0 +1,37 @@ +# Agent Note: Load all instruction candidates with per-directory dedup + +Status: implemented + +English | [中文](2026-07-21-instruction-load-all-dedup.zh.md) + +## Problem + +The [workspace-context plugin](2026-06-24-workspace-context.md) resolved one winning file per candidate list per directory: the first existing name in `instructionFileCandidates` won the base slot, and the [local overlay](2026-07-21-local-instruction-overlay.md) added one more winner. But `AGENTS.md` and `CLAUDE.md` routinely coexist in the same directory. In most repositories one is a symlink to the other, so they carry identical content; in repositories mid-migration they are two distinct real files that have drifted apart. First-wins silently dropped the non-winning committed file, so a directory that legitimately carried two distinct instruction files only ever surfaced one — and which one depended on candidate order, not on content. The request was to read both and deduplicate only when they are effectively the same file. + +## Decision + +Every existing candidate in each list loads — the base list first, then the local list — in configured order. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in that order, and the kept file's original bytes are rendered. Dedup is per-directory rather than global, and symmetric across the base and local lists. Trimming before comparison tolerates a trailing newline or indentation difference between a file and its near-copy while still rendering the survivor verbatim — the "extra safe" comparison the request asked for. + +Symlinks now flow through this uniformly. Instruction discovery resolves each candidate and stats its target instead of rejecting a final-component symlink, so a `CLAUDE.md` that symlinks its sibling `AGENTS.md` resolves to identical content and collapses here like any byte-identical real duplicate. Content dedup therefore renders the common symlink-mirror once through the same path as a real copy. The [follow-symlinks note](2026-07-21-follow-instruction-symlinks.md) owns that reversal and its residual trust-boundary risk. + +## Scope keys become per-candidate + +Each `(directory, candidateName)` pair is now its own logical scope, encoded `directory\u0000candidateName` with a NUL separator that cannot occur in a real path. `candidateScopeKey` / `decodeScopeKey` own the encoding, and `probeScopeInstruction` decodes the candidate name to read exactly that file. This replaces the tier-sentinel scope key the overlay note introduced: a directory no longer has a "base scope" and a "local scope" but one scope per candidate name, so `AGENTS.md` and `CLAUDE.md` in one directory are independent scopes that reconcile separately. + +Because a scope now names one fixed file, the previous "candidate switch within a scope" — an `AGENTS.md` scope that fell through to `CLAUDE.md` and recorded the old name in `previousPath` — can no longer occur. `previousPath` was removed from the change record, the serialized `context/message` metadata, and the render text; a change is now either `set`, a same-file `replace`, or a `remove`. Removing one candidate emits a `remove` for that candidate's own scope, leaving a distinct sibling as an independent scope. + +Dedup is enforced during reconciliation, not only at baseline composition. Each reconciliation pass rebuilds a per-directory set of kept trimmed-content digests in candidate order, so an unchanged file is removed when an earlier candidate converges on its content, and a newly duplicate sibling is dropped or removed. The version cache stores a `trimmedDigest` beside the full content digest so the fast path can re-evaluate duplication without re-reading content. + +## Alternatives considered + +**Keep first-wins per candidate list.** Rejected: it silently drops a directory's second committed instruction file and makes the survivor depend on candidate order rather than on whether the files actually differ, which is exactly the surprise the request set out to remove. + +**Global, cross-directory dedup.** Rejected: identical boilerplate under two different directories is legitimately in scope for each, and the deeper file must still surface for work under the deeper directory. Collapsing across directories would hide instructions the model should see. + +**Compare raw bytes without trimming.** Rejected: an editor that adds a trailing newline, or a copy that reflows indentation, would defeat dedup for files that are the same in substance. Trimming before comparison is the tolerant key the request asked for, and the survivor still renders its original bytes. + +**Follow symlinks so a mirror deduplicates through content.** Rejected for this change to preserve the no-follow invariant, then adopted separately: the [follow-symlinks note](2026-07-21-follow-instruction-symlinks.md) reverses that invariant, after which a symlinked mirror is resolved and deduplicated through content exactly like a real duplicate. + +## Consequences + +A directory with two distinct real instruction files now surfaces both; a directory whose second file merely mirrors the first still renders once, and the ubiquitous symlink case is unchanged. The visible behavior difference is confined to transition repositories that carry two distinct real files. The scope-key shape changed from a tier sentinel to a per-candidate key and `previousPath` disappeared from the durable change metadata; `dsh-session` keeps no compatibility promise for older sessions, so both are free changes. The version cache row grew a `trimmedDigest` field, and reconciliation now compares trimmed content per directory, so an unchanged file can be removed by a sibling's convergence — a transition the [state model](2026-06-24-workspace-context.md) previously could not produce. diff --git a/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.zh.md b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.zh.md new file mode 100644 index 0000000000..e27c2d2ad6 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-21-instruction-load-all-dedup.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 加载全部指令候选并按目录去重 + +Status: implemented + +[English](2026-07-21-instruction-load-all-dedup.md) | 中文 + +## 问题 + +[workspace-context 插件](2026-06-24-workspace-context.md)在每个目录中为每个候选列表只解析出一个胜出文件：`instructionFileCandidates` 中第一个存在的名字赢得基础槽位，[本地覆盖层](2026-07-21-local-instruction-overlay.md)再追加一个胜出者。但 `AGENTS.md` 与 `CLAUDE.md` 经常共处同一目录。在多数仓库里其中一个是另一个的符号链接，因此内容完全相同；在迁移中的仓库里它们则是两个已经产生分歧的、彼此独立的真实文件。先到先得会悄悄丢弃未胜出的已提交文件，于是一个合理地携带两个不同指令文件的目录最终只暴露其中一个——而暴露哪一个取决于候选顺序，而非内容。需求是把两者都读取，仅在它们实质上是同一文件时才去重。 + +## 决策 + +每个列表中每个存在的候选都会被加载——先基础列表，再本地列表——按配置顺序进行。在同一目录内，内容在去除首尾空白后逐字节相同的候选会合并到该顺序中最靠前的候选，并渲染被保留文件的原始字节。去重是按目录进行的，而非全局，并且在基础列表与本地列表之间对称。比较前先做去空白处理，可以容忍某文件与其近似副本之间的末尾换行或缩进差异，同时仍逐字节渲染保留下来的文件——这正是需求所要求的「格外稳妥」的比较。 + +符号链接现在会统一经此流转。指令发现会解析每个候选并对其目标做 stat，而非拒绝末段的符号链接，因此一个符号链接指向其同级 `AGENTS.md` 的 `CLAUDE.md` 会解析到相同内容，并在此像任何逐字节相同的真实副本一样被合并。因此内容去重会通过与真实副本相同的路径把常见的符号链接镜像只渲染一次。[跟随符号链接 note](2026-07-21-follow-instruction-symlinks.md) 拥有该反转决策及其残余的信任边界风险。 + +## scope 键改为按候选划分 + +现在每个 `(directory, candidateName)` 对都是各自独立的逻辑 scope，编码为 `directory\u0000candidateName`，其中 NUL 分隔符在真实路径中不可能出现。`candidateScopeKey` / `decodeScopeKey` 负责这套编码，`probeScopeInstruction` 则解码候选名以精确读取该文件。这取代了覆盖层 note 引入的层级哨兵 scope 键：一个目录不再有「基础 scope」和「本地 scope」，而是每个候选名一个 scope，因此同一目录中的 `AGENTS.md` 与 `CLAUDE.md` 是各自独立协调的 scope。 + +由于一个 scope 现在只对应一个固定文件，此前的「同一 scope 内的候选切换」——即一个 `AGENTS.md` scope 回退到 `CLAUDE.md` 并把旧名字记录在 `previousPath` 中——不再可能发生。`previousPath` 已从变更记录、序列化的 `context/message` 元数据以及渲染文本中移除；一次变更现在要么是 `set`、要么是同一文件的 `replace`、要么是 `remove`。移除某个候选会为该候选自己的 scope 发出一个 `remove`，而把不同的同级文件留作独立的 scope。 + +去重在协调过程中强制执行，而不仅仅在基线组合时。每一轮协调都会按候选顺序重建一个按目录的「已保留去空白摘要」集合，因此当更靠前的候选收敛到某文件的内容时，一个未变更的文件也会被移除，而新出现的重复同级文件会被丢弃或移除。版本缓存在完整内容摘要之外还存储一个 `trimmedDigest`，使快速路径无需重新读取内容即可重新判定是否重复。 + +## 备选方案 + +**每个候选列表保持先到先得。** 否决：这会悄悄丢弃一个目录的第二个已提交指令文件，并使胜出者取决于候选顺序、而非文件是否真的不同，而这恰恰是需求要消除的意外。 + +**全局的、跨目录的去重。** 否决：两个不同目录下相同的样板内容对各自而言都合理地在作用域内，而更深层的文件对于该更深目录下的工作仍必须暴露。跨目录合并会隐藏模型本应看到的指令。 + +**不做去空白、直接比较原始字节。** 否决：一个添加末尾换行的编辑器，或一个重排缩进的副本，都会让实质相同的文件无法去重。比较前去空白正是需求所要求的宽容键，而保留下来的文件仍渲染其原始字节。 + +**跟随符号链接，从而让镜像通过内容去重。** 为本次改动否决以保留「不跟随」不变式，随后另行采纳：[跟随符号链接 note](2026-07-21-follow-instruction-symlinks.md) 反转了该不变式，此后符号链接镜像会被解析，并像真实副本一样通过内容去重。 + +## 影响 + +一个携带两个不同真实指令文件的目录现在会把两者都暴露；一个第二个文件仅仅是镜像的目录仍只渲染一次，而无处不在的符号链接场景保持不变。可见的行为差异被限定在携带两个不同真实文件的迁移期仓库中。scope 键的形态从层级哨兵改为按候选划分，`previousPath` 也从持久的变更元数据中消失；`dsh-session` 对旧会话不作兼容承诺，因此两者都是无成本的改动。版本缓存行新增了一个 `trimmedDigest` 字段，协调过程现在按目录比较去空白后的内容，因此一个未变更的文件可以被同级文件的收敛所移除——这是[状态模型](2026-06-24-workspace-context.md)此前无法产生的转换。 diff --git a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.i18n.yaml index ebfc3c5203..42b09bc4f6 100644 --- a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-07-21-local-instruction-overlay.md: bb413455d453e2a1eb445cae5e4d7193e7939dc8 -2026-07-21-local-instruction-overlay.zh.md: c7447a8f1b2c9eae649225f8d54a03fc671c230a +2026-07-21-local-instruction-overlay.md: 3c7b2141b0515b5e667be4add6ad765e26c88cd8 +2026-07-21-local-instruction-overlay.zh.md: 0fd45cfcdaf6db1ea6cb0746c8d8cfb3e86c76d7 diff --git a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.md b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.md index bb413455d4..3c7b2141b0 100644 --- a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.md +++ b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.md @@ -10,15 +10,15 @@ Personal, git-ignored guidance (`AGENTS.local.md` / `CLAUDE.local.md`) is a Clau ## Decision -The plugin loads a second, independent candidate list per project directory. `localInstructionFileCandidates` defaults to `['AGENTS.local.md', 'CLAUDE.local.md']` and is resolved with the same same-directory validation as `instructionFileCandidates`. In every project directory from the root to the session cwd, the plugin loads the first existing base candidate and then, additively, the first existing local candidate; the local file is ordered after the base file so its guidance takes precedence within the byte budget. An empty `localInstructionFileCandidates` disables the overlay. +The plugin loads a second, independent candidate list per project directory. `localInstructionFileCandidates` defaults to `['AGENTS.local.md', 'CLAUDE.local.md']` and is resolved with the same same-directory validation as `instructionFileCandidates`. In every project directory from the root to the session cwd, the plugin loads the base candidates and then, additively, the local candidates; the local files are ordered after the base files so their guidance takes precedence within the byte budget. Both lists load in full under [per-directory content dedup](2026-07-21-instruction-load-all-dedup.md). An empty `localInstructionFileCandidates` disables the overlay. The default lives in the plugin `Config` schema rather than a product `cordis.yml`, so every embedder (TUI, ACP, headless) reads `.local.` files consistently and a deployment overrides or disables the behavior in one place. This is symmetric with the plugin-owned `instructionFileCandidates` default. The fixed user-global `$DSH_HOME/AGENTS.md` has no local overlay and stays base-only. -## Tiered scope keys +## Independent scopes per candidate -Each directory now yields up to two logical scopes that share a path but must stay independent across baseline freezing, the pending window, the version cache, and reconciliation. `render.ts` encodes the tier into the scope key: the base tier keeps the bare directory scope (`.`, `pkg`, `user-global`) and the local tier appends a NUL sentinel (`\u0000local`) that cannot occur in a real path. `scopeKey`/`decodeScopeKey` own the encoding. `DiscoveredInstructionFile` carries a required `tier` and `LoadedInstructionFile` an optional one (absent means base); discovery tags each file, `baselineInstructionState` derives the tiered key from directory plus tier, `reconcileInstructionContext` enumerates both tiers per project directory when the local list is non-empty, and `probeScopeInstruction` decodes the key to pick the base or local candidate list. The model-facing prompt derives its human directory label from the file display path, so the sentinel never reaches the model, and existing dedup by absolute path still collapses base and local lists that resolve to the same file. +The base and local candidates in one directory must stay independent across baseline freezing, the pending window, the version cache, and reconciliation, so a change to one never suppresses the other. Each `(directory, candidateName)` pair is its own scope key — see [per-candidate scope keys](2026-07-21-instruction-load-all-dedup.md), which replaced the earlier base/local tier sentinel. Discovery iterates the base list and then the local list in each project directory, `reconcileInstructionContext` enumerates every configured candidate per directory, and `probeScopeInstruction` decodes the candidate name to read exactly that file. The model-facing prompt derives its human directory label from the file display path, so the scope key never reaches the model. ## Alternatives considered @@ -28,10 +28,10 @@ Each directory now yields up to two logical scopes that share a path but must st **Default at the product `cordis.yml` level instead of the plugin schema.** Rejected: it would enable `.local.` only for whichever front door remembered to opt in, splitting behavior across TUI/ACP/headless and duplicating a value that belongs beside the existing candidate default. -**Reuse the bare directory as the scope key for both tiers.** Rejected: base and local files in one directory would collide in every scope-keyed map, so a change to one would suppress or overwrite the other. A sentinel-suffixed key keeps the tiers independent without widening the persisted metadata shape. +**Reuse the bare directory as the scope key for base and local files.** Rejected: base and local files in one directory would collide in every scope-keyed map, so a change to one would suppress or overwrite the other. A distinct scope key per candidate keeps them independent without widening the persisted metadata shape. **Extend the overlay to the user-global scope.** Deferred: `$DSH_HOME` is a single fixed `AGENTS.md` with no committed base to supplement, so it stays base-only until a concrete need appears. ## Consequences -`.local.` guidance is read by default across all products with no per-deployment configuration, matching neighboring tools. Each project directory can contribute two durable scopes instead of one, so dynamic discovery, edits, and removals reconcile the base and local tiers independently. The scope-key shape changed to carry the tier; `dsh-session` keeps no compatibility promise for older sessions, so this is a free change. The user-global scope remains base-only, recorded as a Known Limitation in the package README. +`.local.` guidance is read by default across all products with no per-deployment configuration, matching neighboring tools. Each project directory can contribute a durable scope per existing candidate rather than one, so dynamic discovery, edits, and removals reconcile the base and local files independently. The scope key is now [per-candidate](2026-07-21-instruction-load-all-dedup.md); `dsh-session` keeps no compatibility promise for older sessions, so this is a free change. The user-global scope remains base-only, recorded as a Known Limitation in the package README. diff --git a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.zh.md b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.zh.md index c7447a8f1b..0fd45cfcda 100644 --- a/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.zh.md +++ b/.agents/notes/implemented/feature/2026-07-21-local-instruction-overlay.zh.md @@ -10,15 +10,15 @@ Status: implemented ## 决策 -插件为每个项目目录额外加载第二个独立的候选列表。`localInstructionFileCandidates` 默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`，并与 `instructionFileCandidates` 采用相同的同目录校验来解析。在从项目根到会话 cwd 的每个项目目录中，插件先加载第一个存在的基础候选，然后叠加加载第一个存在的本地候选；本地文件排在基础文件之后，因此在字节预算之内其内容优先级更高。将 `localInstructionFileCandidates` 置空即可关闭该覆盖层。 +插件为每个项目目录额外加载第二个独立的候选列表。`localInstructionFileCandidates` 默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`，并与 `instructionFileCandidates` 采用相同的同目录校验来解析。在从项目根到会话 cwd 的每个项目目录中，插件先加载基础候选，然后叠加加载本地候选；本地文件排在基础文件之后，因此在字节预算之内其内容优先级更高。两个列表都会在[按目录内容去重](2026-07-21-instruction-load-all-dedup.md)之下完整加载。将 `localInstructionFileCandidates` 置空即可关闭该覆盖层。 该默认值定义在插件的 `Config` schema 中，而非某个产品的 `cordis.yml` 里，因此每个嵌入方（TUI、ACP、headless）读取 `.local.` 文件的行为一致，部署方也可以在一处覆盖或关闭该行为。这与插件自身持有的 `instructionFileCandidates` 默认值保持对称。 固定的用户全局文件 `$DSH_HOME/AGENTS.md` 没有本地覆盖层，始终只有基础文件。 -## 分层的 scope 键 +## 每个候选各自独立的 scope -现在每个目录最多产生两个逻辑 scope，它们共享同一路径，但在基线冻结、待定窗口、版本缓存和协调过程中都必须彼此独立。`render.ts` 把层级编码进 scope 键：基础层级保留原始的目录 scope（`.`、`pkg`、`user-global`），本地层级则追加一个真实路径中不可能出现的 NUL 哨兵（`\u0000local`）。`scopeKey`/`decodeScopeKey` 负责这套编码。`DiscoveredInstructionFile` 携带必填的 `tier`，`LoadedInstructionFile` 携带可选的 `tier`（缺省即表示基础层级）；发现过程为每个文件打上标记，`baselineInstructionState` 由目录加层级推导出分层的键，`reconcileInstructionContext` 在本地列表非空时为每个项目目录枚举两个层级，`probeScopeInstruction` 则解码该键以选取基础或本地候选列表。面向模型的提示词从文件的展示路径推导出供人阅读的目录标签，因此哨兵永远不会到达模型；而既有的按绝对路径去重仍会把解析到同一文件的基础列表与本地列表合并为一个。 +同一目录下的基础候选与本地候选，在基线冻结、待定窗口、版本缓存和协调过程中都必须彼此独立，因此对其中一个的改动绝不能抑制另一个。现在每个 `(directory, candidateName)` 对都是各自独立的 scope 键——参见[按候选划分的 scope 键](2026-07-21-instruction-load-all-dedup.md)，它取代了此前基础/本地的层级哨兵。发现过程在每个项目目录中先遍历基础列表、再遍历本地列表，`reconcileInstructionContext` 为每个目录枚举每个配置的候选，`probeScopeInstruction` 则解码候选名以精确读取该文件。面向模型的提示词从文件的展示路径推导出供人阅读的目录标签，因此 scope 键永远不会到达模型。 ## 备选方案 @@ -28,10 +28,10 @@ Status: implemented **在产品 `cordis.yml` 层面设默认，而非在插件 schema 中。** 否决：这样只会为记得开启的那个前门启用 `.local.`，从而在 TUI/ACP/headless 之间割裂行为，并重复一个本应与既有候选默认值放在一起的取值。 -**两个层级复用原始目录作为 scope 键。** 否决：同一目录下的基础文件与本地文件会在每个以 scope 为键的映射中冲突，于是对其中一个的改动会抑制或覆盖另一个。带哨兵后缀的键让两个层级保持独立，且无需扩展持久化的元数据结构。 +**两个层级复用原始目录作为 scope 键。** 否决：同一目录下的基础文件与本地文件会在每个以 scope 为键的映射中冲突，于是对其中一个的改动会抑制或覆盖另一个。为每个候选设置各自独立的 scope 键让两者保持独立，且无需扩展持久化的元数据结构。 **将覆盖层扩展到用户全局 scope。** 暂缓：`$DSH_HOME` 是单个固定的 `AGENTS.md`，没有可供补充的已提交基础文件，因此在出现具体需求前始终只有基础文件。 ## 影响 -`.local.` 指导在所有产品中默认被读取，无需按部署单独配置，与邻近工具保持一致。每个项目目录可以贡献两个持久 scope 而非一个，因此动态发现、编辑和移除会分别独立地协调基础层级与本地层级。scope 键的形态发生了变化以携带层级；`dsh-session` 对旧会话不作兼容承诺，因此这是一次无成本的改动。用户全局 scope 仍然只有基础文件，这一点作为 Known Limitation 记录在包 README 中。 +`.local.` 指导在所有产品中默认被读取，无需按部署单独配置，与邻近工具保持一致。每个项目目录可以为每个存在的候选贡献一个持久 scope 而非仅一个，因此动态发现、编辑和移除会分别独立地协调基础文件与本地文件。scope 键现在[按候选划分](2026-07-21-instruction-load-all-dedup.md)；`dsh-session` 对旧会话不作兼容承诺，因此这是一次无成本的改动。用户全局 scope 仍然只有基础文件，这一点作为 Known Limitation 记录在包 README 中。 diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.canonical.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.canonical.md new file mode 100644 index 0000000000..a66cf16a13 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.canonical.md @@ -0,0 +1 @@ +Root snapshot instruction. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md deleted file mode 100644 index a66cf16a13..0000000000 --- a/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -Root snapshot instruction. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md new file mode 120000 index 0000000000..83624c92b7 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-context/workspace/AGENTS.md @@ -0,0 +1 @@ +AGENTS.canonical.md \ No newline at end of file diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.canonical.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.canonical.md new file mode 100644 index 0000000000..862c12a235 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.canonical.md @@ -0,0 +1 @@ +Nested snapshot instruction. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md deleted file mode 100644 index 862c12a235..0000000000 --- a/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -Nested snapshot instruction. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md b/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md new file mode 120000 index 0000000000..83624c92b7 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-context/workspace/nested/AGENTS.md @@ -0,0 +1 @@ +AGENTS.canonical.md \ No newline at end of file diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md index 17c0f7fc59..a7245df91f 100644 --- a/packages/context/workspace-context/README.md +++ b/packages/context/workspace-context/README.md @@ -4,11 +4,11 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The ## Lifecycle -The baseline is composed once per agent-loop instance on `agent/session-prefix`. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, the first existing base candidate and then the first existing local-overlay candidate. The prefix is placed before all derived history, recorded in `EpochHeader.messagePrefix`, and reused verbatim for that loop instance. Because the plugin prepends its contribution before delegating, a later-registered skills catalog appears after workspace instructions. +The baseline is composed once per agent-loop instance on `agent/session-prefix`. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. The prefix is placed before all derived history, recorded in `EpochHeader.messagePrefix`, and reused verbatim for that loop instance. Because the plugin prepends its contribution before delegating, a later-registered skills catalog appears after workspace instructions. -The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. A new file is attached through the result's `additionalContexts`; a changed file or candidate switch appends a replacement; a missing final candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable. +The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable. -Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It calls `ctx.fs.lstat` before resolving a candidate, rejecting a final-component symlink instead of following repository-owned links across the trust boundary. Once `lstat` identifies the winning regular-file candidate, a later resolve/stat failure makes that scope temporarily unavailable instead of falling through to a lower-priority name. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted. +Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It resolves each candidate and stats the result, so a final-component symlink is followed to its target: a link to a regular file loads that target's content, while a missing path or a non-file target (including a link to a directory) is a confirmed absence. A resolve or stat exception instead marks that candidate's scope temporarily unavailable. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted. ## Prompt Shape @@ -40,15 +40,15 @@ These instructions apply to work under `packages/app`. Use them as guidance when ``` -A same-file edit starts with `Updated instructions from: ` and says to use the new content instead of the previously loaded content. A candidate switch additionally names the old path. When no candidate remains, the message is `Instructions removed: ` followed by `The previously loaded instructions from this file no longer apply.` Literal `` text inside an instruction file is escaped so file content cannot close the plugin-owned frame. +A same-file edit starts with `Updated instructions from: ` and says to use the new content instead of the previously loaded content. When a candidate disappears or becomes a per-directory duplicate of an earlier candidate, the message is `Instructions removed: ` followed by `The previously loaded instructions from this file no longer apply.` Literal `` text inside an instruction file is escaped so file content cannot close the plugin-owned frame. The plugin owns the complete `` framing, and every `context/message` (from this plugin or any other) reaches the model verbatim as a user-role message with no wrapping. ## State And Refresh -Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. +Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. -An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only. +An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only. The frozen baseline itself is not rewritten mid-instance. Its initial path/digest map is retained as comparison state; the next successful filesystem touch appends any baseline replacement or removal. A resumed loop recomposes the current baseline and also reconciles still-visible dynamic scopes during prefix composition. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop composes its prefix. @@ -65,7 +65,7 @@ export interface Config { } ``` -`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `maxSourceBytes` limits each source instruction file before rendering and defaults to 1 MiB. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory, the first existing candidate wins; with defaults, `AGENTS.md` is native and `CLAUDE.md` is the compatibility fallback. `localInstructionFileCandidates` defaults to `['AGENTS.local.md', 'CLAUDE.local.md']` and loads the first existing local overlay *in addition to* the base file of the same directory (rendered after it); an empty list disables the overlay. Candidate entries in both lists must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored. +`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `maxSourceBytes` limits each source instruction file before rendering and defaults to 1 MiB. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory every existing candidate loads, and candidates whose content matches an earlier one after trimming surrounding whitespace are dropped, so with the defaults an `AGENTS.md` and a `CLAUDE.md` that share content render once (as `AGENTS.md`) while genuinely distinct siblings both apply. `localInstructionFileCandidates` defaults to `['AGENTS.local.md', 'CLAUDE.local.md']` and loads its existing overlays alongside the base files of the same directory (rendered after them) under the same per-directory dedup; an empty list disables the overlay. Candidate entries in both lists must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored. The user-global file is always `$DSH_HOME/AGENTS.md` with no local overlay; both candidate lists only control project scopes. `$DSH_HOME` defaults to `~/.dsh`, and configured `~`, `~/...`, and Windows-style `~\...` prefixes are expanded against the operating-system home directory. A non-positive or non-finite render budget disables both baseline and dynamic loading; configured `maxSourceBytes` must be a positive integer. @@ -73,7 +73,7 @@ The user-global file is always `$DSH_HOME/AGENTS.md` with no local overlay; both Rendering preserves the most specific instruction files first. It drops whole broader files before truncating the most-specific file and emits a visible `Workspace instruction budget ...` notice naming omitted and truncated paths. The rendered bytes never exceed `maxBytes`. -Instruction content is read through `streamText()` under `maxSourceBytes`, even when provider metadata omits size or a file grows after its metadata probe. An oversized file is ignored without falling through to a lower-priority same-directory candidate; during dynamic reconciliation it is temporarily unavailable rather than removed. The plugin keeps no process-wide cache and never caches instruction prose. Its session-local scope cache uses provider versions only as a fast invalidation signal; after invalidation, SHA-1 over the bounded read remains the cross-provider content identity stored in structured session metadata. +Instruction content is read through `streamText()` under `maxSourceBytes`, even when provider metadata omits size or a file grows after its metadata probe. An oversized file is ignored; during dynamic reconciliation it is temporarily unavailable rather than removed. The plugin keeps no process-wide cache and never caches instruction prose. Its session-local scope cache uses provider versions only as a fast invalidation signal; after invalidation, SHA-1 over the bounded read remains the cross-provider content identity stored in structured session metadata. ## Model Experience @@ -137,7 +137,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -A changed file produces `Updated instructions from: ` plus its replacement content; a candidate switch also names the previous path. A removed final candidate produces the removal notice below. +A changed file produces `Updated instructions from: ` plus its replacement content. A candidate that disappears or becomes a per-directory duplicate of an earlier candidate produces the removal notice below. ##### Removal notice @@ -162,4 +162,6 @@ Append-only; newly visible content follows the reusable request prefix and does - **Discovery follows structured fs tools, not shell navigation** — a `bash` command that changes directories does not trigger nested instruction discovery because shell syntax and per-call shell state are not a reliable filesystem seam. - **Refresh is touch-driven** — there is no watcher; external edits become visible on the next successful first-party `read`, `write`, or `edit`, or when a resumed loop recomposes its prefix. - **Candidate semantics stay intentionally small** — lowercase names, `.claude/rules/`, and `@path` imports are not interpreted; project scopes load `AGENTS.local.md`/`CLAUDE.local.md` overlays by default, but the user-global `$DSH_HOME` scope has no local overlay and other custom names require explicit candidate configuration. +- **Per-directory dedup is content-based** — sibling candidates collapse only when byte-identical after trimming leading and trailing whitespace; a `CLAUDE.md` that symlinks its sibling `AGENTS.md` resolves to the same content and collapses like any duplicate, while a distinct real copy that has drifted from `AGENTS.md` loads in full alongside it. +- **Symlinked instruction files are followed across the trust boundary** — a candidate whose final component is a symlink is resolved and its target loaded, so a cloned repository can surface off-tree file content as lower-authority workspace guidance (it never overrides system, developer, or direct user instructions). Confine `ctx.fs` with the filesystem policy gate or an OS sandbox when loading untrusted repositories. - **Instruction content is bounded, not summarized** — over-budget broad files are omitted and the most-specific file may be truncated; the plugin never asks a model to compress instruction prose. diff --git a/packages/context/workspace-context/src/config.ts b/packages/context/workspace-context/src/config.ts index 4b966e890c..56c048976c 100644 --- a/packages/context/workspace-context/src/config.ts +++ b/packages/context/workspace-context/src/config.ts @@ -23,9 +23,15 @@ export interface Config { maxBytes: number /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */ maxSourceBytes?: number - /** Ordered same-directory project candidates; the first existing regular file wins in each scope. */ + /** + * Ordered same-directory project candidates; every existing file loads, with + * per-directory trimmed-content duplicates collapsed to the earliest candidate. + */ instructionFileCandidates?: string[] - /** Ordered same-directory local-overlay candidates loaded in addition to the base file per scope; empty disables the overlay. */ + /** + * Ordered same-directory local-overlay candidates loaded after the base files + * under the same per-directory trimmed-content dedup; empty disables the overlay. + */ localInstructionFileCandidates?: string[] } diff --git a/packages/context/workspace-context/src/digest.ts b/packages/context/workspace-context/src/digest.ts index 4568371277..23ba351046 100644 --- a/packages/context/workspace-context/src/digest.ts +++ b/packages/context/workspace-context/src/digest.ts @@ -14,3 +14,15 @@ import { createHash } from 'node:crypto' export function instructionContentSha1(content: string): string { return createHash('sha1').update(content).digest('hex') } + +/** + * Compute the whitespace-insensitive identity used for per-directory duplicate + * suppression. Leading and trailing whitespace is trimmed before hashing so a + * symlinked or byte-copied sibling that differs only by surrounding whitespace + * still collapses to a single rendered file. + * @param content - exact UTF-8 instruction text. + * @returns SHA-1 digest of the trimmed content. + */ +export function trimmedInstructionDigest(content: string): string { + return instructionContentSha1(content.trim()) +} diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts index 8656582aa4..3e6a3d5de8 100644 --- a/packages/context/workspace-context/src/files.ts +++ b/packages/context/workspace-context/src/files.ts @@ -5,13 +5,14 @@ */ import { createReadStream } from 'node:fs' -import { lstat, stat } from 'node:fs/promises' +import { stat } from 'node:fs/promises' import { dirname, isAbsolute, join, relative, resolve } from 'node:path' -import type { FileSystem, FsInfo, FsPathInfo, FsTarget, FsVersion } from '@deepseek-ai/dsh-fs' +import type { FileSystem, FsInfo, FsTarget, FsVersion } from '@deepseek-ai/dsh-fs' import { assertNever } from '@deepseek-ai/dsh-llm' import { dshHomeDisplay } from '@deepseek-ai/dsh-paths' import { resolveConfig, resolveDiscoveryConfig, type ResolvedConfig } from './config.ts' -import { decodeScopeKey, renderWorkspaceContext, type InstructionTier, type RenderedWorkspaceContext } from './render.ts' +import { trimmedInstructionDigest } from './digest.ts' +import { decodeScopeKey, renderWorkspaceContext, USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE, type RenderedWorkspaceContext } from './render.ts' /** An instruction candidate identified by absolute and model-facing paths. */ export interface InstructionFile { @@ -24,18 +25,15 @@ export interface LoadedInstructionFile extends InstructionFile { content: string /** Provider freshness token when the file was loaded through `ctx.fs`. */ version?: FsVersion - /** Base file or additive local overlay; absent is treated as base. */ - tier?: InstructionTier } interface DiscoveredInstructionFile extends InstructionFile { target?: FsTarget size?: number version?: FsVersion - tier: InstructionTier } -/** Provider metadata for a winning scope candidate before its content is read. */ +/** Provider metadata for a probed scope candidate before its content is read. */ export interface ProbedInstructionFile extends InstructionFile { target: FsTarget version: FsVersion @@ -90,7 +88,9 @@ function isMissingPathError(error: unknown): boolean { async function nodeStatFile(path: string, signal?: AbortSignal): Promise { try { signal?.throwIfAborted() - const info = await lstat(path) + // stat (not lstat) follows a final-component symlink so a link to a regular + // file loads; a broken link surfaces as ENOENT and is treated as absent below. + const info = await stat(path) signal?.throwIfAborted() if (!info.isFile()) return { kind: 'absent' } return { kind: 'present', info: { size: info.size } } @@ -105,25 +105,15 @@ async function fsStatFile( fileSystem: FileSystem, signal?: AbortSignal, ): Promise { - // TODO(instruction-symlink-race): replace this lstat -> resolve -> read - // protocol, including probeScopeInstruction below, with a provider-owned - // atomic no-follow read so the final component cannot change after validation. - let pathInfo: FsPathInfo | undefined - try { - pathInfo = await fileSystem.lstat(path, undefined, signal) - signal?.throwIfAborted() - } catch { - signal?.throwIfAborted() - return { kind: 'unavailable' } - } - if (pathInfo?.type !== 'file') return { kind: 'absent' } - + // resolve() follows a final-component symlink to its target's stable identity; + // stat then classifies that target. A link to a regular file loads, while a + // missing path or non-file target (including a link to a directory) is absent. try { const target = await fileSystem.resolve(path, signalOptions(signal)) signal?.throwIfAborted() const info = await fileSystem.stat(target, signal) signal?.throwIfAborted() - if (info?.type !== 'file') return { kind: 'unavailable' } + if (info?.type !== 'file') return { kind: 'absent' } return { kind: 'present', info: { target, version: info.version, ...info.size === undefined ? {} : { size: info.size } }, @@ -236,35 +226,32 @@ export function relativeDisplay(root: string, path: string): string { return relative(root, path) } -async function firstExistingInstructionFile( +async function allExistingInstructionFiles( dir: string, root: string, instructionFileCandidates: readonly string[], - tier: InstructionTier, fileSystem?: FileSystem, signal?: AbortSignal, -): Promise { +): Promise { + const found: DiscoveredInstructionFile[] = [] for (const candidate of instructionFileCandidates) { const path = join(dir, candidate) const probe = await statFile(path, fileSystem, signal) switch (probe.kind) { case 'present': - return { - absolutePath: path, - displayPath: relativeDisplay(root, path), - tier, - ...probe.info, - } - case 'absent': + found.push({ absolutePath: path, displayPath: relativeDisplay(root, path), ...probe.info }) continue + // A missing candidate is skipped; a transient provider failure skips only + // that candidate so the remaining independent candidates still load. + case 'absent': case 'unavailable': - return undefined + continue /* v8 ignore next 2 -- StatFileProbe is closed; this arm only makes adding a kind a compile error. */ default: - return assertNever(probe, 'StatFileProbe') + assertNever(probe, 'StatFileProbe') } } - return undefined + return found } async function discoverInstructionFiles( @@ -280,14 +267,13 @@ async function discoverInstructionFiles( files.push(file) } - const userGlobal = join(config.dshHome, 'AGENTS.md') + const userGlobal = join(config.dshHome, USER_GLOBAL_FILE) const userGlobalProbe = await statFile(userGlobal, fileSystem, options.signal) switch (userGlobalProbe.kind) { case 'present': addFile({ absolutePath: userGlobal, displayPath: userGlobalDisplayPath(config.dshHome), - tier: 'base', ...userGlobalProbe.info, }) break @@ -302,11 +288,10 @@ async function discoverInstructionFiles( const cwd = resolve(options.cwd) const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal) for (const dir of ancestorChain(projectRoot, cwd)) { - const base = await firstExistingInstructionFile(dir, projectRoot, config.instructionFileCandidates, 'base', fileSystem, options.signal) - if (base !== undefined) addFile(base) - if (config.localInstructionFileCandidates.length > 0) { - const local = await firstExistingInstructionFile(dir, projectRoot, config.localInstructionFileCandidates, 'local', fileSystem, options.signal) - if (local !== undefined) addFile(local) + for (const candidates of [config.instructionFileCandidates, config.localInstructionFileCandidates]) { + for (const file of await allExistingInstructionFiles(dir, projectRoot, candidates, fileSystem, options.signal)) { + addFile(file) + } } } return files @@ -314,8 +299,10 @@ async function discoverInstructionFiles( /** * Discover host-visible user-global and root-to-cwd instruction candidates. + * All present candidates in each directory are returned; trimmed-content + * duplicates are collapsed later, once content is read. * @param options - cwd, home, root marker, and candidate configuration. - * @returns de-duplicated instruction paths in model precedence order. + * @returns path-deduplicated instruction candidates in model precedence order. */ export async function discoverBaselineInstructionFiles(options: DiscoverOptions): Promise { return (await discoverInstructionFiles(options)).map(({ absolutePath, displayPath }) => ({ absolutePath, displayPath })) @@ -358,6 +345,33 @@ async function readBounded( } } +/** + * Drop later candidates whose trimmed content duplicates an earlier sibling in + * the same directory. Different directories never collapse even when identical; + * within one directory the earliest candidate in discovery order is kept and its + * original bytes are rendered. A candidate that symlinks a sibling resolves to + * the same content and collapses here like any byte-identical real file. + * @param files - loaded files in discovery order. + * @returns the retained files in the same order. + */ +export function dedupInstructionFilesByDirectory(files: LoadedInstructionFile[]): LoadedInstructionFile[] { + const keptDigestsByDir = new Map>() + const kept: LoadedInstructionFile[] = [] + for (const file of files) { + const dir = dirname(file.displayPath) + let digests = keptDigestsByDir.get(dir) + if (digests === undefined) { + digests = new Set() + keptDigestsByDir.set(dir, digests) + } + const digest = trimmedInstructionDigest(file.content) + if (digests.has(digest)) continue + digests.add(digest) + kept.push(file) + } + return kept +} + /** * Discover, read, and render the baseline instruction chain. * @param options - discovery, source-size, byte-budget, and cancellation configuration. @@ -393,23 +407,23 @@ export async function loadBaselineInstructionSet( absolutePath: file.absolutePath, displayPath: file.displayPath, content, - tier: file.tier, ...file.version === undefined ? {} : { version: file.version }, }) } } - if (loaded.length === 0) return undefined - const rendered = renderWorkspaceContext(loaded, { maxBytes: config.maxBytes }) + const deduped = dedupInstructionFilesByDirectory(loaded) + if (deduped.length === 0) return undefined + const rendered = renderWorkspaceContext(deduped, { maxBytes: config.maxBytes }) const omitted = new Set(rendered.omitted.map(file => file.absolutePath)) - return { rendered, included: loaded.filter(file => !omitted.has(file.absolutePath)) } + return { rendered, included: deduped.filter(file => !omitted.has(file.absolutePath)) } } /** - * Probe the current first-winning instruction candidate for one logical scope. - * @param scope - `user-global`, or a {@link scopeKey} for a project directory's base or local tier. + * Probe the current provider metadata for one per-candidate instruction scope. + * @param scope - a {@link candidateScopeKey} identifying a directory and candidate file. * @param projectRoot - project root used to resolve and display project scopes. * @param resolved - normalized plugin configuration. - * @param fileSystem - provider used for no-follow probing. + * @param fileSystem - provider used to resolve and stat scope candidates. * @param signal - cancellation for provider probes. * @returns present metadata, confirmed absence, or temporary unavailability. */ @@ -420,43 +434,32 @@ export async function probeScopeInstruction( fileSystem: FileSystem, signal?: AbortSignal, ): Promise { - const { directory, tier } = decodeScopeKey(scope) - const dir = directory === 'user-global' + const { directory, candidateName } = decodeScopeKey(scope) + const dir = directory === USER_GLOBAL_DIRECTORY ? resolved.dshHome : directory === '.' ? projectRoot : join(projectRoot, directory) - const candidates = directory === 'user-global' - ? ['AGENTS.md'] - : tier === 'local' ? resolved.localInstructionFileCandidates : resolved.instructionFileCandidates - for (const candidate of candidates) { - const absolutePath = join(dir, candidate) - let pathInfo: FsPathInfo | undefined - try { - pathInfo = await fileSystem.lstat(absolutePath, undefined, signal) - } catch { - signal?.throwIfAborted() - return { kind: 'unavailable' } - } - if (pathInfo === undefined || pathInfo.type !== 'file') continue - let target: FsTarget - let info: FsInfo | undefined - try { - target = await fileSystem.resolve(absolutePath, signalOptions(signal)) - info = await fileSystem.stat(target, signal) - } catch { - signal?.throwIfAborted() - return { kind: 'unavailable' } - } - if (info?.type !== 'file') return { kind: 'unavailable' } - const file: ProbedInstructionFile = { - absolutePath, - displayPath: directory === 'user-global' ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath), - target, - version: info.version, - ...info.size === undefined ? {} : { size: info.size }, - } - return { kind: 'present', file } + const absolutePath = join(dir, candidateName) + // resolve() follows a final-component symlink; stat then classifies the target. + // A non-file target (missing, or a link to a directory) is a confirmed absence; + // only a provider exception is reported as unavailable. + let target: FsTarget + let info: FsInfo | undefined + try { + target = await fileSystem.resolve(absolutePath, signalOptions(signal)) + info = await fileSystem.stat(target, signal) + } catch { + signal?.throwIfAborted() + return { kind: 'unavailable' } } - return { kind: 'absent' } + if (info?.type !== 'file') return { kind: 'absent' } + const file: ProbedInstructionFile = { + absolutePath, + displayPath: directory === USER_GLOBAL_DIRECTORY ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath), + target, + version: info.version, + ...info.size === undefined ? {} : { size: info.size }, + } + return { kind: 'present', file } } /** diff --git a/packages/context/workspace-context/src/render.ts b/packages/context/workspace-context/src/render.ts index 7f8fd2f647..baca6bd84b 100644 --- a/packages/context/workspace-context/src/render.ts +++ b/packages/context/workspace-context/src/render.ts @@ -4,7 +4,7 @@ * @module @deepseek-ai/dsh-workspace-context/render */ -import { dirname } from 'node:path' +import { basename, dirname } from 'node:path' import type { InstructionFile, LoadedInstructionFile } from './files.ts' const SYSTEM_REMINDER_OPEN = '' @@ -33,7 +33,6 @@ export interface WorkspaceInstructionChange { action: 'set' | 'replace' | 'remove' scope: string path: string - previousPath?: string digest?: string } @@ -62,8 +61,8 @@ function truncateUtf8(value: string, maxBytes: number): string { function escapeInstructionContent(content: string): string { // TODO(instruction-frame-paths): apply the same delimiter neutralization to - // every interpolated path, scope, and previous path; repository-controlled - // names can otherwise close the plugin-owned system-reminder frame. + // every interpolated path and scope; repository-controlled names can + // otherwise close the plugin-owned system-reminder frame. return content.replaceAll(SYSTEM_REMINDER_CLOSE, '<\\/system-reminder>') } @@ -71,43 +70,63 @@ function sectionText(file: LoadedInstructionFile): string { return `Instructions from: ${file.displayPath}\n\n${escapeInstructionContent(file.content)}` } +/** Directory component that identifies the single user-global instruction scope. */ +export const USER_GLOBAL_DIRECTORY = 'user-global' + +/** + * File name of the single user-global instruction file under `$DSH_HOME`. + * Discovery (`$DSH_HOME/`) and reconciliation (the user-global scope key's + * candidate component) both key on this name, so it lives in one place: were the + * two to disagree, the user-global instruction would load but never reconcile. + */ +export const USER_GLOBAL_FILE = 'AGENTS.md' + /** * Derive the logical instruction scope from a model-facing path. * @param displayPath - project-relative or user-global instruction path. * @returns `user-global`, `.`, or the containing project-relative directory. */ export function scopeForDisplayPath(displayPath: string): string { - if (displayPath === '~/.dsh/AGENTS.md' || displayPath === '$DSH_HOME/AGENTS.md') return 'user-global' + if (displayPath === '~/.dsh/AGENTS.md' || displayPath === '$DSH_HOME/AGENTS.md') return USER_GLOBAL_DIRECTORY return dirname(displayPath) } -/** Instruction tier: the native base file or the additive local overlay. */ -export type InstructionTier = 'base' | 'local' - -const LOCAL_SCOPE_SUFFIX = '\u0000local' +const SCOPE_SEPARATOR = '\u0000' /** - * Compose the reconciliation key for a directory scope and instruction tier. - * The base tier keeps the human-readable directory; the local overlay appends a - * NUL-delimited marker that no directory path can contain, so a directory's base - * and local files never collide in the scope-keyed state maps. + * Compose the reconciliation key for one instruction candidate file. + * Each loaded candidate is tracked independently, so the key pairs the logical + * directory with the exact candidate file name behind a NUL separator that no + * directory path or file name can contain. Distinct candidates in one directory + * (`AGENTS.md` vs `CLAUDE.md`, a base file vs its `.local` overlay) therefore + * never collide in the scope-keyed state maps. * @param directory - `user-global`, `.`, or a project-relative directory. - * @param tier - base file or additive local overlay. - * @returns the collision-free logical scope key. + * @param candidateName - instruction file name within that directory. + * @returns the per-candidate logical scope key. */ -export function scopeKey(directory: string, tier: InstructionTier): string { - return tier === 'local' ? `${directory}${LOCAL_SCOPE_SUFFIX}` : directory +export function candidateScopeKey(directory: string, candidateName: string): string { + return `${directory}${SCOPE_SEPARATOR}${candidateName}` } /** - * Recover the directory and tier that {@link scopeKey} encoded. - * @param scope - a base or local scope key. - * @returns the directory scope and its instruction tier. + * Derive the per-candidate scope key for a loaded instruction file. + * @param displayPath - project-relative or user-global instruction path. + * @returns the scope key pairing the file's directory with its name. */ -export function decodeScopeKey(scope: string): { directory: string; tier: InstructionTier } { - return scope.endsWith(LOCAL_SCOPE_SUFFIX) - ? { directory: scope.slice(0, -LOCAL_SCOPE_SUFFIX.length), tier: 'local' } - : { directory: scope, tier: 'base' } +export function instructionScopeKey(displayPath: string): string { + return candidateScopeKey(scopeForDisplayPath(displayPath), basename(displayPath)) +} + +/** + * Recover the directory and candidate name that {@link candidateScopeKey} encoded. + * @param scope - a per-candidate scope key. + * @returns the directory scope and the candidate file name within it. + */ +export function decodeScopeKey(scope: string): { directory: string; candidateName: string } { + const separator = scope.indexOf(SCOPE_SEPARATOR) + /* v8 ignore next -- every scope key is produced by candidateScopeKey, which always inserts the separator. */ + if (separator < 0) return { directory: scope, candidateName: '' } + return { directory: scope.slice(0, separator), candidateName: scope.slice(separator + 1) } } function additionalSectionText(file: LoadedInstructionFile): string { @@ -129,13 +148,10 @@ function changedSectionText(item: ChangeRenderItem): string { if (change.action === 'remove') { return `Instructions removed: ${change.path}\n\nThe previously loaded instructions from this file no longer apply.` } - const description = change.previousPath === undefined - ? 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.' - : `The instructions previously loaded from \`${change.previousPath}\` no longer apply. Use the following content for \`${scopeForDisplayPath(change.path)}\` instead.` return [ `Updated instructions from: ${change.path}`, '', - description, + 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.', '', escapeInstructionContent(file.content), ].join('\n') diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index 885942a8c5..b2f1fa88ef 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -10,7 +10,7 @@ import type { JsonValue, Session, SessionEvent } from '@deepseek-ai/dsh-session' import type { FileSystem, FsVersion } from '@deepseek-ai/dsh-fs' import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools' import type { ResolvedConfig } from './config.ts' -import { instructionContentSha1 } from './digest.ts' +import { instructionContentSha1, trimmedInstructionDigest } from './digest.ts' import { ancestorChain, descendantDirsBetween, @@ -21,9 +21,12 @@ import { type LoadedInstructionFile, } from './files.ts' import { + candidateScopeKey, + decodeScopeKey, + instructionScopeKey, renderInstructionChanges, - scopeForDisplayPath, - scopeKey, + USER_GLOBAL_DIRECTORY, + USER_GLOBAL_FILE, type ChangeRenderItem, type WorkspaceInstructionChange, } from './render.ts' @@ -45,6 +48,11 @@ export interface InstructionVersionState { path: string version: FsVersion digest: string + /** + * Trimmed-content identity ({@link trimmedInstructionDigest}) used to suppress + * per-directory duplicates on the metadata fast path without re-reading a sibling. + */ + trimmedDigest: string } /** Session-isolated fast-path state keyed by logical instruction scope. */ @@ -72,7 +80,6 @@ function workspaceContextHook(text: string, changes: WorkspaceInstructionChange[ action: change.action, scope: change.scope, path: change.path, - ...change.previousPath !== undefined ? { previousPath: change.previousPath } : {}, ...change.digest !== undefined ? { digest: change.digest } : {}, })) const meta: JsonValue = { kind: 'workspace-instructions', version: 1, changes: serializedChanges } @@ -113,13 +120,11 @@ function workspaceInstructionChanges(meta: JsonValue | undefined): WorkspaceInst if (!isRecord(value)) continue if (value.action !== 'set' && value.action !== 'replace' && value.action !== 'remove') continue if (typeof value.scope !== 'string' || typeof value.path !== 'string') continue - if (value.previousPath !== undefined && typeof value.previousPath !== 'string') continue if (value.digest !== undefined && typeof value.digest !== 'string') continue changes.push({ action: value.action, scope: value.scope, path: value.path, - ...value.previousPath !== undefined ? { previousPath: value.previousPath } : {}, ...value.digest !== undefined ? { digest: value.digest } : {}, }) } @@ -130,7 +135,6 @@ function sameInstructionChange(a: WorkspaceInstructionChange, b: WorkspaceInstru return a.action === b.action && a.scope === b.scope && a.path === b.path - && a.previousPath === b.previousPath && a.digest === b.digest } @@ -170,13 +174,18 @@ export function baselineInstructionState(files: LoadedInstructionFile[]): { const digest = instructionContentSha1(file.content) const change: WorkspaceInstructionChange = { action: 'set', - scope: scopeKey(scopeForDisplayPath(file.displayPath), file.tier ?? 'base'), + scope: instructionScopeKey(file.displayPath), path: file.displayPath, digest, } changes.set(change.scope, change) if (file.version !== undefined) { - versions.set(change.scope, { path: file.displayPath, version: file.version, digest }) + versions.set(change.scope, { + path: file.displayPath, + version: file.version, + digest, + trimmedDigest: trimmedInstructionDigest(file.content), + }) } } return { changes, versions } @@ -392,40 +401,57 @@ export async function reconcileInstructionContext( // recomputing it after marker edits reinterprets the existing relative scope keys. const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal) const scopes = new Set() - const localEnabled = resolved.localInstructionFileCandidates.length > 0 + const addDirScopes = (directory: string): void => { + for (const candidate of resolved.instructionFileCandidates) scopes.add(candidateScopeKey(directory, candidate)) + for (const candidate of resolved.localInstructionFileCandidates) scopes.add(candidateScopeKey(directory, candidate)) + } const addProjectScopes = (dir: string): void => { - const scope = relativeScope(projectRoot, dir) - scopes.add(scope) - if (localEnabled) scopes.add(scopeKey(scope, 'local')) + addDirScopes(relativeScope(projectRoot, dir)) } if (options.includeBaselineScopes) { - scopes.add('user-global') + scopes.add(candidateScopeKey(USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE)) for (const dir of ancestorChain(projectRoot, cwd)) addProjectScopes(dir) } - for (const scope of effective.keys()) scopes.add(scope) + for (const scope of effective.keys()) { + const { directory } = decodeScopeKey(scope) + if (directory === USER_GLOBAL_DIRECTORY) scopes.add(candidateScopeKey(USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE)) + else addDirScopes(directory) + } if (options.touchedPath !== undefined) { for (const dir of descendantDirsBetween(cwd, options.touchedPath)) addProjectScopes(dir) } const versions = versionStatesFor(session, versionCache) const seenAbsolutePaths = new Set() + // Per-directory trimmed-content identities kept so far this pass, iterated in + // candidate order (base before local); a later sibling matching an earlier one + // is a duplicate and is dropped or removed rather than rendered twice. + const keptTrimmedByDir = new Map>() + const registerKeptTrimmed = (directory: string, digest: string): boolean => { + let digests = keptTrimmedByDir.get(directory) + if (digests === undefined) { + digests = new Set() + keptTrimmedByDir.set(directory, digests) + } + if (digests.has(digest)) return true + digests.add(digest) + return false + } const items: ChangeRenderItem[] = [] const versionUpdates: InstructionVersionUpdate[] = [] + const pushRemoval = (scope: string, path: string): void => { + const change: WorkspaceInstructionChange = { action: 'remove', scope, path } + items.push({ change, file: { absolutePath: `removed:${scope}`, displayPath: path, content: '' } }) + versionUpdates.push({ change }) + } for (const scope of scopes) { + const { directory } = decodeScopeKey(scope) const previous = effective.get(scope) const probe = await probeScopeInstruction(scope, projectRoot, resolved, fileSystem, options.signal) if (probe.kind === 'unavailable') continue if (probe.kind === 'absent') { - if (previous === undefined || previous.action === 'remove') { - versions.delete(scope) - continue - } - const change: WorkspaceInstructionChange = { action: 'remove', scope, path: previous.path } - items.push({ - change, - file: { absolutePath: `removed:${scope}`, displayPath: previous.path, content: '' }, - }) - versionUpdates.push({ change }) + if (previous === undefined || previous.action === 'remove') versions.delete(scope) + else pushRemoval(scope, previous.path) continue } const { file: probedFile } = probe @@ -440,29 +466,39 @@ export async function reconcileInstructionContext( && previous.action !== 'remove' && previous.path === cached.path && previous.digest === cached.digest - ) continue + ) { + // Unchanged and previously rendered: keep it, but an earlier sibling that + // now matches its trimmed content makes this the duplicate to remove. + if (registerKeptTrimmed(directory, cached.trimmedDigest)) pushRemoval(scope, previous.path) + continue + } const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal) if (file === undefined) continue const currentDigest = instructionContentSha1(file.content) + const trimmedDigest = trimmedInstructionDigest(file.content) + if (registerKeptTrimmed(directory, trimmedDigest)) { + // A distinct file whose trimmed content already appeared earlier in this + // directory: drop it, removing any copy that was previously rendered. + if (previous !== undefined && previous.action !== 'remove') pushRemoval(scope, previous.path) + else versions.delete(scope) + continue + } const nextVersion: InstructionVersionState = { path: file.displayPath, version: probedFile.version, digest: currentDigest, + trimmedDigest, } if (previous !== undefined && previous.action !== 'remove' && previous.path === file.displayPath && previous.digest === currentDigest) { versions.set(scope, nextVersion) continue } const action = previous === undefined || previous.action === 'remove' ? 'set' : 'replace' - const previousPath = action === 'replace' && previous !== undefined && previous.path !== file.displayPath - ? previous.path - : undefined const change: WorkspaceInstructionChange = { action, scope, path: file.displayPath, - ...previousPath === undefined ? {} : { previousPath }, digest: currentDigest, } items.push({ change, file }) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index c3d1aa05f3..1d329d2171 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1,5 +1,5 @@ -import { mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' -import { dirname, join, resolve } from 'node:path' +import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' +import { dirname, join } from 'node:path' import { tmpdir } from 'node:os' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' @@ -7,9 +7,8 @@ import Loader from '@cordisjs/plugin-loader' import * as workspaceContext from '@deepseek-ai/dsh-workspace-context' import LlmService, { CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session' -import AgentRegistry, { agentEvents, type Agent, type HookContext } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { type Agent, type HookContext } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' -import { scopeTarget } from '@deepseek-ai/dsh-scope' import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs' import type { FsDirEntry, @@ -24,12 +23,7 @@ import type { import LocalFileSystem from '@deepseek-ai/dsh-fs-local' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools' -import type { - PostToolDecision, - ToolExecution, - ToolExecutionResult, - ToolExecutionToken, -} from '@deepseek-ai/dsh-tools' +import type { ToolExecution, ToolExecutionToken } from '@deepseek-ai/dsh-tools' import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import { discoverBaselineInstructionFiles, @@ -44,8 +38,12 @@ import { type InstructionVersionCache, type PendingInstructionChange, } from '../src/state.ts' +import { candidateScopeKey } from '../src/render.ts' import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +/** Per-candidate reconciliation scope key: directory paired with the file name. */ +const sk = (directory: string, candidateName: string): string => candidateScopeKey(directory, candidateName) + const testToolSignal = new AbortController().signal async function tempRepo(): Promise { @@ -59,9 +57,7 @@ async function write(path: string, content: string): Promise { class RecordingFileSystem extends FileSystem { entries = new Map() - lstatTypes = new Map() throwOnStat = new Set() - throwOnRead = new Set() omitSizes = new Set() readTargets: string[] = [] readTextTargets: string[] = [] @@ -70,7 +66,7 @@ class RecordingFileSystem extends FileSystem { override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise { if (opts?.signal !== undefined) this.signals.push(opts.signal) opts?.signal?.throwIfAborted() - const absolute = resolve(opts?.cwd ?? '/', path) + const absolute = join(opts?.cwd ?? '/', path) return { targetKey: FsTargetKey(absolute), displayPath: absolute } } @@ -92,8 +88,6 @@ class RecordingFileSystem extends FileSystem { if (signal !== undefined) this.signals.push(signal) signal?.throwIfAborted() const target = await this.resolve(path, { ...opts, ...signal === undefined ? {} : { signal } }) - const lstatType = this.lstatTypes.get(target.targetKey) - if (lstatType !== undefined) return { version: FsVersion(`lstat:${target.targetKey}`), type: lstatType } const info = await this.stat(target, signal) if (info === undefined) return undefined return { @@ -114,7 +108,6 @@ class RecordingFileSystem extends FileSystem { if (signal !== undefined) this.signals.push(signal) signal?.throwIfAborted() this.readTargets.push(target.targetKey) - if (this.throwOnRead.has(target.targetKey)) throw new Error(`read failed: ${target.displayPath}`) const content = this.entries.get(target.targetKey)?.content ?? '' return (async function* () { const midpoint = Math.ceil(content.length / 2) @@ -235,31 +228,14 @@ const composedPrefixes = new WeakMap() async function composeBaselinePrefix(ctx: Context, agent: Agent): Promise { const empty: Message[] = [] - const prefix = await agentEvents(ctx, agent).waterfall( - 'agent/session-prefix', empty, AbortSignal.timeout(1000), + const prefix = await ctx.waterfall( + 'agent/session-prefix', agent, empty, AbortSignal.timeout(1000), () => Promise.resolve(empty), ) composedPrefixes.set(agent, prefix) return prefix } -function toolEventCarrier(ctx: Context, exec: ToolExecution) { - return scopeTarget(ctx.get('tools') ?? ctx as unknown as ToolRegistry, exec.agent) -} - -function postExecute( - ctx: Context, - exec: ToolExecution, - result: Readonly, - next: () => Promise, -): Promise { - return ctx.waterfall(toolEventCarrier(ctx, exec), 'tools/post-execute', exec, result, next) -} - -function emitToolResult(ctx: Context, exec: ToolExecution, result: Readonly): void { - ctx.emit(toolEventCarrier(ctx, exec), 'tools/result', exec, result) -} - function derivedText(agent: Agent): string { return blocksText(composedPrefixes.get(agent)?.[0]?.content) } @@ -284,7 +260,7 @@ describe('workspace context instruction discovery', () => { } }) - it('loads user-global first, then root-to-cwd workspace instructions using the default candidate order', async () => { + it('loads user-global first, then every root-to-cwd candidate in precedence order', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -292,7 +268,7 @@ describe('workspace context instruction discovery', () => { await mkdir(join(root, '.git'), { recursive: true }) await write(join(home, 'AGENTS.md'), 'global rules') await write(join(root, 'AGENTS.md'), 'root agents') - await write(join(root, 'CLAUDE.md'), 'root claude ignored') + await write(join(root, 'CLAUDE.md'), 'root claude') await write(join(root, 'packages/CLAUDE.md'), 'package claude') await write(join(cwd, 'AGENTS.md'), 'app agents') @@ -301,10 +277,11 @@ describe('workspace context instruction discovery', () => { expect(files.map(file => file.displayPath)).toEqual([ '$DSH_HOME/AGENTS.md', 'AGENTS.md', - join('packages', 'CLAUDE.md'), - join('packages', 'app', 'AGENTS.md'), + 'CLAUDE.md', + 'packages/CLAUDE.md', + 'packages/app/AGENTS.md', ]) - expect(files.map(file => file.absolutePath)).not.toContain(join(root, 'CLAUDE.md')) + expect(files.map(file => file.absolutePath)).toContain(join(root, 'CLAUDE.md')) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -406,44 +383,41 @@ describe('workspace context instruction discovery', () => { } }) - it('skips a provider file whose read fails after a successful metadata probe', async () => { + it('skips a file that becomes unreadable after discovery without failing the request', async () => { const root = await tempRepo() const home = await tempRepo() - const ctx = new Context() try { const cwd = join(root, 'pkg') + await mkdir(join(root, '.git'), { recursive: true }) + await mkdir(cwd, { recursive: true }) const leaf = join(cwd, 'AGENTS.md') - await ctx.plugin(RecordingFileSystem) - const fs = ctx.fs as RecordingFileSystem - fs.entries.set(join(root, '.git'), { type: 'directory' }) - fs.entries.set(leaf, { type: 'file', content: 'secret-ish rule' }) - fs.throwOnRead.add(leaf) + await write(leaf, 'secret-ish rule') + await chmod(leaf, 0) - const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }, fs) + const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }) expect(loaded).toBeUndefined() - expect(fs.readTargets).toEqual([leaf]) + await chmod(leaf, 0o600) } finally { - await ctx.fiber.dispose() await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) } }) - it('rejects symlinked instruction files instead of following repository-controlled links', async () => { + it('follows a symlinked instruction file to its target content', async () => { const root = await tempRepo() const home = await tempRepo() const outside = await tempRepo() try { await mkdir(join(root, '.git'), { recursive: true }) - await write(join(outside, 'secret.txt'), 'outside secret') - await symlink(join(outside, 'secret.txt'), join(root, 'AGENTS.md')) + await write(join(outside, 'shared.md'), 'shared instruction body') + await symlink(join(outside, 'shared.md'), join(root, 'AGENTS.md')) const files = await discoverBaselineInstructionFiles({ cwd: root, dshHome: home }) const loaded = await loadBaselineInstructions({ cwd: root, dshHome: home, maxBytes: 65536 }) - expect(files).toEqual([]) - expect(loaded).toBeUndefined() + expect(files.map(file => file.displayPath)).toContain('AGENTS.md') + expect(loaded?.text).toContain('shared instruction body') } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -451,21 +425,21 @@ describe('workspace context instruction discovery', () => { } }) - it('rejects symlinked instruction files through ctx.fs instead of following repository-controlled links', async () => { + it('follows a symlinked instruction file through ctx.fs to its target content', async () => { const root = await tempRepo() const home = await tempRepo() const outside = await tempRepo() try { await mkdir(join(root, '.git'), { recursive: true }) - await write(join(outside, 'secret.txt'), 'outside secret') - await symlink(join(outside, 'secret.txt'), join(root, 'AGENTS.md')) + await write(join(outside, 'shared.md'), 'shared provider instruction body') + await symlink(join(outside, 'shared.md'), join(root, 'AGENTS.md')) const ctx = new Context() await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) const agent = stubAgent(root) await composeBaselinePrefix(ctx, agent) - expectNoDerivedMessages(agent) + expect(derivedText(agent)).toContain('shared provider instruction body') } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -511,7 +485,7 @@ describe('workspace context instruction discovery', () => { } }) - it('uses the configured instruction candidate order without hard-coding AGENTS.md priority', async () => { + it('loads every configured instruction candidate in configured order without hard-coding AGENTS.md priority', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -526,7 +500,7 @@ describe('workspace context instruction discovery', () => { instructionFileCandidates: ['CLAUDE.local.md', 'AGENTS.md', 'CLAUDE.md'], }) - expect(files.map(file => file.displayPath)).toEqual(['CLAUDE.local.md']) + expect(files.map(file => file.displayPath)).toEqual(['CLAUDE.local.md', 'AGENTS.md', 'CLAUDE.md']) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -556,6 +530,12 @@ describe('workspace context instruction discovery', () => { it('defaults dshHome and uses cwd itself as root when no project marker exists', async () => { const root = await tempRepo() + const emptyHome = await tempRepo() + // Isolate the default-home fallback: blank DSH_HOME is treated as unset, and + // HOME points at an empty dir so the default ~/.dsh holds no global scope. + // Symlinks are now followed, so a real ~/.dsh/AGENTS.md would otherwise leak in. + vi.stubEnv('DSH_HOME', '') + vi.stubEnv('HOME', emptyHome) try { const cwd = join(root, 'child') await mkdir(cwd, { recursive: true }) @@ -567,7 +547,9 @@ describe('workspace context instruction discovery', () => { expect(files.map(file => file.displayPath)).toEqual(['AGENTS.md']) expect(files.map(file => file.absolutePath)).toEqual([join(cwd, 'AGENTS.md')]) } finally { + vi.unstubAllEnvs() await rm(root, { recursive: true, force: true }) + await rm(emptyHome, { recursive: true, force: true }) } }) @@ -596,7 +578,6 @@ describe('workspace context instruction discovery', () => { vi.resetModules() vi.doMock('node:os', () => ({ homedir: () => home })) - vi.stubEnv('DSH_HOME', undefined) const isolated = await import('@deepseek-ai/dsh-workspace-context') const files = await isolated.discoverBaselineInstructionFiles({ cwd: root }) @@ -604,7 +585,6 @@ describe('workspace context instruction discovery', () => { } finally { vi.doUnmock('node:os') vi.resetModules() - vi.unstubAllEnvs() await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) } @@ -871,7 +851,7 @@ describe('workspace context request injection', () => { try { await ctx.plugin(workspaceContext, { maxBytes: 65536 }) - const decision = await postExecute(ctx, stubToolExecution({ + const decision = await ctx.waterfall('tools/post-execute', stubToolExecution({ signal: testToolSignal, callId: CallId('no-fs-post-execute'), name: 'read', @@ -920,7 +900,7 @@ describe('workspace context request injection', () => { } // A later PostToolUse-style policy blocks this otherwise-successful read. - const blocked = await postExecute(ctx, exec, result, async () => ({ + const blocked = await ctx.waterfall('tools/post-execute', exec, result, async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'blocked by policy' }], })) @@ -934,7 +914,7 @@ describe('workspace context request injection', () => { // The same read, when the downstream accepts, DOES surface the nested // instructions — proving the block branch above is what suppressed them, // and that the block did not consume the pending nested change. - const accepted = await postExecute(ctx, exec, result, async () => ({ + const accepted = await ctx.waterfall('tools/post-execute', exec, result, async () => ({ kind: 'accept' as const, })) expect(accepted.kind).toBe('accept') @@ -1009,7 +989,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('omitted AGENTS.md') - expect(derivedText(agent)).toContain(`Instructions from: ${join('pkg', 'AGENTS.md')}\n\npackage rule`) + expect(derivedText(agent)).toContain('Instructions from: pkg/AGENTS.md\n\npackage rule') } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -1059,7 +1039,7 @@ describe('workspace context request injection', () => { }) expect(workspaceContextOf(result)?.meta).toMatchObject({ - changes: [{ action: 'replace', scope: '.', path: 'AGENTS.md' }], + changes: [{ action: 'replace', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' }], }) expect(blocksText(workspaceContextOf(result)?.content)).toContain('Updated instructions from: AGENTS.md') expect(blocksText(workspaceContextOf(result)?.content)).toContain('new root rule with more detail') @@ -1088,7 +1068,7 @@ describe('workspace context request injection', () => { }) expect(workspaceContextOf(result)?.meta).toMatchObject({ - changes: [{ action: 'remove', scope: '.', path: 'AGENTS.md' }], + changes: [{ action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' }], }) expect(blocksText(workspaceContextOf(result)?.content)).toContain('Instructions removed: AGENTS.md') } finally { @@ -1120,6 +1100,32 @@ describe('workspace context request injection', () => { } }) + it('deduplicates trimmed-identical sibling candidates in one directory and renders the earliest original bytes', async () => { + const root = await tempRepo() + const home = await tempRepo() + try { + await mkdir(join(root, '.git'), { recursive: true }) + await write(join(root, 'AGENTS.md'), 'shared repo rule') + await write(join(root, 'CLAUDE.md'), ' shared repo rule\n\n') + await write(join(root, 'file.txt'), 'hello') + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + const agent = stubAgent(root) + + await composeBaselinePrefix(ctx, agent) + + const text = derivedText(agent) + expect(text.match(/shared repo rule/g)).toHaveLength(1) + expect(text).toContain('Instructions from: AGENTS.md') + expect(text).not.toContain('Instructions from: CLAUDE.md') + // The kept candidate's original bytes are rendered, not the whitespace-padded duplicate. + expect(text).not.toContain(' shared repo rule') + } finally { + await rm(root, { recursive: true, force: true }) + await rm(home, { recursive: true, force: true }) + } + }) + it('does not expose state markers when a tiny budget reduces the baseline contribution', async () => { const root = await tempRepo() const home = await tempRepo() @@ -1268,9 +1274,8 @@ describe('workspace context request injection', () => { const controller = new AbortController() const reason = new Error('cancel prefix') const empty: Message[] = [] - const agent = stubAgent(root) - const pending = agentEvents(ctx, agent).waterfall( - 'agent/session-prefix', empty, controller.signal, + const pending = ctx.waterfall( + 'agent/session-prefix', stubAgent(root), empty, controller.signal, () => Promise.resolve(empty), ) @@ -1337,30 +1342,6 @@ describe('workspace context request injection', () => { } }) - it('skips provider-visible instruction candidates when ctx.fs stat disagrees after no-follow preflight', async () => { - const root = await tempRepo() - const home = await tempRepo() - try { - await mkdir(join(root, '.git'), { recursive: true }) - await write(join(root, 'AGENTS.md'), 'node fs rule') - const ctx = new Context() - await ctx.plugin(RecordingFileSystem) - const fs = ctx.fs as RecordingFileSystem - fs.entries.set(join(root, '.git'), { type: 'directory' }) - fs.entries.set(join(root, 'AGENTS.md'), { type: 'directory' }) - fs.lstatTypes.set(join(root, 'AGENTS.md'), 'file') - await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 }) - const agent = stubAgent(root) - - await composeBaselinePrefix(ctx, agent) - - expectNoDerivedMessages(agent) - } finally { - await rm(root, { recursive: true, force: true }) - await rm(home, { recursive: true, force: true }) - } - }) - it('loads instruction files when ctx.fs omits the metadata size', async () => { const root = await tempRepo() const home = await tempRepo() @@ -1407,7 +1388,7 @@ describe('workspace context request injection', () => { } }) - it('does not fall through to a lower-priority candidate when the winning provider file becomes unavailable', async () => { + it('skips a candidate whose provider probe fails while still loading its available sibling', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -1415,16 +1396,16 @@ describe('workspace context request injection', () => { await ctx.plugin(RecordingFileSystem) const fs = ctx.fs as RecordingFileSystem fs.entries.set(join(root, '.git'), { type: 'directory' }) - fs.lstatTypes.set(join(root, 'AGENTS.md'), 'file') fs.throwOnStat.add(join(root, 'AGENTS.md')) - fs.entries.set(join(root, 'CLAUDE.md'), { type: 'file', content: 'must not bypass AGENTS failure' }) + fs.entries.set(join(root, 'CLAUDE.md'), { type: 'file', content: 'claude sibling rule' }) await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 }) const agent = stubAgent(root) await composeBaselinePrefix(ctx, agent) - expectNoDerivedMessages(agent) - expect(fs.readTargets).not.toContain(join(root, 'CLAUDE.md')) + expect(derivedText(agent)).toContain('claude sibling rule') + expect(fs.readTargets).toContain(join(root, 'CLAUDE.md')) + expect(fs.readTargets).not.toContain(join(root, 'AGENTS.md')) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -1498,7 +1479,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('Instructions from: AGENTS.md\n\nroot schema default rule') - expect(derivedText(agent)).toContain(`Instructions from: ${join('child', 'AGENTS.md')}\n\nchild schema default rule`) + expect(derivedText(agent)).toContain('Instructions from: child/AGENTS.md\n\nchild schema default rule') await ctx.fiber.dispose() } finally { await rm(root, { recursive: true, force: true }) @@ -1629,9 +1610,9 @@ describe('workspace context request injection', () => { const actual = await importOriginal() return { ...actual, - lstat: async (path: string) => { + stat: async (path: string) => { observedStats.set(path, (observedStats.get(path) ?? 0) + 1) - return actual.lstat(path) + return actual.stat(path) }, } }) @@ -1649,22 +1630,22 @@ describe('workspace context request injection', () => { } }) - it('does not bypass an unavailable host AGENTS.md with a lower-priority candidate', async () => { + it('skips an unavailable host candidate but still loads its available sibling', async () => { const root = await tempRepo() const home = await tempRepo() try { await mkdir(join(root, '.git'), { recursive: true }) - await write(join(root, 'CLAUDE.md'), 'must not bypass unavailable AGENTS') + await write(join(root, 'CLAUDE.md'), 'claude host sibling rule') vi.resetModules() vi.doMock('node:fs/promises', async (importOriginal) => { const actual = await importOriginal() return { ...actual, - lstat: async (path: string) => { + stat: async (path: string) => { if (path === join(root, 'AGENTS.md')) { throw Object.assign(new Error('permission denied'), { code: 'EACCES' }) } - return actual.lstat(path) + return actual.stat(path) }, } }) @@ -1672,7 +1653,7 @@ describe('workspace context request injection', () => { const rendered = await isolated.loadBaselineInstructions({ cwd: root, dshHome: home, maxBytes: 65536 }) - expect(rendered).toBeUndefined() + expect(rendered?.text).toContain('claude host sibling rule') } finally { vi.doUnmock('node:fs/promises') vi.resetModules() @@ -1718,7 +1699,7 @@ describe('dynamic nested workspace context injection', () => { description: 'Abort the current test step.', parameters: {}, async execute() { - agent.cancel({ kind: 'user' }) + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('test abort') return [{ type: 'text', text: 'aborted' }] }, })) @@ -1751,7 +1732,7 @@ describe('dynamic nested workspace context injection', () => { content: 'root rule', }]) - const change = state.changes.get('.') + const change = state.changes.get(sk('.', 'AGENTS.md')) expect(change).toMatchObject({ action: 'set', path: 'AGENTS.md', @@ -1781,7 +1762,7 @@ describe('dynamic nested workspace context injection', () => { signal: controller.signal, }) - const pending = postExecute(ctx, exec, { + const pending = ctx.waterfall('tools/post-execute', exec, { content: [{ type: 'text', text: 'ok' }], isError: false, }, () => Promise.resolve({ kind: 'accept' as const })) @@ -1822,8 +1803,8 @@ describe('dynamic nested workspace context injection', () => { version: 1, changes: [{ action: 'set', - scope: 'pkg', - path: join('pkg', 'AGENTS.md'), + scope: sk('pkg', 'AGENTS.md'), + path: 'pkg/AGENTS.md', }], }) const meta = workspaceContextOf(result)?.meta @@ -1837,7 +1818,7 @@ describe('dynamic nested workspace context injection', () => { const text = blocksText(workspaceContextOf(result)?.content) expect(text).toBe([ '', - `Additional instructions from: ${join('pkg', 'AGENTS.md')}`, + 'Additional instructions from: pkg/AGENTS.md', '', 'These instructions apply to work under `pkg`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.', '', @@ -1852,7 +1833,7 @@ describe('dynamic nested workspace context injection', () => { } }) - it('uses configured instruction candidates for nested discovery', async () => { + it('loads every configured instruction candidate present in a nested scope', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -1876,9 +1857,11 @@ describe('dynamic nested workspace context injection', () => { }) const text = blocksText(workspaceContextOf(result)?.content) - expect(text).toContain(`Additional instructions from: ${join('pkg', 'CLAUDE.local.md')}`) + expect(text).toContain('Additional instructions from: pkg/CLAUDE.local.md') expect(text).toContain('local package rule') - expect(text).not.toContain('native package rule') + expect(text).toContain('Additional instructions from: pkg/AGENTS.md') + expect(text).toContain('native package rule') + expect(text.indexOf('pkg/CLAUDE.local.md')).toBeLessThan(text.indexOf('pkg/AGENTS.md')) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -1898,6 +1881,7 @@ describe('dynamic nested workspace context injection', () => { await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) const result = await ctx.tools.execute({ + signal: testToolSignal, callId: CallId('read-nested-overlay'), name: 'read', arguments: { file_path: 'pkg/deep/file.txt' }, @@ -1939,6 +1923,7 @@ describe('dynamic nested workspace context injection', () => { }) const result = await ctx.tools.execute({ + signal: testToolSignal, callId: CallId('read-nested-overlay-disabled'), name: 'read', arguments: { file_path: 'pkg/deep/file.txt' }, @@ -2126,11 +2111,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(changed)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], + changes: [{ action: 'replace', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) expect(blocksText(workspaceContextOf(changed)?.content)).toBe([ '', - `Updated instructions from: ${join('pkg', 'AGENTS.md')}`, + 'Updated instructions from: pkg/AGENTS.md', '', 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.', '', @@ -2143,13 +2128,13 @@ describe('dynamic nested workspace context injection', () => { } }) - it('replaces an AGENTS candidate with the configured fallback in the same scope', async () => { + it('reconciles distinct sibling candidates as independent scopes', async () => { const root = await tempRepo() const home = await tempRepo() try { await mkdir(join(root, '.git'), { recursive: true }) await write(join(root, 'pkg/AGENTS.md'), 'native package rule') - await write(join(root, 'pkg/CLAUDE.md'), 'fallback package rule') + await write(join(root, 'pkg/CLAUDE.md'), 'sibling package rule') await write(join(root, 'pkg/file.txt'), 'hello') const ctx = new Context() await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) @@ -2157,29 +2142,129 @@ describe('dynamic nested workspace context injection', () => { const first = await ctx.tools.execute({ signal: testToolSignal, - callId: CallId('read-before-fallback'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + callId: CallId('read-both-siblings'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, }) + const firstText = blocksText(workspaceContextOf(first)?.content) + expect(firstText).toContain('native package rule') + expect(firstText).toContain('sibling package rule') appendAdditionalContexts(agent, first) await rm(join(root, 'pkg/AGENTS.md')) - const changed = await ctx.tools.execute({ + const removed = await ctx.tools.execute({ signal: testToolSignal, - callId: CallId('read-after-fallback'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, - }) - appendAdditionalContexts(agent, changed) - const unchanged = await ctx.tools.execute({ - signal: testToolSignal, - callId: CallId('read-after-logged-fallback'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + callId: CallId('read-after-one-sibling-removed'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, }) - expect(workspaceContextOf(changed)?.meta).toMatchObject({ - changes: [{ - action: 'replace', scope: 'pkg', path: join('pkg', 'CLAUDE.md'), previousPath: join('pkg', 'AGENTS.md'), - }], + // Removing one candidate only removes its own scope; the sibling scope is untouched. + expect(workspaceContextOf(removed)?.meta).toMatchObject({ + changes: [{ action: 'remove', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) - expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`Updated instructions from: ${join('pkg', 'CLAUDE.md')}`) - expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`The instructions previously loaded from \`${join('pkg', 'AGENTS.md')}\` no longer apply. Use the following content for \`pkg\` instead.`) - expect(blocksText(workspaceContextOf(changed)?.content)).toContain('fallback package rule') - expect(unchanged.additionalContexts).toBeUndefined() + expect(blocksText(workspaceContextOf(removed)?.content)).toContain('Instructions removed: pkg/AGENTS.md') + expect(blocksText(workspaceContextOf(removed)?.content)).not.toContain('sibling package rule') + } finally { + await rm(root, { recursive: true, force: true }) + await rm(home, { recursive: true, force: true }) + } + }) + + it('drops a newly discovered sibling whose content duplicates an earlier candidate in the scope', async () => { + const root = await tempRepo() + const home = await tempRepo() + try { + await mkdir(join(root, '.git'), { recursive: true }) + await write(join(root, 'pkg/AGENTS.md'), 'nested rule') + await write(join(root, 'pkg/CLAUDE.md'), 'nested rule') + await write(join(root, 'pkg/deep/file.txt'), 'hello') + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + const agent = stubAgent(root) + + const result = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-nested-dup-siblings'), name: 'read', arguments: { file_path: 'pkg/deep/file.txt' }, agent, + }) + + expect(workspaceContextOf(result)?.meta).toMatchObject({ + changes: [{ action: 'set', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], + }) + const text = blocksText(workspaceContextOf(result)?.content) + expect(text.match(/nested rule/g)).toHaveLength(1) + expect(text).toContain('Additional instructions from: pkg/AGENTS.md') + expect(text).not.toContain('pkg/CLAUDE.md') + } finally { + await rm(root, { recursive: true, force: true }) + await rm(home, { recursive: true, force: true }) + } + }) + + it('removes a previously rendered sibling once its content becomes a duplicate of an earlier candidate', async () => { + const root = await tempRepo() + const home = await tempRepo() + try { + await mkdir(join(root, '.git'), { recursive: true }) + await write(join(root, 'pkg/AGENTS.md'), 'canonical nested rule') + await write(join(root, 'pkg/CLAUDE.md'), 'divergent nested rule') + await write(join(root, 'pkg/file.txt'), 'hello') + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + const agent = stubAgent(root) + + const first = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-before-dup-convergence'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + const firstText = blocksText(workspaceContextOf(first)?.content) + expect(firstText).toContain('canonical nested rule') + expect(firstText).toContain('divergent nested rule') + appendAdditionalContexts(agent, first) + await write(join(root, 'pkg/CLAUDE.md'), 'canonical nested rule') + const converged = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-after-dup-convergence'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + + expect(workspaceContextOf(converged)?.meta).toMatchObject({ + changes: [{ action: 'remove', scope: sk('pkg', 'CLAUDE.md'), path: 'pkg/CLAUDE.md' }], + }) + expect(blocksText(workspaceContextOf(converged)?.content)).toContain('Instructions removed: pkg/CLAUDE.md') + } finally { + await rm(root, { recursive: true, force: true }) + await rm(home, { recursive: true, force: true }) + } + }) + + it('removes an unchanged sibling when an earlier candidate changes to match its content', async () => { + const root = await tempRepo() + const home = await tempRepo() + try { + await mkdir(join(root, '.git'), { recursive: true }) + await write(join(root, 'pkg/AGENTS.md'), 'primary nested rule') + await write(join(root, 'pkg/CLAUDE.md'), 'secondary nested rule') + await write(join(root, 'pkg/file.txt'), 'hello') + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + const agent = stubAgent(root) + + const first = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-before-earlier-converges'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + appendAdditionalContexts(agent, first) + // Only the earlier candidate changes; the sibling stays byte-identical but now duplicates it. + await write(join(root, 'pkg/AGENTS.md'), 'secondary nested rule') + const converged = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-after-earlier-converges'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + + expect(workspaceContextOf(converged)?.meta).toMatchObject({ + changes: [ + { action: 'replace', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }, + { action: 'remove', scope: sk('pkg', 'CLAUDE.md'), path: 'pkg/CLAUDE.md' }, + ], + }) + const text = blocksText(workspaceContextOf(converged)?.content) + expect(text).toContain('Instructions removed: pkg/CLAUDE.md') + expect(text).toContain('Updated instructions from: pkg/AGENTS.md') } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -2211,11 +2296,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(removed)?.meta).toEqual({ kind: 'workspace-instructions', version: 1, - changes: [{ action: 'remove', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], + changes: [{ action: 'remove', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) expect(blocksText(workspaceContextOf(removed)?.content)).toBe([ '', - `Instructions removed: ${join('pkg', 'AGENTS.md')}`, + 'Instructions removed: pkg/AGENTS.md', '', 'The previously loaded instructions from this file no longer apply.', '', @@ -2226,6 +2311,45 @@ describe('dynamic nested workspace context injection', () => { } }) + it('removes a previously loaded instruction file once it resolves to a directory through a symlink', async () => { + const root = await tempRepo() + const home = await tempRepo() + try { + await mkdir(join(root, '.git'), { recursive: true }) + await write(join(root, 'pkg/AGENTS.md'), 'package rule') + await write(join(root, 'pkg/file.txt'), 'hello') + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) + const agent = stubAgent(root) + + const first = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-before-symlink-dir'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + appendAdditionalContexts(agent, first) + expect(blocksText(workspaceContextOf(first)?.content)).toContain('package rule') + + // The candidate now resolves through a symlink to a directory. A non-file + // target is a confirmed absence (not unavailable), so the loaded scope is + // removed; an unavailable classification would emit no change at all. + await rm(join(root, 'pkg/AGENTS.md')) + await mkdir(join(root, 'pkg/elsewhere'), { recursive: true }) + await symlink(join(root, 'pkg/elsewhere'), join(root, 'pkg/AGENTS.md')) + const removed = await ctx.tools.execute({ + signal: testToolSignal, + callId: CallId('read-after-symlink-dir'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, + }) + + expect(workspaceContextOf(removed)?.meta).toMatchObject({ + changes: [{ action: 'remove', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], + }) + expect(blocksText(workspaceContextOf(removed)?.content)).toContain('Instructions removed: pkg/AGENTS.md') + } finally { + await rm(root, { recursive: true, force: true }) + await rm(home, { recursive: true, force: true }) + } + }) + it('loads a candidate again after a logged removal tombstone', async () => { const root = await tempRepo() const home = await tempRepo() @@ -2256,9 +2380,9 @@ describe('dynamic nested workspace context injection', () => { }) expect(workspaceContextOf(restored)?.meta).toMatchObject({ - changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], + changes: [{ action: 'set', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) - expect(blocksText(workspaceContextOf(restored)?.content)).toContain(`Additional instructions from: ${join('pkg', 'AGENTS.md')}`) + expect(blocksText(workspaceContextOf(restored)?.content)).toContain('Additional instructions from: pkg/AGENTS.md') expect(blocksText(workspaceContextOf(restored)?.content)).toContain('restored package rule') } finally { await rm(root, { recursive: true, force: true }) @@ -2363,7 +2487,7 @@ describe('dynamic nested workspace context injection', () => { const update = resumed.session.events.findLast(event => event.type === 'context/message') expect(update?.type === 'context/message' && update.data.meta).toMatchObject({ - changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], + changes: [{ action: 'replace', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume') } finally { @@ -2491,8 +2615,8 @@ describe('dynamic nested workspace context injection', () => { }) const firstText = blocksText(workspaceContextOf(first)?.content) - expect(firstText).toContain(`omitted ${join('pkg', 'AGENTS.md')}`) - expect(firstText).not.toContain(`## ${join('pkg', 'AGENTS.md')}`) + expect(firstText).toContain('omitted pkg/AGENTS.md') + expect(firstText).not.toContain('## pkg/AGENTS.md') expect(firstText).toContain('subtree rule') expect(blocksText(workspaceContextOf(second)?.content)).toContain('parent rule') } finally { @@ -2524,7 +2648,6 @@ describe('dynamic nested workspace context injection', () => { null, { action: 'unknown', scope: 'pkg', path: 'pkg/AGENTS.md' }, { action: 'set', scope: 'pkg', path: 42 }, - { action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md', previousPath: 42 }, { action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md', digest: 42 }, ], }, @@ -2594,7 +2717,7 @@ describe('dynamic nested workspace context injection', () => { } }) - it('treats provider failures and type disagreement after lstat as unavailable, not removed', async () => { + it('treats a reconciliation provider failure as unavailable and a resolved non-file as absent', async () => { const root = await tempRepo() const home = await tempRepo() const ctx = new Context() @@ -2602,7 +2725,6 @@ describe('dynamic nested workspace context injection', () => { await ctx.plugin(RecordingFileSystem) const fs = ctx.fs as RecordingFileSystem fs.entries.set(join(root, '.git'), { type: 'directory' }) - fs.lstatTypes.set(join(root, 'pkg/AGENTS.md'), 'file') fs.throwOnStat.add(join(root, 'pkg/AGENTS.md')) await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 }) const agent = stubAgent(root) @@ -2612,13 +2734,13 @@ describe('dynamic nested workspace context injection', () => { isError: false, } - const failedStat = await postExecute(ctx, stubToolExecution({ + const failedStat = await ctx.waterfall('tools/post-execute', stubToolExecution({ signal: testToolSignal, callId: CallId('provider-stat-failure'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, }), result, async () => ({ kind: 'accept' as const })) fs.throwOnStat.clear() fs.entries.set(join(root, 'pkg/AGENTS.md'), { type: 'directory' }) - const mismatchedStat = await postExecute(ctx, stubToolExecution({ + const mismatchedStat = await ctx.waterfall('tools/post-execute', stubToolExecution({ signal: testToolSignal, callId: CallId('provider-stat-mismatch'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent, }), result, async () => ({ kind: 'accept' as const })) @@ -2635,19 +2757,14 @@ describe('dynamic nested workspace context injection', () => { it('skips unreadable nested instruction files without attaching empty context', async () => { const root = await tempRepo() const home = await tempRepo() - const ctx = new Context() try { + await mkdir(join(root, '.git'), { recursive: true }) const nested = join(root, 'pkg/AGENTS.md') - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - await ctx.plugin(RecordingFileSystem) - const fs = ctx.fs as RecordingFileSystem - fs.entries.set(join(root, '.git'), { type: 'directory' }) - fs.entries.set(nested, { type: 'file', content: 'nested package rule' }) - fs.entries.set(join(root, 'pkg/deep/file.txt'), { type: 'file', content: 'hello' }) - fs.throwOnRead.add(nested) - await ctx.plugin(ToolFs) - await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 }) + await write(nested, 'nested package rule') + await write(join(root, 'pkg/deep/file.txt'), 'hello') + await chmod(nested, 0) + const ctx = new Context() + await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 }) const result = await ctx.tools.execute({ signal: testToolSignal, @@ -2659,9 +2776,8 @@ describe('dynamic nested workspace context injection', () => { expect(result.isError).toBe(false) expect(result.additionalContexts).toBeUndefined() - expect(fs.readTargets).toContain(nested) + await chmod(nested, 0o600) } finally { - await ctx.fiber.dispose() await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) } @@ -2698,7 +2814,7 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(result)?.source).toEqual({ kind: 'plugin', plugin: 'workspace-context' }) expect(workspaceContextOf(result)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], + changes: [{ action: 'set', scope: sk('pkg', 'AGENTS.md'), path: 'pkg/AGENTS.md' }], }) expect(blocksText(workspaceContextOf(result)?.content)).toContain('nested package rule') expect(blocksText(workspaceContextOf(result)?.content)).not.toContain('downstream context') @@ -2816,12 +2932,13 @@ describe('dynamic nested workspace context injection', () => { parameters: {}, async execute(_args, exec) { const nested = await ctx.tools.execute({ + signal: testToolSignal, callId: CallId(`${exec.callId}:nested`), name: 'read', arguments: { file_path: 'pkg/deep/file.txt' }, ...exec.agent === undefined ? {} : { agent: exec.agent }, parent: exec.token, - signal: exec.signal, + ...exec.signal === undefined ? {} : { signal: exec.signal }, }) for (const context of nested.additionalContexts ?? []) exec.deferContext(context) return nested.content @@ -2866,23 +2983,23 @@ describe('dynamic nested workspace context injection', () => { const parent = Symbol('parent') as ToolExecutionToken const plainResult = { callId: CallId('plain'), content: [], isError: false } - emitToolResult(ctx, stubToolExecution({ + ctx.emit('tools/result', stubToolExecution({ signal: testToolSignal, callId: CallId('agentless-child'), name: 'read', arguments: {}, parent, }), plainResult) - emitToolResult(ctx, stubToolExecution({ + ctx.emit('tools/result', stubToolExecution({ signal: testToolSignal, callId: CallId('contextless-child'), name: 'read', arguments: {}, agent, parent, }), { ...plainResult, additionalContexts: [{ content: [], source: { kind: 'plugin', plugin: 'workspace-context' } }] }) - emitToolResult(ctx, stubToolExecution({ + ctx.emit('tools/result', stubToolExecution({ signal: testToolSignal, callId: CallId('first-child'), name: 'read', arguments: {}, agent, parent, }), { ...plainResult, additionalContexts: [workspaceChangeContext('first', 'one')] }) - emitToolResult(ctx, stubToolExecution({ + ctx.emit('tools/result', stubToolExecution({ signal: testToolSignal, callId: CallId('second-child'), name: 'read', arguments: {}, agent, parent, }), { ...plainResult, additionalContexts: [workspaceChangeContext('second', 'two')] }) - emitToolResult(ctx, { + ctx.emit('tools/result', { ...stubToolExecution({ signal: testToolSignal, callId: CallId('agentless-parent'), name: 'composite', arguments: {} }), token: parent, }, plainResult) @@ -2918,7 +3035,7 @@ describe('dynamic nested workspace context injection', () => { ] for (const item of cases) { - const decision = await postExecute(ctx, stubToolExecution({ + const decision = await ctx.waterfall('tools/post-execute', stubToolExecution({ signal: testToolSignal, callId: CallId(`manual-${item.name}-${cases.indexOf(item)}`), name: item.name, @@ -3042,7 +3159,7 @@ describe('workspace context pending state', () => { const [change] = commitPendingInstructionContexts(agent, [workspaceChangeContext('pkg', 'one')], pending) expect(change).toBeDefined() versions.set(agent.session, new Map([['pkg', { - path: 'pkg/AGENTS.md', version: FsVersion('v1'), digest: 'one', + path: 'pkg/AGENTS.md', version: FsVersion('v1'), digest: 'one', trimmedDigest: 'one', }]])) const unrelated = agent.session.append('context/message', { @@ -3079,7 +3196,7 @@ describe('workspace context pending state', () => { agent.session.append('step/start', { turn: 1, step: 1 }) commitPendingInstructionContexts(agent, [workspaceChangeContext('pkg', 'one')], pending) versions.set(agent.session, new Map([['pkg', { - path: 'pkg/AGENTS.md', version: FsVersion('v1'), digest: 'one', + path: 'pkg/AGENTS.md', version: FsVersion('v1'), digest: 'one', trimmedDigest: 'one', }]])) const ended = agent.session.append('step/end', { turn: 1, step: 1 })