@dsh-lattice/transports

DSH Lattice V1 protocol transports: JSON-RPC Content-Length stdio server, CLI, an exactly-one-tool MCP server, config validation, and experimental fail-loud ACP client and A2A HTTP/JSON-RPC client.

This package is an independent community project, part of the DSH Lattice facade. It is not affiliated with, endorsed by, or sponsored by DeepSeek AI.

Surfaces

Surface	Entry	Notes
JSON-RPC stdio	dsh-lattice serve	JSON-RPC 2.0 over Content-Length framing; methods lattice.ping, lattice.status, lattice.uto_run, lattice.shutdown
CLI	dsh-lattice run	deterministic result envelope → stdout, trace ref → stderr (ECC-V1.0 §14.2)
MCP server	dsh-lattice mcp	exactly one tool: lattice.uto_run (one-tool-per-caller)
Config validation	dsh-lattice validate	zod, .strict(): config is contract
ACP client	library	experimental, fail-loud, newline-framed JSON-RPC over stdio
A2A client	library	experimental, HTTP/JSON-RPC tasks/send|get|cancel, messages/send, Agent Card

All surfaces funnel into the single orchestration entry MemoryEngine.utoRun — the reference engine that implements the canonical envelope, deterministic idempotency keys (§9.3), duplicate suppression, capability preflight (fail loud), session modes with fingerprints and override authorization (§16), audit events and metric counters.

pnpm build && node scripts/smoke.mjs   # CLI + stdio + MCP smoke

CLI example

dsh-lattice run \
  --project review-pipeline \
  --task '{"description":"review the pr"}' \
  --members '{"planner":{"provider":"local"},"reviewer":{"provider":"local"}}' \
  --mode coordinate --tenant tenant_1
# → { "status": "completed", "scope": "run", "scopeId": "run_...", ... }
# stderr: trace: trace_...

MCP server

dsh-lattice mcp

tools/list returns exactly one tool, lattice.uto_run. tools/call with any other tool name fails loud (-32602). Protocol version is pinned to 2024-11-05. Note: upstream DeepSeek Harness ships an MCP client, not a public MCP server; this server is a Lattice-owned boundary.

Config validation

validate accepts a JSON file with project and/or adapters:

{
  "project": {
    "slug": "review-pipeline", "version": "1.0.0", "charter": "...",
    "members": { "planner": { "provider": "dsh-sdk" } }
  },
  "adapters": {
    "codex": {
      "name": "codex", "package": "@dsh-lattice/adapter-codex",
      "adapterVersion": "1.0.0",
      "requiredCapabilities": ["oneShot"], "observedCapabilities": ["oneShot"]
    }
  }
}

Defaults follow the spec: retentionDays: 90, maxHops: 16. Unknown keys and inline credential values are rejected.

Experimental ACP client

import { createAcpClient } from "@dsh-lattice/transports/acp-client";

const client = createAcpClient({ executable: "my-acp-agent", args: ["--stdio"] });
client.start();
await client.agentStart({ title: "t" });
const turn = await client.agentTurn({ prompt: "hi" });
client.close();

Fail-loud rules: unknown methods surface as errors, permission requests are never auto-approved (PermissionRequiredError), protocol version mismatches and malformed frames are errors, responses with unmatched ids fail the session.

Experimental A2A client

import { createA2aClient } from "@dsh-lattice/transports/a2a-client";

const client = createA2aClient({
  endpoint: "https://example.com/a2a",
  bearerToken: process.env.A2A_TOKEN, // credential ref; never logged
});
const task = await client.taskSend({ message: { role: "user", parts: [{ text: "hi" }] } });
const state = await client.taskGet(task.id);

Fail-loud: non-2xx status, non-JSON-RPC bodies, id mismatches and remote errors all surface as A2aError.

Honest claims

• Delivery is at-least-once with deterministic idempotency keys and duplicate suppression. No exactly-once side effects are claimed.
• No guaranteed provider KV-cache-hit claim is made (ECC-V1.0 §17).
• The bundled MemoryEngine is a reference/demo engine for protocol smoke tests; the production engine lives in the aggregator.

Upstream compatibility evidence

• The newline framing used by the ACP client mirrors the DeepSeek Harness SDK protocol transport: JSON-RPC 2.0, one compact JSON frame per \n-terminated line, malformed lines ignored (upstream packages/sdk/protocol/README.md, @deepseek-ai/dsh-root 0.1.0-rc.5).
• Upstream ships an MCP client, not a server — verified in the workspace checkout; the MCP server here is Lattice-owned.

Development

pnpm install
pnpm build && pnpm typecheck && pnpm test && pnpm coverage
pnpm smoke

License

Apache-2.0. See LICENSE and NOTICE.