@amaster.ai/dsh-a2a 0.1.18 → 0.1.19

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>
@@ -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/server.js

@@ -25,6 +25,18 @@ export async function startA2aServer(options) {
         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 +204,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 +225,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 +321,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 +337,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 +373,7 @@ export async function startA2aServer(options) {
                 res.off('close', stop);
                 res.off('error', stop);
             };
-            next();
+            heartbeatTask.run(task, next);
         });
     }
     const cardHandler = agentCardHandler({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",