@ai-devkit/agent-manager 0.38.0 → 0.40.0

package/src/adapters/AgentAdapter.ts

@@ -16,6 +16,7 @@ export const AGENT_TYPES = [
   "opencode",
   "copilot",
   "pi",
+  "devin",
 ] as const;
 
 /**

package/src/capacity/index.ts

@@ -3,6 +3,7 @@ import { access as fsAccess } from "node:fs/promises";
 import path from "node:path";
 import { codexUnavailableReport, probeCodexCapacity } from "./sources/codex.js";
 import { probeClaudeCapacity, type ClaudeCapacityOptions } from "./sources/claude.js";
+import { probeDevinCapacity, type DevinCapacityOptions } from "./sources/devin.js";
 import {
   probeOpenAiCapacity,
   probePiAnthropicCapacity,
@@ -15,6 +16,7 @@ import type { CapacityReport } from "./types.js";
 
 export type { CapacityReport, CapacityWindow } from "./types.js";
 export type { ClaudeCapacityOptions } from "./sources/claude.js";
+export type { DevinCapacityOptions } from "./sources/devin.js";
 export type { PiAnthropicCapacityOptions as AnthropicCapacityOptions } from "./sources/pi.js";
 export type {
   PiOpenAiCapacityOptions as OpenAiCapacityOptions,
@@ -103,6 +105,16 @@ export async function getClaudeCapacityReport(
   });
 }
 
+export async function getDevinCapacityReport(
+  options: DevinCapacityOptions = {},
+): Promise<CapacityReport> {
+  const { now, ...probeOptions } = options;
+  return probeDevinCapacity({
+    ...probeOptions,
+    checkedAt: (now?.() ?? new Date()).toISOString(),
+  });
+}
+
 export async function getAnthropicCapacityReport(
   options: PiAnthropicCapacityOptions = {},
 ): Promise<CapacityReport> {

package/src/capacity/providers/devin.ts

@@ -0,0 +1,121 @@
+import type { Availability, CapacityWindow, ProviderCapacitySnapshot } from "../types.js";
+import type { DevinCredential } from "../../harnesses/devin/credentials.js";
+
+const DEVIN_WEBAPP_HOST = "https://app.devin.ai";
+const DAY_MINUTES = 24 * 60;
+const WEEK_MINUTES = 7 * 24 * 60;
+
+type UnknownRecord = Record<string, unknown>;
+
+export type DevinRequestOptions = {
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+};
+
+export class DevinHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "DevinHttpError";
+  }
+}
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function percent(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.max(0, Math.min(100, value));
+}
+
+function timestamp(value: unknown): string | null {
+  if (typeof value !== "string" || !value) return null;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : new Date(ms).toISOString();
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function availability(windows: CapacityWindow[]): Availability {
+  if (windows.length === 0) return "unknown";
+  return windows.some((window) => window.usedPercent !== null && window.usedPercent < 100)
+    ? "yes"
+    : "no";
+}
+
+export function parseDevinCapacity(raw: unknown): ProviderCapacitySnapshot {
+  const root = record(raw);
+  if (!root) throw new Error("Invalid Devin quota response");
+
+  if (root.is_quota_plan !== true || root.has_quota_allocation !== true) {
+    return {
+      authenticated: true,
+      available: "unknown",
+      windows: [],
+      creditsRemaining: null,
+    };
+  }
+
+  const windows: CapacityWindow[] = [];
+  if (root.hide_daily_quota !== true) {
+    windows.push({
+      id: "devin:daily",
+      label: "Daily",
+      durationMinutes: DAY_MINUTES,
+      usedPercent: percent(root.daily_percentage),
+      resetsAt: timestamp(root.daily_reset_at),
+    });
+  }
+  windows.push({
+    id: "devin:weekly",
+    label: "Weekly",
+    durationMinutes: WEEK_MINUTES,
+    usedPercent: percent(root.weekly_percentage),
+    resetsAt: timestamp(root.weekly_reset_at),
+  });
+
+  return {
+    authenticated: true,
+    available: availability(windows),
+    windows,
+    creditsRemaining: finiteNumber(root.overage_balance),
+  };
+}
+
+export async function fetchDevinCapacity(
+  credential: DevinCredential,
+  options: DevinRequestOptions = {},
+): Promise<ProviderCapacitySnapshot> {
+  const url = `${DEVIN_WEBAPP_HOST}/api/${encodeURIComponent(credential.orgId)}/billing/quota/usage`;
+  let response: Response;
+  try {
+    response = await (options.fetch ?? globalThis.fetch)(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${credential.key}` },
+      signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
+    });
+  } catch {
+    throw new Error("Devin quota request failed");
+  }
+  if (response.status !== 200) {
+    throw new DevinHttpError(
+      response.status,
+      `Devin quota request failed: HTTP ${response.status}`,
+    );
+  }
+  try {
+    return parseDevinCapacity(await response.json());
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error("Devin quota response is not valid JSON");
+    }
+    throw error;
+  }
+}

package/src/capacity/sources/devin.ts

@@ -0,0 +1,49 @@
+import { DevinHttpError, fetchDevinCapacity } from "../providers/devin.js";
+import type { CapacityReport } from "../types.js";
+import {
+  resolveDevinCredential,
+  type DevinCredentialOptions,
+} from "../../harnesses/devin/credentials.js";
+
+export type DevinCapacityOptions = DevinCredentialOptions & {
+  now?: () => Date;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+};
+
+export type DevinProbeOptions = DevinCapacityOptions & {
+  checkedAt: string;
+};
+
+function devinReport(
+  snapshot: Omit<CapacityReport, "harness" | "provider" | "generatedAt">,
+  checkedAt: string,
+): CapacityReport {
+  return {
+    harness: "devin",
+    provider: "devin",
+    generatedAt: checkedAt,
+    ...snapshot,
+  };
+}
+
+export async function probeDevinCapacity(options: DevinProbeOptions): Promise<CapacityReport> {
+  const credential = await resolveDevinCredential(options);
+  try {
+    const snapshot = await fetchDevinCapacity(credential, options);
+    return devinReport(snapshot, options.checkedAt);
+  } catch (error) {
+    if (error instanceof DevinHttpError && (error.status === 401 || error.status === 403)) {
+      return devinReport(
+        {
+          authenticated: false,
+          available: "unknown",
+          windows: [],
+          creditsRemaining: null,
+        },
+        options.checkedAt,
+      );
+    }
+    throw error;
+  }
+}

package/src/harnesses/devin/DevinAdapter.ts

@@ -0,0 +1,224 @@
+/**
+ * Devin Adapter
+ *
+ * Detects running Devin CLI agents by:
+ * 1. Filtering `devin` processes from a shared process snapshot, rejecting
+ *    utility subcommands (list, doctor, ssh, ...) and `devin acp` children
+ *    spawned by a Devin TUI
+ * 2. Matching processes to sessions via `session_locks/<slug>.lock` files,
+ *    which contain the PID of the session's `devin acp` backend (lock-first;
+ *    a TUI is matched through its backend child's ppid)
+ * 3. Falling back to `sessions.working_directory` matching in
+ *    ~/.local/share/devin/cli/sessions.db (WAL SQLite, opened read-only)
+ *
+ * sessionFilePath encodes "<dbPath>::<sessionSlug>" so getConversation() can
+ * address a session row without extending the AgentAdapter interface.
+ */
+
+import type {
+  AgentAdapter,
+  AgentInfo,
+  ProcessInfo,
+  ConversationMessage,
+  ConversationOptions,
+  SessionSummary,
+  ListSessionsOptions,
+  AgentDetectionContext,
+} from "../../adapters/AgentAdapter.js";
+import { DevinAgentMapper } from "./DevinAgentMapper.js";
+import { DevinSessionLocator, decodeDevinSessionRef } from "./DevinSessionLocator.js";
+import { DevinSessionParser } from "./DevinSessionParser.js";
+import { findHarnessProcesses, matchesExecutable } from "../shared.js";
+import { executablePath } from "../../utils/process.js";
+
+/**
+ * `devin` invocations that are utilities, not agent sessions. `acp` is
+ * deliberately absent: a standalone `devin acp` serves an external client
+ * and is itself an agent.
+ */
+const UTILITY_SUBCOMMANDS = new Set([
+  "auth",
+  "cloud",
+  "desktop",
+  "doctor",
+  "forward",
+  "help",
+  "list",
+  "ls",
+  "mcp",
+  "migrate",
+  "models",
+  "plugins",
+  "rm",
+  "rules",
+  "sandbox",
+  "setup",
+  "skills",
+  "ssh",
+  "uninstall",
+  "update",
+  "version",
+]);
+
+/**
+ * Flags that always consume the next argv token as their value.
+ * (`devin --help`, main-command options.)
+ */
+const REQUIRED_VALUE_FLAGS = new Set([
+  "--prompt-file",
+  "--config",
+  "--permission-mode",
+  "--model",
+]);
+
+/**
+ * Flags whose value is optional: the next token is consumed only when it
+ * isn't itself a flag (commander `[<VALUE>]` semantics).
+ */
+const OPTIONAL_VALUE_FLAGS = new Set([
+  "-p",
+  "--print",
+  "-r",
+  "--resume",
+  "--export",
+  "--respect-workspace-trust",
+]);
+
+/**
+ * First positional argv token after argv[0] — the subcommand candidate.
+ * Flag values are skipped (so `devin -p "update deps"` isn't mistaken for
+ * the `update` subcommand); `--` ends the search.
+ */
+function firstPositionalToken(command: string): string | null {
+  const argv0 = executablePath(command);
+  const tokens = command
+    .trim()
+    .slice(argv0.length)
+    .trim()
+    .split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token) continue;
+    if (token === "--") return null;
+    if (!token.startsWith("-")) return token;
+    const flag = token.split("=", 1)[0];
+    if (flag === token) {
+      if (REQUIRED_VALUE_FLAGS.has(flag)) {
+        i++;
+      } else if (OPTIONAL_VALUE_FLAGS.has(flag) && !tokens[i + 1]?.startsWith("-")) {
+        i++;
+      }
+    }
+  }
+  return null;
+}
+
+export class DevinAdapter implements AgentAdapter {
+  readonly type = "devin" as const;
+  readonly processNames = ["devin"] as const;
+
+  private readonly parser: DevinSessionParser;
+  private readonly locator: DevinSessionLocator;
+  private readonly mapper: DevinAgentMapper;
+  private readonly cleanup = (): void => this.close();
+
+  constructor(dbPath?: string, locksDir?: string) {
+    this.parser = new DevinSessionParser();
+    // Locator defaults resolve dbPath itself and derive locksDir from it.
+    this.locator = new DevinSessionLocator(dbPath, locksDir, this.parser);
+    this.mapper = new DevinAgentMapper(this.locator.dbFilePath);
+    process.once("exit", this.cleanup);
+    process.once("SIGINT", this.cleanup);
+    process.once("SIGTERM", this.cleanup);
+  }
+
+  close(): void {
+    process.off("exit", this.cleanup);
+    process.off("SIGINT", this.cleanup);
+    process.off("SIGTERM", this.cleanup);
+    this.locator.close();
+  }
+
+  canHandle(processInfo: ProcessInfo): boolean {
+    if (!matchesExecutable(processInfo.command, "devin")) return false;
+    const subcommand = firstPositionalToken(processInfo.command);
+    return subcommand === null || !UTILITY_SUBCOMMANDS.has(subcommand.toLowerCase());
+  }
+
+  async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { processes } = await findHarnessProcesses(this, context);
+    if (processes.length === 0) return [];
+
+    const db = this.locator.openDb();
+    const processByPid = new Map(processes.map((proc) => [proc.pid, proc]));
+
+    // Locks map a session to its holder PID (the `devin acp` backend); a TUI
+    // is matched through its backend child's ppid. Only trust locks whose
+    // holder is a live devin process in this snapshot (stale files and PID
+    // reuse are filtered out).
+    const sessionByPid = new Map<number, string>();
+    for (const lock of this.locator.listActiveLocks()) {
+      const holder = processByPid.get(lock.pid);
+      if (!holder || !this.canHandle(holder)) continue;
+      sessionByPid.set(lock.pid, lock.sessionId);
+      if (holder.ppid !== undefined) sessionByPid.set(holder.ppid, lock.sessionId);
+    }
+
+    const agents: AgentInfo[] = [];
+
+    for (const proc of processes) {
+      if (this.isAcpBackendChild(proc, processByPid)) continue;
+
+      const slug = sessionByPid.get(proc.pid);
+      const session = !db
+        ? null
+        : slug
+          ? this.locator.findSessionById(db, slug)
+          : proc.cwd
+            ? this.locator.findSessionForDirectory(db, proc.cwd)
+            : null;
+
+      if (!session || !db) {
+        agents.push(this.mapper.mapProcessOnlyAgent(proc));
+        continue;
+      }
+
+      const stats = this.parser.getSessionStats(db, session.sessionId);
+      agents.push(this.mapper.mapSessionToAgent(session, stats, proc));
+    }
+
+    return agents;
+  }
+
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
+    const sessionId = decodeDevinSessionRef(sessionFilePath);
+    if (!sessionId) return [];
+
+    const db = this.locator.openDb();
+    if (!db) return [];
+
+    return this.parser.getConversation(db, sessionId, options);
+  }
+
+  async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+    return this.locator.listSessions(opts);
+  }
+
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    return this.locator.findSessionsById(sessionId);
+  }
+
+  /**
+   * A `devin acp` process spawned by another devin process is that session's
+   * backend, not a separate agent. Standalone `acp` processes (external ACP
+   * clients) keep their own agent entry.
+   */
+  private isAcpBackendChild(
+    proc: ProcessInfo,
+    processByPid: Map<number, ProcessInfo>,
+  ): boolean {
+    if (firstPositionalToken(proc.command)?.toLowerCase() !== "acp") return false;
+    if (proc.ppid === undefined) return false;
+    return processByPid.has(proc.ppid);
+  }
+}

package/src/harnesses/devin/DevinAgentMapper.ts

@@ -0,0 +1,43 @@
+import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { generateAgentName } from "../../utils/matching.js";
+import type { DevinSession } from "./DevinSessionLocator.js";
+import { encodeDevinSessionRef } from "./DevinSessionLocator.js";
+import type { DevinSessionStats } from "./DevinSessionParser.js";
+import { isIdle, processOnlyAgent } from "../shared.js";
+
+export class DevinAgentMapper {
+  constructor(private readonly dbPath: string) {}
+
+  mapSessionToAgent(
+    session: DevinSession,
+    stats: DevinSessionStats,
+    proc: ProcessInfo,
+  ): AgentInfo {
+    const lastActive =
+      stats.lastTimeUpdated > 0
+        ? new Date(stats.lastTimeUpdated)
+        : new Date(session.lastActivityAt || session.timeCreated);
+
+    return {
+      name: generateAgentName(session.directory || proc.cwd || "", proc.pid),
+      type: "devin",
+      status: this.determineStatus(stats, lastActive),
+      summary: stats.summary || session.title || "Devin session active",
+      pid: proc.pid,
+      projectPath: session.directory || proc.cwd || "",
+      sessionId: session.sessionId,
+      lastActive,
+      sessionFilePath: encodeDevinSessionRef(this.dbPath, session.sessionId),
+    };
+  }
+
+  mapProcessOnlyAgent(proc: ProcessInfo): AgentInfo {
+    return processOnlyAgent("devin", proc, { summary: "Devin process running" });
+  }
+
+  private determineStatus(stats: DevinSessionStats, lastActive: Date): AgentStatus {
+    if (isIdle(lastActive)) return AgentStatus.IDLE;
+    return stats.lastRole === "assistant" ? AgentStatus.WAITING : AgentStatus.RUNNING;
+  }
+}

package/src/harnesses/devin/DevinSessionLocator.ts

@@ -0,0 +1,230 @@
+import * as fs from "fs";
+import * as path from "path";
+import Database from "better-sqlite3";
+import type { ListSessionsOptions, SessionSummary } from "../../adapters/AgentAdapter.js";
+import { DevinSessionParser } from "./DevinSessionParser.js";
+import { homeDir } from "../shared.js";
+
+const SESSION_REF_SEP = "::";
+const LOCK_FILE_SUFFIX = ".lock";
+
+export function encodeDevinSessionRef(dbPath: string, sessionId: string): string {
+  return `${dbPath}${SESSION_REF_SEP}${sessionId}`;
+}
+
+/** Inverse of {@link encodeDevinSessionRef}; null when the ref has no separator. */
+export function decodeDevinSessionRef(ref: string): string | null {
+  const idx = ref.lastIndexOf(SESSION_REF_SEP);
+  return idx === -1 ? null : ref.slice(idx + SESSION_REF_SEP.length);
+}
+
+export interface DevinSession {
+  sessionId: string;
+  directory: string;
+  title: string | null;
+  /** Epoch milliseconds. */
+  timeCreated: number;
+  /** Epoch milliseconds. */
+  lastActivityAt: number;
+}
+
+/** A live `session_locks/<slug>.lock` entry: the session and its holder PID. */
+export interface DevinSessionLock {
+  sessionId: string;
+  pid: number;
+}
+
+interface DevinSessionRow {
+  id: string;
+  working_directory: string;
+  title: string | null;
+  created_at: number;
+  last_activity_at: number;
+}
+
+function toDevinSession(row: DevinSessionRow): DevinSession {
+  return {
+    sessionId: row.id,
+    directory: row.working_directory,
+    title: row.title,
+    timeCreated: row.created_at * 1000,
+    lastActivityAt: row.last_activity_at * 1000,
+  };
+}
+
+export class DevinSessionLocator {
+  private readonly dbPath: string;
+  private readonly locksDir: string;
+  private db: Database.Database | null = null;
+
+  constructor(
+    dbPath = DevinSessionLocator.resolveDbPath(),
+    locksDir = DevinSessionLocator.defaultLocksDir(dbPath),
+    private readonly parser: DevinSessionParser = new DevinSessionParser(),
+  ) {
+    this.dbPath = dbPath;
+    this.locksDir = locksDir;
+  }
+
+  static resolveDbPath(): string {
+    const xdg = process.env.XDG_DATA_HOME;
+    const base = xdg || path.join(homeDir(), ".local", "share");
+    return path.join(base, "devin", "cli", "sessions.db");
+  }
+
+  static defaultLocksDir(dbPath: string): string {
+    return path.join(path.dirname(dbPath), "session_locks");
+  }
+
+  openDb(): Database.Database | null {
+    if (this.db) return this.db;
+    if (!fs.existsSync(this.dbPath)) return null;
+
+    try {
+      this.db = new Database(this.dbPath, { readonly: true });
+      return this.db;
+    } catch {
+      return null;
+    }
+  }
+
+  close(): void {
+    if (this.db) {
+      try {
+        this.db.close();
+      } catch {
+        /* ignore */
+      }
+      this.db = null;
+    }
+  }
+
+  /**
+   * Read `session_locks/*.lock` entries. Each file name is a session slug and
+   * its body is the PID of the `devin acp` backend holding the session.
+   * Malformed files are skipped; callers validate liveness against the
+   * process snapshot.
+   */
+  listActiveLocks(): DevinSessionLock[] {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(this.locksDir);
+    } catch {
+      return [];
+    }
+
+    const locks: DevinSessionLock[] = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(LOCK_FILE_SUFFIX)) continue;
+      const sessionId = entry.slice(0, -LOCK_FILE_SUFFIX.length);
+      if (!sessionId) continue;
+
+      try {
+        const raw = fs.readFileSync(path.join(this.locksDir, entry), "utf-8").trim();
+        const pid = parseInt(raw, 10);
+        if (Number.isFinite(pid) && pid > 0) locks.push({ sessionId, pid });
+      } catch {
+        /* skip unreadable lock */
+      }
+    }
+    return locks;
+  }
+
+  findSessionById(db: Database.Database, sessionId: string): DevinSession | null {
+    try {
+      const row = db
+        .prepare<[string], DevinSessionRow>(`
+                SELECT id, working_directory, title, created_at, last_activity_at
+                FROM sessions
+                WHERE id = ? AND hidden = 0
+            `)
+        .get(sessionId);
+      return row ? toDevinSession(row) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  findSessionForDirectory(db: Database.Database, directory: string): DevinSession | null {
+    try {
+      const row = db
+        .prepare<[string], DevinSessionRow>(`
+                SELECT id, working_directory, title, created_at, last_activity_at
+                FROM sessions
+                WHERE working_directory = ? AND hidden = 0
+                ORDER BY last_activity_at DESC
+                LIMIT 1
+            `)
+        .get(directory);
+      return row ? toDevinSession(row) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  listSessions(opts?: ListSessionsOptions): SessionSummary[] {
+    const db = this.openDb();
+    if (!db) return [];
+
+    try {
+      const rows = db
+        .prepare<[], DevinSessionRow>(`
+                SELECT id, working_directory, title, created_at, last_activity_at
+                FROM sessions
+                WHERE hidden = 0
+                ORDER BY last_activity_at DESC
+            `)
+        .all();
+
+      const summaries: SessionSummary[] = [];
+      for (const row of rows) {
+        if (opts?.cwd !== undefined && row.working_directory !== opts.cwd) continue;
+        summaries.push(this.toSessionSummary(db, row));
+      }
+      return summaries;
+    } catch {
+      this.close();
+      return [];
+    }
+  }
+
+  findSessionsById(sessionId: string): SessionSummary[] {
+    const db = this.openDb();
+    if (!db) return [];
+
+    try {
+      const row = db
+        .prepare<[string], DevinSessionRow>(`
+                SELECT id, working_directory, title, created_at, last_activity_at
+                FROM sessions
+                WHERE id = ? AND hidden = 0
+            `)
+        .get(sessionId);
+      return row ? [this.toSessionSummary(db, row)] : [];
+    } catch {
+      this.close();
+      return [];
+    }
+  }
+
+  private toSessionSummary(db: Database.Database, row: DevinSessionRow): SessionSummary {
+    const session = toDevinSession(row);
+    return {
+      type: "devin",
+      sessionId: session.sessionId,
+      cwd: session.directory,
+      firstUserMessage: this.parser.getFirstUserMessage(db, session.sessionId),
+      lastActive: new Date(session.lastActivityAt),
+      startedAt: new Date(session.timeCreated),
+      sessionFilePath: encodeDevinSessionRef(this.dbPath, session.sessionId),
+    };
+  }
+
+  get dbFilePath(): string {
+    return this.dbPath;
+  }
+
+  get sessionLocksDir(): string {
+    return this.locksDir;
+  }
+}