@ai-devkit/agent-manager 0.33.1 → 0.35.0

package/src/providers/claude/ClaudeSessionLocator.ts

@@ -6,6 +6,7 @@ import { matchProcessesToSessions, type MatchResult } from "../../utils/matching
 import {
   batchGetSessionFileBirthtimes,
   isDirectory,
+  isSafePathSegment,
   listJsonl,
   safeReaddir,
   safeStat,
@@ -130,6 +131,25 @@ export class ClaudeSessionLocator {
     return out;
   }
 
+  findHistoricalSessionFilesById(
+    sessionId: string,
+  ): Array<{ filePath: string; defaultCwd: string }> {
+    if (!isSafePathSegment(sessionId) || !isDirectory(this.projectsDir)) {
+      return [];
+    }
+
+    const matches: Array<{ filePath: string; defaultCwd: string }> = [];
+    for (const dirName of safeReaddir(this.projectsDir)) {
+      const projectDir = path.join(this.projectsDir, dirName);
+      if (!isDirectory(projectDir)) continue;
+
+      const filePath = path.join(projectDir, `${sessionId}.jsonl`);
+      if (!safeStat(filePath)?.isFile()) continue;
+      matches.push({ filePath, defaultCwd: dirName.replace(/-/g, "/") });
+    }
+    return matches;
+  }
+
   /**
    * Derive the Claude Code project directory for a given CWD.
    *

package/src/providers/codex/CodexAdapter.ts

@@ -95,6 +95,14 @@ export class CodexAdapter implements AgentAdapter {
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const sessionFile = this.createLocator().findSessionFileById(sessionId);
+    if (!sessionFile) return [];
+
+    const summary = this.parser.fileToSessionSummary(sessionFile.filePath);
+    return summary?.sessionId === sessionId ? [summary] : [];
+  }
+
   private async getCodexProcesses(context?: AgentDetectionContext): Promise<ProcessInfo[]> {
     const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
     const relevant = filterByProcessNames(snapshot, this.processNames);

package/src/providers/copilot/CopilotAdapter.ts

@@ -29,7 +29,7 @@ import {
 import { AgentRegistry, type RegistryEntry } from "../../utils/AgentRegistry.js";
 import { CopilotAgentMapper } from "./CopilotAgentMapper.js";
 import { CopilotSessionLocator } from "./CopilotSessionLocator.js";
-import { CopilotSessionParser } from "./CopilotSessionParser.js";
+import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
 
 export interface CopilotAdapterOptions {
   sessionStateDir?: string;
@@ -111,20 +111,36 @@ export class CopilotAdapter implements AgentAdapter {
       if (!session) continue;
       if (opts?.cwd !== undefined && session.projectPath !== opts.cwd) continue;
 
-      summaries.push({
-        type: this.type,
-        sessionId: session.sessionId,
-        cwd: session.projectPath,
-        firstUserMessage: session.firstUserMessage,
-        lastActive: session.lastActive,
-        startedAt: session.sessionStart,
-        sessionFilePath: session.eventsFilePath,
-      });
+      summaries.push(this.toSessionSummary(session));
     }
 
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const match = this.locator.findSessionDirById(sessionId);
+    if (match) {
+      const session = this.parser.readSessionDir(match.sessionDir, match.sessionId);
+      if (session?.sessionId === sessionId) {
+        return [this.toSessionSummary(session)];
+      }
+    }
+
+    return (await this.listSessions()).filter((session) => session.sessionId === sessionId);
+  }
+
+  private toSessionSummary(session: CopilotSession): SessionSummary {
+    return {
+      type: this.type,
+      sessionId: session.sessionId,
+      cwd: session.projectPath,
+      firstUserMessage: session.firstUserMessage,
+      lastActive: session.lastActive,
+      startedAt: session.sessionStart,
+      sessionFilePath: session.eventsFilePath,
+    };
+  }
+
   private applyWrapperRegistryName(
     agent: AgentInfo,
     processInfo: ProcessInfo,

package/src/providers/copilot/CopilotSessionLocator.ts

@@ -1,5 +1,5 @@
 import * as path from "path";
-import { isDirectory, safeReaddir } from "../../utils/session.js";
+import { isDirectory, isSafePathSegment, safeReaddir } from "../../utils/session.js";
 
 export interface CopilotLock {
   sessionDir: string;
@@ -39,6 +39,12 @@ export class CopilotSessionLocator {
     return sessionDirs;
   }
 
+  findSessionDirById(sessionId: string): CopilotSessionDir | null {
+    if (!isSafePathSegment(sessionId)) return null;
+    const sessionDir = path.join(this.sessionStateDir, sessionId);
+    return isDirectory(sessionDir) ? { sessionDir, sessionId } : null;
+  }
+
   discoverActiveLocks(): CopilotLock[] {
     const locks: CopilotLock[] = [];
     for (const { sessionDir, sessionId } of this.listSessionDirs()) {

package/src/providers/gemini/GeminiCliAdapter.ts

@@ -108,6 +108,14 @@ export class GeminiCliAdapter implements AgentAdapter {
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    for (const filePath of this.locator.discoverHistoricalSessionFiles()) {
+      const summary = this.parser.fileToSessionSummary(filePath);
+      if (summary?.sessionId === sessionId) return [summary];
+    }
+    return [];
+  }
+
   private async getGeminiProcesses(context?: AgentDetectionContext): Promise<ProcessInfo[]> {
     const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
     const relevant = filterByProcessNames(snapshot, this.processNames);

package/src/providers/grok/GrokAgentMapper.ts

@@ -0,0 +1,41 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import { GrokSessionParser, type GrokSession } from "./GrokSessionParser.js";
+
+export interface GrokSessionAgentInput {
+  session: GrokSession;
+  processInfo: ProcessInfo;
+}
+
+export class GrokAgentMapper {
+  constructor(private readonly parser: GrokSessionParser = new GrokSessionParser()) {}
+
+  mapSessionToAgent({ session, processInfo }: GrokSessionAgentInput): AgentInfo {
+    return {
+      name: generateAgentName(session.projectPath, processInfo.pid),
+      type: "grok_cli",
+      status: this.parser.determineStatus(session),
+      summary: session.lastUserMessage || "Grok CLI session active",
+      pid: processInfo.pid,
+      projectPath: session.projectPath,
+      sessionId: session.sessionId,
+      lastActive: session.lastActive,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+
+  /** `cwd` is already resolved by the locator (registry first, then process cwd). */
+  mapProcessOnlyAgent(processInfo: ProcessInfo, cwd: string): AgentInfo {
+    return {
+      name: generateAgentName(cwd, processInfo.pid),
+      type: "grok_cli",
+      status: AgentStatus.RUNNING,
+      summary: "Grok CLI process running",
+      pid: processInfo.pid,
+      projectPath: cwd,
+      sessionId: `pid-${processInfo.pid}`,
+      lastActive: new Date(),
+    };
+  }
+}

package/src/providers/grok/GrokCliAdapter.ts

@@ -0,0 +1,125 @@
+import type {
+  AgentAdapter,
+  AgentInfo,
+  ProcessInfo,
+  ConversationMessage,
+  SessionSummary,
+  ListSessionsOptions,
+  AgentDetectionContext,
+} from "../../adapters/AgentAdapter.js";
+import {
+  captureProcessSnapshot,
+  executableBasename,
+  filterByProcessNames,
+} from "../../utils/process.js";
+import { GrokAgentMapper } from "./GrokAgentMapper.js";
+import { GrokSessionLocator } from "./GrokSessionLocator.js";
+import { GrokSessionParser, type GrokSession } from "./GrokSessionParser.js";
+
+/**
+ * Grok Build CLI Adapter
+ *
+ * Detects running Grok Build CLI agents by:
+ * 1. Filtering `grok` processes from a shared asynchronous snapshot — Grok is
+ *    a native binary at ~/.grok/bin/grok, so argv[0] basename is `grok`.
+ * 2. Resolving each live process to its working directory via
+ *    ~/.grok/active_sessions.json, which Grok maintains as a list of
+ *    { pid, cwd, opened_at } for every running session. The cwd is then encoded
+ *    into the session group dir ~/.grok/sessions/<encodeURIComponent(cwd)>/, and
+ *    the most recently active session subdirectory is picked from it. The
+ *    process cwd from lsof is only a fallback when the PID is not registered.
+ * 3. Reading the session transcript from chat_history.jsonl (the authoritative
+ *    record of the conversation). The last user turn (the text inside
+ *    <user_query>...</user_query>) is the summary; the file's mtime is the last
+ *    activity time. summary.json / updates.jsonl are intentionally not used.
+ */
+export class GrokCliAdapter implements AgentAdapter {
+  readonly type = "grok_cli" as const;
+  readonly processNames = ["grok"] as const;
+
+  private parser: GrokSessionParser;
+  private mapper: GrokAgentMapper;
+  private locator: GrokSessionLocator;
+
+  constructor() {
+    this.parser = new GrokSessionParser();
+    this.mapper = new GrokAgentMapper(this.parser);
+    this.locator = new GrokSessionLocator();
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    return this.isGrokExecutable(processInfo.command);
+  }
+
+  private isGrokExecutable(command: string): boolean {
+    const base = executableBasename(command);
+    return base === "grok" || base === "grok.exe";
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
+    const relevant = filterByProcessNames(snapshot, this.processNames);
+    const processes = relevant.filter((process) => this.canHandle(process));
+    if (processes.length === 0) {
+      return [];
+    }
+
+    const agents: AgentInfo[] = [];
+    for (const { process: proc, cwd, sessionDir } of this.locator.matchRunningProcesses(
+      processes,
+    )) {
+      const session = sessionDir ? this.parser.readSession(sessionDir, cwd) : null;
+      if (session) {
+        agents.push(this.mapper.mapSessionToAgent({ session, processInfo: proc }));
+      } else {
+        agents.push(this.mapper.mapProcessOnlyAgent(proc, cwd));
+      }
+    }
+    return agents;
+  }
+
+  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+    return this.parser.getConversation(sessionFilePath, options);
+  }
+
+  async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+    const filterCwd = opts?.cwd;
+    const summaries: SessionSummary[] = [];
+
+    for (const { sessionDir, defaultCwd } of this.locator.discoverHistoricalSessionDirs()) {
+      const session = this.parser.readSession(sessionDir, defaultCwd);
+      if (!session) continue;
+
+      if (filterCwd !== undefined && session.projectPath !== filterCwd) continue;
+
+      summaries.push(this.toSessionSummary(session));
+    }
+
+    return summaries;
+  }
+
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const summaries: SessionSummary[] = [];
+    for (const { sessionDir, defaultCwd } of this.locator.findHistoricalSessionDirsById(
+      sessionId,
+    )) {
+      const session = this.parser.readSession(sessionDir, defaultCwd);
+      if (!session) continue;
+
+      summaries.push(this.toSessionSummary(session));
+    }
+    return summaries;
+  }
+
+  private toSessionSummary(session: GrokSession): SessionSummary {
+    return {
+      type: this.type,
+      sessionId: session.sessionId,
+      cwd: session.projectPath,
+      firstUserMessage: session.firstUserMessage || "",
+      lastActive: session.lastActive,
+      startedAt: session.sessionStart,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+}

package/src/providers/grok/GrokSessionLocator.ts

@@ -0,0 +1,179 @@
+import * as path from "path";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
+import {
+  isDirectory,
+  isSafePathSegment,
+  safeReadFile,
+  safeReaddir,
+  safeStat,
+} from "../../utils/session.js";
+import { CHAT_HISTORY_FILE } from "./GrokSessionParser.js";
+
+const ACTIVE_SESSIONS_FILE = "active_sessions.json";
+const CWD_FILE = ".cwd";
+
+/** One entry of ~/.grok/active_sessions.json. */
+interface ActiveSessionEntry {
+  pid?: number;
+  cwd?: string;
+  opened_at?: number | string;
+}
+
+/** A live Grok process paired with its resolved cwd and (if any) session dir. */
+export interface GrokProcessMatch {
+  process: ProcessInfo;
+  cwd: string;
+  sessionDir: string | null;
+}
+
+/** A historical session dir plus the cwd decoded from its group dir. */
+export interface GrokSessionDir {
+  sessionDir: string;
+  defaultCwd: string;
+}
+
+export interface GrokSessionLocatorOptions {
+  /** Overrides the ~/.grok base directory (defaults to GROK_HOME or ~/.grok). */
+  baseDir?: string;
+}
+
+export class GrokSessionLocator {
+  private readonly baseDir: string;
+  private readonly sessionsDir: string;
+
+  constructor(options: GrokSessionLocatorOptions = {}) {
+    // GROK_HOME overrides the ~/.grok base directory; sessions live under
+    // <base>/sessions/ and the active-session registry at
+    // <base>/active_sessions.json.
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    this.baseDir = options.baseDir ?? (process.env.GROK_HOME || path.join(homeDir, ".grok"));
+    this.sessionsDir = path.join(this.baseDir, "sessions");
+  }
+
+  /**
+   * Pair live Grok processes with their session dirs.
+   *
+   * active_sessions.json is the authoritative pid -> cwd map for live
+   * sessions; the lsof-derived process cwd is only a fallback. The most
+   * recently active session under that cwd's group dir is picked.
+   */
+  matchRunningProcesses(processes: ProcessInfo[]): GrokProcessMatch[] {
+    const pidToCwd = this.readActiveSessions();
+    return processes.map((proc) => {
+      const cwd = pidToCwd.get(proc.pid) || proc.cwd || "";
+      return { process: proc, cwd, sessionDir: cwd ? this.latestSessionDir(cwd) : null };
+    });
+  }
+
+  /** Every session dir under ~/.grok/sessions/, across all project groups. */
+  discoverHistoricalSessionDirs(): GrokSessionDir[] {
+    const results: GrokSessionDir[] = [];
+    for (const { groupDir, defaultCwd } of this.listGroups()) {
+      for (const sessionDir of this.listSessionDirs(groupDir)) {
+        results.push({ sessionDir, defaultCwd });
+      }
+    }
+    return results;
+  }
+
+  /** Session dirs named exactly `sessionId`, across all project groups. */
+  findHistoricalSessionDirsById(sessionId: string): GrokSessionDir[] {
+    if (!isSafePathSegment(sessionId)) return [];
+
+    const results: GrokSessionDir[] = [];
+    for (const { groupDir, defaultCwd } of this.listGroups()) {
+      const sessionDir = path.join(groupDir, sessionId);
+      if (isDirectory(sessionDir)) {
+        results.push({ sessionDir, defaultCwd });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Read ~/.grok/active_sessions.json into a pid -> cwd map. Grok writes one
+   * { pid, cwd, opened_at } entry per running session and removes it on exit,
+   * so this is the reliable way to learn a live process's working directory.
+   */
+  private readActiveSessions(): Map<number, string> {
+    const map = new Map<number, string>();
+    const content = safeReadFile(path.join(this.baseDir, ACTIVE_SESSIONS_FILE));
+    if (content === undefined) return map;
+
+    let entries: unknown;
+    try {
+      entries = JSON.parse(content);
+    } catch {
+      return map;
+    }
+    if (!Array.isArray(entries)) return map;
+
+    for (const entry of entries as ActiveSessionEntry[]) {
+      if (typeof entry?.pid === "number" && typeof entry?.cwd === "string" && entry.cwd) {
+        map.set(entry.pid, entry.cwd);
+      }
+    }
+    return map;
+  }
+
+  /**
+   * Return the most recently active session subdirectory for a cwd, i.e. the
+   * ~/.grok/sessions/<encodeURIComponent(cwd)>/<id>/ whose chat_history.jsonl
+   * was written last. Returns null when the group dir or any transcript is
+   * missing.
+   */
+  private latestSessionDir(cwd: string): string | null {
+    const groupDir = path.join(this.sessionsDir, encodeURIComponent(cwd));
+    if (!isDirectory(groupDir)) return null;
+
+    let best: { dir: string; mtimeMs: number } | null = null;
+    for (const sessionDir of this.listSessionDirs(groupDir)) {
+      const stat = safeStat(path.join(sessionDir, CHAT_HISTORY_FILE));
+      if (!stat) continue;
+      if (!best || stat.mtimeMs > best.mtimeMs) {
+        best = { dir: sessionDir, mtimeMs: stat.mtimeMs };
+      }
+    }
+    return best?.dir ?? null;
+  }
+
+  private listGroups(): Array<{ groupDir: string; defaultCwd: string }> {
+    if (!isDirectory(this.sessionsDir)) return [];
+
+    const groups: Array<{ groupDir: string; defaultCwd: string }> = [];
+    for (const groupName of safeReaddir(this.sessionsDir)) {
+      const groupDir = path.join(this.sessionsDir, groupName);
+      if (!isDirectory(groupDir)) continue;
+      groups.push({ groupDir, defaultCwd: this.decodeGroupCwd(groupName, groupDir) });
+    }
+    return groups;
+  }
+
+  /**
+   * Full paths of the session subdirectories directly under a group dir,
+   * skipping any non-directory entries (e.g. prompt_history.jsonl).
+   */
+  private listSessionDirs(groupDir: string): string[] {
+    return safeReaddir(groupDir)
+      .map((sessionId) => path.join(groupDir, sessionId))
+      .filter((sessionDir) => isDirectory(sessionDir));
+  }
+
+  /**
+   * Resolve the working directory a session group dir was created for.
+   *
+   * The common case is `decodeURIComponent(<group-name>)`. For paths whose
+   * encoded form exceeds the filesystem limit Grok uses a slug+hash and records
+   * the original path in a `.cwd` file inside the group — prefer that when
+   * present.
+   */
+  private decodeGroupCwd(groupName: string, groupDir: string): string {
+    const fromFile = safeReadFile(path.join(groupDir, CWD_FILE));
+    if (fromFile !== undefined && fromFile.trim()) return fromFile.trim();
+    try {
+      return decodeURIComponent(groupName);
+    } catch {
+      return "";
+    }
+  }
+}

package/src/providers/grok/GrokSessionParser.ts

@@ -0,0 +1,166 @@
+import * as path from "path";
+import type { ConversationMessage } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { safeReadFile, safeStat } from "../../utils/session.js";
+
+export const CHAT_HISTORY_FILE = "chat_history.jsonl";
+const IDLE_THRESHOLD_MINUTES = 5;
+
+/** One line of chat_history.jsonl. */
+interface ChatRecord {
+  type?: string;
+  content?: unknown;
+}
+
+interface ChatScan {
+  messages: ConversationMessage[];
+  firstUserMessage?: string;
+  lastUserMessage?: string;
+  lastRole?: ConversationMessage["role"];
+}
+
+/** Parsed state for a single ~/.grok/sessions/<cwd>/<id>/ directory. */
+export interface GrokSession {
+  sessionId: string;
+  projectPath: string;
+  sessionFilePath: string;
+  sessionStart: Date;
+  lastActive: Date;
+  firstUserMessage?: string;
+  lastUserMessage?: string;
+  lastRole?: ConversationMessage["role"];
+}
+
+export class GrokSessionParser {
+  /**
+   * Parse a session directory into a {@link GrokSession} from its
+   * chat_history.jsonl transcript. Returns null when the transcript is
+   * missing — i.e. there is no real session to surface.
+   */
+  readSession(sessionDir: string, defaultCwd: string): GrokSession | null {
+    const chatPath = path.join(sessionDir, CHAT_HISTORY_FILE);
+    const chatStat = safeStat(chatPath);
+    if (!chatStat) return null;
+
+    const scan = this.parseChatHistory(chatPath, false);
+    const dirStat = safeStat(sessionDir);
+    const lastActive = chatStat.mtime;
+
+    return {
+      sessionId: path.basename(sessionDir),
+      projectPath: defaultCwd,
+      sessionFilePath: chatPath,
+      sessionStart: dirStat?.birthtime || lastActive,
+      lastActive,
+      firstUserMessage: scan.firstUserMessage,
+      lastUserMessage: scan.lastUserMessage,
+      lastRole: scan.lastRole,
+    };
+  }
+
+  /** Accepts a session dir or an explicit chat_history.jsonl path. */
+  getConversation(sessionPath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+    return this.parseChatHistory(this.resolveChatPath(sessionPath), options?.verbose ?? false)
+      .messages;
+  }
+
+  /**
+   * Determine agent status from parsed session state.
+   *
+   * - past the idle threshold → IDLE
+   * - last transcript turn is an assistant message → WAITING (awaiting user)
+   * - otherwise (last turn was a user message, or unknown) → RUNNING
+   */
+  determineStatus(session: GrokSession): AgentStatus {
+    const diffMinutes = (Date.now() - session.lastActive.getTime()) / 60000;
+    if (diffMinutes > IDLE_THRESHOLD_MINUTES) {
+      return AgentStatus.IDLE;
+    }
+    if (session.lastRole === "assistant") {
+      return AgentStatus.WAITING;
+    }
+    return AgentStatus.RUNNING;
+  }
+
+  /**
+   * Single pass over chat_history.jsonl. Each line is a
+   * { type: 'system' | 'user' | 'assistant', content } record where content is
+   * either a string or an array of { type: 'text', text } blocks.
+   *
+   * Grok wraps the real user prompt in <user_query>...</user_query>; the other
+   * user records are context injections (<user_info>, <system-reminder>, ...)
+   * and are skipped so the summary is the actual prompt, not boilerplate.
+   */
+  private parseChatHistory(chatPath: string, verbose: boolean): ChatScan {
+    const content = safeReadFile(chatPath);
+    if (content === undefined) return { messages: [] };
+
+    const messages: ConversationMessage[] = [];
+    let lastRole: ConversationMessage["role"] | undefined;
+
+    for (const line of content.trim().split("\n")) {
+      if (!line.trim()) continue;
+
+      let record: ChatRecord;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      const text = this.extractText(record.content);
+      if (record.type === "user") {
+        const query = this.extractUserQuery(text);
+        if (query === null) continue; // context injection, not a real prompt
+        messages.push({ role: "user", content: query });
+        lastRole = "user";
+      } else if (record.type === "assistant") {
+        if (!text) continue;
+        messages.push({ role: "assistant", content: text });
+        lastRole = "assistant";
+      } else if (verbose && record.type === "system") {
+        if (!text) continue;
+        messages.push({ role: "system", content: text });
+      }
+    }
+
+    const userTurns = messages.filter((m) => m.role === "user");
+    return {
+      messages,
+      firstUserMessage: userTurns[0]?.content,
+      lastUserMessage: userTurns[userTurns.length - 1]?.content,
+      lastRole,
+    };
+  }
+
+  /** Flatten a chat record's content (string or text-block array) to text. */
+  private extractText(content: unknown): string {
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content
+        .map((block) =>
+          block &&
+          typeof block === "object" &&
+          typeof (block as { text?: unknown }).text === "string"
+            ? (block as { text: string }).text
+            : "",
+        )
+        .join("");
+    }
+    return "";
+  }
+
+  /**
+   * Extract the prompt inside <user_query>...</user_query>. Returns null when
+   * the record has no such tag (a context injection rather than a prompt).
+   */
+  private extractUserQuery(text: string): string | null {
+    const match = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+    return match ? match[1].trim() : null;
+  }
+
+  /** Resolve a session dir or an explicit chat_history.jsonl path to the file. */
+  private resolveChatPath(sessionPath: string): string {
+    return sessionPath.endsWith(".jsonl") ? sessionPath : path.join(sessionPath, CHAT_HISTORY_FILE);
+  }
+}