agl 1.0.17 → 21.0.2

package/ts_web/classes.controllersocketclient.ts

@@ -0,0 +1,517 @@
+import * as plugins from './plugins.js';
+import * as interfaces from '../ts_interfaces/index.js';
+
+const controllerEventTypes: ReadonlySet<string> = new Set(interfaces.controllerEventTypes);
+const controllerRequestTimeoutMs = 35_000;
+
+const isQualifiedRuntimeId = (
+  valueArg: unknown,
+  allowedHarnessIdsArg: ReadonlySet<interfaces.TControllerHarnessId>,
+): valueArg is interfaces.IControllerRuntimeId => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IControllerRuntimeId>;
+  return (
+    Object.keys(candidate).length === 2
+    && typeof candidate.harnessId === 'string'
+    && allowedHarnessIdsArg.has(candidate.harnessId as interfaces.TControllerHarnessId)
+    && typeof candidate.nativeId === 'string'
+    && candidate.nativeId.length > 0
+    && new TextEncoder().encode(candidate.nativeId).byteLength <= 512
+  );
+};
+
+const sessionHarnessIds: ReadonlySet<interfaces.TControllerHarnessId> = new Set(['opencode', 'flex']);
+const terminalHarnessIds: ReadonlySet<interfaces.TControllerHarnessId> = new Set(['controller']);
+const toolExecutionKeys = new Set([
+  'sessionId', 'messageId', 'partId', 'callId', 'toolName', 'status', 'input', 'output',
+  'exitCode', 'errorText', 'childSessionId', 'model', 'startedAt', 'finishedAt',
+  'order', 'sourceUpdatedAt', 'revision', 'streamEpoch',
+]);
+
+const reasoningUpdateKeys = new Set([
+  'sessionId', 'messageId', 'partId', 'text', 'status', 'order',
+  'sourceUpdatedAt', 'revision', 'streamEpoch',
+]);
+const textUpdateKeys = new Set([
+  'sessionId', 'messageId', 'partId', 'text', 'status', 'order',
+  'sourceUpdatedAt', 'revision', 'streamEpoch',
+]);
+
+const isOptionalFiniteNumber = (valueArg: unknown): boolean => (
+  valueArg === undefined || (typeof valueArg === 'number' && Number.isFinite(valueArg))
+);
+
+const isTranscriptOrder = (valueArg: unknown): boolean => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IControllerTranscriptOrder>;
+  return Object.keys(candidate).length === 2
+    && Number.isSafeInteger(candidate.messageIndex)
+    && (candidate.messageIndex ?? -1) >= 0
+    && Number.isSafeInteger(candidate.partIndex)
+    && (candidate.partIndex ?? -1) >= 0;
+};
+
+const serializedBytesWithin = (valueArg: unknown, byteLimitArg: number): boolean => {
+  try {
+    return new TextEncoder().encode(JSON.stringify(valueArg)).byteLength <= byteLimitArg;
+  } catch {
+    return false;
+  }
+};
+
+const isDraftAttachment = (valueArg: unknown): valueArg is interfaces.IControllerDraftAttachment => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const candidate = valueArg as Partial<interfaces.IControllerDraftAttachment>;
+  if (
+    !Object.keys(candidate).every((key) => (
+      ['id', 'name', 'mediaType', 'size', 'kind', 'dataBase64'].includes(key)
+    ))
+    || typeof candidate.id !== 'string'
+    || candidate.id.length === 0
+    || new TextEncoder().encode(candidate.id).byteLength > 512
+    || typeof candidate.name !== 'string'
+    || candidate.name.length === 0
+    || new TextEncoder().encode(candidate.name).byteLength > 255
+    || typeof candidate.mediaType !== 'string'
+    || candidate.mediaType.length === 0
+    || new TextEncoder().encode(candidate.mediaType).byteLength > 129
+    || !Number.isSafeInteger(candidate.size)
+    || (candidate.size ?? -1) < 0
+    || (candidate.size ?? 0) > interfaces.controllerMaxDraftAttachmentBytes
+    || !['image', 'text', 'binary'].includes(candidate.kind ?? '')
+    || typeof candidate.dataBase64 !== 'string'
+  ) return false;
+  try {
+    const decoded = globalThis.atob(candidate.dataBase64);
+    return decoded.length === candidate.size && globalThis.btoa(decoded) === candidate.dataBase64;
+  } catch {
+    return false;
+  }
+};
+
+const isSessionDraftUpdate = (
+  valueArg: unknown,
+): valueArg is interfaces.IControllerSessionDraftUpdate => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const candidate = valueArg as Partial<interfaces.IControllerSessionDraftUpdate>;
+  if (
+    !Object.keys(candidate).every((key) => ['revision', 'text', 'attachments'].includes(key))
+    || !Number.isSafeInteger(candidate.revision)
+    || (candidate.revision ?? -1) < 0
+    || (candidate.text === undefined && candidate.attachments === undefined)
+    || (candidate.text !== undefined && (
+      typeof candidate.text !== 'string'
+      || new TextEncoder().encode(candidate.text).byteLength > interfaces.controllerMaxDraftTextBytes
+    ))
+    || (candidate.attachments !== undefined && (
+      !Array.isArray(candidate.attachments)
+      || candidate.attachments.length > interfaces.controllerMaxDraftAttachments
+      || !candidate.attachments.every(isDraftAttachment)
+      || candidate.attachments.reduce((sum, attachment) => sum + attachment.size, 0)
+        > interfaces.controllerMaxDraftAttachmentTotalBytes
+    ))
+  ) return false;
+  return true;
+};
+
+const isControllerToolExecution = (
+  valueArg: unknown,
+): valueArg is interfaces.IControllerToolExecution => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IControllerToolExecution>;
+  if (!isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)) return false;
+  const executionHarnessIds: ReadonlySet<interfaces.TControllerHarnessId> = new Set([
+    candidate.sessionId.harnessId,
+  ]);
+  return (
+    Object.keys(candidate).every((key) => toolExecutionKeys.has(key))
+    && isQualifiedRuntimeId(candidate.messageId, executionHarnessIds)
+    && isQualifiedRuntimeId(candidate.partId, executionHarnessIds)
+    && isQualifiedRuntimeId(candidate.callId, executionHarnessIds)
+    && typeof candidate.toolName === 'string'
+    && candidate.toolName.length > 0
+    && new TextEncoder().encode(candidate.toolName).byteLength <= 2048
+    && ['pending', 'running', 'completed', 'error'].includes(candidate.status ?? '')
+    && (candidate.exitCode === undefined
+      || (Number.isSafeInteger(candidate.exitCode) && candidate.exitCode >= 0))
+    && (candidate.errorText === undefined || typeof candidate.errorText === 'string')
+    && (candidate.childSessionId === undefined
+      || isQualifiedRuntimeId(candidate.childSessionId, executionHarnessIds))
+    && (candidate.model === undefined || typeof candidate.model === 'string')
+    && isOptionalFiniteNumber(candidate.startedAt)
+    && isOptionalFiniteNumber(candidate.finishedAt)
+    && (candidate.order === undefined || isTranscriptOrder(candidate.order))
+    && (candidate.sessionId.harnessId !== 'flex' || candidate.order !== undefined)
+    && (candidate.sessionId.harnessId !== 'opencode' || candidate.order === undefined)
+    && typeof candidate.sourceUpdatedAt === 'number'
+    && Number.isFinite(candidate.sourceUpdatedAt)
+    && candidate.sourceUpdatedAt >= 0
+    && Number.isSafeInteger(candidate.revision)
+    && (candidate.revision ?? -1) >= 0
+    && Number.isSafeInteger(candidate.streamEpoch)
+    && (candidate.streamEpoch ?? -1) >= 0
+  );
+};
+
+const isControllerReasoningUpdate = (
+  valueArg: unknown,
+): valueArg is interfaces.IControllerReasoningUpdate => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IControllerReasoningUpdate>;
+  if (!isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)) return false;
+  const harnessIds: ReadonlySet<interfaces.TControllerHarnessId> = new Set([
+    candidate.sessionId.harnessId,
+  ]);
+  return Object.keys(candidate).every((key) => reasoningUpdateKeys.has(key))
+    && isQualifiedRuntimeId(candidate.messageId, harnessIds)
+    && isQualifiedRuntimeId(candidate.partId, harnessIds)
+    && typeof candidate.text === 'string'
+    && new TextEncoder().encode(candidate.text).byteLength
+      <= interfaces.controllerMaxLiveMessageEventBytes
+    && ['running', 'completed', 'cancelled'].includes(candidate.status ?? '')
+    && (candidate.order === undefined || isTranscriptOrder(candidate.order))
+    && (candidate.sessionId.harnessId !== 'flex' || candidate.order !== undefined)
+    && (candidate.sessionId.harnessId !== 'opencode' || candidate.order === undefined)
+    && typeof candidate.sourceUpdatedAt === 'number'
+    && Number.isFinite(candidate.sourceUpdatedAt)
+    && Number.isSafeInteger(candidate.revision)
+    && (candidate.revision ?? -1) >= 0
+    && Number.isSafeInteger(candidate.streamEpoch)
+    && (candidate.streamEpoch ?? -1) >= 0;
+};
+
+const isControllerTextUpdate = (
+  valueArg: unknown,
+): valueArg is interfaces.IControllerTextUpdate => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IControllerTextUpdate>;
+  if (!isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)) return false;
+  const harnessIds: ReadonlySet<interfaces.TControllerHarnessId> = new Set([
+    candidate.sessionId.harnessId,
+  ]);
+  return Object.keys(candidate).every((key) => textUpdateKeys.has(key))
+    && isQualifiedRuntimeId(candidate.messageId, harnessIds)
+    && isQualifiedRuntimeId(candidate.partId, harnessIds)
+    && typeof candidate.text === 'string'
+    && new TextEncoder().encode(candidate.text).byteLength
+      <= interfaces.controllerMaxLiveMessageEventBytes
+    && ['running', 'completed'].includes(candidate.status ?? '')
+    && (candidate.order === undefined || isTranscriptOrder(candidate.order))
+    && (candidate.sessionId.harnessId !== 'flex' || candidate.order !== undefined)
+    && (candidate.sessionId.harnessId !== 'opencode' || candidate.order === undefined)
+    && typeof candidate.sourceUpdatedAt === 'number'
+    && Number.isFinite(candidate.sourceUpdatedAt)
+    && Number.isSafeInteger(candidate.revision)
+    && (candidate.revision ?? -1) >= 0
+    && Number.isSafeInteger(candidate.streamEpoch)
+    && (candidate.streamEpoch ?? -1) >= 0;
+};
+
+export interface IControllerSocketClientOptions {
+  onStatus: (status: plugins.typedsocket.TConnectionStatus) => void;
+  onControllerEvent: (event: interfaces.IControllerEvent) => void | Promise<void>;
+  /** Streamed PTY output for a terminal this client may be viewing. */
+  onTerminalOutput?: (
+    output: interfaces.IReq_ControllerTerminalOutput['request'],
+  ) => void | Promise<void>;
+  onBrowserViewEvent?: (
+    event: TControllerBrowserViewEventMessage,
+  ) => void | Promise<void>;
+  /** Fires when the transport fail-closes the connection (e.g. frame limits). */
+  onTransportClose?: (closeCode: number, reason: string) => void;
+}
+
+export type TControllerBrowserViewEventMessage =
+  plugins.typedrequest.TReverseVirtualStreamDirections<
+    interfaces.IReq_ControllerBrowserViewEvent['request']
+  >;
+
+export interface IControllerSocketRequestOptions
+  extends plugins.typedrequest.ITypedRequestFireOptions {
+  abortSignal?: AbortSignal;
+}
+
+export const isControllerEvent = (valueArg: unknown): valueArg is interfaces.IControllerEvent => {
+  if (!valueArg || typeof valueArg !== 'object') {
+    return false;
+  }
+
+  const candidate = valueArg as Partial<interfaces.IControllerEvent>;
+  const hasSessionMarker = candidate.sessionStatus !== undefined || candidate.sessionError !== undefined;
+  const hasToolExecution = candidate.toolExecution !== undefined;
+  const hasReasoningUpdate = candidate.reasoningUpdate !== undefined;
+  const hasTextUpdate = candidate.textUpdate !== undefined;
+  const hasDraftUpdate = candidate.sessionDraftUpdate !== undefined;
+  const hasUpgrade = candidate.upgrade !== undefined;
+  return (
+    typeof candidate.type === 'string'
+    && controllerEventTypes.has(candidate.type as interfaces.TControllerEventType)
+    && typeof candidate.timestamp === 'number'
+    && Number.isFinite(candidate.timestamp)
+    && (candidate.harnessId === undefined
+      || candidate.harnessId === 'opencode'
+      || candidate.harnessId === 'flex')
+    && (candidate.sessionId === undefined
+      || isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds))
+    && (candidate.projectId === undefined
+      || (typeof candidate.projectId === 'string' && candidate.projectId.length > 0))
+    && (
+      candidate.sessionStatus === undefined
+      || ['idle', 'busy', 'retry', 'error'].includes(candidate.sessionStatus)
+    )
+    && (candidate.sessionError === undefined || candidate.sessionError === true)
+    && (candidate.toolStreamEpoch === undefined || (
+      Number.isSafeInteger(candidate.toolStreamEpoch) && candidate.toolStreamEpoch >= 0
+    ))
+    && (candidate.messageStreamEpoch === undefined || (
+      Number.isSafeInteger(candidate.messageStreamEpoch) && candidate.messageStreamEpoch >= 0
+    ))
+    && (candidate.toolExecution === undefined || isControllerToolExecution(candidate.toolExecution))
+    && (candidate.reasoningUpdate === undefined
+      || isControllerReasoningUpdate(candidate.reasoningUpdate))
+    && (candidate.textUpdate === undefined || isControllerTextUpdate(candidate.textUpdate))
+    && (candidate.sessionDraftUpdate === undefined
+      || isSessionDraftUpdate(candidate.sessionDraftUpdate))
+    && (!hasToolExecution || serializedBytesWithin(
+      candidate,
+      interfaces.controllerMaxToolEventBytes,
+    ))
+    && (!(hasReasoningUpdate || hasTextUpdate) || serializedBytesWithin(
+      candidate,
+      interfaces.controllerMaxLiveMessageEventBytes,
+    ))
+    && (!hasSessionMarker || (
+      candidate.type === 'session.changed'
+      && isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)
+    ))
+    && (
+      candidate.harnessId === undefined
+      || candidate.sessionId === undefined
+      || candidate.harnessId === candidate.sessionId.harnessId
+    )
+    && !(candidate.sessionStatus !== undefined && candidate.sessionError === true)
+    && (!hasToolExecution || (
+      candidate.type === 'session.tool.updated'
+      && (candidate.harnessId === 'opencode' || candidate.harnessId === 'flex')
+      && typeof candidate.projectId === 'string'
+      && isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)
+      && candidate.harnessId === candidate.sessionId.harnessId
+      && candidate.harnessId === candidate.toolExecution!.sessionId.harnessId
+      && interfaces.controllerRuntimeIdKey(candidate.sessionId)
+        === interfaces.controllerRuntimeIdKey(candidate.toolExecution!.sessionId)
+      && candidate.toolStreamEpoch === undefined
+    ))
+    && (hasToolExecution || candidate.type !== 'session.tool.updated')
+    && (!hasReasoningUpdate || (
+      candidate.type === 'session.reasoning.updated'
+      && (candidate.harnessId === 'opencode' || candidate.harnessId === 'flex')
+      && typeof candidate.projectId === 'string'
+      && isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)
+      && candidate.harnessId === candidate.reasoningUpdate!.sessionId.harnessId
+      && interfaces.controllerRuntimeIdKey(candidate.sessionId)
+        === interfaces.controllerRuntimeIdKey(candidate.reasoningUpdate!.sessionId)
+    ))
+    && (hasReasoningUpdate || candidate.type !== 'session.reasoning.updated')
+    && (!hasTextUpdate || (
+      candidate.type === 'session.text.updated'
+      && (candidate.harnessId === 'opencode' || candidate.harnessId === 'flex')
+      && typeof candidate.projectId === 'string'
+      && isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)
+      && candidate.harnessId === candidate.textUpdate!.sessionId.harnessId
+      && interfaces.controllerRuntimeIdKey(candidate.sessionId)
+        === interfaces.controllerRuntimeIdKey(candidate.textUpdate!.sessionId)
+    ))
+    && (hasTextUpdate || candidate.type !== 'session.text.updated')
+    && (!hasDraftUpdate || (
+      candidate.type === 'session.draft.changed'
+      && typeof candidate.projectId === 'string'
+      && isQualifiedRuntimeId(candidate.sessionId, sessionHarnessIds)
+    ))
+    && (hasDraftUpdate || candidate.type !== 'session.draft.changed')
+    && (candidate.toolStreamEpoch === undefined || (
+      candidate.type === 'harness.changed'
+      && (candidate.harnessId === 'opencode' || candidate.harnessId === 'flex')
+      && !hasToolExecution
+    ))
+    && (candidate.messageStreamEpoch === undefined || (
+      candidate.type === 'harness.changed'
+      && (candidate.harnessId === 'opencode' || candidate.harnessId === 'flex')
+      && !hasReasoningUpdate
+      && !hasTextUpdate
+    ))
+    && (candidate.upgrade === undefined || (
+      typeof candidate.upgrade === 'object'
+      && candidate.upgrade !== null
+      && Object.keys(candidate.upgrade).length === 3
+      && typeof candidate.upgrade.fromVersion === 'string'
+      && candidate.upgrade.fromVersion.length > 0
+      && new TextEncoder().encode(candidate.upgrade.fromVersion).byteLength <= 128
+      && typeof candidate.upgrade.toVersion === 'string'
+      && candidate.upgrade.toVersion.length > 0
+      && new TextEncoder().encode(candidate.upgrade.toVersion).byteLength <= 128
+      && ['preparing', 'pausing', 'installing', 'restarting', 'continuing', 'completed', 'failed']
+        .includes(candidate.upgrade.phase)
+    ))
+    && (!hasUpgrade || candidate.type === 'upgrade.changed')
+    && (hasUpgrade || candidate.type !== 'upgrade.changed')
+  );
+};
+
+export const isControllerTerminalOutput = (
+  valueArg: unknown,
+): valueArg is interfaces.IReq_ControllerTerminalOutput['request'] => {
+  if (!valueArg || typeof valueArg !== 'object') return false;
+  const candidate = valueArg as Partial<interfaces.IReq_ControllerTerminalOutput['request']>;
+  return (
+    isQualifiedRuntimeId(candidate.terminalId, terminalHarnessIds)
+    && typeof candidate.dataBase64 === 'string'
+    && (candidate.reset === undefined || typeof candidate.reset === 'boolean')
+    && (candidate.ended === undefined || typeof candidate.ended === 'boolean')
+  );
+};
+
+export class ControllerSocketClient {
+  private readonly typedRouter = new plugins.typedrequest.TypedRouter();
+  private typedSocket: plugins.typedsocket.TypedSocket | undefined;
+  private statusSubscription: { unsubscribe: () => void } | undefined;
+  private diagnosticsSubscription: { unsubscribe: () => void } | undefined;
+  private abortController: AbortController | undefined;
+  private startPromise: Promise<void> | undefined;
+
+  constructor(private readonly options: IControllerSocketClientOptions) {
+    this.typedRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.IReq_ControllerEvent>(
+        'controller.event',
+        async (eventArg) => {
+          if (isControllerEvent(eventArg)) {
+            await this.options.onControllerEvent(eventArg);
+          }
+          return { received: true };
+        },
+      ),
+    );
+    this.typedRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.IReq_ControllerTerminalOutput>(
+        'controller.terminal.output',
+        async (outputArg) => {
+          if (isControllerTerminalOutput(outputArg)) {
+            await this.options.onTerminalOutput?.(outputArg);
+          }
+          return {};
+        },
+      ),
+    );
+    this.typedRouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.IReq_ControllerBrowserViewEvent>(
+        'controller.browser.view.event',
+        async (eventArg) => {
+          await this.options.onBrowserViewEvent?.(eventArg);
+          return {};
+        },
+      ),
+    );
+  }
+
+  public get status(): plugins.typedsocket.TConnectionStatus {
+    return this.typedSocket?.getStatus() ?? 'new';
+  }
+
+  public get isConnected(): boolean {
+    return this.status === 'connected';
+  }
+
+  public async start(): Promise<void> {
+    if (this.typedSocket?.getStatus() === 'connected') {
+      return;
+    }
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+
+    const startPromise = this.startInternal();
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+    } finally {
+      if (this.startPromise === startPromise) {
+        this.startPromise = undefined;
+      }
+    }
+  }
+
+  public async stop(): Promise<void> {
+    this.abortController?.abort();
+    this.abortController = undefined;
+    this.statusSubscription?.unsubscribe();
+    this.statusSubscription = undefined;
+    this.diagnosticsSubscription?.unsubscribe();
+    this.diagnosticsSubscription = undefined;
+
+    const typedSocket = this.typedSocket;
+    this.typedSocket = undefined;
+    if (typedSocket) {
+      await typedSocket.stop();
+    }
+
+    if (this.startPromise) {
+      await this.startPromise.catch(() => undefined);
+    }
+  }
+
+  public async fire<TRequest extends interfaces.TControllerRequest>(
+    method: TRequest['method'],
+    request: TRequest['request'],
+    optionsArg?: IControllerSocketRequestOptions,
+  ): Promise<TRequest['response']> {
+    const typedSocket = this.typedSocket;
+    if (!typedSocket || typedSocket.getStatus() !== 'connected') {
+      throw new Error('The controller connection is not available.');
+    }
+    const timeoutMs = optionsArg?.timeoutMs ?? controllerRequestTimeoutMs;
+    const { abortSignal, ...fireOptions } = optionsArg ?? {};
+    return typedSocket.createTypedRequest<TRequest>(method, undefined, {
+      timeoutMs,
+      abortSignal,
+    }).fire(request, {
+      ...fireOptions,
+      timeoutMs,
+    });
+  }
+
+  private async startInternal(): Promise<void> {
+    this.options.onStatus('connecting');
+    this.abortController = new AbortController();
+
+    const typedSocket = await plugins.typedsocket.TypedSocket.createClient(
+      this.typedRouter,
+      plugins.typedsocket.TypedSocket.useWindowLocationOriginUrl(),
+      {
+        autoReconnect: true,
+        maxRetries: 100,
+        initialBackoffMs: 500,
+        maxBackoffMs: 10_000,
+        abortSignal: this.abortController.signal,
+      },
+    );
+    this.typedSocket = typedSocket;
+    this.statusSubscription = typedSocket.statusSubject.subscribe((statusArg) => {
+      this.options.onStatus(statusArg);
+    });
+    this.diagnosticsSubscription = typedSocket.diagnosticsSubject.subscribe((diagnosticArg) => {
+      if (
+        diagnosticArg.kind === 'connectionClosed'
+        && typeof diagnosticArg.closeCode === 'number'
+        && diagnosticArg.closeCode !== 1000
+      ) {
+        this.options.onTransportClose?.(
+          diagnosticArg.closeCode,
+          typeof diagnosticArg.reason === 'string' ? diagnosticArg.reason : '',
+        );
+      }
+    });
+
+    // createClient resolves after the first connected emission, so subscribers
+    // installed here intentionally receive the current state once explicitly.
+    this.options.onStatus(typedSocket.getStatus());
+  }
+}