{"_id":"@buddhilive/dsh-tmux-context","name":"@buddhilive/dsh-tmux-context","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-tmux-context","description":"Opt-in durable per-step context with this agent's tmux pane and window location","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/context/tmux-context"},"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"},"license":"MIT","dependencies":{"zod":"^4.4.3","@deepseek-ai/schemastery":"^3.18.2"},"peerDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-shell":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3"},"devDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-shell":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-tmux-context@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-tWysSisbyN6YolO+BuqURXEipYAJL5EjAtlK5ks2/qwV7ztfHxhQVHnxvQDuPt/fnhlcuKaC9en5//CaG6ZG2Q==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-tmux-context-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-tmux-context-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-tWysSisbyN6YolO+BuqURXEipYAJL5EjAtlK5ks2/qwV7ztfHxhQVHnxvQDuPt/fnhlcuKaC9en5//CaG6ZG2Q==","shasum":"37b1ba161b222e31fe6ef94450cddc7242eda1e3","tarball":"https://registry.npmjs.org/@buddhilive/dsh-tmux-context/-/dsh-tmux-context-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":85545,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDScXfNUhaUXtumdSOUGpJsFvWa6sDct+NwYP7fwlb65AiBXcf/s7geIuTJ3mhpftw5hSXibWJbhbQVMpMfVl8lQ4A=="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-tmux-context_0.1.2-alpha.3_1788166611447_0.6155637363519502"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:56:51.159Z","0.1.2-alpha.3":"2026-08-31T08:56:51.584Z","modified":"2026-08-31T08:56:51.833Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Opt-in durable per-step context with this agent's tmux pane and window location","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/context/tmux-context"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"可选的按轮次 tmux 位置上下文，供启用或调优 agent 的 session、window 与 pane 感知的用户与维护者阅读。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-tmux-context\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-tmux-context` 告诉模型它的 agent（智能体）进程运行在哪里：在 tmux 状态发生变化的每一轮，它追加一条持久、带来源的读数，命名 tmux session、window 与 pane，以及该 window 的 pane 树布局。它在准备模型请求时每轮采样一次，且仅当进程确实位于所指名的 pane 内时——仅从 tmux 祖先进程继承了 `$TMUX`／`$TMUX_PANE` 的终端会被视为不在 tmux 中，不添加任何内容。位置未变化时不添加任何内容；查询失败是空操作，绝不导致轮次失败。本插件需主动启用，且不属于随附 Web／无头组合。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当 agent 进程运行在 tmux 内、且模型需要知道其 window 与 pane 位置时，挂载此插件。每条读数都是持久历史中额外的一条 user 角色消息；位置未变化时不添加任何内容，因此长时会话累积很少。\n\n### 模型能得到什么\n\n在 tmux 状态发生变化的每一轮，模型会收到一条带来源标记的上下文消息，包含 session 名称、window 索引与名称、pane 索引与 id、活动标志，以及紧凑的 pane 树布局。读数只发生在每轮的第一个步骤；轮次中途移动或缩放的 pane 会在下一轮反映。像素尺寸有意省略，相邻 pane 的可见内容从不采集。\n\n### 配置\n\n最小挂载无需任何配置。正的 `refreshIntervalMs` 会额外抑制距最近一次注入不足该毫秒数的注入；省略或设为 `0` 时，只要 tmux 状态自上次注入以来发生变化就注入。\n\n```yaml\n- name: '@buddhilive/dsh-tmux-context'\n  config:\n    refreshIntervalMs: 60000\n```\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `refreshIntervalMs` | `0`（每个变化轮次） | 同一会话中两次持久注入之间的最小毫秒数 |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-tmux-context)是每个受支持字段及其 JSDoc 的穷尽式真源。\n\n### 何时知道位置\n\n只有当进程的控制终端与 pane 的 `#{pane_tty}` 一致时，才视为位于 tmux 中；从 tmux shell 启动的终端（VS Code 集成终端、桌面启动器）会继承变量但不在 pane 内，因此被视为不在 tmux 中。`ctx.shell` 缺失、环境变量不存在或读数格式非法时是空操作；执行器拒绝会被兜住并记录为警告，而不会使该轮失败。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释插件的设计；可观察行为见[使用本包](#use-this-package)。\n\n### 设计理念\n\n插件前置注册一个 `agent/pre-step` 监听器，仅在每轮的第一个步骤运行。需要注入时，它通过 `ctx.shell` 执行器服务运行一条只读命令——部署方的沙箱与策略都会应用，插件不拥有任何子进程代码。命令在输出制表符分隔字段前，会比较 `$TMUX_PANE` 的 `#{pane_tty}` 与本进程自身的控制终端，因此继承的环境会被视为不在 tmux 中。插件只在渲染出的状态与上次注入不同时重新注入。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口：第一步监听器、shell 查询、变化抑制、调度 |\n| [`src/invariant.ts`](src/invariant.ts) | 快照约定的不变式伴生插件 |\n\n### 主要流程\n\n在每轮的第一个步骤，监听器检查注入是否到期，通过 `ctx.shell` 查询位置，并把渲染状态与该来源最近一次持久注入比较。变化抑制与间隔调度会扫描原始持久会话事件，因此调度可跨压缩（compaction）与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游在步骤前运行的监听器拒绝或失败时，该读数不会被记录。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n包级约定不够用时阅读以下页面。它们从设计决策进入查询所经由的执行器与穷尽式配置。\n\n- [tmux 位置上下文决策记录](../../../.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md)——基于 tty 的检测与读数形状的设计理由。\n- [shell 子系统](../../../docs/subsystems/shell.zh.md)——只读查询所经由的执行器服务。\n- [context 组地图](../README.zh.md)——相邻的请求上下文包。\n- [生成的配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-tmux-context)——每个受支持配置字段及其源声明。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 准备期 tmux 位置\n\n#### 模型看到的内容\n\n在 tmux 状态发生变化的每一轮，注入一条带来源标记、含以下三行的上下文消息。`<window-layout>` 是 tmux 紧凑的 pane 树描述；pane 与 window 的像素尺寸有意省略，相邻 pane 的内容从不采集。\n\n##### 变化轮次读数\n\n```markdown\ntmux location (turn <turn>):\nsession <session>, window <index> \"<name>\", pane <index> <pane-id>\nwindow active=<0|1>, pane active=<0|1>, layout <window-layout>\n```\n\n#### Token 影响\n\n每条三行读数会累积，直到压缩将其遮蔽。位置未变化以及间隔抑制不会新增内容。\n\n#### KV Cache 影响\n\n仅追加；新增可见内容位于可复用的请求前缀之后，不会使已有 KV Cache 条目失效。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明 tmux 位置上下文何时不合适。它们是当前包约束。\n\n- **仅第一个步骤**——轮次中途移动或缩放的 pane 会在下一轮反映，而非在步骤之间。\n- **仅自身位置**——插件从不采集相邻 pane 的可见文本。\n- **只有布局，没有尺寸**——省略 pane/window 像素尺寸；仅报告布局树与活动标志。\n- **制表符分隔字段**——若 tmux window 名称包含字面两字符序列 `\\t`，会使读数分割错误并作为非法读数跳过；常规名称不受影响。\n- **基于 tty 的 pane 判定**——只有当进程的控制终端与 `$TMUX_PANE` 的 `#{pane_tty}` 一致时，才视为「位于 tmux 中」。这会有意排除从 tmux 祖先进程继承 `$TMUX`／`$TMUX_PANE` 的终端（如 VS Code 集成终端）。`ps -o tty=` 属于 POSIX；在其或 `#{pane_tty}` 不可用的环境中，该检查即为空操作。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-40b84ba191be94363fff3e35bc45f19b"}