@downcity/agent 1.1.8 → 1.1.11

package/src/host/runtime/CityRegistry.ts

@@ -1,256 +0,0 @@
-/**
- * CityRegistry：city 后台维护的 agent registry（`~/.downcity/main/agents.json`）。
- *
- * 关键点（中文）
- * - registry 只维护“city 认知到的 agent 项目列表”，用于统一观测与批量管理。
- * - registry 不承载实时健康检查：status/list 会读取每个项目的 daemon pid 并判活。
- * - agent daemon 启动成功后必须登记到 city 后台（强约束）。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import type {
-  ManagedAgentRegistryEntry,
-  ManagedAgentRegistryV1,
-} from "@/shared/types/Platform.js";
-import { getManagedAgentRegistryPath, getCityRuntimeDirPath } from "./CityPaths.js";
-import { isCityRunning } from "./CityRuntime.js";
-
-const CONSOLE_DIR = getCityRuntimeDirPath();
-const MANAGED_AGENTS_FILE = getManagedAgentRegistryPath();
-
-function buildEmptyRegistry(): ManagedAgentRegistryV1 {
-  return {
-    v: 1,
-    updatedAt: new Date().toISOString(),
-    agents: [],
-  };
-}
-
-function normalizeProjectRoot(projectRoot: string): string {
-  const resolved = path.resolve(String(projectRoot || "").trim());
-  if (!resolved) throw new Error("projectRoot is required");
-  return resolved;
-}
-
-function normalizePid(pid: number): number {
-  if (!Number.isFinite(pid) || Number.isNaN(pid) || !Number.isInteger(pid) || pid < 1) {
-    throw new Error(`Invalid pid: ${pid}`);
-  }
-  return pid;
-}
-
-function normalizeIsoTime(input: string | undefined): string {
-  const value = String(input || "").trim();
-  if (!value) return new Date().toISOString();
-  const ms = Date.parse(value);
-  if (!Number.isFinite(ms)) return new Date().toISOString();
-  return new Date(ms).toISOString();
-}
-
-function normalizeRegistryEntry(
-  entry: Partial<ManagedAgentRegistryEntry>,
-): ManagedAgentRegistryEntry | null {
-  try {
-    const projectRoot = normalizeProjectRoot(String(entry.projectRoot || ""));
-    const pid = normalizePid(Number(entry.pid));
-    const startedAt = normalizeIsoTime(
-      typeof entry.startedAt === "string" ? entry.startedAt : undefined,
-    );
-    const updatedAt = normalizeIsoTime(
-      typeof entry.updatedAt === "string" ? entry.updatedAt : undefined,
-    );
-    return {
-      projectRoot,
-      pid,
-      startedAt,
-      updatedAt,
-      status:
-        entry.status === "stopped"
-          ? "stopped"
-          : "running",
-      stoppedAt:
-        entry.status === "stopped"
-          ? normalizeIsoTime(
-              typeof entry.stoppedAt === "string"
-                ? entry.stoppedAt
-                : undefined,
-            )
-          : undefined,
-    };
-  } catch {
-    return null;
-  }
-}
-
-function normalizeRegistry(
-  value: Partial<ManagedAgentRegistryV1> | null | undefined,
-): ManagedAgentRegistryV1 {
-  if (!value || typeof value !== "object") return buildEmptyRegistry();
-  const source = Array.isArray(value.agents) ? value.agents : [];
-  const normalizedAgents: ManagedAgentRegistryEntry[] = [];
-  for (const item of source) {
-    if (!item || typeof item !== "object") continue;
-    const normalized = normalizeRegistryEntry(item as ManagedAgentRegistryEntry);
-    if (!normalized) continue;
-    const existingIndex = normalizedAgents.findIndex(
-      (entry) => entry.projectRoot === normalized.projectRoot,
-    );
-    if (existingIndex >= 0) {
-      normalizedAgents[existingIndex] = normalized;
-      continue;
-    }
-    normalizedAgents.push(normalized);
-  }
-  return {
-    v: 1,
-    updatedAt: normalizeIsoTime(
-      typeof value.updatedAt === "string" ? value.updatedAt : undefined,
-    ),
-    agents: normalizedAgents.sort((a, b) =>
-      a.projectRoot.localeCompare(b.projectRoot),
-    ),
-  };
-}
-
-async function writeManagedAgentRegistry(
-  registry: ManagedAgentRegistryV1,
-): Promise<void> {
-  await fs.ensureDir(CONSOLE_DIR);
-  await fs.writeJson(MANAGED_AGENTS_FILE, normalizeRegistry(registry), {
-    spaces: 2,
-  });
-}
-
-/**
- * 确保 city agent registry 文件存在。
- *
- * 关键点（中文）
- * - 空 city 运行态也应拥有显式的空 registry，避免 Console 将“尚未启动任何 agent”误判为异常。
- * - 若文件已存在则不覆盖，保持历史记录不丢失。
- */
-export async function ensureManagedAgentRegistry(): Promise<void> {
-  await fs.ensureDir(CONSOLE_DIR);
-  if (await fs.pathExists(MANAGED_AGENTS_FILE)) {
-    return;
-  }
-  await writeManagedAgentRegistry(buildEmptyRegistry());
-}
-
-/**
- * 获取 city agent registry 文件路径。
- */
-export function getManagedAgentsRegistryPath(): string {
-  return MANAGED_AGENTS_FILE;
-}
-
-/**
- * 读取 city agent registry（容错）。
- *
- * 关键点（中文）
- * - 文件不存在或损坏时返回空 registry，避免影响主流程。
- */
-export async function readManagedAgentRegistry(): Promise<ManagedAgentRegistryV1> {
-  try {
-    if (!(await fs.pathExists(MANAGED_AGENTS_FILE))) {
-      return buildEmptyRegistry();
-    }
-    const raw = (await fs.readJson(MANAGED_AGENTS_FILE)) as Partial<ManagedAgentRegistryV1>;
-    return normalizeRegistry(raw);
-  } catch {
-    return buildEmptyRegistry();
-  }
-}
-
-/**
- * 列出 city registry 中记录的 agent（按 projectRoot 排序）。
- */
-export async function listManagedAgentEntries(): Promise<ManagedAgentRegistryEntry[]> {
-  const registry = await readManagedAgentRegistry();
-  return [...registry.agents].sort((a, b) => a.projectRoot.localeCompare(b.projectRoot));
-}
-
-/**
- * 新增或更新一条 city agent 记录。
- */
-export async function upsertManagedAgentEntry(input: {
-  projectRoot: string;
-  pid: number;
-  startedAt?: string;
-  status?: "running" | "stopped";
-  stoppedAt?: string;
-}): Promise<void> {
-  // 关键点（中文）：agent 必须登记到 city 后台才“有效”，因此 city 未启动时拒绝写入 registry。
-  if (!(await isCityRunning())) {
-    throw new Error("city runtime is not running");
-  }
-
-  const projectRoot = normalizeProjectRoot(input.projectRoot);
-  const pid = normalizePid(input.pid);
-  const nowIso = new Date().toISOString();
-
-  const registry = await readManagedAgentRegistry();
-  const index = registry.agents.findIndex((entry) => entry.projectRoot === projectRoot);
-  if (index >= 0) {
-    const existing = registry.agents[index];
-    registry.agents[index] = {
-      projectRoot,
-      pid,
-      startedAt: normalizeIsoTime(existing.startedAt || input.startedAt),
-      updatedAt: nowIso,
-      status: input.status === "stopped" ? "stopped" : "running",
-      stoppedAt:
-        input.status === "stopped"
-          ? normalizeIsoTime(input.stoppedAt || nowIso)
-          : undefined,
-    };
-  } else {
-    registry.agents.push({
-      projectRoot,
-      pid,
-      startedAt: normalizeIsoTime(input.startedAt),
-      updatedAt: nowIso,
-      status: input.status === "stopped" ? "stopped" : "running",
-      stoppedAt:
-        input.status === "stopped"
-          ? normalizeIsoTime(input.stoppedAt || nowIso)
-          : undefined,
-    });
-  }
-
-  registry.updatedAt = nowIso;
-  await writeManagedAgentRegistry(registry);
-}
-
-/**
- * 标记 agent 为 stopped（保留历史记录，不删除）。
- */
-export async function markManagedAgentStopped(projectRoot: string): Promise<void> {
-  const key = normalizeProjectRoot(projectRoot);
-  const registry = await readManagedAgentRegistry();
-  const index = registry.agents.findIndex((entry) => entry.projectRoot === key);
-  if (index < 0) return;
-  const nowIso = new Date().toISOString();
-  const current = registry.agents[index];
-  registry.agents[index] = {
-    ...current,
-    status: "stopped",
-    stoppedAt: nowIso,
-    updatedAt: nowIso,
-  };
-  registry.updatedAt = nowIso;
-  await writeManagedAgentRegistry(registry);
-}
-
-/**
- * 按 projectRoot 移除一条 agent 记录。
- */
-export async function removeManagedAgentEntry(projectRoot: string): Promise<void> {
-  const key = normalizeProjectRoot(projectRoot);
-  const registry = await readManagedAgentRegistry();
-  const nextAgents = registry.agents.filter((entry) => entry.projectRoot !== key);
-  if (nextAgents.length === registry.agents.length) return;
-  registry.agents = nextAgents;
-  registry.updatedAt = new Date().toISOString();
-  await writeManagedAgentRegistry(registry);
-}

package/src/host/runtime/CityRuntime.ts

@@ -1,45 +0,0 @@
-/**
- * CityRuntime：city 后台进程状态工具。
- *
- * 关键点（中文）
- * - city 后台负责统一管理/观测多个 agent daemon。
- * - 这里处理的是 city 后台自身的 pid 与判活，不涉及 control plane 进程。
- * - agent daemon 启动前必须确保 city 后台已启动（强约束）。
- */
-
-import fs from "fs-extra";
-import { getCityPidPath } from "./CityPaths.js";
-
-/**
- * 读取 city 后台 pid（读取失败或内容非法返回 null）。
- */
-export async function readCityPid(): Promise<number | null> {
-  try {
-    const raw = await fs.readFile(getCityPidPath(), "utf-8");
-    const pid = Number.parseInt(String(raw).trim(), 10);
-    return Number.isFinite(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 判断 city 后台进程是否存活。
- */
-export function isCityProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 判断 city 后台是否在运行（基于 pid file + 判活）。
- */
-export async function isCityRunning(): Promise<boolean> {
-  const pid = await readCityPid();
-  if (!pid) return false;
-  return isCityProcessAlive(pid);
-}

package/src/host/runtime/ProcessSweep.ts

@@ -1,239 +0,0 @@
-/**
- * 孤儿进程清扫工具。
- *
- * 关键点（中文）
- * - 处理“pid 文件不存在，但旧的 detached 进程还活着”的场景。
- * - 仅匹配 Downcity CLI 自己拉起的 `run` / `console run` / `agent start --foreground true`。
- * - 作为 stop/start 的兜底清理层，避免旧版本进程占住端口却无法被当前 pid 文件追踪。
- * - `run` 指 city 后台，`console run` 指 control plane 命令，二者需要明确区分。
- */
-
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFileCb);
-
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function normalizeCommand(command: string): string {
-  return String(command || "").replace(/\s+/g, " ").trim();
-}
-
-/**
- * 构建 detached 进程停机时的信号目标。
- *
- * 关键点（中文）
- * - POSIX 下 `detached: true` 会让子进程成为新的进程组 leader。
- * - `-pid` 表示向整个进程组发信号，可覆盖 ACP、shell、watcher 等孙进程。
- * - Windows 不支持负 pid 进程组语义，只能回退到单 pid。
- */
-export function buildDetachedProcessSignalTargets(pid: number): number[] {
-  if (!Number.isInteger(pid) || pid <= 0) return [];
-  if (process.platform === "win32") return [pid];
-  return [-pid, pid];
-}
-
-/**
- * 向 detached 进程发送信号。
- *
- * 关键点（中文）
- * - 优先发送到进程组；失败后再尝试单 pid。
- * - 返回值只表示至少有一个目标接收到了信号，不代表进程已经退出。
- */
-export function signalDetachedProcess(
-  pid: number,
-  signal: NodeJS.Signals,
-): boolean {
-  for (const target of buildDetachedProcessSignalTargets(pid)) {
-    try {
-      process.kill(target, signal);
-      return true;
-    } catch {
-      // 尝试下一个目标。
-    }
-  }
-  return false;
-}
-
-export function isDowncityCliCommand(command: string): boolean {
-  return /\/bin\/main\/modules\/cli\/Index\.js(?:\s|$)/.test(command);
-}
-
-/**
- * 判断命令行是否属于本次清扫目标。
- *
- * 关键点（中文）
- * - `Index.js run` 是 city runtime。
- * - `Index.js console run` 是 control plane runtime。
- * - 两者都包含 `run`，因此必须按完整子命令匹配，不能只查 `run` 词元。
- */
-export function shouldSweepDetachedCityCommand(
-  command: string,
-  params: {
-    includeConsole?: boolean;
-    includeUi?: boolean;
-    includeAgent?: boolean;
-  },
-): boolean {
-  if (!isDowncityCliCommand(command)) return false;
-  if (
-    params.includeConsole &&
-    /\/bin\/main\/modules\/cli\/Index\.js\s+run(?:\s|$)/.test(command)
-  ) {
-    return true;
-  }
-  if (
-    params.includeUi &&
-    /\/bin\/main\/modules\/cli\/Index\.js\s+console\s+run(?:\s|$)/.test(command)
-  ) {
-    return true;
-  }
-  if (
-    params.includeAgent &&
-    /\/bin\/main\/modules\/cli\/Index\.js\s+agent\s+start(?:\s|$)/.test(command) &&
-    /--foreground\s+true\b/.test(command)
-  ) {
-    return true;
-  }
-  return false;
-}
-
-async function listDetachedCityProcesses(params: {
-  includeConsole?: boolean;
-  includeUi?: boolean;
-  includeAgent?: boolean;
-  excludePids: Set<number>;
-}): Promise<Array<{ pid: number; command: string }>> {
-  if (process.platform === "win32") {
-    return [];
-  }
-
-  try {
-    const { stdout } = await execFileAsync(
-      "ps",
-      ["-axo", "pid=,command="],
-      {
-        maxBuffer: 1024 * 1024,
-      },
-    );
-
-    return String(stdout || "")
-      .split("\n")
-      .map((line) => line.match(/^\s*(\d+)\s+(.*)$/))
-      .filter((item): item is RegExpMatchArray => Boolean(item))
-      .map((item) => ({
-        pid: Number.parseInt(item[1] || "", 10),
-        command: normalizeCommand(item[2] || ""),
-      }))
-      .filter((item) => Number.isInteger(item.pid) && item.pid > 0)
-      .filter((item) => !params.excludePids.has(item.pid))
-      .filter((item) => shouldSweepDetachedCityCommand(item.command, params));
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 只探测失联的 Downcity detached 进程，不执行停止动作。
- */
-export async function findDetachedCityProcesses(params?: {
-  includeConsole?: boolean;
-  includeUi?: boolean;
-  includeAgent?: boolean;
-  excludePids?: number[];
-}): Promise<Array<{ pid: number; command: string }>> {
-  const excludePids = new Set<number>([
-    process.pid,
-    ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
-  ]);
-
-  return listDetachedCityProcesses({
-    includeConsole: params?.includeConsole,
-    includeUi: params?.includeUi,
-    includeAgent: params?.includeAgent,
-    excludePids,
-  });
-}
-
-async function stopPid(pid: number, timeoutMs: number): Promise<boolean> {
-  if (!isProcessAlive(pid)) return true;
-
-  if (!signalDetachedProcess(pid, "SIGTERM")) {
-    return !isProcessAlive(pid);
-  }
-
-  const termStart = Date.now();
-  while (Date.now() - termStart < timeoutMs) {
-    if (!isProcessAlive(pid)) return true;
-    await new Promise((resolve) => setTimeout(resolve, 200));
-  }
-
-  try {
-    if (isProcessAlive(pid)) {
-      signalDetachedProcess(pid, "SIGKILL");
-    }
-  } catch {
-    return !isProcessAlive(pid);
-  }
-
-  const killStart = Date.now();
-  while (Date.now() - killStart < 2_000) {
-    if (!isProcessAlive(pid)) return true;
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-
-  return !isProcessAlive(pid);
-}
-
-/**
- * 清扫失联的 Downcity detached 进程。
- */
-export async function sweepDetachedCityProcesses(params?: {
-  includeConsole?: boolean;
-  includeUi?: boolean;
-  includeAgent?: boolean;
-  timeoutMs?: number;
-  excludePids?: number[];
-}): Promise<{
-  matched: Array<{ pid: number; command: string }>;
-  stopped: Array<{ pid: number; command: string }>;
-  alive: Array<{ pid: number; command: string }>;
-}> {
-  const timeoutMs = params?.timeoutMs ?? 8_000;
-  const excludePids = new Set<number>([
-    process.pid,
-    ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
-  ]);
-  const matched = await listDetachedCityProcesses({
-    includeConsole: params?.includeConsole,
-    includeUi: params?.includeUi,
-    includeAgent: params?.includeAgent,
-    excludePids,
-  });
-
-  const stopped: Array<{ pid: number; command: string }> = [];
-  const alive: Array<{ pid: number; command: string }> = [];
-
-  for (const item of matched) {
-    // 关键点（中文）：逐个停止，避免并发 kill 时输出与状态难以对应。
-    const ok = await stopPid(item.pid, timeoutMs);
-    if (ok) {
-      stopped.push(item);
-    } else {
-      alive.push(item);
-    }
-  }
-
-  return {
-    matched,
-    stopped,
-    alive,
-  };
-}