@jitsusama/agentic-harness.core 0.6.1 → 0.6.2

package/dist/lsp/standalone/backend.d.ts

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -30,6 +36,8 @@ export interface StandaloneBackendOptions {
     readonly servers?: Readonly<Record<string, ServerConfig>>;
     /** Environment used for PATH resolution. Defaults to process.env. */
     readonly env?: NodeJS.ProcessEnv;
+    /** How long a server may sit unused before it is stopped. */
+    readonly idleMs?: number;
 }
 /** A standalone backend with visibility into its live pool. */
 export interface StandaloneBackend extends LspBackend {

package/dist/lsp/standalone/backend.js

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -28,20 +34,56 @@ export class MissingServerError extends Error {
         this.name = "MissingServerError";
     }
 }
+/**
+ * Default idle window. Long enough that a burst of work on one
+ * project keeps its server warm, short enough that a project left
+ * behind gives its memory back within the hour.
+ */
+const DEFAULT_IDLE_MS = 10 * 60_000;
 /** Construct a standalone backend over the given (or default) server map. */
 export function createStandaloneBackend(options = {}) {
     const servers = options.servers ?? DEFAULT_SERVERS;
     const env = options.env ?? process.env;
+    const idleMs = options.idleMs ?? DEFAULT_IDLE_MS;
     const pool = new Map();
+    // Calls in flight per pool key, and the stop timer armed when a
+    // key's last call finishes.
+    const inFlight = new Map();
+    const idleTimers = new Map();
     const poolKey = (name, root) => `${name}|${root}`;
+    const claim = (key) => {
+        inFlight.set(key, (inFlight.get(key) ?? 0) + 1);
+        clearTimeout(idleTimers.get(key));
+        idleTimers.delete(key);
+    };
+    const release = (key) => {
+        const left = (inFlight.get(key) ?? 1) - 1;
+        if (left > 0) {
+            inFlight.set(key, left);
+            return;
+        }
+        inFlight.delete(key);
+        const timer = setTimeout(() => stopIdle(key), idleMs);
+        // An idle server must never be what keeps the process alive.
+        timer.unref();
+        idleTimers.set(key, timer);
+    };
+    const stopIdle = (key) => {
+        idleTimers.delete(key);
+        if (inFlight.has(key))
+            return;
+        const started = pool.get(key);
+        pool.delete(key);
+        void started?.then((server) => server.dispose(), () => { });
+    };
     const instanceFor = (server, root, binary) => {
         const key = poolKey(server.name, root);
         const existing = pool.get(key);
         if (existing)
-            return existing;
+            return { key, started: existing };
         const started = StandaloneServer.start(server, root, binary);
         pool.set(key, started);
-        return started;
+        return { key, started };
     };
     // Resolve a server's effective command and args for a root. A
     // server with a `resolve` hook picks its binary per project (the
@@ -65,7 +107,22 @@ export function createStandaloneBackend(options = {}) {
             binary,
         };
     };
-    const resolveInstances = async (filePath, typeOnly) => {
+    /**
+     * Run fn against the servers for a file, holding each one's pool
+     * key claimed from before it resolves until fn settles, so no
+     * server is stopped under a call that is using it.
+     */
+    const withInstances = async (filePath, typeOnly, fn) => {
+        const claimed = [];
+        try {
+            return await fn(await resolveInstances(filePath, typeOnly, claimed));
+        }
+        finally {
+            for (const key of claimed)
+                release(key);
+        }
+    };
+    const resolveInstances = async (filePath, typeOnly, claimed) => {
         const candidates = serversForFile(filePath, servers).filter((server) => !typeOnly || !server.isLinter);
         const instances = [];
         const reasons = [];
@@ -80,7 +137,10 @@ export function createStandaloneBackend(options = {}) {
                 reasons.push(eff.reason);
                 continue;
             }
-            instances.push(await instanceFor(eff.config, root, eff.binary));
+            const { key, started } = instanceFor(eff.config, root, eff.binary);
+            claim(key);
+            claimed.push(key);
+            instances.push(await started);
             if (typeOnly)
                 break;
         }
@@ -95,40 +155,46 @@ export function createStandaloneBackend(options = {}) {
     return {
         name: "standalone",
         async diagnostics(path) {
-            const instances = await resolveInstances(path, false);
-            const results = await Promise.all(instances.map((s) => s.diagnose(path)));
-            return results.flat();
+            return withInstances(path, false, async (instances) => {
+                const results = await Promise.all(instances.map((s) => s.diagnose(path)));
+                return results.flat();
+            });
         },
         async definition(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.definition(target);
+            return withInstances(target.path, true, ([server]) => server.definition(target));
         },
         async references(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.references(target);
+            return withInstances(target.path, true, ([server]) => server.references(target));
         },
         async hover(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.hover(target);
+            return withInstances(target.path, true, ([server]) => server.hover(target));
         },
         async documentSymbols(path) {
-            const [server] = await resolveInstances(path, true);
-            return server.documentSymbols(path);
+            return withInstances(path, true, ([server]) => server.documentSymbols(path));
         },
         async workspaceSymbols(query) {
             // Workspace symbols carry no file, so they search every
-            // server already running; nothing is spawned on demand.
-            const live = await Promise.all([...pool.values()]);
-            const results = await Promise.all(live.map((server) => server.workspaceSymbols(query)));
-            return results.flat();
+            // server already running; nothing is spawned on demand, and
+            // a server stopped for idleness is not searched until
+            // something file-bound starts it again.
+            const keys = [...pool.keys()];
+            for (const key of keys)
+                claim(key);
+            try {
+                const live = await Promise.all(keys.map((key) => pool.get(key)));
+                const results = await Promise.all(live.map((server) => server?.workspaceSymbols(query) ?? []));
+                return results.flat();
+            }
+            finally {
+                for (const key of keys)
+                    release(key);
+            }
         },
         async rename(target, newName) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.rename(target, newName);
+            return withInstances(target.path, true, ([server]) => server.rename(target, newName));
         },
         async codeActions(path, range) {
-            const [server] = await resolveInstances(path, true);
-            return server.codeActions(path, range);
+            return withInstances(path, true, ([server]) => server.codeActions(path, range));
         },
         syncDocument(path, text) {
             for (const started of pool.values()) {
@@ -142,6 +208,9 @@ export function createStandaloneBackend(options = {}) {
             return pool.size;
         },
         async dispose() {
+            for (const timer of idleTimers.values())
+                clearTimeout(timer);
+            idleTimers.clear();
             const started = [...pool.values()];
             pool.clear();
             await Promise.all(started.map((s) => s.then((server) => server.dispose())));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jitsusama/agentic-harness.core",
-	"version": "0.6.1",
+	"version": "0.6.2",
 	"description": "Pi-agnostic business logic for agentic-harness: state machines, guardian decisions, quest/TDD domain model.",
 	"license": "MIT",
 	"type": "module",