agent-relay 1.6.0 → 2.0.4

package/packages/policy/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agent-relay/policy",
+  "version": "2.0.4",
+  "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-relay/config": "2.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/policy"
+  }
+}

package/packages/protocol/dist/channels.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 EntityType, type MessageAttachment, type ChannelJoinEnvelope, type ChannelLeaveEnvelope, type ChannelMessageEnvelope } from './types.js';
+export type { MessageAttachment, ChannelJoinPayload, ChannelLeavePayload, ChannelMessagePayload, ChannelJoinEnvelope, ChannelLeaveEnvelope, ChannelMessageEnvelope, } 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';
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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/packages/protocol/dist/channels.js

@@ -0,0 +1,154 @@
+/**
+ * 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 './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/packages/protocol/dist/framing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Frame encoding/decoding for the Agent Relay protocol.
+ * @agent-relay/sdk
+ *
+ * Wire format:
+ * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
+ * - 4 bytes: big-endian payload length
+ * - N bytes: payload (JSON or MessagePack encoded)
+ *
+ * Legacy format (for backwards compatibility):
+ * - 4 bytes: big-endian payload length
+ * - N bytes: JSON payload
+ */
+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.
+ * 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.
+ */
+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[];
+    private extractFrames;
+    private decodePayload;
+    private compact;
+    /**
+     * Reset parser state.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=framing.d.ts.map

package/packages/protocol/dist/framing.js

@@ -0,0 +1,206 @@
+/**
+ * Frame encoding/decoding for the Agent Relay protocol.
+ * @agent-relay/sdk
+ *
+ * Wire format:
+ * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
+ * - 4 bytes: big-endian payload length
+ * - N bytes: payload (JSON or MessagePack encoded)
+ *
+ * Legacy format (for backwards compatibility):
+ * - 4 bytes: big-endian payload length
+ * - N bytes: JSON payload
+ */
+export const MAX_FRAME_BYTES = 1024 * 1024; // 1 MiB
+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
+let msgpack = null;
+/**
+ * Initialize MessagePack support.
+ * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
+ */
+export async function initMessagePack() {
+    if (msgpack)
+        return true;
+    try {
+        // 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 {
+        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) {
+        const encoded = msgpack.encode(envelope);
+        data = Buffer.from(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+        formatByte = FORMAT_MSGPACK;
+    }
+    else {
+        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.
+ */
+export class FrameParser {
+    ring;
+    head = 0;
+    tail = 0;
+    capacity;
+    maxFrameBytes;
+    format = 'json';
+    legacyMode = false;
+    constructor(maxFrameBytes = MAX_FRAME_BYTES) {
+        this.maxFrameBytes = maxFrameBytes;
+        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) {
+        const spaceAtEnd = this.capacity - this.tail;
+        if (data.length > spaceAtEnd) {
+            this.compact();
+            if (data.length > this.capacity - this.tail) {
+                throw new Error(`Buffer overflow: data ${data.length} exceeds capacity`);
+            }
+        }
+        data.copy(this.ring, this.tail);
+        this.tail += data.length;
+        return this.extractFrames();
+    }
+    extractFrames() {
+        const frames = [];
+        const headerSize = this.legacyMode ? LEGACY_HEADER_SIZE : HEADER_SIZE;
+        while (this.pendingBytes >= headerSize) {
+            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);
+            }
+            if (frameLength > this.maxFrameBytes) {
+                throw new Error(`Frame too large: ${frameLength} > ${this.maxFrameBytes}`);
+            }
+            const totalLength = headerSize + frameLength;
+            if (this.pendingBytes < totalLength) {
+                break;
+            }
+            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}`);
+            }
+            this.head += totalLength;
+            frames.push(envelope);
+        }
+        if (this.head > this.capacity / 2 && this.pendingBytes < this.capacity / 4) {
+            this.compact();
+        }
+        return frames;
+    }
+    decodePayload(formatByte, start, end) {
+        if (formatByte === FORMAT_MSGPACK && msgpack) {
+            return msgpack.decode(this.ring.subarray(start, end));
+        }
+        else {
+            return JSON.parse(this.ring.toString('utf-8', start, end));
+        }
+    }
+    compact() {
+        if (this.head === 0)
+            return;
+        const unread = this.pendingBytes;
+        if (unread > 0) {
+            this.ring.copy(this.ring, 0, this.head, this.tail);
+        }
+        this.head = 0;
+        this.tail = unread;
+    }
+    /**
+     * Reset parser state.
+     */
+    reset() {
+        this.head = 0;
+        this.tail = 0;
+    }
+}
+//# sourceMappingURL=framing.js.map

package/packages/protocol/dist/index.d.ts

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

package/packages/protocol/dist/index.js

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