agent-relay 2.0.4 → 2.0.6

package/packages/sdk/dist/client.js

@@ -6,19 +6,11 @@
  */
 import net from 'node:net';
 import { randomUUID } from 'node:crypto';
-import { getDefaultSocketPath } from './discovery.js';
 import { PROTOCOL_VERSION, } from './protocol/types.js';
 import { encodeFrameLegacy, FrameParser } from './protocol/framing.js';
-// Socket path is discovered lazily to allow environment to be set up first
-let _discoveredSocketPath = null;
-function getDiscoveredSocketPath() {
-    if (_discoveredSocketPath === null) {
-        _discoveredSocketPath = getDefaultSocketPath();
-    }
-    return _discoveredSocketPath;
-}
+const DEFAULT_SOCKET_PATH = '/tmp/agent-relay.sock';
 const DEFAULT_CLIENT_CONFIG = {
-    socketPath: '', // Will be set in constructor if not provided
+    socketPath: DEFAULT_SOCKET_PATH,
     agentName: 'agent',
     cli: undefined,
     quiet: false,
@@ -64,39 +56,7 @@ class CircularDedupeCache {
     }
 }
 /**
- * RelayClient - Agent-to-agent communication client for Agent Relay.
- *
- * The client automatically discovers the daemon socket path. You only need to provide
- * your agent name. Use `connect()` to establish a connection, then send/receive messages.
- *
- * @example Basic Usage
- * ```typescript
- * import { RelayClient } from '@agent-relay/sdk';
- *
- * const client = new RelayClient({ agentName: 'MyAgent' });
- * await client.connect();
- *
- * // Send messages
- * client.sendMessage('OtherAgent', 'Hello!');
- * client.sendMessage('#general', 'Channel message');
- * client.sendMessage('*', 'Broadcast');
- *
- * // Receive messages
- * client.onMessage = (from, payload) => {
- *   console.log(`${from}: ${payload.body}`);
- * };
- *
- * // Disconnect when done
- * client.disconnect();
- * ```
- *
- * @example Wait for Response
- * ```typescript
- * const response = await client.sendAndWait('Worker', 'Do this task', {
- *   timeoutMs: 30000,
- * });
- * console.log(`Worker replied: ${response.content}`);
- * ```
+ * RelayClient for agent-to-agent communication.
  */
 export class RelayClient {
     config;
@@ -113,39 +73,16 @@ export class RelayClient {
     writeQueue = [];
     writeScheduled = false;
     pendingSyncAcks = new Map();
-    /**
-     * Callback for receiving direct messages.
-     * @param from - Name of the sending agent
-     * @param payload - Message payload containing body, kind, and optional data
-     * @param messageId - Unique message identifier
-     * @param meta - Optional metadata (sync info, etc.)
-     * @param originalTo - Original recipient (useful for detecting broadcasts when originalTo='*')
-     */
+    // Event handlers
     onMessage;
     /**
      * Callback for channel messages.
-     * @param from - Name of the sending agent
-     * @param channel - Channel name (e.g., '#general')
-     * @param body - Message body text
-     * @param envelope - Full message envelope with metadata
      */
     onChannelMessage;
-    /**
-     * Callback for connection state changes.
-     * @param state - New connection state: 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF'
-     */
     onStateChange;
-    /**
-     * Callback for errors.
-     * @param error - The error that occurred
-     */
     onError;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CLIENT_CONFIG, ...config };
-        // Use discovered socket path if not explicitly provided
-        if (!this.config.socketPath) {
-            this.config.socketPath = getDiscoveredSocketPath();
-        }
         this.parser = new FrameParser();
         this.parser.setLegacyMode(true);
         this.reconnectDelay = this.config.reconnectDelayMs;
@@ -240,30 +177,7 @@ export class RelayClient {
         this.disconnect();
     }
     /**
-     * Send a message to another agent, channel, or broadcast.
-     *
-     * @param to - Recipient: agent name, '#channel', or '*' for broadcast
-     * @param body - Message content
-     * @param kind - Message type (default: 'message')
-     * @param data - Optional structured data to include
-     * @param thread - Optional thread ID for conversation threading
-     * @param meta - Optional metadata (sync info, etc.)
-     * @returns true if message was queued, false if not connected
-     *
-     * @example
-     * ```typescript
-     * // Direct message
-     * client.sendMessage('Worker1', 'Start the task');
-     *
-     * // Channel message
-     * client.sendMessage('#general', 'Team update');
-     *
-     * // Broadcast to all agents
-     * client.sendMessage('*', 'System announcement');
-     *
-     * // With structured data
-     * client.sendMessage('Worker1', 'Process this', 'task', { priority: 'high' });
-     * ```
+     * Send a message to another agent.
      */
     sendMessage(to, body, kind = 'message', data, thread, meta) {
         if (this._state !== 'READY') {
@@ -302,28 +216,7 @@ export class RelayClient {
         return this.send(envelope);
     }
     /**
-     * Send a message and wait for acknowledgment response.
-     *
-     * This is useful for request-response patterns where you need to wait for
-     * the recipient to process your message and reply.
-     *
-     * @param to - Recipient agent name
-     * @param body - Message content
-     * @param options - Options including timeout, thread, etc.
-     * @returns Promise that resolves with the ACK payload when recipient responds
-     * @throws Error if client not ready or timeout exceeded
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const response = await client.sendAndWait('Worker', 'Process this task', {
-     *     timeoutMs: 30000,  // 30 second timeout
-     *   });
-     *   console.log('Worker responded:', response);
-     * } catch (err) {
-     *   console.error('Worker did not respond in time');
-     * }
-     * ```
+     * Send a message and wait for ACK response.
      */
     async sendAndWait(to, body, options = {}) {
         if (this._state !== 'READY') {

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

@@ -29,5 +29,4 @@ export { RelayClient, type ClientState, type ClientConfig, type SyncOptions, } f
 export { createRelay, createPair, type Relay, type RelayConfig, } from './standalone.js';
 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, type SpawnPayload, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ChannelMessagePayload, type ChannelJoinPayload, type ChannelLeavePayload, } from './protocol/index.js';
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
-export { discoverSocket, getDefaultSocketPath, type DiscoveryResult, } from './discovery.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/index.js

@@ -33,6 +33,4 @@ export { createRelay, createPair, } from './standalone.js';
 export { PROTOCOL_VERSION, } from './protocol/index.js';
 // Framing utilities
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
-// Socket discovery utilities
-export { discoverSocket, getDefaultSocketPath, } from './discovery.js';
 //# sourceMappingURL=index.js.map

package/packages/sdk/dist/standalone.js

@@ -52,7 +52,6 @@ export async function createRelay(config = {}) {
     // Lazy-load daemon to keep SDK lightweight for client-only users
     let Daemon;
     try {
-        // @ts-ignore - daemon is an optional peer dependency, may not be installed
         const daemonModule = await import('@agent-relay/daemon');
         Daemon = daemonModule.Daemon;
     }

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Lightweight SDK for agent-to-agent communication via Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.4"
+    "@agent-relay/protocol": "2.0.6"
   },
   "engines": {
     "node": ">=18.0.0"

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.4"
+    "@agent-relay/protocol": "2.0.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/telemetry/dist/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostHog telemetry client singleton.
+ */
+import { getAnonymousId } from './config.js';
+import type { TelemetryEventName, TelemetryEventMap } from './events.js';
+export declare function initTelemetry(options?: {
+    showNotice?: boolean;
+}): void;
+export declare function track<E extends TelemetryEventName>(event: E, properties?: TelemetryEventMap[E]): void;
+export declare function shutdown(): Promise<void>;
+export declare function isEnabled(): boolean;
+export { getAnonymousId };
+export declare function getStatus(): {
+    enabled: boolean;
+    disabledByEnv: boolean;
+    anonymousId: string;
+    notifiedAt: string | undefined;
+};
+//# sourceMappingURL=client.d.ts.map

package/packages/telemetry/dist/client.js

@@ -0,0 +1,126 @@
+/**
+ * PostHog telemetry client singleton.
+ */
+import { PostHog } from 'posthog-node';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isTelemetryEnabled, getAnonymousId, wasNotified, markNotified, isDisabledByEnv, loadPrefs, } from './config.js';
+import { getPostHogConfig } from './posthog-config.js';
+let client = null;
+let commonProps = null;
+let anonymousId = null;
+let initialized = false;
+function findPackageJson(startDir) {
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.join(dir, 'package.json');
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+function getVersion() {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const packageJsonPath = findPackageJson(__dirname);
+        if (packageJsonPath) {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            return pkg.version || 'unknown';
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return 'unknown';
+}
+function buildCommonProperties() {
+    return {
+        agent_relay_version: getVersion(),
+        os: process.platform,
+        os_version: os.release(),
+        node_version: process.version.slice(1),
+        arch: process.arch,
+    };
+}
+function showFirstRunNotice() {
+    if (wasNotified())
+        return;
+    if (isDisabledByEnv()) {
+        markNotified();
+        return;
+    }
+    console.log('');
+    console.log('Agent Relay collects anonymous usage data to improve the product.');
+    console.log('Run `agent-relay telemetry disable` to opt out.');
+    console.log('Learn more: https://agent-relay.com/telemetry');
+    console.log('');
+    markNotified();
+}
+export function initTelemetry(options = {}) {
+    if (initialized)
+        return;
+    initialized = true;
+    if (options.showNotice !== false) {
+        showFirstRunNotice();
+    }
+    if (!isTelemetryEnabled())
+        return;
+    const posthogConfig = getPostHogConfig();
+    if (!posthogConfig)
+        return;
+    client = new PostHog(posthogConfig.apiKey, {
+        host: posthogConfig.host,
+        flushAt: 10,
+        flushInterval: 10000,
+        disableGeoip: false, // CLI runs on user's machine, so IP is correct for geo
+    });
+    commonProps = buildCommonProperties();
+    anonymousId = getAnonymousId();
+}
+export function track(event, properties) {
+    if (!client || !commonProps || !anonymousId)
+        return;
+    client.capture({
+        distinctId: anonymousId,
+        event,
+        properties: {
+            ...commonProps,
+            ...properties,
+        },
+    });
+}
+export async function shutdown() {
+    if (!client)
+        return;
+    try {
+        await client.shutdown();
+    }
+    catch {
+        // Ignore
+    }
+    finally {
+        client = null;
+        commonProps = null;
+        anonymousId = null;
+        initialized = false;
+    }
+}
+export function isEnabled() {
+    return isTelemetryEnabled();
+}
+export { getAnonymousId };
+export function getStatus() {
+    const prefs = loadPrefs();
+    return {
+        enabled: isTelemetryEnabled(),
+        disabledByEnv: isDisabledByEnv(),
+        anonymousId: prefs.anonymousId,
+        notifiedAt: prefs.notifiedAt,
+    };
+}
+//# sourceMappingURL=client.js.map

package/packages/telemetry/dist/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Telemetry preference storage (~/.agent-relay/telemetry.json)
+ */
+export interface TelemetryPrefs {
+    /** Whether telemetry is enabled (default: true) */
+    enabled: boolean;
+    /** ISO timestamp when user was shown the first-run notice */
+    notifiedAt?: string;
+    /** Anonymous ID derived from machine-id hash */
+    anonymousId: string;
+}
+export declare function getPrefsPath(): string;
+export declare function loadPrefs(): TelemetryPrefs;
+export declare function savePrefs(prefs: TelemetryPrefs): void;
+export declare function isDisabledByEnv(): boolean;
+/**
+ * Check if telemetry is enabled.
+ * Order of precedence:
+ * 1. AGENT_RELAY_TELEMETRY_DISABLED=1 -> disabled
+ * 2. ~/.agent-relay/telemetry.json -> use stored pref
+ * 3. Default -> enabled
+ */
+export declare function isTelemetryEnabled(): boolean;
+export declare function enableTelemetry(): void;
+export declare function disableTelemetry(): void;
+export declare function markNotified(): void;
+export declare function wasNotified(): boolean;
+export declare function getAnonymousId(): string;
+//# sourceMappingURL=config.d.ts.map

package/packages/telemetry/dist/config.js

@@ -0,0 +1,88 @@
+/**
+ * Telemetry preference storage (~/.agent-relay/telemetry.json)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createAnonymousId } from './machine-id.js';
+export function getPrefsPath() {
+    const configDir = process.env.AGENT_RELAY_DATA_DIR ||
+        path.join(os.homedir(), '.agent-relay');
+    return path.join(configDir, 'telemetry.json');
+}
+export function loadPrefs() {
+    const prefsPath = getPrefsPath();
+    try {
+        if (fs.existsSync(prefsPath)) {
+            const content = fs.readFileSync(prefsPath, 'utf-8');
+            const prefs = JSON.parse(content);
+            if (!prefs.anonymousId) {
+                prefs.anonymousId = createAnonymousId();
+                savePrefs(prefs);
+            }
+            return {
+                enabled: prefs.enabled ?? true,
+                notifiedAt: prefs.notifiedAt,
+                anonymousId: prefs.anonymousId,
+            };
+        }
+    }
+    catch {
+        // Fall through to defaults
+    }
+    return {
+        enabled: true,
+        anonymousId: createAnonymousId(),
+    };
+}
+export function savePrefs(prefs) {
+    const prefsPath = getPrefsPath();
+    const configDir = path.dirname(prefsPath);
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(prefsPath, JSON.stringify(prefs, null, 2), 'utf-8');
+    }
+    catch (err) {
+        // Silently fail - telemetry shouldn't break the app
+        console.error('[telemetry] Failed to save preferences:', err);
+    }
+}
+export function isDisabledByEnv() {
+    const envValue = process.env.AGENT_RELAY_TELEMETRY_DISABLED;
+    return envValue === '1' || envValue === 'true';
+}
+/**
+ * Check if telemetry is enabled.
+ * Order of precedence:
+ * 1. AGENT_RELAY_TELEMETRY_DISABLED=1 -> disabled
+ * 2. ~/.agent-relay/telemetry.json -> use stored pref
+ * 3. Default -> enabled
+ */
+export function isTelemetryEnabled() {
+    if (isDisabledByEnv()) {
+        return false;
+    }
+    return loadPrefs().enabled;
+}
+export function enableTelemetry() {
+    const prefs = loadPrefs();
+    prefs.enabled = true;
+    savePrefs(prefs);
+}
+export function disableTelemetry() {
+    const prefs = loadPrefs();
+    prefs.enabled = false;
+    savePrefs(prefs);
+}
+export function markNotified() {
+    const prefs = loadPrefs();
+    prefs.notifiedAt = new Date().toISOString();
+    savePrefs(prefs);
+}
+export function wasNotified() {
+    return loadPrefs().notifiedAt !== undefined;
+}
+export function getAnonymousId() {
+    return loadPrefs().anonymousId;
+}
+//# sourceMappingURL=config.js.map

package/packages/telemetry/dist/events.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Type-safe telemetry event definitions.
+ *
+ * Following PostHog naming best practices:
+ * - snake_case for events and properties
+ * - Present tense verbs (spawn, not spawned)
+ * - object_action pattern
+ */
+/** Source of spawn/release action */
+export type ActionSource = 'human_cli' | 'human_dashboard' | 'agent' | 'protocol';
+/** Reason for agent release */
+export type ReleaseReason = 'explicit' | 'crash' | 'timeout' | 'shutdown';
+/**
+ * Common properties attached to every event.
+ */
+export interface CommonProperties {
+    /** Agent Relay version */
+    agent_relay_version: string;
+    /** Operating system (e.g., darwin, linux, win32) */
+    os: string;
+    /** OS release version */
+    os_version: string;
+    /** Node.js version (without 'v' prefix) */
+    node_version: string;
+    /** CPU architecture (e.g., arm64, x64) */
+    arch: string;
+}
+/**
+ * daemon_start - Emitted when the daemon starts.
+ * No additional properties beyond common props.
+ */
+export interface DaemonStartEvent {
+}
+/**
+ * daemon_stop - Emitted when the daemon stops.
+ */
+export interface DaemonStopEvent {
+    /** How long the daemon was running, in seconds */
+    uptime_seconds: number;
+    /** Total agents spawned during this session */
+    agent_spawn_count: number;
+}
+/**
+ * agent_spawn - Emitted when an agent is created.
+ */
+export interface AgentSpawnEvent {
+    /** CLI type (claude, codex, gemini, etc.) */
+    cli: string;
+    /** Where the spawn originated */
+    spawn_source: ActionSource;
+    /** Whether a task was provided */
+    has_task: boolean;
+    /** Whether this is a shadow agent */
+    is_shadow: boolean;
+}
+/**
+ * agent_release - Emitted when an agent is stopped.
+ */
+export interface AgentReleaseEvent {
+    /** CLI type (claude, codex, gemini, etc.) */
+    cli: string;
+    /** Why the agent was released */
+    release_reason: ReleaseReason;
+    /** How long the agent was alive, in seconds */
+    lifetime_seconds: number;
+    /** Where the release originated */
+    release_source: ActionSource;
+}
+/**
+ * agent_crash - Emitted when an agent dies unexpectedly.
+ */
+export interface AgentCrashEvent {
+    /** CLI type (claude, codex, gemini, etc.) */
+    cli: string;
+    /** How long the agent was alive, in seconds */
+    lifetime_seconds: number;
+    /** Exit code if available */
+    exit_code?: number;
+}
+/**
+ * message_send - Emitted when an agent sends a relay message.
+ */
+export interface MessageSendEvent {
+    /** Whether this was a broadcast message */
+    is_broadcast: boolean;
+    /** Whether this message is part of a thread */
+    has_thread: boolean;
+}
+/**
+ * cli_command_run - Emitted when a CLI command is executed.
+ */
+export interface CliCommandRunEvent {
+    /** Name of the command (e.g., 'up', 'spawn', 'who') */
+    command_name: string;
+}
+export type TelemetryEventName = 'daemon_start' | 'daemon_stop' | 'agent_spawn' | 'agent_release' | 'agent_crash' | 'message_send' | 'cli_command_run';
+export interface TelemetryEventMap {
+    daemon_start: DaemonStartEvent;
+    daemon_stop: DaemonStopEvent;
+    agent_spawn: AgentSpawnEvent;
+    agent_release: AgentReleaseEvent;
+    agent_crash: AgentCrashEvent;
+    message_send: MessageSendEvent;
+    cli_command_run: CliCommandRunEvent;
+}
+//# sourceMappingURL=events.d.ts.map

package/packages/telemetry/dist/events.js

@@ -0,0 +1,10 @@
+/**
+ * Type-safe telemetry event definitions.
+ *
+ * Following PostHog naming best practices:
+ * - snake_case for events and properties
+ * - Present tense verbs (spawn, not spawned)
+ * - object_action pattern
+ */
+export {};
+//# sourceMappingURL=events.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * @agent-relay/telemetry - Anonymous usage analytics (opt-out via env or CLI)
+ */
+export { initTelemetry, track, shutdown, isEnabled, getAnonymousId, getStatus, } from './client.js';
+export { isTelemetryEnabled, enableTelemetry, disableTelemetry, wasNotified, markNotified, loadPrefs, savePrefs, getPrefsPath, isDisabledByEnv, type TelemetryPrefs, } from './config.js';
+export type { CommonProperties, ActionSource, ReleaseReason, DaemonStartEvent, DaemonStopEvent, AgentSpawnEvent, AgentReleaseEvent, AgentCrashEvent, MessageSendEvent, CliCommandRunEvent, TelemetryEventName, TelemetryEventMap, } from './events.js';
+export { loadMachineId, createAnonymousId, getMachineIdPath, } from './machine-id.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/telemetry/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @agent-relay/telemetry - Anonymous usage analytics (opt-out via env or CLI)
+ */
+export { initTelemetry, track, shutdown, isEnabled, getAnonymousId, getStatus, } from './client.js';
+export { isTelemetryEnabled, enableTelemetry, disableTelemetry, wasNotified, markNotified, loadPrefs, savePrefs, getPrefsPath, isDisabledByEnv, } from './config.js';
+export { loadMachineId, createAnonymousId, getMachineIdPath, } from './machine-id.js';
+//# sourceMappingURL=index.js.map

package/packages/telemetry/dist/machine-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Machine ID utilities for anonymous user identification.
+ * Uses existing machine-id file at ~/.local/share/agent-relay/machine-id
+ */
+export declare function getMachineIdPath(): string;
+/**
+ * Load or generate machine ID using atomic file creation to avoid race conditions.
+ */
+export declare function loadMachineId(): string;
+/** SHA256 hash of machine ID, truncated to 16 chars */
+export declare function createAnonymousId(): string;
+//# sourceMappingURL=machine-id.d.ts.map