@artinet/sdk 0.5.18 → 0.6.0-preview.2

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

@@ -1,413 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview A2A Service Interface Definitions
- *
- * This module defines interfaces for Agent-to-Agent (A2A) service implementations,
- * including factory parameters, method options, and the main service interface.
- * It extends the core service framework with A2A-specific functionality for
- * agent communication, task management, and message handling.
- *
- * @module A2AService
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { ConnectionManagerInterface, CancellationManagerInterface, ContextManagerInterface, ServiceInterface, TaskManagerInterface, EventManagerOptions } from "../core/index.js";
-import { AgentCard, MessageSendParams, SendMessageSuccessResult, Task, TaskIdParams, TaskQueryParams } from "../../../schemas/a2a/index.js";
-import { UpdateEvent, Command, State, Update } from "./context.js";
-import { A2AEngine } from "./engine.js";
-export type AgentCardParams = (Partial<AgentCard> & Required<Pick<AgentCard, "name">>) | string;
-/**
- * Configuration parameters for creating A2A service instances.
- *
- * This interface defines the required and optional components needed to
- * instantiate an A2A service, including the agent identity, execution engine,
- * and various manager interfaces for handling different aspects of A2A operations.
- *
- * @example
- * ```typescript
- * const factoryParams: FactoryParams = {
- *   agentCard: {
- *     id: 'agent-123',
- *     name: 'MyAgent',
- *     capabilities: ['messaging', 'task-processing']
- *   },
- *   engine: createA2AEngine(),
- *   contexts: createContextManager(),
- *   connections: createConnectionManager(),
- *   methods: {
- *     sendMessage: customSendMessage,
- *     getTask: customGetTask
- *   }
- * };
- *
- * const service = createA2AService(factoryParams);
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface FactoryParams {
-    /** Agent identity and capabilities information */
-    agentCard: AgentCardParams;
-    /** Execution engine for processing A2A commands */
-    engine: A2AEngine;
-    /** Optional context manager for execution state management */
-    contexts?: ContextManagerInterface<Command, State, Update>;
-    /** Optional connection manager for agent connections */
-    connections?: ConnectionManagerInterface;
-    /** Optional cancellation manager for handling operation cancellations */
-    cancellations?: CancellationManagerInterface;
-    /** Optional task manager for task lifecycle management */
-    tasks?: TaskManagerInterface<State>;
-    /** Optional custom method implementations */
-    methods?: Partial<MethodOptions>;
-    /** Optional event manager configuration overrides */
-    events?: EventManagerOptions<Command, State, Update>;
-    /** Enforce parameter validation */
-    enforceParamValidation?: boolean;
-}
-/**
- * Parameters passed to A2A method implementations.
- *
- * This interface defines the dependencies and context information that
- * method implementations receive when they are invoked. It provides access
- * to the service instance, execution engine, context management, and
- * cancellation mechanisms.
- *
- * @example
- * ```typescript
- * const customSendMessage = async (
- *   message: MessageSendParams,
- *   params: MethodParams
- * ): Promise<SendMessageSuccessResult> => {
- *   const { service, engine, contextManager, signal } = params;
- *
- *   // Create execution context
- *   const context = contextManager.createContext(message);
- *
- *   // Check for cancellation
- *   if (signal.aborted) {
- *     throw new Error('Operation cancelled');
- *   }
- *
- *   // Execute message sending
- *   return await service.execute(engine, context);
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface MethodParams {
-    /** The A2A service instance */
-    service: A2AServiceInterface<Command, State, Update>;
-    /** The execution engine for processing */
-    engine: A2AEngine;
-    /** Context manager for execution state */
-    contextManager: ContextManagerInterface<Command, State, Update>;
-    /** Abort signal for cancellation handling */
-    signal: AbortSignal;
-    /** Enforce input validation */
-    enforceValidation?: boolean;
-}
-/**
- * Custom method implementation options for A2A services.
- *
- * This interface allows customization of core A2A operations by providing
- * alternative implementations for task management, message handling, and
- * streaming operations. Each method can be individually overridden to
- * provide custom behavior while maintaining the standard interface.
- *
- * @example
- * ```typescript
- * const customMethods: MethodOptions = {
- *   sendMessage: async (message, params) => {
- *     // Custom message sending logic
- *     console.log(`Sending message to: ${message.recipient}`);
- *     const result = await defaultSendMessage(message, params);
- *     console.log(`Message sent with ID: ${result.messageId}`);
- *     return result;
- *   },
- *
- *   getTask: async (input, params) => {
- *     // Custom task retrieval with caching
- *     const cached = taskCache.get(input.taskId);
- *     if (cached) return cached;
- *
- *     const task = await defaultGetTask(input, params);
- *     taskCache.set(input.taskId, task);
- *     return task;
- *   }
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface MethodOptions {
-    /**
-     * Custom task retrieval implementation.
-     *
-     * @param input - Task query parameters
-     * @param params - Method execution parameters (without engine, contextManager, signal)
-     * @returns Promise resolving to the requested task
-     */
-    getTask: (input: TaskQueryParams, params: Omit<MethodParams, "engine" | "contextManager" | "signal">) => Promise<Task>;
-    /**
-     * Task cancellation.
-     *
-     * @param input - Task identification parameters
-     * @param params - Method execution parameters (without engine, signal)
-     * @returns Promise resolving to the cancelled task
-     */
-    cancelTask: (input: TaskIdParams, params: Omit<MethodParams, "engine" | "signal">) => Promise<Task>;
-    /**
-     * Message sending.
-     *
-     * @param message - Message parameters to send
-     * @param params - Full method execution parameters
-     * @returns Promise resolving to send operation result
-     */
-    sendMessage: (message: MessageSendParams, params: MethodParams) => Promise<SendMessageSuccessResult>;
-    /**
-     * Streaming messages.
-     *
-     * @param message - Message parameters to send
-     * @param params - Full method execution parameters
-     * @returns AsyncGenerator yielding update events
-     */
-    streamMessage: (message: MessageSendParams, params: MethodParams) => AsyncGenerator<UpdateEvent>;
-    /**
-     * Resubscription.
-     *
-     * @param input - Task identification parameters
-     * @param params - Full method execution parameters
-     * @returns AsyncGenerator yielding update events
-     */
-    resubscribe: (input: TaskIdParams, params: MethodParams) => AsyncGenerator<UpdateEvent>;
-}
-/**
- * Public interface for A2A service methods.
- *
- * This interface defines the public API that consumers of A2A services
- * can use to interact with agents. It provides simplified method signatures
- * that hide internal complexity while exposing the essential functionality
- * for agent-to-agent communication.
- *
- * @example
- * ```typescript
- * // Using the methods interface
- * const service: MethodsInterface = createA2AService(params);
- *
- * // Get a task
- * const task = await service.getTask({ taskId: 'task-123' });
- *
- * // Send a message
- * const result = await service.sendMessage({
- *   recipient: 'agent-456',
- *   content: 'Hello, how are you?'
- * });
- *
- * // Stream messages for real-time updates
- * for await (const update of service.streamMessage({
- *   recipient: 'agent-456',
- *   content: 'Processing your request...'
- * })) {
- *   console.log('Update:', update);
- * }
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface MethodsInterface {
-    /**
-     * Retrieves a task by its ID.
-     *
-     * @param input - Task identification parameters
-     * @returns Promise resolving to the requested task
-     */
-    getTask: (input: TaskQueryParams) => Promise<Task>;
-    /**
-     * Cancels a task by its ID.
-     *
-     * @param input - Task identification parameters
-     * @returns Promise resolving to the cancelled task
-     */
-    cancelTask: (input: TaskIdParams) => Promise<Task>;
-    /**
-     * Sends a message to another agent.
-     *
-     * @param message - Message parameters to send
-     * @param params - Optional execution parameters
-     * @returns Promise resolving to send operation result
-     */
-    sendMessage: (message: MessageSendParams, params?: Partial<Omit<MethodParams, "service" | "contextManager">>) => Promise<SendMessageSuccessResult>;
-    /**
-     * Sends a message with streaming updates.
-     *
-     * @param message - Message parameters to send
-     * @param params - Optional execution parameters
-     * @returns AsyncGenerator yielding update events
-     */
-    streamMessage: (message: MessageSendParams, params?: Partial<Omit<MethodParams, "service" | "contextManager">>) => AsyncGenerator<UpdateEvent>;
-    /**
-     * Resubscribes to updates for a specific task.
-     *
-     * @param input - Task identification parameters
-     * @param params - Optional execution parameters
-     * @returns AsyncGenerator yielding update events
-     */
-    resubscribe: (input: TaskIdParams, params?: Partial<Omit<MethodParams, "service" | "contextManager">>) => AsyncGenerator<UpdateEvent>;
-}
-/**
- * Main interface for A2A service implementations.
- *
- * This interface extends the core ServiceInterface and MethodsInterface to provide
- * a complete A2A service implementation. It includes agent identity management,
- * connection tracking, cancellation handling, and state management capabilities
- * specific to agent-to-agent communication scenarios.
- *
- * @template TCommand - The command type, must extend Command
- * @template TState - The state type, must extend State
- * @template TUpdate - The update type, must extend Update
- *
- * @example
- * ```typescript
- * class MyA2AService implements A2AServiceInterface {
- *   constructor(
- *     public agentCard: AgentCard,
- *     private engine: A2AEngine
- *   ) {}
- *
- *   async execute(engine, context) {
- *     // Handle execution
- *   }
- *
- *   async sendMessage(message, params) {
- *     // Handle message sending
- *   }
- *
- *   addConnection(id: string) {
- *     this.connections.add(id);
- *     console.log(`Added connection: ${id}`);
- *   }
- *
- *   // ... implement other methods
- * }
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface A2AServiceInterface<TCommand extends Command = Command, TState extends State = State, TUpdate extends Update = Update> extends ServiceInterface<TCommand, TState, TUpdate>, MethodsInterface {
-    /**
-     * Optional event manager configuration overrides.
-     *
-     * When present, these overrides customize the default event handling
-     * behavior for this service instance.
-     */
-    readonly eventOverrides: EventManagerOptions<TCommand, TState, TUpdate> | undefined;
-    /**
-     * Agent identity and capabilities information.
-     *
-     * This card identifies the agent and describes its capabilities,
-     * which is used for agent discovery and capability matching.
-     */
-    agentCard: AgentCard;
-    /**
-     * Adds a connection to the active connections registry.
-     *
-     * @param id - Unique identifier for the connection
-     *
-     * @example
-     * ```typescript
-     * service.addConnection('connection-123');
-     * ```
-     */
-    addConnection: (id: string) => void;
-    /**
-     * Removes a connection from the active connections registry.
-     *
-     * @param id - Unique identifier for the connection
-     *
-     * @example
-     * ```typescript
-     * service.removeConnection('connection-123');
-     * ```
-     */
-    removeConnection: (id: string) => void;
-    /**
-     * Checks if a specific execution context has been cancelled.
-     *
-     * @param id - Context or execution identifier
-     * @returns True if cancelled, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (service.isCancelled('context-123')) {
-     *   console.log('Execution was cancelled');
-     *   return;
-     * }
-     * ```
-     */
-    isCancelled: (id: string) => boolean;
-    /**
-     * Adds a cancellation marker for a specific execution context.
-     *
-     * @param id - Context or execution identifier to cancel
-     *
-     * @example
-     * ```typescript
-     * service.addCancellation('context-123');
-     * ```
-     */
-    addCancellation: (id: string) => void;
-    /**
-     * Removes a cancellation marker for a specific execution context.
-     *
-     * @param id - Context or execution identifier
-     *
-     * @example
-     * ```typescript
-     * service.removeCancellation('context-123');
-     * ```
-     */
-    removeCancellation: (id: string) => void;
-    /**
-     * Retrieves the current state for a specific Task.
-     *
-     * @param id - Task identifier
-     * @returns Promise resolving to the state, or undefined if not found
-     *
-     * @example
-     * ```typescript
-     * const state = await service.getState('task-123');
-     * if (state) {
-     *   console.log('Current progress:', state.progress);
-     * }
-     * ```
-     */
-    getState: (id: string) => Promise<TState | undefined>;
-    /**
-     * Sets the state for a specific Task.
-     *
-     * @param id - Task identifier
-     * @param data - The state data to store
-     * @returns Promise that resolves when state is saved
-     *
-     * @example
-     * ```typescript
-     * await service.setState('task-123', {
-     *   progress: 0.75,
-     *   status: 'processing',
-     *   data: processedResults
-     * });
-     * ```
-     */
-    setState: (id: string, data: TState) => Promise<void>;
-}

package/dist/types/interfaces/services/a2a/service.js

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

package/dist/types/interfaces/services/core/context/command.d.ts

@@ -1,25 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { CoreCommand } from "./types.js";
-import { EventEmitter } from "events";
-export interface CommandChannelMap<TCommand extends CoreCommand = CoreCommand> {
-    send: [TCommand];
-    close: [];
-}
-export interface SendCommandInterface<TCommand extends CoreCommand = CoreCommand> {
-    isOpen: boolean;
-    send(command: TCommand): void;
-}
-export interface ReceiveCommandInterface<TCommand extends CoreCommand = CoreCommand> extends AsyncIterable<TCommand, TCommand, TCommand | undefined>, EventEmitter<CommandChannelMap<TCommand>> {
-    command: TCommand;
-    commandList: TCommand[];
-    close(): void;
-    next(): Promise<IteratorResult<TCommand>>;
-    return(value: TCommand): Promise<IteratorResult<TCommand>>;
-}
-export type ReceiveCommandProxyInterface<TCommand extends CoreCommand = CoreCommand> = ReceiveCommandInterface<TCommand> & TCommand;
-export interface CommandChannelInterface<TCommand extends CoreCommand = CoreCommand> extends ReceiveCommandInterface<TCommand>, SendCommandInterface<TCommand> {
-}
-export type CommandChannelProxyInterface<TCommand extends CoreCommand = CoreCommand> = CommandChannelInterface<TCommand> & TCommand;

package/dist/types/interfaces/services/core/context/command.js

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

package/dist/types/interfaces/services/core/context/context.d.ts

@@ -1,207 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview Core Context Interface Definition
- *
- * This module defines the CoreContext interface, which serves as the central
- * execution environment for all command processing. The context encapsulates
- * the command, state management, event handling, and cancellation mechanisms
- * required for execution engine operations.
- *
- * @module CoreContext
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { EventManagerInterface } from "../managers/event.js";
-import { CoreCommand, CoreState, CoreUpdate } from "./types.js";
-import { ReceiveCommandProxyInterface } from "./command.js";
-/**
- * Core execution context interface that provide the complete environment for command execution.
- *
- * The CoreContext serves as the primary execution environment passed to execution engines.
- * It encapsulates all the necessary components for command processing, including the command
- * itself, state management, event handling, and cancellation signals. This design enables
- * execution engines to be stateless functions that receive everything they need through
- * the context parameter.
- *
- * The context is designed to support "Context Engineering" - the practice of carefully
- * constructing execution environments that contain all necessary information and capabilities
- * for effective command processing. As the system evolves, the context becomes increasingly
- * important for enabling sophisticated execution patterns.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @example
- * ```typescript
- * // Using context in an execution engine
- * const myEngine: ExecutionEngine<MyCommand, MyState, MyUpdate> = async function* (context) {
- *   const { command, State, events, signal, isCancelled } = context;
- *
- *   // Get current state
- *   const currentState = State();
- *
- *   // Check for cancellation
- *   if (isCancelled() || signal.aborted) {
- *     yield { type: 'cancelled' };
- *     return;
- *   }
- *
- *   // Process command
- *   const result = await processCommand(command);
- *
- *   // Emit events and yield updates
- *   events.emit('progress', { progress: 0.5 });
- *   yield { type: 'progress', progress: 0.5, data: result };
- * };
- * ```
- *
- * @example
- * ```typescript
- * // Creating and using a context
- * const context: CoreContext<MyCommand, MyState, MyUpdate> = {
- *   contextId: 'execution-123',
- *   command: createCommandProxy(myCommand),
- *   events: createEventManager(),
- *   signal: abortController.signal,
- *   isCancelled: () => abortController.signal.aborted,
- *   State: () => getCurrentState()
- * };
- *
- * // Execute with context
- * for await (const update of myEngine(context)) {
- *   console.log('Update:', update);
- * }
- * ```
- *
- * @remarks
- * **Design Philosophy:**
- * The context represents a shift toward functional execution patterns where execution
- * engines are pure functions that receive all necessary dependencies through the
- * context parameter. This approach enables:
- *
- * - **Testability**: Easy to mock and test individual components
- * - **Composability**: Different engines can work with the same context interface
- * - **Flexibility**: Context can be enhanced without changing engine signatures
- * - **Debugging**: Complete execution environment is visible and traceable
- *
- * **Context Engineering:**
- * As mentioned in the original note, Context Engineering is becoming increasingly
- * important. This involves carefully designing contexts that provide the right
- * level of abstraction and capability for specific execution scenarios.
- *
- * @public
- * @since 0.5.6
- */
-export interface CoreContext<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    /**
-     * Unique identifier for this execution context.
-     *
-     * This ID is used throughout the system to track and correlate execution
-     * activities, logs, and state updates with specific command executions.
-     *
-     * @example
-     * ```typescript
-     * console.log(`Starting execution: ${context.contextId}`);
-     * loggerService.info(`[${context.contextId}] Processing command`);
-     * ```
-     */
-    readonly contextId: string;
-    /**
-     * Command proxy interface providing access to the command being executed.
-     *
-     * The command proxy wraps the original command and may provide additional
-     * functionality such as validation, logging, or transformation. It allows
-     * execution engines to access command data in a controlled manner.
-     *
-     * @example
-     * ```typescript
-     * const { command } = context;
-     *
-     * // Access command properties
-     * const userId = command.metadata?.userId;
-     * const taskType = command.type;
-     * const parameters = command.params;
-     *
-     * // Use command data in processing
-     * const result = await processTask(taskType, parameters, userId);
-     * ```
-     */
-    command: ReceiveCommandProxyInterface<TCommand>;
-    /**
-     * Function to check if the execution has been cancelled.
-     *
-     * This function provides a convenient way to check cancellation status
-     * throughout execution. It may aggregate multiple cancellation sources
-     * including abort signals, service-level cancellation, and timeout conditions.
-     *
-     * @returns True if the execution should be cancelled, false otherwise
-     *
-     * @example
-     * ```typescript
-     * // Check before expensive operations
-     * if (context.isCancelled()) {
-     *   yield { type: 'cancelled', reason: 'User cancellation' };
-     *   return;
-     * }
-     *
-     * // Check in processing loops
-     * for (const item of largeDataSet) {
-     *   if (context.isCancelled()) break;
-     *   await processItem(item);
-     * }
-     * ```
-     */
-    readonly isCancelled: () => boolean;
-    /**
-     * Abort signal for cancellation handling.
-     *
-     * This standard AbortSignal provides a way to handle cancellation in a
-     * platform-standard manner. It can be passed to fetch requests, timeouts,
-     * and other async operations that support cancellation.
-     */
-    readonly signal: AbortSignal;
-    /**
-     * Event manager for handling execution lifecycle events.
-     *
-     * The event manager provides event emission and subscription capabilities
-     * for execution lifecycle events. It handles state transitions, error
-     * scenarios, and completion notifications.
-     *
-     * @example
-     * ```typescript
-     * const { events } = context;
-     *
-     * // Listen for events
-     * events.on('update', (state, update) => {
-     *   console.log('State updated:', state);
-     * });
-     *
-     * // Handle errors
-     * events.on('error', (error, state) => {
-     *   console.error('Execution error:', error);
-     * });
-     * ```
-     */
-    readonly events: EventManagerInterface<TCommand, TState, TUpdate>;
-    /**
-     * Function to get the current execution state.
-     *
-     * This function provides access to the current state of the execution.
-     * The state represents the accumulated result of all updates processed
-     * so far and serves as the foundation for decision-making in execution engines.
-     *
-     * @returns The current execution state
-     *
-     * @example
-     * ```typescript
-     * // Get current state for decision making
-     * const currentState = context.State();
-     * ```
-     */
-    readonly State: () => TState;
-}

package/dist/types/interfaces/services/core/context/context.js

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

package/dist/types/interfaces/services/core/context/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./command.js";
-export * from "./context.js";
-export * from "./types.js";

package/dist/types/interfaces/services/core/context/index.js

@@ -1,3 +0,0 @@
-export * from "./command.js";
-export * from "./context.js";
-export * from "./types.js";

package/dist/types/interfaces/services/core/context/types.d.ts

@@ -1,11 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * We're starting with simple base types for the core context.
- * The base types will expand as we determine what is common across all services.
- */
-export type CoreCommand<TCommand extends object = object> = TCommand;
-export type CoreState<TState extends {} = {}> = TState;
-export type CoreUpdate<TUpdate = unknown> = TUpdate;

package/dist/types/interfaces/services/core/context/types.js

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