opensec-pi-subagents 0.19.1 → 0.19.2

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.2] - 2026-09-26
+
+### Changed
+- **Cache unchanged subagent discovery and configuration.** Directory listings, parsed agent files, and parsed subagent settings are reused after metadata validation on each load. Changes invalidate the cache without a timer; sessions, extension initialization, tools, skills, model, and thinking inheritance remain unchanged.
+
 ## [0.19.0] - 2026-08-25
 
 > **⚠️ Breaking — this release requires pi 0.84.0 or newer** (`peerDependencies` moves from `>=0.81.0`). `SubagentWorkflow` needs two host APIs that do not exist below it, and both fail the typecheck rather than degrading quietly — see the `Changed` entry below for which, and why neither was worth reimplementing to hold the old floor. npm flags an older pi at install time.

package/README.md

@@ -269,6 +269,8 @@ Project-level agents override global ones with the same name, so you can customi
 
 An unreadable or unparseable agent file is skipped, not fatal — a warning names the file and the error. If it was overriding a same-named agent, a second line names the file that loads instead. Set `strictAgentFiles: true` in `subagents.json` (or `/agents → Settings → Strict agent files`) to fail startup on a broken file instead; mid-session reloads still only warn.
 
+Discovery reuses unchanged directory listings and parsed agent files within each Pi process. File and directory metadata are checked on every load, so edits, additions, removals, and atomic replacements are picked up on the next discovery without a timer or restart. Parsed `subagents.json` settings use the same bounded cache; their existing application points are unchanged. Each load still builds fresh agent configurations, and each spawn keeps its own session and extension initialization. Model/thinking inheritance, tools, skills, and prompts are unchanged.
+
 ### Example: `.pi/agents/auditor.md`
 
 ```markdown
@@ -946,6 +948,7 @@ src/
   # Agent registry
   default-agents.ts   # Embedded default agent configs (general-purpose, Explore, Plan)
   custom-agents.ts    # Load user-defined agents from .pi/agents/, .agents/agents/, and global agents
+  discovery-cache.ts  # Bounded metadata-validated caches for discovery and parsed configuration
   agent-types.ts      # Unified agent registry (defaults + user), tool name resolution
   agent-file-toggle.ts # Locate/edit an agent's .md: enabled: toggle, eject to frontmatter
   agent-color.ts      # Claude Code/Agency Agents name color parsing and badge rendering

package/dist/custom-agents.js

@@ -5,6 +5,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { createDiscoveryCache } from "./discovery-cache.js";
 /**
  * The one thing a declared `name:` may not contain, matching Claude Code
  * exactly: it reserves `:` for plugin-scoped identifiers (`my-plugin:reviewer`)
@@ -19,6 +20,8 @@ import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
  * and a file must be able to override one.
  */
 const RESERVED_IN_TYPE = ":";
+const readAgentDirectory = createDiscoveryCache((path) => readdirSync(path).filter(f => f.endsWith(".md")), 64);
+const readParsedAgent = createDiscoveryCache((path) => parseAgentFrontmatter(readFileSync(path, "utf-8")));
 /**
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
@@ -55,7 +58,7 @@ function loadFromDir(dir, agents, source, strict) {
         return;
     let files;
     try {
-        files = readdirSync(dir).filter(f => f.endsWith(".md"));
+        files = readAgentDirectory(dir);
     }
     catch {
         return;
@@ -156,7 +159,7 @@ export function parseAgentFrontmatter(content) {
 }
 function readAgentFile(path, strict) {
     try {
-        return parseAgentFrontmatter(readFileSync(path, "utf-8"));
+        return readParsedAgent(path);
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);

package/dist/discovery-cache.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cache successful file parsing or directory listings, not live session state.
+ * Validate on every access (no TTL/watchers); never reuse failures. Values stay
+ * private to the caller, which must not expose mutable cached objects.
+ */
+export declare function createDiscoveryCache<T>(read: (path: string) => T, capacity?: number): (path: string) => T;

package/dist/discovery-cache.js

@@ -0,0 +1,42 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+/** Metadata includes replacement, same-size edits, and permission changes. */
+function fingerprint(path) {
+    const s = statSync(path, { bigint: true });
+    return `${s.dev}:${s.ino}:${s.mode}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
+}
+/**
+ * Cache successful file parsing or directory listings, not live session state.
+ * Validate on every access (no TTL/watchers); never reuse failures. Values stay
+ * private to the caller, which must not expose mutable cached objects.
+ */
+export function createDiscoveryCache(read, capacity = 256) {
+    const entries = new Map();
+    return (path) => {
+        const key = resolve(path);
+        try {
+            const before = fingerprint(key);
+            const cached = entries.get(key);
+            entries.delete(key);
+            if (cached?.fingerprint === before) {
+                entries.set(key, cached);
+                return cached.value;
+            }
+            const value = read(key);
+            // An edit racing the read must not label old content with new metadata.
+            if (before === fingerprint(key)) {
+                entries.set(key, { fingerprint: before, value });
+                if (entries.size > capacity) {
+                    const oldest = entries.keys().next().value;
+                    if (oldest !== undefined)
+                        entries.delete(oldest);
+                }
+            }
+            return value;
+        }
+        catch (error) {
+            entries.delete(key);
+            throw error;
+        }
+    };
+}

package/dist/settings.js

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
+import { createDiscoveryCache } from "./discovery-cache.js";
 const VALID_JOIN_MODES = new Set(["async", "group", "smart"]);
 const VALID_TOOL_DESCRIPTION_MODES = new Set(["full", "compact", "custom"]);
 const VALID_WIDGET_MODES = new Set(["all", "background", "off"]);
@@ -133,11 +134,12 @@ function projectPath(cwd) {
  * exists but can't be parsed emits a warning to stderr so users aren't
  * silently reverted to defaults — and still returns `{}` so startup proceeds.
  */
+const readParsedSettings = createDiscoveryCache((path) => sanitize(JSON.parse(readFileSync(path, "utf-8"))), 64);
 function readSettingsFile(path) {
     if (!existsSync(path))
         return {};
     try {
-        return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+        return readParsedSettings(path);
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "opensec-pi-subagents",
-  "version": "0.19.1",
-  "description": "Fork of @tintinweb/pi-subagents with parent model and thinking inheritance for Explore agents.",
+  "version": "0.19.2",
+  "description": "Fork of @tintinweb/pi-subagents with parent model/thinking inheritance and cached agent discovery.",
   "author": "tintinweb",
   "contributors": ["kushalkhemka"],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opensec-git/opensec-pi-subagents.git"
+  },
+  "homepage": "https://github.com/opensec-git/opensec-pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/opensec-git/opensec-pi-subagents/issues"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/custom-agents.ts

@@ -6,6 +6,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { createDiscoveryCache } from "./discovery-cache.js";
 import type { AgentConfig, IsolationMode, MemoryScope, ThinkingLevel } from "./types.js";
 
 /**
@@ -23,6 +24,14 @@ import type { AgentConfig, IsolationMode, MemoryScope, ThinkingLevel } from "./t
  */
 const RESERVED_IN_TYPE = ":";
 
+const readAgentDirectory = createDiscoveryCache(
+  (path) => readdirSync(path).filter(f => f.endsWith(".md")),
+  64,
+);
+const readParsedAgent = createDiscoveryCache(
+  (path) => parseAgentFrontmatter<Record<string, unknown>>(readFileSync(path, "utf-8")),
+);
+
 /**
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
@@ -62,7 +71,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
 
   let files: string[];
   try {
-    files = readdirSync(dir).filter(f => f.endsWith(".md"));
+    files = readAgentDirectory(dir);
   } catch {
     return;
   }
@@ -172,7 +181,7 @@ export function parseAgentFrontmatter<T extends Record<string, unknown>>(content
 
 function readAgentFile(path: string, strict: boolean): { frontmatter: Record<string, unknown>; body: string } | undefined {
   try {
-    return parseAgentFrontmatter<Record<string, unknown>>(readFileSync(path, "utf-8"));
+    return readParsedAgent(path);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     if (strict) throw new Error(`${path}: ${reason}`);

package/src/discovery-cache.ts

@@ -0,0 +1,42 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+
+/** Metadata includes replacement, same-size edits, and permission changes. */
+function fingerprint(path: string): string {
+  const s = statSync(path, { bigint: true });
+  return `${s.dev}:${s.ino}:${s.mode}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
+}
+
+/**
+ * Cache successful file parsing or directory listings, not live session state.
+ * Validate on every access (no TTL/watchers); never reuse failures. Values stay
+ * private to the caller, which must not expose mutable cached objects.
+ */
+export function createDiscoveryCache<T>(read: (path: string) => T, capacity = 256): (path: string) => T {
+  const entries = new Map<string, { fingerprint: string; value: T }>();
+  return (path) => {
+    const key = resolve(path);
+    try {
+      const before = fingerprint(key);
+      const cached = entries.get(key);
+      entries.delete(key);
+      if (cached?.fingerprint === before) {
+        entries.set(key, cached);
+        return cached.value;
+      }
+      const value = read(key);
+      // An edit racing the read must not label old content with new metadata.
+      if (before === fingerprint(key)) {
+        entries.set(key, { fingerprint: before, value });
+        if (entries.size > capacity) {
+          const oldest = entries.keys().next().value;
+          if (oldest !== undefined) entries.delete(oldest);
+        }
+      }
+      return value;
+    } catch (error) {
+      entries.delete(key);
+      throw error;
+    }
+  };
+}

package/src/settings.ts

@@ -6,6 +6,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
+import { createDiscoveryCache } from "./discovery-cache.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
 export interface SubagentsSettings {
@@ -477,10 +478,15 @@ function projectPath(cwd: string): string {
  * exists but can't be parsed emits a warning to stderr so users aren't
  * silently reverted to defaults — and still returns `{}` so startup proceeds.
  */
+const readParsedSettings = createDiscoveryCache(
+  (path) => sanitize(JSON.parse(readFileSync(path, "utf-8"))),
+  64,
+);
+
 function readSettingsFile(path: string): SubagentsSettings {
   if (!existsSync(path)) return {};
   try {
-    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+    return readParsedSettings(path);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);