agent-relay 1.6.0 → 2.0.0

package/dist/protocol/channels.d.ts

@@ -1,211 +0,0 @@
-/**
- * Channel and User Protocol Types
- *
- * Extends the Agent Relay Protocol to support:
- * - First-class user entities (humans, not just AI agents)
- * - Channels for group communication
- * - Direct messaging between any combination of users and agents
- */
-import { PROTOCOL_VERSION, type Envelope, type EntityType } from './types.js';
-export { PROTOCOL_VERSION };
-/**
- * Extended message types for channels.
- */
-export type ChannelMessageType = 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING';
-/**
- * Check if an entity type represents a user.
- */
-export declare function isUserEntity(entityType: EntityType | undefined): boolean;
-/**
- * Check if an entity type represents an agent.
- * Undefined defaults to agent for backwards compatibility.
- */
-export declare function isAgentEntity(entityType: EntityType | undefined): boolean;
-/**
- * Attachment metadata for messages.
- */
-export interface MessageAttachment {
-    id: string;
-    filename: string;
-    mimeType: string;
-    size?: number;
-    url?: string;
-    data?: string;
-}
-/**
- * Payload for CHANNEL_JOIN message.
- * Sent when a user or agent joins a channel.
- */
-export interface ChannelJoinPayload {
-    /** The channel to join (e.g., '#general', 'dm:alice:bob') */
-    channel: string;
-    /** Optional display name for the channel member list */
-    displayName?: string;
-    /** Optional avatar URL */
-    avatarUrl?: string;
-    /**
-     * Optional member name to add to channel.
-     * If provided, adds this member instead of the sender.
-     * Used for admin operations (e.g., adding agents via dashboard).
-     */
-    member?: string;
-}
-/**
- * Payload for CHANNEL_LEAVE message.
- * Sent when a user or agent leaves a channel.
- */
-export interface ChannelLeavePayload {
-    /** The channel to leave */
-    channel: string;
-    /** Optional reason for leaving */
-    reason?: string;
-    /**
-     * Optional member name to remove from channel.
-     * If provided, removes this member instead of the sender.
-     * Used for admin operations (e.g., removing members via dashboard).
-     */
-    member?: string;
-}
-/**
- * Payload for CHANNEL_MESSAGE.
- * Sent when posting a message to a channel.
- */
-export interface ChannelMessagePayload {
-    /** The target channel */
-    channel: string;
-    /** Message content */
-    body: string;
-    /** Optional thread ID for threaded replies */
-    thread?: string;
-    /** Optional attachments */
-    attachments?: MessageAttachment[];
-    /** Optional metadata */
-    data?: Record<string, unknown>;
-    /** Optional list of mentioned users/agents */
-    mentions?: string[];
-}
-/**
- * Channel member info.
- */
-export interface ChannelMember {
-    name: string;
-    entityType: EntityType;
-    displayName?: string;
-    avatarUrl?: string;
-    status?: 'online' | 'away' | 'offline';
-}
-/**
- * Payload for CHANNEL_INFO.
- * Contains metadata about a channel.
- */
-export interface ChannelInfoPayload {
-    /** Channel identifier */
-    channel: string;
-    /** Human-readable channel name */
-    name: string;
-    /** Optional description */
-    description?: string;
-    /** Optional current topic */
-    topic?: string;
-    /** List of members */
-    members: ChannelMember[];
-    /** When the channel was created */
-    createdAt: string;
-    /** Whether the channel is private */
-    isPrivate?: boolean;
-}
-/**
- * Payload for CHANNEL_MEMBERS.
- * List of members in a channel.
- */
-export interface ChannelMembersPayload {
-    channel: string;
-    members: ChannelMember[];
-}
-/**
- * Payload for CHANNEL_TYPING.
- * Indicates someone is typing in a channel.
- */
-export interface ChannelTypingPayload {
-    channel: string;
-    isTyping: boolean;
-}
-export type ChannelJoinEnvelope = Envelope<ChannelJoinPayload> & {
-    type: 'CHANNEL_JOIN';
-};
-export type ChannelLeaveEnvelope = Envelope<ChannelLeavePayload> & {
-    type: 'CHANNEL_LEAVE';
-};
-export type ChannelMessageEnvelope = Envelope<ChannelMessagePayload> & {
-    type: 'CHANNEL_MESSAGE';
-};
-export type ChannelInfoEnvelope = Envelope<ChannelInfoPayload> & {
-    type: 'CHANNEL_INFO';
-};
-/**
- * Type guard to check if an envelope is a channel message.
- */
-export declare function isChannelMessage(envelope: {
-    type: string;
-}): envelope is ChannelMessageEnvelope;
-/**
- * Type guard to check if an envelope is a channel join.
- */
-export declare function isChannelJoin(envelope: {
-    type: string;
-}): envelope is ChannelJoinEnvelope;
-/**
- * Type guard to check if an envelope is a channel leave.
- */
-export declare function isChannelLeave(envelope: {
-    type: string;
-}): envelope is ChannelLeaveEnvelope;
-/**
- * Create a CHANNEL_JOIN envelope.
- */
-export declare function createChannelJoinEnvelope(from: string, channel: string, options?: {
-    displayName?: string;
-    avatarUrl?: string;
-}): ChannelJoinEnvelope;
-/**
- * Create a CHANNEL_LEAVE envelope.
- */
-export declare function createChannelLeaveEnvelope(from: string, channel: string, reason?: string): ChannelLeaveEnvelope;
-/**
- * Create a CHANNEL_MESSAGE envelope.
- */
-export declare function createChannelMessageEnvelope(from: string, channel: string, body: string, options?: {
-    thread?: string;
-    mentions?: string[];
-    attachments?: MessageAttachment[];
-    data?: Record<string, unknown>;
-}): ChannelMessageEnvelope;
-/**
- * Parse a DM channel name to extract participants.
- * DM channels follow the format: dm:<participant1>:<participant2>:...
- */
-export declare function parseDmChannel(channel: string): string[] | null;
-/**
- * Create a DM channel name from participants.
- * Participants are sorted alphabetically for consistency.
- */
-export declare function createDmChannelName(...participants: string[]): string;
-/**
- * Check if a channel is a DM (direct message).
- */
-export declare function isDmChannel(channel: string): boolean;
-/**
- * Check if a channel is private.
- */
-export declare function isPrivateChannel(channel: string): boolean;
-/**
- * Check if a channel is a public channel (starts with #).
- */
-export declare function isPublicChannel(channel: string): boolean;
-/**
- * Normalize channel name for storage/lookup.
- * - Removes leading # from public channels
- * - Sorts participants in DM channels
- */
-export declare function normalizeChannelName(channel: string): string;
-//# sourceMappingURL=channels.d.ts.map

package/dist/protocol/channels.js

@@ -1,154 +0,0 @@
-/**
- * Channel and User Protocol Types
- *
- * Extends the Agent Relay Protocol to support:
- * - First-class user entities (humans, not just AI agents)
- * - Channels for group communication
- * - Direct messaging between any combination of users and agents
- */
-import { generateId } from '../utils/id-generator.js';
-import { PROTOCOL_VERSION } from './types.js';
-// Re-export for convenience
-export { PROTOCOL_VERSION };
-/**
- * Check if an entity type represents a user.
- */
-export function isUserEntity(entityType) {
-    return entityType === 'user';
-}
-/**
- * Check if an entity type represents an agent.
- * Undefined defaults to agent for backwards compatibility.
- */
-export function isAgentEntity(entityType) {
-    return entityType === 'agent' || entityType === undefined;
-}
-/**
- * Type guard to check if an envelope is a channel message.
- */
-export function isChannelMessage(envelope) {
-    return envelope.type === 'CHANNEL_MESSAGE';
-}
-/**
- * Type guard to check if an envelope is a channel join.
- */
-export function isChannelJoin(envelope) {
-    return envelope.type === 'CHANNEL_JOIN';
-}
-/**
- * Type guard to check if an envelope is a channel leave.
- */
-export function isChannelLeave(envelope) {
-    return envelope.type === 'CHANNEL_LEAVE';
-}
-/**
- * Create a CHANNEL_JOIN envelope.
- */
-export function createChannelJoinEnvelope(from, channel, options) {
-    return {
-        v: PROTOCOL_VERSION,
-        type: 'CHANNEL_JOIN',
-        id: generateId(),
-        ts: Date.now(),
-        from,
-        payload: {
-            channel,
-            displayName: options?.displayName,
-            avatarUrl: options?.avatarUrl,
-        },
-    };
-}
-/**
- * Create a CHANNEL_LEAVE envelope.
- */
-export function createChannelLeaveEnvelope(from, channel, reason) {
-    return {
-        v: PROTOCOL_VERSION,
-        type: 'CHANNEL_LEAVE',
-        id: generateId(),
-        ts: Date.now(),
-        from,
-        payload: {
-            channel,
-            reason,
-        },
-    };
-}
-/**
- * Create a CHANNEL_MESSAGE envelope.
- */
-export function createChannelMessageEnvelope(from, channel, body, options) {
-    return {
-        v: PROTOCOL_VERSION,
-        type: 'CHANNEL_MESSAGE',
-        id: generateId(),
-        ts: Date.now(),
-        from,
-        payload: {
-            channel,
-            body,
-            thread: options?.thread,
-            mentions: options?.mentions,
-            attachments: options?.attachments,
-            data: options?.data,
-        },
-    };
-}
-/**
- * Parse a DM channel name to extract participants.
- * DM channels follow the format: dm:<participant1>:<participant2>:...
- */
-export function parseDmChannel(channel) {
-    if (!channel.startsWith('dm:')) {
-        return null;
-    }
-    const parts = channel.split(':').slice(1);
-    return parts.length >= 2 ? parts : null;
-}
-/**
- * Create a DM channel name from participants.
- * Participants are sorted alphabetically for consistency.
- */
-export function createDmChannelName(...participants) {
-    if (participants.length < 2) {
-        throw new Error('DM requires at least 2 participants');
-    }
-    const sorted = [...participants].sort();
-    return `dm:${sorted.join(':')}`;
-}
-/**
- * Check if a channel is a DM (direct message).
- */
-export function isDmChannel(channel) {
-    return channel.startsWith('dm:');
-}
-/**
- * Check if a channel is private.
- */
-export function isPrivateChannel(channel) {
-    return channel.startsWith('private:');
-}
-/**
- * Check if a channel is a public channel (starts with #).
- */
-export function isPublicChannel(channel) {
-    return channel.startsWith('#');
-}
-/**
- * Normalize channel name for storage/lookup.
- * - Removes leading # from public channels
- * - Sorts participants in DM channels
- */
-export function normalizeChannelName(channel) {
-    if (channel.startsWith('#')) {
-        return channel.slice(1);
-    }
-    if (channel.startsWith('dm:')) {
-        const participants = parseDmChannel(channel);
-        if (participants) {
-            return createDmChannelName(...participants);
-        }
-    }
-    return channel;
-}
-//# sourceMappingURL=channels.js.map

package/dist/protocol/framing.d.ts

@@ -1,94 +0,0 @@
-/**
- * Frame encoding/decoding for the agent relay protocol.
- *
- * Wire format:
- * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
- * - 4 bytes: big-endian payload length
- * - N bytes: payload (JSON or MessagePack encoded)
- *
- * Optimizations:
- * - Ring buffer to avoid Buffer.concat allocations
- * - MessagePack support for faster serialization (optional)
- * - Zero-copy frame extraction where possible
- */
-import type { Envelope } from './types.js';
-export declare const MAX_FRAME_BYTES: number;
-export declare const HEADER_SIZE = 5;
-export declare const LEGACY_HEADER_SIZE = 4;
-export type WireFormat = 'json' | 'msgpack';
-/**
- * Initialize MessagePack support. Call this at startup if you want msgpack.
- * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
- */
-export declare function initMessagePack(): Promise<boolean>;
-/**
- * Check if MessagePack is available.
- */
-export declare function hasMessagePack(): boolean;
-/**
- * Encode a message envelope into a framed buffer.
- *
- * @param envelope - The envelope to encode
- * @param format - Wire format to use (default: 'json')
- * @returns Framed buffer ready for socket write
- */
-export declare function encodeFrame(envelope: Envelope, format?: WireFormat): Buffer;
-/**
- * Encode a frame in legacy format (no format byte, JSON only).
- * Used for backwards compatibility with older clients.
- */
-export declare function encodeFrameLegacy(envelope: Envelope): Buffer;
-/**
- * Ring buffer-based frame parser for streaming data.
- *
- * Optimizations:
- * - Pre-allocated buffer avoids GC pressure from Buffer.concat
- * - Compaction only when necessary (wrap-around)
- * - Direct parsing from buffer offsets
- */
-export declare class FrameParser {
-    private ring;
-    private head;
-    private tail;
-    private readonly capacity;
-    private readonly maxFrameBytes;
-    private format;
-    private legacyMode;
-    constructor(maxFrameBytes?: number);
-    /**
-     * Set the expected wire format for parsing.
-     */
-    setFormat(format: WireFormat): void;
-    /**
-     * Enable legacy mode (4-byte header, JSON only).
-     */
-    setLegacyMode(legacy: boolean): void;
-    /**
-     * Get current unread bytes in buffer.
-     */
-    get pendingBytes(): number;
-    /**
-     * Push data into the parser and extract complete frames.
-     *
-     * @param data - Incoming data buffer
-     * @returns Array of parsed envelope frames
-     */
-    push(data: Buffer): Envelope[];
-    /**
-     * Extract all complete frames from the buffer.
-     */
-    private extractFrames;
-    /**
-     * Decode payload based on format byte.
-     */
-    private decodePayload;
-    /**
-     * Compact the buffer by shifting unread data to the start.
-     */
-    private compact;
-    /**
-     * Reset parser state (e.g., on connection reset).
-     */
-    reset(): void;
-}
-//# sourceMappingURL=framing.d.ts.map

package/dist/protocol/framing.js

@@ -1,240 +0,0 @@
-/**
- * Frame encoding/decoding for the agent relay protocol.
- *
- * Wire format:
- * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
- * - 4 bytes: big-endian payload length
- * - N bytes: payload (JSON or MessagePack encoded)
- *
- * Optimizations:
- * - Ring buffer to avoid Buffer.concat allocations
- * - MessagePack support for faster serialization (optional)
- * - Zero-copy frame extraction where possible
- */
-export const MAX_FRAME_BYTES = 1024 * 1024; // 1 MiB default
-export const HEADER_SIZE = 5; // 1 byte format + 4 bytes length
-export const LEGACY_HEADER_SIZE = 4; // For backwards compatibility
-// Format indicator bytes
-const FORMAT_JSON = 0;
-const FORMAT_MSGPACK = 1;
-// Optional MessagePack - loaded dynamically if available
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let msgpack = null;
-/**
- * Initialize MessagePack support. Call this at startup if you want msgpack.
- * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
- */
-export async function initMessagePack() {
-    if (msgpack)
-        return true; // Already initialized
-    try {
-        // Dynamic import to avoid compile-time dependency
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const mod = await import('@msgpack/msgpack');
-        const encode = mod.encode || mod.default?.encode;
-        const decode = mod.decode || mod.default?.decode;
-        if (encode && decode) {
-            msgpack = { encode, decode };
-            return true;
-        }
-        return false;
-    }
-    catch {
-        // MessagePack not installed, JSON-only mode
-        return false;
-    }
-}
-/**
- * Check if MessagePack is available.
- */
-export function hasMessagePack() {
-    return msgpack !== null;
-}
-/**
- * Encode a message envelope into a framed buffer.
- *
- * @param envelope - The envelope to encode
- * @param format - Wire format to use (default: 'json')
- * @returns Framed buffer ready for socket write
- */
-export function encodeFrame(envelope, format = 'json') {
-    let data;
-    let formatByte;
-    if (format === 'msgpack' && msgpack) {
-        // MessagePack: more compact, faster
-        const encoded = msgpack.encode(envelope);
-        data = Buffer.from(encoded.buffer, encoded.byteOffset, encoded.byteLength);
-        formatByte = FORMAT_MSGPACK;
-    }
-    else {
-        // JSON: human-readable, always available
-        data = Buffer.from(JSON.stringify(envelope), 'utf-8');
-        formatByte = FORMAT_JSON;
-    }
-    if (data.length > MAX_FRAME_BYTES) {
-        throw new Error(`Frame too large: ${data.length} > ${MAX_FRAME_BYTES}`);
-    }
-    const header = Buffer.alloc(HEADER_SIZE);
-    header.writeUInt8(formatByte, 0);
-    header.writeUInt32BE(data.length, 1);
-    return Buffer.concat([header, data]);
-}
-/**
- * Encode a frame in legacy format (no format byte, JSON only).
- * Used for backwards compatibility with older clients.
- */
-export function encodeFrameLegacy(envelope) {
-    const json = JSON.stringify(envelope);
-    const data = Buffer.from(json, 'utf-8');
-    if (data.length > MAX_FRAME_BYTES) {
-        throw new Error(`Frame too large: ${data.length} > ${MAX_FRAME_BYTES}`);
-    }
-    const header = Buffer.alloc(LEGACY_HEADER_SIZE);
-    header.writeUInt32BE(data.length, 0);
-    return Buffer.concat([header, data]);
-}
-/**
- * Ring buffer-based frame parser for streaming data.
- *
- * Optimizations:
- * - Pre-allocated buffer avoids GC pressure from Buffer.concat
- * - Compaction only when necessary (wrap-around)
- * - Direct parsing from buffer offsets
- */
-export class FrameParser {
-    ring;
-    head = 0; // Read position
-    tail = 0; // Write position
-    capacity;
-    maxFrameBytes;
-    format = 'json';
-    legacyMode = false; // Auto-detect legacy clients
-    constructor(maxFrameBytes = MAX_FRAME_BYTES) {
-        this.maxFrameBytes = maxFrameBytes;
-        // Allocate 2x max frame for ring buffer headroom
-        this.capacity = maxFrameBytes * 2 + HEADER_SIZE;
-        this.ring = Buffer.allocUnsafe(this.capacity);
-    }
-    /**
-     * Set the expected wire format for parsing.
-     */
-    setFormat(format) {
-        this.format = format;
-    }
-    /**
-     * Enable legacy mode (4-byte header, JSON only).
-     */
-    setLegacyMode(legacy) {
-        this.legacyMode = legacy;
-    }
-    /**
-     * Get current unread bytes in buffer.
-     */
-    get pendingBytes() {
-        return this.tail - this.head;
-    }
-    /**
-     * Push data into the parser and extract complete frames.
-     *
-     * @param data - Incoming data buffer
-     * @returns Array of parsed envelope frames
-     */
-    push(data) {
-        // Check if we have room at the end
-        const spaceAtEnd = this.capacity - this.tail;
-        if (data.length > spaceAtEnd) {
-            // Need to compact: shift unread data to start
-            this.compact();
-            // Check again after compaction
-            if (data.length > this.capacity - this.tail) {
-                throw new Error(`Buffer overflow: data ${data.length} exceeds capacity`);
-            }
-        }
-        // Copy incoming data to ring buffer (single copy, no concat)
-        data.copy(this.ring, this.tail);
-        this.tail += data.length;
-        // Extract complete frames
-        return this.extractFrames();
-    }
-    /**
-     * Extract all complete frames from the buffer.
-     */
-    extractFrames() {
-        const frames = [];
-        const headerSize = this.legacyMode ? LEGACY_HEADER_SIZE : HEADER_SIZE;
-        while (this.pendingBytes >= headerSize) {
-            // Read frame metadata
-            let formatByte = FORMAT_JSON;
-            let frameLength;
-            if (this.legacyMode) {
-                frameLength = this.ring.readUInt32BE(this.head);
-            }
-            else {
-                formatByte = this.ring.readUInt8(this.head);
-                frameLength = this.ring.readUInt32BE(this.head + 1);
-            }
-            // Validate frame size
-            if (frameLength > this.maxFrameBytes) {
-                throw new Error(`Frame too large: ${frameLength} > ${this.maxFrameBytes}`);
-            }
-            const totalLength = headerSize + frameLength;
-            // Check if we have the complete frame
-            if (this.pendingBytes < totalLength) {
-                break; // Need more data
-            }
-            // Extract and parse the frame
-            const payloadStart = this.head + headerSize;
-            const payloadEnd = this.head + totalLength;
-            let envelope;
-            try {
-                envelope = this.decodePayload(formatByte, payloadStart, payloadEnd);
-            }
-            catch (err) {
-                throw new Error(`Invalid frame payload: ${err}`);
-            }
-            // Advance read position
-            this.head += totalLength;
-            frames.push(envelope);
-        }
-        // Opportunistic compaction if we've consumed most of the buffer
-        if (this.head > this.capacity / 2 && this.pendingBytes < this.capacity / 4) {
-            this.compact();
-        }
-        return frames;
-    }
-    /**
-     * Decode payload based on format byte.
-     */
-    decodePayload(formatByte, start, end) {
-        if (formatByte === FORMAT_MSGPACK && msgpack) {
-            // MessagePack decode
-            return msgpack.decode(this.ring.subarray(start, end));
-        }
-        else {
-            // JSON decode (default)
-            return JSON.parse(this.ring.toString('utf-8', start, end));
-        }
-    }
-    /**
-     * Compact the buffer by shifting unread data to the start.
-     */
-    compact() {
-        if (this.head === 0)
-            return;
-        const unread = this.pendingBytes;
-        if (unread > 0) {
-            // Copy unread data to start of buffer
-            this.ring.copy(this.ring, 0, this.head, this.tail);
-        }
-        this.head = 0;
-        this.tail = unread;
-    }
-    /**
-     * Reset parser state (e.g., on connection reset).
-     */
-    reset() {
-        this.head = 0;
-        this.tail = 0;
-    }
-}
-//# sourceMappingURL=framing.js.map

package/dist/protocol/index.d.ts

@@ -1,4 +0,0 @@
-export * from './types.js';
-export * from './framing.js';
-export * from './channels.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/protocol/index.js

@@ -1,4 +0,0 @@
-export * from './types.js';
-export * from './framing.js';
-export * from './channels.js';
-//# sourceMappingURL=index.js.map