@dreb/coding-agent 2.66.3 → 2.68.0

package/dist/core/tools/subagent.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { completeSimple } from "@dreb/ai";
@@ -559,7 +559,7 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
     });
 }
 const STEP_SESSION_DIR_RE = /^step-(\d+)$/;
-function findNewestJsonlFileInDir(dir) {
+function findNewestJsonlFileInDir(dir, throwOnOperationalError = false) {
     let best;
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         if (!entry.name.endsWith(".jsonl"))
@@ -573,14 +573,14 @@ function findNewestJsonlFileInDir(dir) {
                 best = { path: fullPath, mtime };
         }
         catch (err) {
-            if (isExpectedFilesystemError(err))
+            if (isExpectedFilesystemError(err) && (!throwOnOperationalError || isMissingFilesystemError(err)))
                 continue;
             throw err;
         }
     }
     return best;
 }
-function discoverStepSessionFileCandidates(sessionDir) {
+function discoverStepSessionFileCandidates(sessionDir, throwOnOperationalError = false) {
     const steps = [];
     for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
         if (!entry.isDirectory())
@@ -594,12 +594,12 @@ function discoverStepSessionFileCandidates(sessionDir) {
     const files = [];
     for (const step of steps) {
         try {
-            const candidate = findNewestJsonlFileInDir(join(sessionDir, step.name));
+            const candidate = findNewestJsonlFileInDir(join(sessionDir, step.name), throwOnOperationalError);
             if (candidate)
                 files.push(candidate);
         }
         catch (err) {
-            if (isExpectedFilesystemError(err))
+            if (isExpectedFilesystemError(err) && (!throwOnOperationalError || isMissingFilesystemError(err)))
                 continue;
             throw err;
         }
@@ -615,22 +615,28 @@ function discoverStepSessionFileCandidates(sessionDir) {
  * present this recurses one level into step-* directories and returns one file
  * per step in numeric step order.
  */
-export function discoverSessionFiles(sessionDir, agentName) {
+export function discoverSessionFiles(sessionDir, agentName, options = {}) {
+    const throwOnOperationalError = options.throwOnOperationalError ?? false;
     try {
-        if (!existsSync(sessionDir))
+        if (!throwOnOperationalError && !existsSync(sessionDir))
             return [];
-        const flatFile = findNewestJsonlFileInDir(sessionDir);
+        const flatFile = findNewestJsonlFileInDir(sessionDir, throwOnOperationalError);
         if (flatFile) {
             log.debug(`[subagent] session file: ${flatFile.path} (agent=${agentName})`);
             return [flatFile.path];
         }
-        const stepFiles = discoverStepSessionFileCandidates(sessionDir);
+        const stepFiles = discoverStepSessionFileCandidates(sessionDir, throwOnOperationalError);
         if (stepFiles.length > 0) {
             log.debug(`[subagent] chain session files: ${stepFiles.map((file) => file.path).join(", ")} (agent=${agentName})`);
             return stepFiles.map((file) => file.path);
         }
     }
     catch (err) {
+        if (throwOnOperationalError) {
+            if (isMissingFilesystemError(err))
+                return [];
+            throw err;
+        }
         if (!isExpectedFilesystemError(err))
             throw err;
         log.warn(`[subagent] failed to discover session file (agent=${agentName}): ${err instanceof Error ? err.message : String(err)}`);
@@ -1337,6 +1343,18 @@ function isRecord(value) {
 function isExpectedFilesystemError(err) {
     return typeof err?.code === "string";
 }
+/** Only absence is optional during primary-root restart recovery. */
+function isMissingFilesystemError(err) {
+    return err?.code === "ENOENT";
+}
+function shouldSkipRehydrationFilesystemError(err, isPrimaryRoot, context) {
+    if (isMissingFilesystemError(err))
+        return true;
+    if (isPrimaryRoot || !isExpectedFilesystemError(err))
+        return false;
+    log.warn(`[subagent] skipped compatibility-root recovery (${context}): ${err instanceof Error ? err.message : String(err)}`);
+    return true;
+}
 function parseJsonlLine(line) {
     try {
         const parsed = JSON.parse(line);
@@ -1372,7 +1390,7 @@ function readFirstNonEmptyLine(filePath) {
         return buffered.trim() ? buffered : undefined;
     }
     catch (err) {
-        if (isExpectedFilesystemError(err))
+        if (isMissingFilesystemError(err))
             return undefined;
         throw err;
     }
@@ -1396,7 +1414,7 @@ function readFileSlice(filePath, start, length) {
         return buffer.toString("utf8", 0, bytesRead);
     }
     catch (err) {
-        if (isExpectedFilesystemError(err))
+        if (isMissingFilesystemError(err))
             return undefined;
         throw err;
     }
@@ -1417,7 +1435,7 @@ function readFileStart(filePath, maxBytes) {
         size = Math.min(statSync(filePath).size, maxBytes);
     }
     catch (err) {
-        if (isExpectedFilesystemError(err))
+        if (isMissingFilesystemError(err))
             return undefined;
         throw err;
     }
@@ -1432,7 +1450,7 @@ function readFileTail(filePath, maxBytes) {
         length = size - start;
     }
     catch (err) {
-        if (isExpectedFilesystemError(err))
+        if (isMissingFilesystemError(err))
             return undefined;
         throw err;
     }
@@ -1448,6 +1466,19 @@ function comparablePath(pathValue) {
     const resolved = resolve(pathValue);
     return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
+/** Canonical identity for an existing path, with a lexical fallback for races/missing paths. */
+function canonicalExistingPath(pathValue) {
+    let canonical;
+    try {
+        canonical = realpathSync.native(pathValue);
+    }
+    catch (err) {
+        if (!isMissingFilesystemError(err))
+            throw err;
+        canonical = resolve(pathValue);
+    }
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
 function parentSessionMatches(recordedParentSession, parentSessionFile) {
     if (recordedParentSession === parentSessionFile)
         return true;
@@ -1524,82 +1555,125 @@ function parseStartedAt(header, sessionFile) {
         return statSync(sessionFile).mtime.getTime();
     }
     catch (err) {
-        if (isExpectedFilesystemError(err))
+        if (isMissingFilesystemError(err))
             return Date.now();
         throw err;
     }
 }
 function hasRegisteredSession(sessionDir, sessionFile) {
-    const comparableSessionDir = comparablePath(sessionDir);
-    const comparableSessionFile = comparablePath(sessionFile);
+    const comparableSessionDir = canonicalExistingPath(sessionDir);
+    const comparableSessionFile = canonicalExistingPath(sessionFile);
     for (const agent of backgroundAgentRegistry.values()) {
-        if (agent.sessionDir && comparablePath(agent.sessionDir) === comparableSessionDir)
+        if (agent.sessionDir && canonicalExistingPath(agent.sessionDir) === comparableSessionDir)
             return true;
-        if (agent.sessionFile && comparablePath(agent.sessionFile) === comparableSessionFile)
+        if (agent.sessionFile && canonicalExistingPath(agent.sessionFile) === comparableSessionFile)
             return true;
     }
     return false;
 }
 /**
- * Best-effort recovery for completed background subagents after a dashboard/RPC
- * process resumes an existing parent session. Live background-agent state is an
- * in-memory registry, while child sessions are durable JSONL files under the
- * subagent sessions directory.
+ * Recover completed background subagents after a dashboard/RPC process resumes
+ * an existing parent session. Live background-agent state is an in-memory
+ * registry, while child sessions are durable JSONL files under the subagent
+ * sessions directory.
  *
- * Returns the number of newly registered agents. Expected filesystem and JSONL
- * parse failures are skipped; unexpected programming errors are allowed to throw.
+ * The first root is authoritative: absence races and malformed JSON are skipped,
+ * while operational filesystem failures throw. Later roots are compatibility
+ * stores, so their operational filesystem failures are warned and skipped.
+ * Returns the number of newly registered agents.
  */
-export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSessionsBase = getSubagentSessionsDir()) {
+export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSessionRoots = getSubagentSessionsDir()) {
     if (!parentSessionFile)
         return 0;
-    let entries;
-    try {
-        entries = readdirSync(subagentSessionsBase, { withFileTypes: true });
-    }
-    catch (err) {
-        if (isExpectedFilesystemError(err))
-            return 0;
-        throw err;
-    }
+    const roots = typeof subagentSessionRoots === "string" ? [subagentSessionRoots] : subagentSessionRoots;
+    const scannedRoots = new Set();
+    const seenSessionDirs = new Set();
+    const seenSessionFiles = new Set();
     let registered = 0;
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const sessionDir = join(subagentSessionsBase, entry.name);
-        const sessionFiles = discoverSessionFiles(sessionDir, entry.name);
-        if (sessionFiles.length === 0)
-            continue;
-        let sessionFile;
-        let header;
-        for (const candidateFile of sessionFiles) {
-            const candidateHeader = parseSessionHeader(candidateFile);
-            if (candidateHeader?.type !== "session" || typeof candidateHeader.parentSession !== "string")
-                continue;
-            if (!parentSessionMatches(candidateHeader.parentSession, parentSessionFile))
+    for (const [rootIndex, subagentSessionsBase] of roots.entries()) {
+        const isPrimaryRoot = rootIndex === 0;
+        let canonicalRoot;
+        try {
+            canonicalRoot = canonicalExistingPath(subagentSessionsBase);
+        }
+        catch (err) {
+            if (shouldSkipRehydrationFilesystemError(err, isPrimaryRoot, `root ${subagentSessionsBase}`))
                 continue;
-            sessionFile = candidateFile;
-            header = candidateHeader;
-            break;
+            throw err;
         }
-        if (!sessionFile || !header)
-            continue;
-        const agentId = `${REHYDRATED_AGENT_ID_PREFIX}${entry.name}`;
-        if (backgroundAgentRegistry.has(agentId) || hasRegisteredSession(sessionDir, sessionFile))
+        if (scannedRoots.has(canonicalRoot))
             continue;
-        const statusFile = sessionFiles[sessionFiles.length - 1] ?? sessionFile;
-        const agentType = typeof header.agentType === "string" && header.agentType.trim() ? header.agentType : "agent";
-        const taskSummary = findFirstUserMessageSummary(sessionFile) ?? `${agentType} (${entry.name})`;
-        backgroundAgentRegistry.set(agentId, {
-            agentId,
-            agentType,
-            taskSummary,
-            startedAt: parseStartedAt(header, sessionFile),
-            status: inferCompletedSessionStatus(statusFile),
-            sessionDir,
-            sessionFile,
-            cwd: typeof header.cwd === "string" ? header.cwd : undefined,
-        });
-        registered++;
+        scannedRoots.add(canonicalRoot);
+        let entries;
+        try {
+            entries = readdirSync(subagentSessionsBase, { withFileTypes: true });
+        }
+        catch (err) {
+            if (shouldSkipRehydrationFilesystemError(err, isPrimaryRoot, `root ${subagentSessionsBase}`))
+                continue;
+            throw err;
+        }
+        for (const entry of entries) {
+            const sessionDir = join(subagentSessionsBase, entry.name);
+            try {
+                let isDirectory = entry.isDirectory();
+                if (!isDirectory && entry.isSymbolicLink()) {
+                    isDirectory = statSync(sessionDir).isDirectory();
+                }
+                if (!isDirectory)
+                    continue;
+                const canonicalSessionDir = canonicalExistingPath(sessionDir);
+                if (seenSessionDirs.has(canonicalSessionDir))
+                    continue;
+                seenSessionDirs.add(canonicalSessionDir);
+                const sessionFiles = discoverSessionFiles(sessionDir, entry.name, { throwOnOperationalError: true });
+                if (sessionFiles.length === 0)
+                    continue;
+                let sessionFile;
+                let header;
+                for (const candidateFile of sessionFiles) {
+                    const candidateHeader = parseSessionHeader(candidateFile);
+                    if (candidateHeader?.type !== "session" || typeof candidateHeader.parentSession !== "string")
+                        continue;
+                    if (!parentSessionMatches(candidateHeader.parentSession, parentSessionFile))
+                        continue;
+                    const canonicalSessionFile = canonicalExistingPath(candidateFile);
+                    if (seenSessionFiles.has(canonicalSessionFile))
+                        break;
+                    seenSessionFiles.add(canonicalSessionFile);
+                    sessionFile = candidateFile;
+                    header = candidateHeader;
+                    break;
+                }
+                if (!sessionFile || !header || hasRegisteredSession(sessionDir, sessionFile))
+                    continue;
+                const baseAgentId = `${REHYDRATED_AGENT_ID_PREFIX}${entry.name}`;
+                let agentId = baseAgentId;
+                let suffix = 2;
+                while (backgroundAgentRegistry.has(agentId)) {
+                    agentId = `${baseAgentId}-${suffix++}`;
+                }
+                const statusFile = sessionFiles[sessionFiles.length - 1] ?? sessionFile;
+                const agentType = typeof header.agentType === "string" && header.agentType.trim() ? header.agentType : "agent";
+                const taskSummary = findFirstUserMessageSummary(sessionFile) ?? `${agentType} (${entry.name})`;
+                backgroundAgentRegistry.set(agentId, {
+                    agentId,
+                    agentType,
+                    taskSummary,
+                    startedAt: parseStartedAt(header, sessionFile),
+                    status: inferCompletedSessionStatus(statusFile),
+                    sessionDir,
+                    sessionFile,
+                    cwd: typeof header.cwd === "string" ? header.cwd : undefined,
+                });
+                registered++;
+            }
+            catch (err) {
+                if (shouldSkipRehydrationFilesystemError(err, isPrimaryRoot, `entry ${sessionDir}`))
+                    continue;
+                throw err;
+            }
+        }
     }
     return registered;
 }
@@ -1803,6 +1877,7 @@ export function formatSingleResult(result) {
     return text;
 }
 export function createSubagentToolDefinition(cwd, options) {
+    const subagentSessionsBase = options?.subagentSessionsDir ?? getSubagentSessionsDir();
     const onBackgroundStart = options?.onBackgroundStart;
     const onBackgroundComplete = options?.onBackgroundComplete;
     const onBackgroundEvent = options?.onBackgroundEvent;
@@ -2016,7 +2091,6 @@ export function createSubagentToolDefinition(cwd, options) {
                     return agentId;
                 };
                 // Helper to launch a single background task
-                const subagentSessionsBase = getSubagentSessionsDir();
                 const launchBackgroundTask = (agentName, task, taskLabel, taskCwd, modelOverride, thinkingOverride) => {
                     const resolvedCwd = taskCwd ?? cwd;
                     // Each background agent gets its own session subdirectory