deepseek-harness/docs/subsystems/todo.md

Todo

English | 中文

The durable todo vocabulary owned by @deepseek-ai/dsh-tool-todo. The model-facing tool replaces one agent session's whole list; the package also owns the event declaration, replay projection, and invariant companion. Tool behavior and configuration are on the package README.

Source: packages/todo/tool-todo/src/types.ts

TodoItem — one list entry

/**
 * One entry in an agent's todo list — the unit of the `todo/write`
 * whole-list snapshot declared by this package.
 *
 * Deliberately minimal: a human-readable `content` line and a three-state
 * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
 * on every write (last-write-wins), so entries need no stable identity. The
 * three statuses describe the complete portable lifecycle needed by model and
 * UI consumers.
 */
interface TodoItem {
  /** What this task is — a short imperative line shown in the UI. */
  content: string
  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
  status: 'pending' | 'in_progress' | 'completed'
}

Durable event and invariant

The package declaration-merges todo/write: { todos: TodoItem[] } into SessionEventMap. The event is log-only and carries the complete replacement list; the generated persistence catalog records its declaration site. The package's invariant companion validates existing and newly announced sessions in one pass, then tracks committed turn boundaries incrementally so every live todo/write is checked before append without rescanning the log.