@agentxjs/core

Core types, interfaces, and agent engine for the AgentX framework.

You typically don't install this directly — it's pulled in as a dependency of agentxjs and platform/driver packages.

Architecture

Image  ──has──►  Session (message history)
  │
  ├──has──►  Workspace (file operations)
  │
  └──creates──►  Agent  ──uses──►  Driver (LLM communication)
                   │
                   └──runs on──►  Platform (DI container)

Key Concepts

| Concept | What it is | Analogy | |---------|-----------|---------| | Image | Persistent agent config (prompt, tools, workspace) | Docker image | | Session | Message history for an image | Conversation log | | Agent | Running instance of an image | Docker container | | Workspace | Agent's isolated working directory | Project folder | | Driver | LLM communication bridge | API client | | Platform | Infrastructure dependencies (DI container) | Runtime environment |

Sub-module Imports

import { ... } from "@agentxjs/core/agent";       // Agent engine
import { ... } from "@agentxjs/core/driver";       // Driver interface, ToolDefinition
import { ... } from "@agentxjs/core/platform";     // AgentXPlatform
import { ... } from "@agentxjs/core/runtime";      // AgentXRuntime
import { ... } from "@agentxjs/core/workspace";    // Workspace, WorkspaceProvider
import { ... } from "@agentxjs/core/image";        // Image management
import { ... } from "@agentxjs/core/session";      // Session management
import { ... } from "@agentxjs/core/event";        // EventBus
import { ... } from "@agentxjs/core/bash";         // BashProvider
import { ... } from "@agentxjs/core/persistence";  // Repository interfaces
import { ... } from "@agentxjs/core/network";      // JSON-RPC protocol
import { ... } from "@agentxjs/core/llm";          // LLM provider types

Runtime Operations

Three first-class operations on a running agent:

interface AgentXRuntime {
  // Send message → Driver → LLM → stream events
  receive(instanceId, content): Promise<void>;

  // Interrupt current response
  interrupt(instanceId): void;

  // Rewind to message — truncate session + reset circuit breaker + emit event
  rewind(instanceId, messageId): Promise<void>;
}

Platform (DI Container)

interface AgentXPlatform {
  // Required
  containerRepository: ContainerRepository;
  imageRepository: ImageRepository;
  sessionRepository: SessionRepository;
  eventBus: EventBus;

  // Optional
  bashProvider?: BashProvider;            // Shell execution
  workspaceProvider?: WorkspaceProvider;  // File operations per agent
  contextProvider?: ContextProvider;      // Cognitive context (e.g. RoleX)
  llmProviderRepository?: LLMProviderRepository;
  channelServer?: ChannelServer;          // WebSocket server
  channelClient?: ChannelClientFactory;   // WebSocket client
}

Workspace

Each Image auto-generates a workspaceId. When workspaceProvider is available, agents get 6 built-in file tools: read, write, edit, grep, glob, list.

interface Workspace {
  read(path, options?): Promise<string>;
  write(path, content): Promise<void>;
  exists(path): Promise<boolean>;
  stat(path): Promise<FileStat | null>;
  remove(path): Promise<void>;
  list(path?): Promise<FileEntry[]>;
  mkdir(path): Promise<void>;
}

interface WorkspaceProvider {
  create(workspaceId): Promise<Workspace>;
}

Driver

interface Driver {
  receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
  initialize(): Promise<void>;
  dispose(): Promise<void>;
  interrupt(): void;
  readonly supportedProtocols: readonly LLMProtocol[];
}

type CreateDriver = (config: DriverConfig) => Driver;

Dependencies: commonxjs, rxjs, jsonrpc-lite