@agentica/core 0.19.0 → 0.20.0

package/src/context/internal/AgenticaOperationComposer.ts

@@ -21,7 +21,10 @@ export function compose<Model extends ILlmSchema.Model>(props: {
   config?: IAgenticaConfig<Model> | IMicroAgenticaConfig<Model> | undefined;
 }): AgenticaOperationCollection<Model> {
   const unique: boolean = (props.controllers.length === 1 || (() => {
-    const names = props.controllers.map(controllers => controllers.application.functions.map(func => func.name)).flat();
+    const names = props.controllers.map(
+      // eslint-disable-next-line ts/no-unsafe-return, ts/no-unsafe-call, ts/no-unsafe-member-access
+      controllers => controllers.application.functions.map((func: { name: string }) => func.name),
+    ).flat();
     return new Set(names).size === names.length;
   })());
 
@@ -126,19 +129,24 @@ export function toClassOperations<Model extends ILlmSchema.Model>(props: {
  * @internal
  */
 export function toMcpOperations<Model extends ILlmSchema.Model>(props: {
-  controller: IAgenticaController.IMcp;
+  controller: IAgenticaController.IMcp<Model>;
   index: number;
   naming: (func: string, controllerIndex: number) => string;
 }): AgenticaOperation<Model>[] {
+  // eslint-disable-next-line ts/no-unsafe-call, ts/no-unsafe-member-access, ts/no-unsafe-return
   return props.controller.application.functions.map(func => ({
     protocol: "mcp",
     controller: props.controller,
+    // eslint-disable-next-line ts/no-unsafe-assignment
     function: func,
+    // eslint-disable-next-line ts/no-unsafe-argument, ts/no-unsafe-member-access
     name: props.naming(func.name, props.index),
     toJSON: () => ({
       protocol: "mcp",
       controller: props.controller.name,
+      // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
       function: func.name,
+      // eslint-disable-next-line ts/no-unsafe-argument, ts/no-unsafe-member-access
       name: props.naming(func.name, props.index),
     }),
   }));

package/src/functional/assertMcpController.ts

@@ -0,0 +1,49 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
+import type { ILlmSchema, IMcpLlmApplication, IMcpTool } from "@samchon/openapi";
+
+import { McpLlm } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an MCP controller with type assertion.
+ *
+ * Create an {@link IAgenticaController.IMcp} instance which represents
+ * an MCP (Model Context Protocol) controller with LLM function calling
+ * schemas and client connection.
+ *
+ * @param props Properties to create the MCP controller
+ * @param props.name Name of the MCP implementation.
+ * @param props.client Client connection to the MCP implementation.
+ * @param props.model Model schema of the LLM function calling.
+ * @param props.options Options to create the MCP controller.
+ * @returns MCP LLM application instance
+ * @author Samchon
+ */
+export async function assertMcpController<Model extends ILlmSchema.Model>(props: {
+  name: string;
+  client: Client;
+  model: Model;
+  options?: Partial<IMcpLlmApplication.IOptions<Model>>;
+}): Promise<IAgenticaController.IMcp<Model>> {
+  // for peerDependencies
+  const { ListToolsResultSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+  // get list of tools
+  const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
+
+  // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-call, ts/no-unsafe-member-access
+  const application: IMcpLlmApplication<Model> = McpLlm.application<Model>({
+    model: props.model,
+    tools: typia.assert<Array<IMcpTool>>(tools),
+  });
+
+  return {
+    protocol: "mcp",
+    name: props.name,
+    client: props.client,
+    // eslint-disable-next-line ts/no-unsafe-assignment
+    application,
+  };
+}

package/src/index.ts

@@ -23,7 +23,7 @@ export * from "./events/MicroAgenticaEvent";
 export * as factory from "./factory";
 
 export * from "./functional/assertHttpLlmApplication";
-export * from "./functional/assertMcpLlmApplication";
+export * from "./functional/assertMcpController";
 export * from "./functional/validateHttpLlmApplication";
 // @TODO: implement validateMcpLlmApplication
 

package/src/orchestrate/call.ts

@@ -72,10 +72,13 @@ export async function call<Model extends ILlmSchema.Model>(
           type: "function",
           function: {
             name: s.name,
+            // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
             description: s.function.description,
             parameters: (
               "separated" in s.function
+              // eslint-disable-next-line ts/no-unsafe-member-access
               && s.function.separated !== undefined
+                // eslint-disable-next-line ts/no-unsafe-member-access
                 ? (s.function.separated.llm
                   ?? ({
                     type: "object",
@@ -84,6 +87,7 @@ export async function call<Model extends ILlmSchema.Model>(
                     additionalProperties: false,
                     $defs: {},
                   } satisfies IChatGptSchema.IParameters))
+                // eslint-disable-next-line ts/no-unsafe-member-access
                 : s.function.parameters) as Record<string, any>,
           },
         }) as OpenAI.ChatCompletionTool,
@@ -368,7 +372,7 @@ async function propagateClass<Model extends ILlmSchema.Model>(props: {
 
 async function propagateMcp<Model extends ILlmSchema.Model>(props: {
   ctx: AgenticaContext<Model> | MicroAgenticaContext<Model>;
-  operation: AgenticaOperation.Mcp;
+  operation: AgenticaOperation.Mcp<Model>;
   call: AgenticaCallEvent<Model>;
   retry: number;
 }): Promise<AgenticaExecuteHistory<Model>> {
@@ -435,12 +439,14 @@ async function executeClassOperation<Model extends ILlmSchema.Model>(operation:
   return ((execute as Record<string, unknown>)[operation.function.name] as (...args: unknown[]) => Promise<unknown>)(operationArguments);
 }
 
-async function executeMcpOperation(
-  operation: AgenticaOperation.Mcp,
+async function executeMcpOperation<Model extends ILlmSchema.Model>(
+  operation: AgenticaOperation.Mcp<Model>,
   operationArguments: Record<string, unknown>,
 ): Promise<unknown> {
-  return operation.controller.application.client.callTool({
+  return operation.controller.client.callTool({
+    // eslint-disable-next-line ts/no-unsafe-member-access
     method: operation.function.name,
+    // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
     name: operation.function.name,
     arguments: operationArguments,
   }).then(v => v.content);
@@ -512,6 +518,7 @@ async function correct<Model extends ILlmSchema.Model>(
         type: "function",
         function: {
           name: call.operation.name,
+          // eslint-disable-next-line ts/no-unsafe-assignment, ts/no-unsafe-member-access
           description: call.operation.function.description,
           /**
            * @TODO fix it
@@ -519,7 +526,9 @@ async function correct<Model extends ILlmSchema.Model>(
            */
           parameters: (
             "separated" in call.operation.function
+            // eslint-disable-next-line ts/no-unsafe-member-access
             && call.operation.function.separated !== undefined
+            // eslint-disable-next-line ts/no-unsafe-member-access
               ? (call.operation.function.separated?.llm
                 ?? ({
                   $defs: {},
@@ -528,6 +537,7 @@ async function correct<Model extends ILlmSchema.Model>(
                   additionalProperties: false,
                   required: [],
                 } satisfies IChatGptSchema.IParameters))
+              // eslint-disable-next-line ts/no-unsafe-member-access
               : call.operation.function.parameters) as unknown as Record<string, unknown>,
         },
       },

package/src/structures/IAgenticaController.ts

@@ -1,3 +1,4 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
 import type {
   IHttpConnection,
   IHttpLlmApplication,
@@ -6,10 +7,9 @@ import type {
   ILlmApplication,
   ILlmFunction,
   ILlmSchema,
+  IMcpLlmApplication,
 } from "@samchon/openapi";
 
-import type { IMcpLlmApplication } from "./mcp/IMcpLlmApplication";
-
 /**
  * Controller of the Agentica Agent.
  *
@@ -29,7 +29,7 @@ import type { IMcpLlmApplication } from "./mcp/IMcpLlmApplication";
 export type IAgenticaController<Model extends ILlmSchema.Model> =
   | IAgenticaController.IHttp<Model>
   | IAgenticaController.IClass<Model>
-  | IAgenticaController.IMcp;
+  | IAgenticaController.IMcp<Model>;
 
 export namespace IAgenticaController {
   /**
@@ -122,7 +122,12 @@ export namespace IAgenticaController {
   /**
    * MCP Server controller.
    */
-  export interface IMcp extends IBase<"mcp", IMcpLlmApplication> { }
+  export interface IMcp<Model extends ILlmSchema.Model> extends IBase<"mcp", IMcpLlmApplication<Model>> {
+    /**
+     * MCP client for connection.
+     */
+    client: Client;
+  }
 
   interface IBase<Protocol, Application> {
     /**

package/src/structures/mcp/index.ts

@@ -1,3 +1 @@
-export * from "./IMcpLlmApplication";
-export * from "./IMcpLlmFunction";
 export * from "./IMcpLlmTransportProps";

package/src/utils/AsyncQueue.spec.ts

@@ -0,0 +1,355 @@
+import { AsyncQueue } from "./AsyncQueue";
+
+describe("the AsyncQueue", () => {
+  describe("basic functionality", () => {
+    it("enqueue and dequeue test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Enqueue items
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.enqueue(3);
+
+      // Dequeue items
+      const result1 = await queue.dequeue();
+      const result2 = await queue.dequeue();
+      const result3 = await queue.dequeue();
+
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+      expect(result2.value).toBe(2);
+      expect(result2.done).toBe(false);
+      expect(result3.value).toBe(3);
+      expect(result3.done).toBe(false);
+    });
+
+    it("isEmpty test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.isEmpty()).toBe(true);
+
+      queue.enqueue(1);
+      expect(queue.isEmpty()).toBe(false);
+
+      await queue.dequeue();
+      expect(queue.isEmpty()).toBe(true);
+    });
+
+    it("isClosed test", () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.isClosed()).toBe(false);
+
+      queue.close();
+      expect(queue.isClosed()).toBe(true);
+    });
+
+    it("done test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.done()).toBe(false);
+
+      queue.enqueue(1);
+      expect(queue.done()).toBe(false);
+
+      await queue.dequeue();
+      expect(queue.done()).toBe(false);
+
+      queue.close();
+      expect(queue.done()).toBe(true);
+    });
+  });
+
+  describe("close functionality", () => {
+    it("close test with empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("close test with non-empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.close();
+
+      const result1 = await queue.dequeue();
+      const result2 = await queue.dequeue();
+      const result3 = await queue.dequeue();
+
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+      expect(result2.value).toBe(2);
+      expect(result2.done).toBe(false);
+      expect(result3.done).toBe(true);
+      expect(result3.value).toBeUndefined();
+    });
+
+    it("close test with waiting dequeue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start dequeue before enqueue
+      const dequeuePromise = queue.dequeue();
+
+      // Close the queue
+      queue.close();
+
+      const result = await dequeuePromise;
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+  });
+
+  describe("waitUntilEmpty functionality", () => {
+    it("waitUntilEmpty test with empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Should resolve immediately since queue is empty
+      await queue.waitUntilEmpty();
+
+      queue.enqueue(1);
+      const result = await queue.dequeue();
+      expect(result.value).toBe(1);
+      expect(result.done).toBe(false);
+    });
+
+    it("waitUntilEmpty test with non-empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.enqueue(2);
+
+      // waitUntilEmpty should not resolve since queue is not empty
+      const waitPromise = queue.waitUntilEmpty();
+
+      // Dequeue first value
+      const result1 = await queue.dequeue();
+      expect(result1.value).toBe(1);
+
+      // Dequeue second value
+      const result2 = await queue.dequeue();
+      expect(result2.value).toBe(2);
+
+      // Now queue is empty, waitUntilEmpty should resolve\
+      await waitPromise;
+    });
+  });
+
+  describe("waitClosed functionality", () => {
+    it("waitClosed test with unclosed queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // waitClosed should not resolve since queue is not closed
+      const waitPromise = queue.waitClosed();
+
+      queue.enqueue(1);
+      const result = await queue.dequeue();
+      expect(result.value).toBe(1);
+
+      // Close the queue
+      queue.close();
+
+      // Now queue is closed, waitClosed should resolve
+      await waitPromise;
+    });
+
+    it("waitClosed test with already closed queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+
+      // waitClosed should resolve immediately since queue is already closed
+      await queue.waitClosed();
+    });
+
+    it("multiple waitClosed calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Create multiple waitClosed promises
+      const waitPromises = [queue.waitClosed(), queue.waitClosed(), queue.waitClosed()];
+
+      // Close the queue
+      queue.close();
+
+      // All promises should resolve
+      await Promise.all(waitPromises);
+    });
+
+    it("waitClosed test with delayed close", async () => {
+      const queue = new AsyncQueue<string>();
+
+      // Start waiting for close
+      const closePromise = queue.waitClosed();
+
+      // Close after delay
+      setTimeout(() => {
+        queue.close();
+      }, 10);
+
+      await closePromise; // Should resolve when queue is closed
+    });
+  });
+
+  describe("dequeue behavior", () => {
+    it("dequeue before enqueue test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start dequeue before enqueue
+      const dequeuePromise = queue.dequeue();
+
+      // Enqueue after a small delay
+      setTimeout(() => {
+        queue.enqueue(42);
+      }, 10);
+
+      const result = await dequeuePromise;
+      expect(result.value).toBe(42);
+      expect(result.done).toBe(false);
+    });
+
+    it("multiple dequeue calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start multiple dequeue calls
+      const dequeuePromises = [
+        queue.dequeue(),
+        queue.dequeue(),
+        queue.dequeue(),
+      ];
+
+      // Enqueue values
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.enqueue(3);
+
+      const results = await Promise.all(dequeuePromises);
+
+      expect(results[0]?.value).toBe(1);
+      expect(results[0]?.done).toBe(false);
+      expect(results[1]?.value).toBe(2);
+      expect(results[1]?.done).toBe(false);
+      expect(results[2]?.value).toBe(3);
+      expect(results[2]?.done).toBe(false);
+    });
+
+    it("dequeue after close test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.close();
+
+      const result1 = await queue.dequeue();
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+
+      const result2 = await queue.dequeue();
+      expect(result2.done).toBe(true);
+      expect(result2.value).toBeUndefined();
+    });
+
+    it("duplicate dequeue test", async () => {
+      const queue = new AsyncQueue<string>();
+
+      // Start dequeue operation that will wait for an item
+      const pendingDequeue = queue.dequeue();
+
+      // Add item after a small delay
+      setTimeout(() => {
+        queue.enqueue("delayed item");
+      }, 10);
+
+      const delayedResult = await pendingDequeue;
+      expect(delayedResult.value).toBe("delayed item");
+      expect(delayedResult.done).toBe(false);
+
+      // Check for duplicate dequeue
+      const duplicatedResult = await Promise.race([
+        queue.dequeue(),
+        new Promise(resolve => setTimeout(resolve, 0, false)),
+      ]) as false | IteratorResult<string, undefined>;
+
+      // If duplicatedResult is false, it means the race timed out (expected)
+      // If it's an IteratorResult, it should not have the same value
+      if (duplicatedResult !== false) {
+        expect(duplicatedResult.value).not.toBe("delayed item");
+      }
+    });
+  });
+
+  describe("edge cases and error handling", () => {
+    it("enqueue after close test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+      queue.enqueue(1); // Should still work, but dequeue will return done: true
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("multiple close calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+      queue.close(); // Second close should not cause issues
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("waitUntilEmpty with multiple calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+
+      // Create multiple waitUntilEmpty promises
+      const waitPromises = [queue.waitUntilEmpty(), queue.waitUntilEmpty()];
+
+      // Dequeue the value
+      await queue.dequeue();
+
+      // All promises should resolve
+      await Promise.all(waitPromises);
+    });
+
+    it("concurrent enqueue and dequeue test", async () => {
+      const queue = new AsyncQueue<number>();
+      const results: number[] = [];
+
+      // Start multiple dequeue operations
+      const dequeuePromises = Array.from({ length: 5 }).fill(0).map(async () => queue.dequeue());
+
+      // Enqueue values with small delays
+      for (let i = 0; i < 5; i++) {
+        setTimeout(() => {
+          queue.enqueue(i);
+        }, i * 10);
+      }
+
+      // Wait for all dequeue operations to complete
+      const dequeuedResults = await Promise.all(dequeuePromises);
+
+      // Collect values
+      dequeuedResults.forEach((result) => {
+        if (result.value !== undefined) {
+          results.push(result.value);
+        }
+      });
+
+      // Check that all values were dequeued
+      expect(results.length).toBe(5);
+      expect(results).toContain(0);
+      expect(results).toContain(1);
+      expect(results).toContain(2);
+      expect(results).toContain(3);
+      expect(results).toContain(4);
+    });
+  });
+});

package/src/utils/AsyncQueue.ts

@@ -1,3 +1,10 @@
+export class AsyncQueueClosedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AsyncQueueClosedError";
+  }
+}
+
 export class AsyncQueue<T> {
   private queue: T[] = [];
   private resolvers: ((value: IteratorResult<T, undefined>) => void)[] = [];
@@ -6,6 +13,11 @@ export class AsyncQueue<T> {
   private closed = false;
 
   enqueue(item: T) {
+    if (this.closed) {
+      console.error(new AsyncQueueClosedError("Cannot enqueue item: queue is closed."));
+      return;
+    }
+
     this.queue.push(item);
     if (this.resolvers.length > 0) {
       this.resolvers.shift()?.({ value: this.queue.shift()!, done: false });
@@ -13,16 +25,25 @@ export class AsyncQueue<T> {
   }
 
   async dequeue(): Promise<IteratorResult<T, undefined>> {
-    if (this.queue.length > 0) {
-      return { value: this.queue.shift()!, done: false };
-    }
-    if (this.closed) {
-      if (this.emptyResolvers.length > 0) {
-        this.emptyResolvers.forEach(resolve => resolve());
-        this.emptyResolvers = [];
+    const item = (() => {
+      if (!this.isEmpty()) {
+        return { value: this.queue.shift()!, done: false } as const;
+      }
+      if (this.isClosed()) {
+        return { value: undefined, done: true } as const;
       }
-      return { value: undefined, done: true };
+      return null;
+    })();
+
+    if (this.isEmpty() && this.emptyResolvers.length !== 0) {
+      this.emptyResolvers.forEach(resolve => resolve());
+      this.emptyResolvers = [];
     }
+
+    if (item !== null) {
+      return item;
+    }
+
     return new Promise(resolve => this.resolvers.push(resolve));
   }
 
@@ -46,6 +67,13 @@ export class AsyncQueue<T> {
     this.closeResolvers.forEach(resolve => resolve());
   }
 
+  /**
+   * Wait until the queue is empty
+   *
+   * if the queue is closed, it will not resolve promise
+   * this function only check the queue is empty
+   * @returns A promise that resolves when the queue is empty
+   */
   async waitUntilEmpty() {
     if (this.isEmpty()) {
       return Promise.resolve();