@tonyclaw/agent-inspector 2.0.18 → 2.0.20

package/src/proxy/handler.ts

@@ -23,6 +23,7 @@ import { stripClaudeCodeBillingHeader } from "./claudeCodeStrip";
 import { stripOpenAIOrphanToolMessages } from "./openaiOrphanToolStrip";
 import { buildFileLogEntry, type FinalizeLogJob } from "./logFinalizer";
 import { enqueueFinalizeLogJob } from "./sessionRuntime";
+import { RawStreamCapture } from "./rawStreamCapture";
 import {
   buildUpstreamUrl,
   describeApiRoute,
@@ -138,27 +139,50 @@ function handleStreamingResponse(
   log.streaming = true;
   log.responseStatus = upstreamRes.status;
 
-  const chunks: string[] = [];
+  const capture = new RawStreamCapture();
   const decoder = new TextDecoder();
+  let finalizationScheduled = false;
+
+  const scheduleStreamingFinalization = (type: "streaming" | "stream-abort"): void => {
+    if (finalizationScheduled) return;
+    finalizationScheduled = true;
+
+    const elapsedMs = Date.now() - startTime;
+    const rawStream = capture.snapshot();
+    switch (type) {
+      case "streaming":
+        scheduleLogFinalization({
+          type: "streaming",
+          log,
+          upstreamUrl,
+          elapsedMs,
+          responseStatus: upstreamRes.status,
+          rawStream,
+          collectStreamingChunks,
+        });
+        return;
+      case "stream-abort":
+        scheduleLogFinalization({
+          type: "stream-abort",
+          log,
+          upstreamUrl,
+          elapsedMs,
+          rawStream,
+          hasChunks: capture.hasChunks,
+          collectStreamingChunks,
+        });
+        return;
+    }
+  };
 
   const transform = new TransformStream<Uint8Array, Uint8Array>({
-    transform(chunk, controller) {
+    async transform(chunk, controller) {
       controller.enqueue(chunk);
-      chunks.push(decoder.decode(chunk, { stream: true }));
+      await capture.append(decoder.decode(chunk, { stream: true }));
     },
-    flush() {
-      const full = chunks.join("");
-      const elapsedMs = Date.now() - startTime;
-
-      scheduleLogFinalization({
-        type: "streaming",
-        log,
-        upstreamUrl,
-        elapsedMs,
-        responseStatus: upstreamRes.status,
-        rawStream: full,
-        collectStreamingChunks,
-      });
+    async flush() {
+      await capture.append(decoder.decode());
+      scheduleStreamingFinalization("streaming");
     },
   });
 
@@ -171,19 +195,7 @@ function handleStreamingResponse(
   req.signal?.addEventListener("abort", () => {
     if (log.responseText === null) {
       logger.info(`[handler] Streaming client aborted: ${log.method} ${log.path}`);
-      const elapsedMs = Date.now() - startTime;
-      const full = chunks.join("");
-      const hasChunks = chunks.length > 0;
-
-      scheduleLogFinalization({
-        type: "stream-abort",
-        log,
-        upstreamUrl,
-        elapsedMs,
-        rawStream: full,
-        hasChunks,
-        collectStreamingChunks,
-      });
+      scheduleStreamingFinalization("stream-abort");
     }
   });
 

package/src/proxy/logFinalizer.ts

@@ -1,7 +1,9 @@
+import { readFileSync, rmSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { writeChunks } from "./chunkStorage";
 import { formatForPath } from "./formats";
 import { appendLogEntry, logger } from "./logger";
+import type { RawStreamSource } from "./rawStreamCapture";
 import type { CapturedLog } from "./schemas";
 import { getSessionProcess, isSessionProcessAvailable } from "./sessionProcess";
 import { finalizeLogUpdate } from "./store";
@@ -21,13 +23,13 @@ export type FinalizeNonStreamingLogJob = BaseFinalizeLogJob & {
 export type FinalizeStreamingLogJob = BaseFinalizeLogJob & {
   type: "streaming";
   responseStatus: number;
-  rawStream: string;
+  rawStream: string | RawStreamSource;
   collectStreamingChunks: boolean;
 };
 
 export type FinalizeStreamAbortLogJob = BaseFinalizeLogJob & {
   type: "stream-abort";
-  rawStream: string;
+  rawStream: string | RawStreamSource;
   hasChunks: boolean;
   collectStreamingChunks: boolean;
 };
@@ -41,6 +43,7 @@ export type FinalizeLogResult = {
   log: CapturedLog;
   upstreamUrl: string;
   error: string | null;
+  cleanupRawStreamPath?: string | null;
 };
 
 export function buildFileLogEntry(log: CapturedLog, upstreamUrl: string): Record<string, unknown> {
@@ -98,6 +101,7 @@ function finalizeWithError(
   fallbackStatus: number,
   fallbackResponseText: string,
   err: unknown,
+  cleanupRawStreamPath: string | null = null,
 ): FinalizeLogResult {
   const message = errorMessage(err);
   logger.error(`[logFinalizer] Failed to finalize log #${log.id}:`, message);
@@ -105,7 +109,7 @@ function finalizeWithError(
   log.responseText = log.responseText ?? fallbackResponseText;
   log.elapsedMs = job.elapsedMs;
   log.error = message;
-  return { log, upstreamUrl: job.upstreamUrl, error: message };
+  return { log, upstreamUrl: job.upstreamUrl, error: message, cleanupRawStreamPath };
 }
 
 function finalizeNonStreaming(
@@ -134,40 +138,100 @@ function finalizeNonStreaming(
   }
 }
 
+function cleanupPathForRawStream(rawStream: string | RawStreamSource): string | null {
+  if (typeof rawStream === "string") return null;
+  switch (rawStream.type) {
+    case "memory":
+      return null;
+    case "file":
+      return rawStream.path;
+  }
+}
+
+function readRawStream(rawStream: string | RawStreamSource): {
+  rawStreamText: string;
+  cleanupRawStreamPath: string | null;
+} {
+  if (typeof rawStream === "string") {
+    return { rawStreamText: rawStream, cleanupRawStreamPath: null };
+  }
+
+  switch (rawStream.type) {
+    case "memory":
+      return { rawStreamText: rawStream.rawStream, cleanupRawStreamPath: null };
+    case "file":
+      return {
+        rawStreamText: readFileSync(rawStream.path, "utf-8"),
+        cleanupRawStreamPath: rawStream.path,
+      };
+  }
+}
+
 function finalizeStreaming(job: FinalizeStreamingLogJob, log: CapturedLog): FinalizeLogResult {
   const formatHandler = formatForPath(log.path);
   if (formatHandler === null) {
-    return finalizeWithError(job, log, job.responseStatus, job.rawStream, "Unsupported format");
+    return finalizeWithError(
+      job,
+      log,
+      job.responseStatus,
+      "Streaming response unavailable",
+      "Unsupported format",
+      cleanupPathForRawStream(job.rawStream),
+    );
   }
 
+  let rawStreamText = "";
+  let cleanupRawStreamPath: string | null = null;
   try {
+    const raw = readRawStream(job.rawStream);
+    rawStreamText = raw.rawStreamText;
+    cleanupRawStreamPath = raw.cleanupRawStreamPath;
     log.elapsedMs = job.elapsedMs;
     log.responseStatus = job.responseStatus;
     log.responseText = formatHandler.extractStream(
-      job.rawStream,
+      rawStreamText,
       log,
       log.model ?? undefined,
       job.collectStreamingChunks,
     );
     persistStreamingChunks(log);
 
-    return { log, upstreamUrl: job.upstreamUrl, error: null };
+    return { log, upstreamUrl: job.upstreamUrl, error: null, cleanupRawStreamPath };
   } catch (err) {
-    return finalizeWithError(job, log, job.responseStatus, job.rawStream, err);
+    return finalizeWithError(
+      job,
+      log,
+      job.responseStatus,
+      rawStreamText === "" ? "Streaming response unavailable" : rawStreamText,
+      err,
+      cleanupRawStreamPath ?? cleanupPathForRawStream(job.rawStream),
+    );
   }
 }
 
 function finalizeStreamAbort(job: FinalizeStreamAbortLogJob, log: CapturedLog): FinalizeLogResult {
   const formatHandler = formatForPath(log.path);
   if (formatHandler === null && job.hasChunks) {
-    return finalizeWithError(job, log, 499, "Client aborted", "Unsupported format");
+    return finalizeWithError(
+      job,
+      log,
+      499,
+      "Client aborted",
+      "Unsupported format",
+      cleanupPathForRawStream(job.rawStream),
+    );
   }
 
+  let rawStreamText = "";
+  let cleanupRawStreamPath: string | null = null;
   try {
     log.elapsedMs = job.elapsedMs;
     if (job.hasChunks && formatHandler !== null) {
+      const raw = readRawStream(job.rawStream);
+      rawStreamText = raw.rawStreamText;
+      cleanupRawStreamPath = raw.cleanupRawStreamPath;
       log.responseText = formatHandler.extractStream(
-        job.rawStream,
+        rawStreamText,
         log,
         log.model ?? undefined,
         job.collectStreamingChunks,
@@ -177,9 +241,16 @@ function finalizeStreamAbort(job: FinalizeStreamAbortLogJob, log: CapturedLog):
       log.responseText = "Client aborted";
     }
 
-    return { log, upstreamUrl: job.upstreamUrl, error: "Client aborted" };
+    return { log, upstreamUrl: job.upstreamUrl, error: "Client aborted", cleanupRawStreamPath };
   } catch (err) {
-    return finalizeWithError(job, log, 499, "Client aborted", err);
+    return finalizeWithError(
+      job,
+      log,
+      499,
+      rawStreamText === "" ? "Client aborted" : rawStreamText,
+      err,
+      cleanupRawStreamPath ?? cleanupPathForRawStream(job.rawStream),
+    );
   }
 }
 
@@ -199,6 +270,17 @@ export function buildFinalizeLogResult(job: FinalizeLogJob): FinalizeLogResult {
 export function commitFinalizeLogResult(result: FinalizeLogResult): void {
   appendLogEntry({ ...buildFileLogEntry(result.log, result.upstreamUrl), error: result.error });
   finalizeLogUpdate(result.log);
+  if (result.cleanupRawStreamPath !== undefined && result.cleanupRawStreamPath !== null) {
+    try {
+      rmSync(result.cleanupRawStreamPath, { force: true });
+    } catch (err) {
+      logger.warn(
+        "[logFinalizer] Failed to remove raw stream temp file:",
+        result.cleanupRawStreamPath,
+        errorMessage(err),
+      );
+    }
+  }
 }
 
 // ── Worker pool ────────────────────────────────────────────────

package/src/proxy/logger.ts

@@ -5,6 +5,10 @@ import { getDataDir } from "./dataDir";
 
 const RETENTION_DAYS = Number(process.env["LOG_RETENTION_DAYS"] ?? "7");
 
+function writeStderrFallback(message: string, error: unknown): void {
+  process.stderr.write(`${message} ${String(error)}\n`);
+}
+
 export function resolveLogDir(): string {
   const logDirEnv = process.env["LOG_DIR"];
   if (logDirEnv !== undefined && logDirEnv !== "") {
@@ -51,8 +55,7 @@ export async function initLogger(): Promise<void> {
     }
   } catch (err) {
     // Log directory initialization errors but don't fail startup
-    // eslint-disable-next-line no-console
-    console.error("[logger] Failed to initialize log directory:", err);
+    writeStderrFallback("[logger] Failed to initialize log directory:", err);
   }
 }
 
@@ -74,8 +77,7 @@ async function writeAppLog(message: string): Promise<void> {
     await appendFile(logPath, `[${timestamp}] ${message}\n`, "utf-8");
   } catch (err) {
     // Log to stderr since file logging failed
-    // eslint-disable-next-line no-console
-    console.error(`[logger] Failed to write to ${logPath}:`, err);
+    writeStderrFallback(`[logger] Failed to write to ${logPath}:`, err);
   }
 }
 
@@ -103,6 +105,22 @@ export const logger = {
 const MAX_BUFFER_SIZE = 1000;
 let writeBuffer: string[] = [];
 let writeQueue: Promise<void> = Promise.resolve();
+let logWriteLock: Promise<void> = Promise.resolve();
+
+export async function runWithLogWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  const previousLock = logWriteLock;
+  let releaseLock = (): void => {};
+  logWriteLock = new Promise<void>((resolve) => {
+    releaseLock = resolve;
+  });
+
+  await previousLock;
+  try {
+    return await fn();
+  } finally {
+    releaseLock();
+  }
+}
 
 function drainBuffer(): string {
   const toWrite = writeBuffer.join("");
@@ -110,7 +128,7 @@ function drainBuffer(): string {
   return toWrite;
 }
 
-async function flushWriteBuffer(): Promise<void> {
+async function flushWriteBufferUnlocked(): Promise<void> {
   let toWrite: string;
   {
     toWrite = drainBuffer();
@@ -124,8 +142,7 @@ async function flushWriteBuffer(): Promise<void> {
   } catch (err) {
     // On failure, re-queue the data so it is not lost
     writeBuffer.unshift(toWrite);
-    // eslint-disable-next-line no-console
-    console.error("[logger] Failed to flush write buffer, re-queued:", err);
+    writeStderrFallback("[logger] Failed to flush write buffer, re-queued:", err);
   }
 }
 
@@ -133,9 +150,9 @@ export function appendLogEntry(entry: Record<string, unknown>): void {
   const line = JSON.stringify(entry) + "\n";
   writeBuffer.push(line);
   if (writeBuffer.length >= MAX_BUFFER_SIZE) {
-    writeQueue = writeQueue.then(() => flushWriteBuffer());
+    writeQueue = writeQueue.then(() => runWithLogWriteLock(flushWriteBufferUnlocked));
   } else if (writeBuffer.length === 1) {
-    writeQueue = writeQueue.then(() => flushWriteBuffer());
+    writeQueue = writeQueue.then(() => runWithLogWriteLock(flushWriteBufferUnlocked));
   }
 }
 
@@ -146,10 +163,18 @@ export function appendLogEntry(entry: Record<string, unknown>): void {
 export async function flushLogBuffer(): Promise<void> {
   await writeQueue;
   if (writeBuffer.length > 0) {
-    await flushWriteBuffer();
+    await runWithLogWriteLock(flushWriteBufferUnlocked);
   }
 }
 
+export async function runWithFlushedLogWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  await flushLogBuffer();
+  return await runWithLogWriteLock(async () => {
+    await flushWriteBufferUnlocked();
+    return await fn();
+  });
+}
+
 // Ensure buffered logs are written before the process exits
 process.on("exit", () => {
   if (writeBuffer.length > 0) {

package/src/proxy/providers.ts

@@ -3,6 +3,7 @@ import Conf from "conf";
 import { randomUUID } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { maskApiKey } from "../lib/mask";
 import { logger } from "./logger";
 import { getDataDir, hasExplicitDataDir } from "./dataDir";
 import {
@@ -380,6 +381,17 @@ export function getProvider(id: string): ProviderConfig | undefined {
   return providers.find((p) => p.id === id);
 }
 
+export function redactProvider(provider: ProviderConfig): ProviderConfig {
+  return {
+    ...provider,
+    apiKey: maskApiKey(provider.apiKey),
+  };
+}
+
+export function redactProviders(providers: readonly ProviderConfig[]): ProviderConfig[] {
+  return providers.map(redactProvider);
+}
+
 /**
  * Normalizes an API key by stripping "Bearer " prefix if present.
  */
@@ -630,11 +642,6 @@ export function importProviders(json: string): { imported: number; errors: strin
   return { imported, errors };
 }
 
-function maskApiKey(apiKey: string): string {
-  if (apiKey.length <= 8) return "••••••••";
-  return apiKey.slice(0, 4) + "••••••••" + apiKey.slice(-4);
-}
-
 /**
  * Converts display model name to API usage name based on provider-specific rules.
  * Default behavior: returns model as-is.

package/src/proxy/rawStreamCapture.ts

@@ -0,0 +1,85 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { mkdir, appendFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getDataDir } from "./dataDir";
+
+const DEFAULT_MEMORY_LIMIT_BYTES = 1024 * 1024;
+
+export type RawStreamSource =
+  | {
+      type: "memory";
+      rawStream: string;
+    }
+  | {
+      type: "file";
+      path: string;
+    };
+
+function resolveMemoryLimitBytes(): number {
+  const raw = process.env["AGENT_INSPECTOR_STREAM_MEMORY_LIMIT_BYTES"];
+  if (raw === undefined || raw === "") return DEFAULT_MEMORY_LIMIT_BYTES;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) return DEFAULT_MEMORY_LIMIT_BYTES;
+  return parsed;
+}
+
+function getRawStreamDir(): string {
+  return join(getDataDir(), "raw-streams");
+}
+
+function createRawStreamPath(): string {
+  return join(getRawStreamDir(), `${Date.now()}-${randomUUID()}.stream.tmp`);
+}
+
+export class RawStreamCapture {
+  private readonly memoryLimitBytes: number;
+  private chunks: string[] = [];
+  private byteLength = 0;
+  private filePath: string | null = null;
+  private sawChunk = false;
+
+  constructor(memoryLimitBytes: number = resolveMemoryLimitBytes()) {
+    this.memoryLimitBytes = memoryLimitBytes;
+  }
+
+  get hasChunks(): boolean {
+    return this.sawChunk;
+  }
+
+  async append(text: string): Promise<void> {
+    if (text === "") return;
+    this.sawChunk = true;
+
+    const nextBytes = Buffer.byteLength(text, "utf-8");
+    if (this.filePath === null && this.byteLength + nextBytes <= this.memoryLimitBytes) {
+      this.chunks.push(text);
+      this.byteLength += nextBytes;
+      return;
+    }
+
+    if (this.filePath === null) {
+      await this.spillToFile();
+    }
+
+    if (this.filePath !== null) {
+      await appendFile(this.filePath, text, "utf-8");
+      this.byteLength += nextBytes;
+    }
+  }
+
+  snapshot(): RawStreamSource {
+    if (this.filePath !== null) {
+      return { type: "file", path: this.filePath };
+    }
+    return { type: "memory", rawStream: this.chunks.join("") };
+  }
+
+  private async spillToFile(): Promise<void> {
+    const path = createRawStreamPath();
+    await mkdir(getRawStreamDir(), { recursive: true });
+    await writeFile(path, this.chunks.join(""), "utf-8");
+    this.filePath = path;
+    this.chunks = [];
+  }
+}

package/src/proxy/schemas.ts

@@ -8,8 +8,6 @@ export type { JsonValue };
 
 export type RequestFormat = "anthropic" | "openai" | "unknown";
 
-import { safeGetOwnProperty } from "../lib/objectUtils";
-
 /**
  * A single SSE event from a streaming response.
  */
@@ -50,6 +48,7 @@ export const CapturedLogSchema = z.object({
   headers: z.record(z.string(), z.string()).optional(),
   apiFormat: z.enum(["anthropic", "openai", "unknown"]).default("unknown"),
   isTest: z.boolean().optional().default(false),
+  replayOfLogId: z.number().nullable().optional(),
   providerName: z.string().nullable().optional(),
   clientPort: z.number().nullable().optional(),
   clientPid: z.number().nullable().optional(),
@@ -74,9 +73,6 @@ export type TokenUsage = {
 // Import types and schemas from formats
 // ============================================================
 
-// Import types and schemas from formats for internal use
-import { InspectorRequestSchema, type InspectorRequest } from "./formats/anthropic/schemas";
-
 // Re-export types and schemas from formats for backward compatibility
 export {
   InspectorRequestSchema,
@@ -84,7 +80,6 @@ export {
   SseEventSchema,
 } from "./formats/anthropic/schemas";
 export type {
-  InspectorRequest,
   InspectorResponse,
   ResponseContentBlockType,
 } from "./formats/anthropic/schemas";
@@ -98,35 +93,6 @@ export {
   parseOpenAIResponse,
 } from "./formats/openai/schemas";
 
-// ============================================================
-// Utility functions
-// ============================================================
-
-function detectFormat(rawBody: string | null): RequestFormat {
-  if (rawBody === null) return "unknown";
-  try {
-    const json: unknown = JSON.parse(rawBody);
-    if (typeof json === "object" && json !== null && !Array.isArray(json)) {
-      const hasModel = safeGetOwnProperty(json, "model") !== undefined;
-      const hasMessages = safeGetOwnProperty(json, "messages") !== undefined;
-      if (hasModel && hasMessages) {
-        // Anthropic requests put `system` as a top-level key; OpenAI does not.
-        // Both formats can have `tools`, so we check `system` as the discriminator.
-        if (safeGetOwnProperty(json, "system") !== undefined) {
-          return "anthropic";
-        }
-        const msgVal = safeGetOwnProperty(json, "messages");
-        if (Array.isArray(msgVal)) {
-          return "openai";
-        }
-      }
-    }
-    return "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-
 // Schema for model name in request body (used for routing)
 const RequestModelSchema = z.object({
   model: z.string(),
@@ -191,19 +157,3 @@ export function extractRequestMetadata(body: string | null, headers: Headers): R
   }
   return { model: null, sessionId: headerSessionId };
 }
-
-/**
- * Parse a raw request body into an InspectorRequest.
- * @deprecated Use FormatHandler.parseRequest() instead
- */
-export function parseRequest(rawBody: string | null): InspectorRequest | null {
-  if (rawBody === null) return null;
-  try {
-    const json: unknown = JSON.parse(rawBody);
-    const result = InspectorRequestSchema.safeParse(json);
-    if (result.success) return result.data;
-    return null;
-  } catch {
-    return null;
-  }
-}

package/src/proxy/sessionRuntime.ts

@@ -1,6 +1,5 @@
 import { logger } from "./logger";
 import { executeFinalizeLogJob, type FinalizeLogJob } from "./logFinalizer";
-import type { CapturedLog } from "./schemas";
 import {
   getLogSessionId,
   markSessionTaskFinished,
@@ -70,14 +69,6 @@ export function enqueueSessionTask<T>(
   return current;
 }
 
-export function enqueueLogTask<T>(
-  log: CapturedLog,
-  taskName: SessionTaskName,
-  task: SessionTask<T>,
-): Promise<T> {
-  return enqueueSessionTask(getLogSessionId(log), taskName, task);
-}
-
 export function enqueueFinalizeLogJob(job: FinalizeLogJob): Promise<void> {
   return enqueueSessionTask(getLogSessionId(job.log), "finalize-log", () =>
     executeFinalizeLogJob(job),

package/src/proxy/socketTracker.ts

@@ -1,5 +1,6 @@
 import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { z } from "zod";
 import { logger } from "./logger";
 
 const execAsync = promisify(exec);
@@ -20,6 +21,12 @@ type CacheEntry = ClientInfo & {
 const cache = new Map<number, CacheEntry>();
 const CACHE_TTL_MS = 5 * 60 * 1000;
 const MAX_CACHE_SIZE = 200;
+const RemotePortSchema = z.number().int().min(1).max(65_535);
+const SocketSchema = z
+  .object({
+    remotePort: RemotePortSchema.nullish(),
+  })
+  .passthrough();
 
 // Deduplicate concurrent lookups for the same port
 const inflight = new Map<number, Promise<ClientInfo>>();
@@ -50,14 +57,14 @@ function setCache(port: number, info: ClientInfo): void {
  * Get the remote port from a Request's underlying socket.
  * Works with Bun, Node.js, and Nitro's event.node.req.
  */
-function extractRemotePort(request: Request): number | null {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
-  const socket = (request as any).socket;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
-  const remotePort = (socket as any)?.remotePort;
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-  if (remotePort !== undefined && remotePort !== null) return remotePort;
-  return null;
+export function extractRemotePort(request: Request): number | null {
+  const descriptor = Object.getOwnPropertyDescriptor(request, "socket");
+  if (descriptor === undefined || descriptor.get !== undefined) return null;
+  const parsed = SocketSchema.safeParse(descriptor.value);
+  if (!parsed.success) return null;
+  const remotePort = parsed.data.remotePort;
+  if (remotePort === undefined || remotePort === null) return null;
+  return remotePort;
 }
 
 /**