@artinet/sdk 0.5.13 → 0.5.15

package/README.md

@@ -66,8 +66,12 @@ It has [serveral template projects](https://github.com/the-artinet-project/creat
 - AgentBuilder now prefers the contextId & taskId from the calling context.
 - In a future release the following packages will be set as peer dependancies to reduce the size of the build: `@modelcontextprotocol/sdk`, `@trpc/server`, `cors`, `express`
 - The `history` object from `TaskAndHistory` is deprecated and no longer being updated. Use `Task.history` instead.
-- The A2AClient now checks `/.well-known/agent-card.json` as a opposed to `/.well-known/agent.json` in-line with the A2A spec.
-- The examples folder will be removed in favor of [`create-agent`](https://github.com/the-artinet-project/create-agent)
+- The `A2AClient` now checks `/.well-known/agent-card.json` as a opposed to `/.well-known/agent.json` in-line with the A2A spec.
+- The `A2AClient` now uses uses the `AgentCard`.url if an `AgentCard` has been successfully retrieved, else it will default to the `baseUrl`.
+- The examples folder will be removed in favor of [`create-agent`](https://github.com/the-artinet-project/create-agent).
+- In `Task` the `contextId` field is now required (inline with the A2A spec).
+- In `AgentSkill` the `tag` field is now required (inline with the A2A spec).
+- Optional fields in Agent2Agent schema fields are now nullable for better interoperability.
 
 ## Installation
 

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

@@ -13,10 +13,20 @@ export declare class A2AClient implements Client {
     private cachedAgentCard;
     private customHeaders;
     private fallbackPath;
+    private agentUrl;
     /**
      * Creates a new A2AClient instance.
      * @param baseUrl The base URL for the A2A server.
      * @param headers Optional custom headers to include in all requests.
+     * @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
+     * @example
+     * const client = new A2AClient("http://localhost:4000/a2a");
+     * const card = await client.agentCard();
+     * console.log(card);
+     * @example
+     * const client = new A2AClient("http://localhost:4000/a2a", {}, "/agent-card");
+     * const card = await client.agentCard();
+     * console.log(card);
      */
     constructor(baseUrl: URL | string, headers?: Record<string, string>, fallbackPath?: string);
     /**

package/dist/client/a2a-client.js

@@ -15,15 +15,26 @@ export class A2AClient {
     cachedAgentCard = null;
     customHeaders = {};
     fallbackPath;
+    agentUrl;
     /**
      * Creates a new A2AClient instance.
      * @param baseUrl The base URL for the A2A server.
      * @param headers Optional custom headers to include in all requests.
+     * @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
+     * @example
+     * const client = new A2AClient("http://localhost:4000/a2a");
+     * const card = await client.agentCard();
+     * console.log(card);
+     * @example
+     * const client = new A2AClient("http://localhost:4000/a2a", {}, "/agent-card");
+     * const card = await client.agentCard();
+     * console.log(card);
      */
     constructor(baseUrl, headers = {}, fallbackPath) {
         this.baseUrl = typeof baseUrl === "string" ? new URL(baseUrl) : baseUrl;
         this.customHeaders = headers;
         this.fallbackPath = fallbackPath ?? "/agent-card";
+        this.agentUrl = this.baseUrl;
     }
     /**
      * Retrieves the AgentCard from the A2A server.
@@ -46,7 +57,6 @@ export class A2AClient {
                     throw new Error("No agent card found");
                 }
                 this.cachedAgentCard = card;
-                return this.cachedAgentCard;
             }
             catch (error) {
                 const fallbackUrl = new URL(this.fallbackPath, this.baseUrl);
@@ -57,13 +67,14 @@ export class A2AClient {
                     throw new Error("No fallback agent card found");
                 }
                 this.cachedAgentCard = fallbackCard;
-                return this.cachedAgentCard;
             }
         }
         catch (error) {
             logError("A2AClient:agentCard", "Failed to fetch or parse agent card:", error);
             throw INTERNAL_ERROR(`Could not retrieve agent card: ${error instanceof Error ? error.message : String(error)}`);
         }
+        this.agentUrl = new URL(this.cachedAgentCard.url, this.baseUrl);
+        return this.cachedAgentCard;
     }
     /**
      * Refreshes the cached AgentCard by fetching it again from the server.
@@ -79,7 +90,7 @@ export class A2AClient {
      * @returns A promise resolving to Message/Task response from the agent server or null.
      */
     async sendMessage(params) {
-        return await executeJsonRpcRequest(this.baseUrl, "message/send", createMessageSendParams(params), this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "message/send", createMessageSendParams(params), this.customHeaders);
     }
     /**
      * @deprecated Use sendMessage instead.
@@ -96,7 +107,7 @@ export class A2AClient {
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
      */
     sendStreamingMessage(params) {
-        return executeStreamEvents(this.baseUrl, "message/stream", createMessageSendParams(params), this.customHeaders);
+        return executeStreamEvents(this.agentUrl, "message/stream", createMessageSendParams(params), this.customHeaders);
     }
     /**
      * @deprecated Use sendStreamingMessage instead.
@@ -113,7 +124,7 @@ export class A2AClient {
      * @returns A promise resolving to the Task object or null.
      */
     async getTask(params) {
-        return await executeJsonRpcRequest(this.baseUrl, "tasks/get", params, this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "tasks/get", params, this.customHeaders);
     }
     /**
      * Cancels a currently running task.
@@ -121,7 +132,7 @@ export class A2AClient {
      * @returns A promise resolving to the updated Task object (usually canceled state) or null.
      */
     async cancelTask(params) {
-        return await executeJsonRpcRequest(this.baseUrl, "tasks/cancel", params, this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "tasks/cancel", params, this.customHeaders);
     }
     /**
      * Sets or updates the push notification config for a task.
@@ -129,7 +140,7 @@ export class A2AClient {
      * @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
      */
     async setTaskPushNotification(params) {
-        return await executeJsonRpcRequest(this.baseUrl, "tasks/pushNotificationConfig/set", params, this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/set", params, this.customHeaders);
     }
     /**
      * Retrieves the currently configured push notification config for a task.
@@ -137,7 +148,7 @@ export class A2AClient {
      * @returns A promise resolving to the TaskPushNotificationConfig or null.
      */
     async getTaskPushNotification(params) {
-        return await executeJsonRpcRequest(this.baseUrl, "tasks/pushNotificationConfig/get", params, this.customHeaders);
+        return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/get", params, this.customHeaders);
     }
     /**
      * Resubscribes to an existing task's update stream.
@@ -145,7 +156,7 @@ export class A2AClient {
      * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
      */
     resubscribeTask(params) {
-        return executeStreamEvents(this.baseUrl, "tasks/resubscribe", params, this.customHeaders);
+        return executeStreamEvents(this.agentUrl, "tasks/resubscribe", params, this.customHeaders);
     }
     /**
      * Checks if the server supports a specific capability based on the agent card.

package/dist/server/express/server.d.ts

@@ -23,48 +23,48 @@ export declare function createAgentServer(params: ServerParams & {
             parts: ({
                 file: {
                     bytes: string;
-                    name?: string | undefined;
-                    mimeType?: string | undefined;
-                    uri?: undefined;
+                    name?: string | null | undefined;
+                    mimeType?: string | null | undefined;
+                    uri?: null | undefined;
                 } | {
                     uri: string;
-                    name?: string | undefined;
-                    bytes?: undefined;
-                    mimeType?: string | undefined;
+                    name?: string | null | undefined;
+                    bytes?: null | undefined;
+                    mimeType?: string | null | undefined;
                 };
                 kind: "file";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             } | {
                 text: string;
                 kind: "text";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             } | {
                 data: Record<string, unknown>;
                 kind: "data";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             })[];
             messageId: string;
-            metadata?: Record<string, unknown> | undefined;
-            extensions?: string[] | undefined;
-            referenceTaskIds?: string[] | undefined;
-            taskId?: string | undefined;
-            contextId?: string | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
+            extensions?: string[] | null | undefined;
+            referenceTaskIds?: string[] | null | undefined;
+            taskId?: string | null | undefined;
+            contextId?: string | null | undefined;
         };
-        metadata?: Record<string, unknown> | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
         configuration?: {
-            historyLength?: number | undefined;
+            historyLength?: number | null | undefined;
             pushNotificationConfig?: {
                 url: string;
-                id?: string | undefined;
-                token?: string | undefined;
+                id?: string | null | undefined;
+                token?: string | null | undefined;
                 authentication?: {
                     schemes: string[];
-                    credentials?: string | undefined;
-                } | undefined;
-            } | undefined;
-            acceptedOutputModes?: string[] | undefined;
-            blocking?: boolean | undefined;
-        } | undefined;
+                    credentials?: string | null | undefined;
+                } | null | undefined;
+            } | null | undefined;
+            acceptedOutputModes?: string[] | null | undefined;
+            blocking?: boolean | null | undefined;
+        } | null | undefined;
     }, import("../../types/index.js").TaskAndHistory, import("../../types/index.js").UpdateEvent>;
 };
 export type ExpressAgentServer = ReturnType<typeof createAgentServer>;

package/dist/services/a2a/factory/builder.d.ts

@@ -282,48 +282,48 @@ export declare const AgentBuilder: () => EngineBuilder<{
         parts: ({
             file: {
                 bytes: string;
-                name?: string | undefined;
-                mimeType?: string | undefined;
-                uri?: undefined;
+                name?: string | null | undefined;
+                mimeType?: string | null | undefined;
+                uri?: null | undefined;
             } | {
                 uri: string;
-                name?: string | undefined;
-                bytes?: undefined;
-                mimeType?: string | undefined;
+                name?: string | null | undefined;
+                bytes?: null | undefined;
+                mimeType?: string | null | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         })[];
         messageId: string;
-        metadata?: Record<string, unknown> | undefined;
-        extensions?: string[] | undefined;
-        referenceTaskIds?: string[] | undefined;
-        taskId?: string | undefined;
-        contextId?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        extensions?: string[] | null | undefined;
+        referenceTaskIds?: string[] | null | undefined;
+        taskId?: string | null | undefined;
+        contextId?: string | null | undefined;
     };
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
     configuration?: {
-        historyLength?: number | undefined;
+        historyLength?: number | null | undefined;
         pushNotificationConfig?: {
             url: string;
-            id?: string | undefined;
-            token?: string | undefined;
+            id?: string | null | undefined;
+            token?: string | null | undefined;
             authentication?: {
                 schemes: string[];
-                credentials?: string | undefined;
-            } | undefined;
-        } | undefined;
-        acceptedOutputModes?: string[] | undefined;
-        blocking?: boolean | undefined;
-    } | undefined;
+                credentials?: string | null | undefined;
+            } | null | undefined;
+        } | null | undefined;
+        acceptedOutputModes?: string[] | null | undefined;
+        blocking?: boolean | null | undefined;
+    } | null | undefined;
 }, []>;
 /**
  * Creates an agent execution engine from a list of workflow steps.

package/dist/services/a2a/helpers/message-builder.d.ts

@@ -6,7 +6,7 @@ export declare class MessageBuilder {
 }
 export declare class MessageSendConfigurationBuilder {
     configuration: MessageSendConfiguration;
-    constructor(configuration?: Partial<MessageSendConfiguration>);
+    constructor(configuration?: Partial<MessageSendConfiguration> | null);
     valueOf(): MessageSendConfiguration;
 }
 export declare const createMessageSendParams: (messageSendParams: Partial<MessageSendParams> | string) => MessageSendParams;

package/dist/services/a2a/helpers/message-builder.js

@@ -35,15 +35,15 @@ export class MessageSendConfigurationBuilder {
     };
     constructor(configuration = {}) {
         this.configuration.acceptedOutputModes =
-            configuration.acceptedOutputModes ??
+            configuration?.acceptedOutputModes ??
                 this.configuration.acceptedOutputModes;
         this.configuration.historyLength =
-            configuration.historyLength ?? this.configuration.historyLength;
+            configuration?.historyLength ?? this.configuration.historyLength;
         this.configuration.pushNotificationConfig =
-            configuration.pushNotificationConfig ??
+            configuration?.pushNotificationConfig ??
                 this.configuration.pushNotificationConfig;
         this.configuration.blocking =
-            configuration.blocking ?? this.configuration.blocking;
+            configuration?.blocking ?? this.configuration.blocking;
     }
     valueOf() {
         return this.configuration;

package/dist/services/a2a/methods/get-task.d.ts

@@ -13,100 +13,100 @@ export declare function getTask(input: TaskQueryParams, params: Omit<MethodParam
             parts: ({
                 file: {
                     bytes: string;
-                    name?: string | undefined;
-                    mimeType?: string | undefined;
-                    uri?: undefined;
+                    name?: string | null | undefined;
+                    mimeType?: string | null | undefined;
+                    uri?: null | undefined;
                 } | {
                     uri: string;
-                    name?: string | undefined;
-                    bytes?: undefined;
-                    mimeType?: string | undefined;
+                    name?: string | null | undefined;
+                    bytes?: null | undefined;
+                    mimeType?: string | null | undefined;
                 };
                 kind: "file";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             } | {
                 text: string;
                 kind: "text";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             } | {
                 data: Record<string, unknown>;
                 kind: "data";
-                metadata?: Record<string, unknown> | undefined;
+                metadata?: Record<string, unknown> | null | undefined;
             })[];
             messageId: string;
-            metadata?: Record<string, unknown> | undefined;
-            extensions?: string[] | undefined;
-            referenceTaskIds?: string[] | undefined;
-            taskId?: string | undefined;
-            contextId?: string | undefined;
-        } | undefined;
-        timestamp?: string | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
+            extensions?: string[] | null | undefined;
+            referenceTaskIds?: string[] | null | undefined;
+            taskId?: string | null | undefined;
+            contextId?: string | null | undefined;
+        } | null | undefined;
+        timestamp?: string | null | undefined;
     };
     kind: "task";
-    metadata?: Record<string, unknown> | undefined;
+    contextId: string;
+    metadata?: Record<string, unknown> | null | undefined;
     history?: {
         role: "user" | "agent";
         kind: "message";
         parts: ({
             file: {
                 bytes: string;
-                name?: string | undefined;
-                mimeType?: string | undefined;
-                uri?: undefined;
+                name?: string | null | undefined;
+                mimeType?: string | null | undefined;
+                uri?: null | undefined;
             } | {
                 uri: string;
-                name?: string | undefined;
-                bytes?: undefined;
-                mimeType?: string | undefined;
+                name?: string | null | undefined;
+                bytes?: null | undefined;
+                mimeType?: string | null | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         })[];
         messageId: string;
-        metadata?: Record<string, unknown> | undefined;
-        extensions?: string[] | undefined;
-        referenceTaskIds?: string[] | undefined;
-        taskId?: string | undefined;
-        contextId?: string | undefined;
-    }[] | undefined;
-    contextId?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        extensions?: string[] | null | undefined;
+        referenceTaskIds?: string[] | null | undefined;
+        taskId?: string | null | undefined;
+        contextId?: string | null | undefined;
+    }[] | null | undefined;
     artifacts?: {
         artifactId: string;
         parts: ({
             file: {
                 bytes: string;
-                name?: string | undefined;
-                mimeType?: string | undefined;
-                uri?: undefined;
+                name?: string | null | undefined;
+                mimeType?: string | null | undefined;
+                uri?: null | undefined;
             } | {
                 uri: string;
-                name?: string | undefined;
-                bytes?: undefined;
-                mimeType?: string | undefined;
+                name?: string | null | undefined;
+                bytes?: null | undefined;
+                mimeType?: string | null | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | null | undefined;
         })[];
-        name?: string | undefined;
-        metadata?: Record<string, unknown> | undefined;
-        description?: string | undefined;
-        extension?: string[] | undefined;
-    }[] | undefined;
+        name?: string | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        description?: string | null | undefined;
+        extension?: string[] | null | undefined;
+    }[] | null | undefined;
 }>;
 export type GetTaskMethod = typeof getTask;

package/dist/services/a2a/methods/send-message.js

@@ -6,7 +6,7 @@ import { createContext } from "../factory/context.js";
 export async function sendMessage(input, params) {
     const { service, engine, contextManager, signal } = params;
     const contextId = input.message.contextId;
-    const context = createContext(input, service, contextManager, signal, contextId, service.eventOverrides);
+    const context = createContext(input, service, contextManager, signal, contextId ?? undefined, service.eventOverrides);
     context.events.on("complete", () => {
         contextManager.deleteContext(context.events.contextId);
     });

package/dist/services/a2a/methods/stream-message.js

@@ -7,7 +7,7 @@ import { createContext } from "../factory/context.js";
 export async function* streamMessage(input, params) {
     const { service, engine, contextManager, signal } = params;
     let contextId = input.message.contextId;
-    const context = createContext(input, service, contextManager, signal, contextId, service.eventOverrides);
+    const context = createContext(input, service, contextManager, signal, contextId ?? undefined, service.eventOverrides);
     const stream = new StreamManager(context);
     contextId = stream.getContextId();
     context.events.on("complete", () => {