pi-extended-teams 2.1.16

package/extensions/resources/spawn-resource-plan.ts

@@ -0,0 +1,247 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadSettings, type PiExtendedTeamsSettings } from "../../src/utils/settings";
+
+const SELF_COMMAND_NAME = "agents-extensions";
+export const EXTENSIONS_COMMAND_DESCRIPTION = "Select which observable loaded Pi extensions spawned agents receive.";
+const GENERIC_TOOL_SOURCES = new Set(["builtin", "sdk"]);
+
+type ResourceScope = "user" | "project" | "temporary";
+
+export interface ExtensionSourceInfo {
+  path: string;
+  source: string;
+  scope: ResourceScope;
+  origin: "package" | "top-level";
+  baseDir?: string;
+}
+
+export interface LeadExtensionSnapshot {
+  /** Stable, human-readable selector when unique in the current lead snapshot. */
+  name: string;
+  /** Canonical filesystem identity used for deterministic deduplication. */
+  identity: string;
+  /** Pi's registered extension entrypoint path, passed to the child unchanged. */
+  path: string;
+  sourceInfo: ExtensionSourceInfo;
+  isSelf: boolean;
+}
+
+export type SpawnExtensionState = "selected" | "available" | "blocked" | "self";
+
+export interface SpawnExtensionCandidate extends LeadExtensionSnapshot {
+  selector: string;
+  selected: boolean;
+  state: SpawnExtensionState;
+}
+
+export type SpawnResourceDiagnosticCode =
+  | "stale-selection"
+  | "blocked-selection"
+  | "self-excluded";
+
+export interface SpawnResourceDiagnostic {
+  code: SpawnResourceDiagnosticCode;
+  message: string;
+  configuredEntry?: string;
+}
+
+export interface SpawnResourcePlan {
+  selectionMode: "default" | "explicit";
+  extensionPaths: readonly string[];
+  selfExtensionPath?: string;
+  extensions: readonly SpawnExtensionCandidate[];
+  diagnostics: readonly SpawnResourceDiagnostic[];
+  skills: "all";
+  trust: Readonly<{
+    cwd: string;
+    projectTrusted: boolean;
+  }>;
+}
+
+interface LeadRegistrationApi {
+  getCommands?(): Array<{
+    name?: string;
+    description?: string;
+    source?: string;
+    sourceInfo?: ExtensionSourceInfo;
+  }>;
+  getAllTools?(): Array<{
+    name?: string;
+    sourceInfo?: ExtensionSourceInfo;
+  }>;
+}
+
+export interface CreateSpawnResourcePlanOptions {
+  cwd: string;
+  projectTrusted: boolean;
+  settings?: PiExtendedTeamsSettings;
+  pi?: LeadRegistrationApi;
+  leadExtensions?: readonly LeadExtensionSnapshot[];
+}
+
+function canonicalPath(filePath: string): string {
+  const absolute = path.resolve(filePath);
+  try {
+    return fs.realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+function extensionName(filePath: string): string {
+  const normalized = filePath.replace(/\\/g, "/");
+  const base = normalized.split("/").pop() || normalized;
+  if (/^index\.(?:[cm]?[jt]s)$/.test(base)) {
+    const segments = normalized.split("/");
+    const parent = segments.at(-2) || base;
+    return parent === "extensions" ? segments.at(-3) || parent : parent;
+  }
+  return base.replace(/\.(?:[cm]?[jt]s)$/, "") || base;
+}
+
+function usableSourceInfo(sourceInfo: ExtensionSourceInfo | undefined): sourceInfo is ExtensionSourceInfo {
+  return !!sourceInfo
+    && typeof sourceInfo.path === "string"
+    && sourceInfo.path.length > 0
+    && !sourceInfo.path.startsWith("<");
+}
+
+/**
+ * Snapshot extensions observable through Pi's public registration APIs.
+ *
+ * Pi currently exposes sourceInfo for commands and tools, not for event-only,
+ * renderer-only, shortcut-only, or provider-only extensions. Those extensions
+ * cannot be observed or propagated without using private loader internals.
+ */
+export function snapshotLeadExtensions(pi: LeadRegistrationApi): readonly LeadExtensionSnapshot[] {
+  const commands = typeof pi.getCommands === "function" ? pi.getCommands() : [];
+  const tools = typeof pi.getAllTools === "function" ? pi.getAllTools() : [];
+  const selfPaths = new Set(commands
+    .filter((command) => command.source === "extension"
+      && (command.description === EXTENSIONS_COMMAND_DESCRIPTION
+        || (command.description === undefined && command.name === SELF_COMMAND_NAME)))
+    .map((command) => command.sourceInfo)
+    .filter(usableSourceInfo)
+    .map((sourceInfo) => canonicalPath(sourceInfo.path)));
+
+  const registrations = [
+    ...commands
+      .filter((command) => command.source === "extension")
+      .map((command) => command.sourceInfo),
+    ...tools
+      .filter((tool) => !GENERIC_TOOL_SOURCES.has(tool.sourceInfo?.source ?? ""))
+      .map((tool) => tool.sourceInfo),
+  ].filter(usableSourceInfo);
+
+  const seen = new Set<string>();
+  const snapshot: LeadExtensionSnapshot[] = [];
+  for (const sourceInfo of registrations) {
+    const identity = canonicalPath(sourceInfo.path);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    snapshot.push(Object.freeze({
+      name: extensionName(sourceInfo.path),
+      identity,
+      path: sourceInfo.path,
+      sourceInfo: Object.freeze({ ...sourceInfo }),
+      isSelf: selfPaths.has(identity),
+    }));
+  }
+  return Object.freeze(snapshot);
+}
+
+/** Only propagate trust to the same cwd whose trust the parent context resolved. */
+export function parentProjectTrustForSpawn(ctx: any, spawnCwd: string): boolean {
+  if (!ctx || typeof ctx.isProjectTrusted !== "function" || typeof ctx.cwd !== "string") return false;
+  if (path.resolve(ctx.cwd) !== path.resolve(spawnCwd)) return false;
+  return ctx.isProjectTrusted() === true;
+}
+
+function normalized(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function entryMatchesExtension(entry: string, extension: LeadExtensionSnapshot, cwd: string): boolean {
+  if (entry === extension.name || normalized(entry) === normalized(extension.path)) return true;
+  if (!path.isAbsolute(entry) && !entry.startsWith(".")) return false;
+  return canonicalPath(path.resolve(cwd, entry)) === extension.identity;
+}
+
+function deepFreezePlan(plan: SpawnResourcePlan): SpawnResourcePlan {
+  for (const extension of plan.extensions) Object.freeze(extension);
+  for (const diagnostic of plan.diagnostics) Object.freeze(diagnostic);
+  Object.freeze(plan.extensionPaths);
+  Object.freeze(plan.extensions);
+  Object.freeze(plan.diagnostics);
+  Object.freeze(plan.trust);
+  return Object.freeze(plan);
+}
+
+/** Apply spawned-agent allow/block policy to an immutable lead-session snapshot. */
+export function createSpawnResourcePlan(options: CreateSpawnResourcePlanOptions): SpawnResourcePlan {
+  const cwd = path.resolve(options.cwd);
+  const settings = options.settings ?? loadSettings({
+    projectDir: options.projectTrusted ? cwd : undefined,
+  });
+  const snapshot = options.leadExtensions ?? snapshotLeadExtensions(options.pi ?? {});
+  const allow = settings.extensions.allow;
+  const blocked = settings.extensions.block;
+  const nameCounts = new Map<string, number>();
+  for (const extension of snapshot) nameCounts.set(extension.name, (nameCounts.get(extension.name) ?? 0) + 1);
+
+  const records = snapshot.map((extension) => {
+    const isBlocked = blocked.some((entry) => entryMatchesExtension(entry, extension, cwd));
+    const explicitlyAllowed = allow?.some((entry) => entryMatchesExtension(entry, extension, cwd)) ?? false;
+    const selected = !extension.isSelf && !isBlocked && (allow === null || explicitlyAllowed);
+    const state: SpawnExtensionState = extension.isSelf
+      ? "self"
+      : isBlocked
+        ? "blocked"
+        : selected
+          ? "selected"
+          : "available";
+    return Object.freeze({
+      ...extension,
+      selector: nameCounts.get(extension.name) === 1 ? extension.name : extension.path,
+      selected,
+      state,
+    });
+  });
+
+  const diagnostics: SpawnResourceDiagnostic[] = [];
+  if (allow !== null) {
+    for (const configuredEntry of allow) {
+      const matches = records.filter((record) => entryMatchesExtension(configuredEntry, record, cwd));
+      if (matches.length === 0) {
+        diagnostics.push({
+          code: "stale-selection",
+          configuredEntry,
+          message: `Configured extension is not observable in the lead Pi session: ${configuredEntry}`,
+        });
+      } else if (matches.every((record) => record.isSelf)) {
+        diagnostics.push({
+          code: "self-excluded",
+          configuredEntry,
+          message: `pi-extended-teams is injected by identity and is not an external selection: ${configuredEntry}`,
+        });
+      } else if (matches.every((record) => record.state === "blocked")) {
+        diagnostics.push({
+          code: "blocked-selection",
+          configuredEntry,
+          message: `Configured extension is blocked for spawned agents: ${configuredEntry}`,
+        });
+      }
+    }
+  }
+
+  return deepFreezePlan({
+    selectionMode: allow === null ? "default" : "explicit",
+    extensionPaths: records.filter((extension) => extension.selected).map((extension) => extension.path),
+    selfExtensionPath: records.find((extension) => extension.isSelf)?.path,
+    extensions: records,
+    diagnostics,
+    skills: "all",
+    trust: { cwd, projectTrusted: options.projectTrusted },
+  });
+}

package/extensions/runtime/active-agent-sleep.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createActiveAgentSleepController,
+  runWithActiveAgentSleepAssertion,
+} from "./active-agent-sleep.js";
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function fakeChild() {
+  const listeners = new Map<string, (...args: unknown[]) => void>();
+  const child = {
+    kill: vi.fn(() => true),
+    unref: vi.fn(),
+    once: vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+      listeners.set(event, listener);
+      return child;
+    }),
+  };
+  return {
+    child,
+    emit(event: string, ...args: unknown[]) {
+      listeners.get(event)?.(...args);
+    },
+  };
+}
+
+function darwinController() {
+  const process = fakeChild();
+  const spawnProcess = vi.fn(() => process.child);
+  const controller = createActiveAgentSleepController({
+    platform: "darwin",
+    pid: 4242,
+    executable: "/usr/bin/caffeinate",
+    executableExists: vi.fn(() => true),
+    spawnProcess,
+  });
+  return { controller, process, spawnProcess };
+}
+
+describe("active agent sleep controller", () => {
+  it("shares one idle-sleep assertion until the final concurrent agent releases it", () => {
+    const { controller, process, spawnProcess } = darwinController();
+
+    const releaseFirst = controller.retain();
+    const releaseSecond = controller.retain();
+
+    expect(spawnProcess).toHaveBeenCalledOnce();
+    expect(spawnProcess).toHaveBeenCalledWith(
+      "/usr/bin/caffeinate",
+      ["-i", "-w", "4242"],
+      { stdio: "ignore" },
+    );
+    expect(process.child.unref).toHaveBeenCalledOnce();
+
+    releaseFirst();
+    expect(process.child.kill).not.toHaveBeenCalled();
+
+    releaseSecond();
+    releaseSecond();
+    expect(process.child.kill).toHaveBeenCalledOnce();
+    expect(process.child.kill).toHaveBeenCalledWith("SIGTERM");
+  });
+
+  it.each([
+    { name: "non-macOS", platform: "linux", executableExists: true },
+    { name: "missing caffeinate", platform: "darwin", executableExists: false },
+  ])("is a safe no-op on $name", ({ platform, executableExists }) => {
+    const spawnProcess = vi.fn();
+    const controller = createActiveAgentSleepController({
+      platform,
+      pid: 4242,
+      executable: "/usr/bin/caffeinate",
+      executableExists: vi.fn(() => executableExists),
+      spawnProcess,
+    });
+
+    const release = controller.retain();
+    expect(spawnProcess).not.toHaveBeenCalled();
+    expect(() => release()).not.toThrow();
+    expect(() => controller.dispose()).not.toThrow();
+  });
+
+  it("falls back without failing the agent when caffeinate cannot be spawned", () => {
+    const spawnProcess = vi.fn(() => {
+      throw new Error("spawn failed");
+    });
+    const controller = createActiveAgentSleepController({
+      platform: "darwin",
+      pid: 4242,
+      executable: "/usr/bin/caffeinate",
+      executableExists: vi.fn(() => true),
+      spawnProcess,
+    });
+
+    const release = controller.retain();
+    expect(spawnProcess).toHaveBeenCalledOnce();
+    expect(() => release()).not.toThrow();
+  });
+
+  it("keeps the shared assertion until all wrapped agent runs settle", async () => {
+    const { controller, process, spawnProcess } = darwinController();
+    const first = deferred<void>();
+    const second = deferred<void>();
+
+    const firstRun = runWithActiveAgentSleepAssertion(controller, () => first.promise);
+    const secondRun = runWithActiveAgentSleepAssertion(controller, () => second.promise);
+
+    expect(spawnProcess).toHaveBeenCalledOnce();
+    first.resolve();
+    await firstRun;
+    expect(process.child.kill).not.toHaveBeenCalled();
+
+    second.resolve();
+    await secondRun;
+    expect(process.child.kill).toHaveBeenCalledOnce();
+  });
+
+  it("releases the assertion after synchronous launch failure and async rejection", async () => {
+    const releaseSync = vi.fn();
+    const releaseAsync = vi.fn();
+    const controller = {
+      retain: vi.fn()
+        .mockReturnValueOnce(releaseSync)
+        .mockReturnValueOnce(releaseAsync),
+      dispose: vi.fn(),
+    };
+
+    expect(() => runWithActiveAgentSleepAssertion(controller, () => {
+      throw new Error("sync failure");
+    })).toThrow("sync failure");
+    expect(releaseSync).toHaveBeenCalledOnce();
+
+    await expect(runWithActiveAgentSleepAssertion(controller, async () => {
+      throw new Error("async failure");
+    })).rejects.toThrow("async failure");
+    expect(releaseAsync).toHaveBeenCalledOnce();
+  });
+
+  it("force-releases the assertion during extension disposal", () => {
+    const { controller, process } = darwinController();
+    const release = controller.retain();
+
+    controller.dispose();
+    release();
+
+    expect(process.child.kill).toHaveBeenCalledOnce();
+    expect(process.child.kill).toHaveBeenCalledWith("SIGTERM");
+  });
+});

package/extensions/runtime/active-agent-sleep.ts

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const MACOS_CAFFEINATE = "/usr/bin/caffeinate";
+const NOOP_RELEASE = () => {};
+
+export interface SleepAssertionProcess {
+  kill(signal?: NodeJS.Signals): boolean;
+  unref(): void;
+  once(event: string, listener: (...args: any[]) => void): unknown;
+}
+
+export interface ActiveAgentSleepController {
+  retain(): () => void;
+  dispose(): void;
+}
+
+export interface ActiveAgentSleepControllerOptions {
+  platform?: string;
+  pid?: number;
+  executable?: string;
+  executableExists?(path: string): boolean;
+  spawnProcess?(
+    command: string,
+    args: string[],
+    options: { stdio: "ignore" },
+  ): SleepAssertionProcess;
+}
+
+export function createActiveAgentSleepController(
+  options: ActiveAgentSleepControllerOptions = {},
+): ActiveAgentSleepController {
+  const platform = options.platform ?? process.platform;
+  const pid = options.pid ?? process.pid;
+  const executable = options.executable ?? MACOS_CAFFEINATE;
+  const executableExists = options.executableExists ?? existsSync;
+  const spawnProcess = options.spawnProcess ?? ((command, args, spawnOptions) => {
+    return spawn(command, args, spawnOptions);
+  });
+
+  let activeCount = 0;
+  let disposed = false;
+  let assertionProcess: SleepAssertionProcess | null = null;
+
+  const stopAssertion = () => {
+    const child = assertionProcess;
+    assertionProcess = null;
+    if (!child) return;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // The assertion may already have exited. Releasing remains idempotent.
+    }
+  };
+
+  const startAssertion = () => {
+    if (platform !== "darwin" || !executableExists(executable) || assertionProcess) return;
+
+    let child: SleepAssertionProcess | null = null;
+    try {
+      // -i prevents only idle system sleep. Omitting -d/-u intentionally allows
+      // the display to dim and sleep. -w also releases if the lead Pi exits.
+      child = spawnProcess(executable, ["-i", "-w", String(pid)], { stdio: "ignore" });
+      assertionProcess = child;
+      child.once("error", () => {
+        if (assertionProcess === child) assertionProcess = null;
+      });
+      child.once("exit", () => {
+        if (assertionProcess === child) assertionProcess = null;
+      });
+      child.unref();
+    } catch {
+      if (assertionProcess === child) assertionProcess = null;
+      try {
+        child?.kill("SIGTERM");
+      } catch {
+        // Missing/unlaunchable caffeinate is a portable best-effort no-op.
+      }
+    }
+  };
+
+  return {
+    retain() {
+      if (disposed) return NOOP_RELEASE;
+      activeCount += 1;
+      if (activeCount === 1) startAssertion();
+
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        if (disposed) return;
+        activeCount = Math.max(0, activeCount - 1);
+        if (activeCount === 0) stopAssertion();
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      activeCount = 0;
+      stopAssertion();
+    },
+  };
+}
+
+export function runWithActiveAgentSleepAssertion<T>(
+  controller: ActiveAgentSleepController,
+  launch: () => T | PromiseLike<T>,
+): Promise<Awaited<T>> {
+  const release = controller.retain();
+  try {
+    return Promise.resolve(launch()).finally(release);
+  } catch (error) {
+    release();
+    throw error;
+  }
+}

package/extensions/runtime/nested-read-agents.ts

@@ -0,0 +1,22 @@
+import type { Member } from "../../src/utils/models";
+
+export const NESTED_READ_MODEL_SLOTS = [
+  "read-collect",
+  "read-review",
+  "read-analyze",
+  "read-critical",
+] as const;
+
+export type NestedReadModelSlot = (typeof NESTED_READ_MODEL_SLOTS)[number];
+
+export const NESTED_DELEGATION_TOOL_NAMES = ["spawn_agent", "spawn_swarm_agents"] as const;
+
+const ELIGIBLE_PARENT_MODEL_SLOTS = new Set(["write-feature", "write-critical"]);
+
+export function isEligibleNestedReadParent(member: Member): boolean {
+  return member.role === "write"
+    && member.delegationDepth === 0
+    && member.allowNestedReadAgents === true
+    && typeof member.modelSlot === "string"
+    && ELIGIBLE_PARENT_MODEL_SLOTS.has(member.modelSlot);
+}