@a2anet/a2a-utils 0.1.0 → 0.3.0

package/dist/artifacts/index.js

@@ -0,0 +1,131 @@
+// SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+import { DataArtifacts } from "./data.js";
+import { TextArtifacts } from "./text.js";
+/**
+ * Minimize artifact list for LLM display.
+ *
+ * Combines all TextParts within each artifact into a single TextPartForLLM.
+ * Handles FileParts by including file metadata and saved paths.
+ *
+ * @param artifacts - List of artifacts to minimize.
+ * @param opts.characterLimit - Character limit above which to minimize.
+ * @param opts.minimizedObjectStringLength - Max length for string values in objects.
+ * @param opts.savedFilePaths - Mapping of artifactId to saved file paths.
+ *     When provided, file parts show saved locations.
+ *     When null, FileWithBytes parts show an error and FileWithUri parts
+ *     show the raw URI.
+ * @param opts.textTip - Tip string for minimized text artifacts. null = no tip.
+ * @param opts.dataTip - Tip string for minimized data artifacts. null = no tip.
+ *
+ * @returns List of ArtifactForLLM objects.
+ */
+export function minimizeArtifacts(artifacts, opts) {
+    const characterLimit = opts?.characterLimit ?? 50_000;
+    const minimizedObjectStringLength = opts?.minimizedObjectStringLength ?? 5_000;
+    const savedFilePaths = opts?.savedFilePaths ?? null;
+    const textTip = opts?.textTip ?? null;
+    const dataTip = opts?.dataTip ?? null;
+    const result = [];
+    for (const artifact of artifacts) {
+        const parts = [];
+        // Combine all text parts into one
+        const textSegments = [];
+        for (const part of artifact.parts) {
+            if (part.kind === "text") {
+                textSegments.push(part.text);
+            }
+        }
+        if (textSegments.length > 0) {
+            const combinedText = textSegments.join("");
+            const textMinimized = TextArtifacts.minimize(combinedText, {
+                characterLimit,
+                tip: textTip,
+            });
+            parts.push({
+                kind: "text",
+                ...textMinimized,
+            });
+        }
+        // Each data part stays separate
+        for (const part of artifact.parts) {
+            if (part.kind === "data") {
+                const dataMinimized = DataArtifacts.minimize(part.data, {
+                    characterLimit,
+                    minimizedObjectStringLength,
+                    tip: dataTip,
+                });
+                parts.push({ kind: "data", data: dataMinimized });
+            }
+        }
+        // Handle file parts
+        const artifactSaved = savedFilePaths !== null ? (savedFilePaths[artifact.artifactId] ?? null) : null;
+        for (const part of artifact.parts) {
+            if (part.kind === "file") {
+                const fileObj = part.file;
+                const name = fileObj.name ?? null;
+                const mimeType = fileObj.mimeType ?? null;
+                let filePart;
+                if ("bytes" in fileObj) {
+                    // FileWithBytes
+                    if (artifactSaved !== null) {
+                        filePart = {
+                            kind: "file",
+                            name,
+                            mimeType,
+                            uri: null,
+                            bytes: { _saved_to: artifactSaved },
+                        };
+                    }
+                    else {
+                        filePart = {
+                            kind: "file",
+                            name,
+                            mimeType,
+                            uri: null,
+                            bytes: {
+                                _error: "No FileStore configured. Cannot access file bytes.",
+                            },
+                        };
+                    }
+                }
+                else if ("uri" in fileObj) {
+                    // FileWithUri
+                    if (artifactSaved !== null) {
+                        filePart = {
+                            kind: "file",
+                            name,
+                            mimeType,
+                            uri: { _saved_to: artifactSaved },
+                            bytes: null,
+                        };
+                    }
+                    else {
+                        filePart = {
+                            kind: "file",
+                            name,
+                            mimeType,
+                            uri: fileObj.uri,
+                            bytes: null,
+                        };
+                    }
+                }
+                else {
+                    continue;
+                }
+                parts.push(filePart);
+            }
+        }
+        result.push({
+            artifactId: artifact.artifactId,
+            description: artifact.description ?? null,
+            name: artifact.name ?? null,
+            parts,
+        });
+    }
+    return result;
+}
+export { DataArtifacts } from "./data.js";
+export { TextArtifacts } from "./text.js";
+//# sourceMappingURL=index.js.map

package/dist/artifacts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,sCAAsC;AAQtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC7B,SAAqB,EACrB,IAMC;IAED,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,IAAI,MAAM,CAAC;IACtD,MAAM,2BAA2B,GAAG,IAAI,EAAE,2BAA2B,IAAI,KAAK,CAAC;IAC/E,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,IAAI,IAAI,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC;IAEtC,MAAM,MAAM,GAAqB,EAAE,CAAC;IAEpC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAyD,EAAE,CAAC;QAEvE,kCAAkC;QAClC,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACvB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3C,MAAM,aAAa,GAAG,aAAa,CAAC,QAAQ,CAAC,YAAY,EAAE;gBACvD,cAAc;gBACd,GAAG,EAAE,OAAO;aACf,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,MAAM;gBACZ,GAAI,aAA8C;aACrD,CAAC,CAAC;QACP,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACvB,MAAM,aAAa,GAAG,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE;oBACpD,cAAc;oBACd,2BAA2B;oBAC3B,GAAG,EAAE,OAAO;iBACf,CAAC,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;YACtD,CAAC;QACL,CAAC;QAED,oBAAoB;QACpB,MAAM,aAAa,GACf,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAEnF,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;gBAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;gBAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;gBAE1C,IAAI,QAAwB,CAAC;gBAE7B,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;oBACrB,gBAAgB;oBAChB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;wBACzB,QAAQ,GAAG;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI;4BACJ,QAAQ;4BACR,GAAG,EAAE,IAAI;4BACT,KAAK,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE;yBACtC,CAAC;oBACN,CAAC;yBAAM,CAAC;wBACJ,QAAQ,GAAG;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI;4BACJ,QAAQ;4BACR,GAAG,EAAE,IAAI;4BACT,KAAK,EAAE;gCACH,MAAM,EAAE,oDAAoD;6BAC/D;yBACJ,CAAC;oBACN,CAAC;gBACL,CAAC;qBAAM,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC1B,cAAc;oBACd,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;wBACzB,QAAQ,GAAG;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI;4BACJ,QAAQ;4BACR,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE;4BACjC,KAAK,EAAE,IAAI;yBACd,CAAC;oBACN,CAAC;yBAAM,CAAC;wBACJ,QAAQ,GAAG;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI;4BACJ,QAAQ;4BACR,GAAG,EAAG,OAAuB,CAAC,GAAG;4BACjC,KAAK,EAAE,IAAI;yBACd,CAAC;oBACN,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACJ,SAAS;gBACb,CAAC;gBAED,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACL,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACR,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,WAAW,EAAE,QAAQ,CAAC,WAAW,IAAI,IAAI;YACzC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI;YAC3B,KAAK;SACR,CAAC,CAAC;IACP,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/artifacts/text.d.ts

@@ -0,0 +1,54 @@
+/** Text artifact operations: viewing and minimization. */
+export declare class TextArtifacts {
+    /**
+     * View text content with optional line or character range selection.
+     *
+     * @param text - The text to view.
+     * @param opts.lineStart - Starting line number (1-based, inclusive). null = start.
+     * @param opts.lineEnd - Ending line number (1-based, inclusive). null = end.
+     * @param opts.characterStart - Starting character index (0-based, inclusive). null = start.
+     * @param opts.characterEnd - Ending character index (0-based, exclusive). null = end.
+     * @param opts.characterLimit - Maximum output size in characters.
+     *
+     * @returns Filtered text string.
+     *
+     * @throws Error if both line and character selection are provided,
+     *     or if parameters are invalid.
+     */
+    static view(text: string, opts?: {
+        lineStart?: number | null;
+        lineEnd?: number | null;
+        characterStart?: number | null;
+        characterEnd?: number | null;
+        characterLimit?: number;
+    }): string;
+    /**
+     * Minimize text content for display.
+     *
+     * If text is <= characterLimit chars, return it in full inside "text" key.
+     * If text is > characterLimit chars, show first half and last half with metadata.
+     *
+     * @param text - The text content to minimize.
+     * @param opts.characterLimit - Character limit above which to minimize.
+     * @param opts.tip - Tip to include. Defaults to null (no tip); pass a string to include one.
+     *
+     * @returns Object with "text" key containing readable content and metadata fields.
+     */
+    static minimize(text: string, opts?: {
+        characterLimit?: number;
+        tip?: string | null;
+    }): Record<string, unknown>;
+    /**
+     * Parse line range parameters.
+     *
+     * @param lineStart - Starting line number (1-based, inclusive). null means 1.
+     * @param lineEnd - Ending line number (1-based, inclusive). null means totalLines.
+     * @param totalLines - Total number of lines.
+     *
+     * @returns Tuple of [startIndex, endIndex] as 0-based indices.
+     *
+     * @throws Error if line numbers are invalid.
+     */
+    private static parseLineRange;
+}
+//# sourceMappingURL=text.d.ts.map

package/dist/artifacts/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/artifacts/text.ts"],"names":[],"mappings":"AAaA,0DAA0D;AAC1D,qBAAa,aAAa;IACtB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;KAC3B,GACF,MAAM;IAuCT;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GACF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAqD1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;CA8BhC"}

package/dist/artifacts/text.js

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Text artifact viewing and minimization.
+ */
+/** Format a number with comma separators (locale-independent, matching Python's `f"{n:,}"`). */
+function formatNumber(n) {
+    return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+/** Text artifact operations: viewing and minimization. */
+export class TextArtifacts {
+    /**
+     * View text content with optional line or character range selection.
+     *
+     * @param text - The text to view.
+     * @param opts.lineStart - Starting line number (1-based, inclusive). null = start.
+     * @param opts.lineEnd - Ending line number (1-based, inclusive). null = end.
+     * @param opts.characterStart - Starting character index (0-based, inclusive). null = start.
+     * @param opts.characterEnd - Ending character index (0-based, exclusive). null = end.
+     * @param opts.characterLimit - Maximum output size in characters.
+     *
+     * @returns Filtered text string.
+     *
+     * @throws Error if both line and character selection are provided,
+     *     or if parameters are invalid.
+     */
+    static view(text, opts) {
+        const lineStart = opts?.lineStart ?? null;
+        const lineEnd = opts?.lineEnd ?? null;
+        const characterStart = opts?.characterStart ?? null;
+        const characterEnd = opts?.characterEnd ?? null;
+        const characterLimit = opts?.characterLimit ?? 50_000;
+        const hasLine = lineStart !== null || lineEnd !== null;
+        const hasChar = characterStart !== null || characterEnd !== null;
+        if (hasLine && hasChar) {
+            throw new Error("Cannot use both line and character selection");
+        }
+        let resultText;
+        if (hasChar) {
+            const start = characterStart ?? 0;
+            const end = characterEnd ?? text.length;
+            resultText = text.slice(start, end);
+        }
+        else if (hasLine) {
+            const lines = text.split("\n");
+            const totalLines = lines.length;
+            const [startIdx, endIdx] = TextArtifacts.parseLineRange(lineStart, lineEnd, totalLines);
+            const selectedLines = lines.slice(startIdx, endIdx);
+            resultText = selectedLines.join("\n");
+        }
+        else {
+            resultText = text;
+        }
+        if (resultText.length > characterLimit) {
+            throw new Error(`Selected text (${formatNumber(resultText.length)} characters) exceeds the maximum output size of ${formatNumber(characterLimit)} characters. Try selecting a smaller range.`);
+        }
+        return resultText;
+    }
+    /**
+     * Minimize text content for display.
+     *
+     * If text is <= characterLimit chars, return it in full inside "text" key.
+     * If text is > characterLimit chars, show first half and last half with metadata.
+     *
+     * @param text - The text content to minimize.
+     * @param opts.characterLimit - Character limit above which to minimize.
+     * @param opts.tip - Tip to include. Defaults to null (no tip); pass a string to include one.
+     *
+     * @returns Object with "text" key containing readable content and metadata fields.
+     */
+    static minimize(text, opts) {
+        const characterLimit = opts?.characterLimit ?? 50_000;
+        const tip = opts?.tip ?? null;
+        if (text.length <= characterLimit) {
+            return { text };
+        }
+        const half = Math.floor(characterLimit / 2);
+        const lines = text.split("\n");
+        const lineCount = lines.length;
+        // Find which line the half char falls on for the start
+        let charCount = 0;
+        let startEndLine = 1;
+        for (let i = 0; i < lines.length; i++) {
+            charCount += lines[i].length + 1; // +1 for newline
+            if (charCount >= half) {
+                startEndLine = i + 1;
+                break;
+            }
+        }
+        // Find which line the end section starts on
+        charCount = 0;
+        let endStartLine = lineCount;
+        for (let i = lines.length - 1; i >= 0; i--) {
+            charCount += lines[i].length + 1;
+            if (charCount >= half) {
+                endStartLine = i + 1;
+                break;
+            }
+        }
+        const omittedChars = text.length - 2 * half;
+        const result = {
+            text: `${text.slice(0, half)}\n\n[... ${formatNumber(omittedChars)} characters omitted ...]\n\n${text.slice(-half)}`,
+            _total_lines: lineCount,
+            _total_characters: text.length,
+            _start_line_range: `1-${startEndLine}`,
+            _end_line_range: `${endStartLine}-${lineCount}`,
+            _start_character_range: `0-${half}`,
+            _end_character_range: `${text.length - half}-${text.length}`,
+        };
+        if (tip !== null) {
+            result._tip = tip;
+        }
+        return result;
+    }
+    /**
+     * Parse line range parameters.
+     *
+     * @param lineStart - Starting line number (1-based, inclusive). null means 1.
+     * @param lineEnd - Ending line number (1-based, inclusive). null means totalLines.
+     * @param totalLines - Total number of lines.
+     *
+     * @returns Tuple of [startIndex, endIndex] as 0-based indices.
+     *
+     * @throws Error if line numbers are invalid.
+     */
+    static parseLineRange(lineStart, lineEnd, totalLines) {
+        let start = lineStart ?? 1;
+        let end = lineEnd ?? totalLines;
+        // Handle negative line numbers (count from end)
+        if (start < 0) {
+            start = totalLines + start + 1;
+        }
+        if (end < 0) {
+            end = totalLines + end + 1;
+        }
+        // Validate range
+        if (start < 1) {
+            throw new Error(`line_start must be >= 1 (got ${start})`);
+        }
+        if (end > totalLines) {
+            throw new Error(`line_end (${end}) exceeds total lines (${totalLines})`);
+        }
+        if (start > end) {
+            throw new Error(`line_start (${start}) must be <= line_end (${end})`);
+        }
+        // Convert to 0-based indices
+        return [start - 1, end];
+    }
+}
+//# sourceMappingURL=text.js.map

package/dist/artifacts/text.js.map

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

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

@@ -0,0 +1,94 @@
+/**
+ * A2ASession — main interface for interacting with A2A agents.
+ */
+import type { Message, Task } from "@a2a-js/sdk";
+import { type TaskStore } from "@a2a-js/sdk/server";
+import type { FileStore } from "../files/file-store.js";
+import type { AgentManager } from "./agent-manager.js";
+/** Main interface for sending messages to A2A agents. */
+export declare class A2ASession {
+    readonly agentManager: AgentManager;
+    readonly taskStore: TaskStore;
+    readonly fileStore: FileStore | null;
+    private readonly sendMessageTimeout;
+    private readonly getTaskTimeout;
+    private readonly getTaskPollInterval;
+    constructor(agentManager: AgentManager, opts?: {
+        taskStore?: TaskStore;
+        fileStore?: FileStore | null;
+        sendMessageTimeout?: number;
+        getTaskTimeout?: number;
+        getTaskPollInterval?: number;
+    });
+    /**
+     * 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.
+     */
+    sendMessage(agentId: string, message: string, opts?: {
+        contextId?: string | null;
+        taskId?: string | null;
+        timeout?: number | null;
+    }): Promise<Task | Message>;
+    /**
+     * 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.
+     */
+    getTask(agentId: string, taskId: string, opts?: {
+        timeout?: number | null;
+        pollInterval?: number | null;
+    }): Promise<Task>;
+    /**
+     * Save file artifacts to the file store if configured.
+     *
+     * Idempotent: skips artifacts whose files have already been saved.
+     */
+    private saveFiles;
+    /** Monitor a task via SSE resubscription, falling back to a final fetch. */
+    private getTaskStreaming;
+    /** Monitor a task by polling at regular intervals. */
+    private getTaskPolling;
+    /** Fetch a task via A2AClient.getTask(). */
+    private fetchTask;
+    /** Narrow the SDK client to the methods this package relies on. */
+    private getSessionClient;
+    /** Create an A2AClient with optional custom headers. */
+    private createClient;
+    /**
+     * Resolve agent card and headers.
+     *
+     * @returns Tuple of [AgentCard, headers_dict].
+     *
+     * @throws Error if agent cannot be resolved.
+     */
+    private resolveAgent;
+}
+//# sourceMappingURL=a2a-session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-session.d.ts","sourceRoot":"","sources":["../../src/client/a2a-session.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,KAAK,EAGR,OAAO,EAEP,IAAI,EAGP,MAAM,aAAa,CAAC;AAErB,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuBvD,yDAAyD;AACzD,qBAAa,UAAU;IACnB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAGzC,YAAY,EAAE,YAAY,EAC1B,IAAI,CAAC,EAAE;QACH,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAChC;IAUL;;;;;;;;;;;;;;OAcG;IACG,WAAW,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,GACF,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC;IAwF1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CACT,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,GACF,OAAO,CAAC,IAAI,CAAC;IAkChB;;;;OAIG;YACW,SAAS;IAgBvB,4EAA4E;YAC9D,gBAAgB;IAwC9B,sDAAsD;YACxC,cAAc;IAwB5B,4CAA4C;YAC9B,SAAS;IAevB,mEAAmE;IACnE,OAAO,CAAC,gBAAgB;IAIxB,wDAAwD;IACxD,OAAO,CAAC,YAAY;IAmBpB;;;;;;OAMG;YACW,YAAY;CAS7B"}