deepseek-harness/docs/core-data-structures/tasks.md

Background Task Runtime

Types shared by long-running producers, ctx.tasks, and task control surfaces. The runtime RFC owns the design; this page records the literal shapes from packages/tasks/tasks/src/types.ts.

Ids and status

TaskId is a branded id generated as <kind>-N. Access control relies on owner authorization, not id secrecy. TaskStatus is 'running' | 'stopping' | 'completed' | 'killed' | 'failed'; producer-specific facts belong in TaskSnapshot.detail.

Producer contract

TaskStart declares identity and a starter. The runtime finishes preflight before calling run() and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.

interface TaskStart {
  /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
  kind: string
  /** One-line model-facing label (the command; the delegation description). */
  label: string
  /**
   * Owning live agent. Access is fenced by its session id, and agent disposal
   * cancels and awaits the task. The instance must be the one currently
   * registered under its agent id. `undefined` creates an unowned task, open to
   * any caller until service disposal.
   */
  owner?: Agent | undefined
  /**
   * Start the work after preflight and synchronously return its hooks. Called
   * once; a throw leaves nothing registered, and the producer must clean up any
   * partially started resources.
   */
  run(): TaskHooks
}

TaskHooks.done is the quiescence boundary. Optional readOutput distinguishes consuming stream tasks from final-output-only tasks.

interface TaskHooks {
  /**
   * Request termination. Must be synchronous, idempotent, and eventually settle
   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
   */
  cancel(reason?: string): void
  /**
   * Resolves after the producer releases its resources, not merely when work
   * finishes. Must not reject; the runtime converts a rejection to `failed`.
   * If teardown cancellation throws, the runtime may force-fail only the
   * registry record without claiming that the work stopped.
   */
  done: Promise<TaskOutcome>
  /**
   * Consume output produced since the previous call. The producer formats
   * truncation and spill notices. Absence marks a final-output-only task; each
   * task has one consuming cursor.
   */
  readOutput?(): string
}

interface TaskOutcome {
  /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
  status: 'completed' | 'killed' | 'failed'
  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
  detail?: string
  /** Final output for tasks without `readOutput`; stream tasks leave it unset. */
  output?: string
}

Consumer views

Snapshots are fresh read-only projections. ownerSession carries the shared SessionId used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. reported suppresses a completion notice after another surface has delivered or committed to deliver the terminal state.

interface TaskSnapshot {
  /** The registry-issued id (`<kind>-N`). */
  id: TaskId
  /** The producer kind the task was registered with. */
  kind: string
  /** The producer-supplied one-line label. */
  label: string
  /**
   * Owner session id used for authorization and correlation; absent for
   * unowned tasks. Completion listeners receive the exact {@link Agent}
   * separately through {@link TaskDoneListener}.
   */
  ownerSession?: SessionId
  /** Current lifecycle state. */
  status: TaskStatus
  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
  detail?: string
  /** Epoch ms when the task was registered. */
  startedAt: number
  /** Epoch ms when the task settled; absent while `running`/`stopping`. */
  finishedAt?: number
  /**
   * True when a kill, read, or wait has reported or committed to report the
   * terminal state. Completion surfaces suppress redundant notices when set.
   */
  reported: boolean
}

interface TaskRead {
  /**
   * Stream kinds: the consuming delta since the previous read. Final-output
   * kinds: empty while live, the terminal {@link TaskOutcome.output} (or
   * empty) once settled — idempotent, never consumed.
   */
  text: string
  /** The task's state at read time. */
  snapshot: TaskSnapshot
}

Service behavior

TaskService provides atomic start, caller-scoped get and list, read, kill, bounded wait, contained onTaskDone listeners, and the attachSurface availability fence. Authorization compares owner sessions; owner cleanup selects the exact registered Agent instance. See dsh-tasks for the package contract and dsh-tool-tasks for the model-facing surface.