@jaybeeuu/agent-cortex 1.40.0 → 1.41.0

package/extensions/agent-guardrails/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/extensions/agent-guardrails/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/extensions/agent-guardrails/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/agent-guardrails",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm guardrails.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/agent-guardrails/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/agent-modes/README.md

@@ -46,10 +46,16 @@ flat counterpart for the same agent id.
 ## Development
 
 Discovery and prompt composition live in `discover.ts` (unit-tested against
-fixture directories in `discover.test.ts`); `index.ts` only wires discovery
-into the extension API.
+fixture directories in `discover.test.ts`); `index.ts` wires discovery into the
+extension API and registers `--agent` at load time (`index.test.ts` covers that
+timing and the flag contract).
+
+`--agent` must be registered from the extension factory, not from a
+`session_start` handler: PI matches parsed CLI flags against the extensions
+loaded at startup, so late registration makes `pi --agent <name>` fail with
+`Unknown option: --agent`.
 
 ```bash
-pnpm test        # run discover.test.ts
+pnpm test        # run discover.test.ts and index.test.ts
 pnpm typecheck   # tsc --noEmit
 ```

package/extensions/agent-modes/index.test.ts

@@ -0,0 +1,208 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { type AgentDef, discoverAgents } from "./discover.ts";
+import agentModesExtension, { registerAgentFlag } from "./index.ts";
+
+const AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function agent(id: string): AgentDef {
+  return {
+    id,
+    name: `agent-cortex:${id}`,
+    description: `${id} agent`,
+    color: "accent",
+    tools: [],
+    prompt: "",
+  };
+}
+
+type RegisterFlagArgs = Parameters<ExtensionAPI["registerFlag"]>;
+/** A handler recorded from `pi.on`, invoked via Reflect.apply so its exact
+ *  overload signature does not leak into the fake. */
+type RecordedHandler = (...args: never[]) => unknown;
+
+interface FakeContext {
+  ui: {
+    statuses: Array<{ id: string; text: string | undefined }>;
+    notifications: Array<{ message: string; level: string }>;
+    setStatus(id: string, text: string | undefined): void;
+    notify(message: string, level: string): void;
+    theme: { fg(color: string, text: string): string };
+  };
+  sessionManager: { getEntries(): unknown[] };
+}
+
+interface FakePi {
+  pi: ExtensionAPI;
+  flags: RegisterFlagArgs[];
+  handlers: Map<string, RecordedHandler[]>;
+  setActiveToolsCalls: string[][];
+  /** Simulate pi dispatching an event to the handlers registered for it. */
+  fire(event: string, ...args: unknown[]): void;
+}
+
+/**
+ * Build a full ExtensionAPI test double that records the calls agent-modes
+ * makes. `getFlag` resolves against `flagValues`, and `getActiveTools` returns
+ * a fixed baseline so setActiveTools calls are observable.
+ */
+function createFakePi(flagValues: Record<string, boolean | string> = {}): FakePi {
+  const flags: RegisterFlagArgs[] = [];
+  const handlers = new Map<string, RecordedHandler[]>();
+  const setActiveToolsCalls: string[][] = [];
+  const values = new Map<string, boolean | string>(Object.entries(flagValues));
+  const baselineTools = ["read", "bash"];
+
+  const pi: ExtensionAPI = {
+    on: (event: string, handler: RecordedHandler) => {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+    registerFlag: (name, options) => {
+      flags.push([name, options]);
+    },
+    getFlag: (name) => values.get(name),
+    getActiveTools: () => [...baselineTools],
+    setActiveTools: (toolNames) => {
+      setActiveToolsCalls.push(toolNames);
+    },
+    registerCommand: () => {},
+    registerShortcut: () => {},
+    registerTool: () => {},
+    registerMessageRenderer: () => {},
+    registerProvider: () => {},
+    unregisterProvider: () => {},
+    sendMessage: () => {},
+    sendUserMessage: () => {},
+    appendEntry: () => {},
+    setSessionName: () => {},
+    getSessionName: () => undefined,
+    setLabel: () => {},
+    exec: async () => {
+      throw new Error("not implemented");
+    },
+    getAllTools: () => [],
+    getCommands: () => [],
+    setModel: async () => false,
+    getThinkingLevel: () => "off",
+    setThinkingLevel: () => {},
+    events: { on: () => () => {}, emit: () => {} },
+  };
+
+  return {
+    pi,
+    flags,
+    handlers,
+    setActiveToolsCalls,
+    fire(event, ...args) {
+      for (const handler of handlers.get(event) ?? []) {
+        Reflect.apply(handler, undefined, args);
+      }
+    },
+  };
+}
+
+function createFakeContext(): FakeContext {
+  return {
+    ui: {
+      statuses: [],
+      notifications: [],
+      setStatus(id, text) {
+        this.statuses.push({ id, text });
+      },
+      notify(message, level) {
+        this.notifications.push({ message, level });
+      },
+      theme: { fg: (_color, text) => text },
+    },
+    sessionManager: { getEntries: () => [] },
+  };
+}
+
+// ─── registerAgentFlag ───────────────────────────────────────────────────────
+
+describe("registerAgentFlag", () => {
+  it("registers --agent as a string flag listing the discovered agent ids", () => {
+    const calls: RegisterFlagArgs[] = [];
+    const pi: Pick<ExtensionAPI, "registerFlag"> = {
+      registerFlag: (...args) => calls.push(args),
+    };
+
+    registerAgentFlag(pi, [
+      agent("ralph"),
+      agent("ralph-plan"),
+      agent("plan"),
+      agent("strategy"),
+    ]);
+
+    assert.equal(calls.length, 1);
+    const [name, options] = calls[0];
+    assert.equal(name, "agent");
+    assert.equal(options.type, "string");
+    assert.equal(
+      options.description,
+      "Start in a specific agent mode (ralph, ralph-plan, plan, strategy)",
+    );
+  });
+});
+
+// ─── Registration timing ─────────────────────────────────────────────────────
+
+describe("agentModesExtension flag registration", () => {
+  it("registers --agent during load, before any session event fires", () => {
+    const fake = createFakePi();
+
+    agentModesExtension(fake.pi);
+
+    // The flag must exist straight after the factory returns: pi validates CLI
+    // flags against extensions loaded at startup, so registering it from the
+    // session_start handler would be too late and `pi --agent <name>` would fail.
+    assert.equal(fake.flags.length, 1);
+    const [name, options] = fake.flags[0];
+    assert.equal(name, "agent");
+    assert.equal(options.type, "string");
+    assert.match(options.description ?? "", /^Start in a specific agent mode \(/);
+  });
+});
+
+// ─── --agent flag contract ───────────────────────────────────────────────────
+
+describe("agentModesExtension --agent flag", () => {
+  it("activates the named agent on session start", () => {
+    const fake = createFakePi({ agent: "plan" });
+    const ctx = createFakeContext();
+
+    agentModesExtension(fake.pi);
+    fake.fire("session_start", {}, ctx);
+
+    const plan = discoverAgents(AGENTS_DIR).find((a) => a.id === "plan");
+    assert.ok(plan, "the plan agent should be discoverable");
+    assert.deepEqual(fake.setActiveToolsCalls.at(-1), plan.tools);
+    assert.ok(
+      ctx.ui.statuses.some((s) => s.id === "agent-mode" && s.text?.includes("plan")),
+      "the status indicator should show the active agent",
+    );
+  });
+
+  it("falls back to default mode for an unknown agent and leaves tools untouched", () => {
+    const fake = createFakePi({ agent: "does-not-exist" });
+    const ctx = createFakeContext();
+
+    agentModesExtension(fake.pi);
+    fake.fire("session_start", {}, ctx);
+
+    // Unknown flag → default mode: baseline tools restored, no agent status.
+    assert.deepEqual(fake.setActiveToolsCalls.at(-1), ["read", "bash"]);
+    assert.ok(
+      ctx.ui.statuses.every((s) => !s.text?.includes("agent:")),
+      "no agent mode should be reported",
+    );
+  });
+});

package/extensions/agent-modes/index.ts

@@ -37,6 +37,27 @@ interface OriginalState {
 
 const PERSIST_KEY = "agent-modes-state";
 
+// ─── CLI flag ────────────────────────────────────────────────────────────────
+
+/**
+ * Register the `--agent <name>` CLI flag.
+ *
+ * This must run while the extension is loading (i.e. from the factory), not
+ * from a `session_start` handler: PI matches CLI flags against the extensions
+ * loaded at startup, so a flag registered during `session_start` arrives after
+ * the CLI has already been parsed and `pi --agent <name>` fails with
+ * `Unknown option: --agent`.
+ */
+export function registerAgentFlag(
+  pi: Pick<ExtensionAPI, "registerFlag">,
+  agents: AgentDef[],
+): void {
+  pi.registerFlag("agent", {
+    description: `Start in a specific agent mode (${agents.map((a) => a.id).join(", ")})`,
+    type: "string",
+  });
+}
+
 // ─── Extension ───────────────────────────────────────────────────────────────
 
 export default function agentModesExtension(pi: ExtensionAPI): void {
@@ -47,6 +68,8 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
     return;
   }
 
+  registerAgentFlag(pi, agents);
+
   let activeAgentIndex = agents.length; // default mode is beyond the last agent
   let originalState: OriginalState | undefined;
   let baselineTools: string[] = [];
@@ -186,12 +209,6 @@ export default function agentModesExtension(pi: ExtensionAPI): void {
       },
     });
 
-    // --agent CLI flag
-    pi.registerFlag("agent", {
-      description: `Start in a specific agent mode (${agents.map((a) => a.id).join(", ")})`,
-      type: "string",
-    });
-
     // inject agent prompt before each agent start
     pi.on("before_agent_start", async (event) => {
       const agent = getActiveAgent();

package/extensions/agent-modes/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm discover.test.ts",
+    "test": "node --test --import tsx/esm discover.test.ts index.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/lib/cli.mjs

@@ -9,6 +9,7 @@ const INSTALL_OPTIONS = {
   "--output": { key: "output" },
   "--plugin-root": { key: "pluginRoot" },
   "--require-register": { key: "requireRegister", boolean: true },
+  "--no-provision": { key: "noProvision", boolean: true },
 };
 
 export function parseArgs(argv) {
@@ -94,10 +95,15 @@ Commands:
                         --dry-run        Print what would be generated without writing
                       Options (pi):
                         --dry-run             Show what would be installed without writing
-                        --output <dir>        Install into <dir>/agents and <dir>/skills
-                                              (default: ~/.pi/agent)
+                        --output <dir>        Install into <dir> — agents/, skills/,
+                                              settings.json (merged, packages managed)
+                                              and keybindings.json (default: ~/.pi/agent)
                         --plugin-root <dir>   Override the plugin root used for {{PATH:...}}
                                               tokens (default: token-map.json's pi value)
+                        --no-provision        Skip installing the third-party pi packages
+                                              declared in the package manifest (e.g.
+                                              pi-questions, pi-web-access). They are
+                                              installed by default on a real install.
   --help, -h          Show this help text`;
 }
 

package/lib/pi-packages.mjs

@@ -0,0 +1,169 @@
+// Pi third-party package provisioning.
+//
+// agent-cortex's pi harness needs tools that live in third-party pi packages:
+// ask_questions comes from pi-questions, fetch_content from pi-web-access (see
+// token-map.json notes and docs/ideas/extension-manifests.md). Those packages
+// are declared in the package manifest — package.json → pi.packages — and this
+// module makes them real: `agent-cortex install pi` reads the declaration and
+// installs any package the pi user scope is missing.
+//
+// Provisioning goes through the pi CLI (`pi install <source>`), which both
+// installs the package under ~/.pi/agent/npm and declares it in
+// ~/.pi/agent/settings.json — the same store pi loads packages from. It is
+// opt-in (installPi option `provisionPackages`) and idempotent: a package that
+// is already declared and installed is skipped. A failed install warns and the
+// rest continue, so an offline machine never breaks the agent install.
+
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+const DEFAULT_WARN = (msg) => console.warn(`[pi-packages] ${msg}`);
+
+/**
+ * Read the pi package sources agent-cortex declares it needs.
+ *
+ * @param {string} root Package root containing package.json
+ * @returns {Promise<string[]>} Declared sources, e.g. ["npm:pi-questions"]
+ */
+export async function loadRequiredPackages(root) {
+  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf-8"));
+  const packages = manifest?.pi?.packages;
+  return Array.isArray(packages) ? packages.filter((entry) => typeof entry === "string") : [];
+}
+
+/**
+ * Extract the npm package name from a pi source string.
+ *
+ * @param {string} source e.g. "npm:pi-web-access@0.10.7", "npm:@scope/pkg"
+ * @returns {string | null} The name, or null for sources we cannot inspect locally
+ */
+export function npmSourceName(source) {
+  if (typeof source !== "string" || !source.startsWith("npm:")) return null;
+  const spec = source.slice("npm:".length);
+  const at = spec.lastIndexOf("@");
+  return at > 0 ? spec.slice(0, at) : spec;
+}
+
+/**
+ * Decide which required packages still need installing.
+ *
+ * A package is satisfied only when it is both declared in settings (so pi loads
+ * it) and present in the npm store (so it is installed) — otherwise it needs a
+ * `pi install` to reconcile.
+ *
+ * @param {string[]} required
+ * @param {{ declaredSources: string[], installedNames: string[] }} state
+ * @returns {string[]} The sources still to install
+ */
+export function planPackageInstalls(required, { declaredSources, installedNames }) {
+  const declared = new Set(declaredSources.map(npmSourceName).filter(Boolean));
+  const installed = new Set(installedNames);
+  return required.filter((source) => {
+    const name = npmSourceName(source);
+    return name === null || !declared.has(name) || !installed.has(name);
+  });
+}
+
+/**
+ * Install every required package the pi user scope is missing.
+ *
+ * @param {object} options
+ * @param {string[]} options.required        Declared pi sources (see loadRequiredPackages)
+ * @param {string} options.piRoot            Pi user scope dir (default ~/.pi/agent)
+ * @param {boolean} [options.dryRun]         Report the plan without installing
+ * @param {(source: string) => Promise<{ok: boolean, error: string | null}>} [options.runInstall]
+ * @param {(msg: string) => void} [options.warn]
+ * @returns {Promise<{planned: string[], installed: string[], failed: {source: string, error: string}[]}>}
+ */
+export async function provisionPiPackages({
+  required,
+  piRoot,
+  dryRun = false,
+  runInstall = runPiInstall,
+  warn = DEFAULT_WARN,
+}) {
+  const declaredSources = await readDeclaredSources(join(piRoot, "settings.json"));
+  const installedNames = await readInstalledNames(join(piRoot, "npm", "node_modules"));
+  const planned = planPackageInstalls(required, { declaredSources, installedNames });
+
+  if (dryRun) return { planned, installed: [], failed: [] };
+
+  const installed = [];
+  const failed = [];
+  for (const source of planned) {
+    const result = await runInstall(source);
+    if (result.ok) {
+      installed.push(source);
+    } else {
+      failed.push({ source, error: result.error });
+      warn(`could not install pi package ${source}: ${result.error}`);
+    }
+  }
+  return { planned, installed, failed };
+}
+
+/** Install one pi package source through the pi CLI. */
+export function runPiInstall(source) {
+  return new Promise((resolve) => {
+    const child = spawn("pi", ["install", source], { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stdout.resume(); // drain; only failures are interesting
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (err) => {
+      resolve({
+        ok: false,
+        error: err.code === "ENOENT" ? "pi CLI not found on PATH" : err.message,
+      });
+    });
+    child.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        error: code === 0 ? null : stderr.trim() || `pi install exited with code ${code}`,
+      });
+    });
+  });
+}
+
+// ─── Pi user-scope inspection ────────────────────────────────────────────────
+
+/** Read the package sources declared in a pi settings.json (missing or unreadable → none). */
+async function readDeclaredSources(settingsPath) {
+  let settings;
+  try {
+    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
+  } catch {
+    // Nothing declared yet, or a file pi itself owns and repairs. Provisioning is
+    // a non-essential step — it must never fail the agent install.
+    return [];
+  }
+  const packages = Array.isArray(settings?.packages) ? settings.packages : [];
+  return packages
+    .map((entry) => (typeof entry === "string" ? entry : entry?.source))
+    .filter((source) => typeof source === "string");
+}
+
+/** List installed package names in the pi npm store (missing dir → none). */
+async function readInstalledNames(nodeModulesDir) {
+  let entries;
+  try {
+    entries = await readdir(nodeModulesDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith("@")) {
+      names.push(entry.name);
+      continue;
+    }
+    for (const scoped of await readdir(join(nodeModulesDir, entry.name), { withFileTypes: true })) {
+      if (scoped.isDirectory()) names.push(`${entry.name}/${scoped.name}`);
+    }
+  }
+  return names;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -24,6 +24,10 @@
     ],
     "skills": [
       "./skills"
+    ],
+    "packages": [
+      "npm:pi-questions",
+      "npm:pi-web-access@0.10.7"
     ]
   },
   "scripts": {

package/pi/settings.json

@@ -4,26 +4,37 @@
     "maxNameLength": 40,
     "maxSummaryLength": 100
   },
-  "lastChangelogVersion": "0.83.0",
+  "lastChangelogVersion": "0.87.1",
   "packages": [
-    "../../src/agent-cortex",
+    {
+      "source": "../../src/agent-cortex",
+      "skills": []
+    },
     "npm:pi-web-access@0.10.7",
     "npm:@getpipher/vision",
     "npm:@hypabolic/pi-hypa",
-    "npm:context-mode"
+    "npm:context-mode",
+    "npm:pi-questions"
   ],
   "defaultProvider": "opencode-go",
-  "defaultModel": "qwen3.7-max",
+  "defaultModel": "deepseek-v4.1-flash",
   "theme": "dark",
   "defaultThinkingLevel": "high",
   "enabledModels": [
-    "opencode/nemotron-3-ultra-free",
-    "opencode-go/qwen3.7-max",
-    "opencode/kimi-k2.7-code",
-    "opencode/mimo-v2.5-free",
-    "opencode-go/mimo-v2.5",
-    "opencode/deepseek-v4-flash-free",
+    "opencode/big-pickle",
+    "opencode-go/qwen3.7-plus",
     "opencode-go/deepseek-v4-flash",
-    "opencode/big-pickle"
-  ]
+    "opencode-go/kimi-k3",
+    "opencode/deepseek-v4-flash",
+    "opencode/mimo-v2.5-free",
+    "opencode-go/deepseek-v4.1-flash"
+  ],
+  "compaction": {
+    "enabled": true
+  },
+  "steeringMode": "all",
+  "followUpMode": "all",
+  "tuiMode": "regular",
+  "treeFilterMode": "default",
+  "hideThinkingBlock": true
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "author": {
     "name": "jaybeeuu"
   },

package/scripts/lib/fs.mjs

@@ -0,0 +1,31 @@
+// Shared async filesystem predicates. The install-time generators all need the
+// same "does this path exist and is it a file/directory?" probe, and the repo
+// convention is async-only (no *Sync) in tooling code — see scripts/check-no-sync.mjs.
+//
+// Both probes are stat-based and resolve `false` on any error (missing path,
+// permission denied, broken symlink), so callers can branch on existence
+// without a separate try/catch:
+//
+//   if (await isFile(join(dir, "agent.md"))) { … }
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { stat } from "node:fs/promises";
+
+/** True when `p` exists and is a regular file; false on any error. */
+export async function isFile(p) {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** True when `p` exists and is a directory; false on any error. */
+export async function isDirectory(p) {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}