@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/protocols/A2AAdapter.d.ts

@@ -1,8 +1,3 @@
-/**
- * A2A (Agent-to-Agent) protocol adapter using SSE transport.
- *
- * @module protocols/A2AAdapter
- */
 import type { ChatMessage } from '../types/messages';
 import type { ProtocolAdapterConfig, AgentCard } from '../types';
 import type { ToolDefinition, ToolExecutionResult } from '../types/tools';
@@ -11,7 +6,7 @@ import { BaseProtocolAdapter } from './BaseProtocolAdapter';
  * A2A specific configuration
  */
 export interface A2AAdapterConfig extends ProtocolAdapterConfig {
-    /** Agent URL for .well-known/agent.json discovery */
+    /** Agent URL for .well-known/agent-card.json discovery */
     agentUrl?: string;
     /** Enable A2UI extension */
     enableA2UI?: boolean;
@@ -25,8 +20,29 @@ export declare class A2AAdapter extends BaseProtocolAdapter {
     readonly protocolTransport: "sse";
     private a2aConfig;
     private abortController;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * `abortController` is a single field that each request overwrites, and each
+     * request's `finally` used to clear it unconditionally — so a request that
+     * finished just after a newer one started would null the newer one's handle,
+     * and a subsequent stop had nothing left to abort. The stream carried on and
+     * the transcript went on typing itself after the reader had asked it not to.
+     */
+    private inFlight;
     private agentCard;
     private currentTaskId;
+    /**
+     * Whether the connected agent's card advertised the Datalayer
+     * orchestration extension (ORCHESTRATOR.md, O3-03). Set once, from
+     * `connect()`'s card fetch: neither side infers support from a
+     * successful message (the extension's own negotiation rule), so this is
+     * the one place that decides it, and every request either activates the
+     * extension by this or sends nothing extension-related at all — a worker
+     * that never advertised it sees a plain A2A client, unchanged from
+     * before this existed.
+     */
+    private orchestrationExtensionSupported;
     constructor(config: A2AAdapterConfig);
     /**
      * Connect and discover agent card
@@ -44,6 +60,14 @@ export declare class A2AAdapter extends BaseProtocolAdapter {
      * Get agent card
      */
     getAgentCard(): Promise<AgentCard | null>;
+    /**
+     * Whether the connected agent advertised the Datalayer orchestration
+     * extension. `false` until `connect()` has fetched a card, and `false`
+     * for any card that does not list it — including one that could not be
+     * fetched at all, so a worker with no card behaves exactly as it did
+     * before this existed.
+     */
+    get supportsOrchestrationExtension(): boolean;
     /**
      * Send a message through A2A protocol
      */
@@ -63,6 +87,15 @@ export declare class A2AAdapter extends BaseProtocolAdapter {
             accessToken: string;
         }>;
     }): Promise<void>;
+    /**
+     * Abort every in-flight stream without tearing the adapter down.
+     *
+     * This adapter had no such method, so pressing Stop reached only
+     * `terminateTask` — a request to the backend to cancel — and never closed
+     * the client's own stream. Whatever was already on the wire kept arriving
+     * and kept being rendered. `ChatBase` looks for this by name.
+     */
+    stopGeneration(): void;
     /**
      * Send tool result back
      */

package/lib/protocols/A2AAdapter.js

@@ -2,8 +2,78 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/**
+ * A2A (Agent-to-Agent) protocol adapter using SSE transport.
+ *
+ * @module protocols/A2AAdapter
+ */
+import { ORCHESTRATION_EXTENSION_URI, ENVELOPE_KEY as DATALAYER_META_KEY, readUsageMeta, } from '@datalayer/agent-teams';
 import { generateMessageId, createAssistantMessage } from '../types/messages';
 import { BaseProtocolAdapter } from './BaseProtocolAdapter';
+/**
+ * The header fasta2a-based workers (`agent-runtimes`'s own, and any other
+ * built on it) actually read to activate an extension for one request —
+ * confirmed from `fasta2a.extensions`, not assumed: comma-separated URIs,
+ * answered on the same header naming which of them the agent knows.
+ * Neither this codebase's own `configuration.requestedExtensions` (read by
+ * nothing server-side) nor the A2A SDK's `Message.extensions` field is what
+ * a `fasta2a` worker's `activated_extensions()` looks at — this header is.
+ */
+const A2A_EXTENSIONS_HEADER = 'A2A-Extensions';
+const TERMINAL_TASK_STATES = new Set([
+    'completed',
+    'failed',
+    'canceled',
+    'rejected',
+]);
+/**
+ * `fasta2a` wraps every `message/send` result and every `message/stream`
+ * event in a named key — `{ task: Task }`, `{ statusUpdate: ... }`,
+ * `{ artifactUpdate: ... }`, `{ message: Message }` — instead of the bare,
+ * `kind`-discriminated object
+ * (`Task.kind: 'task'`, `TaskStatusUpdateEvent.kind: 'status-update'`, ...)
+ * the current A2A specification requires and this file was written
+ * against. Confirmed directly, not assumed: `fasta2a.schema.SendMessageResult`
+ * and `StreamResponse` are TypedDicts with those named optional fields, and
+ * neither `Task` nor `TaskStatusUpdateEvent` in that schema carries a
+ * `kind` field at all. `agent_runtimes`' own A2A route is the same
+ * `FastA2A`, so every production Datalayer A2A worker serves this shape —
+ * a spec-conformant client (this file, or a genuine `a2a-sdk`-based one)
+ * could not render a single reply without this normalizer.
+ *
+ * A worker built to the current spec (its `result` already carries
+ * `kind`) passes through unchanged — this only steps in for the shape
+ * `fasta2a` actually sends.
+ *
+ * `fasta2a`'s `TaskStatusUpdateEvent` also has no `final` field, which the
+ * spec has and this file's status-update handling gates on; inferred here
+ * from the status being one of the terminal states, since nothing else in
+ * the payload says so.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function normalizeA2AResult(result) {
+    if (!result || typeof result !== 'object' || result.kind) {
+        return result;
+    }
+    if (result.task) {
+        return { ...result.task, kind: 'task' };
+    }
+    if (result.statusUpdate) {
+        const update = result.statusUpdate;
+        return {
+            ...update,
+            kind: 'status-update',
+            final: update.final ?? TERMINAL_TASK_STATES.has(update.status?.state),
+        };
+    }
+    if (result.artifactUpdate) {
+        return { ...result.artifactUpdate, kind: 'artifact-update' };
+    }
+    if (result.message) {
+        return { ...result.message, kind: 'message' };
+    }
+    return result;
+}
 /**
  * A2A protocol adapter
  * Uses JSON-RPC 2.0 with SSE streaming for responses
@@ -13,8 +83,29 @@ export class A2AAdapter extends BaseProtocolAdapter {
     protocolTransport = 'sse';
     a2aConfig;
     abortController = null;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * `abortController` is a single field that each request overwrites, and each
+     * request's `finally` used to clear it unconditionally — so a request that
+     * finished just after a newer one started would null the newer one's handle,
+     * and a subsequent stop had nothing left to abort. The stream carried on and
+     * the transcript went on typing itself after the reader had asked it not to.
+     */
+    inFlight = new Set();
     agentCard = null;
     currentTaskId = null;
+    /**
+     * Whether the connected agent's card advertised the Datalayer
+     * orchestration extension (ORCHESTRATOR.md, O3-03). Set once, from
+     * `connect()`'s card fetch: neither side infers support from a
+     * successful message (the extension's own negotiation rule), so this is
+     * the one place that decides it, and every request either activates the
+     * extension by this or sends nothing extension-related at all — a worker
+     * that never advertised it sees a plain A2A client, unchanged from
+     * before this existed.
+     */
+    orchestrationExtensionSupported = false;
     constructor(config) {
         super(config);
         this.a2aConfig = {
@@ -28,9 +119,18 @@ export class A2AAdapter extends BaseProtocolAdapter {
     async connect() {
         this.setConnectionState('connecting');
         try {
-            // Fetch agent card from .well-known endpoint
+            // Fetch agent card from .well-known endpoint. The current A2A
+            // specification's path is `agent-card.json` — `fasta2a`'s FastA2A
+            // (and a2a-sdk's own A2ACardResolver default) serves only that,
+            // confirmed by reading FastA2A's own route registration; the plain
+            // `agent.json` this fetched before was an earlier draft's path, and
+            // fetching it here 404s against every real worker, silently, since
+            // a missing card is caught below and connect() still "succeeds" —
+            // found live, against agent_teams.a2a.reference_worker
+            // (ORCHESTRATOR.md O3-04), not assumed: `supportsOrchestrationExtension`
+            // stayed false against a worker whose card plainly advertised it.
             const agentUrl = this.a2aConfig.agentUrl || this.a2aConfig.baseUrl;
-            const wellKnownUrl = new URL('/.well-known/agent.json', agentUrl).toString();
+            const wellKnownUrl = new URL('/.well-known/agent-card.json', agentUrl).toString();
             const response = await fetch(wellKnownUrl, {
                 method: 'GET',
                 headers: this.buildHeaders(),
@@ -38,6 +138,8 @@ export class A2AAdapter extends BaseProtocolAdapter {
             });
             if (response.ok) {
                 this.agentCard = await response.json();
+                this.orchestrationExtensionSupported =
+                    this.agentCard?.capabilities?.extensions?.some(extension => extension.uri === ORCHESTRATION_EXTENSION_URI) ?? false;
             }
             this.setConnectionState('connected');
         }
@@ -51,10 +153,8 @@ export class A2AAdapter extends BaseProtocolAdapter {
      * Disconnect and terminate any ongoing agent execution
      */
     disconnect() {
-        if (this.abortController) {
-            this.abortController.abort();
-            this.abortController = null;
-        }
+        // Every open stream, not merely the newest.
+        this.stopGeneration();
         // Send terminate request to backend if we have a task ID
         if (this.currentTaskId) {
             this.terminateTask(this.currentTaskId).catch(err => {
@@ -99,11 +199,23 @@ export class A2AAdapter extends BaseProtocolAdapter {
     async getAgentCard() {
         return this.agentCard;
     }
+    /**
+     * Whether the connected agent advertised the Datalayer orchestration
+     * extension. `false` until `connect()` has fetched a card, and `false`
+     * for any card that does not list it — including one that could not be
+     * fetched at all, so a worker with no card behaves exactly as it did
+     * before this existed.
+     */
+    get supportsOrchestrationExtension() {
+        return this.orchestrationExtensionSupported;
+    }
     /**
      * Send a message through A2A protocol
      */
     async sendMessage(message, options) {
-        this.abortController = new AbortController();
+        const controller = new AbortController();
+        this.abortController = controller;
+        this.inFlight.add(controller);
         const taskId = options?.threadId || this.currentTaskId || generateMessageId();
         this.currentTaskId = taskId;
         // Build A2A message parts (A2A uses 'kind' discriminator, not 'type')
@@ -166,9 +278,15 @@ export class A2AAdapter extends BaseProtocolAdapter {
                 method: 'POST',
                 headers: this.buildHeaders({
                     Accept: 'text/event-stream, application/json',
+                    // Activates the extension for this one request, only once the
+                    // worker's own card advertised it — degrading to a plain A2A
+                    // request (no header at all) otherwise.
+                    ...(this.orchestrationExtensionSupported && {
+                        [A2A_EXTENSIONS_HEADER]: ORCHESTRATION_EXTENSION_URI,
+                    }),
                 }),
                 body: JSON.stringify(jsonRpcRequest),
-                signal: this.abortController.signal,
+                signal: controller.signal,
             });
             if (!response.ok) {
                 throw new Error(`A2A request failed: ${response.status} ${response.statusText}`);
@@ -198,8 +316,26 @@ export class A2AAdapter extends BaseProtocolAdapter {
             throw error;
         }
         finally {
-            this.abortController = null;
+            this.inFlight.delete(controller);
+            if (this.abortController === controller) {
+                this.abortController = null;
+            }
+        }
+    }
+    /**
+     * Abort every in-flight stream without tearing the adapter down.
+     *
+     * This adapter had no such method, so pressing Stop reached only
+     * `terminateTask` — a request to the backend to cancel — and never closed
+     * the client's own stream. Whatever was already on the wire kept arriving
+     * and kept being rendered. `ChatBase` looks for this by name.
+     */
+    stopGeneration() {
+        for (const controller of this.inFlight) {
+            controller.abort();
         }
+        this.inFlight.clear();
+        this.abortController = null;
     }
     /**
      * Send tool result back
@@ -269,7 +405,7 @@ export class A2AAdapter extends BaseProtocolAdapter {
         console.log('[A2AAdapter] Received event:', JSON.stringify(event, null, 2));
         // Handle JSON-RPC response
         if (event.result) {
-            this.handleTaskUpdate(event.result);
+            this.handleTaskUpdate(normalizeA2AResult(event.result));
         }
         else if (event.error) {
             this.emit({
@@ -298,9 +434,42 @@ export class A2AAdapter extends BaseProtocolAdapter {
             console.log('[A2AAdapter] Status update:', state, 'final:', task.final);
             if (task.final &&
                 (state === 'completed' || state === 'failed' || state === 'canceled')) {
+                // Only read the envelope once the worker actually named the
+                // extension active — a plain worker's status carries no
+                // `datalayer` key, and this stays `undefined` for it exactly as
+                // it did before the extension existed.
+                const datalayerMeta = this.orchestrationExtensionSupported
+                    ? task.status?.message?.metadata?.[DATALAYER_META_KEY]
+                    : undefined;
+                const datalayerUsage = datalayerMeta
+                    ? readUsageMeta(task.status.message.metadata)
+                    : undefined;
                 this.emit({
                     type: 'state-update',
-                    data: { state, final: true },
+                    data: {
+                        state,
+                        final: true,
+                        ...(datalayerMeta?.paused && {
+                            datalayerPaused: datalayerMeta.paused,
+                        }),
+                        ...(datalayerMeta?.error && {
+                            datalayerError: datalayerMeta.error,
+                        }),
+                        ...(datalayerUsage && { datalayerUsage }),
+                    },
+                    // Best-effort mapping onto the cross-protocol shape; a worker
+                    // that priced the run also sets `datalayerUsage.cost`, which
+                    // has no field here and is not dropped — it is still on `data`.
+                    ...(datalayerUsage && {
+                        usage: {
+                            promptTokens: datalayerUsage.inputTokens ?? 0,
+                            completionTokens: datalayerUsage.outputTokens ?? 0,
+                            ...(datalayerUsage.inputTokens !== undefined &&
+                                datalayerUsage.outputTokens !== undefined && {
+                                totalTokens: datalayerUsage.inputTokens + datalayerUsage.outputTokens,
+                            }),
+                        },
+                    }),
                     timestamp: new Date(),
                 });
             }

package/lib/protocols/ACPAdapter.js

@@ -183,17 +183,16 @@ export class ACPAdapter extends BaseProtocolAdapter {
                 console.warn('[ACPAdapter] Cannot terminate: No session ID');
                 return;
             }
-            // Send session/cancel JSON-RPC request
-            const requestId = `cancel-${Date.now()}`;
-            const cancelRequest = {
+            // A notification, as the ACP schema makes session/cancel: no id and no
+            // answer. The running prompt answers with stopReason "cancelled".
+            const cancelNotification = {
                 jsonrpc: '2.0',
                 method: 'session/cancel',
                 params: {
                     sessionId: targetSessionId,
                 },
-                id: requestId,
             };
-            this.ws.send(JSON.stringify(cancelRequest));
+            this.ws.send(JSON.stringify(cancelNotification));
             console.debug('[ACPAdapter] Sent session/cancel for:', targetSessionId);
         }
         catch (err) {
@@ -237,7 +236,7 @@ export class ACPAdapter extends BaseProtocolAdapter {
             }
             await this.sendRequest(AGENT_METHODS.session_prompt, {
                 sessionId: this.session.sessionId,
-                content: [{ type: 'text', text: content }],
+                prompt: [{ type: 'text', text: content }],
                 // Include metadata with model and identities
                 ...(Object.keys(metadata).length > 0 && { metadata }),
             });
@@ -413,12 +412,22 @@ export class ACPAdapter extends BaseProtocolAdapter {
      * Handle session update notifications
      */
     handleSessionUpdate(params) {
-        const updateType = params.sessionUpdate;
-        // Handle streaming text chunks
-        if (updateType === 'agent_message_chunk' && params.chunk) {
-            const chunk = params.chunk;
-            // Filter out debug StreamEvent strings
-            if (!chunk.startsWith('StreamEvent(')) {
+        // As the ACP schema spells it: the update nested under `update`, its text
+        // in a content block. A failed turn is the prompt's JSON-RPC error, not an
+        // update.
+        const update = params.update;
+        if (!update) {
+            return;
+        }
+        const updateType = update.sessionUpdate;
+        const textOf = (content) => content &&
+            typeof content === 'object' &&
+            content.type === 'text'
+            ? String(content.text ?? '')
+            : '';
+        if (updateType === 'agent_message_chunk') {
+            const chunk = textOf(update.content);
+            if (chunk) {
                 this.streamingContent += chunk;
                 // Use stable message ID for streaming updates
                 const streamingMessage = createAssistantMessage(this.streamingContent);
@@ -432,47 +441,41 @@ export class ACPAdapter extends BaseProtocolAdapter {
                 });
             }
         }
-        // Handle tool calls
         if (updateType === 'tool_call') {
+            const call = update;
             this.emit({
                 type: 'tool-call',
                 toolCall: {
-                    toolCallId: params.toolCallId || generateMessageId(),
-                    toolName: params.title || '',
-                    args: params.rawInput || {},
+                    toolCallId: call.toolCallId || generateMessageId(),
+                    toolName: call.title || '',
+                    args: call.rawInput || {},
                 },
                 timestamp: new Date(),
             });
         }
-        // Handle tool results
         if (updateType === 'tool_call_update') {
+            const progress = update;
             this.emit({
                 type: 'tool-result',
                 toolResult: {
-                    success: true,
-                    result: params.rawOutput,
-                },
-                timestamp: new Date(),
-            });
-        }
-        // Handle thought chunks (could be displayed differently)
-        if (updateType === 'agent_thought_chunk' && params.chunk) {
-            this.emit({
-                type: 'activity',
-                activity: {
-                    type: 'thought',
-                    data: params.chunk,
+                    success: progress.status !== 'failed',
+                    result: progress.rawOutput,
                 },
                 timestamp: new Date(),
             });
         }
-        // Handle error events - emit as error, not as message
-        if (params.error) {
-            this.emit({
-                type: 'error',
-                error: new Error(params.error),
-                timestamp: new Date(),
-            });
+        if (updateType === 'agent_thought_chunk') {
+            const thought = textOf(update.content);
+            if (thought) {
+                this.emit({
+                    type: 'activity',
+                    activity: {
+                        type: 'thought',
+                        data: thought,
+                    },
+                    timestamp: new Date(),
+                });
+            }
         }
     }
     /**

package/lib/protocols/AGUIAdapter.d.ts

@@ -23,6 +23,20 @@ export declare class AGUIAdapter extends BaseProtocolAdapter {
     readonly protocolTransport: "sse";
     private aguiConfig;
     private abortController;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * A turn is rarely one request. Each tool result starts a continuation
+     * through `sendMessage`, and that overwrites `abortController` — so the
+     * moment two streams overlap, the earlier one's controller is no longer
+     * reachable and `stopGeneration` cannot abort it. It aborted whichever
+     * request happened to be last and left the others pouring tokens into a
+     * transcript the reader had already asked to stop, which is worst in
+     * exactly the tool-heavy sessions where stopping matters most.
+     *
+     * A set, because the fix has to hold however many are open.
+     */
+    private inFlight;
     private currentThreadId;
     private pendingToolCalls;
     private collectedToolResults;

package/lib/protocols/AGUIAdapter.js

@@ -13,6 +13,20 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     protocolTransport = 'sse';
     aguiConfig;
     abortController = null;
+    /**
+     * Every in-flight request's abort controller, not just the newest.
+     *
+     * A turn is rarely one request. Each tool result starts a continuation
+     * through `sendMessage`, and that overwrites `abortController` — so the
+     * moment two streams overlap, the earlier one's controller is no longer
+     * reachable and `stopGeneration` cannot abort it. It aborted whichever
+     * request happened to be last and left the others pouring tokens into a
+     * transcript the reader had already asked to stop, which is worst in
+     * exactly the tool-heavy sessions where stopping matters most.
+     *
+     * A set, because the fix has to hold however many are open.
+     */
+    inFlight = new Set();
     currentThreadId = null;
     // Track in-progress tool calls to accumulate args and emit results
     pendingToolCalls = new Map();
@@ -66,11 +80,8 @@ export class AGUIAdapter extends BaseProtocolAdapter {
      * Disconnect and terminate any ongoing agent execution
      */
     disconnect() {
-        // Abort any ongoing fetch request
-        if (this.abortController) {
-            this.abortController.abort();
-            this.abortController = null;
-        }
+        // Abort every ongoing fetch request, not merely the newest.
+        this.stopGeneration();
         // Send terminate request to backend if we have a thread ID
         if (this.currentThreadId) {
             this.terminateAgent(this.currentThreadId).catch(err => {
@@ -112,7 +123,12 @@ export class AGUIAdapter extends BaseProtocolAdapter {
      * @param options - Options including full message history
      */
     async sendMessage(message, options) {
-        this.abortController = new AbortController();
+        // Held in a local as well as the field: by the time the `finally` below
+        // runs, a continuation may already have replaced the field, and this
+        // request must only ever retire its own controller.
+        const controller = new AbortController();
+        this.abortController = controller;
+        this.inFlight.add(controller);
         const threadId = options?.threadId || this.currentThreadId || generateMessageId();
         this.currentThreadId = threadId;
         // Use full message history if provided, otherwise just the new message
@@ -195,7 +211,7 @@ export class AGUIAdapter extends BaseProtocolAdapter {
                     Accept: 'text/event-stream',
                 }),
                 body: JSON.stringify(runAgentInput),
-                signal: this.abortController.signal,
+                signal: controller.signal,
             });
             if (!response.ok) {
                 throw new Error(`AG-UI request failed: ${response.status} ${response.statusText}`);
@@ -215,7 +231,13 @@ export class AGUIAdapter extends BaseProtocolAdapter {
             throw error;
         }
         finally {
-            this.abortController = null;
+            // This request's own controller, captured before any continuation could
+            // have replaced the field — clearing the field itself would drop a
+            // newer, still-running request's handle on the floor.
+            this.inFlight.delete(controller);
+            if (this.abortController === controller) {
+                this.abortController = null;
+            }
         }
     }
     /**
@@ -352,7 +374,10 @@ export class AGUIAdapter extends BaseProtocolAdapter {
      * the adapter connection.
      */
     stopGeneration() {
-        this.abortController?.abort();
+        for (const controller of this.inFlight) {
+            controller.abort();
+        }
+        this.inFlight.clear();
         this.abortController = null;
     }
     /**