@amaster.ai/dsh-a2a 0.1.24 → 0.1.26

package/README.md

@@ -12,6 +12,45 @@ A2A protocol server plugin for [DeepSeek Harness (dsh)](https://github.com/deeps
 dsh plugin --profile my-agent add @amaster.ai/dsh-a2a
 ```
 
+## Native inbox execution
+
+`inbox.enabled: true` opts into durable native DSH input instead of request-serialized execution. **This requires the unreleased upstream native inbox capability (`ctx.agents.nativeInboxVersion === 1`); the tested `0.2.0-rc.2` runtime does not provide it.** Startup rejects unsupported factories before opening a backend. Legacy execution remains the default.
+
+In this mode, ordinary `SendMessage` / `SendStreamingMessage` calls enter the DSH inbox before their initial task response is published. Nonblocking sends return a submitted task after durable admission. A context owns one agent, while tasks retain separate message identities, streams, and terminal states. A completed unit of work settles `completed`; use the same context with a new task for later work. Disconnecting an HTTP client does not cancel execution. Task snapshots, polling, and subscriptions use the standard A2A operations.
+
+The optional [inbox extension](../../docs/protocol/inbox-v1.md) selects parked admission (`wakeup: false`) or next-step steering (`target: next-step`). Steering must address the currently active task. It cannot pull an unrelated task's input into the active model step.
+
+The same-process `a2aInbox` service implements the exported `A2aInbox` interface:
+
+```ts
+const inbox = ctx.get('a2aInbox') as A2aInbox;
+const agent = await inbox.resolve(contextId);
+const blocks = await inbox.content(message, contextId);
+await inbox.enqueue(taskId, message); // Host follow-up with explicit task ownership.
+await inbox.pause(contextId);
+await inbox.wake(contextId); // Leaves a persisted pause intact.
+await inbox.wake(contextId, { resume: true }); // Explicitly unpauses existing work.
+await inbox.cancel(taskId, { retainInbox: true }); // Terminal task; pending input stays parked.
+```
+
+`pause` cancels active tasks while retaining their unconsumed input and other queued tasks; resumed input from a canceled task gets a fresh task identity. `CancelTask` remains terminal and removes that task's pending input, retaining other tasks' input. The service's explicit retention option parks the context; resuming retained input creates a new task when its former owner is terminal. `a2aTasks.clearContext` discards pending work even when idle. Plugin unload preserves the native inbox and drains its session writes. For restart recovery, configure durable DSH session persistence and a Redis or GCS TaskStore, then call `wake` for the contexts the host chooses to restore. `SubscribeToTask` observes recovered work without submitting a wake message.
+
+In native mode, host settlement hooks submit follow-ups through `a2aInbox.enqueue(taskId, message)`; it binds and persists the task identity before enqueueing. Raw `Agent.send` / `followup` inputs without A2A attribution are rejected rather than assigned to the most recent hook.
+
+`a2a/before-followup` validates admission; use `a2a/before-assembly` for per-input runtime state. The latter runs after the model-step batch is selected, before prompt assembly, and receives the same `A2aTurnContext` fields. Request headers are process-local: restored inputs receive `requestHeaders: undefined`. Persist replay-safe metadata in the message, never credentials in the queue. Admission observers remain non-vetoing.
+
+Recovery only restores an interrupted claim without a committed `user/message`; it never replays committed model input or promises exactly-once tool effects. A task with committed input, no remaining pending input, and no durable terminal A2A checkpoint becomes failed on recovery, including when the turn ended before the process stopped. The host can then decide what to do next. Keep file parts on persistent storage with `uploadsDir` or `a2aFileMaterializer` when queued inputs must survive host or machine restarts. The memory TaskStore and temporary upload default do not provide that durability. In-process task handles remain until context clear or plugin unload; long-lived hosts should clear finished contexts.
+
+Run the real loop / A2A HTTP / JSONL recovery checks against a prepared upstream checkout:
+
+```bash
+DSH_SOURCE_ROOT=/absolute/path/to/deepseek-harness node .github/scripts/check-native-inbox.mjs
+```
+
+The Integration workflow runs this suite without secrets, including on fork PRs, against a pinned upstream source checkout plus the checked-in native inbox source companion. It verifies insertion during an active turn, FIFO execution, independent task completion, and exactly one user-message commit per input.
+
+The checkout needs its installed dependencies and `pnpm run build:native-system`; model responses are scripted, so this check needs no gateway or model credentials. The upstream source companion is required before native mode can be released; no dependency artifact patch is installed by this plugin.
+
 ## Configuration
 
 Disabled by default. Configure via the profile's `cordis.patch.yml`:

package/lib/bridge.js

@@ -14,6 +14,7 @@
  * autonomous turns through `a2a/task-settlement`.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import { TaskState } from '@a2a-js/sdk';
 import { AgentEvent } from '@a2a-js/sdk/server';
 // installModelSelection is a root-module runtime import: the dsh-agent index
@@ -30,6 +31,7 @@ import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './tra
 export class A2aBridge {
     ctx;
     options;
+    inbox;
     tasks = new Map(); // taskId → entry
     bySession = new Map(); // sessionId (== contextId) → entry
     clearing = new Set();
@@ -117,8 +119,8 @@ export class A2aBridge {
                 this.creating.delete(contextId);
         }
     }
-    async ensureTaskInner(taskId, contextId) {
-        if (this.clearing.has(contextId))
+    async ensureTaskInner(taskId, contextId, clearing = false) {
+        if (this.clearing.has(contextId) && !clearing)
             throw new Error('Context is being cleared.');
         const existing = this.tasks.get(taskId);
         if (existing)
@@ -185,12 +187,18 @@ export class A2aBridge {
         const persistence = this.ctx.get('sessionPersistence');
         const persisted = await persistence?.stat(sessionId);
         const handle = persisted
-            ? await this.ctx.agents.resume({ resumeSessionId: sessionId, agentOptions, setup })
+            ? await this.ctx.agents.resume({
+                resumeSessionId: sessionId,
+                agentOptions,
+                setup,
+                ...(this.inbox ? { keepInboxOnDispose: true } : {}),
+            })
             : await this.ctx.agents.create({
                 sessionId,
                 meta: { cwd: this.options.cwd, ...(agentPreset ? { agentPreset } : {}) },
                 agentOptions,
                 setup,
+                ...(this.inbox ? { keepInboxOnDispose: true } : {}),
             });
         const entry = {
             taskId,
@@ -291,6 +299,19 @@ export class A2aBridge {
     async waitForTurn(entry) {
         await Promise.allSettled([...entry.running]);
     }
+    /** The native inbox selects task ownership before assembling its first prompt. */
+    bindInboxTask(entry, taskId, translator, bus, completion, controller) {
+        this.tasks.delete(entry.taskId);
+        entry.taskId = taskId;
+        entry.translator = translator;
+        entry.bus = bus;
+        entry.interrupted = false;
+        entry.settlementAbort = controller;
+        entry.running.clear();
+        entry.running.add(completion);
+        void completion.then(() => entry.running.delete(completion));
+        this.tasks.set(taskId, entry);
+    }
     /** Inspect a message for a live task before the SDK starts its next request. */
     async beforeWorkingTaskMessage(a2aMessage, requestHeaders) {
         const entry = this.tasks.get(a2aMessage.taskId);
@@ -484,9 +505,16 @@ export class A2aBridge {
             throw new Error('Context is already being cleared.');
         this.clearing.add(contextId);
         try {
+            await this.inbox?.clear(contextId);
             await Promise.allSettled([...(this.creating.get(contextId) ?? [])]);
+            if (this.inbox && !this.bySession.has(contextId)) {
+                const persistence = this.ctx.get('sessionPersistence');
+                if (await persistence?.stat(SessionId(contextId)))
+                    await this.ensureTaskInner(randomUUID(), contextId, true);
+            }
             const entry = this.bySession.get(contextId);
             if (entry) {
+                entry.handle.agent.inbox?.clear();
                 const active = entry.turnActive || entry.running.size > 0;
                 this.settleEntry(entry, 'Context cleared.');
                 if (active) {
@@ -530,6 +558,12 @@ export class A2aBridge {
     }
     /** Dispose every owned agent (plugin unload / server shutdown). */
     async dispose() {
+        try {
+            await this.inbox?.shutdown();
+        }
+        catch (error) {
+            console.error('[dsh-a2a] native inbox shutdown failed:', error);
+        }
         const entries = [...this.tasks.values()];
         this.tasks.clear();
         this.bySession.clear();
@@ -575,6 +609,14 @@ export class A2aBridge {
         }
         if (event.type === 'turn/start')
             entry.turnActive = true;
+        if (this.inbox?.onSessionEvent(session, event)) {
+            if (event.type === 'turn/end') {
+                this.withdrawApprovals(entry);
+                this.asked.delete(session.id);
+                entry.turnActive = false;
+            }
+            return;
+        }
         // No-throw seam: translation errors must never reach the agent loop. The
         // turn/end waiter still resolves below, so a poisoned event cannot hang
         // an in-flight execute() either.
@@ -667,6 +709,8 @@ export class A2aBridge {
      * `assistant/message` events). Same no-throw seam as the session feed.
      */
     onAssistantStream(agent, frame) {
+        if (this.inbox?.onAssistantStream(agent, frame))
+            return;
         const entry = this.bySession.get(agent.session.id);
         if (!entry || entry.staleTurn)
             return;
@@ -679,6 +723,7 @@ export class A2aBridge {
         }
     }
     onSessionDisposed(session) {
+        this.inbox?.onDisposed(session);
         this.children.delete(session);
         const entry = this.bySession.get(session.id);
         if (!entry)

package/lib/executor.js

@@ -29,6 +29,9 @@ export class DshAgentExecutor {
         this.suppressTask = suppressTask;
     }
     async execute(requestContext, eventBus) {
+        if (this.bridge.inbox && !this.bridge.validateApprovalMessage(requestContext.userMessage)) {
+            return this.bridge.trackExecution(requestContext.contextId, () => this.bridge.inbox.execute(requestContext, eventBus));
+        }
         if (this.bridge.isClearing(requestContext.contextId)) {
             this.suppressTask?.(requestContext.taskId);
         }
@@ -87,7 +90,8 @@ export class DshAgentExecutor {
         // canceled statusUpdate via the translator — a harmless duplicate); the
         // published event moves the persisted shell to canceled through the
         // handler's ResultManager either way.
-        const contextId = this.bridge.cancel(taskId) ?? '';
+        const contextId = (this.bridge.inbox ? await this.bridge.inbox.cancel(taskId) : this.bridge.cancel(taskId)) ??
+            '';
         eventBus.publish(terminalStatusUpdate(taskId, contextId, 'canceled', 'Task canceled by request.'));
     };
 }