feat(desktop): DSH Electron desktop shell — harness internals visualized

Minimal Electron shell over the DSH JSON-RPC runtime — a first-look at
what a ChatGPT.app-style host on top of the DeepSeek Harness looks
like, with the harness's normally-invisible internals (trace timeline,
context surface, subagent tree, compaction, plugin registry, rubrics)
brought forward as first-class UI surfaces so plugin authors and
researchers can see what the agent is actually doing.

Runs against three keyless-to-live profiles (stdio-echo works on
master out of the box; daemon-echo / daemon-vibe-echo activate once
the daemon-demo lands; stdio-deepseek and daemon-vibe hit the real
DeepSeek API when you supply a key). HARNESS_DEV auto-resolves to the
in-repo runtime when this shell ships under examples/desktop/, so a
fresh clone launches without config; env DSH_DEV_ROOT overrides for
custom layouts, and a sibling deepseek-harness-dev/ checkout is the
original dev workflow.

Cold-clone gate (P0 fixes for first-time-clone usability):
- HARNESS_DEV: 3-candidate resolver (env → walk-up in-repo marker →
  sibling), unit-tested via mock fs so ordering is locked without
  needing either real layout on disk.
- config yml leaves rewritten at assemble time so the sibling-clone
  paths (../../deepseek-harness-dev/examples/echo-agent/…) become
  the in-repo paths (../../echo-agent/…) in the released tree —
  source yml stays usable for local dev, released tree ships a
  working shape.
- pnpm-workspace.yaml allowBuilds.electron = true (was placeholder).
- missing-key card in stdio-deepseek offers a one-click switch to
  stdio-echo (the keyless profile that works on master) rather than
  daemon-echo (blocked on the not-yet-shipped daemon-demo).
- assemble-oss-release.sh rewrites the source-side breadcrumb name
  'dsh-desktop-demo' → 'dsh-desktop' for the released package.json.

FOUC guard on the onboarding gate (41fc5df carried) keeps the
first-launch splash from flashing before the runtime probe finishes.

Test suite (1634 tests in source, 3990 in the runtime repo) covers
resolver ordering, renderer classifiers, trace timeline shape,
compaction diff rendering, rubric parity, and the missing-key
onboarding paths.

examples/desktop/config/daemon-echo.yml

@@ -0,0 +1,44 @@
+# Daemon-hosted JSON-RPC serving config for the desktop demo — keyless echo.
+#
+# The daemon bin (packages/examples/daemon-demo) binds the unix socket at
+# $DSH_DAEMON_SOCKET_PATH and holds the lockfile at $DSH_DAEMON_LOCKFILE_PATH.
+# Both env values are required so misconfiguration fails loud rather than
+# silently binding a fixed default under $HOME.
+#
+# The leaf mirrors examples/daemon-agent/cordis.yml from the dev clone,
+# with paths rewritten so relative plugin imports still resolve against the
+# echo-agent leaf inside the dev clone.
+
+# Mock adapter and echo tool from the echo-agent leaf; keyless.
+- id: mock-llm
+  name: '../../echo-agent/src/mock-llm.ts'
+
+- id: echo-tool
+  name: '../../echo-agent/src/echo-tool.ts'
+
+# Bash executor — required by the spine's bash tool schema.
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+# session-query backs session/list metadata (title, running, lastEventTime)
+# and the sidebar tree; without it the daemon errors on session/list. Same
+# load pattern as the dev clone's integration-smoke.mjs.
+- id: session-query
+  name: '@deepseek-ai/dsh-session-query'
+
+# NOTE (2026-07-16): user-interaction is NOT loaded here — the
+# `dsh-daemon-demo` bundle below already imports it and installs the
+# interrupt bridge internally (see the "spine + jsonrpc-net + JSONL
+# persistence + user-interaction" line below and daemon-demo/src/index.ts).
+# Loading it again at the top level would double-mount the service and
+# fail loud on daemon start. The stdio profile (echo-jsonrpc.yml) does
+# load it, because that profile has no bundle to piggyback on.
+
+# The daemon app bundle: spine + jsonrpc-net + JSONL persistence + user-interaction.
+- id: daemon-agent
+  name: '@deepseek-ai/dsh-daemon-demo'
+  config:
+    socketPath: !!js process.env.DSH_DAEMON_SOCKET_PATH
+    lockfilePath: !!js process.env.DSH_DAEMON_LOCKFILE_PATH
+    persona: 'You are a mock daemon agent.'
+    persistenceRoot: !!js process.env.DSH_DAEMON_SESSIONS_ROOT ?? './.sessions'

examples/desktop/config/daemon-vibe.yml

@@ -0,0 +1,59 @@
+# Vibe leaf: the daemon-echo agent bundle + the self-referential cordis
+# toolset, so a chat inside the shell can inspect + mount plugins into the
+# live runtime. Loaded through the same daemon-demo bin as `daemon-echo.yml`;
+# the sole difference is the extra `tool-cordis` entry at the end.
+#
+# This leaf expects a real model (`mock-echo` cannot compose plugins), so the
+# UI hides the entry point in the mock profile. The real-model shape lives at
+# `examples/cordis-agent/cordis.yml` in the DSH runtime checkout — this
+# leaf's overlays swap in the DeepSeek adapter when the shell is running
+# under the deepseek profile.
+#
+# See packages/cordis/tool-cordis/README.md for the tool trust stance:
+# `cordis_mount` evaluates model-written JS in a node:vm sandbox — grant it
+# like bash access.
+
+- id: mock-llm
+  name: '../../echo-agent/src/mock-llm.ts'
+
+- id: echo-tool
+  name: '../../echo-agent/src/echo-tool.ts'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+# ctx.fs / ctx.web providers so plugins the model writes have real capabilities
+# to build on. Model-facing read/write/edit + search/fetch tools stay off on
+# purpose — the point is the agent *authors* its own tools rather than picking
+# from a prepacked shelf.
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: web
+  name: '@deepseek-ai/dsh-web'
+
+- id: web-fetch-local
+  name: '@deepseek-ai/dsh-web-fetch-local'
+
+- id: session-query
+  name: '@deepseek-ai/dsh-session-query'
+
+- id: daemon-agent
+  name: '@deepseek-ai/dsh-daemon-demo'
+  config:
+    socketPath: !!js process.env.DSH_DAEMON_SOCKET_PATH
+    lockfilePath: !!js process.env.DSH_DAEMON_LOCKFILE_PATH
+    persistenceRoot: !!js process.env.DSH_DAEMON_SESSIONS_ROOT ?? './.sessions'
+    persona: |
+      You are the DSH vibe agent: you author cordis plugins to extend your own
+      runtime. Use cordis_inspect to look around (its `api` and `events`
+      sections are your reference), cordis_mount to add plugins, and
+      cordis_unmount to clean up. In mounted code, never use Node built-ins
+      (require/setTimeout/fetch) — use the cordis services via inject: fs,
+      web, bash, timer (ctx.setTimeout). Prefer small single-purpose plugins.
+
+# Loaded last so ctx.tools exists — the cordis toolset registers into it.
+- id: tool-cordis
+  name: '@deepseek-ai/dsh-tool-cordis'

examples/desktop/config/deepseek-jsonrpc.yml

@@ -0,0 +1,93 @@
+# JSON-RPC serving config with the real DeepSeek adapter. Needs
+# DEEPSEEK_API_KEY in the environment (the desktop shell inherits it from the
+# user's shell; or set it in `.env` at the DSH runtime root, which
+# dsh-app-boot loads via loadEnv).
+#
+# Composition contract: the desktop shell announces
+# capabilities.interruptions=true on initialize, so the JSON-RPC server needs
+# @deepseek-ai/dsh-user-interaction to mount the interrupt bridge or
+# initialize fails loud. session/list + session/events also require
+# @deepseek-ai/dsh-session-query. Both are loaded below — omitting either
+# leaves the shell showing runtime status "starting" indefinitely while
+# stderr surfaces the failed handshake.
+
+- id: jsonrpc
+  name: '@deepseek-ai/dsh-jsonrpc'
+
+# agent-spine-demo requires an explicit `workspaceContext` (Config | false)
+# because the loader changes model-visible input; there is no schema default.
+# `false` = hermetic prompts (no workspace overview injected). Aligns with
+# packages/examples/agent-spine-demo/src/index.ts Config schema. When we want
+# a workspace overview later, swap for `{ maxBytes: 65536 }` matching the
+# byte-budget pattern in examples/cordis-agent/cordis.yml.
+- id: agent-core
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    workspaceContext: false
+
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-flash
+      - deepseek-v4-pro
+    # Showcase default: pin thinking on so the reasoning fold — our headline
+    # visualization — is visible out of the box for a first-run user. The
+    # provider default is already "enabled", but a future flip would silently
+    # drop reasoning-delta events on this profile and take the fold with it.
+    # See packages/llm/llm-deepseek/src/index.ts Config for the field shape.
+    thinking: enabled
+
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+
+# Host-facing session metadata: session/list and session/events require the
+# session-query service and fail loud without it. The desktop shell polls
+# session/list on every runtime handshake and reads session/events on
+# switch-back.
+- id: session-query
+  name: '@deepseek-ai/dsh-session-query'
+
+# User-interaction seam: required when the JSON-RPC client announces
+# capabilities.interruptions=true (the desktop shell does). Without this the
+# interrupt bridge cannot mount and initialize itself fails loud with
+# "jsonrpc client announced capabilities.interruptions=true but the composition
+# has no ctx.userInteraction …".
+- id: user-interaction
+  name: '@deepseek-ai/dsh-user-interaction'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+# Showcase default: ship the model-facing filesystem tool suite so file edits
+# render the diff card — the second headline visualization after the reasoning
+# fold. This is a three-part stack (matching examples/coding-agent/cordis.yml
+# — the canonical composition):
+#
+#   1. fs-local provides the backend that resolves paths from process.cwd()
+#      (schema in packages/fs/fs-local/src/index.ts).
+#   2. fs-policy enforces the read-before-write / observation contract that
+#      tool-fs's edit/write listeners rely on.
+#   3. tool-fs registers the fs.read / fs.edit / fs.write model-facing tools
+#      (its `inject` is ['tools', 'fs', 'systemPrompt']). Without this, no fs
+#      tool is exposed to the model at all — an fs.edit request would just
+#      make the model reply "no fs tool available", which is exactly what
+#      the previous default-profile behaviour did.
+#
+# Diff cards render only for tools with data-tool-card-family=fs (see
+# src/renderer/tool-cards.js), so this stack is the sole path to the
+# out-of-the-box diff-card demo.
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: fs-policy
+  name: '@deepseek-ai/dsh-fs-policy'
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'

examples/desktop/config/deepseek-vibe.yml

@@ -0,0 +1,57 @@
+# Vibe leaf, DeepSeek variant: same shape as daemon-vibe.yml but with the
+# real DeepSeek adapter swapped in. Loaded through the jsonrpc-demo bin on
+# stdio (the daemon-demo path is fine too, but the deepseek profile only
+# needs one long-lived process for the shell's demo scope).
+#
+# Needs `DEEPSEEK_API_KEY` in `.env` at the DSH runtime root. See
+# `examples/cordis-agent/cordis.yml` in the DSH runtime checkout for the
+# canonical self-referential composition; this is a JSON-RPC-serving mirror
+# of it.
+
+- id: jsonrpc
+  name: '@deepseek-ai/dsh-jsonrpc'
+
+# agent-spine-demo requires an explicit `workspaceContext` (Config | false).
+# Vibe leaf mirrors examples/cordis-agent/cordis.yml which uses a 65536-byte
+# budget so the model gets a workspace overview; the plain deepseek-jsonrpc
+# leaf keeps `false` for hermetic prompts. See
+# `packages/examples/agent-spine-demo/src/index.ts` in the DSH runtime
+# checkout for the Config schema.
+- id: agent-core
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    workspaceContext:
+      maxBytes: 65536
+
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-pro
+      - deepseek-v4-flash
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    timeoutMs: 60000
+
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: web
+  name: '@deepseek-ai/dsh-web'
+
+- id: web-fetch-local
+  name: '@deepseek-ai/dsh-web-fetch-local'
+
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+
+- id: tool-cordis
+  name: '@deepseek-ai/dsh-tool-cordis'

examples/desktop/config/echo-jsonrpc.yml

@@ -0,0 +1,52 @@
+# JSON-RPC serving config for the desktop demo — keyless echo profile.
+#
+# The runtime bin (packages/examples/jsonrpc-demo) hosts these plugins:
+# `dsh-jsonrpc` serves newline-delimited JSON-RPC on stdio, the spine gives
+# the agent shape, and the leaf plugins supply a mock adapter + echo tool so
+# there's no network dependency. Matches the shape in
+# python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml but with
+# the mock-echo adapter swapped in.
+
+# Stdio JSON-RPC serving surface — the demo's whole reason to exist.
+- id: jsonrpc
+  name: '@deepseek-ai/dsh-jsonrpc'
+
+# Agent spine — the SDK server creates agents per sessionId.
+# agent-spine-demo requires an explicit workspaceContext (Config | false)
+# because it changes model-visible input; there is no schema default.
+# `false` = hermetic prompts (no workspace overview injected), which is the
+# right shape for the keyless mock path — the mock adapter ignores any
+# workspace context anyway.
+- id: agent-core
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    workspaceContext: false
+
+# Mock adapter from the echo-agent leaf. Path is relative to this file.
+- id: mock-llm
+  name: '../../echo-agent/src/mock-llm.ts'
+
+# Echo tool so the UI has something to render as a tool call.
+- id: echo-tool
+  name: '../../echo-agent/src/echo-tool.ts'
+
+# Bash executor sits behind agent-core's bash tool schema — required by the spine.
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+# User-interaction seam: required whenever the JSON-RPC client announces
+# capabilities.interruptions=true (the desktop shell always does; see
+# main.js:handshake). Without this the daemon logs
+# "jsonrpc client announced capabilities.interruptions=true but the composition
+# has no ctx.userInteraction" and the shell's runtime-error banner fires on
+# the empty state — hiding the four differentiator cards behind an error
+# strip. Kept in the echo profile too so all default profiles bind the same
+# interaction surface (product-flow-review A-P0-2 root cause, 2026-07-16).
+- id: user-interaction
+  name: '@deepseek-ai/dsh-user-interaction'
+
+# JSONL persistence — sessions land under ./.sessions inside this dir.
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'

examples/desktop/config/plugin-index.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://dsh.dev/schemas/plugin-index-v1.json",
+  "version": 1,
+  "notes": "Curated demo index for the Plugins → Browse tab. Each entry maps 1:1 to a real workspace package under packages/. The `source: local` marker is a placeholder for a future remote index served by plugin.engineer; the renderer already reads `source` so switching to a URL is a config-only change.",
+  "source": "local",
+  "updatedAt": "2026-07-16",
+  "entries": [
+    {
+      "id": "tool-web",
+      "package": "@deepseek-ai/dsh-tool-web",
+      "title": "Web tools",
+      "description": "Model-facing web_search and web_fetch tools over the web capability seam. Ships the search + fetch provider skeleton; wire it to an HTTP backend or use the built-in mock.",
+      "author": "DeepSeek",
+      "permissions": ["net"],
+      "tags": ["research", "browsing"],
+      "entry": { "id": "tool-web", "name": "@deepseek-ai/dsh-tool-web" }
+    },
+    {
+      "id": "tool-fs",
+      "package": "@deepseek-ai/dsh-tool-fs",
+      "title": "Filesystem tools",
+      "description": "Read, write, and edit files through ctx.fs. The bread-and-butter toolset for any coding agent — pair it with tool-bash for a full workbench.",
+      "author": "DeepSeek",
+      "permissions": ["fs"],
+      "tags": ["coding", "essentials"],
+      "entry": { "id": "tool-fs", "name": "@deepseek-ai/dsh-tool-fs" }
+    },
+    {
+      "id": "tool-todo",
+      "package": "@deepseek-ai/dsh-tool-todo",
+      "title": "Todo writer",
+      "description": "Session-owned todo list backed by the event-sourced log. Lets the agent plan a multi-step task and check items off as it goes.",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["planning"],
+      "entry": { "id": "tool-todo", "name": "@deepseek-ai/dsh-tool-todo" }
+    },
+    {
+      "id": "tool-skill",
+      "package": "@deepseek-ai/dsh-tool-skill",
+      "title": "Skill loader",
+      "description": "Model-facing tool that discovers and loads named skills from the skill provider registry. Pair with skill-local to serve skills from disk.",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["skills"],
+      "entry": { "id": "tool-skill", "name": "@deepseek-ai/dsh-tool-skill" }
+    },
+    {
+      "id": "skill-local",
+      "package": "@deepseek-ai/dsh-skill-local",
+      "title": "Local skill provider",
+      "description": "Serves skills from a local filesystem directory to the skill registry. Install alongside tool-skill for a working local skills workflow.",
+      "author": "DeepSeek",
+      "permissions": ["fs"],
+      "tags": ["skills"],
+      "entry": { "id": "skill-local", "name": "@deepseek-ai/dsh-skill-local" }
+    },
+    {
+      "id": "tool-subagent",
+      "package": "@deepseek-ai/dsh-tool-subagent",
+      "title": "Subagent delegation",
+      "description": "Delegate work to a child agent via the ctx.subagents seam. Register one or more subagent providers separately (spawn, subprocess, in-process, ACP, or fork).",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["multi-agent"],
+      "entry": { "id": "tool-subagent", "name": "@deepseek-ai/dsh-tool-subagent" }
+    },
+    {
+      "id": "time-context",
+      "package": "@deepseek-ai/dsh-time-context",
+      "title": "Time context",
+      "description": "Opt-in system-prompt context: the current wall-clock time and the elapsed time since the previous message. Bounded and cheap; nothing model-visible beyond a small prelude.",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["context"],
+      "entry": { "id": "time-context", "name": "@deepseek-ai/dsh-time-context" }
+    },
+    {
+      "id": "timeout-policy",
+      "package": "@deepseek-ai/dsh-timeout-policy",
+      "title": "Tool timeout policy",
+      "description": "Arms a per-tool deadline on tools/execute; returns TOOL_TIMEOUT if the tool call outruns it. Belt-and-braces protection for a shell tool that hangs.",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["reliability"],
+      "entry": { "id": "timeout-policy", "name": "@deepseek-ai/dsh-timeout-policy" }
+    },
+    {
+      "id": "repeat-tool-guard",
+      "package": "@deepseek-ai/dsh-repeat-tool-guard",
+      "title": "Repeat-tool guard",
+      "description": "Advisory reminders when the agent loops on identical tool calls. Nudges the model to change course rather than short-circuiting the loop.",
+      "author": "DeepSeek",
+      "permissions": [],
+      "tags": ["loop-hygiene"],
+      "entry": { "id": "repeat-tool-guard", "name": "@deepseek-ai/dsh-repeat-tool-guard" }
+    },
+    {
+      "id": "mcp-client",
+      "package": "@deepseek-ai/dsh-mcp-client",
+      "title": "MCP client bridge",
+      "description": "Connects to Model Context Protocol servers and registers their tools on ctx.tools. Add MCP server configs after installing.",
+      "author": "DeepSeek",
+      "permissions": ["net", "subprocess"],
+      "tags": ["integration", "mcp"],
+      "entry": { "id": "mcp-client", "name": "@deepseek-ai/dsh-mcp-client" }
+    }
+  ]
+}