@amaster.ai/dsh-a2a 0.1.35 → 0.1.37

package/README.md

@@ -20,13 +20,15 @@ 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.
 
-For external clients, the [native inbox extension specification](#native-inbox-extension-v1) defines `dsh/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.
 
-`dsh/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.
+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.
 
 Existing native agents keep their setup and lifecycle owner. Reading/subscribing does not block their producers. Plugin shutdown detaches its own queued A2A inputs from a borrowed agent, retaining recovery data when configured; native work and the caller's agent remain available.
 
-Wire snapshots are paginated: 50 entries by default, `pageSize: 1..100`, with `totalSize` and `nextPageToken`. Read `dsh/inbox/get` until the token is empty, traversing next-step before next-turn. Any session-version change invalidates the cursor; restart from the first page. Mutations accept `pageSize` and return the first page. Same-process calls without page options still return the full snapshot. Adjacent reorders log only their affected interval, and slow notification checkpoints keep one pending version/error observer per batch.
+Wire snapshots are paginated: 50 entries by default, `pageSize: 1..100`, with `totalSize` and `nextPageToken`. Read `inbox/get` until the token is empty, traversing next-step before next-turn. Any session-version change invalidates the cursor; restart from the first page. Mutations accept `pageSize` and return the first page. Same-process calls without page options still return the full snapshot. Adjacent reorders log only their affected interval, and slow notification checkpoints keep one pending version/error observer per batch.
 
 The `E2E (dsh-a2a.inbox-api)` matrix leg installs the packed plugin into the pinned CLI and uses the real model gateway. It checks queue editing/reordering/removal/clearing, execution and steering, two checkpointed SSE subscribers, native consumption, and model recall in a subsequent context turn. A local loopback forwarder only gates the first model request to make steering deterministic; it never generates model responses.
 
@@ -77,11 +79,10 @@ DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t
 
 ## Native inbox extension v1
 
-Stable protocol identifier: `https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md`
+Protocol identifier: `https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md`
 
-The identifier stays unchanged for existing messages and retained task metadata;
-this README is the canonical specification. Agent Card extension params advertise
-`documentationUrl` pointing to this section.
+This README contains the extension specification. The URI identifies the
+extension during negotiation; no additional documentation parameter is advertised.
 
 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/).
@@ -91,6 +92,8 @@ states, subscriptions and Push configurations keep their official meanings.
 
 ### Methods
 
+Methods use the implementation-neutral `inbox/` namespace.
+
 Send JSON-RPC 2.0 requests to the advertised JSONRPC endpoint. All methods take
 `contextId`. IDs named `id` below are **native inbox message IDs**, not task IDs.
 The extension adds no REST or gRPC service; those clients can discover and use
@@ -98,14 +101,14 @@ the advertised JSONRPC endpoint for these operations.
 
 | Method | Additional parameters | Result |
 | --- | --- | --- |
-| `dsh/inbox/get` | Optional `pageSize`, `pageToken` | Live inbox snapshot page |
-| `dsh/inbox/update` | `id`, `message` (A2A 1.0 user Message) | Updated snapshot |
-| `dsh/inbox/move` | `id`, `index` (zero-based destination in the same list) | Updated snapshot |
-| `dsh/inbox/remove` | `id` | Updated snapshot |
-| `dsh/inbox/clear` | — | Snapshot after clearing pending input |
-| `dsh/inbox/execute` | Optional `id` to move first in the next-turn list | Snapshot after waking pending work |
-| `dsh/inbox/steer` | `id`, `taskId` (active target) | Snapshot after promotion |
-| `dsh/inbox/subscribe` | — | SSE JSON-RPC result stream of `{contextId, version}` |
+| `inbox/get` | Optional `pageSize`, `pageToken` | Live inbox snapshot page |
+| `inbox/update` | `id`, `message` (A2A 1.0 user Message) | Updated snapshot |
+| `inbox/move` | `id`, `index` (zero-based destination in the same list) | Updated snapshot |
+| `inbox/remove` | `id` | Updated snapshot |
+| `inbox/clear` | — | Snapshot after clearing pending input |
+| `inbox/execute` | Optional `id` to move first in the next-turn list | Snapshot after waking pending work |
+| `inbox/steer` | `id`, `taskId` (active target) | Snapshot after promotion |
+| `inbox/subscribe` | — | SSE JSON-RPC result stream of `{contextId, version}` |
 
 A snapshot is `{contextId, version, nextTurn, nextStep, totalSize, nextPageToken}`. Each entry is
 `{id, message, editable}`: `message` uses the standard A2A 1.0 Message JSON shape.
@@ -129,7 +132,7 @@ limit serialized entries to about 1 MiB; one oversized Message is returned intac
 to ensure progress, so a page may contain fewer items than requested. All mutation
 methods accept `pageSize` for their returned first page; invalid values reject
 before changing the queue. Pages traverse `nextStep` before `nextTurn`, keeping
-native order within each list. Continue via `dsh/inbox/get` and `nextPageToken`
+native order within each list. Continue via `inbox/get` and `nextPageToken`
 until the token is empty. Tokens bind the context and session version; a changed
 version rejects stale tokens instead of silently skipping or duplicating input.
 Re-read from the first page after invalidation. Same-process `get(contextId)`
@@ -165,7 +168,7 @@ coalesce changes per context, and checkpoint before publishing. A rejected or
 false checkpoint produces no success notification. Later changes or reconnects
 retry the current state; there is no durable outbox, replay or exactly-once
 delivery. A host can consume the same feed through `a2a/inbox-checkpointed`.
-Notification data contains no message bodies. Re-read `dsh/inbox/get` after an
+Notification data contains no message bodies. Re-read `inbox/get` after an
 invalidation and on reconnect. Each context checkpoints independently; slow SSE
 clients disconnect instead of creating an unbounded notification backlog.
 Closing the plugin unregisters observers/subscriptions and suppresses late sends.

package/lib/inbox-api.js

@@ -6,7 +6,7 @@ import { INBOX_EXTENSION, validateInboxPage } from './inbox.js';
 export function inboxRpcHandler(inbox, card) {
     return async (req, res, next) => {
         const body = req.body;
-        if (typeof body?.method !== 'string' || !body.method.startsWith('dsh/inbox/'))
+        if (typeof body?.method !== 'string' || !body.method.startsWith('inbox/'))
             return next();
         try {
             if (body.jsonrpc !== '2.0' || !['string', 'number'].includes(typeof body.id))
@@ -23,7 +23,7 @@ export function inboxRpcHandler(inbox, card) {
                 !params.contextId.trim() ||
                 (params.tenant !== undefined && params.tenant !== ''))
                 throw new RequestMalformedError('A contextId and the default tenant are required.');
-            const method = body.method.slice('dsh/inbox/'.length);
+            const method = body.method.slice('inbox/'.length);
             const page = { pageSize: params.pageSize, pageToken: params.pageToken };
             validateInboxPage(page);
             if (method !== 'get' && page.pageToken)

package/lib/inbox.js

@@ -7,8 +7,18 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
 import { InboxChanges } from './inbox-changes.js';
 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/docs/protocol/inbox-v1.md';
+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/index.js

@@ -178,9 +178,7 @@ export function apply(ctx, config) {
                         uri: INBOX_EXTENSION,
                         description: 'Native inbox management, steering and checkpointed invalidation',
                         required: false,
-                        params: {
-                            documentationUrl: 'https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md#native-inbox-extension-v1',
-                        },
+                        params: undefined,
                     },
                 ]
                 : [],

package/lib/types/inbox.d.ts

@@ -10,7 +10,7 @@ import { InboxChanges } from './inbox-changes.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 declare const INBOX_EXTENSION = "https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md";
 export interface A2aInboxEvent {
     phase: string;
     contextId: string;
@@ -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.35",
+  "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",