mayf3/dsh-session-doctor

English | 中文

Diagnose, unstick, and read DeepSeek Harness sessions. Five tools for every session: list, read, diagnose, recover, and message other Agent sessions.

What is this

In DeepSeek Harness, one process hosts many Agent sessions. A session can get stuck — for example, a Client-platform query like cordis_inspect_query waits forever for a page response, the agent stays running, and later messages pile up in the inbox unprocessed. This plugin provides:

• List all sessions: title, id, online state, agent status (running/idle), pending inbox counts, working directory;
• Read any session's conversation: user and assistant messages in time order, with title and live state;
• Diagnose whether a session is stuck: online, running/idle, inbox pending counts, last event;
• Recover a stuck session: send a cancel signal (keepInbox: true) to a running agent — abort the stuck activity but keep queued inbox messages; the agent processes them once it settles to idle;
• Send messages to other sessions: deliver directly when online; auto-resume persisted sessions before delivery.

Typical flow: notice another session is stuck → diagnose → recover → read its progress → message it to continue.

Features

Tool	Description
list_sessions	List all sessions: id, title, cwd, persisted state, agent status, pending counts
read_session	Read a session's conversation (user/assistant text), time-ordered, with limit
session_status	Diagnose a session: online, running/idle, inbox pending counts, last event
session_recover	Unstick: cancel a stuck running agent with keepInbox: true — abort stuck activity, keep queued messages
send_session_message	Send a message to a session: direct when online; auto-resume persisted sessions

Install

One-liner

dsh plugin --profile web add dsh-session-doctor

From GitHub

dsh plugin --profile web add github:mayf3/dsh-session-doctor

Via your Agent

In any DSH session, send:

帮我安装会话医生插件,执行:dsh plugin --profile web add dsh-session-doctor

Usage

1. Say "list all sessions" to session A — it calls list_sessions, showing title and status of every session;
2. Suspect a session is stuck → "check status of session <id>" — it calls session_status; status: running with no progress for a long time confirms a stuck agent;
3. "recover session <id>" — it calls session_recover, aborting the stuck activity while keeping queued inbox messages;
4. "read session <id>" — it calls read_session, returning the conversation;
5. "send message to session <id>: ..." — it calls send_session_message; online targets get it immediately, persisted sessions are resumed first.

How it works

• Diagnosis: sessionQuery.listSessions() lists the full logical corpus; ctx.agents.get(id) reads the live agent's status and inbox pending counts; sessionQuery.listEvents(id) provides the last event as progress evidence;
• Recovery: for a live agent with status === 'running', call agent.cancel({ kind: 'user' }, { keepInbox: true }) — abort the stuck activity but keep queued messages; the agent processes them after settling to idle;
• Reading: sessionQuery.readSession(id) replays the full session log, extracting text from user/message and assistant/message events;
• Sending: online → agents.get(id) then followup(); offline → agentLoop.resume() then deliver.

Relationship to dsh-agent-message

dsh-agent-message focuses on cross-session messaging (five delivery modes, receipts, session navigation); this plugin focuses on session health (diagnosis, recovery, reading) with a simple send entry. They coexist: use agent-message for messaging, use session-doctor when a session gets stuck.

Directory layout

dsh-session-doctor/
├── lib/
│   └── index.js      # host half: five tools
├── cordis.patch.yml  # self-register patch (pointed by dsh.bundle.patch)
├── package.json      # DSH plugin manifest (dsh.bundle / dshx.contributes)
├── README.md         # Chinese docs
└── README.en.md      # English documentation

Limitations

• session_recover only acts on live agents (running); offline sessions have no stuck activity to recover.
• send_session_message resumes offline sessions with the default model (not the model manually selected last time).
• Cross-process / cross-machine messaging is out of scope.

License

MIT