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

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();
-}

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

@@ -1,17 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { A2A } from "../../../types/index.js";
-export declare class MessageBuilder {
-    message: A2A.Message;
-    constructor(message?: Partial<A2A.Message>);
-    valueOf(): A2A.Message;
-}
-export declare const MESSAGE: (message?: Partial<A2A.Message>) => A2A.Message;
-export declare class MessageSendConfigurationBuilder {
-    configuration: A2A.MessageSendConfiguration;
-    constructor(configuration?: Partial<A2A.MessageSendConfiguration> | null);
-    valueOf(): A2A.MessageSendConfiguration;
-}
-export declare const createMessageSendParams: (messageSendParams: Partial<A2A.MessageSendParams> | string) => A2A.MessageSendParams;

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

@@ -1,66 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { v4 as uuidv4 } from "uuid";
-export class MessageBuilder {
-    message = {
-        role: "user",
-        parts: [],
-        metadata: undefined,
-        extensions: undefined,
-        referenceTaskIds: undefined,
-        messageId: uuidv4(),
-        taskId: undefined,
-        contextId: undefined,
-        kind: "message",
-    };
-    constructor(message = {}) {
-        this.message.role = message.role ?? this.message.role;
-        this.message.parts = message.parts ?? this.message.parts;
-        this.message.metadata = message.metadata ?? this.message.metadata;
-        this.message.extensions = message.extensions ?? this.message.extensions;
-        this.message.referenceTaskIds =
-            message.referenceTaskIds ?? this.message.referenceTaskIds;
-        this.message.messageId = message.messageId ?? this.message.messageId;
-        this.message.taskId = message.taskId ?? this.message.taskId;
-        this.message.contextId = message.contextId ?? this.message.contextId;
-    }
-    valueOf() {
-        return this.message;
-    }
-}
-export const MESSAGE = (message = {}) => new MessageBuilder(message).message;
-export class MessageSendConfigurationBuilder {
-    configuration = {
-        acceptedOutputModes: undefined,
-        historyLength: undefined,
-        pushNotificationConfig: undefined,
-        blocking: undefined,
-    };
-    constructor(configuration = {}) {
-        this.configuration.acceptedOutputModes =
-            configuration?.acceptedOutputModes ??
-                this.configuration.acceptedOutputModes;
-        this.configuration.historyLength =
-            configuration?.historyLength ?? this.configuration.historyLength;
-        this.configuration.pushNotificationConfig =
-            configuration?.pushNotificationConfig ??
-                this.configuration.pushNotificationConfig;
-        this.configuration.blocking =
-            configuration?.blocking ?? this.configuration.blocking;
-    }
-    valueOf() {
-        return this.configuration;
-    }
-}
-export const createMessageSendParams = (messageSendParams) => {
-    const isString = typeof messageSendParams === "string";
-    return {
-        message: new MessageBuilder(isString
-            ? { parts: [{ text: messageSendParams, kind: "text" }] }
-            : messageSendParams.message).valueOf(),
-        configuration: new MessageSendConfigurationBuilder(isString ? undefined : messageSendParams.configuration).valueOf(),
-        metadata: isString ? undefined : messageSendParams.metadata,
-    };
-};

package/dist/types/a2a/builder.d.ts

@@ -1,43 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { MessageSendParams, DataPart, FilePart, TextPart } from "@artinet/types/a2a";
-import { Context } from "./a2a.js";
-/**
- * Restricting to command for now, but could be extended to other types of commands in the future.
- * When we shift to CoreCommand, move this into core.
- */
-export interface StepArgs {
-    message: MessageSendParams;
-    context: Context;
-    skip: () => Promise<void> | void;
-}
-export type BaseArgs = Record<string, unknown>;
-export type EmptyArgs = Record<string, never>;
-export type StepParams<TInboundArgs extends BaseArgs = EmptyArgs> = StepArgs & Partial<{
-    content: string;
-    args: TInboundArgs;
-}>;
-export type PartContent = DataPart["data"] | FilePart["file"] | TextPart["text"];
-export type StepOutput<TPart extends PartContent> = {
-    parts: Array<TPart> | TPart;
-};
-export type StepOutputWithForwardArgs<TPart extends PartContent, TForwardArgs extends BaseArgs = EmptyArgs> = StepOutput<TPart> & {
-    args: TForwardArgs;
-};
-export type OutputType<TPart extends PartContent, TForwardArgs extends BaseArgs = EmptyArgs> = StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart;
-export type Step<TPart extends PartContent = TextPart["text"], TInboundArgs extends BaseArgs = EmptyArgs, TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<TPart, TForwardArgs> = OutputType<TPart, TForwardArgs>> = (params: StepParams<TInboundArgs>) => Promise<TOutput> | TOutput;
-export type StepWithKind<TPart extends PartContent = TextPart["text"], TInboundArgs extends BaseArgs = EmptyArgs, TForwardArgs extends BaseArgs = EmptyArgs, TOutput extends OutputType<TPart, TForwardArgs> = OutputType<TPart, TForwardArgs>, TKind extends "text" | "file" | "data" = "text"> = {
-    step: Step<TPart, TInboundArgs, TForwardArgs, TOutput>;
-    kind: TKind;
-};
-export type OutArgsOf<O> = O extends StepOutputWithForwardArgs<any, infer A> ? A : EmptyArgs;
-export interface StepBuilder<TInboundArgs extends BaseArgs = EmptyArgs> {
-    /**
-     * Add a step to the builder.
-     * @param step - The step to add.
-     * @returns A new builder with the step added.
-     */
-    addStep<TPart extends PartContent = 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>): StepBuilder<OutArgsOf<TOutput>>;
-}

package/dist/types/a2a/builder.js

@@ -1,5 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export {};