@artinet/sdk 0.5.5 → 0.5.7

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

@@ -0,0 +1,352 @@
+/**
+ * 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 { StepBuilder, Step, StepOutput, StepOutputWithForwardArgs, MessageSendParams, TextPart, DataPart, FilePart, AgentEngine, StepWithKind, FactoryParams } from "../../../types/index.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 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, 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<TCommand extends MessageSendParams = MessageSendParams, TPart extends TextPart["text"] = TextPart["text"], TInboundArgs extends readonly unknown[] = [], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>> = Step<TCommand, TPart, 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 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<TCommand extends MessageSendParams = MessageSendParams, TPart extends FilePart["file"] = FilePart["file"], TInboundArgs extends readonly unknown[] = [], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>> = Step<TCommand, TPart, 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 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<TCommand extends MessageSendParams = MessageSendParams, TPart extends DataPart["data"] = DataPart["data"], TInboundArgs extends readonly unknown[] = [], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>> = Step<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput>;
+/**
+ * Utility type to extract forward arguments from step output.
+ *
+ * This helper type extracts the forward arguments type from a step output,
+ * enabling proper type chaining between workflow steps.
+ *
+ * @template O - The output type to extract arguments from
+ * @internal
+ */
+type OutArgsOf<O> = O extends StepOutputWithForwardArgs<any, infer A> ? A : [];
+/**
+ * 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<TCommand extends MessageSendParams = MessageSendParams, TInboundArgs extends readonly unknown[] = []> implements StepBuilder<TCommand, TInboundArgs> {
+    private steps;
+    /**
+     * Private constructor to enforce factory method usage.
+     *
+     * @param steps - Initial steps array
+     */
+    private constructor();
+    /**
+     * 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<TCommand extends MessageSendParams = MessageSendParams, TInboundArgs extends readonly unknown[] = []>(): EngineBuilder<TCommand, TInboundArgs>;
+    addStep<TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"] = TextPart["text"], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>, TKind extends "text" | "file" | "data" = "text">(step: StepWithKind<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput, TKind>): EngineBuilder<TCommand, 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<TPart extends TextPart["text"] = TextPart["text"], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>>(step: textStep<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput>): EngineBuilder<TCommand, 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<TPart extends FilePart["file"] = FilePart["file"], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>>(step: fileStep<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput>): EngineBuilder<TCommand, 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<TPart extends DataPart["data"] = DataPart["data"], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>>(step: dataStep<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput>): EngineBuilder<TCommand, 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<FactoryParams, "engine">): import("../service.js").A2AService;
+    /**
+     * 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(): AgentEngine;
+    /**
+     * 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<TCommand, 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<{
+    message: {
+        kind: "message";
+        parts: ({
+            file: {
+                bytes: string;
+                name?: string | undefined;
+                mimeType?: string | undefined;
+                uri?: undefined;
+            } | {
+                uri: string;
+                name?: string | undefined;
+                mimeType?: string | undefined;
+                bytes?: 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;
+        })[];
+        role: "user" | "agent";
+        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;
+}, []>;
+/**
+ * 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[]): AgentEngine;
+export {};
+//# sourceMappingURL=builder.d.ts.map

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

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

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

@@ -0,0 +1,133 @@
+/**
+ * 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>;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/factory/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,OAAO,EACP,4BAA4B,EAC5B,KAAK,EACL,MAAM,EACN,OAAO,EACP,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EAEpB,gCAAyB;AAK1B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,EACrE,OAAO,EAAE,QAAQ,GAChB,4BAA4B,CAAC,QAAQ,CAAC,CAExC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,SAAS,OAAO,GAAG,OAAO,EAClC,MAAM,SAAS,KAAK,GAAG,KAAK,EAC5B,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EACvD,cAAc,EAAE,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAClE,WAAW,GAAE,WAA0C,EACvD,SAAS,GAAE,MAAiB,EAC5B,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,GAC9D,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CA8BpC"}

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

@@ -0,0 +1,59 @@
+/**
+ * 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>;
+//# sourceMappingURL=event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/factory/event.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,qCAA0C;AACjE,OAAO,EACL,OAAO,EACP,KAAK,EACL,MAAM,EACN,mBAAmB,EACnB,mBAAmB,EAOpB,gCAAyB;AAW1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,SAAS,OAAO,GAAG,OAAO,EAClC,MAAM,SAAS,KAAK,GAAG,KAAK,EAC5B,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EACvD,EAAE,CAAC,EAAE,MAAM,EACX,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,GAC9D,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CA+JzC"}

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

@@ -0,0 +1,6 @@
+export * from "./context.js";
+export * from "./builder.js";
+export * from "./event.js";
+export * from "./method.js";
+export * from "./service.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/factory/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * 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;
+//# sourceMappingURL=method.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/factory/method.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,gCAAyB;AASjD,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAQ7E"}

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

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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>;
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/factory/service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAA0B,gCAAyB;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAS3C,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,cAWlD;AACD,eAAO,MAAM,WAAW,sBAAgB,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/types/services/a2a/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./part.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/services/a2a/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/types/services/a2a/helpers/part.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part, TextPart, FilePart, DataPart, Message } from "../../../types/schemas/a2a/index.js";
+/**
+ * Extracts and aggregates the text, file, and data contents from an array of Part objects.
+ *
+ * @param parts - An array of Part objects, which may include text, file, or data kinds.
+ * @returns An object containing:
+ *   - text: Concatenated string of all text parts.
+ *   - file: Array of file contents from file parts.
+ *   - data: Array of data contents from data parts.
+ *
+ * @remarks
+ * This utility is used to normalize and access the payloads of message parts
+ * in a structured way for downstream processing.
+ */
+export declare const getParts: (parts: Part[]) => {
+    text: TextPart["text"];
+    file: FilePart["file"][];
+    data: DataPart["data"][];
+};
+/**
+ * Extracts and aggregates the text, file, and data payloads from a Message's parts array.
+ *
+ * @param message - The Message object containing an array of Part objects (text, file, or data).
+ * @returns An object with the following properties:
+ *   - text: A single string containing the concatenated text from all text parts.
+ *   - file: An array of file payloads from all file parts.
+ *   - data: An array of data payloads from all data parts.
+ *
+ * @remarks
+ * This utility function is intended to simplify downstream processing by normalizing
+ * the payloads of a Message's parts into a structured object. It is especially useful
+ * when handling user input or agent responses that may include multiple content types.
+ *
+ * @example
+ * const payload = getPayload(message);
+ * console.log(payload.text); // "Hello world"
+ * console.log(payload.file); // [<file1>, <file2>]
+ * console.log(payload.data); // [<data1>, <data2>]
+ */
+export declare const getPayload: (message: Message) => {
+    text: TextPart["text"];
+    file: FilePart["file"][];
+    data: DataPart["data"][];
+};
+//# sourceMappingURL=part.d.ts.map

package/dist/types/services/a2a/helpers/part.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"part.d.ts","sourceRoot":"","sources":["../../../../../src/services/a2a/helpers/part.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,OAAO,EACR,4CAAqC;AACtC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GACnB,OAAO,IAAI,EAAE,KACZ;IACD,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;CAU1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU,GACrB,SAAS,OAAO,KACf;IACD,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;CAG1B,CAAC"}

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

@@ -1,3 +1,7 @@
-export * from "./repository.js";
+export * from "./factory/index.js";
+export * from "./helpers/index.js";
+export * from "./managers/index.js";
+export * from "./methods/index.js";
+export * from "./state/index.js";
 export * from "./service.js";
 //# sourceMappingURL=index.d.ts.map