@artinet/sdk 0.5.14 → 0.5.16

package/README.md

@@ -69,6 +69,11 @@ It has [serveral template projects](https://github.com/the-artinet-project/creat
 - 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 Zod schemas are now nullable for better interoperability.
+- The `EngineBuilder` constructor is now protected and open for extension.
+- `AgentBuilder` will now throw an error if it recieves an invalid `FilePart`.
 
 ## Installation
 

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

@@ -140,11 +140,11 @@ type OutArgsOf<O> = O extends StepOutputWithForwardArgs<any, infer A> ? A : [];
 export declare class EngineBuilder<TCommand extends MessageSendParams = MessageSendParams, TInboundArgs extends readonly unknown[] = []> implements StepBuilder<TCommand, TInboundArgs> {
     private steps;
     /**
-     * Private constructor to enforce factory method usage.
+     * Protected constructor to enforce factory method usage.
      *
      * @param steps - Initial steps array
      */
-    private constructor();
+    protected constructor(steps?: Array<StepWithKind<TCommand, any, any, any, any, any>>);
     /**
      * Creates a new EngineBuilder instance.
      *
@@ -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/factory/builder.js

@@ -18,6 +18,7 @@ import { TaskState, } from "../../../types/index.js";
 import { createAgent } from "./service.js";
 import { v4 as uuidv4 } from "uuid";
 import { getContent } from "../helpers/content.js";
+import { SUBMITTED_UPDATE, WORKING_UPDATE } from "../../../utils/index.js";
 /**
  * Fluent builder for constructing A2A agent execution engines.
  *
@@ -50,7 +51,7 @@ export class EngineBuilder {
     //@typescript-eslint/no-explicit-any
     steps = [];
     /**
-     * Private constructor to enforce factory method usage.
+     * Protected constructor to enforce factory method usage.
      *
      * @param steps - Initial steps array
      */
@@ -231,23 +232,27 @@ const partToMessagePart = (kind, part) => {
         }
         case "file": {
             const filePart = part;
-            return filePart.uri
-                ? {
+            if (filePart.uri) {
+                return {
                     kind: "file",
                     file: {
                         uri: filePart.uri,
                         name: filePart.name,
                         mimeType: filePart.mimeType,
                     },
-                }
-                : {
-                    kind: "file",
-                    file: {
-                        bytes: filePart.bytes ?? "",
-                        name: filePart.name,
-                        mimeType: filePart.mimeType,
-                    },
                 };
+            }
+            if (!filePart.bytes) {
+                throw new Error("File bytes are required when uri is not provided");
+            }
+            return {
+                kind: "file",
+                file: {
+                    bytes: filePart.bytes,
+                    name: filePart.name,
+                    mimeType: filePart.mimeType,
+                },
+            };
         }
         case "data": {
             return { kind: "data", data: part };
@@ -287,21 +292,12 @@ export function createAgentExecutor(stepsList) {
             content: content,
             args: [],
         };
-        const contextId = context.contextId ?? context.command.message.contextId;
-        const taskId = context.State().task.id ?? context.command.message.taskId;
+        const contextId = context.contextId;
+        const taskId = context.State().task.id;
         if (!contextId || !taskId) {
             throw new Error("Context ID and task ID are required");
         }
-        const taskStarted = {
-            taskId: taskId,
-            contextId: contextId,
-            kind: "status-update",
-            status: {
-                state: TaskState.submitted,
-                timestamp: new Date().toISOString(),
-            },
-            final: false,
-        };
+        const taskStarted = SUBMITTED_UPDATE(taskId, contextId);
         yield taskStarted;
         const finalMessage = {
             taskId: taskId,
@@ -316,65 +312,35 @@ export function createAgentExecutor(stepsList) {
             let parts = [];
             if (Array.isArray(ret)) {
                 parts = ret.map((part) => partToMessagePart(step.kind, part));
-                const taskStatusUpdate = {
-                    taskId: taskId,
-                    contextId: contextId,
-                    kind: "status-update",
-                    status: {
-                        state: TaskState.working,
-                        timestamp: new Date().toISOString(),
-                        message: {
-                            messageId: uuidv4(),
-                            kind: "message",
-                            role: "agent",
-                            parts: parts,
-                        },
-                    },
-                    final: false,
-                };
+                const taskStatusUpdate = WORKING_UPDATE(taskId, contextId, {
+                    messageId: uuidv4(),
+                    kind: "message",
+                    role: "agent",
+                    parts: parts,
+                });
                 yield taskStatusUpdate;
             }
-            else if (typeof ret === "object") {
+            else if (ret !== null && typeof ret === "object") {
                 parts = Array.isArray(ret.parts)
                     ? ret.parts.map((part) => partToMessagePart(step.kind, part))
                     : [partToMessagePart(step.kind, ret.parts)];
-                const taskStatusUpdate = {
-                    taskId: taskId,
-                    contextId: contextId,
-                    kind: "status-update",
-                    status: {
-                        state: TaskState.working,
-                        timestamp: new Date().toISOString(),
-                        message: {
-                            messageId: uuidv4(),
-                            kind: "message",
-                            role: "agent",
-                            parts: parts,
-                        },
-                    },
-                    final: false,
-                };
+                const taskStatusUpdate = WORKING_UPDATE(taskId, contextId, {
+                    messageId: uuidv4(),
+                    kind: "message",
+                    role: "agent",
+                    parts: parts,
+                });
                 yield taskStatusUpdate;
                 stepArgs.args = ret.args;
             }
             else {
                 parts = [partToMessagePart(step.kind, ret)];
-                const taskStatusUpdate = {
-                    taskId: taskId,
-                    contextId: contextId,
-                    kind: "status-update",
-                    status: {
-                        state: TaskState.working,
-                        timestamp: new Date().toISOString(),
-                        message: {
-                            messageId: uuidv4(),
-                            kind: "message",
-                            role: "agent",
-                            parts: parts,
-                        },
-                    },
-                    final: false,
-                };
+                const taskStatusUpdate = WORKING_UPDATE(taskId, contextId, {
+                    messageId: uuidv4(),
+                    kind: "message",
+                    role: "agent",
+                    parts: parts,
+                });
                 yield taskStatusUpdate;
             }
             finalMessage.parts.push(...parts);

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", () => {