@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/src/harnesses/copilot/CopilotAdapter.ts

@@ -0,0 +1,161 @@
+/**
+ * Copilot Adapter
+ *
+ * Detects running GitHub Copilot CLI agents by:
+ * 1. Filtering Copilot processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
+ * 3. Mapping active ~/.copilot/session-state/{sessionId}/inuse.{pid}.lock files to processes
+ *    (only directories modified since the process started are listed, and a
+ *    known lock is re-validated with one stat on later refreshes)
+ * 4. Reading events.jsonl as the primary session/conversation source (incrementally
+ *    cached across refreshes, so unchanged files are not re-read)
+ * 5. Reading workspace.yaml as a flat fallback metadata source
+ */
+
+import * as path from "path";
+import type {
+  AgentAdapter,
+  AgentInfo,
+  ConversationMessage,
+  ConversationOptions,
+  ListSessionsOptions,
+  ProcessInfo,
+  SessionSummary,
+  AgentDetectionContext,
+} from "../../adapters/AgentAdapter.js";
+import { findWrapperProcess, findWrapperProcessPids } from "../../utils/process.js";
+import { AgentRegistry, type RegistryEntry } from "../../utils/AgentRegistry.js";
+import { CopilotAgentMapper } from "./CopilotAgentMapper.js";
+import { CopilotSessionLocator } from "./CopilotSessionLocator.js";
+import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
+import { findHarnessProcesses, homeDir, matchesExecutable } from "../shared.js";
+
+export interface CopilotAdapterOptions {
+  sessionStateDir?: string;
+}
+
+export class CopilotAdapter implements AgentAdapter {
+  readonly type = "copilot" as const;
+  readonly processNames = ["copilot"] as const;
+
+  private readonly registry: AgentRegistry;
+  private readonly parser: CopilotSessionParser;
+  private readonly mapper: CopilotAgentMapper;
+  private readonly locator: CopilotSessionLocator;
+
+  constructor(
+    registry: AgentRegistry = AgentRegistry.default(),
+    options: CopilotAdapterOptions = {},
+  ) {
+    this.registry = registry;
+    this.parser = new CopilotSessionParser();
+    this.mapper = new CopilotAgentMapper(this.parser);
+    this.locator = new CopilotSessionLocator({
+      sessionStateDir: options.sessionStateDir ?? path.join(homeDir(), ".copilot", "session-state"),
+    });
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    return matchesExecutable(processInfo.command, "copilot");
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    try {
+      return await this.detectRunningAgents(context);
+    } finally {
+      // Drop cached event summaries for sessions that were not part of this refresh
+      this.parser.pruneSessionCache();
+    }
+  }
+
+  private async detectRunningAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { processes } = await findHarnessProcesses(this, context);
+    if (processes.length === 0) return [];
+
+    const processByPid = new Map(processes.map((proc) => [proc.pid, proc]));
+    const registryEntriesByPid = new Map(this.registry.list().map((entry) => [entry.pid, entry]));
+    const matchedPids = new Set<number>();
+    const matchedProcesses: ProcessInfo[] = [];
+    const agents: AgentInfo[] = [];
+
+    for (const lock of this.locator.discoverActiveLocks(processes)) {
+      const proc = processByPid.get(lock.pid);
+      if (!proc) continue;
+
+      const session = this.parser.readSessionDirIncremental(lock.sessionDir, lock.sessionId);
+      if (!session) continue;
+
+      const agent = this.mapper.mapSessionToAgent(session, proc);
+      this.applyWrapperRegistryName(agent, proc, processes, registryEntriesByPid);
+      agents.push(agent);
+      matchedPids.add(proc.pid);
+      matchedProcesses.push(proc);
+    }
+
+    const wrapperPids = findWrapperProcessPids(processes, matchedProcesses);
+    for (const proc of processes) {
+      if (!matchedPids.has(proc.pid) && !wrapperPids.has(proc.pid)) {
+        const agent = this.mapper.mapProcessOnlyAgent(proc);
+        this.applyWrapperRegistryName(agent, proc, processes, registryEntriesByPid);
+        agents.push(agent);
+      }
+    }
+
+    return agents;
+  }
+
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
+    return this.parser.getConversation(sessionFilePath, options);
+  }
+
+  async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+    const summaries: SessionSummary[] = [];
+
+    for (const { sessionDir, sessionId } of this.locator.listSessionDirs()) {
+      const session = this.parser.readSessionDir(sessionDir, sessionId);
+      if (!session) continue;
+      if (opts?.cwd !== undefined && session.projectPath !== opts.cwd) continue;
+
+      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,
+    processes: ProcessInfo[],
+    registryEntriesByPid: Map<number, RegistryEntry>,
+  ): void {
+    const wrapper = findWrapperProcess(processes, processInfo);
+    const wrapperEntry = wrapper ? registryEntriesByPid.get(wrapper.pid) : undefined;
+    if (wrapperEntry?.type === this.type) {
+      agent.name = wrapperEntry.name;
+    }
+  }
+}

package/src/harnesses/copilot/CopilotAgentMapper.ts

@@ -0,0 +1,27 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
+import { processOnlyAgent } from "../shared.js";
+
+export class CopilotAgentMapper {
+  constructor(private readonly parser: CopilotSessionParser = new CopilotSessionParser()) {}
+
+  mapSessionToAgent(session: CopilotSession, processInfo: ProcessInfo): AgentInfo {
+    const projectPath = session.projectPath || processInfo.cwd || "";
+    return {
+      name: generateAgentName(projectPath, processInfo.pid),
+      type: "copilot",
+      status: this.parser.determineStatus(session),
+      summary: session.summary || "Copilot session active",
+      pid: processInfo.pid,
+      projectPath,
+      sessionId: session.sessionId,
+      lastActive: session.lastActive,
+      sessionFilePath: session.eventsFilePath,
+    };
+  }
+
+  mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
+    return processOnlyAgent("copilot", processInfo, { summary: "Copilot process running" });
+  }
+}

package/src/harnesses/copilot/CopilotSessionLocator.ts

@@ -0,0 +1,161 @@
+import * as path from "path";
+import { isDirectory, isSafePathSegment, safeReaddir, safeStat } from "../../utils/session.js";
+import { homeDir } from "../shared.js";
+
+export interface CopilotLock {
+  sessionDir: string;
+  sessionId: string;
+  pid: number;
+}
+
+export interface CopilotSessionDir {
+  sessionDir: string;
+  sessionId: string;
+}
+
+/** A live Copilot process whose `inuse.<pid>.lock` file should be located. */
+export interface CopilotLockProcess {
+  pid: number;
+  startTime?: Date;
+}
+
+export interface CopilotSessionLocatorOptions {
+  sessionStateDir?: string;
+}
+
+interface KnownLock extends CopilotSessionDir {
+  startTimeMs: number;
+}
+
+/**
+ * Tolerance between a reported process start time and its lock directory's
+ * mtime: `ps lstart` has 1 s resolution, Linux start times derive from an
+ * estimated boot time, and some filesystems store coarse mtimes.
+ */
+const START_TIME_SLACK_MS = 5 * 60 * 1000;
+
+const LOCK_FILE_PATTERN = /^inuse\.(\d+)\.lock$/;
+
+export class CopilotSessionLocator {
+  private readonly sessionStateDir: string;
+  /** Lock location per PID, trusted only while that PID's start time is unchanged. */
+  private readonly knownLocks = new Map<number, KnownLock>();
+
+  constructor(options: CopilotSessionLocatorOptions = {}) {
+    this.sessionStateDir =
+      options.sessionStateDir ?? path.join(homeDir(), ".copilot", "session-state");
+  }
+
+  listSessionDirs(): CopilotSessionDir[] {
+    if (!isDirectory(this.sessionStateDir)) return [];
+
+    const sessionDirs: CopilotSessionDir[] = [];
+    for (const sessionId of safeReaddir(this.sessionStateDir)) {
+      const sessionDir = path.join(this.sessionStateDir, sessionId);
+      if (!isDirectory(sessionDir)) continue;
+
+      sessionDirs.push({ sessionDir, sessionId });
+    }
+
+    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;
+  }
+
+  /**
+   * Find `inuse.<pid>.lock` files.
+   *
+   * Without `processes`, every session directory is scanned and all locks are
+   * returned. With `processes`, only locks of those PIDs are returned and the
+   * search is bounded:
+   * - a lock found earlier for the same (pid, startTime) is re-validated with
+   *   a single `stat` (a reused PID has a different start time and misses);
+   * - otherwise only session directories whose mtime is at or after the
+   *   earliest unresolved process start time (minus slack) are listed, since
+   *   creating the lock file bumps its directory's mtime;
+   * - if an unresolved process has no start time, every directory is listed.
+   */
+  discoverActiveLocks(processes?: readonly CopilotLockProcess[]): CopilotLock[] {
+    if (!processes) {
+      return this.scanLocks(undefined, () => true);
+    }
+
+    const startTimes = new Map(processes.map((proc) => [proc.pid, proc.startTime?.getTime()]));
+    for (const [pid, known] of this.knownLocks) {
+      if (startTimes.get(pid) !== known.startTimeMs) {
+        this.knownLocks.delete(pid);
+      }
+    }
+
+    const locks: CopilotLock[] = [];
+    const unresolved = new Set<number>();
+    for (const pid of startTimes.keys()) {
+      const known = this.knownLocks.get(pid);
+      if (known && safeStat(path.join(known.sessionDir, lockFileName(pid)))?.isFile()) {
+        locks.push({ sessionDir: known.sessionDir, sessionId: known.sessionId, pid });
+        continue;
+      }
+      this.knownLocks.delete(pid);
+      unresolved.add(pid);
+    }
+    if (unresolved.size === 0) return locks;
+
+    const unresolvedStarts = [...unresolved].map((pid) => startTimes.get(pid));
+    const minMtimeMs = unresolvedStarts.every((start): start is number => start !== undefined)
+      ? Math.min(...unresolvedStarts) - START_TIME_SLACK_MS
+      : undefined;
+
+    const found = this.scanLocks(minMtimeMs, (pid) => unresolved.has(pid));
+
+    const lockCounts = new Map<number, number>();
+    for (const lock of found) {
+      lockCounts.set(lock.pid, (lockCounts.get(lock.pid) ?? 0) + 1);
+    }
+    for (const lock of found) {
+      const startTimeMs = startTimes.get(lock.pid);
+      // Only remember unambiguous locks of processes with a known start time
+      if (startTimeMs !== undefined && lockCounts.get(lock.pid) === 1) {
+        this.knownLocks.set(lock.pid, {
+          sessionDir: lock.sessionDir,
+          sessionId: lock.sessionId,
+          startTimeMs,
+        });
+      }
+    }
+
+    return locks.concat(found);
+  }
+
+  /** List lock files in session directories with mtime >= `minMtimeMs` (all when undefined). */
+  private scanLocks(
+    minMtimeMs: number | undefined,
+    includePid: (pid: number) => boolean,
+  ): CopilotLock[] {
+    const locks: CopilotLock[] = [];
+    for (const sessionId of safeReaddir(this.sessionStateDir)) {
+      const sessionDir = path.join(this.sessionStateDir, sessionId);
+      const stat = safeStat(sessionDir);
+      if (!stat?.isDirectory()) continue;
+      if (minMtimeMs !== undefined && stat.mtimeMs < minMtimeMs) continue;
+
+      for (const entry of safeReaddir(sessionDir)) {
+        const match = entry.match(LOCK_FILE_PATTERN);
+        if (!match) continue;
+
+        const pid = Number.parseInt(match[1], 10);
+        if (!Number.isFinite(pid) || !includePid(pid)) continue;
+        locks.push({ sessionDir, sessionId, pid });
+      }
+    }
+
+    return locks;
+  }
+}
+
+function lockFileName(pid: number): string {
+  return `inuse.${pid}.lock`;
+}