@ai-devkit/agent-manager 0.36.0 → 0.37.0

package/src/index.ts

@@ -32,22 +32,24 @@ export type {
   ReadinessStatus,
 } from "./readiness/AgentReadiness.js";
 
-export { ClaudeCodeAdapter } from "./providers/claude/ClaudeCodeAdapter.js";
-export { CodexAdapter } from "./providers/codex/CodexAdapter.js";
-export { CopilotAdapter } from "./providers/copilot/CopilotAdapter.js";
-export { GeminiCliAdapter } from "./providers/gemini/GeminiCliAdapter.js";
-export { GrokCliAdapter } from "./providers/grok/GrokCliAdapter.js";
-export { AntigravityCliAdapter } from "./adapters/AntigravityCliAdapter.js";
-export { KiroAdapter } from "./adapters/KiroAdapter.js";
-export { OpenCodeAdapter } from "./providers/opencode/OpenCodeAdapter.js";
-export { PiAdapter } from "./providers/pi/PiAdapter.js";
-export { AgentStatus } from "./adapters/AgentAdapter.js";
+export { ClaudeCodeAdapter } from "./harnesses/claude/ClaudeCodeAdapter.js";
+export { CodexAdapter } from "./harnesses/codex/CodexAdapter.js";
+export { CopilotAdapter } from "./harnesses/copilot/CopilotAdapter.js";
+export { GeminiCliAdapter } from "./harnesses/gemini/GeminiCliAdapter.js";
+export { GrokCliAdapter } from "./harnesses/grok/GrokCliAdapter.js";
+export { AntigravityCliAdapter } from "./harnesses/antigravity/AntigravityCliAdapter.js";
+export { KiroAdapter } from "./harnesses/kiro/KiroAdapter.js";
+export { OpenCodeAdapter } from "./harnesses/opencode/OpenCodeAdapter.js";
+export { PiAdapter } from "./harnesses/pi/PiAdapter.js";
+export { createBuiltinAdapters } from "./harnesses/index.js";
+export { AGENT_TYPES, AgentStatus } from "./adapters/AgentAdapter.js";
 export type {
   AgentAdapter,
   AgentType,
   AgentInfo,
   ProcessInfo,
   ConversationMessage,
+  ConversationOptions,
   SessionSummary,
   ListSessionsOptions,
   AgentDetectionContext,
@@ -147,34 +149,34 @@ export type {
   ProcessInspector,
   DurableRunCompletion,
 } from "./durable/DurableAgentRepository.js";
-export { ClaudePrintAgentService } from "./providers/claude/durable/ClaudePrintAgentService.js";
+export { ClaudePrintAgentService } from "./harnesses/claude/durable/ClaudePrintAgentService.js";
 export type {
   ClaudePrintAgentServiceOptions,
   ClaudePrintSendResult,
-} from "./providers/claude/durable/ClaudePrintAgentService.js";
-export { CodexCliProbe } from "./providers/codex/durable/CodexCliProbe.js";
-export type { CodexCliProbeOptions } from "./providers/codex/durable/CodexCliProbe.js";
-export { CodexPrintRunner } from "./providers/codex/durable/CodexPrintRunner.js";
+} from "./harnesses/claude/durable/ClaudePrintAgentService.js";
+export { CodexCliProbe } from "./harnesses/codex/durable/CodexCliProbe.js";
+export type { CodexCliProbeOptions } from "./harnesses/codex/durable/CodexCliProbe.js";
+export { CodexPrintRunner } from "./harnesses/codex/durable/CodexPrintRunner.js";
 export type {
   CodexPrintRunnerOptions,
   CodexPrintRunRequest,
   CodexPrintRunResult,
-} from "./providers/codex/durable/CodexPrintRunner.js";
-export { CodexPrintAgentService } from "./providers/codex/durable/CodexPrintAgentService.js";
+} from "./harnesses/codex/durable/CodexPrintRunner.js";
+export { CodexPrintAgentService } from "./harnesses/codex/durable/CodexPrintAgentService.js";
 export type {
   CodexPrintAgentServiceOptions,
   CodexPrintSendResult,
-} from "./providers/codex/durable/CodexPrintAgentService.js";
-export { PiCliProbe } from "./providers/pi/durable/PiCliProbe.js";
-export type { PiCliProbeOptions } from "./providers/pi/durable/PiCliProbe.js";
-export { PiPrintRunner } from "./providers/pi/durable/PiPrintRunner.js";
+} from "./harnesses/codex/durable/CodexPrintAgentService.js";
+export { PiCliProbe } from "./harnesses/pi/durable/PiCliProbe.js";
+export type { PiCliProbeOptions } from "./harnesses/pi/durable/PiCliProbe.js";
+export { PiPrintRunner } from "./harnesses/pi/durable/PiPrintRunner.js";
 export type {
   PiPrintRunnerOptions,
   PiPrintRunRequest,
   PiPrintRunResult,
-} from "./providers/pi/durable/PiPrintRunner.js";
-export { PiPrintAgentService } from "./providers/pi/durable/PiPrintAgentService.js";
+} from "./harnesses/pi/durable/PiPrintRunner.js";
+export { PiPrintAgentService } from "./harnesses/pi/durable/PiPrintAgentService.js";
 export type {
   PiPrintAgentServiceOptions,
   PiPrintSendResult,
-} from "./providers/pi/durable/PiPrintAgentService.js";
+} from "./harnesses/pi/durable/PiPrintAgentService.js";

package/src/utils/IncrementalJsonlSummary.ts

@@ -0,0 +1,306 @@
+/**
+ * Incremental JSONL Summary
+ *
+ * Keeps a small per-file summary of append-only JSONL transcripts so repeated
+ * refreshes only parse bytes that were appended since the previous read.
+ *
+ * Usage:
+ * ```ts
+ * const summaries = new IncrementalJsonlSummary<MyState>({
+ *   initial: () => ({ lastType: undefined }),
+ *   reduce: (state, entry) => ({ ...state, lastType: (entry as any)?.type }),
+ * });
+ *
+ * const result = summaries.read(filePath); // { state, size, mtime, skippedBytes } | null
+ * summaries.prune(); // once per refresh: evict paths not read since the last prune
+ * ```
+ *
+ * Read rules, keyed by file path:
+ * - dev, ino, size and mtimeMs unchanged → cached state, 0 bytes read.
+ * - same dev/ino and size grew → read only the bytes after the last complete line.
+ * - anything else (first read, shrink, rotation, in-place rewrite) → rebuild.
+ *
+ * A rebuild of a file larger than `headBytes + tailBytes` (default 1 MiB +
+ * 4 MiB) is a bounded cold start rather than a full parse: it folds the
+ * complete lines in `[0, headBytes)`, calls `reducer.skip(state)`, then folds
+ * the lines that start inside `[size - tailBytes, size)`, including a line
+ * that starts exactly at `size - tailBytes` (one extra byte before the window
+ * is read to tell). Lines straddling a window edge are dropped. A field whose
+ * entries all sit in the skipped middle keeps whatever `skip` leaves; there is
+ * never a hidden full scan. The result's `skippedBytes` reports the unread
+ * middle, and the cache is seeded at end of file so later appends stay
+ * incremental.
+ *
+ * An unterminated last line is never folded into the committed state. If it
+ * already parses as JSON it is applied to the returned state only, and it is
+ * re-read (from its start offset) once more bytes arrive.
+ */
+
+import * as fs from "fs";
+
+/**
+ * Pure fold over the entries of a JSONL file.
+ *
+ * `reduce` receives each non-blank line in file order: the parsed JSON value,
+ * or `undefined` when the line is not valid JSON. It must return a new state
+ * rather than mutate `state`, and the state should stay O(1) in file size
+ * (no entry arrays or raw file contents).
+ *
+ * `skip` is called once when a bounded cold start skips the middle of a file,
+ * between the head lines and the tail lines. It returns the state the tail
+ * lines fold onto: keep what the head established (e.g. the first entry) and
+ * reset fields that track the latest entry, so those come only from lines
+ * actually read. Without `skip`, tail lines fold straight onto the head state.
+ */
+export interface JsonlSummaryReducer<S> {
+  initial(): S;
+  reduce(state: S, entry: unknown): S;
+  skip?(state: S): S;
+}
+
+export interface JsonlSummaryResult<S> {
+  state: S;
+  /** File size in bytes when the state was computed. */
+  size: number;
+  /** File mtime (`fs.Stats.mtime`) when the state was computed. */
+  mtime: Date;
+  /** Bytes the bounded cold start did not read; 0 when the whole file was parsed. */
+  skippedBytes: number;
+}
+
+export interface JsonlSummaryBounds {
+  /** Bytes scanned from the start of the file on a cold start. */
+  headBytes: number;
+  /** Bytes scanned at the end of the file on a cold start. */
+  tailBytes: number;
+}
+
+export interface IncrementalJsonlSummaryOptions {
+  /** Bytes read per `fs.readSync` call. */
+  chunkSize?: number;
+  /** Cold-start scan bounds; `false` parses rebuilt files from byte 0. */
+  bounds?: JsonlSummaryBounds | false;
+}
+
+interface CacheEntry<S> {
+  dev: number;
+  ino: number;
+  size: number;
+  mtimeMs: number;
+  mtime: Date;
+  /** Byte offset just past the last newline folded into `committed`. */
+  offset: number;
+  /** `offset` is mid-line: drop bytes up to and including the next newline. */
+  discarding: boolean;
+  /** State after every newline-terminated line. */
+  committed: S;
+  /** `committed` plus the unterminated last line, when it parses as JSON. */
+  state: S;
+  /** Bytes the cold start did not read. */
+  skippedBytes: number;
+  /** Prune generation in which this entry was last read. */
+  seen: number;
+}
+
+export const DEFAULT_HEAD_BYTES = 1024 * 1024;
+export const DEFAULT_TAIL_BYTES = 4 * 1024 * 1024;
+const DEFAULT_CHUNK_SIZE = 1024 * 1024;
+const NEWLINE = 0x0a;
+
+/** Fold a whole JSONL string with a reducer (one-shot, uncached). */
+export function reduceJsonlContent<S>(reducer: JsonlSummaryReducer<S>, content: string): S {
+  let state = reducer.initial();
+  for (const line of content.split("\n")) {
+    state = reduceLine(reducer, state, line);
+  }
+  return state;
+}
+
+export class IncrementalJsonlSummary<S> {
+  private readonly entries = new Map<string, CacheEntry<S>>();
+  private readonly chunkSize: number;
+  private readonly bounds: JsonlSummaryBounds | false;
+  private generation = 0;
+
+  constructor(
+    private readonly reducer: JsonlSummaryReducer<S>,
+    options: IncrementalJsonlSummaryOptions = {},
+  ) {
+    this.chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    this.bounds = options.bounds ?? {
+      headBytes: DEFAULT_HEAD_BYTES,
+      tailBytes: DEFAULT_TAIL_BYTES,
+    };
+  }
+
+  /** Number of cached files. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Return the summary of `filePath`, reading only what changed. Null if unreadable. */
+  read(filePath: string): JsonlSummaryResult<S> | null {
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      this.entries.delete(filePath);
+      return null;
+    }
+
+    const cached = this.entries.get(filePath);
+    const sameFile = cached !== undefined && cached.dev === stat.dev && cached.ino === stat.ino;
+
+    if (sameFile && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) {
+      cached.seen = this.generation;
+      return toResult(cached);
+    }
+
+    const appended = sameFile && stat.size > cached.size;
+    const entry: CacheEntry<S> = appended
+      ? { ...cached }
+      : {
+          dev: stat.dev,
+          ino: stat.ino,
+          size: 0,
+          mtimeMs: 0,
+          mtime: stat.mtime,
+          offset: 0,
+          discarding: false,
+          committed: this.reducer.initial(),
+          state: this.reducer.initial(),
+          skippedBytes: 0,
+          seen: this.generation,
+        };
+
+    try {
+      const fd = fs.openSync(filePath, "r");
+      try {
+        const bounds = this.bounds;
+        if (!appended && bounds && stat.size > bounds.headBytes + bounds.tailBytes) {
+          this.readBounded(fd, entry, stat.size, bounds);
+        } else {
+          this.readRange(fd, entry, stat.size);
+        }
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+      this.entries.delete(filePath);
+      return null;
+    }
+
+    entry.mtimeMs = stat.mtimeMs;
+    entry.mtime = stat.mtime;
+    entry.seen = this.generation;
+    this.entries.set(filePath, entry);
+    return toResult(entry);
+  }
+
+  /** Evict entries not read since the previous `prune()` call. Call once per refresh. */
+  prune(): void {
+    for (const [filePath, entry] of this.entries) {
+      if (entry.seen !== this.generation) {
+        this.entries.delete(filePath);
+      }
+    }
+    this.generation++;
+  }
+
+  /** Cold start: fold the head lines, `skip`, then the lines starting in the tail window. */
+  private readBounded(
+    fd: number,
+    entry: CacheEntry<S>,
+    size: number,
+    { headBytes, tailBytes }: JsonlSummaryBounds,
+  ): void {
+    this.readRange(fd, entry, headBytes);
+
+    const tailStart = size - tailBytes;
+    const head = entry.committed;
+    entry.committed = this.reducer.skip ? this.reducer.skip(head) : head;
+    // Lines are only folded from their first byte, and tailStart may fall
+    // mid-line. Discard from one byte earlier (tailStart > headBytes >= 0): if
+    // that byte is the newline ending the previous line, discarding stops there
+    // and the line starting at tailStart is folded; otherwise the partial line
+    // is dropped up to its newline.
+    entry.offset = tailStart - 1;
+    entry.discarding = true;
+    entry.skippedBytes = tailStart - headBytes;
+    this.readRange(fd, entry, size);
+  }
+
+  /** Fold complete lines in `[entry.offset, end)` into `entry`. */
+  private readRange(fd: number, entry: CacheEntry<S>, end: number): void {
+    const chunk = Buffer.allocUnsafe(Math.min(this.chunkSize, Math.max(end - entry.offset, 1)));
+    let position = entry.offset;
+    let carry: Buffer | undefined;
+    let committed = entry.committed;
+    let discarding = entry.discarding;
+
+    while (position < end) {
+      const bytesRead = fs.readSync(fd, chunk, 0, Math.min(chunk.length, end - position), position);
+      if (bytesRead === 0) break;
+      position += bytesRead;
+
+      let lineStart = 0;
+      let newline = chunk.indexOf(NEWLINE, 0);
+      while (newline !== -1 && newline < bytesRead) {
+        if (discarding) {
+          discarding = false;
+        } else {
+          const lineBytes = carry
+            ? Buffer.concat([carry, chunk.subarray(lineStart, newline)])
+            : chunk.subarray(lineStart, newline);
+          committed = reduceLine(this.reducer, committed, lineBytes.toString("utf8"));
+        }
+        carry = undefined;
+        lineStart = newline + 1;
+        newline = chunk.indexOf(NEWLINE, lineStart);
+      }
+
+      if (lineStart < bytesRead && !discarding) {
+        const rest = Buffer.from(chunk.subarray(lineStart, bytesRead));
+        carry = carry ? Buffer.concat([carry, rest]) : rest;
+      }
+    }
+
+    entry.committed = committed;
+    entry.discarding = discarding;
+    entry.offset = position - (carry?.length ?? 0);
+    entry.size = position;
+    entry.state = carry
+      ? reduceTentative(this.reducer, committed, carry.toString("utf8"))
+      : committed;
+  }
+}
+
+function toResult<S>(entry: CacheEntry<S>): JsonlSummaryResult<S> {
+  return {
+    state: entry.state,
+    size: entry.size,
+    mtime: entry.mtime,
+    skippedBytes: entry.skippedBytes,
+  };
+}
+
+function reduceLine<S>(reducer: JsonlSummaryReducer<S>, state: S, line: string): S {
+  if (!/\S/.test(line)) return state;
+  let entry: unknown;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    entry = undefined;
+  }
+  return reducer.reduce(state, entry);
+}
+
+/** Apply an unterminated line only if it is already valid JSON (i.e. fully written). */
+function reduceTentative<S>(reducer: JsonlSummaryReducer<S>, state: S, line: string): S {
+  if (!/\S/.test(line)) return state;
+  try {
+    return reducer.reduce(state, JSON.parse(line));
+  } catch {
+    return state;
+  }
+}

package/src/utils/agents.ts

@@ -1,18 +1,9 @@
 import path from "path";
-import type { AgentType } from "../adapters/AgentAdapter.js";
+import type { AGENT_TYPES } from "../adapters/AgentAdapter.js";
+import { executablePath } from "./process.js";
 
-export type StartableAgentType = Extract<
-  AgentType,
-  | "claude"
-  | "codex"
-  | "copilot"
-  | "gemini_cli"
-  | "grok_cli"
-  | "antigravity_cli"
-  | "opencode"
-  | "pi"
-  | "kiro"
->;
+/** Every built-in harness can be started, so each needs an {@link AGENTS} entry. */
+export type StartableAgentType = (typeof AGENT_TYPES)[number];
 
 export interface AgentConfig {
   /** Shell command to launch the agent (sent to tmux via `send-keys`). */
@@ -38,38 +29,79 @@ export const AGENTS: Record<StartableAgentType, AgentConfig> = {
   kiro: { command: "kiro-cli", matches: matchAnyBasename(["kiro-cli", "kiro"]) },
 };
 
+/**
+ * Matchers read a `ps` command line, where argv is joined with spaces. argv[0]
+ * is resolved with {@link executablePath} so executables installed under
+ * directories containing spaces are recognised, while arguments are never
+ * folded into the executable path unless that combined path is a real file.
+ *
+ * The filesystem is consulted only when a token after the first could be part
+ * of a matching argv[0]; commands whose first token already decides the match,
+ * or that contain no candidate token at all, are handled with string checks.
+ */
+const ABSOLUTE_PATH = /^(?:\/|[a-zA-Z]:[\\/])/;
+const PATH_SEPARATOR = /[\\/]/;
+
+function basenameOf(token: string): string {
+  return path.basename(token).toLowerCase();
+}
+
+function tokensOf(psCommand: string): string[] {
+  return psCommand.trim().split(/\s+/).filter(Boolean);
+}
+
+/** Split a command line into its resolved argv[0] and the remaining argument tokens. */
+function splitArgv0(psCommand: string): { argv0: string; args: string[] } {
+  const command = psCommand.trim();
+  const argv0 = executablePath(command);
+  return { argv0, args: tokensOf(command.slice(argv0.length)) };
+}
+
+/** Whether argv[0] may span several tokens, i.e. a later path-like token satisfies `test`. */
+function mayContinueArgv0(tokens: string[], test: (token: string) => boolean): boolean {
+  return (
+    ABSOLUTE_PATH.test(tokens[0]) &&
+    tokens.slice(1).some((token) => PATH_SEPARATOR.test(token) && test(token))
+  );
+}
+
 function matchArgv0(name: string): (psCommand: string) => boolean {
   const lower = name.toLowerCase();
+  const test = (token: string) => basenameOf(token) === lower;
   return (psCommand) => {
-    const token = psCommand.trim().split(/\s+/)[0];
-    return token ? path.basename(token).toLowerCase() === lower : false;
+    const tokens = tokensOf(psCommand);
+    if (tokens.length === 0) return false;
+    if (test(tokens[0])) return true;
+    return mayContinueArgv0(tokens, test) && test(executablePath(psCommand));
   };
 }
 
 function matchArgv0Name(name: string): (psCommand: string) => boolean {
   const lower = name.toLowerCase();
+  const test = (token: string) => token.toLowerCase().includes(lower);
   return (psCommand) => {
-    const token = psCommand.trim().split(/\s+/)[0];
-    return token ? token.toLowerCase().includes(lower) : false;
+    const tokens = tokensOf(psCommand);
+    if (tokens.length === 0) return false;
+    if (test(tokens[0])) return true;
+    return mayContinueArgv0(tokens, test) && test(executablePath(psCommand));
   };
 }
 
 function matchAnyToken(name: string): (psCommand: string) => boolean {
-  const lower = name.toLowerCase();
-  return (psCommand) => {
-    for (const token of psCommand.trim().split(/\s+/)) {
-      if (path.basename(token).toLowerCase() === lower) return true;
-    }
-    return false;
-  };
+  return matchAnyBasename([name]);
 }
 
 function matchAnyBasename(names: string[]): (psCommand: string) => boolean {
   const lowers = new Set(names.map((name) => name.toLowerCase()));
+  const test = (token: string) => lowers.has(basenameOf(token));
   return (psCommand) => {
-    for (const token of psCommand.trim().split(/\s+/)) {
-      if (lowers.has(path.basename(token).toLowerCase())) return true;
-    }
-    return false;
+    const tokens = tokensOf(psCommand);
+    if (tokens.length === 0) return false;
+    if (test(tokens[0])) return true;
+    if (!tokens.slice(1).some(test)) return false;
+    if (!ABSOLUTE_PATH.test(tokens[0])) return true;
+
+    const { argv0, args } = splitArgv0(psCommand);
+    return test(argv0) || args.some(test);
   };
 }

package/src/utils/index.ts

@@ -4,7 +4,9 @@ export {
   batchGetProcessStartTimes,
   enrichProcesses,
   captureProcessSnapshot,
+  createProcessSnapshotCapture,
 } from "./process.js";
+export type { ProcessExec, ProcessSnapshotCapture, ProcessSnapshotOptions } from "./process.js";
 export { getProcessTty } from "./process.js";
 export { batchGetSessionFileBirthtimes } from "./session.js";
 export type { SessionFile } from "./session.js";