@amaster.ai/dsh-a2a 0.1.28 → 0.1.29

package/README.md

@@ -20,7 +20,7 @@ Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and
 
 The same-process `a2aInbox` service exposes `resolve(contextId)`, `content(message, contextId)`, `enqueue(taskId, message, { target?, wakeup? })`, `promote(contextId, nativeMessageId, activeTaskId)`, and `cancel(taskId)`. There is no separate pause, wake-only, resume, or retained-task restart operation. Cancellation is terminal and removes that task's pending input. Other tasks' input is retained according to official DSH cancellation semantics, and may wait for the next waking message. Clearing a context discards all its pending work.
 
-`a2a/before-followup` validates admission; `a2a/before-step` runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal follows the official runtime's cancellation behavior. Durable A2A task snapshots require a filesystem, Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.
+`a2a/before-followup` validates admission; `a2a/before-step` runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal cancels tasks by default; `inbox.shutdown: retain-pending` opts into the retention policy below. Durable A2A task snapshots require a filesystem, Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.
 
 ### Goal rounds
 
@@ -40,14 +40,29 @@ Only an unclaimed, single-message independent task in the same context can be pr
 
 Select `taskStore: filesystem` with `filesystem.root` pointing at a retained directory, and separately enable durable DSH session persistence. Keep queued file materialization on retained storage as well. Each task snapshot is scoped by tenant and user, written to a private temporary file and atomically renamed; no additional service is needed. Use one host writer per directory. Files have no automatic expiry; context clearing deletes task snapshots.
 
-After a crash, the host discovers sessions, calls `a2aInbox.resolve(contextId)` and supplies a real attributed waking input through the normal API. Restored unclaimed inputs keep their original task ownership. Startup scanning and scheduling remain host responsibilities. Explicit cancellation stays terminal and discards only the canceled task's input. This does not promise exactly-once external side effects, replay of consumed input, or graceful-unload retention beyond the official DSH lifecycle.
+After a crash, the host discovers sessions, calls `a2aInbox.resolve(contextId)` and supplies a real attributed waking input through the normal API. Restored unclaimed inputs keep their original task ownership. Startup scanning and scheduling remain host responsibilities. Explicit cancellation stays terminal and discards only the canceled task's input. This does not promise exactly-once external side effects, replay of consumed input, or replay of the interrupted active model call.
 
-The dedicated `E2E (dsh-a2a native ownership / issue-75)` integration job runs these regressions with unmodified npm DSH and scripted model responses. Its Langfuse scenario verifies Goal rounds and promoted input under the original task trace, canceled source ownership, and execution restored after SIGKILL. Same-repository CI also sends the scenario to the configured real Langfuse project and polls its Observations API; fork PRs use the local collector without credentials.
+### Graceful host shutdown
+
+Set `inbox: { enabled: true, shutdown: retain-pending }` on both sides of a restart to retain unclaimed A2A `next-step` and `next-turn` input. Keep durable session persistence, the TaskStore and materialized files on retained storage. This is a host configuration policy, not wire metadata. The default `shutdown: cancel` keeps the existing terminal-on-unload behavior.
+
+Retention tracks normalized native inbox splices, including public edits, reordering, removals and queue moves, then freezes the final pending state when host/plugin unloading begins. It stops the current execution, checkpoints pending input in task snapshot metadata with its order and original native/A2A identities, then closes live request/subscription streams. The extra checkpoint survives the core's later inbox-clearing disposal. A task with pending input stays nonterminal for recovery; an interrupted task with no pending input becomes failed. Reconnect subscriptions after restart: streams are not replayed or carried across processes.
+
+On `a2aInbox.resolve(contextId)`, the plugin restores retained ownership before allowing new input, excludes IDs already committed as `user/message`, and drains the retention checkpoint only after the restored session is durable. Explicit `CancelTask`, `a2aInbox.cancel()` and context clearing remain terminal. Claims already handed to the active execution are not retained, and external tool effects are not exactly-once. The host still owns startup discovery and an attributed waking input; merely resolving a context does not wake it. Persistence/checkpoint errors are reported through the existing shutdown error path; the host must not treat a failed checkpoint as a durable restart barrier.
+
+The dedicated `E2E (dsh-a2a graceful retention)` job covers public plugin disposal, a real SIGTERM child process, repeated restarts, promotion/checkpoint races and terminal cancellation. It also reports recovered tasks to Langfuse and verifies their task/turn/generation ancestry through the real Observations API on same-repository CI.
+
+```sh
+node .github/scripts/check-inbox.mjs -t 'graceful retention'
+DSH_GRACEFUL_RETENTION_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'graceful retention.*reports gracefully recovered'
+```
+
+The dedicated `E2E (dsh-a2a native ownership)` integration job runs these regressions with unmodified npm DSH and scripted model responses. Its Langfuse scenario verifies Goal rounds and promoted input under the original task trace, canceled source ownership, and execution restored after SIGKILL. Same-repository CI also sends the scenario to the configured real Langfuse project and polls its Observations API; fork PRs use the local collector without credentials.
 
 ```sh
-node .github/scripts/check-inbox.mjs -t issue-75
+node .github/scripts/check-inbox.mjs -t 'native ownership'
 # With LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY configured:
-DSH_ISSUE75_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'issue-75.*reports Goal continuation'
+DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'native ownership.*reports Goal continuation'
 ```
 
 ## Configuration

package/lib/inbox.js

@@ -5,21 +5,39 @@ import { AgentEvent, ServerCallContext, STATE_HEADERS_KEY, } from '@a2a-js/sdk/s
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
 import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './translator.js';
 export const INBOX_EXTENSION = 'https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md';
+const RETAINED_INPUTS = `${INBOX_EXTENSION}#retained-inputs`;
 export class NativeInbox {
     ctx;
     bridge;
     store;
+    retainPending;
     contexts = new Map();
     resolving = new Map();
     stopping = false;
     shutdownPromise;
     preadmitted = new WeakMap();
     server;
-    constructor(ctx, bridge, store) {
+    persistence;
+    constructor(ctx, bridge, store, retainPending = false) {
         this.ctx = ctx;
         this.bridge = bridge;
         this.store = store;
+        this.retainPending = retainPending;
         bridge.inbox = this;
+        this.persistence = ctx.get('sessionPersistence');
+        if (retainPending)
+            ctx.on('session/event', (session, event) => {
+                const run = this.contexts.get(session.id);
+                if (!run || event.type !== 'agent/inbox/spliced' || this.stopping || this.unloading())
+                    return;
+                try {
+                    const splice = event.data;
+                    run.retained[splice.target].splice(splice.start, splice.removedCount ?? 0, ...structuredClone(splice.inserted));
+                }
+                catch (error) {
+                    console.error('[dsh-a2a] failed to track pending inbox:', error);
+                }
+            });
         ctx.on('agent/pre-step', async (detail, next) => {
             await this.prepare(detail);
             return next();
@@ -73,6 +91,18 @@ export class NativeInbox {
             }
         });
     }
+    unloading() {
+        // Cordis publishes FiberState as a const enum, without a runtime export.
+        const unloading = 5;
+        for (let fiber = this.ctx.fiber;;) {
+            if (fiber.uid === null || fiber.state === unloading)
+                return true;
+            const parent = fiber.parent.fiber;
+            if (parent === fiber)
+                return false;
+            fiber = parent;
+        }
+    }
     content(message, contextId) {
         return this.bridge.buildContent(message, contextId);
     }
@@ -238,9 +268,14 @@ export class NativeInbox {
             for (const message of event.data.inserted) {
                 if (message.source.kind !== 'a2a' || !message.source.promotedFrom)
                     continue;
+                const previous = transfers.get(message.id);
                 transfers.set(message.id, {
                     message: message,
-                    placed: event.data.target === message.source.target,
+                    // A completed transfer stays complete after later public queue edits.
+                    placed: event.data.target === message.source.target ||
+                        !!(previous?.placed &&
+                            previous.message.source.taskId === message.source.taskId &&
+                            previous.message.source.promotionId === message.source.promotionId),
                 });
             }
         }
@@ -276,6 +311,63 @@ export class NativeInbox {
             await this.checkpoint(former, context);
         }
     }
+    async recoverRetained(run, context) {
+        if (!this.retainPending)
+            return;
+        const agent = run.entry.handle.agent;
+        const committed = new Set(agent.session
+            .snapshotEvents()
+            .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])));
+        const snapshots = [];
+        const inputs = [];
+        let pageToken = '';
+        do {
+            const page = await this.store.list({
+                tenant: '',
+                contextId: agent.session.id,
+                pageSize: 100,
+                pageToken,
+                status: TaskState.TASK_STATE_UNSPECIFIED,
+                statusTimestampAfter: undefined,
+            }, context);
+            for (const task of page.tasks) {
+                const retained = task.metadata?.[RETAINED_INPUTS];
+                if (typeof retained !== 'string')
+                    continue;
+                snapshots.push(task);
+                if (this.terminal(task))
+                    continue;
+                for (const input of JSON.parse(retained)) {
+                    const { message } = input;
+                    if (message.source.kind !== 'a2a' || message.source.taskId !== task.id)
+                        throw new Error('Retained input has invalid task ownership.');
+                    if (!committed.has(message.id))
+                        inputs.push(input);
+                }
+            }
+            pageToken = page.nextPageToken;
+        } while (pageToken);
+        for (const { message, target } of inputs.sort((a, b) => a.position - b.position)) {
+            if (message.source.kind !== 'a2a')
+                continue;
+            const existing = this.pending(run).find((pending) => pending.id === message.id);
+            if (existing) {
+                agent.inbox.replace(message.id, message);
+                const destination = target === 'next-step' ? agent.inbox.nextStep : agent.inbox.nextTurn;
+                if (!destination.some((pending) => pending.id === message.id))
+                    this.moveInput(agent, message, target);
+            }
+            else
+                agent.inbox.append(target, message);
+        }
+        if (!snapshots.length)
+            return;
+        await this.flush(agent.session);
+        for (const task of snapshots) {
+            delete task.metadata[RETAINED_INPUTS];
+            await this.checkpoint(task, context);
+        }
+    }
     context(contextId, context = new ServerCallContext()) {
         if (this.stopping)
             return Promise.reject(new Error('Native inbox is unloading.'));
@@ -294,7 +386,9 @@ export class NativeInbox {
                     admissionTail: Promise.resolve(),
                     promotions: new Map(),
                     rolledBack: new Set(),
+                    retained: { 'next-step': [], 'next-turn': [] },
                 };
+                await this.recoverRetained(run, context);
                 await this.recoverPromotions(run, context);
                 const snapshots = new Map();
                 for (const message of this.pending(run)) {
@@ -311,6 +405,10 @@ export class NativeInbox {
                 await this.flush(entry.handle.agent.session);
                 for (const snapshot of snapshots.values())
                     this.restoreTask(run, snapshot, context);
+                run.retained = structuredClone({
+                    'next-step': [...entry.handle.agent.inbox.nextStep],
+                    'next-turn': [...entry.handle.agent.inbox.nextTurn],
+                });
                 this.contexts.set(contextId, run);
                 this.observe('resolved', run);
                 for (const message of this.pending(run))
@@ -323,7 +421,9 @@ export class NativeInbox {
     }
     observe(phase, run, fields = {}) {
         try {
-            const pending = this.pending(run);
+            const pending = this.stopping && this.retainPending
+                ? [...run.retained['next-step'], ...run.retained['next-turn']]
+                : this.pending(run);
             void this.ctx
                 .parallel('a2a/inbox', {
                 phase,
@@ -627,7 +727,7 @@ export class NativeInbox {
                 bus.publish(task.final);
         }
         catch (error) {
-            if (task?.settled)
+            if (task?.settled || (this.stopping && this.retainPending))
                 return;
             if (task && !ownsTask) {
                 bus.publish(AgentEvent.task(structuredClone(task.task)));
@@ -1004,6 +1104,7 @@ export class NativeInbox {
         ];
         for (const admission of run.admissions)
             admission.abort();
+        run.retained = { 'next-step': [], 'next-turn': [] };
         run.entry.handle.agent.inbox.clear();
         run.entry.handle.agent.cancel({ kind: 'user' });
         await run.entry.handle.agent.whenIdle();
@@ -1020,7 +1121,7 @@ export class NativeInbox {
     }
     onDisposed(session) {
         const run = this.contexts.get(session.id);
-        if (!run)
+        if (!run || (this.retainPending && this.stopping))
             return;
         for (const admission of run.admissions)
             admission.abort();
@@ -1053,7 +1154,7 @@ export class NativeInbox {
                 for (const admission of run.admissions)
                     admission.abort();
                 try {
-                    run.entry.handle.agent.cancel({ kind: 'disposed' });
+                    run.entry.handle.agent.cancel({ kind: 'disposed' }, { keepInbox: this.retainPending });
                 }
                 catch (error) {
                     failures.push(error);
@@ -1065,7 +1166,11 @@ export class NativeInbox {
                     failures.push(error);
                 }
                 try {
-                    await this.flush(run.entry.handle.agent.session);
+                    // The persistence barrier tolerates writers already closed by parallel core teardown.
+                    if (this.retainPending && this.persistence)
+                        await this.persistence.flush();
+                    else
+                        await this.flush(run.entry.handle.agent.session);
                 }
                 catch (error) {
                     failures.push(error);
@@ -1073,8 +1178,40 @@ export class NativeInbox {
                 finally {
                     for (const task of run.tasks.values()) {
                         try {
-                            if (!task.settled)
-                                await this.cancelTask(run, task);
+                            if (!task.settled) {
+                                if (this.retainPending) {
+                                    const committed = new Set(run.entry.handle.agent.session
+                                        .snapshotEvents()
+                                        .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])));
+                                    let position = 0;
+                                    const pending = ['next-step', 'next-turn'].flatMap((target) => run.retained[target].flatMap((message) => {
+                                        const input = { message, target, position: position++ };
+                                        return message.source.kind === 'a2a' &&
+                                            message.source.taskId === task.task.id &&
+                                            !committed.has(message.id)
+                                            ? [input]
+                                            : [];
+                                    }));
+                                    if (pending.length) {
+                                        task.task.metadata = {
+                                            ...task.task.metadata,
+                                            [RETAINED_INPUTS]: JSON.stringify(pending),
+                                        };
+                                        await this.checkpoint(structuredClone(task.task), task.context);
+                                    }
+                                    else {
+                                        task.final = terminalStatusUpdate(task.task.id, run.entry.sessionId, 'failed', 'Host stopped; active input will not be replayed.');
+                                        if (task.final.kind === 'statusUpdate')
+                                            task.task.status = task.final.data.status;
+                                        await this.checkpoint(structuredClone(task.task), task.context);
+                                        task.bus.publish(task.final);
+                                    }
+                                    task.settled = true;
+                                    task.controller.abort();
+                                }
+                                else
+                                    await this.cancelTask(run, task);
+                            }
                         }
                         catch (error) {
                             failures.push(error);

package/lib/index.js

@@ -30,7 +30,10 @@ 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 the official DSH inbox for queued turns and steering.'),
+    inbox: Schema.object({
+        enabled: Schema.boolean().default(false),
+        shutdown: Schema.union([Schema.const('cancel'), Schema.const('retain-pending')]).default('cancel'),
+    }).description('Use the official DSH inbox for queued turns and steering.'),
     enabled: Schema.boolean().default(false),
     host: Schema.string().default('127.0.0.1'),
     port: Schema.natural().default(41241),
@@ -114,7 +117,9 @@ export function apply(ctx, config) {
             subagentTools: config.subagentTools,
         });
         const store = createTaskStore(config);
-        const inbox = config.inbox?.enabled ? new NativeInbox(ctx, bridge, store) : undefined;
+        const inbox = config.inbox?.enabled
+            ? new NativeInbox(ctx, bridge, store, config.inbox.shutdown === 'retain-pending')
+            : undefined;
         await store.init?.();
         if (inbox)
             ctx.provide('a2aInbox', inbox);

package/lib/types/inbox.d.ts

@@ -71,13 +71,16 @@ export declare class NativeInbox implements A2aInbox {
     private readonly ctx;
     private readonly bridge;
     private readonly store;
+    private readonly retainPending;
     private readonly contexts;
     private readonly resolving;
     private stopping;
     private shutdownPromise?;
     private readonly preadmitted;
     server?: A2aServer;
-    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore);
+    private readonly persistence?;
+    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore, retainPending?: boolean);
+    private unloading;
     content(message: Message, contextId: string): Promise<ContentBlock[]>;
     resolve(contextId: string): Promise<Agent>;
     enqueue(taskId: string, message: Message, options?: {
@@ -89,6 +92,7 @@ export declare class NativeInbox implements A2aInbox {
     private promoteInput;
     /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
     private recoverPromotions;
+    private recoverRetained;
     private context;
     private observe;
     private observeInput;

package/lib/types/index.d.ts

@@ -71,8 +71,10 @@ export declare const inject: string[];
 export declare const Config: Schema<Schemastery.ObjectS<{
     inbox: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
@@ -158,8 +160,10 @@ export declare const Config: Schema<Schemastery.ObjectS<{
 }>, Schemastery.ObjectT<{
     inbox: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
@@ -246,6 +250,7 @@ export declare const Config: Schema<Schemastery.ObjectS<{
 export interface A2aPluginConfig {
     inbox?: {
         enabled: boolean;
+        shutdown?: 'cancel' | 'retain-pending';
     };
     enabled: boolean;
     host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",
@@ -46,7 +46,8 @@
     "@deepseek-ai/dsh-user-approval": ">=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
     "@google-cloud/storage": "^7.0.0",
     "ioredis": "^5.0.0",
-    "@deepseek-ai/dsh-goal": ">=0.2.0-rc.2 || >=0.2.1-alpha.1"
+    "@deepseek-ai/dsh-goal": ">=0.2.0-rc.2 || >=0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": ">=0.2.0-rc.2 || >=0.2.1-alpha.1"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-attachment": {
@@ -63,6 +64,9 @@
     },
     "@deepseek-ai/dsh-goal": {
       "optional": true
+    },
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -81,7 +85,8 @@
     "ioredis": "^5.0.0",
     "typescript": "^5.6.3",
     "vitest": "^4.1.11",
-    "@deepseek-ai/dsh-goal": "0.2.1-rc.2"
+    "@deepseek-ai/dsh-goal": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.2"
   },
   "engines": {
     "node": "^20.19 || ^22.12 || >=24.0"