@amaster.ai/dsh-a2a 0.1.17 → 0.1.19

package/README.md

@@ -25,6 +25,9 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
         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>
         agent:
@@ -68,6 +71,38 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 - **Restart**: 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.
 - **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:
+
+```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,
+and server disposal. Heartbeats require a responsive event loop; they cannot
+repair event-loop starvation or guarantee delivery during backpressure.
+
 ## Task stores
 
 A2A task snapshots retain protocol history and artifacts; [dsh-storage](../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.
@@ -84,7 +119,7 @@ dsh ships **no authentication or authorization**. The server binds `127.0.0.1` b
 
 ## Compatibility
 
-Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment}@0.2.0-rc.1` — the attachment store is an optional peer) — check the `TODO(verify)` markers in `src/` before upgrading dsh.
+Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment}@0.2.0-rc.2` — the attachment store is an optional peer) — check the `TODO(verify)` markers in `src/` before upgrading dsh.
 
 ## License
 

package/lib/index.js

@@ -31,6 +31,10 @@ export const Config = Schema.object({
     host: Schema.string().default('127.0.0.1'),
     port: Schema.natural().default(41241),
     basePath: Schema.string().default('/a2a'),
+    heartbeat: Schema.object({
+        enabled: Schema.boolean().default(false),
+        intervalMs: Schema.natural().min(1).max(2_147_483_647).default(15_000),
+    }),
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema.string().default(process.cwd()),
     /**
@@ -131,6 +135,7 @@ export function apply(ctx, config) {
             host: config.host,
             port: config.port,
             basePath: config.basePath,
+            heartbeat: config.heartbeat,
             card: {
                 name: config.card.name,
                 description: config.card.description,

package/lib/server.js

@@ -9,7 +9,7 @@
  *   through the SDK's opt-in legacyCompat layer
  *
  * The SSE framing and error envelopes are the SDK's; this layer only binds
- * the server and builds the card.
+ * the server, builds the card, and optionally adds transport heartbeats.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
@@ -20,6 +20,23 @@ import { DefaultExecutionEventBus, DefaultRequestHandler, ServerCallContext, STA
 import { agentCardHandler, jsonRpcHandler, UserBuilder } from '@a2a-js/sdk/server/express';
 import express from 'express';
 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 = [
@@ -187,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());
@@ -208,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);
@@ -303,6 +320,62 @@ export async function startA2aServer(options) {
     // The SDK's jsonRpcHandler parses bodies with express.json()'s 100kb default;
     // 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) => {
+            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 () {
+                flushHeaders.call(this);
+                if (!String(res.getHeader('content-type')).startsWith('text/event-stream') || timer)
+                    return;
+                timer = setInterval(() => {
+                    if (res.destroyed || res.writableEnded)
+                        return stop();
+                    // A slow client gets no additional heartbeat backlog; retry next tick.
+                    if (res.writableNeedDrain)
+                        return;
+                    try {
+                        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();
+                        console.error('[dsh-a2a] heartbeat write failed:', error);
+                    }
+                }, intervalMs);
+                timer.unref();
+                stopHeartbeats.add(stop);
+                res.once('finish', stop);
+                res.once('close', stop);
+                res.once('error', stop);
+            };
+            let timer;
+            const stop = () => {
+                clearInterval(timer);
+                stopHeartbeats.delete(stop);
+                res.off('finish', stop);
+                res.off('close', stop);
+                res.off('error', stop);
+            };
+            heartbeatTask.run(task, next);
+        });
+    }
     const cardHandler = agentCardHandler({
         agentCardProvider: requestHandler,
         legacyCompat: { enabled: true },
@@ -373,6 +446,8 @@ export async function startA2aServer(options) {
     return {
         port: server.address().port,
         close: () => new Promise((resolve) => {
+            for (const stop of stopHeartbeats)
+                stop();
             server.closeAllConnections?.();
             server.close(() => resolve());
         }),

package/lib/types/index.d.ts

@@ -70,6 +70,13 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     host: Schema<string, string>;
     port: Schema<number, number>;
     basePath: Schema<string, string>;
+    heartbeat: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        intervalMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        intervalMs: Schema<number, number>;
+    }>>;
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema<string, string>;
     /**
@@ -135,6 +142,13 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     host: Schema<string, string>;
     port: Schema<number, number>;
     basePath: Schema<string, string>;
+    heartbeat: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        intervalMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        intervalMs: Schema<number, number>;
+    }>>;
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema<string, string>;
     /**
@@ -201,6 +215,10 @@ export interface A2aPluginConfig {
     host: string;
     port: number;
     basePath: string;
+    heartbeat?: {
+        enabled: boolean;
+        intervalMs: number;
+    };
     cwd: string;
     uploadsDir: string;
     agent: {

package/lib/types/server.d.ts

@@ -9,7 +9,7 @@
  *   through the SDK's opt-in legacyCompat layer
  *
  * The SSE framing and error envelopes are the SDK's; this layer only binds
- * the server and builds the card.
+ * the server, builds the card, and optionally adds transport heartbeats.
  */
 import { type Message } from '@a2a-js/sdk';
 import { type AgentExecutor, type TaskStore } from '@a2a-js/sdk/server';
@@ -26,6 +26,10 @@ export interface A2aServerOptions {
     };
     executor: AgentExecutor;
     taskStore: TaskStore;
+    heartbeat?: {
+        enabled: boolean;
+        intervalMs: number;
+    };
     approvalGuard?: (message: Message) => undefined | (() => void);
     beforeWorkingTaskMessage?: (message: Message, requestHeaders: unknown) => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.17",
+  "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",
@@ -62,12 +62,12 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
     "@google-cloud/storage": "^7.0.0",
     "@types/express": "^4.17.21",
     "@types/node": "^22.0.0",