@tonyclaw/agent-inspector 2.1.10 → 2.1.11

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);
+}

package/src/proxy/socketTracker.ts

@@ -498,3 +498,125 @@ export async function getClientInfo(request: Request): Promise<ClientInfo> {
   recentInflight = promise;
   return promise;
 }
+
+/**
+ * Lookup the PID owning a specific client-side local port, then enrich it
+ * with the process's cwd / project folder. Used by the identity-injecting
+ * native HTTP proxy in `identityProxy.ts`, which has access to
+ * `req.socket.remotePort` (the client's ephemeral port) and needs to know
+ * which process opened the connection.
+ *
+ * Results are cached by `clientPort` for `PORT_LOOKUP_TTL_MS` — a single
+ * keep-alive connection typically reuses the same client port for many
+ * requests, so we don't want to spawn a subprocess per request.
+ */
+const PORT_LOOKUP_TTL_MS = 5 * 60 * 1000;
+const portInfoCache = new Map<number, { info: ClientInfo; expiresAt: number }>();
+
+export async function lookupClientByPort(clientPort: number): Promise<ClientInfo> {
+  if (!Number.isInteger(clientPort) || clientPort <= 0 || clientPort > 65_535) {
+    return { port: null, pid: null, cwd: null, projectFolder: null };
+  }
+  const cached = portInfoCache.get(clientPort);
+  if (cached !== undefined && Date.now() < cached.expiresAt) {
+    return cached.info;
+  }
+  try {
+    const pid = await lookupPidByLocalPort(clientPort);
+    if (pid === null) {
+      const fallback: ClientInfo = {
+        port: clientPort,
+        pid: null,
+        cwd: null,
+        projectFolder: null,
+      };
+      portInfoCache.set(clientPort, { info: fallback, expiresAt: Date.now() + PORT_LOOKUP_TTL_MS });
+      return fallback;
+    }
+    const { cwd, projectFolder } = await lookupProcessInfo(pid);
+    const info: ClientInfo = { port: clientPort, pid, cwd, projectFolder };
+    portInfoCache.set(clientPort, { info, expiresAt: Date.now() + PORT_LOOKUP_TTL_MS });
+    return info;
+  } catch (err) {
+    logger.debug(`[socketTracker] lookupClientByPort(${clientPort}) failed:`, String(err));
+    return { port: clientPort, pid: null, cwd: null, projectFolder: null };
+  }
+}
+
+/** Returns the PID owning `clientPort` on the local machine, or `null`
+ *  if the port isn't held by any known process. Cross-platform wrapper
+ *  around the OS-specific connection table. */
+async function lookupPidByLocalPort(clientPort: number): Promise<number | null> {
+  const platform = process.platform;
+  try {
+    if (platform === "win32") {
+      // We deliberately use `netstat -ano | findstr` instead of
+      // `Get-NetTCPConnection -LocalPort`. The PowerShell cmdlet
+      // enumerates the entire socket table before filtering, which on a
+      // busy machine takes 10+ seconds — longer than our per-request
+      // timeout. `netstat -ano` streams its output and `findstr` filters
+      // line by line, completing in ~0.5s.
+      //
+      // `netstat -ano` lists every TCP connection twice — once for each
+      // endpoint. The format is:
+      //
+      //   Proto  LocalAddress        RemoteAddress       State            PID
+      //   TCP    [::1]:25949         [::1]:55193         ESTABLISHED     10936   ← server-side row (proxy owns the listener)
+      //   TCP    [::1]:55193         [::1]:25949         ESTABLISHED     29356   ← client-side row (curl owns the ephemeral port)
+      //
+      // For `clientPort` (the client's ephemeral port) we want the row
+      // whose LOCAL column ends with `:<clientPort>` — that's the row
+      // attributed to the client process.
+      const { stdout } = await execAsync(
+        `netstat -ano | findstr :${clientPort} | findstr ESTABLISHED`,
+        { shell: "cmd.exe", timeout: 2000, windowsHide: true },
+      );
+      const clientToken = `:${clientPort}`;
+      for (const rawLine of stdout.split("\n")) {
+        const line = rawLine.trim();
+        if (line === "") continue;
+        const cols = line.split(/\s+/);
+        if (cols.length < 5) continue;
+        const localAddr = cols[1] ?? "";
+        if (!localAddr.endsWith(clientToken)) continue;
+        const pidStr = cols[cols.length - 1] ?? "";
+        const parsed = parseInt(pidStr, 10);
+        if (Number.isInteger(parsed) && parsed > 0) return parsed;
+      }
+      return null;
+    }
+    // Unix: try `ss` first, fall back to `lsof`. Both need root or
+    // CAP_NET_ADMIN to see PIDs of processes owned by other users; when
+    // permission is denied the command exits non-zero and we return null.
+    try {
+      const { stdout } = await execAsync(
+        `ss -tanp state established 'sport = :${clientPort}' 2>/dev/null | tail -n +2 | head -n 1`,
+        { shell: "/bin/sh" },
+      );
+      const match = stdout.match(/pid=(\d+)/);
+      if (match !== null) {
+        const parsed = parseInt(match[1] ?? "", 10);
+        if (Number.isInteger(parsed) && parsed > 0) return parsed;
+      }
+    } catch {
+      // fall through
+    }
+    try {
+      const { stdout } = await execAsync(
+        `lsof -ti tcp:${clientPort} -sTCP:ESTABLISHED 2>/dev/null`,
+        {
+          shell: "/bin/sh",
+        },
+      );
+      const trimmed = stdout.trim().split("\n")[0] ?? "";
+      const parsed = parseInt(trimmed, 10);
+      if (Number.isInteger(parsed) && parsed > 0) return parsed;
+    } catch {
+      // fall through
+    }
+    return null;
+  } catch (err) {
+    logger.debug(`[socketTracker] lookupPidByLocalPort(${clientPort}) failed:`, String(err));
+    return null;
+  }
+}

package/.output/public/assets/_sessionId-3JCekYV3.js

@@ -1 +0,0 @@
-import{R as s,j as e}from"./main-JvXpk_ov.js";import{P as i}from"./ProxyViewerContainer-Cxwizw8H.js";function t(){const{sessionId:o}=s.useParams();return e.jsx(i,{initialSessionId:o},o)}export{t as component};

package/.output/public/assets/index-B3EOwfg7.js

@@ -1 +0,0 @@
-import{P as o}from"./ProxyViewerContainer-Cxwizw8H.js";import"./main-JvXpk_ov.js";const r=o;export{r as component};