resourcexjs

Resource management protocol for AI Agents. Like npm for AI resources (prompts, tools, agents, configs).

Installation

npm install resourcexjs @resourcexjs/node-provider
# or
bun add resourcexjs @resourcexjs/node-provider

Requirements: Node.js 22+ or Bun

Quick Start

import { createResourceX, setProvider } from "resourcexjs";
import { NodeProvider } from "@resourcexjs/node-provider";

// Configure provider before creating client
setProvider(new NodeProvider());

const rx = createResourceX();

// Add a resource from local directory
await rx.add("./my-prompt");

// Resolve and execute
const result = await rx.resolve("my-prompt:1.0.0");
const content = await result.execute();
console.log(content);

Core Concepts

ResourceX uses five core primitives:

| Primitive | Description | | --------- | --------------------------------------------------- | | RXI | Resource Identifier - structured { registry?, path?, name, tag } | | RXL | Resource Locator - unified locator string (RXI string, path, or URL) | | RXM | Resource Manifest - metadata (name, type, version) | | RXA | Resource Archive - content container (tar.gz) | | RXR | Resource - complete object (RXI + RXM + RXA) |

Locator Format

ResourceX uses a Docker-style locator format:

[registry/][path/]name[:tag]

• name - Resource name (required)
• tag - Version or label (optional, defaults to "latest")
• registry - Registry host (optional, e.g., registry.example.com or localhost:3098)
• path - Path within registry (optional)

Examples:

• hello - local resource with default tag "latest"
• hello:1.0.0 - local resource with version
• prompts/hello:1.0.0 - with path
• registry.example.com/hello:1.0.0 - remote resource
• localhost:3098/org/hello:latest - with port and path

Note: The resource type (e.g., "text", "json") is specified in resource.json, not in the locator.

Resource Directory Structure

A resource directory contains:

my-prompt/
├── resource.json    # Resource metadata (required)
└── content          # Resource content (required for text/json/binary)

Example resource.json:

{
  "name": "my-prompt",
  "type": "text",
  "tag": "1.0.0"
}

Storage Layout

Resources are stored using content-addressable storage (CAS) in ~/.resourcex/:

~/.resourcex/
├── blobs/                        # Content-addressable blob storage
│   └── ab/
│       └── sha256:abcd1234...    # Archive data (tar.gz)
└── manifests/
    ├── _local/                   # Local resources (no registry)
    │   └── my-prompt/
    │       └── 1.0.0.json        # Manifest with digest reference
    └── registry.example.com/     # Cached remote resources
        └── hello/
            └── 1.0.0.json

Provider Configuration

ResourceX requires a platform provider to be configured before use. The provider handles platform-specific storage operations.

import { setProvider, hasProvider, clearProvider } from "resourcexjs";
import { NodeProvider } from "@resourcexjs/node-provider";

// Set provider (required before createResourceX)
setProvider(new NodeProvider());

// Check if provider is configured
if (hasProvider()) {
  const rx = createResourceX();
}

// Clear provider (useful for testing)
clearProvider();

API Reference

createResourceX(config?)

Create a ResourceX client instance. Requires a provider to be set first.

import { createResourceX, setProvider } from "resourcexjs";
import { NodeProvider } from "@resourcexjs/node-provider";

setProvider(new NodeProvider());

const rx = createResourceX({
  path: "~/.resourcex", // Storage path (default: ~/.resourcex)
  registry: "https://...", // Central registry URL (for push/pull)
  types: [myCustomType], // Custom resource types
  isolator: "none", // Sandbox: none | srt | cloudflare | e2b
});

Local Operations

rx.add(path)

Add a resource from a local directory to local storage.

const resource = await rx.add("./my-prompt");
console.log(resource.locator); // "my-prompt:1.0.0"

rx.has(locator)

Check if a resource exists locally.

const exists = await rx.has("hello:1.0.0");

rx.info(locator)

Get detailed resource information.

const info = await rx.info("hello:1.0.0");
console.log(info);
// {
//   locator: "hello:1.0.0",
//   name: "hello",
//   type: "text",
//   tag: "1.0.0",
//   files: ["content"]
// }

rx.remove(locator)

Remove a resource from local storage.

await rx.remove("hello:1.0.0");

rx.resolve(locator)

Load and prepare a resource for execution from an RXL locator string.

const executable = await rx.resolve<string>("hello:1.0.0");

// Execute with optional arguments
const content = await executable.execute();

// Access schema (if defined by the type)
console.log(executable.schema);

Resolution order:

1. Local storage
2. Cache (previously pulled)
3. Remote registry (auto-pull if configured)

rx.search(query?)

Search local resources.

// Search all
const all = await rx.search();

// Search by keyword
const results = await rx.search("prompt");
// ["my-prompt:1.0.0", "system-prompt:2.0.0"]

Remote Operations

rx.push(locator)

Push a local resource to the remote registry.

import { createResourceX, setProvider } from "resourcexjs";
import { NodeProvider } from "@resourcexjs/node-provider";

setProvider(new NodeProvider());

const rx = createResourceX({
  registry: "https://registry.example.com",
});

await rx.add("./my-prompt");
await rx.push("my-prompt:1.0.0");

rx.pull(locator)

Pull a resource from the remote registry to local cache.

await rx.pull("hello:1.0.0");
// Resource is now cached locally

Cache Operations

rx.clearCache(registry?)

Clear cached resources.

// Clear all cache
await rx.clearCache();

// Clear cache for specific registry
await rx.clearCache("registry.example.com");

Extension

rx.supportType(type)

Add support for a custom resource type.

rx.supportType({
  name: "prompt",
  aliases: ["ai-prompt"],
  description: "AI prompt template",
  code: `({
    async resolve(ctx) {
      const template = new TextDecoder().decode(ctx.files["content"]);
      return {
        template,
        render: (vars) => template.replace(/\\{\\{(\\w+)\\}\\}/g, (_, k) => vars[k])
      };
    }
  })`,
});

const result = await rx.resolve("greeting:1.0.0");
const { template, render } = await result.execute();
console.log(render({ name: "World" }));

Built-in Types

| Type | Aliases | Description | Output | | -------- | ---------------- | ------------------ | ------------ | | text | txt, plaintext | Plain text content | string | | json | config, manifest | JSON content | unknown | | binary | bin, blob, raw | Binary content | Uint8Array |

Core Primitives

For advanced use cases, you can work with core primitives directly:

import { parse, format, manifest, archive, resource, extract, wrap } from "resourcexjs";

// Parse locator string to RXI
const rxi = parse("hello:1.0.0");
console.log(rxi.name); // "hello"
console.log(rxi.tag); // "1.0.0"

// Format RXI back to string
const str = format(rxi); // "hello:1.0.0"

// Create manifest from definition
const rxm = manifest({
  name: "hello",
  type: "text",
  tag: "1.0.0",
});

// Create archive from files
const rxa = await archive({
  content: Buffer.from("Hello, World!"),
});

// Create complete resource
const rxr = resource(rxm, rxa);

// Extract files from archive
const files = await extract(rxa); // Record<string, Buffer>

// Wrap raw buffer as archive
const wrapped = wrap(Buffer.from(tarGzData));

ARP - Low-level I/O

ResourceX includes ARP (Agent Resource Protocol) for direct file/network operations:

import { createARP } from "resourcexjs/arp";

const arp = createARP();

// File operations
const fileArl = arp.parse("arp:text:file:///path/to/file.txt");
const { content } = await fileArl.resolve();
await fileArl.deposit("new content");
await fileArl.exists();

// HTTP operations
const httpArl = arp.parse("arp:json:https://api.example.com/data");
const { content: data } = await httpArl.resolve();

Configuration Options

interface ResourceXConfig {
  /**
   * Base path for local storage.
   * Default: ~/.resourcex
   */
  path?: string;

  /**
   * Central registry URL for push/pull operations.
   */
  registry?: string;

  /**
   * Custom resource types to register.
   */
  types?: BundledType[];

  /**
   * Isolator type for resolver execution.
   * - "none": No isolation (default, fastest)
   * - "srt": OS-level isolation
   * - "cloudflare": Container isolation
   * - "e2b": MicroVM isolation
   */
  isolator?: IsolatorType;
}

Types

Resource

User-facing resource object returned by add() and info().

interface Resource {
  locator: string; // Full locator string
  registry?: string; // Registry host (if remote)
  path?: string; // Path within registry
  name: string; // Resource name
  type: string; // Resource type
  tag: string; // Version tag
  files?: string[]; // Files in archive
}

Executable

Result of use().

interface Executable<T = unknown> {
  execute: (args?: unknown) => Promise<T>;
  schema?: unknown; // JSON schema for arguments
}

BundledType

Custom resource type definition.

interface BundledType {
  name: string; // Type name
  aliases?: string[]; // Alternative names
  description: string; // Human-readable description
  schema?: JSONSchema; // Schema for resolver arguments
  code: string; // Bundled resolver code
}

Error Handling

import { RegistryError, ResourceTypeError } from "resourcexjs";

try {
  await rx.resolve("unknown:1.0.0");
} catch (error) {
  if (error instanceof RegistryError) {
    console.error("Resource not found:", error.message);
  }
}

Error hierarchy:

ResourceXError (base)
├── LocatorError      # RXI parsing errors
├── ManifestError     # RXM validation errors
├── ContentError      # RXA operations errors
└── DefinitionError   # RXD validation errors

RegistryError         # Registry operations
ResourceTypeError     # Type not found

ARPError (base)
├── ParseError        # URL parsing
├── TransportError    # Transport operations
└── SemanticError     # Semantic operations

Related Packages

| Package | Description | | ---------------------------- | ------------------------------- | | @resourcexjs/core | Core primitives and CASRegistry | | @resourcexjs/node-provider | Node.js/Bun platform provider | | @resourcexjs/server | Registry server | | @resourcexjs/arp | Low-level I/O protocol |

License

Apache-2.0