Foreword¶

The most common way to run commands for agents is to call exec once and retrieve the standard output. There are a few unavoidable problems on this path: programs cannot enter interactive mode, and things like npm run dev or python that require a TTY cannot run; long tasks can only wait for completion without seeing the process; once a password prompt is encountered, the plaintext password enters the conversation context; and humans and models cannot use the same shell simultaneously.

The plugin introduced in this article, AyanamiiRei/agent-interactive-terminal, turns the terminal into a resource with identity, screen, phase, and lease. The maintainer is AyanamiiRei, version 0.6.9, MIT license, categorized as a client, and has very few stars (2 on the directory page).

What is it¶

In a single sentence: It provides stateful PTY terminal sessions within the DeepSeek Harness; the model reads a discrete screen snapshot, not a byte stream.

It bundles eight terminal_* tools, a real-time shared xterm panel, and password handoff that does not go through the model context. The README states that 73 tests pass on Linux Node 20/22; see docs/design.zh.md for design details.

It does not depend on any agent framework; TerminalRegistry and the terminal_* tools can be used independently in their own runtimes.

Core Features¶

Screen Snapshots, Not Byte Streams¶

The model reads a rendered text screen with phase and status line attached. Writing is an action, waiting is a query, and status is a fact; the three are separated. There is only one screen, with two projections: text for the model, and serialized ANSI for the browser.

Eight Tools¶

Humans and Agents Share the Same Screen¶

On the desktop, the session title bar shows a terminal icon. Clicking opens the xterm panel on the right. Session tabs are numbered in order; middle-click to close. Keyboard ownership rules: if a human types, they take over; if they stop for a few seconds, it returns automatically. The agent’s writes queue during this time; the top bar shows queued commands and a cancel button, and execution resumes in order after handback.

Access levels are divided into three tiers: collaborate (collaboration), observe (read-only), and sealed (both read and write are disconnected, only sanitized records remain in the list). Read-only and disconnected will both reject queuing and return different errors. Authorization is given at session creation and executed by the server, not by the frontend sending keys.

Passwords Don’t Go Through the Model¶

When a password prompt is encountered, wait returns human_required and suspends the agent. The human answers via session.write(secret, { origin: 'human' }). The password does not enter the model context. The repository has implemented key injection and auditing.

There is also a tool strategy switch: by default interactive is prioritized, but it can be switched to one-off command priority or force interactive (the latter hides the agent’s bash). There is also an “Actively use interactive terminal” switch to let REPL tasks enter interactive environments like python first.

Platform Support¶

Prioritize Unix shells (zsh/bash). Linux and macOS use the local zsh/bash directly; on macOS when $SHELL is not set, it defaults to /bin/zsh. Windows automatically looks for wsl.exe. If available, it starts zsh inside WSL (uses bash if zsh is not installed) and translates generated rc files to WSL paths; if WSL is not found, it falls back to PowerShell 7, Windows PowerShell, or cmd.exe. Selecting zsh/bash manually without WSL will explicitly error. Native PowerShell/cmd do not have prompt markers; waiting will fall back to silent judgment based on screen content and output, which is less accurate than WSL.

Themes, fonts, cursor, shortcuts, rollback, bell, copy/paste, and lease timeout are all in the terminal settings. The theme defaults to following DSH but can be fixed to a specific color palette.

Installation and Enablement¶

Requires Node.js 20+ and the C++ toolchain for compiling node-pty.

Add the market index in DSH’s Plugins → Discover:

https://raw.githubusercontent.com/AyanamiiRei/agent-interactive-terminal/main/plugin-market.json

Search for agent-interactive-terminal to install, or directly fill in the Git spec in Add plugin. The first installation requires approval of the node-pty build script; restart DSH after upgrading to a new version.

You can also build manually:

git clone https://github.com/AyanamiiRei/agent-interactive-terminal.git
cd agent-interactive-terminal
npm install
npm run build

Typical Usage¶

The repository comes with three entry points suitable for verifying behavior before integrating into DSH.

npm run demo -- "git status"   # Single command, see the screen and status line the model gets
npm run demo                   # Interactive loop: /snap, /wait, /key, /resize, /quit
npm run attach                 # Browser attach example, open the address printed in the terminal

Using TerminalRegistry directly in code:

import { TerminalRegistry } from 'agent-interactive-terminal'

const sessions = new TerminalRegistry({ maxSessions: 2 })
const session = await sessions.open({ name: 'build', cols: 100, rows: 30 })

await session.write('npm run dev')
const result = await session.wait({ match: ['ready in'], timeoutMs: 60_000 })
console.log(result.outcome, result.view.text)

session.takeOver()
await session.write('y', { origin: 'human' })
session.handBack()
await session.close()

You can also pass createTerminalTools(registry) to your own model runtime; it doesn’t necessarily have to run inside DSH.

Use Cases and Considerations¶

Suitable for these types of needs: needing an agent to drive interactive programs (REPL, scaffolding, interactive installers); tasks with uncertain duration needing to see the process rather than just the result; needing humans and agents to take turns operating the same shell; needing sensitive inputs like passwords to stay outside the model context.

Points to note:

1. The plugin runs with the permissions of the current DSH process. What it can read or execute is within the scope of DSH’s permissions. You should read the repository source code and license (MIT) thoroughly before installing.
2. The first installation requires approval of the node-pty build script. This is a native module compilation and is a normal action, but you should confirm it yourself.
3. The browser example of npm run attach only binds 127.0.0.1 and has no authentication. It is for local demonstration only; do not expose it to the network.
4. Items not yet implemented in the README: obfuscated intervals outside auditing, idle session cleanup, fish integration. See ROADMAP.md for details.

Conclusion¶

The value of this approach lies in upgrading the terminal from “running a single command” to a “session-level resource”: the screen is readable, keys are controllable, waiting is conditional, passwords are isolated, and humans and agents can share it. The repository is still small (2 stars on the directory page, version 0.6.9), but the path covered is complete. Running npm run demo first will confirm if it fits your workflow.

• Directory page: https://www.skillhub.cn/plugins/AyanamiiRei/agent-interactive-terminal
• GitHub: https://github.com/AyanamiiRei/agent-interactive-terminal