@amaster.ai/dsh-a2a 0.1.20 → 0.1.21

package/README.md

@@ -30,6 +30,8 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
           intervalMs: 15000  # positive integer, at most 2147483647
         cwd: /srv/agent-workspaces
         uploadsDir: ''         # file-part upload root; empty = <OS temp>/dsh-a2a-uploads/<date>
+        subagentTools:
+          enabled: false      # opt in to attributed local descendant tool calls/results
         agent:
           provider: ''       # dsh provider/model for A2A sessions; empty = profile default
           model: ''
@@ -103,6 +105,14 @@ queue or catch-up burst. Timers stop on completion, disconnect, response errors,
 and server disposal. Heartbeats require a responsive event loop; they cannot
 repair event-loop starvation or guarantee delivery during backpressure.
 
+## Subagent tools
+
+`subagentTools.enabled` defaults to `false`. When enabled, tool calls/results from local descendant sessions created inside `tools/execute` are forwarded to the owning A2A task. Each child has a separate translator: its text, reasoning, usage and turn state never enter the parent's translator, and child completion or disposal never settles the parent task. Main-agent streaming keeps its existing format.
+
+Child events retain the parent's A2A `taskId` and `contextId`. `metadata.dshAgent.source` carries `{ sessionId, agentId, parentSessionId, parentCallId }` (exported as `SubagentToolSource`): the source child, its immediate parent, and the exact dispatch call that created it. DSH agent IDs are session IDs. Use `(source.sessionId, data.callId)` to identify a child tool call; use `(source.parentSessionId, source.parentCallId)` to attach it to its delegation, including nested descendants. The link is captured with async dispatch context, never inferred from event ordering or descriptions. Verified against DSH 0.2.0-rc.1 and 0.2.0-rc.2's in-process child creation path.
+
+Forwarding follows the owning task's active request bus. Background child events between streams are dropped, with no buffering, replay, extra stream or extension of parent settlement; if the same task opens another stream, live events can appear there. Rebinding the parent context to a new task permanently excludes children created for the old task. Providers running outside this process expose no local child events, so only their parent delegation call/result remain visible. Sessions without a captured dispatch link (including children loaded after a process restart, or created outside tool dispatch) are not forwarded; durable attribution for those cases requires an upstream DSH lineage field.
+
 ## Task stores
 
 A2A task snapshots retain protocol history and artifacts; [dsh-storage](../dsh-storage) separately records the full conversation. Backends save on task-state transitions, including the complete reply at `input-required`, so token-rate stream events never reach Redis or GCS. While a task is working, in-process history accumulates text deltas for `GetTask` and resubscription; a restart before the next state change can lose those transient deltas.
@@ -119,7 +129,7 @@ dsh ships **no authentication or authorization**. The server binds `127.0.0.1` b
 
 ## Compatibility
 
-Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment}@0.2.0-rc.2` — the attachment store is an optional peer) — check the `TODO(verify)` markers in `src/` before upgrading dsh.
+Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.0-rc.2` — the attachment store is an optional peer) — the session peer floor is `>=0.2.0-rc.1` because child attribution uses `firstLifecycleSeq` to reject restored sessions; check the `TODO(verify)` markers in `src/` before upgrading dsh.
 
 ## License
 

package/lib/bridge.js

@@ -13,6 +13,7 @@
  * settles at the next `turn/end`; a host may keep the same task open for
  * autonomous turns through `a2a/task-settlement`.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { TaskState } from '@a2a-js/sdk';
 import { AgentEvent } from '@a2a-js/sdk/server';
 // installModelSelection is a root-module runtime import: the dsh-agent index
@@ -37,6 +38,8 @@ export class A2aBridge {
     asked = new Map();
     approvals = new Map();
     codec;
+    delegation = new AsyncLocalStorage();
+    children = new WeakMap();
     constructor(ctx, options) {
         this.ctx = ctx;
         this.options = options;
@@ -46,6 +49,49 @@ export class A2aBridge {
         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));
+        if (options.subagentTools?.enabled) {
+            // Async context distinguishes concurrent dispatches without relying on event order.
+            ctx.on('tools/execute', (exec, next) => {
+                const session = exec.agent?.session;
+                if (!session)
+                    return next();
+                const child = this.children.get(session);
+                const entry = this.bySession.get(session.id) ?? child?.entry;
+                if (!entry || entry.staleTurn || (child && child.taskId !== entry.taskId))
+                    return next();
+                return this.delegation.run({
+                    entry,
+                    taskId: entry.taskId,
+                    parentSessionId: session.id,
+                    parentCallId: exec.callId,
+                }, next);
+            });
+            // Verified against dsh-subagent/session 0.2.0-rc.2: local child creation runs inside dispatch.
+            ctx.on('session/created', (session) => {
+                try {
+                    const delegation = this.delegation.getStore();
+                    if (!delegation ||
+                        session.header.origin !== 'subagent' ||
+                        session.header.parentSession !== delegation.parentSessionId ||
+                        // A wake/resume dispatch is not the original creating delegation.
+                        session.firstLifecycleSeq !== session.inheritedEventCount ||
+                        delegation.taskId !== delegation.entry.taskId)
+                        return;
+                    this.children.set(session, {
+                        ...delegation,
+                        translator: new SessionTranslator(delegation.taskId, delegation.entry.sessionId, undefined, {
+                            sessionId: session.id,
+                            agentId: session.id,
+                            parentSessionId: delegation.parentSessionId,
+                            parentCallId: delegation.parentCallId,
+                        }),
+                    });
+                }
+                catch (error) {
+                    console.error('[dsh-a2a] failed to attribute child session:', error);
+                }
+            });
+        }
     }
     /**
      * Resolve the live task entry, creating the session/agent when needed.
@@ -500,8 +546,23 @@ export class A2aBridge {
     }
     onSessionEvent(session, event) {
         const entry = this.bySession.get(session.id);
-        if (!entry)
+        if (!entry) {
+            const child = this.children.get(session);
+            if (!child ||
+                child.taskId !== child.entry.taskId ||
+                !child.entry.bus ||
+                child.entry.staleTurn ||
+                (event.type !== 'tool/call' && event.type !== 'tool/result'))
+                return;
+            try {
+                for (const out of child.translator.handle(event))
+                    child.entry.bus.publish(out);
+            }
+            catch (error) {
+                console.error('[dsh-a2a] failed to translate child tool event:', error);
+            }
             return;
+        }
         if (entry.staleTurn) {
             if (event.type === 'turn/end')
                 entry.staleTurn = false;
@@ -618,6 +679,7 @@ export class A2aBridge {
         }
     }
     onSessionDisposed(session) {
+        this.children.delete(session);
         const entry = this.bySession.get(session.id);
         if (!entry)
             return;

package/lib/index.js

@@ -42,6 +42,9 @@ export const Config = Schema.object({
      * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema.string().default(''),
+    subagentTools: Schema.object({
+        enabled: Schema.boolean().default(false),
+    }),
     agent: Schema.object({
         provider: Schema.string().default(''),
         model: Schema.string().default(''),
@@ -102,6 +105,7 @@ export function apply(ctx, config) {
                 model: config.agent.model || undefined,
             },
             preset: config.agent.preset || undefined,
+            subagentTools: config.subagentTools,
         });
         const store = createTaskStore(config);
         await store.init?.();

package/lib/translator.js

@@ -87,6 +87,7 @@ export class SessionTranslator {
     taskId;
     contextId;
     model;
+    source;
     /** messageId shared by this turn's streamed text deltas (client-side aggregation key). */
     textMessageId = randomUUID();
     thoughtMessageId = randomUUID();
@@ -98,10 +99,11 @@ export class SessionTranslator {
     usage;
     /** callId → tool name, for naming `tool/result` payloads. */
     toolNames = new Map();
-    constructor(taskId, contextId, model) {
+    constructor(taskId, contextId, model, source) {
         this.taskId = taskId;
         this.contextId = contextId;
         this.model = model;
+        this.source = source;
     }
     /** Translate one session event into zero or more A2A events. Never throws on unknown types. */
     handle(event) {
@@ -199,7 +201,9 @@ export class SessionTranslator {
         }
     }
     status(state, dshAgent, message, error) {
-        const metadata = { dshAgent };
+        const metadata = {
+            dshAgent: this.source ? { ...dshAgent, source: this.source } : dshAgent,
+        };
         if (this.model)
             metadata.model = this.model;
         const terminal = state !== TaskState.TASK_STATE_WORKING;

package/lib/types/bridge.d.ts

@@ -32,6 +32,10 @@ export interface BridgeOptions {
     };
     /** Agent preset id; empty/absent = the deployment default (when a roster exists). */
     preset?: string;
+    /** Forward attributed descendant tool events; disabled by default. */
+    subagentTools?: {
+        enabled: boolean;
+    };
 }
 export interface TaskEntry {
     taskId: string;
@@ -67,6 +71,8 @@ export declare class A2aBridge {
     private readonly asked;
     private readonly approvals;
     private readonly codec;
+    private readonly delegation;
+    private readonly children;
     constructor(ctx: Context, options: BridgeOptions);
     /**
      * Resolve the live task entry, creating the session/agent when needed.

package/lib/types/index.d.ts

@@ -19,6 +19,7 @@ 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';
+export type { SubagentToolSource } from './translator.js';
 /** Event emitted when one A2A user message enters the dsh inbox. */
 export declare const A2A_MESSAGE_ADMITTED_EVENT: "a2a/message-admitted";
 export interface A2aTurnContext {
@@ -84,6 +85,11 @@ export declare const Config: Schema<Schemastery.ObjectS<{
      * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema<string, string>;
+    subagentTools: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
     agent: Schema<Schemastery.ObjectS<{
         provider: Schema<string, string>;
         model: Schema<string, string>;
@@ -156,6 +162,11 @@ export declare const Config: Schema<Schemastery.ObjectS<{
      * below it). Empty = <OS temp>/dsh-a2a-uploads.
      */
     uploadsDir: Schema<string, string>;
+    subagentTools: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
     agent: Schema<Schemastery.ObjectS<{
         provider: Schema<string, string>;
         model: Schema<string, string>;
@@ -221,6 +232,9 @@ export interface A2aPluginConfig {
     };
     cwd: string;
     uploadsDir: string;
+    subagentTools: {
+        enabled: boolean;
+    };
     agent: {
         provider: string;
         model: string;

package/lib/types/translator.d.ts

@@ -40,6 +40,13 @@ import { type Message } from '@a2a-js/sdk';
 import { type AgentExecutionEvent } from '@a2a-js/sdk/server';
 import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Immediate delegation edge; tool call IDs are scoped by their source session. */
+export interface SubagentToolSource {
+    sessionId: string;
+    agentId: string;
+    parentSessionId: string;
+    parentCallId: string;
+}
 /** One agent-role text message — the single construction site for the plugin's message payloads. */
 export declare function agentTextMessage(taskId: string, contextId: string, text: string, messageId?: string): Message;
 /** A terminal (stream-closing) statusUpdate — shared by the bridge's settle path and the executor's failure/cancel paths. */
@@ -48,6 +55,7 @@ export declare class SessionTranslator {
     private readonly taskId;
     private readonly contextId;
     private readonly model?;
+    private readonly source?;
     /** messageId shared by this turn's streamed text deltas (client-side aggregation key). */
     private textMessageId;
     private thoughtMessageId;
@@ -59,7 +67,7 @@ export declare class SessionTranslator {
     private usage;
     /** callId → tool name, for naming `tool/result` payloads. */
     private readonly toolNames;
-    constructor(taskId: string, contextId: string, model?: string | undefined);
+    constructor(taskId: string, contextId: string, model?: string | undefined, source?: SubagentToolSource | undefined);
     /** Translate one session event into zero or more A2A events. Never throws on unknown types. */
     handle(event: SessionEvent): AgentExecutionEvent[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",
@@ -41,7 +41,8 @@
     "@deepseek-ai/dsh-agent": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
     "@deepseek-ai/dsh-attachment": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
     "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
     "@deepseek-ai/dsh-user-approval": ">=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
     "@google-cloud/storage": "^7.0.0",
     "ioredis": "^5.0.0"
@@ -68,6 +69,7 @@
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
     "@deepseek-ai/dsh-session": "0.2.0-rc.2",
     "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
     "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
     "@google-cloud/storage": "^7.0.0",
     "@types/express": "^4.17.21",