mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
864b7bfd65
# Conflicts: # docs/architecture.md # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/event-producer-consumer.md # docs/module-graph.md # examples/coding-agent/cordis.yml # examples/echo-agent/cordis.yml # knip.json # packages/core/agent-loop/README.md # packages/core/agent-loop/tests/config-session-id.spec.ts # packages/examples/README.md # packages/examples/stdio-demo/README.md # packages/examples/stdio-demo/tests/stdio-agent.spec.ts
63 lines
5.8 KiB
Markdown
63 lines
5.8 KiB
Markdown
# @deepseek-ai/dsh-agent-spine-demo
|
|
|
|
The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.
|
|
|
|
Read this package for the whole plugin tree and its composition order.
|
|
|
|
## The tree it loads
|
|
|
|
`apply(ctx, config)` mounts each of these as a child of the bundle fiber:
|
|
|
|
```
|
|
@cordisjs/plugin-timer timer service (writes nothing to stdout)
|
|
@deepseek-ai/dsh-llm abstract LLM service + content-block vocabulary
|
|
@deepseek-ai/dsh-session event-sourced session log + store
|
|
@deepseek-ai/dsh-system-prompt prompt-section + tool-schema assembly
|
|
@deepseek-ai/dsh-tools registry + guarded pre/around/post/final-result pipeline
|
|
@deepseek-ai/dsh-skill skill provider registry
|
|
@deepseek-ai/dsh-skill-local local filesystem skill provider
|
|
@deepseek-ai/dsh-agent agent registry + agent/* event vocabulary
|
|
@deepseek-ai/dsh-tasks generic background-task registry
|
|
@deepseek-ai/dsh-invariants dev-mode event-contract assertions
|
|
@deepseek-ai/dsh-tool-bash the model-facing bash schema
|
|
@deepseek-ai/dsh-workspace-context AGENTS.md/CLAUDE.md workspace context loader
|
|
@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema
|
|
@deepseek-ai/dsh-tool-tasks task_output/task_list/task_kill schemas + completion notices
|
|
@deepseek-ai/dsh-agent-loop THE concrete loop (gets the forwarded `agents`)
|
|
(dsh-system-prompt gets the forwarded `persona`)
|
|
```
|
|
|
|
## What it deliberately leaves OUTSIDE the bundle
|
|
|
|
The spine is everything COMMON to every front door. The swappable and front-door-coupled pieces stay out, picked by whatever loads the bundle:
|
|
|
|
- **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
|
|
- **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
|
|
- **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
|
|
- **presentation + per-app infra** — the terminal (`dsh-tui` / `dsh-stdio`) or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
|
|
|
|
This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
|
|
|
|
## Config
|
|
|
|
```ts
|
|
import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
|
|
// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks? }
|
|
// workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
|
|
```
|
|
|
|
The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — a stdio app pre-creates `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
|
|
|
|
## Why a code bundle, not a shared YAML include
|
|
|
|
A YAML include can deduplicate config but cannot own a bin or provide front-door defaults. App packages make stdout-safe ACP wiring the default, though a leaf can still add an unsafe logger. Bundle children register services in the root isolate-keyed store, so injected leaf siblings see them without load-order coupling.
|
|
|
|
## Model Experience
|
|
|
|
Indirectly, through `dsh-system-prompt`, `dsh-tool-skill`, `dsh-tool-bash`, and `dsh-tools`, which this bundle mounts without adding model-bound wrapper content.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- **The spine set is fixed in code** — `apply()` mounts every child unconditionally (including `tool-bash`); no config excludes or replaces one, so swapping the loop or dropping a spine member means composing a different bundle.
|
|
- **`dsh-invariants` mounts unconditionally** — this bundle has no toggle, so every composition using it pays the dev-mode relational assertions; Session's always-on validation and freezing are separate.
|