zsspub/dsh-personal-todo

---

summary: SQLite-backed personal todo tools and Web panel for DeepSeek Harness. read_when:

• You want durable todos shared across DSH sessions and projects.
• You are installing or configuring the dsh-personal-todo bundle.

---

dsh-personal-todo

English | Chinese

dsh-personal-todo lets users manage todos themselves or dispatch them to a DSH Agent on demand, without choosing a task type in advance. Todo progress is independent of Agent execution state. See the Chinese documentation for the complete guide.

Features

• Read-only requests such as “show my todos” use personal_todo_show. The tool area retains only the host's compact record, while a complete interactive todo card appears at the end of the turn instead of a Markdown table. The card supports all item actions, scrolling through every result within a fixed height, and opening the right sidebar at a specific todo.
• Historical cards in conversations, the right sidebar, the sidebar count, and @ references share one client-side data store through Nanostores and React useSyncExternalStore. A change in any location is reflected immediately everywhere else. Cards refresh when mounted, when the window regains focus, after a manual refresh, after successful actions, and when the Host reports a change; existing data remains visible if a refresh fails.
• Refreshes are pushed by the Host instead of polled. After a todo write commits (including Agent tool calls, imports, and child-session links) or a linked session's execution state changes, the Host notifies clients through the changes stream Remote, and each client re-reads the lists, counts, and details it displays. Browser windows stay in sync. On every (re)connection the first ready item triggers a full refresh, and a dropped stream is reopened with exponential backoff from 0.5 to 10 seconds.
• The panel and Agent tools support complete JSON import and export. Exports use version 2, while imports accept versions 1 and 2. Duplicate IDs are skipped, and only newly imported todos with legacy running records are reset to pending. Live execution state is not written to backups, and importing never starts an Agent. See the Chinese documentation for more details.
• @ references in the chat composer show only pending and in-progress todos. Press Tab to enter the todo list, search by keyword, and retrieve the latest details when sending. This requires DSH ui-input-trigger >=0.1.2-rc.1.
• Durable SQLite storage with schema versioning, WAL, foreign keys, a busy timeout, and owner-only filesystem permissions.
• Each todo dispatched to an Agent is associated with one persistent root Session, and all follow-up communication stays in the original conversation.
• Automatic discovery of delegated child Sessions, including nested children, as related todo conversations.
• After a service restart, Session state is read without activating an Agent or sending a recovery message.
• The sidebar shows the combined number of unarchived pending and in-progress todos; there is no separate “needs my attention” filter.
• Primary progress uses pending, in_progress, and completed; cancelled is a secondary state, and archiving is independent. Agent execution information is displayed separately.
• Session associations and user action history are retained, along with legacy Runs and results for compatibility. New executions do not create Runs.
• Agent tools are limited to creating, querying, editing, deleting, importing, and exporting todos. They do not force synchronization of progress, questions, or review results.
• The panel uses the host's native right Sidebar Tab. Its primary tabs are Pending, In Progress, and Completed; More contains cancelled and archived todos, while Data has a separate menu. Todos can be grouped by assignee, moved through states manually, and linked back to their Sessions. The panel no longer includes a reply box or review workflow.
• Todos in any lifecycle state can move to a separate archive view, then return to the matching list or be permanently deleted.
• Typed English and Chinese client dictionaries.

Requirements

• 支持右侧 Sidebar Tab、sessionQuery 和 Agent 生命周期通知的 DeepSeek Harness Web profile；本次仅按本机已安装 DSH 0.2.1-rc.3 及客户端自带 API 适配，不追踪最新版或升级 DSH。
• @deepseek-ai/dsh-client-ui-tool 0.2.1-rc.3 和 @deepseek-ai/cordis ~4.0.5。
• Node.js ^22.19.0 || >=24.0.0.
• pnpm 11.7.0 for development.

Installation

Install a pinned GitHub revision so the committed lib/ artifacts are used directly:

pnpm dsh plugin --profile web add github:zsspub/dsh-personal-todo#<commit-sha>

For local development:

pnpm dsh plugin --profile web add /absolute/path/to/dsh-personal-todo

The bundle patch mounts the Host service and tools. Its Web manifest loads the client automatically.

首页打开待办

点击“待办”优先使用当前会话；没有当前会话时，按宿主最近工作区规则创建一个普通空会话，待原生右栏挂载后打开待办标签。没有可用工作区时提示先选择工作区。这个插件方案会增加一个空会话，不提供真正的全局右侧宿主能力，不发送消息或派发待办，不修改 DSH 宿主。连续点击共享创建请求，失败可重试；切换导航或卸载插件会取消后续打开动作。

每个会话的面板保持独立，已访问标签隐藏或切换会话时保留导航和未提交表单；显式关闭标签结束实例。不会移动文件和终端的会话上下文，卸载时不会删除已创建会话。工作区选择、10 秒挂载等待、生命周期及真实 GUI 验收边界详见 中文说明。

Agent tools

Lists return pending and in-progress todos by default and exclude archived todos. Conversation cards retain bounded historical snapshots and use their original filters to read current data. Cards with identical filters share complete paginated requests, and the cards themselves do not poll. Cards do not offer creation, duplication, or JSON import and export. Deletion always requires confirmation, and dangerous state changes on a running todo first require confirmation that execution should stop. The needsAttention filter and count, along with the personal_todo_progress, personal_todo_block, and personal_todo_submit_review tools, have been removed. General editing cannot change todo progress, and Agent tools cannot confirm completion on the user's behalf. The Remote API retains setStatus({ id, status }, signal), stop({ id }, signal), and approve, which is equivalent to marking a todo complete; reply and requestChanges have been removed.

Task flow

Creating a todo or manually marking it in progress does not create a Session or send a message. Execution starts only when the user chooses “Dispatch to Agent”; questions, replies, permission confirmations, and results remain in the original conversation. executionStatus passively observes agent/status, agent/error, agent/disposed, and session/event, projecting running, idle, failed, stopped, or unavailable in memory only. The end of a turn does not mean the todo is complete, and the plugin does not infer that a reply or review is required. Listeners do not use blocking hooks, write progress summaries, or send messages. Cold Sessions are inspected through the read-only sessionQuery.readSession API without activating execution. Users can stop and take over a todo, complete it, cancel it, return it to pending, or archive it; reopening a todo or restarting DSH never starts execution automatically. See the Chinese documentation for more details.

Configuration

The included bundle uses these defaults:

Override the generated plugin entry in the profile patch when deployment policy requires different values. The service rejects relative paths, invalid limits, and databases with a schema newer than it supports.

Data behavior

Titles are trimmed and limited to 200 characters. Notes are trimmed and limited to 10,000 characters. Assignees are optional, trimmed, and limited to 100 characters; unassigned todos appear in a dedicated group after named assignees. A todo accepts up to 20 unique lowercase tags of at most 32 characters each. Due times must be RFC 3339 timestamps and are returned in canonical UTC form.

Before completing, cancelling, returning, or archiving a todo, the plugin cancels its dedicated root Session and related child Agents, then waits until they are actually idle. If it cannot confirm that they have stopped within 15 seconds, it returns an error without changing todo progress. External changes already made are not rolled back, and some Agents may already have stopped. Do not use a todo's dedicated execution Session for unrelated work. Historical Runs, results, and Session associations are retained; restoring an archived todo or reopening a todo does not restart execution.

The database migrates automatically to schema 6: legacy blocked and in_review states become in_progress, while existing Runs and associations are retained. After upgrading, do not open the same database directly with an older plugin version. The JSON backup version is independent of the database schema; imports support versions 1 and 2, with a 20 MiB limit. Session associations are not Session backups. If the original DSH Session no longer exists, importing cannot restore pending replies, review changes, or links to historical conversations. Backups do not contain Session messages, attachments, plugin configuration, or credentials.

Development

pnpm install
pnpm run check
pnpm run artifacts:check

pnpm run check builds Host, Typert, and Web artifacts; typechecks source and tests; lints; runs coverage; and verifies package contents with pnpm pack --dry-run. Built lib/ files are committed so a GitHub SHA can be installed without a lifecycle build script.

License

MIT