dsh-side-workspace

English | 中文

A DeepSeek Harness (DSH) plugin built in the spirit of the ChatGPT / Codex trio —
side conversations · integrated workspace · pinned notes (置顶摘要小黑板)

• Repository: dsh-side-workspace
• Plugin ID / npm package: @dsh-external/dsh-side (unchanged)

Disclaimer: an independent open-source project. Not affiliated with,
endorsed by, or sponsored by OpenAI or DeepSeek. "ChatGPT" and "Codex" are
trademarks of their respective owners, referenced only to describe feature
parity.

Official naming reference (the basis for the repo name):

Features

1. Side conversations /side — Codex side conversations

/side <question> forks the current conversation's full history into a
background side conversation via a boundary context, while the main
conversation stays focused — the two never block each other; /btw <question>
is a one-shot side question (read-only). The child is an ordinary top-level
session (ctx.agents.create) that inherits the parent's agent preset, model,
and cwd, and goes through the deployment's own approval/sandbox policy — side
output never flows back into the main conversation's log.

• Default ephemeral: archived on creation, never enters the ordinary session
  list; idle children past the TTL (default 60 min) are swept by the host;
  running/approval-waiting children never expire; a new /side replaces idle
  older /side children of the same parent.
• Cleanup is a small state machine (active → expiring → removed /
  cleanup-failed with bounded backoff retries) — a failed dispose never loses
  the management record.
• Bare /side opens an EMPTY side conversation: no question is injected,
  the child waits in a ready state, and you type the question directly in
  the panel composer; afterwards it returns to the normal run/complete flow.
• Per-side model and reasoning-effort picker: expand the "Model" row at
  the top of the side detail page — models are grouped by provider; picking a
  model reveals that model's reasoning-effort options. It goes through the
  host's session.selectModel, persists on that child, and applies to its
  next step.

2. Integrated right workspace — ChatGPT Workspace

The session-header toggle opens the shell's right column (the details column;
the main conversation is squeezed), hosting a grouped list + detail pages:

• Side: this session's side conversations (run status, activity line,
  failed/cleanup-failed markers); clicking opens the detail page (full
  transcript + follow-up composer; /btw is read-only).
• Subagents: the session's subagent catalog (reference-counted live feed;
  the header badge shares the same source).
• Goal: the session goal (pause/resume/complete/clear via the goal RPC).
• Any entry opens its detail page inside the same right column — the left
  sidebar and the main conversation never switch; Escape unwinds step by step
  (detail → list → close panel).
• New-status notifications: when a side conversation settles (completed /
  failed / cleanup-failed), a warning dot appears on the small panel button
  above the main conversation (unseen count in the tooltip); opening the
  panel marks them read. History already present when you open a session is a
  silent baseline — never replayed as notifications.

3. Pinned summary board — ChatGPT Notes

A per-session board pinned to the top of the right workspace with its own pin
toggle: a slim chip when collapsed; when expanded it edits a small structured
document — title / objective / one-line status / next steps (checkable) /
decisions and any other non-empty section.

• User edits win: in this phase AI never writes to the board; every edit
  goes through the same CAS domain function the server uses (optimistic
  local apply + a serialized PATCH behind it), so the UI and the server can
  never disagree about what a patch means.
• Conflict handling: a stale-revision response resyncs the board and parks
  the edit with a banner + retry; patch ids make retries idempotent, and a
  lost-but-applied response is detected by content comparison so nothing is
  double-applied.
• Persisted at $DSH_HOME/dsh-side-boards.json (atomic write, tolerant of
  corrupt files); route /plugins/dsh-side/board
  (GET/PATCH/DELETE, same-origin, follows the deployment's ordinary access
  rules).
• A record only — never touches /goal automatically: only the manual
  button on the objective section syncs — goals.create when no goal exists,
  or goals.edit on the projection's CAS revision when one does; non-empty
  next steps ride along as a compact "下一步" list appended to the objective
  text.

4. Sidebar collapse hotzone (best-effort)

A thin drag strip just inside the left sidebar's right edge: drag left past
the threshold to fully collapse the sidebar to its 56px rail, drag right from
the rail to expand. Everything delegates to the host's own toggleSidebar();
geometry discovery is structural (never shadows the sidebar slot, the host
handle, or internal stores).

Install (DSH web profile)

The plugin mounts into the web profile via link:. You must restart dsh web yourself after changes (this plugin ships no HMR):

# 1. add the dependency (and register the client bundle under the profile's
#    dsh.profile.bundles list) to the profile package.json
"@dsh-external/dsh-side": "link:<absolute path to this repo>"

# 2. add the insert row to the profile cordis.patch.yml (this repo's
#    cordis.patch.yml is exactly that row)
# 3. install in the profile directory
pnpm install --config.confirmModulesPurge=false

Config

Usage

/side <question>   Start a continuable side conversation (runs in the
                   background; the right panel reveals it when it settles)
/side              Open an EMPTY side conversation and ask directly in the panel
/btw <question>    One-shot side question (read-only, no follow-ups)
/side list         List this session's side conversations

Diagrams

UI layout (three-column grid + right workspace + pinned board + notification dot)

Architecture & data flow (browser/host halves + shell services + lifecycle)

The hero screenshot lives at assets/screenshot-workspace.png; to replace
it, capture a new full-window shot with one running /side and the board
expanded, then overwrite that file.

Architecture

src/
  index.ts              node half: create/archive/cleanup state machine + TTL
                        sweep + web routes (/plugins/dsh-side/list, /last,
                        /board) + command wiring
  side.ts               fork cut (host fork RPC contract), model inheritance,
                        message shapes
  prompts.ts            boundary prompt / persona / mode line (self-written
                        equivalent of the /side contract)
  registry.ts           parent → child registry + cleanup lifecycle + pure
                        TTL/retry decisions
  board.ts              pure board domain: sections, items, CAS patch engine,
                        locked-item protection, size caps
  board-persistence.ts  BoardStore: one atomic JSON file under DSH_HOME,
                        per-board save chains, patch idempotency
  client/               browser half: right workspace (Side/Subagents/Goal +
                        board), transcript layer (paged history readers with
                        seed cut, streaming merge, FIFO cache), catalog
                        refcount, action gates, session-fenced pollers,
                        sidebar collapse hotzone
tests/                  165 unit tests (domain / persistence / client stores /
                        registry / transcript / …)

Development

pnpm install --config.confirmModulesPurge=false   # see the link notes below
pnpm check    # typecheck (node + client) && vitest && build

pnpm build emits lib/index.js (ESM node half) + lib/index.d.ts +
lib/client.js (CJS browser half wrapped in window.__ModuleLoader__.load;
react/cordis/dsh-client-* externalized, lucide imported per-icon, bundle
≈195kB / gzip 43kB).

Dependency notes: devDependencies reference a local DSH install through
relative link:./dsh-dev/* entries (the official packages are injected by the
profile's pnpm closure — never use the bare cordis/schemastery npm
packages as substitutes). dsh-dev/ is a gitignored junction directory; after
cloning, create it before pnpm install:

# run at the repo root; first confirm `npm root -g` contains @deepseek-ai/dsh
$dsh = (npm root -g) + '\@deepseek-ai\dsh\node_modules'
New-Item -ItemType Junction -Path dsh-dev/ai        -Target "$dsh\@deepseek-ai"
New-Item -ItemType Junction -Path dsh-dev/react     -Target "$dsh\react"
New-Item -ItemType Junction -Path dsh-dev/react-dom -Target "$dsh\react-dom"

pnpm-lock.yaml embeds absolute paths and is not committed (regenerated per
machine).

Known limitations (honest notes)

• Single details track: the shell has one right column — the board and the
  workspace share it vertically (no "double squeeze"); a second column would
  require host support.
• No width setter: ctx.layout exposes only
  toggleSidebar/openDetails/closeDetails; the sidebar handle is clamped to
  264–420px — "free drag to any width + full collapse below the threshold" is
  best-effort, and ctx.layout.setSidebar(widthPx) plus a zero-width collapse
  mode have been suggested upstream.
• The side registry is process-local: after a dsh web restart sides no
  longer appear in the panel (that is the default semantics — see the
  retention contract below).

Roadmap

• Optionally inject board content into the side boundary context (let a side
  work against the objective/next steps);
• AI proposals for the board (the assistant-proposal data model and locked
  items are ready; the proposal entry point is pending);
• True free-drag sidebar (waiting on host ctx.layout.setSidebar);
• Notification extension: subagent/goal phase changes into the same unseen
  queue.

Retention contract (read before changing)

Default is ephemeral (ChatGPT-style temporary side threads): archived on
creation (never in the left session list), registry is process-local (forgotten
on restart), idle past TTL is swept by the host (running children are never
swept), and cleanup failures stay visible with bounded retries. Set
retention: persistent for the pre-0.2 durable top-level-session behavior.

License

MIT. Third-party notices in
licenses/THIRD-PARTY-NOTICES.md.