u-foo 1.7.4 → 1.8.0

package/src/chat/index.js

@@ -9,7 +9,6 @@ const {
   saveConfig,
   normalizeLaunchMode,
   normalizeAgentProvider,
-  normalizeAssistantEngine,
 } = require("../config");
 const { socketPath, isRunning } = require("../daemon");
 const UfooInit = require("../init");
@@ -46,11 +45,19 @@ const { createTerminalAdapterRouter } = require("../terminal/adapterRouter");
 const { createDaemonTransport } = require("./daemonTransport");
 const { listProjectRuntimes, resolveRuntimeDir } = require("../projects/registry");
 const { canonicalProjectRoot, buildProjectId } = require("../projects/projectId");
+const { loadTemplateRegistry } = require("../group/templates");
 const {
   sortProjectRuntimes,
   parseTimestampMs,
   filterVisibleProjectRuntimes,
 } = require("./projectRuntimes");
+const { isGlobalControllerProjectRoot, resolveGlobalControllerProjectRoot } = require("../globalMode");
+const {
+  DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS,
+  setTransientAgentState: setTransientAgentStateValue,
+  getTransientAgentState,
+  pruneTransientAgentStates,
+} = require("./transientAgentState");
 
 const MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal"];
 
@@ -64,10 +71,25 @@ async function runChat(projectRoot, options = {}) {
     activeProjectRoot = path.resolve(projectRoot || process.cwd());
   }
 
-  if (!fs.existsSync(getUfooPaths(projectRoot).ufooDir)) {
+  let globalScope = globalMode ? "controller" : "project";
+
+  const runtimePaths = getUfooPaths(projectRoot);
+  const contextIndexFile = path.join(runtimePaths.ufooDir, "context", "decisions.jsonl");
+  const needsGlobalControllerBootstrap = globalMode && (
+    !fs.existsSync(runtimePaths.ufooDir)
+    || !fs.existsSync(runtimePaths.busDir)
+    || !fs.existsSync(runtimePaths.agentDir)
+    || !fs.existsSync(contextIndexFile)
+  );
+
+  if (needsGlobalControllerBootstrap || !fs.existsSync(runtimePaths.ufooDir)) {
     const repoRoot = path.join(__dirname, "..", "..");
     const init = new UfooInit(repoRoot);
-    await init.init({ modules: "context,bus", project: projectRoot });
+    await init.init({
+      modules: "context,bus",
+      project: projectRoot,
+      controllerMode: globalMode,
+    });
   }
 
   // Ensure subscriber ID exists for chat (persistent across restarts)
@@ -104,7 +126,6 @@ async function runChat(projectRoot, options = {}) {
   const config = loadConfig(projectRoot);
   let launchMode = config.launchMode;
   let agentProvider = config.agentProvider;
-  let assistantEngine = normalizeAssistantEngine(config.assistantEngine);
   let autoResume = config.autoResume !== false;
   let cronTasks = [];
 
@@ -530,6 +551,14 @@ async function runChat(projectRoot, options = {}) {
     completionPanel,
     promptBox,
     commandRegistry: COMMAND_REGISTRY,
+    getGroupTemplateCandidates: () => {
+      const registry = loadTemplateRegistry(activeProjectRoot);
+      return registry.templates.map((item) => ({
+        alias: item.alias,
+        name: item.templateName || item.templateId || "",
+        source: item.source || "",
+      }));
+    },
     getMentionCandidates: () => activeAgents.map((id) => ({
       id,
       label: getAgentLabel(id),
@@ -560,6 +589,14 @@ async function runChat(projectRoot, options = {}) {
     getSelectedAgentIndex: () => selectedAgentIndex,
     getActiveAgents: () => activeAgents,
     getTargetAgent: () => targetAgent,
+    getGlobalScope: () => globalScope,
+    clearTargetAgent,
+    exitProjectScope: () => {
+      setGlobalScope("controller").catch((err) => {
+        const message = err && err.message ? err.message : String(err || "scope switch failed");
+        logMessage("error", `{white-fg}✗{/white-fg} Scope switch failed: ${escapeBlessed(message)}`);
+      });
+    },
     requestCloseAgent,
     logMessage,
     isSuppressKeypress: () => pasteController.isSuppressKeypress(),
@@ -675,7 +712,7 @@ async function runChat(projectRoot, options = {}) {
   let selectedAgentIndex = -1;  // -1 = not in dashboard selection mode
   let targetAgent = null;       // Selected agent for direct messaging
   let focusMode = "input";      // "input" or "dashboard"
-  let dashboardView = "agents"; // "projects" | "agents" | "mode" | "provider" | "assistant" | "cron"
+  let dashboardView = "agents"; // "projects" | "agents" | "mode" | "provider" | "cron"
   let reportPendingTotal = 0;
   let selectedModeIndex = Math.max(0, MODE_OPTIONS.indexOf(launchMode));
   const providerOptions = [
@@ -684,31 +721,21 @@ async function runChat(projectRoot, options = {}) {
     { label: "ucode", value: "ucode" },
   ];
   let selectedProviderIndex = Math.max(0, providerOptions.findIndex((opt) => opt.value === agentProvider));
-  const assistantOptions = [
-    { label: "auto", value: "auto" },
-    { label: "codex", value: "codex" },
-    { label: "claude", value: "claude" },
-    { label: "ucode", value: "ufoo" },
-  ];
-  let selectedAssistantIndex = Math.max(
-    0,
-    assistantOptions.findIndex((opt) => opt.value === assistantEngine)
-  );
   const resumeOptions = [
     { label: "Resume previous session", value: true },
     { label: "Start new session", value: false },
   ];
   let selectedResumeIndex = autoResume ? 0 : 1;
+  let selectedCronIndex = -1;
   const DASH_HINTS = {
     agents: "←/→ select · Enter · ↓ mode · ↑ back",
     agentsGlobal: "←/→ select · Enter · ↓ mode · ↑ projects",
     agentsEmpty: "↓ mode · ↑ back",
     mode: "←/→ select · Enter · ↓ provider · ↑ back",
-    provider: "←/→ select · Enter · ↓ assistant · ↑ back",
-    assistant: "←/→ select · Enter · ↓ cron · ↑ back",
-    cron: "Ctrl+X close · ↑ back",
+    provider: "←/→ select · Enter · ↓ cron · ↑ back",
+    cron: "←/→ switch · Ctrl+X stop · ↑ back",
     resume: "",
-    projects: "Use /project switch <index|path>",
+    projects: "Use /open <path> or /project switch <index|path>",
     projectsFocus: "←/→ switch · Ctrl+X close · ↓ second row · Enter confirm · ↑ back",
     projectsEmpty: "Run ufoo chat or ufoo daemon start in project directories",
   };
@@ -939,9 +966,13 @@ async function runChat(projectRoot, options = {}) {
       rows = [];
     }
     rows = filterVisibleProjectRuntimes(rows);
+    if (globalMode) {
+      rows = rows.filter((row) => !isGlobalControllerProjectRoot(resolveRuntimeProjectRoot(row)));
+    }
     const normalizedActive = String(activeProjectRoot || "");
     if (
       normalizedActive
+      && !(globalMode && isGlobalControllerProjectRoot(normalizedActive))
       && !rows.some((row) => resolveRuntimeProjectRoot(row) === normalizedActive)
     ) {
       rows.unshift({
@@ -1002,18 +1033,24 @@ async function runChat(projectRoot, options = {}) {
   }
 
   function updatePromptBox() {
-    if (targetAgent) {
-      const label = getAgentLabel(targetAgent);
-      promptBox.setContent(`>@${label}`);
-      promptBox.width = label.length + 3;  // >@name + spacer
-      input.left = promptBox.width;
-      input.width = `100%-${promptBox.width}`;
-    } else {
-      promptBox.setContent(">");
-      promptBox.width = 2;
-      input.left = 2;
-      input.width = "100%-2";
+    // Determine scope prefix (only in global mode)
+    let prefix = "";
+    if (globalMode && globalScope === "controller") {
+      prefix = "g";
+    } else if (globalMode && globalScope === "project") {
+      prefix = truncateText(path.basename(activeProjectRoot), 10, "");
     }
+
+    // Build content: [prefix]>[>@agent]
+    const content = targetAgent
+      ? `${prefix}>@${getAgentLabel(targetAgent)}`
+      : `${prefix}>`;
+
+    promptBox.setContent(content);
+    promptBox.width = content.length + 1;  // content + spacer
+    input.left = promptBox.width;
+    input.width = `100%-${promptBox.width}`;
+
     if (!input.parent || !promptBox.parent) return;
     resizeInput();
     if (typeof input._updateCursor === "function") {
@@ -1081,12 +1118,6 @@ async function runChat(projectRoot, options = {}) {
     }
   }
 
-  function setAssistantEngine(value) {
-    if (settingsController) {
-      settingsController.setAssistantEngine(value);
-    }
-  }
-
   function setAutoResume(value) {
     if (settingsController) {
       settingsController.setAutoResume(value);
@@ -1103,7 +1134,6 @@ async function runChat(projectRoot, options = {}) {
     saveConfig,
     normalizeLaunchMode,
     normalizeAgentProvider,
-    normalizeAssistantEngine,
     fsModule: fs,
     getUfooPaths,
     logMessage,
@@ -1124,14 +1154,6 @@ async function runChat(projectRoot, options = {}) {
     setSelectedProviderIndex: (value) => {
       selectedProviderIndex = value;
     },
-    getAssistantEngine: () => assistantEngine,
-    setAssistantEngineState: (value) => {
-      assistantEngine = value;
-    },
-    setSelectedAssistantIndex: (value) => {
-      selectedAssistantIndex = value;
-    },
-    assistantOptions,
     providerOptions,
     modeOptions: MODE_OPTIONS,
     getAutoResume: () => autoResume,
@@ -1154,6 +1176,7 @@ async function runChat(projectRoot, options = {}) {
   function renderDashboard() {
     const computed = computeDashboardContent({
       globalMode,
+      globalScope,
       focusMode,
       dashboardView,
       activeAgents,
@@ -1175,20 +1198,19 @@ async function runChat(projectRoot, options = {}) {
             : "";
         }
         if (metaState) return metaState;
-        const transientState = transientAgentStateMap.get(agentId);
-        return typeof transientState === "string" ? transientState : "";
+        return getTransientAgentState(transientAgentStateMap, agentId, {
+          ttlMs: DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS,
+        });
       },
       launchMode,
       agentProvider,
-      assistantEngine,
       autoResume,
       selectedModeIndex,
       selectedProviderIndex,
-      selectedAssistantIndex,
       selectedResumeIndex,
+      selectedCronIndex,
       cronTasks,
       providerOptions,
-      assistantOptions,
       resumeOptions,
       pendingReports: reportPendingTotal,
       dashHints: DASH_HINTS,
@@ -1228,20 +1250,19 @@ async function runChat(projectRoot, options = {}) {
 
   function updateDashboard(status) {
     activeAgents = status.active || [];
-    if (transientAgentStateMap.size > 0) {
-      const activeSet = new Set(activeAgents);
-      for (const id of transientAgentStateMap.keys()) {
-        if (!activeSet.has(id)) {
-          transientAgentStateMap.delete(id);
-        }
-      }
-    }
+    pruneTransientAgentStates(transientAgentStateMap, activeAgents, {
+      ttlMs: DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS,
+    });
     if (globalMode) {
       refreshProjectRuntimes();
     }
-    reportPendingTotal = Number.isFinite(status?.reports?.pending_total)
+    const publicPending = Number.isFinite(status?.reports?.pending_total)
       ? status.reports.pending_total
       : 0;
+    const controllerPending = Number.isFinite(status?.controller?.pending_total)
+      ? status.controller.pending_total
+      : 0;
+    reportPendingTotal = publicPending + controllerPending;
     cronTasks = Array.isArray(status?.cron?.tasks) ? status.cron.tasks : [];
     const metaList = Array.isArray(status.active_meta) ? status.active_meta : [];
     let fallbackMap = null;
@@ -1317,6 +1338,12 @@ async function runChat(projectRoot, options = {}) {
           selectedAgentIndex = 0;
         }
         clampAgentWindow();
+      } else if (dashboardView === "cron") {
+        if (cronTasks.length === 0) {
+          selectedCronIndex = -1;
+        } else if (selectedCronIndex < 0 || selectedCronIndex >= cronTasks.length) {
+          selectedCronIndex = Math.max(0, Math.min(selectedCronIndex, cronTasks.length - 1));
+        }
       }
     }
     syncTargetFromSelection();
@@ -1329,7 +1356,14 @@ async function runChat(projectRoot, options = {}) {
     dashboardView = globalMode ? "projects" : "agents";
     if (globalMode) {
       refreshProjectRuntimes();
-      syncSelectedProjectToActive();
+      if (globalScope === "project") {
+        syncSelectedProjectToActive();
+      } else {
+        // Controller scope: no active project in list, init to 0 for navigation
+        if (projectRuntimes.length > 0 && (selectedProjectIndex < 0 || selectedProjectIndex >= projectRuntimes.length)) {
+          selectedProjectIndex = 0;
+        }
+      }
     } else {
       selectedAgentIndex = activeAgents.length > 0 ? 0 : -1;
       agentListWindowStart = 0;
@@ -1337,11 +1371,8 @@ async function runChat(projectRoot, options = {}) {
     }
     selectedModeIndex = Math.max(0, MODE_OPTIONS.indexOf(launchMode));
     selectedProviderIndex = Math.max(0, providerOptions.findIndex((opt) => opt.value === agentProvider));
-    selectedAssistantIndex = Math.max(
-      0,
-      assistantOptions.findIndex((opt) => opt.value === assistantEngine)
-    );
     selectedResumeIndex = autoResume ? 0 : 1;
+    selectedCronIndex = cronTasks.length > 0 ? 0 : -1;
     // Immediately set @target when first agent is selected.
     if (!globalMode && selectedAgentIndex >= 0 && selectedAgentIndex < activeAgents.length) {
       targetAgent = activeAgents[selectedAgentIndex];
@@ -1368,15 +1399,13 @@ async function runChat(projectRoot, options = {}) {
     activeAgentMetaMap: { get: () => activeAgentMetaMap },
     selectedModeIndex: { get: () => selectedModeIndex, set: (value) => { selectedModeIndex = value; } },
     selectedProviderIndex: { get: () => selectedProviderIndex, set: (value) => { selectedProviderIndex = value; } },
-    selectedAssistantIndex: { get: () => selectedAssistantIndex, set: (value) => { selectedAssistantIndex = value; } },
     selectedResumeIndex: { get: () => selectedResumeIndex, set: (value) => { selectedResumeIndex = value; } },
+    selectedCronIndex: { get: () => selectedCronIndex, set: (value) => { selectedCronIndex = value; } },
     launchMode: { get: () => launchMode },
     agentProvider: { get: () => agentProvider },
-    assistantEngine: { get: () => assistantEngine },
     autoResume: { get: () => autoResume },
     cronTasks: { get: () => cronTasks },
     providerOptions: { get: () => providerOptions },
-    assistantOptions: { get: () => assistantOptions },
     resumeOptions: { get: () => resumeOptions },
     agentOutputSuppressed: {
       get: () => getAgentOutputSuppressed(),
@@ -1415,12 +1444,24 @@ async function runChat(projectRoot, options = {}) {
     exitDashboardMode,
     setLaunchMode,
     setAgentProvider,
-    setAssistantEngine,
     setAutoResume,
     clampAgentWindow,
     clampAgentWindowWithSelection,
     requestProjectSwitch: requestProjectSwitchByIndex,
     requestCloseProject: requestCloseProjectByIndex,
+    requestCron: (payload = {}) => {
+      send({
+        type: IPC_REQUEST_TYPES.CRON,
+        ...payload,
+      });
+    },
+    setGlobalScope: (scope, targetProjectRoot) => {
+      setGlobalScope(scope, targetProjectRoot).catch((err) => {
+        const message = err && err.message ? err.message : String(err || "scope switch failed");
+        logMessage("error", `{white-fg}✗{/white-fg} Scope switch failed: ${escapeBlessed(message)}`);
+      });
+    },
+    getGlobalScope: () => globalScope,
     renderDashboard,
     renderAgentDashboard,
     renderScreen: () => screen.render(),
@@ -1557,7 +1598,7 @@ async function runChat(projectRoot, options = {}) {
     hasStream: (publisher) => streamTracker.hasStream(publisher),
     setTransientAgentState: (agentId, state) => {
       if (!agentId || !state) return;
-      transientAgentStateMap.set(agentId, state);
+      setTransientAgentStateValue(transientAgentStateMap, agentId, state);
     },
     clearTransientAgentState: (agentId) => {
       if (!agentId) return;
@@ -1669,6 +1710,7 @@ async function runChat(projectRoot, options = {}) {
       if (globalMode) {
         refreshProjectRuntimes();
         syncSelectedProjectToActive();
+        updatePromptBox();
         renderDashboard();
         screen.render();
       }
@@ -1684,6 +1726,44 @@ async function runChat(projectRoot, options = {}) {
     }
   }
 
+  async function setGlobalScope(scope, targetProjectRoot) {
+    if (!globalMode) return;
+
+    if (scope === "controller") {
+      if (globalScope === "controller") return;
+      const controllerRoot = resolveGlobalControllerProjectRoot();
+      if (activeProjectRoot !== controllerRoot) {
+        const result = await requestProjectSwitchByTarget(controllerRoot);
+        if (!result || !result.ok) {
+          const reason = (result && result.error) || "switch to controller failed";
+          logMessage("error", `{white-fg}✗{/white-fg} Scope switch failed: ${escapeBlessed(reason)}`);
+          return;
+        }
+      }
+      globalScope = "controller";
+      targetAgent = null;
+      updatePromptBox();
+      if (projectRuntimes.length > 0 && (selectedProjectIndex < 0 || selectedProjectIndex >= projectRuntimes.length)) {
+        selectedProjectIndex = 0;
+      }
+      renderDashboard();
+      screen.render();
+    } else if (scope === "project") {
+      if (!targetProjectRoot) return;
+      targetAgent = null;
+      const result = await requestProjectSwitchByTarget(targetProjectRoot);
+      if (!result || !result.ok) {
+        const reason = (result && result.error) || "switch to project failed";
+        logMessage("error", `{white-fg}✗{/white-fg} Scope switch failed: ${escapeBlessed(reason)}`);
+        return;
+      }
+      globalScope = "project";
+      updatePromptBox();
+      renderDashboard();
+      screen.render();
+    }
+  }
+
   let projectSwitching = false;
   let pendingProjectSwitchRoot = null;
   let projectSwitchDebounceTimer = null;
@@ -1854,9 +1934,12 @@ async function runChat(projectRoot, options = {}) {
     listProjects: () => listProjectRuntimes({ validate: true, cleanupTmp: true }),
     getCurrentProject: () => ({
       project_root: activeProjectRoot,
-      project_name: path.basename(activeProjectRoot),
+      project_name: globalMode && isGlobalControllerProjectRoot(activeProjectRoot)
+        ? "global-controller"
+        : path.basename(activeProjectRoot),
     }),
     switchProject: async ({ target } = {}) => requestProjectSwitchByTarget(target),
+    globalMode,
   });
 
   async function executeCommand(text) {
@@ -1972,13 +2055,6 @@ async function runChat(projectRoot, options = {}) {
     focusInput();
   });
 
-  // Escape in input mode only clears @target, never exits
-  input.key(["escape"], () => {
-    if (targetAgent) {
-      clearTargetAgent();
-    }
-  });
-
   focusInput();
   if (screen.program && typeof screen.program.decset === "function") {
     screen.program.decset(2004);
@@ -1996,6 +2072,7 @@ async function runChat(projectRoot, options = {}) {
   if (globalMode) {
     refreshProjectRuntimes();
   }
+  updatePromptBox();
   renderDashboard();
   resizeInput();
   requestStatus();

package/src/chat/inputListenerController.js

@@ -7,6 +7,9 @@ function createInputListenerController(options = {}) {
     getSelectedAgentIndex = () => -1,
     getActiveAgents = () => [],
     getTargetAgent = () => null,
+    getGlobalScope = () => "",
+    clearTargetAgent = () => {},
+    exitProjectScope = () => {},
     requestCloseAgent = () => {},
     logMessage = () => {},
     isSuppressKeypress = () => false,
@@ -238,6 +241,17 @@ function createInputListenerController(options = {}) {
     }
 
     if (keyName === "escape") {
+      // Layer 1: clear @target agent
+      if (getTargetAgent && getTargetAgent()) {
+        clearTargetAgent();
+        return;
+      }
+      // Layer 2: exit project scope → global scope
+      if (getGlobalScope && getGlobalScope() === "project") {
+        exitProjectScope();
+        return;
+      }
+      // Layer 3: existing behavior (cancel input)
       if (textarea && typeof textarea._done === "function") {
         textarea._done(null, null);
       }

package/src/chat/inputSubmitHandler.js

@@ -154,14 +154,18 @@ function createInputSubmitHandler(options = {}) {
       const choice = state.pending.disambiguate.candidates[idx - 1];
       if (choice) {
         queueStatusLine(`ufoo-agent processing (assigning ${choice.agent_id})`);
+        const requestMeta = {
+          source: "chat-dialog",
+          dispatch_default_injection_mode: "immediate",
+          allow_relevance_queue: true,
+        };
+        if (state.pending.project_root) {
+          requestMeta.force_project_root = state.pending.project_root;
+        }
         send({
           type: IPC_REQUEST_TYPES.PROMPT,
           text: `Use agent ${choice.agent_id} to handle: ${state.pending.original || "the request"}`,
-          request_meta: {
-            source: "chat-dialog",
-            dispatch_default_injection_mode: "immediate",
-            allow_relevance_queue: true,
-          },
+          request_meta: requestMeta,
         });
         state.pending = null;
       } else {

package/src/chat/settingsController.js

@@ -6,7 +6,6 @@ function createSettingsController(options = {}) {
     saveConfig = () => {},
     normalizeLaunchMode = (value) => value,
     normalizeAgentProvider = (value) => value,
-    normalizeAssistantEngine = (value) => value,
     fsModule,
     getUfooPaths = () => ({ agentDir: "" }),
     logMessage = () => {},
@@ -19,10 +18,6 @@ function createSettingsController(options = {}) {
     getAgentProvider = () => "codex-cli",
     setAgentProviderState = () => {},
     setSelectedProviderIndex = () => {},
-    getAssistantEngine = () => "auto",
-    setAssistantEngineState = () => {},
-    setSelectedAssistantIndex = () => {},
-    assistantOptions = [],
     providerOptions = [],
     modeOptions = [],
     getAutoResume = () => true,
@@ -41,14 +36,6 @@ function createSettingsController(options = {}) {
     return value === "claude-cli" ? "claude" : "codex";
   }
 
-  function assistantLabel(value) {
-    const normalized = normalizeAssistantEngine(value);
-    if (normalized === "codex") return "codex";
-    if (normalized === "claude") return "claude";
-    if (normalized === "ufoo") return "ufoo";
-    return "auto";
-  }
-
   function clearUfooAgentIdentity() {
     const agentDir = getUfooPaths(projectRoot).agentDir;
     const stateFile = path.join(agentDir, "ufoo-agent.json");
@@ -106,26 +93,11 @@ function createSettingsController(options = {}) {
     return true;
   }
 
-  function setAssistantEngine(engine) {
-    const next = normalizeAssistantEngine(engine);
-    if (next === getAssistantEngine()) return false;
-    setAssistantEngineState(next);
-    const idx = assistantOptions.findIndex((opt) => opt && opt.value === next);
-    setSelectedAssistantIndex(idx >= 0 ? idx : 0);
-    saveConfig(projectRoot, { assistantEngine: next });
-    logMessage("status", `{white-fg}⚙{/white-fg} assistant-engine: ${assistantLabel(next)}`);
-    renderDashboard();
-    renderScreen();
-    return true;
-  }
-
   return {
     providerLabel,
-    assistantLabel,
     clearUfooAgentIdentity,
     setLaunchMode,
     setAgentProvider,
-    setAssistantEngine,
     setAutoResume,
   };
 }

package/src/chat/transientAgentState.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS = 8000;
+
+function normalizeNow(now) {
+  return Number.isFinite(now) ? now : Date.now();
+}
+
+function setTransientAgentState(store, agentId, state, now = Date.now()) {
+  if (!(store instanceof Map)) return;
+  const id = String(agentId || "").trim();
+  const nextState = String(state || "").trim();
+  if (!id || !nextState) return;
+  store.set(id, {
+    state: nextState,
+    updatedAt: normalizeNow(now),
+  });
+}
+
+function getTransientAgentState(store, agentId, options = {}) {
+  if (!(store instanceof Map)) return "";
+  const id = String(agentId || "").trim();
+  if (!id) return "";
+  const entry = store.get(id);
+  if (!entry) return "";
+
+  const ttlMs = Number.isFinite(options.ttlMs)
+    ? Math.max(0, Math.trunc(options.ttlMs))
+    : DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS;
+  const now = normalizeNow(options.now);
+  const state = typeof entry === "string" ? entry : String(entry.state || "").trim();
+  const updatedAt = typeof entry === "object" && Number.isFinite(entry.updatedAt)
+    ? entry.updatedAt
+    : now;
+
+  if (!state) {
+    store.delete(id);
+    return "";
+  }
+  if (ttlMs > 0 && now - updatedAt > ttlMs) {
+    store.delete(id);
+    return "";
+  }
+  return state;
+}
+
+function pruneTransientAgentStates(store, activeAgentIds = [], options = {}) {
+  if (!(store instanceof Map)) return;
+  const activeSet = new Set(Array.isArray(activeAgentIds) ? activeAgentIds : []);
+  for (const id of Array.from(store.keys())) {
+    if (!activeSet.has(id)) {
+      store.delete(id);
+      continue;
+    }
+    getTransientAgentState(store, id, options);
+  }
+}
+
+module.exports = {
+  DEFAULT_TRANSIENT_AGENT_STATE_TTL_MS,
+  setTransientAgentState,
+  getTransientAgentState,
+  pruneTransientAgentStates,
+};