@artinet/sdk 0.5.16 → 0.5.18

package/dist/client/a2a-client.js

@@ -2,9 +2,10 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { executeJsonRpcRequest, executeGetRequest, executeStreamEvents, } from "../transport/index.js";
-import { INTERNAL_ERROR } from "../utils/index.js";
-import { logError } from "../utils/logging/index.js";
+import { executeJsonRpcRequest, executeGetRequest, } from "../transport/rpc/rpc-client.js";
+import { executeStreamEvents } from "../transport/streaming/event-stream.js";
+import { INTERNAL_ERROR } from "../utils/common/errors.js";
+import { logError } from "../utils/logging/log.js";
 import { createMessageSendParams } from "../services/a2a/helpers/message-builder.js";
 /**
  * A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
@@ -16,6 +17,7 @@ export class A2AClient {
     customHeaders = {};
     fallbackPath;
     agentUrl;
+    mergePath;
     /**
      * Creates a new A2AClient instance.
      * @param baseUrl The base URL for the A2A server.
@@ -30,11 +32,12 @@ export class A2AClient {
      * const card = await client.agentCard();
      * console.log(card);
      */
-    constructor(baseUrl, headers = {}, fallbackPath) {
+    constructor(baseUrl, headers = {}, fallbackPath, mergePath = false) {
         this.baseUrl = typeof baseUrl === "string" ? new URL(baseUrl) : baseUrl;
         this.customHeaders = headers;
         this.fallbackPath = fallbackPath ?? "/agent-card";
         this.agentUrl = this.baseUrl;
+        this.mergePath = mergePath;
     }
     /**
      * Retrieves the AgentCard from the A2A server.
@@ -47,6 +50,9 @@ export class A2AClient {
         }
         // Standard location for agent cards
         const wellKnownUrl = new URL("/.well-known/agent-card.json", this.baseUrl);
+        if (this.mergePath) {
+            wellKnownUrl.pathname = this.baseUrl.pathname + wellKnownUrl.pathname;
+        }
         try {
             try {
                 if (!URL.canParse(wellKnownUrl)) {
@@ -60,6 +66,9 @@ export class A2AClient {
             }
             catch (error) {
                 const fallbackUrl = new URL(this.fallbackPath, this.baseUrl);
+                if (this.mergePath) {
+                    fallbackUrl.pathname = this.baseUrl.pathname + fallbackUrl.pathname;
+                }
                 const fallbackCard = await executeGetRequest(fallbackUrl, this.customHeaders, "agent card (fallback)");
                 if (!fallbackCard.name ||
                     fallbackCard.name === null ||

package/dist/server/express/errors.js

@@ -13,7 +13,7 @@ export const errorHandler = (err, req, res, _) => {
     if (res.headersSent) {
         headersSent = true;
     }
-    logError("errorHandler", JSON.stringify(err), err);
+    logError("errorHandler", JSON.stringify(err, null, 2), err);
     let reqId = null;
     try {
         if (req.body && typeof req.body === "object" && "id" in req.body) {

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

@@ -3,5 +3,5 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { NextFunction, Request, Response } from "express";
-import { A2AServiceInterface } from "../../types/index.js";
-export declare function jsonRPCMiddleware(service: A2AServiceInterface, req: Request, res: Response, next: NextFunction): Promise<void>;
+import { A2AServiceInterface, AgentCard } from "../../types/index.js";
+export declare function jsonRPCMiddleware(service: A2AServiceInterface, req: Request, res: Response, next: NextFunction, extendedAgentCard?: AgentCard): Promise<void>;

package/dist/server/express/middeware.js

@@ -2,7 +2,7 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { PUSH_NOTIFICATION_NOT_SUPPORTED, INVALID_REQUEST, INVALID_PARAMS, METHOD_NOT_FOUND, } from "../../utils/index.js";
+import { PUSH_NOTIFICATION_NOT_SUPPORTED, INVALID_REQUEST, INVALID_PARAMS, METHOD_NOT_FOUND, AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED, } from "../../utils/index.js";
 import { logError } from "../../utils/logging/index.js";
 const isValidMethod = (method) => {
     return (method &&
@@ -12,8 +12,15 @@ const isValidMethod = (method) => {
         typeof method === "string");
 };
 const checkParams = (params, method) => {
-    if (!params ||
-        (typeof params === "object" && Object.keys(params).length === 0)) {
+    if (!params || (typeof params !== "object" && !Array.isArray(params))) {
+        throw INVALID_PARAMS({
+            data: {
+                message: "Invalid params",
+                method,
+            },
+        });
+    }
+    else if (typeof params === "object" && Object.keys(params).length === 0) {
         throw INVALID_PARAMS({
             data: {
                 message: "No params provided",
@@ -22,10 +29,10 @@ const checkParams = (params, method) => {
         });
     }
 };
-export async function jsonRPCMiddleware(service, req, res, next) {
+export async function jsonRPCMiddleware(service, req, res, next, extendedAgentCard) {
     const { method, params, id, jsonrpc } = req.body;
-    // Validate JSON-RPC format
-    if (jsonrpc !== "2.0" || !id) {
+    if (jsonrpc !== "2.0" ||
+        (id && typeof id !== "string" && typeof id !== "number" && id !== null)) {
         res.json({
             jsonrpc: "2.0",
             id: id || null,
@@ -98,6 +105,19 @@ export async function jsonRPCMiddleware(service, req, res, next) {
                     },
                 });
             }
+            case "agent/getAuthenticatedExtendedCard": {
+                if (!extendedAgentCard ||
+                    service.agentCard.supportsAuthenticatedExtendedCard !== true) {
+                    throw AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED({
+                        data: {
+                            message: "Authenticated Extended Card is not configured",
+                            method,
+                        },
+                    });
+                }
+                result = extendedAgentCard;
+                break;
+            }
             default:
                 throw METHOD_NOT_FOUND({
                     data: {

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

@@ -3,12 +3,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import express from "express";
-import { Agent, FactoryParams as CreateAgentParams } from "../../types/index.js";
+import { Agent, AgentCard, FactoryParams as CreateAgentParams } from "../../types/index.js";
 import { CorsOptions } from "cors";
 export interface ServerParams {
     app?: express.Express;
     corsOptions?: CorsOptions;
     basePath?: string;
+    extendedAgentCard?: AgentCard;
 }
 export declare function createAgentServer(params: ServerParams & {
     agent: Agent | CreateAgentParams;
@@ -23,48 +24,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/server/express/server.js

@@ -3,11 +3,27 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import express from "express";
-import { INVALID_REQUEST } from "../../utils/index.js";
+import { INVALID_REQUEST, PARSE_ERROR } from "../../utils/index.js";
 import { createAgent } from "../../services/index.js";
 import cors from "cors";
 import { jsonRPCMiddleware } from "./middeware.js";
 import { errorHandler } from "./errors.js";
+function rpcParser(req, res, next) {
+    express.json()(req, res, (err) => {
+        if (err) {
+            if (err instanceof SyntaxError &&
+                "status" in err &&
+                err.status === 400 &&
+                "body" in err) {
+                return next(PARSE_ERROR({
+                    data: err.message,
+                }));
+            }
+            return next(err);
+        }
+        next();
+    });
+}
 function ensureAgent(agentOrParams) {
     if (agentOrParams &&
         typeof agentOrParams === "object" &&
@@ -40,9 +56,19 @@ function ensureAgent(agentOrParams) {
 export function createAgentServer(params) {
     const { app = express(), basePath = "/", agentCardPath = "/.well-known/agent-card.json", agent, } = params;
     const agentInstance = ensureAgent(agent);
-    app.use(express.json());
     app.use(cors(params.corsOptions));
-    app.get(agentCardPath, (_, res) => {
+    if (agentCardPath !== "/.well-known/agent-card.json") {
+        // mount at the root for compliance with RFC8615 standard
+        app.use("/.well-known/agent-card.json", (_, res) => {
+            res.json(agentInstance.agentCard);
+        });
+    }
+    app.use(agentCardPath, (_, res) => {
+        // mount at the custom path
+        res.json(agentInstance.agentCard);
+    });
+    // mount at the old agent card path for backwards compatibility
+    app.use("/.well-known/agent.json", (_, res) => {
         res.json(agentInstance.agentCard);
     });
     /**
@@ -51,10 +77,10 @@ export function createAgentServer(params) {
      * transport layer.
      */
     //a standard express middleware to handle json-rpc requests
-    app.post(basePath, express.json(), async (req, res, next) => {
+    app.post(basePath, rpcParser, async (req, res, next) => {
         const { jsonrpc } = req.body;
         if (jsonrpc === "2.0") {
-            return await jsonRPCMiddleware(agentInstance, req, res, next);
+            return await jsonRPCMiddleware(agentInstance, req, res, next, params.extendedAgentCard);
         }
         next(INVALID_REQUEST({ data: { message: "Invalid JSON-RPC request" } }));
     });
@@ -73,7 +99,7 @@ export function createAgentServer(params) {
           },
         })
       );
-     * we could also just use trpc directly or any other transport layer
+     * we could also use trpc directly or any other transport layer
      */
     return { app, agent: agentInstance };
 }

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

@@ -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

@@ -299,6 +299,7 @@ export function createAgentExecutor(stepsList) {
         }
         const taskStarted = SUBMITTED_UPDATE(taskId, contextId);
         yield taskStarted;
+        let finalState = TaskState.completed;
         const finalMessage = {
             taskId: taskId,
             contextId: contextId,
@@ -308,6 +309,10 @@ export function createAgentExecutor(stepsList) {
             parts: [],
         };
         for (const step of stepsList) {
+            if (context.isCancelled()) {
+                finalState = TaskState.canceled;
+                break;
+            }
             const ret = await step.step({ ...stepArgs });
             let parts = [];
             if (Array.isArray(ret)) {
@@ -350,7 +355,7 @@ export function createAgentExecutor(stepsList) {
             id: taskId,
             contextId: contextId,
             status: {
-                state: TaskState.completed,
+                state: finalState,
                 timestamp: new Date().toISOString(),
                 message: finalMessage,
             },

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, params.enforceParamValidation ?? false);
 }
 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,23 @@
+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 ?? [],
+            preferredTransport: agentCard.preferredTransport ?? "JSONRPC",
+        };
+    }
+    valueOf() {
+        return this.agentCard;
+    }
+}
+export function createAgentCard(agentCard) {
+    return new AgentCardBuilder(typeof agentCard === "string" ? { name: agentCard } : agentCard).valueOf();
+}

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

@@ -0,0 +1,2 @@
+import { Message, Task } from "../../../types/index.js";
+export declare function getLatestHistory(task: Task, length?: number): Message[];

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

@@ -0,0 +1,3 @@
+export function getLatestHistory(task, length) {
+    return length ? task.history?.slice(-length) ?? [] : task.history ?? [];
+}

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

@@ -1,3 +1,6 @@
 export * from "./part.js";
 export * from "./content.js";
 export * from "./message-builder.js";
+export * from "./agentcard-builder.js";
+export * from "./history.js";
+export * from "../../../utils/common/schema-validation.js";

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

@@ -1,3 +1,6 @@
 export * from "./part.js";
 export * from "./content.js";
 export * from "./message-builder.js";
+export * from "./agentcard-builder.js";
+export * from "./history.js";
+export * from "../../../utils/common/schema-validation.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;

package/dist/services/a2a/methods/get-task.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { TASK_NOT_FOUND } from "../../../utils/index.js";
+import { getLatestHistory } from "../helpers/index.js";
 export async function getTask(input, params) {
     const { service } = params;
     const state = await service.getState(input.id);
@@ -10,5 +11,6 @@ export async function getTask(input, params) {
     if (!task) {
         throw TASK_NOT_FOUND({ taskId: input.id });
     }
+    task.history = getLatestHistory(task, input.historyLength);
     return task;
 }