@ai-devkit/agent-manager 0.36.0 → 0.37.0

package/src/harnesses/kiro/KiroSessionLocator.ts

@@ -0,0 +1,143 @@
+import * as path from "path";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
+import {
+  isDirectory,
+  isSafePathSegment,
+  safeReadFile,
+  safeReaddir,
+  safeStat,
+} from "../../utils/session.js";
+import { homeDir } from "../shared.js";
+import { asRecord, type KiroSessionPaths } from "./KiroSessionParser.js";
+
+/** A live Kiro process and the session whose lock it holds. */
+export interface KiroProcessMatch {
+  process: ProcessInfo;
+  session: KiroSessionPaths;
+}
+
+export interface KiroSessionLocatorOptions {
+  /** Overrides ~/.kiro/sessions/cli. */
+  sessionsDir?: string;
+}
+
+interface KiroLock {
+  sessionId: string;
+  pid: number;
+}
+
+export class KiroSessionLocator {
+  private readonly sessionsDir: string;
+
+  constructor(options: KiroSessionLocatorOptions = {}) {
+    this.sessionsDir = options.sessionsDir ?? path.join(homeDir(), ".kiro", "sessions", "cli");
+  }
+
+  /**
+   * Pair `<session-id>.lock` files with running Kiro processes.
+   *
+   * @param snapshot every process collected for Kiro's process names, used to
+   *   walk up from the lock's PID (often a `kiro-cli-chat acp` helper)
+   * @param kiroProcesses the top-level Kiro processes that become agents
+   * @param isKiro whether a process is a top-level Kiro process
+   */
+  matchRunningProcesses(
+    snapshot: readonly ProcessInfo[],
+    kiroProcesses: readonly ProcessInfo[],
+    isKiro: (process: ProcessInfo) => boolean,
+  ): KiroProcessMatch[] {
+    const byPid = new Map(snapshot.map((proc) => [proc.pid, proc]));
+    const matches: KiroProcessMatch[] = [];
+
+    for (const lock of this.discoverActiveLocks()) {
+      const proc =
+        this.findKiroAncestor(lock.pid, byPid, isKiro) ??
+        this.matchSoleProcessOnTty(byPid.get(lock.pid)?.tty, kiroProcesses);
+      if (proc) matches.push({ process: proc, session: this.sessionPaths(lock.sessionId) });
+    }
+    return matches;
+  }
+
+  /** Every session with a transcript under the sessions dir. */
+  listSessions(): KiroSessionPaths[] {
+    if (!isDirectory(this.sessionsDir)) return [];
+
+    return safeReaddir(this.sessionsDir)
+      .filter((entry) => entry.endsWith(".jsonl"))
+      .map((entry) => this.sessionPaths(entry.slice(0, -".jsonl".length)));
+  }
+
+  /** The session stored as `<sessionId>.jsonl`, if it exists. */
+  findSession(sessionId: string): KiroSessionPaths | null {
+    if (!isSafePathSegment(sessionId)) return null;
+    const paths = this.sessionPaths(sessionId);
+    return safeStat(paths.transcriptPath)?.isFile() ? paths : null;
+  }
+
+  private sessionPaths(sessionId: string): KiroSessionPaths {
+    return {
+      sessionId,
+      transcriptPath: path.join(this.sessionsDir, `${sessionId}.jsonl`),
+      metadataPath: path.join(this.sessionsDir, `${sessionId}.json`),
+    };
+  }
+
+  private discoverActiveLocks(): KiroLock[] {
+    if (!isDirectory(this.sessionsDir)) return [];
+
+    const locks: KiroLock[] = [];
+    for (const entry of safeReaddir(this.sessionsDir)) {
+      if (!entry.endsWith(".lock")) continue;
+
+      const content = safeReadFile(path.join(this.sessionsDir, entry));
+      if (content === undefined) continue;
+
+      let pid: number | null;
+      try {
+        pid = toPid(asRecord(JSON.parse(content))?.pid);
+      } catch {
+        continue;
+      }
+      if (pid !== null) locks.push({ sessionId: entry.slice(0, -".lock".length), pid });
+    }
+    return locks;
+  }
+
+  /** The outermost Kiro process on the lock PID's parent chain, if collected. */
+  private findKiroAncestor(
+    lockPid: number,
+    byPid: Map<number, ProcessInfo>,
+    isKiro: (process: ProcessInfo) => boolean,
+  ): ProcessInfo | null {
+    let current = byPid.get(lockPid);
+    const seen = new Set<number>();
+    let resolved: ProcessInfo | null = null;
+
+    while (current && !seen.has(current.pid)) {
+      seen.add(current.pid);
+      if (isKiro(current)) resolved = current;
+      current = current.ppid === undefined ? undefined : byPid.get(current.ppid);
+    }
+    return resolved;
+  }
+
+  /**
+   * Fallback when the chain is broken (an uncollected intermediate process):
+   * attach to the only Kiro process on the lock holder's terminal.
+   */
+  private matchSoleProcessOnTty(
+    tty: string | undefined,
+    kiroProcesses: readonly ProcessInfo[],
+  ): ProcessInfo | null {
+    if (!tty || tty === "??" || tty === "?") return null;
+    const matches = kiroProcesses.filter((proc) => proc.tty === tty);
+    return matches.length === 1 ? matches[0] : null;
+  }
+}
+
+function toPid(value: unknown): number | null {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return value;
+  if (typeof value !== "string" || !/^\d+$/.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}

package/src/harnesses/kiro/KiroSessionParser.ts

@@ -0,0 +1,376 @@
+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 { isIdle, parseTimestamp } from "../shared.js";
+
+type KiroRecord = Record<string, unknown>;
+
+/** One line of <session-id>.jsonl. */
+interface KiroLine {
+  kind?: string;
+  timestamp?: string;
+  data?: KiroRecord;
+}
+
+/** The sibling <session-id>.json metadata file. */
+interface KiroMetadata {
+  sessionId: string;
+  cwd: string;
+  title: string;
+  createdAt: Date | null;
+  updatedAt: Date | null;
+}
+
+/** O(1) running summary folded from transcript lines, never the entries themselves. */
+interface KiroSummaryState {
+  /** A bounded cold start skipped the middle: later lines are not the session's first. */
+  pastHead?: boolean;
+  firstUserMessage?: string;
+  lastUserMessage?: string;
+  /** First and last entry timestamps in file order, in epoch ms. */
+  firstTimestampMs?: number;
+  lastTimestampMs?: number;
+  lastEventKind?: string;
+  lastAssistantHasToolUse?: boolean;
+}
+
+export interface KiroSessionParserOptions {
+  /** Cold-start scan bounds for `readSessionIncremental` (see IncrementalJsonlSummary). */
+  summaryBounds?: JsonlSummaryBounds | false;
+}
+
+export interface KiroSessionPaths {
+  sessionId: string;
+  transcriptPath: string;
+  metadataPath: string;
+}
+
+export interface KiroSession {
+  sessionId: string;
+  projectPath: string;
+  sessionFilePath: string;
+  title: string;
+  firstUserMessage: string;
+  lastUserMessage?: string;
+  sessionStart: Date;
+  lastActive: Date;
+  lastEventKind?: string;
+  lastAssistantHasToolUse: boolean;
+}
+
+export class KiroSessionParser {
+  /** Incremental reader backing `getConversation({ tail })`. */
+  private readonly tailReader = new JsonlTailReader();
+
+  private readonly sessionCache: IncrementalJsonlSummary<KiroSummaryState>;
+
+  constructor(options: KiroSessionParserOptions = {}) {
+    this.sessionCache = new IncrementalJsonlSummary(this.summaryReducer, {
+      bounds: options.summaryBounds,
+    });
+  }
+
+  /**
+   * Parse a session from its transcript and metadata. Metadata wins for the
+   * session id, cwd and timestamps; `fallbackCwd` is used when it has no cwd.
+   * Returns null when the transcript is missing.
+   */
+  readSession(paths: KiroSessionPaths, fallbackCwd = ""): KiroSession | null {
+    const stat = safeStat(paths.transcriptPath);
+    if (!stat?.isFile()) return null;
+
+    const content = safeReadFile(paths.transcriptPath);
+    const state = content === undefined ? {} : reduceJsonlContent(this.summaryReducer, content);
+    return this.toSession(paths, fallbackCwd, stat, state);
+  }
+
+  /**
+   * Same result as `readSession`, but the transcript summary is backed by a
+   * per-instance incremental cache, so repeated refreshes only parse bytes
+   * appended since the last call. The small metadata file is still read each
+   * time. Call `pruneSessionCache()` once per refresh.
+   */
+  readSessionIncremental(paths: KiroSessionPaths, fallbackCwd = ""): KiroSession | null {
+    const stat = safeStat(paths.transcriptPath);
+    if (!stat?.isFile()) return null;
+
+    // Present but unreadable: surface the session without a summary, like readSession.
+    const state = this.sessionCache.read(paths.transcriptPath)?.state ?? {};
+    return this.toSession(paths, fallbackCwd, stat, state);
+  }
+
+  /** Evict cached summaries for files not read since the previous prune. */
+  pruneSessionCache(): void {
+    this.sessionCache.prune();
+  }
+
+  getConversation(transcriptPath: string, options?: ConversationOptions): ConversationMessage[] {
+    const verbose = options?.verbose ?? false;
+    const tail = normalizeTail(options?.tail);
+    if (tail === undefined) {
+      return this.entriesToMessages(this.readJsonl(transcriptPath), verbose);
+    }
+
+    return this.tailReader.read(
+      transcriptPath,
+      tail,
+      {
+        parseLine: (line) => {
+          const entry = this.parseJsonlLine(line);
+          return entry ? this.entryToMessage(entry, verbose) : null;
+        },
+      },
+      String(verbose),
+    );
+  }
+
+  /**
+   * - past the idle threshold → IDLE
+   * - last event is an assistant reply without a tool call → WAITING
+   * - otherwise (user prompt, tool call or tool result) → RUNNING
+   */
+  determineStatus(session: KiroSession): AgentStatus {
+    if (isIdle(session.lastActive)) return AgentStatus.IDLE;
+    if (session.lastEventKind === "AssistantMessage" && !session.lastAssistantHasToolUse) {
+      return AgentStatus.WAITING;
+    }
+    return AgentStatus.RUNNING;
+  }
+
+  /**
+   * Fold one transcript line into the O(1) summary. Uses the same entry rules
+   * as `getConversation` (see `entryToMessage`); non-object lines are ignored.
+   *
+   * `skip` (bounded cold start) keeps the head's first prompt and timestamp and
+   * resets the latest fields, so those come from the tail only.
+   */
+  private readonly summaryReducer: JsonlSummaryReducer<KiroSummaryState> = {
+    initial: () => ({}),
+    reduce: (state, value) => {
+      const entry = asRecord(value) as KiroLine | null;
+      if (!entry) return state;
+
+      const next: KiroSummaryState = {
+        ...state,
+        lastEventKind: entry.kind,
+        lastAssistantHasToolUse:
+          entry.kind === "AssistantMessage" && this.hasContentKind(entry, "toolUse"),
+      };
+
+      const timestampMs = parseTimestamp(this.entryTimestamp(entry))?.getTime();
+      if (timestampMs !== undefined) {
+        next.lastTimestampMs = timestampMs;
+        if (next.firstTimestampMs === undefined && !next.pastHead) {
+          next.firstTimestampMs = timestampMs;
+        }
+      }
+
+      const message = this.entryToMessage(entry, false);
+      if (message?.role === "user") {
+        next.lastUserMessage = message.content;
+        if (next.firstUserMessage === undefined && !next.pastHead) {
+          next.firstUserMessage = message.content;
+        }
+      }
+      return next;
+    },
+    skip: (state) => ({
+      pastHead: true,
+      firstUserMessage: state.firstUserMessage,
+      firstTimestampMs: state.firstTimestampMs,
+    }),
+  };
+
+  private toSession(
+    paths: KiroSessionPaths,
+    fallbackCwd: string,
+    stat: { birthtime: Date; mtime: Date },
+    state: KiroSummaryState,
+  ): KiroSession {
+    const metadata = this.readMetadata(paths);
+    const firstTimestamp =
+      state.firstTimestampMs === undefined ? undefined : new Date(state.firstTimestampMs);
+    const lastTimestamp =
+      state.lastTimestampMs === undefined ? undefined : new Date(state.lastTimestampMs);
+
+    return {
+      sessionId: metadata.sessionId,
+      projectPath: metadata.cwd || fallbackCwd,
+      sessionFilePath: paths.transcriptPath,
+      title: metadata.title,
+      firstUserMessage: state.firstUserMessage ?? "",
+      lastUserMessage: state.lastUserMessage,
+      sessionStart: metadata.createdAt ?? firstTimestamp ?? stat.birthtime,
+      lastActive: metadata.updatedAt ?? lastTimestamp ?? stat.mtime,
+      lastEventKind: state.lastEventKind,
+      lastAssistantHasToolUse: state.lastAssistantHasToolUse ?? false,
+    };
+  }
+
+  private readMetadata({ sessionId, metadataPath }: KiroSessionPaths): KiroMetadata {
+    const empty: KiroMetadata = {
+      sessionId,
+      cwd: "",
+      title: "",
+      createdAt: null,
+      updatedAt: null,
+    };
+    const content = safeReadFile(metadataPath);
+    if (content === undefined) return empty;
+
+    let parsed: KiroRecord | null;
+    try {
+      parsed = asRecord(JSON.parse(content));
+    } catch {
+      return empty;
+    }
+    if (!parsed) return empty;
+
+    return {
+      sessionId: firstString(parsed.session_id, parsed.sessionId) ?? sessionId,
+      cwd: firstString(parsed.cwd) ?? "",
+      title: firstString(parsed.title) ?? "",
+      createdAt: parseTimestamp(parsed.created_at ?? parsed.createdAt),
+      updatedAt: parseTimestamp(parsed.updated_at ?? parsed.updatedAt),
+    };
+  }
+
+  private readJsonl(filePath: string): KiroLine[] {
+    const content = safeReadFile(filePath);
+    if (content === undefined) return [];
+
+    const entries: KiroLine[] = [];
+    for (const line of content.split(/\r?\n/)) {
+      const entry = this.parseJsonlLine(line);
+      if (entry) entries.push(entry);
+    }
+    return entries;
+  }
+
+  private parseJsonlLine(line: string): KiroLine | null {
+    const trimmed = line.trim();
+    if (!trimmed) return null;
+    try {
+      return asRecord(JSON.parse(trimmed)) as KiroLine | null;
+    } catch {
+      return null;
+    }
+  }
+
+  private entriesToMessages(entries: KiroLine[], verbose: boolean): ConversationMessage[] {
+    const messages: ConversationMessage[] = [];
+    for (const entry of entries) {
+      const message = this.entryToMessage(entry, verbose);
+      if (message) messages.push(message);
+    }
+    return messages;
+  }
+
+  /**
+   * Prompt → user, AssistantMessage → assistant (tool calls appended in
+   * verbose mode), ToolResults → system (verbose only).
+   */
+  private entryToMessage(entry: KiroLine, verbose: boolean): ConversationMessage | null {
+    let role: ConversationMessage["role"];
+    let content: string;
+
+    if (entry.kind === "Prompt") {
+      role = "user";
+      content = this.textContent(entry);
+    } else if (entry.kind === "AssistantMessage") {
+      role = "assistant";
+      const parts = [this.textContent(entry)];
+      if (verbose) parts.push(...this.toolUseContent(entry));
+      content = parts.filter(Boolean).join("\n");
+    } else if (entry.kind === "ToolResults" && verbose) {
+      role = "system";
+      content = this.toolResultContent(entry).join("\n");
+    } else {
+      return null;
+    }
+
+    if (!content) return null;
+    return {
+      role,
+      content,
+      timestamp: this.entryTimestamp(entry),
+    };
+  }
+
+  private textContent(entry: KiroLine): string {
+    return this.contentBlocks(entry)
+      .filter((block) => block.kind === "text")
+      .map((block) => (typeof block.data === "string" ? block.data : ""))
+      .filter(Boolean)
+      .join("");
+  }
+
+  private toolUseContent(entry: KiroLine): string[] {
+    return this.contentBlocks(entry)
+      .filter((block) => block.kind === "toolUse")
+      .map((block) => {
+        const data = asRecord(block.data);
+        const name = firstString(data?.name) ?? "unknown";
+        const input = formatValue(data?.input);
+        return `[Tool: ${name}]${input ? ` ${input}` : ""}`;
+      });
+  }
+
+  private toolResultContent(entry: KiroLine): string[] {
+    return this.contentBlocks(entry)
+      .filter((block) => block.kind === "toolResult")
+      .map((block) => {
+        const data = asRecord(block.data);
+        const prefix = data?.status === "error" ? "[Tool Error]" : "[Tool Result]";
+        const result = formatValue(data?.result ?? data?.results ?? data?.content);
+        return `${prefix}${result ? ` ${result}` : ""}`;
+      });
+  }
+
+  private contentBlocks(entry: KiroLine): Array<{ kind?: string; data?: unknown }> {
+    const content = entry.data?.content;
+    if (!Array.isArray(content)) return [];
+    return content
+      .map((block) => asRecord(block))
+      .filter((block): block is KiroRecord => block !== null);
+  }
+
+  private hasContentKind(entry: KiroLine, kind: string): boolean {
+    return this.contentBlocks(entry).some((block) => block.kind === kind);
+  }
+
+  /** The line's own timestamp, else `data.meta.timestamp` (epoch seconds/ms or ISO). */
+  private entryTimestamp(entry: KiroLine): string | undefined {
+    const direct = firstString(entry.timestamp);
+    if (direct) return direct;
+
+    const meta = asRecord(entry.data?.meta);
+    return parseTimestamp(meta?.timestamp)?.toISOString();
+  }
+}
+
+export function asRecord(value: unknown): KiroRecord | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as KiroRecord;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  return values.find((value): value is string => typeof value === "string" && value.length > 0);
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined || value === null) return "";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}

package/src/{providers → harnesses}/opencode/OpenCodeAdapter.ts

@@ -16,18 +16,15 @@ import type {
   AgentInfo,
   ProcessInfo,
   ConversationMessage,
+  ConversationOptions,
   SessionSummary,
   ListSessionsOptions,
   AgentDetectionContext,
 } from "../../adapters/AgentAdapter.js";
-import {
-  captureProcessSnapshot,
-  executableBasename,
-  filterByProcessNames,
-} from "../../utils/process.js";
 import { OpenCodeAgentMapper } from "./OpenCodeAgentMapper.js";
 import { OpenCodeSessionLocator } from "./OpenCodeSessionLocator.js";
 import { OpenCodeSessionParser } from "./OpenCodeSessionParser.js";
+import { findHarnessProcesses, matchesExecutable } from "../shared.js";
 
 const SESSION_REF_SEP = "::";
 
@@ -63,14 +60,11 @@ export class OpenCodeAdapter implements AgentAdapter {
   }
 
   canHandle(processInfo: ProcessInfo): boolean {
-    const base = executableBasename(processInfo.command);
-    return base === "opencode" || base === "opencode.exe";
+    return matchesExecutable(processInfo.command, "opencode");
   }
 
   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));
+    const { processes } = await findHarnessProcesses(this, context);
     if (processes.length === 0) return [];
 
     const db = this.locator.openDb();
@@ -96,7 +90,7 @@ export class OpenCodeAdapter implements AgentAdapter {
     return agents;
   }
 
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
     const ref = decodeSessionRef(sessionFilePath);
     if (!ref) return [];
 

package/src/{providers → harnesses}/opencode/OpenCodeAgentMapper.ts

@@ -3,9 +3,9 @@ import { AgentStatus } from "../../adapters/AgentAdapter.js";
 import { generateAgentName } from "../../utils/matching.js";
 import type { OpenCodeSession } from "./OpenCodeSessionLocator.js";
 import type { OpenCodeSessionStats } from "./OpenCodeSessionParser.js";
+import { isIdle, processOnlyAgent } from "../shared.js";
 
 const SESSION_REF_SEP = "::";
-const IDLE_THRESHOLD_MINUTES = 5;
 
 function encodeSessionRef(dbPath: string, sessionId: string): string {
   return `${dbPath}${SESSION_REF_SEP}${sessionId}`;
@@ -36,21 +36,11 @@ export class OpenCodeAgentMapper {
   }
 
   mapProcessOnlyAgent(proc: ProcessInfo): AgentInfo {
-    return {
-      name: generateAgentName(proc.cwd || "", proc.pid),
-      type: "opencode",
-      status: AgentStatus.RUNNING,
-      summary: "OpenCode process running",
-      pid: proc.pid,
-      projectPath: proc.cwd || "",
-      sessionId: `pid-${proc.pid}`,
-      lastActive: new Date(),
-    };
+    return processOnlyAgent("opencode", proc, { summary: "OpenCode process running" });
   }
 
   private determineStatus(stats: OpenCodeSessionStats, lastActive: Date): AgentStatus {
-    const ageMin = (Date.now() - lastActive.getTime()) / 60000;
-    if (ageMin > IDLE_THRESHOLD_MINUTES) return AgentStatus.IDLE;
+    if (isIdle(lastActive)) return AgentStatus.IDLE;
 
     if (stats.lastRole === "assistant" && !stats.lastAssistantCompleted) {
       return AgentStatus.RUNNING;

package/src/{providers → harnesses}/opencode/OpenCodeSessionLocator.ts

@@ -3,6 +3,7 @@ import * as path from "path";
 import Database from "better-sqlite3";
 import type { ListSessionsOptions, SessionSummary } from "../../adapters/AgentAdapter.js";
 import { OpenCodeSessionParser } from "./OpenCodeSessionParser.js";
+import { homeDir } from "../shared.js";
 
 const SESSION_REF_SEP = "::";
 
@@ -35,8 +36,7 @@ export class OpenCodeSessionLocator {
 
   static resolveDbPath(): string {
     const xdg = process.env.XDG_DATA_HOME;
-    const home = process.env.HOME || process.env.USERPROFILE || "";
-    const base = xdg || path.join(home, ".local", "share");
+    const base = xdg || path.join(homeDir(), ".local", "share");
     return path.join(base, "opencode", "opencode.db");
   }
 

package/src/{providers → harnesses}/opencode/OpenCodeSessionParser.ts

@@ -1,4 +1,5 @@
-import type { ConversationMessage } from "../../adapters/AgentAdapter.js";
+import type { ConversationMessage, ConversationOptions } from "../../adapters/AgentAdapter.js";
+import { sliceTail } from "../../utils/jsonlTail.js";
 import type Database from "better-sqlite3";
 
 export interface OpenCodeSessionStats {
@@ -29,7 +30,7 @@ export class OpenCodeSessionParser {
   getConversation(
     db: Database.Database,
     sessionId: string,
-    options?: { verbose?: boolean },
+    options?: ConversationOptions,
   ): ConversationMessage[] {
     const verbose = options?.verbose ?? false;
 
@@ -65,7 +66,7 @@ export class OpenCodeSessionParser {
         }
       }
 
-      return messages;
+      return sliceTail(messages, options?.tail);
     } catch {
       return [];
     }