patchwarden 1.5.0 → 1.6.1

package/src/control/routes/status.ts

@@ -0,0 +1,405 @@
+/**
+ * Control Center routes — runtime status, events, diagnostics, tunnel URLs.
+ *
+ * `handleStatus` is the dashboard's primary poll endpoint: it fans out health
+ * probes, watcher/task snapshots, and suggestion generation, and records
+ * observed state-change events (core/direct/watcher/task transitions) into the
+ * activity timeline. The remaining endpoints expose the control-center status
+ * file, the event timeline, diagnostics (redacted), and tunnel UI URLs.
+ */
+import { existsSync } from "node:fs";
+import { type ServerResponse } from "node:http";
+import { type AgentAvailability } from "../../tools/workspace/listAgents.js";
+import { type TaskEntry } from "../../tools/tasks/listTasks.js";
+import { type WatcherStatusSnapshot } from "../../watcherStatus.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../../version.js";
+import { redactSensitiveValue } from "../../security/contentRedaction.js";
+import {
+  type ControlCenterStatusFile,
+  type RuntimeHealth,
+  type StaleClassification,
+  type StatusTasks,
+  listAgentsSafe,
+  listTasksForStatus,
+  probeRuntimeHealth,
+  readEvents,
+  recordEvent,
+  readToolManifest,
+  readTunnelStatus,
+  readTunnelUrl,
+  readWatcherStatusSafe,
+  resolveWorkspaceRootSafe,
+} from "../runtime.js";
+import { findTunnelClientExecutable } from "./process.js";
+import {
+  config,
+  configIdentitySha256,
+  controlCenterStatusPath,
+  CORE_BASE_URL,
+  DIRECT_BASE_URL,
+  errorMessage,
+  readJsonFileSafe,
+  sendJson,
+} from "../shared.js";
+
+// ── Health suggestions ────────────────────────────────────────────
+
+interface Suggestion {
+  code: string;
+  severity: "info" | "warning" | "error";
+  message: string;
+  action?: string;
+  link?: string;
+}
+
+interface StatusSnapshotForSuggestions {
+  core: RuntimeHealth;
+  direct: RuntimeHealth;
+  watcher: WatcherStatusSnapshot;
+  tunnel: { core: Record<string, unknown>; direct: Record<string, unknown> };
+  agents: AgentAvailability[];
+  tasks: StatusTasks;
+  direct_profile_enabled: boolean;
+}
+
+export interface ExperienceStatus {
+  readiness: "ready" | "needs_action" | "blocked";
+  live_checks: Array<{
+    key: string;
+    label: string;
+    state: "ready" | "needs_action" | "blocked" | "optional";
+    detail: string;
+  }>;
+  historical_summary: {
+    stale_tasks: number;
+    failed_tasks: number;
+    note: string;
+  };
+}
+
+/**
+ * Keep current readiness separate from historical evidence. A month-old failed
+ * task is useful for audit, but must not make a configured local bridge look
+ * unavailable on the first screen.
+ */
+export function buildExperienceStatus(snapshot: StatusSnapshotForSuggestions): ExperienceStatus {
+  const coreReady = snapshot.core.available && snapshot.tunnel.core.ready === true;
+  const watcherReady = snapshot.watcher.status === "healthy";
+  const agentsReady = snapshot.agents.some((agent) => agent.available);
+  const directEnabled = snapshot.direct_profile_enabled;
+  const directReady = snapshot.direct.available && snapshot.tunnel.direct.ready === true;
+  const staleTasks = snapshot.tasks.stale;
+  const failedTasks = snapshot.tasks.tasks.filter((task) => String((task as TaskEntry).status || "").includes("failed")).length;
+
+  const live_checks: ExperienceStatus["live_checks"] = [
+    { key: "workspace_agents", label: "工作区与 Agent", state: agentsReady ? "ready" : "blocked", detail: agentsReady ? "工作区内至少有一个可用 Agent" : "需要配置工作区或可用 Agent" },
+    { key: "core", label: "Core 服务", state: coreReady ? "ready" : "needs_action", detail: coreReady ? "Core 与 Tunnel 已就绪" : "启动 Core 后会继续检查 Tunnel 与 Watcher" },
+    { key: "watcher", label: "任务监视器", state: watcherReady ? "ready" : "needs_action", detail: watcherReady ? "Watcher 心跳正常" : "Core 启动后 Watcher 将处理排队任务" },
+    { key: "direct", label: "Direct 编辑", state: directEnabled ? (directReady ? "ready" : "needs_action") : "optional", detail: directEnabled ? (directReady ? "Direct 已就绪" : "已启用但尚未就绪") : "可选高级能力，未启用不会影响 Core" },
+  ];
+
+  const readiness: ExperienceStatus["readiness"] = !agentsReady
+    ? "blocked"
+    : coreReady && watcherReady && (!directEnabled || directReady)
+      ? "ready"
+      : "needs_action";
+
+  return {
+    readiness,
+    live_checks,
+    historical_summary: {
+      stale_tasks: staleTasks,
+      failed_tasks: failedTasks,
+      note: "历史任务与审计记录不会影响当前实时就绪状态。",
+    },
+  };
+}
+
+export function reconcileTunnelStatus(
+  status: Record<string, unknown>,
+  health: RuntimeHealth,
+): Record<string, unknown> {
+  if (!health.available) return status;
+  return {
+    ...status,
+    observed: true,
+    status: "running",
+    ready: true,
+    reason_code: "health_endpoint_ready",
+    health_observed: true,
+  };
+}
+
+export function buildSuggestions(s: StatusSnapshotForSuggestions): Suggestion[] {
+  const out: Suggestion[] = [];
+
+  if (!s.core.available) {
+    out.push({
+      code: "core_stopped",
+      severity: "warning",
+      message: "Core 未运行，建议启动 Core profile",
+      action: "/api/core/start",
+    });
+  }
+  if (s.direct_profile_enabled && !s.direct.available) {
+    out.push({
+      code: "direct_stopped",
+      severity: "warning",
+      message: "Direct 未运行，建议启动 Direct profile",
+      action: "/api/direct/start",
+    });
+  }
+
+  if (s.watcher.status === "degraded" || s.watcher.status === "stale" || s.watcher.status === "unreadable") {
+    out.push({
+      code: "watcher_stale",
+      severity: "error",
+      message: "Watcher 处于 " + s.watcher.status + " 状态，建议重启 Core",
+      action: "/api/core/restart",
+    });
+  }
+
+  if (s.tasks.stale > 0) {
+    out.push({
+      code: "stale_task",
+      severity: "warning",
+      message: "存在 " + s.tasks.stale + " 个 stale 任务，建议查看并 reconcile",
+      link: "/pages/tasks.html?filter=stale",
+    });
+  }
+
+  const coreTunnelReady = !!(s.tunnel.core && s.tunnel.core.ready);
+  const directTunnelReady = !!(s.tunnel.direct && s.tunnel.direct.ready);
+  if (!coreTunnelReady || (s.direct_profile_enabled && !directTunnelReady)) {
+    out.push({
+      code: "tunnel_not_ready",
+      severity: "warning",
+      message: "Tunnel 未就绪，建议启动 profile 或检查代理",
+      action: "/api/start-all",
+    });
+  }
+
+  const missingAgents = s.agents.filter((a) => !a.available);
+  if (missingAgents.length > 0) {
+    out.push({
+      code: "agent_missing",
+      severity: "info",
+      message: "Agent 未就绪：" + missingAgents.map((a) => a.name).join(", ") + "（请检查对应 CLI 安装与路径）",
+    });
+  }
+
+  return out;
+}
+
+// ── Observed state-change detection (drives activity timeline) ────
+
+interface StatusSnapshotDigest {
+  core_available: boolean;
+  direct_available: boolean;
+  watcher_status: string;
+  task_statuses: Record<string, string>;
+}
+
+let lastStatusDigest: StatusSnapshotDigest | null = null;
+
+function buildStatusDigest(s: StatusSnapshotForSuggestions): StatusSnapshotDigest {
+  const task_statuses: Record<string, string> = {};
+  for (const t of s.tasks.tasks) {
+    const entry = t as TaskEntry & StaleClassification;
+    task_statuses[entry.task_id] = entry.status;
+  }
+  return {
+    core_available: s.core.available,
+    direct_available: s.direct.available,
+    watcher_status: s.watcher.status,
+    task_statuses,
+  };
+}
+
+function diffAndRecordEvents(prev: StatusSnapshotDigest, curr: StatusSnapshotDigest): void {
+  if (prev.core_available !== curr.core_available) {
+    recordEvent("core.status_changed", { from: prev.core_available, to: curr.core_available });
+  }
+  if (prev.direct_available !== curr.direct_available) {
+    recordEvent("direct.status_changed", { from: prev.direct_available, to: curr.direct_available });
+  }
+  if (prev.watcher_status !== curr.watcher_status) {
+    recordEvent("watcher.status_changed", { from: prev.watcher_status, to: curr.watcher_status });
+  }
+  for (const [taskId, newStatus] of Object.entries(curr.task_statuses)) {
+    const oldStatus = prev.task_statuses[taskId];
+    if (oldStatus && oldStatus !== newStatus) {
+      recordEvent("task.status_changed", { task_id: taskId, from: oldStatus, to: newStatus });
+    }
+  }
+}
+
+// ── Handlers ──────────────────────────────────────────────────────
+
+export async function handleStatus(res: ServerResponse): Promise<void> {
+  try {
+    const [coreHealth, directHealth, watcher, tunnelCoreRaw, tunnelDirectRaw, toolsCore, toolsDirect, agents, workspaceRoot, tasks] = await Promise.all([
+      probeRuntimeHealth(CORE_BASE_URL).catch((err): RuntimeHealth => ({
+        available: false,
+        reason: errorMessage(err),
+        healthz: null,
+        readyz: null,
+      })),
+      probeRuntimeHealth(DIRECT_BASE_URL).catch((err): RuntimeHealth => ({
+        available: false,
+        reason: errorMessage(err),
+        healthz: null,
+        readyz: null,
+      })),
+      Promise.resolve(readWatcherStatusSafe()),
+      Promise.resolve(readTunnelStatus(false)),
+      Promise.resolve(readTunnelStatus(true)),
+      Promise.resolve(readToolManifest(false)),
+      Promise.resolve(readToolManifest(true)),
+      Promise.resolve(listAgentsSafe()),
+      Promise.resolve(resolveWorkspaceRootSafe()),
+      Promise.resolve(listTasksForStatus()),
+    ]);
+    const tunnelCore = reconcileTunnelStatus(tunnelCoreRaw, coreHealth);
+    const tunnelDirect = reconcileTunnelStatus(tunnelDirectRaw, directHealth);
+    const snapshotForSuggestions: StatusSnapshotForSuggestions = {
+      core: coreHealth,
+      direct: directHealth,
+      watcher,
+      tunnel: { core: tunnelCore, direct: tunnelDirect },
+      agents,
+      tasks,
+      direct_profile_enabled: config.enableDirectProfile === true,
+    };
+    const suggestions = buildSuggestions(snapshotForSuggestions);
+    const experience = buildExperienceStatus(snapshotForSuggestions);
+    const tunnelClientExe = findTunnelClientExecutable();
+
+    // Diff against the previous poll to record observed state-change events.
+    // This is the only place that observes Core/Direct/watcher/task transitions
+    // (the control center is otherwise stateless and pull-driven).
+    const digest = buildStatusDigest(snapshotForSuggestions);
+    if (lastStatusDigest) {
+      diffAndRecordEvents(lastStatusDigest, digest);
+    }
+    lastStatusDigest = digest;
+
+    sendJson(res, 200, {
+      core: coreHealth,
+      direct: directHealth,
+      watcher,
+      tunnel: { core: tunnelCore, direct: tunnelDirect },
+      tools: { core: toolsCore, direct: toolsDirect },
+      agents,
+      workspace_root: workspaceRoot,
+      tasks,
+      suggestions,
+      experience,
+      direct_profile_enabled: config.enableDirectProfile === true,
+      setup: {
+        tunnel_client: {
+          available: tunnelClientExe !== null,
+          path: tunnelClientExe,
+          source: config.tunnelClientPath && tunnelClientExe === config.tunnelClientPath ? "config" : "detected",
+        },
+        workspace_root: workspaceRoot,
+        watcher: {
+          status: watcher.status,
+          available: watcher.available,
+          reason: watcher.reason,
+        },
+      },
+    });
+  } catch (err) {
+    sendJson(res, 200, { error: errorMessage(err), partial: true });
+  }
+}
+
+export function handleControlCenterStatus(res: ServerResponse): void {
+  // Public read of the status file (used by tray/launcher to confirm identity).
+  if (!existsSync(controlCenterStatusPath)) {
+    sendJson(res, 200, { running: false });
+    return;
+  }
+  const data = readJsonFileSafe<ControlCenterStatusFile>(controlCenterStatusPath);
+  if (!data) {
+    sendJson(res, 200, { running: false });
+    return;
+  }
+  sendJson(res, 200, { running: true, ...data });
+}
+
+export function handleEvents(res: ServerResponse, limit: number): void {
+  const events = readEvents(limit);
+  sendJson(res, 200, {
+    events,
+    total: events.length,
+    limit,
+  });
+}
+
+export function handleTunnelUiUrl(res: ServerResponse): void {
+  sendJson(res, 200, {
+    core: readTunnelUrl(false),
+    direct: readTunnelUrl(true),
+  });
+}
+
+export async function handleDiagnostics(res: ServerResponse): Promise<void> {
+  try {
+    const watcher = readWatcherStatusSafe();
+    const [coreHealth, directHealth] = await Promise.all([
+      probeRuntimeHealth(CORE_BASE_URL),
+      probeRuntimeHealth(DIRECT_BASE_URL),
+    ]);
+    const tunnelCore = reconcileTunnelStatus(readTunnelStatus(false), coreHealth);
+    const tunnelDirect = reconcileTunnelStatus(readTunnelStatus(true), directHealth);
+    const toolsCore = readToolManifest(false);
+    const toolsDirect = readToolManifest(true);
+    const agents = listAgentsSafe();
+
+    let workspaceRoot: string | null = null;
+    try {
+      workspaceRoot = resolveWorkspaceRootSafe();
+    } catch {
+      workspaceRoot = null;
+    }
+
+    // Recent failures: last 5 failed tasks (status contains "failed")
+    let recentFailures: Array<{ task_id: string; status: string }> = [];
+    try {
+      const result = listTasksForStatus();
+      recentFailures = (result.tasks as Array<{ task_id: string; status: string }>)
+        .filter((t) => typeof t.status === "string" && t.status.includes("failed"))
+        .slice(0, 5)
+        .map((t) => ({ task_id: t.task_id, status: t.status }));
+    } catch {
+      recentFailures = [];
+    }
+
+    const coreReady = !!(tunnelCore && tunnelCore.ready);
+    const directReady = !!(tunnelDirect && tunnelDirect.ready);
+
+    const diagnostics = {
+      server_version: PATCHWARDEN_VERSION,
+      schema_epoch: TOOL_SCHEMA_EPOCH,
+      tool_manifest_sha256: toolsCore.tool_manifest_sha256,
+      watcher_status: watcher.status,
+      tunnel_core_ready: coreReady,
+      tunnel_direct_ready: directReady,
+      core_tool_count: toolsCore.tool_count,
+      direct_tool_count: toolsDirect.tool_count,
+      agent_status: agents.map((a) => ({ name: a.name, available: a.available })),
+      workspace_root: workspaceRoot,
+      recent_failures: recentFailures,
+      direct_profile_enabled: config.enableDirectProfile ?? false,
+      config_identity_sha256: configIdentitySha256,
+    };
+
+    // Redact any sensitive content that may have leaked into string fields.
+    const redacted = redactSensitiveValue(diagnostics);
+    sendJson(res, 200, redacted.value);
+  } catch (err) {
+    sendJson(res, 200, { error: errorMessage(err) });
+  }
+}

package/src/control/routes/taskActions.ts

@@ -0,0 +1,214 @@
+/**
+ * Control Center routes — mutating task actions (POST /api/tasks/:id/*).
+ *
+ * These handlers are invoked only after the server router has validated the
+ * control token. They cover reconcile, on-demand audit_task, opening the task
+ * folder in the host file explorer, and hiding a stale task from the
+ * dashboard. None of them delete task files; they annotate or launch external
+ * viewers.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { type ServerResponse } from "node:http";
+import { auditTask } from "../../tools/diagnostics/auditTask.js";
+import { getTasksDir } from "../../config.js";
+import {
+  classifyStaleTask,
+  isValidTaskId,
+  readHiddenStaleIds,
+  reconstructTaskEntry,
+  readWatcherStatusSafe,
+  recordEvent,
+  TERMINAL_TASK_STATUSES,
+  writeHiddenStaleIds,
+} from "../runtime.js";
+import { launchFileManager } from "../fileManager.js";
+import { config, errorMessage, guardControlPath, readJsonFileSafe, sendJson } from "../shared.js";
+import { atomicWriteJsonFileSync } from "../../utils/atomicFile.js";
+import { mutateTaskStatus } from "../../runner/taskStatusStore.js";
+
+/**
+ * Reconcile a stale task. Does NOT delete the task. Reads the task files,
+ * decides whether it is safe to mark the task as stale/archived, writes a
+ * reconcile record, and (when safe) annotates status.json with reconcile
+ * metadata. The task status enum is never changed — only metadata is added.
+ */
+export function handleReconcile(res: ServerResponse, taskId: string): void {
+  try {
+    if (!isValidTaskId(taskId)) {
+      sendJson(res, 400, { error: "Invalid task id" });
+      return;
+    }
+    const tasksDir = getTasksDir(config);
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+      sendJson(res, 404, { error: "Task not found" });
+      return;
+    }
+
+    const statusPath = join(taskDir, "status.json");
+    const runtimePath = join(taskDir, "runtime.json");
+    const statusData = readJsonFileSafe<Record<string, unknown>>(statusPath) ?? {};
+    const runtimeData = readJsonFileSafe<Record<string, unknown>>(runtimePath) ?? {};
+
+    const watcher = readWatcherStatusSafe();
+    const taskEntry = reconstructTaskEntry(taskId, statusData, runtimeData, watcher);
+
+    const cls = classifyStaleTask(taskEntry, watcher);
+    const isTerminal = TERMINAL_TASK_STATUSES.has(taskEntry.status);
+
+    // Safe to mark stale/archived when:
+    //  - terminal status  -> archive (already finished)
+    //  - stale AND watcher is not actively driving it (no current_command OR watcher not healthy)
+    let decision: "marked_stale" | "marked_archived" | "no_action";
+    let safe = false;
+    if (isTerminal) {
+      decision = "marked_archived";
+      safe = true;
+    } else if (
+      cls.is_stale &&
+      (taskEntry.current_command === null || taskEntry.current_command === "" || watcher.status !== "healthy")
+    ) {
+      decision = "marked_stale";
+      safe = true;
+    } else {
+      decision = "no_action";
+      safe = false;
+    }
+
+    const reconciledAt = new Date().toISOString();
+    const reconcileRecord = {
+      task_id: taskId,
+      reconciled_at: reconciledAt,
+      decision,
+      safe,
+      previous_status: taskEntry.status,
+      previous_phase: taskEntry.phase,
+      is_stale: cls.is_stale,
+      stale_reasons: cls.stale_reasons,
+      watcher_status: watcher.status,
+      watcher_last_heartbeat_at: watcher.last_heartbeat_at,
+      task_last_heartbeat_at: taskEntry.last_heartbeat_at || null,
+      task_current_command: taskEntry.current_command,
+      notes:
+        decision === "no_action"
+          ? "Task does not currently qualify for safe reconcile (still actively running or watcher is healthy)."
+          : "Task annotated with reconcile metadata; original status preserved. No files were deleted.",
+    };
+
+    // Write the reconcile record artifact.
+    try {
+      atomicWriteJsonFileSync(join(taskDir, "reconcile.json"), reconcileRecord);
+    } catch (writeErr) {
+      sendJson(res, 500, { error: `Failed to write reconcile record: ${errorMessage(writeErr)}` });
+      return;
+    }
+
+    // Annotate status.json with reconcile metadata (do not mutate status enum).
+    if (safe) {
+      const annotation = {
+        reconcile_state: decision === "marked_archived" ? "archived" : "stale",
+        reconciled_at: reconciledAt,
+      };
+      try {
+        mutateTaskStatus(statusPath, (current) => {
+          if (current.status !== taskEntry.status) {
+            throw new Error("Task status changed while reconcile was being evaluated; retry.");
+          }
+          const next = { ...current, ...annotation, updated_at: new Date().toISOString() };
+          return { next, result: next };
+        });
+      } catch (writeErr) {
+        sendJson(res, 500, { error: `Failed to annotate status.json: ${errorMessage(writeErr)}` });
+        return;
+      }
+    }
+
+    recordEvent("task.reconciled", {
+      task_id: taskId,
+      decision,
+      safe,
+      previous_status: taskEntry.status,
+      is_stale: cls.is_stale,
+    });
+    sendJson(res, 200, reconcileRecord);
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+  }
+}
+
+/**
+ * Run audit_task for a task. Only safe to delegate when the task directory
+ * exists and the task is in a terminal state (auditing a running task mid-flight
+ * would race with the watcher writing artifacts).
+ */
+export function handleTaskAudit(res: ServerResponse, taskId: string): void {
+  try {
+    if (!isValidTaskId(taskId)) {
+      sendJson(res, 400, { error: "Invalid task id" });
+      return;
+    }
+    const tasksDir = getTasksDir(config);
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+      sendJson(res, 404, { error: "Task not found" });
+      return;
+    }
+    const statusData = readJsonFileSafe<Record<string, unknown>>(join(taskDir, "status.json"));
+    const taskStatus = statusData ? String(statusData.status || "") : "";
+    if (!TERMINAL_TASK_STATUSES.has(taskStatus as string)) {
+      sendJson(res, 409, {
+        error: "Task is not in a terminal state; audit_task can only run safely after completion.",
+        status: taskStatus || "unknown",
+      });
+      return;
+    }
+    const output = auditTask(taskId);
+    recordEvent("task.audited", { task_id: taskId, previous_status: taskStatus });
+    sendJson(res, 200, { ok: true, audit: output });
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+  }
+}
+
+export function handleOpenTaskFolder(res: ServerResponse, taskId: string): void {
+  try {
+    if (!isValidTaskId(taskId)) {
+      sendJson(res, 400, { error: "Invalid task id" });
+      return;
+    }
+    const tasksDir = getTasksDir(config);
+    const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+    if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+      sendJson(res, 404, { error: "Task not found" });
+      return;
+    }
+    launchFileManager(taskDir, tasksDir);
+    sendJson(res, 200, { ok: true, path: taskDir });
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+  }
+}
+
+/**
+ * Hide a stale task from the dashboard's stale-task view. The task itself is
+ * NOT deleted or modified — only the control-center's local hidden-stale-ids
+ * state file is updated. Requires control token (enforced by the POST router).
+ */
+export function handleHideStale(res: ServerResponse, taskId: string): void {
+  try {
+    if (!isValidTaskId(taskId)) {
+      sendJson(res, 400, { error: "Invalid task id" });
+      return;
+    }
+    const ids = readHiddenStaleIds();
+    if (!ids.includes(taskId)) {
+      ids.push(taskId);
+      writeHiddenStaleIds(ids);
+    }
+    recordEvent("task.hide_stale", { task_id: taskId });
+    sendJson(res, 200, { ok: true, hidden: taskId });
+  } catch (err) {
+    sendJson(res, 500, { error: errorMessage(err) });
+  }
+}