type SkillsChangeEvent,

} from "./refresh-state.js";

type SkillsWatchState = {

type SkillsPathWatchState = {

watcher: FSWatcher;

pathsKey: string;

debounceMs: number;

timer?: ReturnType<typeof setTimeout>;

pendingPath?: string;

readonly subscribers: Set<string>;

};

const log = createSubsystemLogger("gateway/skills");

const watchers = new Map<string, SkillsWatchState>();

// One watcher per unique watched directory. Agent workspaces that include the

// same shared skill root (the global skills dir, the home skills dir, or a

// configured extra/plugin dir) subscribe to the same watcher instead of each

// opening its own, so open file descriptors scale with distinct directories

// rather than with agent count.

const pathWatchers = new Map<string, SkillsPathWatchState>();

// Watch targets each workspace is currently subscribed to, used to reconcile

// subscriptions and to detect watch-target changes across calls.

const workspaceWatchTargets = new Map<string, string[]>();

setSkillsChangeListenerErrorHandler((err) => {

log.warn(`skills change listener failed: ${String(err)}`);

return path.posix.basename(normalized) !== "SKILL.md";

}

export function ensureSkillsWatcher(params: { workspaceDir: string; config?: OpenClawConfig }) {

const workspaceDir = params.workspaceDir.trim();

if (!workspaceDir) {

return;

}

const watchEnabled = params.config?.skills?.load?.watch !== false;

const debounceMsRaw = params.config?.skills?.load?.watchDebounceMs;

const debounceMs =

typeof debounceMsRaw === "number" && Number.isFinite(debounceMsRaw)

? Math.max(0, debounceMsRaw)

: 250;

const existing = watchers.get(workspaceDir);

if (!watchEnabled) {

if (existing) {

watchers.delete(workspaceDir);

if (existing.timer) {

clearTimeout(existing.timer);

}

void existing.watcher.close().catch(() => {});

}

return;

}

function resolveWatchDebounceMs(config?: OpenClawConfig): number {

const raw = config?.skills?.load?.watchDebounceMs;

return typeof raw === "number" && Number.isFinite(raw) ? Math.max(0, raw) : 250;

}

const watchTargets = resolveWatchTargets(workspaceDir, params.config);

const pathsKey = watchTargets.join("|");

if (existing && existing.pathsKey === pathsKey && existing.debounceMs === debounceMs) {

return;

function sameWatchTargets(a: string[], b: string[]): boolean {

if (a.length !== b.length) {

return false;

}

const watchTargetsChanged = existing ? existing.pathsKey !== pathsKey : false;

if (existing) {

watchers.delete(workspaceDir);

if (existing.timer) {

clearTimeout(existing.timer);

for (let index = 0; index < a.length; index++) {

if (a[index] !== b[index]) {

return false;

}

void existing.watcher.close().catch(() => {});

}

return true;

}

const watcher = chokidar.watch(watchTargets, {

function createSkillsPathWatcher(watchPath: string, debounceMs: number): SkillsPathWatchState {

const watcher = chokidar.watch(watchPath, {

ignoreInitial: true,

// Skill discovery reads root skills, direct child skills, and one grouped skill level.

depth: 2,

ignored: shouldIgnoreSkillsWatchPath,

});

const state: SkillsWatchState = { watcher, pathsKey, debounceMs };

const state: SkillsPathWatchState = { watcher, debounceMs, subscribers: new Set<string>() };

const schedule = (changedPath?: string) => {

state.pendingPath = changedPath ?? state.pendingPath;

const pendingPath = state.pendingPath;

state.pendingPath = undefined;

state.timer = undefined;

bumpSkillsSnapshotVersion({

workspaceDir,

reason: "watch",

changedPath: pendingPath,

});

// Fan the change out to every workspace subscribed to this directory so a

// shared skill root refreshes the snapshot for all agents that use it.

for (const workspaceDir of state.subscribers) {

bumpSkillsSnapshotVersion({

workspaceDir,

reason: "watch",

changedPath: pendingPath,

});

}

}, debounceMs);

};

watcher.on("unlink", (p) => schedule(p));

watcher.on("unlinkDir", (p) => schedule(p));

watcher.on("error", (err) => {

log.warn(`skills watcher error (${workspaceDir}): ${String(err)}`);

log.warn(`skills watcher error (${watchPath}): ${String(err)}`);

});

watchers.set(workspaceDir, state);

return state;

}

function teardownSkillsPathWatcher(state: SkillsPathWatchState): void {

if (state.timer) {

clearTimeout(state.timer);

}

void state.watcher.close().catch(() => {});

}

function subscribeWorkspaceToPath(

workspaceDir: string,

watchPath: string,

debounceMs: number,

): void {

const existing = pathWatchers.get(watchPath);

if (existing && existing.debounceMs === debounceMs) {

existing.subscribers.add(workspaceDir);

return;

}

if (existing) {

// Debounce changed (config reload): rebuild the shared watcher while

// preserving existing subscribers.

const next = createSkillsPathWatcher(watchPath, debounceMs);

for (const subscriber of existing.subscribers) {

next.subscribers.add(subscriber);

}

next.subscribers.add(workspaceDir);

teardownSkillsPathWatcher(existing);

pathWatchers.set(watchPath, next);

return;

}

const state = createSkillsPathWatcher(watchPath, debounceMs);

state.subscribers.add(workspaceDir);

pathWatchers.set(watchPath, state);

}

function unsubscribeWorkspaceFromPath(workspaceDir: string, watchPath: string): void {

const state = pathWatchers.get(watchPath);

if (!state) {

return;

}

state.subscribers.delete(workspaceDir);

if (state.subscribers.size === 0) {

teardownSkillsPathWatcher(state);

pathWatchers.delete(watchPath);

}

}

export function ensureSkillsWatcher(params: { workspaceDir: string; config?: OpenClawConfig }) {

const workspaceDir = params.workspaceDir.trim();

if (!workspaceDir) {

return;

}

const watchEnabled = params.config?.skills?.load?.watch !== false;

const debounceMs = resolveWatchDebounceMs(params.config);

const previousTargets = workspaceWatchTargets.get(workspaceDir) ?? [];

if (!watchEnabled) {

if (previousTargets.length > 0) {

for (const watchPath of previousTargets) {

unsubscribeWorkspaceFromPath(workspaceDir, watchPath);

}

workspaceWatchTargets.delete(workspaceDir);

}

return;

}

const watchTargets = resolveWatchTargets(workspaceDir, params.config);

const targetsUnchanged = sameWatchTargets(previousTargets, watchTargets);

const debounceUnchanged = watchTargets.every(

(watchPath) => pathWatchers.get(watchPath)?.debounceMs === debounceMs,

);

if (targetsUnchanged && debounceUnchanged) {

return;

}

const watchTargetsChanged = previousTargets.length > 0 && !targetsUnchanged;

const nextTargets = new Set(watchTargets);

for (const watchPath of previousTargets) {

if (!nextTargets.has(watchPath)) {

unsubscribeWorkspaceFromPath(workspaceDir, watchPath);

}

}

for (const watchPath of watchTargets) {

subscribeWorkspaceToPath(workspaceDir, watchPath, debounceMs);

}

workspaceWatchTargets.set(workspaceDir, watchTargets);

if (watchTargetsChanged) {

bumpSkillsSnapshotVersion({

workspaceDir,

reason: "watch-targets",

changedPath: pathsKey,

changedPath: watchTargets.join("|"),

});

}

}

export async function resetSkillsRefreshForTest(): Promise<void> {

resetSkillsRefreshStateForTest();

const active = Array.from(watchers.values());

watchers.clear();

const active = Array.from(pathWatchers.values());

pathWatchers.clear();

workspaceWatchTargets.clear();

await Promise.all(

active.map(async (state) => {

if (state.timer) {