@artinet/sdk 0.5.4 → 0.5.6

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

@@ -0,0 +1,392 @@
+/**
+ * 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 1.0.0
+ * @since 0.5.6
+ * @author The Artinet Project
+ */
+import { TaskState, } from "../../../types/index.js";
+import { createAgent } from "./service.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 = [];
+    /**
+     * Private 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;
+            return filePart.uri
+                ? {
+                    kind: "file",
+                    file: {
+                        uri: filePart.uri,
+                        name: filePart.name,
+                        mimeType: filePart.mimeType,
+                    },
+                }
+                : {
+                    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 stepArgs = {
+            command: context.command,
+            context: context,
+            args: [],
+        };
+        const contextId = context.command.message.contextId;
+        const taskId = context.command.message.taskId;
+        const messageId = context.command.message.messageId;
+        if (!contextId || !taskId) {
+            throw new Error("Context ID and task ID are required");
+        }
+        const taskStarted = {
+            taskId: taskId,
+            contextId: contextId,
+            kind: "status-update",
+            status: {
+                state: TaskState.submitted,
+                timestamp: new Date().toISOString(),
+            },
+            final: false,
+        };
+        yield taskStarted;
+        const finalMessage = {
+            taskId: taskId,
+            contextId: contextId,
+            messageId: messageId,
+            kind: "message",
+            role: "agent",
+            parts: [],
+        };
+        for (const step of stepsList) {
+            const ret = await step.step({ ...stepArgs });
+            let parts = [];
+            if (Array.isArray(ret)) {
+                parts = ret.map((part) => partToMessagePart(step.kind, part));
+                const taskStatusUpdate = {
+                    taskId: taskId,
+                    contextId: contextId,
+                    kind: "status-update",
+                    status: {
+                        state: TaskState.working,
+                        timestamp: new Date().toISOString(),
+                        message: {
+                            messageId: messageId,
+                            kind: "message",
+                            role: "agent",
+                            parts: parts,
+                        },
+                    },
+                    final: false,
+                };
+                yield taskStatusUpdate;
+            }
+            else if (typeof ret === "object") {
+                parts = Array.isArray(ret.parts)
+                    ? ret.parts.map((part) => partToMessagePart(step.kind, part))
+                    : [partToMessagePart(step.kind, ret.parts)];
+                const taskStatusUpdate = {
+                    taskId: taskId,
+                    contextId: contextId,
+                    kind: "status-update",
+                    status: {
+                        state: TaskState.working,
+                        timestamp: new Date().toISOString(),
+                        message: {
+                            messageId: messageId,
+                            kind: "message",
+                            role: "agent",
+                            parts: parts,
+                        },
+                    },
+                    final: false,
+                };
+                yield taskStatusUpdate;
+                stepArgs.args = ret.args;
+            }
+            else {
+                parts = [partToMessagePart(step.kind, ret)];
+                const taskStatusUpdate = {
+                    taskId: taskId,
+                    contextId: contextId,
+                    kind: "status-update",
+                    status: {
+                        state: TaskState.working,
+                        timestamp: new Date().toISOString(),
+                        message: {
+                            messageId: messageId,
+                            kind: "message",
+                            role: "agent",
+                            parts: parts,
+                        },
+                    },
+                    final: false,
+                };
+                yield taskStatusUpdate;
+            }
+            finalMessage.parts.push(...parts);
+        }
+        const task = {
+            kind: "task",
+            id: taskId,
+            contextId: contextId,
+            status: {
+                state: TaskState.completed,
+                timestamp: new Date().toISOString(),
+                message: finalMessage,
+            },
+        };
+        yield task;
+    };
+}
+//# sourceMappingURL=builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../../../src/services/a2a/factory/builder.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,151 @@
+/**
+ * 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
+ *
+ * @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 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;
+    const context = {
+        contextId: contextId,
+        command: createCommandChannel(request),
+        events: (newEventManager = createEventManager(service, contextId, eventOverrides)),
+        signal: abortSignal,
+        isCancelled: () => abortSignal?.aborted || service.isCancelled(contextId),
+        State: () => newEventManager.getState(),
+    };
+    contextManager.setContext(contextId, context);
+    return context;
+}
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../src/services/a2a/factory/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAiB;IAEjB,OAAO,cAAc,CAAC,MAAM,CAAW,OAAO,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,MAAM,UAAU,aAAa,CAK3B,OAAiB,EACjB,OAAuD,EACvD,cAAkE,EAClE,cAA2B,IAAI,eAAe,EAAE,CAAC,MAAM,EACvD,YAAoB,MAAM,EAAE,EAC5B,cAA+D;IAE/D,8DAA8D;IAC9D,2EAA2E;IAC3E,6CAA6C;IAC7C,4BAA4B;IAC5B,4DAA4D;IAC5D,sBAAsB;IACtB,iFAAiF;IACjF,8BAA8B;IAC9B,6BAA6B;IAC7B,wCAAwC;IACxC,YAAY;IACZ,QAAQ;IACR,sBAAsB;IACtB,MAAM;IACN,IAAI,eAAiE,CAAC;IACtE,MAAM,OAAO,GAAuC;QAClD,SAAS,EAAE,SAAS;QACpB,OAAO,EAAE,oBAAoB,CAAW,OAAO,CAAC;QAChD,MAAM,EAAE,CAAC,eAAe,GAAG,kBAAkB,CAC3C,OAAO,EACP,SAAS,EACT,cAAc,CACf,CAAC;QACF,MAAM,EAAE,WAAW;QACnB,WAAW,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC;QACzE,KAAK,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,EAAE;KACxC,CAAC;IACF,cAAc,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC"}