Introduction

When running long tasks for agents in DSH, a common issue is the lack of visibility into what is happening right now: the current round of the goal, which subagents are running, which stage the workflow is at, and whether background tasks have failed. This information is scattered across different parts of the session, forcing users to switch back and forth to view it without opening logs.

dsh-agent-pill solves this visibility issue by condensing the current session’s key activities into a status capsule in the top-right corner, and using a shortcut key to expand a floating panel when details are needed. Below is an introduction in the order of function, architecture, installation, and usage.

What is it

dsh-agent-pill is a DSH web plugin maintained by mozhuanzuojing, under the MIT license, current version 0.14.8. One-sentence positioning: ZCode-style agent activity capsule (top-right status capsule) + floating summary panel, Ctrl+Alt+P to toggle.

The plugin is split into two halves:

  • Host half: Aggregates the current session’s Goal / Subagents / Agent status / workflow execution / background tasks, exposing a JSON API with full control verbs via /pill/api.
  • Client half: A top-right floating capsule + an anchor-capsule-based tooltip-style floating panel, containing goal cards, workflow history (steps and observation files), subagent tree, and task list (output / kill).

Core Features

Capsule and Floating Panel

  1. Ctrl+Alt+P to toggle the panel, clicking the capsule works as well.
  2. The panel is a lightweight popover anchored to the capsule, not a fixed right-side drawer: it flips between four viewport edges to stay fully visible, scrolls internally up to about 70vh, and closes on click outside, Esc, or pressing the shortcut again.
  3. Width auto-adaptation (v0.9.0): Driven by ResizeObserver, clamped between 320–520px and capped by the viewport; diff lines maintain white-space: pre without wrapping.
  4. The capsule is draggable to any screen edge, position persisted to localStorage, and stays clamped within the viewport on window resize.
  5. Theme follows DSH: Colors driven by CSS variables, responding to the <body data-ds-dark-theme> signal; instant switching between White / Dark (Moon Night), including a system mode that follows the OS.
  6. Section folding: Goal / Agent / Subagents / Jobs section headers are clickable to fold; state saved to localStorage; default expanded since v0.13.0.
  7. Empty state hiding (v0.6.0): Goals without targets, Subagents without child nodes, Jobs without entries, Activities without events are hidden as a whole—only showing existing content.
  8. Detail layers (v0.7.0): Clicking a workflow run or subagent row pushes a new detail layer inside the popup (with a back button in the header); returns automatically when the goal disappears, resets on session switch. Subagent details include identity, mode, timing, termination status, and stop control.

Goal Card and Workflow History

  • The Goal card displays the goal, stage, round count, elapsed time, and active status, with a round progress bar (roundsStarted / maxGoalRounds).
  • Workflow history (v0.4.0): A bounded ring of the last 5 runs. Each run can be expanded to see steps (seq / label / phase / outcome for each agent() call) and observed files during the run (from the host’s fs/observed stream, deduplicated and attributed to the run). Ended runs retain details until replaced by a new run.
  • Steps and subagent association (v0.6.0): Step rows are associated with subagent rows via childId, displaying subagent duration and termination color.
  • File diff (v0.8.0 / v0.9.0): Workflow file chips open a file detail layer. When displaying results, it shows line-level diff (from dsh-tool-fs tool/result meta, distinguishing new file / edit / overwrite) plus a copy path button. Since v0.9.0, diffs are inline expanded within the file list, each file has a +N/-N badge, defaulting to only changed lines, switchable to include context.
  • Activity timeline (v0.9.0): The Activity section streams the latest host events—tool calls and completions, file activity (counted merged by path), workflow stage changes, subagent start/end, goal changes—a 40-item bounded ring.

Subagent Tree and Background Tasks

  • The Subagent tree is indented by depth, each line displaying running duration and termination stop reason, red for failures. Timestamps come from the host’s subagent/start / subagent/end events.
  • Background tasks are rendered as a single step entry (status, output summary, timing); since jobs have no structured steps, no file extraction is done. The task list supports viewing output and killing.

Real-time Status and Notifications

  • Capsule summary (v0.3.0): Goal elapsed time plus real-time badges—running subagent, running task, active workflow (wf badge, tooltip shows current stage), failed tasks (red).
  • Real-time tool names (v0.5.0): In-flight tool names of the running session are displayed in the capsule bar and tooltip, cleared after tool/result.
  • Tool duration (v0.6.0): Paired tool/call and tool/result display, e.g., ⛭ write · 0s, ✓ edit done · 12s. DSH executes tools serially, so a single in-flight slot is sufficient to complete the pairing.
  • Real-time capsule labels (v0.8.0): Capsule text prioritizes the name·phase of the running workflow, falls back to current tool name, then to AGENT.
  • Queue messages (v0.5.0): The agent/inbox event maintains the queue count per session; the capsule displays a q badge.
  • Completion notifications (v0.5.0): Triggered once each when a workflow ends, a background task fails, or the goal completes. Permissions are requested lazily; ended IDs are registered on page refresh but notifications are not replayed.
  • Idle long polling (v0.8.0): When all idle, the client stops long-polling POST /pill/api/poll (30s limit) on the host instead of polling every 1.5s; wakes up and resumes rhythm when active.

File Records within Sessions (v0.14.x)

  • turn-tail file lines (conversation.chat.turnTail): Displays files processed under each user instruction in the session, with +N/-N badges, inline diff (switchable between only changed lines / with context), and a copy path button.
  • When busy, the capsule shows “Round N · Action”.

History note: Early Usage blocks (token pressure / cost estimation) and the Sessions fleet view were removed in v0.12.0; the plugin now only displays content existing in the current session.

Architecture: Contract Single Source and Domain Modules

The v0.14.8 architecture adjustment revolves around testability and AI navigability, splitting the host half’s orchestration modules by domain:

  1. Contract Single Source: src/contract.ts is the single source of truth for the /pill JSON API wire contract, imported by both host and client. Previously, the host inline views (GoalWireView / SubagentWireView) and the client’s api.ts (PillGoal / PillState, etc.) were two separate hand-written mirrors; changing fields in the host would silently break the client types. Now, a change to the host contract triggers a compile-time error for the client.
  2. Domain Deep Modules: src/goal-tracker.ts (goal projection), src/git-status.ts (pure parsing separated from TTL caching), src/usage-snapshot.ts (token-meter + context-window), src/subagents.ts (subagent descendant tree), and src/jobs.ts (background task list) each come with injected seams for unit testing; src/index.ts returns to a thin seam wiring with method dispatch.

Installation and Enablement

When writing this article, the README and package.json captured did not contain the original installation command, so no concatenation is done here; please refer to the repository README: https://github.com/mozhuanzuojing/dsh-agent-pill

For dependencies, please verify against package.json:

  • peerDependencies: @deepseek-ai/cordis ^4.0.2; @deepseek-ai/dsh-agent, @deepseek-ai/dsh-client-store, @deepseek-ai/dsh-goal, @deepseek-ai/dsh-jobs, @deepseek-ai/dsh-session, @deepseek-ai/dsh-subagent, @deepseek-ai/dsh-web-app are all ^0.1.2-rc.1; react / react-dom ^18.2.0.
  • The dsh field in package.json declares this as a web platform plugin, and the client injects @deepseek-ai/dsh-client-store.

Daily Usage

  1. Ctrl+Alt+P or click the capsule to toggle the summary panel.
  2. Drag the capsule to any edge of the screen; position is preserved across refreshes in localStorage.
  3. Click Goal / Agent / Subagents / Jobs section headers to fold or unfold.
  4. Click a workflow run or subagent row to push a detail layer, use the header back button to return.
  5. Workflow file chips expand line-level diffs, defaulting to only changed lines, switchable with context, with a copy path button.
  6. View output summaries inline for background task rows, kill to terminate when needed.

Use Cases and Caveats

Suitable for DSH web users running long goals / workflows / background tasks who want to grasp agent progress without leaving the current interface. If you previously relied on flipping through logs to judge agent behavior, the Activity timeline and turn-tail file lines will directly present “what changed and where it went” on the interface.

Caveats:

  1. The plugin runs with the permissions of the current dsh process; the host half aggregates session state and exposes /pill/api. Please check the source code and license (MIT) before enabling to confirm it is acceptable.
  2. Browser notification permissions are requested lazily on first trigger; events that have ended will not replay notifications after page refresh.
  3. Usage / Sessions related displays were removed in v0.12.0; looking for entry points based on old version introductions will result in a dead end.

Summary

dsh-agent-pill compresses the activity status of a DSH session into a permanent capsule and a floating panel: you can see what the agent is doing without opening anything, and once expanded, goals, workflows, subagents, background tasks, and file diffs are at your fingertips. MIT license, current version 0.14.8.

  • Directory page: https://www.skillhub.cn/plugins/mozhuanzuojing/dsh-agent-pill
  • GitHub: https://github.com/mozhuanzuojing/dsh-agent-pill

Adding an ecological context: DSH’s philosophy is “everything is a plugin,” and such visibility tools are suitable for on-demand installation; skillhub.cn is a community-maintained independent plugin directory with no official affiliation to DeepSeek / Xuanfang.