dsh-dot-plugin

DSH Dot

A persistent, read-only-first proactive agent for DeepSeek Harness, with user-approved execution.

dsh-dot-plugin is a DSH plugin that gives DeepSeek Harness a real Dot: its own durable Agent Session, a read-only research phase, independent risk review, user-only approvals, and a tightly-scoped execution phase.

It is inspired by the capability model of OpenAI's Dots, but it is an independent open-source project. It is not affiliated with, endorsed by, or connected to OpenAI, and it does not attempt to reproduce OpenAI's hosted cloud computer or 4,000+ app marketplace.

Why

Most agent plugins are reactive: they answer, then stop. Dot is designed to keep a thread of work alive:

1. inspect real, configured sources without modifying anything;
2. decide whether something is worth doing;
3. prepare a concrete proposal;
4. ask the user when the action has real-world consequences;
5. execute only the approved action, with only the approved tools;
6. record the real result and keep long-running work moving.

The ordinary conversation you use to code is not intercepted. Dot has its own Session and its own tool policy.

Features

Capability · How it works Persistent Dot Agent · A top-level Agent/Session resumed from durable state; title Dot Task orchestrator · Dot creates tasks, assigns real worker Agents, tracks status, handles approvals, and lets the user switch focus Native Dot workspace · The Dot Session plus a right rail for status, approvals, tasks, schedules, triggers, recent outputs, and sources Read-only research · Global tool allowlist + a scoped, monotonic tools.guard() Real sources · Local directories, public/API URLs, and read-only MCP tools Proposals · dot_propose_action writes a durable proposal; it never executes Independent risk review · A separate small model classifies every proposal; the proposing model does not grade itself User-only approval · DSH panel and /dot slash command; no Agent Tool can approve a proposal Scoped execution · An approved execution turn receives only that proposal's tools Task tracking · dot_add_task / dot_update_task; progress comes from real evidence DSH schedules · dot_schedule_task uses the Host schedule service, not a private cron loop Event triggers · dot_register_trigger + local webhook/service entry point No global rule hijack · Rules apply to Dot only, not to the user's other Sessions Result attribution · Execution results are read only from the execution turn, and interrupted turns are marked failed

Architecture

┌─────────────────────────────┐
                       │        DSH Host             │
                       │                             │
  user approval ──────▶│  DotRuntime                 │
  (panel or /dot)      │   ├─ Dot Agent/Session      │
                       │   ├─ read-only research     │
                       │   ├─ proposal store         │
                       │   └─ execution allowlist    │
                       │                             │
  sources ────────────▶│  read / glob / grep         │
  (directory/URL/MCP)  │  web_search / web_fetch     │
                       └──────────────┬──────────────┘
                                      │ DSH slots
                       ┌──────────────▼──────────────┐
                       │      Client panel           │
                       │  sidebar icon + main panel  │
                       │  proposals / tasks / status │
                       └─────────────────────────────┘

The Dot Agent is created with the standard DSH preset, then a Dot-scoped prompt section and scoped tools are added.

Research phase

• Allowed global tools default to read, glob, grep, web_search, web_fetch.
• Everything else is removed with tools.restrict() when possible.
• A scoped tools.guard() denies any other call even if a preset-scoped tool is not filtered by the global restriction.
• The research prompt tells Dot to inspect only the configured sources and to propose — not execute — work.
• dot_schedule_task, dot_add_task, and dot_register_trigger are internal bookkeeping tools and remain available during research.

Proposal phase

dot_propose_action records:

• title, description, proposed outcome;
• source and evidence;
• execution_tools (for example ["write"]);
• an exact execution_instruction.

A separate Reviewer asks a small model for a risk verdict (low / medium / high) with a reason. User rules are applied after that. The default configuration does not auto-approve even low-risk proposals; opt in with autoApproveLowRisk: true.

Execution phase

Approval is user-only. On approval:

1. the research restriction is lifted;
2. an execution allowlist is built from the proposal's executionTools plus read / glob / grep;
3. the Dot Agent receives an execution prompt in the same Session;
4. the scoped guard denies every tool outside that allowlist;
5. when the turn ends, the result is read from that turn only and written back to the proposal.

High-risk actions such as send, publish, pay, delete, invite, or credential access are expected to be proposed as drafts or preparatory steps. The user can reject them, or configure stricter rules.

Requirements

• DeepSeek Harness Desktop or dsh web profile
• Node.js >= 22
• pnpm
• A working default model route in DSH
• For real app connectors: the corresponding read-only MCP tools in DSH

The plugin was tested against the DSH 0.2.1-rc.2 family.

Install

git clone https://github.com/1315577677/dsh-dot-plugin.git
cd dsh-dot-plugin
pnpm install
pnpm build
pnpm test

Then install the local bundle with DSH's Plugin Manager:

plugin_manager install_bundle target=/absolute/path/to/dsh-dot-plugin

Or install it from the DSH Plugin Manager UI by choosing the local bundle directory.

Desktop note

The Host half activates immediately. The Client half (sidebar icon + panel) is part of the web boot graph, so fully quit and reopen DSH Desktop after installing or replacing the Client bundle. A browser-style page refresh is not available in the Desktop shell.

After reopening, the sidebar shows DSH Dot and the Dot Session appears in the Session list.

Configure sources

The default cordis.patch.yml intentionally contains no machine-specific sources. Add real read-only sources under the config.sources list and reinstall the bundle (or override the row in your profile patch).

Local directory

- insert:
    - id: dsh-dot-plugin
      name: 'dsh-dot-plugin'
      config:
        enabled: true
        agentPreset: standard
        dotWorkspace: '/absolute/path/to/workspace'
        sources:
          - id: inbox
            kind: directory
            label: Local inbox
            path: '/absolute/path/to/inbox'
        readOnlyTools: [read, glob, grep, web_search, web_fetch]
        executionTools: [write, edit]

dotWorkspace is the Dot Session's cwd and the workspace used by the file sandbox. It should contain the files you want Dot to be able to write after approval.

Public URL / API

sources:
  - id: github
    kind: url
    label: GitHub issues
    url: 'https://api.github.com/repos/owner/repo/issues?state=open&per_page=10'

Dot uses web_fetch for URL sources.

Real apps via MCP

Connect Gmail, Google Calendar, Slack, GitHub, or another app through DSH's MCP support, then expose only read tools to Dot:

sources:
  - id: mail
    kind: mcp
    label: Gmail read-only
    tools: [gmail_search, gmail_read]

readOnlyTools:
  - read
  - glob
  - grep
  - web_search
  - web_fetch
  - gmail_search
  - gmail_read

This plugin does not embed OAuth credentials, app passwords, or a vendor connector. The MCP server owns authentication and the tool surface; DSH owns the tool registry.

Demo fixtures

The repository includes realistic sample files in dot-demo/inbox/. To try the plugin:

1. set dotWorkspace to the repository root;
2. set a directory source to /dot-demo/inbox;
3. reinstall and reopen Desktop;
4. open the DSH Dot panel and click Run research now.

The included dot-demo/outbox/ starts empty; files appear only after an approved execution.

Configuration reference

Key · Default · Description enabled · true · Enable the Dot runtime initialDelayMs · 20000 · Delay before the first research round researchIntervalMs · 300000 · Research heartbeat agentPreset · standard · Preset mounted into the Dot/worker Agents; supplies read/web tools orchestrator · true · Enable the task supervisor/worker model; set false for legacy research maxWorkers · 2 · Maximum concurrent worker Agents workerMaxTurns · 3 · Follow-up turns per worker workerTimeoutMs · 900000 · Worker turn timeout workerStageMaxBytes · 1048576 · Max size of one staged file dotWorkspace · profile default · Dot Session cwd / write sandbox root sources · [] · Directory, URL, or MCP sources readOnlyTools · [read, glob, grep, web_search, web_fetch] · Global tools available during research executionTools · [write, edit] · Tools a proposal may request for execution reviewProvider · current default · Small-model provider for risk review reviewModel · current default · Small-model model for risk review reviewTimeoutMs · 20000 · Risk review timeout rules · built-in defaults · { action_pattern, decision: allow \ · ask \ · deny } autoApproveLowRisk · false · Auto-run proposals that are both rule-allowed and low risk maxProposalsPerRound · 3 · Proposal cap per research turn stateDir · /data · Durable plugin state directory

Rules are regular expressions tested against the proposal's action type, title, outcome, execution instruction, and tools.

Using Dot

Task orchestrator (v0.3)

Set orchestrator: true to turn Dot into a task coordinator:

config:
  orchestrator: true
  maxWorkers: 2
  workerMaxTurns: 3
  dotWorkspace: '/absolute/path/to/workspace'

In this mode:

• Dot is a supervisor, not the worker that does every step. In supervisor mode it has no read, glob, grep, web_search, web_fetch, or generic shell tools; all source evidence comes from workers.
• A user request becomes a durable task.
• dot_assign_worker starts a separate DSH worker Session, or queues the task when maxWorkers is full.
• Workers can read within task roots, search/fetch the web, report progress, and write only to .dsh-dot/staging//.
• A worker return moves the task to coordinating; worker failure moves it to blocked.
• Approved execution runs in a separate executor Agent Session, not in the Dot supervisor Session. The Dot conversation shows task events; the executor owns the real write tool turn.
• The supervisor receives a bounded worker event and decides: continue, ask the user, switch focus, or complete.
• dot_focus_task / clicking a task in the right rail changes priority, never cancels other tasks.
• Task-linked proposals use task_id; approvals and execution results become task events.
• Assignment accepts a running task with no active worker, so the supervisor does not need to cancel and recreate a task after a status transition.
• The coordinator pumps the next queued task when a worker slot frees.
• On Host restart, workers that no longer have a live Agent are marked blocked/interrupted, never falsely running.

Workers do not receive generic write, edit, or bash; they do not receive approval or task-management tools. Real workspace writes still require a user-approved proposal.

Legacy mode: with orchestrator: false, the v0.2 read-only research + proposal + approved-execution behavior remains available.

The DSH Dot workspace

The primary surface is the Dot conversation itself, not a separate chat page:

1. Click the DSH Dot action at the sidebar foot, or open the Dot Session from the Session list.
2. In the Dot conversation header, click Dot. The right rail opens automatically for the Dot Session.
3. The right rail shows the Dot status, pending approvals, tracked tasks, DSH schedules, event triggers, recent outputs, and sources.

The same approval path is in the rail and in the full control panel:

• Approve and execute / Reject are user-only actions;
• each pending proposal shows its risk, action type, execution tools, and linked task;
• Check tasks runs the orchestrator maintenance tick (legacy research only when orchestrator: false);
• Full panel opens the larger DSH Dot control panel.

This is a native DSH layout: the center is the real DSH conversation, the right column is a DSH sidebar tab, and the left remains the normal Session/project list. It deliberately does not imitate a separate hosted Dot desktop with a cloud computer, Slack calls, or voice.

The full panel

Open DSH Dot from the sidebar icon for the larger control panel:

• pending proposals with evidence and execution tools;
• tracked tasks, DSH schedules, and event triggers;
• recent executed proposals and results;
• sources and Dot status;
• Open Dot conversation and Run research now.

/dot command

For environments where the panel is not loaded yet, the same approval path is available as a user command:

/dot
/dot status
/dot approve <n|proposal-id>
/dot reject <n|proposal-id>
/dot run

A slash command is submitted by a human; no Agent Tool can invoke it.

Event triggers

Register a trigger with the Dot tool or directly through the service:

const dot = ctx.get('dshDot')
await dot.fireTrigger(triggerId, {
  from: 'alerts@example.com',
  subject: 'urgent: production review',
})

Local HTTP entry point:

curl -X POST http://127.0.0.1:<dsh-port>/dsh-dot/trigger \
  -H 'content-type: application/json' \
  -H 'x-dsh-dot: 1' \
  -d '{"triggerId":"trigger_...","payload":{"subject":"urgent"}}'

A trigger only wakes Dot for read-only investigation. It does not execute the instruction directly.