@tonyclaw/agent-inspector 2.1.9 → 2.1.11

package/src/cli.ts

@@ -12,11 +12,13 @@ import {
   probeHostForBindHost,
   urlForHost,
 } from "./cli/networkHints.js";
+import { startIdentityProxy } from "./proxy/identityProxy.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const DEFAULT_PORT = 25947;
+const DEFAULT_IDENTITY_PORT = 25949;
 const LOCAL_PROBE_TIMEOUT_MS = 2000;
 const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
 const DEFAULT_CAPTURE_MODE = "simple";
@@ -198,6 +200,34 @@ function printAccessHints(port: number, host?: string): void {
   }
 }
 
+/** Try to start the identity proxy. Returns `null` (and prints a warning)
+ *  if the listen port is already in use by another process — e.g. when
+ *  restarting a previous instance that didn't shut down cleanly. The
+ *  TanStack Start server keeps running either way; clients just lose the
+ *  per-PID attribution until they fall back to direct port `port` access. */
+async function tryStartIdentityProxy(
+  identityPort: number,
+  upstreamPort: number,
+  upstreamHost: string | undefined,
+): Promise<import("node:http").Server | null> {
+  try {
+    const server = await startIdentityProxy({
+      listenPort: identityPort,
+      upstreamHost: upstreamHost ?? "127.0.0.1",
+      upstreamPort,
+    });
+    return server;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[identity-proxy] Could not listen on port ${identityPort}: ${message}. ` +
+        `Falling back to OS-scan heuristic on port ${upstreamPort}. ` +
+        `Pass --identity-proxy-port <n> to choose another port, or --no-identity-proxy to disable.`,
+    );
+    return null;
+  }
+}
+
 async function runStart(args: string[]): Promise<void> {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
@@ -215,6 +245,11 @@ async function runStart(args: string[]): Promise<void> {
   let providersJson: string | undefined;
   let captureMode = DEFAULT_CAPTURE_MODE;
   let captureModeWasSpecified = false;
+  let enableIdentityProxy = true;
+  let identityProxyPort =
+    process.env["AGENT_INSPECTOR_IDENTITY_PORT"] !== undefined
+      ? Number(process.env["AGENT_INSPECTOR_IDENTITY_PORT"])
+      : DEFAULT_IDENTITY_PORT;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -312,6 +347,21 @@ async function runStart(args: string[]): Promise<void> {
         i++;
         break;
       }
+      case "--no-identity-proxy":
+        enableIdentityProxy = false;
+        break;
+      case "--identity-proxy-port": {
+        const value = args[i + 1];
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+          console.error(`Invalid identity-proxy port: ${String(value)}.`);
+          process.exitCode = 1;
+          return;
+        }
+        identityProxyPort = parsed;
+        i++;
+        break;
+      }
       default:
         break;
     }
@@ -425,6 +475,7 @@ async function runStart(args: string[]): Promise<void> {
 
   if (forceRestart) {
     killProcessOnPort(port);
+    if (enableIdentityProxy) killProcessOnPort(identityProxyPort);
   }
 
   console.log(`Server running at ${url}`);
@@ -495,11 +546,34 @@ async function runStart(args: string[]): Promise<void> {
     windowsHide: background,
   });
 
+  // Identity proxy — a native Node HTTP server that sits in front of
+  // TanStack Start and looks up each client's PID via the OS connection
+  // table, injecting the result as `X-Agent-Inspector-Client-*` headers.
+  // This lets AI tools (which can't easily set those headers themselves)
+  // still get accurate session attribution. Started only after TanStack
+  // Start is healthy, so the upstream is ready by the time clients connect.
+  const identityProxy = enableIdentityProxy
+    ? await tryStartIdentityProxy(identityProxyPort, port, host)
+    : null;
+
   if (background) {
     serverProcess.unref();
     if (await waitForInspectorHealthy(port, 5000, host)) {
       console.log(`agent-inspector background server is ready at ${url}`);
+      if (identityProxy !== null) {
+        console.log(`Identity proxy ready on port ${identityProxyPort} (PID-attributing proxy).`);
+      }
       printAccessHints(port, host);
+      if (identityProxy !== null) {
+        console.log(
+          ``,
+          `Route AI coding tools through the identity proxy for accurate PID attribution:`,
+          `   Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${identityProxyPort}/proxy claude`,
+          `   OpenCode:     LLM_BASE_URL=http://localhost:${identityProxyPort}/proxy opencode`,
+          `   MiMo Code:    OPENAI_BASE_URL=http://localhost:${identityProxyPort}/proxy mimo`,
+          `   (Direct ${port} still works; it falls back to OS-scan heuristic.)`,
+        );
+      }
       return;
     }
     console.error(`agent-inspector background server did not become ready at ${url}.`);
@@ -508,4 +582,19 @@ async function runStart(args: string[]): Promise<void> {
   }
 
   process.exitCode = await waitForProcessExit(serverProcess);
+
+  // Foreground path: print the smart-port hint now that the proxy is up,
+  // then keep the proxy alive until the server exits.
+  if (identityProxy !== null) {
+    console.log(
+      ``,
+      `Identity proxy is listening on port ${identityProxyPort}:`,
+      `   Route AI coding tools through the identity proxy for accurate PID attribution:`,
+      `      Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${identityProxyPort}/proxy claude`,
+      `      OpenCode:     LLM_BASE_URL=http://localhost:${identityProxyPort}/proxy opencode`,
+      `      MiMo Code:    OPENAI_BASE_URL=http://localhost:${identityProxyPort}/proxy mimo`,
+      `   Direct port ${port} still works (falls back to OS-scan heuristic).`,
+    );
+    await new Promise<void>((resolve) => identityProxy.close(() => resolve()));
+  }
 }

package/src/components/proxy-viewer/LogEntryHeader.tsx

@@ -243,32 +243,31 @@ export const LogEntryHeader = memo(function ({
           </Tooltip>
         )}
 
-        {/* Elapsed time */}
-        {log.elapsedMs !== null && (
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <span
-                className={cn(
-                  "flex items-center gap-1 text-xs shrink-0",
-                  isSlowResponse ? "text-amber-400" : "text-muted-foreground",
-                )}
-              >
-                <Clock className="size-3" />
-                <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
-                {isSlowResponse && <AlertTriangle className="size-3" aria-label="Slow response" />}
-              </span>
-            </TooltipTrigger>
-            <TooltipContent>
-              {isSlowResponse
-                ? `Slow response: ${formatElapsed(log.elapsedMs)} exceeds ${formatElapsed(
-                    slowResponseThresholdSeconds * 1000,
-                  )}`
-                : log.streaming
-                  ? "Total streaming response time"
-                  : "Elapsed response time"}
-            </TooltipContent>
-          </Tooltip>
-        )}
+        {/* Elapsed time. Tooltip is only shown when this log exceeded the slow-
+            response threshold — for normal-speed logs the elapsed value is
+            self-explanatory, so we skip the tooltip wrapper to keep the row
+            quiet. */}
+        {log.elapsedMs !== null &&
+          (isSlowResponse ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span className="flex items-center gap-1 text-xs text-amber-400 shrink-0">
+                  <Clock className="size-3" />
+                  <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
+                  <AlertTriangle className="size-3" aria-label="Slow response" />
+                </span>
+              </TooltipTrigger>
+              <TooltipContent>
+                Slow response: {formatElapsed(log.elapsedMs)} exceeds{" "}
+                {formatElapsed(slowResponseThresholdSeconds * 1000)}
+              </TooltipContent>
+            </Tooltip>
+          ) : (
+            <span className="flex items-center gap-1 text-xs text-muted-foreground shrink-0">
+              <Clock className="size-3" />
+              <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
+            </span>
+          ))}
 
         {/* Streaming timing */}
         {log.streaming && firstChunkLabel !== null && (

package/src/proxy/identityProxy.ts

@@ -0,0 +1,193 @@
+import http from "node:http";
+import { Buffer } from "node:buffer";
+import { lookupClientByPort } from "./socketTracker";
+
+const IDENTITY_HEADERS = {
+  pid: "x-agent-inspector-client-pid",
+  port: "x-agent-inspector-client-port",
+  cwd: "x-agent-inspector-client-cwd",
+  projectFolder: "x-agent-inspector-client-project-folder",
+} as const;
+
+const REQUEST_HOP_BY_HOP = new Set([
+  "host",
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+]);
+
+const RESPONSE_HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+export type IdentityProxyOptions = {
+  /** Port to listen on (default 25949). Clients point at this. */
+  listenPort: number;
+  /** Host the upstream TanStack Start server listens on. */
+  upstreamHost: string;
+  /** Port the upstream TanStack Start server listens on (default 25947). */
+  upstreamPort: number;
+};
+
+/**
+ * Start a tiny native Node HTTP server that:
+ *   1. Reads the client connection's source port (`req.socket.remotePort`).
+ *   2. Resolves that port to a PID via the OS connection table
+ *      (`Get-NetTCPConnection -LocalPort <port>` on Windows,
+ *       `ss -tanp state established` on Linux/macOS).
+ *   3. Resolves the PID's cwd / project folder.
+ *   4. Injects everything as `X-Agent-Inspector-Client-*` headers.
+ *   5. Reverse-proxies the request to the upstream inspector (TanStack
+ *      Start, which already reads those headers via `getClientInfo`).
+ *
+ * Why this exists: TanStack Start strips the underlying TCP socket from
+ * the fetch-API `Request` before it reaches the proxy handler, so the
+ * handler cannot read `socket.remotePort`. Sitting in front of TanStack
+ * Start as a native Node server restores the ability to look up the
+ * client PID at the socket level — no wrapper script, no client-side
+ * changes, no header configuration by the AI tool author.
+ *
+ * The proxy degrades gracefully when the OS lookup fails (missing
+ * permissions, port not found): the request is still forwarded, just
+ * without identity headers, so it falls back to the existing
+ * best-effort scan inside TanStack Start.
+ */
+export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    // Eagerly resolve client identity on `connection` — at that point the
+    // socket is fresh and the OS connection table still lists it as
+    // ESTABLISHED. By the time `request` fires (let alone after we finish
+    // reading the body) HTTP/1.0 clients have already closed their side
+    // and the row is in TIME_WAIT with PID 0.
+    server.on("connection", (socket: import("node:net").Socket) => {
+      const remotePort = socket.remotePort;
+      if (remotePort !== undefined && remotePort > 0) {
+        void lookupClientByPort(remotePort).catch(() => null);
+      }
+    });
+    server.on("request", (req, res) => {
+      void handleRequest(req, res, options).catch((err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!res.headersSent) {
+          res.writeHead(502, { "content-type": "text/plain" });
+        }
+        res.end(`Identity proxy error: ${message}`);
+      });
+    });
+    server.once("error", reject);
+    server.listen(options.listenPort, () => {
+      server.removeListener("error", reject);
+      resolve(server);
+    });
+  });
+}
+
+async function handleRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  options: IdentityProxyOptions,
+): Promise<void> {
+  // The connection-time lookup already populated the per-port cache; this
+  // call now hits the cache and returns the result synchronously.
+  const remotePort = req.socket.remotePort;
+  let identity: Awaited<ReturnType<typeof lookupClientByPort>> | null = null;
+  if (remotePort !== undefined && remotePort > 0) {
+    try {
+      identity = await lookupClientByPort(remotePort);
+    } catch {
+      identity = null;
+    }
+  }
+
+  // Buffer the request body — TanStack Start needs the raw bytes intact
+  // for SSE/streaming endpoints, so we can't decode-and-re-encode.
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : toBuffer(chunk));
+  }
+  const body = Buffer.concat(chunks);
+
+  const upstreamHeaders: Record<string, string | string[]> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (REQUEST_HOP_BY_HOP.has(name.toLowerCase())) continue;
+    if (value === undefined) continue;
+    upstreamHeaders[name] = value;
+  }
+  if (identity !== null && identity.pid !== null) {
+    upstreamHeaders[IDENTITY_HEADERS.pid] = String(identity.pid);
+    if (identity.port !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.port] = String(identity.port);
+    }
+    if (identity.cwd !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.cwd] = identity.cwd;
+    }
+    if (identity.projectFolder !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.projectFolder] = identity.projectFolder;
+    }
+  }
+
+  process.stderr.write(
+    `[identity-proxy] req ${req.method} ${req.url} remotePort=${remotePort} pid=${identity?.pid ?? "?"}\n`,
+  );
+  process.stderr.write(
+    `[identity-proxy] forwarding headers: pid=${upstreamHeaders[IDENTITY_HEADERS.pid] ?? "?"} cwd=${upstreamHeaders[IDENTITY_HEADERS.cwd] ?? "?"}\n`,
+  );
+
+  const proxyReq = http.request(
+    {
+      hostname: options.upstreamHost,
+      port: options.upstreamPort,
+      path: req.url ?? "/",
+      method: req.method,
+      headers: upstreamHeaders,
+    },
+    (proxyRes) => {
+      const outHeaders: Record<string, string | string[]> = {};
+      for (const [name, value] of Object.entries(proxyRes.headers)) {
+        if (RESPONSE_HOP_BY_HOP.has(name.toLowerCase())) continue;
+        if (value === undefined) continue;
+        outHeaders[name] = value;
+      }
+      res.writeHead(proxyRes.statusCode ?? 502, outHeaders);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("error", (err) => {
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain" });
+    }
+    res.end(`Upstream error: ${err.message}`);
+  });
+  if (body.length > 0) proxyReq.write(body);
+  proxyReq.end();
+}
+
+// `Readable` chunks in Node are typed as `any` (they can be Buffer | string
+// depending on the encoding setting). We narrow them via runtime checks.
+function toBuffer(chunk: unknown): Buffer {
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (typeof chunk === "string") return Buffer.from(chunk);
+  // `for await` over a Node Readable always yields Buffer | string; this
+  // branch is only reachable if a custom stream returns something else
+  // (Uint8Array / ArrayBuffer / etc.). The Buffer constructor accepts an
+  // ArrayBuffer directly; we attempt that first, then fall back to a
+  // best-effort empty buffer so we never throw on an unexpected chunk.
+  if (chunk instanceof ArrayBuffer) return Buffer.from(chunk);
+  if (chunk instanceof Uint8Array)
+    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  return Buffer.alloc(0);
+}