@gotgenes/pi-permission-system 3.7.0 → 3.9.0

package/src/runtime.ts

@@ -0,0 +1,484 @@
+import {
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, normalize } from "node:path";
+import {
+  type ExtensionCommandContext,
+  type ExtensionContext,
+  getAgentDir,
+} from "@mariozechner/pi-coding-agent";
+import {
+  getActiveAgentName,
+  getActiveAgentNameFromSystemPrompt,
+} from "./active-agent";
+import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
+import {
+  DEBUG_LOG_FILENAME,
+  getGlobalConfigPath,
+  getGlobalLogsDir,
+  getLegacyExtensionConfigPath,
+  getLegacyGlobalPolicyPath,
+  getLegacyProjectPolicyPath,
+  getProjectConfigPath,
+  REVIEW_LOG_FILENAME,
+} from "./config-paths";
+import { buildResolvedConfigLogEntry } from "./config-reporter";
+import {
+  DEFAULT_EXTENSION_CONFIG,
+  EXTENSION_ROOT,
+  ensurePermissionSystemLogsDirectory,
+  normalizePermissionSystemConfig,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config";
+import {
+  confirmPermission,
+  type PermissionForwardingDeps,
+  processForwardedPermissionRequests,
+} from "./forwarded-permissions/polling";
+import type { PromptPermissionDetails } from "./handlers/types";
+import { createPermissionSystemLogger } from "./logging";
+import type { PermissionPromptDecision } from "./permission-dialog";
+import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import { PermissionManager } from "./permission-manager";
+import { SessionApprovalCache } from "./session-approval-cache";
+import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
+import { syncPermissionSystemStatus } from "./status";
+import { isSubagentExecutionContext } from "./subagent-context";
+import { shouldAutoApprovePermissionState } from "./yolo-mode";
+
+/**
+ * Runtime context object created once inside `piPermissionSystemExtension()`.
+ *
+ * Holds all path constants (derived from `getAgentDir()` at construction time),
+ * mutable extension state, and the log-writing methods — eliminating the
+ * module-scope cached constants and setter-injection pattern that previously
+ * lived in `src/index.ts`.
+ *
+ * Tests construct this via `createExtensionRuntime({ agentDir: tmpDir })`
+ * without timing issues around `PI_CODING_AGENT_DIR`.
+ */
+export interface ExtensionRuntime {
+  // ── Immutable paths (derived from agentDir at construction) ───────────
+  readonly agentDir: string;
+  readonly sessionsDir: string;
+  readonly subagentSessionsDir: string;
+  readonly forwardingDir: string;
+  readonly globalLogsDir: string;
+
+  // ── Mutable state ──────────────────────────────────────────────────────
+  config: PermissionSystemExtensionConfig;
+  runtimeContext: ExtensionContext | null;
+  permissionManager: PermissionManager;
+  activeSkillEntries: SkillPromptEntry[];
+  lastKnownActiveAgentName: string | null;
+  lastActiveToolsCacheKey: string | null;
+  lastPromptStateCacheKey: string | null;
+  lastConfigWarning: string | null;
+  readonly sessionApprovalCache: SessionApprovalCache;
+
+  // ── Forwarding polling state ───────────────────────────────────────────
+  permissionForwardingContext: ExtensionContext | null;
+  permissionForwardingTimer: NodeJS.Timeout | null;
+  isProcessingForwardedRequests: boolean;
+
+  // ── Logging (backed by logger created at construction) ─────────────────
+  writeDebugLog(event: string, details?: Record<string, unknown>): void;
+  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+}
+
+// ── Pure helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Derive Pi project-level config and agents paths from a working directory.
+ * Returns null when cwd is absent (headless / global-only config).
+ */
+export function derivePiProjectPaths(cwd: string | undefined | null): {
+  projectGlobalConfigPath: string;
+  projectAgentsDir: string;
+} | null {
+  if (!cwd) {
+    return null;
+  }
+  return {
+    projectGlobalConfigPath: getProjectConfigPath(cwd),
+    projectAgentsDir: join(cwd, ".pi", "agent", "agents"),
+  };
+}
+
+/**
+ * Create a new PermissionManager scoped to a working directory's config hierarchy.
+ * Pass `cwd` as null/undefined to use global config only.
+ */
+export function createPermissionManagerForCwd(
+  agentDir: string,
+  cwd: string | undefined | null,
+): PermissionManager {
+  const projectPaths = derivePiProjectPaths(cwd);
+  return new PermissionManager({
+    globalConfigPath: getGlobalConfigPath(agentDir),
+    projectGlobalConfigPath: projectPaths?.projectGlobalConfigPath,
+    projectAgentsDir: projectPaths?.projectAgentsDir,
+  });
+}
+
+/**
+ * Reload merged config from disk into the runtime.
+ * If `ctx` is provided, updates `runtime.runtimeContext` first.
+ */
+export function refreshExtensionConfig(
+  runtime: ExtensionRuntime,
+  ctx?: ExtensionContext,
+): void {
+  if (ctx) {
+    runtime.runtimeContext = ctx;
+  }
+  const cwd = runtime.runtimeContext?.cwd ?? null;
+  const mergeResult = loadAndMergeConfigs(
+    runtime.agentDir,
+    cwd ?? "",
+    EXTENSION_ROOT,
+  );
+  const runtimeConfig = normalizePermissionSystemConfig(mergeResult.merged);
+  runtime.config = runtimeConfig;
+
+  if (runtime.runtimeContext?.hasUI) {
+    syncPermissionSystemStatus(runtime.runtimeContext, runtimeConfig);
+  }
+
+  const warning =
+    mergeResult.issues.length > 0 ? mergeResult.issues.join("\n") : undefined;
+
+  if (warning && warning !== runtime.lastConfigWarning) {
+    runtime.lastConfigWarning = warning;
+    runtime.runtimeContext?.ui.notify(warning, "warning");
+  } else if (!warning) {
+    runtime.lastConfigWarning = null;
+  }
+
+  runtime.writeDebugLog("config.loaded", {
+    warning: warning ?? null,
+    debugLog: runtimeConfig.debugLog,
+    permissionReviewLog: runtimeConfig.permissionReviewLog,
+    yoloMode: runtimeConfig.yoloMode,
+  });
+}
+
+/**
+ * Save updated runtime knobs (debugLog, permissionReviewLog, yoloMode) to the
+ * global config file, then update runtime.config and sync UI status.
+ */
+export function saveExtensionConfig(
+  runtime: ExtensionRuntime,
+  next: PermissionSystemExtensionConfig,
+  ctx: ExtensionCommandContext,
+): void {
+  const normalized = normalizePermissionSystemConfig(next);
+  const globalPath = getGlobalConfigPath(runtime.agentDir);
+
+  const existing = loadUnifiedConfig(globalPath);
+  const merged = {
+    ...existing.config,
+    debugLog: normalized.debugLog,
+    permissionReviewLog: normalized.permissionReviewLog,
+    yoloMode: normalized.yoloMode,
+  };
+
+  const tmpPath = `${globalPath}.tmp`;
+  try {
+    mkdirSync(dirname(globalPath), { recursive: true });
+    writeFileSync(tmpPath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+    renameSync(tmpPath, globalPath);
+  } catch (error) {
+    try {
+      if (existsSync(tmpPath)) {
+        unlinkSync(tmpPath);
+      }
+    } catch {
+      // Ignore cleanup failures.
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(
+      `Failed to save permission-system config at '${globalPath}': ${message}`,
+      "error",
+    );
+    return;
+  }
+
+  runtime.config = normalized;
+  syncPermissionSystemStatus(ctx, normalized);
+  runtime.lastConfigWarning = null;
+
+  runtime.writeDebugLog("config.saved", {
+    debugLog: normalized.debugLog,
+    permissionReviewLog: normalized.permissionReviewLog,
+    yoloMode: normalized.yoloMode,
+  });
+}
+
+/**
+ * Resolve the active agent name from the Pi session, system prompt, or last
+ * known name. Updates `runtime.lastKnownActiveAgentName` as a side effect.
+ */
+export function resolveAgentName(
+  runtime: ExtensionRuntime,
+  ctx: ExtensionContext,
+  systemPrompt?: string,
+): string | null {
+  const fromSession = getActiveAgentName(ctx);
+  if (fromSession) {
+    runtime.lastKnownActiveAgentName = fromSession;
+    return fromSession;
+  }
+  const fromSystemPrompt = getActiveAgentNameFromSystemPrompt(systemPrompt);
+  if (fromSystemPrompt) {
+    runtime.lastKnownActiveAgentName = fromSystemPrompt;
+    return fromSystemPrompt;
+  }
+  return runtime.lastKnownActiveAgentName;
+}
+
+/**
+ * Write the resolved config path set (global, project, legacy) to the review
+ * and debug logs.
+ */
+export function logResolvedConfigPaths(runtime: ExtensionRuntime): void {
+  const policyPaths = runtime.permissionManager.getResolvedPolicyPaths();
+  const cwd = runtime.runtimeContext?.cwd ?? null;
+  const { agentDir } = runtime;
+  const legacyGlobalPolicyDetected = existsSync(
+    getLegacyGlobalPolicyPath(agentDir),
+  );
+  const legacyProjectPolicyDetected = cwd
+    ? existsSync(getLegacyProjectPolicyPath(cwd))
+    : false;
+  const legacyExtConfigPath = getLegacyExtensionConfigPath(EXTENSION_ROOT);
+  const newGlobalPath = getGlobalConfigPath(agentDir);
+  const legacyExtensionConfigDetected =
+    normalize(legacyExtConfigPath) !== normalize(newGlobalPath) &&
+    existsSync(legacyExtConfigPath);
+  const entry = buildResolvedConfigLogEntry({
+    policyPaths,
+    legacyGlobalPolicyDetected,
+    legacyProjectPolicyDetected,
+    legacyExtensionConfigDetected,
+  });
+  runtime.writeReviewLog(
+    "config.resolved",
+    entry as unknown as Record<string, unknown>,
+  );
+  runtime.writeDebugLog(
+    "config.resolved",
+    entry as unknown as Record<string, unknown>,
+  );
+}
+
+// ── Permission helpers ─────────────────────────────────────────────────────
+
+/** Internal: write a structured permission decision entry to the review log. */
+function reviewPermissionDecision(
+  writeReviewLog: (event: string, details: Record<string, unknown>) => void,
+  event: string,
+  details: PromptPermissionDetails & {
+    resolution?: string;
+    denialReason?: string;
+  },
+): void {
+  writeReviewLog(event, {
+    requestId: details.requestId,
+    source: details.source,
+    agentName: details.agentName,
+    message: details.message,
+    toolCallId: details.toolCallId ?? null,
+    toolName: details.toolName ?? null,
+    skillName: details.skillName ?? null,
+    path: details.path ?? null,
+    command: details.command ?? null,
+    target: details.target ?? null,
+    toolInputPreview: details.toolInputPreview ?? null,
+    resolution: details.resolution ?? null,
+    denialReason: details.denialReason ?? null,
+  });
+}
+
+/**
+ * Prompt the user for a permission decision using the forwarding flow,
+ * log the waiting / approved / denied outcome, and return the decision.
+ * In yolo mode, auto-approves without prompting.
+ */
+export async function promptPermission(
+  runtime: ExtensionRuntime,
+  forwardingDeps: PermissionForwardingDeps,
+  ctx: ExtensionContext,
+  details: PromptPermissionDetails,
+): Promise<PermissionPromptDecision> {
+  if (shouldAutoApprovePermissionState("ask", runtime.config)) {
+    reviewPermissionDecision(
+      runtime.writeReviewLog,
+      "permission_request.auto_approved",
+      details,
+    );
+    return { approved: true, state: "approved" };
+  }
+  reviewPermissionDecision(
+    runtime.writeReviewLog,
+    "permission_request.waiting",
+    details,
+  );
+  const decision = await confirmPermission(
+    ctx,
+    details.message,
+    forwardingDeps,
+  );
+  reviewPermissionDecision(
+    runtime.writeReviewLog,
+    decision.approved
+      ? "permission_request.approved"
+      : "permission_request.denied",
+    {
+      ...details,
+      resolution: decision.state,
+      denialReason: decision.denialReason,
+    },
+  );
+  return decision;
+}
+
+// ── Forwarding polling lifecycle ───────────────────────────────────────────
+
+/** Stop the forwarded-permission polling interval and clear related state. */
+export function stopForwardedPermissionPolling(
+  runtime: ExtensionRuntime,
+): void {
+  if (runtime.permissionForwardingTimer) {
+    clearInterval(runtime.permissionForwardingTimer);
+    runtime.permissionForwardingTimer = null;
+  }
+  runtime.permissionForwardingContext = null;
+  runtime.isProcessingForwardedRequests = false;
+}
+
+/**
+ * Start the forwarded-permission polling interval.
+ * No-ops (and stops any existing poll) when the context has no UI or is a
+ * subagent execution context.
+ */
+export function startForwardedPermissionPolling(
+  runtime: ExtensionRuntime,
+  forwardingDeps: PermissionForwardingDeps,
+  ctx: ExtensionContext,
+): void {
+  if (
+    !ctx.hasUI ||
+    isSubagentExecutionContext(ctx, runtime.subagentSessionsDir)
+  ) {
+    stopForwardedPermissionPolling(runtime);
+    return;
+  }
+  runtime.permissionForwardingContext = ctx;
+  if (runtime.permissionForwardingTimer) {
+    return;
+  }
+  runtime.permissionForwardingTimer = setInterval(() => {
+    if (
+      !runtime.permissionForwardingContext ||
+      runtime.isProcessingForwardedRequests
+    ) {
+      return;
+    }
+    runtime.isProcessingForwardedRequests = true;
+    void processForwardedPermissionRequests(
+      runtime.permissionForwardingContext,
+      forwardingDeps,
+    ).finally(() => {
+      runtime.isProcessingForwardedRequests = false;
+    });
+  }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
+}
+
+// ── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create a fully-initialized `ExtensionRuntime`.
+ *
+ * Calls `getAgentDir()` at invocation time (never at module scope), so tests
+ * may set `PI_CODING_AGENT_DIR` before calling the factory.
+ */
+export function createExtensionRuntime(options?: {
+  agentDir?: string;
+}): ExtensionRuntime {
+  const agentDir = options?.agentDir ?? getAgentDir();
+  const sessionsDir = join(agentDir, "sessions");
+  const subagentSessionsDir = join(agentDir, "subagent-sessions");
+  const forwardingDir = join(sessionsDir, "permission-forwarding");
+  const globalLogsDir = getGlobalLogsDir(agentDir);
+
+  // Build a plain-object runtime first so the logger's `getConfig` closure
+  // can reference `runtime.config` directly (always reads current value).
+  const runtime: ExtensionRuntime = {
+    agentDir,
+    sessionsDir,
+    subagentSessionsDir,
+    forwardingDir,
+    globalLogsDir,
+    config: { ...DEFAULT_EXTENSION_CONFIG },
+    runtimeContext: null,
+    permissionManager: createPermissionManagerForCwd(agentDir, undefined),
+    activeSkillEntries: [],
+    lastKnownActiveAgentName: null,
+    lastActiveToolsCacheKey: null,
+    lastPromptStateCacheKey: null,
+    lastConfigWarning: null,
+    sessionApprovalCache: new SessionApprovalCache(),
+    permissionForwardingContext: null,
+    permissionForwardingTimer: null,
+    isProcessingForwardedRequests: false,
+    // Logging methods are replaced below after the logger is constructed.
+    writeDebugLog: () => {},
+    writeReviewLog: () => {},
+  };
+
+  const reportedLoggingWarnings = new Set<string>();
+  const logger = createPermissionSystemLogger({
+    // Reads runtime.config at call time — always current.
+    getConfig: () => runtime.config,
+    debugLogPath: join(globalLogsDir, DEBUG_LOG_FILENAME),
+    reviewLogPath: join(globalLogsDir, REVIEW_LOG_FILENAME),
+    ensureLogsDirectory: () =>
+      ensurePermissionSystemLogsDirectory(globalLogsDir),
+  });
+
+  const reportLoggingWarning = (message: string): void => {
+    if (reportedLoggingWarnings.has(message)) {
+      return;
+    }
+    reportedLoggingWarnings.add(message);
+    // Reads runtime.runtimeContext at call time — always current.
+    runtime.runtimeContext?.ui.notify(message, "warning");
+  };
+
+  runtime.writeDebugLog = (
+    event: string,
+    details: Record<string, unknown> = {},
+  ): void => {
+    const warning = logger.debug(event, details);
+    if (warning) {
+      reportLoggingWarning(warning);
+    }
+  };
+
+  runtime.writeReviewLog = (
+    event: string,
+    details: Record<string, unknown> = {},
+  ): void => {
+    const warning = logger.review(event, details);
+    if (warning) {
+      reportLoggingWarning(warning);
+    }
+  };
+
+  return runtime;
+}

package/src/types.ts

@@ -9,16 +9,8 @@ export type BuiltInToolName =
   | "find"
   | "ls";
 
-export type ToolPermissions = Record<string, PermissionState>;
-
-export type BashPermissions = Record<string, PermissionState>;
-
-export type SkillPermissions = Record<string, PermissionState>;
-
 export type SpecialPermissionName = "external_directory";
 
-export type SpecialPermissions = Record<string, PermissionState>;
-
 export interface PermissionDefaultPolicy {
   tools: PermissionState;
   bash: PermissionState;
@@ -27,17 +19,20 @@ export interface PermissionDefaultPolicy {
   special: PermissionState;
 }
 
-export interface AgentPermissions {
+/**
+ * Per-scope permission config shape after loading and validation.
+ * All fields optional — each scope may define a subset of the policy.
+ *
+ * This replaces the former AgentPermissions / GlobalPermissionConfig
+ * interfaces (removed in #56).
+ */
+export interface ScopeConfig {
   defaultPolicy?: Partial<PermissionDefaultPolicy>;
-  tools?: ToolPermissions;
-  bash?: BashPermissions;
-  mcp?: ToolPermissions;
-  skills?: SkillPermissions;
-  special?: SpecialPermissions;
-}
-
-export interface GlobalPermissionConfig extends AgentPermissions {
-  defaultPolicy: PermissionDefaultPolicy;
+  tools?: Record<string, PermissionState>;
+  bash?: Record<string, PermissionState>;
+  mcp?: Record<string, PermissionState>;
+  skills?: Record<string, PermissionState>;
+  special?: Record<string, PermissionState>;
 }
 
 export interface PermissionCheckResult {

package/tests/defaults.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "vitest";
+import {
+  DEFAULT_POLICY,
+  getSurfaceDefault,
+  mergeDefaults,
+} from "../src/defaults";
+import type { PermissionDefaultPolicy } from "../src/types";
+
+const SPECIAL_KEYS = new Set(["external_directory"]);
+
+describe("getSurfaceDefault", () => {
+  const defaults: PermissionDefaultPolicy = {
+    tools: "allow",
+    bash: "deny",
+    mcp: "ask",
+    skills: "allow",
+    special: "deny",
+  };
+
+  test("returns defaults.bash for surface 'bash'", () => {
+    expect(getSurfaceDefault("bash", defaults, SPECIAL_KEYS)).toBe("deny");
+  });
+
+  test("returns defaults.mcp for surface 'mcp'", () => {
+    expect(getSurfaceDefault("mcp", defaults, SPECIAL_KEYS)).toBe("ask");
+  });
+
+  test("returns defaults.skills for surface 'skill'", () => {
+    expect(getSurfaceDefault("skill", defaults, SPECIAL_KEYS)).toBe("allow");
+  });
+
+  test("returns defaults.special for special-key surfaces", () => {
+    expect(
+      getSurfaceDefault("external_directory", defaults, SPECIAL_KEYS),
+    ).toBe("deny");
+  });
+
+  test("returns defaults.tools for tool-name surfaces", () => {
+    expect(getSurfaceDefault("read", defaults, SPECIAL_KEYS)).toBe("allow");
+    expect(getSurfaceDefault("write", defaults, SPECIAL_KEYS)).toBe("allow");
+    expect(getSurfaceDefault("edit", defaults, SPECIAL_KEYS)).toBe("allow");
+  });
+
+  test("returns defaults.tools for unknown surfaces (least privilege via tools default)", () => {
+    expect(
+      getSurfaceDefault("unknown_extension_tool", defaults, SPECIAL_KEYS),
+    ).toBe("allow");
+  });
+
+  test("uses DEFAULT_POLICY when no overrides exist", () => {
+    expect(getSurfaceDefault("bash", DEFAULT_POLICY, SPECIAL_KEYS)).toBe("ask");
+    expect(getSurfaceDefault("read", DEFAULT_POLICY, SPECIAL_KEYS)).toBe("ask");
+    expect(
+      getSurfaceDefault("external_directory", DEFAULT_POLICY, SPECIAL_KEYS),
+    ).toBe("ask");
+  });
+});
+
+describe("mergeDefaults", () => {
+  test("returns DEFAULT_POLICY when called with no partials", () => {
+    expect(mergeDefaults()).toEqual(DEFAULT_POLICY);
+  });
+
+  test("overrides specific fields from a single partial", () => {
+    const result = mergeDefaults({ tools: "allow", bash: "deny" });
+    expect(result).toEqual({
+      tools: "allow",
+      bash: "deny",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    });
+  });
+
+  test("later partials override earlier ones", () => {
+    const global: Partial<PermissionDefaultPolicy> = { tools: "allow" };
+    const project: Partial<PermissionDefaultPolicy> = { tools: "deny" };
+    const result = mergeDefaults(global, project);
+    expect(result.tools).toBe("deny");
+  });
+
+  test("merges across multiple partials", () => {
+    const global: Partial<PermissionDefaultPolicy> = {
+      tools: "allow",
+      bash: "allow",
+    };
+    const project: Partial<PermissionDefaultPolicy> = { bash: "deny" };
+    const agent: Partial<PermissionDefaultPolicy> = { mcp: "allow" };
+    const result = mergeDefaults(global, project, agent);
+    expect(result).toEqual({
+      tools: "allow",
+      bash: "deny",
+      mcp: "allow",
+      skills: "ask",
+      special: "ask",
+    });
+  });
+
+  test("undefined fields in later partials do not override earlier values", () => {
+    const global: Partial<PermissionDefaultPolicy> = { tools: "allow" };
+    const project: Partial<PermissionDefaultPolicy> = { bash: "deny" };
+    const result = mergeDefaults(global, project);
+    expect(result.tools).toBe("allow");
+  });
+});