@gaunt-sloth/agent 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/modules/a2a/A2AClientWrapper.d.ts

@@ -5,12 +5,33 @@ export interface A2AClientConfig {
     /** URL endpoint for the A2A agent */
     agentUrl: string;
 }
+/**
+ * A single A2A turn's result with its conversation-continuity handles (BATCH-14). Unlike the
+ * text-only {@link A2AClientWrapper.sendMessage}, this carries the `contextId`/`taskId` the server
+ * returned so a caller can thread them into follow-up turns (an ADK agent keeps conversational
+ * context by `contextId`). Both are optional because a response may be a bare `Message` (which
+ * carries them only optionally) or a `Task` (which always carries `contextId`, and `id` as the
+ * taskId).
+ */
+export interface A2AMessageResult {
+    /** The agent's answer text, extracted from the response's text parts. */
+    text: string;
+    /** The A2A context id to thread into subsequent turns for conversational continuity. */
+    contextId?: string;
+    /** The A2A task id, when the response was a Task (`Task.id`) or a task-scoped Message. */
+    taskId?: string;
+}
+/** Optional conversation-continuity handles to attach to an outgoing A2A message (BATCH-14). */
+export interface A2ASendContext {
+    contextId?: string;
+    taskId?: string;
+}
 /**
  * Wrapper around the A2A SDK client for communicating with external agents.
  * @experimental
  */
 export declare class A2AClientWrapper {
-    private client;
+    private clientPromise;
     private config;
     constructor(config: A2AClientConfig);
     /**
@@ -19,4 +40,38 @@ export declare class A2AClientWrapper {
      * @returns The agent's response as a string
      */
     sendMessage(messageText: string): Promise<string>;
+    /**
+     * BATCH-14 — send one message and return its text ALONG WITH the A2A `contextId`/`taskId` needed to
+     * thread a multi-turn conversation. Reads the real `@a2a-js/sdk` result shapes rather than a
+     * loose envelope:
+     *
+     * - A **Message** result carries its text in `parts` and `contextId`/`taskId` directly (both
+     *   optional, and empty-string when absent in the v1.0 proto model).
+     * - A **Task** result — what Google ADK agents commonly return — carries text in
+     *   `status.message.parts` (falling back to the last artifact's parts), `contextId` (required), and
+     *   the taskId as `Task.id`.
+     *
+     * `context.contextId`/`taskId` are attached to the OUTGOING message only when defined, so a
+     * first-turn send stays byte-identical to a contextless one.
+     *
+     * @param messageText - The message to send to the agent.
+     * @param context - Optional context/task ids to continue an existing conversation.
+     * @returns The agent's text answer plus the context/task ids from its response.
+     */
+    sendMessageWithContext(messageText: string, context?: A2ASendContext): Promise<A2AMessageResult>;
+    /** Build the outgoing `SendMessageRequest`. The v1.0 data model is generated from the A2A
+     * protobufs, so every field is required rather than optional: `role` is the numeric {@link Role}
+     * enum (not `'user'`), a text part is `{ content: { $case: 'text', value } }` (not
+     * `{ kind: 'text', text }`), and the continuity handles are empty strings rather than absent
+     * when there is no conversation to continue. */
+    private static buildSendRequest;
+    /** Normalize a `Message | Task` A2A result into text + continuity handles (BATCH-14). Static +
+     * tolerant of missing optional fields so it can be reused and unit-tested directly. */
+    private static extractResult;
+    /** v1.0 dropped the `kind` discriminator that told a Message from a Task, so discriminate
+     * structurally: `messageId` is required on every Message and never present on a Task. */
+    private static isTask;
+    /** Concatenate the text of every {@link https://github.com/a2aproject/A2A TextPart} in `parts`
+     * (ignoring file/data parts), or `''` when there is no text part. */
+    private static extractText;
 }

package/dist/modules/a2a/A2AClientWrapper.js

@@ -3,20 +3,48 @@
  * Wrapper for A2A (Agent-to-Agent) protocol client.
  * @experimental A2A support is experimental and may change.
  */
-import { A2AClient } from '@a2a-js/sdk/client';
+import { ClientFactory, ClientFactoryOptions, DefaultAgentCardResolver, JsonRpcTransportFactory, RestTransportFactory, } from '@a2a-js/sdk/client';
+import { Role } from '@a2a-js/sdk';
 import { debugLog, debugLogError } from '@gaunt-sloth/core/utils/debugUtils.js';
 import { v4 as uuidv4 } from 'uuid';
+/** The A2A spec's well-known agent-card path. The SDK's resolver needs the full CARD url, whereas
+ * {@link A2AClientConfig.agentUrl} is the agent's BASE url — so we append this ourselves and hand
+ * the resolver an empty relative path, keeping the fetched card URL byte-identical to what the
+ * pre-1.0 `A2AClient` string constructor produced. (Letting the resolver append its own default
+ * would resolve the path RELATIVE to the base url, silently dropping a base path segment: for
+ * `http://host/a2a` it would fetch `http://host/.well-known/agent-card.json`.) */
+const AGENT_CARD_PATH = '.well-known/agent-card.json';
 /**
  * Wrapper around the A2A SDK client for communicating with external agents.
  * @experimental
  */
 export class A2AClientWrapper {
-    client;
+    clientPromise;
     config;
     constructor(config) {
         this.config = config;
-        // Initialize with agent URL. The SDK will fetch the agent card.
-        this.client = new A2AClient(config.agentUrl);
+        // `@a2a-js/sdk` 1.0 removed the `A2AClient` class outright; a client is now built by a
+        // `ClientFactory` from the agent card. `legacyCompat` is enabled on the card resolver AND on
+        // every transport factory so we keep talking to agents still on protocol v0.3 — which is what
+        // Google ADK agents (our only real A2A peer today, see adk-eval-it/) currently speak. With it
+        // on, the resolver detects a v0.3-shaped card, translates it to the v1.0 model and stamps each
+        // synthesized interface `protocolVersion: '0.3'`, and the matching factory then instantiates
+        // the v0.3 wire transport. A v1.0 agent is served by the native transports unchanged, so this
+        // wrapper speaks to both.
+        const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+            cardResolver: new DefaultAgentCardResolver({ legacyCompat: { enabled: true } }),
+            transports: [
+                new JsonRpcTransportFactory({ legacyCompat: { enabled: true } }),
+                new RestTransportFactory({ legacyCompat: { enabled: true } }),
+            ],
+        }));
+        // Client construction is async (it fetches the card), so we hold the promise and await it per
+        // send. Empty path = "the base url IS the card url" — see AGENT_CARD_PATH.
+        const cardUrl = `${config.agentUrl.replace(/\/+$/, '')}/${AGENT_CARD_PATH}`;
+        this.clientPromise = factory.createFromUrl(cardUrl, '');
+        // Guard against an unhandled rejection if the wrapper is constructed but never used; real
+        // callers still observe the rejection when they await `clientPromise` inside a send method.
+        void this.clientPromise.catch(() => undefined);
     }
     /**
      * Sends a message to the A2A agent and returns the response.
@@ -26,38 +54,110 @@ export class A2AClientWrapper {
     async sendMessage(messageText) {
         debugLog(`Sending message to A2A agent ${this.config.agentId} at ${this.config.agentUrl}: ${messageText}`);
         try {
-            const messageId = uuidv4();
-            const response = await this.client.sendMessage({
-                message: {
-                    kind: 'message',
-                    messageId: messageId,
-                    role: 'user',
-                    parts: [{ kind: 'text', text: messageText }],
-                },
-            });
-            debugLog(`Received response from A2A agent: ${JSON.stringify(response)}`);
-            // Check for error response
-            if ('error' in response) {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                throw new Error(`A2A Error: ${JSON.stringify(response.error)}`);
-            }
-            // Extract text from response
-            // The result is likely a TaskStatus which contains a message
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const result = response.result;
-            if (result.message && result.message.parts && result.message.parts.length > 0) {
-                // Assuming the first part is text for now
-                return result.message.parts[0].text || JSON.stringify(result.message.parts);
-            }
-            else if (result.state) {
-                return `Task state: ${result.state}`;
-            }
-            return JSON.stringify(result);
+            const client = await this.clientPromise;
+            const result = await client.sendMessage(A2AClientWrapper.buildSendRequest(messageText, uuidv4()));
+            debugLog(`Received response from A2A agent: ${JSON.stringify(result)}`);
+            return A2AClientWrapper.extractResult(result).text;
         }
         catch (error) {
             debugLogError('Error sending message to A2A agent', error);
             throw error;
         }
     }
+    /**
+     * BATCH-14 — send one message and return its text ALONG WITH the A2A `contextId`/`taskId` needed to
+     * thread a multi-turn conversation. Reads the real `@a2a-js/sdk` result shapes rather than a
+     * loose envelope:
+     *
+     * - A **Message** result carries its text in `parts` and `contextId`/`taskId` directly (both
+     *   optional, and empty-string when absent in the v1.0 proto model).
+     * - A **Task** result — what Google ADK agents commonly return — carries text in
+     *   `status.message.parts` (falling back to the last artifact's parts), `contextId` (required), and
+     *   the taskId as `Task.id`.
+     *
+     * `context.contextId`/`taskId` are attached to the OUTGOING message only when defined, so a
+     * first-turn send stays byte-identical to a contextless one.
+     *
+     * @param messageText - The message to send to the agent.
+     * @param context - Optional context/task ids to continue an existing conversation.
+     * @returns The agent's text answer plus the context/task ids from its response.
+     */
+    async sendMessageWithContext(messageText, context) {
+        debugLog(`Sending message (with context) to A2A agent ${this.config.agentId} at ` +
+            `${this.config.agentUrl}: ${messageText}` +
+            (context?.contextId ? ` [contextId=${context.contextId}]` : ''));
+        try {
+            const client = await this.clientPromise;
+            const result = await client.sendMessage(A2AClientWrapper.buildSendRequest(messageText, uuidv4(), context));
+            debugLog(`Received response from A2A agent: ${JSON.stringify(result)}`);
+            return A2AClientWrapper.extractResult(result);
+        }
+        catch (error) {
+            debugLogError('Error sending message (with context) to A2A agent', error);
+            throw error;
+        }
+    }
+    /** Build the outgoing `SendMessageRequest`. The v1.0 data model is generated from the A2A
+     * protobufs, so every field is required rather than optional: `role` is the numeric {@link Role}
+     * enum (not `'user'`), a text part is `{ content: { $case: 'text', value } }` (not
+     * `{ kind: 'text', text }`), and the continuity handles are empty strings rather than absent
+     * when there is no conversation to continue. */
+    static buildSendRequest(messageText, messageId, context) {
+        const message = {
+            messageId,
+            contextId: context?.contextId ?? '',
+            taskId: context?.taskId ?? '',
+            role: Role.ROLE_USER,
+            parts: [
+                {
+                    content: { $case: 'text', value: messageText },
+                    metadata: undefined,
+                    filename: '',
+                    mediaType: 'text/plain',
+                },
+            ],
+            metadata: undefined,
+            extensions: [],
+            referenceTaskIds: [],
+        };
+        return { tenant: '', message, configuration: undefined, metadata: undefined };
+    }
+    /** Normalize a `Message | Task` A2A result into text + continuity handles (BATCH-14). Static +
+     * tolerant of missing optional fields so it can be reused and unit-tested directly. */
+    static extractResult(result) {
+        if (A2AClientWrapper.isTask(result)) {
+            const statusParts = result.status?.message?.parts;
+            const artifactParts = result.artifacts?.[result.artifacts.length - 1]?.parts;
+            const text = A2AClientWrapper.extractText(statusParts ?? artifactParts) || JSON.stringify(result);
+            return {
+                text,
+                contextId: result.contextId || undefined,
+                taskId: result.id || undefined,
+            };
+        }
+        const text = A2AClientWrapper.extractText(result?.parts) || JSON.stringify(result);
+        // The proto model uses '' (not undefined) for an absent id; normalize back to undefined so a
+        // caller can't thread an empty handle into the next turn.
+        return {
+            text,
+            contextId: result?.contextId || undefined,
+            taskId: result?.taskId || undefined,
+        };
+    }
+    /** v1.0 dropped the `kind` discriminator that told a Message from a Task, so discriminate
+     * structurally: `messageId` is required on every Message and never present on a Task. */
+    static isTask(result) {
+        return typeof result?.messageId !== 'string';
+    }
+    /** Concatenate the text of every {@link https://github.com/a2aproject/A2A TextPart} in `parts`
+     * (ignoring file/data parts), or `''` when there is no text part. */
+    static extractText(parts) {
+        if (!parts || parts.length === 0)
+            return '';
+        return parts
+            .filter((part) => part?.content?.$case === 'text')
+            .map((part) => part.content?.value)
+            .join('\n');
+    }
 }
 //# sourceMappingURL=A2AClientWrapper.js.map

package/dist/modules/a2a/A2AClientWrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"A2AClientWrapper.js","sourceRoot":"","sources":["../../../src/modules/a2a/A2AClientWrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAUpC;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAY;IAClB,MAAM,CAAkB;IAEhC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,gEAAgE;QAChE,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,WAAmB;QACnC,QAAQ,CACN,gCAAgC,IAAI,CAAC,MAAM,CAAC,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,EAAE,CACjG,CAAC;QACF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;gBAC7C,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,SAAS,EAAE,SAAS;oBACpB,IAAI,EAAE,MAAM;oBACZ,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;iBAC7C;aACF,CAAC,CAAC;YAEH,QAAQ,CAAC,qCAAqC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAE1E,2BAA2B;YAC3B,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;gBACxB,8DAA8D;gBAC9D,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAE,QAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC3E,CAAC;YAED,6BAA6B;YAC7B,6DAA6D;YAC7D,8DAA8D;YAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAa,CAAC;YAEtC,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9E,0CAA0C;gBAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9E,CAAC;iBAAM,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACxB,OAAO,eAAe,MAAM,CAAC,KAAK,EAAE,CAAC;YACvC,CAAC;YAED,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;YAC3D,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"A2AClientWrapper.js","sourceRoot":"","sources":["../../../src/modules/a2a/A2AClientWrapper.ts"],"names":[],"mappings":"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"}

package/dist/modules/acp/acpAgentApp.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @packageDocumentation
+ * Gaunt Sloth's ACP (Agent Client Protocol) **v2** agent, built on the official SDK's
+ * `experimental/v2` surface.
+ *
+ * ## One of two dialects
+ *
+ * v1 is ACP's stable protocol and v2 is a draft, and the agent serves **both**: `acpRouter.ts`
+ * reads the `protocolVersion` on the first `initialize` and hands the connection to the matching
+ * app, so a host gets the dialect it asked for. This file is the v2 half; `acpAgentAppV1.ts` is
+ * the v1 half. Serving only v2 would cut the surface off from every shipping editor that speaks
+ * ACP today — measured against Zed 1.15.0 stable, which sends `protocolVersion: 1` as a literal
+ * with no setting to change it.
+ *
+ * ## Shape
+ *
+ * v2's agent side is a fluent app builder: `acp.agent()` returns an {@link AgentApp} on which
+ * typed handlers are registered by ACP method name, and `connect()` serves a client — either over
+ * a transport stream or, for tests, directly against a `ClientApp`. The SDK's v1 entry point offers
+ * the same builder, which is why the two dialects read alike even though their handlers differ.
+ *
+ * ## The prompt lifecycle is the part that looks wrong until you read the spec
+ *
+ * This is also the sharpest difference from v1, which answers the prompt request with the stop
+ * reason itself. In v2 `session/prompt` returns `{}` **as soon as the prompt is accepted** — not
+ * when the turn finishes.
+ * Progress, tool calls and the final stop reason all arrive as `session/update` notifications, and
+ * the turn is over when an idle `state_update` carrying a stop reason lands. That is what makes
+ * cancellation expressible at all: a cancelled turn reports `cancelled` on a `state_update`, while
+ * the prompt request it belongs to was answered long before. A client that waited on the prompt
+ * response for the result would hang through every tool call.
+ *
+ * ## Why a runner and not an agent
+ *
+ * Each session drives a {@link GthAgentRunner}, not a bare agent. The runner is where the
+ * tool-approval gate lives, so this is also the surface where `session/request_permission` is
+ * wired — see `acpPermissions.ts` for why that is not optional.
+ *
+ * ## One workspace per process
+ *
+ * Config discovery, the filesystem tools' allowed root, grep and the shell tool ALL resolve
+ * through `getCurrentWorkDir()`, a process-global. So the workspace is bound by the first
+ * `session/new` and a later `session/new` naming a different `cwd` is refused rather than served
+ * from the wrong root. An editor spawns one agent process per project, which is exactly the shape
+ * this serves; the alternative — letting the second session silently re-root the first session's
+ * tools — is the kind of quiet wrongness that is worse than an error a host can report.
+ */
+import * as acp from '@agentclientprotocol/sdk/experimental/v2';
+import { ACP_AGENT_NAME, ACP_AGENT_TITLE, announceAcpStart, isSameWorkspace } from '#src/modules/acp/acpCommon.js';
+import type { AcpAgentAppOptions } from '#src/modules/acp/acpCommon.js';
+export { ACP_AGENT_NAME, ACP_AGENT_TITLE, announceAcpStart, isSameWorkspace };
+export type { AcpAgentAppOptions };
+/**
+ * Builds the ACP v2 agent app. Register-and-return only: nothing is connected and no config is
+ * read until a client connects and creates a session.
+ */
+export declare function createAcpAgentApp(options?: AcpAgentAppOptions): acp.AgentApp;