@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/dist/harnesses/claude/ClaudeSessionLocator.js

@@ -0,0 +1,260 @@
+import * as fs from "fs";
+import * as path from "path";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { matchProcessesToSessions } from "../../utils/matching.js";
+import { batchGetSessionFileBirthtimes, isDirectory, isSafePathSegment, listJsonl, safeReaddir, safeStat } from "../../utils/session.js";
+import { homeDir } from "../shared.js";
+/** Maximum allowed delta (ms) between process start time and PID file startedAt. */ const PID_FILE_STALENESS_MS = 60000;
+export class ClaudeSessionLocator {
+    projectsDir;
+    sessionsDir;
+    constructor(options = {}){
+        this.projectsDir = options.projectsDir ?? path.join(homeDir(), ".claude", "projects");
+        this.sessionsDir = options.sessionsDir ?? path.join(homeDir(), ".claude", "sessions");
+    }
+    /**
+   * Pair live Claude processes with their session files.
+   *
+   * Runs three staged strategies, each handing its unmatched processes
+   * to the next:
+   * 1. `--resume <id>` on the command line — authoritative for resumed
+   *    sessions whose JSONL predates the process.
+   * 2. PID-file matching via ~/.claude/sessions/<pid>.json.
+   * 3. Legacy CWD+birthtime heuristic, for processes with no PID file.
+   */ matchRunningProcesses(processes) {
+        const { direct: resumeDirect, fallback: noResume } = this.tryResumeMatching(processes);
+        const { direct: pidDirect, fallback } = this.tryPidFileMatching(noResume);
+        const legacySessions = this.discoverLiveSessions(fallback);
+        const legacyMatches = fallback.length > 0 && legacySessions.length > 0 ? matchProcessesToSessions(fallback, legacySessions) : [];
+        return {
+            direct: [
+                ...resumeDirect,
+                ...pidDirect
+            ],
+            legacyMatches
+        };
+    }
+    /**
+   * Discover candidate session files for listing historical sessions.
+   *
+   * Always walks every subdirectory of `projectsDir`. We can't use the
+   * encoded-dir shortcut for the cwd-scoped path because Claude Code
+   * indexes session files by where the *process was launched*, not by
+   * the recorded `cwd` field inside the session — these diverge in
+   * worktrees and similar setups. The cwd filter is applied later
+   * against `session.lastCwd` so callers see exactly the sessions whose
+   * recorded cwd matches.
+   */ discoverHistoricalSessionFiles() {
+        const out = [];
+        if (!isDirectory(this.projectsDir)) return out;
+        for (const dirName of safeReaddir(this.projectsDir)){
+            const projectDir = path.join(this.projectsDir, dirName);
+            if (!isDirectory(projectDir)) continue;
+            // Best-effort decode for the rare case session content has no
+            // recorded cwd: '-Users-foo-bar' → '/Users/foo/bar'. Lossy for
+            // paths containing '-'; session content's lastCwd overrides
+            // this when available.
+            const decoded = dirName.replace(/-/g, "/");
+            for (const name of listJsonl(projectDir)){
+                out.push({
+                    filePath: path.join(projectDir, name),
+                    defaultCwd: decoded
+                });
+            }
+        }
+        return out;
+    }
+    findHistoricalSessionFilesById(sessionId) {
+        if (!isSafePathSegment(sessionId) || !isDirectory(this.projectsDir)) {
+            return [];
+        }
+        const matches = [];
+        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.
+   *
+   * Claude Code encodes paths by replacing every non-alphanumeric
+   * character with '-', so '/', '_', '.', spaces, etc. all collapse:
+   *   /Users/foo/bar          → -Users-foo-bar
+   *   /Users/foo/my_project   → -Users-foo-my-project
+   *   /Users/foo/.worktrees/x → -Users-foo--worktrees-x
+   *
+   * The encoding is lossy — multiple real paths can collide on the
+   * same encoded dir. Callers that need to disambiguate must read the
+   * `cwd` field inside each session JSONL.
+   */ getProjectDir(cwd) {
+        const encoded = cwd.replace(/[^a-zA-Z0-9]/g, "-");
+        return path.join(this.projectsDir, encoded);
+    }
+    /**
+   * Discover session files for the given processes.
+   *
+   * For each unique process CWD, encodes it to derive the expected
+   * ~/.claude/projects/<encoded>/ directory, then gets session file birthtimes
+   * via a single batched stat call across all directories.
+   */ discoverLiveSessions(processes) {
+        const dirToCwd = new Map();
+        for (const proc of processes){
+            if (!proc.cwd) continue;
+            const projectDir = this.getProjectDir(proc.cwd);
+            if (dirToCwd.has(projectDir)) continue;
+            try {
+                if (!fs.statSync(projectDir).isDirectory()) continue;
+            } catch  {
+                continue;
+            }
+            dirToCwd.set(projectDir, proc.cwd);
+        }
+        if (dirToCwd.size === 0) return [];
+        const files = batchGetSessionFileBirthtimes([
+            ...dirToCwd.keys()
+        ]);
+        for (const file of files){
+            file.resolvedCwd = dirToCwd.get(file.projectDir) || "";
+        }
+        return files;
+    }
+    /**
+   * Match processes via `claude --resume <uuid>` in their command line.
+   * This works for resumed sessions, where the JSONL was created earlier
+   * (so its birthtime is far from the process startTime and the legacy
+   * matcher can't pair them) and the PID file may also be misaligned.
+   */ tryResumeMatching(processes) {
+        const direct = [];
+        const fallback = [];
+        for (const proc of processes){
+            const sessionId = this.extractResumeSessionId(proc.command);
+            if (!sessionId || !proc.cwd) {
+                fallback.push(proc);
+                continue;
+            }
+            const projectDir = this.getProjectDir(proc.cwd);
+            const jsonlPath = path.join(projectDir, `${sessionId}.jsonl`);
+            const stat = safeStat(jsonlPath);
+            if (!stat) {
+                fallback.push(proc);
+                continue;
+            }
+            // Best-effort: the PID file (if present for this proc) is the
+            // authoritative source of live status. We still match the session
+            // via --resume, but we read the PID file alongside to capture
+            // status/waitingFor.
+            const pidEntry = this.readMatchingPidFile(proc.pid, proc.startTime);
+            direct.push({
+                process: proc,
+                sessionFile: {
+                    sessionId,
+                    filePath: jsonlPath,
+                    projectDir,
+                    birthtimeMs: stat.birthtimeMs,
+                    resolvedCwd: proc.cwd
+                },
+                pidStatus: this.mapPidStatus(pidEntry?.status),
+                waitingFor: pidEntry?.waitingFor
+            });
+        }
+        return {
+            direct,
+            fallback
+        };
+    }
+    extractResumeSessionId(command) {
+        const match = command.match(/--resume\s+([0-9a-f-]{36})/i);
+        return match?.[1] ?? null;
+    }
+    /**
+   * Read and parse ~/.claude/sessions/<pid>.json, returning null on any
+   * I/O / parse failure or when the file is stale relative to the live
+   * process.
+   *
+   * "Stale" means the PID file's startedAt diverges from the process's
+   * start time by more than {@link PID_FILE_STALENESS_MS} — typically
+   * a previous Claude Code process recycled the same PID without cleanup.
+   */ readMatchingPidFile(pid, procStartTime) {
+        const pidFilePath = path.join(this.sessionsDir, `${pid}.json`);
+        try {
+            const entry = JSON.parse(fs.readFileSync(pidFilePath, "utf-8"));
+            if (procStartTime) {
+                const deltaMs = Math.abs(procStartTime.getTime() - entry.startedAt);
+                if (deltaMs > PID_FILE_STALENESS_MS) {
+                    return null;
+                }
+            }
+            return entry;
+        } catch  {
+            return null;
+        }
+    }
+    /**
+   * Map the PID file's live status string to {@link AgentStatus}.
+   *
+   * Returns undefined for missing / unrecognized values so the caller
+   * can fall back to JSONL-derived heuristics.
+   */ mapPidStatus(status) {
+        switch(status){
+            case "running":
+                return AgentStatus.RUNNING;
+            case "waiting":
+                return AgentStatus.WAITING;
+            case "idle":
+                return AgentStatus.IDLE;
+            default:
+                return undefined;
+        }
+    }
+    /**
+   * Attempt to match each process to its session via ~/.claude/sessions/<pid>.json.
+   *
+   * Returns:
+   *   direct  — processes matched authoritatively via PID file
+   *   fallback — processes with no valid PID file (sent to legacy matching)
+   *
+   * Per-process fallback triggers on: file absent, malformed JSON,
+   * stale startedAt (>60s from proc.startTime), or missing JSONL.
+   */ tryPidFileMatching(processes) {
+        const direct = [];
+        const fallback = [];
+        for (const proc of processes){
+            const entry = this.readMatchingPidFile(proc.pid, proc.startTime);
+            if (!entry) {
+                fallback.push(proc);
+                continue;
+            }
+            const projectDir = this.getProjectDir(entry.cwd);
+            const jsonlPath = path.join(projectDir, `${entry.sessionId}.jsonl`);
+            if (!fs.existsSync(jsonlPath)) {
+                fallback.push(proc);
+                continue;
+            }
+            direct.push({
+                process: proc,
+                sessionFile: {
+                    sessionId: entry.sessionId,
+                    filePath: jsonlPath,
+                    projectDir,
+                    birthtimeMs: entry.startedAt,
+                    resolvedCwd: entry.cwd
+                },
+                pidStatus: this.mapPidStatus(entry.status),
+                waitingFor: entry.waitingFor
+            });
+        }
+        return {
+            direct,
+            fallback
+        };
+    }
+}
+
+//# sourceMappingURL=ClaudeSessionLocator.js.map

package/dist/harnesses/claude/ClaudeSessionLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/harnesses/claude/ClaudeSessionLocator.ts"],"sourcesContent":["import * as fs from \"fs\";\nimport * as path from \"path\";\nimport type { ProcessInfo } from \"../../adapters/AgentAdapter.js\";\nimport { AgentStatus } from \"../../adapters/AgentAdapter.js\";\nimport { matchProcessesToSessions, type MatchResult } from \"../../utils/matching.js\";\nimport {\n  batchGetSessionFileBirthtimes,\n  isDirectory,\n  isSafePathSegment,\n  listJsonl,\n  safeReaddir,\n  safeStat,\n  type SessionFile,\n} from \"../../utils/session.js\";\nimport { homeDir } from \"../shared.js\";\n\n/**\n * Entry in ~/.claude/sessions/<pid>.json written by Claude Code.\n * Maps a running process to its session file via PID.\n */\ninterface PidFileEntry {\n  pid: number;\n  sessionId: string;\n  cwd: string;\n  /** Epoch milliseconds when the Claude Code process started */\n  startedAt: number;\n  kind: string;\n  entrypoint: string;\n  /**\n   * Authoritative live status published by the Claude Code process\n   * (e.g., 'running', 'waiting', 'idle'). Preferred over JSONL-derived\n   * status because trailing entries like 'permission-mode' / 'ai-title'\n   * can mask the real conversational state.\n   */\n  status?: string;\n  /** Short description of what the agent is waiting on (e.g., \"approve Read\"). */\n  waitingFor?: string;\n}\n\n/**\n * A process directly matched to a session via PID file (authoritative path).\n *\n * When the matching PID file also exposes live status/waitingFor metadata,\n * those values are carried here so the agent mapper can prefer them over\n * the JSONL-derived heuristic.\n */\nexport interface ClaudeDirectMatch {\n  process: ProcessInfo;\n  sessionFile: SessionFile;\n  pidStatus?: AgentStatus;\n  waitingFor?: string;\n}\n\nexport interface ClaudeProcessSessionMatches {\n  direct: ClaudeDirectMatch[];\n  legacyMatches: MatchResult[];\n}\n\nexport interface ClaudeSessionLocatorOptions {\n  projectsDir?: string;\n  sessionsDir?: string;\n}\n\n/** Maximum allowed delta (ms) between process start time and PID file startedAt. */\nconst PID_FILE_STALENESS_MS = 60000;\n\nexport class ClaudeSessionLocator {\n  private readonly projectsDir: string;\n  private readonly sessionsDir: string;\n\n  constructor(options: ClaudeSessionLocatorOptions = {}) {\n    this.projectsDir = options.projectsDir ?? path.join(homeDir(), \".claude\", \"projects\");\n    this.sessionsDir = options.sessionsDir ?? path.join(homeDir(), \".claude\", \"sessions\");\n  }\n\n  /**\n   * Pair live Claude processes with their session files.\n   *\n   * Runs three staged strategies, each handing its unmatched processes\n   * to the next:\n   * 1. `--resume <id>` on the command line — authoritative for resumed\n   *    sessions whose JSONL predates the process.\n   * 2. PID-file matching via ~/.claude/sessions/<pid>.json.\n   * 3. Legacy CWD+birthtime heuristic, for processes with no PID file.\n   */\n  matchRunningProcesses(processes: ProcessInfo[]): ClaudeProcessSessionMatches {\n    const { direct: resumeDirect, fallback: noResume } = this.tryResumeMatching(processes);\n    const { direct: pidDirect, fallback } = this.tryPidFileMatching(noResume);\n    const legacySessions = this.discoverLiveSessions(fallback);\n    const legacyMatches =\n      fallback.length > 0 && legacySessions.length > 0\n        ? matchProcessesToSessions(fallback, legacySessions)\n        : [];\n\n    return {\n      direct: [...resumeDirect, ...pidDirect],\n      legacyMatches,\n    };\n  }\n\n  /**\n   * Discover candidate session files for listing historical sessions.\n   *\n   * Always walks every subdirectory of `projectsDir`. We can't use the\n   * encoded-dir shortcut for the cwd-scoped path because Claude Code\n   * indexes session files by where the *process was launched*, not by\n   * the recorded `cwd` field inside the session — these diverge in\n   * worktrees and similar setups. The cwd filter is applied later\n   * against `session.lastCwd` so callers see exactly the sessions whose\n   * recorded cwd matches.\n   */\n  discoverHistoricalSessionFiles(): Array<{ filePath: string; defaultCwd: string }> {\n    const out: Array<{ filePath: string; defaultCwd: string }> = [];\n\n    if (!isDirectory(this.projectsDir)) return out;\n\n    for (const dirName of safeReaddir(this.projectsDir)) {\n      const projectDir = path.join(this.projectsDir, dirName);\n      if (!isDirectory(projectDir)) continue;\n\n      // Best-effort decode for the rare case session content has no\n      // recorded cwd: '-Users-foo-bar' → '/Users/foo/bar'. Lossy for\n      // paths containing '-'; session content's lastCwd overrides\n      // this when available.\n      const decoded = dirName.replace(/-/g, \"/\");\n      for (const name of listJsonl(projectDir)) {\n        out.push({ filePath: path.join(projectDir, name), defaultCwd: decoded });\n      }\n    }\n\n    return out;\n  }\n\n  findHistoricalSessionFilesById(\n    sessionId: string,\n  ): Array<{ filePath: string; defaultCwd: string }> {\n    if (!isSafePathSegment(sessionId) || !isDirectory(this.projectsDir)) {\n      return [];\n    }\n\n    const matches: Array<{ filePath: string; defaultCwd: string }> = [];\n    for (const dirName of safeReaddir(this.projectsDir)) {\n      const projectDir = path.join(this.projectsDir, dirName);\n      if (!isDirectory(projectDir)) continue;\n\n      const filePath = path.join(projectDir, `${sessionId}.jsonl`);\n      if (!safeStat(filePath)?.isFile()) continue;\n      matches.push({ filePath, defaultCwd: dirName.replace(/-/g, \"/\") });\n    }\n    return matches;\n  }\n\n  /**\n   * Derive the Claude Code project directory for a given CWD.\n   *\n   * Claude Code encodes paths by replacing every non-alphanumeric\n   * character with '-', so '/', '_', '.', spaces, etc. all collapse:\n   *   /Users/foo/bar          → -Users-foo-bar\n   *   /Users/foo/my_project   → -Users-foo-my-project\n   *   /Users/foo/.worktrees/x → -Users-foo--worktrees-x\n   *\n   * The encoding is lossy — multiple real paths can collide on the\n   * same encoded dir. Callers that need to disambiguate must read the\n   * `cwd` field inside each session JSONL.\n   */\n  private getProjectDir(cwd: string): string {\n    const encoded = cwd.replace(/[^a-zA-Z0-9]/g, \"-\");\n    return path.join(this.projectsDir, encoded);\n  }\n\n  /**\n   * Discover session files for the given processes.\n   *\n   * For each unique process CWD, encodes it to derive the expected\n   * ~/.claude/projects/<encoded>/ directory, then gets session file birthtimes\n   * via a single batched stat call across all directories.\n   */\n  discoverLiveSessions(processes: ProcessInfo[]): SessionFile[] {\n    const dirToCwd = new Map<string, string>();\n\n    for (const proc of processes) {\n      if (!proc.cwd) continue;\n\n      const projectDir = this.getProjectDir(proc.cwd);\n      if (dirToCwd.has(projectDir)) continue;\n\n      try {\n        if (!fs.statSync(projectDir).isDirectory()) continue;\n      } catch {\n        continue;\n      }\n\n      dirToCwd.set(projectDir, proc.cwd);\n    }\n\n    if (dirToCwd.size === 0) return [];\n\n    const files = batchGetSessionFileBirthtimes([...dirToCwd.keys()]);\n\n    for (const file of files) {\n      file.resolvedCwd = dirToCwd.get(file.projectDir) || \"\";\n    }\n\n    return files;\n  }\n\n  /**\n   * Match processes via `claude --resume <uuid>` in their command line.\n   * This works for resumed sessions, where the JSONL was created earlier\n   * (so its birthtime is far from the process startTime and the legacy\n   * matcher can't pair them) and the PID file may also be misaligned.\n   */\n  private tryResumeMatching(processes: ProcessInfo[]): {\n    direct: ClaudeDirectMatch[];\n    fallback: ProcessInfo[];\n  } {\n    const direct: ClaudeDirectMatch[] = [];\n    const fallback: ProcessInfo[] = [];\n\n    for (const proc of processes) {\n      const sessionId = this.extractResumeSessionId(proc.command);\n      if (!sessionId || !proc.cwd) {\n        fallback.push(proc);\n        continue;\n      }\n\n      const projectDir = this.getProjectDir(proc.cwd);\n      const jsonlPath = path.join(projectDir, `${sessionId}.jsonl`);\n\n      const stat = safeStat(jsonlPath);\n      if (!stat) {\n        fallback.push(proc);\n        continue;\n      }\n\n      // Best-effort: the PID file (if present for this proc) is the\n      // authoritative source of live status. We still match the session\n      // via --resume, but we read the PID file alongside to capture\n      // status/waitingFor.\n      const pidEntry = this.readMatchingPidFile(proc.pid, proc.startTime);\n\n      direct.push({\n        process: proc,\n        sessionFile: {\n          sessionId,\n          filePath: jsonlPath,\n          projectDir,\n          birthtimeMs: stat.birthtimeMs,\n          resolvedCwd: proc.cwd,\n        },\n        pidStatus: this.mapPidStatus(pidEntry?.status),\n        waitingFor: pidEntry?.waitingFor,\n      });\n    }\n\n    return { direct, fallback };\n  }\n\n  private extractResumeSessionId(command: string): string | null {\n    const match = command.match(/--resume\\s+([0-9a-f-]{36})/i);\n    return match?.[1] ?? null;\n  }\n\n  /**\n   * Read and parse ~/.claude/sessions/<pid>.json, returning null on any\n   * I/O / parse failure or when the file is stale relative to the live\n   * process.\n   *\n   * \"Stale\" means the PID file's startedAt diverges from the process's\n   * start time by more than {@link PID_FILE_STALENESS_MS} — typically\n   * a previous Claude Code process recycled the same PID without cleanup.\n   */\n  private readMatchingPidFile(pid: number, procStartTime?: Date): PidFileEntry | null {\n    const pidFilePath = path.join(this.sessionsDir, `${pid}.json`);\n    try {\n      const entry = JSON.parse(fs.readFileSync(pidFilePath, \"utf-8\")) as PidFileEntry;\n\n      if (procStartTime) {\n        const deltaMs = Math.abs(procStartTime.getTime() - entry.startedAt);\n        if (deltaMs > PID_FILE_STALENESS_MS) {\n          return null;\n        }\n      }\n\n      return entry;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Map the PID file's live status string to {@link AgentStatus}.\n   *\n   * Returns undefined for missing / unrecognized values so the caller\n   * can fall back to JSONL-derived heuristics.\n   */\n  private mapPidStatus(status: string | undefined): AgentStatus | undefined {\n    switch (status) {\n      case \"running\":\n        return AgentStatus.RUNNING;\n      case \"waiting\":\n        return AgentStatus.WAITING;\n      case \"idle\":\n        return AgentStatus.IDLE;\n      default:\n        return undefined;\n    }\n  }\n\n  /**\n   * Attempt to match each process to its session via ~/.claude/sessions/<pid>.json.\n   *\n   * Returns:\n   *   direct  — processes matched authoritatively via PID file\n   *   fallback — processes with no valid PID file (sent to legacy matching)\n   *\n   * Per-process fallback triggers on: file absent, malformed JSON,\n   * stale startedAt (>60s from proc.startTime), or missing JSONL.\n   */\n  private tryPidFileMatching(processes: ProcessInfo[]): {\n    direct: ClaudeDirectMatch[];\n    fallback: ProcessInfo[];\n  } {\n    const direct: ClaudeDirectMatch[] = [];\n    const fallback: ProcessInfo[] = [];\n\n    for (const proc of processes) {\n      const entry = this.readMatchingPidFile(proc.pid, proc.startTime);\n      if (!entry) {\n        fallback.push(proc);\n        continue;\n      }\n\n      const projectDir = this.getProjectDir(entry.cwd);\n      const jsonlPath = path.join(projectDir, `${entry.sessionId}.jsonl`);\n\n      if (!fs.existsSync(jsonlPath)) {\n        fallback.push(proc);\n        continue;\n      }\n\n      direct.push({\n        process: proc,\n        sessionFile: {\n          sessionId: entry.sessionId,\n          filePath: jsonlPath,\n          projectDir,\n          birthtimeMs: entry.startedAt,\n          resolvedCwd: entry.cwd,\n        },\n        pidStatus: this.mapPidStatus(entry.status),\n        waitingFor: entry.waitingFor,\n      });\n    }\n\n    return { direct, fallback };\n  }\n}\n"],"names":["fs","path","AgentStatus","matchProcessesToSessions","batchGetSessionFileBirthtimes","isDirectory","isSafePathSegment","listJsonl","safeReaddir","safeStat","homeDir","PID_FILE_STALENESS_MS","ClaudeSessionLocator","projectsDir","sessionsDir","options","join","matchRunningProcesses","processes","direct","resumeDirect","fallback","noResume","tryResumeMatching","pidDirect","tryPidFileMatching","legacySessions","discoverLiveSessions","legacyMatches","length","discoverHistoricalSessionFiles","out","dirName","projectDir","decoded","replace","name","push","filePath","defaultCwd","findHistoricalSessionFilesById","sessionId","matches","isFile","getProjectDir","cwd","encoded","dirToCwd","Map","proc","has","statSync","set","size","files","keys","file","resolvedCwd","get","extractResumeSessionId","command","jsonlPath","stat","pidEntry","readMatchingPidFile","pid","startTime","process","sessionFile","birthtimeMs","pidStatus","mapPidStatus","status","waitingFor","match","procStartTime","pidFilePath","entry","JSON","parse","readFileSync","deltaMs","Math","abs","getTime","startedAt","RUNNING","WAITING","IDLE","undefined","existsSync"],"mappings":"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"}

package/dist/harnesses/claude/ClaudeSessionParser.d.ts

@@ -0,0 +1,148 @@
+import type { ConversationMessage, ConversationOptions } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { type JsonlSummaryBounds } from "../../utils/IncrementalJsonlSummary.js";
+/**
+ * Content block within a Claude Code JSONL message entry.
+ * Handles text, tool_use, and tool_result block types.
+ */
+export interface ContentBlock {
+    type?: string;
+    text?: string;
+    content?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    tool_use_id?: string;
+    is_error?: boolean;
+}
+/**
+ * A single line entry in a Claude Code session JSONL file.
+ *
+ * Each line is an independent JSON object with a type discriminator:
+ * - "user" / "assistant" / "system" — conversation turns
+ * - "progress" / "thinking" — intermediate agent state
+ * - "last-prompt" / "file-history-snapshot" — metadata (not conversation state)
+ */
+export interface SessionEntry {
+    type?: string;
+    timestamp?: string;
+    cwd?: string;
+    message?: {
+        content?: string | ContentBlock[];
+    };
+}
+/**
+ * Parsed session state extracted from a JSONL file.
+ * Aggregates data from all entries into a single summary.
+ */
+export interface ClaudeSession {
+    sessionId: string;
+    projectPath: string;
+    lastCwd?: string;
+    sessionStart: Date;
+    lastActive: Date;
+    lastEntryType?: string;
+    isInterrupted: boolean;
+    lastUserMessage?: string;
+    /** First meaningful user prompt in the session (post noise filter) */
+    firstUserMessage?: string;
+}
+export interface ClaudeSessionParserOptions {
+    /** Cold-start scan bounds for `readSessionIncremental` (see IncrementalJsonlSummary). */
+    summaryBounds?: JsonlSummaryBounds | false;
+}
+/**
+ * Parses Claude Code session JSONL files into structured data.
+ *
+ * Session files live at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
+ * and contain one JSON object per line, each representing a conversation
+ * event (user turn, assistant response, tool call, etc.).
+ */
+export declare class ClaudeSessionParser {
+    /** Incremental reader backing `getConversation({ tail })`. */
+    private readonly tailReader;
+    private readonly sessionCache;
+    constructor(options?: ClaudeSessionParserOptions);
+    /**
+     * Parse a session JSONL file into a ClaudeSession summary.
+     *
+     * Iterates all lines to extract: session start time (from first entry),
+     * last activity timestamp, last entry type (for status), whether the
+     * session was interrupted, and the last meaningful user message.
+     *
+     * Returns null if the file is unreadable or empty.
+     */
+    readSession(filePath: string, projectPath: string): ClaudeSession | null;
+    /**
+     * Same result as `readSession`, but backed by a per-instance incremental
+     * cache so repeated refreshes only parse bytes appended since the last call.
+     * Call `pruneSessionCache()` once per refresh to evict files no longer read.
+     *
+     * The first read of a large transcript is a bounded head + tail scan (see
+     * `summaryReducer.skip`); fields whose entries lie only in the skipped
+     * middle fall back to their defaults instead of forcing a full parse.
+     */
+    readSessionIncremental(filePath: string, projectPath: string): ClaudeSession | null;
+    /** Evict cached summaries for files not read since the previous prune. */
+    pruneSessionCache(): void;
+    /**
+     * Fold one JSONL entry into the O(1) session summary. Mirrors the fields
+     * `readSession` exposes: session start comes from the first line only;
+     * everything else tracks the latest matching entry.
+     *
+     * `skip` (bounded cold start) keeps the head's session start and first user
+     * message and clears every "latest" field, so those come from the tail only:
+     * a first user message beyond the head stays undefined, and a last user
+     * message before the tail window stays undefined.
+     */
+    private readonly summaryReducer;
+    private toSession;
+    /**
+     * Determine agent status from parsed session state.
+     *
+     * Status mapping:
+     * - "user" + interrupted → WAITING (agent finished, awaiting new input)
+     * - "user" + not interrupted → RUNNING (agent is processing)
+     * - "progress" / "thinking" → RUNNING
+     * - "assistant" → WAITING (agent responded, awaiting user)
+     * - "system" → IDLE
+     */
+    determineStatus(session: ClaudeSession): AgentStatus;
+    /**
+     * Read the full conversation from a session JSONL file.
+     *
+     * Default mode returns only text content from user/assistant/system messages.
+     * Verbose mode also includes tool_use and tool_result blocks. With `tail`,
+     * only the last N messages are read (from the end of the file).
+     */
+    getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[];
+    /** Convert one JSONL line into a conversation message, or null when it is not one. */
+    private lineToMessage;
+    /**
+     * Parse session start time (epoch ms) from the first JSONL entry.
+     *
+     * Claude Code may emit a "file-history-snapshot" as the first entry,
+     * which stores its timestamp inside "snapshot.timestamp" rather than
+     * at the root level.
+     */
+    private parseSessionStart;
+    /**
+     * Extract meaningful text from a user message content field.
+     *
+     * Handles multiple formats:
+     * - Plain string content
+     * - Array of content blocks (extracts first text block)
+     * - Skill slash-commands (<command-message> tags)
+     * - Expanded skill content (extracts ARGUMENTS line)
+     * - Filters noise messages (interruptions, tool loaded, session continued)
+     */
+    private extractUserMessageText;
+    /**
+     * Parse a <command-message> string into "/command args" format.
+     */
+    private parseCommandMessage;
+    /**
+     * Extract displayable content from a message content field for conversation output.
+     */
+    private extractConversationContent;
+}
+//# sourceMappingURL=ClaudeSessionParser.d.ts.map

package/dist/harnesses/claude/ClaudeSessionParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeSessionParser.d.ts","sourceRoot":"","sources":["../../../src/harnesses/claude/ClaudeSessionParser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,wCAAwC,CAAC;AAGhD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;KACnC,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,IAAI,CAAC;IACnB,UAAU,EAAE,IAAI,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+BD,MAAM,WAAW,0BAA0B;IACzC,yFAAyF;IACzF,aAAa,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IAEpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8C;gBAE/D,OAAO,GAAE,0BAA+B;IAMpD;;;;;;;;OAQG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAWxE;;;;;;;;OAQG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAKnF,0EAA0E;IAC1E,iBAAiB,IAAI,IAAI;IAIzB;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAyD7B;IAEF,OAAO,CAAC,SAAS;IAmBjB;;;;;;;;;OASG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW;IAwBpD;;;;;;OAMG;IACH,eAAe,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,EAAE;IA8B9F,sFAAsF;IACtF,OAAO,CAAC,aAAa;IA6BrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAwC9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;OAEG;IACH,OAAO,CAAC,0BAA0B;CAoCnC"}