@amaster.ai/dsh-a2a 0.1.13 → 0.1.15

package/README.md

@@ -55,7 +55,8 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 ## Behavior notes
 
 - **One task = one dsh session.** The A2A `contextId` IS the dsh session id. By default, a completed turn ends `input-required`, not `completed` — the task is a conversation and stays continuable; `CancelTask` and turn errors are terminal (`canceled` / `failed`), and the SDK rejects follow-ups addressed at a terminal `taskId` (send with only the `contextId` to continue the session under a fresh task id).
-- **Host admission and settlement.** `ctx.on('a2a/before-followup', async (detail) => { ... })` runs before the user message enters the agent inbox. Its detail contains `agent`, `contextId`, `taskId`, the original `a2aMessage`, `dshMessageId`, `requestHeaders`, and an abort `signal`; 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 existing `a2a/message-admitted` event remains an observational tap after insertion. A host can register `ctx.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.
+- **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 contains `agent`, `contextId`, `taskId`, the original `a2aMessage` (including its `messageId`), `requestHeaders`, and an abort `signal`; 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 contains `agent`, `contextId`, `taskId`, the original `a2aMessage`, `dshMessageId`, `requestHeaders`, and an abort `signal`; 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 existing `a2a/message-admitted` event remains an observational tap after insertion. A host can register `ctx.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.preset` pins 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 separate `messageId` and are marked `metadata.dshAgent.kind: 'thought'`. The turn-final event's message carries the full assembled text, so blocking `SendMessage` clients read the answer from `result.task.status.message`. Tool calls/results are data parts marked `tool-call` / `tool-result`; token usage lands in `metadata.usage` of the final event. A2A 1.0 has no `final` flag — 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. 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 under `uploadsDir` (default `<OS temp>/dsh-a2a-uploads/<date>/`, names sanitized cross-platform, collisions suffixed), 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. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.

package/lib/bridge.js

@@ -96,6 +96,7 @@ export class A2aBridge {
             // A turn still open from the previous binding (e.g. a cancel whose abort
             // is still propagating) must not emit events under the new task id.
             forContext.interrupted = false;
+            forContext.terminalState = undefined;
             this.tasks.set(taskId, forContext);
             return { entry: forContext, freshTask: true };
         }
@@ -155,6 +156,7 @@ export class A2aBridge {
             staleTurn: false,
             settled: [],
             running: new Set(),
+            pendingMessageAborts: new Set(),
             settlementAbort: new AbortController(),
             settling: false,
             interrupted: false,
@@ -243,6 +245,38 @@ export class A2aBridge {
     async waitForTurn(entry) {
         await Promise.allSettled([...entry.running]);
     }
+    /** Inspect a message for a live task before the SDK starts its next request. */
+    async beforeWorkingTaskMessage(a2aMessage, requestHeaders) {
+        const entry = this.tasks.get(a2aMessage.taskId);
+        if (!entry ||
+            (a2aMessage.contextId && entry.sessionId !== a2aMessage.contextId) ||
+            entry.running.size === 0)
+            return;
+        const pending = new AbortController();
+        entry.pendingMessageAborts.add(pending);
+        try {
+            await Promise.race([
+                this.ctx.serial('a2a/working-task-message', {
+                    agent: entry.handle.agent,
+                    contextId: entry.sessionId,
+                    taskId: entry.taskId,
+                    a2aMessage,
+                    requestHeaders,
+                    signal: pending.signal,
+                }),
+                new Promise((_, reject) => {
+                    const abort = () => reject(new Error('A2A task was interrupted before message admission.'));
+                    if (pending.signal.aborted)
+                        abort();
+                    else
+                        pending.signal.addEventListener('abort', abort, { once: true });
+                }),
+            ]);
+        }
+        finally {
+            entry.pendingMessageAborts.delete(pending);
+        }
+    }
     /** Include content preparation in the work a context clear must drain. */
     async trackExecution(contextId, run) {
         const execution = run();
@@ -265,10 +299,18 @@ export class A2aBridge {
     async runTurn(entry, content, bus, taskId, a2aMessage, requestHeaders) {
         const previous = [...entry.running];
         const running = (async () => {
+            if (entry.interrupted || entry.taskId !== taskId || this.tasks.get(taskId) !== entry) {
+                bus.publish(terminalStatusUpdate(taskId, entry.sessionId, 'canceled', 'Task interrupted.'));
+                return;
+            }
             await Promise.allSettled(previous);
             if (this.clearing.has(entry.sessionId))
                 throw new Error('Context is being cleared.');
-            if (entry.interrupted || entry.taskId !== taskId) {
+            if (entry.terminalState) {
+                bus.publish(terminalStatusUpdate(taskId, entry.sessionId, entry.terminalState, 'Task ended.'));
+                return;
+            }
+            if (entry.interrupted || entry.taskId !== taskId || this.tasks.get(taskId) !== entry) {
                 bus.publish(terminalStatusUpdate(taskId, entry.sessionId, 'canceled', 'Task interrupted.'));
                 return;
             }
@@ -278,8 +320,14 @@ export class A2aBridge {
         try {
             await running;
         }
+        catch (error) {
+            entry.terminalState = 'failed';
+            throw error;
+        }
         finally {
             entry.running.delete(running);
+            if (entry.running.size === 0)
+                entry.terminalState = undefined;
         }
     }
     async runTurnInner(entry, content, bus, taskId, a2aMessage, requestHeaders) {
@@ -350,6 +398,7 @@ export class A2aBridge {
                 // unhandled rejection would crash the host process, and no turn/end
                 // would ever settle this waiter.
                 void Promise.resolve(result).catch((error) => {
+                    entry.terminalState = 'failed';
                     const message = error instanceof Error ? error.message : String(error);
                     console.error('[dsh-a2a] followup failed:', error);
                     const index = entry.settled.indexOf(resolveSettled);
@@ -511,6 +560,7 @@ export class A2aBridge {
                             .catch((error) => {
                             if (entry.bus !== bus || entry.taskId !== taskId)
                                 return;
+                            entry.terminalState = 'failed';
                             const message = error instanceof Error ? error.message : String(error);
                             console.error('[dsh-a2a] task settlement failed:', error);
                             bus.publish(terminalStatusUpdate(taskId, entry.sessionId, 'failed', message));
@@ -529,6 +579,7 @@ export class A2aBridge {
             console.error('[dsh-a2a] failed to translate session event:', error);
             if (event.type === 'turn/end' &&
                 (event.data.reason.kind === 'completed' || event.data.reason.kind === 'max-tokens')) {
+                entry.terminalState = 'failed';
                 entry.bus?.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'failed', 'Failed to translate agent turn.'));
                 entry.bus = null;
                 entry.settlementAbort.abort();
@@ -536,6 +587,10 @@ export class A2aBridge {
             }
         }
         if (event.type === 'turn/end') {
+            if (event.data.reason.kind === 'blocked' || event.data.reason.kind === 'error')
+                entry.terminalState = 'failed';
+            if (event.data.reason.kind === 'aborted')
+                entry.terminalState = 'canceled';
             this.withdrawApprovals(entry);
             this.asked.delete(session.id);
             entry.turnActive = false;
@@ -576,6 +631,8 @@ export class A2aBridge {
     /** Close an in-flight stream honestly and release every turn waiter. */
     settleEntry(entry, message) {
         entry.interrupted = true;
+        for (const pending of entry.pendingMessageAborts)
+            pending.abort();
         entry.admissionAbort?.abort();
         entry.settlementAbort.abort();
         this.withdrawApprovals(entry);

package/lib/index.js

@@ -140,6 +140,7 @@ export function apply(ctx, config) {
             executor,
             taskStore: store,
             approvalGuard: (message) => bridge.reserveApprovalMessage(message),
+            beforeWorkingTaskMessage: (message, headers) => bridge.beforeWorkingTaskMessage(message, headers),
         });
         serverPort = server.port;
         console.log(`[dsh-a2a] A2A endpoint: http://${config.host}:${server.port}${config.basePath}/ ` +

package/lib/server.js

@@ -11,11 +11,12 @@
  * The SSE framing and error envelopes are the SDK's; this layer only binds
  * the server and builds the card.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { A2A_PROTOCOL_VERSION, AGENT_CARD_PATH, TaskState, } from '@a2a-js/sdk';
 import { duplicateInterfacesForLegacy } from '@a2a-js/sdk/compat/v0_3';
 import { RequestMalformedError } from '@a2a-js/sdk/errors';
-import { DefaultRequestHandler, ServerCallContext, } from '@a2a-js/sdk/server';
+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';
 export async function startA2aServer(options) {
@@ -60,11 +61,71 @@ export async function startA2aServer(options) {
             throw new RequestMalformedError(error instanceof Error ? error.message : String(error));
         }
     };
+    // SDK's default manager gives concurrent sends one bus. Give each send its
+    // own bus while forwarding events to a stable task bus for resubscribe/cancel.
+    const approvalReply = new AsyncLocalStorage();
+    const taskBuses = new Map();
+    const busManager = {
+        createOrGetByTaskId(taskId) {
+            let task = taskBuses.get(taskId);
+            if (!task) {
+                const broadcast = new DefaultExecutionEventBus();
+                task = { broadcast, requests: new Set() };
+                taskBuses.set(taskId, task);
+                broadcast.on('event', (event) => {
+                    const state = event.kind === 'statusUpdate' ? event.data.status?.state : undefined;
+                    if (state !== undefined &&
+                        [
+                            TaskState.TASK_STATE_COMPLETED,
+                            TaskState.TASK_STATE_FAILED,
+                            TaskState.TASK_STATE_CANCELED,
+                            TaskState.TASK_STATE_REJECTED,
+                        ].includes(state))
+                        queueMicrotask(() => broadcast.finished());
+                });
+            }
+            if (approvalReply.getStore()) {
+                const active = task.requests.values().next().value;
+                if (active)
+                    return active;
+            }
+            const requestBus = new DefaultExecutionEventBus();
+            task.requests.add(requestBus);
+            requestBus.on('event', (event) => task.broadcast.publish(event));
+            requestBus.on('finished', () => task.requests.delete(requestBus));
+            return requestBus;
+        },
+        getByTaskId: (taskId) => taskBuses.get(taskId)?.broadcast,
+        cleanupByTaskId(taskId) {
+            const task = taskBuses.get(taskId);
+            task?.broadcast.finished();
+            task?.broadcast.removeAllListeners();
+            taskBuses.delete(taskId);
+        },
+    };
+    const beforeWorkingTaskMessage = async (message, context) => {
+        if (!message?.taskId)
+            return;
+        // Validate through the scoped store before a host hook can affect a live task.
+        const task = await options.taskStore.load(message.taskId, context);
+        if (!task ||
+            task.status?.state !== TaskState.TASK_STATE_WORKING ||
+            (message.contextId && message.contextId !== task.contextId))
+            return;
+        try {
+            await options.beforeWorkingTaskMessage?.(message, context.state.get(STATE_HEADERS_KEY));
+        }
+        catch (error) {
+            throw new RequestMalformedError(error instanceof Error ? error.message : String(error));
+        }
+    };
     const requestHandler = new (class extends DefaultRequestHandler {
         async sendMessage(...args) {
             const release = guardApproval(args[0].message);
             try {
-                return await super.sendMessage(...args);
+                if (!release)
+                    await beforeWorkingTaskMessage(args[0].message, args[1]);
+                return await approvalReply.run(Boolean(release), () => super.sendMessage(...args));
             }
             finally {
                 release?.();
@@ -73,13 +134,27 @@ export async function startA2aServer(options) {
         async *sendMessageStream(...args) {
             const release = guardApproval(args[0].message);
             try {
-                yield* super.sendMessageStream(...args);
+                if (!release)
+                    await beforeWorkingTaskMessage(args[0].message, args[1]);
+                const stream = super.sendMessageStream(...args);
+                try {
+                    if (release) {
+                        const first = await approvalReply.run(true, () => stream.next());
+                        if (!first.done)
+                            yield first.value;
+                    }
+                    yield* stream;
+                }
+                finally {
+                    if (release)
+                        await stream.return(undefined);
+                }
             }
             finally {
                 release?.();
             }
         }
-    })(card, options.taskStore, options.executor);
+    })(card, options.taskStore, options.executor, busManager);
     const app = express();
     // 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.

package/lib/types/bridge.d.ts

@@ -48,11 +48,13 @@ export interface TaskEntry {
     settled: Array<() => void>;
     /** Active execute() calls that must finish before task shells are deleted. */
     running: Set<Promise<void>>;
+    pendingMessageAborts: Set<AbortController>;
     admissionAbort?: AbortController;
     settlementAbort: AbortController;
     settling: boolean;
     lastFinal?: AgentExecutionEvent;
     interrupted: boolean;
+    terminalState?: 'failed' | 'canceled';
 }
 export declare class A2aBridge {
     private readonly ctx;
@@ -92,6 +94,8 @@ export declare class A2aBridge {
     };
     private findApproval;
     waitForTurn(entry: TaskEntry): Promise<void>;
+    /** Inspect a message for a live task before the SDK starts its next request. */
+    beforeWorkingTaskMessage(a2aMessage: Message, requestHeaders: unknown): Promise<void>;
     /** Include content preparation in the work a context clear must drain. */
     trackExecution(contextId: string, run: () => Promise<void>): Promise<void>;
     /** Queue one user-message turn on the task's agent and await its `turn/end`. */

package/lib/types/index.d.ts

@@ -30,8 +30,18 @@ export interface A2aTurnContext {
     requestHeaders: unknown;
     signal: AbortSignal;
 }
+export interface A2aWorkingTaskMessageContext {
+    agent: Agent;
+    contextId: string;
+    taskId: string;
+    a2aMessage: Message;
+    requestHeaders: unknown;
+    signal: AbortSignal;
+}
 declare module '@deepseek-ai/cordis' {
     interface Events {
+        /** Awaited for a message targeting a running task, before waiting for its prior execution. */
+        'a2a/working-task-message'(detail: A2aWorkingTaskMessageContext): void;
         /** Awaited before inbox insertion; failure rejects the A2A request. */
         'a2a/before-followup'(detail: A2aTurnContext): void;
         /** Await host-owned continuation work before closing this task. */

package/lib/types/server.d.ts

@@ -27,6 +27,7 @@ export interface A2aServerOptions {
     executor: AgentExecutor;
     taskStore: TaskStore;
     approvalGuard?: (message: Message) => undefined | (() => void);
+    beforeWorkingTaskMessage?: (message: Message, requestHeaders: unknown) => Promise<void>;
 }
 export interface A2aServer {
     /** The bound port (differs from options.port when 0). */

package/package.json

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