@artinet/sdk 0.5.18 → 0.6.0-preview.2

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

@@ -1,365 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview A2A Agent Builder and Execution Engine Factory
- *
- * This module provides a fluent builder API for constructing A2A agents and
- * execution engines. It enables declarative definition of multi-step agent
- * workflows with type-safe step composition and automatic execution orchestration.
- *
- * @module A2ABuilder
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-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.
- *
- * The EngineBuilder provides a type-safe, fluent API for composing multi-step
- * agent workflows. It supports method chaining to build complex agent behaviors
- * from individual processing steps, with automatic type inference and validation.
- *
- * @template TCommand - The command type, defaults to MessageSendParams
- * @template TInboundArgs - The arguments type received from previous steps
- *
- * @example
- * ```typescript
- * const agent = EngineBuilder.create()
- *   .text(async ({ command }) => {
- *     return `Processing: ${command.message.content}`;
- *   })
- *   .data(async ({ args }) => {
- *     return { processed: true, timestamp: Date.now() };
- *   })
- *   .text(async ({ args }) => {
- *     return `Completed at ${new Date(args[0].timestamp)}`;
- *   })
- *   .createAgent({ agentCard: myAgentCard });
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export class EngineBuilder {
-    //@typescript-eslint/no-explicit-any
-    steps = [];
-    /**
-     * Protected constructor to enforce factory method usage.
-     *
-     * @param steps - Initial steps array
-     */
-    constructor(
-    //@typescript-eslint/no-explicit-any
-    steps = []) {
-        this.steps = steps;
-    }
-    /**
-     * Creates a new EngineBuilder instance.
-     *
-     * @template TCommand - The command type for the builder
-     * @template TInboundArgs - The initial arguments type
-     * @returns A new EngineBuilder instance
-     *
-     * @example
-     * ```typescript
-     * const builder = EngineBuilder.create<MyCommand, [string, number]>();
-     * ```
-     */
-    static create() {
-        return new EngineBuilder();
-    }
-    addStep(step) {
-        return new EngineBuilder([
-            ...this.steps,
-            step,
-        ]);
-    }
-    /**
-     * Adds a text processing step to the workflow.
-     *
-     * @template TPart - The text part type
-     * @template TForwardArgs - Arguments to forward to next step
-     * @template TOutput - The output type of the step
-     * @param step - The text step implementation
-     * @returns New builder instance with updated type parameters
-     *
-     * @example
-     * ```typescript
-     * builder.text(async ({ command, args }) => {
-     *   return `Hello, ${command.message.content}!`;
-     * });
-     * ```
-     */
-    text(step) {
-        return this.addStep({
-            step: step,
-            kind: "text",
-        });
-    }
-    /**
-     * Adds a file processing step to the workflow.
-     *
-     * @template TPart - The file part type
-     * @template TForwardArgs - Arguments to forward to next step
-     * @template TOutput - The output type of the step
-     * @param step - The file step implementation
-     * @returns New builder instance with updated type parameters
-     *
-     * @example
-     * ```typescript
-     * builder.file(async ({ command, args }) => {
-     *   return {
-     *     name: 'output.txt',
-     *     mimeType: 'text/plain',
-     *     bytes: Buffer.from(command.message.content)
-     *   };
-     * });
-     * ```
-     */
-    file(step) {
-        return this.addStep({
-            step: step,
-            kind: "file",
-        });
-    }
-    /**
-     * Adds a data processing step to the workflow.
-     *
-     * @template TPart - The data part type
-     * @template TForwardArgs - Arguments to forward to next step
-     * @template TOutput - The output type of the step
-     * @param step - The data step implementation
-     * @returns New builder instance with updated type parameters
-     *
-     * @example
-     * ```typescript
-     * builder.data(async ({ command, args }) => {
-     *   return {
-     *     analysis: analyzeText(command.message.content),
-     *     timestamp: Date.now()
-     *   };
-     * });
-     * ```
-     */
-    data(step) {
-        return this.addStep({
-            step: step,
-            kind: "data",
-        });
-    }
-    /**
-     * Creates a complete A2A agent using the built workflow.
-     *
-     * @param params - Agent factory parameters (excluding engine)
-     * @returns Configured A2A agent instance
-     *
-     * @example
-     * ```typescript
-     * const agent = builder.createAgent({
-     *   agentCard: {
-     *     id: 'my-agent',
-     *     name: 'Assistant Agent',
-     *     capabilities: ['text-processing']
-     *   }
-     * });
-     * ```
-     */
-    createAgent(params) {
-        return createAgent({
-            ...params,
-            engine: this.createAgentEngine(),
-        });
-    }
-    /**
-     * Creates an agent execution engine from the built workflow.
-     *
-     * @returns Agent execution engine function
-     *
-     * @example
-     * ```typescript
-     * const engine = builder.createAgentEngine();
-     * // Use engine with service execution
-     * ```
-     */
-    createAgentEngine() {
-        return createAgentExecutor(this.build());
-    }
-    /**
-     * Builds the step list for the workflow.
-     *
-     * @returns Array of workflow steps
-     * @throws Error if no steps have been added
-     *
-     * @example
-     * ```typescript
-     * const steps = builder.build();
-     * ```
-     */
-    build() {
-        if (this.steps.length === 0) {
-            throw new Error("No steps provided");
-        }
-        return this.steps;
-    }
-}
-/**
- * Convenience factory function for creating an agent builder with default parameters.
- *
- * @returns New EngineBuilder instance with MessageSendParams command type
- *
- * @example
- * ```typescript
- * const agent = AgentBuilder()
- *   .text(async ({ command }) => `Hello ${command.message.content}!`)
- *   .createAgent({ agentCard: myCard });
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export const AgentBuilder = () => EngineBuilder.create();
-const partToMessagePart = (kind, part) => {
-    switch (kind) {
-        case "text": {
-            return { kind: "text", text: part };
-        }
-        case "file": {
-            const filePart = part;
-            if (filePart.uri) {
-                return {
-                    kind: "file",
-                    file: {
-                        uri: filePart.uri,
-                        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 };
-        }
-        default:
-            throw new Error("Invalid part kind");
-    }
-};
-/**
- * Creates an agent execution engine from a list of workflow steps.
- *
- * This function transforms a list of step definitions into an executable
- * agent engine that processes commands through the defined workflow,
- * yielding updates as each step completes.
- *
- * @param stepsList - Array of workflow steps to execute
- * @returns Agent execution engine function
- *
- * @example
- * ```typescript
- * const steps = [
- *   { kind: 'text', step: greetingStep },
- *   { kind: 'data', step: analysisStep }
- * ];
- * const engine = createAgentExecutor(steps);
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export function createAgentExecutor(stepsList) {
-    return async function* (context) {
-        const content = getContent(context.command.message);
-        const stepArgs = {
-            command: context.command,
-            context: context,
-            content: content,
-            args: [],
-        };
-        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 = SUBMITTED_UPDATE(taskId, contextId);
-        yield taskStarted;
-        let finalState = TaskState.completed;
-        const finalMessage = {
-            taskId: taskId,
-            contextId: contextId,
-            messageId: uuidv4(),
-            kind: "message",
-            role: "agent",
-            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)) {
-                parts = ret.map((part) => partToMessagePart(step.kind, part));
-                const taskStatusUpdate = WORKING_UPDATE(taskId, contextId, {
-                    messageId: uuidv4(),
-                    kind: "message",
-                    role: "agent",
-                    parts: parts,
-                });
-                yield taskStatusUpdate;
-            }
-            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 = 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 = WORKING_UPDATE(taskId, contextId, {
-                    messageId: uuidv4(),
-                    kind: "message",
-                    role: "agent",
-                    parts: parts,
-                });
-                yield taskStatusUpdate;
-            }
-            finalMessage.parts.push(...parts);
-        }
-        const task = {
-            kind: "task",
-            id: taskId,
-            contextId: contextId,
-            status: {
-                state: finalState,
-                timestamp: new Date().toISOString(),
-                message: finalMessage,
-            },
-        };
-        yield task;
-    };
-}

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

@@ -1,58 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview A2A Event Manager Factory
- *
- * This module provides factory functions for creating A2A-specific event managers
- * that handle the complete lifecycle of agent-to-agent communication tasks.
- * It integrates with the core event management system while providing A2A-specific
- * behavior for state management, task tracking, and error handling.
- *
- * @module A2AEventFactory
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { EventManager } from "../../core/managers/event.js";
-import { Command, State, Update, A2AServiceInterface, EventManagerOptions } from "../../../types/index.js";
-/**
- * Creates an A2A-specific event manager with integrated task and state management.
- *
- * This factory function creates an event manager tailored for A2A operations,
- * providing comprehensive lifecycle management for agent-to-agent communication
- * tasks. It handles state persistence, task tracking, error scenarios, and
- * cancellation while integrating with the broader A2A service framework.
- *
- * @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 service - The A2A service instance for state and connection management
- * @param id - Optional context ID (generates UUID if not provided)
- * @param eventOverrides - Optional event handling overrides
- * @returns Configured EventManager instance for A2A operations
- *
- * @example
- * ```typescript
- * const eventManager = createEventManager(
- *   a2aService,
- *   'context-123',
- *   {
- *     onStart: async (context) => {
- *       console.log('A2A task starting');
- *       return await initializeA2AState(context);
- *     },
- *     onComplete: async (finalState) => {
- *       console.log('A2A task completed');
- *       await notifyCompletion(finalState);
- *     }
- *   }
- * );
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export declare function createEventManager<TCommand extends Command = Command, TState extends State = State, TUpdate extends Update = Update>(service: A2AServiceInterface<TCommand, TState, TUpdate>, id?: string, eventOverrides?: EventManagerOptions<TCommand, TState, TUpdate>): EventManager<TCommand, TState, TUpdate>;

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

@@ -1,177 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview A2A Event Manager Factory
- *
- * This module provides factory functions for creating A2A-specific event managers
- * that handle the complete lifecycle of agent-to-agent communication tasks.
- * It integrates with the core event management system while providing A2A-specific
- * behavior for state management, task tracking, and error handling.
- *
- * @module A2AEventFactory
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { EventManager } from "../../core/managers/event.js";
-import { TaskState, } from "../../../types/index.js";
-import { INTERNAL_ERROR, INVALID_PARAMS, CANCEL_UPDATE, FAILED_UPDATE, logError, } from "../../../utils/index.js";
-import { loadState, processUpdate } from "../state/index.js";
-import { v4 as uuidv4 } from "uuid";
-/**
- * Creates an A2A-specific event manager with integrated task and state management.
- *
- * This factory function creates an event manager tailored for A2A operations,
- * providing comprehensive lifecycle management for agent-to-agent communication
- * tasks. It handles state persistence, task tracking, error scenarios, and
- * cancellation while integrating with the broader A2A service framework.
- *
- * @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 service - The A2A service instance for state and connection management
- * @param id - Optional context ID (generates UUID if not provided)
- * @param eventOverrides - Optional event handling overrides
- * @returns Configured EventManager instance for A2A operations
- *
- * @example
- * ```typescript
- * const eventManager = createEventManager(
- *   a2aService,
- *   'context-123',
- *   {
- *     onStart: async (context) => {
- *       console.log('A2A task starting');
- *       return await initializeA2AState(context);
- *     },
- *     onComplete: async (finalState) => {
- *       console.log('A2A task completed');
- *       await notifyCompletion(finalState);
- *     }
- *   }
- * );
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export function createEventManager(service, id, eventOverrides) {
-    const contextId = id ?? uuidv4();
-    /**
-     * Task store implementation that bridges between event management and A2A service state management.
-     *
-     * This store provides the interface needed by the legacy update processing logic
-     * while integrating with the A2A service's state management capabilities.
-     */
-    const taskStore = {
-        save: async (data) => {
-            if (!data.task?.id) {
-                throw INTERNAL_ERROR({
-                    data: {
-                        message: "Task ID is required",
-                    },
-                });
-            }
-            service.setState(data.task.id, data);
-        },
-        load: async (taskId) => {
-            return (await service.getState(taskId).catch(() => null)) ?? null;
-        },
-    };
-    // Configure A2A-specific event handling options
-    const options = {
-        onStart: async (context) => {
-            const request = context.command;
-            if (!request || (!request.message && !("message" in request))) {
-                throw INVALID_PARAMS("No request detected");
-            }
-            let currentContextId = contextId;
-            if (request.message.contextId) {
-                currentContextId = request.message.contextId;
-            }
-            service.addConnection(currentContextId);
-            const currentState = await loadState(taskStore, request.message, request.metadata, request.message.taskId, currentContextId);
-            return currentState;
-        },
-        onCancel: async (current, update) => {
-            const localContextId = update.contextId ?? contextId;
-            const localTaskId = update.taskId ?? update.id;
-            service.addCancellation(localContextId);
-            const cancellation = CANCEL_UPDATE(localTaskId, localContextId);
-            const cancelUpdate = {
-                ...update,
-                ...cancellation,
-                status: {
-                    ...update.status,
-                    ...cancellation.status,
-                    state: TaskState.canceled,
-                },
-                final: true,
-            };
-            await processUpdate(taskStore, {
-                context: {
-                    contextId: localContextId,
-                    task: current.task,
-                    userMessage: current.task?.status?.message ?? {},
-                    isCancelled: () => service.isCancelled(localContextId),
-                    history: [], //deprecating history
-                },
-                current: current,
-                update: cancelUpdate,
-            });
-        },
-        onUpdate: async (current, update) => {
-            if (service.isCancelled(contextId)) {
-                return current;
-            }
-            try {
-                const currentState = (await processUpdate(taskStore, {
-                    context: {
-                        contextId: contextId,
-                        task: current.task,
-                        userMessage: current.task?.status?.message ?? {},
-                        isCancelled: () => service.isCancelled(contextId),
-                        history: [], //deprecating history
-                    },
-                    current: current,
-                    update: update,
-                }));
-                return currentState;
-            }
-            catch (error) {
-                logError(`onUpdate[${contextId}]:`, "error detected", error, update);
-                throw error;
-            }
-        },
-        onError: async (current, error) => {
-            logError(`onError[${contextId}]`, "error detected", error, current);
-            if (!current ||
-                (!current.task?.contextId && !current?.contextId)) {
-                return;
-            }
-            const failedUpdate = FAILED_UPDATE(current.task?.id, current.task?.contextId ?? contextId, "failed-update", error instanceof Error ? error.message : String(error));
-            await processUpdate(taskStore, {
-                context: {
-                    contextId: current.task?.contextId ?? contextId,
-                    task: current.task,
-                    userMessage: current.task?.status?.message ?? {},
-                    isCancelled: () => service.isCancelled(contextId),
-                    history: [], //deprecating history
-                },
-                current: current,
-                update: failedUpdate,
-            });
-        },
-        onComplete: async () => {
-            service.removeCancellation(contextId);
-            service.removeConnection(contextId);
-        },
-    };
-    return new EventManager(contextId, {
-        ...options,
-        ...eventOverrides, // Override options take precedence over defaults
-    });
-}

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

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

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

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

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

@@ -1,7 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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/message-builder.d.ts

@@ -1,12 +0,0 @@
-import { MessageSendParams, Message as MessageType, MessageSendConfiguration } from "../../../types/index.js";
-export declare class MessageBuilder {
-    message: MessageType;
-    constructor(message?: Partial<MessageType>);
-    valueOf(): MessageType;
-}
-export declare class MessageSendConfigurationBuilder {
-    configuration: MessageSendConfiguration;
-    constructor(configuration?: Partial<MessageSendConfiguration> | null);
-    valueOf(): MessageSendConfiguration;
-}
-export declare const createMessageSendParams: (messageSendParams: Partial<MessageSendParams> | string) => MessageSendParams;