@amaster.ai/dsh-a2a 0.1.7 → 0.1.8

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/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

package/lib/index.js

@@ -31,8 +31,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/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

@@ -25,8 +25,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 +90,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.8",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",