@buihongduc132/pi-acp-agents 0.3.1

package/src/management/safe-mkdir.ts

@@ -0,0 +1,78 @@
+/**
+ * safe-mkdir — Ownership-aware directory creation for pi extensions
+ *
+ * Guarantees that created directories are owned by the current user.
+ * Detects root-owned directories (e.g. from sudo test runs) and warns
+ * with a clear fix command instead of silently failing later with EACCES.
+ *
+ * All pi extensions that create directories under ~/.pi/ MUST use this
+ * instead of bare `mkdirSync`.
+ */
+// @ts-nocheck
+
+import { mkdirSync, statSync } from "node:fs";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+/**
+ * Create a directory with current-user ownership guarantee.
+ *
+ * - If the dir doesn't exist: creates it with mode 0o755
+ * - If the dir exists but is owned by another user: warns with fix command
+ * - If the dir exists and is owned by current user: no-op
+ *
+ * @param dirPath - Absolute path to create
+ * @param options - Optional mkdirSync options (mode defaults to 0o755)
+ */
+export function safeMkdir(
+	dirPath: string,
+	options?: { mode?: number },
+): void {
+	const mode = options?.mode ?? 0o755;
+	mkdirSync(dirPath, { recursive: true, mode });
+
+	// Ownership check — detect root-owned dirs from sudo runs
+	try {
+		const stat = statSync(dirPath);
+		if (stat.uid !== process.getuid()) {
+			console.warn(
+				`[pi] WARNING: Directory ${dirPath} is owned by uid ${stat.uid}, ` +
+				`but pi runs as uid ${process.getuid()}. ` +
+				`Fix: sudo chown -R $(whoami) ${dirPath}`,
+			);
+		}
+	} catch (e) {
+		// stat failed — dir may not exist yet, harmless
+		log.debug("safe-mkdir stat failed", e);
+	}
+}
+
+/**
+ * Check if a directory is writable by the current user.
+ * Returns { ok: true } or { ok: false, reason: string, fix: string }.
+ */
+export function checkDirOwnership(dirPath: string): {
+	ok: boolean;
+	reason?: string;
+	fix?: string;
+} {
+	try {
+		const stat = statSync(dirPath);
+		if (stat.uid !== process.getuid()) {
+			return {
+				ok: false,
+				reason: `owned by uid ${stat.uid}, expected ${process.getuid()}`,
+				fix: `sudo chown -R $(whoami) ${dirPath}`,
+			};
+		}
+		return { ok: true };
+	} catch (e) {
+		log.debug("safe-mkdir checkDirOwnership stat failed", e);
+		return {
+			ok: false,
+			reason: `cannot stat ${dirPath}`,
+			fix: `mkdir -p ${dirPath}`,
+		};
+	}
+}

package/src/management/session-archive-store.ts

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AcpArchivedSessionMetadata, AcpSessionHandle } from "../config/types.js";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+interface ArchivePayload {
+  sessions: AcpArchivedSessionMetadataRecord[];
+}
+
+interface ParsedArchivePayload {
+  sessions: AcpArchivedSessionMetadata[];
+}
+
+interface AcpArchivedSessionMetadataRecord {
+  sessionId: string;
+  sessionName?: string;
+  agentName: string;
+  cwd: string;
+  createdAt: string;
+  lastActivityAt: string;
+  lastResponseAt?: string;
+  completedAt?: string;
+  disposed: boolean;
+  autoClosed?: boolean;
+  closeReason?: string;
+  model?: string;
+  mode?: string;
+  loadStatus?: "loadable" | "unloadable" | "unknown";
+  lastLoadAttemptAt?: string;
+  lastLoadError?: string;
+  loadAttemptCount?: number;
+}
+
+const DEFAULT_PAYLOAD: ArchivePayload = { sessions: [] };
+
+export class SessionArchiveStore {
+  constructor(private rootDir?: string) {}
+
+  get(sessionId: string): AcpArchivedSessionMetadata | undefined {
+    return this.read().sessions.find((session) => session.sessionId === sessionId);
+  }
+
+  upsert(session: AcpSessionHandle | AcpArchivedSessionMetadata): AcpArchivedSessionMetadata {
+    const payload = this.readRaw();
+    const record = this.toRecord(session);
+    const index = payload.sessions.findIndex((entry) => entry.sessionId === record.sessionId);
+    if (index >= 0) {
+      payload.sessions[index] = record;
+    } else {
+      payload.sessions.push(record);
+    }
+    this.writeRaw(payload);
+    return this.fromRecord(record);
+  }
+
+  private get filePath(): string {
+    const paths = ensureRuntimeDir(this.rootDir);
+    return join(paths.rootDir, "session-archive.json");
+  }
+
+  private read(): ParsedArchivePayload {
+    return {
+      sessions: this.readRaw().sessions.map((session) => this.fromRecord(session)),
+    };
+  }
+
+  private readRaw(): ArchivePayload {
+    if (!existsSync(this.filePath)) {
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+    try {
+      return JSON.parse(readFileSync(this.filePath, "utf-8")) as ArchivePayload;
+    } catch (e) {
+      // File read failed — return default payload
+      log.debug("session-archive-store read failed", e);
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+  }
+
+  private writeRaw(payload: ArchivePayload): void {
+    try {
+      writeFileSync(this.filePath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    } catch (e) {
+      // File read failed — return default payload
+      // EACCES or other FS error — silently degrade.
+      log.debug("session-archive-store write failed", e);
+    }
+  }
+
+  private toRecord(session: AcpSessionHandle | AcpArchivedSessionMetadata): AcpArchivedSessionMetadataRecord {
+    return {
+      sessionId: session.sessionId,
+      sessionName: session.sessionName,
+      agentName: session.agentName,
+      cwd: session.cwd,
+      createdAt: session.createdAt.toISOString(),
+      lastActivityAt: session.lastActivityAt.toISOString(),
+      lastResponseAt: session.lastResponseAt?.toISOString(),
+      completedAt: session.completedAt?.toISOString(),
+      disposed: session.disposed,
+      autoClosed: session.autoClosed,
+      closeReason: session.closeReason,
+      model: session.model,
+      mode: session.mode,
+      loadStatus: session.loadStatus,
+      lastLoadAttemptAt: session.lastLoadAttemptAt,
+      lastLoadError: session.lastLoadError,
+      loadAttemptCount: session.loadAttemptCount,
+    };
+  }
+
+  private fromRecord(record: AcpArchivedSessionMetadataRecord): AcpArchivedSessionMetadata {
+    return {
+      sessionId: record.sessionId,
+      sessionName: record.sessionName,
+      agentName: record.agentName,
+      cwd: record.cwd,
+      createdAt: new Date(record.createdAt),
+      lastActivityAt: new Date(record.lastActivityAt),
+      lastResponseAt: record.lastResponseAt ? new Date(record.lastResponseAt) : undefined,
+      completedAt: record.completedAt ? new Date(record.completedAt) : undefined,
+      disposed: record.disposed,
+      autoClosed: record.autoClosed,
+      closeReason: record.closeReason,
+      model: record.model,
+      mode: record.mode,
+      loadStatus: record.loadStatus,
+      lastLoadAttemptAt: record.lastLoadAttemptAt,
+      lastLoadError: record.lastLoadError,
+      loadAttemptCount: record.loadAttemptCount,
+    };
+  }
+}

package/src/management/session-name-store.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+interface SessionNameRecord {
+  sessionName: string;
+  sessionId: string;
+}
+
+interface SessionNameRegistryPayload {
+  mappings: SessionNameRecord[];
+}
+
+const DEFAULT_PAYLOAD: SessionNameRegistryPayload = { mappings: [] };
+
+function normalizeSessionName(sessionName: string): string {
+  const normalized = sessionName.trim();
+  if (normalized === "") {
+    throw new Error("session_name is required");
+  }
+  return normalized;
+}
+
+export class SessionNameStore {
+  constructor(
+    private rootDir?: string,
+    private options?: { treatAsRuntimeDir?: boolean },
+  ) {}
+
+  getSessionId(sessionName: string): string | undefined {
+    const normalizedName = normalizeSessionName(sessionName);
+    return this.read().mappings.find((entry) => entry.sessionName === normalizedName)?.sessionId;
+  }
+
+  getName(sessionId: string): string | undefined {
+    return this.read().mappings.find((entry) => entry.sessionId === sessionId)?.sessionName;
+  }
+
+  register(sessionName: string, sessionId: string): SessionNameRecord {
+    const normalizedName = normalizeSessionName(sessionName);
+    const payload = this.read();
+    const existingByName = payload.mappings.find((entry) => entry.sessionName === normalizedName);
+    if (existingByName && existingByName.sessionId !== sessionId) {
+      throw new Error(`Session name "${normalizedName}" is already assigned to session "${existingByName.sessionId}".`);
+    }
+    const existingBySession = payload.mappings.find((entry) => entry.sessionId === sessionId);
+    if (existingBySession && existingBySession.sessionName !== normalizedName) {
+      throw new Error(`Session "${sessionId}" is already assigned friendly name "${existingBySession.sessionName}".`);
+    }
+    const record = existingByName ?? existingBySession ?? { sessionName: normalizedName, sessionId };
+    if (!existingByName && !existingBySession) {
+      payload.mappings.push(record);
+      this.write(payload);
+    }
+    return record;
+  }
+
+  private get filePath(): string {
+    if (this.options?.treatAsRuntimeDir && this.rootDir) {
+      return `${this.rootDir}/session-name-registry.json`;
+    }
+    return ensureRuntimeDir(this.rootDir).sessionNameRegistryFile;
+  }
+
+  private read(): SessionNameRegistryPayload {
+    if (!existsSync(this.filePath)) return structuredClone(DEFAULT_PAYLOAD);
+    try {
+      const parsed = JSON.parse(readFileSync(this.filePath, "utf8")) as SessionNameRegistryPayload;
+      return { mappings: Array.isArray(parsed.mappings) ? parsed.mappings.filter((entry) => entry?.sessionName && entry?.sessionId) : [] };
+    } catch (e) {
+      // File read failed — return default payload
+      log.debug("session-name-store read failed", e);
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+  }
+
+  private write(payload: SessionNameRegistryPayload): void {
+    try {
+      writeFileSync(this.filePath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+    } catch (e) {
+      // File read failed — return default payload
+      // EACCES or other FS error — silently degrade.
+      log.debug("session-name-store write failed", e);
+    }
+  }
+}

package/src/management/task-store.ts

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+import type { AcpTaskPriority } from "../config/types.js";
+
+const log = createNoopLogger();
+
+export type AcpTaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+
+export interface AcpTaskRecord {
+  id: string;
+  subject: string;
+  description?: string;
+  status: AcpTaskStatus;
+  assignee?: string;
+  result?: string;
+  blockedBy: string[];
+  blocks: string[];
+  priority: AcpTaskPriority;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface AcpTaskStorePayload {
+  nextId: number;
+  tasks: AcpTaskRecord[];
+}
+
+const DEFAULT_PAYLOAD: AcpTaskStorePayload = {
+  nextId: 1,
+  tasks: [],
+};
+
+export class AcpTaskStore {
+  constructor(private rootDir?: string) {}
+
+  list(options?: { status?: AcpTaskStatus; includeDeleted?: boolean }): AcpTaskRecord[] {
+    const payload = this.read();
+    return payload.tasks.filter((task) => {
+      if (!options?.includeDeleted && task.status === "deleted") return false;
+      if (options?.status && task.status !== options.status) return false;
+      return true;
+    });
+  }
+
+  get(id: string): AcpTaskRecord | undefined {
+    return this.read().tasks.find((task) => task.id === id);
+  }
+
+  create(input: { subject: string; description?: string; assignee?: string; deps?: string[] }): AcpTaskRecord {
+    const payload = this.read();
+    const now = new Date().toISOString();
+    const task: AcpTaskRecord = {
+      id: String(payload.nextId++),
+      subject: input.subject,
+      description: input.description,
+      assignee: input.assignee,
+      status: "pending",
+      blockedBy: input.deps ?? [],
+      blocks: [],
+      priority: "normal",
+      metadata: {},
+      createdAt: now,
+      updatedAt: now,
+    };
+    payload.tasks.push(task);
+    this.write(payload);
+    return task;
+  }
+
+  update(id: string, mutate: (task: AcpTaskRecord) => void): AcpTaskRecord {
+    const payload = this.read();
+    const task = payload.tasks.find((item) => item.id === id);
+    if (!task) throw new Error(`Task \"${id}\" not found`);
+    mutate(task);
+    task.updatedAt = new Date().toISOString();
+    this.write(payload);
+    return task;
+  }
+
+  clear(mode: "completed" | "all" = "completed"): { removed: number; remaining: number } {
+    const payload = this.read();
+    const before = payload.tasks.length;
+    if (mode === "all") {
+      payload.tasks = [];
+    } else {
+      payload.tasks = payload.tasks.filter((task) => task.status !== "completed" && task.status !== "deleted");
+    }
+    const removed = before - payload.tasks.length;
+    this.write(payload);
+    return { removed, remaining: payload.tasks.length };
+  }
+
+  /** Bulk update tasks matching a filter. Returns updated tasks. */
+  updateWhere(filter: string, mutate: (task: AcpTaskRecord) => void): AcpTaskRecord[] {
+    const payload = this.read();
+    const updated: AcpTaskRecord[] = [];
+    for (const task of payload.tasks) {
+      let matches = false;
+      if (filter === "completed" && task.status === "completed") matches = true;
+      else if (filter === "pending" && task.status === "pending") matches = true;
+      else if (filter === "in_progress" && task.status === "in_progress") matches = true;
+      else if (filter === "" || filter === "all") matches = true;
+      if (matches) {
+        mutate(task);
+        task.updatedAt = new Date().toISOString();
+        updated.push(task);
+      }
+    }
+    if (updated.length > 0) this.write(payload);
+    return updated;
+  }
+
+  /** List tasks with full dependency graph details. */
+  listWithDetails(): AcpTaskRecord[] {
+    return this.list({ includeDeleted: true });
+  }
+
+  /** Create task with priority + metadata support (M3, M5) */
+  createWithPriority(input: { subject: string; description?: string; assignee?: string; priority?: AcpTaskPriority; blockedBy?: string[] }): AcpTaskRecord {
+    const payload = this.read();
+    const now = new Date().toISOString();
+    const task: AcpTaskRecord = {
+      id: String(payload.nextId++),
+      subject: input.subject,
+      description: input.description,
+      assignee: input.assignee,
+      status: "pending",
+      blockedBy: input.blockedBy ?? [],
+      blocks: [],
+      priority: input.priority ?? "normal",
+      metadata: {},
+      createdAt: now,
+      updatedAt: now,
+    };
+    // Maintain reverse edges
+    for (const depId of task.blockedBy) {
+      const dep = payload.tasks.find((t) => t.id === depId);
+      if (dep && !dep.blocks.includes(task.id)) dep.blocks.push(task.id);
+    }
+    payload.tasks.push(task);
+    this.write(payload);
+    return task;
+  }
+
+  /** DFS cycle detection — returns path if cycle found, null otherwise (M5) */
+  findDependencyPath(fromId: string, toId: string): string[] | null {
+    const tasks = this.read().tasks;
+    const visited = new Set<string>();
+    const path: string[] = [];
+
+    function dfs(currentId: string): boolean {
+      if (currentId === toId) {
+        path.push(currentId);
+        return true;
+      }
+      if (visited.has(currentId)) return false;
+      visited.add(currentId);
+      path.push(currentId);
+      const task = tasks.find((t) => t.id === currentId);
+      if (task) {
+        for (const depId of task.blockedBy) {
+          if (dfs(depId)) return true;
+        }
+      }
+      path.pop();
+      return false;
+    }
+
+    return dfs(fromId) ? path : null;
+  }
+
+  /** Check if a task is blocked by incomplete dependencies (M5, M3) */
+  isTaskBlocked(taskId: string): { blocked: boolean; blockedBy: string[] } {
+    const tasks = this.read().tasks;
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task || task.blockedBy.length === 0) return { blocked: false, blockedBy: [] };
+    const incompleteDeps = task.blockedBy.filter((depId) => {
+      const dep = tasks.find((t) => t.id === depId);
+      return !dep || dep.status !== "completed";
+    });
+    return { blocked: incompleteDeps.length > 0, blockedBy: incompleteDeps };
+  }
+
+  /** Auto-claim next available task for a worker (M3) */
+  claimNextAvailable(workerName: string, options?: { excludeTaskIds?: string[] }): AcpTaskRecord | null {
+    const PRIORITY_ORDER: AcpTaskPriority[] = ["urgent", "high", "normal", "low"];
+    const payload = this.read();
+
+    const sorted = [...payload.tasks].sort((a, b) => {
+      const pi = PRIORITY_ORDER.indexOf(a.priority);
+      const bi = PRIORITY_ORDER.indexOf(b.priority);
+      if (pi !== bi) return pi - bi;
+      return parseInt(a.id) - parseInt(b.id);
+    });
+
+    const exclude = new Set(options?.excludeTaskIds ?? []);
+
+    for (const task of sorted) {
+      if (task.status !== "pending") continue;
+      if (task.assignee) continue;
+      if (exclude.has(task.id)) continue;
+      // Check blocked
+      const incompleteDeps = task.blockedBy.filter((depId) => {
+        const dep = payload.tasks.find((t) => t.id === depId);
+        return !dep || dep.status !== "completed";
+      });
+      if (incompleteDeps.length > 0) continue;
+      // Check retry exhausted
+      if (task.metadata?.retryExhausted === true) continue;
+      // Check cooldown
+      if (
+        task.metadata?.cooldownUntil &&
+        new Date(task.metadata.cooldownUntil as string) > new Date()
+      )
+        continue;
+      // Claim
+      task.assignee = workerName;
+      task.status = "in_progress";
+      task.metadata.claimedAt = new Date().toISOString();
+      task.updatedAt = new Date().toISOString();
+      this.write(payload);
+      return task;
+    }
+    return null;
+  }
+
+  private read(): AcpTaskStorePayload {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      if (!existsSync(paths.tasksFile)) {
+        return structuredClone(DEFAULT_PAYLOAD);
+      }
+      const parsed = JSON.parse(readFileSync(paths.tasksFile, "utf-8")) as AcpTaskStorePayload;
+      // Migration: add defaults for legacy records
+      for (const task of parsed.tasks) {
+        if (!task.blocks) task.blocks = [];
+        if (!task.priority) task.priority = "normal";
+        if (!task.metadata) task.metadata = {};
+      }
+      return parsed;
+    } catch (e) {
+      // File read failed — return default payload
+      log.debug("task-store read failed", e);
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+  }
+
+  private write(payload: AcpTaskStorePayload): void {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      writeFileSync(paths.tasksFile, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    } catch (e) {
+      // File read failed — return default payload
+      // EACCES or other FS error — silently degrade. Tasks are non-critical runtime state.
+      log.debug("task-store write failed", e);
+    }
+  }
+}