@copilotkit/shared 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/types/action.ts

@@ -0,0 +1,129 @@
+type TypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  object: object;
+  "string[]": string[];
+  "number[]": number[];
+  "boolean[]": boolean[];
+  "object[]": object[];
+};
+
+type AbstractParameter = {
+  name: string;
+  type?: keyof TypeMap;
+  description?: string;
+  required?: boolean;
+};
+
+interface StringParameter extends AbstractParameter {
+  type: "string";
+  enum?: string[];
+}
+
+interface ObjectParameter extends AbstractParameter {
+  type: "object";
+  attributes?: Parameter[];
+}
+
+interface ObjectArrayParameter extends AbstractParameter {
+  type: "object[]";
+  attributes?: Parameter[];
+}
+
+type SpecialParameters = StringParameter | ObjectParameter | ObjectArrayParameter;
+interface BaseParameter extends AbstractParameter {
+  type?: Exclude<AbstractParameter["type"], SpecialParameters["type"]>;
+}
+
+export type Parameter = BaseParameter | SpecialParameters;
+
+type OptionalParameterType<P extends AbstractParameter> = P["required"] extends false
+  ? undefined
+  : never;
+
+type StringParameterType<P> = P extends StringParameter
+  ? P extends { enum?: Array<infer E> }
+    ? E
+    : string
+  : never;
+
+type ObjectParameterType<P> = P extends ObjectParameter
+  ? P extends { attributes?: infer Attributes extends Parameter[] }
+    ? MappedParameterTypes<Attributes>
+    : object
+  : never;
+
+type ObjectArrayParameterType<P> = P extends ObjectArrayParameter
+  ? P extends { attributes?: infer Attributes extends Parameter[] }
+    ? MappedParameterTypes<Attributes>[]
+    : any[]
+  : never;
+
+type MappedTypeOrString<T> = T extends keyof TypeMap ? TypeMap[T] : string;
+type BaseParameterType<P extends AbstractParameter> = P extends { type: infer T }
+  ? T extends BaseParameter["type"]
+    ? MappedTypeOrString<T>
+    : never
+  : string;
+
+export type MappedParameterTypes<T extends Parameter[] | [] = []> = T extends []
+  ? Record<string, any>
+  : {
+      [P in T[number] as P["name"]]:
+        | OptionalParameterType<P>
+        | StringParameterType<P>
+        | ObjectParameterType<P>
+        | ObjectArrayParameterType<P>
+        | BaseParameterType<P>;
+    };
+
+export type Action<T extends Parameter[] | [] = []> = {
+  name: string;
+  description?: string;
+  parameters?: T;
+  handler?: T extends []
+    ? () => any | Promise<any>
+    : (args: MappedParameterTypes<T>) => any | Promise<any>;
+  additionalConfig?: Record<string, any>;
+};
+
+// This is the original "ceiling is being raised" version of MappedParameterTypes.
+//
+// ceiling is being raised. cursor's copilot helped us write "superhuman code"
+// for a critical feature. We can read this code, but VERY few engineers out
+// there could write it from scratch.
+// Took lots of convincing too. "come on, this must be possible, try harder".
+// and obviously- done in parts.
+//
+// - https://twitter.com/ataiiam/status/1765089261374914957
+//   (Mar 5, 2024)
+//
+// export type MappedParameterTypes<T extends Parameter[]> = {
+//   // Check if the parameter has an 'enum' defined
+//   [P in T[number] as P["name"]]: P extends { enum: Array<infer E> }
+//     ? E extends string // Ensure the enum values are strings
+//       ? P["required"] extends false // Check if the parameter is optional
+//         ? E | undefined // If so, include 'undefined' in the type
+//         : E // Otherwise, use the enum type directly
+//       : never // This case should not occur since 'enum' implies string values
+//     : // Handle parameters defined as 'object' with specified attributes
+//     P extends { type: "object"; attributes: infer Attributes }
+//     ? Attributes extends Parameter[]
+//       ? MappedParameterTypes<Attributes> // Recursively map the attributes of the object
+//       : never // If 'attributes' is not an array of Parameters, this is invalid
+//     : // Handle parameters defined as 'object[]' without specified attributes
+//     P extends { type: "object[]"; attributes?: never }
+//     ? any[] // Default to 'any[]' for arrays of objects without specific attributes
+//     : // Handle parameters defined as 'object[]' with specified attributes
+//     P extends { type: "object[]"; attributes: infer Attributes }
+//     ? Attributes extends Parameter[]
+//       ? MappedParameterTypes<Attributes>[] // Recursively map each object in the array
+//       : any[] // Default to 'any[]' if attributes are not properly defined
+//     : // Handle all other parameter types
+//     P["required"] extends false
+//     ? // Include 'undefined' for optional parameters
+//       TypeMap[P["type"] extends keyof TypeMap ? P["type"] : "string"] | undefined
+//     : // Use the direct mapping from 'TypeMap' for the parameter's type
+//       TypeMap[P["type"] extends keyof TypeMap ? P["type"] : "string"];
+// };

package/src/types/copilot-cloud-config.ts

@@ -0,0 +1,11 @@
+export interface CopilotCloudConfig {
+  guardrails: {
+    input: {
+      restrictToTopic: {
+        enabled: boolean;
+        validTopics: string[];
+        invalidTopics: string[];
+      };
+    };
+  };
+}

package/src/types/error.ts

@@ -0,0 +1,70 @@
+export interface CopilotErrorEvent {
+  type: "error" | "request" | "response" | "agent_state" | "action" | "message" | "performance";
+  timestamp: number;
+  context: CopilotRequestContext;
+  error?: any; // Present when type is 'error'
+}
+
+export interface CopilotRequestContext {
+  // Basic identifiers
+  threadId?: string;
+  runId?: string;
+  source: "runtime" | "ui" | "agent" | "network";
+
+  // Request details
+  request?: {
+    operation: string;
+    method?: string;
+    url?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: any;
+    startTime: number;
+  };
+
+  // Response details
+  response?: {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    body?: any;
+    endTime: number;
+    latency: number;
+  };
+
+  // Agent context
+  agent?: {
+    name?: string;
+    nodeName?: string;
+    state?: any;
+  };
+
+  // Message flow context
+  messages?: {
+    input?: any[];
+    output?: any[];
+    messageCount?: number;
+  };
+
+  // Technical context
+  technical?: {
+    userAgent?: string;
+    host?: string;
+    environment?: string;
+    version?: string;
+    stackTrace?: string;
+  };
+
+  // Performance metrics
+  performance?: {
+    requestDuration?: number;
+    streamingDuration?: number;
+    actionExecutionTime?: number;
+    memoryUsage?: number;
+  };
+
+  // Extensible metadata
+  metadata?: Record<string, any>;
+}
+
+export type CopilotErrorHandler = (errorEvent: CopilotErrorEvent) => void | Promise<void>;

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from "./openai-assistant";
+export * from "./action";
+export * from "./copilot-cloud-config";
+export * from "./utility";
+export * from "./error";
+export * from "./message";

package/src/types/message.ts

@@ -0,0 +1,37 @@
+import agui from "@ag-ui/core";
+
+export interface ImageData {
+  format: string;
+  bytes: string;
+}
+
+// Pass through types
+export type Role = agui.Role;
+export type SystemMessage = agui.SystemMessage;
+export type DeveloperMessage = agui.DeveloperMessage;
+export type ToolCall = agui.ToolCall;
+export type ActivityMessage = agui.ActivityMessage;
+
+// Extended message types
+export type ToolResult = agui.ToolMessage & {
+  toolName?: string;
+};
+
+export type AIMessage = agui.AssistantMessage & {
+  generativeUI?: (props?: any) => any;
+  agentName?: string;
+  state?: any;
+  image?: ImageData;
+};
+
+export type UserMessage = agui.UserMessage & {
+  image?: ImageData;
+};
+
+export type Message =
+  | AIMessage
+  | ToolResult
+  | UserMessage
+  | SystemMessage
+  | DeveloperMessage
+  | ActivityMessage;

package/src/types/openai-assistant.ts

@@ -0,0 +1,62 @@
+export interface FunctionDefinition {
+  /**
+   * The name of the function to be called. Must be a-z, A-Z, 0-9, or contain
+   * underscores and dashes, with a maximum length of 64.
+   */
+  name: string;
+  /**
+   * The parameters the functions accepts, described as a JSON Schema object. See the
+   * [guide](/docs/guides/gpt/function-calling) for examples, and the
+   * [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
+   * documentation about the format.
+   *
+   * To describe a function that accepts no parameters, provide the value
+   * `{"type": "object", "properties": {}}`.
+   */
+  parameters: Record<string, unknown>;
+  /**
+   * A description of what the function does, used by the model to choose when and
+   * how to call the function.
+   */
+  description?: string;
+}
+
+export interface ToolDefinition {
+  type: "function";
+  function: FunctionDefinition;
+}
+
+export interface FunctionCallHandlerArguments {
+  messages: any[];
+  name: string;
+  args: any;
+}
+
+export type FunctionCallHandler = (args: FunctionCallHandlerArguments) => Promise<any>;
+
+export type CoAgentStateRenderHandlerArguments = {
+  name: string;
+  nodeName: string;
+  state: any;
+};
+
+export type CoAgentStateRenderHandler = (args: CoAgentStateRenderHandlerArguments) => Promise<any>;
+
+export type AssistantMessage = {
+  id: string;
+  role: "assistant";
+  content: Array<{
+    type: "text";
+    text: {
+      value: string;
+    };
+  }>;
+};
+
+export type JSONValue =
+  | null
+  | string
+  | number
+  | boolean
+  | { [x: string]: JSONValue }
+  | Array<JSONValue>;

package/src/types/utility.ts

@@ -0,0 +1,2 @@
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type RequiredBy<T, K extends keyof T> = T & { [P in K]-?: T[P] };

package/src/utils/conditions.ts

@@ -0,0 +1,98 @@
+export type ComparisonRule =
+  | "EQUALS"
+  | "NOT_EQUALS"
+  | "GREATER_THAN"
+  | "LESS_THAN"
+  | "CONTAINS"
+  | "NOT_CONTAINS"
+  | "MATCHES"
+  | "STARTS_WITH"
+  | "ENDS_WITH";
+export type LogicalRule = "AND" | "OR" | "NOT";
+export type ExistenceRule = "EXISTS" | "NOT_EXISTS";
+
+export type Rule = ComparisonRule | LogicalRule | ExistenceRule;
+
+export interface BaseCondition {
+  rule: Rule;
+  path?: string;
+}
+
+export interface ComparisonCondition extends BaseCondition {
+  rule: ComparisonRule;
+  value: any;
+}
+
+export interface LogicalCondition extends BaseCondition {
+  rule: LogicalRule;
+  conditions: Condition[];
+}
+
+export interface ExistenceCondition extends BaseCondition {
+  rule: ExistenceRule;
+}
+
+export type Condition = ComparisonCondition | LogicalCondition | ExistenceCondition;
+
+export function executeConditions({
+  conditions,
+  value,
+}: {
+  conditions?: Condition[];
+  value: any;
+}): boolean {
+  // If no conditions, consider it a pass
+  if (!conditions?.length) return true;
+
+  // Run all conditions (implicit AND)
+  return conditions.every((condition) => executeCondition(condition, value));
+}
+
+function executeCondition(condition: Condition, value: any): boolean {
+  const targetValue = condition.path ? getValueFromPath(value, condition.path) : value;
+
+  switch (condition.rule) {
+    // Logical
+    case "AND":
+      return (condition as LogicalCondition).conditions.every((c) => executeCondition(c, value));
+    case "OR":
+      return (condition as LogicalCondition).conditions.some((c) => executeCondition(c, value));
+    case "NOT":
+      return !(condition as LogicalCondition).conditions.every((c) => executeCondition(c, value));
+
+    // Comparison
+    case "EQUALS":
+      return targetValue === (condition as ComparisonCondition).value;
+    case "NOT_EQUALS":
+      return targetValue !== (condition as ComparisonCondition).value;
+    case "GREATER_THAN":
+      return targetValue > (condition as ComparisonCondition).value;
+    case "LESS_THAN":
+      return targetValue < (condition as ComparisonCondition).value;
+    case "CONTAINS":
+      return (
+        Array.isArray(targetValue) && targetValue.includes((condition as ComparisonCondition).value)
+      );
+    case "NOT_CONTAINS":
+      return (
+        Array.isArray(targetValue) &&
+        !targetValue.includes((condition as ComparisonCondition).value)
+      );
+    case "MATCHES":
+      return new RegExp((condition as ComparisonCondition).value).test(String(targetValue));
+    case "STARTS_WITH":
+      return String(targetValue).startsWith((condition as ComparisonCondition).value);
+    case "ENDS_WITH":
+      return String(targetValue).endsWith((condition as ComparisonCondition).value);
+
+    // Existence
+    case "EXISTS":
+      return targetValue !== undefined && targetValue !== null;
+    case "NOT_EXISTS":
+      return targetValue === undefined || targetValue === null;
+  }
+}
+
+function getValueFromPath(obj: any, path: string): any {
+  return path.split(".").reduce((acc, part) => acc?.[part], obj);
+}

package/src/utils/console-styling.ts

@@ -0,0 +1,124 @@
+/**
+ * Console styling utilities for CopilotKit branded messages
+ * Provides consistent, readable colors across light and dark console themes
+ */
+
+/**
+ * Color palette optimized for console readability
+ */
+export const ConsoleColors = {
+  /** Primary brand blue - for titles and links */
+  primary: "#007acc",
+  /** Success green - for positive messaging */
+  success: "#22c55e",
+  /** Purple - for feature highlights */
+  feature: "#a855f7",
+  /** Red - for calls-to-action */
+  cta: "#ef4444",
+  /** Cyan - for closing statements */
+  info: "#06b6d4",
+  /** Inherit console default - for body text */
+  inherit: "inherit",
+  /** Warning style */
+  warning: "#f59e0b",
+} as const;
+
+/**
+ * Console style templates for common patterns
+ */
+export const ConsoleStyles = {
+  /** Large header style */
+  header: `color: ${ConsoleColors.warning}; font-weight: bold; font-size: 16px;`,
+  /** Section header style */
+  section: `color: ${ConsoleColors.success}; font-weight: bold;`,
+  /** Feature highlight style */
+  highlight: `color: ${ConsoleColors.feature}; font-weight: bold;`,
+  /** Call-to-action style */
+  cta: `color: ${ConsoleColors.success}; font-weight: bold;`,
+  /** Info style */
+  info: `color: ${ConsoleColors.info}; font-weight: bold;`,
+  /** Link style */
+  link: `color: ${ConsoleColors.primary}; text-decoration: underline;`,
+  /** Body text - inherits console theme */
+  body: `color: ${ConsoleColors.inherit};`,
+  /** Warning style */
+  warning: `color: ${ConsoleColors.cta}; font-weight: bold;`,
+} as const;
+
+/**
+ * Styled console message for CopilotKit Platform promotion
+ * Displays a beautiful, branded advertisement in the console
+ */
+export function logCopilotKitPlatformMessage() {
+  console.log(
+    `%cCopilotKit Warning%c
+
+useCopilotChatHeadless_c provides full compatibility with CopilotKit's newly released Headless UI feature set. To enable this premium feature, add your public license key, available for free at:
+
+%chttps://cloud.copilotkit.ai%c
+
+Alternatively, useCopilotChat is available for basic programmatic control, and does not require an API key.
+
+To learn more about premium features, read the documentation here:
+
+%chttps://docs.copilotkit.ai/premium%c`,
+    ConsoleStyles.header,
+    ConsoleStyles.body,
+    ConsoleStyles.cta,
+    ConsoleStyles.body,
+    ConsoleStyles.link,
+    ConsoleStyles.body,
+  );
+}
+
+export function publicApiKeyRequired(feature: string) {
+  console.log(
+    `
+%cCopilotKit Warning%c \n
+In order to use ${feature}, you need to add your CopilotKit API key, available for free at https://cloud.copilotkit.ai.
+    `.trim(),
+    ConsoleStyles.header,
+    ConsoleStyles.body,
+  );
+}
+
+/**
+ * Create a styled console message with custom content
+ *
+ * @param template - Template string with %c placeholders
+ * @param styles - Array of style strings matching the %c placeholders
+ *
+ * @example
+ * ```typescript
+ * logStyled(
+ *   '%cCopilotKit%c Welcome to the platform!',
+ *   [ConsoleStyles.header, ConsoleStyles.body]
+ * );
+ * ```
+ */
+export function logStyled(template: string, styles: string[]) {
+  console.log(template, ...styles);
+}
+
+/**
+ * Quick styled console methods for common use cases
+ */
+export const styledConsole = {
+  /** Log a success message */
+  success: (message: string) => logStyled(`%c✅ ${message}`, [ConsoleStyles.section]),
+
+  /** Log an info message */
+  info: (message: string) => logStyled(`%cℹ️ ${message}`, [ConsoleStyles.info]),
+
+  /** Log a feature highlight */
+  feature: (message: string) => logStyled(`%c✨ ${message}`, [ConsoleStyles.highlight]),
+
+  /** Log a call-to-action */
+  cta: (message: string) => logStyled(`%c🚀 ${message}`, [ConsoleStyles.cta]),
+
+  /** Log the CopilotKit platform promotion */
+  logCopilotKitPlatformMessage: logCopilotKitPlatformMessage,
+
+  /** Log a `publicApiKeyRequired` warning */
+  publicApiKeyRequired: publicApiKeyRequired,
+} as const;