@agentxjs/node-platform 2.0.0

package/dist/persistence/index.js

@@ -0,0 +1,18 @@
+import {
+  StorageContainerRepository,
+  StorageImageRepository,
+  StorageSessionRepository,
+  createPersistence,
+  memoryDriver,
+  sqliteDriver
+} from "../chunk-TXESAX3X.js";
+import "../chunk-DGUM43GV.js";
+export {
+  StorageContainerRepository,
+  StorageImageRepository,
+  StorageSessionRepository,
+  createPersistence,
+  memoryDriver,
+  sqliteDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@agentxjs/node-platform",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./persistence": {
+      "types": "./dist/persistence/index.d.ts",
+      "import": "./dist/persistence/index.js",
+      "default": "./dist/persistence/index.js"
+    },
+    "./mq": {
+      "types": "./dist/mq/index.d.ts",
+      "import": "./dist/mq/index.js",
+      "default": "./dist/mq/index.js"
+    },
+    "./network": {
+      "types": "./dist/network/index.d.ts",
+      "import": "./dist/network/index.js",
+      "default": "./dist/network/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests yet'"
+  },
+  "dependencies": {
+    "@agentxjs/core": "^2.0.0",
+    "commonxjs": "^0.1.1",
+    "execa": "9.6.1",
+    "rxjs": "^7.8.2",
+    "unstorage": "^1.10.2",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.3.3"
+  }
+}

package/src/bash/NodeBashProvider.ts

@@ -0,0 +1,54 @@
+/**
+ * NodeBashProvider - Node.js implementation of BashProvider
+ *
+ * Uses execa for subprocess execution with proper timeout,
+ * error handling, and cross-platform shell support.
+ */
+
+import { execa } from "execa";
+import type { BashProvider, BashResult, BashOptions } from "@agentxjs/core/bash";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("node-platform/NodeBashProvider");
+
+/**
+ * Default timeout: 30 seconds
+ */
+const DEFAULT_TIMEOUT = 30_000;
+
+/**
+ * NodeBashProvider - Executes shell commands via execa
+ */
+export class NodeBashProvider implements BashProvider {
+  readonly type = "child-process";
+
+  async execute(command: string, options?: BashOptions): Promise<BashResult> {
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+
+    logger.debug("Executing command", {
+      command: command.substring(0, 100),
+      cwd: options?.cwd,
+      timeout,
+    });
+
+    const result = await execa({
+      shell: true,
+      cwd: options?.cwd,
+      timeout,
+      env: options?.env ? { ...process.env, ...options.env } : undefined,
+      reject: false,
+    })`${command}`;
+
+    logger.debug("Command completed", {
+      exitCode: result.exitCode,
+      stdoutLength: result.stdout.length,
+      stderrLength: result.stderr.length,
+    });
+
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode ?? 1,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * @agentxjs/node-platform
+ *
+ * Node.js platform for AgentX.
+ * Provides implementations for persistence, bash, and network.
+ *
+ * @example
+ * ```typescript
+ * import { createNodePlatform } from "@agentxjs/node-platform";
+ *
+ * const platform = await createNodePlatform({ dataPath: "./data" });
+ * ```
+ */
+
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type { LogLevel } from "commonxjs/logger";
+import { setLoggerFactory, ConsoleLogger } from "commonxjs/logger";
+import { EventBusImpl } from "@agentxjs/core/event";
+import { createPersistence, sqliteDriver } from "./persistence";
+import { NodeBashProvider } from "./bash/NodeBashProvider";
+import { FileLoggerFactory } from "./logger";
+import { join } from "node:path";
+
+/**
+ * Options for creating a Node platform
+ */
+export interface NodePlatformOptions {
+  /**
+   * Base path for data storage
+   * @default "./data"
+   */
+  dataPath?: string;
+
+  /**
+   * Directory for log files
+   * If provided, enables file logging instead of console
+   * @example ".agentx/logs"
+   */
+  logDir?: string;
+
+  /**
+   * Log level
+   * @default "debug" for file logging, "info" for console
+   */
+  logLevel?: LogLevel;
+}
+
+/**
+ * Deferred platform config - resolved lazily
+ */
+export interface DeferredPlatformConfig {
+  readonly __deferred: true;
+  readonly options: NodePlatformOptions;
+  resolve(): Promise<AgentXPlatform>;
+}
+
+/**
+ * Create a Node.js platform configuration (deferred initialization)
+ *
+ * Use this for function-style API. The platform is initialized lazily.
+ *
+ * @param options - Platform options
+ * @returns Deferred platform config
+ *
+ * @example
+ * ```typescript
+ * const server = await createServer({
+ *   platform: nodePlatform({ dataPath: "./data" }),
+ * });
+ * ```
+ */
+export function nodePlatform(options: NodePlatformOptions = {}): DeferredPlatformConfig {
+  return {
+    __deferred: true,
+    options,
+    resolve: () => createNodePlatform(options),
+  };
+}
+
+/**
+ * Create a Node.js platform for AgentX (immediate initialization)
+ *
+ * @param options - Platform options
+ * @returns AgentXPlatform instance
+ */
+export async function createNodePlatform(
+  options: NodePlatformOptions = {}
+): Promise<AgentXPlatform> {
+  const dataPath = options.dataPath ?? "./data";
+
+  // Configure logging
+  if (options.logDir) {
+    const loggerFactory = new FileLoggerFactory({
+      logDir: options.logDir,
+      level: options.logLevel ?? "debug",
+    });
+    setLoggerFactory(loggerFactory);
+  } else if (options.logLevel) {
+    setLoggerFactory({
+      getLogger: (name: string) => new ConsoleLogger(name, { level: options.logLevel }),
+    });
+  }
+
+  // Create persistence with SQLite
+  const persistence = await createPersistence(sqliteDriver({ path: join(dataPath, "agentx.db") }));
+
+  // Create bash provider
+  const bashProvider = new NodeBashProvider();
+
+  // Create event bus
+  const eventBus = new EventBusImpl();
+
+  // Create WebSocket factory (uses ws library for Node.js)
+  const { createNodeWebSocket } = await import("./network/WebSocketFactory");
+
+  return {
+    containerRepository: persistence.containers,
+    imageRepository: persistence.images,
+    sessionRepository: persistence.sessions,
+    eventBus,
+    bashProvider,
+    webSocketFactory: createNodeWebSocket,
+  };
+}
+
+/**
+ * Check if value is a deferred platform config
+ */
+export function isDeferredPlatform(value: unknown): value is DeferredPlatformConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__deferred" in value &&
+    (value as DeferredPlatformConfig).__deferred === true
+  );
+}
+
+// Re-export persistence
+export * from "./persistence";
+
+// Re-export bash
+export { NodeBashProvider } from "./bash/NodeBashProvider";
+
+// Re-export mq
+export { SqliteMessageQueue, OffsetGenerator } from "./mq";
+
+// Re-export network
+export { WebSocketServer, WebSocketConnection } from "./network";
+
+// Re-export logger
+export { FileLoggerFactory, type FileLoggerFactoryOptions } from "./logger";

package/src/logger/FileLoggerFactory.ts

@@ -0,0 +1,175 @@
+/**
+ * FileLoggerFactory - File-based logger for Node.js
+ *
+ * Writes logs to a file instead of console.
+ * Useful for TUI applications where console output interferes with the UI.
+ *
+ * Usage:
+ *   tail -f .agentx/logs/app.log
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Logger, LoggerFactory, LogContext, LogLevel } from "commonxjs/logger";
+
+export interface FileLoggerOptions {
+  level?: LogLevel;
+  timestamps?: boolean;
+}
+
+class FileLogger implements Logger {
+  readonly name: string;
+  readonly level: LogLevel;
+  private readonly timestamps: boolean;
+  private readonly filePath: string;
+  private initialized = false;
+
+  constructor(name: string, filePath: string, options: FileLoggerOptions = {}) {
+    this.name = name;
+    this.filePath = filePath;
+    this.level = options.level ?? "debug";
+    this.timestamps = options.timestamps ?? true;
+  }
+
+  private ensureDir(): void {
+    if (this.initialized) return;
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    this.initialized = 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 {
+    this.ensureDir();
+
+    const parts: string[] = [];
+
+    if (this.timestamps) {
+      parts.push(new Date().toISOString());
+    }
+
+    parts.push(level.padEnd(5));
+    parts.push(`[${this.name}]`);
+    parts.push(message);
+
+    let logLine = parts.join(" ");
+
+    if (context && Object.keys(context).length > 0) {
+      logLine += " " + JSON.stringify(context);
+    }
+
+    logLine += "\n";
+
+    try {
+      appendFileSync(this.filePath, logLine);
+    } catch {
+      // Fallback to stderr if file write fails
+      process.stderr.write(`[FileLogger] Failed to write: ${logLine}`);
+    }
+  }
+}
+
+/**
+ * FileLoggerFactory options
+ */
+export interface FileLoggerFactoryOptions {
+  /**
+   * Directory for log files
+   */
+  logDir: string;
+
+  /**
+   * Log level
+   * @default "debug"
+   */
+  level?: LogLevel;
+
+  /**
+   * Log file name
+   * @default "app.log"
+   */
+  filename?: string;
+}
+
+/**
+ * FileLoggerFactory - Creates FileLogger instances
+ */
+export class FileLoggerFactory implements LoggerFactory {
+  private readonly filePath: string;
+  private readonly level: LogLevel;
+  private readonly loggers: Map<string, FileLogger> = new Map();
+
+  constructor(options: FileLoggerFactoryOptions) {
+    this.filePath = join(options.logDir, options.filename ?? "app.log");
+    this.level = options.level ?? "debug";
+  }
+
+  getLogger(name: string): Logger {
+    if (this.loggers.has(name)) {
+      return this.loggers.get(name)!;
+    }
+
+    const logger = new FileLogger(name, this.filePath, {
+      level: this.level,
+    });
+
+    this.loggers.set(name, logger);
+    return logger;
+  }
+}

package/src/logger/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Logger module for Node.js
+ */
+
+export { FileLoggerFactory, type FileLoggerFactoryOptions } from "./FileLoggerFactory";

package/src/mq/OffsetGenerator.ts

@@ -0,0 +1,48 @@
+/**
+ * OffsetGenerator - Generates monotonically increasing offsets
+ *
+ * Format: "{timestamp_base36}-{sequence_padded}"
+ * Example: "lq5x4g2-0001"
+ *
+ * This format ensures:
+ * - Lexicographic ordering matches temporal ordering
+ * - Multiple events in same millisecond get unique offsets
+ * - Human-readable and compact
+ */
+export class OffsetGenerator {
+  private lastTimestamp = 0;
+  private sequence = 0;
+
+  /**
+   * Generate a new offset
+   */
+  generate(): string {
+    const now = Date.now();
+
+    if (now === this.lastTimestamp) {
+      this.sequence++;
+    } else {
+      this.lastTimestamp = now;
+      this.sequence = 0;
+    }
+
+    const timestampPart = now.toString(36);
+    const sequencePart = this.sequence.toString().padStart(4, "0");
+
+    return `${timestampPart}-${sequencePart}`;
+  }
+
+  /**
+   * Compare two offsets
+   * @returns negative if a < b, 0 if a == b, positive if a > b
+   */
+  static compare(a: string, b: string): number {
+    const [aTime, aSeq] = a.split("-");
+    const [bTime, bSeq] = b.split("-");
+
+    const timeDiff = parseInt(aTime, 36) - parseInt(bTime, 36);
+    if (timeDiff !== 0) return timeDiff;
+
+    return parseInt(aSeq) - parseInt(bSeq);
+  }
+}