This appendix enumerates every workspace package found in the checkout and gives each a one-line role. Use it as a companion to the architecture overview and the glossary.
The big picture
- 245
package.jsonfiles total:- 219 workspace packages under
packages/<group>/<pkg>/(a further 7 test-fixture manifests underpackages/typert/generator/tests/fixtures/bring thepackages/tree to 226), spread across 49 functional groups (core,session,client,subagent, … — everypackages/<group>directory). - 2 application entries under
apps/. - 4 native entries under
native/landlock-run/(one launcher package plus three per-platform binary sub-packages). - 9 vendored framework packages under
vendor/. - 4 entries under
examples/(one umbrella manifest plus three runnable demo apps).
- 219 workspace packages under
- Naming convention: host packages are
@deepseek-ai/dsh-<name>(e.g.@deepseek-ai/dsh-agent,@deepseek-ai/dsh-session). Packages express a capability seam (an abstract service + itsctx.<key>vocabulary) or a provider/consumer of one; the three-role capability-seam pattern often draws them into families (dsh-fs+dsh-fs-local+dsh-fs-sandbox+dsh-tool-fs…). Vendored Cordis packages are kept under@deepseek-ai/cordis*so publishing the harness does not squat the upstream names. Client UI packages follow@deepseek-ai/dsh-client-ui-*.
Prices are read from each package's own package.json at the pinned revision.
packages/core/* — the loop, the scope, the registry
| Package | Role |
|---|---|
dsh-agent | Agent interface, live registry, initiator scope, and agent/* event vocabulary |
dsh-agent-loop | The concrete agent-loop plugin that drives turns and steps |
dsh-agent-default-model | Default model selection shared by Agent entry points |
dsh-agent-tool-presentation | Composes one agent's tools as Code Mode, native, or both |
dsh-scope | The scoped-context registration primitive (scope tags, scope-filtered dispatch) |
dsh-session | The event-sourced SessionEvent store |
dsh-system-prompt | System-prompt section and tool-schema assembly registry |
dsh-tools | The scoped tool registry and guarded execution pipeline |
packages/acp/*, packages/api/*, packages/attachment/*
| Package | Role |
|---|---|
dsh-acp | Automation-only Agent Client Protocol server over JSON-RPC stdio |
dsh-api-gateway | Typert Remote Host dispatcher and Client API endpoint |
dsh-api-remotes | Remote BFF assembly and Host Agent/Session lookup policy |
dsh-attachment | Durable immutable attachment storage seam |
dsh-attachment-local | Private content-addressed $DSH_HOME attachment storage |
packages/boot/* — the composition and launch layer
| Package | Role |
|---|---|
dsh-app-boot | Shared boot glue for app bins: .env loading, fail-loud Loader guards, profile/bundle composition, boot sequence |
dsh-cmdline | Immutable command-line handoff from a dsh launcher to plugins injecting cmdlineArgs |
packages/bundle/* — the profile bundles
| Package | Role |
|---|---|
dsh-base | The shared core as a profile bundle; every profile's first patch layer |
dsh-headless | The one-shot bundle: a direct Agent/Session runner with no Host, HTTP, or browser layer |
dsh-web-app | The browser-surface bundle: web patch layer over dsh-base plus runtime glue |
packages/client/* — the web shell and UI (39 packages)
Client packages split into the shell kernel (web, web-react, runtime, modules, connection, hmr, locale, schema-form) and the UI feature plugins (ui-*).
| Package | Role |
|---|---|
dsh-client-web | Web shell kernel: bootWebShell, module holding, two-stage boot, AppRoot gate |
dsh-client-web-react | Shell-side React glue: createSlotRenderer, SessionProvider, useInvoke, uSES bridge |
dsh-client-runtime | Client core services: SlotRegistry, SessionRuntime (scope tree + object layer) |
dsh-client-modules | Client module system: node half builds the __DSH_BOOT__ entry graph, browser half the lazy-CJS table |
dsh-client-connection | Wire consumer layer: HTTP-up/WebSocket-down client with reconnect |
dsh-client-hmr | Dev-only hot-reload driver for script-loaded client entries |
dsh-client-locale | Locale plugin: Host-backed zh/en preference and typed dictionaries |
dsh-client-schema-form | Schema/draft model layer for settings editors |
dsh-client-ui-primitives | Pure React atoms: controls, icons, markdown, JSON inspectors |
dsh-client-ui-slots | Slot-registry pure core: SlotMap merging, register composition API |
dsh-client-ui-theme | Theme plugin: palette bootstrap, ThemeRuntime, --dsw-* tokens |
dsh-client-ui-layout | Three-column AppFrame shell plugin with drag handles |
dsh-client-ui-sidebar | Sidebar plugin: session tree, search, grouping, state dots |
dsh-client-ui-conversation | Conversation domain: chat flow, composer, busy-Enter preference |
dsh-client-ui-commands | Client command surface: global directory cache, / source, command UI kinds |
dsh-client-ui-input-trigger | Input trigger pipeline: / and @ detection and candidate menus |
dsh-client-ui-model-selection | Model selection /model popupSelect |
dsh-client-ui-plan | Plan-mode composer control over the plan projection |
dsh-client-ui-goal | Session goal GoalBar docked above the composer |
dsh-client-ui-jobs | Session-header background-job list |
dsh-client-ui-subagent | Subagent conversation catalog, continuation routing, @ reference |
dsh-client-ui-tool | Tool call-tree renderer and per-tool presentation slot |
dsh-client-ui-trajectory | Trajectory event ledger with an interactive timing overview |
dsh-client-ui-attachment | Pure React attachment atoms: draft rail, galleries, lightbox |
dsh-client-ui-deliverables | Produced-files turn tail and clickable file references |
dsh-client-ui-settings | Settings domain base plugin and the settings slot contract |
dsh-client-ui-settings-general | General settings section, shell trigger/header chrome, onboarding |
dsh-client-ui-settings-plugins | Plugins settings section with feature-owned tabs |
dsh-client-ui-settings-plugin-inventory | Read-only Cordis Loader inventory tab |
dsh-client-ui-settings-models | Models settings and product-onboarding dialogs |
dsh-client-ui-skill | Web skill references and the dedicated skill tool row |
dsh-client-ui-workspace | Workspace picker plugin in the sidebar |
dsh-client-ui-directory-picker-browse | In-app directory browsing surface |
dsh-client-ui-directory-picker-native | Native (OS chooser) directory-picker surface |
dsh-client-ui-permission-presets | Permission surfaces over the permissions projection |
dsh-client-ui-user-questions | Web ask_user_question feature |
dsh-client-ui-message-feedback | Per-message feedback controls |
dsh-client-ui-agent-preset | Agent-preset surfaces: defaults, session seat, composition editor |
dsh-client-ui-workflow-run | Durable workflow-run Conversation Node and member disclosure |
packages/code-runtime/*, packages/compaction/*, packages/context/*
| Package | Role |
|---|---|
dsh-code-runtime | Abstract code-execution seam (ctx.codeRuntime) |
dsh-code-runtime-worker-thread | Worker-thread implementation of the code-execution seam |
dsh-compaction | Abstract compaction service seam (ctx.compaction) |
dsh-compaction-basic | Token-meter-driven compaction policy and LLM summarization backend |
dsh-compaction-tool-result-pruner | Model-free head/middle/tail pruning for tool-result surface nodes |
dsh-command-compact | Human-facing slash command for explicit session compaction |
dsh-agent-instructions | Workspace context loader for AGENTS.md/CLAUDE.md |
dsh-time-context | Opt-in durable per-step context with current time / elapsed time |
dsh-tmux-context | Opt-in durable per-step context with tmux pane/window location |
dsh-session-reference | Cross-session snapshot references and durable untrusted model context |
packages/credentials/*, packages/e2b/*, packages/extensions/*
| Package | Role |
|---|---|
dsh-credentials | Abstract credential seam (ctx.credentials) |
dsh-credentials-local | File-backed credentials provider ($DSH_HOME/.env) |
dsh-e2b | Shared E2B sandbox lifecycle for provider adapters |
dsh-fs-e2b | E2B filesystem implementation |
dsh-subprocess-e2b | E2B subprocess implementation |
dsh-cordis-host-runner | Dynamic package-definition registry and host-half sandbox lifecycle |
dsh-cordis-client-runner | Browser half of dual-half plugin packages |
dsh-tool-cordis | Self-referential cordis toolset: inspect runtime, mount/dispose model-written plugins |
dsh-client-ui-cordis | (listed under client) |
packages/feedback/*, packages/fs/*
| Package | Role |
|---|---|
dsh-message-feedback | Lifecycle-bound per-message rating and note sidecar |
dsh-command-feedback | Log-only session feedback producer and slash command |
dsh-fs | Abstract filesystem capability seam (ctx.fs) + fs/* event vocabulary |
dsh-fs-local | Local-filesystem implementation of the fs seam |
dsh-fs-sandbox | Sandbox-enforcing implementation: fences writes by per-call sandbox mode |
dsh-fs-observation-policy | Observed-state, read-before-edit, version-guarded write/edit policy plugin |
dsh-tool-fs | Model-facing fs tools (read, write, edit) |
dsh-tool-fs-search | Model-facing discovery tools (glob, grep) over @vscode/ripgrep |
dsh-tool-str-replace-editor | View/create/literal-replace/line-insert tool over the fs service |
packages/goal/*, packages/guard/*, packages/hooks/*
| Package | Role |
|---|---|
dsh-goal | Event-sourced same-session goal state and lifecycle service |
dsh-goal-round-driver | Race-fenced same-session goal-round driver |
dsh-tool-goal | Model-facing goal tools with execution-time authority checks |
dsh-command-goal | Human-facing /goal slash command |
dsh-tool-call-timeout-policy | Per-tool deadline on exec.signal returning TOOL_TIMEOUT |
dsh-repeat-tool-reminder | Advisory reminders when an agent loops on identical tool calls |
dsh-hook-protocol | Shared Claude Code / Codex hook wire protocol and matcher engine |
dsh-hooks-claude-code | Bridge: run a Claude Code hooks config on Harness seams |
dsh-hooks-codex | Bridge: run a Codex hooks config on Harness seams |
packages/host/* — the webserver and pickers
| Package | Role |
|---|---|
dsh-host-webserver | Web route-registration plugin: HTTP/upgrade routes, index taps, static fallback |
dsh-host-frontend-static | SPA dist server for the Web shell |
dsh-host-apiproxy | API gateway (ctx.apiProxy): fetch carrier pair + host-side plugin |
dsh-host-plugin-inventory | Read-only Remote projection of current Loader plugin state |
dsh-host-directory-picker | Abstract workspace-directory picking seam (ctx.directoryPicker) |
dsh-host-directory-picker-auto | Adaptive chooser resolving host situation at boot |
dsh-host-directory-picker-browse | In-app browsing backend of the directory-picker seam |
dsh-host-directory-picker-native | Native-OS-chooser backend of the directory-picker seam |
packages/identity/*, packages/interaction/*
| Package | Role |
|---|---|
dsh-anonymous-user-id | Shared anonymous user identity for telemetry and feedback correlation |
dsh-user-questions | Abstract user-questions seam (ctx.userQuestions) |
dsh-tool-ask-user | Model-facing ask_user_question tool |
dsh-user-approval | User-approval seam (ctx.approval): one-shot permission decisions, fail-closed |
dsh-permission-presets | Product-level Permissions select bundling sandbox-mode and approval-policy knobs |
dsh-commands | Plugin-owned human command registry |
packages/jobs/*, packages/llm/*
| Package | Role |
|---|---|
dsh-jobs | Background job registry (ctx.jobs) for long-running tool work |
dsh-jobs-local | Process-local implementation of the job registry seam |
dsh-tool-jobs | Model-facing job-control tools (job_output, job_list, job_kill) |
dsh-llm | Provider-neutral LLM service interface |
dsh-llm-retry | Provider-routed LLM request retry policy |
dsh-token-meter | Replay-aware token measurement service (ctx.tokenMeter) |
dsh-llm-deepseek | DeepSeek chat-completions adapter |
dsh-llm-pi-ai | pi-ai-backed DeepSeek adapter (design twin of dsh-llm-deepseek) |
packages/lsp/*, packages/mcp/*
| Package | Role |
|---|---|
dsh-lsp | Abstract LSP capability seam (ctx.lsp) |
dsh-lsp-stdio | Generic stdio language-server provider |
dsh-tool-lsp | Model-facing lsp tool with definition/references/implementation/hover |
dsh-mcp-client | MCP client bridge: connects to servers and registers their tools |
packages/plan/*, packages/preset/*, packages/runtime-diagnostics/*
| Package | Role |
|---|---|
dsh-plan-mode | Logged per-agent plan mode with a direct slash command |
dsh-agent-presets | Per-session agent composition from preset cordis.yml files |
dsh-persona | Composition-authored deployment persona section |
dsh-invariants | Registry service for package-owned runtime invariants |
packages/sandbox/*
| Package | Role |
|---|---|
dsh-sandbox | Abstract process-sandbox seam (ctx.sandbox) + SandboxProvider contract |
dsh-sandbox-local | Local backends: bwrap, landlock-run, macOS Seatbelt, Windows ACL — probed, fail-closed |
dsh-sandbox-policy | Per-call sandbox-mode resolver and current model context |
dsh-sandbox-windows-acl | Windows ACL write-restriction backend (restricted-token spawn) |
packages/schedule/*, packages/sdk/*
| Package | Role |
|---|---|
dsh-schedule | Agent-scoped durable after/at/fixed-rate reminders |
dsh-sdk-protocol | Shared wire protocol: newline-delimited JSON-RPC stdio transport and named types |
dsh-sdk-jsonrpc-server | Stdio JSON-RPC server plugin for out-of-process SDK clients |
dsh-sdk-client | TypeScript client SDK driving a runtime subprocess via the high-level turns API |
packages/session/* — the event log and its projections
| Package | Role |
|---|---|
dsh-session-persistence | Abstract durable session persistence seam (ctx.sessionPersistence) |
dsh-session-persistence-jsonl | JSONL durable session persistence backend |
dsh-session-persistence-sqlite | SQLite durable session persistence backend |
dsh-session-projection | Session-projection seam: type table, provider contract, ctx.sessionProjections |
dsh-session-projection-cache | Durable per-session projection checkpoints with cold-read ladder |
dsh-session-checkpoint-policy | Semantic durability checkpoints before model requests and tool side effects |
dsh-session-stats | Whole-log conversation counts and wall times projection |
dsh-session-title | Log-backed session-title service and provider registry |
dsh-session-title-llm | Shared LLM generation policy for title providers |
dsh-session-title-first-prompt-llm | First-message LLM title provider plugin |
dsh-session-title-all-prompts-llm | All-user-messages LLM title provider plugin |
dsh-session-telemetry | SessionTelemetryBackend seam: capture, projection, redaction, handoff |
dsh-session-telemetry-otel | OpenTelemetry backend for the telemetry seam |
packages/session-query/*
| Package | Role |
|---|---|
dsh-session-query | Combined session-query service contract with reads, traces, filters |
dsh-session-query-sqlite | Concrete backend with SQLite FTS5 search |
dsh-tool-session-query | Workspace-authorized model-facing history search/trace/read tools |
dsh-session-log-export | Web Session-log export command and download dialog |
packages/settings/*, packages/shell/*
| Package | Role |
|---|---|
dsh-settings | Abstract user-settings seam (ctx.settings) |
dsh-settings-file | File-backed settings provider (settings.yaml) |
dsh-shell | Abstract bash executor seam (ctx.shell) |
dsh-shell-env | Tool-independent managed DSH_* shell environment registry |
dsh-bash-local | Local-subprocess bash executor provider |
dsh-bash-sandbox | Sandbox-consuming bash executor provider |
dsh-pwsh-local | Local PowerShell bash-executor provider |
dsh-pwsh-sandbox | Sandbox-consuming PowerShell executor provider |
dsh-tool-bash | Model-facing bash tool with background-job and sandbox-escalation support |
dsh-tool-bash-persistent | Owner-scoped persistent Bash tool over the PTY service |
dsh-tool-pwsh | Model-facing pwsh tool over the executor seam |
packages/skill/*, packages/spill/*
| Package | Role |
|---|---|
dsh-skill | Agent skill provider registry |
dsh-skill-filesystem | Local filesystem skill provider |
dsh-skill-badge | Bundled dsh badge skill provider |
dsh-tool-skill | Model-facing skill loading tool |
dsh-spill | Abstract spill storage seam (ctx.spillStore) |
dsh-spill-local | Local-filesystem spill storage (private session-scoped files) |
dsh-spill-policy | Replaces oversized tool results with a retained preview + spill-file path |
packages/storage/*
| Package | Role |
|---|---|
dsh-storage | Storage hub (ctx.storage): named backend registry + mounted data-form facilities |
dsh-storage-domain | Domain data form: schema-validated, event-emitting KV domains |
dsh-storage-json | JSON-file KV storage backend |
dsh-storage-sqlite | SQLite storage backend (kv facet) |
packages/subagent/* — delegation
| Package | Role |
|---|---|
dsh-subagent | Abstract subagent seam (ctx.subagents): named-provider registry |
dsh-subagent-in-process-driver | Shared in-process run driver on ctx.agents |
dsh-subagent-spawn-in-process | In-process spawn backend: fresh child agent |
dsh-subagent-fork-in-process | In-process fork backend: child seeded with a parent-log prefix |
dsh-subagent-dsh-sdk | Out-of-process SDK backend: child runtime over stdio JSON-RPC |
dsh-subagent-acp | Out-of-process ACP backend: child agent in a spawned subprocess |
dsh-subagent-claude-code | One-shot Claude Code provider over the Agent SDK |
dsh-subagent-codex | One-shot Codex provider over the app-server protocol |
dsh-tool-subagent | Model-facing delegation tool over ctx.subagents |
dsh-tool-subagent-control | Globally named send_message, interrupt_agent, list_agents |
dsh-tool-subagent-report | Child-scoped report tool |
packages/subprocess/*, packages/terminal/*, packages/todo/*
| Package | Role |
|---|---|
dsh-subprocess | Subprocess seam (ctx.subprocess): managed groups, bounded output, escalated kills |
dsh-subprocess-local | Local-subprocess implementation |
dsh-terminal | Persistent PTY session seam (ctx.terminals) |
dsh-terminal-bash | Persistent shell PTY backend |
dsh-tool-terminal | Six model-facing persistent PTY tools with owner isolation |
dsh-tool-todo | Model-facing todo_write tool over the session log |
packages/test-support/*
| Package | Role |
|---|---|
dsh-loader-smoke | Shared subprocess + direct-agent harness for keyless Loader smoke tests |
dsh-agent-loop-testkit | Prerequisite mounting for agent-loop tests |
dsh-llm-replay | Replay LLM plugin for keyless snapshot tests |
dsh-llm-mock-server | Scriptable OpenAI-compatible HTTP/SSE fault server |
dsh-client-test-runtime | jsdom slot test runtime with real Cordis context and doubles |
dsh-acp-snapshot | ACP test kit: subprocess launcher, snapshot harness, normalizers |
packages/typert/*
| Package | Role |
|---|---|
dsh-typert-protocol | Compiler-independent Remote metadata and Typert provider protocols |
dsh-typert-generator | TypeScript analyzer and model-driven Typert artifact generator |
dsh-typert-registry | Runtime registry for generated reflection and Zod schemas |
dsh-typert-loader | Loader integration for generated Typert contributions |
packages/util/*
| Package | Role |
|---|---|
dsh-atomic-write | Zero-dependency atomic file replacement (writeFileAtomic) |
dsh-brand | Type-only Branded<B> nominal-typing primitive |
dsh-home-paths | Shared filesystem path helpers (incl. resolveDshHome) |
dsh-launch-environment | Immutable launch environment recording each value's layer |
dsh-native-command | Zero-dependency no-shell execFile runner for OS integrations |
dsh-output-retention | Bounded-retention primitive (ItemRetainer/TextRetainer) |
dsh-timeout | Timeout/deadline primitive and TimeReason taxonomy |
packages/web/*, packages/workflow/*, packages/workspace/*
| Package | Role |
|---|---|
dsh-web | Abstract web-access seam (ctx.web): search/fetch provider registry |
dsh-web-fetch-http | Anonymous public HTTP(S) fetch provider |
dsh-web-search-deepseek | DeepSeek-backed search provider (Anthropic-compatible API) |
dsh-web-search-exa | Exa-backed search provider |
dsh-web-search-perplexity | Perplexity-backed search provider |
dsh-tool-web | Model-facing web_search / web_fetch tools |
dsh-workflow | Workflow capability seam (ctx.workflowEngine) + workflow/* events |
dsh-workflow-worker-thread | Worker-thread workflow engine bridging agent() to ctx.subagents |
dsh-tool-workflow | Model-facing workflow tool |
dsh-tool-ralph | Model-facing fresh-agent Ralph loop tool |
dsh-workspace | Workspace entity registry (ctx.workspaceRegistry) over the domain data form |
packages/examples/* — in-tree demo apps
| Package | Role |
|---|---|
dsh-acp-demo | ACP automation server app: agent spine + JSONL persistence + ACP transport |
dsh-agent-spine-demo | The default executor-less/UI-less agent spine with fallback titles |
dsh-sdk-jsonrpc-demo | Bin booting an external Cordis config for the stdio JSON-RPC SDK runtime |
dsh-client-ui-cordislives inpackages/extensions/ui-cordis; it is cross-referenced under bothclientandextensionsfor discoverability.
apps/*
| Package | Role |
|---|---|
dsh (CLI) | The dsh CLI: profile boot, plugin management, and the browser UI alias |
dsh-web-frontend | Web application entry: Vite build over the dsh-client-web shell; dist/ served by dsh web |
native/landlock-run/* — the Landlock launcher family
native/landlock-run resolves to four packages that together ship a Linux Landlock self-restrict-then-exec launcher used by the local sandbox backend:
| Package | Role |
|---|---|
@deepseek-ai/node-addon-landlock-run-workspace | Monorepo workspace container for the launcher packages (no runtime role of its own) |
@deepseek-ai/node-addon-landlock-run | The JS seam that resolves, probes, and speaks the launcher CLI contract |
@deepseek-ai/node-addon-landlock-run-linux-x64 | Prebuilt static-musl launcher binary for linux-x64 (resolved as a file path) |
@deepseek-ai/node-addon-landlock-run-linux-arm64 | Prebuilt static-musl launcher binary for linux-arm64 (resolved as a file path) |
vendor/* — the vendored Cordis framework family
The Cordis framework and its foundation libraries are vendored under vendor/ and published under the @deepseek-ai scope so the harness does not squat upstream names. See the official-docs map entry for docs/rescope.md.
| Package | Role |
|---|---|
@deepseek-ai/cordis | The plugin meta-framework under dsh: services, typed events, reversible effects |
@deepseek-ai/cosmokit | Collection of common utilities for the framework |
@deepseek-ai/cordis-plugin-group | Nested plugin group for cordis |
@deepseek-ai/cordis-plugin-hmr | Hot Module Replacement plugin for cordis |
@deepseek-ai/cordis-plugin-include | Include files in cordis configurations |
@deepseek-ai/cordis-plugin-loader | Plugin loader for cordis |
@deepseek-ai/cordis-plugin-logger-console | Console logger exporter for cordis |
@deepseek-ai/schemastery | Type-driven schema validator used for plugin config schemas |
@deepseek-ai/cordis-plugin-timer | Timer service for cordis |
examples/* — runnable demos (not workspace-tracked versions)
Three standalone demo apps live at examples/, each with its own package.json. Three more demo folders — examples/mcp-memory, examples/web-cordis, examples/web-schedule — are config-only folders without a package.json of their own; the dsh-examples umbrella manifest at examples/package.json declares their cordis.yml plugins as workspace:* deps.
| Package | Role |
|---|---|
acp-agent-example | Runnable demo: an ACP automation server over JSON-RPC stdio |
jsonrpc-agent-example | Unattended JSON-RPC coding-agent composition |
headless-agent-example | One complete headless coding-agent turn |
Further reading
- Glossary — capability seams, agent scope, and goal terms used throughout this index.
- Map of official docs — where each subsystem and catalog lives upstream.
docs/architecture.md— profiles, bundles, core packages, and event flow (repo-relative).packages/boot/app-boot/README.md— the profile/bundle/patch composition machinery behinddsh-base.