@saadnvd1/agent-os 0.3.728 → 0.3.733

package/lib/health/tick.ts

@@ -11,6 +11,7 @@ import { healthConfig, type HealthConfig } from "./config";
 import { runDetectors } from "./detectors";
 import { gatherFacts, liveBackgroundJobs } from "./facts";
 import { envTick, realEnv, type EnvDeps } from "./env/envTick";
+import { portWaitTick } from "./port-wait-tick";
 import { spinTick } from "./spin-tick";
 import { addNote } from "./notes";
 import { closeResolvedPieces } from "./pieces";
@@ -45,9 +46,9 @@ export const MAX_WAKES = 2;
 export const WAKE_GIVE_UP_MS = 3 * MIN;
 
 // The checks the tick evaluates: piece-dup is raised where a piece starts,
-// bg-spin by the process step (spin-tick.ts).
+// bg-spin and port-wait by the process steps (spin-tick.ts, port-wait-tick.ts).
 export const TICK_CHECKS: readonly CheckId[] = CHECKS.filter(
-  (c) => c !== "piece-dup" && c !== "bg-spin"
+  (c) => c !== "piece-dup" && c !== "bg-spin" && c !== "port-wait"
 );
 
 export interface TickDeps {
@@ -58,6 +59,8 @@ export interface TickDeps {
   env: EnvDeps;
   // Stops background jobs that spin (spin-tick.ts).
   spin: (now: number) => Promise<void>;
+  // Tells agents that wait on a port someone else holds (port-wait-tick.ts).
+  portWait: (now: number, c: HealthConfig) => Promise<void>;
   wake: typeof wake;
 }
 
@@ -68,6 +71,7 @@ export const realTick: TickDeps = {
   route: realRoute,
   env: realEnv,
   spin: spinTick,
+  portWait: portWaitTick,
   wake,
 };
 
@@ -153,6 +157,9 @@ export function healthTick(
   void deps
     .spin(now)
     .catch((error) => console.error("[health] spin check:", error));
+  void deps
+    .portWait(now, c)
+    .catch((error) => console.error("[health] port-wait check:", error));
   void envTick(now, c, deps.env).catch((error) =>
     console.error("[health] environment failures:", error)
   );

package/lib/health/types.ts

@@ -15,6 +15,7 @@ export const CHECKS = [
   "queue-held",
   "bg-quiet",
   "bg-spin",
+  "port-wait",
   "piece-dup",
   "restarts",
   "ci-slow",
@@ -28,6 +29,7 @@ export const AREA_OF: Record<CheckId, Area> = {
   "queue-held": "scheduler",
   "bg-quiet": "tasks",
   "bg-spin": "tasks",
+  "port-wait": "tasks",
   "piece-dup": "pipeline",
   restarts: "pipeline",
   "ci-slow": "pipeline",

package/lib/{ports.ts → ports/allocatePorts.ts}

@@ -6,8 +6,8 @@
 
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { db } from "./db";
-import { windowsListeningPorts } from "./windows-ports";
+import { db } from "@/lib/db";
+import { windowsListeningPorts } from "@/lib/windows-ports";
 
 const execFileAsync = promisify(execFile);
 
@@ -38,7 +38,7 @@ export const portsFor = (
     Object.entries(bases).map(([name, base]) => [name, base + slot])
   );
 
-const parsePorts = (json: string | null | undefined) => {
+export const parsePorts = (json: string | null | undefined) => {
   if (!json) return null;
   try {
     return JSON.parse(json) as Record<string, number>;
@@ -91,13 +91,17 @@ async function reclaimEnded(
   }
 }
 
-// Every port another session holds: its slot's ports, and the single port
-// sessions from before slots were given.
-function portsTaken(exceptId: string): Set<number> {
+// Every port another session on this machine holds: its slot's ports, the
+// single port sessions from before slots were given, and the Dev Servers
+// panel's running servers. A linked machine's session is another network
+// namespace, so its ports never block ours. Slots stay counted across every
+// row: the unique index is on the slot alone.
+export function portsTaken(exceptId: string | null): Set<number> {
   const rows = db
     .prepare(
       `SELECT ports, dev_server_port FROM sessions
-       WHERE id != ? AND (ports IS NOT NULL OR dev_server_port IS NOT NULL)`
+       WHERE id IS NOT ? AND (host_id IS NULL OR host_id = 'local')
+         AND (ports IS NOT NULL OR dev_server_port IS NOT NULL)`
     )
     .all(exceptId) as {
     ports: string | null;
@@ -108,9 +112,28 @@ function portsTaken(exceptId: string): Set<number> {
     for (const p of Object.values(parsePorts(r.ports) ?? {})) taken.add(p);
     if (r.dev_server_port) taken.add(r.dev_server_port);
   }
+  for (const p of devServerPorts()) taken.add(p);
   return taken;
 }
 
+function devServerPorts(): number[] {
+  const rows = db
+    .prepare(
+      `SELECT ports FROM dev_servers WHERE status IN ('running', 'starting')`
+    )
+    .all() as { ports: string }[];
+  return rows.flatMap((r) => {
+    try {
+      const ports = JSON.parse(r.ports) as unknown;
+      return Array.isArray(ports)
+        ? ports.filter((p): p is number => Number.isInteger(p))
+        : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
 const slotsTaken = () =>
   new Set(
     (

package/lib/ports/ensurePorts.ts

@@ -0,0 +1,138 @@
+import { db } from "@/lib/db";
+import { portBases } from "@/lib/project-config";
+import {
+  projectPathOf,
+  sessionConfig,
+  sessionRunningBrief,
+} from "@/lib/project-config/session";
+import { allocatePorts, sessionPorts } from "./allocatePorts";
+import { findHardcodedPorts, hardcodedNote } from "./findHardcodedPorts";
+import { listListeners } from "./listListeners";
+import { reassignPort } from "./reassignPort";
+import type { PortCheck } from "./types";
+import { describeHolder, judgePort, localPortRows } from "./whoHolds";
+
+export interface PortReport {
+  checks: PortCheck[];
+  ports: Record<string, number>;
+  moved: { name: string; from: number; to: number }[];
+  // Something the caller asked about is taken by someone else.
+  blocked: boolean;
+  text: string;
+}
+
+export interface EnsureDeps {
+  listeners: typeof listListeners;
+  reassign: typeof reassignPort;
+  allocate: typeof allocatePorts;
+}
+
+const realDeps: EnsureDeps = {
+  listeners: listListeners,
+  reassign: reassignPort,
+  allocate: allocatePorts,
+};
+
+async function check(
+  sessionId: string,
+  name: string | null,
+  port: number,
+  deps: EnsureDeps
+): Promise<PortCheck> {
+  const { sessions, devServers } = localPortRows();
+  return judgePort(
+    sessionId,
+    name,
+    port,
+    await deps.listeners(),
+    sessions,
+    devServers
+  );
+}
+
+const say = (c: PortCheck): string => {
+  const label = c.name ? `${c.name}=${c.port}` : String(c.port);
+  if (c.free === null)
+    return `${label}: this machine can't be asked who listens (no lsof).`;
+  if (c.free) return `${label} is free.`;
+  if (c.mine) return `${label} is your own server, already running.`;
+  return `${label} is held by ${describeHolder(c.holder!)} on this machine. Don't wait for it and don't stop it.`;
+};
+
+/**
+ * `aos port [NAME|PORT]`: whether the session's ports are free on this
+ * machine and who holds the ones that aren't. A port of the session's that
+ * someone else holds is moved to a free one, and the lines of its brief that
+ * name it are given again with the new value. Asked about a port that isn't
+ * the session's (one a project hardcodes), it says who holds that one and
+ * how to run on the session's own instead.
+ */
+export async function ensurePorts(
+  sessionId: string,
+  target?: string,
+  deps: EnsureDeps = realDeps
+): Promise<PortReport> {
+  if (!db.prepare(`SELECT 1 FROM sessions WHERE id = ?`).get(sessionId))
+    throw new Error(`No session ${sessionId}`);
+  let ports = sessionPorts(sessionId);
+  if (!ports) {
+    const { config } = sessionConfig(sessionId);
+    ports = (await deps.allocate(sessionId, portBases(config))).ports;
+  }
+  const names = Object.keys(ports);
+  const lines: string[] = [];
+  const checks: PortCheck[] = [];
+  let mineToCheck = names;
+  let blocked = false;
+  if (target) {
+    const asNumber = /^\d+$/.test(target) ? Number(target) : null;
+    const byValue = names.find((n) => ports![n] === asNumber);
+    if (names.includes(target)) mineToCheck = [target];
+    else if (byValue) mineToCheck = [byValue];
+    else if (asNumber !== null) {
+      const foreign = await check(sessionId, null, asNumber, deps);
+      checks.push(foreign);
+      lines.push(say(foreign));
+      if (foreign.free === false && !foreign.mine) blocked = true;
+      mineToCheck = names.slice(0, 1);
+    } else
+      throw new Error(
+        `No port named ${target}: yours are ${names.map((n) => `${n}=${ports![n]}`).join(", ")}`
+      );
+  }
+  const moved: PortReport["moved"] = [];
+  for (const name of mineToCheck) {
+    const c = await check(sessionId, name, ports[name], deps);
+    checks.push(c);
+    if (c.free === false && !c.mine) {
+      lines.push(say(c));
+      const to = await deps.reassign(sessionId, name);
+      moved.push({ name, from: c.port, to });
+      lines.push(`Your ${name} is now ${to}: use it, not ${c.port}.`);
+      blocked = true;
+    } else lines.push(say(c));
+  }
+  ports = sessionPorts(sessionId) ?? ports;
+  if (moved.length) {
+    const fresh = moved.map((m) => String(m.to));
+    const brief = sessionRunningBrief(sessionId)
+      .split("\n")
+      .filter((l) => l.startsWith("- ") && fresh.some((p) => l.includes(p)));
+    if (brief.length) lines.push("With your new port:", ...brief);
+  }
+  const dir = projectPathOf(sessionId);
+  if (dir) {
+    const primary = Object.values(ports)[0];
+    const hard = findHardcodedPorts(
+      dir,
+      sessionConfig(sessionId).config.dev,
+      primary
+    );
+    for (const h of hard) lines.push(hardcodedNote(h));
+  }
+  if (blocked)
+    lines.push(
+      'If you need that exact port, tell the orchestrator (`aos send orchestrator "…"`) rather than waiting.'
+    );
+  return { checks, ports, moved, blocked, text: lines.join("\n") };
+}

package/lib/ports/findHardcodedPorts.ts

@@ -0,0 +1,116 @@
+import fs from "fs";
+import path from "path";
+import type { HardcodedPort } from "./types";
+
+const SCRIPTS = ["dev", "start", "serve", "develop"];
+const VITE_CONFIGS = ["ts", "mts", "js", "mjs", "cjs"].map(
+  (ext) => `vite.config.${ext}`
+);
+
+const FLAG = /(^|\s)(-p|--port)(=|\s+)(\d{2,5})(?=\s|$)/;
+const ENV = /(^|\s)PORT=(\d{2,5})(?=\s)/;
+const SHELL_OPS = /&&|\|\||[;|&<>`]|\$\(/;
+
+// A literal port in a command, and the command with `port` in its place.
+export function literalPort(
+  command: string,
+  port: number
+): { port: number; replaced: string } | null {
+  const flag = FLAG.exec(command);
+  if (flag)
+    return {
+      port: Number(flag[4]),
+      replaced: command.replace(FLAG, `$1$2$3${port}`),
+    };
+  const env = ENV.exec(command);
+  if (env)
+    return {
+      port: Number(env[2]),
+      replaced: command.replace(ENV, `$1PORT=${port}`),
+    };
+  return null;
+}
+
+// An npm script runs with node_modules/.bin on PATH; a shell doesn't.
+function runnable(script: string): string | null {
+  if (SHELL_OPS.test(script)) return null;
+  const words = script.trim().split(/\s+/);
+  const envs: string[] = [];
+  while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]))
+    envs.push(words.shift()!);
+  if (!words.length) return null;
+  return [...envs, "npx", ...words].join(" ");
+}
+
+const readJson = (file: string): unknown => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The ports a project fixes for itself instead of taking the session's:
+ * a literal `-p`/`--port`/`PORT=` in its package.json server scripts or
+ * agentos.json `dev`, and `server.port` in a Vite config. Each comes with
+ * the command to run on `port` instead, when there is one.
+ */
+export function findHardcodedPorts(
+  projectDir: string,
+  dev: string | undefined,
+  port: number
+): HardcodedPort[] {
+  const found: HardcodedPort[] = [];
+  const pkg = readJson(path.join(projectDir, "package.json")) as {
+    scripts?: Record<string, unknown>;
+  } | null;
+  const scripts = pkg?.scripts ?? {};
+  for (const name of SCRIPTS) {
+    const script = scripts[name];
+    if (typeof script !== "string") continue;
+    const hit = literalPort(script, port);
+    if (hit && hit.port !== port)
+      found.push({
+        where: `npm run ${name}`,
+        port: hit.port,
+        fix: runnable(hit.replaced),
+      });
+  }
+  if (dev) {
+    const hit = literalPort(dev, port);
+    if (hit && hit.port !== port)
+      found.push({
+        where: "agentos.json dev",
+        port: hit.port,
+        fix: hit.replaced,
+      });
+  }
+  const usesVite = SCRIPTS.some(
+    (n) =>
+      typeof scripts[n] === "string" && /\bvite\b/.test(scripts[n] as string)
+  );
+  for (const file of VITE_CONFIGS) {
+    let text: string;
+    try {
+      text = fs.readFileSync(path.join(projectDir, file), "utf8");
+    } catch {
+      continue;
+    }
+    const m = /\bport\s*:\s*(\d{2,5})\b/.exec(text);
+    if (m && Number(m[1]) !== port)
+      found.push({
+        where: file,
+        port: Number(m[1]),
+        fix: usesVite ? `npx vite --port ${port} --strictPort` : null,
+      });
+    break;
+  }
+  return found;
+}
+
+export function hardcodedNote(h: HardcodedPort): string {
+  return h.fix
+    ? `\`${h.where}\` hardcodes port ${h.port}: run \`${h.fix}\` instead.`
+    : `\`${h.where}\` hardcodes port ${h.port}: start it on your own port instead.`;
+}

package/lib/ports/index.ts

@@ -0,0 +1,15 @@
+export {
+  MAX_SLOT,
+  allocatePorts,
+  isPortInUse,
+  portsFor,
+  portsTaken,
+  releasePort,
+  releasePorts,
+  sessionPorts,
+} from "./allocatePorts";
+export { listListeners, resetListenersCache } from "./listListeners";
+export { describeHolder, judgePort, localPortRows, whoHolds } from "./whoHolds";
+export { reassignPort } from "./reassignPort";
+export { findHardcodedPorts, hardcodedNote } from "./findHardcodedPorts";
+export type * from "./types";

package/lib/ports/listListeners.ts

@@ -0,0 +1,134 @@
+import { execFile } from "child_process";
+import fs from "fs";
+import { promisify } from "util";
+import { windowsListeners } from "@/lib/windows-ports";
+import type { Listener } from "./types";
+
+const execFileAsync = promisify(execFile);
+
+const TTL_MS = 3000;
+
+/** `lsof -F pcn` output: one listener per (pid, port). */
+export function parseLsofListeners(out: string): Listener[] {
+  const seen = new Set<string>();
+  const found: Listener[] = [];
+  let pid: number | null = null;
+  let command: string | null = null;
+  for (const line of out.split("\n")) {
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      pid = Number(value) || null;
+      command = null;
+    } else if (tag === "c") command = value;
+    else if (tag === "n") {
+      const port = Number(value.slice(value.lastIndexOf(":") + 1));
+      if (!Number.isInteger(port) || port <= 0) continue;
+      const key = `${pid}:${port}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push({ port, pid, command, cwd: null });
+    }
+  }
+  return found;
+}
+
+/** `lsof -a -d cwd -Fpn` output as pid → cwd. */
+export function parseLsofCwds(out: string): Map<number, string> {
+  const cwds = new Map<number, string>();
+  let pid: number | null = null;
+  for (const line of out.split("\n")) {
+    if (line[0] === "p") pid = Number(line.slice(1)) || null;
+    else if (line[0] === "n" && pid) cwds.set(pid, line.slice(1));
+  }
+  return cwds;
+}
+
+export async function cwdsOf(pids: number[]): Promise<Map<number, string>> {
+  if (!pids.length) return new Map();
+  if (process.platform === "linux") {
+    const pairs = await Promise.all(
+      pids.map(async (pid) => {
+        try {
+          return [pid, await fs.promises.readlink(`/proc/${pid}/cwd`)] as const;
+        } catch {
+          return null;
+        }
+      })
+    );
+    return new Map(pairs.filter((p) => p !== null));
+  }
+  try {
+    const { stdout } = await execFileAsync(
+      "lsof",
+      ["-a", "-d", "cwd", "-p", pids.join(","), "-Fpn"],
+      { timeout: 5000 }
+    );
+    return parseLsofCwds(stdout);
+  } catch (error) {
+    const out = (error as { stdout?: string }).stdout;
+    return out ? parseLsofCwds(out) : new Map();
+  }
+}
+
+async function lsofListeners(): Promise<Listener[] | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "lsof",
+      ["-nP", "-iTCP", "-sTCP:LISTEN", "-F", "pcn"],
+      { timeout: 5000, maxBuffer: 8 << 20 }
+    );
+    return parseLsofListeners(stdout);
+  } catch (error) {
+    // lsof exits 1 when nothing listens; a missing lsof can't answer.
+    const e = error as { code?: unknown; stdout?: string };
+    if (e.code === "ENOENT") return null;
+    return parseLsofListeners(e.stdout ?? "");
+  }
+}
+
+let cache: { at: number; listeners: Listener[] | null } | undefined;
+
+/**
+ * Every TCP listener in this machine's namespace with its pid, command and
+ * cwd, and Windows' under WSL 2. Null when this machine can't be asked.
+ */
+export async function listListeners(
+  now = Date.now()
+): Promise<Listener[] | null> {
+  if (cache && now - cache.at < TTL_MS) return cache.listeners;
+  const local = await lsofListeners();
+  let listeners: Listener[] | null = local;
+  if (local) {
+    const pids = [
+      ...new Set(local.map((l) => l.pid).filter((p) => p !== null)),
+    ];
+    const cwds = await cwdsOf(pids as number[]);
+    listeners = local.map((l) => ({
+      ...l,
+      cwd: (l.pid && cwds.get(l.pid)) || null,
+    }));
+  }
+  const windows = await windowsListeners();
+  if (windows) {
+    const have = new Set((listeners ?? []).map((l) => l.port));
+    listeners = [
+      ...(listeners ?? []),
+      ...[...windows]
+        .filter(([port]) => !have.has(port))
+        .map(([port, pid]) => ({
+          port,
+          pid,
+          command: null,
+          cwd: null,
+          windows: true,
+        })),
+    ];
+  }
+  cache = { at: now, listeners };
+  return listeners;
+}
+
+export function resetListenersCache() {
+  cache = undefined;
+}

package/lib/ports/reassignPort.ts

@@ -0,0 +1,45 @@
+import { db } from "@/lib/db";
+import { forbiddenPorts } from "@/lib/dev-instance/pickPort";
+import { isPortInUse, portsTaken, sessionPorts } from "./allocatePorts";
+
+const SEARCH = 1000;
+
+// The live AgentOS server's ports: its own, and the ones its env names.
+const livePorts = () => {
+  const banned = forbiddenPorts(process.env, null);
+  const own = Number(process.env.PORT);
+  if (Number.isInteger(own) && own > 0) banned.add(own);
+  return banned;
+};
+
+/**
+ * Moves one of the session's ports to the next free one above it: not held
+ * by another session or the Dev Servers panel, not listening, not AgentOS's
+ * own. The slot stays, so the ports still go back when the session ends.
+ * The claim rechecks under the write lock, like allocatePorts.
+ */
+export async function reassignPort(
+  sessionId: string,
+  name: string,
+  inUse: (port: number) => Promise<boolean> = isPortInUse,
+  banned: Set<number> = livePorts()
+): Promise<number> {
+  const ports = sessionPorts(sessionId);
+  const from = ports?.[name];
+  if (!ports || from === undefined)
+    throw new Error(`This session has no port named ${name}`);
+  const claim = db.transaction((port: number) => {
+    if (portsTaken(sessionId).has(port)) return false;
+    const next = { ...ports, [name]: port };
+    db.prepare(
+      `UPDATE sessions SET ports = ?, dev_server_port = ? WHERE id = ?`
+    ).run(JSON.stringify(next), Object.values(next)[0] ?? null, sessionId);
+    return true;
+  });
+  for (let port = from + 1; port <= Math.min(65535, from + SEARCH); port++) {
+    if (banned.has(port) || portsTaken(sessionId).has(port)) continue;
+    if (await inUse(port)) continue;
+    if (claim.immediate(port)) return port;
+  }
+  throw new Error(`No free port in the ${SEARCH} above ${from}`);
+}

package/lib/ports/types.ts

@@ -0,0 +1,62 @@
+// A TCP listener in this machine's network namespace. Under WSL 2 that
+// includes Windows, whose processes have no cwd we can read.
+export interface Listener {
+  port: number;
+  pid: number | null;
+  command: string | null;
+  cwd: string | null;
+  windows?: boolean;
+}
+
+export type Holder =
+  | {
+      kind: "session";
+      sessionId: string;
+      name: string;
+      project: string | null;
+      pid: number | null;
+      listening: boolean;
+    }
+  | { kind: "dev-server"; id: string; name: string; pid: number | null }
+  | {
+      kind: "outside";
+      pid: number | null;
+      command: string | null;
+      cwd: string | null;
+    }
+  | { kind: "windows"; pid: number | null };
+
+// What a session could be told about one of its ports, or one it wants.
+export interface PortCheck {
+  name: string | null;
+  port: number;
+  // null: this machine can't be asked (no lsof).
+  free: boolean | null;
+  holder: Holder | null;
+  // The holder is the asking session itself.
+  mine: boolean;
+}
+
+export interface SessionPortRow {
+  id: string;
+  name: string;
+  project: string | null;
+  worktree: string | null;
+  ports: Record<string, number> | null;
+  devServerPort: number | null;
+}
+
+export interface DevServerPortRow {
+  id: string;
+  name: string;
+  pid: number | null;
+  ports: number[];
+}
+
+export interface HardcodedPort {
+  // Where it is: "package.json dev", "agentos.json dev", "vite.config.ts".
+  where: string;
+  port: number;
+  // The command with the session's port in place, when one can be given.
+  fix: string | null;
+}