@amaster.ai/dsh-a2a 0.1.18 → 0.1.20

package/README.md

@@ -26,7 +26,7 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
         port: 41241
         basePath: /a2a
         heartbeat:
-          enabled: false     # opt in to transport keepalive comments
+          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>
@@ -53,7 +53,7 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 ## Endpoints
 
 - `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 `tasks/get` also accepts `contextId` without `id` on this path or root `/`, returning the latest stored task or `result: null` when absent.
+- `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
 
@@ -73,20 +73,30 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 
 ## SSE heartbeats
 
-Set `heartbeat.enabled: true` to send the SSE comment `: heartbeat\n\n` 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
+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.
 
-Comments contain no JSON payload and are ignored by SSE event parsers. They
-keep an otherwise idle transport active without changing task state, history,
-results, or event IDs. A client whose idle timeout resets only on parsed JSON
-messages will still time out: reset that transport timer on received bytes, or
-configure a longer timeout. Reverse proxies must forward streaming bytes without
-buffering for keepalives to reach the client.
+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:
+
+```text
+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,

package/lib/legacy-stream.js

@@ -0,0 +1,100 @@
+import { Extensions } from '@a2a-js/sdk';
+import { LegacyJsonRpcTransportHandler } from '@a2a-js/sdk/compat/v0_3/server';
+import { defaultServerCallContextBuilder, validateVersion, } from '@a2a-js/sdk/server';
+import { UserBuilder } from '@a2a-js/sdk/server/express';
+/** SDK 1.1.0 derives legacy final from task terminality, losing interaction endings. */
+export function legacyStreamHandler(requestHandler) {
+    const transport = new LegacyJsonRpcTransportHandler(requestHandler);
+    return async (req, res, next) => {
+        if (req.method !== 'POST' ||
+            req.path !== '/' ||
+            !req.is('application/json') ||
+            !['message/stream', 'tasks/resubscribe'].includes(req.body?.method)) {
+            next();
+            return;
+        }
+        const errorResponse = (error) => ({
+            jsonrpc: '2.0',
+            id: req.body?.id ?? null,
+            error: LegacyJsonRpcTransportHandler.mapToLegacyJSONRPCError(error),
+        });
+        try {
+            const context = defaultServerCallContextBuilder({
+                extensions: Extensions.parseServiceParameter(req.header('X-A2A-Extensions') ?? req.header('A2A-Extensions')),
+                user: await UserBuilder.noAuthentication(),
+                headers: req.headers,
+                requestedVersion: req.header('A2A-Version'),
+            });
+            validateVersion(context.requestedVersion, await requestHandler.getAgentCard(), 'JSONRPC');
+            const response = await transport.handle(req.body, context);
+            if (!(Symbol.asyncIterator in response)) {
+                res.json(response);
+                return;
+            }
+            const stream = response;
+            try {
+                const startStream = () => {
+                    if (context.activatedExtensions)
+                        res.setHeader('X-A2A-Extensions', Array.from(context.activatedExtensions));
+                    res.setHeader('Content-Type', 'text/event-stream');
+                    res.setHeader('Cache-Control', 'no-cache');
+                    res.setHeader('Connection', 'keep-alive');
+                    res.flushHeaders();
+                };
+                // The SDK always streams resubscribe errors; sends validate before SSE headers.
+                if (req.body.method === 'tasks/resubscribe')
+                    startStream();
+                const first = await stream.next();
+                if (!res.headersSent)
+                    startStream();
+                let last;
+                const write = (event) => {
+                    last = event;
+                    const result = event.result;
+                    // INPUT_REQUIRED closes the SDK queue, including real approval waits.
+                    // A task snapshot on resubscribe does not close it and is left intact.
+                    if (result?.kind === 'status-update' && result.status?.state === 'input-required')
+                        result.final = true;
+                    res.write(`data: ${JSON.stringify(event)}\n\n`);
+                    return result?.kind === 'status-update' && result.final;
+                };
+                if (!first.done && write(first.value))
+                    return;
+                for await (const event of stream) {
+                    if (res.destroyed)
+                        break;
+                    if (write(event))
+                        return;
+                }
+                // A cold subscription has no live bus: the SDK ends after the snapshot.
+                const snapshot = last?.result;
+                if (!res.destroyed && snapshot?.kind === 'task')
+                    write({
+                        ...last,
+                        result: {
+                            kind: 'status-update',
+                            taskId: snapshot.id,
+                            contextId: snapshot.contextId,
+                            status: snapshot.status,
+                            metadata: snapshot.metadata,
+                            final: true,
+                        },
+                    });
+            }
+            finally {
+                await stream.return(undefined);
+            }
+        }
+        catch (error) {
+            console.error('[dsh-a2a] legacy stream failed:', error);
+            if (!res.headersSent)
+                res.json(errorResponse(error));
+            else if (!res.destroyed)
+                res.write(`event: error\ndata: ${JSON.stringify(errorResponse(error))}\n\n`);
+        }
+        finally {
+            if (!res.writableEnded)
+                res.end();
+        }
+    };
+}

package/lib/server.js

@@ -19,12 +19,25 @@ import { RequestMalformedError } from '@a2a-js/sdk/errors';
 import { DefaultExecutionEventBus, DefaultRequestHandler, ServerCallContext, STATE_HEADERS_KEY, } from '@a2a-js/sdk/server';
 import { agentCardHandler, jsonRpcHandler, UserBuilder } from '@a2a-js/sdk/server/express';
 import express from 'express';
+import { legacyStreamHandler } from './legacy-stream.js';
 export async function startA2aServer(options) {
     const intervalMs = options.heartbeat?.intervalMs ?? 15_000;
     if (!Number.isInteger(intervalMs) || intervalMs < 1 || intervalMs > 2_147_483_647) {
         throw new Error('[dsh-a2a] heartbeat.intervalMs must be an integer from 1 to 2147483647');
     }
     const stopHeartbeats = new Set();
+    const heartbeatTask = new AsyncLocalStorage();
+    async function* observeTask(stream) {
+        for await (const event of stream) {
+            const state = heartbeatTask.getStore();
+            const payload = event.payload;
+            if (state && payload && payload.$case !== 'message') {
+                state.taskId = payload.$case === 'task' ? payload.value.id : payload.value.taskId;
+                state.contextId = payload.value.contextId;
+            }
+            yield event;
+        }
+    }
     const base = options.basePath.replace(/\/$/, '');
     const publicUrl = (options.card.publicUrl ?? `http://${options.host}:${options.port}`).replace(/\/$/, '');
     const interfaces = [
@@ -192,7 +205,7 @@ export async function startA2aServer(options) {
             try {
                 if (!release)
                     await beforeWorkingTaskMessage(args[0].message, args[1]);
-                const stream = super.sendMessageStream(...args);
+                const stream = observeTask(super.sendMessageStream(...args));
                 try {
                     if (release) {
                         const first = await approvalReply.run(true, () => stream.next());
@@ -213,10 +226,10 @@ export async function startA2aServer(options) {
         async *resubscribe(...args) {
             const task = taskBuses.get(args[0].id);
             if (!task) {
-                yield* super.resubscribe(...args);
+                yield* observeTask(super.resubscribe(...args));
                 return;
             }
-            const stream = super.resubscribe(...args);
+            const stream = observeTask(super.resubscribe(...args));
             try {
                 const replay = task.replay.slice();
                 const last = replay.at(-1);
@@ -309,7 +322,9 @@ export async function startA2aServer(options) {
     // raise the ceiling here — body-parser skips re-parsing an already-read body.
     app.use(express.json({ limit: '16mb' }));
     if (options.heartbeat?.enabled) {
-        app.use((_req, res, next) => {
+        app.use((req, res, next) => {
+            const task = {};
+            const legacy = req.body?.method === 'message/stream' || req.body?.method === 'tasks/resubscribe';
             const flushHeaders = res.flushHeaders;
             // Wait for the SDK to commit SSE headers: validation errors stay JSON.
             res.flushHeaders = function () {
@@ -323,7 +338,22 @@ export async function startA2aServer(options) {
                     if (res.writableNeedDrain)
                         return;
                     try {
-                        res.write(': heartbeat\n\n');
+                        if (!task.taskId || !task.contextId)
+                            return;
+                        const update = {
+                            taskId: task.taskId,
+                            contextId: task.contextId,
+                            artifact: { artifactId: 'heartbeat', name: 'heartbeat', parts: [] },
+                            append: false,
+                            lastChunk: false,
+                        };
+                        res.write(`data: ${JSON.stringify({
+                            jsonrpc: '2.0',
+                            id: req.body.id ?? null,
+                            result: legacy
+                                ? { kind: 'artifact-update', ...update }
+                                : { artifactUpdate: update },
+                        })}\n\n`);
                     }
                     catch (error) {
                         stop();
@@ -344,7 +374,7 @@ export async function startA2aServer(options) {
                 res.off('close', stop);
                 res.off('error', stop);
             };
-            next();
+            heartbeatTask.run(task, next);
         });
     }
     const cardHandler = agentCardHandler({
@@ -408,7 +438,7 @@ export async function startA2aServer(options) {
                 res.sendStatus(404);
         }, contextLookup, rpcHandler);
     }
-    app.use(base, contextLookup, rpcHandler);
+    app.use(base, contextLookup, legacyStreamHandler(requestHandler), rpcHandler);
     const server = createServer(app);
     await new Promise((resolve, reject) => {
         server.once('error', reject);

package/lib/types/legacy-stream.d.ts

@@ -0,0 +1,4 @@
+import { type A2ARequestHandler } from '@a2a-js/sdk/server';
+import type { RequestHandler } from 'express';
+/** SDK 1.1.0 derives legacy final from task terminality, losing interaction endings. */
+export declare function legacyStreamHandler(requestHandler: A2ARequestHandler): RequestHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",
@@ -61,6 +61,7 @@
     }
   },
   "devDependencies": {
+    "@a2a-js/sdk-v03": "npm:@a2a-js/sdk@0.3.14",
     "@deepseek-ai/cordis": "^4.0.4",
     "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
     "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",