@amaster.ai/dsh-a2a 0.1.24 → 0.1.26

package/lib/index.js

@@ -16,17 +16,20 @@ import { ServerCallContext } from '@a2a-js/sdk/server';
 import Schema from '@deepseek-ai/schemastery';
 import { A2aBridge } from './bridge.js';
 import { DshAgentExecutor } from './executor.js';
+import { INBOX_EXTENSION, NativeInbox } from './inbox.js';
 import { startA2aServer } from './server.js';
 import { GcsTaskStore } from './stores/gcs.js';
 import { RedisTaskStore } from './stores/redis.js';
 import { MemoryTaskStore, SanitizedTaskStore } from './task-store.js';
 export { defaultApprovalCodec } from './approval.js';
+export { INBOX_EXTENSION } from './inbox.js';
 /** Event emitted when one A2A user message enters the dsh inbox. */
 export const A2A_MESSAGE_ADMITTED_EVENT = 'a2a/message-admitted';
 export const name = 'dsh-a2a';
 /** The bridge creates and owns agents through the registry service. */
 export const inject = ['agents'];
 export const Config = Schema.object({
+    inbox: Schema.object({ enabled: Schema.boolean().default(false) }).description('Use durable native inbox execution (requires the upstream native inbox capability).'),
     enabled: Schema.boolean().default(false),
     host: Schema.string().default('127.0.0.1'),
     port: Schema.natural().default(41241),
@@ -108,7 +111,10 @@ export function apply(ctx, config) {
             subagentTools: config.subagentTools,
         });
         const store = createTaskStore(config);
+        const inbox = config.inbox?.enabled ? new NativeInbox(ctx, bridge, store) : undefined;
         await store.init?.();
+        if (inbox)
+            ctx.provide('a2aInbox', inbox);
         ctx.provide('a2aTasks', {
             async clearContext(contextId, tenant = '') {
                 const call = new ServerCallContext({ tenant });
@@ -136,6 +142,16 @@ export function apply(ctx, config) {
         });
         const executor = new DshAgentExecutor(bridge, (taskId) => store.suppress(taskId));
         const server = await startA2aServer({
+            extensions: inbox
+                ? [
+                    {
+                        uri: INBOX_EXTENSION,
+                        description: 'Native inbox steering and parked admission',
+                        required: false,
+                        params: undefined,
+                    },
+                ]
+                : [],
             host: config.host,
             port: config.port,
             basePath: config.basePath,
@@ -148,16 +164,35 @@ export function apply(ctx, config) {
             },
             executor,
             taskStore: store,
+            beforeMessage: inbox
+                ? (message, context) => inbox.beforeMessage(message, context)
+                : undefined,
+            beforeTask: inbox ? (taskId, context) => inbox.beforeTask(taskId, context) : undefined,
             approvalGuard: (message) => bridge.reserveApprovalMessage(message),
             beforeWorkingTaskMessage: (message, headers) => bridge.beforeWorkingTaskMessage(message, headers),
         });
         serverPort = server.port;
+        if (inbox)
+            inbox.server = server;
         console.log(`[dsh-a2a] A2A endpoint: http://${config.host}:${server.port}${config.basePath}/ ` +
             `(agent card: /.well-known/agent-card.json)`);
         return async () => {
-            await server.close();
-            await bridge.dispose();
-            await store.close?.();
+            const failures = [];
+            for (const cleanup of [
+                () => inbox?.shutdown(),
+                () => server.close(),
+                () => bridge.dispose(),
+                () => store.close?.(),
+            ]) {
+                try {
+                    await cleanup();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length)
+                throw new AggregateError(failures, 'A2A shutdown failed.');
         };
     }
 }

package/lib/legacy-stream.js

@@ -62,7 +62,7 @@ export function legacyStreamHandler(requestHandler) {
                     return;
                 for await (const event of stream) {
                     if (res.destroyed)
-                        break;
+                        continue; // Keep the SDK consuming results after its client leaves.
                     if (write(event))
                         return;
                 }

package/lib/server.js

@@ -16,7 +16,7 @@ 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 { DefaultExecutionEventBus, DefaultRequestHandler, ServerCallContext, STATE_HEADERS_KEY, } from '@a2a-js/sdk/server';
+import { DefaultExecutionEventBus, DefaultRequestHandler, ExecutionEventQueue, ResultManager, 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';
@@ -59,7 +59,7 @@ export async function startA2aServer(options) {
         capabilities: {
             streaming: true,
             pushNotifications: false,
-            extensions: [],
+            extensions: options.extensions ?? [],
             extendedAgentCard: false,
         },
         securitySchemes: {},
@@ -189,22 +189,39 @@ export async function startA2aServer(options) {
         }
     };
     const requestHandler = new (class extends DefaultRequestHandler {
+        async beforeMessage(message, context) {
+            if (!message)
+                return;
+            try {
+                return await options.beforeMessage?.(message, context);
+            }
+            catch (error) {
+                throw new RequestMalformedError(error instanceof Error ? error.message : String(error));
+            }
+        }
         async sendMessage(...args) {
             const release = guardApproval(args[0].message);
+            let releaseAdmission;
             try {
                 if (!release)
                     await beforeWorkingTaskMessage(args[0].message, args[1]);
+                if (!release)
+                    releaseAdmission = await this.beforeMessage(args[0].message, args[1]);
                 return await approvalReply.run(Boolean(release), () => super.sendMessage(...args));
             }
             finally {
+                releaseAdmission?.();
                 release?.();
             }
         }
         async *sendMessageStream(...args) {
             const release = guardApproval(args[0].message);
+            let releaseAdmission;
             try {
                 if (!release)
                     await beforeWorkingTaskMessage(args[0].message, args[1]);
+                if (!release)
+                    releaseAdmission = await this.beforeMessage(args[0].message, args[1]);
                 const stream = observeTask(super.sendMessageStream(...args));
                 try {
                     if (release) {
@@ -220,10 +237,16 @@ export async function startA2aServer(options) {
                 }
             }
             finally {
+                releaseAdmission?.();
                 release?.();
             }
         }
+        async cancelTask(...args) {
+            await options.beforeTask?.(args[0].id, args[1]);
+            return super.cancelTask(...args);
+        }
         async *resubscribe(...args) {
+            await options.beforeTask?.(args[0].id, args[1]);
             const task = taskBuses.get(args[0].id);
             if (!task) {
                 yield* observeTask(super.resubscribe(...args));
@@ -445,6 +468,24 @@ export async function startA2aServer(options) {
         server.listen(options.port, options.host, () => resolve());
     });
     return {
+        restoreTask(task, context) {
+            const bus = busManager.createOrGetByTaskId(task.id);
+            const queue = new ExecutionEventQueue(bus);
+            const result = new ResultManager(options.taskStore, context);
+            void (async () => {
+                try {
+                    for await (const event of queue.events())
+                        await result.processEvent(event);
+                }
+                catch (error) {
+                    console.error('[dsh-a2a] restored task persistence failed:', error);
+                }
+                finally {
+                    queue.stop();
+                }
+            })();
+            return bus;
+        },
         port: server.address().port,
         close: () => new Promise((resolve) => {
             for (const stop of stopHeartbeats)

package/lib/task-store.js

@@ -63,6 +63,8 @@ export class SanitizedTaskStore {
     inner;
     lastState = new Map();
     writes = new Map();
+    // Terminal task ids stay guarded until unload, like deleted-id tombstones.
+    terminalStates = new Map();
     liveHistory = new Map();
     // ponytail: deleted ids stay tombstoned until plugin unload; use expiring ids if clear volume grows.
     deleted = new Set();
@@ -73,6 +75,11 @@ export class SanitizedTaskStore {
         await this.inner.init?.();
     }
     async close() {
+        let pending;
+        do {
+            pending = [...this.writes.values()];
+            await Promise.all(pending);
+        } while ([...this.writes.values()].some((write) => !pending.includes(write)));
         this.liveHistory.clear();
         await this.inner.close?.();
     }
@@ -88,9 +95,24 @@ export class SanitizedTaskStore {
         this.lastState.delete(taskId);
         this.writes.delete(taskId);
     }
-    async save(task, context) {
+    checkpoint(task, context) {
+        return this.save(task, context, true);
+    }
+    async save(task, context, checkpoint = false) {
         if (this.deleted.has(task.id))
             return;
+        const state = task.status?.state;
+        const terminal = this.terminalStates.get(task.id);
+        if (terminal !== undefined && state !== terminal)
+            return;
+        if (state !== undefined &&
+            [
+                TaskState.TASK_STATE_COMPLETED,
+                TaskState.TASK_STATE_CANCELED,
+                TaskState.TASK_STATE_FAILED,
+                TaskState.TASK_STATE_REJECTED,
+            ].includes(state))
+            this.terminalStates.set(task.id, state);
         const history = structuredClone(task.history ?? []);
         const current = task.status?.message;
         if (task.status?.state === TaskState.TASK_STATE_WORKING && current) {
@@ -120,23 +142,35 @@ export class SanitizedTaskStore {
             else
                 history.push(final);
         }
-        this.liveHistory.set(task.id, {
-            scope: scopeOf(context),
-            history,
-        });
-        const state = task.status?.state;
-        if (state !== undefined && this.lastState.get(task.id) === state)
+        const previousHistory = this.liveHistory.get(task.id);
+        const live = { scope: scopeOf(context), history };
+        this.liveHistory.set(task.id, live);
+        if (!checkpoint && state !== undefined && this.lastState.get(task.id) === state)
             return;
         const write = (this.writes.get(task.id) ?? Promise.resolve()).then(() => this.inner.save(sanitizeTask({ ...task, history }), context));
-        this.writes.set(task.id, write.catch(() => { }));
-        await write;
+        const tail = write.catch(() => { });
+        this.writes.set(task.id, tail);
+        try {
+            await write;
+        }
+        catch (error) {
+            if (this.liveHistory.get(task.id) === live) {
+                if (previousHistory)
+                    this.liveHistory.set(task.id, previousHistory);
+                else
+                    this.liveHistory.delete(task.id);
+            }
+            throw error;
+        }
         if (state === TaskState.TASK_STATE_WORKING || state === TaskState.TASK_STATE_SUBMITTED) {
             this.lastState.set(task.id, state);
         }
         else {
-            this.lastState.delete(task.id);
-            this.writes.delete(task.id);
-            this.liveHistory.delete(task.id);
+            if (this.writes.get(task.id) === tail) {
+                this.lastState.delete(task.id);
+                this.writes.delete(task.id);
+                this.liveHistory.delete(task.id);
+            }
         }
     }
     async load(taskId, context) {

package/lib/types/bridge.d.ts

@@ -19,6 +19,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { AgentHandle } from '@deepseek-ai/dsh-agent';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
 import { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { NativeInbox } from './inbox.js';
 import { SessionTranslator } from './translator.js';
 export interface BridgeOptions {
     /** Absolute working directory for spawned agents. */
@@ -63,6 +64,7 @@ export interface TaskEntry {
 export declare class A2aBridge {
     private readonly ctx;
     private readonly options;
+    inbox?: NativeInbox;
     private readonly tasks;
     private readonly bySession;
     private readonly clearing;
@@ -100,6 +102,8 @@ export declare class A2aBridge {
     };
     private findApproval;
     waitForTurn(entry: TaskEntry): Promise<void>;
+    /** The native inbox selects task ownership before assembling its first prompt. */
+    bindInboxTask(entry: TaskEntry, taskId: string, translator: SessionTranslator, bus: ExecutionEventBus, completion: Promise<void>, controller: AbortController): 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. */

package/lib/types/inbox.d.ts

@@ -0,0 +1,149 @@
+import { Message } from '@a2a-js/sdk';
+import { type ExecutionEventBus, type RequestContext, ServerCallContext } from '@a2a-js/sdk/server';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AssistantStreamFrame, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm/types';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { A2aBridge } from './bridge.js';
+import type { A2aTurnContext } from './index.js';
+import type { A2aServer } from './server.js';
+import type { ManagedTaskStore } from './task-store.js';
+export declare const INBOX_EXTENSION = "https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md";
+export interface A2aInboxEvent {
+    phase: string;
+    contextId: string;
+    at: number;
+    pending: number;
+    target?: 'next-turn' | 'next-step';
+    input?: string;
+    position?: number;
+    paused?: boolean;
+    agentStatus?: string;
+    taskId?: string;
+    taskIds?: string[];
+    messageId?: string;
+    referenceTaskIds?: string[];
+    nativeMessageId?: string;
+    queuedAt?: number;
+    selectedAt?: number;
+    turn?: number;
+    step?: number;
+}
+interface InboxSource {
+    kind: 'a2a';
+    taskId: string;
+    /** JSON encoding removes protobuf optional undefined fields before durable admission. */
+    message: string;
+    target: InboxTarget;
+    queuedAt?: number;
+}
+declare module '@deepseek-ai/dsh-llm/types' {
+    interface MessageSourceMap {
+        a2a: InboxSource;
+    }
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'agent/inbox/paused': {
+            paused: boolean;
+        };
+    }
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /** Native inbox lifecycle; content consumers must honor their capture settings. */
+        'a2a/inbox'(detail: A2aInboxEvent): void;
+        'agent/before-assembly'(detail: {
+            agent: Agent;
+            messages: UserMessage[];
+            turn: number;
+            step: number;
+            signal: AbortSignal;
+        }): void | Promise<void>;
+        /** Selected input, before system-prompt assembly; restored input has no original headers. */
+        'a2a/before-assembly'(detail: A2aTurnContext): void | Promise<void>;
+    }
+}
+/** Same-process queue control; wire messages and task subscriptions remain standard A2A. */
+export interface A2aInbox {
+    resolve(contextId: string): Promise<Agent>;
+    content(message: Message, contextId: string): Promise<ContentBlock[]>;
+    /** Admit a same-process host follow-up under an existing task's durable identity. */
+    enqueue(taskId: string, message: Message, options?: {
+        target?: InboxTarget;
+        wakeup?: boolean;
+    }): Promise<void>;
+    pause(contextId: string): Promise<void>;
+    /** Cancellation is terminal; retained pending input stays paused until explicit resume. */
+    cancel(taskId: string, options?: {
+        retainInbox?: boolean;
+    }): Promise<string | undefined>;
+    /** Recovery does not override a persisted pause unless resume is explicitly true. */
+    wake(contextId: string, options?: {
+        resume?: boolean;
+        context?: ServerCallContext;
+    }): Promise<string[]>;
+}
+/** Fold native input mutations; a claimed input is recoverable only before user/message. */
+export declare function recoverInbox(events: readonly SessionEvent[]): {
+    paused: boolean;
+    pending: UserMessage[];
+    committed: Set<string>;
+};
+export declare class NativeInbox implements A2aInbox {
+    private readonly ctx;
+    private readonly bridge;
+    private readonly store;
+    private readonly contexts;
+    private readonly resolving;
+    private stopping;
+    private shutdownPromise?;
+    private readonly waking;
+    private readonly preadmitted;
+    server?: A2aServer;
+    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore);
+    content(message: Message, contextId: string): Promise<ContentBlock[]>;
+    resolve(contextId: string): Promise<Agent>;
+    enqueue(taskId: string, message: Message, options?: {
+        target?: InboxTarget;
+        wakeup?: boolean;
+    }): Promise<void>;
+    private context;
+    private observe;
+    private observeInput;
+    private flush;
+    private checkpoint;
+    private pending;
+    private task;
+    private controls;
+    /** Reject follow-up admission at the request boundary, without terminating accepted work. */
+    beforeMessage(message: Message, context: ServerCallContext): Promise<undefined | (() => void)>;
+    /** Reattach a cold task before the SDK decides whether cancellation has a live executor. */
+    beforeTask(taskId: string, context: ServerCallContext): Promise<void>;
+    private outcome;
+    private terminal;
+    private admit;
+    execute(request: RequestContext, bus: ExecutionEventBus): Promise<void>;
+    private restoreTask;
+    private drive;
+    private prepare;
+    private publish;
+    onSessionEvent(session: Session, event: SessionEvent): boolean;
+    private settle;
+    onAssistantStream(agent: Agent, frame: AssistantStreamFrame): boolean;
+    private fail;
+    pause(contextId: string): Promise<void>;
+    wake(contextId: string, options?: {
+        resume?: boolean;
+        context?: ServerCallContext;
+    }): Promise<string[]>;
+    private wakeInner;
+    cancel(taskId: string, options?: {
+        retainInbox?: boolean;
+    }): Promise<string | undefined>;
+    private cancelTask;
+    clear(contextId: string): Promise<void>;
+    onDisposed(session: Session): void;
+    shutdown(): Promise<void>;
+}
+export {};

package/lib/types/index.d.ts

@@ -19,6 +19,8 @@ import Schema from '@deepseek-ai/schemastery';
 export type { A2aApproval, A2aApprovalCodec, A2aApprovalReply } from './approval.js';
 export { defaultApprovalCodec } from './approval.js';
 export type { A2aFileMaterializer } from './content.js';
+export type { A2aInbox, A2aInboxEvent } from './inbox.js';
+export { INBOX_EXTENSION } from './inbox.js';
 export type { SubagentToolSource } from './translator.js';
 /** Event emitted when one A2A user message enters the dsh inbox. */
 export declare const A2A_MESSAGE_ADMITTED_EVENT: "a2a/message-admitted";
@@ -67,6 +69,11 @@ export declare const name = "dsh-a2a";
 /** The bridge creates and owns agents through the registry service. */
 export declare const inject: string[];
 export declare const Config: Schema<Schemastery.ObjectS<{
+    inbox: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
     port: Schema<number, number>;
@@ -144,6 +151,11 @@ export declare const Config: Schema<Schemastery.ObjectS<{
         keyFilename: Schema<string, string>;
     }>>;
 }>, Schemastery.ObjectT<{
+    inbox: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
     port: Schema<number, number>;
@@ -222,6 +234,9 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     }>>;
 }>>;
 export interface A2aPluginConfig {
+    inbox?: {
+        enabled: boolean;
+    };
     enabled: boolean;
     host: string;
     port: number;

package/lib/types/server.d.ts

@@ -11,9 +11,10 @@
  * The SSE framing and error envelopes are the SDK's; this layer only binds
  * 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';
+import { type AgentExtension, type Message, type Task } from '@a2a-js/sdk';
+import { type AgentExecutor, DefaultExecutionEventBus, ServerCallContext, type TaskStore } from '@a2a-js/sdk/server';
 export interface A2aServerOptions {
+    extensions?: AgentExtension[];
     host: string;
     port: number;
     basePath: string;
@@ -32,8 +33,12 @@ export interface A2aServerOptions {
     };
     approvalGuard?: (message: Message) => undefined | (() => void);
     beforeWorkingTaskMessage?: (message: Message, requestHeaders: unknown) => Promise<void>;
+    beforeMessage?: (message: Message, context: ServerCallContext) => Promise<undefined | (() => void)>;
+    beforeTask?: (taskId: string, context: ServerCallContext) => Promise<void>;
 }
 export interface A2aServer {
+    /** Reattach persistence and task subscriptions without admitting another message. */
+    restoreTask(task: Task, context: ServerCallContext): DefaultExecutionEventBus;
     /** The bound port (differs from options.port when 0). */
     port: number;
     close(): Promise<void>;

package/lib/types/task-store.d.ts

@@ -21,6 +21,8 @@ import { type ServerCallContext, type TaskStore } from '@a2a-js/sdk/server';
 export declare function sanitizeTask(task: Task): Task;
 /** TaskStore with the optional lifecycle our backends add. */
 export interface ManagedTaskStore extends TaskStore {
+    /** Durable admission checkpoint even when task state has not changed. */
+    checkpoint?(task: Task, context: ServerCallContext): Promise<void>;
     init?(): Promise<void>;
     delete(taskId: string, context: ServerCallContext): Promise<void>;
     close?(): Promise<void>;
@@ -41,6 +43,7 @@ export declare class SanitizedTaskStore implements ManagedTaskStore {
     private readonly inner;
     private readonly lastState;
     private readonly writes;
+    private readonly terminalStates;
     private readonly liveHistory;
     private readonly deleted;
     constructor(inner: ManagedTaskStore);
@@ -49,7 +52,8 @@ export declare class SanitizedTaskStore implements ManagedTaskStore {
     /** Drop SDK saves that may arrive after a clear rejects an in-flight request. */
     suppress(taskId: string): void;
     delete(taskId: string, context: ServerCallContext): Promise<void>;
-    save(task: Task, context: ServerCallContext): Promise<void>;
+    checkpoint(task: Task, context: ServerCallContext): Promise<void>;
+    save(task: Task, context: ServerCallContext, checkpoint?: boolean): Promise<void>;
     load(taskId: string, context: ServerCallContext): Promise<Task | undefined>;
     list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
 }

package/package.json

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