pi-extended-teams 2.1.16

package/extensions/internal/agent-session-files.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as paths from "../../src/utils/paths.js";
+import {
+  PRIVATE_AGENT_SESSION_RETENTION_MS,
+  cleanupPrivateAgentSessionDirectory,
+  cleanupStalePrivateAgentSessions,
+  preparePrivateAgentSessionDirectory,
+} from "./agent-session-files.js";
+
+let root: string;
+let teamsRoot: string;
+
+function privateRunDirectory(teamName: string, agentName: string, runId: string): string {
+  return path.join(teamsRoot, teamName, "agent-sessions", agentName, runId);
+}
+
+function writeTeamConfig(
+  teamName: string,
+  members: Array<{ name: string; lifecycleRunId?: string; isActive?: boolean }> = [],
+): void {
+  const teamDirectory = path.join(teamsRoot, teamName);
+  fs.mkdirSync(teamDirectory, { recursive: true });
+  fs.writeFileSync(path.join(teamDirectory, "config.json"), JSON.stringify({
+    name: teamName,
+    members: [
+      { name: "team-lead", agentType: "lead" },
+      ...members.map(member => ({ ...member, agentType: "teammate" })),
+    ],
+  }));
+}
+
+function createRunDirectory(teamName: string, agentName: string, runId: string): string {
+  const directory = privateRunDirectory(teamName, agentName, runId);
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(path.join(directory, "session.jsonl"), "private transcript\n");
+  return directory;
+}
+
+describe("private spawned-agent session files", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-private-agent-sessions-"));
+    teamsRoot = path.join(root, "teams");
+    fs.mkdirSync(teamsRoot, { recursive: true });
+    vi.spyOn(paths, "teamDir").mockImplementation(teamName => {
+      return path.join(teamsRoot, paths.sanitizeName(String(teamName)));
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("creates a private per-run directory outside Pi's resumable session tree", () => {
+    writeTeamConfig("team");
+
+    const directory = preparePrivateAgentSessionDirectory("team", "reader", "run-one");
+
+    expect(directory).toBe(privateRunDirectory("team", "reader", "run-one"));
+    expect(directory).not.toContain(path.join(".pi", "agent", "sessions"));
+    expect(fs.statSync(directory).isDirectory()).toBe(true);
+    if (process.platform !== "win32") {
+      expect(fs.statSync(directory).mode & 0o777).toBe(0o700);
+    }
+  });
+
+  it("removes only the exact completed run and preserves sibling and unrelated files", () => {
+    writeTeamConfig("team");
+    const completed = createRunDirectory("team", "reader", "run-completed");
+    const retained = createRunDirectory("team", "reader", "run-retained");
+    const unrelated = path.join(teamsRoot, "team", "notes.txt");
+    fs.writeFileSync(unrelated, "keep");
+
+    expect(cleanupPrivateAgentSessionDirectory("team", "reader", "run-completed")).toBe(true);
+
+    expect(fs.existsSync(completed)).toBe(false);
+    expect(fs.existsSync(retained)).toBe(true);
+    expect(fs.readFileSync(unrelated, "utf8")).toBe("keep");
+  });
+
+  it("removes only stale inactive runs while preserving active and recent recovery runs", () => {
+    const now = Date.now();
+    writeTeamConfig("team", [{ name: "reader", lifecycleRunId: "run-active", isActive: false }]);
+    const active = createRunDirectory("team", "reader", "run-active");
+    const stale = createRunDirectory("team", "reader", "run-stale");
+    const recent = createRunDirectory("team", "reader", "run-recent");
+    const old = new Date(now - PRIVATE_AGENT_SESSION_RETENTION_MS - 1_000);
+    fs.utimesSync(path.join(active, "session.jsonl"), old, old);
+    fs.utimesSync(active, old, old);
+    fs.utimesSync(path.join(stale, "session.jsonl"), old, old);
+    fs.utimesSync(stale, old, old);
+    // The directory was admitted long ago, but its transcript was written recently.
+    fs.utimesSync(recent, old, old);
+
+    const cleaned = cleanupStalePrivateAgentSessions({ teamsRoot, now });
+
+    expect(cleaned).toBe(1);
+    expect(fs.existsSync(active)).toBe(true);
+    expect(fs.existsSync(stale)).toBe(false);
+    expect(fs.existsSync(recent)).toBe(true);
+  });
+
+  it("continues cleaning later stale runs when one private-session removal fails", () => {
+    const now = Date.now();
+    writeTeamConfig("team");
+    const failed = createRunDirectory("team", "reader", "run-failed");
+    const cleaned = createRunDirectory("team", "reader", "run-cleaned");
+    const old = new Date(now - PRIVATE_AGENT_SESSION_RETENTION_MS - 1_000);
+    fs.utimesSync(path.join(failed, "session.jsonl"), old, old);
+    fs.utimesSync(failed, old, old);
+    fs.utimesSync(path.join(cleaned, "session.jsonl"), old, old);
+    fs.utimesSync(cleaned, old, old);
+    const originalRemove = fs.rmSync.bind(fs);
+    const remove = vi.spyOn(fs, "rmSync").mockImplementation((target: any, options?: any) => {
+      if (target === failed) throw new Error("simulated removal failure");
+      return originalRemove(target, options);
+    });
+
+    expect(cleanupStalePrivateAgentSessions({ teamsRoot, now })).toBe(1);
+    expect(remove).toHaveBeenCalledWith(failed, { recursive: true, force: false });
+    expect(fs.existsSync(failed)).toBe(true);
+    expect(fs.existsSync(cleaned)).toBe(false);
+  });
+
+  it("retains an uninspectable stale run while cleaning separately inspectable stale runs", () => {
+    const now = Date.now();
+    writeTeamConfig("team");
+    const uninspectable = createRunDirectory("team", "reader", "run-uninspectable");
+    const inspectable = createRunDirectory("team", "reader", "run-inspectable");
+    const uninspectableTranscript = path.join(uninspectable, "session.jsonl");
+    const old = new Date(now - PRIVATE_AGENT_SESSION_RETENTION_MS - 1_000);
+    fs.utimesSync(uninspectableTranscript, old, old);
+    fs.utimesSync(uninspectable, old, old);
+    fs.utimesSync(path.join(inspectable, "session.jsonl"), old, old);
+    fs.utimesSync(inspectable, old, old);
+
+    const originalLstat = fs.lstatSync.bind(fs) as any;
+    vi.spyOn(fs, "lstatSync").mockImplementation(((target: any, ...args: any[]) => {
+      if (String(target) === uninspectableTranscript) {
+        throw Object.assign(new Error("simulated inspection failure"), { code: "EACCES" });
+      }
+      return originalLstat(target, ...args);
+    }) as any);
+
+    expect(cleanupStalePrivateAgentSessions({ teamsRoot, now })).toBe(1);
+    expect(fs.existsSync(uninspectable)).toBe(true);
+    expect(fs.existsSync(inspectable)).toBe(false);
+  });
+
+  it.runIf(process.platform !== "win32")("refuses symlinked private-session directories", () => {
+    writeTeamConfig("team");
+    const external = path.join(root, "external");
+    fs.mkdirSync(external);
+    const privateRoot = path.join(teamsRoot, "team", "agent-sessions");
+    fs.symlinkSync(external, privateRoot, "dir");
+
+    expect(() => preparePrivateAgentSessionDirectory("team", "reader", "run-one"))
+      .toThrow(/private agent session directory/i);
+    expect(fs.readdirSync(external)).toEqual([]);
+  });
+});

package/extensions/internal/agent-session-files.ts

@@ -0,0 +1,320 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as paths from "../../src/utils/paths";
+
+export const PRIVATE_AGENT_SESSION_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+export interface CleanupStalePrivateAgentSessionsOptions {
+  teamsRoot?: string;
+  now?: number;
+  maxAgeMs?: number;
+}
+
+export interface PrivateAgentSessionRetentionOptions {
+  now?: number;
+  maxAgeMs?: number;
+}
+
+export type PrivateAgentSessionRetentionResult = "recent" | "none" | "unknown";
+
+type DirectoryInspection =
+  | { kind: "directory"; stat: fs.Stats }
+  | { kind: "missing" }
+  | { kind: "unsafe" }
+  | { kind: "error" };
+
+type DirectoryEntriesInspection =
+  | { kind: "entries"; entries: fs.Dirent[] }
+  | { kind: "error" };
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+  const code = error.code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function inspectDirectory(directory: string): DirectoryInspection {
+  try {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return { kind: "unsafe" };
+    return { kind: "directory", stat };
+  } catch (error) {
+    return errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR"
+      ? { kind: "missing" }
+      : { kind: "error" };
+  }
+}
+
+function inspectDirectoryEntries(directory: string): DirectoryEntriesInspection {
+  try {
+    return { kind: "entries", entries: fs.readdirSync(directory, { withFileTypes: true }) };
+  } catch {
+    return { kind: "error" };
+  }
+}
+
+function safeComponent(value: string): string {
+  return paths.sanitizeName(value);
+}
+
+function directoryStat(directory: string): fs.Stats | null {
+  try {
+    const stat = fs.lstatSync(directory);
+    return stat.isDirectory() && !stat.isSymbolicLink() ? stat : null;
+  } catch {
+    return null;
+  }
+}
+
+function ensurePrivateDirectory(directory: string): void {
+  const existing = directoryStat(directory);
+  if (!existing) {
+    try {
+      fs.mkdirSync(directory, { mode: 0o700 });
+    } catch (error: any) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+  const verified = directoryStat(directory);
+  if (!verified) {
+    throw new Error(`Refusing untrusted private agent session directory: ${directory}`);
+  }
+  if (process.platform !== "win32" && (verified.mode & 0o777) !== 0o700) {
+    fs.chmodSync(directory, 0o700);
+    const secured = directoryStat(directory);
+    if (!secured || (secured.mode & 0o777) !== 0o700) {
+      throw new Error(`Could not secure private agent session directory: ${directory}`);
+    }
+  }
+}
+
+function privateSessionRoot(teamName: string): string {
+  return path.join(paths.teamDir(safeComponent(teamName)), "agent-sessions");
+}
+
+function privateAgentDirectory(teamName: string, agentName: string): string {
+  return path.join(privateSessionRoot(teamName), safeComponent(agentName));
+}
+
+function privateRunDirectory(teamName: string, agentName: string, lifecycleRunId: string): string {
+  return path.join(privateAgentDirectory(teamName, agentName), safeComponent(lifecycleRunId));
+}
+
+function pruneEmptyDirectory(directory: string): void {
+  try {
+    if (directoryStat(directory)) fs.rmdirSync(directory);
+  } catch {
+    // Siblings or unknown entries keep their parent directory in place.
+  }
+}
+
+export function preparePrivateAgentSessionDirectory(
+  teamName: string,
+  agentName: string,
+  lifecycleRunId: string,
+): string {
+  const teamDirectory = paths.teamDir(safeComponent(teamName));
+  if (!directoryStat(teamDirectory)) {
+    throw new Error(`Refusing private agent session storage without a trusted team directory: ${teamDirectory}`);
+  }
+  const root = privateSessionRoot(teamName);
+  const agentDirectory = privateAgentDirectory(teamName, agentName);
+  const runDirectory = privateRunDirectory(teamName, agentName, lifecycleRunId);
+  ensurePrivateDirectory(root);
+  ensurePrivateDirectory(agentDirectory);
+  ensurePrivateDirectory(runDirectory);
+  return runDirectory;
+}
+
+export function cleanupPrivateAgentSessionDirectory(
+  teamName: string,
+  agentName: string,
+  lifecycleRunId: string,
+): boolean {
+  const root = privateSessionRoot(teamName);
+  const agentDirectory = privateAgentDirectory(teamName, agentName);
+  const runDirectory = privateRunDirectory(teamName, agentName, lifecycleRunId);
+  const runInspection = inspectDirectory(runDirectory);
+  if (runInspection.kind === "missing") return false;
+  const inspections = [
+    { directory: root, inspection: inspectDirectory(root) },
+    { directory: agentDirectory, inspection: inspectDirectory(agentDirectory) },
+    { directory: runDirectory, inspection: runInspection },
+  ];
+  const failedInspection = inspections.find(({ inspection }) => inspection.kind !== "directory");
+  if (failedInspection) {
+    if (failedInspection.inspection.kind === "error") {
+      throw new Error(`Could not inspect private agent session directory: ${failedInspection.directory}`);
+    }
+    throw new Error(`Refusing to remove an untrusted private agent session directory: ${failedInspection.directory}`);
+  }
+  fs.rmSync(runDirectory, { recursive: true, force: false });
+  pruneEmptyDirectory(agentDirectory);
+  pruneEmptyDirectory(root);
+  return true;
+}
+
+function readActiveRuns(teamDirectory: string): Set<string> | null {
+  try {
+    const configPath = path.join(teamDirectory, "config.json");
+    const stat = fs.lstatSync(configPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return null;
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    if (!Array.isArray(config?.members)) return null;
+    const active = new Set<string>();
+    for (const member of config.members) {
+      // A report fence marks the member inactive before trailing session events
+      // and final teardown settle. Roster presence, not isActive, owns retention.
+      if (member?.agentType !== "teammate") continue;
+      if (typeof member.name !== "string" || typeof member.lifecycleRunId !== "string") return null;
+      active.add(`${safeComponent(member.name)}\0${safeComponent(member.lifecycleRunId)}`);
+    }
+    return active;
+  } catch {
+    return null;
+  }
+}
+
+function safeDirectoryEntries(directory: string): fs.Dirent[] {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function latestPrivateRunActivityMs(runDirectory: string, runStat: fs.Stats): number | null {
+  const entries = inspectDirectoryEntries(runDirectory);
+  if (entries.kind === "error") return null;
+
+  let latest = runStat.mtimeMs;
+  for (const entry of entries.entries) {
+    const entryPath = path.join(runDirectory, entry.name);
+    try {
+      const stat = fs.lstatSync(entryPath);
+      if (stat.isSymbolicLink()) continue;
+      latest = Math.max(latest, stat.mtimeMs);
+    } catch {
+      return null;
+    }
+  }
+  return latest;
+}
+
+export function hasRecentPrivateAgentSessions(
+  teamDirectory: string,
+  options: PrivateAgentSessionRetentionOptions = {},
+): PrivateAgentSessionRetentionResult {
+  const now = options.now ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? PRIVATE_AGENT_SESSION_RETENTION_MS;
+  if (maxAgeMs <= 0) return "none";
+
+  const teamInspection = inspectDirectory(teamDirectory);
+  if (teamInspection.kind === "missing" || teamInspection.kind === "unsafe") return "none";
+  if (teamInspection.kind === "error") return "unknown";
+
+  const sessionRoot = path.join(teamDirectory, "agent-sessions");
+  const rootInspection = inspectDirectory(sessionRoot);
+  if (rootInspection.kind === "missing" || rootInspection.kind === "unsafe") return "none";
+  if (rootInspection.kind === "error") return "unknown";
+
+  const agentEntries = inspectDirectoryEntries(sessionRoot);
+  if (agentEntries.kind === "error") return "unknown";
+  for (const agentEntry of agentEntries.entries) {
+    if (!agentEntry.isDirectory()) continue;
+    try {
+      safeComponent(agentEntry.name);
+    } catch {
+      continue;
+    }
+    const agentDirectory = path.join(sessionRoot, agentEntry.name);
+    const agentInspection = inspectDirectory(agentDirectory);
+    if (agentInspection.kind === "error" || agentInspection.kind === "missing") return "unknown";
+    if (agentInspection.kind === "unsafe") continue;
+
+    const runEntries = inspectDirectoryEntries(agentDirectory);
+    if (runEntries.kind === "error") return "unknown";
+    for (const runEntry of runEntries.entries) {
+      if (!runEntry.isDirectory()) continue;
+      try {
+        safeComponent(runEntry.name);
+      } catch {
+        continue;
+      }
+      const runDirectory = path.join(agentDirectory, runEntry.name);
+      const runInspection = inspectDirectory(runDirectory);
+      if (runInspection.kind === "error" || runInspection.kind === "missing") return "unknown";
+      if (runInspection.kind === "unsafe") continue;
+
+      const latestActivity = latestPrivateRunActivityMs(runDirectory, runInspection.stat);
+      if (latestActivity === null) return "unknown";
+      if (now - latestActivity <= maxAgeMs) return "recent";
+    }
+  }
+
+  return "none";
+}
+
+export function cleanupStalePrivateAgentSessions(
+  options: CleanupStalePrivateAgentSessionsOptions = {},
+): number {
+  const teamsRoot = options.teamsRoot ?? path.dirname(paths.teamDir("__probe__"));
+  const now = options.now ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? PRIVATE_AGENT_SESSION_RETENTION_MS;
+  if (!directoryStat(teamsRoot)) return 0;
+  let cleaned = 0;
+
+  for (const teamEntry of safeDirectoryEntries(teamsRoot)) {
+    if (!teamEntry.isDirectory()) continue;
+    let teamName: string;
+    try {
+      teamName = safeComponent(teamEntry.name);
+    } catch {
+      continue;
+    }
+    const teamDirectory = path.join(teamsRoot, teamName);
+    if (!directoryStat(teamDirectory)) continue;
+    const activeRuns = readActiveRuns(teamDirectory);
+    if (!activeRuns) continue;
+    const sessionRoot = path.join(teamDirectory, "agent-sessions");
+    if (!directoryStat(sessionRoot)) continue;
+
+    for (const agentEntry of safeDirectoryEntries(sessionRoot)) {
+      if (!agentEntry.isDirectory()) continue;
+      let agentName: string;
+      try {
+        agentName = safeComponent(agentEntry.name);
+      } catch {
+        continue;
+      }
+      const agentDirectory = path.join(sessionRoot, agentName);
+      if (!directoryStat(agentDirectory)) continue;
+
+      for (const runEntry of safeDirectoryEntries(agentDirectory)) {
+        if (!runEntry.isDirectory()) continue;
+        let runId: string;
+        try {
+          runId = safeComponent(runEntry.name);
+        } catch {
+          continue;
+        }
+        if (activeRuns.has(`${agentName}\0${runId}`)) continue;
+        const runDirectory = path.join(agentDirectory, runId);
+        const stat = directoryStat(runDirectory);
+        if (!stat) continue;
+        const latestActivity = latestPrivateRunActivityMs(runDirectory, stat);
+        if (latestActivity === null || now - latestActivity <= maxAgeMs) continue;
+        try {
+          fs.rmSync(runDirectory, { recursive: true, force: false });
+          cleaned += 1;
+        } catch {
+          // One failed removal must not prevent later eligible runs from being cleaned.
+        }
+      }
+      pruneEmptyDirectory(agentDirectory);
+    }
+    pruneEmptyDirectory(sessionRoot);
+  }
+
+  return cleaned;
+}

package/extensions/internal/debug.ts

@@ -0,0 +1,44 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as paths from "../../src/utils/paths";
+import type { PiExtendedTeamsSettings } from "../../src/utils/settings";
+
+const DISABLED_VALUES = new Set(["", "0", "false", "no", "off"]);
+
+export function isTeamsDebugEnabled(settings?: Pick<PiExtendedTeamsSettings, "debug">): boolean {
+  const envValue = process.env.PI_EXTENDED_TEAMS_DEBUG ?? process.env.PI_TEAMS_DEBUG;
+  if (envValue !== undefined) {
+    return !DISABLED_VALUES.has(envValue.trim().toLowerCase());
+  }
+
+  return settings?.debug.enabled ?? false;
+}
+
+export function teamDebugLogPath(teamName: string): string {
+  return path.join(paths.teamDir(teamName), "debug.log");
+}
+
+export async function writeTeamsDebugEvent(
+  teamName: string,
+  event: string,
+  details: Record<string, unknown>,
+  settings?: Pick<PiExtendedTeamsSettings, "debug">
+): Promise<string | null> {
+  if (!isTeamsDebugEnabled(settings)) return null;
+
+  const logPath = teamDebugLogPath(teamName);
+  const entry = {
+    timestamp: new Date().toISOString(),
+    pid: process.pid,
+    event,
+    ...details,
+  };
+
+  try {
+    await fs.mkdir(path.dirname(logPath), { recursive: true });
+    await fs.appendFile(logPath, `${JSON.stringify(entry)}\n`, "utf-8");
+    return logPath;
+  } catch {
+    return null;
+  }
+}

package/extensions/internal/model-selection.ts

@@ -0,0 +1,82 @@
+import {
+  isKnownQualifiedModel,
+  listPreferredQualifiedModels,
+  loadModelResolutionConfig,
+  loadPiModelSettings,
+  normalizeQualifiedModel,
+  sortAvailableModels,
+  type AvailableModel,
+} from "../../src/utils/model-resolution";
+import type { ThinkingCapableModel } from "../../src/utils/thinking-levels";
+
+export interface AvailableRegisteredModel extends AvailableModel, ThinkingCapableModel {}
+
+export async function getAvailableModels(ctx: any): Promise<AvailableRegisteredModel[]> {
+  try {
+    const available = await ctx.modelRegistry.getAvailable();
+    return available.map((model: any) => ({
+      provider: model.provider,
+      model: model.id,
+      reasoning: model.reasoning,
+      thinkingLevelMap: model.thinkingLevelMap,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+export async function getModelSelectionState(ctx: any, projectDir: string, preferredModels: string[] = []) {
+  const availableModels = await getAvailableModels(ctx);
+  const piSettings = loadPiModelSettings({ projectDir });
+  const config = loadModelResolutionConfig({ projectDir });
+  const preferredQualifiedModels = listPreferredQualifiedModels(availableModels, {
+    projectDir,
+    preferredModels,
+  });
+  const sortedModels = sortAvailableModels(availableModels, {
+    preferredModels: preferredQualifiedModels,
+    providerPriority: config.providerPriority,
+  });
+
+  return {
+    availableModels,
+    piSettings,
+    providerPriority: config.providerPriority,
+    preferredQualifiedModels,
+    sortedModels,
+  };
+}
+
+export function getCurrentQualifiedModel(ctx: any): string | undefined {
+  if (!ctx.model?.provider || !ctx.model?.id) {
+    return undefined;
+  }
+  return `${ctx.model.provider}/${ctx.model.id}`;
+}
+
+export function requireQualifiedKnownModel(
+  model: string | undefined,
+  availableModels: Array<{ provider: string; model: string }>,
+  fieldName: string
+): string | undefined {
+  if (!model) {
+    return undefined;
+  }
+
+  const normalized = normalizeQualifiedModel(model);
+  if (!normalized) {
+    throw new Error(
+      `${fieldName} must be a fully qualified provider/model string. ` +
+      `Use list_available_models to choose a valid model.`
+    );
+  }
+
+  if (!isKnownQualifiedModel(normalized, availableModels)) {
+    throw new Error(
+      `${fieldName} \"${normalized}\" is not available. ` +
+      `Use list_available_models to choose a valid model.`
+    );
+  }
+
+  return normalized;
+}