@buihongduc132/pi-acp-agents 0.3.1

package/src/extension-safety.ts

@@ -0,0 +1,200 @@
+/**
+ * pi-acp-agents — Extension safety module (R-SP1, R-SP4).
+ *
+ * Provides base-detection, safe activation guards, and version
+ * compatibility checks for the pi-acp-advanced extension package.
+ *
+ * R-SP1: Extension MUST fail loudly but never crash when base is missing.
+ * R-SP4: Extension MUST declare and verify minimum base version.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ── R-SP1: Base detection ──────────────────────────────────────────────────
+
+export interface BaseDetectionResult {
+	/** Whether the base package runtime is available */
+	ok: boolean;
+	/** Runtime directory path (only when ok=true) */
+	runtimeDir?: string;
+	/** Config file path (only when ok=true) */
+	configFile?: string;
+	/** Human-readable warning (only when ok=false) */
+	warning?: string;
+	/** Base version string (only when ok=true and detectable) */
+	baseVersion?: string;
+}
+
+/**
+ * Detect whether the pi-acp-agents base package is loaded and configured.
+ *
+ * Checks:
+ * 1. Runtime directory exists (~/.pi/acp-agents/)
+ * 2. Config file exists (~/.pi/acp-agents/config.json)
+ * 3. Config contains at least one agent_server entry (base is initialized)
+ *
+ * Returns a result object with ok=true/false and context.
+ */
+export function detectBaseLoaded(runtimeDirOverride?: string): BaseDetectionResult {
+	const runtimeDir = runtimeDirOverride ?? join(homedir(), ".pi", "acp-agents");
+	const configFile = join(runtimeDir, "config.json");
+
+	if (!existsSync(runtimeDir)) {
+		return {
+			ok: false,
+			warning: `⚠️ pi-acp-advanced requires pi-acp-agents to be installed and loaded first.\n   Runtime dir missing: ${runtimeDir}\n   Fix: Add "npm:pi-acp-agents" to your settings.json packages BEFORE "npm:pi-acp-advanced".\n   Extension is inactive until base is available.`,
+		};
+	}
+
+	if (!existsSync(configFile)) {
+		return {
+			ok: false,
+			warning: `⚠️ pi-acp-advanced requires pi-acp-agents config at ${configFile}.\n   Fix: Add "npm:pi-acp-agents" to your settings.json BEFORE "npm:pi-acp-advanced".\n   Extension is inactive until base is available.`,
+		};
+	}
+
+	// Config exists — check if base has been initialized (has agent_servers)
+	let baseVersion: string | undefined;
+	try {
+		const raw = readFileSync(configFile, "utf-8");
+		const config = JSON.parse(raw);
+		const hasAgents = config.agent_servers && Object.keys(config.agent_servers).length > 0;
+		if (!hasAgents) {
+			return {
+				ok: false,
+				warning: `⚠️ pi-acp-agents runtime dir exists but no agents are configured.\n   Fix: Configure at least one agent in ${configFile}, then restart pi.\n   Extension is inactive until base has agents.`,
+			};
+		}
+		// Try to read base version from package.json in parent dir
+		try {
+			const pkgPath = join(runtimeDir, "../../agent/git/github.com/buihongduc132/pi-acp-agents/package.json");
+			if (existsSync(pkgPath)) {
+				baseVersion = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+			}
+		} catch {
+			// Version detection is best-effort
+		}
+	} catch {
+		// Corrupt config file — treat as not loaded
+		return {
+			ok: false,
+			warning: `⚠️ pi-acp-agents config file at ${configFile} is corrupt or unreadable.\n   Fix: Restore a valid config.json or reconfigure pi-acp-agents.`,
+		};
+	}
+
+	return { ok: true, runtimeDir, configFile, baseVersion };
+}
+
+// ── R-SP1: Safe activation guard ───────────────────────────────────────────
+
+export interface ActivationResult {
+	activated: boolean;
+	warning?: string;
+}
+
+/**
+ * Attempt to activate the extension safely.
+ *
+ * If base is not loaded, returns { activated: false, warning: ... }.
+ * If base is loaded, returns { activated: true }.
+ *
+ * Never throws — caller should use the result to decide whether
+ * to register tools.
+ */
+export function activateExtensionSafely(runtimeDirOverride?: string): ActivationResult {
+	try {
+		const detection = detectBaseLoaded(runtimeDirOverride);
+		if (!detection.ok) {
+			return { activated: false, warning: detection.warning };
+		}
+		return { activated: true };
+	} catch (err) {
+		// Absolute safety net — never crash
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			activated: false,
+			warning: `⚠️ pi-acp-advanced failed during base detection: ${msg}\n   Extension is inactive. Fix the error above and restart pi.`,
+		};
+	}
+}
+
+// ── R-SP4: Version compatibility ───────────────────────────────────────────
+
+export interface VersionCheckResult {
+	compatible: boolean;
+	currentVersion?: string;
+	requiredVersion: string;
+	warning?: string;
+}
+
+/** Minimum base version required by the extension */
+export const MIN_BASE_VERSION = "0.3.0";
+
+/**
+ * Parse a semver string into [major, minor, patch].
+ * Returns null for invalid input.
+ */
+function parseSemver(version: string): [number, number, number] | null {
+	const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+	if (!match) return null;
+	return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+
+/**
+ * Compare two semver tuples: returns -1 if a < b, 0 if equal, 1 if a > b.
+ */
+function compareSemver(a: [number, number, number], b: [number, number, number]): number {
+	if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+	if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
+	if (a[2] !== b[2]) return a[2] < b[2] ? -1 : 1;
+	return 0;
+}
+
+/**
+ * Check whether the detected base version is compatible with the extension.
+ *
+ * @param baseVersion The version string detected from the base package
+ * @param requiredVersion Minimum required version (default: MIN_BASE_VERSION)
+ * @returns VersionCheckResult with compatibility status
+ */
+export function checkVersionCompatibility(
+	baseVersion: string | undefined,
+	requiredVersion: string = MIN_BASE_VERSION,
+): VersionCheckResult {
+	if (!baseVersion) {
+		return {
+			compatible: false,
+			requiredVersion,
+			warning: `⚠️ Cannot determine pi-acp-agents version. Extension requires >=${requiredVersion}.\n   Fix: Ensure pi-acp-agents is installed and properly initialized.`,
+		};
+	}
+
+	const current = parseSemver(baseVersion);
+	const required = parseSemver(requiredVersion);
+
+	if (!current) {
+		return {
+			compatible: false,
+			currentVersion: baseVersion,
+			requiredVersion,
+			warning: `⚠️ Invalid base version format: "${baseVersion}". Expected semver (e.g., 0.3.0).`,
+		};
+	}
+
+	if (!required) {
+		// If required version is invalid, assume compatible (don't block)
+		return { compatible: true, currentVersion: baseVersion, requiredVersion };
+	}
+
+	if (compareSemver(current, required) < 0) {
+		return {
+			compatible: false,
+			currentVersion: baseVersion,
+			requiredVersion,
+			warning: `⚠️ pi-acp-advanced requires pi-acp-agents >=${requiredVersion} (found: ${baseVersion}).\n   Fix: npm i pi-acp-agents@latest`,
+		};
+	}
+
+	return { compatible: true, currentVersion: baseVersion, requiredVersion };
+}

package/src/logger.ts

@@ -0,0 +1,92 @@
+/**
+ * Logger — central logging for ACP agent interactions.
+ */
+import { mkdirSync, appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Logger {
+  info(msg: string, data?: unknown): void;
+  error(msg: string, data?: unknown): void;
+  debug(msg: string, data?: unknown): void;
+}
+
+/** No-op logger — all methods do nothing */
+export function createNoopLogger(): Logger {
+  return {
+    info() {},
+    error() {},
+    debug() {},
+  };
+}
+
+/** File logger — writes JSON lines to a log directory */
+export function createFileLogger(logsDir: string, sessionId?: string): Logger {
+  if (!existsSync(logsDir)) {
+    try {
+      mkdirSync(logsDir, { recursive: true });
+    } catch (err) {
+      console.log("[acp-logger] failed to create logsDir:", err);
+    }
+  }
+
+  const mainLogPath = join(logsDir, "main.log");
+
+  function write(level: string, msg: string, data?: unknown): void {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      msg,
+      ...(data !== undefined ? { data } : {}),
+    };
+    try {
+      appendFileSync(mainLogPath, JSON.stringify(entry) + "\n", "utf-8");
+    } catch (err) {
+      console.log("[acp-logger] failed to write main log:", err);
+    }
+  }
+
+  if (sessionId) {
+    const sessionDir = join(logsDir, sessionId);
+    if (!existsSync(sessionDir)) {
+      try {
+        mkdirSync(sessionDir, { recursive: true });
+      } catch (err) {
+        console.log("[acp-logger] failed to create sessionDir:", err);
+      }
+    }
+    const tracePath = join(sessionDir, "trace.jsonl");
+
+    return {
+      info(msg, data) {
+        write("info", msg, data);
+        try {
+          appendFileSync(tracePath, JSON.stringify({ timestamp: new Date().toISOString(), level: "info", msg, data }) + "\n", "utf-8");
+        } catch (err) {
+          console.log("[acp-logger] failed to write trace:", err);
+        }
+      },
+      error(msg, data) {
+        write("error", msg, data);
+        try {
+          appendFileSync(tracePath, JSON.stringify({ timestamp: new Date().toISOString(), level: "error", msg, data }) + "\n", "utf-8");
+        } catch (err) {
+          console.log("[acp-logger] failed to write trace:", err);
+        }
+      },
+      debug(msg, data) {
+        write("debug", msg, data);
+        try {
+          appendFileSync(tracePath, JSON.stringify({ timestamp: new Date().toISOString(), level: "debug", msg, data }) + "\n", "utf-8");
+        } catch (err) {
+          console.log("[acp-logger] failed to write trace:", err);
+        }
+      },
+    };
+  }
+
+  return {
+    info(msg, data) { write("info", msg, data); },
+    error(msg, data) { write("error", msg, data); },
+    debug(msg, data) { write("debug", msg, data); },
+  };
+}

package/src/management/event-log.ts

@@ -0,0 +1,31 @@
+import { appendFileSync } from "node:fs";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+export interface AcpEventLogEntry {
+  timestamp: string;
+  type: string;
+  data?: Record<string, unknown>;
+}
+
+export class AcpEventLog {
+  constructor(private rootDir?: string) {}
+
+  append(type: string, data?: Record<string, unknown>): AcpEventLogEntry {
+    const entry: AcpEventLogEntry = {
+      timestamp: new Date().toISOString(),
+      type,
+      ...(data ? { data } : {}),
+    };
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      appendFileSync(paths.eventLogFile, JSON.stringify(entry) + "\n", "utf-8");
+    } catch (e) {
+      // EACCES or other FS error — silently degrade. Event log is non-critical.
+      log.debug("event log write failed", e);
+    }
+    return entry;
+  }
+}

package/src/management/governance-store.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+export interface PlanApprovalRequest {
+  agent: string;
+  status: "pending" | "approved" | "rejected";
+  requestedAt: string;
+  resolvedAt?: string;
+  feedback?: string;
+}
+
+export interface ModelPolicyState {
+  allowedModels: string[];
+  blockedModels: string[];
+  requireProviderPrefix: boolean;
+}
+
+interface GovernancePayload {
+  planApprovals: Record<string, PlanApprovalRequest>;
+  modelPolicy: ModelPolicyState;
+}
+
+const DEFAULT_PAYLOAD: GovernancePayload = {
+  planApprovals: {},
+  modelPolicy: {
+    allowedModels: [],
+    blockedModels: [],
+    requireProviderPrefix: false,
+  },
+};
+
+export class GovernanceStore {
+  constructor(private rootDir?: string) {}
+
+  getPlan(agent: string): PlanApprovalRequest | undefined {
+    return this.read().planApprovals[agent];
+  }
+
+  requestPlan(agent: string): PlanApprovalRequest {
+    const payload = this.read();
+    const plan: PlanApprovalRequest = {
+      agent,
+      status: "pending",
+      requestedAt: new Date().toISOString(),
+    };
+    payload.planApprovals[agent] = plan;
+    this.write(payload);
+    return plan;
+  }
+
+  resolvePlan(agent: string, status: "approved" | "rejected", feedback?: string): PlanApprovalRequest {
+    const payload = this.read();
+    const existing = payload.planApprovals[agent] ?? {
+      agent,
+      status: "pending" as const,
+      requestedAt: new Date().toISOString(),
+    };
+    existing.status = status;
+    existing.feedback = feedback;
+    existing.resolvedAt = new Date().toISOString();
+    payload.planApprovals[agent] = existing;
+    this.write(payload);
+    return existing;
+  }
+
+  getModelPolicy(): ModelPolicyState {
+    return this.read().modelPolicy;
+  }
+
+  setModelPolicy(policy: Partial<ModelPolicyState>): ModelPolicyState {
+    const payload = this.read();
+    payload.modelPolicy = {
+      ...payload.modelPolicy,
+      ...policy,
+      allowedModels: policy.allowedModels ?? payload.modelPolicy.allowedModels,
+      blockedModels: policy.blockedModels ?? payload.modelPolicy.blockedModels,
+    };
+    this.write(payload);
+    return payload.modelPolicy;
+  }
+
+  checkModel(model?: string): { ok: boolean; reason: string } {
+    const policy = this.getModelPolicy();
+    if (!model) return { ok: true, reason: "no model override provided" };
+    if (policy.requireProviderPrefix && !model.includes("/")) {
+      return { ok: false, reason: "model must include provider/model format" };
+    }
+    if (policy.blockedModels.includes(model)) {
+      return { ok: false, reason: `model \"${model}\" is blocked` };
+    }
+    if (policy.allowedModels.length > 0 && !policy.allowedModels.includes(model)) {
+      return { ok: false, reason: `model \"${model}\" is not in allowed list` };
+    }
+    return { ok: true, reason: "model allowed" };
+  }
+
+  private read(): GovernancePayload {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      if (!existsSync(paths.governanceFile)) {
+        return structuredClone(DEFAULT_PAYLOAD);
+      }
+      return JSON.parse(readFileSync(paths.governanceFile, "utf-8")) as GovernancePayload;
+    } catch (e) {
+      // EACCES, corrupt file, etc — degrade gracefully, don't crash the extension
+      log.debug("governance-store read failed", e);
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+  }
+
+  private write(payload: GovernancePayload): void {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      writeFileSync(paths.governanceFile, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    } catch (e) {
+      // EACCES or other FS error — silently degrade. Governance is non-critical state.
+      log.debug("governance-store write failed", e);
+    }
+  }
+}

package/src/management/heartbeat-parser.ts

@@ -0,0 +1,92 @@
+/**
+ * Heartbeat delta parsing — defensive parsing for ACP session/update events.
+ *
+ * Task 2.2: malformed/missing fields are treated as zero-delta rather than
+ * crashing the heartbeat consumer. A thrown error is propagated to the caller
+ * so it can be logged via `AcpEventLog` (`heartbeat_parse_error`).
+ */
+import type { SessionUpdate } from "@agentclientprotocol/sdk";
+
+export interface HeartbeatDeltas {
+	tokenDelta: number;
+	toolCallDelta: number;
+}
+
+/**
+ * Dependencies for {@link consumeHeartbeat}. Injected so the consumer is a
+ * pure, testable function (no filesystem / global state required in tests).
+ */
+export interface HeartbeatConsumerDeps {
+	/** Resolve the worker name bound to a session id (undefined = not worker-bound). */
+	resolveWorkerName(sessionId: string): string | undefined;
+	/** Apply deltas to a worker (wraps `WorkerStore.touch`). May throw. */
+	touch(
+		name: string,
+		deltas?: { tokenDelta?: number; toolCallDelta?: number },
+	): unknown;
+	/** Log a malformed/unexpected event to `AcpEventLog` (`heartbeat_parse_error`). */
+	logParseError(entry: {
+		workerName: string;
+		sessionId: string;
+		error: string;
+	}): void;
+}
+
+/**
+ * Parse token/tool deltas from a single session/update event.
+ *
+ * - `usage_update`: extracts `used` tokens; missing/non-number `used`/`size`
+ *   are treated as zero (defensive).
+ * - `tool_call`: counts as one tool call.
+ * - Any other (or missing) `sessionUpdate`: zero-delta.
+ *
+ * @throws never for malformed input — defensive guards handle all shapes.
+ */
+export function parseHeartbeatDeltas(update: SessionUpdate): HeartbeatDeltas {
+	const updateRec = update as Record<string, unknown>;
+	const updateType = updateRec.sessionUpdate;
+	let tokenDelta = 0;
+	let toolCallDelta = 0;
+
+	if (updateType === "usage_update") {
+		// Defensive: treat missing/non-number 'used' as zero-delta
+		const used = typeof updateRec.used === "number" ? updateRec.used : 0;
+		const size = typeof updateRec.size === "number" ? updateRec.size : 0;
+		tokenDelta = used;
+		void size; // size is total context window, not useful as delta
+	} else if (updateType === "tool_call") {
+		toolCallDelta = 1;
+	}
+
+	return { tokenDelta, toolCallDelta };
+}
+
+/**
+ * Heartbeat consumer — process a single ACP `session/update` for a
+ * worker-bound session: defensively parse deltas, apply them via
+ * `WorkerStore.touch`, and log any thrown error as `heartbeat_parse_error`
+ * without crashing the event stream.
+ *
+ * (Tasks 2.1 + 2.2: defensive parsing built-in via {@link parseHeartbeatDeltas}.)
+ *
+ * Exported so it is unit-testable; the production wiring in `index.ts`
+ * delegates to this function.
+ */
+export function consumeHeartbeat(
+	deps: HeartbeatConsumerDeps,
+	sessionId: string,
+	update: SessionUpdate,
+): void {
+	const workerName = deps.resolveWorkerName(sessionId);
+	if (!workerName) return; // Not a worker-bound session
+	try {
+		const { tokenDelta, toolCallDelta } = parseHeartbeatDeltas(update);
+		deps.touch(workerName, { tokenDelta, toolCallDelta });
+	} catch (err) {
+		deps.logParseError({
+			workerName,
+			sessionId,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}

package/src/management/mailbox-manager.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureRuntimeDir } from "./runtime-paths.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+export interface MailMessage {
+  id: string;
+  from: string;
+  to: string;
+  message: string;
+  kind: "dm" | "steer" | "broadcast";
+  createdAt: string;
+  readAt?: string;
+}
+
+interface MailboxPayload {
+  nextId: number;
+  messages: MailMessage[];
+}
+
+const DEFAULT_PAYLOAD: MailboxPayload = {
+  nextId: 1,
+  messages: [],
+};
+
+export class MailboxManager {
+  constructor(private rootDir?: string) {}
+
+  send(input: { from: string; to: string; message: string; kind: MailMessage["kind"] }): MailMessage {
+    const payload = this.read();
+    const mail: MailMessage = {
+      id: String(payload.nextId++),
+      from: input.from,
+      to: input.to,
+      message: input.message,
+      kind: input.kind,
+      createdAt: new Date().toISOString(),
+    };
+    payload.messages.push(mail);
+    this.write(payload);
+    return mail;
+  }
+
+  listFor(recipient: string): MailMessage[] {
+    return this.read().messages.filter((message) => message.to === recipient || message.to === "*");
+  }
+
+  markRead(messageId: string): MailMessage {
+    const payload = this.read();
+    const message = payload.messages.find((item) => item.id === messageId);
+    if (!message) throw new Error(`Message \"${messageId}\" not found`);
+    message.readAt = new Date().toISOString();
+    this.write(payload);
+    return message;
+  }
+
+  clearFor(recipient: string): number {
+    const payload = this.read();
+    const before = payload.messages.length;
+    payload.messages = payload.messages.filter((message) => !(message.to === recipient || message.to === "*"));
+    this.write(payload);
+    return before - payload.messages.length;
+  }
+
+  /** List all messages across all recipients. */
+  listAll(): MailMessage[] {
+    return this.read().messages;
+  }
+
+  private read(): MailboxPayload {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      if (!existsSync(paths.mailboxesFile)) {
+        return structuredClone(DEFAULT_PAYLOAD);
+      }
+      return JSON.parse(readFileSync(paths.mailboxesFile, "utf-8")) as MailboxPayload;
+    } catch (e) {
+      // File read failed — return default payload
+      log.debug("mailbox-manager read failed", e);
+      return structuredClone(DEFAULT_PAYLOAD);
+    }
+  }
+
+  private write(payload: MailboxPayload): void {
+    try {
+      const paths = ensureRuntimeDir(this.rootDir);
+      writeFileSync(paths.mailboxesFile, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    } catch (e) {
+      // File read failed — return default payload
+      // EACCES or other FS error — silently degrade. Mailboxes are non-critical runtime state.
+      log.debug("mailbox-manager write failed", e);
+    }
+  }
+}

package/src/management/runtime-paths.ts

@@ -0,0 +1,34 @@
+import { safeMkdir } from "./safe-mkdir.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface AcpRuntimePaths {
+  rootDir: string;
+  tasksFile: string;
+  mailboxesFile: string;
+  governanceFile: string;
+  eventLogFile: string;
+  sessionArchiveFile: string;
+  sessionNameRegistryFile: string;
+  workersFile: string;
+}
+
+export function getRuntimePaths(rootDir?: string): AcpRuntimePaths {
+  const base = rootDir ?? join(homedir(), ".pi", "acp-agents", "runtime");
+  return {
+    rootDir: base,
+    tasksFile: join(base, "tasks.json"),
+    mailboxesFile: join(base, "mailboxes.json"),
+    governanceFile: join(base, "governance.json"),
+    eventLogFile: join(base, "events.jsonl"),
+    sessionArchiveFile: join(base, "session-archive.json"),
+    sessionNameRegistryFile: join(base, "session-name-registry.json"),
+    workersFile: join(base, "workers.json"),
+  };
+}
+
+export function ensureRuntimeDir(rootDir?: string): AcpRuntimePaths {
+  const paths = getRuntimePaths(rootDir);
+  safeMkdir(paths.rootDir);
+  return paths;
+}