DeepSeek Harness Plugin

7starsseeker/dsh-task-anchor

Stars ★ 0 Downloads (30d) 798 Category Sessions & Messages Added 2026-11-16 npm dsh-task-anchor

Keeps the running plan when a mid-turn message arrives — open todos are written to disk, the interjection is laid out next to them in the turn it lands (cancel, amend, or separate work), a suspended-work block follows in later turns until the items are finished or cancelled, and a turn-closing guard makes leftover work explicit instead of silently dropped; it softens the attention drift rather than removing it.

Install

# from npm (prebuilt)

dsh plugin --profile web add dsh-task-anchor

# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)

dsh plugin --profile web add github:7starsseeker/dsh-task-anchor

Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).

README

中文版:README.zh-CN.md

When a task is interrupted mid-flight, don't let the original task disappear.

selftest

A zero-dependency DeepSeek Harness host plugin. When a turn receives a mid-turn user message and ends with unfinished todos, it steers one notice back into that turn so the model either finishes the work or states plainly what remains.

No core patch, no fork, no change to the session projection.


The failure it addresses

A mid-turn message reaches DSH through one of two paths, and both can drop the running task:

Path Mechanism Where it fails
steer (Enter while busy) The message joins inbox's next-step; the next step boundary claims it and appends it as an ordinary user/message The interjection reaches the model with the same shape and weight as the opening prompt (packages/core/session/src/surface.ts projects it verbatim — a deliberate 2026-07-20 decision), and the system prompt says nothing about mid-turn messages. The model readily treats the newest user message as the only task
queue The message joins next-turn; the current turn ends normally and the message opens the next one The turn ends with todos unfinished and nothing checks what it left behind; the next turn belongs to the new message

Common root: the todo projection is cleared at turn/start (packages/todo/tool-todo/src/index.ts), so the next turn is never reminded that work is still open.

Scope, stated plainly. This softens the drift; it does not remove it. The interrupting message still takes the step it lands on, and the model can still pivot before the next boundary — the contract is advisory and the guard fires only once the turn is already closing. What changes is that the plan survives the pivot: it is written down, re-rendered, and the turn cannot close silently with it unfinished. Closing the gap itself — deciding that a mid-turn message should wait, and giving it a different identity in the transcript — is a harness decision, not a plugin one.

What it does

  1. Contract (task-anchor:contract, a system-prompt section, ~320 tokens per request): a mid-turn user message is new input, not automatically a replacement for the task in progress. Classify it first — added constraint / correction of the current step / question / separate new task / explicit change or cancellation — then act. The same section says how to record a suspended plan, when a finding is expensive enough to persist, that an answer to your own question is a decision rather than a fact, and that work the user cancelled is not re-narrated afterwards. Never silently abandon unfinished work.

  2. Suspended plan (agent/pre-step → one JSON file): when a mid-turn message arrives while todos are open, the open items are written once to suspended-<session>.json. Every later assembly renders them back as a ## Suspended work block — only the items still open, the message that interrupted, where the turn stopped, and the session event number that holds the transcript for session_event_read. When those items leave the list (done or cancelled) the file is deleted. In the turn the interjection actually landed in, the same snapshot renders as ## Interjection during this turn instead: it names the three readings (cancellation / amendment / separate work) and asks the model to decide in that turn — stopping is the model's call, not a plugin-side interrupt. With no snapshot but open work, the section ends with a single Open items: … line, because the todo panel is a per-turn surface and the log is not.

  3. Guard (agent/turn-stopping): when all of the following hold, agent.steer() returns one notice to the turn:

    • this turn observed a mid-turn user message (step > 1 and the batch contains a source.kind === 'user' message), or inbox.nextTurn already holds a queued message;
    • the latest todo/write (within maxStaleTurns turns) still has pending / in_progress items;
    • the turn's final sentence is not a question (skipWhenAsking);
    • this turn was not nudged yet and the session is under maxNudgesPerSession.

    The model takes one more step: finish, or say what remains and why.

  4. Observation (agent/pre-step): read-only bookkeeping of which turns received an interjection; visible in debug logs.

  5. First run (first-run.json): the first start against a store adds a ## First run section that names the switches (returnPolicy, forceStop, onInterject, storeTtlDays), their current values, and asks the model to state them and ask whether to change anything. The version in that note is read from package.json, so it cannot go stale. A marker file keeps it to one run; if the store is unwritable the note simply reappears next start.

Snapshots are swept opportunistically: writing one deletes other sessions' suspended-*.json older than storeTtlDays. The plugin never touches DSH's own session archive.

Install (local profile)

# 1) register the directory as a profile dependency and bundle.
#    Edit <DSH_HOME>/profiles/desktop/package.json:
#    dependencies        -> "dsh-task-anchor": "link:<path-to-this-repo>"
#    dsh.profile.bundles -> "dsh-task-anchor"
# 2) link it
cd <DSH_HOME>/profiles/desktop
pnpm install
# 3) restart DSH (host plugins load at boot; profile bundles are not hot-reloaded)

<DSH_HOME> is the directory that contains profiles/ (wherever your DSH install keeps its profile data).

Config

Under config: in cordis.patch.yml; every key is optional.

Key Default Meaning
enabled true Master switch; false registers nothing
contract true Inject the prompt contract (~320 tokens/request); also gates the anchor block
guard true Enable the turn-stopping guard
onInterject triage On a mid-turn message, persist the suspended plan (triage) or only keep the guard (off)
returnPolicy auto Nudge the turn (auto) or record only until the user speaks again (wait). wait disables the nudge; on its own it cannot abort a running turn — see DESIGN §7.4
forceStop off Experimental. off / always / triage. End the turn at the step boundary the interjection landed on and hand that message to the next turn. triage stops only when the text does not read as a cancellation or an amendment. Off by default; ending a turn makes the host play its end-of-task cue, so this is not the recommended path
cancelPatterns built-in list Regexes (case-insensitive) that mark an interjection as "drop the plan". Supplying an array replaces the defaults
amendPatterns built-in list Regexes that mark an interjection as "same plan, changed". Supplying an array replaces the defaults
triggerQueued true Also act when a queued message is waiting for the next turn
skipWhenAsking true Skip when the turn ended with a question
maxNudgesPerSession 6 Nudges per session; 0 = observe only
maxNoticeItems 5 Items listed in the notice / the Open items: line
maxStaleTurns 3 Turns after which a todo list is stale (guard only)
storeDir <DSH_HOME>/task-anchor Where suspended-<session>.json lives; falls back to ~/.dsh/task-anchor
storeTtlDays 7 Age after which another session's stale snapshot is swept while writing; 0 disables

Boundaries

  • No relation classification. The plugin calls no model and does not decide which kind of interjection arrived; the contract plus the model own that judgement. The plugin only enforces the mechanical part: was open work left behind?
  • Step-1 interjections are not detected. claim() takes next-step and next-turn together at step 1, so "steering" and "opener" cannot be told apart by step alone. Documented known gap.
  • Turns without a todo list are never nudged. No declared plan, no open item to account for.
  • It never delays an interjection. A agent/pre-step listener could rewrite the step's messages — the waterfall's enter decision is exactly what gets logged and sent to the model — and park the message for later; returning reject instead ends the turn right there (turn/end reason blocked). This plugin deliberately does neither: holding a message would silence a legitimate "stop, wrong direction", and rejecting the step would throw away the half-done work too. Stopping because of an interjection stays the user's call.
  • It does not touch surface.ts. The model-side identity of a steering message stays flat; adding a render-layer marker requires a meta renderer and a new Agent Note.

Relation to neighbouring plugins

  • dsh-loop-continue and dsh-early-stop-guard also agent.steer() from agent/turn-stopping. This plugin nudges at most once per turn, but two plugins can each nudge in the same turn; pick one.
  • dsh-todo-float-ball only displays "plans lost to an interruption"; it does not inject anything. Complementary.

Verify

cd <path-to-this-repo>
node --test     # 52 tests: policy decisions + apply() wiring, no harness needed

Manual end-to-end after a restart: give the agent a three-step task that starts with a todo list, inject an unrelated question during step 2, then check that a [task-anchor] notice appears before the turn closes and that the model accounts for the remaining items.

Log keys: task-anchor: steered a reminder (info), task-anchor: mid-turn user message observed (debug).

Confirmed 2026-11-15 on DSH 0.2.2-rc.3: after a restart the session system prompt contains the contract section, an unrelated mid-turn question produced a suspended-<session>.json plus the ## Suspended work block, and the turn closed with an [task-anchor] notice. Rewriting the todo list without the suspended items deleted the file.

returnPolicy: wait was also tried: the guard stayed quiet as intended, but the turn did not stop — the model kept working on the suspended plan on its own. That is the honest boundary: wait removes the nudge, and the only thing left to ask for a stop is the contract text, so ### Waiting for the user was added to state it explicitly. The main path is therefore not a forced stop but the same-turn block described above: the model sees what is parked and what just arrived, in the turn where it happened, and it is the one that decides. forceStop: always exists as an experimental mechanical stop: the agent/pre-step handler parks the claimed message into next-turn and returns reject, so the step never opens, turn/end records blocked, and the next turn starts with the interjection. Verified live on 2026-11-15 (turn/end reason=blocked → message re-delivered at the next turn's start), and the same run showed the cost: the host plays its end-of-task cue, which the user reads as "my task was killed". forceStop: triage narrows that to messages that do not read as a cancellation or an amendment; keyword heuristic, not verified live.

Experimental: the hard stop (forceStop)

Off by default (forceStop: off), and not the recommended path — the same-turn block above is. It exists for people who want a mechanical guarantee instead of a suggestion.

Mechanism. On agent/pre-step, when the claimed batch contains a user message, parkAndStop() appends each interjection to the inbox as next-turn (written first, so a crash cannot lose it) and returns { kind: 'reject' }. The loop turns that into turnEnds = { kind: 'blocked' } and returns without calling step() (dsh-agent-loop/src/agent.ts:354-357), so the host sees a normal end of turn and the message is delivered verbatim as the opening of the next one.

Limits.

  • It ends the turn, not the plan: the todo list survives, the transcript up to that point survives, earlier tool results stay readable.
  • The rejected turn has no assistant closing line; the transcript just stops.
  • The host plays its end-of-task cue, indistinguishable from "the task finished" — that is the cost that keeps it off by default.
  • triage narrows the stop to text that matches neither cancelPatterns nor amendPatterns. Those are keyword heuristics, not semantics: an unrelated question with no cancel/amend wording still reads as separate work and still stops.
  • Parked messages are re-delivered when the loop goes idle. If it never does, they stay in next-turn and ride along with the next user message.
  • Config: forceStop: off | always | triage, returnPolicy: auto | wait. Defaults are off + auto.

Status

Progress, evidence, open items, next steps: docs/STATUS.md. Design rationale: docs/DESIGN.md.

Content from the project README on GitHub ↗

Links

More in this category

View the whole category →

Community comments

Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.