@cortexkit/aft-bridge 0.58.0 → 0.58.1

package/dist/config-watch.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Live reload of AFT config file edits in a host plugin.
+ *
+ * The plugin keeps its own copy of the resolved config (`ctx.config`) for the
+ * keys it enforces or uses itself, such as the path restriction pre-check and
+ * the bash wait limits. The engine applies its own keys from the same files
+ * separately, so this module only swaps the plugin's copy.
+ *
+ * Only keys that are safe to change under a running session are applied: the
+ * ones the plugin reads from `ctx.config` on every tool call. Keys that change
+ * the registered tools, their descriptions or the system text stay as loaded
+ * and apply at the next host restart; they are reported as deferred.
+ */
+import { watch } from "node:fs";
+/** How long a burst of file events must be quiet before the files are read. */
+export declare const CONFIG_WATCH_DEBOUNCE_MS = 150;
+/**
+ * Appended to a config error found by a live reload, in place of the
+ * "restart the host" note a startup config error carries: the plugin keeps
+ * running on the last valid configuration.
+ */
+export declare const CONFIG_LIVE_KEEP_NOTE = "AFT keeps using the last valid configuration until the file is fixed.";
+/** One config key the plugin applies live: how to read it and write it. */
+export interface LiveConfigKey<C> {
+    /** Dotted config key, as the user writes it in aft.jsonc. */
+    name: string;
+    read(config: C): unknown;
+    /** Return a copy of `config` with this key set to `value`. */
+    write(config: C, value: unknown): C;
+}
+/** The bash settings this module needs from a host's `resolveBashConfig`. */
+export interface ResolvedBashForLiveReload {
+    foreground_wait_window_ms: number;
+    host_fallback: boolean;
+    subagent_background: boolean;
+    watch_sync_max_ms: number;
+}
+/**
+ * Every key the plugins read that a live reload applies. The engine-side
+ * list is `apply_live_config` in `crates/aft/src/config_live.rs`.
+ */
+export declare function aftLiveConfigKeys<C>(resolveBash: (config: C) => ResolvedBashForLiveReload & Record<string, unknown>): LiveConfigKey<C>[];
+/** What {@link applyLiveConfigKeys} changed and what it left for a restart. */
+export interface LiveConfigApply<C> {
+    /** `current` with only the changed live keys taken from `next`. */
+    config: C;
+    applied: string[];
+    deferred: string[];
+    /** Security keys a project edit would have loosened; they stay as they were. */
+    held?: string[];
+}
+/**
+ * Copy the live keys that differ from `current` out of `next`. `config` is a
+ * new object whenever something was applied, so a caller that captured the
+ * old one keeps a consistent snapshot. Other settings that differ from
+ * `baseline` (the config the plugin loaded at startup) are listed in
+ * `deferred` and not applied.
+ */
+export declare function applyLiveConfigKeys<C>(current: C, next: C, keys: readonly LiveConfigKey<C>[], baseline?: C): LiveConfigApply<C>;
+/** Options for {@link watchAftConfigFiles}. */
+export interface WatchAftConfigFilesOptions {
+    /** The config files to watch (user and project `aft.jsonc`). */
+    paths: readonly string[];
+    /**
+     * Called after a quiet debounce window when any file's text changed.
+     * Returning `false` means the new text was not accepted (for example a
+     * half-written save): it is not recorded as seen, and the files are checked
+     * again shortly even if no further event arrives. Returning a map records
+     * the texts the callback actually accepted (path to text, `null` for an
+     * absent file) instead of the texts this check read, which may differ if a
+     * file changed in between.
+     */
+    onChange: () => unknown;
+    debounceMs?: number;
+    /**
+     * The texts the caller already applied, keyed by path; a path that is not
+     * listed was absent. When omitted, the texts are unknown, so the first
+     * check calls `onChange`.
+     */
+    initialTexts?: Readonly<Record<string, string>>;
+    /** Check the files once as soon as the watch is attached. */
+    checkAtStart?: boolean;
+    /** Test seam: replaces `fs.watch`. */
+    watchImpl?: typeof watch;
+    /** Test seam: runs between reading a directory's identity and watching it. */
+    beforeWatchForTest?: (dir: string) => void;
+}
+/**
+ * Watch config files the way editors save them: the parent directory is
+ * watched, because an editor replaces the file by renaming a temporary
+ * sibling over it. A directory that does not exist yet is watched through its
+ * nearest existing ancestor until it appears, and a watch whose directory was
+ * replaced or failed is re-armed. Every event in a watched directory wakes
+ * the check (platforms may coalesce several changes into one event naming a
+ * different entry), and a steady stream of events delays it at most
+ * {@link CONFIG_WATCH_MAX_DELAY_MS}. `onChange` runs only when a file's text
+ * actually differs from what was last seen. Returns a function that stops
+ * every watch.
+ */
+export declare function watchAftConfigFiles(options: WatchAftConfigFilesOptions): () => void;
+/**
+ * Result of loading the config files for a live reload. `sources` lists the
+ * config files the load actually read; a file it relied on last time that is
+ * missing from it counts as deleted.
+ */
+export type LiveConfigLoad<C> = {
+    ok: true;
+    config: C;
+    sources: readonly string[];
+    /** The project config file's text as this load read it, or null when absent. */
+    projectText?: string | null;
+    /** The text of each file this load read, keyed by path. */
+    texts?: Readonly<Record<string, string>>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * A security key and which of two values is the stricter one. A project-file
+ * edit may move these only towards strict while the host runs.
+ */
+export interface LiveSecurityKey<C> {
+    key: LiveConfigKey<C>;
+    /** Whether changing the value from `current` to `next` loosens it. */
+    loosens(current: unknown, next: unknown): boolean;
+}
+/** The plugin-read security keys: the path restriction and host fallback. */
+export declare function aftLiveSecurityKeys<C>(keys: readonly LiveConfigKey<C>[]): LiveSecurityKey<C>[];
+/** Options for {@link startLiveConfigReload}. */
+export interface LiveConfigReloadOptions<C> {
+    /** The user and project `aft.jsonc` files. */
+    paths: readonly string[];
+    /** Load and resolve both files. Anything but a clean load is `ok: false`. */
+    load(): LiveConfigLoad<C>;
+    /** The config files the startup load that produced `getConfig()` read. */
+    initialSources: readonly string[];
+    /** The project config text the startup load read, or null when absent. */
+    initialProjectText?: string | null;
+    /** The text of each file the startup load read, keyed by path. */
+    initialTexts?: Readonly<Record<string, string>>;
+    /** Keys a project-file edit may only tighten; see {@link aftLiveSecurityKeys}. */
+    securityKeys?: readonly LiveSecurityKey<C>[];
+    keys: readonly LiveConfigKey<C>[];
+    getConfig(): C;
+    setConfig(config: C): void;
+    /** Informational log line. */
+    log(message: string): void;
+    /** A config error, logged and shown to the user once per distinct message. */
+    reportError(message: string): void;
+    /** Skip the file watch; tests call `reload()` directly. */
+    watch?: boolean;
+    debounceMs?: number;
+}
+/** Handle for a running live config reload. */
+export interface LiveConfigReload {
+    /** Read the files now and apply the live keys that changed. */
+    reload(): LiveConfigApply<unknown> | null;
+    stop(): void;
+}
+/** The log line a reload writes, in the same shape as the engine's. */
+export declare function liveConfigReloadLogLine(applied: string[], deferred: string[]): string;
+/**
+ * Watch the config files and keep `ctx.config` current for the live keys.
+ * An invalid, unreadable or deleted file keeps the last valid config: the
+ * error is reported and nothing else changes. Right after the watch starts
+ * the files are read once, so an edit made while the host was starting (after
+ * its config was loaded, before the watch existed) is not missed.
+ */
+export declare function startLiveConfigReload<C>(options: LiveConfigReloadOptions<C>): LiveConfigReload;
+//# sourceMappingURL=config-watch.d.ts.map

package/dist/config-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-watch.d.ts","sourceRoot":"","sources":["../src/config-watch.ts"],"names":[],"mappings":"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"}

package/dist/config-watch.js

@@ -0,0 +1,479 @@
+/**
+ * Live reload of AFT config file edits in a host plugin.
+ *
+ * The plugin keeps its own copy of the resolved config (`ctx.config`) for the
+ * keys it enforces or uses itself, such as the path restriction pre-check and
+ * the bash wait limits. The engine applies its own keys from the same files
+ * separately, so this module only swaps the plugin's copy.
+ *
+ * Only keys that are safe to change under a running session are applied: the
+ * ones the plugin reads from `ctx.config` on every tool call. Keys that change
+ * the registered tools, their descriptions or the system text stay as loaded
+ * and apply at the next host restart; they are reported as deferred.
+ */
+import { readFileSync, statSync, watch } from "node:fs";
+import { basename, dirname } from "node:path";
+/** How long a burst of file events must be quiet before the files are read. */
+export const CONFIG_WATCH_DEBOUNCE_MS = 150;
+/**
+ * Appended to a config error found by a live reload, in place of the
+ * "restart the host" note a startup config error carries: the plugin keeps
+ * running on the last valid configuration.
+ */
+export const CONFIG_LIVE_KEEP_NOTE = "AFT keeps using the last valid configuration until the file is fixed.";
+function pathKey(name) {
+    const segments = name.split(".");
+    return {
+        name,
+        read(config) {
+            let value = config;
+            for (const segment of segments) {
+                if (value === null || typeof value !== "object")
+                    return undefined;
+                value = value[segment];
+            }
+            return value;
+        },
+        write(config, value) {
+            const set = (target, index) => {
+                const copy = target !== null && typeof target === "object" && !Array.isArray(target)
+                    ? { ...target }
+                    : {};
+                const segment = segments[index];
+                if (index === segments.length - 1) {
+                    if (value === undefined)
+                        delete copy[segment];
+                    else
+                        copy[segment] = value;
+                }
+                else {
+                    copy[segment] = set(copy[segment], index + 1);
+                }
+                return copy;
+            };
+            return set(config, 0);
+        },
+    };
+}
+/**
+ * Bash keys are read through the host's `resolveBashConfig`, because `bash`
+ * may be a boolean, an object or the legacy `experimental.bash` block. A write
+ * turns `bash` into the equivalent object form, so every other bash setting
+ * (for example `compress` or `background`, which are not live) resolves to
+ * the same value as before.
+ */
+function bashKey(name, resolveBash) {
+    return {
+        name: `bash.${name}`,
+        read: (config) => resolveBash(config)[name],
+        write(config, value) {
+            const resolved = { ...resolveBash(config), [name]: value };
+            for (const key of Object.keys(resolved)) {
+                if (resolved[key] === undefined)
+                    delete resolved[key];
+            }
+            return { ...config, bash: resolved };
+        },
+    };
+}
+/**
+ * Every key the plugins read that a live reload applies. The engine-side
+ * list is `apply_live_config` in `crates/aft/src/config_live.rs`.
+ */
+export function aftLiveConfigKeys(resolveBash) {
+    return [
+        pathKey("configure_warnings_delivery"),
+        pathKey("restrict_to_project_root"),
+        pathKey("inspect.diagnostics_timeout_ms"),
+        pathKey("inspect.tier2_idle_minutes"),
+        bashKey("foreground_wait_window_ms", resolveBash),
+        bashKey("host_fallback", resolveBash),
+        bashKey("subagent_background", resolveBash),
+        bashKey("watch_sync_max_ms", resolveBash),
+    ];
+}
+function sameValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function flattenLeaves(value, prefix, out) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0 && prefix)
+            out.set(prefix, "{}");
+        for (const [key, child] of entries) {
+            flattenLeaves(child, prefix ? `${prefix}.${key}` : key, out);
+        }
+        return;
+    }
+    if (prefix)
+        out.set(prefix, JSON.stringify(value));
+}
+/**
+ * Copy the live keys that differ from `current` out of `next`. `config` is a
+ * new object whenever something was applied, so a caller that captured the
+ * old one keeps a consistent snapshot. Other settings that differ from
+ * `baseline` (the config the plugin loaded at startup) are listed in
+ * `deferred` and not applied.
+ */
+export function applyLiveConfigKeys(current, next, keys, baseline = current) {
+    let config = current;
+    const applied = [];
+    for (const key of keys) {
+        const value = key.read(next);
+        if (sameValue(key.read(current), value))
+            continue;
+        config = key.write(config, value);
+        applied.push(key.name);
+    }
+    const before = new Map();
+    const after = new Map();
+    flattenLeaves(baseline, "", before);
+    flattenLeaves(next, "", after);
+    const liveNames = keys.map((key) => key.name);
+    const isLive = (leaf) => liveNames.some((name) => leaf === name || leaf.startsWith(`${name}.`));
+    const deferred = new Set();
+    for (const leaf of new Set([...before.keys(), ...after.keys()])) {
+        if (before.get(leaf) === after.get(leaf) || isLive(leaf))
+            continue;
+        deferred.add(leaf);
+    }
+    return { config, applied, deferred: [...deferred].sort() };
+}
+function readTextOrNull(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** How often the watches are checked against the directories on disk. */
+const CONFIG_WATCH_REVALIDATE_MS = 2_000;
+/** How many times a rejected text is re-checked without a new event. */
+const CONFIG_WATCH_REJECTED_RETRIES = 3;
+/** Longest a stream of events may postpone a check. */
+const CONFIG_WATCH_MAX_DELAY_MS = 1_000;
+/**
+ * A directory's identity, which changes when the directory is replaced under
+ * the same name.
+ *
+ * - Everywhere: device and inode. On Windows Node reports the volume serial
+ *   number and the 64-bit file index there; `bigint` keeps the index exact.
+ * - Not on Windows: also the birth time, because ext4 hands a freed inode
+ *   number straight to the next directory created, so a directory deleted and
+ *   recreated keeps its inode number while inotify's watch stays on the
+ *   deleted one. On Windows the birth time is left out: NTFS file-name
+ *   tunneling gives a name reused within about 15 s the creation time of the
+ *   entry that last had it, so it carries no information there.
+ *
+ * Where a filesystem records no birth time it is 0 and the inode decides; the
+ * delete event (see `watchAftConfigFiles`) re-arms the watch in that case.
+ */
+function identityOf(dir) {
+    try {
+        const stat = statSync(dir, { bigint: true });
+        const base = `${stat.dev}:${stat.ino}`;
+        return process.platform === "win32" ? base : `${base}:${stat.birthtimeNs}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The directory to watch for `file`: its own directory, or while that does
+ * not exist, the nearest existing ancestor.
+ */
+function watchDirFor(file) {
+    let dir = dirname(file);
+    while (dir !== dirname(dir) && identityOf(dir) === null)
+        dir = dirname(dir);
+    return dir;
+}
+/**
+ * Watch config files the way editors save them: the parent directory is
+ * watched, because an editor replaces the file by renaming a temporary
+ * sibling over it. A directory that does not exist yet is watched through its
+ * nearest existing ancestor until it appears, and a watch whose directory was
+ * replaced or failed is re-armed. Every event in a watched directory wakes
+ * the check (platforms may coalesce several changes into one event naming a
+ * different entry), and a steady stream of events delays it at most
+ * {@link CONFIG_WATCH_MAX_DELAY_MS}. `onChange` runs only when a file's text
+ * actually differs from what was last seen. Returns a function that stops
+ * every watch.
+ */
+export function watchAftConfigFiles(options) {
+    const debounceMs = options.debounceMs ?? CONFIG_WATCH_DEBOUNCE_MS;
+    // `undefined` for a path means "not known", which differs from every text.
+    const lastSeen = new Map();
+    for (const path of options.paths) {
+        if (options.initialTexts)
+            lastSeen.set(path, options.initialTexts[path] ?? null);
+        else
+            lastSeen.set(path, options.checkAtStart ? undefined : readTextOrNull(path));
+    }
+    let timer = null;
+    let firstPendingAt = null;
+    let stopped = false;
+    const watchers = new Map();
+    const watchImpl = options.watchImpl ?? watch;
+    let rejectedRetries = 0;
+    const check = () => {
+        timer = null;
+        firstPendingAt = null;
+        if (stopped)
+            return;
+        revalidate();
+        const seen = new Map();
+        for (const path of options.paths) {
+            const text = readTextOrNull(path);
+            if (text !== lastSeen.get(path))
+                seen.set(path, text);
+        }
+        if (seen.size === 0)
+            return;
+        const outcome = options.onChange();
+        if (outcome === false) {
+            // Not accepted: keep the old texts as seen so the next event retries,
+            // and retry on our own a few times in case no further event comes (an
+            // editor that finished its save before this check read the file).
+            if (rejectedRetries < CONFIG_WATCH_REJECTED_RETRIES) {
+                rejectedRetries += 1;
+                retryTimer = setTimeout(check, CONFIG_WATCH_MAX_DELAY_MS);
+                retryTimer.unref?.();
+            }
+            return;
+        }
+        rejectedRetries = 0;
+        if (outcome instanceof Map) {
+            for (const path of options.paths)
+                lastSeen.set(path, outcome.get(path) ?? null);
+        }
+        else {
+            for (const [path, text] of seen)
+                lastSeen.set(path, text);
+        }
+    };
+    let retryTimer = null;
+    const schedule = () => {
+        if (stopped)
+            return;
+        const now = Date.now();
+        firstPendingAt ??= now;
+        if (timer)
+            clearTimeout(timer);
+        const delay = Math.max(0, Math.min(debounceMs, firstPendingAt + CONFIG_WATCH_MAX_DELAY_MS - now));
+        timer = setTimeout(check, delay);
+        timer.unref?.();
+    };
+    /** Bring the watches in line with the directories on disk. */
+    function revalidate() {
+        const wanted = new Set(options.paths.map(watchDirFor));
+        let moved = false;
+        for (const [dir, entry] of watchers) {
+            // A directory that is no longer wanted (its child appeared) or that was
+            // replaced under the watch is dropped and, if still wanted, re-armed.
+            if (!wanted.has(dir) || entry.stale || identityOf(dir) !== entry.identity) {
+                entry.watcher.close();
+                watchers.delete(dir);
+                moved = true;
+            }
+        }
+        for (const dir of wanted) {
+            if (watchers.has(dir))
+                continue;
+            try {
+                // Read the identity first and confirm it after: a directory replaced
+                // in between would leave the watch on the old one under the new
+                // one's identity, and it would never be re-armed.
+                const identity = identityOf(dir);
+                options.beforeWatchForTest?.(dir);
+                const name = basename(dir);
+                const watcher = watchImpl(dir, { persistent: false }, (event, filename) => {
+                    // A `rename` naming the watched directory itself means the
+                    // directory was deleted or moved: the watch follows the old one,
+                    // so the next check re-arms it on whatever now has this path.
+                    if (event === "rename" && filename === name) {
+                        const current = watchers.get(dir);
+                        if (current && current.watcher === watcher)
+                            current.stale = true;
+                    }
+                    schedule();
+                });
+                if (identityOf(dir) !== identity) {
+                    watcher.close();
+                    moved = true;
+                    continue;
+                }
+                const entry = { watcher, identity, stale: false };
+                entry.watcher.on("error", () => {
+                    entry.watcher.close();
+                    if (watchers.get(dir) === entry)
+                        watchers.delete(dir);
+                    // Re-arm on the next check rather than going silent.
+                    schedule();
+                });
+                watchers.set(dir, entry);
+                moved = true;
+            }
+            catch {
+                // The directory vanished between the check and the watch; the next
+                // revalidation finds its nearest existing ancestor.
+            }
+        }
+        return moved;
+    }
+    revalidate();
+    if (options.checkAtStart)
+        check();
+    // Some platforms stop reporting on a deleted or replaced directory without
+    // an error; a periodic check re-arms such a watch. Moving a watch (for
+    // example once `.cortexkit/` is created) may reveal a file, so it checks.
+    const revalidateTimer = setInterval(() => {
+        if (!stopped && revalidate())
+            schedule();
+    }, CONFIG_WATCH_REVALIDATE_MS);
+    revalidateTimer.unref?.();
+    return () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+        if (retryTimer)
+            clearTimeout(retryTimer);
+        clearInterval(revalidateTimer);
+        for (const entry of watchers.values())
+            entry.watcher.close();
+        watchers.clear();
+    };
+}
+/** The plugin-read security keys: the path restriction and host fallback. */
+export function aftLiveSecurityKeys(keys) {
+    const byName = new Map(keys.map((key) => [key.name, key]));
+    const pick = (name) => {
+        const key = byName.get(name);
+        if (!key)
+            throw new Error(`unknown live config key ${name}`);
+        return key;
+    };
+    return [
+        {
+            key: pick("restrict_to_project_root"),
+            loosens: (current, next) => current === true && next !== true,
+        },
+        {
+            key: pick("bash.host_fallback"),
+            loosens: (current, next) => current !== true && next === true,
+        },
+    ];
+}
+/** The log line a reload writes, in the same shape as the engine's. */
+export function liveConfigReloadLogLine(applied, deferred) {
+    let line = "config reload";
+    if (applied.length > 0)
+        line += ` applied=[${applied.join(",")}]`;
+    if (deferred.length > 0) {
+        line += ` deferred=[${deferred.join(",")}] (deferred keys apply on next connect/restart)`;
+    }
+    return line;
+}
+/**
+ * Watch the config files and keep `ctx.config` current for the live keys.
+ * An invalid, unreadable or deleted file keeps the last valid config: the
+ * error is reported and nothing else changes. Right after the watch starts
+ * the files are read once, so an edit made while the host was starting (after
+ * its config was loaded, before the watch existed) is not missed.
+ */
+export function startLiveConfigReload(options) {
+    const baseline = options.getConfig();
+    let lastError = null;
+    // The files the last accepted load read. A load that no longer reads one of
+    // them keeps the last valid config rather than resolving the file as empty:
+    // a security setting must not loosen because a file vanished mid-save or
+    // was deleted by mistake. The next host restart applies a real deletion.
+    let acceptedSources = new Set(options.initialSources);
+    // The project text the published security values rest on. A project edit
+    // that would loosen one of them is held until the next restart, and this
+    // stays at the older text so later reloads keep holding it.
+    let acceptedProjectText = options.initialProjectText ?? null;
+    // The texts the last accepted load read, handed to the watch so it records
+    // what was applied rather than what it happened to read.
+    let acceptedTexts;
+    const reload = () => {
+        let loaded = options.load();
+        if (loaded.ok) {
+            const read = new Set(loaded.sources);
+            const deleted = [...acceptedSources].find((path) => !read.has(path));
+            if (deleted !== undefined) {
+                loaded = { ok: false, message: `AFT config at ${deleted} was deleted` };
+            }
+            else {
+                acceptedSources = read;
+            }
+        }
+        if (!loaded.ok) {
+            const message = `${loaded.message.trim().replace(/[.!?]?$/, ".")} ${CONFIG_LIVE_KEEP_NOTE}`;
+            if (message !== lastError) {
+                lastError = message;
+                options.reportError(message);
+            }
+            return null;
+        }
+        lastError = null;
+        acceptedTexts = loaded.texts;
+        const current = options.getConfig();
+        let next = loaded.config;
+        const held = [];
+        const projectText = loaded.projectText ?? null;
+        if (loaded.projectText !== undefined && projectText !== acceptedProjectText) {
+            for (const security of options.securityKeys ?? []) {
+                const now = security.key.read(current);
+                if (security.loosens(now, security.key.read(next))) {
+                    next = security.key.write(next, now);
+                    held.push(security.key.name);
+                }
+            }
+            if (held.length === 0)
+                acceptedProjectText = projectText;
+        }
+        const result = applyLiveConfigKeys(current, next, options.keys, baseline);
+        if (result.applied.length > 0)
+            options.setConfig(result.config);
+        if (result.applied.length > 0 || result.deferred.length > 0 || held.length > 0) {
+            let line = liveConfigReloadLogLine(result.applied, result.deferred);
+            if (held.length > 0) {
+                line += ` held=[${held.join(",")}] (not loosened while the project file differs from the one the published values came from; the next restart applies them)`;
+            }
+            options.log(line);
+        }
+        return { ...result, held };
+    };
+    const safeReload = () => {
+        try {
+            acceptedTexts = undefined;
+            if (reload() === null)
+                return false;
+            const texts = acceptedTexts;
+            if (!texts)
+                return true;
+            return new Map(options.paths.map((path) => [path, texts[path] ?? null]));
+        }
+        catch (err) {
+            options.reportError(`AFT config reload failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    if (options.watch === false) {
+        return { reload: reload, stop: () => { } };
+    }
+    // The first check runs as soon as the watch is attached, through the same
+    // accepted-text and retry path as every later one, so an edit made while
+    // the host was starting is applied and a transient rejection is retried.
+    const stop = watchAftConfigFiles({
+        paths: options.paths,
+        debounceMs: options.debounceMs,
+        onChange: safeReload,
+        initialTexts: options.initialTexts,
+        checkAtStart: true,
+    });
+    return { reload: reload, stop };
+}
+//# sourceMappingURL=config-watch.js.map