holo-codex 0.1.0

package/plugins/autonomous-pr-loop/core/notification-feed.ts

@@ -0,0 +1,263 @@
+import type { MergeReadiness } from "./autonomy-policy.js";
+import type { AgentLoopConfig, AgentLoopEvent, AgentLoopGate, AgentTimelineEntry, WorkerRun } from "./types.js";
+import { isRecord } from "./config.js";
+import { redactSecrets } from "./redaction.js";
+
+export type NotificationSeverity = "informational" | "attention" | "confirmation_required" | "blocked";
+
+export interface LoopNotification {
+  id: string;
+  severity: NotificationSeverity;
+  title: string;
+  reason: string;
+  source: "event" | "gate" | "timeline" | "worker" | "merge";
+  sourceId: string;
+  createdAt: string;
+  payload?: unknown;
+}
+
+/** Derive dashboard notifications from events and gates without making progress noisy. */
+export function deriveNotifications(input: {
+  config: AgentLoopConfig;
+  events: AgentLoopEvent[];
+  gates: AgentLoopGate[];
+  timelineEntries?: AgentTimelineEntry[];
+  workers?: WorkerRun[];
+  mergeReadiness?: MergeReadiness;
+  runId?: string;
+  now?: Date;
+  dismissedIds?: Set<string>;
+}): LoopNotification[] {
+  const readIds = new Set([
+    ...notificationReadIds(input.events),
+    ...notificationDismissedIds(input.events),
+    ...(input.dismissedIds ?? [])
+  ]);
+  const gateNotifications = input.gates
+    .filter((gate) => gate.status === "open")
+    .map((gate): LoopNotification => ({
+      id: `gate:${gate.id}`,
+      severity: severityForGate(gate.kind),
+      title: gate.kind,
+      reason: reasonForGate(gate.kind),
+      source: "gate",
+      sourceId: gate.id,
+      createdAt: gate.createdAt,
+      payload: redactPayload(gate.details)
+    }));
+  const eventNotifications = input.events
+    .map((event) => notificationForEvent(event))
+    .filter((item): item is LoopNotification => item !== undefined);
+  const timelineNotifications = timelineDerivedNotifications(input.timelineEntries ?? [], input.workers ?? [], input.now ?? new Date());
+  const mergeRunId = input.runId ?? currentRunId(input.workers);
+  const mergeNotifications = input.mergeReadiness?.ready && mergeRunId
+    ? [mergeReadyNotification(mergeRunId, input.mergeReadiness, input.now ?? new Date())]
+    : [];
+  return [...gateNotifications, ...eventNotifications, ...timelineNotifications, ...mergeNotifications]
+    .filter((notification) => !readIds.has(notification.id))
+    .filter((notification) => isVisibleForMode(input.config.notifyMode, notification.severity))
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+function notificationReadIds(events: AgentLoopEvent[]): Set<string> {
+  return notificationIdsForKind(events, "notification_marked_read");
+}
+
+function notificationDismissedIds(events: AgentLoopEvent[]): Set<string> {
+  return notificationIdsForKind(events, "notification_dismissed");
+}
+
+function notificationIdsForKind(events: AgentLoopEvent[], kind: string): Set<string> {
+  const ids = new Set<string>();
+  for (const event of events) {
+    if (event.kind !== kind || !isRecord(event.payload)) {
+      continue;
+    }
+    const notificationIds = event.payload.notificationIds;
+    if (Array.isArray(notificationIds)) {
+      for (const id of notificationIds) {
+        if (typeof id === "string") ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+function notificationForEvent(event: AgentLoopEvent): LoopNotification | undefined {
+  const severity = severityForEvent(event.kind);
+  if (!severity) {
+    return undefined;
+  }
+  return {
+    id: `event:${event.id}`,
+    severity,
+    title: event.kind,
+    reason: reasonForEvent(event.kind, severity),
+    source: "event",
+    sourceId: event.id,
+    createdAt: event.createdAt,
+    payload: redactPayload(event.payload)
+  };
+}
+
+function timelineDerivedNotifications(entries: AgentTimelineEntry[], workers: WorkerRun[], now: Date): LoopNotification[] {
+  const notifications: LoopNotification[] = [];
+  const workerStatuses = new Map(workers.map((worker) => [worker.id, worker.status]));
+  for (const worker of workers) {
+    if (worker.status === "failed" || worker.status === "timed_out" || worker.status === "invalid_output") {
+      notifications.push({
+        id: `worker:${worker.id}:${worker.status}`,
+        severity: "attention",
+        title: worker.status === "failed" ? "worker_failed" : `worker_${worker.status}`,
+        reason: "A worker reached a terminal failure state.",
+        source: "worker",
+        sourceId: worker.id,
+        createdAt: worker.completedAt ?? worker.startedAt,
+        payload: redactPayload({ type: worker.type, error: worker.error })
+      });
+    }
+  }
+  for (const entry of entries) {
+    if (isPermissionRequestEntry(entry)) {
+      const workerId = entry.workerId ?? "unknown";
+      const itemId = timelineItemId(entry);
+      notifications.push({
+        id: `permission:${workerId}:${itemId}`,
+        severity: "confirmation_required",
+        title: "permission_requested",
+        reason: "A permission request is visible in the agent timeline.",
+        source: "timeline",
+        sourceId: entry.rawRef.id,
+        createdAt: entry.occurredAt,
+        payload: redactPayload({ title: entry.title, summary: entry.summary })
+      });
+    }
+    if (entry.source === "worker_event" && entry.kind === "command_execution" && !isTerminalWorkerStatus(workerStatuses.get(entry.workerId ?? "")) && isLongRunningCommand(entry, now)) {
+      const workerId = entry.workerId ?? "unknown";
+      const itemId = timelineItemId(entry);
+      notifications.push({
+        id: `longrunning:${workerId}:${itemId}`,
+        severity: "attention",
+        title: "long_running_command",
+        reason: "A command has been running for more than 60 seconds without a terminal event.",
+        source: "timeline",
+        sourceId: entry.rawRef.id,
+        createdAt: entry.occurredAt,
+        payload: redactPayload({ title: entry.title, summary: entry.summary })
+      });
+    }
+  }
+  return notifications;
+}
+
+function isPermissionRequestEntry(entry: AgentTimelineEntry): boolean {
+  return entry.kind === "PermissionRequest" ||
+    entry.kind === "permission_request" ||
+    entry.kind === "permission.requested" ||
+    entry.kind === "permission_requested";
+}
+
+function isTerminalWorkerStatus(status: WorkerRun["status"] | undefined): boolean {
+  return status === "succeeded" || status === "failed" || status === "timed_out" || status === "invalid_output";
+}
+
+function mergeReadyNotification(runId: string, mergeReadiness: MergeReadiness, now: Date): LoopNotification {
+  return {
+    id: `mergeready:${runId}`,
+    severity: "confirmation_required",
+    title: "merge_ready",
+    reason: "Merge readiness evidence is complete under the configured policy.",
+    source: "merge",
+    sourceId: runId,
+    createdAt: now.toISOString(),
+    payload: redactPayload({ state: mergeReadiness.state, evidence: mergeReadiness.evidence })
+  };
+}
+
+function currentRunId(workers: WorkerRun[] | undefined): string | undefined {
+  return workers?.[0]?.runId;
+}
+
+function isLongRunningCommand(entry: AgentTimelineEntry, now: Date): boolean {
+  if (entry.status && entry.status !== "started" && entry.status !== "running") {
+    return false;
+  }
+  const summary = parseSummary(entry.summary);
+  const startedAt = typeof summary?.startedAt === "string" ? summary.startedAt : entry.createdAt;
+  const startedMs = Date.parse(startedAt);
+  return !Number.isNaN(startedMs) && now.getTime() - startedMs > 60_000;
+}
+
+function parseSummary(summary: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(summary) as unknown;
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function timelineItemId(entry: AgentTimelineEntry): string {
+  const summary = parseSummary(entry.summary);
+  return typeof summary?.id === "string" && summary.id.length > 0 ? summary.id : entry.rawRef.id;
+}
+
+function redactPayload(value: unknown): unknown {
+  if (typeof value === "string") {
+    return redactSecrets(value);
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 20).map(redactPayload);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).slice(0, 40).map(([key, nested]) => [
+    key,
+    /token|api_key|authorization|password|secret/i.test(key) ? "[redacted]" : redactPayload(nested)
+  ]));
+}
+
+function severityForGate(kind: string): NotificationSeverity {
+  if (kind === "merge_requires_confirmation") return "confirmation_required";
+  if (kind.includes("timeout") || kind.includes("policy") || kind.includes("unavailable")) return "blocked";
+  if (kind.includes("ci") || kind.includes("review") || kind.includes("github")) return "attention";
+  return "blocked";
+}
+
+function severityForEvent(kind: string): NotificationSeverity | undefined {
+  if (kind.includes("merge_completed") || kind.includes("pr_merged")) return "informational";
+  if (kind.includes("ci_failed") || kind.includes("review_arrived")) return "attention";
+  if (kind.includes("worker") && (kind.includes("failed") || kind.includes("invalid"))) return "attention";
+  if (kind.includes("loop_stopped")) return "informational";
+  return undefined;
+}
+
+function isVisibleForMode(mode: AgentLoopConfig["notifyMode"], severity: NotificationSeverity): boolean {
+  if (mode === "blockers_only") {
+    return severity === "blocked" || severity === "confirmation_required";
+  }
+  if (mode === "important_only") {
+    return severity !== "informational";
+  }
+  return true;
+}
+
+function reasonForGate(kind: string): string {
+  if (kind === "merge_requires_confirmation") {
+    return "Policy requires an explicit confirmation before the loop can continue.";
+  }
+  if (kind.includes("ci")) return "CI evidence is missing, pending, or failed.";
+  if (kind.includes("review")) return "Review evidence needs attention before autonomous progress.";
+  if (kind.includes("policy")) return "A policy guard blocked unsafe progress.";
+  return "The loop cannot safely continue until this gate is resolved.";
+}
+
+function reasonForEvent(kind: string, severity: NotificationSeverity): string {
+  if (severity === "informational") {
+    return "Progress was recorded without requiring operator attention.";
+  }
+  if (kind.includes("worker")) return "A worker output or execution issue needs attention.";
+  if (kind.includes("ci")) return "CI changed in a way that may affect loop progress.";
+  return "This event may require operator attention under the current policy.";
+}

package/plugins/autonomous-pr-loop/core/plan-parser.ts

@@ -0,0 +1,206 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export interface PlanPrItem {
+  id: string;
+  title: string;
+  status: "completed" | "current" | "next" | "unknown";
+  file: string;
+  dependsOn: string[];
+  issueRefs: string[];
+  whySelected?: string;
+}
+
+export interface PlanNavigatorModel {
+  convention: string;
+  currentMilestone: string;
+  selectedNext?: PlanPrItem;
+  completed: PlanPrItem[];
+  candidates: PlanPrItem[];
+  ambiguous: boolean;
+  evidence: string[];
+}
+
+interface SpecIndex {
+  orderedIds: string[];
+  completedIds: Set<string>;
+}
+
+/** Parse documented PR plan/spec files for the dashboard Plan Navigator. */
+export function parsePlanNavigator(repoRoot: string, plansDir: string): PlanNavigatorModel {
+  const convention = "PR plan documents use files named pr-<letter>-<slug>.md with a top-level `# PR X ...` heading; legacy spec indexes are supported when present.";
+  const specDir = join(repoRoot, "docs", "specs");
+  const planDir = join(repoRoot, plansDir);
+  const specIndex = readSpecIndex(specDir);
+  const files = [
+    ...markdownFiles(specDir).filter((file) => /^pr-[a-z0-9]+-/i.test(basename(file))),
+    ...markdownFiles(planDir)
+  ];
+  const items = files.map((file) => parsePlanFile(file)).filter((item): item is PlanPrItem => item !== undefined);
+  const unique = inferStatuses(dedupeById(items).sort(compareBySpecIndex(specIndex)), specIndex);
+  const completed = unique.filter((item) => item.status === "completed");
+  const candidates = unique.filter((item) => item.status === "next" || item.status === "current" || item.status === "unknown");
+  const nextCandidates = candidates.filter((item) => item.status === "next");
+  const selectedNext = nextCandidates.length === 1 ? nextCandidates[0] : candidates[0];
+  return {
+    convention,
+    currentMilestone: selectedNext?.id ?? completed.at(-1)?.id ?? "unknown",
+    ...(selectedNext ? { selectedNext } : {}),
+    completed,
+    candidates,
+    ambiguous: nextCandidates.length > 1 || (!selectedNext && unique.length === 0),
+    evidence: evidenceFor(unique, nextCandidates)
+  };
+}
+
+function markdownFiles(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => join(dir, name));
+}
+
+function readSpecIndex(specDir: string): SpecIndex {
+  const readmePath = join(specDir, "README.md");
+  if (!existsSync(readmePath)) {
+    return { orderedIds: [], completedIds: new Set() };
+  }
+  const text = readFileSync(readmePath, "utf8");
+  const completedIds = new Set<string>();
+  const orderedIds: string[] = [];
+  let inFutureSection = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (isFutureSpecSection(line)) {
+      inFutureSection = true;
+    }
+    const id = /^\s*\d+\.\s+\[PR\s+([A-Z0-9]+)/i.exec(line)?.[1]?.toUpperCase();
+    if (!id) {
+      continue;
+    }
+    const normalized = `PR ${id}`;
+    orderedIds.push(normalized);
+    if (!inFutureSection) {
+      completedIds.add(normalized);
+    }
+  }
+  return { orderedIds, completedIds };
+}
+
+function isFutureSpecSection(line: string): boolean {
+  return /(?:后续|未来|待办)\s*PR\s*顺序/i.test(line) || /future\s+PR\s+order/i.test(line);
+}
+
+function parsePlanFile(file: string): PlanPrItem | undefined {
+  const text = readFileSync(file, "utf8");
+  const heading = /^#\s+(?:SPEC[:：]\s*)?(PR\s+[A-Z0-9]+[^\n]*)/m.exec(text)?.[1];
+  const id = /PR\s+([A-Z0-9]+)/i.exec(heading ?? basename(file))?.[1]?.toUpperCase();
+  if (!id) {
+    return undefined;
+  }
+  const markerStatus = /status:\s*(completed|current|next|unknown)/i.exec(text)?.[1]?.toLowerCase();
+  return {
+    id: `PR ${id}`,
+    title: heading ?? basename(file, ".md"),
+    status: statusFromMarker(markerStatus),
+    file,
+    dependsOn: [...text.matchAll(/depends(?:On| on)[:：]\s*([A-Z0-9,\s]+)/gi)].flatMap((match) =>
+      (match[1] ?? "").split(/,\s*/).filter(Boolean)
+    ),
+    issueRefs: [...text.matchAll(/#(\d+)/g)].map((match) => `#${match[1]}`)
+  };
+}
+
+function statusFromMarker(markerStatus: string | undefined): PlanPrItem["status"] {
+  if (markerStatus === "completed" || markerStatus === "current" || markerStatus === "next" || markerStatus === "unknown") {
+    return markerStatus;
+  }
+  return "unknown";
+}
+
+function inferStatuses(items: PlanPrItem[], specIndex: SpecIndex): PlanPrItem[] {
+  if (items.some((item) => item.status === "next" || item.status === "current")) {
+    return items.map((item) => item.status === "next" && item.whySelected === undefined
+      ? { ...item, whySelected: "Marked next in the plan/spec document." }
+      : item);
+  }
+  const indexedNext = specIndex.orderedIds.find((id) => !specIndex.completedIds.has(id) && items.some((item) => item.id === id));
+  if (indexedNext) {
+    return items.map((item) => {
+      if (item.status !== "unknown") return item;
+      if (specIndex.completedIds.has(item.id)) return { ...item, status: "completed" };
+      if (item.id === indexedNext) {
+        return { ...item, status: "next", whySelected: "Selected as the first uncompleted PR from the legacy spec index." };
+      }
+      return item;
+    });
+  }
+  if (specIndex.orderedIds.length > 0) {
+    return items.map((item) => item.status === "unknown" && specIndex.completedIds.has(item.id)
+      ? { ...item, status: "completed" }
+      : item);
+  }
+  const lastUnknownIndex = findLastIndex(items, (item) => item.status === "unknown");
+  if (lastUnknownIndex < 0) {
+    return items;
+  }
+  return items.map((item, index) => {
+    if (item.status !== "unknown") return item;
+    if (index === lastUnknownIndex) {
+      return { ...item, status: "next", whySelected: "Selected as the highest uncompleted PR from parsed plan/spec documents." };
+    }
+    return { ...item, status: "completed" };
+  });
+}
+
+function dedupeById(items: PlanPrItem[]): PlanPrItem[] {
+  const map = new Map<string, PlanPrItem>();
+  for (const item of items) {
+    const existing = map.get(item.id);
+    if (!existing || item.file.includes("/docs/specs/")) {
+      map.set(item.id, item);
+    }
+  }
+  return [...map.values()];
+}
+
+function evidenceFor(items: PlanPrItem[], nextCandidates: PlanPrItem[]): string[] {
+  if (items.length === 0) {
+    return ["No parseable PR plan/spec files found."];
+  }
+  if (nextCandidates.length > 1) {
+    return nextCandidates.map((item) => `${item.id}: ${item.file}`);
+  }
+  return [`Parsed ${items.length} PR plan/spec documents.`];
+}
+
+function compareBySpecIndex(specIndex: SpecIndex): (a: PlanPrItem, b: PlanPrItem) => number {
+  return (a, b) => {
+    const left = specIndex.orderedIds.indexOf(a.id);
+    const right = specIndex.orderedIds.indexOf(b.id);
+    if (left >= 0 && right >= 0) return left - right;
+    if (left >= 0) return -1;
+    if (right >= 0) return 1;
+    return comparePlanItems(a, b);
+  };
+}
+
+function comparePlanItems(a: PlanPrItem, b: PlanPrItem): number {
+  return planSortKey(a.id).localeCompare(planSortKey(b.id), undefined, { numeric: true });
+}
+
+function planSortKey(id: string): string {
+  const value = /PR\s+([A-Z]+)(\d*)/i.exec(id);
+  if (!value) {
+    return id;
+  }
+  return `${value[1]}${value[2] ? value[2].padStart(3, "0") : "000"}`;
+}
+
+function findLastIndex<T>(items: T[], predicate: (item: T) => boolean): number {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    if (predicate(items[index] as T)) return index;
+  }
+  return -1;
+}

package/plugins/autonomous-pr-loop/core/plugin-paths.ts

@@ -0,0 +1,32 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Resolve the repository/package root that contains this plugin from a module URL. */
+export function packageRootFromUrl(metaUrl: string): string {
+  return resolve(dirname(fileURLToPath(metaUrl)), "../../..");
+}
+
+/** Resolve the repository/package root that contains this plugin. */
+export function defaultPackageRoot(): string {
+  return packageRootFromUrl(import.meta.url);
+}
+
+/** Resolve the HOLO-Codex plugin runtime directory. */
+export function autonomousPrLoopRoot(packageRoot = defaultPackageRoot()): string {
+  return join(packageRoot, "plugins", "autonomous-pr-loop");
+}
+
+/** Resolve the dashboard UI source directory bundled with this plugin. */
+export function dashboardUiRoot(packageRoot = defaultPackageRoot()): string {
+  return join(autonomousPrLoopRoot(packageRoot), "ui");
+}
+
+/** Resolve the hook source directory bundled with this plugin. */
+export function hookSourceRoot(packageRoot = defaultPackageRoot()): string {
+  return join(autonomousPrLoopRoot(packageRoot), "hooks");
+}
+
+/** Resolve the compiled hook runner directory bundled with this plugin. */
+export function hookDistRoot(packageRoot = defaultPackageRoot()): string {
+  return join(hookSourceRoot(packageRoot), "dist");
+}

package/plugins/autonomous-pr-loop/core/policy.ts

@@ -0,0 +1,65 @@
+import { AgentLoopError } from "./errors.js";
+import type { AgentLoopConfig } from "./types.js";
+
+/** Assert that a path is not blocked by the repository policy protectedPaths globs. */
+export function assertAllowedPath(config: AgentLoopConfig, path: string): void {
+  const blocked = config.protectedPaths.some((pattern) => matchesProtectedPath(pattern, path));
+
+  if (blocked) {
+    throw new AgentLoopError(
+      "policy_violation",
+      `Path is protected by agent-loop policy: ${path}`,
+      { details: { path } }
+    );
+  }
+}
+
+/** Match the small glob subset used by protectedPaths: `*`, `**`, and `/**` directory roots. */
+export function matchesProtectedPath(pattern: string, path: string): boolean {
+  const normalizedPattern = normalizePath(pattern);
+  const normalizedPath = normalizePath(path);
+  if (!normalizedPattern.includes("/")) {
+    const basename = normalizedPath.split("/").at(-1) ?? normalizedPath;
+    return globToRegExp(normalizedPattern).test(basename);
+  }
+  if (normalizedPattern.endsWith("/**")) {
+    const prefix = normalizedPattern.slice(0, -3);
+    if (normalizedPath === prefix) {
+      return true;
+    }
+  }
+  return globToRegExp(normalizedPattern).test(normalizedPath);
+}
+
+function normalizePath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let source = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+    const afterNext = pattern[index + 2];
+    if (char === "*" && next === "*" && afterNext === "/") {
+      source += "(?:.*/)?";
+      index += 2;
+      continue;
+    }
+    if (char === "*" && next === "*") {
+      source += ".*";
+      index += 1;
+      continue;
+    }
+    if (char === "*") {
+      source += "[^/]*";
+      continue;
+    }
+    source += escapeRegExp(char ?? "");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}