@deepseek-ai/dsh-tmux-context 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.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 packages/context/tmux-context/README.md
+README.md: 59c452be53b8bb7cb7244a9bb2017749750ce4bf
+README.zh.md: f343c9b25c832cafcb3366209bc2ce39308ad0d5

package/README.md

@@ -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. It is sampled once per turn during model-request preparation and is not part of the shipped Web/headless composition. 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/pre-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 service:
+
+```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
+
+The plugin prepends an `agent/pre-step` listener. When an injection is due and the downstream decision enters the proposed step, it prepends one sourced `UserMessage` to the returned batch. AgentLoop records that context after `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. A downstream pre-step listener that rejects or fails prevents the reading from being recorded.
+
+## 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.

package/README.zh.md

@@ -0,0 +1,68 @@
+# @deepseek-ai/dsh-tmux-context
+
+[English](README.md) | 中文
+
+可选启用的持久上下文，记录本 agent（智能体）进程所在的 tmux session、window、pane，以及该 window 的 pane 树布局。在准备模型请求时每轮采样一次；随附 Web／无头组合不包含它。决策记录见：[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/pre-step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器服务运行一条只读命令：
+
+```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 状态与上次注入不同时才重新注入，因此位置不变时不会新增任何内容。
+
+## 时序语义
+
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会向返回的批次前置添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游 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 Cache 影响
+
+只追加；新增可见内容位于可复用的请求前缀之后，不会使已有 KV Cache 条目失效。
+
+## 已知限制与后续工作
+
+- **仅第一个 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}` 不可用的环境中，该检查即为空操作。

package/lib/index.js

@@ -0,0 +1,350 @@
+import { createRequire } from "node:module";
+import z from "@deepseek-ai/schemastery";
+import "@deepseek-ai/cordis";
+//#region ../../llm/llm/src/brand.ts
+/**
+* Brand a message identifier.
+* @param id - the opaque message identifier.
+* @returns the same string, branded; no validation is performed.
+*/
+function MessageId(id) {
+	return id;
+}
+//#endregion
+//#region ../../llm/llm/src/call-config.ts
+/**
+* Deep-freeze a value in place with an iterative traversal, guarding cycles,
+* so later mutation throws without imposing a JavaScript call-stack depth cap.
+* {@link AbortSignal} objects are deliberately skipped because they are the
+* request's live cancellation channel and freezing them breaks abort.
+* @param value - the value to freeze in place.
+* @returns the same value, frozen.
+*/
+function deepFreeze(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const pending = [{
+		kind: "visit",
+		node: value
+	}];
+	while (pending.length > 0) {
+		const task = pending.pop();
+		/* v8 ignore next -- the loop condition guarantees one pending task. */
+		if (task === void 0) continue;
+		if (task.kind === "property") {
+			pending.push({
+				kind: "visit",
+				node: task.source[task.key]
+			});
+			continue;
+		}
+		const node = task.node;
+		if (node === null || typeof node !== "object") continue;
+		if (node instanceof AbortSignal) continue;
+		if (seen.has(node)) continue;
+		seen.add(node);
+		Object.freeze(node);
+		const keys = Object.keys(node);
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) continue;
+			pending.push({
+				kind: "property",
+				source: node,
+				key
+			});
+		}
+	}
+	return value;
+}
+//#endregion
+//#region ../../llm/llm/src/message.ts
+/** Message value types, identity, and immutable construction helpers. */
+/**
+* Detach and deep-freeze a message whose identity already exists.
+* @param message - complete message, including its stable identity.
+* @returns an immutable snapshot that preserves the identity.
+*/
+function freezeMessage(message) {
+	return deepFreeze(structuredClone(message));
+}
+/**
+* Create one identified message and freeze it before publication.
+* @param input - complete role, content, and source for a new message.
+* @returns an immutable message with a fresh stable identity.
+*/
+function createMessage(input) {
+	return freezeMessage({
+		...input,
+		id: MessageId(crypto.randomUUID())
+	});
+}
+/**
+* Create one identified user-role message and freeze it before publication.
+* @param input - complete content and source for a new user message.
+* @returns an immutable user message with a fresh stable identity.
+*/
+function createUserMessage(input) {
+	return createMessage({
+		...input,
+		role: "user"
+	});
+}
+//#endregion
+//#region ../../util/timeout/src/index.ts
+/** Largest delay Node schedules without clamping it to one millisecond. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+//#endregion
+//#region ../../llm/llm/src/error.ts
+/**
+* Canonical provider-neutral code for a response that completed normally but
+* carried no content blocks at all. Providers occasionally emit a degenerate
+* completion (a terminal stop with zero output); adapters classify it as this
+* failure instead of yielding an empty assistant message, because an empty
+* message silently ends the turn with nothing for the user or the loop to act
+* on. The attempt produced nothing durable, so retry policy treats it as safe
+* to repeat.
+*/
+const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
+new RegExp(String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]` + String.raw`(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, "i");
+new RegExp(String.raw`\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?` + String.raw`too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?` + String.raw`(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, "i");
+new RegExp(String.raw`\b(?:input|prompt|request|messages?)\b.{0,40}` + String.raw`\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}` + String.raw`\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, "i");
+//#endregion
+//#region ../../llm/llm/src/retry-policy.ts
+/**
+* Provider-owned request-retry policy configuration and resolution.
+*
+* Adapters expose one resolved policy per registered provider route; the
+* optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
+*
+* @module @deepseek-ai/dsh-llm/retry-policy
+*/
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 1e4;
+const DEFAULT_JITTER_RATIO = .1;
+const DEFAULT_RETRYABLE_CODES = Object.freeze([
+	EMPTY_RESPONSE_CODE,
+	"RATE_LIMIT",
+	"SERVER",
+	"TIMEOUT",
+	"TRANSPORT"
+]);
+const backoffSchema = z.object({
+	initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
+	maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
+	jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO)
+});
+const normalPolicySchema = z.object({
+	mode: z.const("normal").required(),
+	maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
+	retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
+	backoff: backoffSchema
+});
+const alwaysPolicySchema = z.object({
+	mode: z.const("always").required(),
+	backoff: backoffSchema
+});
+z.union([normalPolicySchema, alwaysPolicySchema]);
+//#endregion
+//#region ../../llm/llm/src/attribution.ts
+/**
+* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+* adapters from drifting. See
+* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+*
+* App-attribution vocabulary for provider requests.
+* @module @deepseek-ai/dsh-llm/attribution
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+//#endregion
+//#region lib/types/index.js
+/**
+* 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, for the first request (`step === 1`), by
+* running one `tmux display-message` through the `ctx.bash` executor service. 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
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "tmux-context";
+/** The agent registry that owns pre-step processing. */
+const inject = ["agents"];
+/** Schemastery validation for {@link Config}. */
+const 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}"
+];
+/** 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 service 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, logger, processId, signal) {
+	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;
+	try {
+		result = await bash.run(bash.resolve({
+			command,
+			signal
+		}));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.warn(`tmux location query failed: ${message}; injecting no location this turn`);
+		return;
+	}
+	if (result.exitCode !== 0) return void 0;
+	const parts = result.stdout.text.split("\n", 1)[0].split(FIELD_SEP);
+	if (parts.length !== TMUX_FIELDS.length) return void 0;
+	const [sessionName, windowIndex, windowName, paneIndex, paneId, windowActive, paneActive, windowLayout] = parts;
+	if (paneId.length === 0) return void 0;
+	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) {
+	return `session ${location.sessionName}, window ${location.windowIndex} ${JSON.stringify(location.windowName)}, pane ${location.paneIndex} ${location.paneId}\nwindow active=${location.windowActive}, pane active=${location.paneActive}, layout ${location.windowLayout}`;
+}
+/** Render the full durable reading, including the volatile turn preamble. */
+function renderReading(location, turn) {
+	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) {
+	for (const event of [...agent.session.events].reverse()) if (event.type === "user/message" && event.data.source.kind === "plugin" && event.data.source.plugin === "tmux-context") {
+		const [block] = event.data.content;
+		if (block?.type !== "text") return void 0;
+		const newline = block.text.indexOf("\n");
+		return {
+			state: newline === -1 ? "" : block.text.slice(newline + 1),
+			time: event.time
+		};
+	}
+}
+/** Reject refresh intervals that cannot represent an exact elapsed-millisecond threshold. */
+function validateRefreshInterval(refreshIntervalMs) {
+	if (refreshIntervalMs !== void 0 && (!Number.isSafeInteger(refreshIntervalMs) || refreshIntervalMs < 0)) throw new TypeError(`tmux-context: refreshIntervalMs must be a non-negative safe integer, got ${String(refreshIntervalMs)}`);
+}
+/**
+* Register a prepended pre-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.
+*/
+function apply(ctx, config) {
+	const refreshIntervalMs = config.refreshIntervalMs;
+	validateRefreshInterval(refreshIntervalMs);
+	ctx.on("agent/pre-step", async ({ agent, turn, step, signal }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject" || signal.aborted || step !== 1) return decision;
+		const bash = ctx.get("bash");
+		if (bash === void 0) return decision;
+		const previous = latestInjectedState(agent);
+		if (refreshIntervalMs !== void 0 && refreshIntervalMs > 0 && previous !== void 0) {
+			const now = Date.now();
+			if (now >= previous.time && now - previous.time < refreshIntervalMs) return decision;
+		}
+		const location = await queryTmuxLocation(bash, ctx.logger, process.pid, signal);
+		if (location === void 0) return decision;
+		const state = renderState(location);
+		if (previous !== void 0 && previous.state === state) return decision;
+		const text = renderReading(location, turn);
+		return {
+			kind: "enter",
+			messages: [createUserMessage({
+				content: [{
+					type: "text",
+					text
+				}],
+				source: {
+					kind: "plugin",
+					plugin: name,
+					form: "snapshot",
+					sections: [{
+						name,
+						text
+					}]
+				}
+			}), ...decision.messages]
+		};
+	}, { prepend: true });
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tmux-context`.
+* @module @deepseek-ai/dsh-tmux-context/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tmux-context";
+/** Cordis companion plugin name. */
+const name = "tmux-context-invariant";
+/** Service required before the companion can reserve package ownership. */
+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 = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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, for the first request (`step === 1`), by
+ * running one `tmux display-message` through the `ctx.bash` executor service. 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 } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "tmux-context";
+/** The agent registry that owns pre-step processing. */
+export declare const inject: string[];
+/** 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 declare const Config: z<Config>;
+/**
+ * Register a prepended pre-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 declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tmux-context`.
+ * @module @deepseek-ai/dsh-tmux-context/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tmux-context-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "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-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1"
+  }
+}