@artinet/sdk 0.5.5 → 0.5.7

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

@@ -0,0 +1,116 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Core Service Interface Definition
+ *
+ * This module defines the fundamental service interface that all core services
+ * must implement. It provides the contract for executing commands through
+ * execution engines and managing service lifecycle.
+ *
+ * @module CoreService
+ * @version 0.5.7
+ * @since 0.5.6
+ * @author The Artinet Project
+ */
+import { CoreContext, CoreCommand, CoreState, CoreUpdate } from "./context/index.js";
+import { ExecutionEngine } from "./execution/index.js";
+/**
+ * Core service interface defining the contract for all service implementations.
+ *
+ * Services are responsible for orchestrating command execution through execution
+ * engines, managing the execution lifecycle, and providing a consistent interface
+ * for starting and stopping operations. This interface serves as the foundation
+ * for all service types in the core framework.
+ *
+ * The service acts as a coordinator between execution engines and the broader
+ * system, handling concerns like resource management, execution tracking, and
+ * graceful shutdown while delegating the actual command processing to engines.
+ *
+ * @public
+ * @since 0.5.6
+ */
+export interface ServiceInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
+    /**
+     * Executes a command using the provided execution engine and context.
+     *
+     * This is the primary method for processing commands. The service receives
+     * an execution engine (which defines how to process the command) and a
+     * context (which contains the command, state, and execution environment).
+     *
+     * The service is responsible for:
+     * - Coordinating the execution process
+     * - Managing resources during execution
+     * - Handling the stream of updates from the engine
+     * - Ensuring proper cleanup on completion or failure
+     *
+     * @param engine - The execution engine that will process the command
+     * @param context - The execution context containing command and environment
+     * @returns Promise that resolves when execution is complete
+     *
+     * @throws Should handle and wrap any execution errors appropriately
+     *
+     * @example
+     * ```typescript
+     * // Basic execution
+     * await service.execute(myEngine, executionContext);
+     *
+     * // With error handling
+     * try {
+     *   await service.execute(myEngine, executionContext);
+     * } catch (error) {
+     *   console.error('Execution failed:', error);
+     *   await handleExecutionError(error, executionContext);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Service implementation with update handling
+     * async execute(engine, context) {
+     *   const updates: TUpdate[] = [];
+     *
+     *   try {
+     *     for await (const update of engine(context)) {
+     *       updates.push(update);
+     *       await this.notifySubscribers(update);
+     *
+     *       if (context.isCancelled()) {
+     *         console.log('Execution cancelled');
+     *         break;
+     *       }
+     *     }
+     *   } catch (error) {
+     *     await this.handleExecutionError(error, context);
+     *     throw error;
+     *   }
+     *
+     *   console.log(`Execution completed with ${updates.length} updates`);
+     * }
+     * ```
+     */
+    execute: (engine: ExecutionEngine<TCommand, TState, TUpdate>, context: CoreContext<TCommand, TState, TUpdate>) => Promise<void>;
+    /**
+     * Stops the service and performs cleanup operations.
+     *
+     * This method is called to gracefully shut down the service, ensuring that
+     * all active executions are properly terminated and resources are cleaned up.
+     * Implementation should handle stopping active executions, releasing resources,
+     * and preparing for service shutdown.
+     *
+     * The stop method should be idempotent - calling it multiple times should
+     * not cause errors or unexpected behavior.
+     *
+     * @returns Promise that resolves when the service has been stopped and cleaned up
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * await service.stop();
+     * console.log('Service stopped successfully');
+     * ```
+     */
+    stop: () => Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/types/types/interfaces/services/core/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../../src/types/interfaces/services/core/service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB,CAC/B,QAAQ,SAAS,WAAW,GAAG,WAAW,EAC1C,MAAM,SAAS,SAAS,GAAG,SAAS,EACpC,OAAO,SAAS,UAAU,GAAG,UAAU;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAClD,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,KAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

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

@@ -0,0 +1,5 @@
+export * from "./a2a/index.js";
+export * from "./core/index.js";
+export * from "./mcp/index.js";
+export * from "./protocol.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/types/interfaces/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/types/interfaces/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/types/types/interfaces/services/mcp/index.d.ts

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

package/dist/types/types/interfaces/services/mcp/index.d.ts.map

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

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

@@ -0,0 +1,50 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview MCP Service Interface Definition
+ *
+ * This module defines the MCP service interface that all MCP services
+ * must implement. It provides the contract for registering base tools and
+ * managing service lifecycle.
+ *
+ * @module MCPService
+ * @version 0.5.7
+ * @since 0.5.7
+ * @author The Artinet Project
+ */
+import { ServiceInterface } from "../core/index.js";
+/**
+ * Main interface for MCP service implementations.
+ *
+ * This interface extends the core ServiceInterface to provide
+ * a complete MCP service implementation. It includes base tool registration.
+ *
+ * @example
+ * ```typescript
+ * class MyMCPService implements MCPServiceInterface {
+ *   constructor(
+ *     public agentCard: AgentCard,
+ *     // ... other dependencies
+ *   ) {}
+ *
+ *   registerTools(uri: string) {
+ *     // Register tools
+ *   }
+ *
+ *   // ... implement other MCP service methods
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.5.7
+ */
+export interface MCPServiceInterface extends Omit<ServiceInterface, "execute"> {
+    /**
+     * Registers tools for the MCP service.
+     * @param uri - The URI of the agent card resource.
+     */
+    registerTools?: (uri: string) => void;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/types/types/interfaces/services/mcp/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../../src/types/interfaces/services/mcp/service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC5E;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC"}

package/dist/types/types/{services → interfaces/services}/protocol.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
 /**
  * @description The protocol enum.
  */

package/dist/types/types/interfaces/services/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../../../src/types/interfaces/services/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,oBAAY,QAAQ;IAClB;;OAEG;IACH,GAAG,QAAQ;IACX;;OAEG;IACH,GAAG,QAAQ;IACX;;OAEG;IACH,GAAG,QAAQ;IACX;;OAEG;IACH,IAAI,SAAS;IACb;;OAEG;IACH,KAAK,UAAU;IACf;;OAEG;IACH,MAAM,WAAW;CAClB"}

package/dist/types/types/interfaces/storage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface Store<T> {
+    set(data: T, id?: string): Promise<void>;
+    get(id: string): Promise<T | undefined>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/types/types/interfaces/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../src/types/interfaces/storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACzC"}