@copilotkitnext/core 0.0.1

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@copilotkitnext/core",
+  "version": "0.0.1",
+  "description": "Core web utilities for CopilotKit2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.30.0",
+    "tsup": "^8.5.0",
+    "typescript": "5.8.2",
+    "vitest": "^3.2.4",
+    "@copilotkitnext/typescript-config": "0.0.0",
+    "@copilotkitnext/eslint-config": "0.0.0"
+  },
+  "dependencies": {
+    "@ag-ui/client": "0.0.36-alpha.1",
+    "rxjs": "7.8.1",
+    "zod": "^3.25.75",
+    "@copilotkitnext/shared": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/__tests__/core-agent-constraints.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CopilotKitCore } from '../core';
+import { FrontendTool } from '../types';
+import { MockAgent, createAssistantMessage } from './test-utils';
+
+describe('CopilotKitCore - Agent Constraints', () => {
+  it('should add tool with agentId', () => {
+    const core = new CopilotKitCore({
+      headers: {},
+      properties: {},
+    });
+    
+    const tool: FrontendTool = {
+      name: 'testTool',
+      handler: vi.fn(),
+      agentId: 'agent1',
+    };
+    
+    core.addTool(tool);
+    expect(core.tools['testTool']).toBeDefined();
+    expect(core.tools['testTool']?.agentId).toBe('agent1');
+  });
+
+  it('should add multiple tools with different agentIds', () => {
+    const core = new CopilotKitCore({
+      headers: {},
+      properties: {},
+    });
+    
+    const globalTool: FrontendTool = {
+      name: 'globalTool',
+      handler: vi.fn(),
+    };
+    
+    const agent1Tool: FrontendTool = {
+      name: 'agent1Tool',
+      handler: vi.fn(),
+      agentId: 'agent1',
+    };
+    
+    const agent2Tool: FrontendTool = {
+      name: 'agent2Tool',
+      handler: vi.fn(),
+      agentId: 'agent2',
+    };
+    
+    core.addTool(globalTool);
+    core.addTool(agent1Tool);
+    core.addTool(agent2Tool);
+    
+    expect(core.tools['globalTool']).toBeDefined();
+    expect(core.tools['globalTool']?.agentId).toBeUndefined();
+    
+    expect(core.tools['agent1Tool']).toBeDefined();
+    expect(core.tools['agent1Tool']?.agentId).toBe('agent1');
+    
+    expect(core.tools['agent2Tool']).toBeDefined();
+    expect(core.tools['agent2Tool']?.agentId).toBe('agent2');
+  });
+
+  it('should preserve all FrontendTool properties including agentId', () => {
+    const core = new CopilotKitCore({
+      headers: {},
+      properties: {},
+    });
+    
+    const handler = vi.fn(async () => 'result');
+    const tool: FrontendTool = {
+      name: 'fullTool',
+      description: 'A complete tool',
+      handler,
+      followUp: false,
+      agentId: 'specificAgent',
+    };
+    
+    core.addTool(tool);
+    
+    const addedTool = core.tools['fullTool'];
+    expect(addedTool).toBeDefined();
+    expect(addedTool?.name).toBe('fullTool');
+    expect(addedTool?.description).toBe('A complete tool');
+    expect(addedTool?.handler).toBe(handler);
+    expect(addedTool?.followUp).toBe(false);
+    expect(addedTool?.agentId).toBe('specificAgent');
+  });
+});

package/src/__tests__/core-basic-functionality.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { CopilotKitCore } from "../core";
+import {
+  MockAgent,
+  createMessage,
+  createAssistantMessage,
+  createToolCallMessage,
+  createTool,
+} from "./test-utils";
+
+describe("CopilotKitCore.runAgent - Basic Functionality", () => {
+  let copilotKitCore: CopilotKitCore;
+
+  beforeEach(() => {
+    copilotKitCore = new CopilotKitCore({});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should run agent without tools", async () => {
+    const messages = [
+      createMessage({ content: "Hello" }),
+      createAssistantMessage({ content: "Hi there!" }),
+    ];
+    const agent = new MockAgent({ newMessages: messages });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual(messages);
+    expect(agent.runAgentCalls).toHaveLength(1);
+    expect(agent.runAgentCalls[0].forwardedProps).toEqual({});
+  });
+
+  it("should pass withMessages to agent.addMessages", async () => {
+    const initialMessages = [createMessage({ content: "Initial" })];
+    const newMessages = [createAssistantMessage({ content: "Response" })];
+    const agent = new MockAgent({ newMessages });
+
+    await copilotKitCore.runAgent({ agent: agent as any, withMessages: initialMessages });
+
+    expect(agent.addMessages).toHaveBeenCalledWith(initialMessages);
+    expect(agent.messages).toContain(initialMessages[0]);
+  });
+
+  it("should work without withMessages parameter", async () => {
+    const newMessages = [createAssistantMessage({ content: "Response" })];
+    const agent = new MockAgent({ newMessages });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual(newMessages);
+    expect(agent.addMessages).not.toHaveBeenCalled();
+  });
+
+  it("should forward properties to agent.runAgent", async () => {
+    const properties = { apiKey: "test-key", model: "gpt-4" };
+    copilotKitCore = new CopilotKitCore({ properties });
+    const agent = new MockAgent({ newMessages: [] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls[0].forwardedProps).toEqual(properties);
+  });
+
+  it("should handle empty newMessages array", async () => {
+    const agent = new MockAgent({ newMessages: [] });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual([]);
+    expect(agent.runAgentCalls).toHaveLength(1);
+  });
+
+  it("should ignore non-assistant messages for tool processing", async () => {
+    const messages = [
+      createMessage({ role: "user", content: "User message" }),
+      createMessage({ role: "system", content: "System message" }),
+      createMessage({ role: "tool", content: "Tool result", toolCallId: "123" }),
+    ];
+    const agent = new MockAgent({ newMessages: messages });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual(messages);
+    expect(agent.runAgentCalls).toHaveLength(1);
+  });
+
+  it("should handle messages with undefined toolCalls", async () => {
+    const message = createAssistantMessage({ 
+      content: "Response",
+      toolCalls: undefined 
+    });
+    const agent = new MockAgent({ newMessages: [message] });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual([message]);
+    expect(agent.runAgentCalls).toHaveLength(1);
+  });
+
+  it("should handle tool returning undefined as empty string", async () => {
+    const toolName = "undefinedTool";
+    const tool = createTool({
+      name: toolName,
+      handler: vi.fn(async () => undefined),
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage(toolName);
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.messages).toContainEqual(
+      expect.objectContaining({
+        role: "tool",
+        content: "", // Should be empty string, not "undefined"
+      })
+    );
+  });
+
+  it("should handle tool returning null as empty string", async () => {
+    const toolName = "nullTool";
+    const tool = createTool({
+      name: toolName,
+      handler: vi.fn(async () => null),
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage(toolName);
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.messages).toContainEqual(
+      expect.objectContaining({
+        role: "tool",
+        content: "", // Should be empty string, not "null"
+      })
+    );
+  });
+
+  it("should return correct result structure", async () => {
+    const newMessages = [
+      createAssistantMessage({ content: "Test" })
+    ];
+    const agent = new MockAgent({ newMessages });
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result).toHaveProperty("newMessages");
+    expect(Array.isArray(result.newMessages)).toBe(true);
+    expect(result.newMessages).toEqual(newMessages);
+  });
+});

package/src/__tests__/core-basic.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { CopilotKitCore } from "../core";
+
+describe("CopilotKitCore Basic", () => {
+  let copilotKitCore: CopilotKitCore;
+
+  beforeEach(() => {
+    copilotKitCore = new CopilotKitCore({});
+  });
+
+  it("should create an instance", () => {
+    expect(copilotKitCore).toBeDefined();
+    expect(copilotKitCore.agents).toEqual({});
+    expect(copilotKitCore.tools).toEqual({});
+  });
+
+  it("should add a tool", () => {
+    const tool = {
+      name: "testTool",
+      handler: vi.fn(),
+    };
+    
+    copilotKitCore.addTool(tool);
+    
+    expect(copilotKitCore.tools["testTool"]).toBe(tool);
+  });
+});

package/src/__tests__/core-edge-cases.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { CopilotKitCore } from "../core";
+import {
+  MockAgent,
+  createAssistantMessage,
+  createToolCallMessage,
+  createToolResultMessage,
+  createTool,
+} from "./test-utils";
+
+describe("CopilotKitCore.runAgent - Edge Cases", () => {
+  let copilotKitCore: CopilotKitCore;
+
+  beforeEach(() => {
+    copilotKitCore = new CopilotKitCore({});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should skip tool call when result already exists in newMessages", async () => {
+    const tool = createTool({
+      name: "alreadyProcessedTool",
+      handler: vi.fn(async () => "Should not be called"),
+    });
+    copilotKitCore.addTool(tool);
+
+    const toolCallId = "processed-call";
+    const assistantMsg = createToolCallMessage("alreadyProcessedTool");
+    if (assistantMsg.role === 'assistant' && assistantMsg.toolCalls && assistantMsg.toolCalls[0]) {
+      assistantMsg.toolCalls[0].id = toolCallId;
+    }
+    const existingResult = createToolResultMessage(toolCallId, "Already processed");
+
+    const agent = new MockAgent({
+      newMessages: [assistantMsg, existingResult],
+    });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(tool.handler).not.toHaveBeenCalled();
+  });
+
+  it("should handle empty tool function name", async () => {
+    const message = createAssistantMessage({
+      content: "",
+      toolCalls: [{
+        id: "empty-name-call",
+        type: "function",
+        function: {
+          name: "",
+          arguments: "{}",
+        },
+      }],
+    });
+
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.messages.filter(m => m.role === "tool")).toHaveLength(0);
+  });
+
+  it("should handle tool arguments as empty string", async () => {
+    const tool = createTool({
+      name: "emptyArgsTool",
+      handler: vi.fn(async (args) => `Received: ${JSON.stringify(args)}`),
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createAssistantMessage({
+      content: "",
+      toolCalls: [{
+        id: "empty-args-call",
+        type: "function",
+        function: {
+          name: "emptyArgsTool",
+          arguments: "",
+        },
+      }],
+    });
+
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await expect(copilotKitCore.runAgent({ agent: agent as any })).rejects.toThrow();
+  });
+
+  it("should handle very large tool result", async () => {
+    const largeResult = "x".repeat(100000); // 100KB string
+    const tool = createTool({
+      name: "largeTool",
+      handler: vi.fn(async () => largeResult),
+      followUp: false,
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage("largeTool");
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    const toolMessage = agent.messages.find(m => m.role === "tool");
+    expect(toolMessage?.content).toBe(largeResult);
+  });
+
+  it("should handle tool handler modifying agent state", async () => {
+    const tool = createTool({
+      name: "stateTool",
+      handler: vi.fn(async () => {
+        // Try to modify agent messages during execution
+        agent.messages.push(createAssistantMessage({ content: "Injected" }));
+        return "Result";
+      }),
+      followUp: false,
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage("stateTool");
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    // The injected message should be present
+    expect(agent.messages.some(m => m.content === "Injected")).toBe(true);
+    // Tool result should still be added correctly
+    expect(agent.messages.some(m => m.role === "tool" && m.content === "Result")).toBe(true);
+  });
+
+  it("should propagate errors from agent.runAgent", async () => {
+    const errorMessage = "Agent execution failed";
+    const agent = new MockAgent({ 
+      error: new Error(errorMessage)
+    });
+
+    await expect(copilotKitCore.runAgent({ agent: agent as any }))
+      .rejects
+      .toThrow(errorMessage);
+  });
+
+  it("should handle tool with invalid JSON arguments", async () => {
+    const toolName = "invalidJsonTool";
+    const tool = createTool({
+      name: toolName,
+      handler: vi.fn(async () => "Should not be called"),
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createAssistantMessage({
+      content: "",
+      toolCalls: [{
+        id: "tool-call-1",
+        type: "function",
+        function: {
+          name: toolName,
+          arguments: "{ invalid json",
+        },
+      }],
+    });
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await expect(copilotKitCore.runAgent({ agent: agent as any })).rejects.toThrow();
+    expect(tool.handler).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/core-follow-up.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { CopilotKitCore } from "../core";
+import { FrontendTool } from "../types";
+import {
+  MockAgent,
+  createAssistantMessage,
+  createToolCallMessage,
+  createMultipleToolCallsMessage,
+  createTool,
+} from "./test-utils";
+
+describe("CopilotKitCore.runAgent - Follow-up Logic", () => {
+  let copilotKitCore: CopilotKitCore;
+
+  beforeEach(() => {
+    copilotKitCore = new CopilotKitCore({});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should trigger recursive call when tool.followUp is true", async () => {
+    const tool = createTool({
+      name: "followUpTool",
+      handler: vi.fn(async () => "Result"),
+      followUp: true,
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage("followUpTool");
+    const followUpMessage = createAssistantMessage({ content: "Follow-up response" });
+    
+    const agent = new MockAgent({ newMessages: [message] });
+    let callCount = 0;
+    agent.runAgentCallback = () => {
+      callCount++;
+      if (callCount === 2) {
+        agent.setNewMessages([followUpMessage]);
+      }
+    };
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(2);
+    expect(result.newMessages).toContain(followUpMessage);
+  });
+
+  it("should not trigger recursive call when tool.followUp is false", async () => {
+    const tool = createTool({
+      name: "noFollowUpTool",
+      handler: vi.fn(async () => "Result"),
+      followUp: false,
+    });
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage("noFollowUpTool");
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(1);
+  });
+
+  it("should trigger recursive call when tool.followUp is undefined (default)", async () => {
+    const tool: FrontendTool = {
+      name: "defaultFollowUpTool",
+      handler: vi.fn(async () => "Result"),
+      // followUp is undefined
+    };
+    copilotKitCore.addTool(tool);
+
+    const message = createToolCallMessage("defaultFollowUpTool");
+    const followUpMessage = createAssistantMessage({ content: "Follow-up" });
+    
+    const agent = new MockAgent({ newMessages: [message] });
+    let callCount = 0;
+    agent.runAgentCallback = () => {
+      callCount++;
+      if (callCount === 2) {
+        agent.setNewMessages([followUpMessage]);
+      }
+    };
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(2);
+  });
+
+  it("should trigger follow-up when at least one tool needs it", async () => {
+    const tool1 = createTool({
+      name: "tool1",
+      handler: vi.fn(async () => "Result 1"),
+      followUp: false,
+    });
+    const tool2 = createTool({
+      name: "tool2",
+      handler: vi.fn(async () => "Result 2"),
+      followUp: true,
+    });
+    const tool3 = createTool({
+      name: "tool3",
+      handler: vi.fn(async () => "Result 3"),
+      followUp: false,
+    });
+    copilotKitCore.addTool(tool1);
+    copilotKitCore.addTool(tool2);
+    copilotKitCore.addTool(tool3);
+
+    const message = createMultipleToolCallsMessage([
+      { name: "tool1" },
+      { name: "tool2" },
+      { name: "tool3" },
+    ]);
+    
+    const agent = new MockAgent({ newMessages: [message] });
+    let callCount = 0;
+    agent.runAgentCallback = () => {
+      callCount++;
+      if (callCount === 2) {
+        agent.setNewMessages([]);
+      }
+    };
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(2);
+  });
+
+  it("should not trigger follow-up when all tools have followUp=false", async () => {
+    const tool1 = createTool({
+      name: "tool1",
+      handler: vi.fn(async () => "Result 1"),
+      followUp: false,
+    });
+    const tool2 = createTool({
+      name: "tool2",
+      handler: vi.fn(async () => "Result 2"),
+      followUp: false,
+    });
+    copilotKitCore.addTool(tool1);
+    copilotKitCore.addTool(tool2);
+
+    const message = createMultipleToolCallsMessage([
+      { name: "tool1" },
+      { name: "tool2" },
+    ]);
+    
+    const agent = new MockAgent({ newMessages: [message] });
+
+    await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(1);
+  });
+
+  it("should return final result after recursive follow-up", async () => {
+    const tool = createTool({
+      name: "recursiveTool",
+      handler: vi.fn(async () => "Tool result"),
+      followUp: true,
+    });
+    copilotKitCore.addTool(tool);
+
+    const initialMessage = createToolCallMessage("recursiveTool");
+    const finalMessage = createAssistantMessage({ content: "Final response" });
+    
+    const agent = new MockAgent({ newMessages: [initialMessage] });
+    let callCount = 0;
+    agent.runAgentCallback = () => {
+      callCount++;
+      if (callCount === 2) {
+        agent.setNewMessages([finalMessage]);
+      }
+    };
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(result.newMessages).toEqual([finalMessage]);
+  });
+
+  it("should handle multiple recursive follow-ups (chain)", async () => {
+    const tool1 = createTool({
+      name: "chainTool1",
+      handler: vi.fn(async () => "Result 1"),
+      followUp: true,
+    });
+    const tool2 = createTool({
+      name: "chainTool2",
+      handler: vi.fn(async () => "Result 2"),
+      followUp: true,
+    });
+    copilotKitCore.addTool(tool1);
+    copilotKitCore.addTool(tool2);
+
+    const msg1 = createToolCallMessage("chainTool1");
+    const msg2 = createToolCallMessage("chainTool2");
+    const finalMsg = createAssistantMessage({ content: "Done" });
+    
+    const agent = new MockAgent({ newMessages: [msg1] });
+    let callCount = 0;
+    agent.runAgentCallback = () => {
+      callCount++;
+      if (callCount === 2) {
+        agent.setNewMessages([msg2]);
+      } else if (callCount === 3) {
+        agent.setNewMessages([finalMsg]);
+      }
+    };
+
+    const result = await copilotKitCore.runAgent({ agent: agent as any });
+
+    expect(agent.runAgentCalls).toHaveLength(3);
+    expect(result.newMessages).toEqual([finalMsg]);
+  });
+});