feat(context): add tmux-context plugin injecting the agent's tmux location

Add @deepseek-ai/dsh-tmux-context: an opt-in per-turn context plugin that
reads which tmux session/window/pane this agent process runs in (plus the
window layout tree) via the ctx.bash seam, and injects it as one durable,
source-attributed user/message when the location changes.

- Pull on the first step of each turn; no tmux hook or background process.
- Detect a real pane by tty, not $TMUX_PANE alone: a terminal launched from
  a tmux shell inherits $TMUX/$TMUX_PANE from that ancestor, so the command
  also matches the pane's #{pane_tty} against this process's controlling
  terminal and emits fields only on a match.
- No-op outside a real pane, without a bash executor, or on a malformed
  reading.
- Own location and layout only: no pane sizes, no sibling-pane scraping.
- Unit tests at 100% per-file coverage, plus a keyless Loader e2e with a
  mock bash provider so it replays without tmux.
- Agent Note: 2026-07-27-tmux-location-context.

examples/headless-agent/tests/fixtures/tmux-context-driver.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/** Test driver that sends two turns through one Headless Loader composition. */
+
+import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+
+const configPath = process.argv[2]
+if (configPath === undefined) throw new Error('tmux-context driver requires a config path')
+
+const ctx = await boot('tmux-context-e2e', resolveConfigPath(configPath, undefined))
+try {
+  await runOneShot(ctx, { task: 'first' })
+  await runOneShot(ctx, { task: 'second' })
+} finally {
+  await ctx.fiber.dispose()
+}

examples/headless-agent/tests/fixtures/tmux-context-mock-bash.ts

@@ -0,0 +1,46 @@
+import type { Context } from 'cordis'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
+
+/**
+ * Deterministic `ctx.bash` for the tmux-context Loader fixture: any command
+ * (the plugin's `tmux display-message`) returns a fixed tab-delimited reading,
+ * so the injected tmux location is stable without a real tmux server. `start()`
+ * throws — tmux-context must never spawn a background process.
+ */
+class TmuxMockBash extends BashExecutor {
+  override resolve(request: BashExecRequest): BashExecSpec {
+    return {
+      command: request.command,
+      workdir: request.workdir ?? process.cwd(),
+      timeoutMs: request.timeoutMs ?? 60_000,
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
+      signal: request.signal,
+      sandboxPolicy: request.sandboxPolicy,
+    }
+  }
+
+  override run(_spec: BashExecSpec): Promise<BashRunResult> {
+    const line = ['work', '0', 'editor', '1', '%3', '1', '1', 'a1b2,80x24,0,0,4'].join('\\t')
+    return Promise.resolve({
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      aborted: false,
+      timeoutMs: 60_000,
+      stdout: { text: `${line}\n`, truncated: false },
+      stderr: { text: '', truncated: false },
+    })
+  }
+
+  override start(): BashProcess {
+    throw new Error('tmux-context must never start a background task')
+  }
+}
+
+export const name = 'tmux-context-mock-bash'
+
+/** Register the deterministic `ctx.bash` executor for the fixture. */
+export function apply(ctx: Context): void {
+  ctx.plugin(TmuxMockBash)
+}

examples/headless-agent/tests/fixtures/tmux-context-mock-llm.ts

@@ -0,0 +1,22 @@
+import type { Context } from 'cordis'
+import { LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+/** Deterministic one-step adapter for the tmux-context Loader fixture. */
+class TmuxContextMockAdapter extends LlmAdapter {
+  async * stream(): AsyncIterable<StreamChunk> {
+    const text = 'tmux context sampled'
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'text-delta', index: 0, text }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text } }
+    yield { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+export const name = 'tmux-context-mock-llm'
+export const inject = ['llm']
+
+/** Register the test-only `tmux-context-mock` adapter. */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['tmux-context-mock'], new TmuxContextMockAdapter())
+}

examples/headless-agent/tests/fixtures/tmux-context.cordis.yml

@@ -0,0 +1,21 @@
+# Test-only composition: keep tmux-context opt-in while exercising its real Loader/app path.
+# A deterministic mock ctx.bash returns a fixed tmux reading, so the injected location
+# is stable without a real tmux server on the test host.
+- id: tmux-context-mock-llm
+  name: './tmux-context-mock-llm.ts'
+
+- id: bash
+  name: './tmux-context-mock-bash.ts'
+
+- id: tmux-context
+  name: '@deepseek-ai/dsh-tmux-context'
+
+- id: cli-agent
+  name: '@deepseek-ai/dsh-cli-demo'
+  config:
+    provider: tmux-context-mock
+    model: tmux-context-mock
+    persona: 'Test the tmux-context plugin.'
+    persistenceRoot: './.sessions'
+    persistenceCompression: 'none'
+    workspaceContext: false

examples/package.json

@@ -10,6 +10,7 @@
     "@deepseek-ai/dsh-acp-demo": "workspace:*",
     "@deepseek-ai/dsh-agent-spine-demo": "workspace:*",
     "@deepseek-ai/dsh-app-boot": "workspace:*",
+    "@deepseek-ai/dsh-bash": "workspace:*",
     "@deepseek-ai/dsh-bash-local": "workspace:*",
     "@deepseek-ai/dsh-bash-sandbox": "workspace:*",
     "@deepseek-ai/dsh-cli-demo": "workspace:*",
@@ -54,6 +55,7 @@
     "@deepseek-ai/dsh-tasks-local": "workspace:*",
     "@deepseek-ai/dsh-time-context": "workspace:*",
     "@deepseek-ai/dsh-timeout-policy": "workspace:*",
+    "@deepseek-ai/dsh-tmux-context": "workspace:*",
     "@deepseek-ai/dsh-token-meter": "workspace:*",
     "@deepseek-ai/dsh-tool-ask-user": "workspace:*",
     "@deepseek-ai/dsh-tool-cordis": "workspace:*",