arp

@resourcexjs/arp

Agent Resource Protocol (ARP) - A URL protocol for AI agents to access resources.

Installation

bun add @resourcexjs/arp
# or
npm install @resourcexjs/arp

Overview

ARP provides a unified URL-based abstraction for resource I/O operations. It separates what a resource means (semantic) from where and how to access it (transport).

URL Format

arp:{semantic}:{transport}://{location}

Component	Description	Examples
semantic	Content interpretation	text, binary
transport	Storage backend	file, http, https
location	Resource path	/path/to/file, example.com/data

Example URLs

arp:text:file:///path/to/file.txt       # Absolute file path
arp:text:file://./relative/file.txt     # Relative file path
arp:binary:https://example.com/image.png # HTTPS resource
arp:text:http://localhost:3000/data      # HTTP resource

Quick Start

import { createARP } from "@resourcexjs/arp";

const arp = createARP();

// Parse ARP URL into ARL (Agent Resource Locator)
const arl = arp.parse("arp:text:file://./data.txt");

// Core operations
await arl.deposit("Hello, World!"); // Write
const resource = await arl.resolve(); // Read
console.log(resource.content); // "Hello, World!"

if (await arl.exists()) {
  // Check existence
  await arl.delete(); // Delete
}

Core Concepts

ARI vs ARL

• ARI (Agent Resource Identifier): Identifies resource type (semantic + transport)
• ARL (Agent Resource Locator): Full locator with operations (semantic + transport + location)

interface ARI {
  readonly semantic: string;
  readonly transport: string;
}

interface ARL extends ARI {
  readonly location: string;
  resolve(params?): Promise<Resource>;
  deposit(data, params?): Promise<void>;
  exists(): Promise<boolean>;
  delete(): Promise<void>;
  list(options?): Promise<string[]>;
  mkdir(): Promise<void>;
  toString(): string;
}

Resource

The result of arl.resolve():

interface Resource<T = unknown> {
  type: string; // Semantic type ("text", "binary")
  content: T; // Content (string for text, Buffer for binary)
  meta: ResourceMeta; // Metadata
}

interface ResourceMeta {
  url: string; // Original ARP URL
  semantic: string;
  transport: string;
  location: string;
  size: number;
  encoding?: string; // e.g., "utf-8" for text
  mimeType?: string;
  resolvedAt: string; // ISO timestamp
  type?: "file" | "directory";
}

Built-in Handlers

createARP() automatically registers standard handlers:

Transports

Name	Description	Read	Write	Exists	Delete	List	Mkdir
file	Local filesystem	Yes	Yes	Yes	Yes	Yes	Yes
http	HTTP resources	Yes	No	Yes	No	No	No
https	HTTPS resources	Yes	No	Yes	No	No	No

Semantics

Name	Input Type	Output Type	Description
text	string	string	UTF-8 text content
binary	Buffer, Uint8Array, ArrayBuffer, number[]	Buffer	Raw binary data

API Reference

createARP(config?): ARP

Create an ARP instance.

interface ARPConfig {
  transports?: TransportHandler[]; // Custom transports
  semantics?: SemanticHandler[]; // Custom semantics
}

const arp = createARP();

// With custom handlers
const arp = createARP({
  transports: [myTransport],
  semantics: [mySemantic],
});

arp.parse(url): ARL

Parse an ARP URL string into an ARL object.

const arl = arp.parse("arp:text:file://./data.txt");

console.log(arl.semantic); // "text"
console.log(arl.transport); // "file"
console.log(arl.location); // "./data.txt"
console.log(arl.toString()); // "arp:text:file://./data.txt"

Throws: ParseError if URL format is invalid

arp.registerTransport(handler): void

Register a custom transport handler.

arp.registerTransport(myTransportHandler);

arp.registerSemantic(handler): void

Register a custom semantic handler.

arp.registerSemantic(mySemanticHandler);

ARL Operations

arl.resolve(params?): Promise<Resource>

Read resource from location.

const resource = await arl.resolve();
console.log(resource.type); // "text"
console.log(resource.content); // string or Buffer
console.log(resource.meta); // ResourceMeta

Params: TransportParams - Key-value pairs passed to transport

// Pass parameters to transport
const resource = await arl.resolve({
  recursive: "true",
  pattern: "*.json",
});

arl.deposit(data, params?): Promise<void>

Write data to location.

// Text semantic
await arl.deposit("Hello, World!");

// Binary semantic
await arl.deposit(Buffer.from([0x48, 0x69]));
await arl.deposit(new Uint8Array([1, 2, 3]));
await arl.deposit([1, 2, 3, 4]); // number array

Throws: SemanticError if semantic doesn't support deposit

arl.exists(): Promise<boolean>

Check if resource exists.

if (await arl.exists()) {
  console.log("Resource exists");
}

arl.delete(): Promise<void>

Delete resource at location.

await arl.delete();

arl.list(options?): Promise<string[]>

List directory contents (file transport only).

interface ListOptions {
  recursive?: boolean; // List subdirectories
  pattern?: string; // Glob pattern filter (e.g., "*.json")
}

const arl = arp.parse("arp:text:file://./my-dir");
const files = await arl.list(); // ["file1.txt", "file2.txt"]
const all = await arl.list({ recursive: true }); // ["sub/file.txt", ...]
const json = await arl.list({ pattern: "*.json" }); // ["config.json", ...]

Throws: TransportError if transport doesn't support list

arl.mkdir(): Promise<void>

Create directory (file transport only).

const arl = arp.parse("arp:text:file://./new-dir");
await arl.mkdir();

Throws: TransportError if transport doesn't support mkdir

Transport Handlers

Interface

interface TransportHandler {
  readonly name: string;
  get(location: string, params?: TransportParams): Promise<TransportResult>;
  set(location: string, content: Buffer, params?: TransportParams): Promise<void>;
  exists(location: string): Promise<boolean>;
  delete(location: string): Promise<void>;
  list?(location: string, options?: ListOptions): Promise<string[]>;
  mkdir?(location: string): Promise<void>;
}

type TransportParams = Record<string, string>;

interface TransportResult {
  content: Buffer;
  metadata?: {
    type?: "file" | "directory";
    size?: number;
    modifiedAt?: Date;
    [key: string]: unknown;
  };
}

File Transport

Local filesystem operations with full read-write support.

// Paths
arp.parse("arp:text:file:///absolute/path.txt"); // Absolute
arp.parse("arp:text:file://./relative/path.txt"); // Relative to cwd

// Directory operations
const dir = arp.parse("arp:text:file://./my-dir");
await dir.mkdir(); // Create directory
const files = await dir.list({ recursive: true }); // List recursively

HTTP/HTTPS Transport

Read-only network resource access.

const arl = arp.parse("arp:text:https://example.com/data.txt");

// Read
const resource = await arl.resolve();

// Check existence (HEAD request)
const exists = await arl.exists();

// Query parameters
const arl2 = arp.parse("arp:text:https://api.example.com/data?format=json");
const resource2 = await arl2.resolve({ token: "abc123" }); // Merges params

Note: set, delete, list, mkdir throw TransportError

Semantic Handlers

Interface

interface SemanticHandler<T = unknown> {
  readonly name: string;
  resolve(
    transport: TransportHandler,
    location: string,
    context: SemanticContext
  ): Promise<Resource<T>>;
  deposit?(
    transport: TransportHandler,
    location: string,
    data: T,
    context: SemanticContext
  ): Promise<void>;
  exists?(
    transport: TransportHandler,
    location: string,
    context: SemanticContext
  ): Promise<boolean>;
  delete?(transport: TransportHandler, location: string, context: SemanticContext): Promise<void>;
}

interface SemanticContext {
  url: string;
  semantic: string;
  transport: string;
  location: string;
  timestamp: Date;
  params?: TransportParams;
}

Text Semantic

UTF-8 text handling.

const arl = arp.parse("arp:text:file://./hello.txt");

await arl.deposit("Hello, World!");

const resource = await arl.resolve();
// resource.type = "text"
// resource.content = "Hello, World!" (string)
// resource.meta.encoding = "utf-8"
// resource.meta.mimeType = "text/plain"

Binary Semantic

Raw binary data handling.

const arl = arp.parse("arp:binary:file://./data.bin");

// Multiple input types supported
await arl.deposit(Buffer.from([1, 2, 3, 4]));
await arl.deposit(new Uint8Array([1, 2, 3, 4]));
await arl.deposit(new ArrayBuffer(4));
await arl.deposit([1, 2, 3, 4]); // number[]

const resource = await arl.resolve();
// resource.type = "binary"
// resource.content = Buffer

Error Handling

import { ARPError, ParseError, TransportError, SemanticError } from "@resourcexjs/arp";

try {
  const arl = arp.parse("invalid-url");
} catch (error) {
  if (error instanceof ParseError) {
    console.error("Invalid ARP URL:", error.url);
  }
}

try {
  await arl.resolve();
} catch (error) {
  if (error instanceof TransportError) {
    console.error("Transport failed:", error.transport);
  }
  if (error instanceof SemanticError) {
    console.error("Semantic failed:", error.semantic);
  }
}

Error Hierarchy

ARPError (base)
├── ParseError      - Invalid ARP URL format
├── TransportError  - Transport operation failed
└── SemanticError   - Semantic operation failed

Examples

Copy File

const source = arp.parse("arp:binary:file://./source.bin");
const dest = arp.parse("arp:binary:file://./dest.bin");

const { content } = await source.resolve();
await dest.deposit(content);

Download and Save

const remote = arp.parse("arp:text:https://example.com/data.txt");
const local = arp.parse("arp:text:file://./downloaded.txt");

const { content } = await remote.resolve();
await local.deposit(content);

Conditional Write

const arl = arp.parse("arp:text:file://./config.txt");

if (!(await arl.exists())) {
  await arl.deposit("default config");
}

Process Directory

const dir = arp.parse("arp:text:file://./data");

// List all JSON files recursively
const files = await dir.list({ recursive: true, pattern: "*.json" });

for (const file of files) {
  const fileArl = arp.parse(`arp:text:file://./data/${file}`);
  const { content } = await fileArl.resolve();
  console.log(`${file}: ${content.length} chars`);
}

Custom Handlers

Custom Transport

import type { TransportHandler, TransportResult, TransportParams } from "@resourcexjs/arp";

class S3Transport implements TransportHandler {
  readonly name = "s3";

  async get(location: string, params?: TransportParams): Promise<TransportResult> {
    // location format: "bucket-name/key/path"
    const [bucket, ...keyParts] = location.split("/");
    const key = keyParts.join("/");

    const data = await s3.getObject({ Bucket: bucket, Key: key });
    return {
      content: Buffer.from(await data.Body!.transformToByteArray()),
      metadata: { type: "file", size: data.ContentLength },
    };
  }

  async set(location: string, content: Buffer, params?: TransportParams): Promise<void> {
    const [bucket, ...keyParts] = location.split("/");
    await s3.putObject({ Bucket: bucket, Key: keyParts.join("/"), Body: content });
  }

  async exists(location: string): Promise<boolean> {
    try {
      const [bucket, ...keyParts] = location.split("/");
      await s3.headObject({ Bucket: bucket, Key: keyParts.join("/") });
      return true;
    } catch {
      return false;
    }
  }

  async delete(location: string): Promise<void> {
    const [bucket, ...keyParts] = location.split("/");
    await s3.deleteObject({ Bucket: bucket, Key: keyParts.join("/") });
  }
}

// Register and use
const arp = createARP();
arp.registerTransport(new S3Transport());

const arl = arp.parse("arp:binary:s3://my-bucket/path/file.bin");

Custom Semantic

import type { SemanticHandler, Resource, SemanticContext, ResourceMeta } from "@resourcexjs/arp";
import type { TransportHandler } from "@resourcexjs/arp";

interface JsonResource extends Resource<unknown> {
  type: "json";
  content: unknown;
}

class JsonSemantic implements SemanticHandler<unknown> {
  readonly name = "json";

  async resolve(
    transport: TransportHandler,
    location: string,
    context: SemanticContext
  ): Promise<JsonResource> {
    const result = await transport.get(location, context.params);
    const text = result.content.toString("utf-8");
    const content = JSON.parse(text);

    const meta: ResourceMeta = {
      url: context.url,
      semantic: context.semantic,
      transport: context.transport,
      location: context.location,
      size: result.content.length,
      encoding: "utf-8",
      mimeType: "application/json",
      resolvedAt: context.timestamp.toISOString(),
      type: "file",
    };

    return { type: "json", content, meta };
  }

  async deposit(
    transport: TransportHandler,
    location: string,
    data: unknown,
    context: SemanticContext
  ): Promise<void> {
    const json = JSON.stringify(data, null, 2);
    const buffer = Buffer.from(json, "utf-8");
    await transport.set(location, buffer, context.params);
  }
}

// Register and use
arp.registerSemantic(new JsonSemantic());

const arl = arp.parse("arp:json:file://./config.json");
await arl.deposit({ key: "value", nested: { foo: "bar" } });
const { content } = await arl.resolve(); // parsed object

Exports

// Core
export { ARP, createARP, type ARPConfig };
export type { ARI, ARL };
export const VERSION: string;

// Errors
export { ARPError, ParseError, TransportError, SemanticError };

// Transport
export type { TransportHandler, TransportResult, TransportParams, ListOptions };
export { FileTransportHandler, fileTransport };
export { HttpTransportHandler, httpTransport, httpsTransport };

// Semantic
export type { Resource, SemanticHandler, ResourceMeta, SemanticContext };
export type { TextResource, BinaryResource, BinaryInput };
export { TextSemanticHandler, textSemantic };
export { BinarySemanticHandler, binarySemantic };

License

Apache-2.0