@amaster.ai/dsh-a2a 0.1.8 → 0.1.10

package/README.md

@@ -60,8 +60,9 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 - **Message parts beyond text.** File parts can carry inline bytes or a `url`; the plugin downloads URLs over http/https, bounded to 64 MiB and 30 s. Supported images use the composed attachment store (`ctx.attachments`, e.g. `@deepseek-ai/dsh-attachment-local`) to reach vision-capable models. Non-image files use a configured materializer or persist under `uploadsDir` (default `<OS temp>/dsh-a2a-uploads/<date>/`, names sanitized cross-platform, collisions suffixed), even when an attachment store exists. The prompt references the resulting readable path inside a `<document>` tag. Ensure the local directory is readable by the agent's tools. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.
 - **Remote execution files.** A deployment can register `ctx.provide('a2aFileMaterializer', { materializeFile })`, using the exported `A2aFileMaterializer` type. The callback receives `{ contextId, bytes, filename, mediaType }` (with a sanitized basename) and returns `{ readablePath }`, a path readable by that context's file/shell tools. When configured, non-image FileParts use the materializer instead of `ctx.attachments.saveFile()`; the model receives the returned `<document path="...">`. Images keep the existing attachment handling. A failed callback yields a delivery note, never a host-path fallback. The deployment owns sandbox selection, upload, and lifetime; no E2B SDK is required by this plugin.
 - **Local execution files.** Without a remote materializer, inline and downloaded non-image FileParts persist under `uploadsDir`; the `<document>` envelope carries the path, source URL, media type, size, and original filename when sanitization or a collision changes it. Images still use native attachment handling.
-- **No approval bridge**: dsh ships the mid-turn approval seam only as the optional `dsh-user-approval` package, which headless profiles do not compose, so tools that would ask are governed by the profile's own approval setup; the A2A side never enters a mid-turn `input-required`.
-- **One in-flight message per task** is the supported flow (send the next message after the turn-final event). dsh serializes queued follow-ups into successive turns, but concurrent requests share one event bus — a second in-flight request may resolve with the first turn's final event.
+- **Tool approvals.** When the profile composes `@deepseek-ai/dsh-user-approval` with policy `ask`, A2A-owned agents answer `approval/request` by publishing `input-required` with a DataPart `{ requestId, toolName, reason?, callId? }`. Reply on the same `taskId`/`contextId` with one DataPart `{ requestId, callId?, outcome: "allowed-once" | "rejected" }`. The reply settles the waiting tool call inside the original dsh turn; it does not create another user message or billing turn. Invalid, duplicate, and withdrawn replies are rejected. `never` policy rejects inside dsh before the A2A answerer is called. The approval service is optional; without it, `ask` fails closed as usual.
+- **Custom approval payloads.** A deployment may register `ctx.provide('a2aApprovalCodec', codec)` before this plugin starts. The exported `A2aApprovalCodec` has `encode(request)` and `decode(message)` methods; `decode` returns `{ requestId?, callId?, outcome }` only for a supported one-shot decision. A unique `callId` can replace `requestId` for legacy clients. Reject unsupported outcomes in the decoder; never translate `proceed_always` into `allowed-once`. Other message types, including question, plan, and UI markup, remain outside this plugin.
+- **One in-flight user turn per task** is the supported flow (send the next user message after the turn-final event). Approval confirmations are the exception: they settle a pending decision in that same turn. dsh serializes queued follow-ups into successive turns, but concurrent unrelated requests share one event bus — a second in-flight request may resolve with the first turn's final event.
 - **Restart**: persisted task shells survive in Redis/GCS. With `sessionPersistence` composed, a `contextId` already present on disk resumes its dsh session after restart; a new id creates a new session.
 - **Clear**: the same-process gateway can call `ctx.get('a2aTasks').clearContext(contextId)` before reporting `messages/clear` success. It cancels and drains the live turn, removes the binding and every TaskStore shell for that context, and returns the removed task IDs. The gateway owns the separate session-surface replacement and client-visible history-ID update.
 

package/lib/approval.js

@@ -0,0 +1,19 @@
+export class ApprovalReplyError extends Error {
+}
+export const defaultApprovalCodec = {
+    encode: ({ requestId, toolName, reason, callId }) => ({ requestId, toolName, reason, callId }),
+    decode(message) {
+        const data = message.parts.length === 1 && message.parts[0].content?.$case === 'data'
+            ? message.parts[0].content.value
+            : undefined;
+        if (!data || !Object.hasOwn(data, 'requestId'))
+            return;
+        if (typeof data.requestId !== 'string' ||
+            !data.requestId ||
+            (data.outcome !== 'allowed-once' && data.outcome !== 'rejected') ||
+            (data.callId !== undefined && typeof data.callId !== 'string')) {
+            throw new Error('Unsupported approval reply.');
+        }
+        return { requestId: data.requestId, outcome: data.outcome, callId: data.callId };
+    },
+};

package/lib/bridge.js

@@ -15,6 +15,8 @@
  * turn order). The final status-update is published before the waiter
  * resolves, so an execute() that returns always landed its events first.
  */
+import { TaskState } from '@a2a-js/sdk';
+import { AgentEvent } from '@a2a-js/sdk/server';
 // installModelSelection is a root-module runtime import: the dsh-agent index
 // pulls workspace-internal packages (dsh-scope) that are absent from the
 // plugin's dev install, so unit tests vi.mock this module.
@@ -23,8 +25,9 @@ import { installModelSelection } from '@deepseek-ai/dsh-agent';
 // modules import packages that are not on npm yet (dsh-timeout, dsh-scope).
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
 import { SessionId } from '@deepseek-ai/dsh-session/types';
+import { ApprovalReplyError, defaultApprovalCodec, } from './approval.js';
 import { buildMessageContent, uploadsDir } from './content.js';
-import { SessionTranslator, terminalStatusUpdate } from './translator.js';
+import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './translator.js';
 export class A2aBridge {
     ctx;
     options;
@@ -33,12 +36,18 @@ export class A2aBridge {
     clearing = new Set();
     creating = new Map();
     executing = new Map();
+    asked = new Map();
+    approvals = new Map();
+    codec;
     constructor(ctx, options) {
         this.ctx = ctx;
         this.options = options;
+        this.codec =
+            ctx.get('a2aApprovalCodec') ?? defaultApprovalCodec;
         ctx.on('session/event', (session, event) => this.onSessionEvent(session, event));
         ctx.on('session/disposed', (session) => this.onSessionDisposed(session));
         ctx.on('agent/assistant-stream', ({ agent, frame }) => this.onAssistantStream(agent, frame));
+        ctx.on('approval/request', (req, next) => this.onApprovalRequest(req, next));
     }
     /**
      * Resolve the live task entry, creating the session/agent when needed.
@@ -72,6 +81,7 @@ export class A2aBridge {
             return { entry: existing, freshTask: false };
         const forContext = this.bySession.get(contextId);
         if (forContext) {
+            this.withdrawApprovals(forContext);
             this.tasks.delete(forContext.taskId);
             forContext.taskId = taskId;
             forContext.translator = new SessionTranslator(taskId, contextId, this.options.agentOptions?.model);
@@ -151,6 +161,77 @@ export class A2aBridge {
     isClearing(contextId) {
         return this.clearing.has(contextId);
     }
+    /** Called before the SDK starts an executor, so a bad reply cannot fail the live task. */
+    validateApprovalMessage(message) {
+        const entry = message.contextId
+            ? this.bySession.get(message.contextId)
+            : this.tasks.get(message.taskId);
+        const pending = [...this.approvals].filter(([, value]) => value.entry === entry);
+        const reply = this.codec.decode(message);
+        if (!pending.length && !reply)
+            return false;
+        if (!entry || !message.taskId || entry.taskId !== message.taskId || !reply) {
+            throw new ApprovalReplyError('Approval reply requires the current task and a supported outcome.');
+        }
+        const found = this.findApproval(entry, reply);
+        if (!found || (found[1].reservedBy && found[1].reservedBy !== message.messageId)) {
+            throw new ApprovalReplyError('Approval request ID or call ID does not match a pending request.');
+        }
+        return true;
+    }
+    /** Reserve one reply before the SDK asynchronously loads and saves the task. */
+    reserveApprovalMessage(message) {
+        if (!this.validateApprovalMessage(message))
+            return;
+        const entry = this.tasks.get(message.taskId);
+        const [id, approval] = this.findApproval(entry, this.codec.decode(message));
+        if (approval.reservedBy)
+            throw new ApprovalReplyError('Approval reply is already in progress.');
+        approval.reservedBy = message.messageId;
+        return () => {
+            if (this.approvals.get(id) === approval)
+                approval.reservedBy = undefined;
+        };
+    }
+    /** Claim the decision before publishing the reply's task anchor. */
+    claimApproval(message) {
+        const reply = this.codec.decode(message);
+        if (!reply)
+            throw new ApprovalReplyError('Unsupported approval reply.');
+        const entry = this.tasks.get(message.taskId);
+        const found = entry && this.findApproval(entry, reply);
+        if (!found ||
+            entry.sessionId !== message.contextId ||
+            (found[1].reservedBy && found[1].reservedBy !== message.messageId)) {
+            throw new ApprovalReplyError('Approval is no longer pending.');
+        }
+        const [id, approval] = found;
+        this.approvals.delete(id);
+        approval.removeAbort();
+        return {
+            entry,
+            resume: () => {
+                approval.resolve(reply.outcome);
+                this.publishNextApproval(entry);
+            },
+        };
+    }
+    findApproval(entry, reply) {
+        if (reply.requestId) {
+            const approval = this.approvals.get(reply.requestId);
+            return approval?.entry === entry &&
+                (reply.callId === undefined || approval.request.callId === reply.callId)
+                ? [reply.requestId, approval]
+                : undefined;
+        }
+        if (!reply.callId)
+            return;
+        const matches = [...this.approvals].filter(([, approval]) => approval.entry === entry && approval.request.callId === reply.callId);
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    async waitForTurn(entry) {
+        await Promise.allSettled([...entry.running]);
+    }
     /** Include content preparation in the work a context clear must drain. */
     async trackExecution(contextId, run) {
         const execution = run();
@@ -170,10 +251,10 @@ export class A2aBridge {
         }
     }
     /** Queue one user-message turn on the task's agent and await its `turn/end`. */
-    async runTurn(entry, content, bus) {
+    async runTurn(entry, content, bus, a2aMessageId, requestHeaders) {
         if (this.clearing.has(entry.sessionId))
             throw new Error('Context is being cleared.');
-        const running = this.runTurnInner(entry, content, bus);
+        const running = this.runTurnInner(entry, content, bus, a2aMessageId, requestHeaders);
         entry.running.add(running);
         try {
             await running;
@@ -182,7 +263,7 @@ export class A2aBridge {
             entry.running.delete(running);
         }
     }
-    async runTurnInner(entry, content, bus) {
+    async runTurnInner(entry, content, bus, a2aMessageId, requestHeaders) {
         let resolveSettled;
         const settled = new Promise((resolve) => {
             resolveSettled = resolve;
@@ -190,26 +271,45 @@ export class A2aBridge {
         entry.settled.push(resolveSettled);
         entry.bus = bus;
         try {
-            const result = entry.handle.agent.followup(createUserMessage({
-                content,
-                source: { kind: 'user' },
-            }));
-            // followup() is typed void; guard a mistyped async impl anyway — an
-            // unhandled rejection would crash the host process, and no turn/end
-            // would ever settle this waiter.
-            void Promise.resolve(result).catch((error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                console.error('[dsh-a2a] followup failed:', error);
-                if (entry.bus === bus) {
-                    entry.bus.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'failed', message));
-                }
-                resolveSettled();
+            const message = createUserMessage({ content, source: { kind: 'user' } });
+            // followup() inserts synchronously, then may claim the message before
+            // returning. Observe that insertion so the mapping is both real and early.
+            const stopListening = this.ctx.on('agent/inbox/inserted', ({ agent, message: inserted }) => {
+                if (agent !== entry.handle.agent || inserted.id !== message.id)
+                    return;
+                stopListening();
+                void this.ctx
+                    .parallel('a2a/message-admitted', {
+                    contextId: entry.sessionId,
+                    taskId: entry.taskId,
+                    a2aMessageId,
+                    dshMessageId: message.id,
+                    requestHeaders,
+                })
+                    .catch((error) => {
+                    console.error('[dsh-a2a] message-admitted listener failed:', error);
+                });
             });
-            // Never rejects: waiters only resolve. A synchronous followup() throw is
-            // the one failure path — it means no turn ever started, so pull this
-            // waiter back out of the FIFO before it can be settled by the NEXT
-            // turn's turn/end (which would resolve one execute() too early).
-            await settled;
+            try {
+                const result = entry.handle.agent.followup(message);
+                // followup() is typed void; guard a mistyped async impl anyway — an
+                // unhandled rejection would crash the host process, and no turn/end
+                // would ever settle this waiter.
+                void Promise.resolve(result).catch((error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.error('[dsh-a2a] followup failed:', error);
+                    if (entry.bus === bus) {
+                        entry.bus.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'failed', message));
+                    }
+                    resolveSettled();
+                });
+                // Never rejects: waiters only resolve. A synchronous followup() throw
+                // means no turn started, so pull its waiter from the FIFO below.
+                await settled;
+            }
+            finally {
+                stopListening();
+            }
         }
         catch (error) {
             const index = entry.settled.indexOf(resolveSettled);
@@ -231,6 +331,7 @@ export class A2aBridge {
             await Promise.allSettled([...(this.creating.get(contextId) ?? [])]);
             const entry = this.bySession.get(contextId);
             if (entry) {
+                this.withdrawApprovals(entry);
                 if (entry.turnActive || entry.running.size > 0) {
                     await entry.handle.agent.cancel({ kind: 'user' });
                 }
@@ -253,6 +354,7 @@ export class A2aBridge {
         const entry = this.tasks.get(taskId);
         if (!entry)
             return undefined;
+        this.withdrawApprovals(entry);
         // cancel() is typed void; the guard keeps a mistyped async impl from
         // crashing the host (the caller already published its canceled final).
         void Promise.resolve(entry.handle.agent.cancel({ kind: 'user' })).catch((error) => console.error('[dsh-a2a] cancel failed:', error));
@@ -264,6 +366,7 @@ export class A2aBridge {
         this.tasks.clear();
         this.bySession.clear();
         for (const entry of entries) {
+            this.withdrawApprovals(entry);
             this.settleEntry(entry, 'Plugin unloaded.');
             try {
                 await entry.handle.dispose();
@@ -277,6 +380,11 @@ export class A2aBridge {
         const entry = this.bySession.get(session.id);
         if (!entry)
             return;
+        if (event.type === 'approval/asked') {
+            const queue = this.asked.get(session.id) ?? [];
+            queue.push({ id: event.data.id, toolName: event.data.toolName, callId: event.data.callId });
+            this.asked.set(session.id, queue);
+        }
         if (event.type === 'turn/start')
             entry.turnActive = true;
         // A turn carried over from a previous task binding (e.g. a canceled turn
@@ -298,6 +406,8 @@ export class A2aBridge {
             console.error('[dsh-a2a] failed to translate session event:', error);
         }
         if (event.type === 'turn/end') {
+            this.withdrawApprovals(entry);
+            this.asked.delete(session.id);
             entry.turnActive = false;
             entry.settled.shift()?.();
         }
@@ -322,6 +432,7 @@ export class A2aBridge {
         const entry = this.bySession.get(session.id);
         if (!entry)
             return;
+        this.withdrawApprovals(entry);
         this.tasks.delete(entry.taskId);
         this.bySession.delete(session.id);
         // A mid-turn disposal never emits turn/end — settle instead of hanging
@@ -330,6 +441,7 @@ export class A2aBridge {
     }
     /** Close an in-flight stream honestly and release every turn waiter. */
     settleEntry(entry, message) {
+        this.withdrawApprovals(entry);
         if (entry.turnActive && entry.bus) {
             entry.bus.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'canceled', message));
         }
@@ -337,6 +449,88 @@ export class A2aBridge {
         for (const resolve of entry.settled.splice(0))
             resolve();
     }
+    onApprovalRequest(req, next) {
+        const entry = this.bySession.get(req.agent.session.id);
+        if (!entry || entry.handle.agent !== req.agent)
+            return next();
+        const queue = this.asked.get(entry.sessionId) ?? [];
+        const matching = queue.filter((ask) => ask.toolName === req.toolName && ask.callId === req.callId);
+        // The answerer request has no request ID; duplicate unclaimed audit asks
+        // cannot be paired safely without a distinct call ID.
+        const asked = matching.length === 1 ? queue.splice(queue.indexOf(matching[0]), 1)[0] : undefined;
+        if (!asked || !entry.bus || !entry.turnActive || req.signal?.aborted)
+            return Promise.resolve('unavailable');
+        return new Promise((resolve) => {
+            const onAbort = () => {
+                this.approvals.delete(asked.id);
+                resolve('cancelled');
+                this.publishNextApproval(entry);
+            };
+            req.signal?.addEventListener('abort', onAbort, { once: true });
+            this.approvals.set(asked.id, {
+                entry,
+                request: {
+                    requestId: asked.id,
+                    toolName: req.toolName,
+                    reason: req.reason,
+                    callId: asked.callId,
+                },
+                prompted: false,
+                resolve,
+                removeAbort: () => req.signal?.removeEventListener('abort', onAbort),
+            });
+            this.publishNextApproval(entry);
+        });
+    }
+    publishNextApproval(entry) {
+        const waiting = [...this.approvals].filter(([, approval]) => approval.entry === entry);
+        if (waiting.some(([, approval]) => approval.prompted))
+            return;
+        const next = waiting[0];
+        if (!next || !entry.bus)
+            return;
+        const [id, approval] = next;
+        approval.prompted = true;
+        try {
+            const data = this.codec.encode(approval.request);
+            const message = agentTextMessage(entry.taskId, entry.sessionId, 'Tool approval required.');
+            message.parts = [
+                {
+                    content: { $case: 'data', value: data },
+                    metadata: undefined,
+                    filename: '',
+                    mediaType: 'application/json',
+                },
+            ];
+            entry.bus.publish(AgentEvent.statusUpdate({
+                taskId: entry.taskId,
+                contextId: entry.sessionId,
+                status: {
+                    state: TaskState.TASK_STATE_INPUT_REQUIRED,
+                    message,
+                    timestamp: new Date().toISOString(),
+                },
+                metadata: { dshAgent: { kind: 'state-change', reason: 'approval' } },
+            }));
+        }
+        catch (error) {
+            console.error('[dsh-a2a] failed to publish approval:', error);
+            this.approvals.delete(id);
+            approval.removeAbort();
+            approval.resolve('unavailable');
+            this.publishNextApproval(entry);
+        }
+    }
+    withdrawApprovals(entry) {
+        for (const [id, approval] of this.approvals) {
+            if (approval.entry !== entry)
+                continue;
+            this.approvals.delete(id);
+            approval.removeAbort();
+            approval.resolve('cancelled');
+        }
+        this.asked.delete(entry.sessionId);
+    }
     /**
      * Config override wins per field; otherwise the deployment default read from
      * the `agentDefaultModel` service (the entry-point contract — the loop

package/lib/executor.js

@@ -18,7 +18,8 @@
  * `cancelTask` is an arrow property because the SDK destructures it.
  */
 import { TaskState } from '@a2a-js/sdk';
-import { AgentEvent } from '@a2a-js/sdk/server';
+import { AgentEvent, STATE_HEADERS_KEY } from '@a2a-js/sdk/server';
+import { ApprovalReplyError } from './approval.js';
 import { agentTextMessage, terminalStatusUpdate } from './translator.js';
 export class DshAgentExecutor {
     bridge;
@@ -37,6 +38,18 @@ export class DshAgentExecutor {
         const { userMessage, taskId, contextId } = requestContext;
         let anchored = false;
         try {
+            if (this.bridge.validateApprovalMessage(userMessage)) {
+                const approval = this.bridge.claimApproval(userMessage);
+                try {
+                    eventBus.publish(taskEvent(taskId, contextId, TaskState.TASK_STATE_WORKING));
+                    anchored = true;
+                }
+                finally {
+                    approval.resume();
+                }
+                await this.bridge.waitForTurn(approval.entry);
+                return;
+            }
             const content = await this.bridge.buildContent(userMessage, contextId);
             const { entry, freshTask } = await this.bridge.ensureTask(taskId, contextId);
             eventBus.publish(freshTask
@@ -48,9 +61,12 @@ export class DshAgentExecutor {
                     // stored task (history/artifacts preserved).
                     taskEvent(taskId, contextId, TaskState.TASK_STATE_WORKING));
             anchored = true;
-            await this.bridge.runTurn(entry, content, eventBus);
+            const requestHeaders = requestContext.context.state.get(STATE_HEADERS_KEY);
+            await this.bridge.runTurn(entry, content, eventBus, userMessage.messageId, requestHeaders);
         }
         catch (error) {
+            if (error instanceof ApprovalReplyError)
+                return;
             if (this.bridge.isClearing(contextId))
                 this.suppressTask?.(taskId);
             const message = error instanceof Error ? error.message : String(error);

package/lib/index.js

@@ -20,6 +20,9 @@ import { startA2aServer } from './server.js';
 import { GcsTaskStore } from './stores/gcs.js';
 import { RedisTaskStore } from './stores/redis.js';
 import { MemoryTaskStore, SanitizedTaskStore } from './task-store.js';
+export { defaultApprovalCodec } from './approval.js';
+/** Event emitted when one A2A user message enters the dsh inbox. */
+export const A2A_MESSAGE_ADMITTED_EVENT = 'a2a/message-admitted';
 export const name = 'dsh-a2a';
 /** The bridge creates and owns agents through the registry service. */
 export const inject = ['agents'];
@@ -136,6 +139,7 @@ export function apply(ctx, config) {
             },
             executor,
             taskStore: store,
+            approvalGuard: (message) => bridge.reserveApprovalMessage(message),
         });
         serverPort = server.port;
         console.log(`[dsh-a2a] A2A endpoint: http://${config.host}:${server.port}${config.basePath}/ ` +

package/lib/server.js

@@ -14,6 +14,7 @@
 import { createServer } from 'node:http';
 import { A2A_PROTOCOL_VERSION, AGENT_CARD_PATH, TaskState, } from '@a2a-js/sdk';
 import { duplicateInterfacesForLegacy } from '@a2a-js/sdk/compat/v0_3';
+import { RequestMalformedError } from '@a2a-js/sdk/errors';
 import { DefaultRequestHandler, ServerCallContext, } from '@a2a-js/sdk/server';
 import { agentCardHandler, jsonRpcHandler, UserBuilder } from '@a2a-js/sdk/server/express';
 import express from 'express';
@@ -49,7 +50,36 @@ export async function startA2aServer(options) {
         skills: [],
         signatures: [],
     };
-    const requestHandler = new DefaultRequestHandler(card, options.taskStore, options.executor);
+    const guardApproval = (message) => {
+        if (!message)
+            return;
+        try {
+            return options.approvalGuard?.(message);
+        }
+        catch (error) {
+            throw new RequestMalformedError(error instanceof Error ? error.message : String(error));
+        }
+    };
+    const requestHandler = new (class extends DefaultRequestHandler {
+        async sendMessage(...args) {
+            const release = guardApproval(args[0].message);
+            try {
+                return await super.sendMessage(...args);
+            }
+            finally {
+                release?.();
+            }
+        }
+        async *sendMessageStream(...args) {
+            const release = guardApproval(args[0].message);
+            try {
+                yield* super.sendMessageStream(...args);
+            }
+            finally {
+                release?.();
+            }
+        }
+    })(card, options.taskStore, options.executor);
     const app = express();
     // The SDK's jsonRpcHandler parses bodies with express.json()'s 100kb default;
     // raise the ceiling here — body-parser skips re-parsing an already-read body.

package/lib/translator.js

@@ -33,12 +33,8 @@
  * A2A 1.0 removed the `final` flag: the SDK's event queue stops on terminal
  * and interrupted (input-required) states, which is exactly the set above.
  *
- * dsh ships the approval seam as the optional
- * @deepseek-ai/dsh-user-approval package (the `ctx.approval` service), but
- * headless profiles do not compose it and `tools/pre-execute`'s `ask` fails
- * closed without one, so no approval bridge exists here. TODO(verify):
- * bridge approval asks to A2A input-required once a deployment composes the
- * service.
+ * Mid-turn approvals are mapped separately by A2aBridge: they interrupt the
+ * A2A task while this translator keeps the original dsh turn open.
  */
 import { randomUUID } from 'node:crypto';
 import { Role, TaskState } from '@a2a-js/sdk';

package/lib/types/approval.d.ts

@@ -0,0 +1,21 @@
+import type { Message } from '@a2a-js/sdk';
+export declare class ApprovalReplyError extends Error {
+}
+export interface A2aApproval {
+    requestId: string;
+    toolName: string;
+    reason?: string;
+    callId?: string;
+}
+export interface A2aApprovalReply {
+    /** A legacy codec may correlate by a unique callId instead. */
+    requestId?: string;
+    callId?: string;
+    outcome: 'allowed-once' | 'rejected';
+}
+/** A2A has no standard approval DataPart schema. Deployments may replace this codec. */
+export interface A2aApprovalCodec {
+    encode(request: A2aApproval): Record<string, unknown>;
+    decode(message: Message): A2aApprovalReply | undefined;
+}
+export declare const defaultApprovalCodec: A2aApprovalCodec;

package/lib/types/bridge.d.ts

@@ -15,8 +15,8 @@
  * turn order). The final status-update is published before the waiter
  * resolves, so an execute() that returns always landed its events first.
  */
-import type { Message } from '@a2a-js/sdk';
-import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { type Message } from '@a2a-js/sdk';
+import { type ExecutionEventBus } from '@a2a-js/sdk/server';
 import type { Context } from '@deepseek-ai/cordis';
 import type { AgentHandle } from '@deepseek-ai/dsh-agent';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
@@ -59,6 +59,9 @@ export declare class A2aBridge {
     private readonly clearing;
     private readonly creating;
     private readonly executing;
+    private readonly asked;
+    private readonly approvals;
+    private readonly codec;
     constructor(ctx: Context, options: BridgeOptions);
     /**
      * Resolve the live task entry, creating the session/agent when needed.
@@ -75,10 +78,21 @@ export declare class A2aBridge {
     /** A2A parts → dsh content blocks; throws only when no part is usable. */
     buildContent(message: Message, contextId: string): Promise<ContentBlock[]>;
     isClearing(contextId: string): boolean;
+    /** Called before the SDK starts an executor, so a bad reply cannot fail the live task. */
+    validateApprovalMessage(message: Message): boolean;
+    /** Reserve one reply before the SDK asynchronously loads and saves the task. */
+    reserveApprovalMessage(message: Message): (() => void) | undefined;
+    /** Claim the decision before publishing the reply's task anchor. */
+    claimApproval(message: Message): {
+        entry: TaskEntry;
+        resume: () => void;
+    };
+    private findApproval;
+    waitForTurn(entry: TaskEntry): Promise<void>;
     /** Include content preparation in the work a context clear must drain. */
     trackExecution(contextId: string, run: () => Promise<void>): Promise<void>;
     /** Queue one user-message turn on the task's agent and await its `turn/end`. */
-    runTurn(entry: TaskEntry, content: ContentBlock[], bus: ExecutionEventBus): Promise<void>;
+    runTurn(entry: TaskEntry, content: ContentBlock[], bus: ExecutionEventBus, a2aMessageId: string, requestHeaders: unknown): Promise<void>;
     private runTurnInner;
     /** Cancel and release the live binding before the caller deletes stored shells. */
     clearContext(contextId: string, clearStored?: (liveIds: string[]) => Promise<string[]>): Promise<string[]>;
@@ -95,6 +109,9 @@ export declare class A2aBridge {
     private onSessionDisposed;
     /** Close an in-flight stream honestly and release every turn waiter. */
     private settleEntry;
+    private onApprovalRequest;
+    private publishNextApproval;
+    private withdrawApprovals;
     /**
      * Config override wins per field; otherwise the deployment default read from
      * the `agentDefaultModel` service (the entry-point contract — the loop

package/lib/types/index.d.ts

@@ -13,7 +13,23 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+export type { A2aApproval, A2aApprovalCodec, A2aApprovalReply } from './approval.js';
+export { defaultApprovalCodec } from './approval.js';
 export type { A2aFileMaterializer } from './content.js';
+/** Event emitted when one A2A user message enters the dsh inbox. */
+export declare const A2A_MESSAGE_ADMITTED_EVENT: "a2a/message-admitted";
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /** Link a protocol message to the dsh inbox message created for its turn. */
+        'a2a/message-admitted'(detail: {
+            contextId: string;
+            taskId: string;
+            a2aMessageId: string;
+            dshMessageId: string;
+            requestHeaders: unknown;
+        }): void;
+    }
+}
 export declare const name = "dsh-a2a";
 /** The bridge creates and owns agents through the registry service. */
 export declare const inject: string[];

package/lib/types/server.d.ts

@@ -11,6 +11,7 @@
  * The SSE framing and error envelopes are the SDK's; this layer only binds
  * the server and builds the card.
  */
+import { type Message } from '@a2a-js/sdk';
 import { type AgentExecutor, type TaskStore } from '@a2a-js/sdk/server';
 export interface A2aServerOptions {
     host: string;
@@ -25,6 +26,7 @@ export interface A2aServerOptions {
     };
     executor: AgentExecutor;
     taskStore: TaskStore;
+    approvalGuard?: (message: Message) => undefined | (() => void);
 }
 export interface A2aServer {
     /** The bound port (differs from options.port when 0). */

package/lib/types/translator.d.ts

@@ -33,12 +33,8 @@
  * A2A 1.0 removed the `final` flag: the SDK's event queue stops on terminal
  * and interrupted (input-required) states, which is exactly the set above.
  *
- * dsh ships the approval seam as the optional
- * @deepseek-ai/dsh-user-approval package (the `ctx.approval` service), but
- * headless profiles do not compose it and `tools/pre-execute`'s `ask` fails
- * closed without one, so no approval bridge exists here. TODO(verify):
- * bridge approval asks to A2A input-required once a deployment composes the
- * service.
+ * Mid-turn approvals are mapped separately by A2aBridge: they interrupt the
+ * A2A task while this translator keeps the original dsh turn open.
  */
 import { type Message } from '@a2a-js/sdk';
 import { type AgentExecutionEvent } from '@a2a-js/sdk/server';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",
@@ -42,6 +42,7 @@
     "@deepseek-ai/dsh-attachment": ">=0.1.5-rc.1 || >=0.1.6-alpha.1",
     "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1",
     "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 || >=0.1.6-alpha.1",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.6-alpha.2",
     "@google-cloud/storage": "^7.0.0",
     "ioredis": "^5.0.0"
   },
@@ -49,6 +50,9 @@
     "@deepseek-ai/dsh-attachment": {
       "optional": true
     },
+    "@deepseek-ai/dsh-user-approval": {
+      "optional": true
+    },
     "@google-cloud/storage": {
       "optional": true
     },
@@ -62,6 +66,7 @@
     "@deepseek-ai/dsh-attachment": "0.1.6-alpha.2",
     "@deepseek-ai/dsh-llm": "0.1.6-alpha.2",
     "@deepseek-ai/dsh-session": "0.1.6-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.6-alpha.2",
     "@google-cloud/storage": "^7.0.0",
     "@types/express": "^4.17.21",
     "@types/node": "^22.0.0",