@a2anet/a2a-utils 0.4.0 → 0.6.0

package/dist/client/a2a-tools.js

@@ -1,14 +1,89 @@
 // SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
 //
 // SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
 import { DataArtifacts, TextArtifacts, minimizeArtifacts } from "../artifacts/index.js";
 import { ArtifactSettings } from "../types.js";
 export const TEXT_MINIMIZED_TIP = "Text was minimized. Call view_text_artifact() to view specific line ranges.";
 export const DATA_MINIMIZED_TIP = "Data was minimized. Call view_data_artifact() to navigate to specific data.";
+// -- Zod schemas (one per tool) --
+const getAgentsSchema = z.object({});
+const getAgentSchema = z.object({
+    agentId: z.string().describe("The agent's unique identifier (from get_agents)."),
+});
+const sendMessageSchema = z.object({
+    agentId: z.string().describe("ID of the agent to message (from get_agents)."),
+    message: z.string().describe("The message content to send."),
+    contextId: z
+        .string()
+        .describe("Continue an existing conversation by providing its context ID.")
+        .optional(),
+    taskId: z
+        .string()
+        .describe("Attach to an existing task (for input_required flows).")
+        .optional(),
+    timeout: z.number().describe("Override the default timeout in seconds.").optional(),
+    data: z
+        .array(z.unknown())
+        .describe("Structured data to include with the message. " +
+        "Each item is sent as a separate JSON object alongside the text.")
+        .optional(),
+    files: z
+        .array(z.string())
+        .describe("Files to include with the message. " +
+        "Accepts local file paths (read and sent as binary, max 1MB) " +
+        "or URLs (sent as references for the remote agent to fetch).")
+        .optional(),
+});
+const getTaskSchema = z.object({
+    agentId: z.string().describe("ID of the agent that owns the task."),
+    taskId: z.string().describe("Task ID from a previous send_message response."),
+    timeout: z.number().describe("Override the monitoring timeout in seconds.").optional(),
+    pollInterval: z
+        .number()
+        .describe("Override the interval between status checks in seconds.")
+        .optional(),
+});
+const viewTextArtifactSchema = z.object({
+    agentId: z.string().describe("ID of the agent that produced the artifact."),
+    taskId: z.string().describe("Task ID containing the artifact."),
+    artifactId: z
+        .string()
+        .describe("The artifact's unique identifier (from the task's artifacts list)."),
+    lineStart: z.number().describe("Starting line number (1-based, inclusive).").optional(),
+    lineEnd: z.number().describe("Ending line number (1-based, inclusive).").optional(),
+    characterStart: z
+        .number()
+        .describe("Starting character index (0-based, inclusive).")
+        .optional(),
+    characterEnd: z.number().describe("Ending character index (0-based, exclusive).").optional(),
+});
+const viewDataArtifactSchema = z.object({
+    agentId: z.string().describe("ID of the agent that produced the artifact."),
+    taskId: z.string().describe("Task ID containing the artifact."),
+    artifactId: z
+        .string()
+        .describe("The artifact's unique identifier (from the task's artifacts list)."),
+    jsonPath: z
+        .string()
+        .describe('Dot-separated path to navigate into the data (e.g. "results.items").')
+        .optional(),
+    rows: z
+        .string()
+        .describe('Row selection for list data. Examples: "0" (single), "0-10" (range), "0,2,5" (specific), "all".')
+        .optional(),
+    columns: z
+        .string()
+        .describe('Column selection for tabular data. Examples: "name" (single), "name,age" (multiple), "all".')
+        .optional(),
+});
 /**
  * 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.
+ * Each tool has LLM-friendly docstrings, returns JSON-serialisable objects, and returns actionable error messages.
+ *
+ * Each tool is an instance property with `name`, `description`, `schema` (Zod),
+ * and `execute`. Use the `toolDefinitions` getter for the full array.
  */
 export class A2ATools {
     session;
@@ -17,264 +92,244 @@ export class A2ATools {
         this.session = session;
         this.artifactSettings = opts?.artifactSettings ?? new ArtifactSettings();
     }
-    /**
-     * 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.
-     */
-    async getAgents() {
-        try {
-            const result = await this.session.agents.getAgentsForLlm("basic");
-            const initErrors = this.session.agents.initializationErrors;
-            if (Object.keys(result).length === 0 && Object.keys(initErrors).length > 0) {
-                const errors = {};
-                for (const [agentId, error] of Object.entries(initErrors)) {
-                    errors[agentId] = `Failed to load agent: ${error}`;
+    // -- Tool definitions --
+    getAgents = {
+        name: "get_agents",
+        description: "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.',
+        schema: getAgentsSchema,
+        execute: async () => {
+            try {
+                const result = await this.session.agents.getAgentsForLlm("basic");
+                const initErrors = this.session.agents.initializationErrors;
+                if (Object.keys(result).length === 0 && Object.keys(initErrors).length > 0) {
+                    const errors = {};
+                    for (const [agentId, error] of Object.entries(initErrors)) {
+                        errors[agentId] = `Failed to load agent: ${error}`;
+                    }
+                    return { agents: result, errors };
                 }
-                return { agents: result, errors };
+                return result;
             }
-            return result;
-        }
-        catch (e) {
-            return { error: true, error_message: `Failed to list agents: ${e}` };
-        }
-    }
-    /**
-     * 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).
-     */
-    async getAgent(agentId) {
-        try {
-            const result = await this.session.agents.getAgentForLlm(agentId, "full");
-            if (result === null) {
-                const available = Object.keys(await this.session.agents.getAgents()).sort();
-                return {
-                    error: true,
-                    error_message: `Agent '${agentId}' not found. Use get_agents to see available agents. Available: ${available.length > 0 ? available.join(", ") : "(none)"}`,
-                };
+            catch (e) {
+                return { error: true, error_message: `Failed to list agents: ${e}` };
             }
-            return result;
-        }
-        catch (e) {
-            return { error: true, error_message: `Failed to get agent info: ${e}` };
-        }
-    }
-    /**
-     * 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.
-     */
-    async sendMessage(agentId, message, contextId, taskId, timeout) {
-        try {
-            const result = await this.session.sendMessage(agentId, message, {
-                contextId,
-                taskId,
-                timeout,
-            });
-            let llmResult;
-            if (result.kind === "task") {
-                llmResult = await this.buildTaskForLlm(result);
+        },
+    };
+    getAgent = {
+        name: "get_agent",
+        description: "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.",
+        schema: getAgentSchema,
+        execute: async ({ agentId }) => {
+            try {
+                const result = await this.session.agents.getAgentForLlm(agentId, "full");
+                if (result === null) {
+                    const available = Object.keys(await this.session.agents.getAgents()).sort();
+                    return {
+                        error: true,
+                        error_message: `Agent '${agentId}' not found. Use get_agents to see available agents. Available: ${available.length > 0 ? available.join(", ") : "(none)"}`,
+                    };
+                }
+                return result;
             }
-            else {
-                llmResult = this.buildMessageForLlm(result);
+            catch (e) {
+                return { error: true, error_message: `Failed to get agent info: ${e}` };
             }
-            return llmResult;
-        }
-        catch (e) {
-            const errorMsg = String(e);
-            if (errorMsg.toLowerCase().includes("not found")) {
-                return {
-                    error: true,
-                    error_message: `${errorMsg} Use get_agents to see available agents.`,
-                };
+        },
+    };
+    sendMessage = {
+        name: "send_message",
+        description: "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.",
+        schema: sendMessageSchema,
+        execute: async ({ agentId, message, contextId, taskId, timeout, data, files, }) => {
+            try {
+                const result = await this.session.sendMessage(agentId, message, {
+                    contextId: contextId ?? null,
+                    taskId: taskId ?? null,
+                    timeout: timeout ?? null,
+                    data: data,
+                    files,
+                });
+                let llmResult;
+                if (result.kind === "task") {
+                    llmResult = await this.buildTaskForLlm(result);
+                }
+                else {
+                    llmResult = await this.buildMessageForLlm(result);
+                }
+                return llmResult;
             }
-            if (e instanceof DOMException && e.name === "TimeoutError") {
-                return {
-                    error: true,
-                    error_message: "Request timed out. You can retry with a longer timeout, " +
-                        "or if a task_id was returned earlier, use get_task to check progress.",
-                };
+            catch (e) {
+                const errorMsg = String(e);
+                if (errorMsg.toLowerCase().includes("not found")) {
+                    return {
+                        error: true,
+                        error_message: `${errorMsg} Use get_agents to see available agents.`,
+                    };
+                }
+                if (e instanceof DOMException && e.name === "TimeoutError") {
+                    return {
+                        error: true,
+                        error_message: "Request timed out. You can retry with a longer timeout, " +
+                            "or if a task_id was returned earlier, use get_task to check progress.",
+                    };
+                }
+                return { error: true, error_message: `Failed to send message: ${e}` };
             }
-            return { error: true, error_message: `Failed to send message: ${e}` };
-        }
-    }
-    /**
-     * 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.
-     */
-    async getTask(agentId, taskId, timeout, pollInterval) {
-        try {
-            const result = await this.session.getTask(agentId, taskId, {
-                timeout,
-                pollInterval,
-            });
-            const llmResult = await this.buildTaskForLlm(result);
-            return llmResult;
-        }
-        catch (e) {
-            const errorMsg = String(e);
-            if (errorMsg.toLowerCase().includes("not found")) {
-                return {
-                    error: true,
-                    error_message: `${errorMsg} Use get_agents to see available agents.`,
-                };
+        },
+    };
+    getTask = {
+        name: "get_task",
+        description: "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.",
+        schema: getTaskSchema,
+        execute: async ({ agentId, taskId, timeout, pollInterval, }) => {
+            try {
+                const result = await this.session.getTask(agentId, taskId, {
+                    timeout,
+                    pollInterval,
+                });
+                const llmResult = await this.buildTaskForLlm(result);
+                return llmResult;
             }
-            if (e instanceof DOMException && e.name === "TimeoutError") {
-                return {
-                    error: true,
-                    error_message: "Request timed out. You can retry with a longer timeout, " +
-                        "or use get_task again to continue monitoring.",
+            catch (e) {
+                const errorMsg = String(e);
+                if (errorMsg.toLowerCase().includes("not found")) {
+                    return {
+                        error: true,
+                        error_message: `${errorMsg} Use get_agents to see available agents.`,
+                    };
+                }
+                if (e instanceof DOMException && e.name === "TimeoutError") {
+                    return {
+                        error: true,
+                        error_message: "Request timed out. You can retry with a longer timeout, " +
+                            "or use get_task again to continue monitoring.",
+                    };
+                }
+                return { error: true, error_message: `Failed to get task: ${e}` };
+            }
+        },
+    };
+    viewTextArtifact = {
+        name: "view_text_artifact",
+        description: "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.",
+        schema: viewTextArtifactSchema,
+        execute: async ({ agentId, taskId, artifactId, lineStart, lineEnd, characterStart, characterEnd, }) => {
+            try {
+                const artifact = await this.getArtifact(agentId, taskId, artifactId);
+                const text = A2ATools.extractText(artifact);
+                const filtered = TextArtifacts.view(text, {
+                    lineStart,
+                    lineEnd,
+                    characterStart,
+                    characterEnd,
+                    characterLimit: this.artifactSettings.viewArtifactCharacterLimit,
+                });
+                const result = {
+                    artifactId: artifact.artifactId,
+                    description: artifact.description ?? null,
+                    name: artifact.name ?? null,
+                    parts: [{ kind: "text", text: filtered }],
                 };
+                return result;
             }
-            return { error: true, error_message: `Failed to get task: ${e}` };
-        }
-    }
-    /**
-     * 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).
-     */
-    async viewTextArtifact(agentId, taskId, artifactId, lineStart, lineEnd, characterStart, characterEnd) {
-        try {
-            const artifact = await this.getArtifact(agentId, taskId, artifactId);
-            const text = A2ATools.extractText(artifact);
-            const filtered = TextArtifacts.view(text, {
-                lineStart,
-                lineEnd,
-                characterStart,
-                characterEnd,
-                characterLimit: this.artifactSettings.viewArtifactCharacterLimit,
-            });
-            const result = {
-                artifactId: artifact.artifactId,
-                description: artifact.description ?? null,
-                name: artifact.name ?? null,
-                parts: [{ kind: "text", text: filtered }],
-            };
-            return result;
-        }
-        catch (e) {
-            const errorMsg = String(e);
-            if (errorMsg.toLowerCase().includes("not found")) {
-                if (errorMsg.toLowerCase().includes("artifact")) {
+            catch (e) {
+                const errorMsg = String(e);
+                if (errorMsg.toLowerCase().includes("not found")) {
+                    if (errorMsg.toLowerCase().includes("artifact")) {
+                        return {
+                            error: true,
+                            error_message: `Artifact '${artifactId}' not found in task '${taskId}'. Check the task's artifacts list for valid artifact IDs.`,
+                        };
+                    }
                     return {
                         error: true,
-                        error_message: `Artifact '${artifactId}' not found in task '${taskId}'. Check the task's artifacts list for valid artifact IDs.`,
+                        error_message: `${errorMsg} Use get_agents to see available agents.`,
                     };
                 }
-                return {
-                    error: true,
-                    error_message: `${errorMsg} Use get_agents to see available agents.`,
+                return { error: true, error_message: `Failed to view text artifact: ${e}` };
+            }
+        },
+    };
+    viewDataArtifact = {
+        name: "view_data_artifact",
+        description: "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.",
+        schema: viewDataArtifactSchema,
+        execute: async ({ agentId, taskId, artifactId, jsonPath, rows, columns, }) => {
+            try {
+                const parsedRows = A2ATools.parseRows(rows ?? null);
+                const parsedColumns = A2ATools.parseColumns(columns ?? null);
+                const artifact = await this.getArtifact(agentId, taskId, artifactId);
+                const data = A2ATools.extractData(artifact);
+                const filtered = DataArtifacts.view(data, {
+                    jsonPath,
+                    rows: parsedRows,
+                    columns: parsedColumns,
+                    characterLimit: this.artifactSettings.viewArtifactCharacterLimit,
+                });
+                const result = {
+                    artifactId: artifact.artifactId,
+                    description: artifact.description ?? null,
+                    name: artifact.name ?? null,
+                    parts: [{ kind: "data", data: filtered }],
                 };
+                return result;
             }
-            return { error: true, error_message: `Failed to view text artifact: ${e}` };
-        }
-    }
-    /**
-     * 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).
-     */
-    async viewDataArtifact(agentId, taskId, artifactId, jsonPath, rows, columns) {
-        try {
-            const parsedRows = A2ATools.parseRows(rows ?? null);
-            const parsedColumns = A2ATools.parseColumns(columns ?? null);
-            const artifact = await this.getArtifact(agentId, taskId, artifactId);
-            const data = A2ATools.extractData(artifact);
-            const filtered = DataArtifacts.view(data, {
-                jsonPath,
-                rows: parsedRows,
-                columns: parsedColumns,
-                characterLimit: this.artifactSettings.viewArtifactCharacterLimit,
-            });
-            const result = {
-                artifactId: artifact.artifactId,
-                description: artifact.description ?? null,
-                name: artifact.name ?? null,
-                parts: [{ kind: "data", data: filtered }],
-            };
-            return result;
-        }
-        catch (e) {
-            const errorMsg = String(e);
-            if (errorMsg.toLowerCase().includes("not found")) {
-                if (errorMsg.toLowerCase().includes("artifact")) {
+            catch (e) {
+                const errorMsg = String(e);
+                if (errorMsg.toLowerCase().includes("not found")) {
+                    if (errorMsg.toLowerCase().includes("artifact")) {
+                        return {
+                            error: true,
+                            error_message: `Artifact '${artifactId}' not found in task '${taskId}'. Check the task's artifacts list for valid artifact IDs.`,
+                        };
+                    }
                     return {
                         error: true,
-                        error_message: `Artifact '${artifactId}' not found in task '${taskId}'. Check the task's artifacts list for valid artifact IDs.`,
+                        error_message: `${errorMsg} Use get_agents to see available agents.`,
                     };
                 }
-                return {
-                    error: true,
-                    error_message: `${errorMsg} Use get_agents to see available agents.`,
-                };
+                return { error: true, error_message: `Failed to view data artifact: ${e}` };
             }
-            return { error: true, error_message: `Failed to view data artifact: ${e}` };
-        }
+        },
+    };
+    /** All tool definitions as an array. */
+    get toolDefinitions() {
+        return [
+            this.getAgents,
+            this.getAgent,
+            this.sendMessage,
+            this.getTask,
+            this.viewTextArtifact,
+            this.viewDataArtifact,
+        ];
     }
-    // -- LLM conversion methods --
-    /**
-     * Convert an A2A Message to MessageForLLM.
-     *
-     * Combines all TextParts into a single TextPartForLLM.
-     * FileParts are ignored; file handling is done at the artifact level.
-     */
-    buildMessageForLlm(message) {
+    // -- Private helpers --
+    /** Convert an A2A Message to MessageForLLM. */
+    async buildMessageForLlm(message) {
         const parts = [];
         // Combine all text parts
         const textSegments = [];
@@ -292,6 +347,17 @@ export class A2ATools {
                 parts.push({ kind: "data", data: part.data });
             }
         }
+        // Handle file parts
+        let savedPaths = [];
+        if (this.session.fileStore !== null) {
+            savedPaths = await this.session.fileStore.getMessage(message.messageId);
+        }
+        const hasSavedPaths = savedPaths.length > 0;
+        for (const part of message.parts) {
+            if (part.kind === "file") {
+                parts.push(A2ATools.buildFilePartForLlm(part, hasSavedPaths ? savedPaths : null));
+            }
+        }
         return {
             contextId: message.contextId ?? null,
             kind: "message",
@@ -300,12 +366,11 @@ export class A2ATools {
     }
     /** Convert a Task to TaskForLLM with artifact minimization and file path queries. */
     async buildTaskForLlm(task) {
-        // Query fileStore for saved file paths
         let savedFilePaths = null;
         if (this.session.fileStore !== null && task.artifacts) {
             savedFilePaths = {};
             for (const artifact of task.artifacts) {
-                const paths = await this.session.fileStore.get(task.id, artifact.artifactId);
+                const paths = await this.session.fileStore.getArtifact(task.id, artifact.artifactId);
                 if (paths.length > 0) {
                     savedFilePaths[artifact.artifactId] = paths;
                 }
@@ -320,10 +385,9 @@ export class A2ATools {
                 dataTip: DATA_MINIMIZED_TIP,
             })
             : [];
-        // Build status message
         let statusMessage = null;
         if (task.status.message) {
-            statusMessage = this.buildMessageForLlm(task.status.message);
+            statusMessage = await this.buildMessageForLlm(task.status.message);
         }
         return {
             id: task.id,
@@ -336,18 +400,8 @@ export class A2ATools {
             artifacts: minimized,
         };
     }
-    /**
-     * 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.
-     */
+    /** Look up an artifact through the resolution chain. */
     async getArtifact(agentId, taskId, artifactId) {
-        // 1. Check task store (local cache)
         const cachedTask = await this.session.taskStore.load(taskId);
         if (cachedTask?.artifacts) {
             for (const artifact of cachedTask.artifacts) {
@@ -356,7 +410,6 @@ export class A2ATools {
                 }
             }
         }
-        // 2. Fetch fresh via session.getTask
         const task = await this.session.getTask(agentId, taskId);
         if (task.artifacts) {
             for (const artifact of task.artifacts) {
@@ -367,11 +420,6 @@ export class A2ATools {
         }
         throw new Error(`Artifact '${artifactId}' not found in task '${taskId}'. The artifact may have expired or the task_id may be incorrect.`);
     }
-    /**
-     * Extract text content from artifact parts.
-     *
-     * @throws Error if artifact does not contain text content.
-     */
     static extractText(artifact) {
         const textParts = [];
         for (const part of artifact.parts) {
@@ -386,11 +434,6 @@ export class A2ATools {
         }
         return textParts.join("\n");
     }
-    /**
-     * Extract data content from artifact parts.
-     *
-     * @throws Error if artifact does not contain data content.
-     */
     static extractData(artifact) {
         const dataParts = [];
         for (const part of artifact.parts) {
@@ -405,12 +448,6 @@ export class A2ATools {
         }
         return dataParts.length === 1 ? dataParts[0] : dataParts;
     }
-    /**
-     * 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.
-     */
     static parseRows(rows) {
         if (rows === null) {
             return null;
@@ -419,7 +456,6 @@ export class A2ATools {
         if (trimmedRows === "all") {
             return "all";
         }
-        // Comma-separated list: "0,2,5"
         if (trimmedRows.includes(",")) {
             try {
                 return trimmedRows.split(",").map((x) => {
@@ -434,23 +470,15 @@ export class A2ATools {
                 throw new Error(`Invalid rows format: '${trimmedRows}'. Comma-separated values must be integers. Examples: '0', '0-10', '0,2,5', 'all'.`);
             }
         }
-        // Range string: "0-10"
         if (trimmedRows.includes("-")) {
             return trimmedRows;
         }
-        // Single integer: "0"
         const n = Number.parseInt(trimmedRows, 10);
         if (Number.isNaN(n)) {
             throw new Error(`Invalid rows format: '${trimmedRows}'. Examples: '0' (single row), '0-10' (range), '0,2,5' (specific rows), 'all'.`);
         }
         return n;
     }
-    /**
-     * 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.
-     */
     static parseColumns(columns) {
         if (columns === null) {
             return null;
@@ -459,12 +487,55 @@ export class A2ATools {
         if (trimmedColumns === "all") {
             return "all";
         }
-        // Comma-separated list: "name,age"
         if (trimmedColumns.includes(",")) {
             return trimmedColumns.split(",").map((c) => c.trim());
         }
-        // Single column name
         return trimmedColumns;
     }
+    static buildFilePartForLlm(part, savedPaths) {
+        if (part.kind !== "file") {
+            throw new Error("Expected file part");
+        }
+        const fileObj = part.file;
+        const name = fileObj.name ?? null;
+        const mimeType = fileObj.mimeType ?? null;
+        if ("bytes" in fileObj) {
+            if (savedPaths !== null) {
+                return {
+                    kind: "file",
+                    name,
+                    mimeType,
+                    uri: null,
+                    bytes: { _saved_to: savedPaths },
+                };
+            }
+            return {
+                kind: "file",
+                name,
+                mimeType,
+                uri: null,
+                bytes: { _error: "No FileStore configured. Cannot access file bytes." },
+            };
+        }
+        if ("uri" in fileObj) {
+            if (savedPaths !== null) {
+                return {
+                    kind: "file",
+                    name,
+                    mimeType,
+                    uri: { _saved_to: savedPaths },
+                    bytes: null,
+                };
+            }
+            return {
+                kind: "file",
+                name,
+                mimeType,
+                uri: fileObj.uri,
+                bytes: null,
+            };
+        }
+        return { kind: "file", name, mimeType, uri: null, bytes: null };
+    }
 }
 //# sourceMappingURL=a2a-tools.js.map