@ai-devkit/agent-manager 0.10.0 → 0.11.0

package/src/adapters/AgentAdapter.ts

@@ -81,6 +81,70 @@ export interface ConversationMessage {
     timestamp?: string;
 }
 
+/**
+ * A historical session discovered on disk (running or not).
+ *
+ * Used by `listSessions` to surface enough context for a user to identify
+ * a session and resume it via the originating tool's resume command.
+ */
+export interface SessionSummary {
+    /** Tool that produced this session */
+    type: AgentType;
+
+    /**
+     * ID accepted by the tool's resume command. Adapters MUST pass this
+     * through verbatim — no normalization, no encoding/decoding — so it
+     * round-trips into `claude --resume <id>` (and equivalents).
+     */
+    sessionId: string;
+
+    /** Working directory the session was started in (best-known value) */
+    cwd: string;
+
+    /**
+     * Trimmed first user message; empty string if none. Adapters apply
+     * the same noise-filter their existing parsers use (skip tool_result
+     * blocks, request-interruption notices, system-injected skill
+     * content). The CLI table renderer substitutes a placeholder for
+     * empty values; JSON output keeps the empty string raw.
+     */
+    firstUserMessage: string;
+
+    /** Last activity timestamp (from session content; falls back to file mtime) */
+    lastActive: Date;
+
+    /** Session start time (from session content; falls back to file birthtime/mtime) */
+    startedAt: Date;
+
+    /** Absolute path to the session file on disk (debug/diagnostics) */
+    sessionFilePath: string;
+}
+
+/**
+ * Filters passed by the CLI to {@link AgentAdapter.listSessions}.
+ *
+ * The CLI is the source of truth for filter defaults and semantics
+ * (e.g. cwd defaults to process.cwd(); --all clears it). Adapters apply
+ * the values they receive — they don't invent defaults.
+ */
+export interface ListSessionsOptions {
+    /**
+     * Filter to sessions whose recorded cwd matches this path using strict
+     * equality (no prefix/ancestor matching in v1). Undefined = no cwd
+     * filter.
+     */
+    cwd?: string;
+
+    /**
+     * Filter to a single tool. Enforced by `AgentManager.listSessions`,
+     * which skips adapters whose `type` doesn't match. Adapters MAY
+     * ignore this field — by the time their `listSessions` runs, the
+     * type filter is already satisfied. Undefined = include every
+     * registered adapter.
+     */
+    type?: AgentType;
+}
+
 /**
  * Agent Adapter Interface
  *
@@ -110,4 +174,16 @@ export interface AgentAdapter {
      * @returns Array of conversation messages
      */
     getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[];
+
+    /**
+     * Enumerate historical sessions for this tool from disk.
+     *
+     * Applies `opts.cwd` as a strict-equality filter when set. Returns
+     * {@link SessionSummary} entries unsorted; sorting and global filters
+     * are handled by `AgentManager` and the CLI.
+     *
+     * @param opts Filter options computed by the CLI
+     * @returns Array of sessions discovered on disk
+     */
+    listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]>;
 }

package/src/adapters/ClaudeCodeAdapter.ts

@@ -1,9 +1,16 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { AgentAdapter, AgentInfo, ProcessInfo, ConversationMessage } from './AgentAdapter';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './AgentAdapter';
 import { AgentStatus } from './AgentAdapter';
 import { listAgentProcesses, enrichProcesses } from '../utils/process';
-import { batchGetSessionFileBirthtimes } from '../utils/session';
+import { batchGetSessionFileBirthtimes, isDirectory, listJsonl, safeReaddir, safeStat } from '../utils/session';
 import type { SessionFile } from '../utils/session';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching';
 import { ClaudeSessionParser } from '../utils/ClaudeSessionParser';
@@ -265,4 +272,71 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
         return this.parser.getConversation(sessionFilePath, options);
     }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        const filterCwd = opts?.cwd;
+        const candidates = this.discoverSessionFiles();
+        const summaries: SessionSummary[] = [];
+
+        for (const { filePath, defaultCwd } of candidates) {
+            const session = this.parser.readSession(filePath, defaultCwd);
+            if (!session) continue;
+
+            // Drop sessions whose JSONL had no parseable conversation entries.
+            // readSession is permissive (returns a shell record even when every
+            // line fails to parse); listSessions needs at least one real entry
+            // so we don't surface garbage files.
+            if (!session.lastEntryType) continue;
+
+            const recordedCwd = session.lastCwd || defaultCwd;
+            if (filterCwd !== undefined && recordedCwd !== filterCwd) continue;
+
+            const stat = safeStat(filePath);
+
+            summaries.push({
+                type: 'claude',
+                sessionId: session.sessionId,
+                cwd: recordedCwd,
+                firstUserMessage: session.firstUserMessage || '',
+                lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
+                startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
+                sessionFilePath: filePath,
+            });
+        }
+
+        return summaries;
+    }
+
+    /**
+     * Discover candidate session files for {@link listSessions}.
+     *
+     * 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.
+     */
+    private discoverSessionFiles(): Array<{ filePath: string; defaultCwd: string }> {
+        const out: Array<{ filePath: string; defaultCwd: string }> = [];
+
+        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;
+    }
 }

package/src/adapters/CodexAdapter.ts

@@ -12,10 +12,17 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import type { AgentAdapter, AgentInfo, ProcessInfo, ConversationMessage } from './AgentAdapter';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './AgentAdapter';
 import { AgentStatus } from './AgentAdapter';
 import { listAgentProcesses, enrichProcesses } from '../utils/process';
-import { batchGetSessionFileBirthtimes } from '../utils/session';
+import { batchGetSessionFileBirthtimes, isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session';
 import type { SessionFile } from '../utils/session';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching';
 
@@ -326,12 +333,8 @@ export class CodexAdapter implements AgentAdapter {
     getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
         const verbose = options?.verbose ?? false;
 
-        let content: string;
-        try {
-            content = fs.readFileSync(sessionFilePath, 'utf-8');
-        } catch {
-            return [];
-        }
+        const content = safeReadFile(sessionFilePath);
+        if (content === undefined) return [];
 
         const lines = content.trim().split('\n');
         const messages: ConversationMessage[] = [];
@@ -372,4 +375,119 @@ export class CodexAdapter implements AgentAdapter {
 
         return messages;
     }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        if (!isDirectory(this.codexSessionsDir)) return [];
+
+        const files = this.collectAllSessionFiles();
+        const summaries: SessionSummary[] = [];
+
+        for (const filePath of files) {
+            const summary = this.fileToSessionSummary(filePath);
+            if (!summary) continue;
+            if (opts?.cwd !== undefined && summary.cwd !== opts.cwd) continue;
+            summaries.push(summary);
+        }
+
+        return summaries;
+    }
+
+    /**
+     * Walk every YYYY/MM/DD directory under `codexSessionsDir` and return
+     * absolute paths of `.jsonl` files. Tolerates malformed layouts
+     * (skips entries that aren't directories at the expected depth).
+     */
+    private collectAllSessionFiles(): string[] {
+        const out: string[] = [];
+
+        for (const yearEntry of safeReaddir(this.codexSessionsDir)) {
+            const yearDir = path.join(this.codexSessionsDir, yearEntry);
+            if (!isDirectory(yearDir)) continue;
+
+            for (const monthEntry of safeReaddir(yearDir)) {
+                const monthDir = path.join(yearDir, monthEntry);
+                if (!isDirectory(monthDir)) continue;
+
+                for (const dayEntry of safeReaddir(monthDir)) {
+                    const dayDir = path.join(monthDir, dayEntry);
+                    if (!isDirectory(dayDir)) continue;
+
+                    for (const fileEntry of safeReaddir(dayDir)) {
+                        if (!fileEntry.endsWith('.jsonl')) continue;
+                        out.push(path.join(dayDir, fileEntry));
+                    }
+                }
+            }
+        }
+
+        return out;
+    }
+
+    /**
+     * Read a Codex session JSONL file and produce a {@link SessionSummary}.
+     * Returns null when the file is unreadable, has no `session_meta`, or
+     * lacks a session id.
+     */
+    private fileToSessionSummary(filePath: string): SessionSummary | null {
+        const content = safeReadFile(filePath);
+        if (content === undefined) return null;
+
+        const allLines = content.trim().split('\n');
+        if (!allLines[0]) return null;
+
+        let metaEntry: CodexEventEntry;
+        try {
+            metaEntry = JSON.parse(allLines[0]);
+        } catch {
+            return null;
+        }
+
+        if (metaEntry.type !== 'session_meta' || !metaEntry.payload?.id) {
+            return null;
+        }
+
+        let firstUserMessage = '';
+        let lastTimestamp: Date | null = null;
+
+        for (let i = 1; i < allLines.length; i++) {
+            let entry: CodexEventEntry;
+            try {
+                entry = JSON.parse(allLines[i]);
+            } catch {
+                continue;
+            }
+
+            const ts = this.parseTimestamp(entry.timestamp);
+            if (ts) lastTimestamp = ts;
+
+            if (
+                !firstUserMessage &&
+                entry.payload?.type === 'user_message' &&
+                typeof entry.payload.message === 'string' &&
+                entry.payload.message.trim().length > 0
+            ) {
+                firstUserMessage = entry.payload.message.trim();
+            }
+        }
+
+        const stat = safeStat(filePath);
+
+        const startedAt =
+            this.parseTimestamp(metaEntry.payload.timestamp) ||
+            lastTimestamp ||
+            stat?.birthtime ||
+            stat?.mtime ||
+            new Date();
+        const lastActive = lastTimestamp || startedAt;
+
+        return {
+            type: 'codex',
+            sessionId: metaEntry.payload.id,
+            cwd: metaEntry.payload.cwd || '',
+            firstUserMessage,
+            lastActive,
+            startedAt,
+            sessionFilePath: filePath,
+        };
+    }
 }

package/src/adapters/GeminiCliAdapter.ts

@@ -13,9 +13,17 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import type { AgentAdapter, AgentInfo, ProcessInfo, ConversationMessage } from './AgentAdapter';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './AgentAdapter';
 import { AgentStatus } from './AgentAdapter';
 import { listAgentProcesses, enrichProcesses } from '../utils/process';
+import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session';
 import type { SessionFile } from '../utils/session';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching';
 
@@ -441,12 +449,8 @@ export class GeminiCliAdapter implements AgentAdapter {
     getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
         const verbose = options?.verbose ?? false;
 
-        let content: string;
-        try {
-            content = fs.readFileSync(sessionFilePath, 'utf-8');
-        } catch {
-            return [];
-        }
+        const content = safeReadFile(sessionFilePath);
+        if (content === undefined) return [];
 
         let parsed: GeminiSessionFile;
         try {
@@ -485,4 +489,95 @@ export class GeminiCliAdapter implements AgentAdapter {
 
         return messages;
     }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        if (!isDirectory(this.geminiTmpDir)) return [];
+
+        const summaries: SessionSummary[] = [];
+
+        for (const shortId of safeReaddir(this.geminiTmpDir)) {
+            const chatsDir = path.join(
+                this.geminiTmpDir,
+                shortId,
+                GeminiCliAdapter.CHATS_DIR_NAME,
+            );
+            if (!isDirectory(chatsDir)) continue;
+
+            for (const fileName of safeReaddir(chatsDir)) {
+                if (
+                    !fileName.startsWith(GeminiCliAdapter.SESSION_FILE_PREFIX) ||
+                    !fileName.endsWith('.json')
+                ) {
+                    continue;
+                }
+
+                const filePath = path.join(chatsDir, fileName);
+                const summary = this.fileToSessionSummary(filePath);
+                if (!summary) continue;
+                if (opts?.cwd !== undefined && summary.cwd !== opts.cwd) continue;
+                summaries.push(summary);
+            }
+        }
+
+        return summaries;
+    }
+
+    /**
+     * Read a Gemini session JSON file and produce a {@link SessionSummary}.
+     * Returns null when the file is unreadable, the JSON doesn't parse,
+     * or the body lacks a sessionId.
+     */
+    private fileToSessionSummary(filePath: string): SessionSummary | null {
+        const content = safeReadFile(filePath);
+        if (content === undefined) return null;
+
+        let parsed: GeminiSessionFile;
+        try {
+            parsed = JSON.parse(content);
+        } catch {
+            return null;
+        }
+
+        if (!parsed.sessionId) return null;
+
+        const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+        const firstUserMessage = this.extractFirstUserMessage(messages);
+
+        const cwd =
+            Array.isArray(parsed.directories) && parsed.directories.length > 0
+                ? parsed.directories[0]
+                : '';
+
+        const stat = safeStat(filePath);
+
+        const lastEntryTimestamp = this.parseTimestamp(
+            messages.length > 0 ? messages[messages.length - 1]?.timestamp : undefined,
+        );
+        const lastActive =
+            this.parseTimestamp(parsed.lastUpdated) ||
+            lastEntryTimestamp ||
+            stat?.mtime ||
+            new Date();
+        const startedAt =
+            this.parseTimestamp(parsed.startTime) || stat?.birthtime || stat?.mtime || lastActive;
+
+        return {
+            type: 'gemini_cli',
+            sessionId: parsed.sessionId,
+            cwd,
+            firstUserMessage,
+            lastActive,
+            startedAt,
+            sessionFilePath: filePath,
+        };
+    }
+
+    private extractFirstUserMessage(messages: GeminiMessageEntry[]): string {
+        for (const entry of messages) {
+            if (entry?.type !== 'user') continue;
+            const text = this.messageText(entry).trim();
+            if (text) return text;
+        }
+        return '';
+    }
 }

package/src/index.ts

@@ -4,7 +4,15 @@ export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter';
 export { CodexAdapter } from './adapters/CodexAdapter';
 export { GeminiCliAdapter } from './adapters/GeminiCliAdapter';
 export { AgentStatus } from './adapters/AgentAdapter';
-export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo, ConversationMessage } from './adapters/AgentAdapter';
+export type {
+    AgentAdapter,
+    AgentType,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+} from './adapters/AgentAdapter';
 
 export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager';
 export type { TerminalLocation } from './terminal/TerminalFocusManager';

package/src/terminal/TerminalFocusManager.ts

@@ -1,6 +1,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getProcessTty } from '../utils/process';
+import { escapeAppleScript } from '../utils/applescript';
 
 const execFileAsync = promisify(execFile);
 
@@ -17,10 +18,6 @@ export interface TerminalLocation {
     tty: string;        // e.g., "/dev/ttys030"
 }
 
-function escapeAppleScript(text: string): string {
-    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
-
 export class TerminalFocusManager {
     /**
      * Find the terminal location (emulator info) for a given process ID

package/src/terminal/TtyWriter.ts

@@ -2,20 +2,10 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import type { TerminalLocation } from './TerminalFocusManager';
 import { TerminalType } from './TerminalFocusManager';
+import { escapeAppleScript } from '../utils/applescript';
 
 const execFileAsync = promisify(execFile);
 
-/**
- * Escape a string for safe use inside an AppleScript double-quoted string.
- * Backslashes, double quotes, and newlines must be escaped.
- */
-function escapeAppleScript(text: string): string {
-    return text
-        .replace(/\\/g, '\\\\')
-        .replace(/"/g, '\\"')
-        .replace(/\r\n|\r|\n/g, '\\n');
-}
-
 export class TtyWriter {
     /**
      * Send a message as keyboard input to a terminal session.

package/src/utils/ClaudeSessionParser.ts

@@ -47,6 +47,8 @@ export interface ClaudeSession {
     lastEntryType?: string;
     isInterrupted: boolean;
     lastUserMessage?: string;
+    /** First meaningful user prompt in the session (post noise filter) */
+    firstUserMessage?: string;
 }
 
 /** Entry types that are metadata, not conversation state. */
@@ -91,6 +93,7 @@ export class ClaudeSessionParser {
         let lastCwd: string | undefined;
         let isInterrupted = false;
         let lastUserMessage: string | undefined;
+        let firstUserMessage: string | undefined;
 
         for (const line of allLines) {
             try {
@@ -125,6 +128,9 @@ export class ClaudeSessionParser {
                         const text = this.extractUserMessageText(msgContent);
                         if (text) {
                             lastUserMessage = text;
+                            if (!firstUserMessage) {
+                                firstUserMessage = text;
+                            }
                         }
                     } else {
                         isInterrupted = false;
@@ -144,6 +150,7 @@ export class ClaudeSessionParser {
             lastEntryType,
             isInterrupted,
             lastUserMessage,
+            firstUserMessage,
         };
     }
 
@@ -340,9 +347,9 @@ export class ClaudeSessionParser {
         if (!content) return undefined;
 
         if (typeof content === 'string') {
-            const trimmed = content.trim();
-            if (role === 'user' && isNoiseMessage(trimmed)) return undefined;
-            return trimmed || undefined;
+            const cleaned = stripHarnessTags(content);
+            if (role === 'user' && isNoiseMessage(cleaned)) return undefined;
+            return cleaned || undefined;
         }
 
         if (!Array.isArray(content)) return undefined;
@@ -351,8 +358,10 @@ export class ClaudeSessionParser {
 
         for (const block of content) {
             if (block.type === 'text' && block.text?.trim()) {
-                if (role === 'user' && isNoiseMessage(block.text.trim())) continue;
-                parts.push(block.text.trim());
+                const cleaned = stripHarnessTags(block.text);
+                if (!cleaned) continue;
+                if (role === 'user' && isNoiseMessage(cleaned)) continue;
+                parts.push(cleaned);
             } else if (block.type === 'tool_use' && verbose) {
                 const inputSummary = block.input?.file_path || block.input?.pattern || block.input?.command || '';
                 parts.push(`[Tool: ${block.name}]${inputSummary ? ' ' + inputSummary : ''}`);
@@ -367,6 +376,51 @@ export class ClaudeSessionParser {
     }
 }
 
+/**
+ * Tags whose entire block (including content) should be dropped — they are
+ * harness-injected prompt context (system reminders, hook output, command
+ * stdout), not meaningful conversation content.
+ */
+const HARNESS_DROP_TAGS = [
+    'system-reminder',
+    'local-command-stdout',
+    'local-command-stderr',
+    'user-prompt-submit-hook',
+    'command-stdout',
+    'command-stderr',
+    'bash-input',
+    'bash-stdout',
+    'bash-stderr',
+    'command-message',
+] as const;
+
+const HARNESS_DROP_RE = new RegExp(
+    `<(${HARNESS_DROP_TAGS.join('|')})>[\\s\\S]*?</\\1>`,
+    'g',
+);
+
+const COMMAND_INVOCATION_RE =
+    /<command-name>([^<]+)<\/command-name>(?:\s*<command-args>([\s\S]*?)<\/command-args>)?/g;
+
+/**
+ * Remove harness-injected XML blocks from message text and collapse
+ * <command-name>/<command-args> pairs into a "/name args" shorthand.
+ *
+ * Returns the cleaned, trimmed text. Returns an empty string if nothing
+ * survives stripping.
+ */
+function stripHarnessTags(text: string): string {
+    let out = text.replace(HARNESS_DROP_RE, '');
+
+    out = out.replace(COMMAND_INVOCATION_RE, (_match, rawName: string, rawArgs?: string) => {
+        const name = rawName.trim();
+        const args = rawArgs?.trim();
+        return args ? `${name} ${args}` : name;
+    });
+
+    return out.replace(/\n{3,}/g, '\n\n').trim();
+}
+
 /** Check if a message is noise (not a meaningful user intent). */
 function isNoiseMessage(text: string): boolean {
     return (

package/src/utils/applescript.ts

@@ -0,0 +1,10 @@
+/**
+ * Escape a string for safe use inside an AppleScript double-quoted string.
+ * Backslashes, double quotes, and newlines must be escaped.
+ */
+export function escapeAppleScript(text: string): string {
+    return text
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\r\n|\r|\n/g, '\\n');
+}