2026-08-02 03:48:16 +08:00
# Subsystems
English | [中文 ](README.zh.md )
One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis surface** section carrying its service and event reference. The folder complements [architecture.md ](../architecture.md ), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
| Page | Owns |
|---|---|
2026-08-09 15:27:21 +08:00
| [core.md ](core.md ) | how `packages/core` controls the agent loop: the package-by-package loop description, agent creation and ownership (`AgentHandle` ), the `Agent` handle's delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union` , branded ids) |
| [llm-streaming.md ](llm-streaming.md ) | the `packages/llm` conversation types — `Message` /`ContentBlock` , the assembled model request, the `StreamChunk` wire protocol and adapter contract, `BlockAssembler` , and the `LlmAdapter` provider contract |
2026-08-02 03:48:16 +08:00
| [token-meter.md ](token-meter.md ) | immutable scalar and positional replay measurements with consumed-log revisions |
| [scope.md ](scope.md ) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
2026-08-09 15:34:32 +08:00
| [typert.md ](typert.md ) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API boundaries |
2026-08-02 03:48:16 +08:00
| [goal.md ](goal.md ) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
2026-08-09 15:34:32 +08:00
| [commands.md ](commands.md ) | the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views |
2026-08-02 03:48:16 +08:00
| [session.md ](session.md ) | the full `SessionEventMap` variant catalog, `TurnTrigger` /`TurnEndReason` , `deriveMessages()` , execution enclosure, and standalone events |
| [persistence.md ](persistence.md ) | the durability seam: `SessionPersistence` , JSONL + SQLite backends, `session/flush` , crash recovery, `SessionHeader` |
| [settings.md ](settings.md ) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
| [credentials.md ](credentials.md ) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo` , provider source layers |
| [session-query.md ](session-query.md ) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
2026-08-09 15:35:02 +08:00
| [session-title.md ](session-title.md ) | durable title snapshots, cited source-message seqs, and the asynchronous provider contract |
docs(subsystems): open core.md on agent creation/ownership and the Agent contract; enforce a complete folder index
core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro.
The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
2026-08-03 16:34:00 +08:00
| [session-reference.md ](session-reference.md ) | structured cross-session references: `SessionReferenceInput` /`Candidate` , prepared message contexts, the stable error taxonomy |
2026-08-02 03:48:16 +08:00
| [system-prompt.md ](system-prompt.md ) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
| [tools.md ](tools.md ) | `ToolDefinition` full fields, the schema DSL, `ToolExecution` /`ToolResult` , tool-presentation UI types, and the guarded execution pipeline |
| [user-interaction.md ](user-interaction.md ) | the UI-backed human question/answer seam: `AskUserQuestionRequest` , answer/options vocabulary, provider API, error taxonomy |
2026-08-09 15:27:21 +08:00
| [approval.md ](approval.md ) | the one-shot user-approval seam: `ApprovalRequest` , `ApprovalOutcome` , per-session policy, audit events, and answerer contracts |
2026-08-09 23:33:35 +08:00
| [attachment.md ](attachment.md ) | durable image identity and metadata, validation inputs, verified reads, and the `AttachmentStore` seam |
2026-08-02 03:48:16 +08:00
| [bash.md ](bash.md ) | the bash executor seam: `BashExecRequest` /`Spec` , `BashRunResult` , background `BashProcess` handles |
| [subprocess.md ](subprocess.md ) | the subprocess seam: fully-explicit `SubprocessSpawnSpec` , offset-based output readers, unclassified `SubprocessOutcome` , and the managed `DSH_*` environment vocabulary |
| [pty.md ](pty.md ) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
| [sandbox.md ](sandbox.md ) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv` , enforcement and fail-closed errors |
| [code-runtime.md ](code-runtime.md ) | the code-execution seam: `CodeRunRequest` /`Result` , binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
| [filesystem.md ](filesystem.md ) | the filesystem seam: `FsTarget` , read/write/edit outcomes, observed-file state, `FsErrorCode` |
| [lsp.md ](lsp.md ) | the LSP navigation seam: `LspQueryRequest` /`Result` , `LspProvider` /`Service` , four operations, `LspError` |
| [skills.md ](skills.md ) | the skill service: discovery priority, `SkillSummary` /`SkillDefinition` , session-prefix catalog, model-facing `skill` loading |
| [compaction.md ](compaction.md ) | the compaction seam: the `compact/*` session events, `CompactionResult` , the `CompactService` interface |
| [subagent.md ](subagent.md ) | the subagent seam: the named-provider registry, `SubagentStartRequest` /`Result` /`Run` , the start-time-vs-runtime capability split |
| [web.md ](web.md ) | the web access seam: `WebSearchRequest` /`Result` , `WebFetchRequest` /`Result` , `WebFetchBody` , provider availability, `WebError` |
| [spill.md ](spill.md ) | the spill storage seam: `SaveTextSpill` , `SpillOwner` /`SpillSource` , `SpillRef` , the branded `SpillLocator` |
| [workflow.md ](workflow.md ) | the workflow seam: `WorkflowStartRequest` , `WorkflowMeta` , `WorkflowRun` /`Result` , the `workflow/*` event payloads, `WorkflowError` fatality |
2026-08-09 15:27:21 +08:00
| [tasks.md ](tasks.md ) | the background-task runtime: branded `TaskId` s, the producer contract, consumer views, and `ctx.tasks` service behavior |
2026-08-02 03:48:16 +08:00
| [permission.md ](permission.md ) | the permission-preset layer: `PresetSpec` /`PresetOption` , the derived `custom` state, the log-only `permission/preset` event |
| [plan.md ](plan.md ) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig` , the `exit_plan_mode` review arc |
| [invariants.md ](invariants.md ) | the runtime-invariant registry: selection `Config` , `InvariantInstaller` /`InvariantFailure` , the empty-companion contract |
docs(subsystems): open core.md on agent creation/ownership and the Agent contract; enforce a complete folder index
core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro.
The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
2026-08-03 16:34:00 +08:00
| [http-server.md ](http-server.md ) | the HTTP carrier: `WebRouteKind` /`WebRoute` , match order, the claimable fallback seat, index taps |
2026-08-09 15:34:32 +08:00
| [storage.md ](storage.md ) | the storage subsystem: the backend contract (`StorageBackend` ), `StorageForms` , `DomainSpec` /`Domain` , `domain/changed` |
2026-08-02 03:48:16 +08:00
| [workspace.md ](workspace.md ) | the workspace registry: `Workspace` /`WorkspaceId` , registration and resolution, the session `cwd` relationship |
2026-08-10 20:39:26 +08:00
| [client-modules.md ](client-modules.md ) | the web plugin table: `dsh.client` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
2026-08-02 03:48:16 +08:00
| [session-projection.md ](session-projection.md ) | the projection seam: `SessionProjectionMap` , the pure `ProjectionDefinition` unit, `ProjectionSnapshot` 's consistent cut, the change feed |
2026-08-09 15:27:21 +08:00
| [telemetry.md ](telemetry.md ) | the outbound session-reporting capability seam: `TelemetryRecord` /`TelemetrySeverity` , the `TelemetryBackend` contract, and the `telemetry/record` redact waterfall |
2026-08-02 03:48:16 +08:00
> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
