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

Files

Tianyi Cui fb9636db44 feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio

Implements the RFC 010 MVP: a new `@deepseek-ai/dsh-acp` package bridges the
harness agent to the Agent Client Protocol (JSON-RPC 2.0 over newline-delimited
stdio), so Zed and other ACP editors can drive the coding agent — streaming
render, tool-call display, and resumable sessions via `session/load`.

- packages/acp: AgentSideConnection wiring; initialize/newSession/loadSession/
  prompt/cancel; a total TurnEndReason→StopReason codec; settle-once with a
  fallback chain (agent/turn-end → logged turn/end → idle); single-session
  guard; cwd-must-equal-launch-dir validation; load replays from the persisted
  event log (assistant/chunk→agent_message_chunk, tool/call/result→tool_call*).
- agent: add Agent.whenIdle() quiescence signal to the interface; LoopAgent
  implements it (resolves on the first running→idle/disposed transition). The
  bridge awaits it on disposal so teardown reaches quiescence, not just abort.
- examples: extract the shared provider/tool core into examples/base.yml;
  coding-agent nest-includes it; new examples/acp-agent serves the agent over
  ACP with JSONL persistence and no stdout logger (stdout is the protocol).
- Permission gate deferred (TODO(rfc010-permission-gate)): tools run with the
  executor's full authority; only the Agent→sessionId ownership seam is laid
  down. Cancel is best-effort for a not-yet-started queued turn
  (TODO(rfc010-cancel-prestep)). RFC 010 stays `proposed`.
- Docs: package README + Zed snippet; client-driver cookbook section; root and
  packages layout/commands; RFC 010 implementation-status note.

48 bridge tests + whenIdle coverage; 100% per-file coverage; e2e boots the
example as a subprocess and verifies a written file on disk (key-gated, with a
no-key stdout-purity check).

2026-06-16 18:44:31 +08:00

4.0 KiB

Raw Blame History

Packages

Harness packages, all under the @deepseek-ai/dsh-* scope. Each package is a Cordis service (microkernel plugin-style): it exports a default Service class that gets registered via ctx.plugin(), declares its ctx key and events through declaration merging, and exposes extension points through ctx.effect(), ctx.on(), and ctx.waterfall().

Dependency graph

dsh-llm          (no harness deps — pure vocabulary)
dsh-bash          (no harness deps — abstract executor seam)
dsh-session       ← dsh-llm
dsh-system-prompt ← dsh-llm
dsh-agent         ← dsh-llm, dsh-session
dsh-tools         ← dsh-llm, dsh-system-prompt, dsh-agent
dsh-bash-local    ← dsh-bash                       (BashExecutor impl)
dsh-tool-bash     ← dsh-bash, dsh-tools            (bash tool schemas)
dsh-llm-deepseek  ← dsh-llm                        (DeepSeek adapter)
dsh-llm-pi-ai     ← dsh-llm                        (pi-ai-backed adapter)
dsh-agent-loop    ← dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent
dsh-invariants    ← dsh-llm, dsh-session, dsh-agent (dev-mode contract checks)
dsh-acp           ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence  (ACP JSON-RPC bridge)

The rule: plugins depend on interfaces, never on the concrete loop. dsh-agent-loop is swappable — UI/hook/tool plugins keep working against the dsh-agent vocabulary if the loop is replaced. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see ADR 0009).

What goes where

Package	Role	ctx key
`llm/`	Abstract LLM service + content-block vocabulary + chunk assembler	`ctx.llm`
`session/`	Event-sourced session log + in-memory store	`ctx.sessions`
`system-prompt/`	Prompt-section + tool-schema assembly registry	`ctx.systemPrompt`
`tools/`	Tool registry + `tools/execute` waterfall	`ctx.tools`
`agent/`	Agent interface, registry, `agent/*` event vocabulary	`ctx.agents`
`agent-loop/`	THE concrete plugin: `LoopAgent` + the loop driver	`ctx.agentLoop`
`bash/`	Abstract bash executor seam (interface + vocabulary)	`ctx.bash`
`bash-local/`	Local-subprocess `BashExecutor` implementation	(registers `ctx.bash`)
`tool-bash/`	Model-facing `bash`/`bash_output`/`bash_kill` tool schemas	(registers on `ctx.tools`)
`llm-deepseek/`	DeepSeek API adapter (hand-rolled fetch/SSE)	(registers on `ctx.llm`)
`llm-pi-ai/`	DeepSeek adapter via `@earendil-works/pi-ai` (design twin)	(registers on `ctx.llm`)
`invariants/`	Dev-mode event-contract invariants + session-log freeze	(listens on `session/`, `agent/`)
`acp/`	Agent Client Protocol bridge: serves the agent to an ACP editor over JSON-RPC stdio	(drives `ctx.agents`/`ctx.sessions`)

Each package has its own README.md with purpose, service API, events, extension points, and deliberate non-goals (TODOs).

Conventions (applied across all harness packages)

Registrations are effects: every contribution (adapter, tool, section, agent, event listener) goes through ctx.effect() / ctx.on(), so disposal and HMR clean up automatically. Every register() returns the disposer.
Declaration merging for events and ctx: services declare their events in declare module 'cordis' { interface Events { ... } } and their ctx key in interface Context.
Waterfall semantics: ctx.waterfall listeners receive (...args, next) and MUST call next() to delegate; returning without it short-circuits (the veto mechanism).
Extensible unions: ContentBlockMap, MessageSourceMap, FinishReasonMap, TurnTriggerMap, TurnEndReasonMap, and SessionEventMap use the merge-extensible-map pattern so plugins can add variants via declaration merging.
ESM everywhere; imports use package names across package boundaries, .ts extensions within a package.
Tests: vitest, colocated under packages/<name>/tests/*.spec.ts. Every registry needs an HMR-safety test. Err on the side of more tests.

4.0 KiB Raw Blame History

Packages

Dependency graph

What goes where

Conventions (applied across all harness packages)

4.0 KiB

Raw Blame History