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 11:10:25 +08:00
parent add59a3336
commit fb9636db44
39 changed files with 2819 additions and 51 deletions
@@ -0,0 +1,120 @@
+/**
+ * Property-based protocol-shape tests for the ACP update stream (RFC 001 →
+ * ADR 0013 precedent). Fuzz arbitrary harness `SessionEvent` sequences through
+ * the pure `streamSessionEventUpdate` translator and assert the invariants an
+ * ACP client relies on:
+ *
+ *  - every emitted update is a legal `SessionUpdate` variant;
+ *  - a `tool_call_update` for a given id is never emitted before a `tool_call`
+ *    for that id (the client must see the pending call before its completion);
+ *  - the translator is a pure function of the event (same event → same updates),
+ *    so live streaming and `session/load` replay produce identical streams.
+ *
+ * Pure-function fuzzing (no live loop) keeps these deterministic — a failure is
+ * a real finding, not timing noise.
+ */
+
+import { describe, expect, it } from 'vitest'
+import fc from 'fast-check'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionNotification } from '@agentclientprotocol/sdk'
+import { streamSessionEventUpdate } from '../src/index.ts'
+
+const LEGAL_UPDATE_KINDS = new Set([
+  'agent_message_chunk',
+  'agent_thought_chunk',
+  'tool_call',
+  'tool_call_update',
+])
+
+/**
+ * Build a WELL-FORMED harness event sequence: a list of "actions" where a tool
+ * result can only reference a call already opened earlier. This mirrors what
+ * the loop actually appends (tool/call always precedes its tool/result), so the
+ * ordering invariant is asserted over realistic logs, not arbitrary noise.
+ */
+type Action =
+  | { kind: 'text'; text: string }
+  | { kind: 'reasoning'; text: string }
+  | { kind: 'call'; id: string; name: string }
+  | { kind: 'result'; idx: number; isError: boolean }
+  | { kind: 'ignored' }
+
+function actionsArb(): fc.Arbitrary<Action[]> {
+  const action: fc.Arbitrary<Action> = fc.oneof(
+    fc.string().map((text): Action => ({ kind: 'text', text })),
+    fc.string().map((text): Action => ({ kind: 'reasoning', text })),
+    fc.record({ id: fc.string({ minLength: 1 }), name: fc.string() }).map(({ id, name }): Action => ({ kind: 'call', id, name })),
+    fc.record({ idx: fc.nat(), isError: fc.boolean() }).map(({ idx, isError }): Action => ({ kind: 'result', idx, isError })),
+    fc.constant<Action>({ kind: 'ignored' }),
+  )
+  return fc.array(action, { maxLength: 30 })
+}
+
+/** Lower well-formed actions into a harness event sequence. */
+function actionsToEvents(actions: Action[]): SessionEvent[] {
+  const events: SessionEvent[] = []
+  const openCalls: string[] = []
+  for (const a of actions) {
+    switch (a.kind) {
+      case 'text':
+        events.push({ type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: a.text } } })
+        break
+      case 'reasoning':
+        events.push({ type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: a.text } } })
+        break
+      case 'call':
+        openCalls.push(a.id)
+        events.push({ type: 'tool/call', seq: 0, time: 0, data: { turn: 1, step: 1, callId: CallId(a.id), name: a.name, arguments: '{}' } })
+        break
+      case 'result': {
+        // Only emit a result for an already-opened call (well-formedness).
+        if (openCalls.length === 0) break
+        const id = openCalls[a.idx % openCalls.length]!
+        events.push({ type: 'tool/result', seq: 0, time: 0, data: { turn: 1, step: 1, callId: CallId(id), content: [], isError: a.isError } })
+        break
+      }
+      case 'ignored':
+        events.push({ type: 'turn/end', seq: 0, time: 0, data: { turn: 1, reason: { kind: 'completed' } } })
+        break
+    }
+  }
+  return events
+}
+
+function runStream(events: SessionEvent[]): SessionNotification['update'][] {
+  const out: SessionNotification['update'][] = []
+  for (const event of events) streamSessionEventUpdate('s1', event, n => out.push(n.update))
+  return out
+}
+
+describe('ACP update-stream invariants (property-based)', () => {
+  it('every emitted update is a legal SessionUpdate variant', () => {
+    fc.assert(fc.property(actionsArb(), (actions) => {
+      for (const update of runStream(actionsToEvents(actions))) {
+        expect(LEGAL_UPDATE_KINDS.has(update.sessionUpdate)).toBe(true)
+      }
+    }))
+  })
+
+  it('never emits a tool_call_update for an id before that id\'s tool_call', () => {
+    fc.assert(fc.property(actionsArb(), (actions) => {
+      const seenCall = new Set<string>()
+      for (const update of runStream(actionsToEvents(actions))) {
+        if (update.sessionUpdate === 'tool_call') {
+          seenCall.add(update.toolCallId)
+        } else if (update.sessionUpdate === 'tool_call_update') {
+          expect(seenCall.has(update.toolCallId)).toBe(true)
+        }
+      }
+    }))
+  })
+
+  it('is a pure function of the event (replay equals live)', () => {
+    fc.assert(fc.property(actionsArb(), (actions) => {
+      const events = actionsToEvents(actions)
+      expect(runStream(events)).toEqual(runStream(events))
+    }))
+  })
+})