@ai-devkit/agent-manager 0.32.0 → 0.33.0

package/src/__tests__/utils/session.test.ts

@@ -2,153 +2,147 @@
  * Tests for utils/session.ts
  */
 
-import type { MockedFunction } from 'vitest';
+import type { MockedFunction } from "vitest";
 
-import * as fs from 'fs';
-import { batchGetSessionFileBirthtimes } from '../../utils/session.js';
+import * as fs from "fs";
+import { batchGetSessionFileBirthtimes } from "../../utils/session.js";
 
-vi.mock('fs', () => ({
-    readdirSync: vi.fn(),
-    statSync: vi.fn(),
+vi.mock("fs", () => ({
+  readdirSync: vi.fn(),
+  statSync: vi.fn(),
 }));
 
 const mockedReaddirSync = fs.readdirSync as MockedFunction<typeof fs.readdirSync>;
 const mockedStatSync = fs.statSync as MockedFunction<typeof fs.statSync>;
 
-describe('batchGetSessionFileBirthtimes', () => {
-    beforeEach(() => {
-        mockedReaddirSync.mockReset();
-        mockedStatSync.mockReset();
+describe("batchGetSessionFileBirthtimes", () => {
+  beforeEach(() => {
+    mockedReaddirSync.mockReset();
+    mockedStatSync.mockReset();
+  });
+
+  it("should parse session files correctly", () => {
+    mockedReaddirSync.mockReturnValue(["abc123.jsonl", "def456.jsonl"] as unknown as ReturnType<
+      typeof fs.readdirSync
+    >);
+    mockedStatSync
+      .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
+      .mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/home/.claude/projects/my-app"]);
+
+    expect(results).toHaveLength(2);
+    expect(results[0]).toEqual({
+      sessionId: "abc123",
+      filePath: "/home/.claude/projects/my-app/abc123.jsonl",
+      projectDir: "/home/.claude/projects/my-app",
+      birthtimeMs: 1710800324000,
+      resolvedCwd: "",
     });
-
-    it('should parse session files correctly', () => {
-        mockedReaddirSync.mockReturnValue([
-            'abc123.jsonl',
-            'def456.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
-            .mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/home/.claude/projects/my-app']);
-
-        expect(results).toHaveLength(2);
-        expect(results[0]).toEqual({
-            sessionId: 'abc123',
-            filePath: '/home/.claude/projects/my-app/abc123.jsonl',
-            projectDir: '/home/.claude/projects/my-app',
-            birthtimeMs: 1710800324000,
-            resolvedCwd: '',
-        });
-        expect(results[1].sessionId).toBe('def456');
-        expect(results[1].birthtimeMs).toBe(1710800500000);
-    });
-
-    it('should return empty array for empty dirs list', () => {
-        expect(batchGetSessionFileBirthtimes([])).toEqual([]);
-        expect(mockedReaddirSync).not.toHaveBeenCalled();
-    });
-
-    it('should return empty array on readdir failure', () => {
-        mockedReaddirSync.mockImplementation(() => {
-            throw new Error('ENOENT');
-        });
-
-        expect(batchGetSessionFileBirthtimes(['/some/dir'])).toEqual([]);
+    expect(results[1].sessionId).toBe("def456");
+    expect(results[1].birthtimeMs).toBe(1710800500000);
+  });
+
+  it("should return empty array for empty dirs list", () => {
+    expect(batchGetSessionFileBirthtimes([])).toEqual([]);
+    expect(mockedReaddirSync).not.toHaveBeenCalled();
+  });
+
+  it("should return empty array on readdir failure", () => {
+    mockedReaddirSync.mockImplementation(() => {
+      throw new Error("ENOENT");
     });
 
-    it('should skip files with invalid birthtime (0 or negative)', () => {
-        mockedReaddirSync.mockReturnValue([
-            'bad.jsonl',
-            'negative.jsonl',
-            'good.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 0 } as fs.Stats)
-            .mockReturnValueOnce({ birthtimeMs: -1 } as fs.Stats)
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/dir']);
-        expect(results).toHaveLength(1);
-        expect(results[0].sessionId).toBe('good');
-    });
-
-    it('should skip non-jsonl files', () => {
-        mockedReaddirSync.mockReturnValue([
-            'sessions-index.json',
-            'abc123.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/dir']);
-        expect(results).toHaveLength(1);
-        expect(results[0].sessionId).toBe('abc123');
-    });
-
-    it('should handle empty directory', () => {
-        mockedReaddirSync.mockReturnValue([] as unknown as ReturnType<typeof fs.readdirSync>);
-        expect(batchGetSessionFileBirthtimes(['/dir'])).toEqual([]);
-    });
-
-    it('should handle UUID session IDs', () => {
-        mockedReaddirSync.mockReturnValue([
-            '068e7b1f-cff5-4c94-bf69-b9acd32d765c.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/dir']);
-        expect(results).toHaveLength(1);
-        expect(results[0].sessionId).toBe('068e7b1f-cff5-4c94-bf69-b9acd32d765c');
-    });
-
-    it('should leave resolvedCwd empty', () => {
-        mockedReaddirSync.mockReturnValue([
-            'abc.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/dir']);
-        expect(results[0].resolvedCwd).toBe('');
-    });
-
-    it('should enumerate multiple directories', () => {
-        mockedReaddirSync
-            .mockReturnValueOnce([
-                'sess1.jsonl',
-                'sess3.jsonl',
-            ] as unknown as ReturnType<typeof fs.readdirSync>)
-            .mockReturnValueOnce([
-                'sess2.jsonl',
-            ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
-            .mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats)
-            .mockReturnValueOnce({ birthtimeMs: 1710800400000 } as fs.Stats);
-
-        const results = batchGetSessionFileBirthtimes(['/projects/app-a', '/projects/app-b']);
-
-        expect(mockedReaddirSync).toHaveBeenCalledTimes(2);
-
-        expect(results).toHaveLength(3);
-        expect(results[0].projectDir).toBe('/projects/app-a');
-        expect(results[1].projectDir).toBe('/projects/app-a');
-        expect(results[2].projectDir).toBe('/projects/app-b');
-    });
-
-    it('should skip files where statSync fails', () => {
-        mockedReaddirSync.mockReturnValue([
-            'good.jsonl',
-            'gone.jsonl',
-        ] as unknown as ReturnType<typeof fs.readdirSync>);
-        mockedStatSync
-            .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
-            .mockImplementationOnce(() => { throw new Error('ENOENT'); });
-
-        const results = batchGetSessionFileBirthtimes(['/dir']);
-        expect(results).toHaveLength(1);
-        expect(results[0].sessionId).toBe('good');
-    });
+    expect(batchGetSessionFileBirthtimes(["/some/dir"])).toEqual([]);
+  });
+
+  it("should skip files with invalid birthtime (0 or negative)", () => {
+    mockedReaddirSync.mockReturnValue([
+      "bad.jsonl",
+      "negative.jsonl",
+      "good.jsonl",
+    ] as unknown as ReturnType<typeof fs.readdirSync>);
+    mockedStatSync
+      .mockReturnValueOnce({ birthtimeMs: 0 } as fs.Stats)
+      .mockReturnValueOnce({ birthtimeMs: -1 } as fs.Stats)
+      .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/dir"]);
+    expect(results).toHaveLength(1);
+    expect(results[0].sessionId).toBe("good");
+  });
+
+  it("should skip non-jsonl files", () => {
+    mockedReaddirSync.mockReturnValue([
+      "sessions-index.json",
+      "abc123.jsonl",
+    ] as unknown as ReturnType<typeof fs.readdirSync>);
+    mockedStatSync.mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/dir"]);
+    expect(results).toHaveLength(1);
+    expect(results[0].sessionId).toBe("abc123");
+  });
+
+  it("should handle empty directory", () => {
+    mockedReaddirSync.mockReturnValue([] as unknown as ReturnType<typeof fs.readdirSync>);
+    expect(batchGetSessionFileBirthtimes(["/dir"])).toEqual([]);
+  });
+
+  it("should handle UUID session IDs", () => {
+    mockedReaddirSync.mockReturnValue([
+      "068e7b1f-cff5-4c94-bf69-b9acd32d765c.jsonl",
+    ] as unknown as ReturnType<typeof fs.readdirSync>);
+    mockedStatSync.mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/dir"]);
+    expect(results).toHaveLength(1);
+    expect(results[0].sessionId).toBe("068e7b1f-cff5-4c94-bf69-b9acd32d765c");
+  });
+
+  it("should leave resolvedCwd empty", () => {
+    mockedReaddirSync.mockReturnValue(["abc.jsonl"] as unknown as ReturnType<
+      typeof fs.readdirSync
+    >);
+    mockedStatSync.mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/dir"]);
+    expect(results[0].resolvedCwd).toBe("");
+  });
+
+  it("should enumerate multiple directories", () => {
+    mockedReaddirSync
+      .mockReturnValueOnce(["sess1.jsonl", "sess3.jsonl"] as unknown as ReturnType<
+        typeof fs.readdirSync
+      >)
+      .mockReturnValueOnce(["sess2.jsonl"] as unknown as ReturnType<typeof fs.readdirSync>);
+    mockedStatSync
+      .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
+      .mockReturnValueOnce({ birthtimeMs: 1710800500000 } as fs.Stats)
+      .mockReturnValueOnce({ birthtimeMs: 1710800400000 } as fs.Stats);
+
+    const results = batchGetSessionFileBirthtimes(["/projects/app-a", "/projects/app-b"]);
+
+    expect(mockedReaddirSync).toHaveBeenCalledTimes(2);
+
+    expect(results).toHaveLength(3);
+    expect(results[0].projectDir).toBe("/projects/app-a");
+    expect(results[1].projectDir).toBe("/projects/app-a");
+    expect(results[2].projectDir).toBe("/projects/app-b");
+  });
+
+  it("should skip files where statSync fails", () => {
+    mockedReaddirSync.mockReturnValue(["good.jsonl", "gone.jsonl"] as unknown as ReturnType<
+      typeof fs.readdirSync
+    >);
+    mockedStatSync
+      .mockReturnValueOnce({ birthtimeMs: 1710800324000 } as fs.Stats)
+      .mockImplementationOnce(() => {
+        throw new Error("ENOENT");
+      });
+
+    const results = batchGetSessionFileBirthtimes(["/dir"]);
+    expect(results).toHaveLength(1);
+    expect(results[0].sessionId).toBe("good");
+  });
 });

package/src/adapters/AgentAdapter.ts

@@ -1,6 +1,6 @@
 /**
  * Agent Adapter Interface
- * 
+ *
  * Defines the contract for detecting and managing different types of AI agents.
  * Each adapter is responsible for detecting agents of a specific type (e.g., claude).
  */
@@ -8,83 +8,91 @@
 /**
  * Type of AI agent
  */
-export type AgentType = 'claude' | 'gemini_cli' | 'grok_cli' | 'codex' | 'opencode' | 'copilot' | 'pi' | 'other';
+export type AgentType =
+  | "claude"
+  | "gemini_cli"
+  | "grok_cli"
+  | "codex"
+  | "opencode"
+  | "copilot"
+  | "pi"
+  | "other";
 
 /**
  * Current status of an agent
  */
 export enum AgentStatus {
-    RUNNING = 'running',
-    WAITING = 'waiting',
-    IDLE = 'idle',
-    UNKNOWN = 'unknown'
+  RUNNING = "running",
+  WAITING = "waiting",
+  IDLE = "idle",
+  UNKNOWN = "unknown",
 }
 
 /**
  * Information about a detected agent
  */
 export interface AgentInfo {
-    /** Project-based name (e.g., "ai-devkit" or "ai-devkit (merry)") */
-    name: string;
+  /** Project-based name (e.g., "ai-devkit" or "ai-devkit (merry)") */
+  name: string;
 
-    /** Type of agent */
-    type: AgentType;
+  /** Type of agent */
+  type: AgentType;
 
-    /** Current status */
-    status: AgentStatus;
+  /** Current status */
+  status: AgentStatus;
 
-    /** Last user prompt from history */
-    summary: string;
+  /** Last user prompt from history */
+  summary: string;
 
-    /** Process ID */
-    pid: number;
+  /** Process ID */
+  pid: number;
 
-    /** Working directory/project path */
-    projectPath: string;
+  /** Working directory/project path */
+  projectPath: string;
 
-    /** Session UUID */
-    sessionId: string;
+  /** Session UUID */
+  sessionId: string;
 
-    /** Timestamp of last activity */
-    lastActive: Date;
+  /** Timestamp of last activity */
+  lastActive: Date;
 
-    /** Whether the live process is pinned in the agent console */
-    pinned?: boolean;
+  /** Whether the live process is pinned in the agent console */
+  pinned?: boolean;
 
-    /** Path to the session JSONL file on disk */
-    sessionFilePath?: string;
+  /** Path to the session JSONL file on disk */
+  sessionFilePath?: string;
 }
 
 /**
  * Information about a running process
  */
 export interface ProcessInfo {
-    /** Process ID */
-    pid: number;
+  /** Process ID */
+  pid: number;
 
-    /** Parent process ID, populated by process discovery when available */
-    ppid?: number;
+  /** Parent process ID, populated by process discovery when available */
+  ppid?: number;
 
-    /** Process command */
-    command: string;
+  /** Process command */
+  command: string;
 
-    /** Working directory */
-    cwd: string;
+  /** Working directory */
+  cwd: string;
 
-    /** Terminal TTY (e.g., "ttys030") */
-    tty: string;
+  /** Terminal TTY (e.g., "ttys030") */
+  tty: string;
 
-    /** Process start time, populated by process enrichment */
-    startTime?: Date;
+  /** Process start time, populated by process enrichment */
+  startTime?: Date;
 }
 
 /**
  * A single message in a conversation
  */
 export interface ConversationMessage {
-    role: 'user' | 'assistant' | 'system';
-    content: string;
-    timestamp?: string;
+  role: "user" | "assistant" | "system";
+  content: string;
+  timestamp?: string;
 }
 
 /**
@@ -94,36 +102,36 @@ export interface ConversationMessage {
  * 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;
+  /** 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;
 }
 
 /**
@@ -134,26 +142,26 @@ export interface SessionSummary {
  * 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;
+  /**
+   * 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;
 }
 
 export interface AgentDetectionContext {
-    /** One enriched process snapshot shared across this manager refresh. */
-    readonly processes: readonly ProcessInfo[];
+  /** One enriched process snapshot shared across this manager refresh. */
+  readonly processes: readonly ProcessInfo[];
 }
 
 /**
@@ -162,42 +170,42 @@ export interface AgentDetectionContext {
  * Implementations must provide detection logic for a specific agent type.
  */
 export interface AgentAdapter {
-    /** Type of agent this adapter handles */
-    readonly type: AgentType;
-
-    /** Executable basenames required for shared process discovery. */
-    readonly processNames?: readonly string[];
-
-    /**
-     * Detect running agents of this type
-     * @returns List of detected agents
-     */
-    detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]>;
-
-    /**
-     * Check if this adapter can handle the given process
-     * @param processInfo Process information
-     * @returns True if this adapter can handle the process
-     */
-    canHandle(processInfo: ProcessInfo): boolean;
-
-    /**
-     * Read the full conversation from a session file
-     * @param sessionFilePath Path to the session JSONL file
-     * @param options.verbose Include tool call/result details
-     * @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[]>;
+  /** Type of agent this adapter handles */
+  readonly type: AgentType;
+
+  /** Executable basenames required for shared process discovery. */
+  readonly processNames?: readonly string[];
+
+  /**
+   * Detect running agents of this type
+   * @returns List of detected agents
+   */
+  detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]>;
+
+  /**
+   * Check if this adapter can handle the given process
+   * @param processInfo Process information
+   * @returns True if this adapter can handle the process
+   */
+  canHandle(processInfo: ProcessInfo): boolean;
+
+  /**
+   * Read the full conversation from a session file
+   * @param sessionFilePath Path to the session JSONL file
+   * @param options.verbose Include tool call/result details
+   * @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[]>;
 }