Merge branch 'worktree-llm-dynamic-config' into worktree-llm-web-config
# Conflicts: # apps/cli/cordis.yml # apps/web/tests/snapshots/code-mode-round/session.jsonl # apps/web/tests/snapshots/cordis-tool-round/session.jsonl # apps/web/tests/snapshots/fresh-round-trip/session.jsonl # apps/web/tests/snapshots/lifecycle-chrome/session.jsonl # apps/web/tests/snapshots/live-interactions/session.jsonl # apps/web/tests/snapshots/navigation-panes/seed.jsonl # apps/web/tests/snapshots/question-composer/session.jsonl # apps/web/tests/snapshots/seeded-history/seed.jsonl # apps/web/tests/snapshots/steering/session.jsonl # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/settings.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/workspace-context/session.jsonl # packages/client/connection/README.i18n.yaml # packages/client/connection/src/index.ts # packages/client/connection/tests/node-half.spec.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/runtime/src/client/index.ts # packages/client/runtime/tests/fake-api.ts # packages/client/ui-models/README.i18n.yaml # packages/examples/tui-demo/README.i18n.yaml # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/package.json # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/rpc.schema.ts # packages/host/apiproxy/src/api/rpc.ts # packages/llm/llm-deepseek/README.i18n.yaml # packages/llm/llm-deepseek/README.zh.md # packages/llm/llm-pi-ai/README.i18n.yaml # packages/llm/llm/README.i18n.yaml # packages/llm/llm/README.zh.md # packages/sdk/sdk-client/README.i18n.yaml # packages/settings/settings/README.i18n.yaml # packages/settings/settings/README.md # packages/settings/settings/README.zh.md # packages/subagent/subagent-dsh-sdk/README.i18n.yaml # packages/subagent/subagent-dsh-sdk/README.zh.md # packages/support/llm-replay/README.i18n.yaml # packages/ui/jsonrpc/README.i18n.yaml # packages/ui/jsonrpc/README.zh.md # packages/ui/tui/tests/snapshots/model-selector.expected.txt # packages/ui/tui/tests/snapshots/model-switching.expected.txt # packages/ui/tui/tests/snapshots/resume-sessions.expected.txt # packages/ui/tui/tests/snapshots/status-diagnostics-narrow.expected.txt # packages/ui/tui/tests/snapshots/status-diagnostics.expected.txt # packages/ui/tui/tests/tui.snapshot.ts # pnpm-lock.yaml # python/sdk/README.i18n.yaml # scripts/snapshots/translation-prompt-v4/request-response.expected.json
This commit is contained in:
Yichen Jiang
@@ -1,6 +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
|
||||
README.md: a5244dfe99a714605744b57d33f97359d4d6fa4e
|
||||
README.zh.md: 2c1bdd6e5b290a771094719daa6e4d7c3bf577db
|
||||
# pnpm run verify-translation-pairing --write packages/context/README.md
|
||||
README.md: fce6e21816d261171aaeaa217171580adb7c43f9
|
||||
README.zh.md: b8a4d68ca6892b51ed52479a7296513f5edcc292
|
||||
|
||||
@@ -2,12 +2,13 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Product plugins that add model-visible request context without defining a tool. `workspace-context` is included by the default `dsh-agent-spine-demo` bundle and can be disabled through bundle config; `time-context` is opt-in, while the standard TUI bundle composes `session-reference` explicitly.
|
||||
Product plugins that add model-visible request context without defining a tool. `workspace-context` is included by the default `dsh-agent-spine-demo` bundle and can be disabled through bundle config; `time-context` and `tmux-context` are opt-in, while the standard TUI bundle composes `session-reference` explicitly.
|
||||
|
||||
| Package | Role | ctx key |
|
||||
|---|---|---|
|
||||
| `session-reference/` | Bounded current-surface snapshots of other sessions | `ctx.sessionReferences` |
|
||||
| `time-context/` | Durable per-step current time and elapsed-time context | (none) |
|
||||
| `tmux-context/` | Durable per-turn context with this agent's tmux pane/window location | (listens on `agent/step`, reads `ctx.bash`) |
|
||||
| `workspace-context/` | `AGENTS.md`/`CLAUDE.md` workspace context loader | (listens on `agent/step` + `tools/post-execute`) |
|
||||
|
||||
The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
|
||||
|
||||
@@ -2,12 +2,13 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
这些产品插件无需定义工具，即可增加模型可见的请求上下文。`workspace-context` 包含在默认的 `dsh-agent-spine-demo` 组合包中，且可通过组合包配置将其禁用；`time-context` 需要选择启用，标准 TUI 组合包则会显式组合 `session-reference`。
|
||||
这些产品插件无需定义工具，即可增加模型可见的请求上下文。`workspace-context` 包含在默认的 `dsh-agent-spine-demo` 组合包中，且可通过组合包配置将其禁用；`time-context` 与 `tmux-context` 均需显式启用，标准 TUI 组合包则会显式组合 `session-reference`。
|
||||
|
||||
| 包 | 职责 | ctx key |
|
||||
|---|---|---|
|
||||
| `session-reference/` | 其他会话当前表层的有界快照 | `ctx.sessionReferences` |
|
||||
| `time-context/` | 持久的逐步骤当前时间与耗时上下文 | （无） |
|
||||
| `time-context/` | 持久化的逐步骤当前时间与已用时上下文 | （无） |
|
||||
| `tmux-context/` | 持久化的逐轮次上下文，记录本 agent 所在的 tmux pane/window 位置 | （监听 `agent/step`，读取 `ctx.bash`） |
|
||||
| `workspace-context/` | `AGENTS.md`／`CLAUDE.md` 工作区上下文 loader | （监听 `agent/step` + `tools/post-execute`） |
|
||||
|
||||
[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释了它的逐 agent／会话隔离与生命周期拆分。
|
||||
[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释了每个 agent（智能体）和会话各自隔离的方式，以及相应的生命周期拆分。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/context/session-reference/README.md
|
||||
README.md: 66df45b18df6d859239c8d3216d6c8b9fa61ab23
|
||||
README.zh.md: 7431f1375d50f4734f3efeea9a2597b7296e38c2
|
||||
README.zh.md: b59a98b86baf88f53429bc2409ad1776b1638736
|
||||
|
||||
@@ -6,13 +6,13 @@
|
||||
|
||||
## 公开 API
|
||||
|
||||
- `listCandidates(agent, query?, limit?)` 会列出 `agent.id` 之外的会话，按 id、cwd 或日志中最新的标题进行不区分大小写的筛选，再按同 cwd、无 cwd、其他 cwd 记录排序，同时保持每组内的 `listSessions()` 创建顺序。每个已选候选会话都使用该标题作为 mention label；标题不存在或无法读取时回退到会话 id。不搜索消息主体。
|
||||
- `prepare(agent, content, references, signal?)` 会保留首次 mention 顺序、对 id 去重，并拒绝自引用或超过已配置不同源上限的情况。它会并行读取所有源，返回与输入脱离的内容，外加零个或一个聚合且带标识的 `UserMessage` 上下文。任何无效引用、读取失败、取消或预算失败都会在宿主调用 `followup()` 或 `steer()` 之前被拒绝。
|
||||
- `encodeSessionReferenceUri()` 与 `decodeSessionReferenceUri()` 实现 `dsh-session:<base64url(JSON.stringify(sessionId))>`，因此每个 JavaScript 字符串 id 都能精确往返。`formatSessionReferenceMention()` 发出 `@[label](uri)`，`parseSessionReferenceText()` 将 Markdown mention 或裸规范 URI 替换为可读的 `@label` 文本，并返回结构化引用。显式 Markdown mention 会拒绝每个格式错误的 URI；只当 scheme 后跟非空、符合 base64url 形状的 payload 时，裸文本才被视为引用，匹配但非规范的候选项仍会失败。空 scheme mention 或只含标点符号的 scheme mention 仍是普通讨论文本。
|
||||
- `listCandidates(agent, query?, limit?)` 会列出 `agent.id` 之外的会话，按 id、cwd 或以日志为依据的最新标题进行不区分大小写的筛选，再按同 cwd、无 cwd、其他 cwd 记录排序，同时保持每组内的 `listSessions()` 创建顺序。每个已选候选会话都使用该标题作为 mention label；标题不存在或无法读取时回退到会话 id。不搜索消息主体。
|
||||
- `prepare(agent, content, references, signal?)` 会保留首次 mention 顺序、对 id 去重，并拒绝自引用或超过已配置不同源上限的情况。它会并行读取所有源，返回与输入脱离的内容，外加零个或一个聚合且带标识的 `UserMessage` 上下文。任何无效引用、读取失败、取消或预算失败，都会使准备操作在宿主调用 `followup()` 或 `steer()` 之前失败。
|
||||
- `encodeSessionReferenceUri()` 与 `decodeSessionReferenceUri()` 实现 `dsh-session:<base64url(JSON.stringify(sessionId))>`，因此每个 JavaScript 字符串 id 都能精确往返。`formatSessionReferenceMention()` 发出 `@[label](uri)`，`parseSessionReferenceText()` 将 Markdown mention 或裸规范 URI 替换为可读的 `@label` 文本，并返回结构化引用。解析器会拒绝显式 Markdown mention 中任何格式错误的 URI；只当 scheme 后跟非空、符合 base64url 形状的 payload 时，裸文本才被视为引用，匹配但非规范的候选项仍会失败。空 scheme mention 或只含标点符号的 scheme mention 仍是普通讨论文本。
|
||||
|
||||
## 快照语义
|
||||
|
||||
准备阶段会对每个不同源调用一次 `ctx.sessionQuery.readSurface()`，入队后绝不重读。它仅投影折叠后当前表层中的直接 user `user/message`、直接 user `steering/message`、assistant 文本，以及 `user/message` 检查点；这类检查点携带规范 `dsh-compact` 源标记。对于已经包含烘焙前缀上下文的源提示词，投影只读取其对模型隐藏的显示内容，以防止快照递归传播。已遮蔽的压缩前事件、工具、reasoning、上下文、除已标记 compact 检查点外的插件生成 user 消息，以及未完成的 assistant chunk 均会被排除。因此，已压缩源贡献的是最新检查点与之后保留的会话，而非已恢复的遮蔽文本。
|
||||
准备阶段会对每个不同源调用一次 `ctx.sessionQuery.readSurface()`，入队后绝不重读。它仅投影折叠后当前表层中的用户直接发出的 `user/message`、用户直接发出的 `steering/message`、assistant 文本，以及 `user/message` 检查点；这类检查点携带规范 `dsh-compact` 源标记。对于已经包含固化前缀上下文的源提示词，投影只读取其对模型隐藏的显示内容，以防止快照递归传播。已遮蔽的压缩（compaction）前事件、工具、推理（reasoning）、上下文、除已标记 compact 检查点外的插件生成 user 消息，以及未完成的 assistant 分片均会被排除。因此，已压缩源只会提供最新检查点及其后保留的会话内容，不会还原已遮蔽的文本。
|
||||
|
||||
上下文源为 `{ kind: 'session-reference', version: 1, references }`；每条引用会记录其源 id 与 label、捕获 seq、是否存在 compact、已保留／已省略消息数、已省略 UTF-8 字节数与截断状态。标准 TUI 在不把上下文附加到通用 inbox 记录的情况下保留接纳归属：next-step 接收窗口之外，一次性 `agent/prompt-submit` 包装层只为获准决策添加快照；提示词接纳期间或轮次打开时，`inject()` 与 `steer()` 会并排暂存到同一安全边界。目标日志因此会先记录一条带来源信息的上下文 `user/message`，再记录可读的直接 `user/message` 或 `steering/message`。后续源变更、压缩或删除都无法改变目标回放。
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
| `candidateLimit` | `50` | 返回给宿主的默认候选数量。 |
|
||||
| `maxReferenceBytes` | `65536` | 一个引用对象的最大序列化 JSON 字节数。 |
|
||||
|
||||
保留会对每个源独立应用 `maxReferenceBytes`，保留 compact 检查点与最新消息，再丢弃较旧的非检查点单元，并使用 `dsh-retention` 头部／尾部截断和精确 UTF-8 省略通知。如果某个源的固定序列化字段无法容纳，准备会以 `SESSION_REFERENCE_BUDGET_EXCEEDED` 失败，而不返回部分上下文。
|
||||
保留会对每个源独立应用 `maxReferenceBytes`，保留 compact 检查点与最新消息，再丢弃较旧的非检查点单元，并使用 `dsh-retention` 头部／尾部截断和精确 UTF-8 省略通知。如果某个源的固定序列化字段本身就超出限额，准备会以 `SESSION_REFERENCE_BUDGET_EXCEEDED` 失败，而不返回部分上下文。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -32,11 +32,11 @@
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
模型会看到两条连续的 user 角色消息：先是 `## Referenced sessions` 不受信任快照，再是带可读 `@label` 的当前消息。警告禁止遵循快照中的指令、权限声明或工具请求，除非当前 user 重复这些内容。Label、cwd 值、id 与会话文本作为 JSON 在 `<referenced-sessions>` 标签中序列化；每个数据 `<` 都发出为无损 JSON 转义 `\u003c`，因此源文本无法拼出框定标签。
|
||||
模型会看到两条连续的 user 角色消息：先是 `## Referenced sessions` 不受信任快照，再是带可读 `@label` 的当前消息。警告禁止遵循快照中的指令、权限声明或工具请求，除非当前 user 重复这些内容。标签、cwd 值、id 与会话文本会作为 JSON 在 `<referenced-sessions>` 标签中序列化；数据中的每个 `<` 都会以无损 JSON 转义 `\u003c` 的形式发出，因此源文本无法拼出定界标签。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
每条引用消息都会添加固定警告和最多三个序列化快照，每个快照都受 `maxReferenceBytes` 独立限制。精确快照会保留在目标历史中，直到目标压缩遮蔽或摘要它；源会话变更不会添加更多 token。
|
||||
每条包含引用的消息都会添加固定警告和最多三个序列化快照，每个快照都受 `maxReferenceBytes` 独立限制。精确快照会保留在目标历史中，直到目标压缩遮蔽或摘要它；源会话变更不会添加更多 token。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
@@ -44,7 +44,7 @@
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **不支持正文发现**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化契约。
|
||||
- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化契约。
|
||||
- **受信任调用方边界**：该服务假设宿主有权读取 `ctx.sessionQuery` 公开的每个会话；它不是面向模型的搜索工具。
|
||||
- **只投影文本**：不会在会话间传播非文本 user 与 assistant 块。
|
||||
- **没有实时链接**：引用是快照，不是 fork、恢复、订阅或源会话变更。
|
||||
|
||||
@@ -110,8 +110,8 @@ export class SessionReferenceService extends Service {
|
||||
*/
|
||||
async listCandidates(
|
||||
agent: Agent,
|
||||
query = '',
|
||||
limit = this.config.candidateLimit,
|
||||
query: string = '',
|
||||
limit: number = this.config.candidateLimit,
|
||||
signal?: AbortSignal,
|
||||
): Promise<SessionReferenceCandidate[]> {
|
||||
if (!Number.isSafeInteger(limit) || limit <= 0) {
|
||||
|
||||
@@ -1,6 +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
|
||||
# pnpm run verify-translation-pairing --write packages/context/time-context/README.md
|
||||
README.md: 9fe818855439466b2a3e349cd54a2f408cf5ec10
|
||||
README.zh.md: 337ce3613d7b17134db7cf85a808881017f4e2c3
|
||||
README.zh.md: 1133715ebb3348d6e3dbbf8bbef169d6d8c56d8f
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
可选的持久上下文，包含模型请求准备期间采样的当前分区时间与已经过时间。`dsh-agent-spine-demo` 与已发布示例不装载它。决策记录：[持久 time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md)。
|
||||
可选的持久上下文，包含模型请求准备期间采样的带时区的当前时间与经过时长。`dsh-agent-spine-demo` 与随附示例不挂载该插件。决策记录：[持久 time-context Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md)。
|
||||
|
||||
## 配置
|
||||
|
||||
@@ -16,21 +16,21 @@
|
||||
|
||||
省略 `timeZone` 时，插件会在加载时解析一次 Node 进程的系统时区。Node 遵循 `TZ`；如果没有该覆盖，时区由宿主或容器提供。显式 `timeZone` 必须是 IANA 标识符，并在插件加载时验证。
|
||||
|
||||
`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，对每次信号尚未 abort 的合格步骤前尝试执行追加。正数值只会在会话没有早先 time-context 注入、墙上时间向后移动，或自最新注入起已经过至少相应毫秒数时执行追加。
|
||||
`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，对每次信号尚未中止的合格步骤前尝试执行追加。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时执行追加。
|
||||
|
||||
## 时序语义
|
||||
|
||||
该插件会前置一个 `agent/step` listener。需要注入时，它会追加一条注入的 `user/message`，通过 `agent.inject()` 完成，时机位于 `step/start` 和普通自动压缩之前，其源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制的尝试不追加任何内容。
|
||||
该插件会前置一个 `agent/step` 监听器。需要注入时，它会追加一条注入的 `user/message`，通过 `agent.inject()` 完成，时机位于 `step/start` 和普通自动压缩（compaction）之前，其源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制的尝试不追加任何内容。
|
||||
|
||||
正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的 reading。因此，调度可以跨轮次和已恢复进程应用，不需要进程本地 cache 状态。它会降低追加频率与历史增长，但绝不移除现有 reading，且每个会话独立调度。
|
||||
正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的时间读数。因此，调度可以跨轮次以及进程恢复持续生效，不需要进程本地缓存状态。它会降低追加频率与历史增长，但绝不移除现有时间读数，且每个会话独立调度。
|
||||
|
||||
第 1 步从最新的前置模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；墙上时钟向后移动时，已经过时间限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次 reading，则报告 `unavailable`。
|
||||
第 1 步从前一条模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；挂钟时间倒退时，经过时长限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次时间读数，则报告 `unavailable`。
|
||||
|
||||
时间 reading 记录的是一次请求准备尝试，不是已提交步骤或已传输请求。因为 listener 首先运行，后续步骤前 listener 取消或使尝试失败时，该追加可能仍会保留。日志仅追加，该插件不执行回滚。
|
||||
时间读数记录的是一次请求准备尝试，不是已提交步骤或已传输请求。因为 listener 首先运行，后续的步骤前监听器取消或使该尝试失败时，该追加可能仍会保留。日志仅追加，该插件不执行回滚。
|
||||
|
||||
单独发布的 `./invariant` 配套模块会根据开启轮次、下一个步骤前位置、已经过时间基线与持久事件时间检查每个归因于插件的 reading。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使 reading 失效。
|
||||
单独发布的 `./invariant` 配套模块会根据当前未结束的轮次、下一个步骤前位置、经过时长基线与持久事件时间检查每个归因于插件的时间读数。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使时间读数失效。
|
||||
|
||||
时间 reading 会保留在派生会话历史中，直到后续压缩遮蔽它。请求标头不含 time-context 状态。请求重建会在每个 `step/start` 处使用完整持久表层前缀，因此已传输请求无需与 reading 一一对应：失败的准备可能留下额外 reading，而间隔抑制可让请求复用现有历史，无需添加 reading。
|
||||
时间读数会保留在派生会话历史中，直到后续压缩遮蔽它。请求标头不含 time-context 状态。请求重建会在每个 `step/start` 处使用完整持久表层前缀，因此已传输请求无需与时间读数一一对应：失败的准备可能留下额外时间读数，而间隔抑制可让请求复用现有历史，无需添加时间读数。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -38,7 +38,7 @@
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
每次执行注入的准备尝试都会生成一条带源标记的上下文消息，包含下方两行。`<timestamp>` 是带数字偏移与 IANA 时区、形如 ISO 的本地时间戳；持续时间使用紧凑的整秒单位。正间隔可能使某次步骤尝试没有新 reading。
|
||||
每次执行注入的准备尝试都会生成一条带源标记的上下文消息，包含下方两行。`<timestamp>` 是带数字偏移与 IANA 时区、形如 ISO 的本地时间戳；持续时间使用紧凑的整秒单位。正间隔可能使某次步骤尝试没有新时间读数。
|
||||
|
||||
##### 第一步
|
||||
|
||||
@@ -60,11 +60,11 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **整秒显示**：时间戳与持续时间省略亚秒精度，尽管持久事件时间保留毫秒。
|
||||
- **会话事件基线**：已经过时间从持久追加时间戳起计算，而非客户端传输的原始发送时间戳。
|
||||
- **进程本地默认时区**：省略设置时，使用插件加载时捕获的 Node 进程 `TZ`、宿主或容器时区，而非远程 user 的时区；两者不同时，请配置显式 IANA 时区。
|
||||
- **压缩之间的历史成本**：省略设置或设为 `0` 会为每次合格准备尝试保留一条 reading，包括后续取消或失败的尝试；正间隔可以降低但无法消除该成本。
|
||||
- **会话事件基线**：经过时长从持久追加时间戳起计算，而非客户端传输的原始发送时间戳。
|
||||
- **进程本地默认时区**：省略设置时，使用插件加载时捕获的 Node 进程 `TZ`、宿主或容器时区，而非远程用户的时区；两者不同时，请配置显式 IANA 时区。
|
||||
- **压缩之间的历史成本**：省略设置或设为 `0` 会为每次合格准备尝试保留一条时间读数，包括后续取消或失败的尝试；正间隔可以降低但无法消除该成本。
|
||||
|
||||
@@ -49,6 +49,7 @@ function sessionAgent(session: Session, id = 'agent'): Agent {
|
||||
session.append('user/message', input, { surfaceOp: 'append' })
|
||||
},
|
||||
send: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
|
||||
6
packages/context/tmux-context/README.i18n.yaml
Normal file
6
packages/context/tmux-context/README.i18n.yaml
Normal file
@@ -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 packages/context/tmux-context/README.md
|
||||
README.md: a166a46d20f472cb5d8f045e2456ce3e6de7a2f2
|
||||
README.zh.md: 0575d549e352239e7d954870eaf40beea1169cc6
|
||||
68
packages/context/tmux-context/README.md
Normal file
68
packages/context/tmux-context/README.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# @deepseek-ai/dsh-tmux-context
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Opt-in durable context naming the tmux session, window, and pane this agent process runs in, plus the window's pane-tree layout. Sampled once per turn during model-request preparation. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the tmux-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md).
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
- id: tmux-context
|
||||
name: '@deepseek-ai/dsh-tmux-context'
|
||||
config:
|
||||
refreshIntervalMs: 60000 # optional; omit or set to 0 to inject on every changed turn
|
||||
```
|
||||
|
||||
`refreshIntervalMs` must be a non-negative safe integer. Omission or `0` injects whenever the tmux state changed since the last injection. A positive value additionally suppresses injections that fall within that many milliseconds of the latest one.
|
||||
|
||||
## How it reads tmux
|
||||
|
||||
The plugin prepends an `agent/step` listener that runs only on the first step of each turn. When due, it runs one read-only command through the `ctx.bash` executor seam:
|
||||
|
||||
```sh
|
||||
[ -n "$TMUX_PANE" ] || exit 1
|
||||
self_tty=$(ps -o tty= -p <pid> | tr -d ' ')
|
||||
pane_tty=$(tmux display-message -t "$TMUX_PANE" -p '#{pane_tty}') || exit 1
|
||||
[ "$pane_tty" = "/dev/$self_tty" ] || exit 1
|
||||
exec tmux display-message -t "$TMUX_PANE" -p '<format>'
|
||||
```
|
||||
|
||||
`$TMUX_PANE` alone is insufficient: a terminal launched from a tmux shell (a VS Code integrated terminal, a desktop launcher) **inherits** `$TMUX` and `$TMUX_PANE` from that ancestor, so the variables are present even though the process does not live in that pane. The command therefore also compares the pane's `#{pane_tty}` against this process's own controlling terminal (`ps -o tty=` for its pid): a genuine pane owns this process's tty, while an inherited environment names some other pane's tty. Running through `ctx.bash` applies the deployment's sandbox and policy; the plugin owns no subprocess code. When `ctx.bash` is absent, the process is not in a real tmux pane (`$TMUX_PANE` unset, or the tty does not match ⇒ nonzero exit), or the reading is malformed, the attempt is a no-op, never an error. The location is optional, so an executor rejection — a policy refusal from `resolve()` or an infrastructure failure from `run()` — is contained and logged as a warning rather than failing the turn.
|
||||
|
||||
State is pulled on every eligible turn — a moved, renamed, or re-laid-out pane is picked up without any tmux hook or background process. The plugin re-injects only when the rendered tmux state differs from its last injection, so an unchanged location adds nothing.
|
||||
|
||||
## Timing semantics
|
||||
|
||||
When an injection is due, the plugin appends one injected `user/message` through `agent.inject()` before `step/start`, with source `{ kind: 'plugin', plugin: 'tmux-context' }`. Change suppression and interval scheduling scan the raw durable session events for the latest injection of this source, so the schedule survives compaction and resumed processes without process-local cache state; sessions schedule independently. The reading records a request-preparation attempt, not a committed step; because the listener runs first, its append may remain when a later pre-step listener cancels or fails the attempt (the log is append-only and the plugin performs no rollback).
|
||||
|
||||
## Model Experience
|
||||
|
||||
### Preparation-time tmux location
|
||||
|
||||
#### What the model sees
|
||||
|
||||
On each turn whose tmux state changed, one source-tagged context message with the three lines below. `<window-layout>` is tmux's compact pane-tree description; pane and window pixel sizes are intentionally excluded, and the contents of sibling panes are never captured.
|
||||
|
||||
##### Changed-turn reading
|
||||
|
||||
```markdown
|
||||
tmux location (turn <turn>):
|
||||
session <session>, window <index> "<name>", pane <index> <pane-id>
|
||||
window active=<0|1>, pane active=<0|1>, layout <window-layout>
|
||||
```
|
||||
|
||||
#### Token effect
|
||||
|
||||
Each two-line reading accumulates until compaction shadows it. Unchanged locations and interval suppression add nothing.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **First step only** — a pane moved or resized mid-turn is reflected on the next turn, not between steps.
|
||||
- **Own location only** — the plugin never captures the visible text of sibling panes.
|
||||
- **Layout, not size** — pane/window pixel dimensions are omitted; only the layout tree and active flags are reported.
|
||||
- **Tab-delimited fields** — a tmux window name containing the literal two-character sequence `\t` would mis-split the reading and be skipped as malformed; ordinary names are unaffected.
|
||||
- **tty-based pane detection** — the process is considered "in tmux" only when its controlling terminal matches `$TMUX_PANE`'s `#{pane_tty}`. This deliberately excludes terminals that inherited `$TMUX`/`$TMUX_PANE` from a tmux ancestor (e.g. a VS Code integrated terminal). `ps -o tty=` is POSIX; the check is a no-op wherever it or `#{pane_tty}` is unavailable.
|
||||
68
packages/context/tmux-context/README.zh.md
Normal file
68
packages/context/tmux-context/README.zh.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# @deepseek-ai/dsh-tmux-context
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
可选启用的持久上下文，记录本 agent 进程所在的 tmux session、window、pane，以及该 window 的 pane 树布局。在准备模型请求时每轮采样一次。`dsh-agent-spine-demo` 与随附示例均不挂载它。决策记录见：[tmux-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md)。
|
||||
|
||||
## 配置
|
||||
|
||||
```yaml
|
||||
- id: tmux-context
|
||||
name: '@deepseek-ai/dsh-tmux-context'
|
||||
config:
|
||||
refreshIntervalMs: 60000 # optional; omit or set to 0 to inject on every changed turn
|
||||
```
|
||||
|
||||
`refreshIntervalMs` 必须是非负安全整数。省略或 `0` 表示只要 tmux 状态自上次注入以来发生变化就注入。正值会额外抑制距最近一次注入不足该毫秒数的注入。
|
||||
|
||||
## 如何读取 tmux
|
||||
|
||||
插件前置注册一个 `agent/step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器 seam 运行一条只读命令：
|
||||
|
||||
```sh
|
||||
[ -n "$TMUX_PANE" ] || exit 1
|
||||
self_tty=$(ps -o tty= -p <pid> | tr -d ' ')
|
||||
pane_tty=$(tmux display-message -t "$TMUX_PANE" -p '#{pane_tty}') || exit 1
|
||||
[ "$pane_tty" = "/dev/$self_tty" ] || exit 1
|
||||
exec tmux display-message -t "$TMUX_PANE" -p '<format>'
|
||||
```
|
||||
|
||||
仅凭 `$TMUX_PANE` 并不足够：从 tmux shell 启动的终端（VS Code 集成终端、桌面启动器）会从该祖先进程**继承** `$TMUX` 与 `$TMUX_PANE`，因此即使进程并不位于那个 pane 中，这些变量依然存在。为此该命令还会把 pane 的 `#{pane_tty}` 与本进程自己的控制终端（对其 pid 执行 `ps -o tty=`）作比较：真正的 pane 拥有本进程的 tty，而继承而来的环境指向的是另一个 pane 的 tty。通过 `ctx.bash` 运行会应用部署方的沙箱与策略；插件不拥有任何子进程代码。当 `ctx.bash` 缺失、进程不在真实的 tmux pane 内（`$TMUX_PANE` 未设置，或 tty 不匹配 ⇒ 非零退出）或读取结果格式非法时，本次尝试为空操作，绝不报错。由于位置信息是可选的，执行器的拒绝——`resolve()` 的策略拒绝或 `run()` 的基础设施故障——会被兜住并记录为警告，而不会使该轮失败。
|
||||
|
||||
状态在每个符合条件的轮次拉取——pane 被移动、改名或重新布局都会被感知，无需任何 tmux hook 或后台进程。插件仅在渲染出的 tmux 状态与上次注入不同时才重新注入，因此位置不变时不会新增任何内容。
|
||||
|
||||
## 时序语义
|
||||
|
||||
当需要注入时，插件在 `step/start` 之前通过 `agent.inject()` 追加一条注入的 `user/message`，来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。该读数记录的是一次请求准备尝试，而非已提交的 step；由于监听器最先运行，当后续 pre-step 监听器取消或失败时，它的追加可能仍会保留（日志只追加，插件不做回滚）。
|
||||
|
||||
## 模型体验
|
||||
|
||||
### 准备期 tmux 位置
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
在 tmux 状态发生变化的每一轮，注入一条带来源标记、含以下三行的上下文消息。`<window-layout>` 是 tmux 紧凑的 pane 树描述；pane 与 window 的像素尺寸有意省略，相邻 pane 的内容从不采集。
|
||||
|
||||
##### 变化轮次读数
|
||||
|
||||
```markdown
|
||||
tmux location (turn <turn>):
|
||||
session <session>, window <index> "<name>", pane <index> <pane-id>
|
||||
window active=<0|1>, pane active=<0|1>, layout <window-layout>
|
||||
```
|
||||
|
||||
#### Token 影响
|
||||
|
||||
每条两行读数会累积，直到压缩将其遮蔽。位置未变化以及间隔抑制不会新增内容。
|
||||
|
||||
#### KV 缓存影响
|
||||
|
||||
只追加；新增可见内容位于可复用的请求前缀之后，不会使已有 KV 缓存条目失效。
|
||||
|
||||
## 已知限制与后续工作
|
||||
|
||||
- **仅第一个 step**——轮次中途移动或缩放的 pane 会在下一轮反映，而非在 step 之间。
|
||||
- **仅自身位置**——插件从不采集相邻 pane 的可见文本。
|
||||
- **只有布局，没有尺寸**——省略 pane/window 像素尺寸；仅报告布局树与活动标志。
|
||||
- **制表符分隔字段**——若 tmux window 名称包含字面两字符序列 `\t`，会使读数分割错误并作为非法读数跳过；常规名称不受影响。
|
||||
- **基于 tty 的 pane 判定**——只有当进程的控制终端与 `$TMUX_PANE` 的 `#{pane_tty}` 一致时，才视为“位于 tmux 中”。这会有意排除从 tmux 祖先进程继承 `$TMUX`／`$TMUX_PANE` 的终端（如 VS Code 集成终端）。`ps -o tty=` 属于 POSIX；在其或 `#{pane_tty}` 不可用的环境中，该检查即为空操作。
|
||||
48
packages/context/tmux-context/package.json
Normal file
48
packages/context/tmux-context/package.json
Normal file
@@ -0,0 +1,48 @@
|
||||
{
|
||||
"name": "@deepseek-ai/dsh-tmux-context",
|
||||
"description": "Opt-in durable per-step context with this agent's tmux pane and window location",
|
||||
"version": "0.0.1",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"main": "lib/index.js",
|
||||
"types": "lib/types/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"types": "./lib/types/index.d.ts",
|
||||
"default": "./lib/index.js"
|
||||
},
|
||||
"./invariant": {
|
||||
"types": "./lib/types/invariant.d.ts",
|
||||
"default": "./lib/invariant.js"
|
||||
},
|
||||
"./src/*": "./src/*",
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"dependencies": {
|
||||
"schemastery": "^3.18.0"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@deepseek-ai/dsh-agent": "^0.0.1",
|
||||
"@deepseek-ai/dsh-bash": "^0.0.1",
|
||||
"@deepseek-ai/dsh-invariants": "^0.0.1",
|
||||
"@deepseek-ai/dsh-session": "^0.0.1",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@deepseek-ai/dsh-agent": "workspace:^",
|
||||
"@deepseek-ai/dsh-bash": "workspace:^",
|
||||
"@deepseek-ai/dsh-invariants": "workspace:^",
|
||||
"@deepseek-ai/dsh-llm": "workspace:^",
|
||||
"@deepseek-ai/dsh-session": "workspace:^",
|
||||
"@deepseek-ai/dsh-system-prompt": "workspace:^",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
}
|
||||
}
|
||||
241
packages/context/tmux-context/src/index.ts
Normal file
241
packages/context/tmux-context/src/index.ts
Normal file
@@ -0,0 +1,241 @@
|
||||
/**
|
||||
* Opt-in request-preparation tmux-location context. Eligible step attempts
|
||||
* append durable, source-attributed context naming the tmux session, window,
|
||||
* and pane this agent process runs in, plus the window's pane-tree layout.
|
||||
*
|
||||
* The plugin pulls state once per turn, on the first step (`step === 1`), by
|
||||
* running one `tmux display-message` through the `ctx.bash` executor seam. It
|
||||
* confirms this process genuinely runs inside the pane `$TMUX_PANE` names by
|
||||
* matching the pane's `#{pane_tty}` against this process's controlling terminal,
|
||||
* so a terminal that merely inherited `$TMUX`/`$TMUX_PANE` from a tmux ancestor
|
||||
* (e.g. a VS Code integrated terminal) reads as "not in tmux". It re-injects
|
||||
* only when the rendered tmux state changes since the last injection (a moved,
|
||||
* renamed, or re-laid-out pane), with an optional `refreshIntervalMs` floor
|
||||
* between injections. Absent tmux environment, an inherited-only environment,
|
||||
* absent `ctx.bash`, or a failed query is a no-op, never an error: an executor
|
||||
* rejection is contained and logged as a warning so the turn continues.
|
||||
*
|
||||
* @module @deepseek-ai/dsh-tmux-context
|
||||
*/
|
||||
|
||||
import type { Context, LoggerService } from 'cordis'
|
||||
import z from 'schemastery'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import type { BashExecutor, BashRunResult } from '@deepseek-ai/dsh-bash'
|
||||
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
/** Cordis plugin name used by loader diagnostics. */
|
||||
export const name = 'tmux-context'
|
||||
|
||||
/** The agent registry that owns the `agent/step` lifecycle seam. */
|
||||
export const inject = ['agents']
|
||||
|
||||
/** Per-turn tmux-location scheduling. Invalid values fail plugin load. */
|
||||
export interface Config {
|
||||
/** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject on every eligible change. */
|
||||
refreshIntervalMs?: number
|
||||
}
|
||||
|
||||
/** Schemastery validation for {@link Config}. */
|
||||
export const Config: z<Config> = z.object({
|
||||
refreshIntervalMs: z.number(),
|
||||
})
|
||||
|
||||
/**
|
||||
* Tab-separated tmux format fields, in query order. Layout (`window_layout`)
|
||||
* is the pane-tree description; pane/window pixel sizes are intentionally
|
||||
* excluded (own location and layout only, per the package scope).
|
||||
*/
|
||||
const TMUX_FIELDS = [
|
||||
'#{session_name}',
|
||||
'#{window_index}',
|
||||
'#{window_name}',
|
||||
'#{pane_index}',
|
||||
'#{pane_id}',
|
||||
'#{window_active}',
|
||||
'#{pane_active}',
|
||||
'#{window_layout}',
|
||||
] as const
|
||||
|
||||
/** Structured tmux location parsed from one `display-message` reading. */
|
||||
interface TmuxLocation {
|
||||
sessionName: string
|
||||
windowIndex: string
|
||||
windowName: string
|
||||
paneIndex: string
|
||||
paneId: string
|
||||
windowActive: string
|
||||
paneActive: string
|
||||
windowLayout: string
|
||||
}
|
||||
|
||||
/** Prefix marking the volatile turn/step preamble line of a rendered reading. */
|
||||
const READING_PREFIX = 'tmux location (turn '
|
||||
|
||||
/**
|
||||
* Field separator between tmux format fields. tmux does not interpret C escapes
|
||||
* in a format, so the literal two-character sequence `\t` is emitted verbatim
|
||||
* and split back out here; this avoids embedding raw whitespace in the command.
|
||||
*/
|
||||
const FIELD_SEP = '\\t'
|
||||
|
||||
/**
|
||||
* Read this process's tmux location through the bash seam, or `undefined` when
|
||||
* this process is not genuinely running inside a tmux pane or the query fails.
|
||||
*
|
||||
* `$TMUX_PANE` alone is insufficient: a terminal launched from a tmux shell
|
||||
* (e.g. VS Code's integrated terminal, a desktop launcher) inherits `$TMUX` and
|
||||
* `$TMUX_PANE` from that ancestor, so the variables are present even though this
|
||||
* process does not live in that pane. The command therefore also compares the
|
||||
* pane's `#{pane_tty}` against this process's own controlling terminal
|
||||
* (`ps -o tty=` for {@link processId}); a genuine pane owns this process's tty,
|
||||
* an inherited environment names some other pane's tty. Fields are emitted only
|
||||
* on a match, so an inherited environment reads as "not in tmux" and injects
|
||||
* nothing.
|
||||
*
|
||||
* The location is optional context, so an executor rejection is a failed query,
|
||||
* not a turn failure: `resolve()` may reject the command on policy grounds and
|
||||
* `run()` only promises to resolve for nonzero exits, timeouts, and aborts, so
|
||||
* both are contained and reported as a warning.
|
||||
*
|
||||
* @param bash - the executor seam used to run the read-only tmux/ps commands.
|
||||
* @param logger - receives a warning when the executor rejects the query.
|
||||
* @param processId - this agent process's pid, whose controlling tty must match the pane.
|
||||
* @param signal - abort signal forwarded to the executor.
|
||||
* @returns the parsed location, or `undefined` when not in a real pane or on any failure.
|
||||
*/
|
||||
async function queryTmuxLocation(
|
||||
bash: BashExecutor,
|
||||
logger: LoggerService,
|
||||
processId: number,
|
||||
signal: AbortSignal,
|
||||
): Promise<TmuxLocation | undefined> {
|
||||
const format = TMUX_FIELDS.join(FIELD_SEP)
|
||||
const command = [
|
||||
'[ -n "$TMUX_PANE" ] || exit 1',
|
||||
`self_tty=$(ps -o tty= -p ${processId} | tr -d ' ')`,
|
||||
'[ -n "$self_tty" ] || exit 1',
|
||||
'pane_tty=$(tmux display-message -t "$TMUX_PANE" -p \'#{pane_tty}\') || exit 1',
|
||||
'[ "$pane_tty" = "/dev/$self_tty" ] || exit 1',
|
||||
`exec tmux display-message -t "$TMUX_PANE" -p '${format}'`,
|
||||
].join('\n')
|
||||
let result: BashRunResult
|
||||
try {
|
||||
result = await bash.run(bash.resolve({ command, signal }))
|
||||
} catch (error: unknown) {
|
||||
const message = error instanceof Error ? error.message : String(error)
|
||||
logger.warn(`tmux location query failed: ${message}; injecting no location this turn`)
|
||||
return undefined
|
||||
}
|
||||
if (result.exitCode !== 0) return undefined
|
||||
const line = result.stdout.text.split('\n', 1)[0] as string
|
||||
const parts = line.split(FIELD_SEP)
|
||||
if (parts.length !== TMUX_FIELDS.length) return undefined
|
||||
const [
|
||||
sessionName,
|
||||
windowIndex,
|
||||
windowName,
|
||||
paneIndex,
|
||||
paneId,
|
||||
windowActive,
|
||||
paneActive,
|
||||
windowLayout,
|
||||
] = parts as [string, string, string, string, string, string, string, string]
|
||||
if (paneId.length === 0) return undefined
|
||||
return {
|
||||
sessionName,
|
||||
windowIndex,
|
||||
windowName,
|
||||
paneIndex,
|
||||
paneId,
|
||||
windowActive,
|
||||
paneActive,
|
||||
windowLayout,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the stable tmux state block: the part of a reading compared for
|
||||
* change suppression. It excludes the turn preamble so re-injection is driven
|
||||
* only by tmux state, not by loop position.
|
||||
*/
|
||||
function renderState(location: TmuxLocation): string {
|
||||
return `session ${location.sessionName}, `
|
||||
+ `window ${location.windowIndex} ${JSON.stringify(location.windowName)}, `
|
||||
+ `pane ${location.paneIndex} ${location.paneId}\n`
|
||||
+ `window active=${location.windowActive}, pane active=${location.paneActive}, `
|
||||
+ `layout ${location.windowLayout}`
|
||||
}
|
||||
|
||||
/** Render the full durable reading, including the volatile turn preamble. */
|
||||
function renderReading(location: TmuxLocation, turn: number): string {
|
||||
return `${READING_PREFIX}${turn}):\n${renderState(location)}`
|
||||
}
|
||||
|
||||
/**
|
||||
* The stable state block of this plugin's latest durable injection, or
|
||||
* `undefined` when the session has none. Scans raw durable events so the
|
||||
* schedule survives compaction and resumed processes without process-local
|
||||
* cache state.
|
||||
*/
|
||||
function latestInjectedState(agent: Agent): { state: string; time: number } | undefined {
|
||||
for (const event of [...agent.session.events].reverse()) {
|
||||
if (event.type === 'user/message'
|
||||
&& event.data.source.kind === 'plugin'
|
||||
&& event.data.source.plugin === name) {
|
||||
const [block] = event.data.content
|
||||
if (block?.type !== 'text') return undefined
|
||||
const newline = block.text.indexOf('\n')
|
||||
const state = newline === -1 ? '' : block.text.slice(newline + 1)
|
||||
return { state, time: event.time }
|
||||
}
|
||||
}
|
||||
return undefined
|
||||
}
|
||||
|
||||
/** Reject refresh intervals that cannot represent an exact elapsed-millisecond threshold. */
|
||||
function validateRefreshInterval(refreshIntervalMs: number | undefined): void {
|
||||
if (refreshIntervalMs !== undefined && (
|
||||
!Number.isSafeInteger(refreshIntervalMs)
|
||||
|| refreshIntervalMs < 0
|
||||
)) {
|
||||
throw new TypeError(
|
||||
`tmux-context: refreshIntervalMs must be a non-negative safe integer, got ${String(refreshIntervalMs)}`,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a prepended `agent/step` listener for the lifetime of `ctx`.
|
||||
* @param ctx - plugin context; the listener is disposed with it.
|
||||
* @param config - durable refresh scheduling configuration.
|
||||
* @throws when the refresh interval is invalid.
|
||||
*/
|
||||
export function apply(ctx: Context, config: Config): void {
|
||||
const refreshIntervalMs = config.refreshIntervalMs
|
||||
validateRefreshInterval(refreshIntervalMs)
|
||||
|
||||
ctx.on('agent/step', async (
|
||||
agent: Agent,
|
||||
turn: number,
|
||||
step: number,
|
||||
signal: AbortSignal,
|
||||
): Promise<void> => {
|
||||
if (signal.aborted || step !== 1) return
|
||||
const bash = ctx.get('bash')
|
||||
if (bash === undefined) return
|
||||
const previous = latestInjectedState(agent)
|
||||
if (refreshIntervalMs !== undefined && refreshIntervalMs > 0 && previous !== undefined) {
|
||||
const now = Date.now()
|
||||
if (now >= previous.time && now - previous.time < refreshIntervalMs) return
|
||||
}
|
||||
const location = await queryTmuxLocation(bash, ctx.logger, process.pid, signal)
|
||||
if (location === undefined) return
|
||||
const state = renderState(location)
|
||||
if (previous !== undefined && previous.state === state) return
|
||||
agent.inject(createUserMessage({
|
||||
content: [{ type: 'text', text: renderReading(location, turn) }],
|
||||
source: { kind: 'plugin', plugin: name },
|
||||
}))
|
||||
}, { prepend: true })
|
||||
}
|
||||
30
packages/context/tmux-context/src/invariant.ts
Normal file
30
packages/context/tmux-context/src/invariant.ts
Normal file
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* Package-owned invariant companion for `@deepseek-ai/dsh-tmux-context`.
|
||||
* @module @deepseek-ai/dsh-tmux-context/invariant
|
||||
*/
|
||||
|
||||
/* jscpd:ignore-start */
|
||||
import type { Context } from 'cordis'
|
||||
import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
|
||||
|
||||
const PACKAGE_NAME = '@deepseek-ai/dsh-tmux-context'
|
||||
|
||||
/** Cordis companion plugin name. */
|
||||
export const name = 'tmux-context-invariant'
|
||||
/** Service required before the companion can reserve package ownership. */
|
||||
export const inject = ['invariants']
|
||||
|
||||
/**
|
||||
* No runtime invariant: a reading is a per-turn snapshot of external tmux state, so the session
|
||||
* holds no cross-event relation to check; scheduling and format are owned by pipeline tests.
|
||||
*/
|
||||
const install: InvariantInstaller = () => {}
|
||||
|
||||
/**
|
||||
* Register this package's invariant companion.
|
||||
* @param ctx - Cordis context carrying the invariant service.
|
||||
* @returns the installed registration's disposer after setup succeeds.
|
||||
*/
|
||||
export const apply = (ctx: Context): Promise<() => void> =>
|
||||
Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
|
||||
/* jscpd:ignore-end */
|
||||
408
packages/context/tmux-context/tests/tmux-context.spec.ts
Normal file
408
packages/context/tmux-context/tests/tmux-context.spec.ts
Normal file
@@ -0,0 +1,408 @@
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||||
import { Context } from 'cordis'
|
||||
import { Session, SessionId } from '@deepseek-ai/dsh-session'
|
||||
import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
|
||||
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
import { BashExecutor } from '@deepseek-ai/dsh-bash'
|
||||
import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
|
||||
import * as tmuxContext from '@deepseek-ai/dsh-tmux-context'
|
||||
import type { Config } from '@deepseek-ai/dsh-tmux-context'
|
||||
|
||||
const SIGNAL = new AbortController().signal
|
||||
|
||||
/** One `#{...}`-joined tmux reading line for the eight queried fields. */
|
||||
function tmuxLine(fields: {
|
||||
sessionName?: string
|
||||
windowIndex?: string
|
||||
windowName?: string
|
||||
paneIndex?: string
|
||||
paneId?: string
|
||||
windowActive?: string
|
||||
paneActive?: string
|
||||
windowLayout?: string
|
||||
} = {}): string {
|
||||
return [
|
||||
fields.sessionName ?? '0',
|
||||
fields.windowIndex ?? '1',
|
||||
fields.windowName ?? 'node',
|
||||
fields.paneIndex ?? '2',
|
||||
fields.paneId ?? '%90',
|
||||
fields.windowActive ?? '1',
|
||||
fields.paneActive ?? '0',
|
||||
fields.windowLayout ?? 'd517,270x71,0,0{135x71,0,0,87,134x71,136,0[134x35,136,0,90,134x35,136,36,93]}',
|
||||
].join('\\t')
|
||||
}
|
||||
|
||||
function runResult(stdout: string, overrides: Partial<BashRunResult> = {}): BashRunResult {
|
||||
return {
|
||||
exitCode: 0,
|
||||
signal: null,
|
||||
timedOut: false,
|
||||
aborted: false,
|
||||
timeoutMs: 60_000,
|
||||
stdout: { text: stdout, truncated: false },
|
||||
stderr: { text: '', truncated: false },
|
||||
...overrides,
|
||||
}
|
||||
}
|
||||
|
||||
/** A scriptable fake `ctx.bash` recording the command it was asked to run. */
|
||||
class FakeBash extends BashExecutor {
|
||||
commands: string[] = []
|
||||
result: BashRunResult = runResult(`${tmuxLine()}\n`)
|
||||
runError?: Error
|
||||
resolveError?: Error
|
||||
|
||||
override resolve(request: BashExecRequest): BashExecSpec {
|
||||
if (this.resolveError) throw this.resolveError
|
||||
return {
|
||||
command: request.command,
|
||||
workdir: request.workdir ?? '/work',
|
||||
timeoutMs: request.timeoutMs ?? 60_000,
|
||||
stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
|
||||
signal: request.signal,
|
||||
sandboxPolicy: request.sandboxPolicy,
|
||||
}
|
||||
}
|
||||
override async run(spec: BashExecSpec): Promise<BashRunResult> {
|
||||
this.commands.push(spec.command)
|
||||
if (this.runError) throw this.runError
|
||||
return this.result
|
||||
}
|
||||
override start(): BashProcess {
|
||||
throw new Error('tmux-context must never start a background task')
|
||||
}
|
||||
}
|
||||
|
||||
async function mount(config: Config, withBash: true): Promise<{ ctx: Context; bash: FakeBash }>
|
||||
async function mount(config?: Config, withBash?: boolean): Promise<{ ctx: Context; bash: FakeBash | undefined }>
|
||||
async function mount(
|
||||
config: Config = {},
|
||||
withBash = false,
|
||||
): Promise<{ ctx: Context; bash: FakeBash | undefined }> {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(AgentRegistry)
|
||||
let bash: FakeBash | undefined
|
||||
if (withBash) {
|
||||
await ctx.plugin(FakeBash)
|
||||
bash = ctx.bash as FakeBash
|
||||
}
|
||||
await ctx.plugin(tmuxContext, config)
|
||||
return { ctx, bash }
|
||||
}
|
||||
|
||||
function sessionAgent(session: Session, id = 'agent'): Agent {
|
||||
return {
|
||||
id: SessionId(id),
|
||||
options: {},
|
||||
session,
|
||||
status: 'running',
|
||||
acceptsNextStep: true,
|
||||
ctx: new Context(),
|
||||
followup: () => {},
|
||||
steer: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
inject(input) {
|
||||
session.append('user/message', input, { surfaceOp: 'append' })
|
||||
},
|
||||
send: () => {},
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
}
|
||||
|
||||
function openMessageTurn(session: Session, turn: number): void {
|
||||
session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
|
||||
session.append('user/message', createUserMessage({
|
||||
content: [{ type: 'text', text: `turn ${turn}` }],
|
||||
source: { kind: 'user' },
|
||||
}), { surfaceOp: 'append' })
|
||||
}
|
||||
|
||||
function contextTexts(session: Session): string[] {
|
||||
const texts: string[] = []
|
||||
for (const event of session.events) {
|
||||
if (event.type === 'user/message'
|
||||
&& event.data.source.kind === 'plugin'
|
||||
&& event.data.source.plugin === 'tmux-context') {
|
||||
texts.push(event.data.content.find(block => block.type === 'text')?.text ?? '')
|
||||
}
|
||||
}
|
||||
return texts
|
||||
}
|
||||
|
||||
async function fire(
|
||||
ctx: Context,
|
||||
agent: Agent,
|
||||
turn: number,
|
||||
step: number,
|
||||
signal: AbortSignal = SIGNAL,
|
||||
): Promise<void> {
|
||||
await agentEvents(ctx, agent).serial('agent/step', turn, step, signal)
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks()
|
||||
vi.useRealTimers()
|
||||
})
|
||||
|
||||
describe('tmux-context injection', () => {
|
||||
it('injects the tmux location on the first step of a turn', async () => {
|
||||
const { ctx } = await mount({}, true)
|
||||
const session = new Session(SessionId('first'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toEqual([
|
||||
'tmux location (turn 1):\n'
|
||||
+ 'session 0, window 1 "node", pane 2 %90\n'
|
||||
+ 'window active=1, pane active=0, '
|
||||
+ 'layout d517,270x71,0,0{135x71,0,0,87,134x71,136,0[134x35,136,0,90,134x35,136,36,93]}',
|
||||
])
|
||||
const event = session.events.at(-1)
|
||||
if (event?.type !== 'user/message') throw new Error('missing tmux context')
|
||||
expect(event.data.source).toEqual({ kind: 'plugin', plugin: 'tmux-context' })
|
||||
expect(event.surfaceOp).toBe('append')
|
||||
})
|
||||
|
||||
it('queries the pane this process runs in and matches its controlling tty', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
const session = new Session(SessionId('command'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(bash.commands).toHaveLength(1)
|
||||
const command = bash.commands[0]!
|
||||
expect(command).toContain('[ -n "$TMUX_PANE" ]')
|
||||
expect(command).toContain('tmux display-message -t "$TMUX_PANE" -p')
|
||||
// Guards against an inherited $TMUX_PANE: the pane's tty must equal this
|
||||
// process's controlling tty (resolved for this exact pid).
|
||||
expect(command).toContain(`ps -o tty= -p ${process.pid}`)
|
||||
expect(command).toContain('#{pane_tty}')
|
||||
expect(command).toContain('[ "$pane_tty" = "/dev/$self_tty" ]')
|
||||
})
|
||||
|
||||
it('does not run on later steps of a turn', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
const session = new Session(SessionId('later-step'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 2)
|
||||
|
||||
expect(bash.commands).toHaveLength(0)
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('re-injects a new turn only when tmux state changed', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
const session = new Session(SessionId('change'))
|
||||
const agent = sessionAgent(session)
|
||||
|
||||
openMessageTurn(session, 1)
|
||||
await fire(ctx, agent, 1, 1)
|
||||
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
|
||||
|
||||
// Same state on turn 2: suppressed.
|
||||
openMessageTurn(session, 2)
|
||||
await fire(ctx, agent, 2, 1)
|
||||
session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
|
||||
expect(contextTexts(session)).toHaveLength(1)
|
||||
|
||||
// Moved pane on turn 3: re-injected.
|
||||
bash.result = runResult(`${tmuxLine({ windowName: 'shell', paneId: '%12' })}\n`)
|
||||
openMessageTurn(session, 3)
|
||||
await fire(ctx, agent, 3, 1)
|
||||
|
||||
const texts = contextTexts(session)
|
||||
expect(texts).toHaveLength(2)
|
||||
expect(texts[1]).toContain('tmux location (turn 3):')
|
||||
expect(texts[1]).toContain('window 1 "shell", pane 2 %12')
|
||||
})
|
||||
|
||||
it('honors a positive refresh interval between injections', async () => {
|
||||
vi.useFakeTimers()
|
||||
vi.setSystemTime(1_000)
|
||||
const { ctx, bash } = await mount({ refreshIntervalMs: 10_000 }, true)
|
||||
const session = new Session(SessionId('interval'))
|
||||
const agent = sessionAgent(session)
|
||||
|
||||
openMessageTurn(session, 1)
|
||||
await fire(ctx, agent, 1, 1)
|
||||
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
|
||||
|
||||
// Changed state but inside the interval: suppressed, and never queried.
|
||||
bash.result = runResult(`${tmuxLine({ paneId: '%99' })}\n`)
|
||||
vi.setSystemTime(5_000)
|
||||
openMessageTurn(session, 2)
|
||||
await fire(ctx, agent, 2, 1)
|
||||
expect(contextTexts(session)).toHaveLength(1)
|
||||
expect(bash.commands).toHaveLength(1)
|
||||
|
||||
// Past the interval: queried and re-injected.
|
||||
vi.setSystemTime(12_000)
|
||||
openMessageTurn(session, 3)
|
||||
await fire(ctx, agent, 3, 1)
|
||||
expect(contextTexts(session)).toHaveLength(2)
|
||||
expect(bash.commands).toHaveLength(2)
|
||||
})
|
||||
})
|
||||
|
||||
describe('tmux-context prior-reading resilience', () => {
|
||||
it('treats a prior non-text plugin reading as absent and injects afresh', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
const session = new Session(SessionId('prior-non-text'))
|
||||
const agent = sessionAgent(session)
|
||||
openMessageTurn(session, 1)
|
||||
session.append('user/message', createUserMessage({
|
||||
content: [{ type: 'reasoning', text: 'not a location' }],
|
||||
source: { kind: 'plugin', plugin: 'tmux-context' },
|
||||
}), { surfaceOp: 'append' })
|
||||
|
||||
await fire(ctx, agent, 1, 1)
|
||||
|
||||
expect(bash.commands).toHaveLength(1)
|
||||
expect(contextTexts(session).at(-1)).toContain('tmux location (turn 1):')
|
||||
})
|
||||
|
||||
it('treats a prior single-line plugin reading (no newline) as empty state', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
const session = new Session(SessionId('prior-single-line'))
|
||||
const agent = sessionAgent(session)
|
||||
openMessageTurn(session, 1)
|
||||
session.append('user/message', createUserMessage({
|
||||
content: [{ type: 'text', text: 'single line, no newline' }],
|
||||
source: { kind: 'plugin', plugin: 'tmux-context' },
|
||||
}), { surfaceOp: 'append' })
|
||||
|
||||
await fire(ctx, agent, 1, 1)
|
||||
|
||||
// Empty prior state never equals the multi-line reading, so it re-injects.
|
||||
expect(bash.commands).toHaveLength(1)
|
||||
expect(contextTexts(session).at(-1)).toContain('tmux location (turn 1):')
|
||||
})
|
||||
})
|
||||
|
||||
describe('tmux-context no-op paths', () => {
|
||||
it('is a no-op when no bash executor is mounted', async () => {
|
||||
const { ctx } = await mount()
|
||||
const session = new Session(SessionId('no-bash'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('is a no-op when the tmux query exits nonzero (outside tmux, or an inherited env whose tty does not match the pane)', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
bash.result = runResult('', { exitCode: 1 })
|
||||
const session = new Session(SessionId('outside-tmux'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('is a no-op when the reading has the wrong field count', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
bash.result = runResult('0\\t1\\tnode\n')
|
||||
const session = new Session(SessionId('malformed'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('is a no-op when the pane id is empty', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
bash.result = runResult(`${tmuxLine({ paneId: '' })}\n`)
|
||||
const session = new Session(SessionId('empty-pane'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('warns and injects nothing when the executor rejects the run', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
bash.runError = new Error('bash executor unavailable')
|
||||
const warn = vi.spyOn(ctx.logger, 'warn')
|
||||
const session = new Session(SessionId('run-rejected'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
expect(warn).toHaveBeenCalledWith(expect.stringContaining('bash executor unavailable'))
|
||||
})
|
||||
|
||||
it('warns and injects nothing when the executor rejects the command at resolve', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
bash.resolveError = new Error('command denied by policy')
|
||||
const warn = vi.spyOn(ctx.logger, 'warn')
|
||||
const session = new Session(SessionId('resolve-rejected'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
expect(warn).toHaveBeenCalledWith(expect.stringContaining('command denied by policy'))
|
||||
})
|
||||
|
||||
it('reports a non-Error rejection in the warning', async () => {
|
||||
const { ctx, bash } = await mount({}, true)
|
||||
// Non-Error throw: the executor seam is typed, but a bad impl can reject with anything.
|
||||
bash.runError = 'spawn refused' as unknown as Error
|
||||
const warn = vi.spyOn(ctx.logger, 'warn')
|
||||
const session = new Session(SessionId('non-error-rejection'))
|
||||
openMessageTurn(session, 1)
|
||||
|
||||
await fire(ctx, sessionAgent(session), 1, 1)
|
||||
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
expect(warn).toHaveBeenCalledWith(expect.stringContaining('spawn refused'))
|
||||
})
|
||||
|
||||
it('skips an already-aborted step and runs before ordinary agent/step listeners', async () => {
|
||||
const { ctx } = await mount({}, true)
|
||||
const session = new Session(SessionId('ordering'))
|
||||
const agent = sessionAgent(session)
|
||||
openMessageTurn(session, 1)
|
||||
let ordinarySawContext = false
|
||||
ctx.on('agent/step', (subject) => {
|
||||
ordinarySawContext = subject.session.events.some(
|
||||
event => event.type === 'user/message'
|
||||
&& event.data.source.kind === 'plugin'
|
||||
&& event.data.source.plugin === 'tmux-context',
|
||||
)
|
||||
})
|
||||
|
||||
const abort = new AbortController()
|
||||
abort.abort()
|
||||
await fire(ctx, agent, 1, 1, abort.signal)
|
||||
expect(contextTexts(session)).toHaveLength(0)
|
||||
|
||||
await fire(ctx, agent, 1, 1)
|
||||
expect(ordinarySawContext).toBe(true)
|
||||
expect(contextTexts(session)).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe('tmux-context configuration', () => {
|
||||
it('rejects a negative refresh interval at plugin load', async () => {
|
||||
await expect(mount({ refreshIntervalMs: -1 })).rejects.toThrow(
|
||||
/refreshIntervalMs must be a non-negative safe integer/,
|
||||
)
|
||||
})
|
||||
|
||||
it('rejects a non-integer refresh interval at plugin load', async () => {
|
||||
await expect(mount({ refreshIntervalMs: 1.5 })).rejects.toThrow(
|
||||
/refreshIntervalMs must be a non-negative safe integer/,
|
||||
)
|
||||
})
|
||||
})
|
||||
37
packages/context/tmux-context/tsconfig.json
Normal file
37
packages/context/tmux-context/tsconfig.json
Normal file
@@ -0,0 +1,37 @@
|
||||
{
|
||||
"extends": "../../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "src",
|
||||
"outDir": "lib/types"
|
||||
},
|
||||
"include": ["src"],
|
||||
"references": [
|
||||
{
|
||||
"path": "../../../vendor/cosmokit"
|
||||
},
|
||||
{
|
||||
"path": "../../../vendor/cordis"
|
||||
},
|
||||
{
|
||||
"path": "../../../vendor/schemastery"
|
||||
},
|
||||
{
|
||||
"path": "../../llm/llm"
|
||||
},
|
||||
{
|
||||
"path": "../../bash/bash"
|
||||
},
|
||||
{
|
||||
"path": "../../core/agent"
|
||||
},
|
||||
{
|
||||
"path": "../../core/system-prompt"
|
||||
},
|
||||
{
|
||||
"path": "../../support/invariants"
|
||||
},
|
||||
{
|
||||
"path": "../../core/session"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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 packages/context/workspace-context/README.md
|
||||
README.md: df75b29dd3e8dbb504aac9e9885c32a809cbf70f
|
||||
README.zh.md: 8bd926302f09ecdf453c7832b3a15b0e7fcc1b2a
|
||||
README.md: 2669422ec1fa7a74ba329cd96ee6b7e5e6da7e9d
|
||||
README.zh.md: e9fab4c6998f1193068389b41bdd7fa7d8c98dca
|
||||
|
||||
@@ -42,7 +42,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
|
||||
</system-reminder>
|
||||
```
|
||||
|
||||
A same-file edit starts with `Updated instructions from: <path>` 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: <path>` followed by `The previously loaded instructions from this file no longer apply.` Literal `</system-reminder>` 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: <path>` 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: <path>` followed by `The previously loaded instructions from this file no longer apply.` Literal `</system-reminder>` text anywhere in instruction content or model-visible path, scope, and budget metadata is escaped so repository-controlled text cannot close the plugin-owned frame.
|
||||
|
||||
The plugin owns the complete `<system-reminder>` framing, and every injected `user/message` reaches the model verbatim with no core wrapper.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
为每个会话加载与 `AGENTS.md` 兼容的工作区指令文件。该插件会将初始 user 全局指令与项目指令链注入持久历史，随后发现嵌套文件，并在成功的文件系统工具调用后报告后续变更或移除。
|
||||
为每个会话加载与 `AGENTS.md` 兼容的工作区指令文件。该插件会将初始的用户全局指令与项目指令链注入持久历史，随后发现嵌套文件，并在成功的文件系统工具调用后报告后续变更或移除。
|
||||
|
||||
## 生命周期
|
||||
|
||||
@@ -10,9 +10,9 @@
|
||||
|
||||
该插件还会监听 `tools/post-execute` 中成功的第一方 `read`、`write` 和 `edit` 调用。每次 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件通过结果的 `additionalContexts` 附加；已改变文件追加替换；文件消失或成为同一目录中较早候选文件的重复项时，追加移除通知。原生调用与 Code Mode 子分派共享该路径：`run_code` 将每个嵌套上下文延迟到外层结果，因此 loop 仍会在工具调用／结果相邻关系完成后追加更新。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
|
||||
|
||||
指令读取使用可选 `ctx.fs` 提供方。该插件不会静态注入 `fs`，因此没有提供方的产品树仍可启动，指令加载在提供方出现前不执行任何操作。它会解析每个候选文件并获取结果状态，因此会跟随最终组件 symlink 到其目标：指向常规文件的链接会加载目标内容，缺失路径或非文件目标（包括指向目录的链接）则已确认不存在。resolve 或 stat 异常会改为将该候选文件的 scope 标记为暂时不可用。步骤取消与动态工具取消会传播到解析、元数据探测与流式读取。文件加载后的提供方失败会视为暂时不可用，而非文件已删除的证据。
|
||||
指令读取使用可选 `ctx.fs` 提供方。该插件不会静态注入 `fs`，因此没有提供方的产品树仍可启动，指令加载在提供方出现前不执行任何操作。它会解析每个候选文件并对解析结果执行 stat，因此会跟随路径最后一段的 symlink 到其目标：指向常规文件的链接会加载目标内容，缺失路径或非文件目标（包括指向目录的链接）则已确认不存在。resolve 或 stat 异常会改为将该候选文件的 scope 标记为暂时不可用。前缀取消与动态工具取消会传播到解析、元数据探测与流式读取。文件加载后的提供方失败会视为暂时不可用，而非文件已删除的证据。
|
||||
|
||||
## 提示词形状
|
||||
## 提示词结构
|
||||
|
||||
基线指令是持久的 user 角色消息，使用熟悉的 system-reminder 模式框定：
|
||||
|
||||
@@ -42,15 +42,15 @@ These instructions apply to work under `packages/app`. Use them as guidance when
|
||||
</system-reminder>
|
||||
```
|
||||
|
||||
同一文件的编辑以 `Updated instructions from: <path>` 开头，并说明使用新内容替代之前加载的内容。候选文件消失或成为同一目录中较早候选文件的重复项时，消息是 `Instructions removed: <path>`，后跟 `The previously loaded instructions from this file no longer apply.`。指令文件中的字面 `</system-reminder>` 文本会转义，因此文件内容无法关闭插件拥有的 frame。
|
||||
同一文件的编辑以 `Updated instructions from: <path>` 开头，并说明使用新内容替代之前加载的内容。候选文件消失或成为同一目录中较早候选文件的重复项时，消息是 `Instructions removed: <path>`，后跟 `The previously loaded instructions from this file no longer apply.`。指令内容或模型可见的路径、scope 与预算元数据中出现的字面 `</system-reminder>` 文本都会转义，因此仓库控制的文本无法关闭插件控制的框架。
|
||||
|
||||
该插件拥有完整 `<system-reminder>` framing，每个注入的 `user/message` 都会在没有核心包装的情况下逐字达到模型。
|
||||
该插件控制完整的 `<system-reminder>` 框架，每个注入的 `user/message` 都不经核心包装便原样传给模型。
|
||||
|
||||
## 状态与刷新
|
||||
|
||||
模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整的启动或恢复基线还会携带 `baseline: true`。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。匹配的持久 `user/message` 会确认 pending 转换。如果所属 `step/end` 在匹配上下文进入日志之前到达，插件会清除 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
|
||||
|
||||
路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
|
||||
路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
|
||||
|
||||
初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态；下一次成功的文件系统 touch 会在压缩后重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。插件热重挂只有在其带类型的事件仍然可见时才保留基线，同时会重建当前 scope 与版本跟踪状态；否则会注入当前基线。恢复的 loop 始终重新组合当前基线，并在第一个请求前对账仍可见的动态 scope。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复 loop 准备基线时可见。
|
||||
|
||||
@@ -67,15 +67,15 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
`maxBytes` 必填，因此每个部署都必须显式选择提示词预算。`maxSourceBytes` 在渲染前限制每个源指令文件，默认为 1 MiB。`projectRootMarkers` 默认为 `['.git']`，`instructionFileCandidates` 默认为 `['AGENTS.md', 'CLAUDE.md']`。每个项目目录中的所有现有候选文件都会加载，在去除周围空白后与较早候选文件内容匹配的文件会被丢弃。因此，使用默认设置时，内容相同的 `AGENTS.md` 与 `CLAUDE.md` 只渲染一次（作为 `AGENTS.md`），真正不同的同级文件则同时应用。`localInstructionFileCandidates` 默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`，会与同一目录的基础文件一起加载其现有 overlay（渲染在它们之后），并应用同一个每目录去重；空列表会禁用 overlay。两个列表的候选配置项都必须是同目录文件名，因此会忽略空配置项、`.`／`..` 以及包含 `/` 或 `\` 的配置项。
|
||||
`maxBytes` 必填，因此每个部署都必须显式选择提示词预算。`maxSourceBytes` 在渲染前限制每个源指令文件，默认为 1 MiB。`projectRootMarkers` 默认为 `['.git']`，`instructionFileCandidates` 默认为 `['AGENTS.md', 'CLAUDE.md']`。每个项目目录中的所有现有候选文件都会加载，在去除周围空白后与较早候选文件内容匹配的文件会被丢弃。因此，使用默认设置时，内容相同的 `AGENTS.md` 与 `CLAUDE.md` 只渲染一次（作为 `AGENTS.md`），真正不同的同级文件则同时应用。`localInstructionFileCandidates` 默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`，会与同一目录的基础文件一起加载其现有 overlay（渲染在它们之后），并应用同一个每目录去重；空列表会禁用 overlay。两个列表中的候选项都必须是同一目录下的文件名，因此会忽略空项、`.`／`..` 以及包含 `/` 或 `\` 的项。
|
||||
|
||||
user 全局文件始终是 `$DSH_HOME/AGENTS.md`，没有本地 overlay；两个候选列表只控制项目 scope。`$DSH_HOME` 默认为 `~/.dsh`，已配置的 `~`、`~/...` 与 Windows 风格 `~\...` 前缀会基于操作系统 home 目录展开。非正数或非有限渲染预算会同时禁用基线与动态加载；已配置 `maxSourceBytes` 必须是正整数。
|
||||
用户全局文件始终是 `$DSH_HOME/AGENTS.md`，没有本地 overlay；两个候选列表只控制项目 scope。`$DSH_HOME` 默认为 `~/.dsh`，已配置的 `~`、`~/...` 与 Windows 风格 `~\...` 前缀会基于操作系统 home 目录展开。非正数或非有限渲染预算会同时禁用基线与动态加载；已配置 `maxSourceBytes` 必须是正整数。
|
||||
|
||||
## 预算与有界读取
|
||||
|
||||
渲染会优先保留最具体的指令文件。它会先丢弃完整的较宽泛文件，再截断最具体文件，并发出可见 `Workspace instruction budget ...` 通知，其中指名已省略与已截断路径。渲染后字节数绝不超过 `maxBytes`。
|
||||
|
||||
即使提供方元数据省略大小，或文件在元数据探测后增长，指令内容仍会通过 `streamText()` 在 `maxSourceBytes` 下读取。超大文件会被忽略；在动态对账期间，它会暂时不可用，而不是被移除。该插件不保留进程级 cache，绝不缓存指令文本。其会话本地 scope cache 只将提供方版本用作快速失效信号；失效后，对有界读取计算的 SHA-1 仍是存储在结构化消息来源中的跨提供方内容身份。
|
||||
即使提供方元数据省略大小，或文件在元数据探测后增长，指令内容仍会通过 `streamText()` 在 `maxSourceBytes` 下读取。超大文件会被忽略；在动态对账期间，它会暂时不可用，而不是被移除。该插件不保留进程级 cache，绝不缓存指令文本。其会话本地 scope cache 只将提供方版本用作快速失效信号；失效后，对有界读取计算的 SHA-1 仍是存储在结构化消息来源中的跨提供方内容标识。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -83,7 +83,7 @@ user 全局文件始终是 `$DSH_HOME/AGENTS.md`，没有本地 overlay；两个
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
在每个 loop 实例的第一个请求中，模型会收到一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界 user 全局指令与项目指令链。
|
||||
在每个 loop 实例的第一个请求中，模型会收到一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界用户全局指令与项目指令链。
|
||||
|
||||
##### 基线指令模板
|
||||
|
||||
@@ -133,7 +133,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
|
||||
### 已改变或移除的指令上下文
|
||||
|
||||
@@ -157,13 +157,13 @@ The previously loaded instructions from this file no longer apply.
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
|
||||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **发现跟随结构化 fs 工具，而非 shell 导航**：更改目录的 `bash` 命令不会触发嵌套指令发现，因为 shell 语法与每次调用 shell 状态不是可靠的文件系统 seam。
|
||||
- **刷新由 touch 驱动**：没有 watcher；外部编辑会在下一次成功的第一方 `read`、`write` 或 `edit` 时可见，也会在恢复 loop 准备基线时可见。
|
||||
- **候选语义有意保持简单**：不解释小写名称、`.claude/rules/` 与 `@path` import；项目 scope 默认加载 `AGENTS.local.md`／`CLAUDE.local.md` overlay，但 user 全局 `$DSH_HOME` scope 没有本地 overlay，其他自定义名称需要显式候选配置。
|
||||
- **候选语义有意保持简单**：不解释小写名称、`.claude/rules/` 与 `@path` import；项目 scope 默认加载 `AGENTS.local.md`／`CLAUDE.local.md` overlay，但用户全局 `$DSH_HOME` scope 没有本地 overlay，其他自定义名称需要显式候选配置。
|
||||
- **每目录去重基于内容**：只有在去除首尾空白后字节完全一致时，才折叠同级候选文件。`CLAUDE.md` 若 symlink 到同级 `AGENTS.md`，会解析为相同内容，并像任何重复项一样折叠；从 `AGENTS.md` 漂移的独立实体副本则会与它一起完整加载。
|
||||
- **Symlink 指令文件会跨越信任边界跟随**：最终组件是 symlink 的候选文件会被解析并加载其目标，因此克隆仓库可以将树外文件内容呈现为较低权限的工作区指引（它绝不会覆盖 system、developer 或直接 user 指令）。加载不受信任仓库时，请用文件系统策略门禁或 OS 沙箱限制 `ctx.fs`。
|
||||
- **指令内容受限但不会摘要**：超出预算的宽泛文件会被省略，最具体文件可能被截断；该插件绝不请求模型压缩指令文本。
|
||||
- **Symlink 指令文件会跨越信任边界跟随**：最终组件是 symlink 的候选文件会被解析并加载其目标，因此克隆仓库可以将树外文件内容呈现为较低优先级的工作区指引（它绝不会覆盖 system、developer 或用户直接下达的指令）。加载不受信任仓库时，请用文件系统策略门禁或 OS 沙箱限制 `ctx.fs`。
|
||||
- **指令内容受限但不会被摘要**：超出预算的宽泛文件会被省略，最具体文件可能被截断；该插件绝不请求模型压缩指令文本。
|
||||
|
||||
@@ -59,15 +59,12 @@ function truncateUtf8(value: string, maxBytes: number): string {
|
||||
return truncated
|
||||
}
|
||||
|
||||
function escapeInstructionContent(content: string): string {
|
||||
// TODO(instruction-frame-paths): apply the same delimiter neutralization to
|
||||
// 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>')
|
||||
function escapeInstructionFrameBody(body: string): string {
|
||||
return body.replaceAll(SYSTEM_REMINDER_CLOSE, '<\\/system-reminder>')
|
||||
}
|
||||
|
||||
function sectionText(file: LoadedInstructionFile): string {
|
||||
return `Instructions from: ${file.displayPath}\n\n${escapeInstructionContent(file.content)}`
|
||||
return `Instructions from: ${file.displayPath}\n\n${file.content}`
|
||||
}
|
||||
|
||||
/** Directory component that identifies the single user-global instruction scope. */
|
||||
@@ -136,7 +133,7 @@ function additionalSectionText(file: LoadedInstructionFile): string {
|
||||
'',
|
||||
`These instructions apply to work under \`${scope}\`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.`,
|
||||
'',
|
||||
escapeInstructionContent(file.content),
|
||||
file.content,
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
@@ -153,7 +150,7 @@ function changedSectionText(item: ChangeRenderItem): string {
|
||||
'',
|
||||
'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.',
|
||||
'',
|
||||
escapeInstructionContent(file.content),
|
||||
file.content,
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
@@ -214,7 +211,7 @@ function buildInstructionText(
|
||||
// producer's content (the pattern a future `meta`-driven renderer would
|
||||
// generalize — see the deferred note in
|
||||
// ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md).
|
||||
return [SYSTEM_REMINDER_OPEN, body.join('\n\n'), SYSTEM_REMINDER_CLOSE].join('\n')
|
||||
return [SYSTEM_REMINDER_OPEN, escapeInstructionFrameBody(body.join('\n\n')), SYSTEM_REMINDER_CLOSE].join('\n')
|
||||
}
|
||||
|
||||
function withTruncatedContent(file: LoadedInstructionFile, includedBytes: number): LoadedInstructionFile {
|
||||
@@ -285,8 +282,10 @@ function renderInstructionContext(
|
||||
originalBytes: byteLength(mostSpecific.content),
|
||||
includedBytes: 0,
|
||||
}]
|
||||
const compactNotice = markerText(maxBytes, omitted, truncated)
|
||||
const compactWithHeading = [compactNotice, style.section(withTruncatedContent(mostSpecific, 0))].join('\n\n')
|
||||
const compactNotice = escapeInstructionFrameBody(markerText(maxBytes, omitted, truncated))
|
||||
const compactWithHeading = escapeInstructionFrameBody(
|
||||
[compactNotice, style.section(withTruncatedContent(mostSpecific, 0))].join('\n\n'),
|
||||
)
|
||||
if (byteLength(compactWithHeading) <= maxBytes) return { text: compactWithHeading, omitted, truncated }
|
||||
const text = byteLength(compactNotice) <= maxBytes ? compactNotice : truncateUtf8(compactNotice, maxBytes)
|
||||
return { text, omitted, truncated }
|
||||
|
||||
@@ -41,7 +41,7 @@ import {
|
||||
type InstructionVersionCache,
|
||||
type PendingInstructionChange,
|
||||
} from '../src/state.ts'
|
||||
import { candidateScopeKey } from '../src/render.ts'
|
||||
import { candidateScopeKey, renderInstructionChanges } 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. */
|
||||
@@ -184,6 +184,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
|
||||
session.append('user/message', input, { surfaceOp: 'append' })
|
||||
},
|
||||
send: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
@@ -681,6 +682,37 @@ describe('workspace context rendering', () => {
|
||||
expect(rendered.text).toContain('<\\/system-reminder>')
|
||||
})
|
||||
|
||||
it('neutralizes system-reminder closing delimiters in paths and derived scopes', () => {
|
||||
const displayPath = 'scope</system-reminder>/AGENTS.md'
|
||||
const file = { absolutePath: `/repo/${displayPath}`, displayPath, content: 'rules' }
|
||||
const rendered = [
|
||||
renderWorkspaceContext([file], { maxBytes: 65536 }).text,
|
||||
...(['set', 'replace', 'remove'] as const).map(action => renderInstructionChanges([{
|
||||
change: { action, scope: 'scope</system-reminder>\0AGENTS.md', path: displayPath },
|
||||
file,
|
||||
}], 65536).text),
|
||||
]
|
||||
|
||||
for (const text of rendered) {
|
||||
expect(text.match(/<\/system-reminder>/g)).toHaveLength(1)
|
||||
expect(text).toContain('scope<\\/system-reminder>')
|
||||
}
|
||||
})
|
||||
|
||||
it('neutralizes a system-reminder closing delimiter in budget marker paths', () => {
|
||||
const rendered = renderWorkspaceContext([
|
||||
{
|
||||
absolutePath: '/repo/scope</system-reminder>/AGENTS.md',
|
||||
displayPath: 'scope</system-reminder>/AGENTS.md',
|
||||
content: 'root '.repeat(100),
|
||||
},
|
||||
{ absolutePath: '/repo/leaf/AGENTS.md', displayPath: 'leaf/AGENTS.md', content: 'leaf rules' },
|
||||
], { maxBytes: 400 })
|
||||
|
||||
expect(rendered.text).toContain('omitted scope<\\/system-reminder>/AGENTS.md')
|
||||
expect(rendered.text.match(/<\/system-reminder>/g)).toHaveLength(1)
|
||||
})
|
||||
|
||||
it('preserves more specific files under the byte budget and names omitted/truncated paths', () => {
|
||||
const rendered = renderWorkspaceContext([
|
||||
{ absolutePath: '/repo/AGENTS.md', displayPath: 'AGENTS.md', content: 'root '.repeat(100) },
|
||||
|
||||
Reference in New Issue
Block a user