@xiyiyiru/dsh-state

A plain-text session notebook for dsh agents: add_state / read_state / compact_state over session-log events, plus a two-tool task stack (focus_task / focus_complete).

中文 README

dsh agent 的会话状态笔记本：抗上下文压缩、跨 resume 存活的纯文本笔记层，外加一个任务栈。零自动注入——想看笔记就调 read_state，没有后台魔法。

Why

Context compaction deletes working memory. An agent that just learned "the bug is in the retry loop, user confirmed fix #2" loses exactly that when the window compresses. Auto-injected state has the inverse failure: it burns the same tokens every request and trains the model to ignore it.

This plugin persists working facts as ordinary log events — they survive compaction and resume — and keeps the folded view out of every request unless the agent explicitly reads it. Five verbs, no storage to manage, no schema to migrate.

The notebook

mycel/state log events, folded in order; the session log is the only source of truth.

tool	verb	semantics
add_state	append	push one note line. Mistakes are corrected by appending a correction line — there is no edit verb
read_state	read	full text + size; appends a compress hint once the notebook passes 8K
compact_state	replace	the compression verb: read first, then replace the whole view with a rewritten summary. History stays in the log; only the folded view changes

add_state's model-facing guidance carries hard triggers (record the moment it happens, not at task end):

1. the user made a decision or correction ("yes", "no — do it this way" landing)
2. a key fact or root cause was established (a path, a cause, a number that would need re-discovering)
3. a multi-step task is starting (goal + acceptance criteria — recovery material after compaction)
4. a milestone completed (conclusion + artifact paths; work that leaves no trace didn't happen)

The task stack

mycel/focus / mycel/focus-done events; frames are plain one-line task descriptions.

tool	verb	semantics
focus_task	push	lock a multi-step task; the previous task is pushed down automatically
focus_complete	pop	declare done with a one-line conclusion and fall back to the previous task (or clear the stack). Call it before delivering the answer — the task's completion standard is the artifact landing

focus_task's guidance on when not to use it: single-turn Q&A, or a change of working posture within the same task (that is the mode plugin's business — the two are orthogonal by design: the stack restores your task, a re-switch restores your methodology; frames carry no mode snapshot).

Interrupted mid-task? Lock the blocker with focus_task, solve it, focus_complete back to the main task.

As a convenience, focus events also append to <session-cwd>/.mycel/focus.log — best-effort, for grepping a workspace's task history; the session log remains authoritative.

What it does not do

• ❌ no auto-injection: the notebook never leaks into a request on its own
• ❌ no prompt section, no system-prompt contribution at all
• ❌ no mode knowledge, no snapshot riding frames (mode-agnostic since 2026-09-03)
• ❌ no edit/delete verbs — append or compact-replace, two verbs total

Install

dsh plugin --profile <name> add @xiyiyiru/dsh-state

Peer dependencies (@deepseek-ai/cordis, dsh-agent, dsh-session, dsh-system-prompt, dsh-tools) resolve from your dsh installation automatically.

API

import {
  ADD_STATE, READ_STATE, COMPACT_STATE,
  FOCUS_TASK, FOCUS_COMPLETE, FOCUS_TASK_DESCRIPTION, FOCUS_COMPLETE_DESCRIPTION,
  foldNotes, foldFocus, SIZE_WARN_THRESHOLD,
  type StateNote,
} from '@xiyiyiru/dsh-state'

export	what it is
foldNotes(events)	the folded notebook lines for a session log (or any prefix)
foldFocus(events)	the stacked task lines, bottom frame first
SIZE_WARN_THRESHOLD	8000 — where read_state starts appending the compress hint
ADD_STATE … FOCUS_COMPLETE	tool names; *_DESCRIPTION their model-facing descriptions
StateNote	{ op: 'append' | 'compact', text: string } — one mycel/state event

Session events: mycel/state (StateNote), mycel/focus ({ task }), mycel/focus-done ({ task, note? }) — all log-only, non-surface, never compacted away.

Design notes

• Zero auto-injection — reading is an explicit act; the folded view costs tokens only when spent deliberately.
• Append-mostly — two verbs (append / compact-replace) keep the fold trivial and the semantics total; correction is a new line, not a rewrite.
• Log is truth — everything derives by folding the session log; the focus.log sidecar is a convenience projection, lossy by design.

License

MIT