@artinet/sdk 0.5.18 → 0.6.0-preview.2

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

@@ -3,69 +3,27 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import express from "express";
-import { Agent, AgentCard, FactoryParams as CreateAgentParams } from "../../types/index.js";
+import { A2A } from "../../types/index.js";
+import { Agent } from "../../services/a2a/index.js";
+import { ServiceParams as CreateAgentParams } from "../../services/index.js";
 import { CorsOptions } from "cors";
 export interface ServerParams {
     app?: express.Express;
     corsOptions?: CorsOptions;
     basePath?: string;
-    extendedAgentCard?: AgentCard;
-}
-export declare function createAgentServer(params: ServerParams & {
+    port?: number;
+    /**
+     * Your agentCard must have supportsAuthenticatedExtendedCard set to true
+     */
+    extendedAgentCard?: A2A.AgentCard;
     agent: Agent | CreateAgentParams;
     agentCardPath?: string;
     register?: boolean;
-}): {
-    app: import("express-serve-static-core").Express;
-    agent: Agent<{
-        message: {
-            role: "user" | "agent";
-            kind: "message";
-            parts: ({
-                file: {
-                    bytes: string;
-                    name?: string | undefined;
-                    mimeType?: string | undefined;
-                    uri?: undefined;
-                } | {
-                    uri: string;
-                    name?: string | undefined;
-                    bytes?: undefined;
-                    mimeType?: string | undefined;
-                };
-                kind: "file";
-                metadata?: Record<string, unknown> | undefined;
-            } | {
-                text: string;
-                kind: "text";
-                metadata?: Record<string, unknown> | undefined;
-            } | {
-                data: Record<string, unknown>;
-                kind: "data";
-                metadata?: Record<string, unknown> | undefined;
-            })[];
-            messageId: string;
-            metadata?: Record<string, unknown> | undefined;
-            extensions?: string[] | undefined;
-            referenceTaskIds?: string[] | undefined;
-            taskId?: string | undefined;
-            contextId?: string | undefined;
-        };
-        metadata?: Record<string, unknown> | undefined;
-        configuration?: {
-            historyLength?: number | undefined;
-            pushNotificationConfig?: {
-                url: string;
-                id?: string | undefined;
-                token?: string | undefined;
-                authentication?: {
-                    schemes: string[];
-                    credentials?: string | undefined;
-                } | undefined;
-            } | undefined;
-            acceptedOutputModes?: string[] | undefined;
-            blocking?: boolean | undefined;
-        } | undefined;
-    }, import("../../types/index.js").TaskAndHistory, import("../../types/index.js").UpdateEvent>;
+}
+export declare function rpcParser(req: express.Request, res: express.Response, next: express.NextFunction): void;
+export declare function createAgentServer({ app, basePath, agentCardPath, agent, corsOptions, extendedAgentCard, register, port, }: ServerParams): {
+    app: express.Express;
+    agent: Agent;
+    start: (_port?: number) => import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
 };
 export type ExpressAgentServer = ReturnType<typeof createAgentServer>;

package/dist/server/express/server.js

@@ -3,62 +3,57 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import express from "express";
-import { INVALID_REQUEST, PARSE_ERROR } from "../../utils/index.js";
-import { createAgent } from "../../services/index.js";
+import { createAgent, Service, } from "../../services/index.js";
 import cors from "cors";
 import { jsonRPCMiddleware } from "./middeware.js";
 import { errorHandler } from "./errors.js";
-function rpcParser(req, res, next) {
+import { logger } from "../../config/index.js";
+import { A2AError } from "@a2a-js/sdk/server";
+import { formatJson } from "../../utils/common/utils.js";
+export function rpcParser(req, res, next) {
     express.json()(req, res, (err) => {
+        if (!req.body || typeof req.body !== "object") {
+            return next(A2AError.parseError(`Invalid request body: ${formatJson(req.body)}`));
+        }
         if (err) {
             if (err instanceof SyntaxError &&
                 "status" in err &&
                 err.status === 400 &&
                 "body" in err) {
-                return next(PARSE_ERROR({
-                    data: err.message,
-                }));
+                return next(A2AError.parseError(`Invalid request body: ${formatJson(req.body)}`));
             }
             return next(err);
         }
         next();
     });
 }
-function ensureAgent(agentOrParams) {
-    if (agentOrParams &&
-        typeof agentOrParams === "object" &&
-        "agentCard" in agentOrParams &&
-        typeof agentOrParams.agentCard === "object" &&
-        "sendMessage" in agentOrParams &&
-        typeof agentOrParams.sendMessage === "function" &&
-        "streamMessage" in agentOrParams &&
-        typeof agentOrParams.streamMessage === "function" &&
-        "addConnection" in agentOrParams &&
-        typeof agentOrParams.addConnection === "function" &&
-        "removeConnection" in agentOrParams &&
-        typeof agentOrParams.removeConnection === "function" &&
-        "getState" in agentOrParams &&
-        typeof agentOrParams.getState === "function" &&
-        "setState" in agentOrParams &&
-        typeof agentOrParams.setState === "function") {
-        return agentOrParams;
-    }
-    else if (agentOrParams &&
+const isParams = (agentOrParams) => {
+    return (agentOrParams &&
         typeof agentOrParams === "object" &&
         "engine" in agentOrParams &&
         typeof agentOrParams.engine === "function" &&
         "agentCard" in agentOrParams &&
-        typeof agentOrParams.agentCard === "object") {
+        typeof agentOrParams.agentCard === "object");
+};
+const ensureAgent = (agentOrParams) => {
+    if (agentOrParams instanceof Service) {
+        return agentOrParams;
+    }
+    else if (isParams(agentOrParams)) {
         return createAgent(agentOrParams);
     }
     throw new Error("invalid agent or params");
-}
-export function createAgentServer(params) {
-    const { app = express(), basePath = "/", agentCardPath = "/.well-known/agent-card.json", agent, } = params;
+};
+const registerAgent = async (agentCard) => {
+    logger.debug("registerAgent: not implemented", { agentCard });
+    return Promise.resolve(agentCard);
+};
+export function createAgentServer({ app = express(), basePath = "/", agentCardPath = "/.well-known/agent-card.json", agent, corsOptions, extendedAgentCard, register = false, port, }) {
     const agentInstance = ensureAgent(agent);
-    app.use(cors(params.corsOptions));
+    app.use(cors(corsOptions));
     if (agentCardPath !== "/.well-known/agent-card.json") {
         // mount at the root for compliance with RFC8615 standard
+        // todo: align with emerging multi-agent standards
         app.use("/.well-known/agent-card.json", (_, res) => {
             res.json(agentInstance.agentCard);
         });
@@ -79,10 +74,10 @@ export function createAgentServer(params) {
     //a standard express middleware to handle json-rpc requests
     app.post(basePath, rpcParser, async (req, res, next) => {
         const { jsonrpc } = req.body;
-        if (jsonrpc === "2.0") {
-            return await jsonRPCMiddleware(agentInstance, req, res, next, params.extendedAgentCard);
+        if (jsonrpc !== "2.0") {
+            return next(A2AError.invalidRequest("Invalid JSON-RPC request"));
         }
-        next(INVALID_REQUEST({ data: { message: "Invalid JSON-RPC request" } }));
+        return await jsonRPCMiddleware(agentInstance, req, res, next, extendedAgentCard);
     });
     app.use(errorHandler);
     /** this is an example of using trpc as express middleware
@@ -101,5 +96,21 @@ export function createAgentServer(params) {
       );
      * we could also use trpc directly or any other transport layer
      */
-    return { app, agent: agentInstance };
+    const start = (_port) => {
+        try {
+            const listenPort = _port ?? port;
+            const server = app.listen(listenPort, () => {
+                logger.info(`Agent server started on port ${listenPort}`);
+            });
+            if (register) {
+                registerAgent(agentInstance.agentCard);
+            }
+            return server;
+        }
+        catch (error) {
+            logger.error(`Failed to start agent server`, error);
+            throw error;
+        }
+    };
+    return { app, agent: agentInstance, start };
 }

package/dist/services/a2a/execute.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../types/index.js";
+/**
+ * Our universal executor for {@link A2A.Engine}.
+ * @param engine - {@link A2A.Engine} to execute.
+ * @param context - {@link A2A.Context} provided to the engine.
+ */
+export declare const execute: (engine: A2A.Engine, context: A2A.Context) => Promise<void>;

package/dist/services/a2a/execute.js

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Our universal executor for {@link A2A.Engine}.
+ * @param engine - {@link A2A.Engine} to execute.
+ * @param context - {@link A2A.Context} provided to the engine.
+ */
+export const execute = async (engine, context) => {
+    try {
+        if (context.publisher.onStart) {
+            await context.publisher.onStart(context);
+        }
+        for await (const update of engine(context)) {
+            if ((await context.isCancelled()) || context.abortSignal.aborted) {
+                await context.publisher.onCancel(update);
+                break;
+            }
+            await context.publisher.onUpdate(update);
+        }
+    }
+    catch (error) {
+        /* onError triggers completion internally */
+        await context.publisher.onError(error);
+        /* rethrow the error to be handled by the caller */
+        throw error;
+    }
+    finally {
+        await context.publisher.onComplete();
+    }
+};

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

@@ -2,131 +2,18 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-/**
- * @fileoverview A2A Context Factory Functions
- *
- * This module provides factory functions for creating A2A execution contexts
- * and command channels. It handles the composition of various context components
- * including command proxies, event managers, and cancellation mechanisms.
- *
- * @module A2AContextFactory
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { Command, ReceiveCommandProxyInterface, State, Update, Context, A2AServiceInterface, ContextManagerInterface, EventManagerOptions } from "../../../types/index.js";
-/**
- * Creates a command channel proxy for the given command.
- *
- * This function wraps a command in a proxy interface that provides
- * controlled access to command data and may add additional functionality
- * such as validation, logging, or transformation.
- *
- * @template TCommand - The command type, must extend Command
- * @param request - The command to wrap in a proxy
- * @returns Command proxy interface for the request
- *
- * @example
- * ```typescript
- * const command: MessageSendParams = {
- *   message: {
- *     content: 'Hello, world!',
- *     recipient: 'agent-123'
- *   }
- * };
- *
- * const commandProxy = createCommandChannel(command);
- * // Use commandProxy to access command data safely
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export declare function createCommandChannel<TCommand extends Command = Command>(request: TCommand): ReceiveCommandProxyInterface<TCommand>;
-/**
- * Creates a complete A2A execution context for command processing.
- *
- * This is the main factory function for creating execution contexts in the A2A
- * framework. It assembles all the necessary components including command proxy,
- * event management, cancellation handling, and state management into a cohesive
- * execution environment.
- *
- * The context serves as the primary execution environment passed to execution
- * engines and provides access to all the resources and capabilities needed
- * for command processing.
- *
- * @template TCommand - The command type, must extend Command
- * @template TState - The state type, must extend State
- * @template TUpdate - The update type, must extend Update
- *
- * @param request - The command to execute
- * @param service - The A2A service instance
- * @param contextManager - Manager for context lifecycle
- * @param abortSignal - Optional abort signal for cancellation
- * @param contextId - Optional context ID (generates UUID if not provided)
- * @param eventOverrides - Optional event manager configuration overrides
- * @returns Fully configured execution context
- *
- * @example
- * ```typescript
- * // Basic context creation
- * const context = createContext(
- *   messageCommand,
- *   a2aService,
- *   contextManager
- * );
- *
- * // Execute with the context
- * for await (const update of engine(context)) {
- *   console.log('Update:', update);
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Context creation with custom options
- * const abortController = new AbortController();
- * const customEventOptions = {
- *   onStart: async (ctx) => {
- *     console.log('Custom start handler');
- *     return initialState;
- *   }
- * };
- *
- * const context = createContext(
- *   command,
- *   service,
- *   contextManager,
- *   abortController.signal,
- *   'custom-context-id',
- *   customEventOptions
- * );
- *
- * // Cancel after 30 seconds
- * setTimeout(() => abortController.abort(), 30000);
- * ```
- *
- * @remarks
- * **Context Lifecycle:**
- * 1. Command proxy is created to wrap the incoming request
- * 2. Event manager is instantiated with service and override options
- * 3. Cancellation mechanisms are configured (abort signal + service cancellation)
- * 4. State accessor is bound to the event manager
- * 5. Complete context is registered with the context manager
- *
- * **Cancellation Handling:**
- * The context provides multiple cancellation mechanisms:
- * - AbortSignal for standard cancellation patterns
- * - Service-level cancellation tracking
- * - Combined cancellation status through isCancelled()
- *
- * **Event Management:**
- * The context includes an event manager that handles:
- * - Execution lifecycle events (start, update, complete, error)
- * - State transitions and persistence
- * - Custom event handling through overrides
- *
- * @public
- * @since 0.5.6
- */
-export declare function createContext<TCommand extends Command = Command, TState extends State = State, TUpdate extends Update = Update>(request: TCommand, service: A2AServiceInterface<TCommand, TState, TUpdate>, contextManager: ContextManagerInterface<TCommand, TState, TUpdate>, abortSignal?: AbortSignal, contextId?: string, eventOverrides?: EventManagerOptions<TCommand, TState, TUpdate>): Context<TCommand, TState, TUpdate>;
+import { A2A } from "../../../types/index.js";
+export declare function createBaseContext({ contextId, service, task, overrides, abortSignal, }: {
+    contextId: string;
+    service: A2A.Service;
+    task: A2A.Task;
+    overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>;
+    abortSignal?: AbortSignal;
+}): A2A.BaseContext;
+export declare function createContext({ baseContext, taskId, messenger, extensions, references, }: {
+    baseContext: A2A.BaseContext;
+    taskId: string;
+    messenger: A2A.MessageConsumerProxy;
+    extensions?: A2A.AgentExtension[];
+    references?: A2A.Task[];
+}): A2A.Context;

package/dist/services/a2a/factory/context.js

@@ -2,149 +2,43 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { createEventManager } from "./event.js";
-import { v4 as uuidv4 } from "uuid";
-import { CommandChannel } from "../../core/managers/command.js";
 /**
- * Creates a command channel proxy for the given command.
- *
- * This function wraps a command in a proxy interface that provides
- * controlled access to command data and may add additional functionality
- * such as validation, logging, or transformation.
- *
- * @template TCommand - The command type, must extend Command
- * @param request - The command to wrap in a proxy
- * @returns Command proxy interface for the request
- *
- * @example
- * ```typescript
- * const command: MessageSendParams = {
- *   message: {
- *     content: 'Hello, world!',
- *     recipient: 'agent-123'
- *   }
- * };
- *
- * const commandProxy = createCommandChannel(command);
- * // Use commandProxy to access command data safely
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export function createCommandChannel(request) {
-    return CommandChannel.create(request);
-}
-/**
- * Creates a complete A2A execution context for command processing.
- *
- * This is the main factory function for creating execution contexts in the A2A
- * framework. It assembles all the necessary components including command proxy,
- * event management, cancellation handling, and state management into a cohesive
- * execution environment.
- *
- * The context serves as the primary execution environment passed to execution
- * engines and provides access to all the resources and capabilities needed
- * for command processing.
- *
- * @template TCommand - The command type, must extend Command
- * @template TState - The state type, must extend State
- * @template TUpdate - The update type, must extend Update
+ * @fileoverview A2A Context Factory Functions
  *
- * @param request - The command to execute
- * @param service - The A2A service instance
- * @param contextManager - Manager for context lifecycle
- * @param abortSignal - Optional abort signal for cancellation
- * @param contextId - Optional context ID (generates UUID if not provided)
- * @param eventOverrides - Optional event manager configuration overrides
- * @returns Fully configured execution context
+ * This module provides factory functions for creating A2A execution contexts
+ * and command channels. It handles the composition of various context components
+ * including command proxies, event managers, and cancellation mechanisms.
  *
- * @example
- * ```typescript
- * // Basic context creation
- * const context = createContext(
- *   messageCommand,
- *   a2aService,
- *   contextManager
- * );
- *
- * // Execute with the context
- * for await (const update of engine(context)) {
- *   console.log('Update:', update);
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Context creation with custom options
- * const abortController = new AbortController();
- * const customEventOptions = {
- *   onStart: async (ctx) => {
- *     console.log('Custom start handler');
- *     return initialState;
- *   }
- * };
- *
- * const context = createContext(
- *   command,
- *   service,
- *   contextManager,
- *   abortController.signal,
- *   'custom-context-id',
- *   customEventOptions
- * );
- *
- * // Cancel after 30 seconds
- * setTimeout(() => abortController.abort(), 30000);
- * ```
- *
- * @remarks
- * **Context Lifecycle:**
- * 1. Command proxy is created to wrap the incoming request
- * 2. Event manager is instantiated with service and override options
- * 3. Cancellation mechanisms are configured (abort signal + service cancellation)
- * 4. State accessor is bound to the event manager
- * 5. Complete context is registered with the context manager
- *
- * **Cancellation Handling:**
- * The context provides multiple cancellation mechanisms:
- * - AbortSignal for standard cancellation patterns
- * - Service-level cancellation tracking
- * - Combined cancellation status through isCancelled()
- *
- * **Event Management:**
- * The context includes an event manager that handles:
- * - Execution lifecycle events (start, update, complete, error)
- * - State transitions and persistence
- * - Custom event handling through overrides
- *
- * @public
+ * @module A2AContextFactory
+ * @version 0.6.0-preview
  * @since 0.5.6
+ * @author The Artinet Project
  */
-export function createContext(request, service, contextManager, abortSignal = new AbortController().signal, contextId = uuidv4(), eventOverrides) {
-    // Note: Context reuse logic is currently disabled for testing
-    // Future versions may re-enable context reuse for performance optimization
-    //   if (contextId && contextId.length > 0) {
-    //     //disable for testing
-    //     const context = contextManager.getContext(contextId);
-    //     if (!context) {
-    //       console.error("createExecutionContext", contextId, "Context not found");
-    //       throw new TRPCError({
-    //         code: "NOT_FOUND",
-    //         message: "Context not found",
-    //       });
-    //     }
-    //     return context;
-    //   }
-    let newEventManager;
+import { createStateMachine } from "./state-machine.js";
+import { v4 as uuidv4 } from "uuid";
+export function createBaseContext({ contextId = uuidv4(), service, task, overrides, abortSignal = new AbortController().signal, }) {
+    const isCancelled = async () => (await service.cancellations.has(task.id)) || abortSignal.aborted;
+    const getState = async (args) => args ? await service.tasks.get(args) : task;
     const context = {
         contextId: contextId,
-        command: createCommandChannel(request),
-        events: (newEventManager = createEventManager(service, contextId, eventOverrides)),
-        signal: abortSignal,
-        isCancelled: () => abortSignal?.aborted || service.isCancelled(contextId),
-        State: () => newEventManager.getState(),
+        service: service,
+        publisher: createStateMachine({ contextId, service, task, overrides }),
+        isCancelled,
+        abortSignal: abortSignal,
+        getState,
+    };
+    return context;
+}
+export function createContext({ baseContext, taskId, messenger, extensions, references, }) {
+    const getTask = async () => baseContext.publisher.currentTask;
+    const context = {
+        ...baseContext,
+        taskId,
+        userMessage: messenger.message,
+        messages: messenger,
+        getTask,
+        extensions: extensions,
+        references: references,
     };
-    contextManager.setContext(contextId, context);
     return context;
 }

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

@@ -0,0 +1,6 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export declare function createHandler(methods?: Omit<Partial<A2A.RequestHandler>, "getAgentCard">): Omit<A2A.RequestHandler, "getAgentCard">;

package/dist/services/a2a/factory/handler.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getTask, cancelTask, sendMessage, sendMessageStream, subscribeToTask, } from "../handlers/index.js";
+export function createHandler(methods) {
+    return {
+        getTask: methods?.getTask ?? getTask,
+        cancelTask: methods?.cancelTask ?? cancelTask,
+        sendMessage: methods?.sendMessage ?? sendMessage,
+        streamMessage: methods?.streamMessage ?? sendMessageStream,
+        resubscribe: methods?.resubscribe ?? subscribeToTask,
+    };
+}

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

@@ -1,5 +1,3 @@
 export * from "./context.js";
-export * from "./builder.js";
-export * from "./event.js";
-export * from "./method.js";
+export * from "./state-machine.js";
 export * from "./service.js";

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

@@ -1,5 +1,3 @@
 export * from "./context.js";
-export * from "./builder.js";
-export * from "./event.js";
-export * from "./method.js";
+export * from "./state-machine.js";
 export * from "./service.js";

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

@@ -1,9 +1,22 @@
+import * as describe from "../../../create/agentcard-builder.js";
+import { A2A } from "../../../types/index.js";
+import { Service } from "../service.js";
+export interface ServiceParams {
+    agentCard: describe.AgentCardParams;
+    engine: A2A.Engine;
+    contexts?: A2A.Contexts;
+    streams?: A2A.Streams;
+    connections?: A2A.Connections;
+    cancellations?: A2A.Cancellations;
+    tasks?: A2A.Tasks;
+    methods?: Omit<A2A.RequestHandler, "getAgentCard">;
+    overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>;
+}
+export type CreateAgentParams = ServiceParams;
+export declare function createService(params: ServiceParams): Service;
+export declare const createAgent: typeof createService;
+export type AgentHandler = ReturnType<typeof createService>;
 /**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
+ * @deprecated Use AgentHandler instead
  */
-import { FactoryParams } from "../../../types/index.js";
-import { A2AService } from "../service.js";
-export declare function createService(params: FactoryParams): A2AService;
-export declare const createAgent: typeof createService;
-export type AgentImpl = ReturnType<typeof createAgent>;
+export type AgentImpl = AgentHandler;