@artinet/sdk 0.6.0-preview.1 → 0.6.0-preview.3

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

@@ -1,292 +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.6.0-preview
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { StepBuilder, Step, A2A, StepWithKind, OutputType, BaseArgs, EmptyArgs, OutArgsOf, PartContent } from "../../../types/index.js";
-import { ServiceParams } from "./service.js";
-/**
- * Type alias for text-based workflow steps.
- *
- * This type represents a step that processes or generates text content
- * within an agent workflow. Text steps are the most common type of step
- * and are used for message processing, content generation, and text-based
- * decision making.
- *
- * @template TCommand - The command type, defaults to MessageSendParams
- * @template TPart - The text part type, defaults to A2A.TextPart["text"]
- * @template TInboundArgs - Arguments received from previous step
- * @template TForwardArgs - Arguments passed to next step
- * @template TOutput - The output type of the step
- *
- * @example
- * ```typescript
- * const greetingStep: textStep = async ({ command, context, content, args }) => {
- *   const userName = command.message.metadata?.userName || 'there';
- *   return `Hello, ${userName}! How can I help you today?`;
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export type textStep<TInboundArgs extends BaseArgs = EmptyArgs, TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.TextPart["text"], TForwardArgs> = OutputType<A2A.TextPart["text"], TForwardArgs>> = Step<A2A.TextPart["text"], TInboundArgs, TForwardArgs, TOutput>;
-/**
- * Type alias for file-based workflow steps.
- *
- * This type represents a step that processes or generates file content
- * within an agent workflow. File steps handle document processing,
- * file generation, and file-based data operations.
- *
- * @template TCommand - The command type, defaults to MessageSendParams
- * @template TPart - The file part type, defaults to A2A.FilePart["file"]
- * @template TInboundArgs - Arguments received from previous step
- * @template TForwardArgs - Arguments passed to next step
- * @template TOutput - The output type of the step
- *
- * @example
- * ```typescript
- * const documentStep: fileStep = async ({ command, context, args }) => {
- *   const content = generateDocument(command.message.content);
- *   return {
- *     name: 'report.pdf',
- *     mimeType: 'application/pdf',
- *     bytes: content
- *   };
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export type fileStep<TInboundArgs extends BaseArgs = EmptyArgs, TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.FilePart["file"], TForwardArgs> = OutputType<A2A.FilePart["file"], TForwardArgs>> = Step<A2A.FilePart["file"], TInboundArgs, TForwardArgs, TOutput>;
-/**
- * Type alias for data-based workflow steps.
- *
- * This type represents a step that processes or generates structured data
- * within an agent workflow. Data steps handle JSON processing, API responses,
- * and structured data transformations.
- *
- * @template TCommand - The command type, defaults to MessageSendParams
- * @template TPart - The data part type, defaults to A2A.DataPart["data"]
- * @template TInboundArgs - Arguments received from previous step
- * @template TForwardArgs - Arguments passed to next step
- * @template TOutput - The output type of the step
- *
- * @example
- * ```typescript
- * const analyzeStep: dataStep = async ({ command, context, args }) => {
- *   const analysis = await analyzeMessage(command.message.content);
- *   return {
- *     sentiment: analysis.sentiment,
- *     entities: analysis.entities,
- *     confidence: analysis.confidence
- *   };
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export type dataStep<TInboundArgs extends BaseArgs = EmptyArgs, TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.DataPart["data"], TForwardArgs> = OutputType<A2A.DataPart["data"], TForwardArgs>> = Step<A2A.DataPart["data"], TInboundArgs, TForwardArgs, TOutput>;
-/**
- * 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 declare class EngineBuilder<TInboundArgs extends BaseArgs = EmptyArgs> implements StepBuilder<TInboundArgs> {
-    private steps;
-    /**
-     * Protected constructor to enforce factory method usage.
-     *
-     * @param steps - Initial steps array
-     */
-    protected constructor(steps?: Array<StepWithKind<any, any, any, any, any>>);
-    /**
-     * 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<TInboundArgs extends BaseArgs = EmptyArgs>(): EngineBuilder<TInboundArgs>;
-    addStep<TPart extends PartContent = A2A.TextPart["text"], TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<TPart, TForwardArgs> = OutputType<TPart, TForwardArgs>, TKind extends "text" | "file" | "data" = "text">(step: StepWithKind<TPart, TInboundArgs, TForwardArgs, TOutput, TKind>): EngineBuilder<OutArgsOf<TOutput>>;
-    /**
-     * 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<TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.TextPart["text"], TForwardArgs> = OutputType<A2A.TextPart["text"], TForwardArgs>>(step: textStep<TInboundArgs, TForwardArgs, TOutput> | string): EngineBuilder<OutArgsOf<TOutput>>;
-    /**
-     * 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<TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.FilePart["file"], TForwardArgs> = OutputType<A2A.FilePart["file"], TForwardArgs>>(step: fileStep<TInboundArgs, TForwardArgs, TOutput>): EngineBuilder<OutArgsOf<TOutput>>;
-    /**
-     * 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<TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<A2A.DataPart["data"], TForwardArgs> = OutputType<A2A.DataPart["data"], TForwardArgs>>(step: dataStep<TInboundArgs, TForwardArgs, TOutput>): EngineBuilder<OutArgsOf<TOutput>>;
-    /**
-     * 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: Omit<ServiceParams, "engine">): import("../service.js").Service;
-    /**
-     * 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(): A2A.Engine;
-    /**
-     * 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(): StepWithKind<any, any, any, any, any>[];
-}
-/**
- * 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 declare const AgentBuilder: () => EngineBuilder<EmptyArgs>;
-/**
- * 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 declare function createAgentExecutor(stepsList: StepWithKind[]): A2A.Engine;

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

@@ -1,370 +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.6.0-preview
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { A2A, } 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: typeof step === "string" ? () => 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.userMessage);
-        let _skipStep = false;
-        const stepArgs = {
-            message: context.messages,
-            context: context,
-            content: content,
-            skip: () => {
-                _skipStep = true;
-                return;
-            },
-        };
-        const contextId = context.contextId;
-        const taskId = context.taskId;
-        if (!contextId || !taskId) {
-            throw new Error("Context ID and task ID are required");
-        }
-        const taskStarted = SUBMITTED_UPDATE(taskId, contextId);
-        yield taskStarted;
-        let finalState = A2A.TaskState.completed;
-        const finalMessage = {
-            taskId: taskId,
-            contextId: contextId,
-            messageId: uuidv4(),
-            kind: "message",
-            role: "agent",
-            parts: [],
-        };
-        for (const step of stepsList) {
-            if (await context.isCancelled()) {
-                finalState = A2A.TaskState.canceled;
-                break;
-            }
-            const ret = await step.step({ ...stepArgs });
-            if (_skipStep) {
-                _skipStep = false;
-                continue;
-            }
-            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" in ret) {
-                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/helpers/agentcard-builder.d.ts

@@ -1,11 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { A2A } from "../../../types/index.js";
-export declare class AgentCardBuilder {
-    agentCard: A2A.AgentCard;
-    constructor(agentCard: Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>);
-    valueOf(): A2A.AgentCard;
-}
-export declare function createAgentCard(agentCard: A2A.AgentCardParams): A2A.AgentCard;

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

@@ -1,27 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.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();
-}