pi-extended-teams 2.1.16

package/src/utils/model-resolution.ts

@@ -0,0 +1,322 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { THINKING_LEVEL_NAMES } from "./thinking-levels";
+
+export interface AvailableModel {
+  provider: string;
+  model: string;
+}
+
+export interface ModelResolutionConfig {
+  providerPriority?: string[];
+}
+
+export interface ResolvedModelResolutionConfig {
+  providerPriority: string[];
+}
+
+export interface PiModelSettings {
+  defaultProvider?: string;
+  defaultModel?: string;
+  enabledModels?: string[];
+}
+
+export interface SortedModel extends AvailableModel {
+  qualified: string;
+  preferred: boolean;
+  preferredIndex: number;
+  providerPriorityIndex: number;
+}
+
+const THINKING_LEVELS = new Set<string>(THINKING_LEVEL_NAMES);
+
+function normalizeList(values: unknown): string[] | undefined {
+  if (!Array.isArray(values)) return undefined;
+
+  const normalized = values
+    .map((value) => String(value).trim())
+    .filter(Boolean);
+
+  return normalized.length > 0 ? Array.from(new Set(normalized)) : [];
+}
+
+function readJsonFile<T>(filePath: string): T | null {
+  if (!fs.existsSync(filePath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function readConfigFile(configPath: string): ModelResolutionConfig {
+  const parsed = readJsonFile<ModelResolutionConfig>(configPath);
+  if (!parsed) {
+    return {};
+  }
+
+  return {
+    providerPriority: normalizeList(parsed.providerPriority)?.map((value) => value.toLowerCase()),
+  };
+}
+
+/**
+ * Loads pi-extended-teams model-selection preferences.
+ *
+ * Supported locations:
+ * - ~/.pi/pi-extended-teams.json
+ * - <project>/.pi/pi-extended-teams.json
+ *
+ * Legacy ~/.pi/pi-teams.json and <project>/.pi/pi-teams.json files are still
+ * read for compatibility, but the pi-extended-teams paths win when present.
+ * Project-local config overrides global config.
+ */
+export function loadModelResolutionConfig(options?: {
+  projectDir?: string;
+  homeDir?: string;
+}): ResolvedModelResolutionConfig {
+  const homeDir = options?.homeDir ?? os.homedir();
+  const projectDir = options?.projectDir;
+
+  const legacyGlobalConfigPath = path.join(homeDir, ".pi", "pi-teams.json");
+  const globalConfigPath = path.join(homeDir, ".pi", "pi-extended-teams.json");
+  const legacyProjectConfigPath = projectDir ? path.join(projectDir, ".pi", "pi-teams.json") : null;
+  const projectConfigPath = projectDir ? path.join(projectDir, ".pi", "pi-extended-teams.json") : null;
+
+  const merged: ResolvedModelResolutionConfig = {
+    providerPriority: [],
+  };
+
+  for (const configPath of [legacyGlobalConfigPath, globalConfigPath, legacyProjectConfigPath, projectConfigPath]) {
+    if (!configPath) continue;
+
+    const config = readConfigFile(configPath);
+    if (config.providerPriority) {
+      merged.providerPriority = config.providerPriority;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Loads pi settings relevant to model selection.
+ *
+ * Supported locations:
+ * - ~/.pi/agent/settings.json
+ * - <project>/.pi/settings.json
+ *
+ * Project-local settings override global settings.
+ */
+export function loadPiModelSettings(options?: {
+  projectDir?: string;
+  homeDir?: string;
+}): PiModelSettings {
+  const homeDir = options?.homeDir ?? os.homedir();
+  const projectDir = options?.projectDir;
+
+  const globalSettingsPath = path.join(homeDir, ".pi", "agent", "settings.json");
+  const projectSettingsPath = projectDir ? path.join(projectDir, ".pi", "settings.json") : null;
+
+  const merged: PiModelSettings = {};
+
+  for (const settingsPath of [globalSettingsPath, projectSettingsPath]) {
+    if (!settingsPath) continue;
+
+    const settings = readJsonFile<PiModelSettings>(settingsPath);
+    if (!settings) continue;
+
+    if (typeof settings.defaultProvider === "string" && settings.defaultProvider.trim()) {
+      merged.defaultProvider = settings.defaultProvider.trim();
+    }
+    if (typeof settings.defaultModel === "string" && settings.defaultModel.trim()) {
+      merged.defaultModel = settings.defaultModel.trim();
+    }
+    if (Array.isArray(settings.enabledModels)) {
+      merged.enabledModels = settings.enabledModels
+        .map((value) => String(value).trim())
+        .filter(Boolean);
+    }
+  }
+
+  return merged;
+}
+
+export function stripThinkingSuffix(specifier: string): string {
+  const trimmed = specifier.trim();
+  const lastColon = trimmed.lastIndexOf(":");
+  if (lastColon === -1) {
+    return trimmed;
+  }
+
+  const suffix = trimmed.slice(lastColon + 1).toLowerCase();
+  return THINKING_LEVELS.has(suffix) ? trimmed.slice(0, lastColon) : trimmed;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function matchesPattern(pattern: string, value: string): boolean {
+  const normalizedPattern = pattern.toLowerCase();
+  const normalizedValue = value.toLowerCase();
+
+  if (normalizedPattern.includes("*")) {
+    const regex = new RegExp(`^${normalizedPattern.split("*").map(escapeRegex).join(".*")}$`, "i");
+    return regex.test(value);
+  }
+
+  return normalizedValue === normalizedPattern || normalizedValue.includes(normalizedPattern);
+}
+
+export function parseQualifiedModel(specifier: string): AvailableModel | null {
+  const cleaned = stripThinkingSuffix(specifier);
+  const slashIndex = cleaned.indexOf("/");
+  if (slashIndex === -1) {
+    return null;
+  }
+
+  const provider = cleaned.slice(0, slashIndex).trim();
+  const model = cleaned.slice(slashIndex + 1).trim();
+  if (!provider || !model) {
+    return null;
+  }
+
+  return { provider, model };
+}
+
+export function isQualifiedModel(specifier: string): boolean {
+  return parseQualifiedModel(specifier) !== null;
+}
+
+export function normalizeQualifiedModel(specifier: string): string | null {
+  const parsed = parseQualifiedModel(specifier);
+  return parsed ? `${parsed.provider}/${parsed.model}` : null;
+}
+
+function qualifyDefaultModel(settings: PiModelSettings): string | null {
+  if (!settings.defaultModel) {
+    return null;
+  }
+
+  if (isQualifiedModel(settings.defaultModel)) {
+    return normalizeQualifiedModel(settings.defaultModel);
+  }
+
+  if (settings.defaultProvider) {
+    return `${settings.defaultProvider}/${stripThinkingSuffix(settings.defaultModel)}`;
+  }
+
+  return null;
+}
+
+/**
+ * Builds a list of preferred fully-qualified models from pi settings.
+ *
+ * Order is significant:
+ * 1. preferredModels passed by the caller (must already be fully qualified)
+ * 2. pi default model (qualified via defaultProvider when necessary)
+ * 3. available models matching enabledModels patterns, in settings order
+ */
+export function buildPreferredModelsFromSettings(
+  availableModels: AvailableModel[],
+  settings: PiModelSettings,
+  preferredModels: string[] = []
+): string[] {
+  const results: string[] = [];
+  const seen = new Set<string>();
+
+  const push = (specifier?: string | null) => {
+    if (!specifier) return;
+    const normalized = normalizeQualifiedModel(specifier);
+    if (!normalized || seen.has(normalized)) return;
+    seen.add(normalized);
+    results.push(normalized);
+  };
+
+  for (const model of preferredModels) {
+    push(model);
+  }
+
+  push(qualifyDefaultModel(settings));
+
+  for (const pattern of settings.enabledModels ?? []) {
+    const cleanedPattern = stripThinkingSuffix(pattern);
+    for (const availableModel of availableModels) {
+      const qualified = `${availableModel.provider}/${availableModel.model}`;
+      const target = cleanedPattern.includes("/") ? qualified : availableModel.model;
+      if (matchesPattern(cleanedPattern, target)) {
+        push(qualified);
+      }
+    }
+  }
+
+  return results;
+}
+
+export function listPreferredQualifiedModels(
+  availableModels: AvailableModel[],
+  options?: {
+    projectDir?: string;
+    homeDir?: string;
+    preferredModels?: string[];
+  }
+): string[] {
+  const settings = loadPiModelSettings(options);
+  return buildPreferredModelsFromSettings(availableModels, settings, options?.preferredModels ?? []);
+}
+
+export function sortAvailableModels(
+  availableModels: AvailableModel[],
+  options?: {
+    preferredModels?: string[];
+    providerPriority?: string[];
+  }
+): SortedModel[] {
+  const preferredModels = options?.preferredModels ?? [];
+  const providerPriority = (options?.providerPriority ?? []).map((value) => value.toLowerCase());
+
+  const preferredIndex = new Map(preferredModels.map((value, index) => [value, index]));
+  const providerPriorityIndex = new Map(providerPriority.map((value, index) => [value, index]));
+
+  return availableModels
+    .map((model) => {
+      const qualified = `${model.provider}/${model.model}`;
+      return {
+        ...model,
+        qualified,
+        preferred: preferredIndex.has(qualified),
+        preferredIndex: preferredIndex.get(qualified) ?? Number.MAX_SAFE_INTEGER,
+        providerPriorityIndex: providerPriorityIndex.get(model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER,
+      };
+    })
+    .sort((a, b) => {
+      if (a.preferred !== b.preferred) {
+        return a.preferred ? -1 : 1;
+      }
+      if (a.preferredIndex !== b.preferredIndex) {
+        return a.preferredIndex - b.preferredIndex;
+      }
+      if (a.providerPriorityIndex !== b.providerPriorityIndex) {
+        return a.providerPriorityIndex - b.providerPriorityIndex;
+      }
+      const providerCompare = a.provider.localeCompare(b.provider);
+      if (providerCompare !== 0) {
+        return providerCompare;
+      }
+      return a.model.localeCompare(b.model);
+    });
+}
+
+export function isKnownQualifiedModel(model: string, availableModels: AvailableModel[]): boolean {
+  const normalized = normalizeQualifiedModel(model);
+  if (!normalized) {
+    return false;
+  }
+
+  return availableModels.some(
+    (availableModel) => `${availableModel.provider}/${availableModel.model}` === normalized
+  );
+}

package/src/utils/models.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { THINKING_LEVELS } from "./models";
+
+describe("thinking levels", () => {
+  it("includes xhigh for teammate configuration", () => {
+    expect(THINKING_LEVELS).toContain("xhigh");
+  });
+});

package/src/utils/models.ts

@@ -0,0 +1,115 @@
+import { THINKING_LEVEL_NAMES, type ThinkingLevelName } from "./thinking-levels";
+
+export const THINKING_LEVELS = THINKING_LEVEL_NAMES;
+export type ThinkingLevel = ThinkingLevelName;
+
+export interface Member {
+  agentId: string;
+  name: string;
+  agentType: string;
+  model?: string;
+  joinedAt: number;
+  tmuxPaneId: string;
+  windowId?: string;
+  cwd: string;
+  subscriptions: any[];
+  prompt?: string;
+  color?: string;
+  thinking?: ThinkingLevel;
+  planModeRequired?: boolean;
+  backendType?: string;
+  isActive?: boolean;
+  /** Optional programmatic orchestration/idempotency metadata. */
+  metadata?: Record<string, any>;
+  /** Authoritative identity for one admitted lifecycle run. Never stored in user metadata. */
+  lifecycleRunId?: string;
+  /** Runtime-owned delegation depth. Public lead spawns are depth 0; restricted children are depth 1. */
+  delegationDepth?: number;
+  /** Lead-approved opt-in for restricted nested read delegation. */
+  allowNestedReadAgents?: boolean;
+  /** Lead-approved lazy access to a filtered active-branch session snapshot. */
+  sessionContext?: "lazy";
+  /** Runtime-owned parent identity for a restricted nested read child. */
+  parentAgentName?: string;
+  /** Runtime-owned parent lifecycle identity for a restricted nested read child. */
+  parentLifecycleRunId?: string;
+  /** "read" agents run in-process (no pane); "write" agents spawn in tmux. */
+  role?: "read" | "write";
+  /** Optional category preset name from settings.json. */
+  category?: string;
+  /** Optional favorite model slot selected at spawn time. */
+  modelSlot?: string;
+  /** Agent that requested this read helper; final reports are delivered there. */
+  requestedBy?: string;
+  /** Marks extension-managed helper agents with special delivery/cleanup semantics. */
+  helperKind?: "read_helper";
+}
+
+export interface TeamConfig {
+  name: string;
+  description: string;
+  createdAt: number;
+  leadAgentId: string;
+  leadSessionId: string;
+  members: Member[];
+  defaultModel?: string;
+  separateWindows?: boolean;
+  /** Optional programmatic orchestration/idempotency metadata. */
+  metadata?: Record<string, any>;
+}
+
+export interface TaskFile {
+  id: string;
+  subject: string;
+  description: string;
+  activeForm?: string;
+  status: "pending" | "planning" | "in_progress" | "completed" | "deleted";
+  plan?: string;
+  planFeedback?: string;
+  blocks: string[];
+  blockedBy: string[];
+  owner?: string;
+  /** Monotonic task version for guarded programmatic updates. */
+  version?: number;
+  createdAt?: string;
+  updatedAt?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface InboxMessage {
+  id?: string;
+  from: string;
+  text: string;
+  timestamp: string;
+  read: boolean;
+  summary?: string;
+  color?: string;
+  operationId?: string;
+  workflowRunId?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface TeamReportEvent {
+  id: string;
+  teamName: string;
+  agentName: string;
+  role?: string;
+  status: "completed" | "failed";
+  report: string;
+  summary?: string;
+  reportPath?: string;
+  createdAt: number;
+  startedAt?: number;
+  elapsedMs?: number;
+  tokensUsed?: number;
+  costUsd?: number;
+  model?: string;
+  thinking?: string;
+  modelSlot?: string;
+  color?: string;
+  requestedBy?: string;
+  source: "read-agent" | "write-agent" | "lead-inbox" | "tool" | "workflow";
+  operationId?: string;
+  workflowRunId?: string;
+  metadata?: Record<string, any>;
+}

package/src/utils/paths.ts

@@ -0,0 +1,81 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+export const PI_DIR = path.join(os.homedir(), ".pi");
+export const TEAMS_DIR = path.join(PI_DIR, "teams");
+export const TASKS_DIR = path.join(PI_DIR, "tasks");
+
+export function ensureDirs() {
+  if (!fs.existsSync(PI_DIR)) fs.mkdirSync(PI_DIR);
+  if (!fs.existsSync(TEAMS_DIR)) fs.mkdirSync(TEAMS_DIR);
+  if (!fs.existsSync(TASKS_DIR)) fs.mkdirSync(TASKS_DIR);
+}
+
+export function sanitizeName(name: string): string {
+  // Allow only alphanumeric characters, hyphens, and underscores.
+  if (/[^a-zA-Z0-9_-]/.test(name)) {
+    throw new Error(`Invalid name: "${name}". Only alphanumeric characters, hyphens, and underscores are allowed.`);
+  }
+  return name;
+}
+
+export function teamDir(teamName: string) {
+  return path.join(TEAMS_DIR, sanitizeName(teamName));
+}
+
+export function taskDir(teamName: string) {
+  return path.join(TASKS_DIR, sanitizeName(teamName));
+}
+
+export function inboxPath(teamName: string, agentName: string) {
+  return path.join(teamDir(teamName), "inboxes", `${sanitizeName(agentName)}.json`);
+}
+
+export function runtimeStatusPath(teamName: string, agentName: string) {
+  return path.join(teamDir(teamName), "runtime", `${sanitizeName(agentName)}.json`);
+}
+
+export function sessionContextReferencePath(teamName: string, agentName: string, lifecycleRunId: string) {
+  return path.join(
+    teamDir(teamName),
+    "session-context",
+    `${sanitizeName(agentName)}--${sanitizeName(lifecycleRunId)}.md`,
+  );
+}
+
+export function lifecycleTombstonePath(teamName: string, agentName: string) {
+  return path.join(teamDir(teamName), "lifecycle", "quarantine", `${sanitizeName(agentName)}.json`);
+}
+
+export function configPath(teamName: string) {
+  return path.join(teamDir(teamName), "config.json");
+}
+
+export function claimsPath(teamName: string) {
+  return path.join(teamDir(teamName), "claims.json");
+}
+
+export function writeQueuePath(teamName: string) {
+  return path.join(teamDir(teamName), "write-queue.json");
+}
+
+export function readHelperQueuePath(teamName: string) {
+  return path.join(teamDir(teamName), "read-helper-queue.json");
+}
+
+export function sharedMemoryPath(teamName: string) {
+  return path.join(teamDir(teamName), "shared-memory.json");
+}
+
+export function reportEventsPath(teamName: string) {
+  return path.join(teamDir(teamName), "reports.json");
+}
+
+export function reportFilesDir() {
+  return path.join(PI_DIR, "agent", "reports");
+}
+
+export function leadSessionPath(teamName: string) {
+  return path.join(teamDir(teamName), "lead-session.json");
+}

package/src/utils/predefined-teams/types.ts

@@ -0,0 +1,48 @@
+import type { ThinkingLevel } from "../models";
+
+/**
+ * Represents an agent definition from a .md file
+ */
+export interface AgentDefinition {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  thinking?: ThinkingLevel;
+  prompt: string;
+  filePath: string;
+}
+
+/**
+ * Represents a predefined team from teams.yaml
+ */
+export interface PredefinedTeam {
+  name: string;
+  agents: string[];
+  description?: string;
+}
+
+/**
+ * Options for saving a team as a template
+ */
+export interface SaveTeamTemplateOptions {
+  templateName: string;
+  description?: string;
+  scope: "user" | "project";
+  projectDir?: string;
+}
+
+/**
+ * Result of saving a team as a template
+ */
+export interface SaveTeamTemplateResult {
+  templateName: string;
+  agentsDir: string;
+  teamsYamlPath: string;
+  savedAgents: Array<{
+    name: string;
+    path: string;
+    existed: boolean;
+  }>;
+  templateExisted: boolean;
+}

package/src/utils/predefined-teams.save-template.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { saveTeamTemplate } from "./predefined-teams";
+
+describe("saveTeamTemplate", () => {
+  const rootPiDir = path.join(os.homedir(), ".pi");
+  const globalAgentsDir = path.join(rootPiDir, "agent", "agents");
+  const globalTeamsPath = path.join(rootPiDir, "teams.yaml");
+  const projectDir = path.join(os.tmpdir(), "pi-extended-teams-test-save-" + Date.now());
+
+  let originalGlobalTeams: string | null = null;
+  let originalAgentFiles = new Set<string>();
+
+  beforeEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+
+    if (fs.existsSync(globalTeamsPath)) {
+      originalGlobalTeams = fs.readFileSync(globalTeamsPath, "utf-8");
+    }
+    if (fs.existsSync(globalAgentsDir)) {
+      originalAgentFiles = new Set(fs.readdirSync(globalAgentsDir));
+    }
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(projectDir)) {
+      fs.rmSync(projectDir, { recursive: true });
+    }
+
+    if (originalGlobalTeams === null) {
+      if (fs.existsSync(globalTeamsPath)) fs.rmSync(globalTeamsPath);
+    } else {
+      fs.mkdirSync(path.dirname(globalTeamsPath), { recursive: true });
+      fs.writeFileSync(globalTeamsPath, originalGlobalTeams);
+    }
+
+    if (fs.existsSync(globalAgentsDir)) {
+      for (const file of fs.readdirSync(globalAgentsDir)) {
+        if (!originalAgentFiles.has(file)) {
+          fs.rmSync(path.join(globalAgentsDir, file));
+        }
+      }
+    }
+  });
+
+  it("writes user-scoped teams to ~/.pi/teams.yaml and agents to ~/.pi/agent/agents", () => {
+    const result = saveTeamTemplate(
+      {
+        name: "audit-team",
+        members: [
+          {
+            name: "security-worker",
+            agentType: "teammate",
+            prompt: "Audit security issues",
+          },
+        ],
+      },
+      {
+        templateName: "audit-team",
+        scope: "user",
+      }
+    );
+
+    expect(result.teamsYamlPath).toBe(globalTeamsPath);
+    expect(result.agentsDir).toBe(globalAgentsDir);
+    expect(fs.existsSync(globalTeamsPath)).toBe(true);
+    expect(fs.readFileSync(globalTeamsPath, "utf-8")).toContain("audit-team:");
+    expect(fs.existsSync(path.join(globalAgentsDir, "security-worker.md"))).toBe(true);
+  });
+});