@nexrall/code-core 1.4.66 → 1.4.67

package/dist/agent/lifecycleHost.js

@@ -0,0 +1,294 @@
+"use strict";
+// Host-driven lifecycle hooks — the two events the AGENT LOOP cannot fire itself:
+//
+//   • FileChanged        — a watched file in the working directory changed on disk.
+//                          The loop has no watcher; the host (CLI / VS Code) starts one.
+//   • InstructionsLoaded — instruction files (nexrall.md, memory) were read. Only the
+//                          host knows which files those were and why they were read.
+//
+// Both use the same config, payload and exit-code protocol as every other hook; see
+// loop.ts. Both are OBSERVERS: a hook can inform the user, it cannot veto anything —
+// the file already changed, the file is already loaded.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fireInstructionsLoadedHooks = fireInstructionsLoadedHooks;
+exports.startFileChangedWatcher = startFileChangedWatcher;
+exports.filesChangedSinceSnapshot = filesChangedSinceSnapshot;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const loop_1 = require("./loop");
+/**
+ * Tell the InstructionsLoaded hooks which instruction files this session loaded.
+ * Observer: output and exit code are ignored (Claude Code says the same for this event).
+ *
+ * Called by the host at the moment the files are actually read — a `--bare` run reads
+ * none and therefore fires nothing, which is the honest behaviour.
+ */
+async function fireInstructionsLoadedHooks(workDir, sessionId, files) {
+    if (!files.length)
+        return;
+    try {
+        const items = (0, loop_1.loadHooks)(workDir).InstructionsLoaded;
+        if (!items?.length)
+            return;
+        for (const f of files) {
+            await (0, loop_1.runLifecycleHooks)(items, 'InstructionsLoaded', workDir, {
+                session_id: sessionId,
+                file_path: f.file_path,
+                memory_type: f.memory_type,
+                load_reason: f.load_reason,
+                ...(f.globs ? { globs: f.globs } : {}),
+            }, f.load_reason).catch(() => undefined);
+        }
+    }
+    catch { /* a hook must never break startup */ }
+}
+/** Only basenames in the working directory can be watched — a matcher is a filename, not a path. */
+function isWatchableName(name) {
+    // Claude Code is narrower still (letters, digits, _, |); we allow the characters a real
+    // filename needs and drop anything that tries to be a path or a glob.
+    return !!name && !name.includes('/') && !name.includes('\\') && !name.includes('*') && !name.includes('?') && name !== '.' && name !== '..';
+}
+/**
+ * Start watching the files named by the FileChanged hooks' matchers ("a.txt|b.txt").
+ *
+ * - Returns null when no FileChanged hook is configured, so callers can wire it
+ *   unconditionally.
+ * - `fs.watch` on the WORKING DIRECTORY (not the files themselves: editors replace
+ *   files, which kills a per-file watch on rename) filtered to the watched basenames,
+ *   with a short per-file debounce — one save is several fs events.
+ * - A hook's `{"watchPaths": […]}` answer replaces the dynamic list; `{"systemMessage": "…"}`
+ *   is handed to `onSystemMessage` for the host to display.
+ * - Never throws into the host: watching is best-effort (an OS without inotify, a
+ *   directory that vanishes) and a broken watch must not break the session.
+ */
+function startFileChangedWatcher(workDir, sessionId, opts) {
+    let items;
+    try {
+        items = (0, loop_1.loadHooks)(workDir).FileChanged;
+    }
+    catch {
+        items = undefined;
+    }
+    if (!items?.length)
+        return null;
+    // Static names: every literal in every matcher. Flat handlers contribute none — a flat
+    // handler with no matcher watches nothing until some hook returns a watchPaths list.
+    const staticNames = new Set();
+    for (const it of items) {
+        if (it && Array.isArray(it.hooks)) {
+            const m = it.matcher;
+            if (!m || m === '*')
+                continue;
+            for (const raw of m.split('|')) {
+                const name = raw.trim();
+                if (isWatchableName(name))
+                    staticNames.add(name);
+            }
+        }
+    }
+    if (!staticNames.size)
+        return null;
+    const dynamicNames = new Set();
+    const watched = () => new Set([...staticNames, ...dynamicNames]);
+    // Who existed when we last looked. fs.watch's eventType is NOT an add/change oracle:
+    // on macOS a plain overwrite arrives as 'rename', so distinguishing by eventType
+    // labelled every save an "add". Existence across events is the honest signal, and it
+    // needs a seed — a file already present when the watcher starts is not "added" later.
+    const known = new Set();
+    const seedKnown = (names) => {
+        for (const n of names) {
+            try {
+                if (fs.existsSync(path.join(workDir, n)))
+                    known.add(n);
+            }
+            catch { /* best-effort */ }
+        }
+    };
+    seedKnown(staticNames);
+    // A cheap identity for "this file changed": mtime + size. Used by the ARMING RECONCILE
+    // below, which exists because fs.watch arms ASYNCHRONOUSLY — the FSEvents/FSEventStream
+    // stream starts on the next tick, and an event that lands before it is armed is not
+    // queued, it is GONE. An editor that saves the instant the session starts is exactly
+    // that case (measured: under load the write was lost outright, the hook never ran).
+    const stamp = (name) => {
+        try {
+            const st = fs.statSync(path.join(workDir, name));
+            return `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            return '';
+        }
+    };
+    const seen = new Map();
+    const snapshot = (names) => { for (const n of names)
+        seen.set(n, stamp(n)); };
+    snapshot(staticNames);
+    const pending = new Map();
+    let closed = false;
+    /** Arm the per-file debounce — shared by real fs events and by the arming reconcile. */
+    const scheduleFire = (name) => {
+        const prev = pending.get(name);
+        if (prev)
+            clearTimeout(prev);
+        pending.set(name, setTimeout(() => {
+            pending.delete(name);
+            let exists = true;
+            try {
+                exists = fs.existsSync(path.join(workDir, name));
+            }
+            catch {
+                exists = false;
+            }
+            const event = !exists ? 'unlink' : known.has(name) ? 'change' : 'add';
+            if (exists)
+                known.add(name);
+            else
+                known.delete(name);
+            seen.set(name, stamp(name));
+            void fireChanged(workDir, sessionId, name, event, items, dynamicNames.has(name)).then((o) => {
+                if (!o)
+                    return;
+                if (o.systemMessage && opts?.onSystemMessage) {
+                    try {
+                        opts.onSystemMessage(o.systemMessage);
+                    }
+                    catch { /* host callback */ }
+                }
+                if (o.watchPaths) {
+                    // watchPaths REPLACES the dynamic list (Claude Code semantics); the static
+                    // matcher names always stay watched — they are what activated this watcher.
+                    dynamicNames.clear();
+                    for (const p of o.watchPaths) {
+                        const n = isWatchableName(path.basename(p)) ? path.basename(p) : '';
+                        if (n)
+                            dynamicNames.add(n);
+                    }
+                    seedKnown(dynamicNames);
+                    snapshot(dynamicNames);
+                }
+            }).catch(() => { });
+        }, 250));
+    };
+    let watcher = null;
+    try {
+        watcher = fs.watch(workDir, { persistent: false }, (_eventType, filename) => {
+            if (closed)
+                return;
+            const name = filename ? path.basename(String(filename)) : '';
+            if (!name || !watched().has(name))
+                return;
+            // Debounce per file: a single save reaches us as create+change+change on some
+            // platforms, and running the hook per raw event would fire it 3×.
+            scheduleFire(name);
+        });
+        // A watcher that failed to attach must not hold a dead object.
+        watcher.on('error', () => { });
+    }
+    catch {
+        return null;
+    }
+    // Arming reconcile (see `stamp` above): one look after the stream has had time to arm,
+    // to catch a write the stream was not yet listening for. It reuses scheduleFire, so a
+    // file caught by BOTH paths still fires exactly once (the pending timer is re-armed,
+    // not duplicated).
+    const armGraceMs = opts?.armGraceMs ?? 400;
+    const reconcileTimer = armGraceMs > 0
+        ? setTimeout(() => {
+            if (closed)
+                return;
+            for (const n of filesChangedSinceSnapshot(watched(), seen, stamp))
+                scheduleFire(n);
+        }, armGraceMs)
+        : null;
+    return {
+        stop() {
+            closed = true;
+            if (reconcileTimer)
+                clearTimeout(reconcileTimer);
+            for (const t of pending.values())
+                clearTimeout(t);
+            pending.clear();
+            try {
+                watcher?.close();
+            }
+            catch { /* already closed */ }
+            watcher = null;
+        },
+        updateWatchPaths(paths) {
+            dynamicNames.clear();
+            for (const p of paths) {
+                const n = isWatchableName(path.basename(p)) ? path.basename(p) : '';
+                if (n)
+                    dynamicNames.add(n);
+            }
+            seedKnown(dynamicNames);
+            snapshot(dynamicNames);
+        },
+        watchedFiles() { return [...watched()].sort(); },
+    };
+}
+/**
+ * Which watched files differ from the snapshot taken when the watcher armed. This is the
+ * whole substance of the arming reconcile: fs.watch arms asynchronously, so a write that
+ * lands before the stream is listening is not queued — it is gone. Exported so the
+ * comparison can be tested without racing an OS event.
+ */
+function filesChangedSinceSnapshot(names, seen, stamp) {
+    const out = [];
+    for (const n of names)
+        if (stamp(n) !== (seen.get(n) ?? ''))
+            out.push(n);
+    return out;
+}
+/** Fire the FileChanged hooks for one file, returning the merged outcome (or null on any failure). */
+async function fireChanged(workDir, sessionId, name, event, items, isDynamic) {
+    const abs = path.join(workDir, name);
+    try {
+        // A file admitted through watchPaths had no matcher naming it, so no matcher may
+        // filter it either — every FileChanged group hears about it. A static matcher file
+        // runs only the groups that named it.
+        const o = await (0, loop_1.runLifecycleHooks)(items, 'FileChanged', workDir, {
+            session_id: sessionId,
+            file_path: abs,
+            event,
+        }, isDynamic ? undefined : name);
+        return { watchPaths: o.watchPaths, systemMessage: o.systemMessage };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=lifecycleHost.js.map