2026-08-25 23:47:20 +08:00
---
description: "The core group map: the session log, system-prompt assembly, tool registry, agent vocabulary, and default loop that form the product API spine."
kind: "package-group"
---
# packages/core
2026-06-20 23:25:33 +08:00
2026-07-26 05:03:53 +08:00
English | [中文 ](README.zh.md )
2026-08-25 23:47:20 +08:00
## Summary
2026-08-26 14:12:26 +08:00
The core group provides the product API spine of the DeepSeek Harness: an append-only session log, system-prompt assembly, a tool registry, the `Agent` handle, and the concrete loop that drives them. Every composition boots these packages, and plugins and consumers build against their stable contracts. A turn flows through all of them — the loop claims a prompt, opens a turn on the session log, assembles the request through system-prompt, streams the model response, dispatches tool calls through the registry, and appends every model-visible fact back to the log. Choose this group when you build an agent or extend one; the default product composition is [`dsh-base` ](../bundle/base/README.md ).
2026-08-25 23:47:20 +08:00
## Table of Contents
- [Packages ](#packages )
- [Related documentation ](#related-documentation )
- [Dev Note ](#dev-note )
-----
< a id = "packages" > < / a >
## Packages
2026-06-20 23:25:33 +08:00
| Package | Role | ctx key |
|---|---|---|
2026-08-25 23:47:20 +08:00
| [`scope/` ](scope/README.md ) | Scoped registration and event routing that isolate one agent's contributions | library — no ctx key |
| [`session/` ](session/README.md ) | The append-only session event log every agent's history derives from | `ctx.sessions` |
| [`system-prompt/` ](system-prompt/README.md ) | System-prompt assembly from ordered sections, tool schemas, and variables | `ctx.systemPrompt` |
| [`tools/` ](tools/README.md ) | The tool registry and guarded execution pipeline the loop dispatches through | `ctx.tools` |
| [`agent-tool-presentation/` ](agent-tool-presentation/README.md ) | Per-agent tool-presentation selector for presets | no ctx key |
| [`agent/` ](agent/README.md ) | The `Agent` handle plugins program against, plus its live registry and events | `ctx.agents` |
| [`agent-default-model/` ](agent-default-model/README.md ) | The deployment default model selection entry points apply to fresh agents | `ctx.agentDefaultModel` |
| [`agent-loop/` ](agent-loop/README.md ) | The default agent driver: creates agents and runs the turn and step lifecycle | `ctx.agentLoop` |
2026-08-26 14:12:26 +08:00
`scope` supplies the shared scoping primitive; `agent` owns the public `Agent` contract, while `agent-loop` is its default implementation, so extension plugins depend on `agent` and the driver stays swappable. `agent-default-model` owns the deployment selection an entry point applies when a session has none of its own. Runnable compositions live under [`packages/bundle` ](../bundle/README.md ); this group owns only the swappable spine pieces.
2026-08-25 23:47:20 +08:00
-----
< a id = "related-documentation" > < / a >
## Related documentation
- [Core subsystem ](../../docs/subsystems/core.md ) — the package-by-package loop map and the `Agent` handle contracts.
- [Session subsystem ](../../docs/subsystems/session.md ) — the session event vocabulary and derived history.
- [System-prompt subsystem ](../../docs/subsystems/system-prompt.md ) — prompt section, dynamic context, and tool-schema types.
- [Tools subsystem ](../../docs/subsystems/tools.md ) — the tool execution pipeline and presentation vocabulary.
- [Scoped registration subsystem ](../../docs/subsystems/scope.md ) — the scoped-layer primitive these registries build on.
- [Architecture ](../../docs/architecture.md ) — the turn flow and where new behavior goes.
2026-08-26 14:12:26 +08:00
- [Base bundle ](../bundle/base/README.md ) — the default product composition.
- [SDK minimal bundle ](../bundle/sdk-minimal/README.md ) — a complete standalone composition with a deliberately smaller feature set.
2026-08-25 23:47:20 +08:00
-----
< a id = "dev-note" > < / a >
## Dev Note
2026-06-20 23:25:33 +08:00
2026-08-25 23:47:20 +08:00
< details >
< summary > Working context for maintainers — click to expand< / summary >
docs: agent-scope RFC, CONTEXT.md glossary, architecture scope section, README sync
The agent-scope-contexts RFC (implemented) records the decision tree:
the dsh-scope primitive over cordis extend/Context.filter/no-op fibers,
two-level flat scope with shadowing, restriction/grant semantics, the
scoped-dispatch rule with fused helpers, the setup window, and the
alternatives (explicit scope params, isolate, event-filtering-only,
vendored support) with why each lost. CONTEXT.md pins the glossary.
architecture.md gains the Agent Scope section, the dsh-scope spine row,
the scoped turn-flow line, and an extension-table row (ceiling 1640→1790:
the two-layer registration model is a new architectural axis; additions
are condensed to pointers). READMEs of every touched package re-state
their scoped facts; the stale structured-runtime README section is
replaced by the scoped-registration description.
2026-07-09 03:01:11 +08:00
2026-08-25 23:47:20 +08:00
None.
docs: anchor each subsystem page to its package group; make group READMEs thin tables
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.
Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
2026-08-02 05:54:15 +08:00
2026-08-25 23:47:20 +08:00
< / details >
