@artinet/sdk 0.5.16 → 0.5.18

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

@@ -0,0 +1,413 @@
+/**
+ * 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/browser/types/interfaces/services/a2a/service.js

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

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

@@ -0,0 +1,25 @@
+/**
+ * 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/browser/types/interfaces/services/core/context/command.js

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

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

@@ -0,0 +1,207 @@
+/**
+ * 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/browser/types/interfaces/services/core/context/context.js

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

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

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

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * 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/browser/types/interfaces/services/core/context/types.js

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