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

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 forA2A-Version: 1.0clients, the 0.3 shape for headerless clients (the legacy/.well-known/agent.jsonpath is served as an alias)POST <basePath>/β JSON-RPC. v1 methods:SendMessage(blocking by default,configuration.returnImmediately: truereturns 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 carryfinal: true, includinginput-requiredafter 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. Legacytasks/getalso acceptscontextIdwithoutidon this path or root/, returning the latest stored task orresult: nullwhen absent.
Behavior notes
- One task = one dsh session. The A2A
contextIdIS the dsh session id. By default, a completed turn endsinput-required, notcompletedβ the task is a conversation and stays continuable;CancelTaskand turn errors are terminal (canceled/failed), and the SDK rejects follow-ups addressed at a terminaltaskId(send with only thecontextIdto 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 containsagent,contextId,taskId, the originala2aMessage(including itsmessageId),requestHeaders, and an abortsignal; 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 containsagent,contextId,taskId, the originala2aMessage,dshMessageId,requestHeaders, and an abortsignal; 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 existinga2a/message-admittedevent remains an observational tap after insertion. A host can registerctx.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.presetpins 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 separatemessageIdand are markedmetadata.dshAgent.kind: 'thought'. The turn-final event's message carries the full assembled text, so blockingSendMessageclients read the answer fromresult.task.status.message. Tool calls/results are data parts markedtool-call/tool-result; token usage lands inmetadata.usageof the final event. A2A 1.0 has nofinalflag β 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, seturlDownloads.allowPrivate: trueto allow every private or loopback host without an allowlist;urlDownloads.allowedHostsremains 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 underuploadsDir(default<OS temp>/dsh-a2a-uploads/<date>/, names sanitized cross-platform, duplicate names stored in uniqueupload-*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.dataparts 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 exportedA2aFileMaterializertype. 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 ofctx.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-approvalwith policyask, A2A-owned agents answerapproval/requestby publishinginput-requiredwith a DataPart{ requestId, toolName, reason?, callId? }. Reply on the sametaskId/contextIdwith 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.neverpolicy rejects inside dsh before the A2A answerer is called. The approval service is optional; without it,askfails closed as usual. - Custom approval payloads. A deployment may register
ctx.provide('a2aApprovalCodec', codec)before this plugin starts. The exportedA2aApprovalCodechasencode(request)anddecode(message)methods;decodereturns{ requestId?, callId?, outcome }only for a supported one-shot decision. A uniquecallIdcan replacerequestIdfor legacy clients. Reject unsupported outcomes in the decoder; never translateproceed_alwaysintoallowed-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
sessionPersistencecomposed, acontextIdalready 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 reportingmessages/clearsuccess. 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 restartfilesystemβ private, atomically replaced JSON snapshots underfilesystem.root; no additional peer dependencyredisβ task JSON under<keyPrefix>:tasks:<scope>:<taskId>with a TTL; requires theioredispeergcsβ gzipped task JSON at<prefix>/<scope>/<taskId>/metadata.json.gz; requires the@google-cloud/storagepeer.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