@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/worktree.d.ts

@@ -0,0 +1,52 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface WorktreeInfo {
+    /** Absolute path to the worktree directory (the copied repo's root). */
+    path: string;
+    /** Branch name created for this worktree (if changes exist). */
+    branch: string;
+    /** Commit SHA that the worktree was created from. */
+    baseSha: string;
+    /**
+     * Where the agent should work inside the worktree: the equivalent of the
+     * cwd the worktree was created from. Equals `path` when that cwd was the
+     * repo root; points at the copied subdirectory when it was deeper (e.g. a
+     * monorepo package), so the requested scoping survives isolation.
+     */
+    workPath: string;
+}
+export declare function setWorktreeIsolationEnabled(enabled: boolean): void;
+export declare function isWorktreeIsolationEnabled(): boolean;
+export interface WorktreeCleanupResult {
+    /** Whether changes were found in the worktree. */
+    hasChanges: boolean;
+    /** Branch name if changes were committed. */
+    branch?: string;
+    /** Worktree path if it was kept. */
+    path?: string;
+}
+/**
+ * Create a temporary git worktree for an agent.
+ * Returns the worktree path, or undefined if not in a git repo.
+ */
+export declare function createWorktree(pi: ExtensionAPI, cwd: string, agentId: string): Promise<WorktreeInfo | undefined>;
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export declare function cleanupWorktree(pi: ExtensionAPI, cwd: string, worktree: WorktreeInfo, agentDescription: string): Promise<WorktreeCleanupResult>;
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export declare function pruneWorktrees(pi: ExtensionAPI, cwd: string): Promise<void>;

package/dist/worktree.js

@@ -0,0 +1,164 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ *
+ * Every git call goes through `pi.exec` (async) rather than `execFileSync`: a
+ * worktree copy can take seconds, and a session that spawns several isolated
+ * agents at once would otherwise serialize them all on the TUI's event loop.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+/**
+ * Project-wide switch for worktree isolation (`worktreeIsolation` in
+ * subagents.json). Default `true` — unchanged behaviour.
+ *
+ * The `"off"` isolation value gives a model a legal way to decline a worktree,
+ * but it still depends on the model choosing it. This is the deterministic half
+ * of the same fix: on a large repo where every worktree costs real time and
+ * disk (#184), turning it off means no caller can create one, whatever it
+ * passes.
+ */
+let worktreeIsolationEnabled = true;
+export function setWorktreeIsolationEnabled(enabled) {
+    worktreeIsolationEnabled = enabled;
+}
+export function isWorktreeIsolationEnabled() {
+    return worktreeIsolationEnabled;
+}
+/**
+ * Run git and return its trimmed stdout, throwing on failure so callers keep
+ * the try/catch control flow `execFileSync` gave them.
+ *
+ * `pi.exec` never rejects — it reports failure in the result — and a command
+ * killed by its timeout comes back as `killed` with an exit code of 0, so both
+ * have to be checked to reproduce `execFileSync`'s "throws on anything but a
+ * clean exit".
+ */
+async function git(pi, cwd, args, timeout) {
+    const result = await pi.exec("git", args, { cwd, timeout });
+    if (result.killed || result.code !== 0) {
+        throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed (exit ${result.code})`);
+    }
+    return result.stdout.trim();
+}
+/**
+ * Create a temporary git worktree for an agent.
+ * Returns the worktree path, or undefined if not in a git repo.
+ */
+export async function createWorktree(pi, cwd, agentId) {
+    // Verify we're in a git repo with at least one commit (HEAD must exist)
+    let baseSha;
+    let subdir;
+    try {
+        await git(pi, cwd, ["rev-parse", "--is-inside-work-tree"], 5000);
+        baseSha = await git(pi, cwd, ["rev-parse", "HEAD"], 5000);
+        // Where cwd sits inside the repo ("" at the root): the agent must work at
+        // the same subdirectory inside the copy, or a monorepo-package cwd would
+        // silently widen to the whole repo. realpath both sides — git emits
+        // resolved paths while cwd may arrive through a symlink (macOS /tmp).
+        const topLevel = await git(pi, cwd, ["rev-parse", "--show-toplevel"], 5000);
+        subdir = relative(realpathSync(topLevel), realpathSync(cwd));
+    }
+    catch {
+        return undefined;
+    }
+    const branch = `pi-agent-${agentId}`;
+    const suffix = randomUUID().slice(0, 8);
+    const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+    try {
+        // Create detached worktree at HEAD
+        await git(pi, cwd, ["worktree", "add", "--detach", worktreePath, "HEAD"], 30000);
+        return { path: worktreePath, branch, baseSha, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
+    }
+    catch {
+        // If worktree creation fails, return undefined (agent runs in normal cwd)
+        return undefined;
+    }
+}
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export async function cleanupWorktree(pi, cwd, worktree, agentDescription) {
+    if (!existsSync(worktree.path)) {
+        return { hasChanges: false };
+    }
+    try {
+        // Check for uncommitted changes in the worktree
+        const status = await git(pi, worktree.path, ["status", "--porcelain"], 10000);
+        if (status) {
+            // Changes exist — stage, commit, and create a branch
+            await git(pi, worktree.path, ["add", "-A"], 10000);
+            // Truncate description for commit message (no shell sanitization needed — pi.exec uses argv)
+            const safeDesc = agentDescription.slice(0, 200);
+            const commitMsg = `pi-agent: ${safeDesc}`;
+            await git(pi, worktree.path, ["commit", "--no-verify", "-m", commitMsg], 10000);
+        }
+        else {
+            const currentSha = await git(pi, worktree.path, ["rev-parse", "HEAD"], 5000);
+            if (currentSha === worktree.baseSha) {
+                // No changes — remove worktree
+                await removeWorktree(pi, cwd, worktree.path);
+                return { hasChanges: false };
+            }
+        }
+        // Create a branch pointing to the worktree's HEAD.
+        // If the branch already exists, append a suffix to avoid overwriting previous work.
+        let branchName = worktree.branch;
+        try {
+            await git(pi, worktree.path, ["branch", branchName], 5000);
+        }
+        catch {
+            // Branch already exists — use a unique suffix
+            branchName = `${worktree.branch}-${Date.now()}`;
+            await git(pi, worktree.path, ["branch", branchName], 5000);
+        }
+        // Update branch name in worktree info for the caller
+        worktree.branch = branchName;
+        // Remove the worktree (branch persists in main repo)
+        await removeWorktree(pi, cwd, worktree.path);
+        return {
+            hasChanges: true,
+            branch: worktree.branch,
+            path: worktree.path,
+        };
+    }
+    catch {
+        // Best effort cleanup on error
+        try {
+            await removeWorktree(pi, cwd, worktree.path);
+        }
+        catch { /* ignore */ }
+        return { hasChanges: false };
+    }
+}
+/**
+ * Force-remove a worktree.
+ */
+async function removeWorktree(pi, cwd, worktreePath) {
+    try {
+        await git(pi, cwd, ["worktree", "remove", "--force", worktreePath], 10000);
+    }
+    catch {
+        // If git worktree remove fails, try pruning
+        try {
+            await git(pi, cwd, ["worktree", "prune"], 5000);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export async function pruneWorktrees(pi, cwd) {
+    try {
+        await git(pi, cwd, ["worktree", "prune"], 5000);
+    }
+    catch { /* ignore */ }
+}

package/dist/xml.d.ts

@@ -0,0 +1,10 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+/** Escape XML special characters to prevent injection in structured notifications. */
+export declare function escapeXml(s: string): string;

package/dist/xml.js

@@ -0,0 +1,12 @@
+/**
+ * xml.ts — escaping for the `<task-notification>` payloads.
+ *
+ * A module of its own because both notification builders need it and they sit
+ * on opposite sides of a dependency edge: the agent one lives in `index.ts`,
+ * which imports `workflow/task.ts`, so the workflow one cannot reach back for
+ * it without a cycle.
+ */
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/docs/packages.md

@@ -0,0 +1,211 @@
+# Shipping subagents in a pi package
+
+A pi package can declare its own subagents and workflow scripts. Installing the package is then the whole setup — no copying `.md` files into every project's `.pi/agents/`, and no sync script running on container start ([#109](https://github.com/tintinweb/pi-subagents/issues/109)).
+
+This guide is for both sides of that: authoring a package that ships agents, and controlling which packages a machine accepts them from.
+
+For where locally-authored agents live and what their frontmatter accepts, see [`README.md`](../README.md#custom-agents).
+
+## The idea
+
+Pi already ships four resource types inside packages — `extensions`, `skills`, `prompts`, `themes` — declared under a `pi` key in `package.json` and installed with `pi install`. Subagents are this extension's concept, so pi knows nothing about them, and until now a package author's only option was to tell users to copy files.
+
+The mechanism here is the same shape as pi's, with one deliberate difference: **a package must declare its agents by name.** Pi falls back to scanning conventional directories (`skills/`, `prompts/`, …) when a package has no `pi` key at all. This extension never does. A package that happens to carry an `agents/` folder for some other tool contributes nothing until it says so — that is the author's half of the agreement, and installing the package is the user's.
+
+## Authoring
+
+### 1. Declare the paths
+
+```json
+{
+  "name": "my-subagents",
+  "version": "1.0.0",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./src/index.ts"],
+    "subagents": {
+      "agents": ["./agents"],
+      "workflows": ["./workflows"]
+    }
+  }
+}
+```
+
+`keywords: ["pi-package"]` is pi's discoverability convention, not a requirement. The `extensions` entry is only there to show the keys coexisting — a package can ship agents and nothing else.
+
+Adding `pi.subagents` is safe for pi itself: its manifest reader looks at `extensions`, `skills`, `prompts` and `themes` and ignores every other key.
+
+### 2. Put the files there
+
+```
+my-subagents/
+├── package.json
+├── agents/
+│   ├── researcher.md
+│   └── reviewer.md
+└── workflows/
+    └── audit.js
+```
+
+An agent file is an ordinary agent `.md` — the same frontmatter a `.pi/agents/` file takes, documented in [`README.md`](../README.md#custom-agents). A workflow file is an ordinary saved workflow, and still has to carry its `export const meta = …` declaration to count as one ([`workflows.md`](workflows.md)).
+
+```markdown
+---
+name: pkg-researcher
+description: Research with sources, for the my-subagents toolchain
+tools: read, grep, ext:my-mcp/search
+model: claude-haiku-4-5
+---
+
+You research things. Cite what you read.
+```
+
+### 3. Ship it
+
+Include the directories in the published tarball — npm's `files` field, or an `.npmignore` that does not exclude them. Then:
+
+```bash
+pi install npm:my-subagents          # published
+pi install git:github.com/me/repo    # straight from git
+pi install /path/to/my-subagents     # local checkout, for development
+pi install ./my-subagents -l         # project scope, into .pi/settings.json
+```
+
+A local-path install is not copied, so an edit to the agent file is live on the next `Agent` call — the fastest authoring loop.
+
+### Entry syntax
+
+Entries are paths relative to the package root.
+
+| Entry | Meaning |
+|---|---|
+| `"./agents"` | A directory. Scanned for `*.md` (`*.js` for workflows), non-recursively. |
+| `"./agents/one.md"` | A single file, taken as-is. |
+| `"!./agents/wip.md"` | An exclusion. Applies to a file inside an included directory, which is the only form that does anything useful. |
+
+The exclusion may name a path the package does not ship yet, so a file added in a later version is still skipped rather than silently appearing.
+
+Nothing outside the package root is read. The containment check runs on canonical paths, so `../../.ssh` is refused and a symlinked `agents/` pointing at `/etc` does not get around it either.
+
+Glob patterns are deliberately **not** supported. Pi expands globs because it resolves four resource types across arbitrary layouts; here the entries are one or two directories, and answering a glob would mean walking a third-party tree.
+
+### Accepted spellings
+
+All four mean the same thing. The top-level `pi-subagents` key is the one [`nicobailon/pi-subagents`](https://github.com/nicobailon/pi-subagents) reads, so a single manifest works with either extension.
+
+```jsonc
+"pi": { "subagents": { "agents": ["./agents"], "workflows": ["./flows"] } }
+"pi": { "subagents": ["./agents"] }            // shorthand for { "agents": [...] }
+"pi-subagents": { "agents": ["./agents"] }
+"pi-subagents": ["./agents"]                   // shorthand for { "agents": [...] }
+```
+
+`pi.subagents` wins if a package carries both.
+
+### Naming
+
+A package agent registers under its frontmatter `name:`, with no namespace prefix. There is no `mypkg:researcher` form (yet — the `:` character stays reserved for it, so agent names may not contain one).
+
+That makes a name a shared space, so prefix anything that could collide: `acme-researcher` rather than `researcher`. Two packages claiming one name is last-load-wins with a warning naming the file that took over, and *any* local file claiming it takes it from both.
+
+## Operating
+
+### Which packages are read
+
+Only what pi itself has installed — the `packages[]` array in pi's `settings.json`, global (`~/.pi/agent/settings.json`) and project (`.pi/settings.json`), resolved through pi's own package manager so npm, git and local sources all land on the right install root.
+
+`node_modules` is never scanned. Being a transitive dependency of your project means nothing here, exactly as it means nothing to pi.
+
+A package listed only by a project's settings stays invisible until you trust the project, matching pi — an untrusted `.pi/settings.json` is not read at all. This is the shape a team distributes agents in: commit the package to `.pi/settings.json`, and everyone who trusts the repo gets them.
+
+One wrinkle on the *very first* session in a repo, before pi has saved a trust decision. The `Agent` tool's description — the list of agent types the model is told about — is built when the extension loads, which is before the trust prompt is answered. A project-scoped package's agents are registered and can be spawned by name that session, but the model is not told they exist until the next one. Once the decision is saved (or `defaultProjectTrust` is `"always"`), every later session is correct from the first turn.
+
+### Precedence
+
+Lowest to highest:
+
+| | Source |
+|---|---|
+| 1 (lowest) | Built-in agents (`general-purpose`, `Explore`, `Plan`) |
+| 2 | Installed pi packages |
+| 3 | `$PI_CODING_AGENT_DIR/agents/*.md` (global) |
+| 4 | `.agents/agents/*.md` (project workspace) |
+| 5 (highest) | `.pi/agents/*.md` (project) |
+
+A package can offer a `reviewer`; it can never take the name from a `reviewer` of yours. This mirrors pi's own precedence for package-provided skills and Claude Code's for plugin agents.
+
+Saved workflows resolve first-hit-wins over the same ordering, so package directories are searched last.
+
+One consequence worth knowing: a package agent *does* outrank a built-in. A package could ship a `general-purpose` — which is also the default `fallbackSubagent` — and take over unspecified delegation. Narrow the gate below if that matters for your setup.
+
+### In `/agents`
+
+A package agent is listed with a `▪` badge and is read-only: its file lives under pi's install root, where an edit is lost on the next `pi update` and a delete is undone by the next `pi install`.
+
+The badge says a package won, not which one. The declaring package's name — the full `@scope/name`, which is also what you can write into a [`packageAgents` allowlist](#turning-it-off) — is prefixed to the description line under the highlighted row, and titles the agent's action menu.
+
+- **Eject** copies it into your project or personal agent directory as an editable file that shadows the original. The copy carries the agent's full configuration, including `ext:` tool selectors and `persist_session`.
+- **Disable** writes an `enabled: false` stub at project or personal scope, which shadows the package definition without touching it. Deleting that stub restores the package agent.
+
+An agent the *package author* shipped with `enabled: false` shows as disabled and offers no Enable — only the package can take that back. Ejecting it is the way out: the copy is written without an `enabled:` line, so the ejected agent is on.
+
+### Turning it off
+
+`packageAgents` and `packageWorkflows` in [`subagents.json`](../README.md#persistent-settings) both default to `true`:
+
+```json
+{
+  "packageAgents": ["my-subagents"],
+  "packageWorkflows": false
+}
+```
+
+| Value | Effect |
+|---|---|
+| `true` (or absent) | Every declaring package contributes. |
+| `false` | None do. |
+| `["a", "b"]` | Only those packages. |
+
+A list entry matches the unscoped short name (`@acme/tools` → `tools`), the full package name, or the settings source string, case-insensitively. A bare string is read as a one-entry list, so a `"my-pkg"` typo narrows the gate rather than silently widening it.
+
+The two are separate on purpose: an agent is markdown handed to a model, a workflow is JavaScript this extension executes, so package agents can be accepted while package workflow scripts are refused.
+
+Both appear in `/agents → Settings` as on/off rows. An allowlist is hand-written in `subagents.json`; toggling the row replaces it, and the toast says what it replaced.
+
+### Why on by default
+
+Installing a package is already the trust decision. Pi executes an installed package's `extensions/` and puts its `skills/` descriptions in the system prompt, with no per-resource prompt — [pi's own docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) say so plainly: *"Pi packages run with full system access."*
+
+A declared `.md` agent is strictly less privileged than what the same package already runs, so it rides the boundary the user crossed at `pi install` rather than inventing a second one. The gate exists for narrowing that anyway, not as a second install step.
+
+## Troubleshooting
+
+**The agent does not appear.**
+
+1. `pi list` — is the package in pi's settings at all? Discovery reads that array, not `node_modules`, and not a `pi -e` source: a `--extension` install is resolved for that one run and never written to `packages[]`, so its agents stay invisible even though its extensions and skills load.
+2. Does `package.json` carry `pi.subagents` (or `pi-subagents`)? A `pi` key that declares only `extensions` contributes no agents; the conventional `agents/` directory is not scanned.
+3. Is the file `*.md` directly inside a declared directory? The scan is not recursive.
+4. Does the frontmatter parse, and does it have a `name:`? A broken file is skipped with a `[pi-subagents] Skipping agent file …` warning on stderr.
+5. Is `packageAgents` set to `false` or to a list that does not include it? Check `/agents → Settings → Package agents`.
+6. Is the package configured only in an untrusted project's `.pi/settings.json`? Trust the project, or install it globally.
+
+**It appears but a different one runs.** A local file of the same name outranks it. `/agents` shows the badge of whichever won — `•` project, `◦` global, `▪` package.
+
+**Edits to the package file do nothing.** Agents reload on every `Agent` call, so a local-path install picks up edits immediately. An npm or git install is a copy under `~/.pi/agent/{npm,git}/`; edit the source and reinstall, or install the local path during development.
+
+**A file over 1 MB is skipped.** Package files are third-party content re-read on every spawn, so there is a per-file ceiling, matching Claude Code's for plugin agents. Local files are unbounded.
+
+**`strictAgentFiles` and a broken package file.** Strict mode fails startup over an unparseable file in *your* `.pi/agents/`, which is the point of it. It deliberately does not extend to files inside installed packages — those are not yours to fix, and one bad `.md` in a dependency should not stop pi from starting.
+
+## Reference
+
+| | |
+|---|---|
+| Manifest keys | `pi.subagents.agents`, `pi.subagents.workflows`, `pi-subagents.agents`, `pi-subagents.workflows`, plus the bare-array shorthand for each |
+| Settings | `packageAgents`, `packageWorkflows` — `boolean \| string[]`, default `true` |
+| Agent file layout | `<declared dir>/*.md`, non-recursive |
+| Workflow file layout | `<declared dir>/*.js`, must carry `export const meta = …` |
+| Per-file size ceiling | 1 MiB |
+| Discovery source | pi's `settings.json → packages[]`, global and project |
+| Precedence | Above built-ins, below every local agent |
+| Implementation | [`src/package-resources.ts`](../src/package-resources.ts) |