@saadnvd1/agent-os 0.3.723 → 0.3.731

package/lib/export/turn.ts

@@ -0,0 +1,48 @@
+/**
+ * One turn as Markdown for the clipboard: the same model and serializer as a
+ * session export (build.ts, markdown.ts), redacted for secrets, cut to one turn.
+ */
+
+import type { ChatItem } from "../chat/events";
+import type { ShareContext } from "../share/redact";
+import { BadShare } from "../share/service";
+import { buildDoc, type BuildInput, type ExportTurn } from "./build";
+import { itemMd } from "./markdown";
+import { groupTurns } from "./turns";
+
+export interface TurnCopy {
+  /** Reasoning, tool calls and their output, errors and the answer, in order. */
+  full: string;
+  /** The turn's last agent message. */
+  response: string;
+}
+
+/** The turn body: every item after the message that began it. */
+export function turnMarkdown(turn: ExportTurn): TurnCopy {
+  // The first item is the message that began the turn: already on screen.
+  const body = turn.userId ? turn.items.slice(1) : turn.items;
+  const parts = body.map(itemMd);
+  if (turn.ended) parts.push(`*Turn ended early: ${turn.ended}*`);
+  if (turn.interrupted) parts.push("*Turn stopped before it finished*");
+  const last = [...turn.items].reverse().find((i) => i.kind === "assistant");
+  return { full: parts.join("\n\n"), response: last?.text ?? "" };
+}
+
+/** The turn that begins with message `startId`. 404 as BadShare. */
+export function copyTurn(
+  items: ChatItem[],
+  startId: string,
+  ctx: ShareContext,
+  meta: BuildInput["meta"]
+): TurnCopy {
+  const turn = groupTurns(items).find((t) => t.items[0]?.id === startId);
+  if (!turn) throw new BadShare("Turn not found", 404);
+  const doc = buildDoc({
+    items: turn.items,
+    meta,
+    mode: "full",
+    redact: "secrets",
+    ctx,
+  });
+  return turnMarkdown(doc.turns[0]);
+}

package/lib/health/config.ts

@@ -8,6 +8,7 @@ export const HEALTH_DEFAULTS = {
   loadRedMinutes: 10,
   queueHeldMinutes: 60,
   bgQuietMinutes: 20,
+  portWaitMinutes: 10,
   pieceDupOverlap: 0.4,
   restartsMax: 2,
   restartsWindowMinutes: 60,
@@ -33,6 +34,7 @@ export const HEALTH_LABELS: Record<HealthKey, string> = {
   loadRedMinutes: "Machine load red for (minutes)",
   queueHeldMinutes: "Queued task held for (minutes)",
   bgQuietMinutes: "Background job quiet for (minutes)",
+  portWaitMinutes: "Waiting on a port someone else holds for (minutes)",
   pieceDupOverlap: "Plan piece matches merged work (0 to 1 overlap)",
   restartsMax: "Server restarts allowed per window",
   restartsWindowMinutes: "Restart window (minutes)",

package/lib/health/env/classes.ts

@@ -11,6 +11,19 @@ const USE_ENV =
   "run it through the repo's own environment (`uv run …` when it has a pyproject.toml or uv.lock, else its .venv/bin/python), not a bare `python3`";
 
 export const ENV_CLASSES: readonly EnvClass[] = [
+  {
+    id: "port-in-use",
+    label: "Port taken by another process",
+    scope: "shell",
+    match: [
+      /\bEADDRINUSE\b/,
+      /^(?:\S+Error: )?(?:\[Errno \d+\] )?Address already in use\b/i,
+      /^(?:Error: )?Port \d+ is already in use\b/,
+      /^Something is already running on port \d+/,
+      /\bport is already allocated\b/,
+    ],
+    fix: "A port this command needs is taken by another process on this machine. Don't wait for it and don't stop it: run `aos port <that port>` to see who holds it and get a free one, then start on that one (pass it with --port or PORT=). If you need that exact port, tell the orchestrator.",
+  },
   {
     id: "python-version",
     label: "Python too old for the code",
@@ -116,4 +129,4 @@ export const SHELL_TOOLS = new Set([
 // Commands that show text somebody else wrote: an error in their output is
 // in the data, not something this run hit.
 export const READERS =
-  /^(?:grep|egrep|rg|ag|cat|head|tail|less|more|sed\s+-n|awk|jq|sqlite3|journalctl|echo|printf|aos\s+(?:history|inbox)|sm\s+logs|gh\s+run\s+view|git\s+(?:log|show|diff|grep))\b/;
+  /^(?:grep|egrep|rg|ag|cat|head|tail|less|more|ls|wc|sed\s+-n|awk|jq|sqlite3|journalctl|echo|printf|aos\s+(?:history|inbox)|sm\s+logs|gh\s+run\s+view|git\s+(?:log|show|diff|grep))\b/;

package/lib/health/port-wait-tick.ts

@@ -0,0 +1,222 @@
+/**
+ * The I/O half of port-wait (port-wait.ts decides): once a minute, find the
+ * sessions' shell loops that have waited on a port for long enough, ask who
+ * holds that port, and when it's someone else tell the agent and its
+ * orchestrator once per holder. Nothing is stopped: a sleeping loop costs
+ * nothing, and the agent ends its own job. Each machine judges its own
+ * sessions, since ports only meet inside one machine's network.
+ */
+
+import { execFile } from "child_process";
+import { sendMessage } from "../bus";
+import { db } from "../db";
+import { readSnapshot } from "../load/usage";
+import { queueEventOnce } from "../orchestrator/events";
+import { untrusted } from "../orchestrator/untrusted";
+import {
+  describeHolder,
+  judgePort,
+  listListeners,
+  localPortRows,
+  sessionPorts,
+  type Holder,
+} from "../ports";
+import { cwdsOf } from "../ports/listListeners";
+import type { HealthConfig } from "./config";
+import {
+  findPortWaits,
+  parsePsArgs,
+  portWaitLine,
+  portWaitNote,
+  waitedPorts,
+  type ArgsProc,
+  type WaitSession,
+} from "./port-wait";
+import { close, recordTrips } from "./store";
+import { MIN, type Trip } from "./types";
+
+export interface PortWaitDeps {
+  procs: () => Promise<ArgsProc[] | null>;
+  panes: () => Promise<{ tmux: string; pid: number }[]>;
+  cwds: (pids: number[]) => Promise<Map<number, string>>;
+  listeners: typeof listListeners;
+  portRows: typeof localPortRows;
+  sessions: () => WaitSession[];
+  tell: (sessionId: string, body: string) => Promise<void>;
+  event: (
+    workspaceId: string,
+    key: string,
+    subject: string,
+    line: string,
+    now: number
+  ) => void;
+  record: (trip: Trip, now: number) => void;
+}
+
+const readArgs = (): Promise<ArgsProc[] | null> =>
+  new Promise((resolve) =>
+    execFile(
+      "ps",
+      ["-Ao", "pid=,ppid=,etime=,args="],
+      { timeout: 5000, maxBuffer: 16 << 20 },
+      (err, out) => {
+        const rows = err ? [] : parsePsArgs(out);
+        resolve(rows.length ? rows : null);
+      }
+    )
+  );
+
+function localSessions(): WaitSession[] {
+  return (
+    db
+      .prepare(
+        `SELECT s.id, s.name, p.workspace_id, s.tmux_name, s.worktree_path
+         FROM sessions s LEFT JOIN projects p ON p.id = s.project_id
+         WHERE s.archived_at IS NULL AND (s.host_id IS NULL OR s.host_id = 'local')`
+      )
+      .all() as {
+      id: string;
+      name: string;
+      workspace_id: string | null;
+      tmux_name: string | null;
+      worktree_path: string | null;
+    }[]
+  ).map((r) => ({
+    id: r.id,
+    name: r.name,
+    workspaceId: r.workspace_id,
+    tmuxName: r.tmux_name,
+    worktree: r.worktree_path,
+  }));
+}
+
+export const realPortWait: PortWaitDeps = {
+  procs: readArgs,
+  panes: async () => (await readSnapshot()).panes,
+  cwds: cwdsOf,
+  listeners: listListeners,
+  portRows: localPortRows,
+  sessions: localSessions,
+  tell: async (sessionId, body) => {
+    await sendMessage({
+      fromId: null,
+      to: sessionId,
+      body,
+      fromLabel: "AgentOS health",
+      origin: { kind: "system", label: "Health", body },
+    });
+  },
+  event: (ws, key, subject, line, now) => {
+    queueEventOnce(ws, key, subject, line, now);
+  },
+  record: (trip, now) => {
+    const { opened } = recordTrips([trip], [], now);
+    // History only: the agent and orchestrator are told directly.
+    for (const row of opened) close(row.id, "told", now);
+  },
+};
+
+const holderKey = (h: Holder) =>
+  h.kind === "session"
+    ? `s:${h.sessionId}`
+    : h.kind === "dev-server"
+      ? `d:${h.id}`
+      : `${h.kind}:${h.pid}`;
+
+// session:port -> the holder it was told about. A wait that ends, or a new
+// holder, re-arms it.
+const told = new Map<string, string>();
+let running = false;
+
+export function resetPortWait(): void {
+  told.clear();
+  running = false;
+}
+
+export async function portWaitTick(
+  now: number,
+  c: HealthConfig,
+  deps: PortWaitDeps = realPortWait
+): Promise<void> {
+  const minMs = c.portWaitMinutes * MIN;
+  if (!minMs || running) return;
+  running = true;
+  try {
+    const procs = await deps.procs();
+    if (!procs) return;
+    const old = procs.filter(
+      (p) => p.ageMs >= minMs && waitedPorts(p.args).length
+    );
+    if (!old.length) {
+      told.clear();
+      return;
+    }
+    const [panes, cwds] = await Promise.all([
+      deps.panes(),
+      deps.cwds(old.map((p) => p.pid)),
+    ]);
+    const waits = findPortWaits(procs, deps.sessions(), panes, cwds, minMs);
+    const live = new Set(waits.map((w) => `${w.sessionId}:${w.port}`));
+    for (const k of told.keys()) if (!live.has(k)) told.delete(k);
+    if (!waits.length) return;
+    const listeners = await deps.listeners();
+    if (!listeners) return;
+    const { sessions, devServers } = deps.portRows();
+    for (const w of waits) {
+      const check = judgePort(
+        w.sessionId,
+        null,
+        w.port,
+        listeners,
+        sessions,
+        devServers
+      );
+      if (!check.holder || check.mine) continue;
+      const key = `${w.sessionId}:${w.port}`;
+      const who = holderKey(check.holder);
+      if (told.get(key) === who) continue;
+      told.set(key, who);
+      const holder = describeHolder(check.holder);
+      const line = portWaitLine(w, holder);
+      try {
+        deps.record(
+          {
+            check: "port-wait",
+            subject: key,
+            severity: "warn",
+            line,
+            detail: {
+              sessionId: w.sessionId,
+              port: w.port,
+              pid: w.pid,
+              holder: check.holder,
+            },
+            workspaceId: w.workspaceId,
+          },
+          now
+        );
+      } catch (error) {
+        console.error("[health] port-wait record:", error);
+      }
+      if (w.workspaceId)
+        deps.event(
+          w.workspaceId,
+          `port-wait:${key}:${who}`,
+          w.sessionId,
+          // Session names and commands are agents' own text.
+          `Health (tasks): ${untrusted("health detector", line)}`,
+          now
+        );
+      try {
+        await deps.tell(
+          w.sessionId,
+          portWaitNote(w, holder, sessionPorts(w.sessionId))
+        );
+      } catch (error) {
+        console.error("[health] port-wait note:", error);
+      }
+    }
+  } finally {
+    running = false;
+  }
+}

package/lib/health/port-wait.ts

@@ -0,0 +1,160 @@
+/**
+ * port-wait, the deciding half (port-wait-tick.ts does the I/O): a shell
+ * loop that waits on a port someone else holds can't end, since that holder
+ * won't free it for the agent. Sleeping loops use no CPU, so bg-spin never
+ * sees them; this names the holder and the way out instead.
+ */
+
+import { claimTrees } from "../load/usage";
+import { MIN } from "./types";
+
+export const PORT_WAIT_MIN_MS = 10 * MIN;
+
+const LOOP =
+  /\b(?:until|while)\b[\s\S]*?\b(?:curl|wget|nc|lsof|ss|netstat|http)\b|\bwait-on\b|\bwait-port\b/;
+const PORT_REFS = [
+  /(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]):(\d{2,5})\b/g,
+  /\btcp:(\d{2,5})\b/g,
+  /\s-i\s*:(\d{2,5})\b/g,
+  /\b[sd]port\s*=\s*:(\d{2,5})\b/g,
+  /\bnc\s+(?:-\w+\s+)*\S+\s+(\d{2,5})\b/g,
+];
+
+// The ports a command waits on, when it is a wait loop at all.
+export function waitedPorts(args: string): number[] {
+  if (!LOOP.test(args)) return [];
+  const ports = new Set<number>();
+  for (const re of PORT_REFS)
+    for (const m of args.matchAll(re)) {
+      const p = Number(m[1]);
+      if (p > 0 && p <= 65535) ports.add(p);
+    }
+  return [...ports];
+}
+
+// ps's etime, `[[dd-]hh:]mm:ss`, in seconds.
+export function parseEtime(s: string): number | null {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(s.trim());
+  if (!m) return null;
+  const [, d, h, mm, ss] = m;
+  return (
+    ((Number(d ?? 0) * 24 + Number(h ?? 0)) * 60 + Number(mm)) * 60 + Number(ss)
+  );
+}
+
+export interface ArgsProc {
+  pid: number;
+  ppid: number;
+  ageMs: number;
+  args: string;
+}
+
+// `ps -Ao pid=,ppid=,etime=,args=`: args is last and holds spaces.
+export function parsePsArgs(out: string): ArgsProc[] {
+  const rows: ArgsProc[] = [];
+  for (const line of out.split("\n")) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const age = parseEtime(m[3]);
+    if (age === null) continue;
+    rows.push({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      ageMs: age * 1000,
+      args: m[4],
+    });
+  }
+  return rows;
+}
+
+export interface WaitSession {
+  id: string;
+  name: string;
+  workspaceId: string | null;
+  tmuxName: string | null;
+  worktree: string | null;
+}
+
+export interface PortWait {
+  sessionId: string;
+  sessionName: string;
+  workspaceId: string | null;
+  pid: number;
+  port: number;
+  args: string;
+  waitedMs: number;
+}
+
+const inside = (cwd: string, dir: string) =>
+  cwd === dir || cwd.startsWith(`${dir.replace(/\/$/, "")}/`);
+
+/**
+ * Each session's waits on a port for at least `minMs`, one per session and
+ * port (a loop's wrapper shells are folded into its oldest). A process is
+ * the session's when it runs in its worktree, or under its tmux pane.
+ */
+export function findPortWaits(
+  procs: ArgsProc[],
+  sessions: WaitSession[],
+  panes: { tmux: string; pid: number }[],
+  cwds: Map<number, string>,
+  minMs: number
+): PortWait[] {
+  const byTmux = new Map(
+    sessions.filter((s) => s.tmuxName).map((s) => [s.tmuxName!, s])
+  );
+  const roots = panes
+    .filter((p) => byTmux.has(p.tmux))
+    .map((p) => ({ key: byTmux.get(p.tmux)!.id, pid: p.pid }));
+  const owner = claimTrees(
+    procs.map((p) => ({ pid: p.pid, ppid: p.ppid, pcpu: 0, rss: 0 })),
+    roots
+  );
+  const out = new Map<string, PortWait>();
+  for (const p of procs) {
+    if (p.ageMs < minMs) continue;
+    const ports = waitedPorts(p.args);
+    if (!ports.length) continue;
+    const cwd = cwds.get(p.pid);
+    const s =
+      (cwd && sessions.find((x) => x.worktree && inside(cwd, x.worktree))) ||
+      sessions.find((x) => x.id === owner.get(p.pid));
+    if (!s) continue;
+    for (const port of ports) {
+      const key = `${s.id}:${port}`;
+      const had = out.get(key);
+      if (had && had.waitedMs >= p.ageMs) continue;
+      out.set(key, {
+        sessionId: s.id,
+        sessionName: s.name,
+        workspaceId: s.workspaceId,
+        pid: p.pid,
+        port,
+        args: p.args,
+        waitedMs: p.ageMs,
+      });
+    }
+  }
+  return [...out.values()];
+}
+
+const short = (args: string) =>
+  args.length > 120 ? `${args.slice(0, 117)}...` : args;
+
+export function portWaitNote(
+  w: PortWait,
+  holder: string,
+  own: Record<string, number> | null
+): string {
+  const mins = Math.round(w.waitedMs / MIN);
+  const mine =
+    own && Object.keys(own).length
+      ? ` Your ports are ${Object.entries(own)
+          .map(([n, p]) => `${n}=${p}`)
+          .join(", ")}.`
+      : "";
+  return `You've waited ${mins} min for port ${w.port} (pid ${w.pid}: \`${short(w.args)}\`). It's held by ${holder}, which isn't yours and won't free it for you, so that wait can't end. Stop it (\`kill ${w.pid}\`, your own job), don't stop the holder, and run \`aos port ${w.port}\` for a free port of your own to start on.${mine} If you need ${w.port} itself, tell the orchestrator.`;
+}
+
+export const portWaitLine = (w: PortWait, holder: string) =>
+  `${w.sessionName} has waited ${Math.round(w.waitedMs / MIN)} min for port ${w.port}, held by ${holder}. It was told to move to its own port.`;

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/loops/analyse.ts

@@ -0,0 +1,46 @@
+import type { RunUsage } from "../usage/check-runs";
+import { runClaude, type ClaudeRunner } from "../orchestrator/claude-cli";
+import { checkout, removeCheckout } from "../orchestrator/repo";
+import {
+  ANALYSIS_SCHEMA,
+  ANALYST_SYSTEM,
+  analystPrompt,
+  toAnalysis,
+  type AnalystInput,
+} from "./analyst-prompt";
+import type { Analysis } from "./types";
+
+// The model role the analyst runs on (BR02-17's "analyze"); the role's
+// model is Settings' and the workspace's to pick, never the task's.
+export const ANALYST_ROLE = "analyze" as const;
+
+// One stateless run on a throwaway checkout of the snapshot: Read, Grep and
+// Glob inside it, nothing else. Its cost comes back with the analysis.
+export async function analyse(input: {
+  repo: string;
+  sha: string;
+  workspaceId: string | null;
+  prompt: AnalystInput;
+  claude?: ClaudeRunner;
+}): Promise<{ analysis: Analysis; costUsd: number }> {
+  const dir = await checkout(input.repo, input.sha);
+  let cost = 0;
+  try {
+    const answer = await (input.claude ?? runClaude)({
+      cwd: dir,
+      system: ANALYST_SYSTEM,
+      prompt: analystPrompt(input.prompt),
+      schema: ANALYSIS_SCHEMA,
+      tools: ["Read", "Grep", "Glob"],
+      allow: [`Read(/${dir}/**)`, `Grep(/${dir}/**)`, `Glob(/${dir}/**)`],
+      onUsage: (u: RunUsage) => {
+        cost += u.costUsd;
+      },
+      role: ANALYST_ROLE,
+      workspaceId: input.workspaceId,
+    });
+    return { analysis: toAnalysis(answer), costUsd: cost };
+  } finally {
+    await removeCheckout(input.repo, dir);
+  }
+}