@amaster.ai/dsh-a2a 0.1.36 → 0.1.37

package/README.md

@@ -20,6 +20,8 @@ Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and
 
 The same-process `a2aInbox` service exposes `resolve`, `content`, `enqueue`, `promote`, `cancel`, `get`, `update`, `move`, `remove`, `clearPending`, and `executePending`, plus the existing pause/wake/resume controls. Pending-only clearing preserves active work; context clearing discards all work.
 
+Pause is process-local and writes no custom required session event. After restart, restored input stays parked until a waking admission or explicit execution. Retention recovery accepts snapshots under the historical extension URI as well as the current URI, writes only the current metadata key, and clears both keys after consumption. Explicit resume durably transfers input to a fresh task before waking it; retry after an interrupted cleanup reuses the existing replacement instead of replaying its input.
+
 For external clients, the [native inbox extension specification](#native-inbox-extension-v1) defines `inbox/get`, `update`, `move`, `remove`, `clear`, `execute`, `steer`, and `subscribe` at the advertised JSONRPC endpoint. Activate it with the `A2A-Extensions` header set to the extension URI. Updates use standard A2A 1.0 user Messages; operations address native inbox IDs. REST/gRPC clients use the advertised JSONRPC endpoint for these extension methods. No extra queue or consumer is created.
 
 `inbox/subscribe` streams checkpointed invalidations `{contextId, version}` over SSE, including native consumption and edits. It registers before its initial checkpoint and sends only after owner-scoped `ctx.sessions.flush()` returns true. A false/rejected checkpoint sends no success notification. Re-read the live inbox on invalidation and reconnect; there is no replay or durable outbox. Slow clients disconnect instead of accumulating notifications. To publish the same invalidations to host listeners on `a2a/inbox-checkpointed` without an SSE subscriber, enable `inbox.notifications: true` (default false). Hosts retain authentication, authorization and product-specific fan-out.

package/lib/inbox.js

@@ -9,6 +9,16 @@ import { commitInboxInput, markInboxInputPending } from './task-store.js';
 import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './translator.js';
 export const INBOX_EXTENSION = 'https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md';
 const RETAINED_INPUTS = `${INBOX_EXTENSION}#retained-inputs`;
+const LEGACY_RETAINED_INPUTS = 'https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md#retained-inputs';
+function retainedSnapshot(task) {
+    return task.metadata?.[RETAINED_INPUTS] ?? task.metadata?.[LEGACY_RETAINED_INPUTS];
+}
+function clearRetainedSnapshot(task) {
+    if (!task.metadata)
+        return;
+    delete task.metadata[RETAINED_INPUTS];
+    delete task.metadata[LEGACY_RETAINED_INPUTS];
+}
 export function validateInboxPage(page) {
     if (page === undefined)
         return;
@@ -508,56 +518,103 @@ export class NativeInbox {
     }
     async resume(contextId, taskId) {
         const context = new ServerCallContext();
-        const previous = await this.store.load(taskId, context);
-        if (!previous || previous.contextId !== contextId || !this.terminal(previous))
-            throw new Error('Resume requires a terminal retained task.');
-        const retained = previous.metadata?.[RETAINED_INPUTS];
-        if (typeof retained !== 'string')
-            throw new Error('Task has no retained input to resume.');
-        const inputs = JSON.parse(retained);
-        if (!inputs.length)
-            throw new Error('Task has no retained input to resume.');
         const run = await this.context(contextId, context);
-        const id = randomUUID();
-        const replacement = {
-            ...previous,
-            id,
-            status: {
-                state: TaskState.TASK_STATE_SUBMITTED,
-                timestamp: new Date().toISOString(),
-                message: undefined,
-            },
-            history: [],
-            metadata: { ...previous.metadata },
-        };
-        delete replacement.metadata[RETAINED_INPUTS];
-        const retainedInputs = inputs.map((input) => {
-            if (input.message.source.kind !== 'a2a')
-                throw new Error('Retained input has invalid task ownership.');
-            const original = Message.fromJSON(JSON.parse(input.message.source.message));
-            original.taskId = id;
-            original.referenceTaskIds = [...new Set([...original.referenceTaskIds, taskId])];
-            replacement.history.push(markInboxInputPending(original));
-            return {
-                ...input,
-                message: {
-                    ...input.message,
-                    source: {
-                        ...input.message.source,
-                        taskId: id,
-                        message: JSON.stringify(Message.toJSON(original)),
-                    },
+        const operation = run.admissionTail.then(async () => {
+            if (this.stopping || this.bridge.isClearing(contextId))
+                throw new Error('Context is unavailable.');
+            const previous = await this.store.load(taskId, context);
+            if (!previous || previous.contextId !== contextId || !this.terminal(previous))
+                throw new Error('Resume requires a terminal retained task.');
+            const retained = retainedSnapshot(previous);
+            if (typeof retained !== 'string')
+                throw new Error('Task has no retained input to resume.');
+            const inputs = JSON.parse(retained);
+            if (!inputs.length)
+                throw new Error('Task has no retained input to resume.');
+            const nativeIds = new Set(inputs.map((input) => input.message.id));
+            const resumed = new Map();
+            const messages = [
+                ...run.entry.handle.agent.session
+                    .snapshotEvents()
+                    .flatMap((event) => (event.type === 'user/message' ? [event.data] : [])),
+                ...this.pending(run),
+                ...[...run.tasks.values()].flatMap((task) => task.claimedInputs ?? []),
+            ];
+            for (const message of messages) {
+                if (!nativeIds.has(message.id) || message.source.kind !== 'a2a')
+                    continue;
+                const original = Message.fromJSON(JSON.parse(message.source.message));
+                if (message.source.taskId !== taskId && original.referenceTaskIds.includes(taskId))
+                    resumed.set(message.id, message.source.taskId);
+            }
+            if (resumed.size) {
+                const replacements = new Set(resumed.values());
+                if (resumed.size !== nativeIds.size || replacements.size !== 1)
+                    throw new Error('Retained input has already been partially resumed.');
+                const id = resumed.values().next().value;
+                await this.flush(run.entry.handle.agent.session);
+                const replacement = run.tasks.get(id)?.task ?? (await this.store.load(id, context));
+                if (!replacement)
+                    throw new Error('Resumed task is unavailable.');
+                clearRetainedSnapshot(replacement);
+                await this.checkpoint(replacement, context);
+                clearRetainedSnapshot(previous);
+                await this.checkpoint(previous, context);
+                if (this.pending(run).some((message) => message.source.kind === 'a2a' && message.source.taskId === id))
+                    await this.wake(contextId);
+                return id;
+            }
+            const id = randomUUID();
+            const replacement = {
+                ...previous,
+                id,
+                status: {
+                    state: TaskState.TASK_STATE_SUBMITTED,
+                    timestamp: new Date().toISOString(),
+                    message: undefined,
                 },
+                history: [],
+                metadata: { ...previous.metadata },
             };
+            clearRetainedSnapshot(replacement);
+            const retainedInputs = inputs.map((input) => {
+                if (input.message.source.kind !== 'a2a')
+                    throw new Error('Retained input has invalid task ownership.');
+                const original = Message.fromJSON(JSON.parse(input.message.source.message));
+                original.taskId = id;
+                original.referenceTaskIds = [...new Set([...original.referenceTaskIds, taskId])];
+                replacement.history.push(markInboxInputPending(original));
+                return {
+                    ...input,
+                    message: {
+                        ...input.message,
+                        source: {
+                            ...input.message.source,
+                            taskId: id,
+                            message: JSON.stringify(Message.toJSON(original)),
+                        },
+                    },
+                };
+            });
+            replacement.metadata[RETAINED_INPUTS] = JSON.stringify(retainedInputs);
+            await this.checkpoint(replacement, context);
+            for (const input of retainedInputs) {
+                if (this.pending(run).some((pending) => pending.id === input.message.id))
+                    run.entry.handle.agent.inbox.remove(input.message.id);
+                run.entry.handle.agent.send(input.message, input.target, false);
+            }
+            this.restoreTask(run, replacement, context);
+            // Consume the old snapshot only after its replacement input is durable.
+            await this.flush(run.entry.handle.agent.session);
+            clearRetainedSnapshot(replacement);
+            await this.checkpoint(replacement, context);
+            clearRetainedSnapshot(previous);
+            await this.checkpoint(previous, context);
+            await this.wake(contextId);
+            return id;
         });
-        await this.checkpoint(replacement, context);
-        for (const [index, input] of retainedInputs.entries()) {
-            if (this.pending(run).some((pending) => pending.id === input.message.id))
-                run.entry.handle.agent.inbox.remove(input.message.id);
-            run.entry.handle.agent.send(input.message, input.target, index === retainedInputs.length - 1);
-        }
-        this.restoreTask(run, replacement, context);
-        return id;
+        run.admissionTail = operation.then(() => { }, () => { });
+        return operation;
     }
     /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
     async recoverPromotions(run, context) {
@@ -632,7 +689,7 @@ export class NativeInbox {
                 statusTimestampAfter: undefined,
             }, context);
             for (const task of page.tasks) {
-                const retained = task.metadata?.[RETAINED_INPUTS];
+                const retained = retainedSnapshot(task);
                 if (typeof retained !== 'string')
                     continue;
                 // Terminal snapshots belong to explicit resume(); do not consume their
@@ -736,7 +793,7 @@ export class NativeInbox {
             return;
         await this.flush(agent.session);
         for (const task of snapshots) {
-            delete task.metadata[RETAINED_INPUTS];
+            clearRetainedSnapshot(task);
             await this.checkpoint(task, context);
         }
     }
@@ -762,11 +819,6 @@ export class NativeInbox {
                     rolledBack: new Set(),
                     retained: { 'next-step': [], 'next-turn': [] },
                 };
-                const pause = [...run.entry.handle.agent.session.snapshotEvents()]
-                    .reverse()
-                    .find((event) => event.type === 'agent/inbox/paused');
-                if (pause)
-                    run.paused = pause.data.paused;
                 await this.recoverRetained(run, context);
                 await this.recoverPromotions(run, context);
                 const snapshots = new Map();
@@ -1548,7 +1600,6 @@ export class NativeInbox {
         if (run.paused)
             return;
         run.paused = true;
-        run.entry.handle.agent.session.append('agent/inbox/paused', { paused: true });
         for (const admission of run.admissions)
             admission.abort();
         run.entry.handle.agent.cancel({ kind: 'user' }, { keepInbox: true });
@@ -1560,7 +1611,6 @@ export class NativeInbox {
         const agent = run.entry.handle.agent;
         const pending = this.pending(run);
         run.paused = false;
-        agent.session.append('agent/inbox/paused', { paused: false });
         const target = agent.inbox.nextTurn.length ? 'next-turn' : 'next-step';
         const items = target === 'next-turn' ? agent.inbox.nextTurn : agent.inbox.nextStep;
         const input = items.at(-1);
@@ -1732,6 +1782,7 @@ export class NativeInbox {
                                 if (this.retainPending) {
                                     const pending = retainedByTask.get(task.task.id) ?? [];
                                     if (pending.length) {
+                                        clearRetainedSnapshot(task.task);
                                         task.task.metadata = {
                                             ...task.task.metadata,
                                             [RETAINED_INPUTS]: JSON.stringify(pending),

package/lib/types/inbox.d.ts

@@ -46,13 +46,6 @@ declare module '@deepseek-ai/dsh-llm/types' {
         goal: GoalMessageSource;
     }
 }
-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. */

package/package.json

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