@amaster.ai/dsh-a2a 0.1.17 → 0.1.18

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 transport keepalive comments
+          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,28 @@ 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 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
+`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 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 +109,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,11 @@ 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 base = options.basePath.replace(/\/$/, '');
     const publicUrl = (options.card.publicUrl ?? `http://${options.host}:${options.port}`).replace(/\/$/, '');
     const interfaces = [
@@ -303,6 +308,45 @@ 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 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 {
+                        res.write(': heartbeat\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);
+            };
+            next();
+        });
+    }
     const cardHandler = agentCardHandler({
         agentCardProvider: requestHandler,
         legacyCompat: { enabled: true },
@@ -373,6 +417,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.18",
   "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",