indus-swarms 0.1.0

package/extensions/teams/mailbox.ts

@@ -0,0 +1,131 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withLock } from "./fs-lock.js";
+import { sanitizeName } from "./names.js";
+
+export interface MailboxMessage {
+	from: string;
+	text: string;
+	timestamp: string;
+	read: boolean;
+	color?: string;
+}
+
+function inboxDir(teamDir: string, namespace: string): string {
+	return path.join(teamDir, "mailboxes", sanitizeName(namespace), "inboxes");
+}
+
+export function getInboxPath(teamDir: string, namespace: string, agentName: string): string {
+	return path.join(inboxDir(teamDir, namespace), `${sanitizeName(agentName)}.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 isLockTimeoutError(err: unknown): err is Error {
+	return err instanceof Error && err.message.startsWith("Timeout acquiring lock:");
+}
+
+function coerceMailboxMessage(v: unknown): MailboxMessage | null {
+	if (!isRecord(v)) return null;
+	if (typeof v.from !== "string") return null;
+	if (typeof v.text !== "string") return null;
+	if (typeof v.timestamp !== "string") return null;
+	const read = typeof v.read === "boolean" ? v.read : false;
+	const color = typeof v.color === "string" ? v.color : undefined;
+	return { from: v.from, text: v.text, timestamp: v.timestamp, read, color };
+}
+
+async function readJsonArray(file: string): Promise<unknown[]> {
+	try {
+		const raw = await fs.promises.readFile(file, "utf8");
+		const parsed: unknown = JSON.parse(raw);
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+
+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);
+}
+
+/** Append a message to an agent's inbox. */
+export async function writeToMailbox(
+	teamDir: string,
+	namespace: string,
+	recipient: string,
+	msg: Omit<MailboxMessage, "read"> & { read?: boolean },
+): Promise<void> {
+	const inboxPath = getInboxPath(teamDir, namespace, recipient);
+	const lockPath = `${inboxPath}.lock`;
+
+	await ensureDir(path.dirname(inboxPath));
+
+	await withLock(
+		lockPath,
+		async () => {
+			const arr = await readJsonArray(inboxPath);
+			const m: MailboxMessage = {
+				from: msg.from,
+				text: msg.text,
+				timestamp: msg.timestamp,
+				read: msg.read ?? false,
+				color: msg.color,
+			};
+			arr.push(m);
+			await writeJsonAtomic(inboxPath, arr);
+		},
+		{ label: `mailbox:write:${namespace}:${recipient}` },
+	);
+}
+
+/**
+ * Read unread messages and mark them as read in a single locked transaction.
+ * This is the worker/leader poll primitive.
+ */
+export async function popUnreadMessages(teamDir: string, namespace: string, agentName: string): Promise<MailboxMessage[]> {
+	const inboxPath = getInboxPath(teamDir, namespace, agentName);
+	const lockPath = `${inboxPath}.lock`;
+
+	await ensureDir(path.dirname(inboxPath));
+
+	try {
+		return await withLock(
+			lockPath,
+			async () => {
+				const arr = (await readJsonArray(inboxPath))
+					.map(coerceMailboxMessage)
+					.filter((m): m is MailboxMessage => m !== null);
+				if (arr.length === 0) return [];
+
+				const unread: MailboxMessage[] = [];
+				const updated = arr.map((m) => {
+					if (!m.read) {
+						const next = { ...m, read: true };
+						unread.push(next);
+						return next;
+					}
+					return m;
+				});
+
+				if (unread.length) await writeJsonAtomic(inboxPath, updated);
+				return unread;
+			},
+			{ label: `mailbox:pop:${namespace}:${agentName}` },
+		);
+	} catch (err: unknown) {
+		// In practice this can happen if a previous process crashed and left a non-stale
+		// lockfile behind. Treat as transient and try again on the next poll tick.
+		if (isLockTimeoutError(err)) return [];
+		throw err;
+	}
+}

package/extensions/teams/model-policy.ts

@@ -0,0 +1,142 @@
+const SONNET4_DEPRECATED_MARKER = "claude-sonnet-4";
+const SONNET45_ALLOWED_MARKERS = ["claude-sonnet-4-5", "claude-sonnet-4.5"];
+
+function normalizeModelId(modelId: string): string {
+	return modelId.trim().toLowerCase();
+}
+
+function hasAnyMarker(value: string, markers: readonly string[]): boolean {
+	for (const marker of markers) {
+		if (value.includes(marker)) return true;
+	}
+	return false;
+}
+
+function trimOrUndefined(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function isDeprecatedTeammateModelId(modelId: string): boolean {
+	const normalized = normalizeModelId(modelId);
+	if (!normalized) return false;
+	if (!normalized.includes(SONNET4_DEPRECATED_MARKER)) return false;
+	if (hasAnyMarker(normalized, SONNET45_ALLOWED_MARKERS)) return false;
+
+	const idx = normalized.indexOf(SONNET4_DEPRECATED_MARKER);
+	const next = normalized.at(idx + SONNET4_DEPRECATED_MARKER.length);
+	if (!next) return true;
+	return next === "-" || next === "_" || next === "." || next === ":";
+}
+
+export type TeammateModelSource = "override" | "inherit_leader" | "default";
+
+export interface ResolvedTeammateModel {
+	source: TeammateModelSource;
+	provider?: string;
+	modelId?: string;
+	warnings: string[];
+}
+
+export type ResolveTeammateModelResult =
+	| {
+			ok: true;
+			value: ResolvedTeammateModel;
+	  }
+	| {
+			ok: false;
+			error: string;
+			reason: "invalid_override" | "deprecated_override";
+	  };
+
+export function formatProviderModel(provider: string | undefined, modelId: string | undefined): string | null {
+	if (!modelId) return null;
+	return provider ? `${provider}/${modelId}` : modelId;
+}
+
+export function resolveTeammateModelSelection(input: {
+	modelOverride?: string;
+	leaderProvider?: string;
+	leaderModelId?: string;
+}): ResolveTeammateModelResult {
+	const override = trimOrUndefined(input.modelOverride);
+	if (override) {
+		const slashIdx = override.indexOf("/");
+		if (slashIdx >= 0) {
+			const provider = override.slice(0, slashIdx).trim();
+			const id = override.slice(slashIdx + 1).trim();
+			if (!provider || !id) {
+				return {
+					ok: false,
+					reason: "invalid_override",
+					error: `Invalid model override '${override}'. Expected <provider>/<modelId>.`,
+				};
+			}
+			if (isDeprecatedTeammateModelId(id)) {
+				return {
+					ok: false,
+					reason: "deprecated_override",
+					error: `Model override '${override}' is deprecated. Choose a current model id.`,
+				};
+			}
+			return {
+				ok: true,
+				value: {
+					source: "override",
+					provider,
+					modelId: id,
+					warnings: [],
+				},
+			};
+		}
+
+		if (isDeprecatedTeammateModelId(override)) {
+			return {
+				ok: false,
+				reason: "deprecated_override",
+				error: `Model override '${override}' is deprecated. Choose a current model id.`,
+			};
+		}
+
+		const leaderProvider = trimOrUndefined(input.leaderProvider);
+		const warnings: string[] = [];
+		if (!leaderProvider) {
+			warnings.push(
+				`Model override '${override}' provided without a provider. ` +
+					`Teammate will use its default provider; use <provider>/<modelId> to force one.`,
+			);
+		}
+		return {
+			ok: true,
+			value: {
+				source: "override",
+				provider: leaderProvider,
+				modelId: override,
+				warnings,
+			},
+		};
+	}
+
+	const leaderModelId = trimOrUndefined(input.leaderModelId);
+	const leaderProvider = trimOrUndefined(input.leaderProvider);
+	if (leaderModelId && !isDeprecatedTeammateModelId(leaderModelId)) {
+		return {
+			ok: true,
+			value: {
+				source: "inherit_leader",
+				provider: leaderProvider,
+				modelId: leaderModelId,
+				warnings: [],
+			},
+		};
+	}
+
+	return {
+		ok: true,
+		value: {
+			source: "default",
+			warnings: [],
+		},
+	};
+}

package/extensions/teams/names.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared name sanitization.
+ *
+ * Must be stable across leader/worker/mailbox so file paths and mailbox ids match.
+ */
+export function sanitizeName(name: string): string {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+
+/** Pool of person names for auto-generated comrades (soviet style). */
+export const COMRADE_NAME_POOL: readonly string[] = [
+	"ivan",
+	"natasha",
+	"boris",
+	"olga",
+	"dmitri",
+	"katya",
+	"sergei",
+	"anya",
+	"nikolai",
+	"mila",
+	"viktor",
+	"lena",
+	"pavel",
+	"zoya",
+	"alexei",
+	"daria",
+	"yuri",
+	"vera",
+	"andrei",
+	"sonya",
+	"maxim",
+	"nina",
+	"roman",
+	"tanya",
+	"leon",
+	"irina",
+	"oleg",
+	"nadia",
+	"artem",
+	"lydia",
+];
+
+/** Pool of pirate-ish names for auto-generated mateys (pirate style). */
+export const PIRATE_NAME_POOL: readonly string[] = [
+	"blackbeard",
+	"anne-bonny",
+	"calico-jack",
+	"mary-read",
+	"long-john",
+	"redbeard",
+	"silver",
+	"bones",
+	"hook",
+	"sparrow",
+	"gibbs",
+	"barbossa",
+	"rackham",
+	"flint",
+	"morgan",
+	"teach",
+];
+
+/**
+ * Pick `count` names from the pool that aren't already taken.
+ * Falls back to `<name>-2`, `<name>-3` etc. if pool is exhausted.
+ */
+export function pickNamesFromPool(opts: {
+	pool: readonly string[];
+	count: number;
+	taken: ReadonlySet<string>;
+	fallbackBase: string;
+}): string[] {
+	const { pool, count, taken, fallbackBase } = opts;
+	const available = pool.filter((n) => !taken.has(n));
+	const picked: string[] = [];
+
+	for (let i = 0; i < count; i++) {
+		const avail = available[i];
+		if (avail !== undefined) {
+			picked.push(avail);
+			continue;
+		}
+
+		// Exhaust pool: append suffix to cycle through names again
+		const base = pool.length > 0 ? (pool[i % pool.length] ?? fallbackBase) : fallbackBase;
+		let suffix = 2;
+		let candidate = `${base}-${suffix}`;
+		while (taken.has(candidate) || picked.includes(candidate)) {
+			suffix++;
+			candidate = `${base}-${suffix}`;
+		}
+		picked.push(candidate);
+	}
+
+	return picked;
+}
+
+export function pickComradeNames(count: number, taken: ReadonlySet<string>): string[] {
+	return pickNamesFromPool({ pool: COMRADE_NAME_POOL, count, taken, fallbackBase: "comrade" });
+}
+
+export function pickPirateNames(count: number, taken: ReadonlySet<string>): string[] {
+	return pickNamesFromPool({ pool: PIRATE_NAME_POOL, count, taken, fallbackBase: "matey" });
+}
+
+/**
+ * Deterministic default names for normal style.
+ * Produces agent1, agent2, ... skipping taken.
+ */
+export function pickAgentNames(count: number, taken: ReadonlySet<string>): string[] {
+	const picked: string[] = [];
+	let i = 1;
+	while (picked.length < count) {
+		const candidate = `agent${i}`;
+		i++;
+		if (taken.has(candidate) || picked.includes(candidate)) continue;
+		picked.push(candidate);
+	}
+	return picked;
+}

package/extensions/teams/paths.ts

@@ -0,0 +1,37 @@
+import * as path from "node:path";
+import { getAgentDir } from "indusagi-coding-agent";
+
+/**
+ * Root directory for all team artifacts (config, sessions, mailboxes, tasks).
+ *
+ * Default: `${getAgentDir()}/teams`
+ * Override: set `PI_TEAMS_ROOT_DIR` to an absolute path (recommended) or a path
+ * relative to the agent dir.
+ */
+export function getTeamsRootDir(): string {
+	const override = process.env.PI_TEAMS_ROOT_DIR;
+	if (override && override.trim()) {
+		const p = override.trim();
+		return path.isAbsolute(p) ? p : path.join(getAgentDir(), p);
+	}
+	return path.join(getAgentDir(), "teams");
+}
+
+export function getTeamDir(teamId: string): string {
+	return path.join(getTeamsRootDir(), teamId);
+}
+
+/** Directory for custom team UI styles (terminology + name rules). */
+export function getTeamsStylesDir(): string {
+	return path.join(getTeamsRootDir(), "_styles");
+}
+
+/** Directory for hook scripts and hook configuration (quality gates). */
+export function getTeamsHooksDir(): string {
+	const override = process.env.PI_TEAMS_HOOKS_DIR;
+	if (override && override.trim()) {
+		const p = override.trim();
+		return path.isAbsolute(p) ? p : path.join(getTeamsRootDir(), p);
+	}
+	return path.join(getTeamsRootDir(), "_hooks");
+}

package/extensions/teams/protocol.ts

@@ -0,0 +1,241 @@
+import type { TeamTask } from "./task-store.js";
+
+export const TEAM_MAILBOX_NS = "team";
+
+export function taskAssignmentPayload(task: TeamTask, assignedBy: string): {
+	type: "task_assignment";
+	taskId: string;
+	subject: string;
+	description: string;
+	assignedBy: string;
+	timestamp: string;
+} {
+	return {
+		type: "task_assignment",
+		taskId: task.id,
+		subject: task.subject,
+		description: task.description,
+		assignedBy,
+		timestamp: new Date().toISOString(),
+	};
+}
+
+function safeParseJson(text: string): unknown | null {
+	try {
+		const parsed: unknown = JSON.parse(text);
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
+function getString(obj: Record<string, unknown>, key: string): string | undefined {
+	const v = obj[key];
+	return typeof v === "string" ? v : undefined;
+}
+
+// Leader-side inbox messages
+
+export function isIdleNotification(
+	text: string,
+): {
+	from: string;
+	timestamp?: string;
+	completedTaskId?: string;
+	completedStatus?: string;
+	failureReason?: string;
+} | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "idle_notification") return null;
+	return {
+		from: getString(obj, "from") ?? "unknown",
+		timestamp: getString(obj, "timestamp"),
+		completedTaskId: getString(obj, "completedTaskId"),
+		completedStatus: getString(obj, "completedStatus"),
+		failureReason: getString(obj, "failureReason"),
+	};
+}
+
+export function isShutdownApproved(
+	text: string,
+): {
+	from: string;
+	requestId: string;
+	timestamp?: string;
+} | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "shutdown_approved") return null;
+	const requestId = getString(obj, "requestId");
+	if (!requestId) return null;
+	return {
+		from: getString(obj, "from") ?? "unknown",
+		requestId,
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+export function isShutdownRejected(
+	text: string,
+): {
+	from: string;
+	requestId: string;
+	reason: string;
+	timestamp?: string;
+} | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "shutdown_rejected") return null;
+	const requestId = getString(obj, "requestId");
+	if (!requestId) return null;
+	return {
+		from: getString(obj, "from") ?? "unknown",
+		requestId,
+		reason: getString(obj, "reason") ?? "",
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+export function isPlanApprovalRequest(
+	text: string,
+): {
+	requestId: string;
+	from: string;
+	plan: string;
+	taskId?: string;
+	timestamp?: string;
+} | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "plan_approval_request") return null;
+	const requestId = getString(obj, "requestId");
+	const from = getString(obj, "from");
+	const plan = getString(obj, "plan");
+	if (!requestId || !from || !plan) return null;
+	return {
+		requestId,
+		from,
+		plan,
+		taskId: getString(obj, "taskId"),
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+export function isPeerDmSent(
+	text: string,
+): {
+	from: string;
+	to: string;
+	summary: string;
+	timestamp?: string;
+} | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "peer_dm_sent") return null;
+	const from = getString(obj, "from");
+	const to = getString(obj, "to");
+	const summary = getString(obj, "summary");
+	if (!from || !to || !summary) return null;
+	return {
+		from,
+		to,
+		summary,
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+// Worker-side inbox messages
+
+export function isTaskAssignmentMessage(
+	text: string,
+): { taskId: string; subject?: string; description?: string; assignedBy?: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "task_assignment") return null;
+	const taskId = getString(obj, "taskId");
+	if (!taskId) return null;
+	return {
+		taskId,
+		subject: getString(obj, "subject"),
+		description: getString(obj, "description"),
+		assignedBy: getString(obj, "assignedBy"),
+	};
+}
+
+export function isShutdownRequestMessage(
+	text: string,
+): { requestId: string; from?: string; reason?: string; timestamp?: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "shutdown_request") return null;
+	const requestId = getString(obj, "requestId");
+	if (!requestId) return null;
+	return {
+		requestId,
+		from: getString(obj, "from"),
+		reason: getString(obj, "reason"),
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+export function isSetSessionNameMessage(text: string): { name: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "set_session_name") return null;
+	const name = getString(obj, "name");
+	if (!name) return null;
+	return { name };
+}
+
+export function isAbortRequestMessage(
+	text: string,
+): { requestId: string; from?: string; taskId?: string; reason?: string; timestamp?: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "abort_request") return null;
+	const requestId = getString(obj, "requestId");
+	if (!requestId) return null;
+	return {
+		requestId,
+		from: getString(obj, "from"),
+		taskId: getString(obj, "taskId"),
+		reason: getString(obj, "reason"),
+		timestamp: getString(obj, "timestamp"),
+	};
+}
+
+export function isPlanApprovedMessage(text: string): { requestId: string; from: string; timestamp: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "plan_approved") return null;
+	const requestId = getString(obj, "requestId");
+	const from = getString(obj, "from");
+	if (!requestId || !from) return null;
+	return {
+		requestId,
+		from,
+		timestamp: getString(obj, "timestamp") ?? "",
+	};
+}
+
+export function isPlanRejectedMessage(
+	text: string,
+): { requestId: string; from: string; feedback: string; timestamp: string } | null {
+	const obj = safeParseJson(text);
+	if (!isRecord(obj)) return null;
+	if (getString(obj, "type") !== "plan_rejected") return null;
+	const requestId = getString(obj, "requestId");
+	const from = getString(obj, "from");
+	if (!requestId || !from) return null;
+	return {
+		requestId,
+		from,
+		feedback: getString(obj, "feedback") ?? "",
+		timestamp: getString(obj, "timestamp") ?? "",
+	};
+}

package/extensions/teams/spawn-types.ts

@@ -0,0 +1,36 @@
+import type { ThinkingLevel } from "indusagi/agent";
+import type { ExtensionContext } from "indusagi-coding-agent";
+
+export type ContextMode = "fresh" | "branch";
+export type WorkspaceMode = "shared" | "worktree";
+
+export interface SpawnTeammateOptions {
+	name: string;
+	mode?: ContextMode;
+	workspaceMode?: WorkspaceMode;
+	planRequired?: boolean;
+	/**
+	 * Optional model override for the spawned teammate.
+	 *
+	 * Supported forms:
+	 * - "<provider>/<modelId>"  (e.g. "openai-codex/gpt-5.1-codex-mini")
+	 * - "<modelId>"             (provider inherited from leader when available)
+	 */
+	model?: string;
+	/** Optional thinking level override for the spawned teammate. */
+	thinking?: ThinkingLevel;
+}
+
+export type SpawnTeammateResult =
+	| {
+			ok: true;
+			name: string;
+			mode: ContextMode;
+			workspaceMode: WorkspaceMode;
+			childCwd?: string;
+			note?: string;
+			warnings: string[];
+	  }
+	| { ok: false; error: string };
+
+export type SpawnTeammateFn = (ctx: ExtensionContext, opts: SpawnTeammateOptions) => Promise<SpawnTeammateResult>;