@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/lib/copilot-task.ts

@@ -0,0 +1,201 @@
+/**
+ * This class is used to execute one-off tasks, for example on button press. It can use the context available via [useCopilotReadable](/reference/hooks/useCopilotReadable) and the actions provided by [useCopilotAction](/reference/hooks/useCopilotAction), or you can provide your own context and actions.
+ *
+ * ## Example
+ * In the simplest case, use CopilotTask in the context of your app by giving it instructions on what to do.
+ *
+ * ```tsx
+ * import { CopilotTask, useCopilotContext } from "@copilotkit/react-core";
+ *
+ * export function MyComponent() {
+ *   const context = useCopilotContext();
+ *
+ *   const task = new CopilotTask({
+ *     instructions: "Set a random message",
+ *     actions: [
+ *       {
+ *         name: "setMessage",
+ *       description: "Set the message.",
+ *       argumentAnnotations: [
+ *         {
+ *           name: "message",
+ *           type: "string",
+ *           description:
+ *             "A message to display.",
+ *           required: true,
+ *         },
+ *       ],
+ *      }
+ *     ]
+ *   });
+ *
+ *   const executeTask = async () => {
+ *     await task.run(context, action);
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={executeTask}>
+ *         Execute task
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * Have a look at the [Presentation Example App](https://github.com/CopilotKit/CopilotKit/blob/main/src/v1.x/examples/next-openai/src/app/presentation/page.tsx) for a more complete example.
+ */
+
+import {
+  ActionExecutionMessage,
+  CopilotRuntimeClient,
+  Message,
+  Role,
+  TextMessage,
+  convertGqlOutputToMessages,
+  convertMessagesToGqlInput,
+  filterAgentStateMessages,
+  CopilotRequestType,
+  ForwardedParametersInput,
+} from "@copilotkit/runtime-client-gql";
+import { FrontendAction, processActionsForRuntimeRequest } from "../types/frontend-action";
+import { CopilotContextParams } from "../context";
+import { defaultCopilotContextCategories } from "../components";
+
+export interface CopilotTaskConfig {
+  /**
+   * The instructions to be given to the assistant.
+   */
+  instructions: string;
+  /**
+   * An array of action definitions that can be called.
+   */
+  actions?: FrontendAction<any>[];
+  /**
+   * Whether to include the copilot readable context in the task.
+   */
+  includeCopilotReadable?: boolean;
+
+  /**
+   * Whether to include actions defined via useCopilotAction in the task.
+   */
+  includeCopilotActions?: boolean;
+
+  /**
+   * The forwarded parameters to use for the task.
+   */
+  forwardedParameters?: ForwardedParametersInput;
+}
+
+export class CopilotTask<T = any> {
+  private instructions: string;
+  private actions: FrontendAction<any>[];
+  private includeCopilotReadable: boolean;
+  private includeCopilotActions: boolean;
+  private forwardedParameters?: ForwardedParametersInput;
+  constructor(config: CopilotTaskConfig) {
+    this.instructions = config.instructions;
+    this.actions = config.actions || [];
+    this.includeCopilotReadable = config.includeCopilotReadable !== false;
+    this.includeCopilotActions = config.includeCopilotActions !== false;
+    this.forwardedParameters = config.forwardedParameters;
+  }
+
+  /**
+   * Run the task.
+   * @param context The CopilotContext to use for the task. Use `useCopilotContext` to obtain the current context.
+   * @param data The data to use for the task.
+   */
+  async run(context: CopilotContextParams, data?: T): Promise<void> {
+    const actions = this.includeCopilotActions ? Object.assign({}, context.actions) : {};
+
+    // merge functions into entry points
+    for (const fn of this.actions) {
+      actions[fn.name] = fn;
+    }
+
+    let contextString = "";
+
+    if (data) {
+      contextString = (typeof data === "string" ? data : JSON.stringify(data)) + "\n\n";
+    }
+
+    if (this.includeCopilotReadable) {
+      contextString += context.getContextString([], defaultCopilotContextCategories);
+    }
+
+    const systemMessage = new TextMessage({
+      content: taskSystemMessage(contextString, this.instructions),
+      role: Role.System,
+    });
+
+    const messages: Message[] = [systemMessage];
+
+    const runtimeClient = new CopilotRuntimeClient({
+      url: context.copilotApiConfig.chatApiEndpoint,
+      publicApiKey: context.copilotApiConfig.publicApiKey,
+      headers: context.copilotApiConfig.headers,
+      credentials: context.copilotApiConfig.credentials,
+    });
+
+    const response = await runtimeClient
+      .generateCopilotResponse({
+        data: {
+          frontend: {
+            actions: processActionsForRuntimeRequest(Object.values(actions)),
+            url: window.location.href,
+          },
+          messages: convertMessagesToGqlInput(filterAgentStateMessages(messages)),
+          metadata: {
+            requestType: CopilotRequestType.Task,
+          },
+          forwardedParameters: {
+            // if forwardedParameters is provided, use it
+            toolChoice: "required",
+            ...(this.forwardedParameters ?? {}),
+          },
+        },
+        properties: context.copilotApiConfig.properties,
+      })
+      .toPromise();
+
+    const functionCallHandler = context.getFunctionCallHandler(actions);
+    const functionCalls = convertGqlOutputToMessages(
+      response.data?.generateCopilotResponse?.messages || [],
+    ).filter((m): m is ActionExecutionMessage => m.isActionExecutionMessage());
+
+    for (const functionCall of functionCalls) {
+      await functionCallHandler({
+        messages,
+        name: functionCall.name,
+        args: functionCall.arguments,
+      });
+    }
+  }
+}
+
+function taskSystemMessage(contextString: string, instructions: string): string {
+  return `
+Please act as an efficient, competent, conscientious, and industrious professional assistant.
+
+Help the user achieve their goals, and you do so in a way that is as efficient as possible, without unnecessary fluff, but also without sacrificing professionalism.
+Always be polite and respectful, and prefer brevity over verbosity.
+
+The user has provided you with the following context:
+\`\`\`
+${contextString}
+\`\`\`
+
+They have also provided you with functions you can call to initiate actions on their behalf.
+
+Please assist them as best you can.
+
+This is not a conversation, so please do not ask questions. Just call a function without saying anything else.
+
+The user has given you the following task to complete:
+
+\`\`\`
+${instructions}
+\`\`\`
+`;
+}

package/src/lib/index.ts

@@ -0,0 +1 @@
+export * from "./copilot-task";

package/src/lib/status-checker.ts

@@ -0,0 +1,64 @@
+import {
+  COPILOT_CLOUD_API_URL,
+  COPILOT_CLOUD_PUBLIC_API_KEY_HEADER,
+  Severity,
+} from "@copilotkit/shared";
+
+const STATUS_CHECK_INTERVAL = 1000 * 60 * 5; // 5 minutes
+
+export type Status = {
+  severity: Severity;
+  message: string;
+};
+
+export class StatusChecker {
+  private activeKey: string | null = null;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private instanceCount = 0;
+  private lastResponse: Status | null = null;
+
+  async start(publicApiKey: string, onUpdate?: (status: Status | null) => void) {
+    this.instanceCount++;
+    if (this.activeKey === publicApiKey) return;
+
+    if (this.intervalId) clearInterval(this.intervalId);
+
+    const checkStatus = async () => {
+      try {
+        const response = await fetch(`${COPILOT_CLOUD_API_URL}/ciu`, {
+          method: "GET",
+          headers: {
+            [COPILOT_CLOUD_PUBLIC_API_KEY_HEADER]: publicApiKey,
+          },
+        }).then((response) => response.json() as Promise<Status>);
+        this.lastResponse = response;
+        onUpdate?.(response);
+        return response;
+      } catch (error) {
+        // Silently fail
+        return null;
+      }
+    };
+
+    const initialResponse = await checkStatus();
+    this.intervalId = setInterval(checkStatus, STATUS_CHECK_INTERVAL);
+    this.activeKey = publicApiKey;
+    return initialResponse;
+  }
+
+  getLastResponse() {
+    return this.lastResponse;
+  }
+
+  stop() {
+    this.instanceCount--;
+    if (this.instanceCount === 0) {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+        this.activeKey = null;
+        this.lastResponse = null;
+      }
+    }
+  }
+}

package/src/setupTests.ts

@@ -0,0 +1,26 @@
+// Mock modules that cause ES module issues
+jest.mock("@segment/analytics-node", () => ({
+  Analytics: jest.fn().mockImplementation(() => ({
+    track: jest.fn(),
+    identify: jest.fn(),
+    page: jest.fn(),
+    group: jest.fn(),
+    alias: jest.fn(),
+  })),
+}));
+
+jest.mock("@copilotkit/shared", () => ({
+  parseJson: jest.fn((jsonString, defaultValue) => {
+    try {
+      return JSON.parse(jsonString);
+    } catch {
+      return defaultValue;
+    }
+  }),
+  CopilotKitAgentDiscoveryError: jest.fn(),
+}));
+
+// Mock react-dom/test-utils to avoid compatibility issues
+jest.mock("react-dom/test-utils", () => ({
+  act: jest.fn((fn) => fn()),
+}));

package/src/types/chat-suggestion-configuration.ts

@@ -0,0 +1,23 @@
+export interface CopilotChatSuggestionConfiguration {
+  /**
+   * A prompt or instructions for the GPT to generate suggestions.
+   */
+  instructions: string;
+
+  /**
+   * The minimum number of suggestions to generate. Defaults to `1`.
+   * @default 1
+   */
+  minSuggestions?: number;
+
+  /**
+   * The maximum number of suggestions to generate. Defaults to `3`.
+   * @default 1
+   */
+  maxSuggestions?: number;
+
+  /**
+   * An optional class name to apply to the suggestions.
+   */
+  className?: string;
+}

package/src/types/coagent-action.ts

@@ -0,0 +1,31 @@
+export type CoAgentStateRenderProps<T> = {
+  state: T;
+  nodeName: string;
+  status: "inProgress" | "complete";
+};
+
+export type CoAgentStateRenderHandlerArguments<T> = {
+  nodeName: string;
+  state: T;
+};
+
+export interface CoAgentStateRender<T = any> {
+  /**
+   * The name of the coagent.
+   */
+  name: string;
+  /**
+   * The node name of the coagent.
+   */
+  nodeName?: string;
+  /**
+   * The handler function to handle the state of the agent.
+   */
+  handler?: (props: CoAgentStateRenderHandlerArguments<T>) => void | Promise<void>;
+  /**
+   * The render function to handle the state of the agent.
+   */
+  render?:
+    | ((props: CoAgentStateRenderProps<T>) => string | React.ReactElement | undefined | null)
+    | string;
+}

package/src/types/coagent-state.ts

@@ -0,0 +1,13 @@
+export interface CoagentState {
+  name: string;
+  state: any;
+  running: boolean;
+  active: boolean;
+  threadId?: string;
+  config?: {
+    configurable?: Record<string, any>;
+    [key: string]: any;
+  };
+  nodeName?: string;
+  runId?: string;
+}

package/src/types/crew.ts

@@ -0,0 +1,89 @@
+/**
+ * Status of a response or action that requires user input
+ */
+export type CrewsResponseStatus = "inProgress" | "complete" | "executing";
+
+/**
+ * Response data structure for the ResponseRenderer
+ */
+export interface CrewsResponse {
+  /**
+   * Unique identifier for the response
+   */
+  id: string;
+
+  /**
+   * The content of the response to display
+   */
+  content: string;
+
+  /**
+   * Optional metadata for the response
+   */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Base state item interface for agent state items
+ */
+export interface CrewsStateItem {
+  /**
+   * Unique identifier for the item
+   */
+  id: string;
+
+  /**
+   * Timestamp when the item was created
+   */
+  timestamp: string;
+}
+
+/**
+ * Tool execution state item
+ */
+export interface CrewsToolStateItem extends CrewsStateItem {
+  /**
+   * Name of the tool that was executed
+   */
+  tool: string;
+
+  /**
+   * Optional thought process for the tool execution
+   */
+  thought?: string;
+
+  /**
+   * Result of the tool execution
+   */
+  result?: any;
+}
+
+/**
+ * Task state item
+ */
+export interface CrewsTaskStateItem extends CrewsStateItem {
+  /**
+   * Name of the task
+   */
+  name: string;
+
+  /**
+   * Description of the task
+   */
+  description?: string;
+}
+
+/**
+ * AgentState containing information about steps and tasks
+ */
+export interface CrewsAgentState {
+  /**
+   * Array of tool execution steps
+   */
+  steps?: CrewsToolStateItem[];
+
+  /**
+   * Array of tasks
+   */
+  tasks?: CrewsTaskStateItem[];
+}

package/src/types/document-pointer.ts

@@ -0,0 +1,7 @@
+export interface DocumentPointer {
+  id: string;
+  name: string;
+  sourceApplication: string;
+  iconImageUri: string;
+  getContents: () => string;
+}

package/src/types/frontend-action.ts

@@ -0,0 +1,202 @@
+import { ActionInputAvailability } from "@copilotkit/runtime-client-gql";
+import {
+  Action,
+  Parameter,
+  MappedParameterTypes,
+  actionParametersToJsonSchema,
+} from "@copilotkit/shared";
+import React from "react";
+
+interface InProgressState<T extends Parameter[] | [] = []> {
+  status: "inProgress";
+  args: Partial<MappedParameterTypes<T>>;
+  result: undefined;
+}
+
+interface ExecutingState<T extends Parameter[] | [] = []> {
+  status: "executing";
+  args: MappedParameterTypes<T>;
+  result: undefined;
+}
+
+interface CompleteState<T extends Parameter[] | [] = []> {
+  status: "complete";
+  args: MappedParameterTypes<T>;
+  result: any;
+}
+
+interface InProgressStateNoArgs<T extends Parameter[] | [] = []> {
+  status: "inProgress";
+  args: Partial<MappedParameterTypes<T>>;
+  result: undefined;
+}
+
+interface ExecutingStateNoArgs<T extends Parameter[] | [] = []> {
+  status: "executing";
+  args: MappedParameterTypes<T>;
+  result: undefined;
+}
+
+interface CompleteStateNoArgs<T extends Parameter[] | [] = []> {
+  status: "complete";
+  args: MappedParameterTypes<T>;
+  result: any;
+}
+
+interface InProgressStateWait<T extends Parameter[] | [] = []> {
+  status: "inProgress";
+  args: Partial<MappedParameterTypes<T>>;
+  /** @deprecated use respond instead */
+  handler: undefined;
+  respond: undefined;
+  result: undefined;
+}
+
+interface ExecutingStateWait<T extends Parameter[] | [] = []> {
+  status: "executing";
+  args: MappedParameterTypes<T>;
+  /** @deprecated use respond instead */
+  handler: (result: any) => void;
+  respond: (result: any) => void;
+  result: undefined;
+}
+
+interface CompleteStateWait<T extends Parameter[] | [] = []> {
+  status: "complete";
+  args: MappedParameterTypes<T>;
+  /** @deprecated use respond instead */
+  handler: undefined;
+  respond: undefined;
+  result: any;
+}
+
+interface InProgressStateNoArgsWait<T extends Parameter[] | [] = []> {
+  status: "inProgress";
+  args: Partial<MappedParameterTypes<T>>;
+  /** @deprecated use respond instead */
+  handler: undefined;
+  respond: undefined;
+  result: undefined;
+}
+
+interface ExecutingStateNoArgsWait<T extends Parameter[] | [] = []> {
+  status: "executing";
+  args: MappedParameterTypes<T>;
+  /** @deprecated use respond instead */
+  handler: (result: any) => void;
+  respond: (result: any) => void;
+  result: undefined;
+}
+
+interface CompleteStateNoArgsWait<T extends Parameter[] | [] = []> {
+  status: "complete";
+  args: MappedParameterTypes<T>;
+  /** @deprecated use respond instead */
+  handler: undefined;
+  respond: undefined;
+}
+
+export type ActionRenderProps<T extends Parameter[] | [] = []> =
+  | CompleteState<T>
+  | ExecutingState<T>
+  | InProgressState<T>;
+
+export type ActionRenderPropsNoArgs<T extends Parameter[] | [] = []> =
+  | CompleteStateNoArgs<T>
+  | ExecutingStateNoArgs<T>
+  | InProgressStateNoArgs<T>;
+
+export type ActionRenderPropsWait<T extends Parameter[] | [] = []> =
+  | CompleteStateWait<T>
+  | ExecutingStateWait<T>
+  | InProgressStateWait<T>;
+
+export type ActionRenderPropsNoArgsWait<T extends Parameter[] | [] = []> =
+  | CompleteStateNoArgsWait<T>
+  | ExecutingStateNoArgsWait<T>
+  | InProgressStateNoArgsWait<T>;
+
+export type CatchAllActionRenderProps<T extends Parameter[] | [] = []> =
+  | (CompleteState<T> & {
+      name: string;
+    })
+  | (ExecutingState<T> & {
+      name: string;
+    })
+  | (InProgressState<T> & {
+      name: string;
+    });
+
+export type FrontendActionAvailability = "disabled" | "enabled" | "remote" | "frontend";
+
+export type FrontendAction<
+  T extends Parameter[] | [] = [],
+  N extends string = string,
+> = Action<T> & {
+  name: Exclude<N, "*">;
+  /**
+   * @deprecated Use `available` instead.
+   */
+  disabled?: boolean;
+  available?: FrontendActionAvailability;
+  pairedAction?: string;
+  followUp?: boolean;
+} & (
+    | {
+        render?:
+          | string
+          | (T extends []
+              ? (props: ActionRenderPropsNoArgs<T>) => string | React.ReactElement
+              : (props: ActionRenderProps<T>) => string | React.ReactElement);
+        /** @deprecated use renderAndWaitForResponse instead */
+        renderAndWait?: never;
+        renderAndWaitForResponse?: never;
+      }
+    | {
+        render?: never;
+        /** @deprecated use renderAndWaitForResponse instead */
+        renderAndWait?: T extends []
+          ? (props: ActionRenderPropsNoArgsWait<T>) => React.ReactElement
+          : (props: ActionRenderPropsWait<T>) => React.ReactElement;
+        renderAndWaitForResponse?: T extends []
+          ? (props: ActionRenderPropsNoArgsWait<T>) => React.ReactElement
+          : (props: ActionRenderPropsWait<T>) => React.ReactElement;
+        handler?: never;
+      }
+  );
+
+export type CatchAllFrontendAction = {
+  name: "*";
+  render: (props: CatchAllActionRenderProps<any>) => React.ReactElement;
+};
+
+export type RenderFunctionStatus = ActionRenderProps<any>["status"];
+
+export function processActionsForRuntimeRequest(actions: FrontendAction<any>[]) {
+  const filteredActions = actions
+    .filter(
+      (action) =>
+        action.available !== ActionInputAvailability.Disabled &&
+        action.disabled !== true &&
+        action.name !== "*" &&
+        action.available != "frontend" &&
+        !action.pairedAction,
+    )
+    .map((action) => {
+      let available: ActionInputAvailability | undefined = ActionInputAvailability.Enabled;
+      if (action.disabled) {
+        available = ActionInputAvailability.Disabled;
+      } else if (action.available === "disabled") {
+        available = ActionInputAvailability.Disabled;
+      } else if (action.available === "remote") {
+        available = ActionInputAvailability.Remote;
+      }
+      return {
+        name: action.name,
+        description: action.description || "",
+        jsonSchema: JSON.stringify(actionParametersToJsonSchema(action.parameters || [])),
+        available,
+      };
+    });
+  return filteredActions;
+}

package/src/types/index.ts

@@ -0,0 +1,17 @@
+export type { DocumentPointer } from "./document-pointer";
+export type { SystemMessageFunction } from "./system-message";
+export type {
+  ActionRenderProps,
+  ActionRenderPropsNoArgs,
+  ActionRenderPropsWait,
+  ActionRenderPropsNoArgsWait,
+  FrontendAction,
+  FrontendActionAvailability,
+  RenderFunctionStatus,
+  CatchAllActionRenderProps,
+  CatchAllFrontendAction,
+} from "./frontend-action";
+
+export type { CopilotChatSuggestionConfiguration } from "./chat-suggestion-configuration";
+export * from "./crew";
+export * from "./interrupt-action";