feat(runtime): add getBridgeInfo() meta call

src/runtime/bridge-protocol.ts

@@ -16,14 +16,26 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
+import type { BridgeInfo } from '../types/index.js';
+
 import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { BridgeProtocolError } from './errors.js';
 import { SafeCodec, type CodecOptions } from './safe-codec.js';
+import { TYWRAP_PROTOCOL_VERSION } from './protocol.js';
 import { PROTOCOL_ID, type Transport, type ProtocolMessage } from './transport.js';
 
 // =============================================================================
 // TYPES
 // =============================================================================
 
+export interface GetBridgeInfoOptions {
+  /**
+   * If true, bypasses the cached info and queries the bridge again.
+   * This is useful when you want up-to-date instance counts or diagnostics.
+   */
+  refresh?: boolean;
+}
+
 /**
  * Configuration options for BridgeProtocol.
  */
@@ -38,6 +50,129 @@ export interface BridgeProtocolOptions {
   defaultTimeoutMs?: number;
 }
 
+function validateBridgeInfoPayload(value: unknown): BridgeInfo {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    const kind = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+    throw new BridgeProtocolError(`Invalid bridge info payload: expected object, got ${kind}`);
+  }
+
+  interface BridgeInfoWire {
+    protocol?: unknown;
+    protocolVersion?: unknown;
+    bridge?: unknown;
+    pythonVersion?: unknown;
+    pid?: unknown;
+    codecFallback?: unknown;
+    arrowAvailable?: unknown;
+    scipyAvailable?: unknown;
+    torchAvailable?: unknown;
+    sklearnAvailable?: unknown;
+    instances?: unknown;
+  }
+
+  const formatValue = (val: unknown): string => {
+    try {
+      const serialized = JSON.stringify(val);
+      return serialized ?? String(val);
+    } catch {
+      return String(val);
+    }
+  };
+
+  const obj = value as BridgeInfoWire;
+
+  const protocol = obj.protocol;
+  if (protocol !== PROTOCOL_ID) {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: protocol expected "${PROTOCOL_ID}", got ${formatValue(protocol)}`
+    );
+  }
+
+  const protocolVersion = obj.protocolVersion;
+  if (protocolVersion !== TYWRAP_PROTOCOL_VERSION) {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: protocolVersion expected ${TYWRAP_PROTOCOL_VERSION}, got ${formatValue(protocolVersion)}`
+    );
+  }
+
+  const bridge = obj.bridge;
+  if (bridge !== 'python-subprocess') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: bridge expected "python-subprocess", got ${formatValue(bridge)}`
+    );
+  }
+
+  const pythonVersion = obj.pythonVersion;
+  if (typeof pythonVersion !== 'string' || pythonVersion.length === 0) {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: pythonVersion expected non-empty string, got ${formatValue(pythonVersion)}`
+    );
+  }
+
+  const pid = obj.pid;
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: pid expected positive integer, got ${formatValue(pid)}`
+    );
+  }
+
+  const codecFallback = obj.codecFallback;
+  if (codecFallback !== 'json' && codecFallback !== 'none') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: codecFallback expected "json" or "none", got ${formatValue(codecFallback)}`
+    );
+  }
+
+  const arrowAvailable = obj.arrowAvailable;
+  if (typeof arrowAvailable !== 'boolean') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: arrowAvailable expected boolean, got ${formatValue(arrowAvailable)}`
+    );
+  }
+
+  const scipyAvailable = obj.scipyAvailable;
+  if (typeof scipyAvailable !== 'boolean') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: scipyAvailable expected boolean, got ${formatValue(scipyAvailable)}`
+    );
+  }
+
+  const torchAvailable = obj.torchAvailable;
+  if (typeof torchAvailable !== 'boolean') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: torchAvailable expected boolean, got ${formatValue(torchAvailable)}`
+    );
+  }
+
+  const sklearnAvailable = obj.sklearnAvailable;
+  if (typeof sklearnAvailable !== 'boolean') {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: sklearnAvailable expected boolean, got ${formatValue(sklearnAvailable)}`
+    );
+  }
+
+  const instances = obj.instances;
+  if (typeof instances !== 'number' || !Number.isInteger(instances) || instances < 0) {
+    throw new BridgeProtocolError(
+      `Invalid bridge info payload: instances expected non-negative integer, got ${formatValue(instances)}`
+    );
+  }
+
+  return {
+    protocol: PROTOCOL_ID,
+    protocolVersion: TYWRAP_PROTOCOL_VERSION,
+    bridge: 'python-subprocess',
+    pythonVersion,
+    pid,
+    codecFallback,
+    arrowAvailable,
+    scipyAvailable,
+    torchAvailable,
+    sklearnAvailable,
+    instances,
+  };
+}
+
 // =============================================================================
 // BRIDGE PROTOCOL BASE CLASS
 // =============================================================================
@@ -80,6 +215,9 @@ export class BridgeProtocol extends BoundedContext {
   /** Counter for generating unique request IDs */
   private requestId = 0;
 
+  /** Cached bridge diagnostics info (populated by getBridgeInfo). */
+  private bridgeInfoCache?: BridgeInfo;
+
   /**
    * Create a new BridgeProtocol instance.
    *
@@ -117,6 +255,7 @@ export class BridgeProtocol extends BoundedContext {
    * but should not need to dispose the transport manually.
    */
   protected async doDispose(): Promise<void> {
+    this.bridgeInfoCache = undefined;
     // Transport is tracked and will be disposed by BoundedContext
     // Subclasses can override to add additional cleanup
   }
@@ -316,4 +455,29 @@ export class BridgeProtocol extends BoundedContext {
       },
     });
   }
+
+  /**
+   * Fetch bridge diagnostics and feature availability.
+   *
+   * The Python bridge supports a `meta` method that returns protocol and environment info
+   * (including optional codec availability and current instance count).
+   */
+  async getBridgeInfo(options: GetBridgeInfoOptions = {}): Promise<BridgeInfo> {
+    if (!options.refresh && this.bridgeInfoCache) {
+      return this.bridgeInfoCache;
+    }
+
+    const info = await this.sendMessage<BridgeInfo>(
+      {
+        method: 'meta',
+        params: {},
+      },
+      {
+        validate: validateBridgeInfoPayload,
+      }
+    );
+
+    this.bridgeInfoCache = info;
+    return info;
+  }
 }

test/runtime_node.test.ts

@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os';
 import { delimiter, join } from 'path';
 import { NodeBridge } from '../src/runtime/node.js';
 import { BridgeProtocolError } from '../src/runtime/errors.js';
+import { TYWRAP_PROTOCOL_VERSION } from '../src/runtime/protocol.js';
 import { getDefaultPythonPath, resolvePythonExecutable } from '../src/utils/python.js';
 import { isNodejs, getVenvBinDir } from '../src/utils/runtime.js';
 
@@ -130,6 +131,36 @@ describeNodeOnly('Node.js Runtime Bridge', () => {
       },
       testTimeout
     );
+
+    it(
+      'should report bridge info and track instance counts',
+      async () => {
+        const pythonAvailable = await isPythonAvailable();
+        if (!pythonAvailable || !isBridgeScriptAvailable()) return;
+
+        const info = await bridge.getBridgeInfo();
+        expect(info.protocol).toBe('tywrap/1');
+        expect(info.protocolVersion).toBe(TYWRAP_PROTOCOL_VERSION);
+        expect(info.bridge).toBe('python-subprocess');
+        expect(info.pythonVersion).toMatch(/^\d+\.\d+\.\d+$/);
+        expect(typeof info.scipyAvailable).toBe('boolean');
+        expect(typeof info.torchAvailable).toBe('boolean');
+        expect(typeof info.sklearnAvailable).toBe('boolean');
+
+        const cached = await bridge.getBridgeInfo();
+        expect(cached).toBe(info);
+
+        const before = info.instances;
+        const handle = await bridge.instantiate('collections', 'Counter', [[1, 2, 2]]);
+        const mid = await bridge.getBridgeInfo({ refresh: true });
+        expect(mid.instances).toBe(before + 1);
+
+        await bridge.disposeInstance(handle);
+        const after = await bridge.getBridgeInfo({ refresh: true });
+        expect(after.instances).toBe(before);
+      },
+      testTimeout
+    );
   });
 
   describe('Stdlib Serialization', () => {
@@ -478,7 +509,7 @@ def get_path():
 
     it.each(['__proto__', 'prototype', 'constructor'])(
       'should reject dangerous environment override key %s',
-      (dangerousKey) => {
+      dangerousKey => {
         const envOverrides = Object.create(null) as Record<string, string | undefined>;
         Object.defineProperty(envOverrides, dangerousKey, {
           value: 'blocked',