@linzumi/cli 0.0.4-beta → 0.0.6-beta

package/src/portForwardWatcher.ts

@@ -0,0 +1,404 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
+  Relationship: Detects descendant listener ports for the local Codex runner so
+  Kandan can prompt the authorized listener user before exposing a local
+  service through the runner forward route.
+*/
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
+
+export type ProcessRow = {
+  readonly pid: number;
+  readonly ppid: number;
+  readonly command: string;
+};
+
+export type ListenSocketRow = {
+  readonly pid: number;
+  readonly port: number;
+  readonly command: string;
+};
+
+export type PortForwardCandidate = {
+  readonly port: number;
+  readonly pid: number;
+  readonly command: string;
+  readonly cwd?: string | undefined;
+};
+
+export type PortForwardWatcher = {
+  readonly close: () => void;
+};
+
+export type PortForwardWatcherOptions = {
+  readonly rootPid?: number | undefined;
+  readonly intervalMs?: number | undefined;
+  readonly debounceMs?: number | undefined;
+  readonly scanProcesses?: (() => readonly ProcessRow[]) | undefined;
+  readonly scanListenSockets?: (() => readonly ListenSocketRow[]) | undefined;
+  readonly scanProcessCwds?: ((pids: readonly number[]) => ReadonlyMap<number, string>) | undefined;
+  readonly nowMs?: (() => number) | undefined;
+  readonly onCandidate: (candidate: PortForwardCandidate) => void | Promise<void>;
+  readonly onError?: ((error: Error) => void) | undefined;
+};
+
+const defaultIntervalMs = 2_000;
+const defaultDebounceMs = 750;
+
+export type ObservedPortForwardCandidate = {
+  readonly candidate: PortForwardCandidate;
+  readonly firstSeenAtMs: number;
+};
+
+export function startPortForwardWatcher(
+  options: PortForwardWatcherOptions,
+): PortForwardWatcher {
+  const rootPid = options.rootPid ?? process.pid;
+  const intervalMs = options.intervalMs ?? defaultIntervalMs;
+  const debounceMs = options.debounceMs ?? defaultDebounceMs;
+  const scanProcesses = options.scanProcesses ?? readProcessRows;
+  const scanListenSockets = options.scanListenSockets ?? readListenSocketRows;
+  const scanProcessCwds = options.scanProcessCwds ?? readProcessCwdRows;
+  const nowMs = options.nowMs ?? Date.now;
+  const candidateStabilityByPort = new Map<number, ObservedPortForwardCandidate>();
+  const emittedByPort = new Map<number, PortForwardCandidate>();
+  const inFlight = { value: false };
+
+  const scan = () => {
+    if (inFlight.value) {
+      return;
+    }
+
+    inFlight.value = true;
+    void Promise.resolve()
+      .then(async () => {
+        const descendants = descendantPidSet(scanProcesses(), rootPid);
+        const sockets = scanListenSockets();
+        const candidatePids = sockets
+          .filter(socket => descendants.has(socket.pid))
+          .map(socket => socket.pid);
+        const candidates = detectedForwardCandidates(
+          sockets,
+          descendants,
+          scanProcessCwds(candidatePids),
+        );
+        const stable = stableForwardCandidates(
+          candidateStabilityByPort,
+          candidates,
+          nowMs(),
+          debounceMs,
+        );
+        const changes = changedForwardCandidates(emittedByPort, stable.stableCandidates);
+        candidateStabilityByPort.clear();
+        emittedByPort.clear();
+
+        for (const [port, observed] of stable.nextObservedByPort) {
+          candidateStabilityByPort.set(port, observed);
+        }
+
+        for (const [port, candidate] of changes.nextObservedByPort) {
+          emittedByPort.set(port, candidate);
+        }
+
+        for (const candidate of changes.changedCandidates) {
+          await options.onCandidate(candidate);
+        }
+      })
+      .catch(error => {
+        options.onError?.(error instanceof Error ? error : new Error(String(error)));
+      })
+      .finally(() => {
+        inFlight.value = false;
+      });
+  };
+
+  scan();
+  const interval = setInterval(scan, intervalMs);
+
+  return {
+    close: () => clearInterval(interval),
+  };
+}
+
+export function changedForwardCandidates(
+  previousObservedByPort: ReadonlyMap<number, PortForwardCandidate>,
+  candidates: readonly PortForwardCandidate[],
+): {
+  readonly nextObservedByPort: Map<number, PortForwardCandidate>;
+  readonly changedCandidates: PortForwardCandidate[];
+} {
+  const nextObservedByPort = new Map<number, PortForwardCandidate>();
+  const changedCandidates: PortForwardCandidate[] = [];
+
+  for (const candidate of candidates) {
+    nextObservedByPort.set(candidate.port, candidate);
+    const previous = previousObservedByPort.get(candidate.port);
+
+    if (previous === undefined || !sameForwardCandidate(previous, candidate)) {
+      changedCandidates.push(candidate);
+    }
+  }
+
+  return { nextObservedByPort, changedCandidates };
+}
+
+export function stableForwardCandidates(
+  previousObservedByPort: ReadonlyMap<number, ObservedPortForwardCandidate>,
+  candidates: readonly PortForwardCandidate[],
+  nowMs: number,
+  debounceMs: number,
+): {
+  readonly nextObservedByPort: Map<number, ObservedPortForwardCandidate>;
+  readonly stableCandidates: PortForwardCandidate[];
+} {
+  const nextObservedByPort = new Map<number, ObservedPortForwardCandidate>();
+  const stableCandidates: PortForwardCandidate[] = [];
+
+  for (const candidate of candidates) {
+    const previous = previousObservedByPort.get(candidate.port);
+    const firstSeenAtMs =
+      previous !== undefined && sameForwardCandidate(previous.candidate, candidate)
+        ? previous.firstSeenAtMs
+        : nowMs;
+    const observed = { candidate, firstSeenAtMs };
+    nextObservedByPort.set(candidate.port, observed);
+
+    if (debounceMs <= 0 || nowMs - firstSeenAtMs >= debounceMs) {
+      stableCandidates.push(candidate);
+    }
+  }
+
+  return { nextObservedByPort, stableCandidates };
+}
+
+export function sameForwardCandidate(
+  left: PortForwardCandidate,
+  right: PortForwardCandidate,
+): boolean {
+  return (
+    left.port === right.port &&
+    left.pid === right.pid &&
+    left.command === right.command &&
+    left.cwd === right.cwd
+  );
+}
+
+export function descendantPidSet(
+  rows: readonly ProcessRow[],
+  rootPid: number,
+): Set<number> {
+  const childrenByParent = new Map<number, number[]>();
+
+  for (const row of rows) {
+    const existing = childrenByParent.get(row.ppid) ?? [];
+    childrenByParent.set(row.ppid, [...existing, row.pid]);
+  }
+
+  const descendants = new Set<number>();
+  const queue = [...(childrenByParent.get(rootPid) ?? [])];
+
+  while (queue.length > 0) {
+    const pid = queue.shift();
+
+    if (pid === undefined || descendants.has(pid)) {
+      continue;
+    }
+
+    descendants.add(pid);
+    queue.push(...(childrenByParent.get(pid) ?? []));
+  }
+
+  return descendants;
+}
+
+export function detectedForwardCandidates(
+  sockets: readonly ListenSocketRow[],
+  descendantPids: ReadonlySet<number>,
+  processCwds: ReadonlyMap<number, string> = new Map(),
+): PortForwardCandidate[] {
+  return sockets
+    .filter(socket => descendantPids.has(socket.pid))
+    .filter(socket => socket.port > 0 && socket.port < 65_536)
+    .sort((left, right) => left.port - right.port)
+    .map(socket => {
+      const cwd = processCwds.get(socket.pid);
+
+      return {
+        port: socket.port,
+        pid: socket.pid,
+        command: socket.command,
+        ...(cwd === undefined ? {} : { cwd }),
+      };
+    });
+}
+
+export function parseProcessRows(output: string): ProcessRow[] {
+  return output
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line !== "")
+    .map(line => {
+      const match = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+
+      if (match === null) {
+        return undefined;
+      }
+
+      return {
+        pid: Number(match[1]),
+        ppid: Number(match[2]),
+        command: match[3] ?? "",
+      };
+    })
+    .filter((row): row is ProcessRow => row !== undefined);
+}
+
+export function parseLsofListenRows(output: string): ListenSocketRow[] {
+  const rows: ListenSocketRow[] = [];
+  let currentPid: number | undefined;
+  let currentCommand: string | undefined;
+
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+
+    if (line.startsWith("p")) {
+      currentPid = Number(line.slice(1));
+      currentCommand = undefined;
+      continue;
+    }
+
+    if (line.startsWith("c")) {
+      currentCommand = line.slice(1);
+      continue;
+    }
+
+    if (!line.startsWith("n") || currentPid === undefined) {
+      continue;
+    }
+
+    const port = portFromLsofName(line.slice(1));
+
+    if (port !== undefined) {
+      rows.push({
+        pid: currentPid,
+        port,
+        command: currentCommand ?? "unknown",
+      });
+    }
+  }
+
+  return rows;
+}
+
+export function parseLsofCwdRows(output: string): Map<number, string> {
+  const rows = new Map<number, string>();
+  let currentPid: number | undefined;
+
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+
+    if (line.startsWith("p")) {
+      currentPid = Number(line.slice(1));
+      continue;
+    }
+
+    if (line.startsWith("n") && currentPid !== undefined) {
+      const cwd = line.slice(1).trim();
+
+      if (cwd !== "") {
+        rows.set(currentPid, cwd);
+      }
+    }
+  }
+
+  return rows;
+}
+
+function readProcessRows(): ProcessRow[] {
+  const result = spawnSync("ps", ["-axo", "pid=,ppid=,command="], {
+    encoding: "utf8",
+  });
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`ps failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseProcessRows(result.stdout);
+}
+
+function readListenSocketRows(): ListenSocketRow[] {
+  const result = spawnSync(
+    "lsof",
+    ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPcn"],
+    { encoding: "utf8" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    if (result.status === 1 && result.stdout.trim() === "") {
+      return [];
+    }
+
+    throw new Error(`lsof failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseLsofListenRows(result.stdout);
+}
+
+function readProcessCwdRows(pids: readonly number[]): ReadonlyMap<number, string> {
+  const uniquePids = [...new Set(pids)].filter(pid => Number.isInteger(pid) && pid > 0);
+
+  if (uniquePids.length === 0) {
+    return new Map();
+  }
+
+  const result = spawnSync(
+    "lsof",
+    ["-a", "-p", uniquePids.join(","), "-d", "cwd", "-Fn"],
+    { encoding: "utf8" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    if (result.status === 1 && result.stdout.trim() === "") {
+      return new Map();
+    }
+
+    throw new Error(`lsof cwd failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseLsofCwdRows(result.stdout);
+}
+
+function portFromLsofName(name: string): number | undefined {
+  const match = name.match(/:(\d+)(?:\s|\(|$)/);
+
+  if (match === null) {
+    return undefined;
+  }
+
+  const port = Number(match[1]);
+
+  return Number.isInteger(port) ? port : undefined;
+}
+
+export function commandLabel(command: string): string {
+  const trimmed = command.trim();
+
+  if (trimmed === "") {
+    return "unknown";
+  }
+
+  return basename(trimmed.split(/\s+/)[0] ?? trimmed);
+}

package/src/protocol.ts

@@ -14,6 +14,29 @@
   Relationship: Defines the typed runner control that carries a Kandan
   Approve/Deny decision back to the local Codex app-server approval request
   without exposing a browser-to-runner socket.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Carries the runner streaming flush interval so live Codex
+  output can be batched before Kandan persistence without changing the logical
+  transcript protocol.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-forwarding-and-editor-plan.md
+  Relationship: Defines the typed control used by Kandan to ask a connected
+  runner to perform one bounded HTTP request against an explicitly allowed
+  local preview port, and the typed control used to ask the runner to start a
+  loopback-only local code-server editor for an allowed cwd.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
+  Relationship: Defines the typed approval control Kandan sends after the
+  in-app local port prompt is resolved by the authorized listener user.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
+  Relationship: Defines the typed WebSocket forwarding controls used by
+  isolated preview subdomains.
 */
 export type JsonValue =
   | null
@@ -56,14 +79,17 @@ export type JsonRpcResponse =
       };
     };
 
-export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+export type JsonRpcMessage =
+  | JsonRpcRequest
+  | JsonRpcNotification
+  | JsonRpcResponse;
 
 export type PhoenixFrame = readonly [
   joinRef: string | null,
   ref: string | null,
   topic: string,
   event: string,
-  payload: JsonValue
+  payload: JsonValue,
 ];
 
 export type RunnerToKandanEvent =
@@ -108,6 +134,11 @@ export type KandanControl =
       readonly instanceId?: string;
       readonly cwd?: string;
       readonly launchTui?: boolean;
+      readonly model?: string;
+      readonly reasoningEffort?: string;
+      readonly approvalPolicy?: string;
+      readonly sandbox?: string;
+      readonly fast?: boolean;
     }
   | {
       readonly type: "stop_instance";
@@ -150,11 +181,73 @@ export type KandanControl =
       readonly requestId: string;
       readonly decision: "approve" | "deny";
     }
+  | {
+      readonly type: "resolve_port_forward_request";
+      readonly instanceId: string;
+      readonly requestId: string;
+      readonly decision: "approve" | "deny";
+      readonly actorUserId?: number | undefined;
+      readonly actorSlug?: string | undefined;
+    }
   | {
       readonly type: "read_thread";
       readonly instanceId: string;
       readonly threadId: string;
       readonly includeTurns?: boolean;
+    }
+  | {
+      readonly type: "forward_http_request";
+      readonly instanceId?: string;
+      readonly requestId: string;
+      readonly port: number;
+      readonly method: string;
+      readonly path: string;
+      readonly queryString?: string;
+      readonly headers?: JsonValue;
+      readonly bodyBase64?: string;
+    }
+  | {
+      readonly type: "forward_websocket_open";
+      readonly instanceId?: string;
+      readonly socketId: string;
+      readonly port: number;
+      readonly path: string;
+      readonly queryString?: string;
+      readonly headers?: JsonValue;
+    }
+  | {
+      readonly type: "forward_websocket_send";
+      readonly instanceId?: string;
+      readonly socketId: string;
+      readonly opcode: "text" | "binary" | "ping" | "pong";
+      readonly bodyBase64: string;
+    }
+  | {
+      readonly type: "forward_websocket_close";
+      readonly instanceId?: string;
+      readonly socketId: string;
+    }
+  | {
+      readonly type: "update_runner_config";
+      readonly instanceId?: string;
+      readonly allowedCwds: readonly string[];
+      readonly configVersion?: number;
+    }
+  | {
+      readonly type: "start_local_editor";
+      readonly instanceId?: string;
+      readonly requestId?: string;
+      readonly cwd: string;
+      readonly browserBaseUrl?: string;
+      readonly collaboration?: {
+        readonly provider: "oct";
+        readonly editorSessionId: number;
+        readonly runtimeSessionId: string;
+        readonly roomId: string;
+        readonly extensionAssetPath: string;
+        readonly serverAssetPath: string;
+        readonly bootstrapToken?: string;
+      };
     };
 
 export type KandanChannelSessionOptions = {
@@ -166,6 +259,7 @@ export type KandanChannelSessionOptions = {
   readonly reasoningEffort?: string | undefined;
   readonly sandbox?: string | undefined;
   readonly approvalPolicy?: string | undefined;
+  readonly streamFlushMs?: number | undefined;
 };
 
 export function parseJsonObject(text: string): JsonObject {
@@ -204,7 +298,7 @@ export function extractCodexIds(params: JsonObject): JsonObject {
     ["turnId", params.turnId],
     ["itemId", params.itemId],
     ["processId", params.processId],
-    ["requestId", params.requestId]
+    ["requestId", params.requestId],
   ].filter((entry): entry is [string, JsonValue] => entry[1] !== undefined);
 
   return Object.fromEntries(entries) as JsonObject;