pi-open-agents 0.1.0

package/ATTRIBUTION.md

@@ -0,0 +1,38 @@
+# Attribution
+
+This project builds on ideas and code from the following open-source projects.
+Significant portions of the initial implementation are derived from these sources.
+
+## pi-agent-mode
+
+- **Source**: https://github.com/ZGltYQ/agent-mode
+- **Author**: ZGltYQ
+- **License**: MIT
+- **Version at time of fork**: v1.3.0 (commit `751abef`)
+- **What we use**: Primary agent loading, inline system prompt injection,
+  model switching, tool whitelist, TUI selector/search UI, status banner,
+  `set_agent`/`search_agents` tools, session persistence, `--agent` CLI flag.
+
+## pi-subagents
+
+- **Source**: https://github.com/jwu/pi-subagents
+- **Author**: jwu (John Wu)
+- **License**: MIT
+- **Version at time of fork**: v2.1.0 (commit `6c568dd`)
+- **What we use**: Subagent execution engine, child session spawning,
+  tool scoping, parent-child IPC, TUI rendering for subagent streams,
+  `maxDepth`/`allowedAgents` controls, `thinking` frontmatter support.
+
+## opencode
+
+- **Source**: https://github.com/anomalyco/opencode
+- **Author**: anomalyco (fork of sst/opencode)
+- **Version at time of clone**: commit `cfddb24`
+- **What we reference**: Agent definition format, frontmatter schema,
+  discovery paths (`.opencode/agent/`), compatibility target for
+  cross-runtime agent definitions.
+
+## License compliance
+
+Each source file derived from these projects retains appropriate attribution
+in its header comments. The upstream licenses apply to their respective code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Tomassi
+
+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,137 @@
+# pi-open-agents
+
+Unified agent and subagent management for [pi](https://github.com/earendil-works/pi-coding-agent), with [OpenCode](https://github.com/sst/opencode)-compatible agent definitions.
+
+Replaces `pi-agent-mode` and `@johnnywu/pi-subagents` with a single, coherent system.
+
+## Why
+
+Pi delegates agent management to two separate npm plugins that use incompatible frontmatter schemas, divergent defaults, and fragmented semantics. This plugin replaces both with one unified system that also reads OpenCode-format agent definitions.
+
+## Features
+
+- **Unified agent definitions** — one `.md` file format, superset of OpenCode + pi
+- **Mode-based visibility** — `primary` agents in the TUI selector, `subagent` agents for delegation, `all` for both
+- **OpenCode-compatible** — reads agents from `.opencode/agent/`, `.opencode/mode/`, and `.agents/`
+- **Permission system** — OpenCode-style `allow`/`deny`/`ask` with glob patterns, last-match-wins
+- **Thinking level per-agent** — `off`/`minimal`/`low`/`medium`/`high`/`xhigh`, with fallback to `settings.json`
+- **Subagent execution** — child pi process spawning with scoped tools, skills, and session fork
+- **Skill loading** — per-agent skills with wildcard support (`lark-*`, `github`)
+
+## Installation
+
+```bash
+pi install pi-open-agents
+```
+
+Then remove the old plugins from `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    "pi-open-agents"
+  ]
+}
+```
+
+## Agent Definition Format
+
+```yaml
+---
+# === Identity ===
+name: my-agent                    # required
+description: When to use this agent
+mode: primary|subagent|all        # default: all
+hidden: false                     # hide from TUI selectors
+color: "#44BA81"
+
+# === Model ===
+model: provider/model-id          # per-agent override
+variant: thinking                 # model variant
+temperature: 0.7
+top_p: 0.95
+
+# === Execution ===
+thinking: xhigh                   # off|minimal|low|medium|high|xhigh
+steps: 50                         # max agentic iterations
+systemPrompt: append|replace|replace-all  # default: append
+
+# === Permissions (OpenCode-style) ===
+permission:
+  bash: allow
+  edit:
+    "*.env": deny
+    "*.md": allow
+  read: allow
+
+# === Subagent controls ===
+maxDepth: 10                      # recursion limit
+allowedAgents: worker, explorer   # which subagents this can spawn
+skills: lark-*, github            # per-agent skills with wildcards
+---
+You are a specialized agent. Your markdown body becomes the system prompt.
+```
+
+## Discovery Paths
+
+Agents are loaded from multiple locations (project overrides global by name):
+
+| Path | Scope | Format |
+|------|-------|--------|
+| `~/.pi/agent/agents/*.md` | Global | pi |
+| `~/.opencode/{agent,agents,mode}/*.md` | Global | OpenCode |
+| `.pi/agents/*.md` | Project | pi |
+| `.opencode/{agent,agents,mode}/*.md` | Project | OpenCode |
+| `.agents/*.md` | Project | Shared |
+
+## Usage
+
+### Interactive
+
+| Action | What it does |
+|---|---|
+| `/agent` | Open agent selector (primary/all only) |
+| `/agent <name>` | Switch to agent directly |
+| `/agents` | List all agents |
+| `/agent-search <query>` | Search agents |
+| `Ctrl+Shift+M` | Cycle agents |
+| `Alt+S` | Search prompt |
+| `--agent <name>` | CLI flag for startup agent |
+
+### Programmatic (LLM tools)
+
+| Tool | Description |
+|---|---|
+| `set_agent` | Switch agent programmatically |
+| `search_agents` | Search agents by name/description/body |
+| `subagent` | Delegate task to a subagent (subagent/all mode only) |
+
+## Migration from pi-agent-mode + pi-subagents
+
+1. Install: `pi install pi-open-agents`
+2. Remove `npm:pi-agent-mode` and `npm:@johnnywu/pi-subagents` from settings
+3. Existing agent `.md` files work without changes (default `mode: all`)
+4. Gradually add `mode: primary` or `mode: subagent` to control visibility
+5. Gradually adopt `permission:` over `tools:` whitelist
+
+## Development
+
+```bash
+npm install
+npm test          # 84 tests
+npm run typecheck # tsc --noEmit
+```
+
+## Attribution
+
+This project builds on code and ideas from:
+
+- [pi-agent-mode](https://github.com/ZGltYQ/agent-mode) by ZGltYQ (MIT)
+- [pi-subagents](https://github.com/jwu/pi-subagents) by jwu (MIT)
+- [opencode](https://github.com/sst/opencode) by sst (MIT)
+
+See `ATTRIBUTION.md` for details.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,8 @@
+/**
+ * pi-open-agents entry point.
+ *
+ * Re-exports from src/index.ts so pi can resolve the extension name
+ * from the package root (not the "src" directory).
+ */
+export { default } from "./src/index.ts";
+export * from "./src/index.ts";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-open-agents",
+  "version": "0.1.0",
+  "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "agents",
+    "subagents",
+    "opencode"
+  ],
+  "author": "Andrea Tomassi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrea-tomassi/pi-open-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andrea-tomassi/pi-open-agents/issues"
+  },
+  "homepage": "https://github.com/andrea-tomassi/pi-open-agents#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "ATTRIBUTION.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx test/**/*.test.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/config/frontmatter.ts

@@ -0,0 +1,247 @@
+/**
+ * Self-contained YAML frontmatter parser.
+ *
+ * Handles the subset of YAML used by agent definitions:
+ * - Flat key-value pairs
+ * - Nested objects (for permission rules)
+ * - Type coercion (boolean, number, string)
+ * - Quoted values
+ *
+ * No external dependencies — works in isolation for testing.
+ */
+
+interface RawLine {
+  indent: number;
+  content: string;
+  lineNumber: number;
+}
+
+export interface ParsedFrontmatter {
+  data: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * Extract and parse frontmatter from markdown content.
+ *
+ * Returns { data: {}, body: content } if no frontmatter is present.
+ */
+export function parseFrontmatter(content: string): ParsedFrontmatter {
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+  // No frontmatter block
+  if (!normalized.startsWith("---")) {
+    return { data: {}, body: normalized.trim() };
+  }
+
+  // Find the closing ---
+  // Skip the opening --- and the newline after it
+  const afterOpening = normalized.slice(3);
+  if (!afterOpening.startsWith("\n") && !afterOpening.startsWith("\r")) {
+    // --- immediately followed by content (not a frontmatter block)
+    return { data: {}, body: normalized.trim() };
+  }
+
+  const closingIdx = normalized.indexOf("\n---", 3);
+  if (closingIdx === -1) {
+    // No closing delimiter — treat entire content as body
+    return { data: {}, body: normalized.trim() };
+  }
+
+  const yamlString = normalized.slice(4, closingIdx);
+  const body = normalized.slice(closingIdx + 4).replace(/^\n/, "").trim();
+
+  const data = parseYaml(yamlString);
+
+  return { data, body };
+}
+
+// ─── Minimal YAML Parser ─────────────────────────────────────────────────────
+
+/**
+ * Parse a YAML string into a nested object.
+ *
+ * Handles:
+ * - key: value          (flat string/number/boolean)
+ * - key:                (start of nested object)
+ * -   subkey: value     (nested under parent)
+ * - key: [a, b, c]      (inline array)
+ * - Comments (# ...)
+ * - Quoted values
+ */
+function parseYaml(input: string): Record<string, unknown> {
+  const lines = preprocessLines(input);
+  const root: Record<string, unknown> = {};
+  parseBlock(lines, 0, lines.length, 0, root);
+  return root;
+}
+
+function preprocessLines(input: string): RawLine[] {
+  const result: RawLine[] = [];
+  const rawLines = input.split("\n");
+
+  for (let i = 0; i < rawLines.length; i++) {
+    const line = rawLines[i];
+
+    // Skip empty lines and comments
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    // Calculate indentation (spaces only, tabs not supported in YAML)
+    const indent = line.length - line.trimStart().length;
+
+    result.push({
+      indent,
+      content: line.trim(),
+      lineNumber: i + 1,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Recursively parse a block of lines at a given indentation level.
+ *
+ * @param lines    All preprocessed lines
+ * @param start    Start index in lines array
+ * @param end      End index (exclusive)
+ * @param indent   Expected indentation level for this block
+ * @param target   Object to populate
+ * @returns        Number of lines consumed
+ */
+function parseBlock(
+  lines: RawLine[],
+  start: number,
+  end: number,
+  indent: number,
+  target: Record<string, unknown>,
+): number {
+  let i = start;
+
+  while (i < end) {
+    const line = lines[i];
+
+    // This line belongs to a shallower scope — we're done with this block
+    if (line.indent < indent) break;
+
+    // Deeper indentation without a parent key — skip (malformed)
+    if (line.indent > indent) {
+      i++;
+      continue;
+    }
+
+    const colonIdx = line.content.indexOf(":");
+    if (colonIdx === -1) {
+      // No colon — skip malformed line
+      i++;
+      continue;
+    }
+
+    const key = line.content.slice(0, colonIdx).trim().replace(/^['"]|['"]$/g, "");
+    const rawValue = line.content.slice(colonIdx + 1).trim();
+
+    if (!key) {
+      i++;
+      continue;
+    }
+
+    if (rawValue === "") {
+      // Value is empty — check if next lines are nested
+      if (i + 1 < end && lines[i + 1].indent > indent) {
+        // Parse nested object
+        const nested: Record<string, unknown> = {};
+        const childIndent = lines[i + 1].indent;
+        let consumed = 0;
+        let j = i + 1;
+
+        while (j < end && lines[j].indent >= childIndent) {
+          if (lines[j].indent === childIndent) {
+            const subColon = lines[j].content.indexOf(":");
+            if (subColon === -1) {
+              j++;
+              continue;
+            }
+            const subKey = lines[j].content.slice(0, subColon).trim().replace(/^['"]|['"]$/g, "");
+            const subRaw = lines[j].content.slice(subColon + 1).trim();
+
+            if (subRaw === "" && j + 1 < end && lines[j + 1].indent > childIndent) {
+              // Double nesting (e.g. edit: { "*.env": deny })
+              const deepNested: Record<string, unknown> = {};
+              const deepIndent = lines[j + 1].indent;
+              let deepJ = j + 1;
+              while (deepJ < end && lines[deepJ].indent >= deepIndent) {
+                if (lines[deepJ].indent === deepIndent) {
+                  const dColon = lines[deepJ].content.indexOf(":");
+                  if (dColon !== -1) {
+                    const dKey = lines[deepJ].content.slice(0, dColon).trim().replace(/^['"]|['"]$/g, "");
+                    const dVal = lines[deepJ].content.slice(dColon + 1).trim();
+                    deepNested[dKey] = coerceValue(dVal);
+                  }
+                }
+                deepJ++;
+              }
+              nested[subKey] = deepNested;
+              j = deepJ;
+            } else {
+              nested[subKey] = coerceValue(subRaw);
+              j++;
+            }
+          } else {
+            j++;
+          }
+        }
+        target[key] = nested;
+        i = j;
+      } else {
+        // Empty value with no children
+        target[key] = "";
+        i++;
+      }
+    } else {
+      // Inline value
+      target[key] = coerceValue(rawValue);
+      i++;
+    }
+  }
+
+  return i - start;
+}
+
+/**
+ * Coerce a raw string value into the appropriate JS type.
+ *
+ * Handles:
+ * - Quoted strings: "hello" or 'hello' → hello
+ * - Booleans: true/false
+ * - Numbers: 42, 0.7
+ * - Inline arrays: [a, b, c]
+ * - Everything else: string
+ */
+function coerceValue(raw: string): unknown {
+  // Inline array: [a, b, c]
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    const inner = raw.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(",").map((s) => coerceValue(s.trim()) as string);
+  }
+
+  // Quoted strings — strip quotes, keep inner content
+  if (
+    (raw.startsWith('"') && raw.endsWith('"')) ||
+    (raw.startsWith("'") && raw.endsWith("'"))
+  ) {
+    return raw.slice(1, -1);
+  }
+
+  // Booleans
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+
+  // Numbers (integer or float)
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+
+  // Plain string
+  return raw;
+}

package/src/config/paths.ts

@@ -0,0 +1,120 @@
+/**
+ * Discovery paths for agent definition files.
+ *
+ * Scans three path families: pi, OpenCode, and shared.
+ * Project paths override global paths by agent name.
+ */
+
+import * as path from "node:path";
+import * as os from "node:os";
+
+export interface DiscoveryPath {
+  /** Absolute directory path to scan */
+  dir: string;
+  /** Whether this is a global or project-scoped path */
+  source: "global" | "project";
+  /** Which path family this belongs to */
+  family: "pi" | "opencode" | "shared";
+  /**
+   * Subdirectory pattern within the dir to scan.
+   * If empty, scans the dir directly.
+   * Multiple patterns are tried in order.
+   */
+  subdirs: string[];
+}
+
+// ─── Path Builders ───────────────────────────────────────────────────────────
+
+/**
+ * Build all discovery paths for the given cwd and agent dir.
+ *
+ * @param cwd       Current working directory (project root)
+ * @param agentDir  pi agent directory (~/.pi/agent by default)
+ * @returns Ordered list of paths to scan (global first, then project)
+ */
+export function getDiscoveryPaths(cwd: string, agentDir: string): DiscoveryPath[] {
+  const home = os.homedir();
+  const opencodeHome = path.join(home, ".opencode");
+  const opencodeConfig = path.join(home, ".config", "opencode");
+
+  const paths: DiscoveryPath[] = [];
+
+  // ── Global paths (scanned first, lower priority) ──
+
+  // pi global
+  paths.push({
+    dir: path.join(agentDir, "agents"),
+    source: "global",
+    family: "pi",
+    subdirs: [""],
+  });
+
+  // OpenCode global (config dir)
+  paths.push({
+    dir: opencodeConfig,
+    source: "global",
+    family: "opencode",
+    subdirs: ["agent", "agents", "mode", "modes"],
+  });
+
+  // OpenCode global (home .opencode)
+  paths.push({
+    dir: opencodeHome,
+    source: "global",
+    family: "opencode",
+    subdirs: ["agent", "agents", "mode", "modes"],
+  });
+
+  // ── Project paths (scanned after global, higher priority) ──
+
+  // pi project
+  paths.push({
+    dir: path.join(cwd, ".pi", "agents"),
+    source: "project",
+    family: "pi",
+    subdirs: [""],
+  });
+
+  // OpenCode project
+  paths.push({
+    dir: path.join(cwd, ".opencode"),
+    source: "project",
+    family: "opencode",
+    subdirs: ["agent", "agents", "mode", "modes"],
+  });
+
+  // Shared (cross-runtime)
+  paths.push({
+    dir: path.join(cwd, ".agents"),
+    source: "project",
+    family: "shared",
+    subdirs: [""],
+  });
+
+  return paths;
+}
+
+/**
+ * Derive the agent name from a file path, using the discovery path info.
+ *
+ * For pi/shared: uses the filename without extension
+ *   .pi/agents/my-agent.md → "my-agent"
+ *
+ * For OpenCode: strips the subdir prefix
+ *   .opencode/agent/triage.md → "triage"
+ *   .opencode/agents/deep/code-review.md → "deep-code-review" (flattened)
+ *
+ * An explicit `name:` in frontmatter always takes precedence.
+ */
+export function deriveAgentName(filePath: string, basePath: string, subdir: string): string {
+  const fullPath = subdir ? path.join(basePath, subdir) : basePath;
+  const relative = path.relative(fullPath, filePath);
+
+  // Remove .md extension
+  const withoutExt = relative.replace(/\.md$/i, "");
+
+  // Normalize path separators
+  const normalized = withoutExt.replace(/[/\\]/g, "-");
+
+  return normalized;
+}