Skip to content

dsh-a2a

Verified

@amaster.ai/dsh-a2a Β· v0.1.42 Β· MIT

A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.

Install

dsh plugin add @amaster.ai/dsh-a2a

Confirm the layer applied with dsh --profile default --dump-config β€” see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Readme

@amaster.ai/dsh-a2a

dsh-a2a preview

A2A protocol server plugin for DeepSeek Harness (dsh): expose dsh agents as A2A agents β€” streaming turns, task cancel, agent card, and pluggable task-state stores. Speaks A2A 1.0 (JSON-RPC + SSE) on @a2a-js/sdk 1.x, with the SDK's opt-in v0.3 compatibility layer kept on so pre-1.0 clients keep working. Ported from the source project's packages/a2a-server.

dsh-a2a is the network boundary for a dsh agent. It gives A2A clients a stable task-oriented interface while the agent continues to use the profile's models, presets, tools, and workspace rules.

Install

dsh plugin --profile my-agent add @amaster.ai/dsh-a2a

Native inbox execution

inbox.enabled: true uses the official DSH inbox (Agent.send) for ordinary next-turn input and next-step steering. Requires @deepseek-ai/dsh-agent >=0.2.2-rc.1 for model selection through agent options. Tested with the unmodified npm runtime 0.2.2-rc.1; no core patch is required. Cold task recovery scans committed input once per batch and groups it by task, preserving input order. The queue and its durable projection belong to DSH. The plugin only materializes messages, attaches A2A task identities, and translates execution events.

Standard SendMessage / SendStreamingMessage, task queries, cancellation and task subscriptions keep their official meanings. Optional inbox metadata forwards target and wakeup to DSH. wakeup: false leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.

The same-process a2aInbox service exposes recoveryCandidates, resolve, content, enqueue, promote, cancel, get, update, move, remove, clearPending, and executePending, plus the existing pause/wake/resume controls. Pending-only clearing preserves active work; context clearing discards all work.

Pause is process-local and writes no custom required session event. After restart, restored input stays parked until a waking admission or explicit execution. Retention recovery accepts snapshots under the historical extension URI as well as the current URI, writes only the current metadata key, and clears both keys after consumption. Explicit resume durably transfers input to a fresh task before waking it; retry after an interrupted cleanup reuses the existing replacement instead of replaying its input.

For external clients, the native inbox extension specification defines inbox/get, update, move, remove, clear, execute, steer, and subscribe at the advertised JSONRPC endpoint. No A2A-Extensions header or extension activation is required. Updates use standard A2A 1.0 user Messages; operations address native inbox IDs. REST/gRPC clients use the advertised JSONRPC endpoint for these extension methods. No extra queue or consumer is created.

inbox/subscribe streams checkpointed invalidations {contextId, version} over SSE, including native consumption and edits. It registers before its initial checkpoint and sends only after owner-scoped ctx.sessions.flush() returns true. A false/rejected checkpoint sends no success notification. Re-read the live inbox on invalidation and reconnect; there is no replay or durable outbox. Slow clients disconnect instead of accumulating notifications. To publish the same invalidations to host listeners on a2a/inbox-checkpointed without an SSE subscriber, enable inbox.notifications: true (default false). Hosts retain authentication, authorization and product-specific fan-out.

Existing native agents keep their setup and lifecycle owner. Reading/subscribing does not block their producers. Plugin shutdown detaches its own queued A2A inputs from a borrowed agent, retaining recovery data when configured; native work and the caller's agent remain available.

Wire snapshots are paginated: 50 entries by default, pageSize: 1..100, with totalSize and nextPageToken. Read inbox/get until the token is empty, traversing next-step before next-turn. Any session-version change invalidates the cursor; restart from the first page. Mutations accept pageSize and return the first page. Same-process calls without page options still return the full snapshot. Adjacent reorders log only their affected interval, and slow notification checkpoints keep one pending version/error observer per batch.

The E2E (dsh-a2a.inbox-api) matrix leg installs the packed plugin into the pinned CLI and uses the real model gateway. It checks queue editing/reordering/removal/clearing, execution and steering, two checkpointed SSE subscribers, native consumption, and model recall in a subsequent context turn. A local loopback forwarder only gates the first model request to make steering deterministic; it never generates model responses.

a2a/before-followup validates admission; a2a/before-step runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal cancels tasks by default; inbox.shutdown: retain-pending opts into the retention policy below. Durable A2A task snapshots require a filesystem, Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.

Goal rounds

When the optional official @deepseek-ai/dsh-goal and dsh-goal-round-driver plugins are mounted, a Goal created or resumed during an A2A task keeps that task open while the Goal is active and armed. Automatic rounds retain the driver's original native message ID, content and goal source. The official driver still validates its reservation, revision and round; the plugin selects the owning task for streaming and a2a/before-step billing attribution. Editing the same Goal from another task preserves its original owner. Completing, pausing, blocking or disarming the Goal releases that ownership. A cold restart does not inherit automatic Goal authority: the host must explicitly resume it through a live attributed task.

Promote a queued input

Queue an ordinary future turn as a new task (omit taskId). To steer an active task with that already admitted input, pass its native DSH message ID, available from agent.inbox.nextTurn or a2a/inbox observations:

await ctx.a2aInbox.promote(contextId, nativeMessageId, activeTaskId);

Only an unclaimed, single-message independent task in the same context can be promoted. The native ID and A2A messageId stay unchanged; the target task owns the next-step input, and referenceTaskIds records the original task, which settles canceled after the durable transfer. Claimed input, a finished target, concurrent consumption or task settlement reject a stale request. A failed session checkpoint restores independent ownership; a later storage error can report failure after the transfer committed: inspect the queue and task states before sending new input. Recovery repairs interrupted transfers without replaying an ordinary DSH claim or committed model input.

Local restart recovery

Select taskStore: filesystem with filesystem.root pointing at a retained directory, and separately enable durable DSH session persistence. Keep queued file materialization on retained storage as well. Each task snapshot is scoped by tenant and user, written to a private temporary file and atomically renamed; no additional service is needed. Use one host writer per directory. Files have no automatic expiry; context clearing deletes task snapshots.

After a crash, the host discovers sessions, calls a2aInbox.resolve(contextId) and supplies a real attributed waking input through the normal API. Restored unclaimed inputs keep their original task ownership. Startup scanning and scheduling remain host responsibilities. Explicit cancellation stays terminal and discards only the canceled task's input. This does not promise exactly-once external side effects, replay of consumed input, or replay of the interrupted active model call.

Discovering recovery candidates

await a2aInbox.recoveryCandidates(call?) returns sorted, distinct context IDs from nonterminal task checkpoints in the caller's SDK tenant/user scope (default: the anonymous default scope). It does not open session logs, create agents, resolve contexts or wake input. Pass the same call to a2aInbox.resolve(contextId, call) to restore tasks from that scope. Prepare host identity before resolving a context; the host still decides whether restored work should run. Paused, input-required and interrupted tasks can all be candidates, including tasks with no remaining unclaimed input. Completed, canceled, failed and rejected tasks are excluded; retained input on a terminal task still requires explicit resume.

Context IDs identify agents globally within one plugin instance; the TaskStore scope is not a separate agent namespace. Resolving an already loading or loaded context with a different explicit tenant/user scope rejects. Existing host controls without a call context continue to address that loaded agent.

No separate index or storage configuration is needed. Discovery uses the same atomic summaries as task listing: bounded snapshot prefixes under filesystem.root, Redis keys under the configured prefix, or object metadata in the configured GCS bucket. Each call enumerates the scope once, without sorting or hydrating full task pages. Old, malformed or oversized summaries fall back to reading their snapshots; unreadable snapshots and backend errors reject the call. Custom TaskStores without the optional discovery method use exhaustive task pagination. Task listing counts, filters and cursor semantics are unchanged.

Discovery remains O(task count) in lightweight summaries; it is not a pending-only index. It covers surviving task snapshots, not orphaned session logs. Keep the host's session-scan fallback for deployments whose historical tasks were not durably stored or have expired. The memory backend has no restart durability. Redis persistence must be configured separately, and its task TTL (default 24 hours) still applies. Durable recovery also requires retained DSH session logs and materialized files; a TaskStore alone does not preserve them.

Graceful host shutdown

Set inbox: { enabled: true, shutdown: retain-pending } on both sides of a restart to retain unclaimed A2A next-step and next-turn input. Keep durable session persistence, the TaskStore and materialized files on retained storage. This is a host configuration policy, not wire metadata. The default shutdown: cancel keeps the existing terminal-on-unload behavior.

Retention tracks normalized native inbox splices, including public edits, reordering, removals and queue moves, then freezes the final pending state when host/plugin unloading begins. It stops the current execution, checkpoints pending input in task snapshot metadata with its order and original native/A2A identities, then closes live request/subscription streams. The extra checkpoint survives the core's later inbox-clearing disposal. A task with pending input stays nonterminal for recovery; an interrupted task with no pending input becomes failed. Reconnect subscriptions after restart: streams are not replayed or carried across processes.

On a2aInbox.resolve(contextId), the plugin restores retained ownership before allowing new input, excludes IDs already committed as user/message, and drains the retention checkpoint only after the restored session is durable. Explicit CancelTask, a2aInbox.cancel() and context clearing remain terminal. Claims already handed to the active execution are not retained, and external tool effects are not exactly-once. The host still owns startup discovery and an attributed waking input; merely resolving a context does not wake it. Persistence/checkpoint errors are reported through the existing shutdown error path; the host must not treat a failed checkpoint as a durable restart barrier.

The dedicated E2E (dsh-a2a graceful retention) job covers public plugin disposal, a real SIGTERM child process, repeated restarts, promotion/checkpoint races and terminal cancellation. It also reports recovered tasks to Langfuse and verifies their task/turn/generation ancestry through the real Observations API on same-repository CI.

node .github/scripts/check-inbox.mjs -t 'graceful retention'
DSH_GRACEFUL_RETENTION_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'graceful retention.*reports gracefully recovered'

The dedicated E2E (dsh-a2a native ownership) integration job runs these regressions with unmodified npm DSH and scripted model responses. Its Langfuse scenario verifies Goal rounds and promoted input under the original task trace, canceled source ownership, and execution restored after SIGKILL. Same-repository CI also sends the scenario to the configured real Langfuse project and polls its Observations API; fork PRs use the local collector without credentials.

node .github/scripts/check-inbox.mjs -t 'native ownership'
# With LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY configured:
DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'native ownership.*reports Goal continuation'

Native inbox extension v1

Protocol identifier: https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md

This README contains the extension specification. The URI remains a metadata namespace and discovery identifier for compatibility; callers do not need to send it.

This is a project extension, not an official A2A extension. It follows the A2A extension mechanism. The Agent Card advertises it when inbox.enabled is true. Inbox methods and optional admission controls do not require an A2A-Extensions header or an activation handshake. Standard task methods, states, subscriptions and Push configurations keep their official meanings.

Methods

Methods use the implementation-neutral inbox/ namespace.

Send JSON-RPC 2.0 requests to the advertised JSONRPC endpoint. All methods take contextId. IDs named id below are native inbox message IDs, not task IDs. The extension adds no REST or gRPC service; those clients can discover and use the advertised JSONRPC endpoint for these operations.

Method Additional parameters Result
inbox/get Optional pageSize, pageToken Live inbox snapshot page
inbox/update id, message (A2A 1.0 user Message) Updated snapshot
inbox/move id, index (zero-based destination in the same list) Updated snapshot
inbox/remove id Updated snapshot
inbox/clear β€” Snapshot after clearing pending input
inbox/execute Optional id to move first in the next-turn list Snapshot after waking pending work
inbox/steer id, taskId (active target) Snapshot after promotion
inbox/subscribe β€” SSE JSON-RPC result stream of {contextId, version}

A snapshot is {contextId, version, nextTurn, nextStep, totalSize, nextPageToken}. Each entry is {id, message, editable}: message uses the standard A2A 1.0 Message JSON shape. Native inputs without A2A ownership expose text and have editable: false; editing them requires the originating producer. Queue removal/reordering still uses native IDs. Updates preserve native/protocol IDs, context and task ownership; they cannot replace message identity or edit already claimed input. Index is evaluated after removing the selected item. Execute preserves other pending items and their order; steer reuses the existing task-ownership promotion rules. Explicit execution also drives native-producer input without inventing an A2A Task for it; its conversation events remain in the native session history. Reading or subscribing does not gate input from native producers. An already live native agent is reused with its existing setup and lifecycle owner. Plugin shutdown leaves native work running; it detaches plugin-owned queued A2A input, retaining it in task metadata only under the configured retention policy. Clearing pending input does not cancel an active turn; use standard CancelTask for task cancellation. Removed independent queued tasks become canceled.

HTTP snapshots default to 50 entries, with pageSize from 1 to 100. Pages also limit serialized entries to about 1 MiB; one oversized Message is returned intact to ensure progress, so a page may contain fewer items than requested. All mutation methods accept pageSize for their returned first page; invalid values reject before changing the queue. Pages traverse nextStep before nextTurn, keeping native order within each list. Continue via inbox/get and nextPageToken until the token is empty. Tokens bind the context and session version; a changed version rejects stale tokens instead of silently skipping or duplicating input. Re-read from the first page after invalidation. Same-process get(contextId) and mutation calls without page options retain full-snapshot behavior; passing {pageSize} opts into bounded materialization there too.

Reordering uses one atomic native splice over only the affected interval; executing an input already at the head skips the reorder. Notifications retain one pending version and one error observer per context checkpoint batch, including when a slow checkpoint sees many changes.

Methods use SDK JSON-RPC error serialization. Invalid parameters and stale claims are RequestMalformedError; missing extension activation is ExtensionSupportRequiredError. Unknown extension methods return method-not-found. No tenant namespace or authorization model is added: sessions are native DSH contexts. The host must authenticate/authorize access before exposing this loopback-default server. A nonempty tenant is rejected for these methods.

Checkpointed invalidation

version is a session event sequence (last included event, initially -1), not a task revision. Snapshots describe the live queue and may include newer changes than a previously notified checkpoint. Do not treat a snapshot as a durability acknowledgement. Mutation failures may occur after a native mutation; re-read the authoritative queue before retrying. Same-process host observers opt in with inbox.notifications: true (default false); an SSE subscription activates its own session feed without enabling unused contexts.

Subscribe registers before checkpointing, then sends an initial invalidation only after ctx.sessions.flush(session) returns true. Subsequent invalidations observe native agent/inbox/spliced events, including edits and consumption, coalesce changes per context, and checkpoint before publishing. A rejected or false checkpoint produces no success notification. Later changes or reconnects retry the current state; there is no durable outbox, replay or exactly-once delivery. A host can consume the same feed through a2a/inbox-checkpointed. Notification data contains no message bodies. Re-read inbox/get after an invalidation and on reconnect. Each context checkpoints independently; slow SSE clients disconnect instead of creating an unbounded notification backlog. Closing the plugin unregisters observers/subscriptions and suppresses late sends.

Existing admission metadata

Standard SendMessage/SendStreamingMessage continues to accept metadata[URI] = {target: 'next-turn' | 'next-step', wakeup: boolean} on its Message, without extension negotiation. Prefer those standard methods for new input. The operations above control already queued input; they do not add another queue, consumer, task-state machine or webhook configuration store.

Configuration

Disabled by default. Configure via the profile's cordis.patch.yml:

- insert:
    - id: a2a
      name: '@amaster.ai/dsh-a2a'
      config:
        enabled: true
        host: 127.0.0.1        # no auth built in β€” keep loopback or front with a proxy
        port: 41241
        basePath: /a2a
        heartbeat:
          enabled: false     # opt in to SSE heartbeats
          intervalMs: 15000  # positive integer, at most 2147483647
        cwd: /srv/agent-workspaces
        uploadsDir: ''         # file-part upload root; empty = <OS temp>/dsh-a2a-uploads/<date>
        urlDownloads:
          allowPrivate: false  # true = allow all private/loopback hosts in a trusted intranet
          allowedHosts: []     # or allow only these private/loopback hosts; public hosts need no entry
        subagentTools:
          enabled: false      # opt in to attributed local descendant tool calls/results
        agent:
          provider: ''       # dsh provider/model for A2A sessions; empty = profile default
          model: ''
          preset: ''         # agent preset mounted per task; empty = deployment default
        card:
          name: my-agent
          description: My dsh agent over A2A
          version: 0.1.0
          publicUrl: https://agent.example.com
        taskStore: redis       # memory | filesystem | redis | gcs
        filesystem:
          root: /srv/dsh/a2a-tasks # required when taskStore: filesystem
        redis:
          url: redis://127.0.0.1:6379
          keyPrefix: a2a
          ttlSeconds: 86400
        gcs:
          bucket: my-agent-archives
          prefix: tasks
          keyFilename: ''      # GOOGLE_APPLICATION_CREDENTIALS path; empty = ADC

Endpoints

All eleven A2A 1.0 operations use the official @a2a-js/sdk handlers. JSON-RPC is the default binding; HTTP+JSON/REST and gRPC are opt-in and share the same TaskStore, executor, subscriptions, and push configuration store.

Operation JSON-RPC HTTP+JSON/REST, relative to <basePath>/rest gRPC
Send message SendMessage POST /message:send SendMessage
Stream message SendStreamingMessage POST /message:stream SendStreamingMessage
Get / list tasks GetTask, ListTasks GET /tasks/{id}, GET /tasks GetTask, ListTasks
Cancel task CancelTask POST /tasks/{id}:cancel CancelTask
Subscribe SubscribeToTask GET or POST /tasks/{id}:subscribe SubscribeToTask
Create / list push configs CreateTaskPushNotificationConfig, ListTaskPushNotificationConfigs POST / GET /tasks/{id}/pushNotificationConfigs Same operation names
Get / delete push config GetTaskPushNotificationConfig, DeleteTaskPushNotificationConfig GET / DELETE /tasks/{id}/pushNotificationConfigs/{configId} Same operation names
Extended card GetExtendedAgentCard GET /extendedAgentCard GetExtendedAgentCard

Push operations require pushNotifications: true. The extended card operation requires a host provider; otherwise the SDK returns its standard unsupported error. Requests use A2A-Version: 1.0 and JSON bodies accept application/a2a+json or application/json. REST SSE carries event objects directly, while JSON-RPC SSE carries JSON-RPC response envelopes. REST tenant routes prepend /{tenant}; gRPC requests carry the standard tenant field.

rest: true                 # default: false; uses the HTTP listener
grpc:
  enabled: true            # default: false; separate plaintext HTTP/2 listener
  port: 41242              # same bind host as HTTP, default 127.0.0.1
  publicUrl: ''            # advertised gRPC host:port; empty uses bound address

Install @grpc/grpc-js and @bufbuild/protobuf in the host when enabling gRPC. They are optional peer dependencies and are loaded only when gRPC is enabled. Both gRPC versions use the SDK service descriptors and coexist on this listener; the Agent Card advertises only enabled bindings, including their v0.3 mirrors. REST v0.3 uses the SDK's /v1/... routes and protobuf JSON shapes (for example, ROLE_USER); it is distinct from v0.3 JSON-RPC kind-tagged messages. Use the matching SDK client rather than copying payloads between bindings.

A small connection adapter releases an individual subscription's SDK queue when its client disconnects; it never cancels the task or other subscribers. Disconnected sends continue draining task events for persistence, independently of client read speed. After a stream writer first reports backpressure, it may queue at most 1 MiB of additional HTTP output or 16 additional gRPC messages (plus the frame that crosses the limit). A writer that exceeds this allowance is disconnected; clients can retrieve the persisted task or resubscribe. A single large frame is allowed, and a drain resets the allowance. This bounds the plugin's Node output backlog, not individual frame size or the SDK's internal event/push queues.

The host can register an SDK ExtendedAgentCardProvider with ctx.provide('a2aExtendedCard', provider) before loading this plugin. The type is also exported by this package. The provider receives the SDK ServerCallContext and must authenticate and authorize the caller before returning private card data. The SDK stores HTTP headers or gRPC metadata at context.state.get(STATE_HEADERS_KEY) (STATE_HEADERS_KEY is exported by @a2a-js/sdk/server); tenant and requested version are also available. A rejected provider call returns an error, and the public discovery card stays public. Enabling the provider advertises capabilities.extendedAgentCard: true.

The plugin does not supply an identity provider or TLS certificates. Keep the loopback default or use a host gateway for authentication, authorization and TLS on every enabled listener. Application session listing, queue editing and optional card signing are separate from these eleven operations. This support matrix describes the wired SDK surface, not independent protocol certification.

The secret-free E2E (dsh-a2a protocol bindings) job runs HTTP/gRPC contract tests and real DSH runtime turns with scripted model responses. It covers cross-binding task state, authenticated push callbacks, extended cards, reconnect cleanup and slow readers independently of the LLM/Langfuse integration gate.

  • GET /.well-known/agent-card.json β€” agent card: A2A 1.0 shape for A2A-Version: 1.0 clients, the 0.3 shape for headerless clients (the legacy /.well-known/agent.json path is served as an alias)
  • POST <basePath>/ β€” JSON-RPC. v1 methods: SendMessage (blocking by default, configuration.returnImmediately: true returns after the first event), SendStreamingMessage (SSE), GetTask, ListTasks (filter + cursor pagination), CancelTask, SubscribeToTask (the current task is the first event; the bus stays alive while the task is interrupted, so interrupted tasks can be re-followed live). v0.3 spellings (message/send, message/stream, tasks/get, tasks/cancel, tasks/resubscribe) keep working through the compat layer. Legacy SSE status updates that end an interaction carry final: true, including input-required after a completed turn or an approval wait; this ends the stream without making the task terminal. Resubscribe snapshots keep waiting for future events while a live task bus exists. Legacy tasks/get also accepts contextId without id on this path or root /, returning the latest stored task or result: null when absent.

Behavior notes

  • One task = one dsh session. The A2A contextId IS the dsh session id. By default, a completed turn ends input-required, not completed β€” the task is a conversation and stays continuable; CancelTask and turn errors are terminal (canceled / failed), and the SDK rejects follow-ups addressed at a terminal taskId (send with only the contextId to continue the session under a fresh task id).
  • Same-task messages. ctx.on('a2a/working-task-message', async (detail) => { ... }) runs when another message targets an executing task, before waiting for that task's prior request. Its detail contains agent, contextId, taskId, the original a2aMessage (including its messageId), requestHeaders, and an abort signal; the host can use it to end or revise pending continuation. Failure rejects the new request without enqueueing it. The plugin still serializes agent follow-ups.
  • Host admission and settlement. ctx.on('a2a/before-followup', async (detail) => { ... }) runs before every user message enters the agent inbox. Its detail contains agent, contextId, taskId, the original a2aMessage, dshMessageId, requestHeaders, and an abort signal; rejection fails the A2A task without enqueueing the message. A host may inspect its own A2A message metadata here; the plugin does not interpret it. The existing a2a/message-admitted event remains an observational tap after insertion. A host can register ctx.on('a2a/task-settlement', async ({ agent, contextId, taskId, reason, signal }, next) => { await hostWork; return next(); }). The hook starts after the first completed turn and may wait for any number of autonomous follow-ups, including none. The plugin streams their events under the same task ID and publishes the latest turn's final status when the hook resolves. Cancel, clear, and disposal abort the signal and release the waiter. Without this hook, the first completed turn settles as before. The host must end its wait when its work is done; the plugin does not infer that from product metadata.
  • Agents are full preset citizens. Each task's agent is created with the deployment's default model selection (agentDefaultModel) and mounts its agent preset (the web profile keeps all tools inside presets β€” without one the agent would see an empty tool catalog). agent.preset pins a specific preset.
  • Streaming aggregation. Text deltas of a turn share one messageId, so clients accumulate them into a single message; reasoning deltas ride a separate messageId and are marked metadata.dshAgent.kind: 'thought'. The turn-final event's message carries the full assembled text, so blocking SendMessage clients read the answer from result.task.status.message. Tool calls/results are data parts marked tool-call / tool-result; token usage lands in metadata.usage of the final event. A2A 1.0 has no final flag β€” terminal and interrupted states close the stream.
  • Message parts beyond text. File parts can carry inline bytes or a url; the plugin downloads URLs over http/https, bounded to 64 MiB and 30 s, including the DNS-validation wait. Downloads default to public IP addresses and revalidate every redirect. In a trusted intranet, set urlDownloads.allowPrivate: true to allow every private or loopback host without an allowlist; urlDownloads.allowedHosts remains available to allow only named hosts. Supported images use the composed attachment store (ctx.attachments, e.g. @deepseek-ai/dsh-attachment-local) to reach vision-capable models. Non-image files use a configured materializer or persist under uploadsDir (default <OS temp>/dsh-a2a-uploads/<date>/, names sanitized cross-platform, duplicate names stored in unique upload-* subdirectories), even when an attachment store exists. The prompt references the resulting readable path inside a <document> tag. Ensure the local directory is readable by the agent's tools. data parts become <data> JSON text. A turn never fails because a part kind is unsupported.
  • Remote execution files. A deployment can register ctx.provide('a2aFileMaterializer', { materializeFile }), using the exported A2aFileMaterializer type. The callback receives { contextId, bytes, filename, mediaType, signal? } (with a sanitized basename) and returns { readablePath }, a path readable by that context's file/shell tools. When configured, non-image FileParts use the materializer instead of ctx.attachments.saveFile(); the model receives the returned <document path="...">. Images keep the existing attachment handling. A failed callback yields a delivery note, never a host-path fallback. Task cancellation, context clearing, and plugin unload stop waiting for file preparation. Materializers should honor the optional abort signal to stop their underlying work; a backend that ignores it may still finish independently. The deployment owns sandbox selection, upload, and lifetime; no E2B SDK is required by this plugin.
  • Local execution files. Without a remote materializer, inline and downloaded non-image FileParts persist under uploadsDir; the <document> envelope carries the path, source URL, media type, size, and original filename when sanitization or a collision changes it. Images still use native attachment handling.
  • Tool approvals. When the profile composes @deepseek-ai/dsh-user-approval with policy ask, A2A-owned agents answer approval/request by publishing input-required with a DataPart { requestId, toolName, reason?, callId? }. Reply on the same taskId/contextId with one DataPart { requestId, callId?, outcome: "allowed-once" | "rejected" }. The reply settles the waiting tool call inside the original dsh turn; it does not create another user message or billing turn. Invalid, duplicate, and withdrawn replies are rejected. never policy rejects inside dsh before the A2A answerer is called. The approval service is optional; without it, ask fails closed as usual.
  • Custom approval payloads. A deployment may register ctx.provide('a2aApprovalCodec', codec) before this plugin starts. The exported A2aApprovalCodec has encode(request) and decode(message) methods; decode returns { requestId?, callId?, outcome } only for a supported one-shot decision. A unique callId can replace requestId for legacy clients. Reject unsupported outcomes in the decoder; never translate proceed_always into allowed-once. Other message types, including question, plan, and UI markup, remain outside this plugin.
  • Requests for one task execute in order. Autonomous turns covered by a settlement hook finish before the next user request starts. Approval confirmations settle a pending decision inside its current turn.
  • Restart and workers: persisted task shells survive in Redis/GCS. With sessionPersistence composed, a contextId already present on disk resumes its dsh session after restart; a new id creates a new session. Shared stores do not provide multi-active execution: route a working task/context to its owning worker. A non-owner cancellation fails fast instead of reporting a cancel while the original agent continues.
  • Clear: the same-process gateway can call ctx.get('a2aTasks').clearContext(contextId) before reporting messages/clear success. It cancels and drains the live turn, removes the binding and every TaskStore shell for that context, and returns the removed task IDs. The gateway owns the separate session-surface replacement and client-visible history-ID update.

SSE heartbeats

Set heartbeat.enabled: true to send heartbeats every heartbeat.intervalMs (default 15000 ms). The default is disabled. Intervals must be positive integers no greater than 2147483647 ms (Node's timer limit). This covers SendStreamingMessage / SubscribeToTask and their legacy message/stream / tasks/resubscribe equivalents. The timer starts after the SDK commits SSE headers; pre-stream validation and failures retain their JSON responses. There is no heartbeat while waiting for the SDK's first stream event.

Heartbeats are JSON artifact updates with artifact.name === "heartbeat", so clients that refresh their idle timer on parsed JSON messages receive activity throughout otherwise idle task streams. Legacy streams receive:

data: {"jsonrpc":"2.0","id":"<request-id>","result":{"kind":"artifact-update","taskId":"<task-id>","contextId":"<context-id>","artifact":{"artifactId":"heartbeat","name":"heartbeat","parts":[]},"append":false,"lastChunk":false}}

Native A2A 1.0 streams use result.artifactUpdate with the same fields (without kind). Identifiers come from the current request and streamed task, including resubscription requests. Clients should refresh their idle timer and discard these empty heartbeat artifacts without displaying content. Heartbeats are sent directly on the transport, never persisted as task artifacts or history, and do not change task status, completion, or event IDs. Reverse proxies must forward streaming bytes without buffering for keepalives to reach the client.

Heartbeats are skipped while the response requires drain, with no heartbeat queue or catch-up burst. Timers stop on completion, disconnect, response errors, and server disposal. Heartbeats require a responsive event loop; they cannot repair event-loop starvation or guarantee delivery during backpressure.

Subagent tools

subagentTools.enabled defaults to false. When enabled, tool calls/results from local descendant sessions created inside tools/execute are forwarded to the owning A2A task. Each child has a separate translator: its text, reasoning, usage and turn state never enter the parent's translator, and child completion or disposal never settles the parent task. Main-agent streaming keeps its existing format.

Child events retain the parent's A2A taskId and contextId. metadata.dshAgent.source carries { sessionId, agentId, parentSessionId, parentCallId } (exported as SubagentToolSource): the source child, its immediate parent, and the exact dispatch call that created it. DSH agent IDs are session IDs. Use (source.sessionId, data.callId) to identify a child tool call; use (source.parentSessionId, source.parentCallId) to attach it to its delegation, including nested descendants. The link is captured with async dispatch context, never inferred from event ordering or descriptions. Verified against DSH 0.2.0-rc.1 and 0.2.0-rc.2's in-process child creation path.

Forwarding follows the owning task's active request bus. Background child events between streams are dropped, with no buffering, replay, extra stream or extension of parent settlement; if the same task opens another stream, live events can appear there. Rebinding the parent context to a new task permanently excludes children created for the old task. Providers running outside this process expose no local child events, so only their parent delegation call/result remain visible. Sessions without a captured dispatch link (including children loaded after a process restart, or created outside tool dispatch) are not forwarded; durable attribution for those cases requires an upstream DSH lineage field.

Task stores

A2A task snapshots retain protocol history and artifacts; dsh-storage separately records the full conversation. Backends save on task-state transitions, including the complete reply at input-required, so token-rate stream events never reach Redis or GCS. While a task is working, in-process history accumulates text deltas for GetTask and resubscription; a restart before the next state change can lose those transient deltas.

  • memory (default) β€” in-process, lost on restart
  • filesystem β€” private, atomically replaced JSON snapshots under filesystem.root; no additional peer dependency
  • redis β€” task JSON under <keyPrefix>:tasks:<scope>:<taskId> with a TTL; requires the ioredis peer
  • gcs β€” gzipped task JSON at <prefix>/<scope>/<taskId>/metadata.json.gz; requires the @google-cloud/storage peer. archiveWorkspace() (tar of the workspace) exists but is not wired to the lifecycle yet.

Task listing scans lightweight summaries and loads full snapshots only for the selected page. Filesystem and Redis snapshots carry the summary in the same JSON write; GCS stores it as object metadata in the same upload. Scoped legacy snapshots and oversized summaries fall back to full reads, so no migration is required. Listing still enumerates and sorts the summaries in the caller's scope; this is not a database query index. Filtering, totals, cursor ordering, history, and optional artifacts keep the same API semantics.

<scope> is a hash of the A2A tenant and user. Older unscoped Redis/GCS task records are not read after this upgrade; migrate known records into their scope or let them expire before rollout.

Security

dsh ships no authentication or authorization. The server binds 127.0.0.1 by default; if you expose it, put an authenticated reverse proxy in front and treat every agent as running with the host process's OS privileges. File parts carrying a url are fetched server-side (http/https only, bounded) β€” another reason to keep the endpoint off untrusted networks.

Compatibility

Optional Goal integration requires @deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1 || >=0.2.2-rc.1 and the official Goal round driver (both tested at 0.2.2-rc.1).

Pinned dsh/cordis versions live in the root compat matrix. Event payloads ride pre-release dsh APIs (@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.2-rc.1 β€” the attachment store is an optional peer) β€” the session peer floor is >=0.2.1-rc.5 || >=0.2.2-rc.1 for the owner-scoped SessionStore.flush checkpoint barrier; check the TODO(verify) markers in src/ before upgrading dsh.

Standard A2A notifications

Use SendStreamingMessage / SubscribeToTask for live task updates, GetTask for task snapshots/history, and ListTasks scoped by contextId for discovery. Multiple clients can subscribe independently. Use streaming for interactive UI; use official task Push Notifications for a receiver that cannot keep a stream open. See the official streaming and push guide.

Enable the SDK's standard push capability explicitly (default: false):

config:
  enabled: true
  pushNotifications: true

The Agent Card then advertises capabilities.pushNotifications: true. This plugin passes the official SDK's InMemoryPushNotificationStore and createLegacyAwarePushNotificationSender into its DefaultRequestHandler. Configuration CRUD, dispatch, authentication headers, serialization and timeouts are SDK behavior. Restored native task events use that same sender after their existing SDK ResultManager persistence drain; there is no separate notification protocol, sender adapter, queue-change channel, message correlation cache or plugin retry scheduler.

A v1.0 client can register its webhook while sending a message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "fixture-message-1",
      "role": "user",
      "parts": [{ "text": "Run this task" }]
    },
    "configuration": {
      "taskPushNotificationConfig": {
        "url": "https://receiver.example.invalid/a2a-notifications",
        "authentication": { "scheme": "Bearer", "credentials": "placeholder-token" }
      }
    }
  }
}

Send A2A-Version: 1.0. For an existing task use CreateTaskPushNotificationConfig with { taskId, url, authentication }. The SDK assigns the returned config ID. Manage it with GetTaskPushNotificationConfig, ListTaskPushNotificationConfigs and DeleteTaskPushNotificationConfig (Get and Delete use { taskId, id }). Configuration access uses the SDK's tenant/owner scope. The existing legacy methods and configuration.pushNotificationConfig are handled by the SDK's v0.3 compatibility layer.

The receiver gets HTTP POSTs with Content-Type: application/a2a+json and a standard StreamResponse: { task }, { message }, { statusUpdate } or { artifactUpdate }. The configured Bearer credentials become Authorization; incoming application identity headers are not automatically forwarded. A webhook registered over v0.3 receives the SDK's v0.3 task snapshots and application/json, even if a later triggering request uses a different wire version.

The host verifies webhook authentication and resolves application/context ownership before bridging the update to its existing WebSocket/UI refresh logic. Product topics, permission rules, and snapshot selection stay in the host. Native queue editing/reordering still uses the existing inbox API and snapshots; this plugin does not manufacture new A2A task states for queue edits. A task update does not promise that a separate application database mirror has flushed. GetTask returns the authoritative A2A task snapshot instead.

The official store is in memory. Configs and their credentials are lost on restart, independently of the chosen durable TaskStore backend; clients must register again. Delete configurations that are no longer needed. The SDK uses its default five-second webhook request timeout and logs delivery failures without failing task execution. No plugin-level retries, shutdown drain or persistent delivery guarantee are added. Read task snapshots on initial connection/reconnection and tolerate missing or duplicate notifications.

Keep the loopback default. Push registration lets callers choose outbound webhook destinations; enable it only behind host authentication/authorization and an appropriate outbound-network policy. The SDK wiring does not add an application identity provider or a webhook URL allowlist. Use placeholder credentials and temporary session directories such as /tmp/dsh-a2a-example when testing locally.

License

MIT