dsh-task-supervisor

description: "Add persistent tasks, DAG progress, checkpoint reviews and Supervisor consultation to a DSH Web profile." kind: "package-bundle"

DSH Task Supervisor

English | 中文

npm · Report an issue · Community

Summary

Use /task to track, pause and rework a goal, follow its DAG, and obtain reviews during planning, execution and completion. The main Agent plans and delivers; Supervisor persists state, schedules reviews, and continues, pauses or closes the task under valid decisions. Discuss requirements, ask about progress and explicitly change tasks in consultation. Default review examines the main conversation log; direct artifact reads and isolated checks require configuration, and passing review does not guarantee that nothing was missed.

Table of Contents

• Get started
• Architecture and responsibilities
• The complete Task lifecycle
• When reviewers intervene and what they check
• Evidence and independent verification
• Continuation, pause and recovery
• Understand the implementation and develop
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work

Get started

This page describes 0.1.4, which creates Tasks in native DSH modes. Complete reports are separate from tool process details; requirement outcomes, Task/attempt evidence scope and bounded read correction are described in review experience. Earlier native-process and recovery changes are in the 0.1.3 release. Earlier versions and public Host boundaries are documented in the 0.1.2 release, public DSH installation validation and supervised tasks in native modes.

Install into a Web profile

Node 24 and official DSH 0.2.0-rc.2 are validated without Host or native sandbox modifications. Retain the profile's model configuration and install the public package:

dsh plugin --profile web add dsh-task-supervisor@0.1.4
dsh web

To test current source, build and pack it with the development commands below, then use dsh plugin --profile web add /absolute/path/to/package.tgz in an isolated profile. The package includes Host and Web plugins plus an optional check gateway; DSH provides its native components.

Create and approve a task

Enter /task <objective> in the main conversation to begin planning. Bare /task waits for the next message as the objective; with an unfinished task it shows status without resuming execution. /task new <objective> remains a compatibility alias. The main Agent can also use the task tool for an explicit natural-language creation request.

After plan review passes, execution normally waits for /task approve, a qualifying approval reply in the main conversation, or the sidebar approval button. Explicitly authorize execution after review to automate that approval. Approval permits implementation; node and whole-task acceptance still apply.

The main conversation shows a compact DAG, participating Agents, progress and short review notices. A node or details link opens the full sidebar: conversation handles consultation and requirements; details holds plans, nodes, reviews and controls. The more menu provides read-only task history.

An earlier isolated validation example retaining the reason and dependency impact of a passed node entering a new rework attempt.

Architecture and responsibilities

Supervisor contains a deterministic controller and model reviewers. The controller owns task state and continuation authority; reviewers make evidence-based decisions. Consultation is a user-facing Session, separate from automatic checkpoint review.

flowchart TD
  U["用户 / User"] --> M["主 Agent / Main Agent"]
  U -->|"批准、暂停 / Controls"| C["Supervisor 控制器 / Controller"]
  M -->|"计划、报告、完成申请 / Submissions"| C
  C -->|"绑定版本与证据 / Bound review job"| R["审查者 / Reviewer"]
  R -->|"裁决与引用 / Decision and evidence"| C
  C -->|"续行、暂停、完成 / Continue, pause, complete"| M
  M --> L["DSH 原生 Session 日志 / Session logs"]
  C --> L
  R --> L

Current source retains the main Session's native preset and Goal/Plan tools. While a Task exists, Supervisor disarms native Goal continuation through public GoalService; native Plan/Todo can organize work but cannot approve or accept the Task. Supervisor does not act as a general Team Lead; the main Agent and Workers implement.

The complete Task lifecycle

A task can span many model turns. Reviews in this diagram are formal checkpoints handed to the controller after submission; planning and execution also receive activity observations under the next section's conditions.

flowchart TD
  A["建立目标 / Create task"] --> B["勘察与规划 / Plan"]
  B --> C["计划覆盖审查 / Plan review"]
  C -->|"修订 / Revise"| B
  C -->|"通过 / Pass"| D["执行批准 / Approval"]
  D --> E["实施就绪节点 / Execute ready node"]
  E --> F["节点验收 / Node review"]
  F -->|"补做 / Revise"| E
  F -->|"还有节点 / More nodes"| E
  F -->|"全部通过 / All passed"| G["整体验收 / Completion review"]
  G -->|"补做 / Revise"| E
  G -->|"通过 / Pass"| H["完成 / Complete"]
  H --> I["发现原目标缺陷 / Repair proposal"]
  I -->|"用户确认影响 / Confirm impact"| E

1. Establish requirements. Create a task directly, or refine a broad idea into a consultation draft first. The controller binds the main Session, task ID and requirements version. Original human requirements remain the acceptance authority.
2. Investigate and form a plan. The main Agent uses native tools to inspect inputs and the workspace, then proposes criteria and a DAG. Planning retains native permissions and asks for investigation before implementation approval; it does not prohibit every read or run_code. Supervisor can inspect planning progress for unknown conditions, repetition or stalled investigation.
3. Submit the plan. task_submit_plan persists the job, proposal, requirements version, evidence cutoff and reviewer Session identity, promptly returns submitted, and ends the turn. After tool activity settles, the controller runs coverage review. Revision findings return to the main Agent; a pass enters initial execution approval.
4. Admit implementation. Wait for user approval by default; explicit preauthorization permits automatic execution only after review passes. Independent mode checks declared capabilities and toolchains first. Requirements edits revoke prior approval and preauthorization and return to planning. Later plan revisions under unchanged requirements still need review without unconditionally repeating initial approval.
5. Execute DAG nodes. Predecessors must pass review before successors become ready. The main Agent records the current attempt with task_start_node, then implements or delegates non-overlapping file scopes. After integration and rechecks it submits evidence with task_report_stage. Supervisor can inspect progress during work or continue after a turn ends.
6. Accept or rework a node. Only a passing review accepts the attempt and releases dependencies. Revision requires more work without accepting the node. A defect in an accepted node can trigger task_rework_node, creating new attempts for it and its descendants while retaining unrelated branches and historical reviews. Resubmissions bind the current attempt.
7. Check the whole delivery. All nodes passing still requires the main Agent to submit the current combined result with task_request_completion. Completion review checks every necessary original requirement, component relationships and supporting evidence. Only a valid applied pass completes the Task. Revision returns to implementation; user needs or internal faults pause it.
8. Continue after completion. The same Session can start another task and retain the previous one in history. An original-objective defect first requires a repair reason, root nodes and impact proposal. Every reopening waits for a user confirmation click, then returns to the same Task/DAG, preserving prior completion and reaccepting affected nodes and the combined result.

“Review submitted” does not mean “review passed”; native turn completion does not mean Task completion. During review, the main Agent waits for handoff. The UI shows job kind, elapsed time, evidence reads, last activity, deadline and next action; the proposal DAG is explicitly unapproved. Read counts measure activity, not completion percentage or coverage.

When reviewers intervene and what they check

These are five job kinds in one review engine, not five resident Agents. Jobs bind requirements, plan, node attempt and evidence cutoff. A pass has a different meaning at each checkpoint.

Default native safe-step observations trigger on 24 tool results, five minutes with recorded tool activity since the previous observation, or three consecutive tool errors. Wall time alone without new tool results does not trigger inspection or prove drift. Execution also uses maxAutomaticRoundsWithoutReport: 3 as a turn-based fallback. Formal verdicts reset observation so review time cannot immediately count as another main-Agent progress interval.

planningSupervision controls planning review; observeLongTurns controls in-turn observation; progressReviewMode: required-only skips execution-progress review while retaining plan, node and completion checkpoints. Thresholds are configurable, not continuous observation of every operation. On an output-limit ending, the controller can resume another turn with confirmed context; that recovery is not a review pass.

Evidence and independent verification

A separate Session isolates review context but does not prove that the reviewer ran or observed artifacts. The UI shows the effective mode. Plan and progress jobs use log review; node and completion jobs use the configured verification method.

Explicit independent mode with independentVerification.storageRoot enables the generic protocol below; execution additionally needs a configured container and toolchain. Sessions retaining only legacy independentVerification use the compatibility protocol without invented historical check plans. Independent node and completion reviews proceed in this order:

1. Plan checks. Read complete original requirements, necessary inputs and constraints; list artifacts and capabilities. Persist sources, facts, methods, expectations and coverage with task_review_check_plan, separating explicit requirements from hypotheses before expanding deliverables.
2. Inspect independently. Choose reading, recalculation or execution from requirements, rather than a code/document checklist. Assess whether existing assertions and operation paths support them; retain actual checks, failures, unverified results, coverage and limitations.
3. Compare reports. Persist independent findings with task_review_observations before opening main reports, execution logs and historical verdicts. Investigate discrepancies and append checks while retaining earlier findings.
4. Decide. task_review_decision cites evidence actually read or run in this job. The controller checks identity, version and artifact freshness before application. File existence, zero exit status or test counts alone cannot prove a requirement.

Missing necessary capabilities cannot silently downgrade to a pass. Known needs can be prepared before dispatch; needs identified in planning are checked before implementation approval. See independent artifact checks for configuration and generic review enhancement for protocol and real-model evidence.

Continuation, pause and recovery

After native activity settles, the controller checks task identity, permission, versions and pending human input before another turn. Continuation carries the current objective, DAG/attempt, recorded progress and next action, rather than only “continue.” Formal plan, node and completion submissions end the tool turn; the controller owns review, so normal outer PTC settlement does not cancel a handed-off job.

Ordinary log review defaults to a ten-minute deadline; independent checks use their configured deadline, default thirty minutes. Missing decision protocol allows bounded supplementation within the same job, Session and cutoff; exhaustion pauses as an internal fault. User stops, disabling, version changes and Host exit have distinct cancellation semantics; not all cancellations retry automatically. Fault retries and protocol supplementation have separate counters; supplementation does not extend the current deadline. Retries retain the reviewer Session, requirements, node attempt, evidence cutoff and artifact snapshot. History subscribes only when expanded; viewing never starts a model. Running process details expand by default, then collapse while the full recorded report stays visible; the controller supplies the actual next action.

New configuration: reviewFaultRetryAttempts defaults to 1 (0–3), reviewFaultRetryDelayMs to 3000 (0–60000), and resumeAfterReviewRecovery to true, reusing only a valid original permit. reviewReadCorrectionAttempts defaults to 1 (0–1), cumulatively per job without extending its deadline. Review control records use version 8; old records remain readable without gaining permission. Successful original tool reads restore evidence eligibility; index summaries, failed calls and model claims do not. See native review process and recovery for the handoff and boundaries.

See review-job lifetime and progress display.

Understand the implementation and develop

The plugin uses public DSH Sessions, Inbox, lifecycle and client extensions. Source and owning documents maintain exact protocols. These modules locate responsibility for control, evidence and views.

pnpm install
pnpm run build
DSH_SOURCE=/absolute/path/to/deepseek-harness node spikes/kernel/typecheck.mjs
DSH_SOURCE=/absolute/path/to/deepseek-harness node spikes/kernel/run.mjs
pnpm pack --dry-run

Further Exploration

These pages own implementation, recovery, independent checks and evaluation. Early design proposals do not describe current installation capabilities.

• Implementation status: effective configuration, validated behavior and capability boundaries.
• Native tasks: presets, Goal/Plan composition and legacy Session recovery.
• Post-completion repair: impact confirmation, original DAG and prior acceptance.
• Generic review enhancement: requirement-driven methods, evidence coverage and independent checks.
• Review-job lifetime: tool handoff, deadlines, cancellation and same-job recovery.
• Evaluation design: public benchmarks, conditions, metrics and results.

Model Experience

The main Agent receives task context and uses tools to submit plans, start nodes, report and request completion. Human input and answers retain native rendering. Reviewers receive only permitted evidence/tools and cite actual checks against current requirements. Consultation uses native conversation and compaction without interfering through ordinary questions.

Review defaults to the main Agent's effective DSH route. reviewerModel can select a provider, model and reasoning level from the current profile; records retain the actual route and Session identity. Responses aim to follow human language requirements or explicit configuration; the plugin cannot guarantee the main model's internal reasoning language.

Known Limitations and Deferred Work

Current source runs one Task per main Session at a time and permits another after completion. automaticContinuation: false prevents automatic new turns. executionApproval: after-review or /task auto-approve-on only preauthorizes the current requirements version and expires on edit. User-decision timeout continuation, parallel multi-task queues and /task plan are unimplemented.

Independent browser observation and automatic check-directory restoration are unavailable; commands changing the captured artifact tree invalidate evidence. Controlled Workers default to at most two and write exact assigned files; arbitrary shell and final integration belong to the main Agent. These limits do not prohibit native main-Agent tools.

Keep the original Host for 0.1.0 private-extension logs; this version does not rewrite them. Recovering npm 0.1.1 dedicated presets requires explicit legacyPresets. Without the plugin, public Host cannot install its admission protection; unloading is not a protected pause. Independent reviews can miss defects; installation and development regressions do not prove better long-horizon success than Goal, Plan or Agent Team.

Dev Note