pi-crew 0.1.51 → 0.2.0

package/src/adapters/types.ts

@@ -0,0 +1,23 @@
+export interface ExportContent {
+	id: string;
+	name: string;
+	description: string;
+	category: string;
+	tags: string[];
+	body: string;
+	source: { type: "agent" | "team" | "workflow" | "skill"; name: string };
+}
+
+export interface ExportAdapter {
+	readonly toolId: string;
+	readonly toolName: string;
+	readonly fileExtension: string;
+	getFilePath(content: ExportContent): string;
+	formatFile(content: ExportContent): string;
+}
+
+export interface AdapterRegistry {
+	get(toolId: string): ExportAdapter | undefined;
+	getAll(): ExportAdapter[];
+	register(adapter: ExportAdapter): void;
+}

package/src/agents/agent-config.ts

@@ -31,6 +31,8 @@ export interface AgentConfig {
 	defaultTools?: string[] | null;
 	/** Context mode: "fresh" = clean start, "fork" = inherit parent session context */
 	contextMode?: "fresh" | "fork";
+	/** Maximum turns for this agent. Overrides runtime config if set. */
+	maxTurns?: number;
 	disabled?: boolean;
 	override?: { source: "config"; path: string };
 }

package/src/agents/agent-search.ts

@@ -1,98 +1,98 @@
-import type { AgentConfig } from "./agent-config.ts";
-
-// ─── BM25 Agent Search ──────────────────────────────────────────────────────
-// Lightweight BM25 search over agent descriptors for task-to-agent matching.
-// Based on the same BM25 algorithm used in oh-my-pi's tool-index.ts.
-
-export interface AgentSearchDocument {
-	agent: AgentConfig;
-	termFrequencies: Map<string, number>;
-	length: number;
-}
-
-export interface AgentSearchIndex {
-	documents: AgentSearchDocument[];
-	averageLength: number;
-	documentFrequencies: Map<string, number>;
-}
-
-export interface AgentSearchResult {
-	agent: AgentConfig;
-	score: number;
-}
-
-const BM25_K1 = 1.2;
-const BM25_B = 0.75;
-const FIELD_WEIGHTS = {
-	name: 6,
-	description: 2,
-	role: 3,
-} as const;
-
-function tokenize(value: string): string[] {
-	return value
-		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-		.replace(/[^a-zA-Z0-9]+/g, " ")
-		.toLowerCase()
-		.trim()
-		.split(/\s+/)
-		.filter((token) => token.length > 0);
-}
-
-function addWeightedTokens(termFrequencies: Map<string, number>, value: string | undefined, weight: number): void {
-	if (!value) return;
-	for (const token of tokenize(value)) {
-		termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
-	}
-}
-
-function buildAgentSearchDocument(agent: AgentConfig): AgentSearchDocument {
-	const termFrequencies = new Map<string, number>();
-	addWeightedTokens(termFrequencies, agent.name, FIELD_WEIGHTS.name);
-	addWeightedTokens(termFrequencies, agent.description, FIELD_WEIGHTS.description);
-	// Role from agent name heuristic
-	const roleHint = agent.name?.replace(/[-_]/g, " ") ?? "";
-	addWeightedTokens(termFrequencies, roleHint, FIELD_WEIGHTS.role);
-	const length = Array.from(termFrequencies.values()).reduce((sum, value) => sum + value, 0);
-	return { agent, termFrequencies, length };
-}
-
-export function buildAgentSearchIndex(agents: Iterable<AgentConfig>): AgentSearchIndex {
-	const documents = Array.from(agents, buildAgentSearchDocument);
-	const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
-	const documentFrequencies = new Map<string, number>();
-	for (const document of documents) {
-		for (const token of new Set(document.termFrequencies.keys())) {
-			documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
-		}
-	}
-	return { documents, averageLength, documentFrequencies };
-}
-
-export function searchAgents(index: AgentSearchIndex, query: string, limit: number): AgentSearchResult[] {
-	const queryTokens = tokenize(query);
-	if (queryTokens.length === 0) return [];
-	if (index.documents.length === 0) return [];
-
-	const queryTermCounts = new Map<string, number>();
-	for (const token of queryTokens) {
-		queryTermCounts.set(token, (queryTermCounts.get(token) ?? 0) + 1);
-	}
-
-	return index.documents
-		.map((document) => {
-			let score = 0;
-			for (const [token, queryTermCount] of queryTermCounts) {
-				const termFrequency = document.termFrequencies.get(token) ?? 0;
-				if (termFrequency === 0) continue;
-				const documentFrequency = index.documentFrequencies.get(token) ?? 0;
-				const idf = Math.log(1 + (index.documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
-				const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (document.length / index.averageLength));
-				score += queryTermCount * idf * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
-			}
-			return { agent: document.agent, score };
-		})
-		.filter((result) => result.score > 0)
-		.sort((left, right) => right.score - left.score || left.agent.name.localeCompare(right.agent.name))
-		.slice(0, limit);
-}
+import type { AgentConfig } from "./agent-config.ts";
+
+// ─── BM25 Agent Search ──────────────────────────────────────────────────────
+// Lightweight BM25 search over agent descriptors for task-to-agent matching.
+// Based on the same BM25 algorithm used in oh-my-pi's tool-index.ts.
+
+export interface AgentSearchDocument {
+	agent: AgentConfig;
+	termFrequencies: Map<string, number>;
+	length: number;
+}
+
+export interface AgentSearchIndex {
+	documents: AgentSearchDocument[];
+	averageLength: number;
+	documentFrequencies: Map<string, number>;
+}
+
+export interface AgentSearchResult {
+	agent: AgentConfig;
+	score: number;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const FIELD_WEIGHTS = {
+	name: 6,
+	description: 2,
+	role: 3,
+} as const;
+
+function tokenize(value: string): string[] {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.toLowerCase()
+		.trim()
+		.split(/\s+/)
+		.filter((token) => token.length > 0);
+}
+
+function addWeightedTokens(termFrequencies: Map<string, number>, value: string | undefined, weight: number): void {
+	if (!value) return;
+	for (const token of tokenize(value)) {
+		termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
+	}
+}
+
+function buildAgentSearchDocument(agent: AgentConfig): AgentSearchDocument {
+	const termFrequencies = new Map<string, number>();
+	addWeightedTokens(termFrequencies, agent.name, FIELD_WEIGHTS.name);
+	addWeightedTokens(termFrequencies, agent.description, FIELD_WEIGHTS.description);
+	// Role from agent name heuristic
+	const roleHint = agent.name?.replace(/[-_]/g, " ") ?? "";
+	addWeightedTokens(termFrequencies, roleHint, FIELD_WEIGHTS.role);
+	const length = Array.from(termFrequencies.values()).reduce((sum, value) => sum + value, 0);
+	return { agent, termFrequencies, length };
+}
+
+export function buildAgentSearchIndex(agents: Iterable<AgentConfig>): AgentSearchIndex {
+	const documents = Array.from(agents, buildAgentSearchDocument);
+	const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+	const documentFrequencies = new Map<string, number>();
+	for (const document of documents) {
+		for (const token of new Set(document.termFrequencies.keys())) {
+			documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+		}
+	}
+	return { documents, averageLength, documentFrequencies };
+}
+
+export function searchAgents(index: AgentSearchIndex, query: string, limit: number): AgentSearchResult[] {
+	const queryTokens = tokenize(query);
+	if (queryTokens.length === 0) return [];
+	if (index.documents.length === 0) return [];
+
+	const queryTermCounts = new Map<string, number>();
+	for (const token of queryTokens) {
+		queryTermCounts.set(token, (queryTermCounts.get(token) ?? 0) + 1);
+	}
+
+	return index.documents
+		.map((document) => {
+			let score = 0;
+			for (const [token, queryTermCount] of queryTermCounts) {
+				const termFrequency = document.termFrequencies.get(token) ?? 0;
+				if (termFrequency === 0) continue;
+				const documentFrequency = index.documentFrequencies.get(token) ?? 0;
+				const idf = Math.log(1 + (index.documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
+				const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (document.length / index.averageLength));
+				score += queryTermCount * idf * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
+			}
+			return { agent: document.agent, score };
+		})
+		.filter((result) => result.score > 0)
+		.sort((left, right) => right.score - left.score || left.agent.name.localeCompare(right.agent.name))
+		.slice(0, limit);
+}

package/src/agents/discover-agents.ts

@@ -58,8 +58,9 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 		loadMode: parseLoadMode(frontmatter.loadMode),
 		defaultTools: frontmatter.defaultTools !== undefined ? parseCsv(frontmatter.defaultTools) ?? null : undefined,
 		contextMode: parseContextMode(frontmatter.contextMode),
+		maxTurns: (() => { const n = Number.parseInt(frontmatter.maxTurns, 10); return Number.isFinite(n) && n > 0 ? n : undefined; })(),
 		disabled: frontmatter.disabled === "true" || frontmatter.enabled === "false",
-			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
+		routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
 		};
 	} catch (error) {
 		logInternalError("discoverAgents.parseAgentFile", error, `filePath=${filePath}`);

package/src/config/config.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { PiTeamsAutonomyProfileSchema, PiTeamsConfigSchema } from "../schema/config-schema.ts";
+import { suggestConfigKey } from "./suggestions.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 
 export type PiTeamsAutonomyProfile = "manual" | "suggested" | "assisted" | "aggressive";
@@ -226,10 +227,21 @@ function errorPathFromValidation(error: unknown): string {
 	return "config";
 }
 
+/** Known top-level config keys from the schema — used for fuzzy suggestions. */
+const KNOWN_TOP_LEVEL_KEYS = Object.keys(PiTeamsConfigSchema.properties ?? {}) as string[];
+
 function validateConfigWithWarnings(raw: unknown): string[] {
 	if (!Value.Check(PiTeamsConfigSchema, raw)) {
 		return [...Value.Errors(PiTeamsConfigSchema, raw)].map((error) => {
-			return `${errorPathFromValidation(error)}: ${(error as { message?: unknown }).message ?? "invalid value"}`;
+			const path = errorPathFromValidation(error);
+			const message = (error as { message?: unknown }).message ?? "invalid value";
+			// Enhance "additionalProperties" errors with fuzzy suggestions
+			if ((error as { keyword?: unknown }).keyword === "additionalProperties") {
+				const offendingKey = path.split("/").pop() ?? path;
+				const suggestion = suggestConfigKey(offendingKey, KNOWN_TOP_LEVEL_KEYS);
+				if (suggestion) return `${path}: ${message} (did you mean '${suggestion}'?)`;
+			}
+			return `${path}: ${message}`;
 		});
 	}
 	return [];

package/src/config/drift-detector.ts

@@ -0,0 +1,211 @@
+import type { PiTeamsConfig } from "./config.ts";
+import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
+
+/**
+ * A single drift finding between discovered resources and config expectations.
+ */
+export interface DriftItem {
+	kind: "agent" | "team" | "workflow" | "config-key";
+	name: string;
+	status: "missing" | "extra" | "mismatched";
+	expected?: string;
+	actual?: string;
+	severity: "error" | "warning";
+}
+
+/**
+ * Summary counts by drift status.
+ */
+export interface DriftSummary {
+	missing: number;
+	extra: number;
+	mismatched: number;
+}
+
+/**
+ * Full drift report produced by `detectDrift`.
+ */
+export interface DriftReport {
+	hasDrift: boolean;
+	items: DriftItem[];
+	summary: DriftSummary;
+}
+
+/**
+ * Discovered resources passed into the drift detector.
+ */
+export interface DiscoveredResources {
+	agents: string[];
+	teams: string[];
+	workflows: string[];
+}
+
+/**
+ * Config references extracted from team roles and workflow steps.
+ * Used to compare against discovered resources.
+ */
+export interface ConfigReferences {
+	agents: Set<string>;
+	teams: Set<string>;
+	workflows: Set<string>;
+}
+
+/**
+ * Known top-level config keys allowed by the schema.
+ */
+const SCHEMA_KEYS: ReadonlySet<string> = new Set<string>(
+	Object.keys(PiTeamsConfigSchema.properties ?? {}),
+);
+
+/**
+ * Extract all agent, team, and workflow names referenced in a raw config object.
+ *
+ * Looks at:
+ * - `agents.overrides` keys → referenced agent names
+ * - Top-level keys that aren't in the schema are ignored (handled separately as config-key drift)
+ */
+function extractConfigReferences(config: Record<string, unknown>): ConfigReferences {
+	const agents = new Set<string>();
+	const teams = new Set<string>();
+	const workflows = new Set<string>();
+
+	// agents.overrides keys are explicit agent references
+	const agentsObj = typeof config.agents === "object" && config.agents !== null && !Array.isArray(config.agents)
+		? config.agents as Record<string, unknown>
+		: undefined;
+	if (agentsObj) {
+		const overrides = typeof agentsObj.overrides === "object" && agentsObj.overrides !== null && !Array.isArray(agentsObj.overrides)
+			? agentsObj.overrides as Record<string, unknown>
+			: undefined;
+		if (overrides) {
+			for (const name of Object.keys(overrides)) {
+				agents.add(name);
+			}
+		}
+	}
+
+	return { agents, teams, workflows };
+}
+
+/**
+ * Detect config drift between discovered resources and the configuration.
+ *
+ * Checks:
+ * 1. **Missing**: resource referenced in config (e.g. agents.overrides) but not discovered → error
+ * 2. **Extra**: discovered resource not referenced anywhere in config → warning
+ * 3. **Mismatched**: resource exists in both but with structural differences → warning
+ * 4. **Config keys**: config keys not present in the schema → warning
+ *
+ * For agents: compares against `agents.overrides` in config. Discovered agents not in overrides
+ * are NOT considered extra (they may be built-in). Only agents referenced in overrides but not
+ * discovered are considered missing.
+ *
+ * For teams/workflows: the config currently doesn't have explicit team/workflow references,
+ * so missing/extra checks rely solely on what resources reference each other.
+ */
+export function detectDrift(
+	discovered: DiscoveredResources,
+	config: PiTeamsConfig,
+): DriftReport {
+	const items: DriftItem[] = [];
+
+	const configRaw = config as Record<string, unknown>;
+	const refs = extractConfigReferences(configRaw);
+
+	// --- Agent drift ---
+	const discoveredAgentSet = new Set<string>(discovered.agents);
+
+	// Missing: referenced in agents.overrides but not discovered
+	for (const agentName of refs.agents) {
+		if (!discoveredAgentSet.has(agentName)) {
+			items.push({
+				kind: "agent",
+				name: agentName,
+				status: "missing",
+				expected: "agent file discovered",
+				actual: "not found",
+				severity: "error",
+			});
+		}
+	}
+
+	// Extra: discovered agent referenced in overrides doesn't apply here;
+	// discovered agents not in overrides are not "extra" since they can be built-in.
+	// We only check if the override references a disabled agent that doesn't exist.
+
+	// --- Team drift ---
+	// Teams reference agents via roles; check if any role.agent is not in discovered agents
+	// This is already handled by validate-resources, so we keep it lightweight here.
+	// We do NOT mark teams as "extra" because teams can exist without explicit config references.
+
+	// --- Workflow drift ---
+	// Similar to teams — workflows are discovered but not directly referenced in config.
+	// No extra/missing checks for workflows from config alone.
+
+	// --- Config-key drift ---
+	const configKeys = Object.keys(configRaw);
+	for (const key of configKeys) {
+		if (!SCHEMA_KEYS.has(key)) {
+			items.push({
+				kind: "config-key",
+				name: key,
+				status: "extra",
+				expected: `key not in schema`,
+				actual: `present in config`,
+				severity: "warning",
+			});
+		}
+	}
+
+	// --- Mismatched config-key check ---
+	// Check if agents.overrides references exist but have unexpected structure
+	if (config.agents?.overrides) {
+		for (const [agentName, override] of Object.entries(config.agents.overrides)) {
+			if (override && typeof override === "object") {
+				const overrideKeys = Object.keys(override as Record<string, unknown>);
+				const knownOverrideKeys = new Set(["disabled", "model", "fallbackModels", "thinking", "tools", "skills"]);
+				const unknownKeys = overrideKeys.filter((key) => !knownOverrideKeys.has(key));
+				if (unknownKeys.length > 0) {
+					items.push({
+						kind: "agent",
+						name: agentName,
+						status: "mismatched",
+						expected: `override keys from schema: ${[...knownOverrideKeys].join(", ")}`,
+						actual: `unknown keys: ${unknownKeys.join(", ")}`,
+						severity: "warning",
+					});
+				}
+			}
+		}
+	}
+
+	// --- Build summary ---
+	const missing = items.filter((item) => item.status === "missing").length;
+	const extra = items.filter((item) => item.status === "extra").length;
+	const mismatched = items.filter((item) => item.status === "mismatched").length;
+
+	return {
+		hasDrift: items.length > 0,
+		items,
+		summary: { missing, extra, mismatched },
+	};
+}
+
+/**
+ * Format a drift report into a human-readable multi-line string.
+ */
+export function formatDriftReport(report: DriftReport): string {
+	if (!report.hasDrift) {
+		return "No drift detected.";
+	}
+	const lines: string[] = [
+		`Drift summary: ${report.summary.missing} missing, ${report.summary.extra} extra, ${report.summary.mismatched} mismatched`,
+		"",
+	];
+	for (const item of report.items) {
+		const severityTag = item.severity === "error" ? "ERROR" : "WARN";
+		const detail = item.expected && item.actual ? ` (expected: ${item.expected}, actual: ${item.actual})` : "";
+		lines.push(`- ${severityTag} [${item.kind}] ${item.name}: ${item.status}${detail}`);
+	}
+	return lines.join("\n");
+}