Runtime & orchestration
The core subsystem is packages/core — the packages every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent types, and the concrete loop that drives them. This page explains what the agent/agent-loop pair declares — how an agent is created and owned, and the Agent handle’s delivery, cancellation, and interception contracts — plus the two type patterns every subsystem follows. The group’s dedicated pages and the rest of the folder are indexed in the subsystems README.
The scope package supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the agent-scope runtime-design Agent Note owns the lifecycle rationale, the shared-storage Agent Note owns the registry-layer decision, and the package README owns the callable API and filtering semantics.
Sources: packages/core/scope/src/index.ts and packages/core/scope/src/store.ts.
dsh-invariants is the configurable registry service (ctx.invariants) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a ./invariant companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in AGENTS.md; the registry design is owned by the invariant-service Agent Note.
Source: packages/runtime-diagnostics/invariants/src/index.ts
The in-memory, event-sourced model of dsh-session. A Session is an append-only log of typed SessionEvents — the single source of truth for an agent’s whole interaction history. The LLM message history is derived from the log, never stored separately; replay is re-derivation from the same events. How the log is made durable (the persistence seam, backends, crash recovery) is the sibling concern on persistence.md.
Source: packages/core/session/src/types.ts
Query vocabulary over the live-preferred logical session corpus. The Service Definition package owns exact reads, source precedence, relationship tracing, semantic extraction, and provider-independent filters, while the SQLite provider owns the concrete full-text index lifecycle.
Source: packages/session-query/session-query/src/types.ts
Structured cross-session reference requests and prepared message contexts. The package contract defines canonical URIs, current-surface projection, tag-safe JSON and byte retention, stable errors, and the untrusted model prompt. Host adapters use these types instead of passing their UI mention syntax into the agent core.
Source: packages/context/session-reference/src/types.ts
Durable latest-wins title state and the optional asynchronous provider vocabulary owned by @deepseek-ai/dsh-session-title. The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated persistence catalog owns the complete event declarations.
Sources: packages/session/session-title/src/index.ts, packages/session/session-title-llm/src/index.ts
The session-projection seam — a capability seam through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry (dsh-session-projection, ctx.sessionProjections), domain contributors (each registering one pure unit), and carriers (dsh-host-apiproxy’s history tail page and session/projection push frame). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to session/event once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the session-projection RFC; drive/cache/feed contracts: the package README.
Source: packages/session/session-projection/src/index.ts
The durability seam for the event log. session.md describes the in-memory Session — the append-only SessionEvent log that is the source of truth. This page describes how that log is made durable: the abstract SessionPersistence service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated persistence log event catalog.
The seam is a capability seam: one abstract service (dsh-session-persistence, ctx.sessionPersistence) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing SessionEvent — no parallel persisted event type — and two interchangeable backends implementing the same contract. See the session-persistence Agent Note.
The spill storage seam — a capability seam that persists a tool’s oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition (dsh-spill, ctx.spillStore), Service Provider (dsh-spill-local, private session-scoped files on the host filesystem), and Consumer (dsh-spill-policy, the tools/post-execute policy). Spill is one optional capability, not part of the agent-loop spine — so its vocabulary lives here, not in core.md. Preview mechanics stay in dsh-output-retention; this seam only saves the final text the policy hands it.
Source: packages/spill/spill/src/types.ts
Outbound session reporting is split as a capability seam: the Service Definition and capture coordinator (dsh-session-telemetry, ctx.sessionTelemetry) own the capture points, fixed chunk projection, session-telemetry/record redaction waterfall, handoff cursor, and minimal backend contract; the Service Provider a deployment loads (dsh-session-telemetry-otel) is the OpenTelemetry JS SDK’s log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness’s aspect ends at emit(); batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the revival Agent Note; the capture points, cursor, and projection contracts live in the Service Definition README.
Source: packages/session/session-telemetry/src/index.ts
The conversation and streaming types from packages/llm: the Message/ContentBlock variants every request and durable history share, the fully assembled model request, the raw StreamChunk protocol, the adapter contract every adapter must implement, and the shared assembler. The core packages hold and log these values on every turn; this page declares them.
Source: packages/llm/llm/src/types.ts
@deepseek-ai/dsh-token-meter exposes one detached replay snapshot for request pressure and positional surface pricing. logRevision is the number of durable events consumed for every field in the measurement.
Source: packages/llm/token-meter/src/types.ts
The system-prompt package owns the data exchanged between prompt contributors and one assembly call. The package README documents registration, ordering, scoping, and rendering behavior; this page records the exact cross-package types that plugins implement or pass.
Source: packages/core/system-prompt/src/index.ts.
The compaction seam — a capability seam split like bash: Service Definition (dsh-compaction, ctx.compaction), Service Provider (a backend such as dsh-compaction-basic), and human Consumer (dsh-command-compact). Compaction is one optional capability, not part of the agent-loop spine — so its vocabulary lives here, not in core.md. A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on dsh-session and dsh-llm: its verbs act on an agent-owned Session, and its durable summary event uses the ContentBlock vocabulary (see the compaction capability-seam Agent Note).
Source: packages/compaction/compaction/src/types.ts
The tool pipeline of dsh-tools. core.md introduces ToolDefinition as the pipeline-authoring type shared by the core packages; the model-facing ToolSchema wire type is declared with the model request. This page documents every ToolDefinition field, the typed schema DSL that builds it, the guarded execution types, and the UI-presentation types.
Source: packages/core/tools/src/index.ts · packages/core/tools/src/schema.ts · packages/core/tools/src/presentation.ts
The bash execution seam is split across a Service Definition (dsh-shell, ctx.shell), Service Providers (dsh-bash-local and dsh-bash-sandbox), and Consumer (dsh-tool-bash, the bash schema). Generic background-job ids, ownership, and controls live in jobs.md; this seam returns a task-free process handle. Raw process-group mechanics live behind the subprocess seam.
Source: packages/shell/shell/src/types.ts
The subprocess seam is split across a Service Definition (dsh-subprocess, ctx.subprocess) and Service Provider (dsh-subprocess-local); its Consumers are other capability seams and out-of-process backends: the bash executor family uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed DSH_* environment namespace, the shared credential scrub (scrubbedParentEnv), and the CollectedOutput shape; dsh-shell re-exports the vocabulary so bash consumers keep one import root.
Source: packages/subprocess/subprocess/src/types.ts and packages/subprocess/subprocess/src/index.ts
Types shared by PTY backends, ctx.terminals, and the model-facing consumer. The persistent PTY Agent Note owns the rationale; this page records the cross-package vocabulary from packages/terminal/terminal/src/types.ts.
Types shared by long-running producers, ctx.jobs, and job controls. The runtime Agent Note owns the design; this page records the exact fields and variants from packages/jobs/jobs/src/types.ts.
The optional filesystem capability has four parts: dsh-fs owns ctx.fs and atomic text operations with optional guards, dsh-fs-local implements local disk, dsh-fs-observation-policy records observed presence or absence and adds freshness rules through events rather than a service, and dsh-tool-fs directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
dsh-fs-observation-policy is optional. Without it, the FileSystem Service Definition, a provider, and the dsh-tool-fs Consumer form the complete, unconstrained filesystem seam: write unconditionally creates or overwrites, and edit unconditionally replaces literal text. The policy plugin changes these operations by deciding the fs/* waterfalls. Removing it does not break the tool because the tool calls ctx.fs and dispatches events; it does not call policy methods. A deployment that loads dsh-tool-fs is expected to also load dsh-fs-observation-policy so the default behavior is read-before-write/edit.
Provider source: packages/fs/fs/src/types.ts and packages/fs/fs/src/index.ts. Policy source: packages/fs/fs-observation-policy/src/types.ts. Read-rendering source: packages/fs/tool-fs/src/read-render.ts.
The LSP seam — a capability seam exposing semantic code navigation on one ctx.lsp service, split across packages: Service Definition (dsh-lsp, ctx.lsp + the provider registry), a generic Service Provider (dsh-lsp-stdio, a configured stdio language-server host), and Consumer (dsh-tool-lsp, the lsp tool schema). LSP is one optional capability, not part of the agent-loop spine — so its vocabulary lives here, not in core.md. A provider swap does not change how the model asks for navigation.
Source: packages/lsp/lsp/src/types.ts
The code-execution seam — a capability seam whose Service Definition (dsh-code-runtime, ctx.codeRuntime) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is one optional capability, not part of the agent-loop spine — so its vocabulary lives here, not in core.md. Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service Provider and tool-registry Consumer are specified by the Code Mode foundation and typed-return contract.
Source: packages/code-runtime/code-runtime/src/types.ts
The web access seam — a capability seam that spans two operations (search and fetch) on one ctx.web service, split across packages: Service Definition (dsh-web, ctx.web + the provider registries), Service Providers (dsh-web-search-exa, dsh-web-search-perplexity, dsh-web-search-deepseek, dsh-web-fetch-http), and Consumer (dsh-tool-web, the web_search/web_fetch tool schemas). Web is one optional capability, not part of the agent-loop spine — so its vocabulary lives here, not in core.md. A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
Source: packages/web/web/src/types.ts
The skill capability family includes the Service Definition (dsh-skill, ctx.skills), the local Service Provider (dsh-skill-filesystem), the optional packaged badge provider (dsh-skill-badge), and the Consumer (dsh-tool-skill). The registry merges provider catalogs across its host and per-scope layers; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing skill tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in core.md.
Source: packages/skill/skill/src/index.ts, packages/skill/skill-filesystem/src/index.ts, packages/skill/skill-badge/src/index.ts, and packages/skill/tool-skill/src/index.ts.
The workflow seam lets an agent run a model-written orchestration SCRIPT that starts subagents. Like subagent it is one optional capability, not part of the agent loop, so its types and operations live here rather than in core.md. Like bash, it permits ONE engine implementation per context to provide ctx.workflowEngine; there is no named-provider registry (a second engine replaces the first through plugin configuration rather than running beside it).
Service Definition: dsh-workflow (ctx.workflowEngine + the vocabulary below). The Service Provider is dsh-workflow-worker-thread (a node:worker_threads engine — one worker per run, the script’s vm context inside it); the model-facing Consumer is dsh-tool-workflow. The proposal and rationale: the dynamic-workflows Agent Note.
Sources: browser-safe vocabulary in packages/workflow/workflow/src/types.ts, Host request and live-run handles in runtime-types.ts.
The subagent seam lets an agent delegate work to a child agent. Like bash, it is one optional capability, not part of the agent loop, so its types live here rather than in core.md. It differs from the other capability seams because multiple provider implementations coexist in one context, registered by name (ctx.subagents), while bash allows only one executor. Its registry follows the LLM adapter registry, not the single-service bash executor.
Service Definition: dsh-subagent (ctx.subagents + the vocabulary below). Service Providers are sibling packages (dsh-subagent-spawn-in-process, -fork, -acp, -codex, -claude-code, -dsh-sdk); the model-facing Consumers are dsh-tool-subagent (per-provider delegation), dsh-tool-subagent-control (the optional global send_message, interrupt_agent, and list_agents controls), and dsh-tool-subagent-report (the optional child-scoped report return channel). The same ctx.subagents service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in the Codex and Claude Code Agent Note; common-seam rationale lives in the subagent Agent Note, the continuable subagents Agent Note, the report-tool Agent Note, the durable catalog Agent Note, the list-identity-projection Agent Note, and the merged-service Agent Note.
Sources: packages/subagent/subagent/src/types.ts, packages/subagent/subagent/src/index.ts, and packages/subagent/subagent/src/continuation.ts
The user-approval seam of dsh-user-approval answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the ctx.approval dispatch service, the approval/request answerer waterfall, the log-only audit pair, and the per-session ask/never policy. UI channels may provide human answerers; the ACP automation bridge provides one-shot machine decisions for its own agents. Callers such as dsh-tools and dsh-tool-bash consume the closed outcome and fail closed unless it is allowed-once.
Source: packages/interaction/user-approval/src/index.ts
The permission-preset layer of dsh-permission-presets (ctx.permissionPresets, PermissionPresetService) bundles the two independent enforcement knobs — sandbox mode (sandbox/mode) and approval policy (approval/policy) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob’s canonical setter. The package README owns composition status and limitations; the sandbox switching design owns the rationale.
Source: packages/interaction/permission-presets/src/index.ts
The process-sandbox seam of dsh-sandbox wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. dsh-sandbox-local supplies Linux bwrap/Landlock, macOS Seatbelt, and the Windows ACL restricted-token backend; dsh-bash-sandbox and dsh-pwsh-sandbox consume it. Containers, microVMs, and remote execution are sibling implementations of whole capability seams, not providers of ctx.sandbox.
Source: packages/sandbox/sandbox/src/index.ts
Plan mode is logged per-agent collaboration state owned by dsh-plan-mode (ctx.planMode, PlanModeController): while active, a deployment-owned guidance section is included in each model request. Plan mode is soft guidance. Sandbox mode and approval policy enforce restrictions independently; neither reads or writes plan state, so deployments configure them separately. The package is optional, and the agent loop does not depend on it. It contributes the plan:policy prompt section and registers the exit_plan_mode tool and /plan command. The design note owns the rationale; the package README owns the model-experience and limitation detail.
Source: packages/plan/plan-mode/src/index.ts
The user-questions seam of dsh-user-questions. It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active UserQuestionProvider; the host runtime relays requests to its connected client.
Source: packages/interaction/user-questions/src/index.ts
The human-command registry service from dsh-commands. Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The command Agent Note owns dispatch and lifecycle rationale; the package README owns composition and limitations.
Source: packages/interaction/commands/src/index.ts
Types shared by the event-sourced goal service and its policy consumers. The goal-domain Agent Note owns the persistence and activation decisions; this page records the exact fields and variants from packages/goal/goal/src/types.ts.
Schedule owns durable reminders that return to the original live Session as ordinary later conversation turns. The durable Schedule Agent Note owns the persistence and lifecycle decisions, conversational delivery owns the no-receipt boundary, the explicit time-zone boundary owns browser-local interpretation, and bounded fixed-rate Schedule owns recurrence. This page records the durable and model-facing shapes from packages/schedule/schedule/src/types.ts; the package README owns composition, tool behavior, and the exact reminder framing.
dsh-host-webserver is the browser HTTP carrier for the GUI host: a single node:http plugin providing ctx.webServer, a named-route registry, index.html transform callbacks, and one fallback handler that a plugin may claim. It is not part of the agent loop and not a capability seam; it knows no harness concepts, and another plugin registers every feature route, including the /api bridge, plugin bundles, and the HMR event stream (layering note). It serves browsers only: Electron loads the built files over file:// and sends fetch requests through an IPC bridge instead of this server.
Source: packages/host/webserver/src/index.ts
Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The Typert Gateway Agent Note owns the architecture and transport decisions; this page records the literal public contracts from dsh-typert-protocol and dsh-api-gateway.
The web plugin table: the Node half of the client module system in dsh-client-modules, provided as ctx.clientModules (ClientModuleRegistry). It scans the host Loader’s entries for packages declaring dsh.client, composes the window.__DSH_BOOT__ entry graph, serves each bundle at /plugins/<id>/client.js, and taps the index render to inject the boot manifest — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of dsh-host-webserver: the carrier described in web-server.md supplies the prefix route and index tap this service registers. The same package’s browser half (ctx.modules, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the package README, not here.
Source: packages/client/modules/src/client/manifest.ts
The storage subsystem persists everything that is not a session event log (session logs have their own seam — persistence.md). It is one optional capability, not part of the agent-loop spine, split as a capability seam: the hub and Service Definition (dsh-storage, ctx.storage), the Service Providers (dsh-storage-json, registered as json, and dsh-storage-sqlite, registered as sqlite), and the Consumer data form (dsh-storage-domain, ctx.storageDomain, also reachable as ctx.storage.domain) — the backend contract’s only Consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: domain KV storage Agent Note.
Source: packages/storage/storage/src/backend.ts · packages/storage/storage-domain/src/spec.ts · packages/storage/storage-domain/src/events.ts
A workspace is the persistent record of a directory the user works in: a stable id over a canonical path, a display title, and the ordered account of sessions that belong to it. The subsystem is one package (dsh-workspace, ctx.workspaceRegistry) — an optional host-side capability, not part of the agent-loop spine, and invisible to models (no tools, no prompt text, no session events). It stores its records through the storage domain form and validates session membership against SessionHeader.cwd, so storageDomain and sessionPersistence are mandatory startup dependencies: an unavailable persistence peer leaves the plugin pending rather than being mistaken for an empty history. Design record: domain KV storage Agent Note; bootstrap and GUI ordering: Workspace UI product-flow Agent Note.
Source: packages/workspace/workspace/src/types.ts
The user-settings seam of dsh-settings holds one user-owned document of per-namespace sections and resolves each registered namespace as schema defaults, then the registrant’s composition base, then the user section. Providers such as dsh-settings-file store the raw document and push external edits; consumer plugins register a schema and read or observe the resolved value. Composition config stays in cordis.yml — a namespace carries only the user-editable subset.
Source: packages/settings/settings/src/index.ts
The credential seam of dsh-credentials keeps secrets out of configuration: settings sections and cordis.yml entries carry references (environment-variable names), providers such as dsh-credentials-local own the values, and consumers resolve a reference once per operation — the LLM adapters resolve once per model request, so a rotated credential reaches the very next request without any restart. One seam-wide rule binds every provider: an empty stored value is absent everywhere.