@amaster.ai/dsh-a2a 0.1.36 → 0.1.38

package/README.md

@@ -16,11 +16,13 @@ dsh plugin --profile my-agent add @amaster.ai/dsh-a2a
 
 `inbox.enabled: true` uses the official DSH inbox (`Agent.send`) for ordinary `next-turn` input and `next-step` steering. Tested with the unmodified npm runtime `0.2.1-rc.5`; no core patch is required. The queue and its durable projection belong to DSH. The plugin only materializes messages, attaches A2A task identities, and translates execution events.
 
-Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and task subscriptions keep their official meanings. The negotiated inbox extension forwards `target` and `wakeup` to DSH. `wakeup: false` leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.
+Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and task subscriptions keep their official meanings. Optional inbox metadata forwards `target` and `wakeup` to DSH. `wakeup: false` leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.
 
 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.
 
-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.
+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. No `A2A-Extensions` header or extension activation is required. 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.
 
@@ -79,14 +81,15 @@ DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t
 
 Protocol identifier: `https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md`
 
-This README contains the extension specification. The URI identifies the
-extension during negotiation; no additional documentation parameter is advertised.
+This README contains the extension specification. The URI remains a metadata
+namespace and discovery identifier for compatibility; callers do not need to send it.
 
 This is a project extension, not an official A2A extension. It follows the
 [A2A extension mechanism](https://a2a-protocol.org/v1.0.1/topics/extensions/).
-The Agent Card advertises it when `inbox.enabled` is true. Activate it with the
-`A2A-Extensions` HTTP header. Responses echo that header. Standard task methods,
-states, subscriptions and Push configurations keep their official meanings.
+The Agent Card advertises it when `inbox.enabled` is true. Inbox methods and
+optional admission controls do not require an `A2A-Extensions` header or an
+activation handshake. Standard task methods, states, subscriptions and Push
+configurations keep their official meanings.
 
 ### Methods
 
@@ -175,7 +178,7 @@ Closing the plugin unregisters observers/subscriptions and suppresses late sends
 
 Standard SendMessage/SendStreamingMessage continues to accept
 `metadata[URI] = {target: 'next-turn' | 'next-step', wakeup: boolean}` on its
-Message, negotiated as before. Prefer those standard methods for new input.
+Message, without extension negotiation. Prefer those standard methods for new input.
 The operations above control already queued input; they do not add another
 queue, consumer, task-state machine or webhook configuration store.
 

package/lib/inbox-api.js

@@ -1,8 +1,8 @@
 /** JSON-RPC method extension; standard task methods stay with the official SDK. */
-import { A2A_PROTOCOL_VERSION, A2A_VERSION_HEADER, Extensions, HTTP_EXTENSION_HEADER, Message, } from '@a2a-js/sdk';
-import { ExtensionSupportRequiredError, RequestMalformedError, toJsonRpcError, } from '@a2a-js/sdk/errors';
+import { A2A_PROTOCOL_VERSION, A2A_VERSION_HEADER, Message } from '@a2a-js/sdk';
+import { RequestMalformedError, toJsonRpcError } from '@a2a-js/sdk/errors';
 import { validateVersion } from '@a2a-js/sdk/server';
-import { INBOX_EXTENSION, validateInboxPage } from './inbox.js';
+import { validateInboxPage } from './inbox.js';
 export function inboxRpcHandler(inbox, card) {
     return async (req, res, next) => {
         const body = req.body;
@@ -12,9 +12,6 @@ export function inboxRpcHandler(inbox, card) {
             if (body.jsonrpc !== '2.0' || !['string', 'number'].includes(typeof body.id))
                 throw new RequestMalformedError('A JSON-RPC 2.0 request id is required.');
             validateVersion(req.get(A2A_VERSION_HEADER) || A2A_PROTOCOL_VERSION, card, 'JSONRPC');
-            if (!Extensions.parseServiceParameter(req.get(HTTP_EXTENSION_HEADER)).includes(INBOX_EXTENSION))
-                throw new ExtensionSupportRequiredError('Activate the native inbox extension.');
-            res.setHeader(HTTP_EXTENSION_HEADER, INBOX_EXTENSION);
             const params = body.params;
             if (!params ||
                 typeof params !== 'object' ||

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();
@@ -899,12 +951,10 @@ export class NativeInbox {
             context: new ServerCallContext({ tenant: context.tenant, user: context.user }),
         };
     }
-    controls(message, context) {
+    controls(message) {
         const value = message.metadata?.[INBOX_EXTENSION];
         if (value === undefined)
             return { target: 'next-turn', wakeup: true };
-        if (!context.requestedExtensions?.includes(INBOX_EXTENSION))
-            throw new Error('Inbox controls require A2A-Extensions negotiation.');
         if (!value ||
             typeof value !== 'object' ||
             Array.isArray(value) ||
@@ -914,7 +964,6 @@ export class NativeInbox {
             throw new Error('Invalid inbox target.');
         if (value.wakeup !== undefined && typeof value.wakeup !== 'boolean')
             throw new Error('Invalid inbox wakeup.');
-        context.addActivatedExtension(INBOX_EXTENSION);
         return {
             target: value.target === 'next-step' ? 'next-step' : 'next-turn',
             wakeup: value.wakeup !== false,
@@ -924,7 +973,7 @@ export class NativeInbox {
     async beforeMessage(message, context) {
         if (!message.messageId)
             throw new Error('message.messageId is required.');
-        const controls = this.controls(message, context);
+        const controls = this.controls(message);
         if (!message.taskId) {
             if (controls.target === 'next-step')
                 throw new Error('Steering must address an active task.');
@@ -1097,7 +1146,7 @@ export class NativeInbox {
         let task;
         let ownsTask = false;
         try {
-            const controls = this.controls(userMessage, context);
+            const controls = this.controls(userMessage);
             const run = await this.context(contextId, context);
             task = run.tasks.get(taskId);
             if (!task) {
@@ -1548,7 +1597,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 +1608,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 +1779,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.38",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",