2026-08-02 03:48:16 +08:00
# Subsystems
English | [中文 ](README.zh.md )
2026-08-11 14:04:19 +08:00
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 API** 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.
2026-08-02 03:48:16 +08:00
| 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-13 00:36:22 +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 22:54:28 +08:00
| [schedule.md ](schedule.md ) | Session-local reminder records, durable transitions, active views, and ordinary-conversation delivery |
2026-08-22 22:22:43 +08:00
| [todo.md ](todo.md ) | the todo package's whole-list item type, durable event ownership, projection, and open-turn invariant |
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-10 11:28:38 -07:00
| [feedback.md ](feedback.md ) | lifecycle-bound per-message feedback records, optimistic versions, sidecar persistence, and the Host Remote contract |
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 |
2026-08-13 00:36:22 +08:00
| [user-questions.md ](user-questions.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-13 00:36:22 +08:00
| [shell.md ](shell.md ) | the bash executor seam: `ShellExecRequest` /`Spec` , `ShellRunResult` , background `ShellProcess` handles |
2026-08-02 03:48:16 +08:00
| [subprocess.md ](subprocess.md ) | the subprocess seam: fully-explicit `SubprocessSpawnSpec` , offset-based output readers, unclassified `SubprocessOutcome` , and the managed `DSH_*` environment vocabulary |
2026-08-13 00:36:22 +08:00
| [terminal.md ](terminal.md ) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
2026-08-02 03:48:16 +08:00
| [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 |
2026-08-13 01:59:32 +08:00
| [extensions.md ](extensions.md ) | versioned dynamic Cordis Plugins and Packages, Host/Client activation, approval, runtime inspection, and lifecycle teardown |
2026-08-02 03:48:16 +08:00
| [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 |
2026-08-13 00:36:22 +08:00
| [compaction.md ](compaction.md ) | the compaction seam: the `compaction/*` session events, `CompactionResult` , the `CompactionEngine` interface |
2026-08-02 03:48:16 +08:00
| [subagent.md ](subagent.md ) | the subagent seam: the named-provider registry, `SubagentStartRequest` /`Result` /`Run` , the start-time-vs-runtime capability split |
2026-08-19 22:44:23 +08:00
| [agent-team.md ](agent-team.md ) | Agent Teams: implicit Lead identity, named continuable teammates, durable peer mailbox, and shared task DAG |
2026-08-02 03:48:16 +08:00
| [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-13 00:36:22 +08:00
| [jobs.md ](jobs.md ) | the background-job runtime: branded `JobId` s, the producer contract, consumer views, and `ctx.jobs` service behavior |
| [permission-presets.md ](permission-presets.md ) | the permission-preset layer: `PresetSpec` /`PresetOption` , the derived `custom` state, the log-only `permission/preset` event |
2026-08-02 03:48:16 +08:00
| [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 |
2026-08-13 00:36:22 +08:00
| [web-server.md ](web-server.md ) | the HTTP carrier: `WebRouteKind` /`WebRoute` , match order, the claimable fallback seat, index taps |
2026-08-22 23:44:56 +08:00
| [webhook.md ](webhook.md ) | authenticated provider deliveries, arbitrary programmatic rules, and fire-and-forget Workspace Session creation |
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-24 01:27:48 +08:00
| [web-client.md ](web-client.md ) | the browser architecture: boot, Remote communication, paired Client models, UI adapters, Conversation assembly, Slots, and reconnect semantics |
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-24 01:27:48 +08:00
| [slots.md ](slots.md ) | typed Web UI composition: declaration ownership, cardinality and scope, framework and feature injection, props derivation, and the shipped hierarchy |
| [conversation.md ](conversation.md ) | target-neutral Session-event assembly: Context identity, Location data, replay paths, view builders, and target-owned render nodes |
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-13 00:36:22 +08:00
| [session-telemetry.md ](session-telemetry.md ) | the outbound session-reporting capability seam: `SessionTelemetryRecord` /`SessionTelemetrySeverity` , the `SessionTelemetrySink` contract, and the `session-telemetry/record` redact waterfall |
2026-08-02 03:48:16 +08:00
2026-08-11 14:04:19 +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 API** section.
