dsh-a2a-server

Inbound A2A protocol server for DeepSeek Harness.
Publish an Agent Card, accept tasks from any compliant peer.
Everything is a plugin — this is one.

English · 简体中文

_{A community plugin, not an official DeepSeek product.}

dsh-a2a-server makes a DeepSeek Harness agent reachable over the A2A (Agent2Agent) protocol. It serves an Agent Card at a well-known URI and implements the v0.3.0 JSON-RPC binding, so any compliant peer that knows the deployment's URL can discover the agent and submit tasks to it.

The plugin is inbound only: it never connects to another agent. There is no client, no peer directory, and no A2A subagent provider. It is a transport adapter over ctx.agents, not a capability seam.

Install

dsh plugin --profile web add dsh-a2a-server

dsh plugin forwards to pnpm inside the profile directory and appends this bundle to dsh.profile.bundles, because the package declares dsh.bundle.

To work from a checkout instead, point it at the directory:

dsh plugin --profile web add ./path/to/dsh-a2a-server

The plugin stays PENDING until the three required services exist. ctx.webServer ships in dsh-web-app rather than dsh-base, so a headless profile needs @deepseek-ai/dsh-host-webserver mounted before this bundle serves anything. dsh --profile <name> --dump-config prints the composed rows.

Quick start

The bundled example composition runs a real model and a listening server.

pnpm install
A2A_PEERS="alice:demo123" A2A_PORT=9922 pnpm serve

$env:A2A_PEERS = "alice:demo123"
$env:A2A_PORT = "9922"
pnpm serve

Peer names are arbitrary — alice is this demo's default, not a protocol fixture. Name as many as you like, and either carry the token inline or store it under the derived credential reference:

A2A_PEERS="ops:tok1,research:tok2"   # inline
A2A_PEERS="ops,research"             # tokens from A2A_PEER_OPS / A2A_PEER_RESEARCH

The model credential is resolved through ctx.credentials, so an existing DEEPSEEK_API_KEY in the harness home, either .env layer, or the process environment is picked up unchanged. A missing credential fails the boot.

Fetch the card and submit a task:

curl -s http://127.0.0.1:9922/.well-known/agent-card.json

curl -s http://127.0.0.1:9922/a2a \
  -H "authorization: Bearer demo123" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{
        "message":{"kind":"message","messageId":"m1","role":"user",
                   "parts":[{"kind":"text","text":"hello"}]}}}'

A one-shot probe runs 48 checks against a live server and exits non-zero on any mismatch:

pnpm probe                                        # defaults to :9922 / demo123
node example/probe.mjs http://127.0.0.1:9922 demo123

Interface

Both dialects are accepted. v0.3 (message/send, "working", kind-tagged parts) is the mainline; the v1.0 spellings (SendMessage, TASK_STATE_WORKING, member-presence parts) are normalized inbound and rendered back in whichever dialect the request used.

Inbound messages may carry text, file, and data parts. File and data parts are rendered into the model's context as bracketed references. Replies are text.

Authentication, rate limiting, and the trust gate answer with HTTP 401, 429, and 403; the body remains a valid JSON-RPC error envelope. A task belonging to another peer answers exactly as an absent one.

Configuration

- id: a2a-server
  name: dsh-a2a-server
  config:
    basePath: /a2a
    publicUrl: https://agents.example.com/a2a   # advertised on the card
    protocolVersion: 0.3.0
    provider: deepseek-official
    model: deepseek-v4-flash

    card:
      name: dsh-harness
      description: Reads code, runs commands, reports findings.
      public: true
      skills:
        - id: general
          name: general
          description: General-purpose task execution.
          tags: [coding, research]
      provider:
        organization: Example Inc.
        url: https://example.com

    peers:
      alice: { tokenEnv: A2A_PEER_ALICE }
      bob:   { tokenEnv: A2A_PEER_BOB }
    trustedPeers: [alice]
    rateLimitPerMinute: 60
    maxContextTurns: 5

    sendMode: block
    blockTimeoutMs: 60000
    contextIdleTtlMs: 1800000
    maxResidentContexts: 64

    isolation:
      workspaceMode: per-peer
      workspaceRoot: /srv/dsh/a2a
      peerWorkspaces:
        alice: /srv/project

    push:
      enabled: false

Configuration is refused at load when isolation.workspaceRoot is absent, a peer name is not [A-Za-z0-9][A-Za-z0-9_-]*, a tokenEnv is not a POSIX identifier, trustedPeers or peerWorkspaces names an undeclared peer, or basePath does not start with /.

Credentials

Configuration carries credential references, never values:

peers:
  alice: { tokenEnv: A2A_PEER_ALICE }

# ~/.dsh/.credentials.yaml
A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>

ctx.credentials resolves the reference per request across four layers — the process environment, the managed document, <cwd>/.env, and $DSH_HOME/.env — so rotating a token takes effect on the next request without a restart. Peer identity comes from the presented credential only; nothing in a request body can assert it. There is no shared bearer token: isolation is built on distinct identities.

Isolation

per-peer (the default) derives each identity's cwd from workspaceRoot. shared places every peer in one directory, which suits peers collaborating on a single repository; under it, files written by one peer are readable by another.

Boundaries

• Inbound only. No outbound client, peer directory, or A2A subagent provider.
• JSONRPC binding only. gRPC and HTTP+JSON are not served, and the card says so.
• Push notifications are not implemented. push.enabled selects which error the push methods return; the card advertises pushNotifications: false.
• No extended Agent Card, stateTransitionHistory, protocol extensions, or card signatures.
• Streaming emits committed assistant messages. Per-chunk streaming is not implemented.
• No orphan-task watchdog: a task wedged non-terminal stays that way.
• Cross-session tool denial is not implemented; isolation rests on workspaceMode.
• A token ceiling settles a task as completed; the real turn ending travels in Task.metadata.dsh.stopReason, which A2A's state enum cannot express.
• Task state survives settlement but not a process restart: session persistence is not composed, so the projection has no log to cold-fold after a reboot.
• ctx.webServer provides no TLS. Any non-loopback exposure belongs behind a reverse proxy.
• A configuration change restarts the plugin and cancels in-flight tasks.

Architecture

src/
├── protocol/          dependency-free library: no Cordis, no HTTP, no harness
│   ├── wire.ts        the A2A vocabulary, normalized to v0.3 spelling
│   ├── normalize.ts   v0.3 <-> v1.0 dialect translation, both directions
│   ├── jsonrpc.ts     framing and the A2A error codes
│   ├── card.ts        Agent Card construction
│   └── sse.ts         SSE frame encoding
├── index.ts           the Cordis plugin: wiring, agent ownership, teardown
├── router.ts          HTTP + JSON-RPC dispatch, free of Cordis so it unit-tests
├── contexts.ts        contextId -> Activation registry and residency policy
├── tasks.ts           task slots and the three-stage turn correlation
├── projection.ts      the a2aTask fold over the session log
├── security.ts        authentication, rate limiting, defanging, redaction
├── config.ts          schema plus the cross-field checks that fail at load
└── types.ts           declaration merges into SessionEventMap / MessageSourceMap

A task is an interval, not a turn. One submitted message may span several turns if tools queue more work, so settlement uses three hooks: agent/inbox/claimed binds the message to a turn, turn/end records that turn's ending, and agent.whenIdle() settles once the whole agent is quiet.

Task state lives in the session log. Lifecycle transitions are a2a/task events; a projection unit folds them into the read model. The terminal edge carries the committed output, so the fold serves the answer without reaching back into message history.

Residency is explicit. HTTP has no connection lifetime, so each contextId maps to an Activation evicted when idle, leaving the durable Session behind.

Development

pnpm install
pnpm typecheck
pnpm test       # 129 tests across 9 files
pnpm serve      # a listening server
pnpm probe      # 48 checks against a running server
pnpm build      # emit lib/

The end-to-end suites boot a real Cordis composition with a real agent loop and drive it over HTTP, using a deterministic stub adapter so assertions do not depend on model output.

Relationship to the official project

Built against deepseek-ai/deepseek-harness.

The official project supplies the agent runtime, the plugin system, and the capability seams this plugin consumes. This project supplies:

• The A2A v0.3.0 JSON-RPC binding, served inbound
• Agent Card construction and dialect normalization
• Mapping between A2A tasks and harness turns
• Per-peer authentication, isolation, and workspace policy

The harness is pre-release and does not promise compatibility across renames or repackaging, so peer dependencies are pinned exactly to 0.1.0-rc.6.

Community

Scan to join the WeChat group A2A 产品应用和探索 — discussion of A2A in practice, this plugin included.

If the code has expired, open an issue and we will refresh it.

License

MIT