README.md

@agentxjs/node-platform

Node.js runtime platform for AgentX. Provides concrete implementations of persistence (SQLite), bash execution, networking (WebSocket), message queue, and logging.

Overview

@agentxjs/node-platform assembles platform-specific components into an AgentXPlatform instance that the AgentX runtime requires. It handles storage, shell execution, and event infrastructure -- the driver (LLM) is injected separately.

Quick Start

import { createNodePlatform } from "@agentxjs/node-platform";

const platform = await createNodePlatform({
  dataPath: "./data",
});

// platform.containerRepository  -- SQLite container storage
// platform.imageRepository      -- SQLite image storage
// platform.sessionRepository    -- SQLite session + message storage
// platform.eventBus             -- In-memory EventBus
// platform.bashProvider         -- Shell execution via execa

Deferred Initialization

Use nodePlatform() for lazy initialization (e.g., when passing to createServer):

import { nodePlatform } from "@agentxjs/node-platform";
import { createServer } from "@agentxjs/server";

const server = await createServer({
  platform: nodePlatform({ dataPath: "./data" }), // resolved lazily
  createDriver: myCreateDriver,
});

API Reference

createNodePlatform(options?): Promise<AgentXPlatform>

Immediately creates and returns a fully initialized platform.

nodePlatform(options?): DeferredPlatformConfig

Returns a deferred config. Call .resolve() to initialize.

isDeferredPlatform(value): value is DeferredPlatformConfig

Type guard for deferred platform configs.

Returned AgentXPlatform

Property	Type	Description
containerRepository	ContainerRepository	Container CRUD (SQLite)
imageRepository	ImageRepository	Image CRUD (SQLite)
sessionRepository	SessionRepository	Session + message CRUD (SQLite)
eventBus	EventBus	In-memory pub/sub
bashProvider	BashProvider	Shell execution via execa

Additional Exports

// Persistence
import { createPersistence, sqliteDriver, memoryDriver } from "@agentxjs/node-platform/persistence";

// Network
import { WebSocketServer, WebSocketConnection } from "@agentxjs/node-platform/network";

// Message Queue
import { SqliteMessageQueue, OffsetGenerator } from "@agentxjs/node-platform/mq";

// Bash
import { NodeBashProvider } from "@agentxjs/node-platform";

// Logger
import { FileLoggerFactory } from "@agentxjs/node-platform";

Configuration

NodePlatformOptions

interface NodePlatformOptions {
  dataPath?: string; // default: "./data"
  logDir?: string; // enables file logging if set
  logLevel?: LogLevel; // default: "debug" (file) / "info" (console)
}

Option	Type	Default	Description
dataPath	string	"./data"	Base directory for SQLite database (<dataPath>/agentx.db)
logDir	string	--	Log file directory. Enables file logging when set.
logLevel	LogLevel	"debug" (file) / "info" (console)	"debug" | "info" | "warn" | "error" | "silent"

Persistence Drivers

// SQLite (production)
const persistence = await createPersistence(sqliteDriver({ path: "./data/agentx.db" }));

// In-memory (testing)
const persistence = await createPersistence(memoryDriver());

File Logging

import { FileLoggerFactory } from "@agentxjs/node-platform";
import { setLoggerFactory } from "commonxjs/logger";

setLoggerFactory(
  new FileLoggerFactory({
    logDir: ".agentx/logs",
    level: "info",
    filename: "app.log", // default
  })
);

When logDir is passed to createNodePlatform, file logging is configured automatically.

Sub-path Exports

Import path	Contents
@agentxjs/node-platform	Main entry (everything)
@agentxjs/node-platform/persistence	createPersistence, sqliteDriver, memoryDriver
@agentxjs/node-platform/mq	SqliteMessageQueue, OffsetGenerator
@agentxjs/node-platform/network	WebSocketServer, WebSocketConnection