pi-famulus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leechael and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# pi-famulus
+
+Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi.
+
+After the first public release:
+
+```sh
+pi install npm:pi-famulus
+```
+
+npm installs the matching native manager automatically through an exact-version optional dependency. No Rust compiler, postinstall download, or separate manager installation is needed. Keep optional dependencies enabled.
+
+Supported native packages:
+
+| System | CPU | Package |
+|---|---|---|
+| Linux | x64 | `pi-famulus-linux-x64` |
+| Linux | arm64 | `pi-famulus-linux-arm64` |
+| macOS | Intel x64 | `pi-famulus-darwin-x64` |
+| macOS | Apple Silicon arm64 | `pi-famulus-darwin-arm64` |
+
+Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; your Node/pi runtime's requirements also apply. Windows and other CPU architectures are not supported.
+
+The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The extension's binary search order is:
+
+1. Executable `managerPath` from configuration.
+2. Executable `PI_FAMULUS_MANAGER_PATH` override.
+3. The matching-version installed native npm package.
+4. Executable `~/.pi/agent/pi-famulus/bin/pi-famulus` (or the equivalent beneath `PI_FAMULUS_HOME`).
+5. Executable `pi-famulus` on `PATH`.
+
+Configuration and runtime state remain in `~/.pi/agent/pi-famulus`. Installing/updating the npm package does not move that state or copy a binary into the shared home. The npm CLI uses the package's native executable; use the extension configuration above when intentionally running a separately built manager.
+
+If optional dependencies were omitted, reinstall with them enabled. The CLI reports an actionable error; the extension can still discover an explicitly installed manager and otherwise enters degraded mode. An arbitrary different-version native npm package is never substituted.
+
+See the [project README](https://github.com/Leechael/pi-famulus#readme) for tools, settings, one-time migration, and source-build instructions; see the [CLI manual](https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md) for operations.

package/bin/pi-famulus.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { nativePackageName, resolveNativeManagerPath } from "../src/native-manager.js";
+
+const binary = resolveNativeManagerPath();
+if (!binary) {
+  const name = nativePackageName(process.platform, process.arch);
+  console.error(name
+    ? `pi-famulus: missing usable ${name}. Reinstall pi-famulus with optional dependencies enabled (npm install --include=optional pi-famulus).`
+    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS x64/arm64 are supported.`);
+  process.exit(1);
+}
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+// Supervisors often signal the wrapper PID, not the whole process group.
+const forwarders = new Map(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"].map(signal => {
+  const forward = () => child.kill(signal);
+  process.on(signal, forward);
+  return [signal, forward];
+}));
+let failed = false;
+child.once("error", error => {
+  failed = true;
+  console.error(`pi-famulus: cannot execute native manager: ${error.message}`);
+});
+child.once("close", (code, signal) => {
+  for (const [name, forward] of forwarders) process.off(name, forward);
+  process.exitCode = failed ? 1 : (code ?? 1);
+  if (signal && !failed) process.kill(process.pid, signal);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pi-famulus",
+  "version": "0.1.0",
+  "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Leechael/pi-famulus",
+    "directory": "extension"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" },
+  "os": ["linux", "darwin"],
+  "cpu": ["x64", "arm64"],
+  "files": ["src", "bin", "README.md"],
+  "bin": { "pi-famulus": "./bin/pi-famulus.js" },
+  "optionalDependencies": {
+    "pi-famulus-linux-x64": "0.1.0",
+    "pi-famulus-linux-arm64": "0.1.0",
+    "pi-famulus-darwin-x64": "0.1.0",
+    "pi-famulus-darwin-arm64": "0.1.0"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "typebox": "^1.3.7"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  }
+}

package/src/agents/builtins.ts

@@ -0,0 +1,41 @@
+/**
+ * Built-in agent definitions (design doc §4.8).
+ *
+ * These form the lowest precedence layer: user and project definitions with
+ * the same name replace them wholesale.
+ */
+import type { AgentDefinition } from "./definition";
+
+export const BUILTIN_AGENTS: AgentDefinition[] = [
+  {
+    name: "explorer",
+    description:
+      "Fast read-only codebase exploration — finds files, symbols, and answers structure questions",
+    tools: ["read", "grep", "find", "ls", "bash"],
+    systemPrompt: [
+      "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.",
+      "",
+      "Rules:",
+      "- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.",
+      "- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.",
+      "- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.",
+      "- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
+    ].join("\n"),
+    source: "builtin",
+  },
+  {
+    name: "worker",
+    description: "General-purpose executor — completes concrete coding tasks end to end",
+    tools: ["read", "bash", "edit", "write"],
+    systemPrompt: [
+      "You are a worker agent. Your job is to complete the concrete task you were given, end to end.",
+      "",
+      "Rules:",
+      "- Do the task, don't just describe it. Make the actual edits and run the actual commands.",
+      "- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.",
+      "- Stay within the task's scope; do not refactor unrelated code.",
+      "- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
+    ].join("\n"),
+    source: "builtin",
+  },
+];

package/src/agents/definition.ts

@@ -0,0 +1,221 @@
+/**
+ * Agent definition types and markdown parsing (design doc §4.8, appendix B).
+ *
+ * Pure module: zero pi dependencies, zero npm dependencies. Agent definitions
+ * are markdown files with a hand-parsed YAML-subset frontmatter block:
+ *
+ *   ---
+ *   name: explorer
+ *   description: Fast codebase exploration
+ *   tools: [read, bash, grep, find, ls]   # or: read, bash, grep, find, ls
+ *   model: anthropic:claude-haiku-4-5
+ *   thinking: high
+ *   ---
+ *
+ *   Body becomes the system prompt (trimmed; may be empty).
+ */
+
+export interface AgentDefinition {
+  /** Must match ^[a-z][a-z0-9-]*$ */
+  name: string;
+  /** Required, non-empty. */
+  description: string;
+  /** Tool allowlist. Defaults to ["read","bash","edit","write"]. */
+  tools: string[];
+  /** "provider:id" or bare id. */
+  model?: string;
+  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  /** Frontmatter body, trimmed. Empty body → "". */
+  systemPrompt: string;
+  source: "builtin" | "user" | "project";
+  /** Filesystem path; builtins have none. */
+  path?: string;
+}
+
+export const DEFAULT_AGENT_TOOLS: readonly string[] = ["read", "bash", "edit", "write"];
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh"] as const;
+type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+type Fail = (reason: string) => never;
+
+function makeFail(source: AgentDefinition["source"], path: string | undefined): Fail {
+  return (reason) => {
+    const where = path ? ` at ${path}` : ` (${source} definition)`;
+    throw new Error(`Invalid agent definition${where}: ${reason}`);
+  };
+}
+
+/** Strip a trailing ` # comment` outside quotes and brackets (yaml-subset). */
+function stripInlineComment(value: string): string {
+  let quote: '"' | "'" | null = null;
+  let depth = 0;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === "[") depth++;
+    else if (ch === "]") depth = Math.max(0, depth - 1);
+    else if (ch === "#" && depth === 0 && (i === 0 || /\s/.test(value[i - 1]))) {
+      return value.slice(0, i);
+    }
+  }
+  return value;
+}
+
+function unquote(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function parseScalar(raw: string, field: string, fail: Fail): string {
+  const value = unquote(stripInlineComment(raw).trim());
+  if (value.startsWith("[") || value.endsWith("]")) {
+    fail(`field '${field}' must be a plain string, not an array`);
+  }
+  return value;
+}
+
+function parseStringArray(raw: string, field: string, fail: Fail): string[] {
+  const value = stripInlineComment(raw).trim();
+  // Accept both YAML flow arrays `[a, b, c]` and bare comma lists `a, b, c`
+  // (single item `a` included). Half-open brackets are still errors.
+  let inner: string;
+  if (value.startsWith("[") && value.endsWith("]")) {
+    inner = value.slice(1, -1).trim();
+  } else if (value.startsWith("[") || value.endsWith("]")) {
+    fail(`field '${field}' must use array syntax [a, b, c] or a comma list a, b, c`);
+  } else {
+    inner = value;
+  }
+  if (inner === "") return [];
+  return inner.split(",").map((item) => {
+    const scalar = unquote(item.trim());
+    if (scalar === "") fail(`field '${field}' contains an empty array item`);
+    if (scalar.startsWith("[") || scalar.startsWith("]")) {
+      fail(`field '${field}' has a malformed array item: "${item.trim()}"`);
+    }
+    return scalar;
+  });
+}
+
+interface Frontmatter {
+  fields: Record<string, string>;
+  body: string;
+}
+
+function parseFrontmatter(content: string, fail: Fail): Frontmatter {
+  const text = content.replace(/\r\n/g, "\n");
+  const lines = text.split("\n");
+  if ((lines[0] ?? "").trim() !== "---") {
+    fail("missing frontmatter block (file must start with '---')");
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    fail("unterminated frontmatter block (missing closing '---')");
+  }
+  const fields: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(trimmed);
+    if (!match) fail(`malformed frontmatter line: "${trimmed}"`);
+    fields[match[1]] = match[2];
+  }
+  return { fields, body: lines.slice(end + 1).join("\n") };
+}
+
+/**
+ * Parse one agent definition markdown file.
+ * Throws Error (message includes path and reason) on any validation failure.
+ */
+export function parseAgentMarkdown(
+  content: string,
+  source: AgentDefinition["source"],
+  path?: string,
+): AgentDefinition {
+  const fail = makeFail(source, path);
+  const { fields, body } = parseFrontmatter(content, fail);
+
+  if (fields.name === undefined) fail("missing required field 'name'");
+  const name = parseScalar(fields.name, "name", fail);
+  if (!NAME_PATTERN.test(name)) {
+    fail(`invalid name "${name}" (must match ^[a-z][a-z0-9-]*$)`);
+  }
+
+  if (fields.description === undefined) fail("missing required field 'description'");
+  const description = parseScalar(fields.description, "description", fail);
+  if (description === "") fail("field 'description' must be non-empty");
+
+  let tools = [...DEFAULT_AGENT_TOOLS];
+  if (fields.tools !== undefined) {
+    tools = parseStringArray(fields.tools, "tools", fail);
+  }
+
+  let model: string | undefined;
+  if (fields.model !== undefined) {
+    const value = parseScalar(fields.model, "model", fail);
+    if (value === "") fail("field 'model' must be non-empty when present");
+    model = value;
+  }
+
+  let thinking: ThinkingLevel | undefined;
+  if (fields.thinking !== undefined) {
+    const value = parseScalar(fields.thinking, "thinking", fail);
+    if (!(THINKING_LEVELS as readonly string[]).includes(value)) {
+      fail(
+        `invalid thinking level "${value}" (expected one of: ${THINKING_LEVELS.join(", ")})`,
+      );
+    }
+    thinking = value as ThinkingLevel;
+  }
+
+  return {
+    name,
+    description,
+    tools,
+    ...(model !== undefined ? { model } : {}),
+    ...(thinking !== undefined ? { thinking } : {}),
+    systemPrompt: body.trim(),
+    source,
+    ...(path !== undefined ? { path } : {}),
+  };
+}
+
+/**
+ * Resolve an agent by name. undefined → the default "worker" definition.
+ * Unknown names throw an Error listing all available agent names.
+ */
+export function resolveAgent(
+  defs: AgentDefinition[],
+  name: string | undefined,
+): AgentDefinition {
+  const target = name ?? "worker";
+  const found = defs.find((def) => def.name === target);
+  if (found) return found;
+  const available = defs
+    .map((def) => def.name)
+    .sort()
+    .join(", ");
+  const list = available === "" ? "(none)" : available;
+  if (name === undefined) {
+    throw new Error(`Default agent "worker" is not defined. Available agents: ${list}`);
+  }
+  throw new Error(`Unknown agent "${name}". Available agents: ${list}`);
+}

package/src/agents/loader.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent definition loading and caching (design doc §4.8, appendix B).
+ *
+ * Three-tier merge, later layers win by name:
+ *   builtin < userDir (**\/*.md) < projectDir (**\/*.md)
+ *
+ * Pure module: node:fs/node:path only. Missing directories are an empty set,
+ * not an error. Unparseable files are collected into LoadReport.errors and
+ * never abort the load.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { BUILTIN_AGENTS } from "./builtins";
+import { parseAgentMarkdown, type AgentDefinition } from "./definition";
+
+export interface LoadReport {
+  definitions: AgentDefinition[];
+  errors: { path: string; error: string }[];
+}
+
+export interface LoadAgentDefinitionsOptions {
+  userDir: string;
+  projectDir: string;
+}
+
+/** Recursively list *.md files under dir (sorted; missing dir → []). */
+function scanMarkdownFiles(dir: string): string[] {
+  const out: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...scanMarkdownFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/** One-shot load: scan both dirs, parse everything, merge three tiers. */
+export function loadAgentDefinitions(opts: LoadAgentDefinitionsOptions): LoadReport {
+  const merged = new Map<string, AgentDefinition>();
+  const errors: { path: string; error: string }[] = [];
+
+  for (const def of BUILTIN_AGENTS) {
+    merged.set(def.name, def);
+  }
+
+  const layers: { dir: string; source: "user" | "project" }[] = [
+    { dir: opts.userDir, source: "user" },
+    { dir: opts.projectDir, source: "project" },
+  ];
+  for (const { dir, source } of layers) {
+    for (const path of scanMarkdownFiles(dir)) {
+      try {
+        const def = parseAgentMarkdown(readFileSync(path, "utf8"), source, path);
+        merged.set(def.name, def);
+      } catch (err) {
+        errors.push({ path, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  }
+
+  return { definitions: [...merged.values()], errors };
+}
+
+export interface AgentLoader {
+  /**
+   * Return the current definitions. Re-parses only when the set of markdown
+   * files or any file's mtime has changed since the last call; otherwise
+   * returns the identical LoadReport object.
+   */
+  reload(): LoadReport;
+}
+
+/**
+ * Create a loader with an mtime fingerprint cache. The fingerprint covers the
+ * sorted file list plus each file's mtime, so added/removed/modified files all
+ * trigger a re-parse while an unchanged tree costs only a directory scan.
+ */
+export function createAgentLoader(opts: LoadAgentDefinitionsOptions): AgentLoader {
+  let cached: LoadReport | null = null;
+  let fingerprint: string | null = null;
+
+  function computeFingerprint(): string {
+    const parts: string[] = [];
+    for (const dir of [opts.userDir, opts.projectDir]) {
+      for (const path of scanMarkdownFiles(dir)) {
+        let mtime = "?";
+        try {
+          mtime = String(statSync(path).mtimeMs);
+        } catch {
+          // Unstatable file: keep "?" so the fingerprint differs from any
+          // previous numeric mtime and the load below records the error.
+        }
+        parts.push(`${path}:${mtime}`);
+      }
+    }
+    return parts.join("\n");
+  }
+
+  return {
+    reload(): LoadReport {
+      const fp = computeFingerprint();
+      if (cached !== null && fp === fingerprint) {
+        return cached;
+      }
+      cached = loadAgentDefinitions(opts);
+      fingerprint = fp;
+      return cached;
+    },
+  };
+}