@pify/swarm 0.6.2 → 0.7.0

package/README.md

@@ -57,7 +57,7 @@ match_keywords: rust, memory safety
 
 `match_patterns` are globs matched against path-like tokens in the item — the longest match wins, so a specific rule beats a general one. `match_keywords` match the item's words. `review src/auth.rs` routes to the Rust auditor; `test the login flow` to a tester; anything matching nothing falls back to the read-only `scout`, so **the fallback can never mutate**.
 
-The catalog is the same `.pi/agents/*.md` one [`@pify/subagent`](https://github.com/pifydev/subagent) reads — `description`, `tools`, `model`, `thinking`, `max_turns` — plus the two routing keys. Project-local definitions load only once pi's project trust has been granted.
+The catalog is the same `.pi/agents/*.md` one [`@pify/subagent`](https://github.com/pifydev/subagent) reads — `description`, `tools`, `model`, `thinking`, `max_turns` — plus the two routing keys. Project-local definitions load only after you approve them — once per project, remembered in `pify-project-consent.json`, the same "agents" answer [`@pify/subagent`](https://github.com/pifydev/subagent) records, so approving or refusing once means the same thing across the suite. pi's own project trust is necessary but not sufficient here: pi only asks about trust when a repo ships something pi itself loads, and `.pi/agents/` is not on that list — measured, a repo whose only pi file is `.pi/agents/reviewer.md` reports `isProjectTrusted=true`. For CI, `PIFY_TRUST_PROJECT=1`. (Earlier versions of this paragraph claimed the gate existed before it did; as of v0.7.0 it does.)
 
 ## Behaviour
 
@@ -67,7 +67,7 @@ The catalog is the same `.pi/agents/*.md` one [`@pify/subagent`](https://github.
 
 ## A background run comes back to you
 
-`swarm_status` on a run still in flight used to say "still running", which left the model one option: ask again. Now the aggregated report is **delivered** into the conversation when the run finishes, and asking early returns a structured result carrying `retryable`, the elapsed time and `pollRequired: false` — a normal answer rather than an error, because a tool error over a condition only time resolves invites the model's retry machinery into a loop.
+`swarm_status` on a run still in flight used to say "still running", which left the model one option: ask again. The aggregated report is *sent* into the conversation when the run finishes — honestly: this delivery mechanism is the same one whose only live measurement in the suite (subagent's) currently fails under print mode's teardown, and swarm has no live test of its own yet, so treat delivery as unmeasured and `swarm_status` as the reliable path. Asking early returns a structured result carrying `retryable`, the elapsed time and `pollRequired: false` — a normal answer rather than an error, because a tool error over a condition only time resolves invites the model's retry machinery into a loop.
 
 ## Command
 

package/extensions/swarm.ts

@@ -25,6 +25,14 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { BUILTIN_AGENTS } from "../src/builtin.ts";
+import {
+  consentQuestion,
+  decideConsent,
+  envConsent,
+  parseConsent,
+  readConsent,
+  writeConsent,
+} from "../src/consent.ts";
 import { LiveChildren, cancelNote, type CancelReason } from "../src/cancel.ts";
 import { DELIVERY_TYPE, deliveryMessage, pendingResult } from "../src/pending.ts";
 import { createIsolationWorktree, isolationNote, removeIfUnchanged } from "../src/isolate.ts";
@@ -41,7 +49,7 @@ import {
   type ItemState,
   type SwarmRun,
 } from "../src/types.ts";
-import { readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
 const RUN_ENTRY = "swarm-run";
@@ -50,16 +58,23 @@ const CLEAN_WORKTREE_NOTE =
 
 type UiContext = ExtensionContext;
 
-function loadDefs(cwd: string, agentDir: string): Map<string, AgentDef> {
+function loadDefs(cwd: string, agentDir: string, projectAllowed: boolean): Map<string, AgentDef> {
   const defs = new Map<string, AgentDef>();
   for (const [name, content] of Object.entries(BUILTIN_AGENTS)) {
     const def = parseAgentFile(name, content, "builtin");
     if (def) defs.set(def.name, def);
   }
-  for (const [dir, source] of [
-    [join(agentDir, "agents"), "global"],
-    [join(cwd, ".pi", "agents"), "project"],
-  ] as const) {
+  // The project directory is consent-gated: `.pi/agents/*.md` is repo-shipped
+  // text that becomes a CHILD SYSTEM PROMPT, overriding builtins of the same
+  // name, and pi never asks about it — measured, a repo whose only pi file is
+  // `.pi/agents/reviewer.md` reports isProjectTrusted=true. One answer,
+  // recorded under the same "agents" scope subagent uses, governs the catalog
+  // across the whole suite.
+  const sources: Array<readonly [string, "global" | "project"]> = [
+    [join(agentDir, "agents"), "global"] as const,
+    ...(projectAllowed ? [[join(cwd, ".pi", "agents"), "project"] as const] : []),
+  ];
+  for (const [dir, source] of sources) {
     try {
       for (const file of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
         try {
@@ -243,6 +258,15 @@ export default function swarm(pi: ExtensionAPI) {
       item.status =
         last?.stopReason === "aborted" ? "aborted" : last?.stopReason === "error" ? "error" : "done";
       if (item.status === "error") item.error = text || "child session error";
+      // A child that stopped cleanly and said nothing has not answered — the
+      // fix subagent already carries and this executor never received. Left
+      // as "done", a reasoning-only finish (measured on anthropic/claude-opus-5
+      // through child sessions) rendered a successful fan-out of "(empty
+      // report)" items. An exit status is not an answer.
+      if (item.status === "done" && !item.result) {
+        item.status = "error";
+        item.error = "the child finished without producing an answer";
+      }
     } catch (err) {
       item.status = "error";
       item.error = err instanceof Error ? err.message : String(err);
@@ -332,6 +356,7 @@ export default function swarm(pi: ExtensionAPI) {
   pi.registerTool({
     name: "swarm_run",
     label: "Run swarm",
+    promptSnippet: "Run many independent items through child agents at once",
     description:
       `Fan out 1-${MAX_ITEMS} independent task items to parallel child agents (concurrency ${DEFAULT_CONCURRENCY}). ` +
       "Each item auto-routes to an agent type via its match_patterns/match_keywords, falling back to the " +
@@ -410,11 +435,11 @@ export default function swarm(pi: ExtensionAPI) {
       }
 
       if (run.background) {
-        void executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true).then(() => {
-          notify(uiCtx, `swarm ${run.runId} finished`, "info");
-          // The report goes to the agent, not only to the screen — otherwise
-          // asking again was its only way to find out.
-          try {
+        void executeRun(uiCtx, run, params.context ?? "", params.agent, params.isolation === "worktree", params.mailbox === true)
+          .then(() => {
+            notify(uiCtx, `swarm ${run.runId} finished`, "info");
+            // The report goes to the agent, not only to the screen — otherwise
+            // asking again was its only way to find out.
             pi.sendMessage(
               {
                 customType: DELIVERY_TYPE,
@@ -424,10 +449,15 @@ export default function swarm(pi: ExtensionAPI) {
               },
               { deliverAs: "followUp", triggerTurn: true },
             );
-          } catch {
-            // Delivery is a convenience; swarm_status still works.
-          }
-        });
+          })
+          .catch(() => {
+            // The whole chain, not just sendMessage: a /reload or session
+            // switch while the run is in flight makes every captured pi/ctx
+            // handle throw "ctx is stale" on next use, and an uncaught
+            // rejection here takes the entire process down with it — the run's
+            // work lost to a notification. Delivery is a convenience;
+            // swarm_status still works.
+          });
         return {
           content: [
             { type: "text", text: `Swarm ${run.runId} started (${items.length} items). Poll swarm_status runId="${run.runId}".` },
@@ -451,6 +481,7 @@ export default function swarm(pi: ExtensionAPI) {
   pi.registerTool({
     name: "swarm_status",
     label: "Swarm status",
+    promptSnippet: "Progress of a running swarm",
     description: "Progress of a swarm run (default: the latest). Returns the full report when finished.",
     parameters: Type.Object({
       runId: Type.Optional(Type.String()),
@@ -481,8 +512,51 @@ export default function swarm(pi: ExtensionAPI) {
 
   // ── Lifecycle & command ──────────────────────────────────────────────
 
+  /** Where the suite records which projects you approved, and for what. */
+  function consentFile(): string {
+    return join(getAgentDir(), "pify-project-consent.json");
+  }
+
+  /**
+   * May this repository's own agent definitions load? Same question, same
+   * store, and the same "agents" scope subagent records — one answer governs
+   * the catalog across subagent, swarm and workflow, so approving or refusing
+   * once means the same thing everywhere.
+   */
+  async function projectAgentsAllowed(ctx: ExtensionContext): Promise<boolean> {
+    const dir = join(ctx.cwd, ".pi", "agents");
+    if (!existsSync(dir)) return false;
+    const file = consentFile();
+    let raw: string | null = null;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch {
+      raw = null;
+    }
+    const store = parseConsent(raw);
+    const verdict = decideConsent({
+      projectTrusted: (ctx as unknown as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() ?? false,
+      remembered: readConsent(store, ctx.cwd, "agents"),
+      hasUI: ctx.hasUI,
+      envOverride: envConsent(process.env),
+    });
+    if (verdict !== "ask") return verdict === "allow";
+
+    const approved = await ctx.ui.confirm(
+      "Load this project's agent definitions?",
+      consentQuestion("its own agent definitions, which override the builtins of the same name", dir),
+    );
+    try {
+      writeFileSync(file, `${JSON.stringify(writeConsent(store, ctx.cwd, "agents", approved), null, 2)}
+`);
+    } catch {
+      // An unwritable consent file costs us the memory of the answer, not the answer.
+    }
+    return approved;
+  }
+
   pi.on("session_start", async (_event, ctx) => {
-    defs = loadDefs(ctx.cwd, getAgentDir());
+    defs = loadDefs(ctx.cwd, getAgentDir(), await projectAgentsAllowed(ctx));
     runs.clear();
     activeRun = null;
     for (const entry of ctx.sessionManager.getBranch()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/swarm",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Coordinate multiple pi agents in parallel: swarm_run fan-out with per-item auto-routing, concurrency queue, aggregated reports",
   "keywords": [
     "pi-package",

package/src/consent.ts

@@ -0,0 +1,116 @@
+/**
+ * Consent for project-supplied files that pi does not know about.
+ *
+ * `ctx.isProjectTrusted()` looked like the right gate, and for pi's own
+ * project resources it is. But pi only *asks* about trust when the repository
+ * ships one of the things pi itself loads — `.pi/settings.json`,
+ * `.pi/extensions`, `.pi/skills`, `.pi/prompts`, `.pi/themes`, `SYSTEM.md`,
+ * `APPEND_SYSTEM.md`. A repository carrying only a repository carrying only its own extension config
+ * triggers no prompt at all, and `isProjectTrusted()` then returns true by
+ * default. Measured, not assumed: a repo whose only pi file was
+ * `.pi/agents/reviewer.md` reported `isProjectTrusted=true`, while the same repo
+ * with a `.pi/skills` directory reported false.
+ *
+ * So a file this extension invented needs consent this extension asks for. pi
+ * saying no is still final — this can only ever be a second gate, never a way
+ * around the first.
+ */
+
+/** What to do with a project-supplied file this session. */
+export type ConsentVerdict = "allow" | "refuse" | "ask";
+
+export interface ConsentInput {
+  /** pi's own decision. False is final. */
+  projectTrusted: boolean;
+  /** What the user answered for this project before, if they ever did. */
+  remembered: boolean | undefined;
+  /** Whether there is a UI to ask through. */
+  hasUI: boolean;
+  /**
+   * PIFY_TRUST_PROJECT, for headless runs. An environment variable is set by
+   * whoever starts the process, never by the repository being read, so it is
+   * a signal from the user and not from the code under inspection.
+   */
+  envOverride?: boolean;
+}
+
+/** Read PIFY_TRUST_PROJECT the same way everywhere. */
+export function envConsent(env: Record<string, string | undefined>): boolean | undefined {
+  const raw = env.PIFY_TRUST_PROJECT?.trim().toLowerCase();
+  if (raw === undefined || raw === "") return undefined;
+  if (raw === "1" || raw === "true" || raw === "yes") return true;
+  if (raw === "0" || raw === "false" || raw === "no") return false;
+  return undefined;
+}
+
+export function decideConsent(input: ConsentInput): ConsentVerdict {
+  // pi already refused; nothing here may widen that.
+  if (!input.projectTrusted) return "refuse";
+  // An explicit answer from the person who started the process outranks a
+  // remembered one — that is what typing it again means.
+  if (input.envOverride !== undefined) return input.envOverride ? "allow" : "refuse";
+  if (input.remembered === true) return "allow";
+  if (input.remembered === false) return "refuse";
+  // Headless runs cannot ask, and a file nobody approved must not be loaded
+  // just because no one was there to say no.
+  if (!input.hasUI) return "refuse";
+  return "ask";
+}
+
+/**
+ * Consent is per project *and* per kind of file: approving a repository's
+ * memory says nothing about approving the agent definitions it also ships.
+ */
+export type ConsentFile = Record<string, Record<string, boolean>>;
+
+export function readConsent(file: ConsentFile, cwd: string, scope: string): boolean | undefined {
+  const entry = file[normalizeCwd(cwd)];
+  if (!entry) return undefined;
+  const value = entry[scope];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+export function writeConsent(
+  file: ConsentFile,
+  cwd: string,
+  scope: string,
+  allowed: boolean,
+): ConsentFile {
+  const key = normalizeCwd(cwd);
+  return { ...file, [key]: { ...(file[key] ?? {}), [scope]: allowed } };
+}
+
+/** Tolerate anything on disk: a corrupt consent file means "never asked". */
+export function parseConsent(raw: string | null): ConsentFile {
+  if (!raw) return {};
+  try {
+    const data = JSON.parse(raw) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+    const out: ConsentFile = {};
+    for (const [cwd, scopes] of Object.entries(data as Record<string, unknown>)) {
+      if (!scopes || typeof scopes !== "object" || Array.isArray(scopes)) continue;
+      const entry: Record<string, boolean> = {};
+      for (const [scope, value] of Object.entries(scopes as Record<string, unknown>)) {
+        if (typeof value === "boolean") entry[scope] = value;
+      }
+      if (Object.keys(entry).length > 0) out[cwd] = entry;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function normalizeCwd(cwd: string): string {
+  return cwd.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+}
+
+export function consentQuestion(what: string, path: string): string {
+  return [
+    `This project ships ${what}:`,
+    `  ${path}`,
+    "",
+    "pi did not ask about it, because it is not one of the files pi itself loads.",
+    "Load it for this project from now on?",
+  ].join("\n");
+}