agent-relay 2.0.29 → 2.0.32

package/packages/sdk/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * @agent-relay/sdk
+ *
+ * Lightweight SDK for agent-to-agent communication via Agent Relay.
+ *
+ * ## Quick Start (Standalone - No Setup Required)
+ *
+ * ```typescript
+ * import { createRelay } from '@agent-relay/sdk';
+ *
+ * const relay = await createRelay();
+ * const alice = await relay.client('Alice');
+ * const bob = await relay.client('Bob');
+ *
+ * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+ * alice.sendMessage('Bob', 'Hello!');
+ * ```
+ *
+ * ## With External Daemon
+ *
+ * ```typescript
+ * import { RelayClient } from '@agent-relay/sdk';
+ *
+ * const client = new RelayClient({ agentName: 'MyAgent' });
+ * await client.connect();
+ * ```
+ */
+
+// Main client
+export {
+  RelayClient,
+  type ClientState,
+  type ClientConfig,
+  type SyncOptions,
+} from './client.js';
+
+// Standalone relay (in-process daemon for simple use cases)
+export {
+  createRelay,
+  createPair,
+  type Relay,
+  type RelayConfig,
+} from './standalone.js';
+
+// Protocol types (re-export for convenience)
+export {
+  PROTOCOL_VERSION,
+  type MessageType,
+  type PayloadKind,
+  type Envelope,
+  type EntityType,
+  type SendPayload,
+  type SendMeta,
+  type SyncMeta,
+  type DeliveryInfo,
+  type AckPayload,
+  type ErrorCode,
+  type ErrorPayload,
+  type SpeakOnTrigger,
+  type ShadowConfig,
+  // Spawn/release types
+  type SpawnPayload,
+  type SpawnResultPayload,
+  type ReleasePayload,
+  type ReleaseResultPayload,
+  // Channel types
+  type ChannelMessagePayload,
+  type ChannelJoinPayload,
+  type ChannelLeavePayload,
+  type MessageAttachment,
+  // Query/response types
+  type StatusResponsePayload,
+  type InboxMessage,
+  type MessagesResponsePayload,
+  type AgentInfo,
+  type HealthResponsePayload,
+  type CrashRecord,
+  type AlertRecord,
+  type MetricsResponsePayload,
+  type AgentMetrics,
+  // Consensus types
+  type ConsensusType,
+  type VoteValue,
+  type ProposalStatus,
+  type CreateProposalOptions,
+  type VoteOptions,
+} from './protocol/index.js';
+
+// Framing utilities
+export {
+  encodeFrame,
+  encodeFrameLegacy,
+  FrameParser,
+  MAX_FRAME_BYTES,
+} from './protocol/index.js';
+
+// Log utilities (file-based, doesn't require connection)
+export {
+  getLogs,
+  listLoggedAgents,
+  type GetLogsOptions,
+  type LogsResult,
+} from './logs.js';

package/packages/sdk/src/logs.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { getLogs, listLoggedAgents } from './logs.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+// Mock fs/promises
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+  readdir: vi.fn(),
+  stat: vi.fn(),
+}));
+
+describe('getLogs', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return log content when file exists', async () => {
+    const mockContent = 'line 1\nline 2\nline 3\nline 4\nline 5';
+    vi.mocked(fs.stat).mockResolvedValue({} as any);
+    vi.mocked(fs.readFile).mockResolvedValue(mockContent);
+
+    const result = await getLogs('Worker1', { logsDir: '/test/logs', lines: 3 });
+
+    expect(result.found).toBe(true);
+    expect(result.agent).toBe('Worker1');
+    expect(result.content).toBe('line 3\nline 4\nline 5');
+    expect(result.lineCount).toBe(3);
+  });
+
+  it('should return found=false when file does not exist', async () => {
+    vi.mocked(fs.stat).mockRejectedValue(new Error('ENOENT'));
+
+    const result = await getLogs('NonExistent', { logsDir: '/test/logs' });
+
+    expect(result.found).toBe(false);
+    expect(result.agent).toBe('NonExistent');
+    expect(result.content).toBe('');
+    expect(result.lineCount).toBe(0);
+  });
+
+  it('should use default lines value of 50', async () => {
+    const lines = Array.from({ length: 100 }, (_, i) => `line ${i + 1}`).join('\n');
+    vi.mocked(fs.stat).mockResolvedValue({} as any);
+    vi.mocked(fs.readFile).mockResolvedValue(lines);
+
+    const result = await getLogs('Worker1', { logsDir: '/test/logs' });
+
+    expect(result.found).toBe(true);
+    expect(result.lineCount).toBe(50);
+  });
+
+  it('should handle empty files', async () => {
+    vi.mocked(fs.stat).mockResolvedValue({} as any);
+    vi.mocked(fs.readFile).mockResolvedValue('');
+
+    const result = await getLogs('Worker1', { logsDir: '/test/logs' });
+
+    expect(result.found).toBe(true);
+    expect(result.content).toBe('');
+    expect(result.lineCount).toBe(0);
+  });
+});
+
+describe('listLoggedAgents', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return agent names from log files', async () => {
+    vi.mocked(fs.readdir).mockResolvedValue([
+      'Alice.log',
+      'Bob.log',
+      'Worker1.log',
+      'some-other-file.txt',
+    ] as any);
+
+    const result = await listLoggedAgents('/test/logs');
+
+    expect(result).toEqual(['Alice', 'Bob', 'Worker1']);
+  });
+
+  it('should return empty array when directory does not exist', async () => {
+    vi.mocked(fs.readdir).mockRejectedValue(new Error('ENOENT'));
+
+    const result = await listLoggedAgents('/nonexistent');
+
+    expect(result).toEqual([]);
+  });
+
+  it('should return empty array when no log files exist', async () => {
+    vi.mocked(fs.readdir).mockResolvedValue(['file.txt', 'README.md'] as any);
+
+    const result = await listLoggedAgents('/test/logs');
+
+    expect(result).toEqual([]);
+  });
+});

package/packages/sdk/src/logs.ts

@@ -0,0 +1,126 @@
+/**
+ * Log reading utilities for Agent Relay SDK.
+ *
+ * These utilities read agent logs from the local filesystem.
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Options for reading agent logs.
+ */
+export interface GetLogsOptions {
+  /** Directory containing worker logs. Defaults to `.agent-relay/worker-logs` in cwd. */
+  logsDir?: string;
+  /** Number of lines to return from the end. Default: 50 */
+  lines?: number;
+}
+
+/**
+ * Result of a logs query.
+ */
+export interface LogsResult {
+  /** Agent name */
+  agent: string;
+  /** Log content */
+  content: string;
+  /** Whether log file exists */
+  found: boolean;
+  /** Number of lines returned */
+  lineCount: number;
+}
+
+/**
+ * Get the default logs directory path.
+ */
+function getDefaultLogsDir(): string {
+  return join(process.cwd(), '.agent-relay', 'worker-logs');
+}
+
+/**
+ * Read the last N lines from a file.
+ */
+async function tailFile(filePath: string, lines: number): Promise<string> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const allLines = content.split('\n');
+    const tailLines = allLines.slice(-lines);
+    return tailLines.join('\n').trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Get logs for a specific agent.
+ *
+ * @example
+ * ```typescript
+ * import { getLogs } from '@agent-relay/sdk';
+ *
+ * const result = await getLogs('Worker1', { lines: 100 });
+ * if (result.found) {
+ *   console.log(result.content);
+ * }
+ * ```
+ *
+ * @param agent - Agent name
+ * @param options - Options for reading logs
+ * @returns Log content and metadata
+ */
+export async function getLogs(
+  agent: string,
+  options: GetLogsOptions = {}
+): Promise<LogsResult> {
+  const logsDir = options.logsDir ?? getDefaultLogsDir();
+  const lines = options.lines ?? 50;
+  const logFile = join(logsDir, `${agent}.log`);
+
+  try {
+    await stat(logFile);
+    const content = await tailFile(logFile, lines);
+    const lineCount = content ? content.split('\n').length : 0;
+
+    return {
+      agent,
+      content,
+      found: true,
+      lineCount,
+    };
+  } catch {
+    return {
+      agent,
+      content: '',
+      found: false,
+      lineCount: 0,
+    };
+  }
+}
+
+/**
+ * List all agents that have log files.
+ *
+ * @example
+ * ```typescript
+ * import { listLoggedAgents } from '@agent-relay/sdk';
+ *
+ * const agents = await listLoggedAgents();
+ * console.log('Agents with logs:', agents);
+ * ```
+ *
+ * @param logsDir - Directory containing worker logs
+ * @returns Array of agent names
+ */
+export async function listLoggedAgents(logsDir?: string): Promise<string[]> {
+  const dir = logsDir ?? getDefaultLogsDir();
+
+  try {
+    const files = await readdir(dir);
+    return files
+      .filter((f) => f.endsWith('.log'))
+      .map((f) => f.replace('.log', ''));
+  } catch {
+    return [];
+  }
+}

package/packages/sdk/src/protocol/framing.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import {
+  encodeFrame,
+  encodeFrameLegacy,
+  FrameParser,
+  HEADER_SIZE,
+  LEGACY_HEADER_SIZE,
+  MAX_FRAME_BYTES,
+  type Envelope,
+} from '@agent-relay/protocol';
+
+describe('protocol framing', () => {
+  describe('legacy format (4-byte header)', () => {
+    it('roundtrips an envelope with correct length prefix', () => {
+      const envelope: Envelope = {
+        v: 1,
+        type: 'PING',
+        id: 'test-1',
+        ts: 1,
+        payload: { nonce: 'abc' },
+      };
+
+      const frame = encodeFrameLegacy(envelope);
+      const declaredLength = frame.readUInt32BE(0);
+      const jsonBytes = frame.subarray(LEGACY_HEADER_SIZE);
+      expect(declaredLength).toBe(jsonBytes.length);
+
+      const parser = new FrameParser();
+      parser.setLegacyMode(true);
+      const [parsed] = parser.push(frame);
+      expect(parsed).toEqual(envelope);
+    });
+
+    it('rejects oversized frames', () => {
+      const oversize = 'x'.repeat(MAX_FRAME_BYTES + 1);
+      const envelope: Envelope = {
+        v: 1,
+        type: 'PING',
+        id: 'test-oversize',
+        ts: 1,
+        payload: { nonce: oversize },
+      };
+
+      expect(() => encodeFrameLegacy(envelope)).toThrow(/Frame too large/);
+    });
+
+    it('handles multiple frames in sequence', () => {
+      const parser = new FrameParser();
+      parser.setLegacyMode(true);
+
+      const envelope1: Envelope = { v: 1, type: 'PING', id: '1', ts: 1, payload: {} };
+      const envelope2: Envelope = { v: 1, type: 'PONG', id: '2', ts: 2, payload: {} };
+
+      const frame1 = encodeFrameLegacy(envelope1);
+      const frame2 = encodeFrameLegacy(envelope2);
+
+      // Send both frames at once
+      const combined = Buffer.concat([frame1, frame2]);
+      const parsed = parser.push(combined);
+
+      expect(parsed).toHaveLength(2);
+      expect(parsed[0]).toEqual(envelope1);
+      expect(parsed[1]).toEqual(envelope2);
+    });
+
+    it('handles partial frames (streaming)', () => {
+      const parser = new FrameParser();
+      parser.setLegacyMode(true);
+
+      const envelope: Envelope = { v: 1, type: 'PING', id: 'stream-test', ts: 1, payload: {} };
+      const frame = encodeFrameLegacy(envelope);
+
+      // Send first half
+      const half = Math.floor(frame.length / 2);
+      let parsed = parser.push(frame.subarray(0, half));
+      expect(parsed).toHaveLength(0); // Not complete yet
+
+      // Send second half
+      parsed = parser.push(frame.subarray(half));
+      expect(parsed).toHaveLength(1);
+      expect(parsed[0]).toEqual(envelope);
+    });
+  });
+
+  describe('new format (5-byte header with format indicator)', () => {
+    it('roundtrips an envelope with JSON format', () => {
+      const envelope: Envelope = {
+        v: 1,
+        type: 'SEND',
+        id: 'new-format-test',
+        ts: Date.now(),
+        to: 'Agent',
+        payload: { kind: 'message', body: 'Hello' },
+      };
+
+      const frame = encodeFrame(envelope, 'json');
+
+      // New format: 1 byte format + 4 bytes length
+      expect(frame.readUInt8(0)).toBe(0); // 0 = JSON
+      const declaredLength = frame.readUInt32BE(1);
+      const jsonBytes = frame.subarray(HEADER_SIZE);
+      expect(declaredLength).toBe(jsonBytes.length);
+
+      const parser = new FrameParser();
+      // Default is new format (legacy = false)
+      const [parsed] = parser.push(frame);
+      expect(parsed).toEqual(envelope);
+    });
+
+    it('handles multiple new format frames', () => {
+      const parser = new FrameParser();
+
+      const envelopes: Envelope[] = [
+        { v: 1, type: 'PING', id: '1', ts: 1, payload: {} },
+        { v: 1, type: 'PONG', id: '2', ts: 2, payload: {} },
+        { v: 1, type: 'SEND', id: '3', ts: 3, to: 'Bob', payload: { kind: 'message', body: 'Hi' } },
+      ];
+
+      const frames = envelopes.map((e) => encodeFrame(e, 'json'));
+      const combined = Buffer.concat(frames);
+
+      const parsed = parser.push(combined);
+      expect(parsed).toHaveLength(3);
+      expect(parsed).toEqual(envelopes);
+    });
+  });
+
+  describe('FrameParser ring buffer', () => {
+    it('handles many small messages efficiently', () => {
+      const parser = new FrameParser();
+      parser.setLegacyMode(true);
+
+      const envelope: Envelope = { v: 1, type: 'PING', id: 'x', ts: 1, payload: {} };
+      const frame = encodeFrameLegacy(envelope);
+
+      // Process 1000 messages
+      let totalParsed = 0;
+      for (let i = 0; i < 1000; i++) {
+        const parsed = parser.push(frame);
+        totalParsed += parsed.length;
+      }
+
+      expect(totalParsed).toBe(1000);
+    });
+
+    it('reports pending bytes correctly', () => {
+      const parser = new FrameParser();
+      parser.setLegacyMode(true);
+
+      expect(parser.pendingBytes).toBe(0);
+
+      // Send partial header
+      const partialHeader = Buffer.alloc(2);
+      partialHeader.writeUInt16BE(0, 0);
+      parser.push(partialHeader);
+
+      expect(parser.pendingBytes).toBe(2);
+
+      // Reset should clear
+      parser.reset();
+      expect(parser.pendingBytes).toBe(0);
+    });
+  });
+});

package/packages/sdk/src/protocol/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Protocol exports for @agent-relay/sdk
+ *
+ * Re-exports from @agent-relay/protocol for backwards compatibility.
+ * New code should import directly from @agent-relay/protocol.
+ */
+
+export * from '@agent-relay/protocol';

package/packages/sdk/src/standalone.ts

@@ -0,0 +1,176 @@
+/**
+ * Standalone Relay - Dead Simple Agent Communication
+ *
+ * Use Agent Relay as a pure communication layer without any external setup.
+ * Just import and go.
+ *
+ * @example
+ * ```typescript
+ * import { createRelay } from '@agent-relay/sdk/standalone';
+ *
+ * const relay = await createRelay();
+ *
+ * const alice = await relay.client('Alice');
+ * const bob = await relay.client('Bob');
+ *
+ * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+ * alice.sendMessage('Bob', 'Hello!');
+ *
+ * await relay.stop();
+ * ```
+ */
+
+import { RelayClient, type ClientConfig } from './client.js';
+
+// Types for the daemon (avoid importing to keep this file lightweight)
+interface DaemonLike {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isRunning: boolean;
+}
+
+export interface RelayConfig {
+  /** Socket path for IPC. Default: /tmp/agent-relay-standalone.sock */
+  socketPath?: string;
+  /** Suppress console logging. Default: true */
+  quiet?: boolean;
+}
+
+export interface Relay {
+  /** Create a connected client for an agent */
+  client(name: string, config?: Partial<ClientConfig>): Promise<RelayClient>;
+  /** Stop the relay and disconnect all clients */
+  stop(): Promise<void>;
+  /** Check if relay is running */
+  readonly isRunning: boolean;
+  /** The socket path being used */
+  readonly socketPath: string;
+}
+
+const DEFAULT_SOCKET_PATH = '/tmp/agent-relay-standalone.sock';
+
+/**
+ * Create a standalone relay for pure agent-to-agent communication.
+ *
+ * This starts an in-process daemon - no external setup required.
+ * Perfect for using Agent Relay as just a communication layer.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const relay = await createRelay();
+ *
+ * const agent1 = await relay.client('Agent1');
+ * const agent2 = await relay.client('Agent2');
+ *
+ * agent2.onMessage = (from, payload) => {
+ *   console.log(`Message from ${from}: ${payload.body}`);
+ * };
+ *
+ * agent1.sendMessage('Agent2', 'Hello!');
+ * ```
+ *
+ * @example With Custom Socket
+ * ```typescript
+ * const relay = await createRelay({ socketPath: '/tmp/my-relay.sock' });
+ * ```
+ */
+export async function createRelay(config: RelayConfig = {}): Promise<Relay> {
+  const socketPath = config.socketPath ?? DEFAULT_SOCKET_PATH;
+  const quiet = config.quiet ?? true;
+
+  // Lazy-load daemon to keep SDK lightweight for client-only users
+  let Daemon: new (config: Record<string, unknown>) => DaemonLike;
+  try {
+    const daemonModule = await import('@agent-relay/daemon');
+    Daemon = daemonModule.Daemon;
+  } catch {
+    throw new Error(
+      'To use standalone relay, install @agent-relay/daemon:\n' +
+      '  npm install @agent-relay/daemon\n\n' +
+      'Or if you have an external daemon running, use RelayClient directly.'
+    );
+  }
+
+  const daemon = new Daemon({
+    socketPath,
+    consensus: false, // Minimal mode - just messaging
+    cloudSync: false, // No cloud features
+  });
+
+  await daemon.start();
+
+  const clients: RelayClient[] = [];
+
+  return {
+    async client(name: string, clientConfig: Partial<ClientConfig> = {}): Promise<RelayClient> {
+      const client = new RelayClient({
+        agentName: name,
+        socketPath,
+        quiet,
+        reconnect: true,
+        ...clientConfig,
+      });
+      await client.connect();
+      clients.push(client);
+      return client;
+    },
+
+    async stop(): Promise<void> {
+      // Disconnect all clients first
+      for (const client of clients) {
+        client.destroy();
+      }
+      clients.length = 0;
+      // Stop the daemon
+      await daemon.stop();
+    },
+
+    get isRunning(): boolean {
+      return daemon.isRunning;
+    },
+
+    get socketPath(): string {
+      return socketPath;
+    },
+  };
+}
+
+/**
+ * Quick helper to create two connected agents for simple communication.
+ *
+ * @example
+ * ```typescript
+ * const { alice, bob, stop } = await createPair('Alice', 'Bob');
+ *
+ * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+ * alice.sendMessage('Bob', 'Hi there!');
+ *
+ * await stop();
+ * ```
+ */
+export async function createPair(
+  name1: string,
+  name2: string,
+  config: RelayConfig = {}
+): Promise<{
+  [K in typeof name1]: RelayClient;
+} & {
+  [K in typeof name2]: RelayClient;
+} & {
+  relay: Relay;
+  stop: () => Promise<void>;
+}> {
+  const relay = await createRelay(config);
+  const client1 = await relay.client(name1);
+  const client2 = await relay.client(name2);
+
+  return {
+    [name1]: client1,
+    [name2]: client2,
+    relay,
+    stop: () => relay.stop(),
+  } as any;
+}
+
+// Re-export client for convenience
+export { RelayClient, type ClientConfig } from './client.js';

package/packages/sdk/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/packages/sdk/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});