@amaster.ai/dsh-a2a 0.1.6 → 0.1.7

package/README.md

@@ -57,7 +57,8 @@ 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) become durable image/file content blocks when the deployment composes an attachment store (`ctx.attachments`, e.g. `@deepseek-ai/dsh-attachment-local`): images reach vision-capable models natively, and every file projects to deterministic handle text naming the file and — on host-file-backed stores — its read-only saved path. Without a store, 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, so the agent reads or converts them with its own tools. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.
+- **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.
+- **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.
 - **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

@@ -143,9 +143,10 @@ export class A2aBridge {
         return { entry, freshTask: true };
     }
     /** A2A parts → dsh content blocks; throws only when no part is usable. */
-    async buildContent(message) {
+    async buildContent(message, contextId) {
         const attachments = this.ctx.get('attachments');
-        return buildMessageContent(message.parts, attachments, uploadsDir(this.options.uploadsDir));
+        const materializer = this.ctx.get('a2aFileMaterializer');
+        return buildMessageContent(message.parts, attachments, uploadsDir(this.options.uploadsDir), materializer ? { contextId, materializer } : undefined);
     }
     isClearing(contextId) {
         return this.clearing.has(contextId);

package/lib/content.js

@@ -3,15 +3,14 @@
  * part kinds:
  *
  *   - `text` parts stay text;
- *   - file parts (inline `raw` bytes or a `url`) become durable image/file
- *     content blocks when the deployment composes an attachment store
- *     (`ctx.attachments`, e.g. @deepseek-ai/dsh-attachment-local); url parts
- *     are downloaded by the plugin (http/https only, size- and time-bounded);
- *   - without a store — or when a store refuses the bytes — file parts
+ *   - 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);
+ *   - 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>/
- *     dsh-a2a-uploads/<date>/`) and the prompt references them by path, so
- *     the agent reads or converts them with its own tools (the same
- *     path-based model dsh-llm's file-block projection uses);
+ *     dsh-a2a-uploads/<date>/`) and the prompt references them by path;
  *   - `data` parts become JSON text.
  *
  * The SDK's admission helpers (admitEncodedFile/admitPromptContent) are not
@@ -27,7 +26,7 @@ const DOWNLOAD_TIMEOUT_MS = 30_000;
 // TODO(verify): the confirmation data-part protocol ({callId, outcome}) maps
 // onto the optional dsh-user-approval service (0.1.2+, asks carry the exact
 // tool call) — bridge it once a deployment composes that service.
-export async function buildMessageContent(parts, attachments, dir) {
+export async function buildMessageContent(parts, attachments, dir, materialization) {
     const content = [];
     for (const part of parts) {
         const c = part.content;
@@ -43,7 +42,7 @@ export async function buildMessageContent(parts, attachments, dir) {
                 break;
             case 'raw':
             case 'url':
-                content.push(await fileContent(c, part, attachments, dir));
+                content.push(await fileContent(c, part, attachments, dir, materialization));
                 break;
             default:
                 // A part kind this SDK version predates: keep it visible, never drop.
@@ -67,7 +66,7 @@ function failNote(part, mediaType, uri, label, error) {
     return note(part, mediaType, uri, error instanceof Error ? error.message : String(error));
 }
 /** Resolve one file part to an attachment block or a workspace file. */
-async function fileContent(c, part, attachments, dir) {
+async function fileContent(c, part, attachments, dir, materialization) {
     let bytes;
     let mediaType = part.mediaType;
     let uri;
@@ -85,11 +84,29 @@ async function fileContent(c, part, attachments, dir) {
     catch (error) {
         return failNote(part, mediaType, uri, 'failed to read a file part', error);
     }
-    if (attachments) {
+    const image = attachments?.imageLimits.mediaTypes.includes(mediaType.toLowerCase());
+    if (attachments && (!materialization || image)) {
         const block = await saveAttachment(attachments, bytes, mediaType, part.filename);
         if (block)
             return block;
     }
+    if (materialization && !image) {
+        try {
+            const { readablePath } = await materialization.materializer.materializeFile({
+                contextId: materialization.contextId,
+                bytes,
+                filename: sanitizeUploadFileName(part.filename),
+                mediaType,
+            });
+            if (!readablePath)
+                throw new Error('materializer returned no readable path');
+            return documentBlock(uri, mediaType, bytes.byteLength, readablePath);
+        }
+        catch (error) {
+            console.error('[dsh-a2a] failed to materialize a file part:', error);
+            return note(part, mediaType, uri, 'file materialization failed');
+        }
+    }
     try {
         const name = sanitizeUploadFileName(part.filename);
         const filePath = await persistUpload(dir, name, bytes);
@@ -156,12 +173,12 @@ function sanitizeUploadFileName(name) {
     const stem = cleaned.split('.')[0].toUpperCase();
     return !cleaned || WINDOWS_RESERVED_STEMS.has(stem) ? 'unnamed-file' : cleaned;
 }
-/** Workspace-file stand-in for a file part that did not become an attachment. */
+/** Tool-readable path stand-in for a file part. */
 function documentBlock(uri, mediaType, bytes, filePath) {
     const attrs = [
         // The basename of the final path, so name= always matches the file on
         // disk — including collision suffixes.
-        `name="${attr(path.basename(filePath))}"`,
+        `name="${attr(path.win32.basename(filePath))}"`,
         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
- *      attachments with a store composed, workspace files otherwise)
+ *      execution-world paths with a materializer, attachments or local files 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
@@ -37,7 +37,7 @@ export class DshAgentExecutor {
         const { userMessage, taskId, contextId } = requestContext;
         let anchored = false;
         try {
-            const content = await this.bridge.buildContent(userMessage);
+            const content = await this.bridge.buildContent(userMessage, contextId);
             const { entry, freshTask } = await this.bridge.ensureTask(taskId, contextId);
             eventBus.publish(freshTask
                 ? // First contact: the submitted anchor carries the user message

package/lib/types/bridge.d.ts

@@ -73,7 +73,7 @@ export declare class A2aBridge {
     }>;
     private ensureTaskInner;
     /** A2A parts → dsh content blocks; throws only when no part is usable. */
-    buildContent(message: Message): Promise<ContentBlock[]>;
+    buildContent(message: Message, contextId: string): Promise<ContentBlock[]>;
     isClearing(contextId: string): boolean;
     /** Include content preparation in the work a context clear must drain. */
     trackExecution(contextId: string, run: () => Promise<void>): Promise<void>;

package/lib/types/content.d.ts

@@ -3,15 +3,14 @@
  * part kinds:
  *
  *   - `text` parts stay text;
- *   - file parts (inline `raw` bytes or a `url`) become durable image/file
- *     content blocks when the deployment composes an attachment store
- *     (`ctx.attachments`, e.g. @deepseek-ai/dsh-attachment-local); url parts
- *     are downloaded by the plugin (http/https only, size- and time-bounded);
- *   - without a store — or when a store refuses the bytes — file parts
+ *   - 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);
+ *   - 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>/
- *     dsh-a2a-uploads/<date>/`) and the prompt references them by path, so
- *     the agent reads or converts them with its own tools (the same
- *     path-based model dsh-llm's file-block projection uses);
+ *     dsh-a2a-uploads/<date>/`) and the prompt references them by path;
  *   - `data` parts become JSON text.
  *
  * The SDK's admission helpers (admitEncodedFile/admitPromptContent) are not
@@ -21,6 +20,22 @@
 import type { Part } from '@a2a-js/sdk';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
-export declare function buildMessageContent(parts: readonly Part[], attachments: AttachmentStore | undefined, dir: string): Promise<ContentBlock[]>;
+/** Deployment-owned writer for files read by an agent's active tools. */
+export interface A2aFileMaterializer {
+    materializeFile(input: {
+        contextId: string;
+        bytes: Uint8Array;
+        filename: string;
+        mediaType: string;
+    }): Promise<{
+        readablePath: string;
+    }>;
+}
+interface Materialization {
+    contextId: string;
+    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. */
 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
- *      attachments with a store composed, workspace files otherwise)
+ *      execution-world paths with a materializer, attachments or local files 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

@@ -13,6 +13,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+export type { A2aFileMaterializer } from './content.js';
 export declare const name = "dsh-a2a";
 /** The bridge creates and owns agents through the registry service. */
 export declare const inject: string[];

package/package.json

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