packages/core/README.md

# core/ — product API spine

The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.

| Package | Role | ctx key |
|---|---|---|
| `scope/` | Scoped-context registration primitive (scope tags, scope-filtered dispatch) | (library — no ctx key) |
| `session/` | Event-sourced session log + in-memory store | `ctx.sessions` |
| `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` |
| `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
| `agent/` | Agent interface, live registry, process-local initiator scope, `agent/*` event vocabulary | `ctx.agents` |
| `agent-loop/` | Concrete plugin implementing the public `Agent` contract and owning the loop driver | `ctx.agentLoop` |

`scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.

`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop. It runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent`, including when they need the initiating Agent, and never on `agent-loop` directly, so the loop stays swappable.

The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + fallback session titles + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
Document the package hierarchy and finalize the RFC 2026-06-20 23:25:33 +08:00			`# core/ — product API spine`

feat(skill): move catalogs into session prefixes 2026-07-10 14:19:06 +08:00			`The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are product packages — the stable surface plugins and consumers build against.`
Document the package hierarchy and finalize the RFC 2026-06-20 23:25:33 +08:00
			`\| Package \| Role \| ctx key \|`
			`\|---\|---\|---\|`
docs: agent-scope RFC, CONTEXT.md glossary, architecture scope section, README sync 2026-07-09 03:01:11 +08:00			\| `scope/` \| Scoped-context registration primitive (scope tags, scope-filtered dispatch) \| (library — no ctx key) \|
Document the package hierarchy and finalize the RFC 2026-06-20 23:25:33 +08:00			\| `session/` \| Event-sourced session log + in-memory store \| `ctx.sessions` \|
			\| `system-prompt/` \| Prompt-section + tool-schema assembly registry \| `ctx.systemPrompt` \|
docs: align the agent-scope contracts 2026-07-11 22:55:40 +08:00			\| `tools/` \| Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation \| `ctx.tools` \|
refactor(core): fold initiator scope into agents 2026-07-19 13:30:45 +08:00			\| `agent/` \| Agent interface, live registry, process-local initiator scope, `agent/*` event vocabulary \| `ctx.agents` \|
docs(core): describe the public loop contract 2026-07-16 01:17:46 +08:00			\| `agent-loop/` \| Concrete plugin implementing the public `Agent` contract and owning the loop driver \| `ctx.agentLoop` \|
Document the package hierarchy and finalize the RFC 2026-06-20 23:25:33 +08:00
docs: agent-scope RFC, CONTEXT.md glossary, architecture scope section, README sync 2026-07-09 03:01:11 +08:00			`scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.

refactor(core): fold initiator scope into agents 2026-07-19 13:30:45 +08:00			`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop. It runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent`, including when they need the initiating Agent, and never on `agent-loop` directly, so the loop stays swappable.
refactor(examples): extract the app spine into dsh-agent-core + app packages 2026-06-21 12:03:44 +08:00
docs(session-title): record contracts and generated catalogs 2026-07-21 01:54:00 +08:00			The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + fallback session titles + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.