mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui e2bde2902c refactor(examples): extract the app spine into dsh-agent-core + app packages

Implements docs/rfc/.../2026-06-20-extract-example-app-packages.md. Each
example was thick — a hand-rolled start.ts, an infra preamble, nested
base.yml/base-core.yml/acp-tail.yml includes, and a coupled front-door
cluster enforced only by prose. This moves the composition into packages so
each example is a thin leaf cordis.yml: pick the swappable backends, load one
app package.

New packages:
  - @deepseek-ai/dsh-agent-core (packages/core/agent-core): one bundle plugin
    that loads the providerless/executor-less/UI-less spine (timer + llm +
    sessions + system-prompt + tools + agents + invariants + tool-bash +
    agent-loop) via ctx.plugin(...) inside apply(), and forwards agent-loop's
    `agents` list as its own Config (export const Config = AgentLoop.Config,
    default []).
  - @deepseek-ai/dsh-stdio-agent (packages/ui/stdio-agent): terminal chat APP —
    agent-core + console logger + readline UI + a pre-created `main` agent, with
    a bin. The demo:echo/coding front door.
  - @deepseek-ai/dsh-acp-agent (packages/ui/acp-agent): ACP server APP —
    agent-core + JSONL persistence + the acp bridge, NO stdout logger, with a
    bin. The stdout-purity footgun is structurally unreachable from the leaf.

Amendment to the RFC: hmr stays a LEAF cordis.yml entry, not baked into
dsh-stdio-agent. hmr is a Loader-only dev plugin (throws without
--expose-internals; the in-process test tier can't even import its decorator
form), so a package statically importing it could never carry the per-file
coverage gate. Unlike the console logger, a stray hmr is not a stdout-purity
footgun, so leaving it at the leaf costs no safety. With hmr out, all three new
packages carry in-process unit specs at 100%.

Boot glue (Loader tail, .env load, snapshot-mode selection, stdin-dispose
lifecycle) moves into each app's bin; start.ts and base.yml/base-core.yml/
acp-tail.yml are deleted. Each app package gets a keyless real-load-path test
that boots through its bin + the cordis Loader (guarding the unwrapExports
export-shape bug class, postmortem 0001). ACP snapshot replay stays green
against the existing committed goldens (pure boot restructuring). RFC moved
proposed->implemented with the amendment recorded; package/example/architecture
docs and the module graph updated.

2026-06-21 12:06:38 +08:00

2.1 KiB

Raw Blame History

RFC: Make the shared example base providerless

Status: rejected — superseded by Extract example apps into packages, which moves the spine into a dsh-agent-core bundle and deletes the base*.yml files, so there is no shared base YAML left to rename.

Problem

The examples had two shared base files: examples/base-core.yml was providerless, while examples/base.yml included that core plus the real llm-deepseek adapter. Snapshot replay needs the providerless core with llm-replay, because loading the real adapter without a key throws. The normal demos need the real adapter. The result was a naming inversion: the file named base.yml was not the reusable base for all examples, while the true base was base-core.yml.

The split was understandable, but it made every config explanation longer. It also led to awkward test setup like a keyless smoke test carrying a dummy API key so an adapter could boot even though the model is not called.

Proposal

Rename the providerless core to examples/base.yml and make adapter selection explicit in each concrete example. The coding and ACP real configs add a tiny llm-deepseek include or local block; snapshot config adds llm-replay. Delete examples/base-core.yml.

The shared base should contain only provider-neutral services and tools: llm, sessions, system prompt, tools, agents, invariants, bash executor, and bash tool schemas. Anything that chooses a model provider belongs at the leaf config.

Acceptance criteria

examples/base.yml is providerless.
examples/base-core.yml is deleted.
Real demo configs explicitly add the DeepSeek adapter.
Snapshot replay config includes the same providerless base and its replay adapter.
The examples README, example-specific READMEs, and RFC references stop explaining "base = base-core plus adapter".

What we give up

Real demos lose one layer of convenience: each must opt into the adapter. That is the right default for examples, because adapter choice is the variable part and providerless wiring is the shared product core.

2.1 KiB Raw Blame History