@amaster.ai/dsh-a2a 0.1.7 → 0.1.9

package/README.md

@@ -57,8 +57,9 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 - **One task = one dsh session.** The A2A `contextId` IS the dsh session id. A completed turn ends `input-required`, not `completed` — the task is a conversation and stays continuable; `CancelTask` and turn errors are terminal (`canceled` / `failed`), and the SDK rejects follow-ups addressed at a terminal `taskId` (send with only the `contextId` to continue the session under a fresh task id).
 - **Agents are full preset citizens.** Each task's agent is created with the deployment's default model selection (`agentDefaultModel`) and mounts its agent preset (the web profile keeps all tools inside presets — without one the agent would see an empty tool catalog). `agent.preset` pins a specific preset.
 - **Streaming aggregation.** Text deltas of a turn share one `messageId`, so clients accumulate them into a single message; reasoning deltas ride a separate `messageId` and are marked `metadata.dshAgent.kind: 'thought'`. The turn-final event's message carries the full assembled text, so blocking `SendMessage` clients read the answer from `result.task.status.message`. Tool calls/results are data parts marked `tool-call` / `tool-result`; token usage lands in `metadata.usage` of the final event. A2A 1.0 has no `final` flag — terminal and interrupted states close the stream.
-- **Message parts beyond text.** File parts (inline bytes or a `url` — the plugin downloads those over http/https, bounded to 64 MiB and 30 s) use the composed attachment store (`ctx.attachments`, e.g. `@deepseek-ai/dsh-attachment-local`) unless a non-image materializer is configured: images reach vision-capable models natively, and stored files project to deterministic handle text with a read-only path when dsh can map one into the execution world. Without a store or materializer, files persist under the configured `uploadsDir` (default `<OS temp>/dsh-a2a-uploads/<date>/`, names sanitized cross-platform, collisions suffixed) and the prompt references them by absolute path inside a `<document>` tag. Ensure that directory is readable by the agent's tools. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.
+- **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.
 - **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.

package/lib/bridge.js

@@ -170,10 +170,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 +182,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 +190,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);

package/lib/content.js

@@ -3,13 +3,12 @@
  * part kinds:
  *
  *   - `text` parts stay text;
- *   - file parts (inline `raw` bytes or a `url`) use the composed attachment
- *     store unless a non-image materializer is configured; url parts are
- *     downloaded by the plugin (http/https only, size- and time-bounded);
+ *   - file parts (inline `raw` bytes or a `url`) are downloaded by the plugin
+ *     (http/https only, size- and time-bounded) when they carry a URL;
  *   - an optional deployment materializer puts non-image files into the
  *     active execution world instead of saving a host attachment;
- *   - without a materializer, files with no store (or refused by a store)
- *     persist under the configured upload root (default `<OS temp>/
+ *   - without a materializer, non-image files persist under the configured
+ *     upload root even when an attachment store exists (default `<OS temp>/
  *     dsh-a2a-uploads/<date>/`) and the prompt references them by path;
  *   - `data` parts become JSON text.
  *
@@ -54,11 +53,11 @@ export async function buildMessageContent(parts, attachments, dir, materializati
     }
     return content;
 }
-/** The directory file parts persist into when they are not attachments. */
+/** The directory non-image file parts persist into without a materializer. */
 export function uploadsDir(root) {
     // 'sv-SE' renders YYYY-MM-DD; the bucket is local time.
     const segment = new Date().toLocaleDateString('sv-SE').replaceAll('-', '');
-    return path.join(root || path.join(os.tmpdir(), 'dsh-a2a-uploads'), segment);
+    return path.resolve(root || path.join(os.tmpdir(), 'dsh-a2a-uploads'), segment);
 }
 /** Log and degrade one file-part failure to a metadata note. */
 function failNote(part, mediaType, uri, label, error) {
@@ -85,7 +84,7 @@ async function fileContent(c, part, attachments, dir, materialization) {
         return failNote(part, mediaType, uri, 'failed to read a file part', error);
     }
     const image = attachments?.imageLimits.mediaTypes.includes(mediaType.toLowerCase());
-    if (attachments && (!materialization || image)) {
+    if (attachments && image) {
         const block = await saveAttachment(attachments, bytes, mediaType, part.filename);
         if (block)
             return block;
@@ -100,7 +99,7 @@ async function fileContent(c, part, attachments, dir, materialization) {
             });
             if (!readablePath)
                 throw new Error('materializer returned no readable path');
-            return documentBlock(uri, mediaType, bytes.byteLength, readablePath);
+            return documentBlock(uri, mediaType, bytes.byteLength, readablePath, part.filename);
         }
         catch (error) {
             console.error('[dsh-a2a] failed to materialize a file part:', error);
@@ -110,7 +109,7 @@ async function fileContent(c, part, attachments, dir, materialization) {
     try {
         const name = sanitizeUploadFileName(part.filename);
         const filePath = await persistUpload(dir, name, bytes);
-        return documentBlock(uri, mediaType, bytes.byteLength, filePath);
+        return documentBlock(uri, mediaType, bytes.byteLength, filePath, part.filename);
     }
     catch (error) {
         return failNote(part, mediaType, uri, 'failed to persist a file part', error);
@@ -174,11 +173,14 @@ function sanitizeUploadFileName(name) {
     return !cleaned || WINDOWS_RESERVED_STEMS.has(stem) ? 'unnamed-file' : cleaned;
 }
 /** Tool-readable path stand-in for a file part. */
-function documentBlock(uri, mediaType, bytes, filePath) {
+function documentBlock(uri, mediaType, bytes, filePath, originalName) {
     const attrs = [
         // The basename of the final path, so name= always matches the file on
         // disk — including collision suffixes.
         `name="${attr(path.win32.basename(filePath))}"`,
+        originalName &&
+            originalName !== path.win32.basename(filePath) &&
+            `originalName="${attr(originalName)}"`,
         uri && `uri="${attr(uri)}"`,
         mediaType && `type="${attr(mediaType)}"`,
         `size="${bytes}"`,

package/lib/executor.js

@@ -3,7 +3,7 @@
  * bridge. One `execute()` = one user-message turn:
  *
  *   1. map the message's parts onto dsh content blocks (file parts become
- *      execution-world paths with a materializer, attachments or local files otherwise)
+ *      execution-world paths with a materializer, local paths otherwise)
  *   2. ensure the task's session/agent exists (creating it on first contact)
  *   3. publish a `task` event first — A2A 1.0 stream ordering REQUIRES the
  *      first event of every execute to be a task or message, including
@@ -18,7 +18,7 @@
  * `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 { agentTextMessage, terminalStatusUpdate } from './translator.js';
 export class DshAgentExecutor {
     bridge;
@@ -48,7 +48,8 @@ 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 (this.bridge.isClearing(contextId))

package/lib/index.js

@@ -20,6 +20,8 @@ import { startA2aServer } from './server.js';
 import { GcsTaskStore } from './stores/gcs.js';
 import { RedisTaskStore } from './stores/redis.js';
 import { MemoryTaskStore, SanitizedTaskStore } from './task-store.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'];
@@ -31,8 +33,8 @@ export const Config = Schema.object({
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema.string().default(process.cwd()),
     /**
-     * Root directory file parts persist into when no attachment store is
-     * composed (date-layered below it). Empty = <OS temp>/dsh-a2a-uploads.
+     * Root directory for fallback or opted-in local file parts (date-layered
+     * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema.string().default(''),
     agent: Schema.object({

package/lib/types/bridge.d.ts

@@ -78,7 +78,7 @@ export declare class A2aBridge {
     /** 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[]>;

package/lib/types/content.d.ts

@@ -3,13 +3,12 @@
  * part kinds:
  *
  *   - `text` parts stay text;
- *   - file parts (inline `raw` bytes or a `url`) use the composed attachment
- *     store unless a non-image materializer is configured; url parts are
- *     downloaded by the plugin (http/https only, size- and time-bounded);
+ *   - file parts (inline `raw` bytes or a `url`) are downloaded by the plugin
+ *     (http/https only, size- and time-bounded) when they carry a URL;
  *   - an optional deployment materializer puts non-image files into the
  *     active execution world instead of saving a host attachment;
- *   - without a materializer, files with no store (or refused by a store)
- *     persist under the configured upload root (default `<OS temp>/
+ *   - without a materializer, non-image files persist under the configured
+ *     upload root even when an attachment store exists (default `<OS temp>/
  *     dsh-a2a-uploads/<date>/`) and the prompt references them by path;
  *   - `data` parts become JSON text.
  *
@@ -36,6 +35,6 @@ interface Materialization {
     materializer: A2aFileMaterializer;
 }
 export declare function buildMessageContent(parts: readonly Part[], attachments: AttachmentStore | undefined, dir: string, materialization?: Materialization): Promise<ContentBlock[]>;
-/** The directory file parts persist into when they are not attachments. */
+/** The directory non-image file parts persist into without a materializer. */
 export declare function uploadsDir(root?: string): string;
 export {};

package/lib/types/executor.d.ts

@@ -3,7 +3,7 @@
  * bridge. One `execute()` = one user-message turn:
  *
  *   1. map the message's parts onto dsh content blocks (file parts become
- *      execution-world paths with a materializer, attachments or local files otherwise)
+ *      execution-world paths with a materializer, local paths otherwise)
  *   2. ensure the task's session/agent exists (creating it on first contact)
  *   3. publish a `task` event first — A2A 1.0 stream ordering REQUIRES the
  *      first event of every execute to be a task or message, including

package/lib/types/index.d.ts

@@ -14,6 +14,20 @@
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
 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[];
@@ -25,8 +39,8 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema<string, string>;
     /**
-     * Root directory file parts persist into when no attachment store is
-     * composed (date-layered below it). Empty = <OS temp>/dsh-a2a-uploads.
+     * Root directory for fallback or opted-in local file parts (date-layered
+     * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema<string, string>;
     agent: Schema<Schemastery.ObjectS<{
@@ -90,8 +104,8 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     /** Working directory for agents spawned by A2A tasks. Must be absolute. */
     cwd: Schema<string, string>;
     /**
-     * Root directory file parts persist into when no attachment store is
-     * composed (date-layered below it). Empty = <OS temp>/dsh-a2a-uploads.
+     * Root directory for fallback or opted-in local file parts (date-layered
+     * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema<string, string>;
     agent: Schema<Schemastery.ObjectS<{

package/package.json

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