agent-relay 2.0.4 → 2.0.5

package/packages/telemetry/dist/client.js

@@ -0,0 +1,125 @@
+/**
+ * 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,
+    });
+    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

package/packages/telemetry/dist/machine-id.js

@@ -0,0 +1,58 @@
+/**
+ * Machine ID utilities for anonymous user identification.
+ * Uses existing machine-id file at ~/.local/share/agent-relay/machine-id
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export function getMachineIdPath() {
+    const dataDir = process.env.AGENT_RELAY_DATA_DIR ||
+        path.join(os.homedir(), '.local', 'share', 'agent-relay');
+    return path.join(dataDir, 'machine-id');
+}
+/**
+ * Load or generate machine ID using atomic file creation to avoid race conditions.
+ */
+export function loadMachineId() {
+    const machineIdPath = getMachineIdPath();
+    try {
+        return fs.readFileSync(machineIdPath, 'utf-8').trim();
+    }
+    catch (readErr) {
+        if (readErr.code !== 'ENOENT') {
+            return `${os.hostname()}-${Date.now().toString(36)}`;
+        }
+        try {
+            const dataDir = path.dirname(machineIdPath);
+            fs.mkdirSync(dataDir, { recursive: true });
+            const machineId = `${os.hostname()}-${randomBytes(8).toString('hex')}`;
+            // O_CREAT | O_EXCL fails if file exists - prevents race condition
+            const fd = fs.openSync(machineIdPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+            fs.writeSync(fd, machineId);
+            fs.closeSync(fd);
+            return machineId;
+        }
+        catch (writeErr) {
+            // Another process created the file first
+            if (writeErr.code === 'EEXIST') {
+                try {
+                    return fs.readFileSync(machineIdPath, 'utf-8').trim();
+                }
+                catch {
+                    // Fall through
+                }
+            }
+            return `${os.hostname()}-${Date.now().toString(36)}`;
+        }
+    }
+}
+/** SHA256 hash of machine ID, truncated to 16 chars */
+export function createAnonymousId() {
+    const machineId = loadMachineId();
+    return createHash('sha256')
+        .update(machineId)
+        .digest('hex')
+        .substring(0, 16);
+}
+//# sourceMappingURL=machine-id.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * PostHog configuration.
+ *
+ * Environment variables:
+ *   POSTHOG_API_KEY     - Override API key (any environment)
+ *   POSTHOG_HOST        - Override host URL
+ *
+ * Key selection:
+ *   1. POSTHOG_API_KEY (if set, always used)
+ *   3. PROD_API_KEY (fallback)
+ */
+export declare function getPostHogConfig(): {
+    apiKey: string;
+    host: string;
+} | null;
+//# sourceMappingURL=posthog-config.d.ts.map

package/packages/telemetry/dist/posthog-config.js

@@ -0,0 +1,33 @@
+/**
+ * PostHog configuration.
+ *
+ * Environment variables:
+ *   POSTHOG_API_KEY     - Override API key (any environment)
+ *   POSTHOG_HOST        - Override host URL
+ *
+ * Key selection:
+ *   1. POSTHOG_API_KEY (if set, always used)
+ *   3. PROD_API_KEY (fallback)
+ */
+// =============================================================================
+// Configure your PostHog production key here
+// =============================================================================
+/** Production PostHog API key (write-only, safe for client-side) */
+const PROD_API_KEY = 'phc_2uDu01GtnLABJpVkWw4ri1OgScLU90aEmXmDjufGdqr';
+const HOST = 'https://us.i.posthog.com';
+// =============================================================================
+// Exports
+// =============================================================================
+export function getPostHogConfig() {
+    const host = process.env.POSTHOG_HOST || HOST;
+    // Explicit override for any environment
+    if (process.env.POSTHOG_API_KEY) {
+        return { apiKey: process.env.POSTHOG_API_KEY, host };
+    }
+    // Fallback to production key
+    if (!PROD_API_KEY) {
+        return null;
+    }
+    return { apiKey: PROD_API_KEY, host };
+}
+//# sourceMappingURL=posthog-config.js.map

package/packages/telemetry/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agent-relay/telemetry",
+  "version": "2.0.5",
+  "description": "Anonymous telemetry for Agent Relay usage analytics",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "posthog-node": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/telemetry"
+  }
+}

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.4"
+    "@agent-relay/config": "2.0.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/resiliency": "2.0.4"
+    "@agent-relay/resiliency": "2.0.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/index.js",

package/packages/wrapper/dist/relay-pty-orchestrator.js

@@ -73,7 +73,7 @@ export class RelayPtyOrchestrator extends BaseWrapper {
     hasReceivedOutput = false;
     // Queue monitor for stuck message detection
     queueMonitorTimer;
-    QUEUE_MONITOR_INTERVAL_MS = 30000; // Check every 30 seconds
+    QUEUE_MONITOR_INTERVAL_MS = 5000; // Check every 5 seconds
     injectionStartTime = 0; // Track when isInjecting was set to true
     MAX_INJECTION_STUCK_MS = 60000; // Force reset after 60 seconds
     // Protocol monitor for detecting agent mistakes (e.g., empty AGENT_RELAY_NAME)

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.0.4",
-    "@agent-relay/protocol": "2.0.4",
-    "@agent-relay/config": "2.0.4",
-    "@agent-relay/continuity": "2.0.4",
-    "@agent-relay/resiliency": "2.0.4"
+    "@agent-relay/api-types": "2.0.5",
+    "@agent-relay/protocol": "2.0.5",
+    "@agent-relay/config": "2.0.5",
+    "@agent-relay/continuity": "2.0.5",
+    "@agent-relay/resiliency": "2.0.5"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

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

@@ -1,29 +0,0 @@
-/**
- * Socket Discovery for Agent Relay SDK
- *
- * Discovers the daemon socket path for local development and cloud environments.
- */
-export interface DiscoveryResult {
-    socketPath: string;
-    projectId: string;
-    source: 'env' | 'cloud' | 'project' | 'legacy';
-}
-/**
- * Discover the relay daemon socket path.
- *
- * Discovery order:
- * 1. RELAY_SOCKET environment variable (explicit override)
- * 2. Cloud workspace socket (if WORKSPACE_ID is set)
- * 3. Project-local socket ({projectRoot}/.agent-relay/relay.sock)
- * 4. Legacy fallback (/tmp/agent-relay.sock)
- *
- * @param cwd - Working directory to start search from (default: process.cwd())
- * @returns Discovery result with socket path and metadata
- */
-export declare function discoverSocket(cwd?: string): DiscoveryResult;
-/**
- * Get the default socket path using discovery.
- * Convenience function that returns just the path.
- */
-export declare function getDefaultSocketPath(cwd?: string): string;
-//# sourceMappingURL=discovery.d.ts.map