indus-swarms 0.1.0

package/extensions/teams/team-attach-claim.ts

@@ -0,0 +1,205 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withLock } from "./fs-lock.js";
+
+export const TEAM_ATTACH_CLAIM_FILE = ".attach-claim.json";
+export const TEAM_ATTACH_CLAIM_STALE_MS = 30_000;
+
+export interface TeamAttachClaim {
+	holderSessionId: string;
+	claimedAt: string;
+	heartbeatAt: string;
+	pid: number;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
+function getString(obj: Record<string, unknown>, key: string): string | null {
+	const value = obj[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function getNumber(obj: Record<string, unknown>, key: string): number | null {
+	const value = obj[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseTeamAttachClaim(value: unknown): TeamAttachClaim | null {
+	if (!isRecord(value)) return null;
+	const holderSessionId = getString(value, "holderSessionId");
+	const claimedAt = getString(value, "claimedAt");
+	const heartbeatAt = getString(value, "heartbeatAt");
+	const pid = getNumber(value, "pid");
+	if (!holderSessionId || !claimedAt || !heartbeatAt || pid === null) return null;
+	return { holderSessionId, claimedAt, heartbeatAt, pid };
+}
+
+function getClaimPath(teamDir: string): string {
+	return path.join(teamDir, TEAM_ATTACH_CLAIM_FILE);
+}
+
+function getClaimLockPath(teamDir: string): string {
+	return `${getClaimPath(teamDir)}.lock`;
+}
+
+async function readClaimUnchecked(teamDir: string): Promise<TeamAttachClaim | null> {
+	const file = getClaimPath(teamDir);
+	try {
+		const raw = await fs.promises.readFile(file, "utf8");
+		const parsed: unknown = JSON.parse(raw);
+		return parseTeamAttachClaim(parsed);
+	} catch {
+		return null;
+	}
+}
+
+async function writeClaimAtomic(teamDir: string, claim: TeamAttachClaim): Promise<void> {
+	const file = getClaimPath(teamDir);
+	await fs.promises.mkdir(teamDir, { recursive: true });
+	const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+	await fs.promises.writeFile(tmp, JSON.stringify(claim, null, 2) + "\n", "utf8");
+	await fs.promises.rename(tmp, file);
+}
+
+export function assessAttachClaimFreshness(claim: TeamAttachClaim, nowMs = Date.now(), staleMs = TEAM_ATTACH_CLAIM_STALE_MS): {
+	isStale: boolean;
+	ageMs: number;
+} {
+	const heartbeatMs = Date.parse(claim.heartbeatAt);
+	if (!Number.isFinite(heartbeatMs)) {
+		return { isStale: true, ageMs: Number.POSITIVE_INFINITY };
+	}
+	const ageMs = Math.max(0, nowMs - heartbeatMs);
+	return {
+		isStale: ageMs > staleMs,
+		ageMs,
+	};
+}
+
+export async function readTeamAttachClaim(teamDir: string): Promise<TeamAttachClaim | null> {
+	return await readClaimUnchecked(teamDir);
+}
+
+export type AcquireTeamAttachClaimResult =
+	| {
+			ok: true;
+			claim: TeamAttachClaim;
+			replacedClaim?: TeamAttachClaim;
+	  }
+	| {
+			ok: false;
+			reason: "claimed_by_other";
+			claim: TeamAttachClaim;
+	  };
+
+export async function acquireTeamAttachClaim(
+	teamDir: string,
+	holderSessionId: string,
+	opts?: { force?: boolean; staleMs?: number; nowMs?: number },
+): Promise<AcquireTeamAttachClaimResult> {
+	const lockFile = getClaimLockPath(teamDir);
+	const staleMs = opts?.staleMs ?? TEAM_ATTACH_CLAIM_STALE_MS;
+	const force = opts?.force === true;
+
+	await fs.promises.mkdir(teamDir, { recursive: true });
+
+	return await withLock(
+		lockFile,
+		async () => {
+			const nowMs = opts?.nowMs ?? Date.now();
+			const nowIso = new Date(nowMs).toISOString();
+			const current = await readClaimUnchecked(teamDir);
+			if (current) {
+				const freshness = assessAttachClaimFreshness(current, nowMs, staleMs);
+				const sameHolder = current.holderSessionId === holderSessionId;
+				if (!sameHolder && !freshness.isStale && !force) {
+					return { ok: false, reason: "claimed_by_other", claim: current };
+				}
+
+				const claim: TeamAttachClaim = {
+					holderSessionId,
+					claimedAt: sameHolder ? current.claimedAt : nowIso,
+					heartbeatAt: nowIso,
+					pid: process.pid,
+				};
+				await writeClaimAtomic(teamDir, claim);
+				return {
+					ok: true,
+					claim,
+					replacedClaim: sameHolder ? undefined : current,
+				};
+			}
+
+			const claim: TeamAttachClaim = {
+				holderSessionId,
+				claimedAt: nowIso,
+				heartbeatAt: nowIso,
+				pid: process.pid,
+			};
+			await writeClaimAtomic(teamDir, claim);
+			return { ok: true, claim };
+		},
+		{ label: `team-attach-claim:acquire:${holderSessionId}` },
+	);
+}
+
+export type TeamAttachClaimHeartbeatResult = "updated" | "not_owner" | "missing";
+
+export async function heartbeatTeamAttachClaim(
+	teamDir: string,
+	holderSessionId: string,
+	opts?: { nowMs?: number },
+): Promise<TeamAttachClaimHeartbeatResult> {
+	const lockFile = getClaimLockPath(teamDir);
+	await fs.promises.mkdir(teamDir, { recursive: true });
+
+	return await withLock(
+		lockFile,
+		async () => {
+			const current = await readClaimUnchecked(teamDir);
+			if (!current) return "missing";
+			if (current.holderSessionId !== holderSessionId) return "not_owner";
+			const nowMs = opts?.nowMs ?? Date.now();
+			const nowIso = new Date(nowMs).toISOString();
+			const updated: TeamAttachClaim = {
+				...current,
+				heartbeatAt: nowIso,
+				pid: process.pid,
+			};
+			await writeClaimAtomic(teamDir, updated);
+			return "updated";
+		},
+		{ label: `team-attach-claim:heartbeat:${holderSessionId}` },
+	);
+}
+
+export type TeamAttachClaimReleaseResult = "released" | "not_owner" | "none";
+
+export async function releaseTeamAttachClaim(
+	teamDir: string,
+	holderSessionId: string,
+	opts?: { force?: boolean },
+): Promise<TeamAttachClaimReleaseResult> {
+	const lockFile = getClaimLockPath(teamDir);
+	const file = getClaimPath(teamDir);
+	const force = opts?.force === true;
+	await fs.promises.mkdir(teamDir, { recursive: true });
+
+	return await withLock(
+		lockFile,
+		async () => {
+			const current = await readClaimUnchecked(teamDir);
+			if (!current) return "none";
+			if (!force && current.holderSessionId !== holderSessionId) return "not_owner";
+			try {
+				await fs.promises.unlink(file);
+			} catch {
+				// ignore: treat as released best effort
+			}
+			return "released";
+		},
+		{ label: `team-attach-claim:release:${holderSessionId}` },
+	);
+}

package/extensions/teams/team-config.ts

@@ -0,0 +1,335 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withLock } from "./fs-lock.js";
+import { sanitizeName } from "./names.js";
+import type { TeamsStyle } from "./teams-style.js";
+import { normalizeTeamsStyleId } from "./teams-style.js";
+
+export interface TeamMember {
+	name: string;
+	role: "lead" | "worker";
+	addedAt: string;
+	status: "online" | "offline";
+	lastSeenAt?: string;
+	/** Optional: teammate session file path (useful for debugging) */
+	sessionFile?: string;
+	/** Optional: teammate working directory */
+	cwd?: string;
+	/** Freeform metadata for future use */
+	meta?: Record<string, unknown>;
+}
+
+export type TeamHooksFailureAction = "warn" | "followup" | "reopen" | "reopen_followup";
+export type TeamHooksFollowupOwnerPolicy = "member" | "lead" | "none";
+
+export interface TeamHooksPolicy {
+	failureAction?: TeamHooksFailureAction;
+	maxReopensPerTask?: number;
+	followupOwner?: TeamHooksFollowupOwnerPolicy;
+}
+
+export interface TeamConfig {
+	version: 1;
+	teamId: string;
+	/** Task list namespace identifier (Claude-style: often teamName or parentSessionId) */
+	taskListId: string;
+	/** Internal leader agent id (mailbox name, member name, etc.) */
+	leadName: string;
+	/** Optional UI/UX style. If omitted, treat as "normal". */
+	style?: TeamsStyle;
+	/** Optional per-team hooks policy override (env remains fallback). */
+	hooks?: TeamHooksPolicy;
+	createdAt: string;
+	updatedAt: string;
+	members: TeamMember[];
+}
+
+export function getTeamConfigPath(teamDir: string): string {
+	return path.join(teamDir, "config.json");
+}
+
+async function ensureDir(p: string): Promise<void> {
+	await fs.promises.mkdir(p, { recursive: true });
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
+function coerceStyle(v: unknown): TeamsStyle | undefined {
+	return normalizeTeamsStyleId(v) ?? undefined;
+}
+
+function isTeamHooksFailureAction(v: unknown): v is TeamHooksFailureAction {
+	return v === "warn" || v === "followup" || v === "reopen" || v === "reopen_followup";
+}
+
+function isTeamHooksFollowupOwnerPolicy(v: unknown): v is TeamHooksFollowupOwnerPolicy {
+	return v === "member" || v === "lead" || v === "none";
+}
+
+function coerceNonNegativeInt(v: unknown): number | undefined {
+	if (typeof v !== "number" || !Number.isFinite(v) || v < 0) return undefined;
+	return Math.floor(v);
+}
+
+function coerceHooksPolicy(v: unknown): TeamHooksPolicy | undefined {
+	if (!isRecord(v)) return undefined;
+	const failureAction = isTeamHooksFailureAction(v.failureAction) ? v.failureAction : undefined;
+	const maxReopensPerTask = coerceNonNegativeInt(v.maxReopensPerTask);
+	const followupOwner = isTeamHooksFollowupOwnerPolicy(v.followupOwner) ? v.followupOwner : undefined;
+	if (!failureAction && maxReopensPerTask === undefined && !followupOwner) return undefined;
+	return { failureAction, maxReopensPerTask, followupOwner };
+}
+
+async function readJson(file: string): Promise<unknown | null> {
+	try {
+		const raw = await fs.promises.readFile(file, "utf8");
+		const parsed: unknown = JSON.parse(raw);
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+
+async function writeJsonAtomic(file: string, data: unknown): Promise<void> {
+	await ensureDir(path.dirname(file));
+	const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+	await fs.promises.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
+	await fs.promises.rename(tmp, file);
+}
+
+function coerceMember(obj: unknown): TeamMember | null {
+	if (!isRecord(obj)) return null;
+	if (typeof obj.name !== "string") return null;
+	if (obj.role !== "lead" && obj.role !== "worker") return null;
+	if (obj.status !== "online" && obj.status !== "offline") return null;
+	if (typeof obj.addedAt !== "string") return null;
+
+	return {
+		name: sanitizeName(obj.name),
+		role: obj.role,
+		status: obj.status,
+		addedAt: obj.addedAt,
+		lastSeenAt: typeof obj.lastSeenAt === "string" ? obj.lastSeenAt : undefined,
+		sessionFile: typeof obj.sessionFile === "string" ? obj.sessionFile : undefined,
+		cwd: typeof obj.cwd === "string" ? obj.cwd : undefined,
+		meta: isRecord(obj.meta) ? obj.meta : undefined,
+	};
+}
+
+function coerceConfig(obj: unknown): TeamConfig | null {
+	if (!isRecord(obj)) return null;
+	if (obj.version !== 1) return null;
+	if (typeof obj.teamId !== "string") return null;
+	if (typeof obj.taskListId !== "string") return null;
+	if (typeof obj.leadName !== "string") return null;
+	if (typeof obj.createdAt !== "string") return null;
+	if (typeof obj.updatedAt !== "string") return null;
+	if (!Array.isArray(obj.members)) return null;
+
+	const style = coerceStyle(obj.style);
+	const hooks = coerceHooksPolicy(obj.hooks);
+	const members = obj.members.map(coerceMember).filter((m): m is TeamMember => m !== null);
+	return {
+		version: 1,
+		teamId: obj.teamId,
+		taskListId: obj.taskListId,
+		leadName: sanitizeName(obj.leadName),
+		style,
+		hooks,
+		createdAt: obj.createdAt,
+		updatedAt: obj.updatedAt,
+		members,
+	};
+}
+
+export async function loadTeamConfig(teamDir: string): Promise<TeamConfig | null> {
+	const file = getTeamConfigPath(teamDir);
+	const obj = await readJson(file);
+	return coerceConfig(obj);
+}
+
+export async function ensureTeamConfig(
+	teamDir: string,
+	init: { teamId: string; taskListId: string; leadName: string; style?: TeamsStyle },
+): Promise<TeamConfig> {
+	const file = getTeamConfigPath(teamDir);
+	const lock = `${file}.lock`;
+
+	await ensureDir(teamDir);
+
+	return await withLock(
+		lock,
+		async () => {
+			const existing = coerceConfig(await readJson(file));
+			if (existing) return existing;
+
+			const now = new Date().toISOString();
+			const cfg: TeamConfig = {
+				version: 1,
+				teamId: init.teamId,
+				taskListId: init.taskListId,
+				leadName: sanitizeName(init.leadName),
+				style: init.style ?? "normal",
+				createdAt: now,
+				updatedAt: now,
+				members: [
+					{
+						name: sanitizeName(init.leadName),
+						role: "lead",
+						addedAt: now,
+						status: "online",
+						lastSeenAt: now,
+					},
+				],
+			};
+
+			await writeJsonAtomic(file, cfg);
+			return cfg;
+		},
+		{ label: "team-config:ensure" },
+	);
+}
+
+export async function setTeamStyle(teamDir: string, style: TeamsStyle): Promise<TeamConfig | null> {
+	const file = getTeamConfigPath(teamDir);
+	const lock = `${file}.lock`;
+
+	await ensureDir(teamDir);
+
+	return await withLock(
+		lock,
+		async () => {
+			const existing = coerceConfig(await readJson(file));
+			if (!existing) return null;
+
+			const now = new Date().toISOString();
+			const updated: TeamConfig = { ...existing, style, updatedAt: now };
+			await writeJsonAtomic(file, updated);
+			return updated;
+		},
+		{ label: `team-config:style:${style}` },
+	);
+}
+
+export async function updateTeamHooksPolicy(
+	teamDir: string,
+	updater: (current: TeamHooksPolicy) => TeamHooksPolicy | undefined,
+): Promise<TeamConfig | null> {
+	const file = getTeamConfigPath(teamDir);
+	const lock = `${file}.lock`;
+
+	await ensureDir(teamDir);
+
+	return await withLock(
+		lock,
+		async () => {
+			const existing = coerceConfig(await readJson(file));
+			if (!existing) return null;
+
+			const nextHooks = coerceHooksPolicy(updater(existing.hooks ?? {}));
+			const now = new Date().toISOString();
+			const updated: TeamConfig = { ...existing, hooks: nextHooks, updatedAt: now };
+			await writeJsonAtomic(file, updated);
+			return updated;
+		},
+		{ label: "team-config:hooks-policy" },
+	);
+}
+
+export async function upsertMember(
+	teamDir: string,
+	member: Omit<TeamMember, "name" | "addedAt"> & { name: string; addedAt?: string },
+): Promise<TeamConfig> {
+	const file = getTeamConfigPath(teamDir);
+	const lock = `${file}.lock`;
+
+	await ensureDir(teamDir);
+
+	return await withLock(
+		lock,
+		async () => {
+			const existing = coerceConfig(await readJson(file));
+			if (!existing) {
+				throw new Error(`Team config missing. Call ensureTeamConfig() first. path=${file}`);
+			}
+
+			const now = new Date().toISOString();
+			const name = sanitizeName(member.name);
+			const idx = existing.members.findIndex((m) => m.name === name);
+			const prev = idx >= 0 ? existing.members[idx] : undefined;
+			if (idx >= 0 && !prev) {
+				throw new Error(`Team config corrupted: member index out of range. idx=${idx}`);
+			}
+
+			const nextMember: TeamMember = {
+				name,
+				role: member.role,
+				status: member.status,
+				addedAt: prev ? prev.addedAt : member.addedAt ?? now,
+				lastSeenAt: member.lastSeenAt ?? now,
+				sessionFile: member.sessionFile,
+				cwd: member.cwd,
+				meta: member.meta,
+			};
+
+			const members = existing.members.slice();
+			if (prev) {
+				members[idx] = { ...prev, ...nextMember, addedAt: prev.addedAt };
+			} else {
+				members.push(nextMember);
+			}
+
+			const updated: TeamConfig = {
+				...existing,
+				updatedAt: now,
+				members,
+			};
+
+			await writeJsonAtomic(file, updated);
+			return updated;
+		},
+		{ label: `team-config:upsert:${member.name}` },
+	);
+}
+
+export async function setMemberStatus(
+	teamDir: string,
+	memberName: string,
+	status: "online" | "offline",
+	extra?: { lastSeenAt?: string; meta?: Record<string, unknown> },
+): Promise<TeamConfig | null> {
+	const file = getTeamConfigPath(teamDir);
+	const lock = `${file}.lock`;
+
+	await ensureDir(teamDir);
+
+	return await withLock(
+		lock,
+		async () => {
+			const existing = coerceConfig(await readJson(file));
+			if (!existing) return null;
+
+			const name = sanitizeName(memberName);
+			const idx = existing.members.findIndex((m) => m.name === name);
+			if (idx < 0) return existing;
+
+			const now = new Date().toISOString();
+			const members = existing.members.slice();
+			const prev = members[idx];
+			if (!prev) return existing;
+			members[idx] = {
+				...prev,
+				status,
+				lastSeenAt: extra?.lastSeenAt ?? now,
+				meta: extra?.meta ? { ...(prev.meta ?? {}), ...extra.meta } : prev.meta,
+			};
+
+			const updated: TeamConfig = { ...existing, updatedAt: now, members };
+			await writeJsonAtomic(file, updated);
+			return updated;
+		},
+		{ label: `team-config:status:${memberName}` },
+	);
+}

package/extensions/teams/team-discovery.ts

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getTeamsRootDir } from "./paths.js";
+import { assessAttachClaimFreshness, readTeamAttachClaim } from "./team-attach-claim.js";
+import { loadTeamConfig } from "./team-config.js";
+import type { TeamsStyle } from "./teams-style.js";
+
+export interface DiscoveredTeam {
+	teamId: string;
+	teamDir: string;
+	taskListId: string;
+	leadName: string;
+	style: TeamsStyle;
+	workerCount: number;
+	onlineWorkerCount: number;
+	updatedAt: string;
+	attachedBySessionId?: string;
+	attachClaimStale?: boolean;
+	attachHeartbeatAt?: string;
+}
+
+export async function listDiscoveredTeams(teamsRoot = getTeamsRootDir()): Promise<DiscoveredTeam[]> {
+	let entries: fs.Dirent[];
+	try {
+		entries = await fs.promises.readdir(teamsRoot, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const out: DiscoveredTeam[] = [];
+	for (const e of entries) {
+		if (!e.isDirectory()) continue;
+		if (e.name.startsWith("_")) continue;
+		const teamDir = path.join(teamsRoot, e.name);
+		const cfg = await loadTeamConfig(teamDir);
+		if (!cfg) continue;
+
+		const workers = cfg.members.filter((m) => m.role === "worker");
+		const onlineWorkerCount = workers.filter((m) => m.status === "online").length;
+		const attachClaim = await readTeamAttachClaim(teamDir);
+		const freshness = attachClaim ? assessAttachClaimFreshness(attachClaim) : null;
+		out.push({
+			teamId: cfg.teamId,
+			teamDir,
+			taskListId: cfg.taskListId,
+			leadName: cfg.leadName,
+			style: cfg.style ?? "normal",
+			workerCount: workers.length,
+			onlineWorkerCount,
+			updatedAt: cfg.updatedAt,
+			attachedBySessionId: attachClaim?.holderSessionId,
+			attachClaimStale: freshness?.isStale,
+			attachHeartbeatAt: attachClaim?.heartbeatAt,
+		});
+	}
+
+	out.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
+	return out;
+}