@agentxjs/core 1.9.1-dev

package/src/agent/types/message.ts

@@ -0,0 +1,387 @@
+/**
+ * Message Types - Content Parts and Message Types
+ *
+ * This file defines:
+ * - Content Parts: TextPart, ThinkingPart, ImagePart, FilePart, ToolCallPart, ToolResultPart
+ * - Message Types: UserMessage, AssistantMessage, ToolCallMessage, ToolResultMessage, ErrorMessage
+ * - Message Role and Subtype discriminators
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Content Parts
+// =============================================================================
+
+/**
+ * Text Part
+ *
+ * Plain text content in a message.
+ */
+export interface TextPart {
+  /** Content type discriminator */
+  type: "text";
+
+  /** The text content (supports Markdown) */
+  text: string;
+}
+
+/**
+ * Thinking Part
+ *
+ * AI's reasoning/thinking process (extended thinking).
+ */
+export interface ThinkingPart {
+  /** Content type discriminator */
+  type: "thinking";
+
+  /** The reasoning text */
+  reasoning: string;
+
+  /** Tokens used for thinking (optional) */
+  tokenCount?: number;
+}
+
+/**
+ * Image Part
+ *
+ * Image content in a message.
+ */
+export interface ImagePart {
+  /** Content type discriminator */
+  type: "image";
+
+  /** Image data (base64-encoded string or URL) */
+  data: string;
+
+  /** Image MIME type */
+  mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+
+  /** Optional image name/filename */
+  name?: string;
+}
+
+/**
+ * File Part
+ *
+ * File attachment in a message (PDF, documents, etc.).
+ */
+export interface FilePart {
+  /** Content type discriminator */
+  type: "file";
+
+  /** File data (base64-encoded string or URL) */
+  data: string;
+
+  /** File MIME type (IANA media type) */
+  mediaType: string;
+
+  /** Optional filename */
+  filename?: string;
+}
+
+/**
+ * Tool Call Part
+ *
+ * AI's request to invoke a tool.
+ */
+export interface ToolCallPart {
+  /** Content type discriminator */
+  type: "tool-call";
+
+  /** Unique identifier for this tool call */
+  id: string;
+
+  /** Tool name */
+  name: string;
+
+  /** Tool input parameters */
+  input: Record<string, unknown>;
+}
+
+/**
+ * Tool Result Output
+ *
+ * Enhanced tool result format supporting multiple output types.
+ * Based on Vercel AI SDK and industry best practices.
+ */
+export type ToolResultOutput =
+  /**
+   * Plain text result
+   */
+  | {
+      type: "text";
+      value: string;
+    }
+
+  /**
+   * JSON result
+   */
+  | {
+      type: "json";
+      value: unknown;
+    }
+
+  /**
+   * Text error
+   */
+  | {
+      type: "error-text";
+      value: string;
+    }
+
+  /**
+   * JSON error
+   */
+  | {
+      type: "error-json";
+      value: unknown;
+    }
+
+  /**
+   * User denied tool execution
+   */
+  | {
+      type: "execution-denied";
+      reason?: string;
+    }
+
+  /**
+   * Rich content (multiple parts)
+   */
+  | {
+      type: "content";
+      value: Array<TextPart | ImagePart | FilePart>;
+    };
+
+/**
+ * Tool Result Part
+ *
+ * Result of tool execution.
+ */
+export interface ToolResultPart {
+  /** Content type discriminator */
+  type: "tool-result";
+
+  /** Tool call ID this result corresponds to */
+  id: string;
+
+  /** Tool name */
+  name: string;
+
+  /** Tool execution output */
+  output: ToolResultOutput;
+}
+
+/**
+ * Content Part
+ *
+ * Discriminated union of all content part types.
+ * Used in messages to support multi-modal and complex content.
+ */
+export type ContentPart =
+  | TextPart
+  | ThinkingPart
+  | ImagePart
+  | FilePart
+  | ToolCallPart
+  | ToolResultPart;
+
+/**
+ * User Content Part
+ *
+ * Subset of ContentPart types that users can send in messages.
+ * - TextPart: Plain text content
+ * - ImagePart: Image attachments (JPEG, PNG, GIF, WebP)
+ * - FilePart: File attachments (PDF, documents, etc.)
+ */
+export type UserContentPart = TextPart | ImagePart | FilePart;
+
+// =============================================================================
+// Message Types
+// =============================================================================
+
+/**
+ * Message Role
+ *
+ * Represents who sent the message in the conversation.
+ * Five fundamental roles in the conversation.
+ */
+export type MessageRole = "user" | "assistant" | "tool" | "system" | "error";
+
+/**
+ * Message Subtype
+ *
+ * Represents the specific type/category of the message.
+ * Used together with role for serialization and type discrimination.
+ */
+export type MessageSubtype = "user" | "assistant" | "tool-call" | "tool-result" | "error";
+
+/**
+ * Token usage information
+ */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens?: number;
+}
+
+/**
+ * User Message
+ *
+ * Message sent by the user.
+ * Can contain simple text or rich content (text, images, files).
+ */
+export interface UserMessage {
+  /** Unique identifier */
+  id: string;
+
+  /** Message role */
+  role: "user";
+
+  /** Message subtype for serialization */
+  subtype: "user";
+
+  /** Message content - can be simple string or array of parts */
+  content: string | UserContentPart[];
+
+  /** When this message was created (Unix timestamp in milliseconds) */
+  timestamp: number;
+
+  /** Parent message ID for threading (optional) */
+  parentId?: string;
+}
+
+/**
+ * Assistant Message
+ *
+ * Message generated by the AI assistant.
+ * Contains text, thinking process, or files.
+ *
+ * Note: Tool calls are separate - use ToolCallMessage for tool invocations.
+ */
+export interface AssistantMessage {
+  /** Unique identifier */
+  id: string;
+
+  /** Message role */
+  role: "assistant";
+
+  /** Message subtype for serialization */
+  subtype: "assistant";
+
+  /** Message content - can be simple string or array of parts */
+  content: string | Array<TextPart | ThinkingPart | FilePart>;
+
+  /** When this message was created (Unix timestamp in milliseconds) */
+  timestamp: number;
+
+  /** Parent message ID for threading (optional) */
+  parentId?: string;
+
+  /** Token usage for this AI response (optional) */
+  usage?: TokenUsage;
+}
+
+/**
+ * Tool Call Message
+ *
+ * Represents AI's request to invoke a tool.
+ * Emitted when tool call parameters are fully assembled.
+ *
+ * Subject: Assistant (AI decided to call a tool)
+ * Timing: At tool_use_content_block_stop
+ */
+export interface ToolCallMessage {
+  /** Unique message identifier */
+  id: string;
+
+  /** Message role - assistant initiates tool calls */
+  role: "assistant";
+
+  /** Message subtype for serialization */
+  subtype: "tool-call";
+
+  /** Tool call details */
+  toolCall: ToolCallPart;
+
+  /** When this message was created (Unix timestamp in milliseconds) */
+  timestamp: number;
+
+  /** Parent message ID (the assistant message that triggered this) */
+  parentId?: string;
+}
+
+/**
+ * Tool Result Message
+ *
+ * Represents the result of tool execution.
+ * Emitted after tool execution completes.
+ *
+ * Subject: Tool (execution completed with result)
+ * Timing: At tool_result event
+ */
+export interface ToolResultMessage {
+  /** Unique message identifier */
+  id: string;
+
+  /** Message role - tool returns results */
+  role: "tool";
+
+  /** Message subtype for serialization */
+  subtype: "tool-result";
+
+  /** Tool result details */
+  toolResult: ToolResultPart;
+
+  /** ID of the corresponding tool call */
+  toolCallId: string;
+
+  /** When this message was created (Unix timestamp in milliseconds) */
+  timestamp: number;
+}
+
+/**
+ * Error Message
+ *
+ * Message representing an error that occurred during conversation.
+ * Displayed in the chat history so users can see what went wrong.
+ */
+export interface ErrorMessage {
+  /** Unique identifier */
+  id: string;
+
+  /** Message role */
+  role: "error";
+
+  /** Message subtype for serialization */
+  subtype: "error";
+
+  /** Error message content (human-readable) */
+  content: string;
+
+  /** Error code (e.g., "rate_limit_error", "api_error") */
+  errorCode?: string;
+
+  /** When this error occurred (Unix timestamp in milliseconds) */
+  timestamp: number;
+
+  /** Parent message ID for threading (optional) */
+  parentId?: string;
+}
+
+/**
+ * Message
+ *
+ * Discriminated union of all message types.
+ * Use `subtype` field for precise type discrimination.
+ *
+ * Role: Who sent it (user, assistant, tool, system, error)
+ * Subtype: What type of message (user, assistant, tool-call, tool-result, error)
+ */
+export type Message =
+  | UserMessage
+  | AssistantMessage
+  | ToolCallMessage
+  | ToolResultMessage
+  | ErrorMessage;

package/src/common/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Common utilities module
+ *
+ * Re-exports from commonxjs for backward compatibility.
+ * Prefer importing directly from "commonxjs/logger".
+ */
+
+export * from "commonxjs/logger";

package/src/common/logger/ConsoleLogger.ts

@@ -0,0 +1,137 @@
+/**
+ * ConsoleLogger - Default logger implementation
+ *
+ * Simple console-based logger with color support.
+ * Used as fallback when no custom LoggerFactory is provided.
+ */
+
+import type { Logger, LogContext, LogLevel } from "./types";
+
+export interface ConsoleLoggerOptions {
+  level?: LogLevel;
+  colors?: boolean;
+  timestamps?: boolean;
+}
+
+export class ConsoleLogger implements Logger {
+  readonly name: string;
+  readonly level: LogLevel;
+  private readonly colors: boolean;
+  private readonly timestamps: boolean;
+
+  private static readonly COLORS = {
+    DEBUG: "\x1b[36m",
+    INFO: "\x1b[32m",
+    WARN: "\x1b[33m",
+    ERROR: "\x1b[31m",
+    RESET: "\x1b[0m",
+  };
+
+  constructor(name: string, options: ConsoleLoggerOptions = {}) {
+    this.name = name;
+    this.level = options.level ?? "info";
+    this.colors = options.colors ?? this.isNodeEnvironment();
+    this.timestamps = options.timestamps ?? true;
+  }
+
+  debug(message: string, context?: LogContext): void {
+    if (this.isDebugEnabled()) {
+      this.log("DEBUG", message, context);
+    }
+  }
+
+  info(message: string, context?: LogContext): void {
+    if (this.isInfoEnabled()) {
+      this.log("INFO", message, context);
+    }
+  }
+
+  warn(message: string, context?: LogContext): void {
+    if (this.isWarnEnabled()) {
+      this.log("WARN", message, context);
+    }
+  }
+
+  error(message: string | Error, context?: LogContext): void {
+    if (this.isErrorEnabled()) {
+      if (message instanceof Error) {
+        this.log("ERROR", message.message, { ...context, stack: message.stack });
+      } else {
+        this.log("ERROR", message, context);
+      }
+    }
+  }
+
+  isDebugEnabled(): boolean {
+    return this.getLevelValue(this.level) <= this.getLevelValue("debug");
+  }
+
+  isInfoEnabled(): boolean {
+    return this.getLevelValue(this.level) <= this.getLevelValue("info");
+  }
+
+  isWarnEnabled(): boolean {
+    return this.getLevelValue(this.level) <= this.getLevelValue("warn");
+  }
+
+  isErrorEnabled(): boolean {
+    return this.getLevelValue(this.level) <= this.getLevelValue("error");
+  }
+
+  private getLevelValue(level: LogLevel): number {
+    const levels: Record<LogLevel, number> = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      silent: 4,
+    };
+    return levels[level];
+  }
+
+  private log(level: string, message: string, context?: LogContext): void {
+    const parts: string[] = [];
+
+    if (this.timestamps) {
+      parts.push(new Date().toISOString());
+    }
+
+    if (this.colors) {
+      const color = ConsoleLogger.COLORS[level as keyof typeof ConsoleLogger.COLORS];
+      parts.push(`${color}${level.padEnd(5)}${ConsoleLogger.COLORS.RESET}`);
+    } else {
+      parts.push(level.padEnd(5));
+    }
+
+    parts.push(`[${this.name}]`);
+    parts.push(message);
+
+    const logLine = parts.join(" ");
+    const consoleMethod = this.getConsoleMethod(level);
+
+    if (context && Object.keys(context).length > 0) {
+      consoleMethod(logLine, context);
+    } else {
+      consoleMethod(logLine);
+    }
+  }
+
+  private getConsoleMethod(level: string): (...args: unknown[]) => void {
+    switch (level) {
+      case "DEBUG":
+        return console.debug.bind(console);
+      case "INFO":
+        return console.info.bind(console);
+      case "WARN":
+        return console.warn.bind(console);
+      case "ERROR":
+        return console.error.bind(console);
+      default:
+        return console.log.bind(console);
+    }
+  }
+
+  private isNodeEnvironment(): boolean {
+    return typeof process !== "undefined" && process.versions?.node !== undefined;
+  }
+}

package/src/common/logger/LoggerFactoryImpl.ts

@@ -0,0 +1,123 @@
+/**
+ * LoggerFactoryImpl - Central factory for creating logger instances
+ *
+ * Implements lazy initialization pattern:
+ * - createLogger() can be called at module level (before config)
+ * - Real logger is created on first use
+ * - External LoggerFactory can be injected via Runtime
+ */
+
+import type { Logger, LoggerFactory, LogContext, LogLevel } from "./types";
+import { ConsoleLogger, type ConsoleLoggerOptions } from "./ConsoleLogger";
+
+// External factory injected via Runtime
+let externalFactory: LoggerFactory | null = null;
+
+// Version counter to invalidate cached real loggers
+let factoryVersion = 0;
+
+export interface LoggerFactoryConfig {
+  defaultImplementation?: (name: string) => Logger;
+  defaultLevel?: LogLevel;
+  consoleOptions?: Omit<ConsoleLoggerOptions, "level">;
+}
+
+/**
+ * Internal LoggerFactory implementation
+ *
+ * Uses lazy proxy pattern to allow module-level createLogger() calls.
+ */
+export class LoggerFactoryImpl {
+  private static loggers: Map<string, Logger> = new Map();
+  private static config: LoggerFactoryConfig = {
+    defaultLevel: "info",
+  };
+
+  static getLogger(nameOrClass: string | (new (...args: unknown[]) => unknown)): Logger {
+    const name = typeof nameOrClass === "string" ? nameOrClass : nameOrClass.name;
+
+    if (this.loggers.has(name)) {
+      return this.loggers.get(name)!;
+    }
+
+    const lazyLogger = this.createLazyLogger(name);
+    this.loggers.set(name, lazyLogger);
+    return lazyLogger;
+  }
+
+  static configure(config: LoggerFactoryConfig): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  static reset(): void {
+    this.loggers.clear();
+    this.config = { defaultLevel: "info" };
+    externalFactory = null;
+    factoryVersion++; // Invalidate all cached real loggers
+  }
+
+  private static createLazyLogger(name: string): Logger {
+    let realLogger: Logger | null = null;
+    let loggerVersion = -1; // Track which factory version created this logger
+
+    const getRealLogger = (): Logger => {
+      // Recreate logger if factory version changed (setLoggerFactory was called)
+      if (!realLogger || loggerVersion !== factoryVersion) {
+        realLogger = this.createLogger(name);
+        loggerVersion = factoryVersion;
+      }
+      return realLogger;
+    };
+
+    return {
+      name,
+      level: this.config.defaultLevel || "info",
+      debug: (message: string, context?: LogContext) => getRealLogger().debug(message, context),
+      info: (message: string, context?: LogContext) => getRealLogger().info(message, context),
+      warn: (message: string, context?: LogContext) => getRealLogger().warn(message, context),
+      error: (message: string | Error, context?: LogContext) =>
+        getRealLogger().error(message, context),
+      isDebugEnabled: () => getRealLogger().isDebugEnabled(),
+      isInfoEnabled: () => getRealLogger().isInfoEnabled(),
+      isWarnEnabled: () => getRealLogger().isWarnEnabled(),
+      isErrorEnabled: () => getRealLogger().isErrorEnabled(),
+    };
+  }
+
+  private static createLogger(name: string): Logger {
+    if (externalFactory) {
+      return externalFactory.getLogger(name);
+    }
+
+    if (this.config.defaultImplementation) {
+      return this.config.defaultImplementation(name);
+    }
+
+    return new ConsoleLogger(name, {
+      level: this.config.defaultLevel,
+      ...this.config.consoleOptions,
+    });
+  }
+}
+
+/**
+ * Set external LoggerFactory (called by Runtime initialization)
+ */
+export function setLoggerFactory(factory: LoggerFactory): void {
+  externalFactory = factory;
+  LoggerFactoryImpl.reset();
+  externalFactory = factory;
+}
+
+/**
+ * Create a logger instance
+ *
+ * Safe to call at module level before Runtime is configured.
+ * Uses lazy initialization - actual logger is created on first use.
+ *
+ * @param name - Logger name (hierarchical, e.g., "engine/AgentEngine")
+ * @returns Logger instance (lazy proxy)
+ */
+export function createLogger(name: string): Logger {
+  return LoggerFactoryImpl.getLogger(name);
+}

package/src/common/logger/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Logger module
+ *
+ * Internal logger implementation for AgentX platform.
+ * Provides lazy-initialized logging with pluggable backends.
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from "@anthropic-ai/sdk-core/common";
+ *
+ * // Safe at module level (before Runtime configured)
+ * const logger = createLogger("engine/AgentEngine");
+ *
+ * // Later, at runtime
+ * logger.info("Agent initialized", { agentId: "xxx" });
+ * ```
+ */
+
+export type { Logger, LoggerFactory, LogContext, LogLevel } from "./types";
+export { ConsoleLogger, type ConsoleLoggerOptions } from "./ConsoleLogger";
+export {
+  LoggerFactoryImpl,
+  type LoggerFactoryConfig,
+  setLoggerFactory,
+  createLogger,
+} from "./LoggerFactoryImpl";