@artinet/sdk 0.5.15 → 0.5.17

package/README.md

@@ -71,7 +71,10 @@ It has [serveral template projects](https://github.com/the-artinet-project/creat
 - 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.
+- ~~Optional fields in Agent2Agent Zod schemas are now nullable for better interoperability.~~ **Nullable Schemas have been reverted.**
+- The `EngineBuilder` constructor is now protected and open for extension.
+- `AgentBuilder` will now throw an error if it recieves an invalid `FilePart`.
+- `createAgent`/`createService` can now take a single string (i.e. agentName) as valid value for the AgentCard and will populate the rest of the required fields with placeholder values (see `src/services/a2a/helpers/agentcard-builder.ts` for reference).
 
 ## Installation
 
@@ -112,21 +115,13 @@ const { app, agent } = createAgentServer({
     return `You said: ${userInput}`;
   })
   .createAgent({
-    agentCard: {
-      name: "QuickStart Agent",
-      description: "A simple agent that echoes the user's message",
-      url: "http://localhost:4000/a2a",
-      version: "0.1.0",
-      capabilities: { streaming: true },
-      skills: [{ id: "echo", name: "Echo Skill" }],
-      ...
-    },
+    agentCard: "QuickStart Agent",
   }),
   basePath: "/a2a"
 });
 
-app.listen(4000, () => {
-  console.log("A2A Server running at http://localhost:4000/a2a");
+app.listen(3000, () => {
+  console.log("A2A Server running at http://localhost:3000/a2a");
 });
 ```
 
@@ -136,7 +131,7 @@ app.listen(4000, () => {
 import { A2AClient, TaskStatusUpdateEvent } from "@artinet/sdk";
 
 async function runClient() {
-  const client = new A2AClient("http://localhost:4000/a2a");
+  const client = new A2AClient("http://localhost:3000/a2a");
 
   const stream = client.sendStreamingMessage("Hello World!");
 
@@ -269,13 +264,7 @@ const { app, agent } = createAgentServer({
       return `Task completed. Status: ${status}`;
     }) //A final Task is returned to the caller which contains all of the emitted parts.
     .createAgent({
-      agentCard: {
-        name: "Multi-Step Agent",
-        url: "http://localhost:3000/a2a",
-        version: "1.0.0",
-        capabilities: { streaming: true },
-        skills: [{ id: "multi-processor", name: "Multi-Step Processor" }],
-      },
+      agentCard: "Multi-Step Agent",
     }),
   basePath: "/a2a",
 });
@@ -380,13 +369,7 @@ const agent = createAgent({
       ...
     });
   },
-  agentCard: {
-    name: "Event-Monitored Agent",
-    url: "http://localhost:3000/a2a",
-    version: "1.0.0",
-    capabilities: { streaming: true },
-    skills: [{ id: "monitor", name: "Monitored Agent" }],
-  },
+  agentCard: "Event-Monitored Agent",
   contexts: customContextManager,
   tasks: new TaskManager(),
   eventOverrides: { //for even greater control create your own Event Handlers
@@ -600,13 +583,7 @@ const mcpAgent = createMCPAgent({
   },
   agent: createAgent({
     engine: myAgentEngine,
-    agentCard: {
-      name: "My Agent",
-      url: "http://localhost:3000/a2a",
-      version: "1.0.0",
-      capabilities: { streaming: true },
-      skills: [{ id: "helper", name: "Helper Agent" }],
-    },
+    agentCard: "MCP Agent",
   }),
   agentCardUri: "agent://card", //customize the URI for your AgentCard
 });

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

@@ -23,48 +23,48 @@ export declare function createAgentServer(params: ServerParams & {
             parts: ({
                 file: {
                     bytes: string;
-                    name?: string | null | undefined;
-                    mimeType?: string | null | undefined;
-                    uri?: null | undefined;
+                    name?: string | undefined;
+                    mimeType?: string | undefined;
+                    uri?: undefined;
                 } | {
                     uri: string;
-                    name?: string | null | undefined;
-                    bytes?: null | undefined;
-                    mimeType?: string | null | undefined;
+                    name?: string | undefined;
+                    bytes?: undefined;
+                    mimeType?: string | undefined;
                 };
                 kind: "file";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             } | {
                 text: string;
                 kind: "text";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             } | {
                 data: Record<string, unknown>;
                 kind: "data";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             })[];
             messageId: string;
-            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;
+            extensions?: string[] | undefined;
+            referenceTaskIds?: string[] | undefined;
+            taskId?: string | undefined;
+            contextId?: string | undefined;
         };
-        metadata?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | undefined;
         configuration?: {
-            historyLength?: number | null | undefined;
+            historyLength?: number | undefined;
             pushNotificationConfig?: {
                 url: string;
-                id?: string | null | undefined;
-                token?: string | null | undefined;
+                id?: string | undefined;
+                token?: string | undefined;
                 authentication?: {
                     schemes: string[];
-                    credentials?: string | null | undefined;
-                } | null | undefined;
-            } | null | undefined;
-            acceptedOutputModes?: string[] | null | undefined;
-            blocking?: boolean | null | undefined;
-        } | null | undefined;
+                    credentials?: string | undefined;
+                } | undefined;
+            } | undefined;
+            acceptedOutputModes?: string[] | undefined;
+            blocking?: boolean | undefined;
+        } | 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 | null | undefined;
-                mimeType?: string | null | undefined;
-                uri?: null | undefined;
+                name?: string | undefined;
+                mimeType?: string | undefined;
+                uri?: undefined;
             } | {
                 uri: string;
-                name?: string | null | undefined;
-                bytes?: null | undefined;
-                mimeType?: string | null | undefined;
+                name?: string | undefined;
+                bytes?: undefined;
+                mimeType?: string | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         })[];
         messageId: string;
-        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;
+        extensions?: string[] | undefined;
+        referenceTaskIds?: string[] | undefined;
+        taskId?: string | undefined;
+        contextId?: string | undefined;
     };
-    metadata?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
     configuration?: {
-        historyLength?: number | null | undefined;
+        historyLength?: number | undefined;
         pushNotificationConfig?: {
             url: string;
-            id?: string | null | undefined;
-            token?: string | null | undefined;
+            id?: string | undefined;
+            token?: string | undefined;
             authentication?: {
                 schemes: string[];
-                credentials?: string | null | undefined;
-            } | null | undefined;
-        } | null | undefined;
-        acceptedOutputModes?: string[] | null | undefined;
-        blocking?: boolean | null | undefined;
-    } | null | undefined;
+                credentials?: string | undefined;
+            } | undefined;
+        } | undefined;
+        acceptedOutputModes?: string[] | undefined;
+        blocking?: boolean | undefined;
+    } | 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/factory/service.js

@@ -5,7 +5,8 @@
 import { A2AService } from "../service.js";
 import { ContextManager, ConnectionManager, CancellationManager, TaskManager, } from "../managers/index.js";
 import { createMethods } from "./method.js";
+import { createAgentCard } from "../helpers/agentcard-builder.js";
 export function createService(params) {
-    return new A2AService(params.agentCard, params.engine, params.contexts ?? new ContextManager(), params.connections ?? new ConnectionManager(), params.cancellations ?? new CancellationManager(), params.tasks ?? new TaskManager(), createMethods(params.methods), params.events);
+    return new A2AService(createAgentCard(params.agentCard), params.engine, params.contexts ?? new ContextManager(), params.connections ?? new ConnectionManager(), params.cancellations ?? new CancellationManager(), params.tasks ?? new TaskManager(), createMethods(params.methods), params.events);
 }
 export const createAgent = createService;

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

@@ -0,0 +1,7 @@
+import { AgentCard, AgentCardParams } from "../../../types/index.js";
+export declare class AgentCardBuilder {
+    agentCard: AgentCard;
+    constructor(agentCard: Partial<AgentCard> & Required<Pick<AgentCard, "name">>);
+    valueOf(): AgentCard;
+}
+export declare function createAgentCard(agentCard: AgentCardParams): AgentCard;

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

@@ -0,0 +1,22 @@
+export class AgentCardBuilder {
+    agentCard;
+    constructor(agentCard) {
+        this.agentCard = {
+            ...agentCard,
+            protocolVersion: agentCard.protocolVersion ?? "0.3.0",
+            description: agentCard.description ?? "An agent that can use the A2A protocol.",
+            url: agentCard.url ?? "https://localhost:3000/a2a",
+            version: agentCard.version ?? "0.0.0",
+            capabilities: agentCard.capabilities ?? {},
+            defaultInputModes: agentCard.defaultInputModes ?? [],
+            defaultOutputModes: agentCard.defaultOutputModes ?? [],
+            skills: agentCard.skills ?? [],
+        };
+    }
+    valueOf() {
+        return this.agentCard;
+    }
+}
+export function createAgentCard(agentCard) {
+    return new AgentCardBuilder(typeof agentCard === "string" ? { name: agentCard } : agentCard).valueOf();
+}

package/dist/services/a2a/helpers/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./part.js";
 export * from "./content.js";
 export * from "./message-builder.js";
+export * from "./agentcard-builder.js";

package/dist/services/a2a/helpers/index.js

@@ -1,3 +1,4 @@
 export * from "./part.js";
 export * from "./content.js";
 export * from "./message-builder.js";
+export * from "./agentcard-builder.js";

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 | null | undefined;
-                    mimeType?: string | null | undefined;
-                    uri?: null | undefined;
+                    name?: string | undefined;
+                    mimeType?: string | undefined;
+                    uri?: undefined;
                 } | {
                     uri: string;
-                    name?: string | null | undefined;
-                    bytes?: null | undefined;
-                    mimeType?: string | null | undefined;
+                    name?: string | undefined;
+                    bytes?: undefined;
+                    mimeType?: string | undefined;
                 };
                 kind: "file";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             } | {
                 text: string;
                 kind: "text";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             } | {
                 data: Record<string, unknown>;
                 kind: "data";
-                metadata?: Record<string, unknown> | null | undefined;
+                metadata?: Record<string, unknown> | undefined;
             })[];
             messageId: string;
-            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;
+            metadata?: Record<string, unknown> | undefined;
+            extensions?: string[] | undefined;
+            referenceTaskIds?: string[] | undefined;
+            taskId?: string | undefined;
+            contextId?: string | undefined;
+        } | undefined;
+        timestamp?: string | undefined;
     };
     kind: "task";
     contextId: string;
-    metadata?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
     history?: {
         role: "user" | "agent";
         kind: "message";
         parts: ({
             file: {
                 bytes: string;
-                name?: string | null | undefined;
-                mimeType?: string | null | undefined;
-                uri?: null | undefined;
+                name?: string | undefined;
+                mimeType?: string | undefined;
+                uri?: undefined;
             } | {
                 uri: string;
-                name?: string | null | undefined;
-                bytes?: null | undefined;
-                mimeType?: string | null | undefined;
+                name?: string | undefined;
+                bytes?: undefined;
+                mimeType?: string | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         })[];
         messageId: string;
-        metadata?: Record<string, unknown> | null | undefined;
-        extensions?: string[] | null | undefined;
-        referenceTaskIds?: string[] | null | undefined;
-        taskId?: string | null | undefined;
-        contextId?: string | null | undefined;
-    }[] | null | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        extensions?: string[] | undefined;
+        referenceTaskIds?: string[] | undefined;
+        taskId?: string | undefined;
+        contextId?: string | undefined;
+    }[] | undefined;
     artifacts?: {
         artifactId: string;
         parts: ({
             file: {
                 bytes: string;
-                name?: string | null | undefined;
-                mimeType?: string | null | undefined;
-                uri?: null | undefined;
+                name?: string | undefined;
+                mimeType?: string | undefined;
+                uri?: undefined;
             } | {
                 uri: string;
-                name?: string | null | undefined;
-                bytes?: null | undefined;
-                mimeType?: string | null | undefined;
+                name?: string | undefined;
+                bytes?: undefined;
+                mimeType?: string | undefined;
             };
             kind: "file";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             text: string;
             kind: "text";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         } | {
             data: Record<string, unknown>;
             kind: "data";
-            metadata?: Record<string, unknown> | null | undefined;
+            metadata?: Record<string, unknown> | undefined;
         })[];
-        name?: string | null | undefined;
-        metadata?: Record<string, unknown> | null | undefined;
-        description?: string | null | undefined;
-        extension?: string[] | null | undefined;
-    }[] | null | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+        extension?: string[] | undefined;
+    }[] | undefined;
 }>;
 export type GetTaskMethod = typeof getTask;