deepseek-harness/docs/subsystems

Subsystems

English | 中文

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, 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
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	the packages/llm conversation types — Message/ContentBlock, the assembled model request, the StreamChunk wire protocol and adapter contract, BlockAssembler, and the LlmAdapter provider contract
token-meter.md	immutable scalar and positional replay measurements with consumed-log revisions
scope.md	scoped registration identity, dispatch carriers, and the owned Scope context
typert.md	Remote invocation descriptors, lookup/Context declarations, Typert registries, and the Host Gateway/Client API boundaries
goal.md	persisted goal identity, lifecycle snapshots, activation, change records, and round attribution
schedule.md	Session-local reminder records, durable transitions, active views, and ordinary-conversation delivery
todo.md	the todo package's whole-list item type, durable event ownership, projection, and open-turn invariant
commands.md	the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views
session.md	the full SessionEventMap variant catalog, TurnEndReason, deriveMessages(), execution enclosure, and standalone events
persistence.md	the durability seam: SessionPersistence, JSONL + SQLite backends, session/flush, crash recovery, SessionHeader
settings.md	the user-settings seam: SettingsNamespace registration, layered resolution (defaults → composition base → user document), owner scopes, hot commits
credentials.md	the credential seam: CredentialRef references (never values) in configuration, per-operation resolution, UI-safe CredentialInfo, provider source layers
session-query.md	logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages
feedback.md	lifecycle-bound per-message feedback records, optimistic versions, sidecar persistence, and the Host Remote contract
session-title.md	durable title snapshots, cited source-message seqs, and the asynchronous provider contract
session-reference.md	structured cross-session references: SessionReferenceInput/Candidate, prepared message contexts, the stable error taxonomy
system-prompt.md	per-assembly context, tool-provider results, prompt sections, and cooperative assembly
tools.md	ToolDefinition full fields, the schema DSL, ToolExecution/ToolResult, tool-presentation UI types, and the guarded execution pipeline
user-questions.md	the UI-backed human question/answer seam: AskUserQuestionRequest, answer/options vocabulary, provider API, error taxonomy
approval.md	the one-shot user-approval seam: ApprovalRequest, ApprovalOutcome, per-session policy, audit events, and answerer contracts
attachment.md	durable image identity and metadata, validation inputs, verified reads, and the AttachmentStore seam
shell.md	the bash executor seam: ShellExecRequest/Spec, ShellRunResult, background ShellProcess handles
subprocess.md	the subprocess seam: fully-explicit SubprocessSpawnSpec, offset-based output readers, unclassified SubprocessOutcome, and the managed DSH_* environment vocabulary
terminal.md	persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots
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	the code-execution seam: CodeRunRequest/Result, binding namespaces, captured logs, the CodeRunFailure taxonomy
extensions.md	versioned dynamic Cordis Plugins and Packages, Host/Client activation, approval, runtime inspection, and lifecycle teardown
filesystem.md	the filesystem seam: FsTarget, read/write/edit outcomes, observed-file state, FsErrorCode
lsp.md	the LSP navigation seam: LspQueryRequest/Result, LspProvider/Service, four operations, LspError
skills.md	the skill service: discovery priority, SkillSummary/SkillDefinition, session-prefix catalog, model-facing skill loading
compaction.md	the compaction seam: the compaction/* session events, CompactionResult, the CompactionEngine interface
subagent.md	the subagent seam: the named-provider registry, SubagentStartRequest/Result/Run, the start-time-vs-runtime capability split
agent-team.md	Agent Teams: implicit Lead identity, named continuable teammates, durable peer mailbox, and shared task DAG
web.md	the web access seam: WebSearchRequest/Result, WebFetchRequest/Result, WebFetchBody, provider availability, WebError
spill.md	the spill storage seam: SaveTextSpill, SpillOwner/SpillSource, SpillRef, the branded SpillLocator
workflow.md	the workflow seam: WorkflowStartRequest, WorkflowMeta, WorkflowRun/Result, the workflow/* event payloads, WorkflowError fatality
jobs.md	the background-job runtime: branded JobIds, the producer contract, consumer views, and ctx.jobs service behavior
permission-presets.md	the permission-preset layer: PresetSpec/PresetOption, the derived custom state, the log-only permission/preset event
plan.md	plan mode: the log-only plan/mode state, pending-selection flush, PlanModeConfig, the exit_plan_mode review arc
invariants.md	the runtime-invariant registry: selection Config, InvariantInstaller/InvariantFailure, the empty-companion contract
web-server.md	the HTTP carrier: WebRouteKind/WebRoute, match order, the claimable fallback seat, index taps
webhook.md	authenticated provider deliveries, arbitrary programmatic rules, and fire-and-forget Workspace Session creation
storage.md	the storage subsystem: the backend contract (StorageBackend), StorageForms, DomainSpec/Domain, domain/changed
workspace.md	the workspace registry: Workspace/WorkspaceId, registration and resolution, the session cwd relationship
web-client.md	the browser architecture: boot, Remote communication, paired Client models, UI adapters, Conversation assembly, Slots, and reconnect semantics
client-modules.md	the web plugin table: dsh.client declarations, WebBootGraph wire composition, the bundle route and index tap
slots.md	typed Web UI composition: declaration ownership, cardinality and scope, framework and feature injection, props derivation, and the shipped hierarchy
conversation.md	target-neutral Session-event assembly: Context identity, Location data, replay paths, view builders, and target-owned render nodes
session-projection.md	the projection seam: SessionProjectionMap, the pure ProjectionDefinition unit, ProjectionSnapshot's consistent cut, the change feed
session-telemetry.md	the outbound session-reporting capability seam: SessionTelemetryRecord/SessionTelemetrySeverity, the SessionTelemetrySink contract, and the session-telemetry/record redact waterfall

Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by pnpm run verify-type-equiv (see development.md). 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.