@modelprofile.com/mcp-crossharness 5.0.0

package/ts/classes.connectionregistry.ts

@@ -0,0 +1,309 @@
+import * as plugins from './plugins.js';
+import { OpencodeConnection } from './classes.connection.opencode.js';
+import { CodexConnection } from './classes.connection.codex.js';
+import type * as interfaces from './interfaces.js';
+
+export interface IConnectionRegistryOptions {
+  allowedServerUrls?: string[];
+  maxConnections?: number;
+  openCodeCredentials?: IOpenCodeCredentials;
+}
+
+export interface IOpenCodeCredentials {
+  serverUrl: string;
+  username?: string;
+  password: string;
+}
+
+export class ConnectionRegistry {
+  private connections = new Map<string, interfaces.IHarnessConnection>();
+  private connecting = new Map<string, interfaces.IHarnessConnection>();
+  private closingConnections = new Map<string, interfaces.IHarnessConnection>();
+  private allowedServerUrls: Set<string>;
+  private maxConnections: number;
+  private openCodeCredentials: IOpenCodeCredentials | undefined;
+  private closing = false;
+  private closingTasks = new Map<string, Promise<void>>();
+  private shutdownPromise: Promise<void> | undefined;
+
+  constructor(optionsArg: IConnectionRegistryOptions = {}) {
+    const configured =
+      optionsArg.allowedServerUrls ??
+      (process.env.CROSSHARNESS_ALLOWED_SERVER_URLS ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    this.allowedServerUrls = new Set(configured.map((entry) => this.normalizeUrl(entry).toString()));
+    this.maxConnections = optionsArg.maxConnections ?? 32;
+    if (!Number.isInteger(this.maxConnections) || this.maxConnections < 1) {
+      throw new Error('maxConnections must be a positive integer');
+    }
+    if (optionsArg.openCodeCredentials) {
+      const { serverUrl, username, password } = optionsArg.openCodeCredentials;
+      const credentialUrl = this.normalizeUrl(serverUrl);
+      if (
+        serverUrl.length > 2048
+        || serverUrl.includes('?')
+        || serverUrl.includes('#')
+        || credentialUrl.username
+        || credentialUrl.password
+        || credentialUrl.search
+        || credentialUrl.hash
+        || credentialUrl.pathname !== '/'
+        || !['http:', 'https:'].includes(credentialUrl.protocol)
+        || !this.allowedServerUrls.has(credentialUrl.toString())
+        || (
+          credentialUrl.protocol === 'http:'
+          && !['127.0.0.1', '[::1]', '::1', 'localhost'].includes(credentialUrl.hostname)
+        )
+        || typeof password !== 'string'
+        || password.length === 0
+        || Buffer.byteLength(password, 'utf8') > 1024
+        || password.includes('\r')
+        || password.includes('\n')
+        || (username !== undefined && (
+          typeof username !== 'string'
+          || username.length === 0
+          || Buffer.byteLength(username, 'utf8') > 1024
+          || username.includes('\r')
+          || username.includes('\n')
+        ))
+      ) throw new Error('openCodeCredentials are invalid');
+      this.openCodeCredentials = {
+        serverUrl: credentialUrl.toString(),
+        password,
+        ...(username === undefined ? {} : { username }),
+      };
+    }
+  }
+
+  public async connect(
+    harnessArg: interfaces.THarnessName,
+    serverUrlArg: string,
+    directoryArg: string,
+    signalArg?: AbortSignal,
+  ): Promise<interfaces.IConnectionInfo> {
+    if (signalArg?.aborted) throw this.abortError(signalArg.reason);
+    if (this.closing) {
+      throw new Error('connection registry is closing');
+    }
+    if (harnessArg === 'claudecode') {
+      throw new Error(
+        'Claude Code 2.1.219 exposes no URL-addressable session server; connection-first Crossharness cannot connect to it',
+      );
+    }
+    if (!directoryArg.startsWith('/')) {
+      throw new Error('connection directory must be an absolute path on the harness server');
+    }
+    if (directoryArg.length > 4096) {
+      throw new Error('connection directory exceeds 4096 characters');
+    }
+    if (serverUrlArg.length > 2048) {
+      throw new Error('server URL exceeds 2048 characters');
+    }
+    const url = this.validateAllowedUrl(harnessArg, serverUrlArg);
+    if (
+      this.connections.size + this.connecting.size + this.closingConnections.size >=
+      this.maxConnections
+    ) {
+      throw new Error(`connection registry is full (maximum ${this.maxConnections})`);
+    }
+    const duplicate = [
+      ...this.connections.values(),
+      ...this.connecting.values(),
+      ...this.closingConnections.values(),
+    ].find(
+      (connection) =>
+        connection.harness === harnessArg &&
+        connection.serverUrl === url.toString() &&
+        connection.directory === directoryArg,
+    );
+    if (duplicate) {
+      throw new Error(
+        `a ${harnessArg} connection already exists for ${url.toString()} and ${directoryArg}`,
+      );
+    }
+    const connectionId = `c-${plugins.crypto.randomBytes(8).toString('hex')}`;
+    const markClosingConnection = () => {
+      this.connections.delete(connectionId);
+      this.connecting.delete(connectionId);
+      this.closingConnections.set(connectionId, connection);
+    };
+    const removeClosedConnection = () => {
+      this.connections.delete(connectionId);
+      this.connecting.delete(connectionId);
+      this.closingConnections.delete(connectionId);
+    };
+    const connection: interfaces.IHarnessConnection =
+      harnessArg === 'opencode'
+        ? new OpencodeConnection(
+            connectionId,
+            url.toString(),
+            directoryArg,
+            markClosingConnection,
+            removeClosedConnection,
+            this.openCodeCredentials?.serverUrl === url.toString()
+              ? this.openCodeCredentials
+              : undefined,
+          )
+        : new CodexConnection(
+            connectionId,
+            url.toString(),
+            directoryArg,
+            markClosingConnection,
+            removeClosedConnection,
+          );
+    this.connecting.set(connectionId, connection);
+    let abortCleanupTask: Promise<void> | undefined;
+    const abortHandler = signalArg
+      ? () => {
+          abortCleanupTask ??= this.closeConnection(
+            connection,
+            this.abortError(signalArg.reason).message,
+          );
+          void abortCleanupTask.catch(() => undefined);
+        }
+      : undefined;
+    if (abortHandler) signalArg!.addEventListener('abort', abortHandler, { once: true });
+    try {
+      await connection.connect();
+      if (signalArg?.aborted) throw this.abortError(signalArg.reason);
+      if (this.closing) {
+        throw new Error('connection registry closed during setup');
+      }
+      this.connections.set(connectionId, connection);
+      return connection.getInfo();
+    } catch (errorArg) {
+      const operationError = signalArg?.aborted ? this.abortError(signalArg.reason) : errorArg;
+      try {
+        await (abortCleanupTask ?? this.closeConnection(connection, 'connection setup failed'));
+      } catch (cleanupErrorArg) {
+        throw new AggregateError(
+          [operationError, cleanupErrorArg],
+          'Connection setup failed and cleanup is incomplete.',
+        );
+      }
+      throw operationError;
+    } finally {
+      if (abortHandler) signalArg!.removeEventListener('abort', abortHandler);
+      this.connecting.delete(connectionId);
+    }
+  }
+
+  public get(connectionIdArg: string): interfaces.IHarnessConnection {
+    const connection = this.connections.get(connectionIdArg);
+    if (!connection) {
+      throw new Error(`unknown connectionId ${connectionIdArg}`);
+    }
+    return connection;
+  }
+
+  public list(): interfaces.IConnectionInfo[] {
+    return [...this.connections.values()].map((connection) => connection.getInfo());
+  }
+
+  public async disconnect(connectionIdArg: string): Promise<interfaces.IConnectionInfo> {
+    const connection = this.connections.get(connectionIdArg)
+      ?? this.closingConnections.get(connectionIdArg);
+    if (!connection) throw new Error(`unknown connectionId ${connectionIdArg}`);
+    await this.closeConnection(connection, 'connection explicitly disconnected');
+    return connection.getInfo();
+  }
+
+  public async closeAll(): Promise<void> {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.closing = true;
+    const connections = [
+      ...new Set([
+        ...this.connections.values(),
+        ...this.connecting.values(),
+        ...this.closingConnections.values(),
+      ]),
+    ];
+    const shutdownPromise = Promise.allSettled(
+      connections.map((connection) => this.closeConnection(
+        connection,
+        'Crossharness MCP transport closed',
+      )),
+    ).then((results) => {
+      const errors = results.flatMap((result) => (
+        result.status === 'rejected' ? [result.reason] : []
+      ));
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) {
+        throw new AggregateError(errors, 'Closing Crossharness connections failed.');
+      }
+    });
+    this.shutdownPromise = shutdownPromise;
+    try {
+      await shutdownPromise;
+    } finally {
+      if (this.shutdownPromise === shutdownPromise) this.shutdownPromise = undefined;
+    }
+  }
+
+  private closeConnection(
+    connectionArg: interfaces.IHarnessConnection,
+    reasonArg: string,
+  ): Promise<void> {
+    const connectionId = connectionArg.connectionId;
+    const existing = this.closingTasks.get(connectionId);
+    if (existing) return existing;
+    this.connections.delete(connectionId);
+    this.connecting.delete(connectionId);
+    this.closingConnections.set(connectionId, connectionArg);
+    let task!: Promise<void>;
+    task = Promise.resolve().then(() => connectionArg.close(reasonArg)).then(
+      () => {
+        if (this.closingConnections.get(connectionId) === connectionArg) {
+          this.closingConnections.delete(connectionId);
+        }
+      },
+      (errorArg) => {
+        this.connections.delete(connectionId);
+        this.connecting.delete(connectionId);
+        this.closingConnections.set(connectionId, connectionArg);
+        throw errorArg;
+      },
+    ).finally(() => {
+      if (this.closingTasks.get(connectionId) === task) this.closingTasks.delete(connectionId);
+    });
+    this.closingTasks.set(connectionId, task);
+    return task;
+  }
+
+  private validateAllowedUrl(harnessArg: interfaces.THarnessName, valueArg: string): URL {
+    const url = this.normalizeUrl(valueArg);
+    if (url.username || url.password || url.search || url.hash) {
+      throw new Error('server URL must not contain credentials, query parameters, or a fragment');
+    }
+    if (url.pathname !== '/') {
+      throw new Error('server URL must be an origin with no path');
+    }
+    const protocols = harnessArg === 'opencode' ? ['http:', 'https:'] : ['ws:', 'wss:'];
+    if (!protocols.includes(url.protocol)) {
+      throw new Error(`${harnessArg} server URL must use ${protocols.join(' or ')}`);
+    }
+    if (!this.allowedServerUrls.has(url.toString())) {
+      throw new Error(
+        `server URL ${url.toString()} is not in CROSSHARNESS_ALLOWED_SERVER_URLS`,
+      );
+    }
+    return url;
+  }
+
+  private normalizeUrl(valueArg: string): URL {
+    let url: URL;
+    try {
+      url = new URL(valueArg);
+    } catch {
+      throw new Error(`invalid server URL: ${valueArg}`);
+    }
+    url.pathname = url.pathname || '/';
+    return url;
+  }
+
+  private abortError(reasonArg: unknown): Error {
+    return reasonArg instanceof Error ? reasonArg : new Error('connection cancelled');
+  }
+}

package/ts/classes.dispatchregistry.ts

@@ -0,0 +1,216 @@
+import type * as interfaces from './interfaces.js';
+
+export type TDispatchStatus = 'working' | 'completed' | 'failed';
+
+export interface IDispatchRecord {
+  dispatchId: string;
+  connectionId: string;
+  harness: interfaces.THarnessName;
+  chatId: string;
+  startedAt: string;
+  completedAt?: string;
+  status: TDispatchStatus;
+  reply?: string;
+  via?: string;
+  error?: string;
+}
+
+interface IDispatchWaiter {
+  resolve: (recordArg: IDispatchRecord | undefined) => void;
+  timer: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  abortHandler?: () => void;
+}
+
+export interface IDispatchRegistryOptions {
+  maxRecords?: number;
+  completedTtlMs?: number;
+}
+
+export class DispatchRegistry {
+  private records = new Map<string, IDispatchRecord>();
+  private expiryTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private waiters = new Map<string, Set<IDispatchWaiter>>();
+  private waiterCount = 0;
+  private counter = 0;
+  private instancePrefix = Math.random().toString(36).slice(2, 7);
+  private disposed = false;
+
+  constructor(private options: IDispatchRegistryOptions = {}) {
+    if (!Number.isInteger(options.maxRecords ?? 100) || (options.maxRecords ?? 100) < 1) {
+      throw new Error('dispatch maxRecords must be a positive integer');
+    }
+    if ((options.completedTtlMs ?? 2 * 60 * 60 * 1000) < 0) {
+      throw new Error('dispatch completedTtlMs must not be negative');
+    }
+  }
+
+  public track(
+    connectionIdArg: string,
+    harnessArg: interfaces.THarnessName,
+    chatIdArg: string,
+    sendFactoryArg: () => Promise<interfaces.ISendResult>,
+  ): IDispatchRecord {
+    if (this.disposed) throw new Error('dispatch registry is closed');
+    this.reserveCapacity();
+    const record: IDispatchRecord = {
+      dispatchId: `d-${this.instancePrefix}-${++this.counter}`,
+      connectionId: connectionIdArg,
+      harness: harnessArg,
+      chatId: chatIdArg,
+      startedAt: new Date().toISOString(),
+      status: 'working',
+    };
+    this.records.set(record.dispatchId, record);
+    Promise.resolve().then(sendFactoryArg).then(
+      (result) => {
+        if (this.disposed || record.status !== 'working') return;
+        record.status = 'completed';
+        record.completedAt = new Date().toISOString();
+        record.reply = result.reply.slice(0, 100000);
+        record.via = result.via;
+        this.notifyWaiters(record.dispatchId, record);
+        this.scheduleExpiry(record.dispatchId);
+        this.prune();
+      },
+      (error) => {
+        if (this.disposed || record.status !== 'working') return;
+        record.status = 'failed';
+        record.completedAt = new Date().toISOString();
+        record.error = (error instanceof Error ? error.message : String(error)).slice(0, 4000);
+        this.notifyWaiters(record.dispatchId, record);
+        this.scheduleExpiry(record.dispatchId);
+        this.prune();
+      },
+    );
+    return record;
+  }
+
+  public get(connectionIdArg: string, dispatchIdArg: string): IDispatchRecord | undefined {
+    this.prune();
+    const record = this.records.get(dispatchIdArg);
+    return record?.connectionId === connectionIdArg ? record : undefined;
+  }
+
+  public async waitFor(
+    connectionIdArg: string,
+    dispatchIdArg: string,
+    waitMsArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<IDispatchRecord | undefined> {
+    const deadline = Date.now() + waitMsArg;
+    const record = this.get(connectionIdArg, dispatchIdArg);
+    if (!record || record.status !== 'working' || waitMsArg <= 0) return record;
+    if (signalArg?.aborted) return record;
+    if (this.waiterCount >= 1000) return record;
+    return new Promise<IDispatchRecord | undefined>((resolve) => {
+      const waiter: IDispatchWaiter = {
+        resolve,
+        timer: setTimeout(() => {
+          this.removeWaiter(dispatchIdArg, waiter);
+          resolve(this.get(connectionIdArg, dispatchIdArg));
+        }, Math.max(0, deadline - Date.now())),
+        signal: signalArg,
+      };
+      if (signalArg) {
+        waiter.abortHandler = () => {
+          this.removeWaiter(dispatchIdArg, waiter);
+          resolve(this.get(connectionIdArg, dispatchIdArg));
+        };
+        signalArg.addEventListener('abort', waiter.abortHandler, { once: true });
+      }
+      const dispatchWaiters = this.waiters.get(dispatchIdArg) ?? new Set();
+      dispatchWaiters.add(waiter);
+      this.waiterCount++;
+      this.waiters.set(dispatchIdArg, dispatchWaiters);
+      const current = this.get(connectionIdArg, dispatchIdArg);
+      if (!current || current.status !== 'working') {
+        this.notifyWaiters(dispatchIdArg, current);
+      }
+    });
+  }
+
+  public dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const timer of this.expiryTimers.values()) clearTimeout(timer);
+    this.expiryTimers.clear();
+    for (const dispatchId of [...this.waiters.keys()]) {
+      this.notifyWaiters(dispatchId, undefined);
+    }
+    this.records.clear();
+  }
+
+  private prune(): void {
+    const completedTtlMs = this.options.completedTtlMs ?? 2 * 60 * 60 * 1000;
+    const now = Date.now();
+    for (const [dispatchId, record] of this.records) {
+      if (
+        record.status !== 'working' &&
+        record.completedAt &&
+        now - Date.parse(record.completedAt) > completedTtlMs
+      ) {
+        this.forget(dispatchId);
+      }
+    }
+  }
+
+  private scheduleExpiry(dispatchIdArg: string): void {
+    const existingTimer = this.expiryTimers.get(dispatchIdArg);
+    if (existingTimer) clearTimeout(existingTimer);
+    const timer = setTimeout(() => {
+      this.expiryTimers.delete(dispatchIdArg);
+      this.records.delete(dispatchIdArg);
+    }, this.options.completedTtlMs ?? 2 * 60 * 60 * 1000);
+    this.expiryTimers.set(dispatchIdArg, timer);
+    timer.unref();
+  }
+
+  private reserveCapacity(): void {
+    this.prune();
+    const maxRecords = this.options.maxRecords ?? 100;
+    for (const [dispatchId, record] of this.records) {
+      if (this.records.size < maxRecords) break;
+      if (record.status !== 'working') this.forget(dispatchId);
+    }
+    if (this.records.size >= maxRecords) {
+      throw new Error('dispatch registry is full of active sends');
+    }
+  }
+
+  private forget(dispatchIdArg: string): void {
+    this.records.delete(dispatchIdArg);
+    const timer = this.expiryTimers.get(dispatchIdArg);
+    if (timer) clearTimeout(timer);
+    this.expiryTimers.delete(dispatchIdArg);
+    this.notifyWaiters(dispatchIdArg, undefined);
+  }
+
+  private notifyWaiters(
+    dispatchIdArg: string,
+    recordArg: IDispatchRecord | undefined,
+  ): void {
+    const dispatchWaiters = this.waiters.get(dispatchIdArg);
+    if (!dispatchWaiters) return;
+    this.waiters.delete(dispatchIdArg);
+    this.waiterCount -= dispatchWaiters.size;
+    for (const waiter of dispatchWaiters) {
+      clearTimeout(waiter.timer);
+      if (waiter.abortHandler) waiter.signal?.removeEventListener('abort', waiter.abortHandler);
+      waiter.resolve(recordArg);
+    }
+  }
+
+  private removeWaiter(dispatchIdArg: string, waiterArg: IDispatchWaiter): void {
+    const dispatchWaiters = this.waiters.get(dispatchIdArg);
+    if (!dispatchWaiters) return;
+    if (dispatchWaiters.delete(waiterArg)) {
+      this.waiterCount--;
+      clearTimeout(waiterArg.timer);
+      if (waiterArg.abortHandler) {
+        waiterArg.signal?.removeEventListener('abort', waiterArg.abortHandler);
+      }
+    }
+    if (dispatchWaiters.size === 0) this.waiters.delete(dispatchIdArg);
+  }
+}