@banbolee/dsh-fish-shell 0.7.0 → 0.8.0

package/node_modules/@deepseek-ai/cosmokit/src/types.ts

@@ -0,0 +1,168 @@
+import { isNullable } from './misc.ts'
+import { isVolatile } from './volatile.ts'
+
+type GlobalConstructorNames = keyof {
+  [K in keyof typeof globalThis as typeof globalThis[K] extends abstract new (...args: any) => any ? K : never]: K
+}
+
+/** Create a predicate for a global constructor name. */
+export function is<K extends GlobalConstructorNames>(type: K): (value: any) => value is InstanceType<typeof globalThis[K]>
+/** Test whether a value matches a global constructor name. */
+export function is<K extends GlobalConstructorNames>(type: K, value: any): value is InstanceType<typeof globalThis[K]>
+/** Test values using `instanceof` with a `toStringTag` fallback. */
+export function is<K extends GlobalConstructorNames>(type: K, value?: any): any {
+  if (arguments.length === 1) return (value: any) => is(type, value)
+  return type in globalThis && value instanceof (globalThis[type] as any)
+    || Object.prototype.toString.call(value).slice(8, -1) === type
+}
+
+function isArrayBufferLike(value: any): value is ArrayBufferLike {
+  return is('ArrayBuffer', value) || is('SharedArrayBuffer', value)
+}
+
+function isArrayBufferSource(value: any): value is Binary.Source {
+  return isArrayBufferLike(value) || ArrayBuffer.isView(value)
+}
+
+/** Binary source detection and base64/hex conversion helpers. */
+export namespace Binary {
+  export type Source<T extends ArrayBufferLike = ArrayBufferLike> = T | ArrayBufferView<T>
+
+  export const is = isArrayBufferLike
+  export const isSource = isArrayBufferSource
+
+  export function fromSource<T extends ArrayBufferLike>(source: Source<T>): T {
+    if (ArrayBuffer.isView(source)) {
+      // https://stackoverflow.com/questions/8609289/convert-a-binary-nodejs-buffer-to-javascript-arraybuffer#answer-31394257
+      return source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength) as T
+    } else {
+      return source
+    }
+  }
+
+  export function toBase64(source: Source) {
+    source = fromSource(source)
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(source).toString('base64')
+    }
+    let binary = ''
+    const bytes = new Uint8Array(source)
+    for (let i = 0; i < bytes.byteLength; i++) {
+      binary += String.fromCharCode(bytes[i])
+    }
+    return btoa(binary)
+  }
+
+  export function fromBase64(source: string) {
+    if (typeof Buffer !== 'undefined') return fromSource(Buffer.from(source, 'base64'))
+    return Uint8Array.from(atob(source), c => c.charCodeAt(0))
+  }
+
+  export function toHex(source: Source) {
+    source = fromSource(source)
+    if (typeof Buffer !== 'undefined') return Buffer.from(source).toString('hex')
+    return Array.from(new Uint8Array(source), byte => byte.toString(16).padStart(2, '0')).join('')
+  }
+
+  export function fromHex(source: string) {
+    if (typeof Buffer !== 'undefined') return fromSource(Buffer.from(source, 'hex'))
+    const hex = source.length % 2 === 0 ? source : source.slice(0, source.length - 1)
+    const buffer: number[] = []
+    for (let i = 0; i < hex.length; i += 2) {
+      buffer.push(parseInt(`${hex[i]}${hex[i + 1]}`, 16))
+    }
+    return Uint8Array.from(buffer).buffer
+  }
+}
+
+/** Decode a base64 string into binary data. */
+export const base64ToArrayBuffer = Binary.fromBase64
+/** Encode binary data as base64. */
+export const arrayBufferToBase64 = Binary.toBase64
+/** Decode a hex string into binary data. */
+export const hexToArrayBuffer = Binary.fromHex
+/** Encode binary data as hex. */
+export const arrayBufferToHex = Binary.toHex
+
+/** Deep-clone common JavaScript values while preserving prototypes. */
+export function clone<T>(source: T): T
+/** Deep-clone common JavaScript values while preserving prototypes and cycles. */
+export function clone(source: any, refs = new Map<any, any>()) {
+  if (!source || typeof source !== 'object') return source
+  if (is('Date', source)) return new Date(source.valueOf())
+  if (is('RegExp', source)) return new RegExp(source.source, source.flags)
+  if (isArrayBufferLike(source)) return source.slice(0)
+  if (ArrayBuffer.isView(source)) return source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength)
+  const cached = refs.get(source)
+  if (cached) return cached
+  if (Array.isArray(source)) {
+    const result: any[] = []
+    refs.set(source, result)
+    source.forEach((value, index) => {
+      result[index] = Reflect.apply(clone, null, [value, refs])
+    })
+    return result
+  }
+  const result = Object.create(Object.getPrototypeOf(source))
+  refs.set(source, result)
+  for (const key of Reflect.ownKeys(source)) {
+    const descriptor = { ...Reflect.getOwnPropertyDescriptor(source, key) }
+    if ('value' in descriptor) {
+      descriptor.value = Reflect.apply(clone, null, [descriptor.value, refs])
+    }
+    Reflect.defineProperty(result, key, descriptor)
+  }
+  return result
+}
+
+/**
+ * Compare values recursively, treating two volatile references as equal regardless of value.
+ * Strict comparison distinguishes null/undefined, treats opaque objects by identity,
+ * compares URLs by normalized href, treats array holes as undefined, and considers distinct cyclic structures unequal.
+ * @param a - first value.
+ * @param b - second value.
+ * @param strict - whether to require strict data equality outside volatile references.
+ * @returns whether the values compare equal.
+ */
+export function deepEqual(a: any, b: any, strict?: boolean): boolean {
+  const ancestors = new Set<object>()
+  function compare(a: any, b: any): boolean {
+    if (a === b) return true
+    if (isVolatile(a) || isVolatile(b)) return isVolatile(a) && isVolatile(b)
+    if (!strict && isNullable(a) && isNullable(b)) return true
+    if (typeof a !== typeof b || typeof a !== 'object' || !a || !b) return false
+    if (ancestors.has(a)) return false
+
+    function check<T>(test: (x: any) => x is T, then: (a: T, b: T) => boolean) {
+      return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : undefined
+    }
+
+    ancestors.add(a)
+    try {
+      return check(Array.isArray, (a, b) => {
+        if (a.length !== b.length) return false
+        for (let index = 0; index < a.length; index++) {
+          if (!compare(a[index], b[index])) return false
+        }
+        return true
+      })
+        ?? check(is('Date'), (a, b) => a.valueOf() === b.valueOf())
+        ?? check(is('URL'), (a, b) => a.href === b.href)
+        ?? check(is('RegExp'), (a, b) => a.source === b.source && a.flags === b.flags)
+        ?? check(isArrayBufferLike, (a, b) => {
+          if (a.byteLength !== b.byteLength) return false
+          const viewA = new Uint8Array(a)
+          const viewB = new Uint8Array(b)
+          for (let i = 0; i < viewA.length; i++) {
+            if (viewA[i] !== viewB[i]) return false
+          }
+          return true
+        })
+        ?? ((!strict || [a, b].every(value => Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null))
+          && Object.keys({ ...a, ...b }).every(key => compare(a[key], b[key])))
+    } finally {
+      ancestors.delete(a)
+    }
+  }
+  return compare(a, b)
+}

package/node_modules/@deepseek-ai/cosmokit/src/volatile.ts

@@ -0,0 +1,86 @@
+/** Shared config references used by schema validators and plugin runtimes. */
+
+const write = Symbol.for('cosmokit.volatile.write')
+
+/** Recursively readonly data returned by a volatile config reference. */
+export type VolatileSnapshot<T> = T extends object ? { readonly [K in keyof T]: VolatileSnapshot<T[K]> } : T
+
+/** A stable reference; keep the reference, or capture its value for one operation only. */
+export interface Volatile<T> {
+  /** @returns the current immutable snapshot, including undefined for an absent value. */
+  get(): VolatileSnapshot<T>
+}
+
+interface WritableVolatile extends Volatile<unknown> {
+  [write](value: unknown): void
+}
+
+function snapshot(value: unknown, ancestors = new Set<object>()): unknown {
+  if (typeof value === 'function') throw new TypeError('volatile config cannot contain functions')
+  if (value === null || typeof value !== 'object') return value
+  if (ancestors.has(value)) throw new TypeError('volatile config cannot contain cycles')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) return Object.freeze(value.map(item => snapshot(item, ancestors)))
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      throw new TypeError('volatile config objects must be plain objects or arrays')
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item, ancestors)])))
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+/**
+ * Create a detached reference containing an immutable copy of the supplied data.
+ * @param value - validated config data; class instances and functions are unsupported.
+ * @returns a reference whose value is updated only by its owning runtime.
+ */
+export function createVolatile<T>(value: T): Volatile<T> {
+  let current = snapshot(value)
+  return Object.freeze({
+    get: () => current,
+    [write]: (value: unknown) => { current = value },
+  }) as Volatile<T>
+}
+
+/**
+ * Identify references across ESM/CJS copies of the shared library.
+ * @param value - a parsed config value.
+ * @returns whether the value implements the shared reference protocol.
+ */
+export function isVolatile(value: unknown): value is Volatile<unknown> {
+  return typeof value === 'object' && value !== null && write in value
+}
+
+/**
+ * Collect config references without descending into their snapshots or opaque objects.
+ * @internal
+ * @param value - parsed config; cyclic ordinary fields are visited once per path.
+ * @returns references and their object-key paths, including an empty path for a root reference.
+ */
+export function volatileEntries(value: unknown): { path: string[]; ref: Volatile<unknown> }[] {
+  const ancestors = new Set<object>()
+  function visit(value: unknown, path: string[]): { path: string[]; ref: Volatile<unknown> }[] {
+    if (isVolatile(value)) return [{ path, ref: value }]
+    if (!value || typeof value !== 'object' || ancestors.has(value)) return []
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return []
+    ancestors.add(value)
+    try {
+      return Object.entries(value).flatMap(([key, child]) => visit(child, [...path, key]))
+    } finally {
+      ancestors.delete(value)
+    }
+  }
+  return visit(value, [])
+}
+
+/**
+ * Commit an already validated immutable snapshot from another reference.
+ * @internal
+ * @param target - the owning plugin's stable reference.
+ * @param source - a newly parsed candidate reference.
+ */
+export function updateVolatile(target: Volatile<unknown>, source: Volatile<unknown>): void {
+  ;(target as WritableVolatile)[write](source.get())
+}

package/node_modules/@deepseek-ai/dsh-tool-terminal/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@deepseek-ai/dsh-tool-terminal/README.i18n.yaml

@@ -0,0 +1,100 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/terminal/tool-terminal/README.md
+/:
+  en: fc74eecdf1f2ad5b
+  zh: dc9c2a28ce96ce67
+/deepseek-ai-dsh-tool-terminal:
+  en: 47fa84b67ff171b9
+  zh: bbd625bbf85694e1
+/deepseek-ai-dsh-tool-terminal/summary:
+  en: c0e810d4279333a5
+  zh: 7e79b6a63fa10029
+/deepseek-ai-dsh-tool-terminal/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-terminal/use-this-package:
+  en: dcc6b2ac23494026
+  zh: f5b755ec75994458
+/deepseek-ai-dsh-tool-terminal/use-this-package/the-six-tools:
+  en: 3e9b6211dd72ec64
+  zh: aa4cd15195cb43d6
+/deepseek-ai-dsh-tool-terminal/use-this-package/composition:
+  en: 4ce2a232b60ff77d
+  zh: 3a8a0f13371ca6b9
+/deepseek-ai-dsh-tool-terminal/use-this-package/configuration:
+  en: 0af09df923fcb322
+  zh: 6d9d766c24c530bc
+/deepseek-ai-dsh-tool-terminal/use-this-package/background-sends:
+  en: 2ad49d4f69deb06d
+  zh: 5f29972b5feec7e3
+/deepseek-ai-dsh-tool-terminal/use-this-package/observable-outcomes-and-failures:
+  en: 321a982fdbbf4ada
+  zh: 8c2636e5379815e1
+/deepseek-ai-dsh-tool-terminal/understand-the-implementation:
+  en: 6302fca8fef89136
+  zh: 6327d56edb798ab2
+/deepseek-ai-dsh-tool-terminal/understand-the-implementation/design-concept:
+  en: dc500eeff749a06f
+  zh: 9402f5005d7ca338
+/deepseek-ai-dsh-tool-terminal/understand-the-implementation/source-map:
+  en: a59f4e76dc926bed
+  zh: 24813cb1bd8fbf32
+/deepseek-ai-dsh-tool-terminal/understand-the-implementation/result-bounding:
+  en: c1953779a1617d09
+  zh: cc6a4a6e76fa021c
+/deepseek-ai-dsh-tool-terminal/understand-the-implementation/ui-render-intents:
+  en: 03e5bb37f0c3aada
+  zh: 8d51eeb758eabe9c
+/deepseek-ai-dsh-tool-terminal/further-exploration:
+  en: 45a0c33ed8104fb1
+  zh: ae50c9e583ef4867
+/deepseek-ai-dsh-tool-terminal/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-terminal/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/deepseek-ai-dsh-tool-terminal/model-experience/system-prompt/what-the-model-sees:
+  en: 99887ae1de81aaeb
+  zh: 4846a1d3ea8a3dc3
+/deepseek-ai-dsh-tool-terminal/model-experience/system-prompt/what-the-model-sees/terminal-guidance:
+  en: 3ab4211f41e40211
+  zh: b730cc3f278be17c
+/deepseek-ai-dsh-tool-terminal/model-experience/system-prompt/token-effect:
+  en: c9d6d1a8238b74ab
+  zh: 7f4b12d6180b9bac
+/deepseek-ai-dsh-tool-terminal/model-experience/system-prompt/kv-cache-effect:
+  en: 7fdc10b826aeeb51
+  zh: 998c86c09efe43bd
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-schemas/what-the-model-sees:
+  en: 32127d768242d8c4
+  zh: 3095d987d6011f44
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-schemas/token-effect:
+  en: 824644a1f5fe76df
+  zh: b34c7dd78c5ce3cd
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-schemas/kv-cache-effect:
+  en: c8cbbef533bdb90f
+  zh: c0b00813b8419f46
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-results-and-task-context:
+  en: 54e0c8a019f02479
+  zh: 7331b10d1a455d59
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-results-and-task-context/what-the-model-sees:
+  en: cc1e88a508d0679e
+  zh: a219be277705c0ab
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-results-and-task-context/token-effect:
+  en: e4746b7b386944df
+  zh: be52cd2fd38276b5
+/deepseek-ai-dsh-tool-terminal/model-experience/tool-results-and-task-context/kv-cache-effect:
+  en: ac583ab16185a93c
+  zh: 78df55a519b2ec1f
+/deepseek-ai-dsh-tool-terminal/known-limitations-and-deferred-work:
+  en: ba974b703d6ed0bc
+  zh: 655810d5d338343c
+/deepseek-ai-dsh-tool-terminal/known-limitations-and-deferred-work/dev-note:
+  en: a4c4901129addb49
+  zh: 78f339ece6da423b

package/node_modules/@deepseek-ai/dsh-tool-terminal/README.md

@@ -0,0 +1,186 @@
+---
+description: "Six model-facing persistent terminal tools with owner isolation, bounded results, and optional background sends for agents that need cross-call terminal state."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-terminal
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-tool-terminal` when an agent needs persistent terminal state or interactive input across calls. It can open, send to, read, signal, close, and list terminal sessions while preventing one agent from operating another agent's sessions. Sends may wait for bounded foreground output or return a background job id for later collection or interruption. `maxResultBytes` caps each result, which remains in session history until compaction. The model is guided to prefer one-shot tools for bounded work.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Enable these tools when the composition mounts a terminal backend and the model should be able to use terminal state across calls — stepping a debugger, exploring in a REPL, or returning to a shell after interrupting a foreground command. The guidance section steers the model toward the one-shot bash, read, write, and edit tools for bounded operations.
+
+### The six tools
+
+| Tool | What it does | Result |
+|---|---|---|
+| `terminal_open` | Creates an owner-scoped session from a backend type | Session id, name, type, pid, status, and bounded startup output |
+| `terminal_send` | Writes text, optionally submitting Enter, and waits for readiness — or starts a background job | Bounded output plus wait and session status, or a job id |
+| `terminal_read` | Reads a bounded page of retained output without sending input | Text with line pagination metadata |
+| `terminal_signal` | Delivers one allowed signal to the foreground process group | `delivered` plus the target process group id |
+| `terminal_close` | Closes a session and waits for its process tree to end | Closed or already-closing outcome |
+| `terminal_list` | Lists the caller's live sessions | Owner-scoped session summaries |
+
+### Composition
+
+```yaml
+- name: '@deepseek-ai/dsh-terminal'
+- name: '@deepseek-ai/dsh-terminal-bash'
+- name: '@deepseek-ai/dsh-tool-terminal'
+```
+
+The tools need `ctx.terminals` — a backend must be mounted — and the system-prompt service for the guidance section. Background sends additionally require the jobs service and its model-facing controller (`@deepseek-ai/dsh-tool-jobs`).
+
+### Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enableRunInBackground` | `true` | Expose and accept `run_in_background`; `false` removes the schema field and rejects the argument |
+| `maxResultBytes` | `262144` | UTF-8 cap (minimum `64`) for each complete terminal result after wait, session, pagination, truncation, and job-status metadata |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-terminal) and [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-terminal) are the exhaustive sources for config fields and schemas.
+
+### Background sends
+
+`terminal_send(run_in_background: true)` returns a job id immediately instead of waiting. The job is collected with `job_output`, which waits and reads incremental output, and stopped with `job_kill`, which delivers a real `SIGINT` to the foreground process group. Background mode fails before writing input when the jobs surface is absent.
+
+### Observable outcomes and failures
+
+A foreground send returns the terminal's new output plus `wait: <reason>` and the session status; `session_exit` means the top-level shell exited, while `inferred_idle` or `timeout` never proves the foreground command exited. Opening a session with an unregistered backend type fails. Results larger than `maxResultBytes` are truncated at a UTF-8 boundary with a marker.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the tools and points at the code that realizes it; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The package is a thin adapter: the six tools forward to `ctx.terminals` with the executing agent as the owner, and the presentation layer renders bounded results. Background sends register the in-flight operation on `ctx.jobs` so the generic job surface owns waiting, incremental reads, and `SIGINT` delivery.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Six tool definitions, schemas, guidance section, background-job integration |
+| [`src/render.ts`](src/render.ts) | Result rendering and the complete-result UTF-8 cap |
+
+### Result bounding
+
+Every terminal-owned single-text result is capped by `maxResultBytes` after normalized tool or pipeline errors, policy denials and short-circuits, replacements and blocks, and generic job-status text; cuts preserve UTF-8 boundaries and reserve room for a truncation marker. Structured multi-block policy results retain their shape. The minimum cap of 64 bytes keeps every registry-issued session or job id visible in its creation acknowledgement.
+
+### UI render intents
+
+Foreground sends use terminal call and result cards; background sends and the other five tools use generic `execute`, `read`, or `delete` cards. None of the tools emits source locations.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the generated schemas to the service contract, the backend, and the background-job surface.
+
+- [Tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-terminal) — the six generated schemas and result shapes.
+- [Terminal subsystem reference](../../../docs/subsystems/terminal.md) — the service contract and shared types behind the tools.
+- [terminal service](../terminal/README.md) — session operations, owner fencing, and cleanup semantics.
+- [terminal-bash backend](../terminal-bash/README.md) — the shipped shell backend that provides sessions.
+- [jobs package map](../../jobs/README.md) — the background-job surface that collects and kills background sends.
+- [Persistent PTY Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) — the capability design and deferred boundaries.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+The plugin contributes this fixed guidance section:
+
+##### Terminal guidance
+
+```markdown
+Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer shell/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.
+```
+
+#### Token effect
+
+Small fixed input cost on every request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the registration scope and guidance text are unchanged.
+
+### Tool schemas
+
+#### What the model sees
+
+The six generated schemas are listed in the [`dsh-tool-terminal` catalog section](../../../docs/tool-catalog.md#deepseek-aidsh-tool-terminal). Their fixed schema tokens are present whenever this plugin is active; agent-scoped tool filtering may hide them.
+
+#### Token effect
+
+Fixed schema cost on requests where the tools are visible.
+
+#### KV Cache effect
+
+Prefix-stable while tool visibility and definitions are unchanged.
+
+### Tool results and task context
+
+#### What the model sees
+
+Spawn returns the id and bounded startup output. Send and read return bounded terminal text plus readiness and history markers. Background mode returns a generic job id. Every terminal-owned single-text result is capped by `maxResultBytes`; results remain in session history until compaction, and incremental task reads do not repeat consumed output.
+
+#### Token effect
+
+Terminal-owned results are data-dependent and bounded by `maxResultBytes`; each returned result stays in history until compaction.
+
+#### KV Cache effect
+
+Append-only; new results follow the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define the model-facing surface that is absent. They are current package constraints, not a task backlog.
+
+- **No TUI or key-sequence surface** — named key sequences, full-screen TUI interaction, BEL, resize, and auto-start are not exposed in any schema.
+- **Background mode requires the jobs surface** — `run_in_background` needs both `@deepseek-ai/dsh-jobs` and its model-facing controller (`@deepseek-ai/dsh-tool-jobs`); without them the argument is rejected.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. This stateless adapter contributes tools and prompt guidance, while PTY lifecycle and background-job relationships remain owned by the services it composes.