@ian2018cs/agenthub 0.1.76 → 0.1.78

package/server/routes/agents.js

@@ -159,6 +159,217 @@ function parseYamlMcps(yamlContent) {
   return mcps;
 }
 
+/**
+ * Parse git_repos list from agent.yaml content string.
+ * Returns array of { name, repo, branch }.
+ */
+function parseYamlGitRepos(yamlContent) {
+  const repos = [];
+  const section = yamlContent.match(/^git_repos:\s*\n((?:[ \t]+.+\n?)*)/m);
+  if (!section) return repos;
+  const lines = section[1].split('\n');
+  let current = null;
+  for (const line of lines) {
+    const nameMatch = line.match(/^\s+-\s+name:\s*["']?(.+?)["']?\s*$/);
+    if (nameMatch) {
+      if (current) repos.push(current);
+      current = { name: nameMatch[1].trim(), repo: '', branch: 'main' };
+    }
+    const repoMatch = line.match(/^\s+repo:\s*["']?(.+?)["']?\s*$/);
+    if (repoMatch && current) current.repo = repoMatch[1].trim();
+    const branchMatch = line.match(/^\s+branch:\s*["']?(.+?)["']?\s*$/);
+    if (branchMatch && current) current.branch = branchMatch[1].trim();
+  }
+  if (current) repos.push(current);
+  return repos;
+}
+
+/**
+ * Run a git command and return stdout (for reading git info).
+ */
+function runGitOutput(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const opts = { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } };
+    if (cwd) opts.cwd = cwd;
+    const proc = spawn('git', args, opts);
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', d => { stdout += d.toString(); });
+    proc.stderr.on('data', d => { stderr += d.toString(); });
+    proc.on('close', code => {
+      if (code === 0) resolve(stdout.trim());
+      else reject(new Error(stderr || `git ${args[0]} failed with code ${code}`));
+    });
+    proc.on('error', err => reject(err));
+  });
+}
+
+/**
+ * Scan immediate subdirectories of a project for git repositories.
+ * Returns array of { name, repo, branch }.
+ */
+async function scanGitRepos(projectPath) {
+  const results = [];
+  const SKIP_DIRS = new Set(['node_modules', '.claude', '.git', '.vscode', '__pycache__', '.next', 'dist', 'build']);
+
+  let entries;
+  try {
+    entries = await fs.readdir(projectPath, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+
+    const subdirPath = path.join(projectPath, entry.name);
+
+    // Check if this is a git repo (has .git directory)
+    try {
+      await fs.access(path.join(subdirPath, '.git'));
+    } catch {
+      continue;
+    }
+
+    // Get remote URL
+    let repoUrl;
+    try {
+      repoUrl = await runGitOutput(['remote', 'get-url', 'origin'], subdirPath);
+    } catch {
+      continue; // Skip repos without remote
+    }
+    if (!repoUrl) continue;
+
+    // Get current branch
+    let branch;
+    try {
+      branch = await runGitOutput(['branch', '--show-current'], subdirPath);
+    } catch {
+      try {
+        branch = await runGitOutput(['rev-parse', '--abbrev-ref', 'HEAD'], subdirPath);
+      } catch {
+        branch = 'main';
+      }
+    }
+    if (!branch) branch = 'main';
+
+    results.push({ name: entry.name, repo: repoUrl, branch });
+  }
+
+  return results;
+}
+
+/**
+ * Get the shared git repo path for a given repo URL and branch.
+ * Path structure: data/git-repo/{owner}/{repo}/{branch}/
+ */
+function getSharedGitRepoPath(repoUrl, branch) {
+  const parsed = parseGitUrl(repoUrl);
+  if (!parsed) return null;
+  const publicPaths = getPublicPaths();
+  return path.join(publicPaths.gitRepoDir, parsed.owner, parsed.repo, branch);
+}
+
+/**
+ * Ensure a shared git repo exists at data/git-repo/{owner}/{repo}/{branch}/.
+ * - If target exists: fetch + checkout + pull (reset on conflict)
+ * - If target doesn't exist but same repo other branch exists: copy + fetch + checkout
+ * - If completely new: clone + checkout
+ * Returns the local path to the shared repo.
+ */
+async function ensureSharedGitRepo(repoUrl, branch) {
+  const parsed = parseGitUrl(repoUrl);
+  if (!parsed) throw new Error(`Cannot parse git URL: ${repoUrl}`);
+
+  const publicPaths = getPublicPaths();
+  const targetPath = path.join(publicPaths.gitRepoDir, parsed.owner, parsed.repo, branch);
+  const repoParentDir = path.join(publicPaths.gitRepoDir, parsed.owner, parsed.repo);
+
+  // Case 1: Target path already exists — update it
+  try {
+    await fs.access(targetPath);
+    console.log(`[GitRepo] Updating existing shared repo at ${targetPath}`);
+    try {
+      await runGit(['fetch', 'origin'], targetPath);
+    } catch (e) {
+      console.warn(`[GitRepo] fetch failed: ${e.message}`);
+    }
+    await runGit(['checkout', branch], targetPath);
+    try {
+      await runGit(['pull', 'origin', branch], targetPath);
+    } catch {
+      // Pull failed (conflict) — reset and retry
+      console.warn(`[GitRepo] pull conflict, resetting...`);
+      await runGit(['checkout', '.'], targetPath);
+      await runGit(['clean', '-fd'], targetPath);
+      await runGit(['pull', 'origin', branch], targetPath);
+    }
+    return targetPath;
+  } catch {
+    // Target doesn't exist — continue to Case 2/3
+  }
+
+  // Case 2: Same repo, different branch exists — copy + fetch + checkout
+  try {
+    await fs.access(repoParentDir);
+    const branches = await fs.readdir(repoParentDir, { withFileTypes: true });
+    const existingBranch = branches.find(b => b.isDirectory());
+    if (existingBranch) {
+      const existingPath = path.join(repoParentDir, existingBranch.name);
+      console.log(`[GitRepo] Copying from existing branch "${existingBranch.name}" to "${branch}"`);
+      await fs.mkdir(targetPath, { recursive: true });
+      await fs.cp(existingPath, targetPath, { recursive: true });
+      try {
+        await runGit(['fetch', 'origin'], targetPath);
+      } catch (e) {
+        console.warn(`[GitRepo] fetch after copy failed: ${e.message}`);
+      }
+      await runGit(['checkout', branch], targetPath);
+      try {
+        await runGit(['pull', 'origin', branch], targetPath);
+      } catch {
+        await runGit(['checkout', '.'], targetPath);
+        await runGit(['clean', '-fd'], targetPath);
+        await runGit(['pull', 'origin', branch], targetPath);
+      }
+      return targetPath;
+    }
+  } catch {
+    // No existing branches — continue to Case 3
+  }
+
+  // Case 3: Fresh clone
+  console.log(`[GitRepo] Cloning ${repoUrl} branch ${branch} to ${targetPath}`);
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await runGit(['clone', repoUrl, targetPath]);
+  await runGit(['checkout', branch], targetPath);
+  return targetPath;
+}
+
+/**
+ * Create a symlink from a project subdirectory to a shared git repo.
+ * Removes existing directory or symlink at the target location.
+ */
+async function linkGitRepoToProject(projectDir, subdirName, sharedRepoPath) {
+  const linkPath = path.join(projectDir, subdirName);
+
+  // Remove existing directory or symlink
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (stat.isSymbolicLink()) {
+      await fs.unlink(linkPath);
+    } else if (stat.isDirectory()) {
+      await fs.rm(linkPath, { recursive: true, force: true });
+    }
+  } catch {
+    // Doesn't exist — fine
+  }
+
+  await fs.symlink(sharedRepoPath, linkPath);
+  console.log(`[GitRepo] Created symlink: ${linkPath} → ${sharedRepoPath}`);
+}
+
 /**
  * Ensure a skill repo is available for the user. Clone if needed.
  * Returns the local path to the skill directory inside the repo.
@@ -586,6 +797,20 @@ router.post('/install', async (req, res) => {
       }
     }
 
+    // Install git repo dependencies (clone/update shared repo + create symlink)
+    const gitRepoResults = [];
+    for (const gitRepo of agent.git_repos || []) {
+      if (!gitRepo.name || !gitRepo.repo) continue;
+      try {
+        const sharedPath = await ensureSharedGitRepo(gitRepo.repo, gitRepo.branch || 'main');
+        await linkGitRepoToProject(projectDir, gitRepo.name, sharedPath);
+        gitRepoResults.push({ name: gitRepo.name, success: true });
+      } catch (err) {
+        console.error(`[AgentInstall] Failed to install git repo "${gitRepo.name}":`, err.message);
+        gitRepoResults.push({ name: gitRepo.name, success: false, error: err.message });
+      }
+    }
+
     // Mark project as agent in project-config.json
     const config = await loadProjectConfig(userUuid);
     const projectKey = projectDir.replace(/\//g, '-');
@@ -597,7 +822,10 @@ router.post('/install', async (req, res) => {
         installedAt: new Date().toISOString(),
         isAgent: true,
         claudeMdHash,
-        installedFiles
+        installedFiles,
+        gitRepos: (agent.git_repos || []).filter(g => g.name && g.repo).map(g => ({
+          name: g.name, repo: g.repo, branch: g.branch || 'main'
+        }))
       }
     };
     await saveProjectConfig(config, userUuid);
@@ -606,7 +834,8 @@ router.post('/install', async (req, res) => {
       success: true,
       project: { ...project, agentInfo: config[projectKey].agentInfo },
       skills: skillResults,
-      mcps: mcpResults
+      mcps: mcpResults,
+      gitRepos: gitRepoResults
     });
   } catch (error) {
     console.error('Error installing agent:', error);
@@ -685,7 +914,10 @@ router.get('/preview', async (req, res) => {
     // Scan CLAUDE.md for referenced local files
     const refFiles = await scanClaudeMdRefs(projectPath);
 
-    res.json({ hasClaudeMd, skills, mcps, refFiles });
+    // Scan subdirectories for git repositories
+    const gitRepos = await scanGitRepos(projectPath);
+
+    res.json({ hasClaudeMd, skills, mcps, refFiles, gitRepos });
   } catch (error) {
     console.error('Error getting agent preview:', error);
     res.status(500).json({ error: 'Failed to get preview', details: error.message });
@@ -737,6 +969,11 @@ router.get('/project-files', async (req, res) => {
 
         if (entry.isDirectory()) {
           if (AGENT_SKIP_DIRS.has(entry.name)) continue;
+          // Skip directories that are git repositories (handled as git_repos dependencies)
+          try {
+            await fs.access(path.join(fullPath, '.git'));
+            continue; // Has .git → skip entire subtree
+          } catch {}
           await walk(fullPath, depth + 1);
         } else if (entry.isFile()) {
           if (entry.name === 'CLAUDE.md') continue;
@@ -1287,6 +1524,49 @@ router.post('/submissions/:id/approve', async (req, res) => {
         }
       }
 
+      // === C. Handle git repo dependencies ===
+      const yamlGitRepos = agentYamlContent ? parseYamlGitRepos(agentYamlContent) : [];
+      if (yamlGitRepos.length > 0) {
+        for (const gitRepo of yamlGitRepos) {
+          if (!gitRepo.name || !gitRepo.repo) continue;
+          try {
+            // Ensure shared git repo exists
+            const sharedPath = await ensureSharedGitRepo(gitRepo.repo, gitRepo.branch || 'main');
+            console.log(`[AgentApprove] Ensured shared git repo "${gitRepo.name}" at ${sharedPath}`);
+
+            // Replace submitter's original subdirectory with symlink to shared repo
+            if (submitterUuid) {
+              const submitterProjectDir = path.join(getUserPaths(submitterUuid).projectsDir, submission.agent_name);
+              try {
+                await linkGitRepoToProject(submitterProjectDir, gitRepo.name, sharedPath);
+                console.log(`[AgentApprove] Linked git repo "${gitRepo.name}" for submitter`);
+              } catch (e) {
+                console.warn(`[AgentApprove] Could not link git repo "${gitRepo.name}" for submitter:`, e.message);
+              }
+            }
+          } catch (e) {
+            console.error(`[AgentApprove] Failed to setup shared git repo "${gitRepo.name}":`, e.message);
+          }
+        }
+
+        // Update submitter's agentInfo with git repos
+        if (submitterUuid) {
+          try {
+            const submitterConfig = await loadProjectConfig(submitterUuid);
+            const submitterProjectDir = path.join(getUserPaths(submitterUuid).projectsDir, submission.agent_name);
+            const submitterKey = submitterProjectDir.replace(/\//g, '-');
+            if (submitterConfig[submitterKey]?.agentInfo) {
+              submitterConfig[submitterKey].agentInfo.gitRepos = yamlGitRepos.filter(g => g.name && g.repo).map(g => ({
+                name: g.name, repo: g.repo, branch: g.branch || 'main'
+              }));
+              await saveProjectConfig(submitterConfig, submitterUuid);
+            }
+          } catch (e) {
+            console.warn('[AgentApprove] Could not update submitter gitRepos config:', e.message);
+          }
+        }
+      }
+
       // Remove temporary migration directories from extractDir before publishing to agent repo
       await fs.rm(path.join(extractDir, '_skill_files'), { recursive: true, force: true });
       await fs.rm(path.join(extractDir, '_mcp_configs'), { recursive: true, force: true });
@@ -1390,6 +1670,54 @@ router.post('/submissions/:id/approve', async (req, res) => {
               entry.agentInfo.installedAt = new Date().toISOString();
               entry.agentInfo.claudeMdHash = newClaudeMdHash;
               entry.agentInfo.installedFiles = newInstalledFiles;
+
+              // Update git repo dependencies
+              if (publishedAgent) {
+                const newGitRepos = (publishedAgent.git_repos || []).filter(g => g.name && g.repo);
+                const oldGitRepos = entry.agentInfo.gitRepos || [];
+
+                // Build lookup maps
+                const oldByName = new Map(oldGitRepos.map(g => [g.name, g]));
+                const newByName = new Map(newGitRepos.map(g => [g.name, g]));
+
+                // Remove symlinks for deleted git repos
+                for (const old of oldGitRepos) {
+                  if (!newByName.has(old.name)) {
+                    try {
+                      const linkPath = path.join(projectDir, old.name);
+                      await fs.unlink(linkPath).catch(() => {});
+                      console.log(`[AgentApprove] Removed git repo symlink "${old.name}" for user ${user.uuid}`);
+                    } catch {}
+                  }
+                }
+
+                // Add/update git repos
+                for (const gitRepo of newGitRepos) {
+                  const old = oldByName.get(gitRepo.name);
+                  const branchChanged = !old || old.branch !== gitRepo.branch;
+                  const repoChanged = !old || old.repo !== gitRepo.repo;
+
+                  if (!old || branchChanged || repoChanged) {
+                    try {
+                      const sharedPath = await ensureSharedGitRepo(gitRepo.repo, gitRepo.branch || 'main');
+                      await linkGitRepoToProject(projectDir, gitRepo.name, sharedPath);
+                      console.log(`[AgentApprove] Updated git repo "${gitRepo.name}" for user ${user.uuid}`);
+                    } catch (e) {
+                      console.warn(`[AgentApprove] Failed to update git repo "${gitRepo.name}" for user ${user.uuid}:`, e.message);
+                    }
+                  } else {
+                    // Same repo + branch — just ensure shared repo is up to date
+                    try {
+                      await ensureSharedGitRepo(gitRepo.repo, gitRepo.branch || 'main');
+                    } catch {}
+                  }
+                }
+
+                entry.agentInfo.gitRepos = newGitRepos.map(g => ({
+                  name: g.name, repo: g.repo, branch: g.branch || 'main'
+                }));
+              }
+
               userUpdated = true;
             }
 

package/server/services/builtin-tools/background-task-pool.js

@@ -0,0 +1,316 @@
+/**
+ * BackgroundTaskPool — 后台任务进程池
+ *
+ * 管理 child_process.spawn 子进程，提供 per-user 和全局并发限制、
+ * 超时处理、输出截断，以及 EventEmitter 'task-complete' 事件。
+ *
+ * PendingResultQueue — 待投递结果队列
+ *
+ * 保存已完成但尚未投递给 agent 的任务结果，
+ * 按 userUuid:sessionId 分组，支持逐条出队。
+ */
+
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import crypto from 'crypto';
+
+// ─── 配置 ───
+
+const PER_USER_LIMIT   = parseInt(process.env.BG_TASK_PER_USER_LIMIT, 10) || 3;
+const GLOBAL_LIMIT     = parseInt(process.env.BG_TASK_GLOBAL_LIMIT, 10)    || 20;
+const DEFAULT_TIMEOUT  = parseInt(process.env.BG_TASK_DEFAULT_TIMEOUT, 10) || 600_000;   // 10 min
+const MAX_TIMEOUT      = parseInt(process.env.BG_TASK_MAX_TIMEOUT, 10)     || 1_800_000; // 30 min
+const MAX_OUTPUT_BYTES = parseInt(process.env.BG_TASK_MAX_OUTPUT, 10)      || 102_400;   // 100 KB
+
+// 已完成任务保留时长（30 min），之后自动清理引用
+const COMPLETED_TTL_MS = 30 * 60 * 1000;
+// 清理扫描间隔（5 min）
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+// ─── BackgroundTaskPool ───
+
+class BackgroundTaskPool extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, Task>} 所有任务（running + completed 未清理） */
+    this.tasks = new Map();
+    /** @type {Map<string, number>} 每用户当前 running 计数 */
+    this.userTaskCount = new Map();
+    /** 全局 running 计数 */
+    this.runningCount = 0;
+
+    // 定期清理已完成任务
+    this._cleanupTimer = setInterval(() => this._cleanupCompleted(), CLEANUP_INTERVAL_MS);
+    if (this._cleanupTimer.unref) this._cleanupTimer.unref();
+  }
+
+  /**
+   * 提交一个后台任务
+   * @returns {Task} 返回任务对象（status='running'）
+   * @throws {Error} 超出并发限制
+   */
+  submit({ userUuid, sessionId, cwd, command, timeout, label }) {
+    // 并发检查
+    const userCount = this.userTaskCount.get(userUuid) || 0;
+    if (userCount >= PER_USER_LIMIT) {
+      throw new Error(`每用户最多同时运行 ${PER_USER_LIMIT} 个后台任务（当前 ${userCount} 个）`);
+    }
+    if (this.runningCount >= GLOBAL_LIMIT) {
+      throw new Error(`系统后台任务已满（最多 ${GLOBAL_LIMIT} 个）`);
+    }
+
+    // 规范化 timeout
+    const timeoutMs = Math.min(Math.max(timeout || DEFAULT_TIMEOUT, 1000), MAX_TIMEOUT);
+
+    const id = this._genId();
+    const task = {
+      id,
+      userUuid,
+      sessionId,
+      cwd,
+      command,
+      label: label || command.slice(0, 80),
+      timeout: timeoutMs,
+      status: 'running',
+      startTime: Date.now(),
+      childProcess: null,
+      stdout: '',
+      stderr: '',
+      exitCode: null,
+      signal: null,
+      truncated: false,
+      _stdoutTruncated: false,
+      _stderrTruncated: false,
+    };
+
+    // 启动子进程
+    const child = spawn('sh', ['-c', command], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+    task.childProcess = child;
+
+    // 收集 stdout
+    child.stdout.on('data', (chunk) => {
+      if (task._stdoutTruncated) return;
+      const str = chunk.toString();
+      if (task.stdout.length + str.length > MAX_OUTPUT_BYTES) {
+        task.stdout += str.slice(0, MAX_OUTPUT_BYTES - task.stdout.length);
+        task._stdoutTruncated = true;
+        task.truncated = true;
+      } else {
+        task.stdout += str;
+      }
+    });
+
+    // 收集 stderr
+    child.stderr.on('data', (chunk) => {
+      if (task._stderrTruncated) return;
+      const str = chunk.toString();
+      if (task.stderr.length + str.length > MAX_OUTPUT_BYTES) {
+        task.stderr += str.slice(0, MAX_OUTPUT_BYTES - task.stderr.length);
+        task._stderrTruncated = true;
+        task.truncated = true;
+      } else {
+        task.stderr += str;
+      }
+    });
+
+    // 进程结束
+    child.on('close', (code, sig) => {
+      if (task.status !== 'running') return; // 已被 timeout/cancel 处理
+      task.status = 'completed';
+      task.exitCode = code;
+      task.signal = sig;
+      this._onFinished(task);
+    });
+
+    child.on('error', (err) => {
+      if (task.status !== 'running') return;
+      task.status = 'failed';
+      task.stderr += `\n[spawn error] ${err.message}`;
+      this._onFinished(task);
+    });
+
+    // 超时定时器
+    task._timeoutTimer = setTimeout(() => {
+      if (task.status !== 'running') return;
+      task.status = 'timeout';
+      // 先 SIGTERM
+      try { child.kill('SIGTERM'); } catch (_) { /* ignore */ }
+      // 5s 后 SIGKILL
+      task._killTimer = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch (_) { /* ignore */ }
+      }, 5000);
+      this._onFinished(task);
+    }, timeoutMs);
+
+    // 注册
+    this.tasks.set(id, task);
+    this.userTaskCount.set(userUuid, userCount + 1);
+    this.runningCount++;
+
+    console.log(`[BgTask] Task ${id} started for user ${userUuid}, session ${sessionId}: ${task.label}`);
+    return task;
+  }
+
+  /**
+   * 取消一个任务
+   * @returns {boolean} 是否成功取消
+   */
+  cancel(taskId, userUuid) {
+    const task = this.tasks.get(taskId);
+    if (!task) return false;
+    if (task.userUuid !== userUuid) return false; // 不允许跨用户取消
+    if (task.status !== 'running') return false;
+
+    task.status = 'killed';
+    try { task.childProcess.kill('SIGTERM'); } catch (_) { /* ignore */ }
+    setTimeout(() => {
+      try { task.childProcess.kill('SIGKILL'); } catch (_) { /* ignore */ }
+    }, 3000);
+
+    this._onFinished(task);
+    return true;
+  }
+
+  /** 获取单个任务 */
+  getTask(taskId) {
+    return this.tasks.get(taskId) || null;
+  }
+
+  /** 获取用户所有任务 */
+  getUserTasks(userUuid) {
+    return [...this.tasks.values()].filter(t => t.userUuid === userUuid);
+  }
+
+  /** 获取指定 session 的任务 */
+  getSessionTasks(userUuid, sessionId) {
+    return [...this.tasks.values()].filter(t => t.userUuid === userUuid && t.sessionId === sessionId);
+  }
+
+  /** 统计信息 */
+  getStats() {
+    return {
+      running: this.runningCount,
+      total: this.tasks.size,
+      perUser: Object.fromEntries(this.userTaskCount),
+    };
+  }
+
+  // ─── 内部方法 ───
+
+  _onFinished(task) {
+    // 清理定时器
+    if (task._timeoutTimer) { clearTimeout(task._timeoutTimer); task._timeoutTimer = null; }
+    if (task._killTimer) { clearTimeout(task._killTimer); task._killTimer = null; }
+
+    // 更新计数
+    const prev = this.userTaskCount.get(task.userUuid) || 1;
+    if (prev <= 1) {
+      this.userTaskCount.delete(task.userUuid);
+    } else {
+      this.userTaskCount.set(task.userUuid, prev - 1);
+    }
+    this.runningCount = Math.max(0, this.runningCount - 1);
+
+    // 释放进程引用
+    task.childProcess = null;
+
+    // 记录完成时间
+    task.endTime = Date.now();
+
+    console.log(`[BgTask] Task ${task.id} finished: status=${task.status}, exitCode=${task.exitCode}, duration=${task.endTime - task.startTime}ms`);
+
+    // 发出事件
+    this.emit('task-complete', task);
+  }
+
+  _cleanupCompleted() {
+    const now = Date.now();
+    for (const [id, task] of this.tasks) {
+      if (task.status !== 'running' && task.endTime && now - task.endTime > COMPLETED_TTL_MS) {
+        this.tasks.delete(id);
+      }
+    }
+  }
+
+  _genId() {
+    return 'bg_' + crypto.randomBytes(6).toString('hex');
+  }
+}
+
+// ─── PendingResultQueue ───
+
+/** @type {Map<string, object[]>} key = "userUuid:sessionId" */
+const pendingResults = new Map();
+
+function _key(userUuid, sessionId) {
+  return `${userUuid}:${sessionId}`;
+}
+
+/**
+ * 将已完成的任务结果加入待投递队列
+ */
+export function enqueueResult(userUuid, sessionId, taskResult) {
+  const k = _key(userUuid, sessionId);
+  if (!pendingResults.has(k)) pendingResults.set(k, []);
+  pendingResults.get(k).push({
+    id: taskResult.id,
+    command: taskResult.command,
+    label: taskResult.label,
+    status: taskResult.status,
+    exitCode: taskResult.exitCode,
+    signal: taskResult.signal,
+    stdout: taskResult.stdout,
+    stderr: taskResult.stderr,
+    truncated: taskResult.truncated,
+    startTime: taskResult.startTime,
+    endTime: taskResult.endTime,
+    cwd: taskResult.cwd,
+    sessionId: taskResult.sessionId,
+    userUuid: taskResult.userUuid,
+  });
+}
+
+/**
+ * 从队列取出一条结果（FIFO）
+ */
+export function dequeueResult(userUuid, sessionId) {
+  const k = _key(userUuid, sessionId);
+  const q = pendingResults.get(k);
+  if (!q || q.length === 0) return null;
+  const item = q.shift();
+  if (q.length === 0) pendingResults.delete(k);
+  return item;
+}
+
+/**
+ * 检查是否有待投递结果
+ */
+export function hasResults(userUuid, sessionId) {
+  const k = _key(userUuid, sessionId);
+  const q = pendingResults.get(k);
+  return q && q.length > 0;
+}
+
+/**
+ * 获取用户所有 session 的待投递结果
+ * @returns {Array<{sessionId: string, results: object[]}>}
+ */
+export function getAllPendingForUser(userUuid) {
+  const out = [];
+  for (const [k, results] of pendingResults) {
+    if (k.startsWith(userUuid + ':')) {
+      const sessionId = k.slice(userUuid.length + 1);
+      out.push({ sessionId, results: [...results] });
+    }
+  }
+  return out;
+}
+
+// ─── 单例导出 ───
+
+export const backgroundTaskPool = new BackgroundTaskPool();
+export default backgroundTaskPool;