@a2anet/a2a-utils 0.1.0 → 0.4.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":"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"}

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-agents.d.ts

@@ -0,0 +1,94 @@
+import type { AgentURLAndCustomHeaders } from "../types.js";
+/**
+ * Manages A2A agent cards keyed by user-defined agent IDs.
+ *
+ * Agents are configured via a dict mapping agent_id to config, or a JSON file path.
+ */
+export declare class A2AAgents {
+    private config;
+    private agents;
+    private initErrors;
+    private initialized;
+    private initPromise;
+    private readonly timeout;
+    /**
+     * Initialize the agent manager.
+     *
+     * @param agents - Agent config as:
+     *   - object: {"agent-id": {"url": "https://...", "custom_headers": {"X-API-Key": "..."}}}
+     *   - string: path to agents.json file with the same structure
+     *   - null: empty, add agents later
+     * @param opts.timeout - HTTP timeout in seconds for fetching agent cards (default: 15s).
+     */
+    constructor(agents?: Record<string, Record<string, unknown>> | string | null, opts?: {
+        timeout?: number;
+    });
+    /** Load and validate agent config. */
+    private loadConfig;
+    /** Lazily fetch all agent cards on first use (double-check locking). */
+    private ensureInitialized;
+    private doInitialize;
+    /** Fetch a single agent card and register it. */
+    private fetchAgent;
+    /** Create a fetch implementation that applies the configured timeout and custom headers. */
+    private createFetchImpl;
+    /** Parse agent card URL into base_url and card_path. */
+    private parseAgentCardUrl;
+    /**
+     * Register a new agent at runtime.
+     *
+     * @param agentId - User-defined agent identifier.
+     * @param url - Agent card URL.
+     * @param customHeaders - Optional custom HTTP headers.
+     *
+     * @throws Error if agentId is already registered.
+     */
+    addAgent(agentId: string, url: string, customHeaders?: Record<string, string>): Promise<void>;
+    /**
+     * Retrieve agent by ID.
+     *
+     * @param agentId - User-defined agent identifier.
+     *
+     * @returns AgentURLAndCustomHeaders, or null if not found.
+     */
+    getAgent(agentId: string): Promise<AgentURLAndCustomHeaders | null>;
+    /**
+     * Get errors from the most recent initialization attempt.
+     *
+     * @returns Object mapping agent_id to error message for agents that failed to load.
+     */
+    get initializationErrors(): Record<string, string>;
+    /**
+     * Get all registered agents.
+     *
+     * @returns Object mapping agent_id to AgentURLAndCustomHeaders.
+     */
+    getAgents(): Promise<Record<string, AgentURLAndCustomHeaders>>;
+    /**
+     * Format a single agent card into a summary object.
+     *
+     * @param card - The agent card to format.
+     * @param detail - Detail level — "name", "basic", "skills", or "full".
+     *
+     * @returns Summary object for the agent.
+     */
+    private formatAgentForLlm;
+    /**
+     * Generate summary for a single agent.
+     *
+     * @param agentId - User-defined agent identifier.
+     * @param detail - Detail level — "name", "basic", "skills", or "full".
+     *
+     * @returns Summary object for the agent, or null if not found.
+     */
+    getAgentForLlm(agentId: string, detail?: "name" | "basic" | "skills" | "full"): Promise<Record<string, unknown> | null>;
+    /**
+     * Generate summary of all agents.
+     *
+     * @param detail - Detail level — "name", "basic", "skills", or "full".
+     *
+     * @returns Object mapping agent_id to summary object, sorted by agent_id.
+     */
+    getAgentsForLlm(detail?: "name" | "basic" | "skills" | "full"): Promise<Record<string, Record<string, unknown>>>;
+}
+//# sourceMappingURL=a2a-agents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-agents.d.ts","sourceRoot":"","sources":["../../src/client/a2a-agents.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;GAIG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,MAAM,CAAgD;IAC9D,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;;;;OAQG;gBAEC,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,GAAG,IAAW,EACtE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAM/B,sCAAsC;IACtC,OAAO,CAAC,UAAU;IAelB,wEAAwE;YAC1D,iBAAiB;YAUjB,YAAY;IAoC1B,iDAAiD;YACnC,UAAU;IAgBxB,4FAA4F;IAC5F,OAAO,CAAC,eAAe;IAqBvB,wDAAwD;IACxD,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;OAQG;IACG,QAAQ,CACV,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;OAMG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAKzE;;;;OAIG;IACH,IAAI,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEjD;IAED;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAKpE;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;;;;;;OAOG;IACG,cAAc,CAChB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAgB,GACvD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAS1C;;;;;;OAMG;IACG,eAAe,CACjB,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAgB,GACvD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAStD"}