pi-harness-runtime 1.1.336 → 1.1.337

package/packages/connection-runtime/dist/supervisor.js

@@ -0,0 +1,169 @@
+/**
+ * Connection Supervisor
+ *
+ * Inspired by T3Code's connection supervisor:
+ * - Jittered exponential backoff for reconnection
+ * - Resets delay after successful connection
+ * - Cap at maxDelay to prevent thundering herd
+ */
+import { DEFAULT_CONNECTION_OPTIONS } from './types.js';
+/**
+ * Sleep utility - cross-platform
+ */
+function sleep(ms) {
+    // SAFETY: globalThis is always available in JS environments
+    // We assert it has setTimeout which is true for browsers and Node.js
+    const global = globalThis;
+    return new Promise(resolve => {
+        const tid = global.setTimeout(resolve, ms);
+        // Prevent unref warning in Node.js
+        if (typeof tid.unref === 'function') {
+            tid.unref?.();
+        }
+    });
+}
+/**
+ * Connection Supervisor
+ *
+ * Manages transport connection with automatic reconnection using
+ * jittered exponential backoff.
+ */
+export class ConnectionSupervisor {
+    transport;
+    delay;
+    maxDelay;
+    maxRetries;
+    jitter;
+    retries = 0;
+    state = 'idle';
+    stopping = false;
+    onConnected;
+    onDisconnected;
+    onError;
+    onRetry;
+    constructor(options) {
+        const opts = { ...DEFAULT_CONNECTION_OPTIONS, ...options };
+        this.transport = options.transport;
+        this.delay = opts.initialDelay ?? 1000;
+        this.maxDelay = opts.maxDelay ?? 5 * 60 * 1000;
+        this.maxRetries = opts.maxRetries ?? 0;
+        this.jitter = opts.jitter ?? true;
+        this.onConnected = options.onConnected;
+        this.onDisconnected = options.onDisconnected;
+        this.onError = options.onError;
+        this.onRetry = options.onRetry;
+    }
+    /**
+     * Current connection state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Number of retries attempted
+     */
+    getRetries() {
+        return this.retries;
+    }
+    /**
+     * Start the connection
+     */
+    async connect() {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            return;
+        }
+        this.stopping = false;
+        this.state = 'connecting';
+        try {
+            await this.transport.open();
+            this.onConnected?.();
+            this.state = 'connected';
+            this.delay = this.getInitialDelay(); // Reset on success
+            this.retries = 0;
+        }
+        catch (error) {
+            this.handleConnectionError(error);
+        }
+    }
+    /**
+     * Stop the connection
+     */
+    async disconnect() {
+        this.stopping = true;
+        this.state = 'stopped';
+        try {
+            await this.transport.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+        this.onDisconnected?.();
+    }
+    /**
+     * Force reconnection
+     */
+    async reconnect() {
+        if (this.state === 'reconnecting') {
+            return;
+        }
+        this.state = 'reconnecting';
+        await this.attemptConnection();
+    }
+    /**
+     * Handle connection error with backoff
+     */
+    async handleConnectionError(error) {
+        this.onError?.(error);
+        if (this.stopping) {
+            this.state = 'stopped';
+            return;
+        }
+        this.state = 'reconnecting';
+        await this.attemptConnection();
+    }
+    /**
+     * Attempt connection with backoff
+     */
+    async attemptConnection() {
+        while (!this.stopping) {
+            this.retries++;
+            if (this.maxRetries > 0 && this.retries > this.maxRetries) {
+                this.state = 'error';
+                this.onError?.(new Error(`Max retries (${this.maxRetries}) exceeded`));
+                return;
+            }
+            // Calculate delay with optional jitter
+            const actualDelay = this.jitter
+                ? this.delay + Math.random() * this.delay * 0.3 // Up to 30% jitter
+                : this.delay;
+            this.onRetry?.(this.retries, actualDelay);
+            await sleep(actualDelay);
+            if (this.stopping) {
+                this.state = 'stopped';
+                return;
+            }
+            try {
+                await this.transport.open();
+                this.onConnected?.();
+                this.state = 'connected';
+                this.delay = this.getInitialDelay(); // Reset on success
+                this.retries = 0;
+                return;
+            }
+            catch (error) {
+                this.onError?.(error);
+                // Exponential backoff
+                this.delay = Math.min(this.delay * 2, this.maxDelay);
+            }
+        }
+        this.state = 'stopped';
+    }
+    /**
+     * Get initial delay (allows override)
+     */
+    getInitialDelay() {
+        return this.transport.isConnected()
+            ? this.delay
+            : 1000;
+    }
+}

package/packages/connection-runtime/dist/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Connection types
+ *
+ * Note: Uses minimal EventEmitter-like interface to avoid Node.js dependency.
+ * Implementations can swap in Node's EventEmitter or use any compatible event system.
+ */
+/**
+ * Minimal event emitter interface
+ */
+export interface EventEmitter {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off(event: string, listener: (...args: unknown[]) => void): void;
+    emit(event: string, ...args: unknown[]): void;
+    once(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(event?: string): void;
+}
+/**
+ * Connection state
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Connection error
+ */
+export interface ConnectionError extends Error {
+    code?: string;
+    recoverable?: boolean;
+}
+/**
+ * Transport interface
+ */
+export interface Transport {
+    /** Open the connection */
+    open(): Promise<void>;
+    /** Close the connection */
+    close(): Promise<void>;
+    /** Send a message */
+    send(data: unknown): Promise<void>;
+    /** Check if connected */
+    isConnected(): boolean;
+    /** Event emitter for connection events */
+    events: EventEmitter;
+}
+/**
+ * Transport events
+ */
+export interface TransportEvents {
+    'open': () => void;
+    'close': () => void;
+    'error': (error: Error) => void;
+    'message': (data: unknown) => void;
+}
+/**
+ * Connection options
+ */
+export interface ConnectionOptions {
+    /** Initial retry delay in ms */
+    initialDelay?: number;
+    /** Maximum retry delay in ms */
+    maxDelay?: number;
+    /** Maximum number of retries (0 = infinite) */
+    maxRetries?: number;
+    /** Enable jitter (recommended) */
+    jitter?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Default connection options
+ */
+export declare const DEFAULT_CONNECTION_OPTIONS: Required<ConnectionOptions>;

package/packages/connection-runtime/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Connection types
+ *
+ * Note: Uses minimal EventEmitter-like interface to avoid Node.js dependency.
+ * Implementations can swap in Node's EventEmitter or use any compatible event system.
+ */
+/**
+ * Default connection options
+ */
+export const DEFAULT_CONNECTION_OPTIONS = {
+    initialDelay: 1000,
+    maxDelay: 5 * 60 * 1000, // 5 minutes
+    maxRetries: 0, // Infinite
+    jitter: true,
+    verbose: false,
+};

package/packages/connection-runtime/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@pi-harness/connection-runtime",
+  "version": "1.1.337",
+  "type": "module",
+  "description": "Connection management with jittered exponential backoff for pi-harness",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@pi-harness/contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/packages/connection-runtime/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Connection Runtime for pi-harness
+ * 
+ * Inspired by T3Code's client-runtime:
+ * - Jittered exponential backoff for reconnection
+ * - One transport retry owner per environment
+ * - Shared subscription logic across clients
+ */
+
+export * from './supervisor.js';
+export * from './registry.js';
+export * from './types.js';

package/packages/connection-runtime/src/registry.ts

@@ -0,0 +1,142 @@
+/**
+ * Connection Registry
+ * 
+ * Scopes connections by environment/context.
+ * Tracks active connections and their state.
+ */
+
+import type { EventEmitter } from './types.js';
+import { ConnectionSupervisor } from './supervisor.js';
+
+export interface RegistryEntry {
+  id: string;
+  supervisor: ConnectionSupervisor;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  lastConnectedAt?: Date;
+}
+
+/**
+ * Connection Registry
+ * 
+ * Manages multiple connections by ID.
+ * Connections persist even after disconnect (for reconnection).
+ */
+export class ConnectionRegistry {
+  private connections = new Map<string, RegistryEntry>();
+  private onChange?: (entries: RegistryEntry[]) => void;
+
+  constructor(onChange?: (entries: RegistryEntry[]) => void) {
+    this.onChange = onChange;
+  }
+
+  /**
+   * Register a new connection
+   */
+  register(id: string, supervisor: ConnectionSupervisor, metadata?: Record<string, unknown>): RegistryEntry {
+    const entry: RegistryEntry = {
+      id,
+      supervisor,
+      metadata,
+      createdAt: new Date(),
+    };
+
+    this.connections.set(id, entry);
+    this.notifyChange();
+    return entry;
+  }
+
+  /**
+   * Unregister a connection
+   */
+  unregister(id: string): boolean {
+    const entry = this.connections.get(id);
+    if (entry) {
+      entry.supervisor.disconnect().catch(() => {});
+      this.connections.delete(id);
+      this.notifyChange();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get a connection by ID
+   */
+  get(id: string): RegistryEntry | undefined {
+    return this.connections.get(id);
+  }
+
+  /**
+   * Get all connections
+   */
+  list(): RegistryEntry[] {
+    return Array.from(this.connections.values());
+  }
+
+  /**
+   * Get connections by state
+   */
+  listByState(state: string): RegistryEntry[] {
+    return this.list().filter(e => e.supervisor.getState() === state);
+  }
+
+  /**
+   * Update connection metadata
+   */
+  updateMetadata(id: string, metadata: Record<string, unknown>): boolean {
+    const entry = this.connections.get(id);
+    if (entry) {
+      entry.metadata = { ...entry.metadata, ...metadata };
+      this.notifyChange();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Update last connected timestamp
+   */
+  touch(id: string): boolean {
+    const entry = this.connections.get(id);
+    if (entry) {
+      entry.lastConnectedAt = new Date();
+      this.notifyChange();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Clear all connections
+   */
+  async clear(): Promise<void> {
+    const promises = this.list().map(e => e.supervisor.disconnect());
+    await Promise.allSettled(promises);
+    this.connections.clear();
+    this.notifyChange();
+  }
+
+  /**
+   * Get count of connections
+   */
+  size(): number {
+    return this.connections.size;
+  }
+
+  /**
+   * Check if connection exists
+   */
+  has(id: string): boolean {
+    return this.connections.has(id);
+  }
+
+  /**
+   * Notify change listeners
+   */
+  private notifyChange(): void {
+    if (this.onChange) {
+      this.onChange(this.list());
+    }
+  }
+}

package/packages/connection-runtime/src/supervisor.ts

@@ -0,0 +1,224 @@
+/**
+ * Connection Supervisor
+ * 
+ * Inspired by T3Code's connection supervisor:
+ * - Jittered exponential backoff for reconnection
+ * - Resets delay after successful connection
+ * - Cap at maxDelay to prevent thundering herd
+ */
+
+import type { EventEmitter } from './types.js';
+import { DEFAULT_CONNECTION_OPTIONS } from './types.js';
+
+/**
+ * Sleep utility - cross-platform
+ */
+function sleep(ms: number): Promise<void> {
+  // SAFETY: globalThis is always available in JS environments
+  // We assert it has setTimeout which is true for browsers and Node.js
+  const global = globalThis as unknown as {
+    setTimeout: (fn: () => void, ms: number) => { unref?: () => void }
+  };
+  return new Promise(resolve => {
+    const tid = global.setTimeout(resolve, ms);
+    // Prevent unref warning in Node.js
+    if (typeof tid.unref === 'function') {
+      tid.unref?.();
+    }
+  });
+}
+
+/**
+ * Connection Supervisor options
+ */
+export interface SupervisorOptions {
+  /** Transport to manage */
+  transport: EventEmitter & {
+    open(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+  };
+  /** Initial retry delay in ms */
+  initialDelay?: number;
+  /** Maximum retry delay in ms */
+  maxDelay?: number;
+  /** Maximum retries (0 = infinite) */
+  maxRetries?: number;
+  /** Enable jitter */
+  jitter?: boolean;
+  /** Callback when connected */
+  onConnected?: () => void;
+  /** Callback when disconnected */
+  onDisconnected?: () => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+  /** Callback on retry attempt */
+  onRetry?: (attempt: number, delay: number) => void;
+}
+
+/**
+ * Connection Supervisor
+ * 
+ * Manages transport connection with automatic reconnection using
+ * jittered exponential backoff.
+ */
+export class ConnectionSupervisor {
+  private transport: SupervisorOptions['transport'];
+  private delay: number;
+  private maxDelay: number;
+  private maxRetries: number;
+  private jitter: boolean;
+  private retries = 0;
+  private state: 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'stopped' | 'error' = 'idle';
+  private stopping = false;
+  private onConnected?: () => void;
+  private onDisconnected?: () => void;
+  private onError?: (error: Error) => void;
+  private onRetry?: (attempt: number, delay: number) => void;
+
+  constructor(options: SupervisorOptions) {
+    const opts = { ...DEFAULT_CONNECTION_OPTIONS, ...options };
+    
+    this.transport = options.transport;
+    this.delay = opts.initialDelay ?? 1000;
+    this.maxDelay = opts.maxDelay ?? 5 * 60 * 1000;
+    this.maxRetries = opts.maxRetries ?? 0;
+    this.jitter = opts.jitter ?? true;
+    this.onConnected = options.onConnected;
+    this.onDisconnected = options.onDisconnected;
+    this.onError = options.onError;
+    this.onRetry = options.onRetry;
+  }
+
+  /**
+   * Current connection state
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Number of retries attempted
+   */
+  getRetries() {
+    return this.retries;
+  }
+
+  /**
+   * Start the connection
+   */
+  async connect(): Promise<void> {
+    if (this.state === 'connected' || this.state === 'connecting') {
+      return;
+    }
+
+    this.stopping = false;
+    this.state = 'connecting';
+
+    try {
+      await this.transport.open();
+      this.onConnected?.();
+      this.state = 'connected';
+      this.delay = this.getInitialDelay(); // Reset on success
+      this.retries = 0;
+    } catch (error) {
+      this.handleConnectionError(error as Error);
+    }
+  }
+
+  /**
+   * Stop the connection
+   */
+  async disconnect(): Promise<void> {
+    this.stopping = true;
+    this.state = 'stopped';
+    
+    try {
+      await this.transport.close();
+    } catch {
+      // Ignore close errors
+    }
+    
+    this.onDisconnected?.();
+  }
+
+  /**
+   * Force reconnection
+   */
+  async reconnect(): Promise<void> {
+    if (this.state === 'reconnecting') {
+      return;
+    }
+
+    this.state = 'reconnecting';
+    await this.attemptConnection();
+  }
+
+  /**
+   * Handle connection error with backoff
+   */
+  private async handleConnectionError(error: Error): Promise<void> {
+    this.onError?.(error);
+    
+    if (this.stopping) {
+      this.state = 'stopped';
+      return;
+    }
+
+    this.state = 'reconnecting';
+    await this.attemptConnection();
+  }
+
+  /**
+   * Attempt connection with backoff
+   */
+  private async attemptConnection(): Promise<void> {
+    while (!this.stopping) {
+      this.retries++;
+      
+      if (this.maxRetries > 0 && this.retries > this.maxRetries) {
+        this.state = 'error';
+        this.onError?.(new Error(`Max retries (${this.maxRetries}) exceeded`));
+        return;
+      }
+
+      // Calculate delay with optional jitter
+      const actualDelay = this.jitter 
+        ? this.delay + Math.random() * this.delay * 0.3 // Up to 30% jitter
+        : this.delay;
+
+      this.onRetry?.(this.retries, actualDelay);
+      await sleep(actualDelay);
+
+      if (this.stopping) {
+        this.state = 'stopped';
+        return;
+      }
+
+      try {
+        await this.transport.open();
+        this.onConnected?.();
+        this.state = 'connected';
+        this.delay = this.getInitialDelay(); // Reset on success
+        this.retries = 0;
+        return;
+      } catch (error) {
+        this.onError?.(error as Error);
+        
+        // Exponential backoff
+        this.delay = Math.min(this.delay * 2, this.maxDelay);
+      }
+    }
+
+    this.state = 'stopped';
+  }
+
+  /**
+   * Get initial delay (allows override)
+   */
+  protected getInitialDelay(): number {
+    return this.transport.isConnected() 
+      ? this.delay 
+      : 1000;
+  }
+}