@ai-devkit/agent-manager 0.36.0 → 0.37.0

package/src/{providers → harnesses}/grok/GrokAgentMapper.ts

@@ -1,6 +1,6 @@
 import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
-import { AgentStatus } from "../../adapters/AgentAdapter.js";
 import { generateAgentName } from "../../utils/matching.js";
+import { processOnlyAgent } from "../shared.js";
 import { GrokSessionParser, type GrokSession } from "./GrokSessionParser.js";
 
 export interface GrokSessionAgentInput {
@@ -27,15 +27,6 @@ export class GrokAgentMapper {
 
   /** `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(),
-    };
+    return processOnlyAgent("grok_cli", processInfo, { summary: "Grok CLI process running", cwd });
   }
 }

package/src/{providers → harnesses}/grok/GrokCliAdapter.ts

@@ -3,15 +3,12 @@ import type {
   AgentInfo,
   ProcessInfo,
   ConversationMessage,
+  ConversationOptions,
   SessionSummary,
   ListSessionsOptions,
   AgentDetectionContext,
 } from "../../adapters/AgentAdapter.js";
-import {
-  captureProcessSnapshot,
-  executableBasename,
-  filterByProcessNames,
-} from "../../utils/process.js";
+import { findHarnessProcesses, matchesExecutable } from "../shared.js";
 import { GrokAgentMapper } from "./GrokAgentMapper.js";
 import { GrokSessionLocator } from "./GrokSessionLocator.js";
 import { GrokSessionParser, type GrokSession } from "./GrokSessionParser.js";
@@ -32,6 +29,8 @@ import { GrokSessionParser, type GrokSession } from "./GrokSessionParser.js";
  *    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.
+ *    The summary is cached incrementally across refreshes, so an unchanged
+ *    transcript is not re-read and an appended one is read only from its tail.
  */
 export class GrokCliAdapter implements AgentAdapter {
   readonly type = "grok_cli" as const;
@@ -48,18 +47,20 @@ export class GrokCliAdapter implements AgentAdapter {
   }
 
   canHandle(processInfo: ProcessInfo): boolean {
-    return this.isGrokExecutable(processInfo.command);
+    return matchesExecutable(processInfo.command, "grok");
   }
 
-  private isGrokExecutable(command: string): boolean {
-    const base = executableBasename(command);
-    return base === "grok" || base === "grok.exe";
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    try {
+      return await this.detectRunningAgents(context);
+    } finally {
+      // Drop cached summaries for sessions that were not part of this refresh
+      this.parser.pruneSessionCache();
+    }
   }
 
-  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));
+  private async detectRunningAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { processes } = await findHarnessProcesses(this, context);
     if (processes.length === 0) {
       return [];
     }
@@ -68,7 +69,7 @@ export class GrokCliAdapter implements AgentAdapter {
     for (const { process: proc, cwd, sessionDir } of this.locator.matchRunningProcesses(
       processes,
     )) {
-      const session = sessionDir ? this.parser.readSession(sessionDir, cwd) : null;
+      const session = sessionDir ? this.parser.readSessionIncremental(sessionDir, cwd) : null;
       if (session) {
         agents.push(this.mapper.mapSessionToAgent({ session, processInfo: proc }));
       } else {
@@ -78,7 +79,7 @@ export class GrokCliAdapter implements AgentAdapter {
     return agents;
   }
 
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
     return this.parser.getConversation(sessionFilePath, options);
   }
 

package/src/{providers → harnesses}/grok/GrokSessionLocator.ts

@@ -7,6 +7,7 @@ import {
   safeReaddir,
   safeStat,
 } from "../../utils/session.js";
+import { homeDir } from "../shared.js";
 import { CHAT_HISTORY_FILE } from "./GrokSessionParser.js";
 
 const ACTIVE_SESSIONS_FILE = "active_sessions.json";
@@ -45,8 +46,7 @@ export class GrokSessionLocator {
     // 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.baseDir = options.baseDir ?? (process.env.GROK_HOME || path.join(homeDir(), ".grok"));
     this.sessionsDir = path.join(this.baseDir, "sessions");
   }
 

package/src/harnesses/grok/GrokSessionParser.ts

@@ -0,0 +1,251 @@
+import * as path from "path";
+import type { ConversationMessage, ConversationOptions } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import {
+  IncrementalJsonlSummary,
+  reduceJsonlContent,
+  type JsonlSummaryBounds,
+  type JsonlSummaryReducer,
+} from "../../utils/IncrementalJsonlSummary.js";
+import { JsonlTailReader, normalizeTail } from "../../utils/jsonlTail.js";
+import { safeReadFile, safeStat } from "../../utils/session.js";
+import { flattenTextBlocks, isIdle } from "../shared.js";
+
+export const CHAT_HISTORY_FILE = "chat_history.jsonl";
+
+/** One line of chat_history.jsonl. */
+interface ChatRecord {
+  type?: string;
+  content?: unknown;
+}
+
+/**
+ * O(1) running summary folded from chat records: only the first/last real
+ * prompt and the role of the last user/assistant turn, never the turns.
+ */
+interface GrokSummaryState {
+  /** A bounded cold start skipped the middle: later lines are not the session's first. */
+  pastHead?: boolean;
+  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 interface GrokSessionParserOptions {
+  /** Cold-start scan bounds for `readSessionIncremental` (see IncrementalJsonlSummary). */
+  summaryBounds?: JsonlSummaryBounds | false;
+}
+
+export class GrokSessionParser {
+  /** Incremental reader backing `getConversation({ tail })`. */
+  private readonly tailReader = new JsonlTailReader();
+
+  private readonly sessionCache: IncrementalJsonlSummary<GrokSummaryState>;
+
+  constructor(options: GrokSessionParserOptions = {}) {
+    this.sessionCache = new IncrementalJsonlSummary(this.summaryReducer, {
+      bounds: options.summaryBounds,
+    });
+  }
+
+  /**
+   * 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 content = safeReadFile(chatPath);
+    const state = content === undefined ? {} : reduceJsonlContent(this.summaryReducer, content);
+    return this.toSession(sessionDir, defaultCwd, chatPath, chatStat.mtime, state);
+  }
+
+  /**
+   * 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(sessionDir: string, defaultCwd: string): GrokSession | null {
+    const chatPath = path.join(sessionDir, CHAT_HISTORY_FILE);
+    const result = this.sessionCache.read(chatPath);
+    if (result) {
+      return this.toSession(sessionDir, defaultCwd, chatPath, result.mtime, result.state);
+    }
+    // Present but unreadable: surface the session without a summary, like readSession.
+    const chatStat = safeStat(chatPath);
+    return chatStat ? this.toSession(sessionDir, defaultCwd, chatPath, chatStat.mtime, {}) : null;
+  }
+
+  /** Evict cached summaries for files not read since the previous prune. */
+  pruneSessionCache(): void {
+    this.sessionCache.prune();
+  }
+
+  /** Accepts a session dir or an explicit chat_history.jsonl path. */
+  getConversation(sessionPath: string, options?: ConversationOptions): ConversationMessage[] {
+    const chatPath = this.resolveChatPath(sessionPath);
+    const verbose = options?.verbose ?? false;
+    const tail = normalizeTail(options?.tail);
+    if (tail !== undefined) {
+      return this.tailReader.read(
+        chatPath,
+        tail,
+        { parseLine: (line) => this.lineToMessage(line, verbose) },
+        String(verbose),
+      );
+    }
+    return this.parseChatHistory(chatPath, verbose);
+  }
+
+  /**
+   * 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 {
+    if (isIdle(session.lastActive)) {
+      return AgentStatus.IDLE;
+    }
+    if (session.lastRole === "assistant") {
+      return AgentStatus.WAITING;
+    }
+    return AgentStatus.RUNNING;
+  }
+
+  /**
+   * Fold one chat_history.jsonl entry into the O(1) summary. Uses the same
+   * record rules as `getConversation` (see `toMessage`), minus system records.
+   *
+   * `skip` (bounded cold start) keeps the head's first user message and
+   * clears the last user message and last role, so those come from the tail
+   * only. A first user message beyond the head stays undefined rather than
+   * being filled from the tail; latest fields before the tail window stay
+   * undefined.
+   */
+  private readonly summaryReducer: JsonlSummaryReducer<GrokSummaryState> = {
+    initial: () => ({}),
+    reduce: (state, value) => {
+      const message = this.toMessage(value, false);
+      if (!message) return state;
+      if (message.role === "user") {
+        return {
+          ...state,
+          firstUserMessage:
+            state.firstUserMessage ?? (state.pastHead ? undefined : message.content),
+          lastUserMessage: message.content,
+          lastRole: "user",
+        };
+      }
+      return { ...state, lastRole: message.role };
+    },
+    skip: (state) => ({ pastHead: true, firstUserMessage: state.firstUserMessage }),
+  };
+
+  private toSession(
+    sessionDir: string,
+    defaultCwd: string,
+    chatPath: string,
+    lastActive: Date,
+    state: GrokSummaryState,
+  ): GrokSession {
+    const dirStat = safeStat(sessionDir);
+    return {
+      sessionId: path.basename(sessionDir),
+      projectPath: defaultCwd,
+      sessionFilePath: chatPath,
+      sessionStart: dirStat?.birthtime || lastActive,
+      lastActive,
+      firstUserMessage: state.firstUserMessage,
+      lastUserMessage: state.lastUserMessage,
+      lastRole: state.lastRole,
+    };
+  }
+
+  /** Full pass over chat_history.jsonl building every conversation turn. */
+  private parseChatHistory(chatPath: string, verbose: boolean): ConversationMessage[] {
+    const content = safeReadFile(chatPath);
+    if (content === undefined) return [];
+
+    const messages: ConversationMessage[] = [];
+    for (const line of content.trim().split("\n")) {
+      const message = this.lineToMessage(line, verbose);
+      if (message) messages.push(message);
+    }
+    return messages;
+  }
+
+  /**
+   * Map one parsed chat record to a conversation turn, or null to skip it.
+   * Each record is a { type: 'system' | 'user' | 'assistant', content } object
+   * 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 toMessage(value: unknown, verbose: boolean): ConversationMessage | null {
+    if (!value || typeof value !== "object") return null;
+    const record = value as ChatRecord;
+
+    const text = flattenTextBlocks(record.content);
+    if (record.type === "user") {
+      const query = this.extractUserQuery(text);
+      return query === null ? null : { role: "user", content: query };
+    }
+    if (record.type === "assistant") {
+      return text ? { role: "assistant", content: text } : null;
+    }
+    if (verbose && record.type === "system") {
+      return text ? { role: "system", content: text } : null;
+    }
+    return null;
+  }
+
+  /** Convert one chat_history.jsonl line into a message, or null when it is not one. */
+  private lineToMessage(line: string, verbose: boolean): ConversationMessage | null {
+    if (!line.trim()) return null;
+
+    let record: unknown;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      return null;
+    }
+    return this.toMessage(record, verbose);
+  }
+
+  /**
+   * 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);
+  }
+}

package/src/harnesses/index.ts

@@ -0,0 +1,28 @@
+import type { AgentAdapter } from "../adapters/AgentAdapter.js";
+import { AntigravityCliAdapter } from "./antigravity/AntigravityCliAdapter.js";
+import { ClaudeCodeAdapter } from "./claude/ClaudeCodeAdapter.js";
+import { CodexAdapter } from "./codex/CodexAdapter.js";
+import { CopilotAdapter } from "./copilot/CopilotAdapter.js";
+import { GeminiCliAdapter } from "./gemini/GeminiCliAdapter.js";
+import { GrokCliAdapter } from "./grok/GrokCliAdapter.js";
+import { KiroAdapter } from "./kiro/KiroAdapter.js";
+import { OpenCodeAdapter } from "./opencode/OpenCodeAdapter.js";
+import { PiAdapter } from "./pi/PiAdapter.js";
+
+/**
+ * One instance of every built-in harness adapter, in registration order
+ * (which is also the order agents are listed in). Register a new harness here.
+ */
+export function createBuiltinAdapters(): AgentAdapter[] {
+  return [
+    new ClaudeCodeAdapter(),
+    new CodexAdapter(),
+    new CopilotAdapter(),
+    new GeminiCliAdapter(),
+    new GrokCliAdapter(),
+    new KiroAdapter(),
+    new AntigravityCliAdapter(),
+    new OpenCodeAdapter(),
+    new PiAdapter(),
+  ];
+}

package/src/harnesses/kiro/KiroAdapter.ts

@@ -0,0 +1,143 @@
+import * as path from "path";
+import type {
+  AgentAdapter,
+  AgentInfo,
+  ProcessInfo,
+  ConversationMessage,
+  ConversationOptions,
+  SessionSummary,
+  ListSessionsOptions,
+  AgentDetectionContext,
+} from "../../adapters/AgentAdapter.js";
+import { executablePath } from "../../utils/process.js";
+import { findHarnessProcesses } from "../shared.js";
+import { KiroAgentMapper } from "./KiroAgentMapper.js";
+import { KiroSessionLocator } from "./KiroSessionLocator.js";
+import { KiroSessionParser, type KiroSession } from "./KiroSessionParser.js";
+
+const KIRO_BASENAMES = new Set(["kiro-cli", "kiro"]);
+const SCRIPT_RUNTIMES = new Set(["node", "bun"]);
+
+/**
+ * Kiro Adapter
+ *
+ * Detects running Kiro agents by matching the PID in each
+ * ~/.kiro/sessions/cli/<session-id>.lock to a running Kiro process (walking up
+ * from helper processes such as `kiro-cli-chat acp`), then reading the sibling
+ * <session-id>.json metadata and <session-id>.jsonl transcript.
+ */
+export class KiroAdapter implements AgentAdapter {
+  readonly type = "kiro" as const;
+  /**
+   * Also collects the helpers between a lock holder and its kiro-cli, such as
+   * the bundled `bun … tui.js`; `canHandle` still decides which are agents.
+   */
+  readonly processNames = ["kiro-cli", "kiro", "kiro-cli-chat", "node", "bun"] as const;
+
+  private parser: KiroSessionParser;
+  private mapper: KiroAgentMapper;
+  private locator: KiroSessionLocator;
+
+  constructor() {
+    this.parser = new KiroSessionParser();
+    this.mapper = new KiroAgentMapper(this.parser);
+    this.locator = new KiroSessionLocator();
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    return this.isKiroExecutable(processInfo.command);
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    try {
+      return await this.detectRunningAgents(context);
+    } finally {
+      // Drop cached summaries for sessions that were not part of this refresh
+      this.parser.pruneSessionCache();
+    }
+  }
+
+  private async detectRunningAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { relevant, processes } = await findHarnessProcesses(this, context);
+    if (processes.length === 0) return [];
+
+    const agents: AgentInfo[] = [];
+    const matchedPids = new Set<number>();
+    for (const match of this.locator.matchRunningProcesses(relevant, processes, (process) =>
+      this.canHandle(process),
+    )) {
+      const session = this.parser.readSessionIncremental(match.session, match.process.cwd);
+      if (!session) continue;
+
+      agents.push(this.mapper.mapSessionToAgent({ session, processInfo: match.process }));
+      matchedPids.add(match.process.pid);
+    }
+
+    for (const proc of processes) {
+      if (!matchedPids.has(proc.pid)) {
+        agents.push(this.mapper.mapProcessOnlyAgent(proc));
+      }
+    }
+    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 paths of this.locator.listSessions()) {
+      const session = this.parser.readSession(paths);
+      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 paths = this.locator.findSession(sessionId);
+    const session = paths ? this.parser.readSession(paths) : null;
+    // listSessions reports the metadata's id, so only an exact match counts.
+    return session?.sessionId === sessionId ? [this.toSessionSummary(session)] : [];
+  }
+
+  private toSessionSummary(session: KiroSession): SessionSummary {
+    return {
+      type: this.type,
+      sessionId: session.sessionId,
+      cwd: session.projectPath,
+      firstUserMessage: session.firstUserMessage,
+      lastActive: session.lastActive,
+      startedAt: session.sessionStart,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+
+  /** `kiro-cli` / `kiro`, directly or as a script run by node or bun. */
+  private isKiroExecutable(command: string): boolean {
+    const trimmed = command.trim();
+    const executable = executablePath(trimmed);
+    if (!executable) return false;
+
+    const executableName = kiroBasename(executable);
+    if (KIRO_BASENAMES.has(executableName)) return true;
+    if (!SCRIPT_RUNTIMES.has(executableName)) return false;
+
+    const args = trimmed.slice(executable.length).trim().split(/\s+/);
+    const scriptIndex = args.findIndex((token) => token !== "" && !token.startsWith("-"));
+    if (scriptIndex === -1) return false;
+    // The script path may also contain spaces; resolve it like argv[0].
+    const script = executablePath(args.slice(scriptIndex).join(" "));
+    return KIRO_BASENAMES.has(kiroBasename(script));
+  }
+}
+
+function kiroBasename(executable: string): string {
+  return path
+    .basename(executable.replace(/\\/g, "/"))
+    .toLowerCase()
+    .replace(/\.(exe|js)$/, "");
+}

package/src/harnesses/kiro/KiroAgentMapper.ts

@@ -0,0 +1,34 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import { processOnlyAgent, SUMMARY_MAX_LENGTH, truncate } from "../shared.js";
+import { KiroSessionParser, type KiroSession } from "./KiroSessionParser.js";
+
+export interface KiroSessionAgentInput {
+  session: KiroSession;
+  processInfo: ProcessInfo;
+}
+
+export class KiroAgentMapper {
+  constructor(private readonly parser: KiroSessionParser = new KiroSessionParser()) {}
+
+  mapSessionToAgent({ session, processInfo }: KiroSessionAgentInput): AgentInfo {
+    return {
+      name: generateAgentName(session.projectPath, processInfo.pid),
+      type: "kiro",
+      status: this.parser.determineStatus(session),
+      summary: truncate(
+        session.lastUserMessage || session.title || "Kiro session active",
+        SUMMARY_MAX_LENGTH,
+      ),
+      pid: processInfo.pid,
+      projectPath: session.projectPath,
+      sessionId: session.sessionId,
+      lastActive: session.lastActive,
+      sessionFilePath: session.sessionFilePath,
+    };
+  }
+
+  mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
+    return processOnlyAgent("kiro", processInfo, { summary: "Kiro process running" });
+  }
+}