indus-swarms 0.1.0

package/extensions/teams/activity-tracker.ts

@@ -0,0 +1,234 @@
+import type { AgentEvent } from "indusagi/agent";
+
+// ── Transcript types ──
+
+export type TranscriptEntry =
+	| { kind: "text"; text: string; timestamp: number }
+	| { kind: "tool_start"; toolName: string; timestamp: number }
+	| { kind: "tool_end"; toolName: string; durationMs: number; timestamp: number }
+	| { kind: "turn_end"; turnNumber: number; tokens: number; timestamp: number };
+
+const MAX_TRANSCRIPT = 200;
+
+export class TranscriptLog {
+	private entries: TranscriptEntry[] = [];
+
+	push(entry: TranscriptEntry): void {
+		this.entries.push(entry);
+		if (this.entries.length > MAX_TRANSCRIPT) {
+			this.entries.splice(0, this.entries.length - MAX_TRANSCRIPT);
+		}
+	}
+
+	getEntries(): readonly TranscriptEntry[] {
+		return this.entries;
+	}
+
+	get length(): number {
+		return this.entries.length;
+	}
+
+	reset(): void {
+		this.entries = [];
+	}
+}
+
+export class TranscriptTracker {
+	private logs = new Map<string, TranscriptLog>();
+	private toolStarts = new Map<string, Map<string, number>>(); // name -> toolCallId -> startTimestamp
+	private pendingText = new Map<string, string>(); // name -> accumulated text
+	private turnCounts = new Map<string, number>();
+	private lastTokens = new Map<string, number>(); // name -> tokens from last message_end
+
+	handleEvent(name: string, ev: AgentEvent): void {
+		const log = this.getOrCreate(name);
+		const now = Date.now();
+
+		if (ev.type === "message_update") {
+			const ame = ev.assistantMessageEvent;
+			if (ame.type === "text_delta") {
+				const cur = this.pendingText.get(name) ?? "";
+				this.pendingText.set(name, cur + ame.delta);
+				// Flush complete lines
+				this.flushText(name, log, now, false);
+			}
+			return;
+		}
+
+		if (ev.type === "tool_execution_start") {
+			// Flush any pending text before a tool starts
+			this.flushText(name, log, now, true);
+			const starts = this.toolStarts.get(name) ?? new Map<string, number>();
+			starts.set(ev.toolCallId, now);
+			this.toolStarts.set(name, starts);
+			log.push({ kind: "tool_start", toolName: ev.toolName, timestamp: now });
+			return;
+		}
+
+		if (ev.type === "tool_execution_end") {
+			const starts = this.toolStarts.get(name);
+			const startTs = starts?.get(ev.toolCallId);
+			const durationMs = startTs === undefined ? 0 : now - startTs;
+			starts?.delete(ev.toolCallId);
+			log.push({ kind: "tool_end", toolName: ev.toolName, durationMs, timestamp: now });
+			return;
+		}
+
+		if (ev.type === "message_end") {
+			// Capture tokens for use in the turn_end entry
+			const msg: unknown = ev.message;
+			if (isRecord(msg)) {
+				const usage = msg.usage;
+				if (isRecord(usage) && typeof usage.totalTokens === "number") {
+					this.lastTokens.set(name, (this.lastTokens.get(name) ?? 0) + usage.totalTokens);
+				}
+			}
+			return;
+		}
+
+		if (ev.type === "agent_end") {
+			// Flush remaining text
+			this.flushText(name, log, now, true);
+			const turn = (this.turnCounts.get(name) ?? 0) + 1;
+			this.turnCounts.set(name, turn);
+			const tokens = this.lastTokens.get(name) ?? 0;
+			log.push({ kind: "turn_end", turnNumber: turn, tokens, timestamp: now });
+			this.lastTokens.set(name, 0);
+			return;
+		}
+	}
+
+	get(name: string): TranscriptLog {
+		return this.logs.get(name) ?? new TranscriptLog();
+	}
+
+	reset(name: string): void {
+		this.logs.delete(name);
+		this.toolStarts.delete(name);
+		this.pendingText.delete(name);
+		this.turnCounts.delete(name);
+		this.lastTokens.delete(name);
+	}
+
+	private getOrCreate(name: string): TranscriptLog {
+		const existing = this.logs.get(name);
+		if (existing) return existing;
+		const created = new TranscriptLog();
+		this.logs.set(name, created);
+		return created;
+	}
+
+	private flushText(name: string, log: TranscriptLog, timestamp: number, force: boolean): void {
+		const buf = this.pendingText.get(name);
+		if (!buf) return;
+
+		// Split into lines; keep the last incomplete line unless forced
+		const parts = buf.split("\n");
+		if (force) {
+			// Flush everything
+			for (const part of parts) {
+				const trimmed = part.trimEnd();
+				if (trimmed) log.push({ kind: "text", text: trimmed, timestamp });
+			}
+			this.pendingText.delete(name);
+		} else if (parts.length > 1) {
+			// Flush all complete lines, keep the last (potentially incomplete) part
+			for (let i = 0; i < parts.length - 1; i++) {
+				const part = parts[i];
+				if (part === undefined) continue;
+				const trimmed = part.trimEnd();
+				if (trimmed) log.push({ kind: "text", text: trimmed, timestamp });
+			}
+			this.pendingText.set(name, parts[parts.length - 1] ?? "");
+		}
+	}
+}
+
+// ── Activity types ──
+
+type TrackedEventType = "tool_execution_start" | "tool_execution_end" | "agent_end" | "message_end";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null;
+}
+
+export interface TeammateActivity {
+	toolUseCount: number;
+	currentToolName: string | null;
+	lastToolName: string | null;
+	turnCount: number;
+	totalTokens: number;
+	recentEvents: Array<{ type: TrackedEventType; toolName?: string; timestamp: number }>;
+}
+
+const MAX_RECENT = 10;
+
+function emptyActivity(): TeammateActivity {
+	return {
+		toolUseCount: 0,
+		currentToolName: null,
+		lastToolName: null,
+		turnCount: 0,
+		totalTokens: 0,
+		recentEvents: [],
+	};
+}
+
+export class ActivityTracker {
+	private data = new Map<string, TeammateActivity>();
+
+	handleEvent(name: string, ev: AgentEvent): void {
+		const a = this.getOrCreate(name);
+		const now = Date.now();
+
+		if (ev.type === "tool_execution_start") {
+			a.currentToolName = ev.toolName;
+			a.recentEvents.push({ type: ev.type, toolName: ev.toolName, timestamp: now });
+			if (a.recentEvents.length > MAX_RECENT) a.recentEvents.shift();
+			return;
+		}
+
+		if (ev.type === "tool_execution_end") {
+			const toolName = a.currentToolName ?? ev.toolName;
+			a.toolUseCount++;
+			a.lastToolName = toolName;
+			a.currentToolName = null;
+			a.recentEvents.push({ type: ev.type, toolName, timestamp: now });
+			if (a.recentEvents.length > MAX_RECENT) a.recentEvents.shift();
+			return;
+		}
+
+		if (ev.type === "agent_end") {
+			a.turnCount++;
+			a.recentEvents.push({ type: ev.type, timestamp: now });
+			if (a.recentEvents.length > MAX_RECENT) a.recentEvents.shift();
+			return;
+		}
+
+		if (ev.type === "message_end") {
+			const msg: unknown = ev.message;
+			if (!isRecord(msg)) return;
+			const usage = msg.usage;
+			if (!isRecord(usage)) return;
+			const totalTokens = usage.totalTokens;
+			if (typeof totalTokens === "number") a.totalTokens += totalTokens;
+		}
+	}
+
+	get(name: string): TeammateActivity {
+		return this.data.get(name) ?? emptyActivity();
+	}
+
+	reset(name: string): void {
+		this.data.delete(name);
+	}
+
+	private getOrCreate(name: string): TeammateActivity {
+		const existing = this.data.get(name);
+		if (existing) return existing;
+
+		const created = emptyActivity();
+		this.data.set(name, created);
+		return created;
+	}
+}

package/extensions/teams/cleanup.ts

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function assertTeamDirWithinTeamsRoot(teamsRootDir: string, teamDir: string): {
+	teamsRootAbs: string;
+	teamDirAbs: string;
+} {
+	const teamsRootAbs = path.resolve(teamsRootDir);
+	const teamDirAbs = path.resolve(teamDir);
+
+	const rel = path.relative(teamsRootAbs, teamDirAbs);
+	// rel === "" => same path (would delete the whole root)
+	// rel starts with ".." or is absolute => outside root
+	if (!rel || rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+		throw new Error(
+			`Refusing to operate on path outside teams root. teamsRootDir=${teamsRootAbs} teamDir=${teamDirAbs}`,
+		);
+	}
+
+	return { teamsRootAbs, teamDirAbs };
+}
+
+/**
+ * Recursively delete the given teamDir, but only if it's safely inside teamsRootDir.
+ *
+ * Uses fs.rm({ recursive: true, force: true }) so it's idempotent.
+ */
+export async function cleanupTeamDir(teamsRootDir: string, teamDir: string): Promise<void> {
+	const { teamDirAbs } = assertTeamDirWithinTeamsRoot(teamsRootDir, teamDir);
+	await fs.promises.rm(teamDirAbs, { recursive: true, force: true });
+}

package/extensions/teams/fs-lock.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((r) => setTimeout(r, ms));
+}
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+	return typeof err === "object" && err !== null && "code" in err;
+}
+
+export interface LockOptions {
+	/** How long to wait to acquire the lock before failing. */
+	timeoutMs?: number;
+	/** If lock file is older than this, consider it stale and remove it. */
+	staleMs?: number;
+	/** Poll interval while waiting for lock. */
+	pollMs?: number;
+	/** Optional label to help debugging (written into lock file). */
+	label?: string;
+}
+
+export async function withLock<T>(lockFilePath: string, fn: () => Promise<T>, opts: LockOptions = {}): Promise<T> {
+	const timeoutMs = opts.timeoutMs ?? 10_000;
+	const staleMs = opts.staleMs ?? 60_000;
+	const basePollMs = opts.pollMs ?? 50;
+	const maxPollMs = Math.max(basePollMs, 1_000);
+	const start = Date.now();
+
+	let fd: number | null = null;
+	let attempt = 0;
+
+	while (fd === null) {
+		try {
+			fd = fs.openSync(lockFilePath, "wx");
+			const payload = {
+				pid: process.pid,
+				createdAt: new Date().toISOString(),
+				label: opts.label,
+			};
+			fs.writeFileSync(fd, JSON.stringify(payload));
+		} catch (err: unknown) {
+			if (!isErrnoException(err) || err.code !== "EEXIST") throw err;
+
+			// Stale lock handling
+			try {
+				const st = fs.statSync(lockFilePath);
+				const age = Date.now() - st.mtimeMs;
+				if (age > staleMs) {
+					fs.unlinkSync(lockFilePath);
+					attempt = 0;
+					continue;
+				}
+			} catch {
+				// ignore: stat/unlink failures fall through to wait
+			}
+
+			const elapsedMs = Date.now() - start;
+			if (elapsedMs > timeoutMs) {
+				throw new Error(`Timeout acquiring lock: ${lockFilePath}`);
+			}
+
+			attempt += 1;
+			const expBackoff = Math.min(maxPollMs, basePollMs * 2 ** Math.min(attempt, 6));
+			const jitterFactor = 0.5 + Math.random(); // [0.5, 1.5)
+			const jitteredBackoff = Math.min(maxPollMs, Math.round(expBackoff * jitterFactor));
+
+			const remainingMs = timeoutMs - elapsedMs;
+			const sleepMs = Math.max(1, Math.min(remainingMs, jitteredBackoff));
+			await sleep(sleepMs);
+		}
+	}
+
+	try {
+		return await fn();
+	} finally {
+		try {
+			if (fd !== null) fs.closeSync(fd);
+		} catch {
+			// ignore
+		}
+		try {
+			fs.unlinkSync(lockFilePath);
+		} catch {
+			// ignore
+		}
+	}
+}

package/extensions/teams/hooks.ts

@@ -0,0 +1,363 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { getTeamsHooksDir } from "./paths.js";
+import type { TeamTask } from "./task-store.js";
+
+export type TeamsHookEvent = "idle" | "task_completed" | "task_failed";
+
+export type TeamsHookInvocation = {
+	event: TeamsHookEvent;
+	teamId: string;
+	teamDir: string;
+	taskListId: string;
+	style: string;
+	memberName?: string;
+	timestamp?: string;
+	completedTask?: TeamTask | null;
+};
+
+export type TeamsHookRunResult = {
+	ran: boolean;
+	hookPath?: string;
+	command?: readonly string[];
+	exitCode: number | null;
+	timedOut: boolean;
+	durationMs: number;
+	stdout: string;
+	stderr: string;
+	error?: string;
+};
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+	return typeof err === "object" && err !== null && "code" in err;
+}
+
+function isExecutable(st: fs.Stats): boolean {
+	// Owner/group/other execute bit.
+	return (st.mode & 0o111) !== 0;
+}
+
+function trimOutput(s: string, limit = 12_000): string {
+	if (s.length <= limit) return s;
+	return s.slice(0, limit) + `\n… (truncated, ${s.length - limit} bytes omitted)`;
+}
+
+function parseTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env.PI_TEAMS_HOOK_TIMEOUT_MS;
+	if (!raw) return 60_000;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : 60_000;
+}
+
+export function areTeamsHooksEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env.PI_TEAMS_HOOKS_ENABLED === "1";
+}
+
+export type TeamsHookFailureAction = "warn" | "followup" | "reopen" | "reopen_followup";
+export type TeamsHookFollowupOwnerPolicy = "member" | "lead" | "none";
+
+export function isTeamsHookFailureAction(value: string): value is TeamsHookFailureAction {
+	return value === "warn" || value === "followup" || value === "reopen" || value === "reopen_followup";
+}
+
+export function getTeamsHookFailureAction(
+	env: NodeJS.ProcessEnv = process.env,
+	override?: string,
+): TeamsHookFailureAction {
+	const explicit = override?.trim().toLowerCase();
+	if (explicit && isTeamsHookFailureAction(explicit)) return explicit;
+	const raw = env.PI_TEAMS_HOOKS_FAILURE_ACTION?.trim().toLowerCase();
+	if (raw && isTeamsHookFailureAction(raw)) return raw;
+	if (env.PI_TEAMS_HOOKS_CREATE_TASK_ON_FAILURE === "1") return "followup";
+	return "warn";
+}
+
+export function shouldCreateHookFollowupTask(action: TeamsHookFailureAction): boolean {
+	return action === "followup" || action === "reopen_followup";
+}
+
+export function shouldReopenTaskOnHookFailure(action: TeamsHookFailureAction): boolean {
+	return action === "reopen" || action === "reopen_followup";
+}
+
+export function isTeamsHookFollowupOwnerPolicy(value: string): value is TeamsHookFollowupOwnerPolicy {
+	return value === "member" || value === "lead" || value === "none";
+}
+
+export function getTeamsHookFollowupOwnerPolicy(
+	env: NodeJS.ProcessEnv = process.env,
+	override?: string,
+): TeamsHookFollowupOwnerPolicy {
+	const explicit = override?.trim().toLowerCase();
+	if (explicit && isTeamsHookFollowupOwnerPolicy(explicit)) return explicit;
+	const raw = env.PI_TEAMS_HOOKS_FOLLOWUP_OWNER?.trim().toLowerCase();
+	if (raw && isTeamsHookFollowupOwnerPolicy(raw)) return raw;
+	return "member";
+}
+
+export function resolveTeamsHookFollowupOwner(opts: {
+	policy: TeamsHookFollowupOwnerPolicy;
+	memberName?: string;
+	leadName?: string;
+}): string | undefined {
+	if (opts.policy === "none") return undefined;
+	if (opts.policy === "lead") {
+		const lead = opts.leadName?.trim();
+		return lead ? lead : undefined;
+	}
+	const member = opts.memberName?.trim();
+	if (member) return member;
+	const lead = opts.leadName?.trim();
+	return lead ? lead : undefined;
+}
+
+export function getTeamsHookMaxReopensPerTask(env: NodeJS.ProcessEnv = process.env, override?: number): number {
+	if (typeof override === "number" && Number.isFinite(override) && override >= 0) return Math.floor(override);
+	const raw = env.PI_TEAMS_HOOKS_MAX_REOPENS_PER_TASK?.trim();
+	if (!raw) return 3;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return 3;
+	return parsed;
+}
+
+function truncateField(value: string, max: number): string {
+	if (value.length <= max) return value;
+	return `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+
+function getHookContextJson(invocation: TeamsHookInvocation): string {
+	const task = invocation.completedTask;
+	const payload = {
+		version: 1,
+		event: invocation.event,
+		team: {
+			id: invocation.teamId,
+			dir: invocation.teamDir,
+			taskListId: invocation.taskListId,
+			style: invocation.style,
+		},
+		member: invocation.memberName ?? null,
+		timestamp: invocation.timestamp ?? null,
+		task: task
+			? {
+				id: task.id,
+				subject: truncateField(task.subject, 1_000),
+				description: truncateField(task.description, 8_000),
+				owner: task.owner ?? null,
+				status: task.status,
+				blockedBy: task.blockedBy.slice(0, 200),
+				blocks: task.blocks.slice(0, 200),
+				metadata: task.metadata ?? {},
+				createdAt: task.createdAt,
+				updatedAt: task.updatedAt,
+			}
+			: null,
+	};
+	return JSON.stringify(payload);
+}
+
+export function getHookBaseName(event: TeamsHookEvent): string {
+	switch (event) {
+		case "idle":
+			return "on_idle";
+		case "task_completed":
+			return "on_task_completed";
+		case "task_failed":
+			return "on_task_failed";
+	}
+}
+
+type HookCommand = { cmd: string; args: string[]; hookPath: string; display: readonly string[] };
+
+function resolveHookCommand(hooksDir: string, event: TeamsHookEvent): HookCommand | null {
+	const base = getHookBaseName(event);
+	const candidates = [
+		path.join(hooksDir, base),
+		path.join(hooksDir, `${base}.sh`),
+		path.join(hooksDir, `${base}.js`),
+		path.join(hooksDir, `${base}.mjs`),
+	];
+
+	for (const file of candidates) {
+		try {
+			if (!fs.existsSync(file)) continue;
+			const st = fs.statSync(file);
+			if (!st.isFile()) continue;
+
+			const ext = path.extname(file).toLowerCase();
+			if (ext === ".js" || ext === ".mjs") {
+				return { cmd: "node", args: [file], hookPath: file, display: ["node", file] };
+			}
+
+			if (ext === ".sh") {
+				return { cmd: "bash", args: [file], hookPath: file, display: ["bash", file] };
+			}
+
+			if (isExecutable(st)) {
+				return { cmd: file, args: [], hookPath: file, display: [file] };
+			}
+
+			// Non-executable with unknown extension: ignore.
+		} catch {
+			// ignore
+		}
+	}
+
+	return null;
+}
+
+async function runWithTimeout(opts: {
+	cmd: string;
+	args: readonly string[];
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	timeoutMs: number;
+}): Promise<{ exitCode: number | null; timedOut: boolean; stdout: string; stderr: string; error?: string }> {
+	return await new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+
+		const child = spawn(opts.cmd, [...opts.args], {
+			cwd: opts.cwd,
+			env: opts.env,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		child.stdout?.on("data", (d: Buffer) => {
+			stdout += d.toString("utf8");
+		});
+		child.stderr?.on("data", (d: Buffer) => {
+			stderr += d.toString("utf8");
+		});
+
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				// ignore
+			}
+			setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// ignore
+				}
+			}, 1000);
+		}, opts.timeoutMs);
+
+		child.on("close", (code) => {
+			clearTimeout(timeout);
+			resolve({
+				exitCode: code,
+				timedOut,
+				stdout: trimOutput(stdout),
+				stderr: trimOutput(stderr),
+			});
+		});
+
+		child.on("error", (err: unknown) => {
+			clearTimeout(timeout);
+			const msg = err instanceof Error ? err.message : String(err);
+			resolve({ exitCode: null, timedOut: false, stdout: trimOutput(stdout), stderr: trimOutput(stderr), error: msg });
+		});
+	});
+}
+
+export async function runTeamsHook(opts: {
+	invocation: TeamsHookInvocation;
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<TeamsHookRunResult> {
+	const env = opts.env ?? process.env;
+	if (!areTeamsHooksEnabled(env)) {
+		return {
+			ran: false,
+			exitCode: null,
+			timedOut: false,
+			durationMs: 0,
+			stdout: "",
+			stderr: "",
+		};
+	}
+
+	const hooksDir = getTeamsHooksDir();
+	const hook = resolveHookCommand(hooksDir, opts.invocation.event);
+	if (!hook) {
+		return {
+			ran: false,
+			exitCode: null,
+			timedOut: false,
+			durationMs: 0,
+			stdout: "",
+			stderr: "",
+		};
+	}
+
+	const timeoutMs = parseTimeoutMs(env);
+	const start = Date.now();
+
+	const baseEnv: NodeJS.ProcessEnv = {
+		...env,
+		PI_TEAMS_HOOK_EVENT: opts.invocation.event,
+		PI_TEAMS_HOOK_CONTEXT_VERSION: "1",
+		PI_TEAMS_HOOK_CONTEXT_JSON: getHookContextJson(opts.invocation),
+		PI_TEAMS_TEAM_ID: opts.invocation.teamId,
+		PI_TEAMS_TEAM_DIR: opts.invocation.teamDir,
+		PI_TEAMS_TASK_LIST_ID: opts.invocation.taskListId,
+		PI_TEAMS_STYLE: opts.invocation.style,
+		...(opts.invocation.memberName ? { PI_TEAMS_MEMBER: opts.invocation.memberName } : {}),
+		...(opts.invocation.timestamp ? { PI_TEAMS_EVENT_TIMESTAMP: opts.invocation.timestamp } : {}),
+	};
+
+	const t = opts.invocation.completedTask;
+	const envWithTask: NodeJS.ProcessEnv = {
+		...baseEnv,
+		...(t?.id ? { PI_TEAMS_TASK_ID: t.id } : {}),
+		...(t?.subject ? { PI_TEAMS_TASK_SUBJECT: t.subject } : {}),
+		...(t?.owner ? { PI_TEAMS_TASK_OWNER: t.owner } : {}),
+		...(t?.status ? { PI_TEAMS_TASK_STATUS: t.status } : {}),
+	};
+
+	let res;
+	try {
+		res = await runWithTimeout({ cmd: hook.cmd, args: hook.args, cwd: opts.cwd, env: envWithTask, timeoutMs });
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			ran: true,
+			hookPath: hook.hookPath,
+			command: hook.display,
+			exitCode: null,
+			timedOut: false,
+			durationMs: Date.now() - start,
+			stdout: "",
+			stderr: "",
+			error: msg,
+		};
+	}
+
+	return {
+		ran: true,
+		hookPath: hook.hookPath,
+		command: hook.display,
+		exitCode: res.exitCode,
+		timedOut: res.timedOut,
+		durationMs: Date.now() - start,
+		stdout: res.stdout,
+		stderr: res.stderr,
+		error: res.error,
+	};
+}
+
+export async function ensureHooksDirExists(): Promise<void> {
+	const dir = getTeamsHooksDir();
+	try {
+		await fs.promises.mkdir(dir, { recursive: true });
+	} catch (err) {
+		// ignore permission errors; caller can surface if needed
+		if (isErrnoException(err) && err.code === "EACCES") return;
+	}
+}