@a2anet/a2a-utils 0.1.0 → 0.3.0

package/dist/client/a2a-session.js

@@ -0,0 +1,264 @@
+// SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+import { A2AClient } from "@a2a-js/sdk/client";
+import { InMemoryTaskStore } from "@a2a-js/sdk/server";
+import { v4 as uuidv4 } from "uuid";
+import { TERMINAL_OR_ACTIONABLE_STATES } from "../types.js";
+function sleep(seconds) {
+    return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+/** Main interface for sending messages to A2A agents. */
+export class A2ASession {
+    agentManager;
+    taskStore;
+    fileStore;
+    sendMessageTimeout;
+    getTaskTimeout;
+    getTaskPollInterval;
+    constructor(agentManager, opts) {
+        this.agentManager = agentManager;
+        this.taskStore = opts?.taskStore ?? new InMemoryTaskStore();
+        this.fileStore = opts?.fileStore ?? null;
+        this.sendMessageTimeout = opts?.sendMessageTimeout ?? 60.0;
+        this.getTaskTimeout = opts?.getTaskTimeout ?? 60.0;
+        this.getTaskPollInterval = opts?.getTaskPollInterval ?? 5.0;
+    }
+    /**
+     * Send a message to an A2A agent.
+     *
+     * @param agentId - Registered agent identifier.
+     * @param message - The message content to send.
+     * @param opts.contextId - Optional context ID to continue a conversation.
+     *     Auto-generated when null.
+     * @param opts.taskId - Optional task ID to attach to the message.
+     * @param opts.timeout - HTTP timeout in seconds. Defaults to sendMessageTimeout
+     *     from constructor.
+     *
+     * @returns Task for task responses, Message for message-only responses.
+     *
+     * @throws Error if agent is not found.
+     */
+    async sendMessage(agentId, message, opts) {
+        const [agentCard, headers] = await this.resolveAgent(agentId);
+        const contextId = opts?.contextId ?? uuidv4();
+        // Build A2A message
+        const a2aMessage = {
+            kind: "message",
+            messageId: uuidv4(),
+            parts: [{ kind: "text", text: message }],
+            role: "user",
+            contextId,
+        };
+        if (opts?.taskId != null) {
+            a2aMessage.taskId = opts.taskId;
+        }
+        const effectiveTimeout = opts?.timeout !== undefined && opts?.timeout !== null
+            ? opts.timeout
+            : this.sendMessageTimeout;
+        const start = performance.now();
+        const client = this.createClient(agentCard, headers);
+        const response = await this.getSessionClient(client).sendMessage({
+            message: a2aMessage,
+            configuration: { blocking: false },
+        }, { signal: AbortSignal.timeout(effectiveTimeout * 1000) });
+        if ("error" in response) {
+            throw new Error(`JSON-RPC error: ${response.error.message} (code: ${response.error.code})`);
+        }
+        const result = response.result;
+        // Handle Message result
+        if (result.kind === "message") {
+            return result;
+        }
+        // Handle Task result
+        if (result.kind !== "task") {
+            throw new Error("Expected Task or Message response, got unexpected kind");
+        }
+        let task = result;
+        await this.taskStore.save(task);
+        // If task is already in a terminal/actionable state, save files and return
+        if (TERMINAL_OR_ACTIONABLE_STATES.has(task.status.state)) {
+            await this.saveFiles(task);
+            return task;
+        }
+        // Task is in a non-terminal state (e.g. working) — monitor with remaining time
+        const elapsed = (performance.now() - start) / 1000;
+        const remaining = Math.max(0, effectiveTimeout - elapsed);
+        if (remaining > 0) {
+            const supportsStreaming = agentCard.capabilities !== undefined &&
+                agentCard.capabilities !== null &&
+                agentCard.capabilities.streaming === true;
+            if (supportsStreaming) {
+                task = await this.getTaskStreaming(agentCard, headers, task.id, remaining);
+            }
+            else {
+                task = await this.getTaskPolling(agentCard, headers, task.id, remaining, this.getTaskPollInterval);
+            }
+            await this.taskStore.save(task);
+        }
+        await this.saveFiles(task);
+        return task;
+    }
+    /**
+     * Get the current state of a task, monitoring until terminal/actionable state.
+     *
+     * If the remote agent supports streaming, uses SSE resubscription for real-time
+     * updates. Otherwise, polls at regular intervals.
+     *
+     * On monitoring timeout, returns the current task state (which may still be
+     * non-terminal, e.g. "working"). The only errors from getTask are failed
+     * HTTP requests (agent down, network error).
+     *
+     * @param agentId - Registered agent identifier.
+     * @param taskId - Task ID from a previous sendMessage call.
+     * @param opts.timeout - Total monitoring timeout in seconds. Defaults to
+     *     getTaskTimeout from constructor.
+     * @param opts.pollInterval - Interval between polls in seconds (used when streaming
+     *     is not supported). Defaults to getTaskPollInterval from constructor.
+     *
+     * @returns Task with the current task state. If monitoring times out, the
+     *     returned task may still be in a non-terminal state.
+     *
+     * @throws Error if agent is not found.
+     */
+    async getTask(agentId, taskId, opts) {
+        const [agentCard, headers] = await this.resolveAgent(agentId);
+        const effectiveTimeout = opts?.timeout !== undefined && opts?.timeout !== null
+            ? opts.timeout
+            : this.getTaskTimeout;
+        const effectivePollInterval = opts?.pollInterval !== undefined && opts?.pollInterval !== null
+            ? opts.pollInterval
+            : this.getTaskPollInterval;
+        const supportsStreaming = agentCard.capabilities !== undefined &&
+            agentCard.capabilities !== null &&
+            agentCard.capabilities.streaming === true;
+        let task;
+        if (supportsStreaming) {
+            task = await this.getTaskStreaming(agentCard, headers, taskId, effectiveTimeout);
+        }
+        else {
+            task = await this.getTaskPolling(agentCard, headers, taskId, effectiveTimeout, effectivePollInterval);
+        }
+        await this.taskStore.save(task);
+        await this.saveFiles(task);
+        return task;
+    }
+    /**
+     * Save file artifacts to the file store if configured.
+     *
+     * Idempotent: skips artifacts whose files have already been saved.
+     */
+    async saveFiles(task) {
+        if (this.fileStore === null || !task.artifacts) {
+            return;
+        }
+        for (const artifact of task.artifacts) {
+            const hasFiles = artifact.parts.some((p) => p.kind === "file");
+            if (hasFiles) {
+                const existing = await this.fileStore.get(task.id, artifact.artifactId);
+                if (existing.length === 0) {
+                    await this.fileStore.save(task.id, artifact);
+                }
+            }
+        }
+    }
+    /** Monitor a task via SSE resubscription, falling back to a final fetch. */
+    async getTaskStreaming(agentCard, headers, taskId, timeout) {
+        const client = this.createClient(agentCard, headers);
+        const params = { id: taskId };
+        try {
+            const stream = this.getSessionClient(client).resubscribeTask(params, {
+                signal: AbortSignal.timeout(timeout * 1000),
+            });
+            for await (const event of stream) {
+                if (event.kind === "status-update") {
+                    const statusEvent = event;
+                    if (TERMINAL_OR_ACTIONABLE_STATES.has(statusEvent.status.state)) {
+                        break;
+                    }
+                }
+                else if (event.kind === "task") {
+                    const taskEvent = event;
+                    if (TERMINAL_OR_ACTIONABLE_STATES.has(taskEvent.status.state)) {
+                        break;
+                    }
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === "AbortError") {
+                console.info(`Task ${taskId} still in working state after ${timeout}s`);
+            }
+            else {
+                throw e;
+            }
+        }
+        // Final fetch to get the complete Task with all artifacts
+        return this.fetchTask(client, taskId, timeout);
+    }
+    /** Monitor a task by polling at regular intervals. */
+    async getTaskPolling(agentCard, headers, taskId, timeout, pollInterval) {
+        const client = this.createClient(agentCard, headers);
+        const start = performance.now();
+        while (true) {
+            const task = await this.fetchTask(client, taskId, timeout);
+            if (TERMINAL_OR_ACTIONABLE_STATES.has(task.status.state)) {
+                return task;
+            }
+            const elapsed = (performance.now() - start) / 1000;
+            if (elapsed >= timeout) {
+                console.info(`Task ${taskId} still in working state after ${timeout}s`);
+                return task;
+            }
+            await sleep(pollInterval);
+        }
+    }
+    /** Fetch a task via A2AClient.getTask(). */
+    async fetchTask(client, taskId, timeout) {
+        const response = await this.getSessionClient(client).getTask({ id: taskId }, timeout !== undefined ? { signal: AbortSignal.timeout(timeout * 1000) } : undefined);
+        if ("error" in response) {
+            throw new Error(`JSON-RPC error: ${response.error.message} (code: ${response.error.code})`);
+        }
+        return response.result;
+    }
+    /** Narrow the SDK client to the methods this package relies on. */
+    getSessionClient(client) {
+        return client;
+    }
+    /** Create an A2AClient with optional custom headers. */
+    createClient(agentCard, headers) {
+        if (Object.keys(headers).length > 0) {
+            const customHeaders = headers;
+            const wrappedFetch = (input, init) => {
+                const mergedInit = {
+                    ...init,
+                    headers: {
+                        ...init?.headers,
+                        ...customHeaders,
+                    },
+                };
+                return fetch(input, mergedInit);
+            };
+            wrappedFetch.preconnect = fetch.preconnect;
+            return new A2AClient(agentCard, { fetchImpl: wrappedFetch });
+        }
+        return new A2AClient(agentCard);
+    }
+    /**
+     * Resolve agent card and headers.
+     *
+     * @returns Tuple of [AgentCard, headers_dict].
+     *
+     * @throws Error if agent cannot be resolved.
+     */
+    async resolveAgent(agentId) {
+        const agent = await this.agentManager.getAgent(agentId);
+        if (agent === null) {
+            const agents = await this.agentManager.getAgents();
+            const available = Object.keys(agents).sort().join(", ");
+            throw new Error(`Agent '${agentId}' not found. Available agents: ${available}`);
+        }
+        return [agent.agentCard, agent.customHeaders];
+    }
+}
+//# sourceMappingURL=a2a-session.js.map

package/dist/client/a2a-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-session.js","sourceRoot":"","sources":["../../src/client/a2a-session.ts"],"names":[],"mappings":"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"}

package/dist/client/a2a-tools.d.ts

@@ -0,0 +1,152 @@
+import { ArtifactSettings } from "../types.js";
+import type { A2ASession } from "./a2a-session.js";
+export declare const TEXT_MINIMIZED_TIP = "Text was minimized. Call view_text_artifact() to view specific line ranges.";
+export declare const DATA_MINIMIZED_TIP = "Data was minimized. Call view_data_artifact() to navigate to specific data.";
+/**
+ * LLM-friendly tools that can be used out-of-the-box with agent frameworks.
+ *
+ * Each method has LLM-friendly docstrings, returns JSON-serialisable objects, and returns actionable error messages.
+ */
+export declare class A2ATools {
+    private readonly session;
+    private readonly artifactSettings;
+    constructor(session: A2ASession, opts?: {
+        artifactSettings?: ArtifactSettings | null;
+    });
+    /**
+     * List all available agents with their names and descriptions.
+     *
+     * Use this first to discover what agents are available before sending messages.
+     * Each agent has a unique ID (the key) that you'll need for other tools like
+     * send_message and get_agent.
+     *
+     * Returns an object mapping agent IDs to their name and description.
+     * If any agents failed to load, an "errors" field is included with details.
+     */
+    getAgents(): Promise<Record<string, unknown>>;
+    /**
+     * Get detailed information about a specific agent, including its skills.
+     *
+     * Use this after get_agents to learn more about what a specific agent can do.
+     * The response includes the agent's name, description, and a list of skills
+     * with their descriptions.
+     *
+     * @param agentId - The agent's unique identifier (from get_agents).
+     */
+    getAgent(agentId: string): Promise<Record<string, unknown>>;
+    /**
+     * Send a message to an agent and receive a structured response.
+     *
+     * This is the primary way to communicate with agents. The response includes
+     * the agent's reply and any generated artifacts.
+     *
+     * Artifact data in responses may be minimized for display. Fields prefixed
+     * with "_" indicate metadata about minimized content. Use view_text_artifact
+     * or view_data_artifact to access full artifact data.
+     *
+     * If the task is still in progress after the timeout, the response includes
+     * a task_id. Use get_task with that task_id to continue monitoring.
+     *
+     * @param agentId - ID of the agent to message (from get_agents).
+     * @param message - The message content to send.
+     * @param contextId - Continue an existing conversation by providing its context ID.
+     *     Omit to start a new conversation.
+     * @param taskId - Attach to an existing task (for input_required flows).
+     * @param timeout - Override the default timeout in seconds.
+     */
+    sendMessage(agentId: string, message: string, contextId?: string | null, taskId?: string | null, timeout?: number | null): Promise<Record<string, unknown>>;
+    /**
+     * Check the progress of a task that is still in progress.
+     *
+     * Use this after send_message returns a task in a non-terminal state
+     * (e.g. "working") to monitor its progress.
+     *
+     * If the task is still running after the timeout, the current state is
+     * returned. Call get_task again to continue monitoring.
+     *
+     * @param agentId - ID of the agent that owns the task.
+     * @param taskId - Task ID from a previous send_message response.
+     * @param timeout - Override the monitoring timeout in seconds.
+     * @param pollInterval - Override the interval between status checks in seconds.
+     */
+    getTask(agentId: string, taskId: string, timeout?: number | null, pollInterval?: number | null): Promise<Record<string, unknown>>;
+    /**
+     * View text content from an artifact, optionally selecting a range.
+     *
+     * Use this for artifacts containing text (documents, logs, code, etc.).
+     * You can select by line range OR character range, but not both.
+     *
+     * @param agentId - ID of the agent that produced the artifact.
+     * @param taskId - Task ID containing the artifact.
+     * @param artifactId - The artifact's unique identifier (from the task's artifacts list).
+     * @param lineStart - Starting line number (1-based, inclusive).
+     * @param lineEnd - Ending line number (1-based, inclusive).
+     * @param characterStart - Starting character index (0-based, inclusive).
+     * @param characterEnd - Ending character index (0-based, exclusive).
+     */
+    viewTextArtifact(agentId: string, taskId: string, artifactId: string, lineStart?: number | null, lineEnd?: number | null, characterStart?: number | null, characterEnd?: number | null): Promise<Record<string, unknown>>;
+    /**
+     * View structured data from an artifact with optional filtering.
+     *
+     * Use this for artifacts containing JSON data (objects, arrays, tables).
+     * You can navigate to specific data with json_path, then filter with
+     * rows and columns for tabular data.
+     *
+     * @param agentId - ID of the agent that produced the artifact.
+     * @param taskId - Task ID containing the artifact.
+     * @param artifactId - The artifact's unique identifier (from the task's artifacts list).
+     * @param jsonPath - Dot-separated path to navigate into the data (e.g. "results.items").
+     * @param rows - Row selection for list data. Examples: "0" (single row), "0-10" (range),
+     *     "0,2,5" (specific rows), "all" (every row).
+     * @param columns - Column selection for tabular data (list of objects). Examples:
+     *     "name" (single column), "name,age" (multiple columns), "all" (every column).
+     */
+    viewDataArtifact(agentId: string, taskId: string, artifactId: string, jsonPath?: string | null, rows?: string | null, columns?: string | null): Promise<Record<string, unknown>>;
+    /**
+     * Convert an A2A Message to MessageForLLM.
+     *
+     * Combines all TextParts into a single TextPartForLLM.
+     * FileParts are ignored; file handling is done at the artifact level.
+     */
+    private buildMessageForLlm;
+    /** Convert a Task to TaskForLLM with artifact minimization and file path queries. */
+    private buildTaskForLlm;
+    /**
+     * Look up an artifact through the resolution chain.
+     *
+     * 1. Check the task store (local cache)
+     * 2. Fetch fresh via session.getTask (remote retrieval)
+     *
+     * @returns The Artifact.
+     *
+     * @throws Error if artifact cannot be found.
+     */
+    private getArtifact;
+    /**
+     * Extract text content from artifact parts.
+     *
+     * @throws Error if artifact does not contain text content.
+     */
+    private static extractText;
+    /**
+     * Extract data content from artifact parts.
+     *
+     * @throws Error if artifact does not contain data content.
+     */
+    private static extractData;
+    /**
+     * Parse a rows string into the type expected by DataArtifacts.view.
+     *
+     * Accepts: "0" (single int), "0-10" (range string), "0,2,5" (comma-separated
+     * list of ints), "all" (passthrough string), or null.
+     */
+    private static parseRows;
+    /**
+     * Parse a columns string into the type expected by DataArtifacts.view.
+     *
+     * Accepts: "name" (single column), "name,age" (comma-separated list),
+     * "all" (passthrough string), or null.
+     */
+    private static parseColumns;
+}
+//# sourceMappingURL=a2a-tools.d.ts.map

package/dist/client/a2a-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-tools.d.ts","sourceRoot":"","sources":["../../src/client/a2a-tools.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,eAAO,MAAM,kBAAkB,gFACkD,CAAC;AAClF,eAAO,MAAM,kBAAkB,gFACkD,CAAC;AAElF;;;;GAIG;AACH,qBAAa,QAAQ;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;gBAExC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE;IAKtF;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAiBnD;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAgBjE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAkCnC;;;;;;;;;;;;;OAaG;IACG,OAAO,CACT,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,EACvB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA4BnC;;;;;;;;;;;;;OAaG;IACG,gBAAgB,CAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,EACvB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,EAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAoCnC;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAwCnC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA6B1B,qFAAqF;YACvE,eAAe;IAyC7B;;;;;;;;;OASG;YACW,WAAW;IA8BzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAiB1B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAiB1B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IA2CxB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAmB9B"}