@agentxjs/core 1.9.10-dev → 2.0.1

package/src/event/types/session.ts

@@ -13,38 +13,35 @@ import type { SystemEvent } from "./base";
 /**
  * Base SessionLifecycleEvent
  */
-interface BaseSessionLifecycleEvent<T extends string, D = unknown> extends SystemEvent<
-  T,
-  D,
-  "session",
-  "lifecycle",
-  "notification"
-> {}
+interface BaseSessionLifecycleEvent<T extends string, D = unknown>
+  extends SystemEvent<T, D, "session", "lifecycle", "notification"> {}
 
 /**
  * SessionCreatedEvent - Session was created
  */
-export interface SessionCreatedEvent extends BaseSessionLifecycleEvent<
-  "session_created",
-  {
-    sessionId: string;
-    imageId: string;
-    containerId: string;
-    title?: string;
-    createdAt: number;
-  }
-> {}
+export interface SessionCreatedEvent
+  extends BaseSessionLifecycleEvent<
+    "session_created",
+    {
+      sessionId: string;
+      imageId: string;
+      containerId: string;
+      title?: string;
+      createdAt: number;
+    }
+  > {}
 
 /**
  * SessionDestroyedEvent - Session was destroyed
  */
-export interface SessionDestroyedEvent extends BaseSessionLifecycleEvent<
-  "session_destroyed",
-  {
-    sessionId: string;
-    reason?: string;
-  }
-> {}
+export interface SessionDestroyedEvent
+  extends BaseSessionLifecycleEvent<
+    "session_destroyed",
+    {
+      sessionId: string;
+      reason?: string;
+    }
+  > {}
 
 /**
  * SessionLifecycleEvent - All session lifecycle events
@@ -68,72 +65,66 @@ export function isSessionLifecycleEvent(event: {
 /**
  * Base SessionPersistRequest
  */
-interface BaseSessionPersistRequest<T extends string, D = unknown> extends SystemEvent<
-  T,
-  D,
-  "session",
-  "persist",
-  "request"
-> {}
+interface BaseSessionPersistRequest<T extends string, D = unknown>
+  extends SystemEvent<T, D, "session", "persist", "request"> {}
 
 /**
  * Base SessionPersistResult
  */
-interface BaseSessionPersistResult<T extends string, D = unknown> extends SystemEvent<
-  T,
-  D,
-  "session",
-  "persist",
-  "result"
-> {}
+interface BaseSessionPersistResult<T extends string, D = unknown>
+  extends SystemEvent<T, D, "session", "persist", "result"> {}
 
 /**
  * SessionSaveRequest - Request to save session
  */
-export interface SessionSaveRequest extends BaseSessionPersistRequest<
-  "session_save_request",
-  {
-    sessionId: string;
-    title?: string;
-    metadata?: Record<string, unknown>;
-  }
-> {}
+export interface SessionSaveRequest
+  extends BaseSessionPersistRequest<
+    "session_save_request",
+    {
+      sessionId: string;
+      title?: string;
+      metadata?: Record<string, unknown>;
+    }
+  > {}
 
 /**
  * SessionSavedEvent - Session was saved
  */
-export interface SessionSavedEvent extends BaseSessionPersistResult<
-  "session_saved",
-  {
-    sessionId: string;
-    savedAt: number;
-  }
-> {}
+export interface SessionSavedEvent
+  extends BaseSessionPersistResult<
+    "session_saved",
+    {
+      sessionId: string;
+      savedAt: number;
+    }
+  > {}
 
 /**
  * MessagePersistRequest - Request to persist a message
  */
-export interface MessagePersistRequest extends BaseSessionPersistRequest<
-  "message_persist_request",
-  {
-    sessionId: string;
-    messageId: string;
-    role: "user" | "assistant" | "tool_call" | "tool_result";
-    content: unknown;
-  }
-> {}
+export interface MessagePersistRequest
+  extends BaseSessionPersistRequest<
+    "message_persist_request",
+    {
+      sessionId: string;
+      messageId: string;
+      role: "user" | "assistant" | "tool_call" | "tool_result";
+      content: unknown;
+    }
+  > {}
 
 /**
  * MessagePersistedEvent - Message was persisted
  */
-export interface MessagePersistedEvent extends BaseSessionPersistResult<
-  "message_persisted",
-  {
-    sessionId: string;
-    messageId: string;
-    savedAt: number;
-  }
-> {}
+export interface MessagePersistedEvent
+  extends BaseSessionPersistResult<
+    "message_persisted",
+    {
+      sessionId: string;
+      messageId: string;
+      savedAt: number;
+    }
+  > {}
 
 /**
  * SessionPersistEvent - All session persist events
@@ -171,94 +162,90 @@ export function isSessionPersistEvent(event: {
 /**
  * Base SessionActionRequest
  */
-interface BaseSessionActionRequest<T extends string, D = unknown> extends SystemEvent<
-  T,
-  D,
-  "session",
-  "action",
-  "request"
-> {}
+interface BaseSessionActionRequest<T extends string, D = unknown>
+  extends SystemEvent<T, D, "session", "action", "request"> {}
 
 /**
  * Base SessionActionResult
  */
-interface BaseSessionActionResult<T extends string, D = unknown> extends SystemEvent<
-  T,
-  D,
-  "session",
-  "action",
-  "result"
-> {}
+interface BaseSessionActionResult<T extends string, D = unknown>
+  extends SystemEvent<T, D, "session", "action", "result"> {}
 
 /**
  * SessionResumeRequest - Request to resume a session
  */
-export interface SessionResumeRequest extends BaseSessionActionRequest<
-  "session_resume_request",
-  {
-    sessionId: string;
-    containerId?: string;
-  }
-> {}
+export interface SessionResumeRequest
+  extends BaseSessionActionRequest<
+    "session_resume_request",
+    {
+      sessionId: string;
+      containerId?: string;
+    }
+  > {}
 
 /**
  * SessionResumedEvent - Session was resumed
  */
-export interface SessionResumedEvent extends BaseSessionActionResult<
-  "session_resumed",
-  {
-    sessionId: string;
-    agentId: string;
-    resumedAt: number;
-  }
-> {}
+export interface SessionResumedEvent
+  extends BaseSessionActionResult<
+    "session_resumed",
+    {
+      sessionId: string;
+      agentId: string;
+      resumedAt: number;
+    }
+  > {}
 
 /**
  * SessionForkRequest - Request to fork a session
  */
-export interface SessionForkRequest extends BaseSessionActionRequest<
-  "session_fork_request",
-  {
-    sessionId: string;
-    newTitle?: string;
-  }
-> {}
+export interface SessionForkRequest
+  extends BaseSessionActionRequest<
+    "session_fork_request",
+    {
+      sessionId: string;
+      newTitle?: string;
+    }
+  > {}
 
 /**
  * SessionForkedEvent - Session was forked
  */
-export interface SessionForkedEvent extends BaseSessionActionResult<
-  "session_forked",
-  {
-    originalSessionId: string;
-    newSessionId: string;
-    newImageId: string;
-    forkedAt: number;
-  }
-> {}
+export interface SessionForkedEvent
+  extends BaseSessionActionResult<
+    "session_forked",
+    {
+      originalSessionId: string;
+      newSessionId: string;
+      newImageId: string;
+      forkedAt: number;
+    }
+  > {}
 
 /**
  * SessionTitleUpdateRequest - Request to update session title
  */
-export interface SessionTitleUpdateRequest extends BaseSessionActionRequest<
-  "session_title_update_request",
-  {
-    sessionId: string;
-    title: string;
-  }
-> {}
+export interface SessionTitleUpdateRequest
+  extends BaseSessionActionRequest<
+    "session_title_update_request",
+    {
+      sessionId: string;
+      title: string;
+    }
+  > {}
 
 /**
  * SessionTitleUpdatedEvent - Session title was updated
  */
-export interface SessionTitleUpdatedEvent extends BaseSessionActionResult<
-  "session_title_updated",
-  {
-    sessionId: string;
-    title: string;
-    updatedAt: number;
-  }
-> {}
+export interface SessionTitleUpdatedEvent
+  extends BaseSessionActionResult<
+    "session_title_updated",
+    {
+      sessionId: string;
+      title: string;
+      updatedAt: number;
+    }
+  > {}
 
 /**
  * SessionActionEvent - All session action events

package/src/image/Image.ts

@@ -6,7 +6,7 @@
  */
 
 import { createLogger } from "commonxjs/logger";
-import type { Image, ImageRecord, ImageContext, ImageCreateConfig } from "./types";
+import type { Image, ImageContext, ImageCreateConfig, ImageRecord } from "./types";
 
 const logger = createLogger("image/Image");
 
@@ -49,6 +49,10 @@ export class ImageImpl implements Image {
     return this.record.mcpServers;
   }
 
+  get customData(): Record<string, unknown> | undefined {
+    return this.record.customData;
+  }
+
   get createdAt(): number {
     return this.record.createdAt;
   }
@@ -76,6 +80,7 @@ export class ImageImpl implements Image {
       description: config.description,
       systemPrompt: config.systemPrompt,
       mcpServers: config.mcpServers,
+      customData: config.customData,
       createdAt: now,
       updatedAt: now,
     };
@@ -135,12 +140,17 @@ export class ImageImpl implements Image {
   /**
    * Update image metadata
    */
-  async update(updates: { name?: string; description?: string }): Promise<Image> {
+  async update(updates: {
+    name?: string;
+    description?: string;
+    customData?: Record<string, unknown>;
+  }): Promise<Image> {
     const now = Date.now();
     const updatedRecord: ImageRecord = {
       ...this.record,
       name: updates.name ?? this.record.name,
       description: updates.description ?? this.record.description,
+      customData: updates.customData !== undefined ? updates.customData : this.record.customData,
       updatedAt: now,
     };
 

package/src/image/index.ts

@@ -24,13 +24,12 @@
  * ```
  */
 
+export { createImage, ImageImpl, loadImage } from "./Image";
 export type {
-  ImageMetadata,
-  ImageRecord,
-  ImageRepository,
   Image,
   ImageContext,
   ImageCreateConfig,
+  ImageMetadata,
+  ImageRecord,
+  ImageRepository,
 } from "./types";
-
-export { ImageImpl, createImage, loadImage } from "./Image";

package/src/image/types.ts

@@ -34,13 +34,18 @@ export interface Image {
   readonly description: string | undefined;
   readonly systemPrompt: string | undefined;
   readonly mcpServers: Record<string, McpServerConfig> | undefined;
+  readonly customData: Record<string, unknown> | undefined;
   readonly createdAt: number;
   readonly updatedAt: number;
 
   /**
-   * Update image metadata (name, description)
+   * Update image metadata (name, description, customData)
    */
-  update(updates: { name?: string; description?: string }): Promise<Image>;
+  update(updates: {
+    name?: string;
+    description?: string;
+    customData?: Record<string, unknown>;
+  }): Promise<Image>;
 
   /**
    * Delete this image and its session
@@ -74,4 +79,5 @@ export interface ImageCreateConfig {
   description?: string;
   systemPrompt?: string;
   mcpServers?: Record<string, McpServerConfig>;
+  customData?: Record<string, unknown>;
 }

package/src/mq/OffsetGenerator.ts

@@ -43,6 +43,6 @@ export class OffsetGenerator {
     const timeDiff = parseInt(aTime, 36) - parseInt(bTime, 36);
     if (timeDiff !== 0) return timeDiff;
 
-    return parseInt(aSeq) - parseInt(bSeq);
+    return parseInt(aSeq, 10) - parseInt(bSeq, 10);
   }
 }

package/src/mq/__tests__/OffsetGenerator.test.ts

@@ -2,7 +2,7 @@
  * OffsetGenerator.test.ts - Unit tests for OffsetGenerator
  */
 
-import { describe, it, expect, beforeEach } from "bun:test";
+import { beforeEach, describe, expect, it } from "bun:test";
 import { OffsetGenerator } from "../OffsetGenerator";
 
 describe("OffsetGenerator", () => {

package/src/mq/index.ts

@@ -7,12 +7,11 @@
  * - OffsetGenerator: Utility for generating monotonic offsets
  */
 
+export { OffsetGenerator } from "./OffsetGenerator";
 export type {
-  QueueEntry,
-  QueueConfig,
-  Unsubscribe,
   MessageQueue,
   MessageQueueProvider,
+  QueueConfig,
+  QueueEntry,
+  Unsubscribe,
 } from "./types";
-
-export { OffsetGenerator } from "./OffsetGenerator";

package/src/network/RpcClient.ts

@@ -25,33 +25,32 @@
  * ```
  */
 
+import type { SystemEvent } from "../event/types/base";
 import {
-  createRequest,
   createNotification,
-  parseMessage,
-  isSuccessResponse,
+  createRequest,
   isErrorResponse,
   isNotification,
   isStreamEvent,
-  type RpcMethod,
+  isSuccessResponse,
   type NotificationMethod,
+  parseMessage,
+  type RpcMethod,
   type StreamEventParams,
 } from "./jsonrpc";
-import type { SystemEvent } from "../event/types/base";
-
-/**
- * Check if running in browser environment
- */
-function isBrowser(): boolean {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const globalWindow = typeof globalThis !== "undefined" ? (globalThis as any).window : undefined;
-  return globalWindow?.document !== undefined;
-}
 
 // ============================================================================
 // Types
 // ============================================================================
 
+/**
+ * Factory function for creating WebSocket instances.
+ * Platform layer provides the implementation:
+ * - Browser: native WebSocket (default)
+ * - Node.js: ws library (via @agentxjs/node-platform)
+ */
+export type WebSocketFactory = (url: string) => WebSocket;
+
 /**
  * RpcClient configuration
  */
@@ -61,6 +60,12 @@ export interface RpcClientConfig {
    */
   url: string;
 
+  /**
+   * Factory for creating WebSocket instances.
+   * If not provided, falls back to the global WebSocket constructor.
+   */
+  createWebSocket?: WebSocketFactory;
+
   /**
    * Request timeout in milliseconds (default: 30000)
    */
@@ -77,7 +82,7 @@ export interface RpcClientConfig {
   reconnectDelay?: number;
 
   /**
-   * Headers for authentication (Node.js only, sent in first message for browser)
+   * Headers for authentication (sent in first message after connection)
    */
   headers?:
     | Record<string, string>
@@ -172,14 +177,9 @@ export class RpcClient {
 
     const url = this.config.url;
 
-    // Create WebSocket (browser or Node.js)
-    let ws: WebSocket;
-    if (isBrowser()) {
-      ws = new WebSocket(url);
-    } else {
-      const { default: WS } = await import("ws");
-      ws = new WS(url) as unknown as WebSocket;
-    }
+    // Create WebSocket via injected factory or global WebSocket
+    const factory = this.config.createWebSocket ?? ((u: string) => new WebSocket(u));
+    const ws = factory(url);
 
     this.ws = ws;
 
@@ -191,8 +191,9 @@ export class RpcClient {
           console.log("[RpcClient] Connected to", url);
         }
 
-        // Send auth if in browser (headers not supported in WebSocket API)
-        if (isBrowser() && this.config.headers) {
+        // Send auth headers after connection (for environments where
+        // WebSocket constructor doesn't support headers, e.g. browser)
+        if (this.config.headers) {
           const headers =
             typeof this.config.headers === "function"
               ? await this.config.headers()

package/src/network/index.ts

@@ -12,65 +12,62 @@
  * - @agentxjs/cloudflare: Durable Objects WebSocket
  */
 
-// Types
-export type {
-  Unsubscribe,
-  MinimalHTTPServer,
-  SendReliableOptions,
-  ConnectionState,
-  ChannelConnection,
-  ChannelServer,
-  ChannelServerOptions,
-  ChannelClient,
-  ChannelClientOptions,
-  ChannelServerProvider,
-  ChannelClientProvider,
-} from "./types";
-
-// Protocol (reliable delivery)
-export type { ReliableWrapper, AckMessage } from "./protocol";
-export {
-  isReliableWrapper,
-  isAckMessage,
-  wrapMessage,
-  createAck,
-  unwrapMessage,
-  generateMessageId,
-} from "./protocol";
-
 // JSON-RPC 2.0 Protocol
 export type {
-  RpcMethod,
+  ControlAckParams,
   NotificationMethod,
-  RpcRequest,
-  RpcSuccessResponse,
   RpcErrorResponse,
+  RpcMethod,
   RpcNotification,
+  RpcRequest,
+  RpcSuccessResponse,
   StreamEventParams,
-  ControlAckParams,
 } from "./jsonrpc";
 export {
-  JsonRpcError,
-  RpcErrorCodes,
-  createRequest,
+  createAckNotification,
+  createErrorResponse,
   createNotification,
+  createRequest,
   createStreamEvent,
-  createAckNotification,
   createSuccessResponse,
-  createErrorResponse,
-  parseMessage,
-  parseMessageObject,
-  isRequest,
-  isNotification,
-  isSuccessResponse,
+  eventTypeToRpcMethod,
+  isControlAck,
   isErrorResponse,
   isInvalid,
+  isNotification,
+  isRequest,
   isStreamEvent,
-  isControlAck,
-  eventTypeToRpcMethod,
+  isSuccessResponse,
+  JsonRpcError,
+  parseMessage,
+  parseMessageObject,
+  RpcErrorCodes,
   rpcMethodToResponseType,
 } from "./jsonrpc";
-
+// Protocol (reliable delivery)
+export type { AckMessage, ReliableWrapper } from "./protocol";
+export {
+  createAck,
+  generateMessageId,
+  isAckMessage,
+  isReliableWrapper,
+  unwrapMessage,
+  wrapMessage,
+} from "./protocol";
 // RPC Client
-export type { RpcClientConfig, RpcClientState } from "./RpcClient";
+export type { RpcClientConfig, RpcClientState, WebSocketFactory } from "./RpcClient";
 export { RpcClient } from "./RpcClient";
+// Types
+export type {
+  ChannelClient,
+  ChannelClientOptions,
+  ChannelClientProvider,
+  ChannelConnection,
+  ChannelServer,
+  ChannelServerOptions,
+  ChannelServerProvider,
+  ConnectionState,
+  MinimalHTTPServer,
+  SendReliableOptions,
+  Unsubscribe,
+} from "./types";

package/src/network/jsonrpc.ts

@@ -11,16 +11,16 @@
  * @see https://www.jsonrpc.org/specification
  */
 
+import type { IParsedObject, JsonRpc } from "jsonrpc-lite";
 import {
-  request as jsonrpcRequest,
-  notification as jsonrpcNotification,
-  success as jsonrpcSuccess,
+  JsonRpcError,
   error as jsonrpcError,
+  notification as jsonrpcNotification,
   parse as jsonrpcParse,
   parseObject as jsonrpcParseObject,
-  JsonRpcError,
+  request as jsonrpcRequest,
+  success as jsonrpcSuccess,
 } from "jsonrpc-lite";
-import type { IParsedObject, JsonRpc } from "jsonrpc-lite";
 import type { SystemEvent } from "../event/types/base";
 
 // ============================================================================