pi-crew 0.1.0

package/src/state/mailbox.ts

@@ -0,0 +1,188 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "./types.ts";
+
+export type MailboxDirection = "inbox" | "outbox";
+export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
+
+export interface MailboxMessage {
+	id: string;
+	runId: string;
+	direction: MailboxDirection;
+	from: string;
+	to: string;
+	body: string;
+	createdAt: string;
+	status: MailboxMessageStatus;
+	taskId?: string;
+	acknowledgedAt?: string;
+}
+
+export interface MailboxDeliveryState {
+	messages: Record<string, MailboxMessageStatus>;
+	updatedAt: string;
+}
+
+export interface MailboxValidationIssue {
+	level: "error" | "warning";
+	path: string;
+	message: string;
+}
+
+export interface MailboxValidationReport {
+	issues: MailboxValidationIssue[];
+	repaired: string[];
+}
+
+function mailboxDir(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "mailbox");
+}
+
+function taskMailboxDir(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(mailboxDir(manifest), "tasks", taskId);
+}
+
+function mailboxPath(manifest: TeamRunManifest, direction: MailboxDirection, taskId?: string): string {
+	return taskId ? path.join(taskMailboxDir(manifest, taskId), `${direction}.jsonl`) : path.join(mailboxDir(manifest), `${direction}.jsonl`);
+}
+
+function deliveryPath(manifest: TeamRunManifest): string {
+	return path.join(mailboxDir(manifest), "delivery.json");
+}
+
+function ensureMailbox(manifest: TeamRunManifest, taskId?: string): void {
+	fs.mkdirSync(taskId ? taskMailboxDir(manifest, taskId) : mailboxDir(manifest), { recursive: true });
+	for (const direction of ["inbox", "outbox"] as const) {
+		const filePath = mailboxPath(manifest, direction, taskId);
+		if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, "", "utf-8");
+	}
+	fs.mkdirSync(mailboxDir(manifest), { recursive: true });
+	const delivery = deliveryPath(manifest);
+	if (!fs.existsSync(delivery)) fs.writeFileSync(delivery, `${JSON.stringify({ messages: {}, updatedAt: new Date().toISOString() }, null, 2)}\n`, "utf-8");
+}
+
+function isDirection(value: unknown): value is MailboxDirection {
+	return value === "inbox" || value === "outbox";
+}
+
+function isStatus(value: unknown): value is MailboxMessageStatus {
+	return value === "queued" || value === "delivered" || value === "acknowledged";
+}
+
+function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection): MailboxMessage | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.id !== "string" || typeof obj.runId !== "string" || !isDirection(obj.direction) || typeof obj.from !== "string" || typeof obj.to !== "string" || typeof obj.body !== "string" || typeof obj.createdAt !== "string" || !isStatus(obj.status)) return undefined;
+	if (obj.direction !== expectedDirection) return undefined;
+	return { id: obj.id, runId: obj.runId, direction: obj.direction, from: obj.from, to: obj.to, body: obj.body, createdAt: obj.createdAt, status: obj.status, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined };
+}
+
+function readMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
+	if (!fs.existsSync(filePath)) return [];
+	const messages: MailboxMessage[] = [];
+	const raw = fs.readFileSync(filePath, "utf-8");
+	for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+		try {
+			const message = parseMailboxMessage(JSON.parse(line) as unknown, direction);
+			if (message) messages.push(message);
+		} catch {
+			// Invalid mailbox lines are reported by validateMailbox().
+		}
+	}
+	return messages;
+}
+
+export function readMailbox(manifest: TeamRunManifest, direction?: MailboxDirection, taskId?: string): MailboxMessage[] {
+	ensureMailbox(manifest, taskId);
+	const directions = direction ? [direction] : ["inbox", "outbox"] as const;
+	const messages = directions.flatMap((item) => readMailboxFile(mailboxPath(manifest, item, taskId), item));
+	return messages.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliveryState {
+	ensureMailbox(manifest);
+	try {
+		const raw = JSON.parse(fs.readFileSync(deliveryPath(manifest), "utf-8")) as unknown;
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid delivery state.");
+		const obj = raw as Record<string, unknown>;
+		const messages: Record<string, MailboxMessageStatus> = {};
+		if (obj.messages && typeof obj.messages === "object" && !Array.isArray(obj.messages)) {
+			for (const [id, status] of Object.entries(obj.messages)) if (isStatus(status)) messages[id] = status;
+		}
+		return { messages, updatedAt: typeof obj.updatedAt === "string" ? obj.updatedAt : new Date().toISOString() };
+	} catch {
+		return { messages: {}, updatedAt: new Date().toISOString() };
+	}
+}
+
+function writeDeliveryState(manifest: TeamRunManifest, state: MailboxDeliveryState): void {
+	ensureMailbox(manifest);
+	fs.writeFileSync(deliveryPath(manifest), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+
+export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<MailboxMessage, "id" | "runId" | "createdAt" | "status"> & { id?: string; status?: MailboxMessageStatus }): MailboxMessage {
+	ensureMailbox(manifest, message.taskId);
+	const createdAt = new Date().toISOString();
+	const complete: MailboxMessage = {
+		id: message.id ?? `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+		runId: manifest.runId,
+		direction: message.direction,
+		from: message.from,
+		to: message.to,
+		body: message.body,
+		createdAt,
+		status: message.status ?? "queued",
+		taskId: message.taskId,
+	};
+	fs.appendFileSync(mailboxPath(manifest, complete.direction, complete.taskId), `${JSON.stringify(complete)}\n`, "utf-8");
+	const delivery = readDeliveryState(manifest);
+	delivery.messages[complete.id] = complete.status;
+	delivery.updatedAt = createdAt;
+	writeDeliveryState(manifest, delivery);
+	return complete;
+}
+
+export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId: string): MailboxDeliveryState {
+	const delivery = readDeliveryState(manifest);
+	if (!delivery.messages[messageId]) throw new Error(`Mailbox message '${messageId}' not found.`);
+	delivery.messages[messageId] = "acknowledged";
+	delivery.updatedAt = new Date().toISOString();
+	writeDeliveryState(manifest, delivery);
+	return delivery;
+}
+
+export function validateMailbox(manifest: TeamRunManifest, options: { repair?: boolean } = {}): MailboxValidationReport {
+	ensureMailbox(manifest);
+	const issues: MailboxValidationIssue[] = [];
+	const repaired: string[] = [];
+	for (const direction of ["inbox", "outbox"] as const) {
+		const filePath = mailboxPath(manifest, direction);
+		const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+		const validLines: string[] = [];
+		for (const line of lines) {
+			try {
+				const parsed = JSON.parse(line) as unknown;
+				const message = parseMailboxMessage(parsed, direction);
+				if (!message) throw new Error("invalid message schema");
+				validLines.push(JSON.stringify(message));
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				issues.push({ level: "error", path: filePath, message });
+			}
+		}
+		if (options.repair && validLines.length !== lines.length) {
+			fs.writeFileSync(filePath, `${validLines.join("\n")}${validLines.length ? "\n" : ""}`, "utf-8");
+			repaired.push(filePath);
+		}
+	}
+	const delivery = readDeliveryState(manifest);
+	const allMessages = readMailbox(manifest);
+	for (const message of allMessages) if (!delivery.messages[message.id]) issues.push({ level: "warning", path: deliveryPath(manifest), message: `Missing delivery entry for ${message.id}.` });
+	if (options.repair) {
+		for (const message of allMessages) delivery.messages[message.id] ??= message.status;
+		delivery.updatedAt = new Date().toISOString();
+		writeDeliveryState(manifest, delivery);
+		repaired.push(deliveryPath(manifest));
+	}
+	return { issues, repaired };
+}

package/src/state/state-store.ts

@@ -0,0 +1,119 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest, TeamTaskState } from "./types.ts";
+import { canTransitionRunStatus } from "./contracts.ts";
+import { atomicWriteJson, readJsonFile } from "./atomic-write.ts";
+import { appendEvent } from "./event-log.ts";
+import { createRunId, createTaskId } from "../utils/ids.ts";
+import { projectPiRoot, userPiRoot } from "../utils/paths.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+
+export interface RunPaths {
+	runId: string;
+	stateRoot: string;
+	artifactsRoot: string;
+	manifestPath: string;
+	tasksPath: string;
+	eventsPath: string;
+}
+
+function useProjectState(cwd: string): boolean {
+	return fs.existsSync(path.join(cwd, ".pi")) || fs.existsSync(path.join(cwd, ".git"));
+}
+
+export function createRunPaths(cwd: string, runId = createRunId()): RunPaths {
+	const baseRoot = useProjectState(cwd)
+		? path.join(projectPiRoot(cwd), "teams")
+		: path.join(userPiRoot(), "extensions", "pi-crew", "runs");
+	const stateRoot = path.join(baseRoot, "state", "runs", runId);
+	const artifactsRoot = path.join(baseRoot, "artifacts", runId);
+	return {
+		runId,
+		stateRoot,
+		artifactsRoot,
+		manifestPath: path.join(stateRoot, "manifest.json"),
+		tasksPath: path.join(stateRoot, "tasks.json"),
+		eventsPath: path.join(stateRoot, "events.jsonl"),
+	};
+}
+
+export function createTasksFromWorkflow(runId: string, workflow: WorkflowConfig, team: TeamConfig, cwd: string): TeamTaskState[] {
+	return workflow.steps.map((step, index) => {
+		const role = team.roles.find((candidate) => candidate.name === step.role);
+		return {
+			id: createTaskId(step.id, index),
+			runId,
+			stepId: step.id,
+			role: step.role,
+			agent: role?.agent ?? step.role,
+			title: step.id,
+			status: "queued",
+			dependsOn: step.dependsOn ?? [],
+			cwd,
+		};
+	});
+}
+
+export function createRunManifest(params: {
+	cwd: string;
+	team: TeamConfig;
+	workflow?: WorkflowConfig;
+	goal: string;
+	workspaceMode?: "single" | "worktree";
+}): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
+	const paths = createRunPaths(params.cwd);
+	const now = new Date().toISOString();
+	const tasks = params.workflow ? createTasksFromWorkflow(paths.runId, params.workflow, params.team, params.cwd) : [];
+	const manifest: TeamRunManifest = {
+		schemaVersion: 1,
+		runId: paths.runId,
+		team: params.team.name,
+		workflow: params.workflow?.name,
+		goal: params.goal,
+		status: "queued",
+		workspaceMode: params.workspaceMode ?? params.team.workspaceMode ?? "single",
+		createdAt: now,
+		updatedAt: now,
+		cwd: params.cwd,
+		stateRoot: paths.stateRoot,
+		artifactsRoot: paths.artifactsRoot,
+		tasksPath: paths.tasksPath,
+		eventsPath: paths.eventsPath,
+		artifacts: [],
+	};
+	fs.mkdirSync(paths.stateRoot, { recursive: true });
+	fs.mkdirSync(paths.artifactsRoot, { recursive: true });
+	atomicWriteJson(paths.manifestPath, manifest);
+	atomicWriteJson(paths.tasksPath, tasks);
+	appendEvent(paths.eventsPath, { type: "run.created", runId: paths.runId, data: { team: params.team.name, workflow: params.workflow?.name } });
+	return { manifest, tasks, paths };
+}
+
+export function saveRunManifest(manifest: TeamRunManifest): void {
+	atomicWriteJson(path.join(manifest.stateRoot, "manifest.json"), manifest);
+}
+
+export function saveRunTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]): void {
+	atomicWriteJson(manifest.tasksPath, tasks);
+}
+
+export function updateRunStatus(manifest: TeamRunManifest, status: TeamRunManifest["status"], summary?: string): TeamRunManifest {
+	if (!canTransitionRunStatus(manifest.status, status)) {
+		throw new Error(`Invalid run status transition: ${manifest.status} -> ${status}`);
+	}
+	const updated: TeamRunManifest = { ...manifest, status, updatedAt: new Date().toISOString(), summary: summary ?? manifest.summary };
+	saveRunManifest(updated);
+	appendEvent(updated.eventsPath, { type: `run.${status}`, runId: updated.runId, message: summary });
+	return updated;
+}
+
+export function loadRunManifestById(cwd: string, runId: string): { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined {
+	const projectPath = path.join(projectPiRoot(cwd), "teams", "state", "runs", runId);
+	const userPath = path.join(userPiRoot(), "extensions", "pi-crew", "runs", "state", "runs", runId);
+	const stateRoot = fs.existsSync(projectPath) ? projectPath : userPath;
+	const manifest = readJsonFile<TeamRunManifest>(path.join(stateRoot, "manifest.json"));
+	if (!manifest) return undefined;
+	const tasks = readJsonFile<TeamTaskState[]>(path.join(stateRoot, "tasks.json")) ?? [];
+	return { manifest, tasks };
+}

package/src/state/task-claims.ts

@@ -0,0 +1,42 @@
+import { randomUUID } from "node:crypto";
+import type { TeamTaskState } from "./types.ts";
+
+export interface TaskClaimState {
+	owner: string;
+	token: string;
+	leasedUntil: string;
+}
+
+export function createTaskClaim(owner: string, leaseMs = 5 * 60_000, now = new Date()): TaskClaimState {
+	return { owner, token: randomUUID(), leasedUntil: new Date(now.getTime() + leaseMs).toISOString() };
+}
+
+export function isTaskClaimExpired(claim: TaskClaimState | undefined, now = new Date()): boolean {
+	if (!claim) return false;
+	return Date.parse(claim.leasedUntil) <= now.getTime();
+}
+
+export function canUseTaskClaim(task: Pick<TeamTaskState, "claim">, owner: string, token: string, now = new Date()): boolean {
+	return task.claim?.owner === owner && task.claim.token === token && !isTaskClaimExpired(task.claim, now);
+}
+
+export function claimTask<T extends TeamTaskState>(task: T, owner: string, leaseMs?: number, now = new Date()): T {
+	if (task.claim && !isTaskClaimExpired(task.claim, now)) {
+		throw new Error(`Task '${task.id}' is already claimed by '${task.claim.owner}'.`);
+	}
+	return { ...task, claim: createTaskClaim(owner, leaseMs, now) };
+}
+
+export function releaseTaskClaim<T extends TeamTaskState>(task: T, owner: string, token: string, now = new Date()): T {
+	if (!canUseTaskClaim(task, owner, token, now)) {
+		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
+	}
+	return { ...task, claim: undefined };
+}
+
+export function transitionClaimedTaskStatus<T extends TeamTaskState>(task: T, owner: string, token: string, status: T["status"], now = new Date()): T {
+	if (!canUseTaskClaim(task, owner, token, now)) {
+		throw new Error(`Task '${task.id}' claim is not held by '${owner}' or has expired.`);
+	}
+	return { ...task, status };
+}

package/src/state/types.ts

@@ -0,0 +1,88 @@
+import type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
+import type { TaskClaimState } from "./task-claims.ts";
+import type { WorkerHeartbeatState } from "../runtime/worker-heartbeat.ts";
+export type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
+
+export interface ArtifactDescriptor {
+	kind: "plan" | "prompt" | "result" | "summary" | "log" | "diff" | "patch" | "progress" | "notepad" | "metadata";
+	path: string;
+	createdAt: string;
+	producer: string;
+	sizeBytes?: number;
+	contentHash?: string;
+	retention: "run" | "project" | "temporary";
+	expiresAt?: string;
+}
+
+export interface AsyncRunState {
+	pid?: number;
+	logPath: string;
+	spawnedAt: string;
+}
+
+export interface TeamRunManifest {
+	schemaVersion: 1;
+	runId: string;
+	team: string;
+	workflow?: string;
+	goal: string;
+	status: TeamRunStatus;
+	workspaceMode: "single" | "worktree";
+	createdAt: string;
+	updatedAt: string;
+	cwd: string;
+	stateRoot: string;
+	artifactsRoot: string;
+	tasksPath: string;
+	eventsPath: string;
+	artifacts: ArtifactDescriptor[];
+	async?: AsyncRunState;
+	summary?: string;
+}
+
+export interface UsageState {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: number;
+	turns?: number;
+}
+
+export interface ModelAttemptState {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+}
+
+export interface TaskWorktreeState {
+	path: string;
+	branch: string;
+	reused: boolean;
+}
+
+export interface TeamTaskState {
+	id: string;
+	runId: string;
+	stepId?: string;
+	role: string;
+	agent: string;
+	title: string;
+	status: TeamTaskStatus;
+	dependsOn: string[];
+	cwd: string;
+	worktree?: TaskWorktreeState;
+	promptArtifact?: ArtifactDescriptor;
+	resultArtifact?: ArtifactDescriptor;
+	logArtifact?: ArtifactDescriptor;
+	startedAt?: string;
+	finishedAt?: string;
+	exitCode?: number | null;
+	modelAttempts?: ModelAttemptState[];
+	usage?: UsageState;
+	jsonEvents?: number;
+	error?: string;
+	claim?: TaskClaimState;
+	heartbeat?: WorkerHeartbeatState;
+}

package/src/state/usage.ts

@@ -0,0 +1,29 @@
+import type { TeamTaskState, UsageState } from "./types.ts";
+
+export function aggregateUsage(tasks: TeamTaskState[]): UsageState | undefined {
+	const total: UsageState = {};
+	let found = false;
+	for (const task of tasks) {
+		if (!task.usage) continue;
+		found = true;
+		total.input = (total.input ?? 0) + (task.usage.input ?? 0);
+		total.output = (total.output ?? 0) + (task.usage.output ?? 0);
+		total.cacheRead = (total.cacheRead ?? 0) + (task.usage.cacheRead ?? 0);
+		total.cacheWrite = (total.cacheWrite ?? 0) + (task.usage.cacheWrite ?? 0);
+		total.cost = (total.cost ?? 0) + (task.usage.cost ?? 0);
+		total.turns = (total.turns ?? 0) + (task.usage.turns ?? 0);
+	}
+	return found ? total : undefined;
+}
+
+export function formatUsage(usage: UsageState | undefined): string {
+	if (!usage) return "(none)";
+	const parts: string[] = [];
+	if (usage.input !== undefined) parts.push(`input=${usage.input}`);
+	if (usage.output !== undefined) parts.push(`output=${usage.output}`);
+	if (usage.cacheRead !== undefined) parts.push(`cacheRead=${usage.cacheRead}`);
+	if (usage.cacheWrite !== undefined) parts.push(`cacheWrite=${usage.cacheWrite}`);
+	if (usage.cost !== undefined) parts.push(`cost=${usage.cost.toFixed(6)}`);
+	if (usage.turns !== undefined) parts.push(`turns=${usage.turns}`);
+	return parts.join(", ") || "(none)";
+}

package/src/teams/discover-teams.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ResourceSource } from "../agents/agent-config.ts";
+import type { TeamConfig, TeamRole } from "./team-config.ts";
+import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
+import { packageRoot, projectPiRoot, userPiRoot } from "../utils/paths.ts";
+
+export interface TeamDiscoveryResult {
+	builtin: TeamConfig[];
+	user: TeamConfig[];
+	project: TeamConfig[];
+}
+
+function parseRoleLine(line: string): TeamRole | undefined {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith("-")) return undefined;
+	const value = trimmed.slice(1).trim();
+	if (!value) return undefined;
+	const [namePart, restPart] = value.split(":", 2);
+	const name = namePart?.trim();
+	if (!name) return undefined;
+	const agentMatch = restPart?.match(/agent\s*=\s*([\w-]+)/);
+	return {
+		name,
+		agent: agentMatch?.[1] ?? name,
+		description: restPart?.replace(/agent\s*=\s*[\w-]+/, "").trim() || undefined,
+	};
+}
+
+function parseCost(value: string | undefined): "free" | "cheap" | "expensive" | undefined {
+	return value === "free" || value === "cheap" || value === "expensive" ? value : undefined;
+}
+
+function parseTeamFile(filePath: string, source: ResourceSource): TeamConfig | undefined {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		const { frontmatter, body } = parseFrontmatter(content);
+		const name = frontmatter.name?.trim() || path.basename(filePath, ".team.md");
+		const roles = body.split("\n").map(parseRoleLine).filter((role): role is TeamRole => role !== undefined);
+		const triggers = parseCsv(frontmatter.triggers ?? frontmatter.trigger);
+		const useWhen = parseCsv(frontmatter.useWhen);
+		const avoidWhen = parseCsv(frontmatter.avoidWhen);
+		const cost = parseCost(frontmatter.cost);
+		const category = frontmatter.category?.trim() || undefined;
+		return {
+			name,
+			description: frontmatter.description?.trim() || "No description provided.",
+			source,
+			filePath,
+			roles,
+			defaultWorkflow: frontmatter.defaultWorkflow || frontmatter.workflow || undefined,
+			workspaceMode: frontmatter.workspaceMode === "worktree" ? "worktree" : "single",
+			maxConcurrency: frontmatter.maxConcurrency ? Number.parseInt(frontmatter.maxConcurrency, 10) : undefined,
+			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function readTeamDir(dir: string, source: ResourceSource): TeamConfig[] {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((entry) => entry.endsWith(".team.md"))
+		.map((entry) => parseTeamFile(path.join(dir, entry), source))
+		.filter((team): team is TeamConfig => team !== undefined)
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function discoverTeams(cwd: string): TeamDiscoveryResult {
+	return {
+		builtin: readTeamDir(path.join(packageRoot(), "teams"), "builtin"),
+		user: readTeamDir(path.join(userPiRoot(), "teams"), "user"),
+		project: readTeamDir(path.join(projectPiRoot(cwd), "teams"), "project"),
+	};
+}
+
+export function allTeams(discovery: TeamDiscoveryResult): TeamConfig[] {
+	const byName = new Map<string, TeamConfig>();
+	for (const team of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
+		byName.set(team.name, team);
+	}
+	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/teams/team-config.ts

@@ -0,0 +1,22 @@
+import type { ResourceSource, RoutingMetadata } from "../agents/agent-config.ts";
+
+export interface TeamRole {
+	name: string;
+	agent: string;
+	description?: string;
+	model?: string;
+	skills?: string[] | false;
+	maxConcurrency?: number;
+}
+
+export interface TeamConfig {
+	name: string;
+	description: string;
+	source: ResourceSource;
+	filePath: string;
+	roles: TeamRole[];
+	defaultWorkflow?: string;
+	workspaceMode?: "single" | "worktree";
+	maxConcurrency?: number;
+	routing?: RoutingMetadata;
+}

package/src/teams/team-serializer.ts

@@ -0,0 +1,36 @@
+import type { TeamConfig, TeamRole } from "./team-config.ts";
+
+function line(key: string, value: string | string[] | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+	return `${key}: ${value}`;
+}
+
+function serializeRole(role: TeamRole): string {
+	const parts = [`agent=${role.agent}`];
+	if (role.model) parts.push(`model=${role.model}`);
+	if (role.maxConcurrency !== undefined) parts.push(`maxConcurrency=${role.maxConcurrency}`);
+	if (role.description) parts.push(role.description);
+	return `- ${role.name}: ${parts.join(" ")}`;
+}
+
+export function serializeTeam(team: TeamConfig): string {
+	const lines = [
+		"---",
+		`name: ${team.name}`,
+		`description: ${team.description}`,
+		team.defaultWorkflow ? `defaultWorkflow: ${team.defaultWorkflow}` : undefined,
+		team.workspaceMode ? `workspaceMode: ${team.workspaceMode}` : undefined,
+		team.maxConcurrency !== undefined ? `maxConcurrency: ${team.maxConcurrency}` : undefined,
+		line("triggers", team.routing?.triggers),
+		line("useWhen", team.routing?.useWhen),
+		line("avoidWhen", team.routing?.avoidWhen),
+		line("cost", team.routing?.cost),
+		line("category", team.routing?.category),
+		"---",
+		"",
+		...team.roles.map(serializeRole),
+		"",
+	].filter((entry): entry is string => entry !== undefined);
+	return lines.join("\n");
+}