@ai-devkit/agent-manager 0.37.0 → 0.39.0

package/src/harnesses/claude/credentials.ts

@@ -0,0 +1,122 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+export type ClaudeCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+  now?: () => Date;
+  cwd?: string;
+  platform?: NodeJS.Platform;
+  keychainRead?: (service: string) => Promise<string | null>;
+};
+
+type Credential = { token: string | null; expired: boolean };
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function credentialsPath(options: ClaudeCredentialOptions): string {
+  const env = options.env ?? process.env;
+  const configured = nonEmptyText(env.CLAUDE_CONFIG_DIR);
+  if (configured) {
+    const profileRoot = isAbsolute(configured)
+      ? configured
+      : resolve(options.cwd ?? process.cwd(), configured);
+    return join(profileRoot, ".credentials.json");
+  }
+  return join(env.HOME || homedir(), ".claude", ".credentials.json");
+}
+
+function credentialFromRoot(root: Record<string, unknown> | null, now: Date): Credential {
+  const oauth = record(root?.claudeAiOauth);
+  const token = nonEmptyText(oauth?.accessToken);
+  if (!token) return { token: null, expired: false };
+  const expired =
+    typeof oauth?.expiresAt === "number" &&
+    Number.isFinite(oauth.expiresAt) &&
+    oauth.expiresAt <= now.getTime();
+  return { token: expired ? null : token, expired };
+}
+
+function credentialFromPayload(payload: string | null, now: Date): Credential {
+  if (!payload) return { token: null, expired: false };
+  try {
+    return credentialFromRoot(record(JSON.parse(payload)), now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+async function readProfileCredential(
+  options: ClaudeCredentialOptions,
+  now: Date,
+): Promise<Credential> {
+  try {
+    const payload = await (options.readFile ?? readFile)(credentialsPath(options), "utf8");
+    return credentialFromPayload(payload, now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+async function readClaudeKeychain(service: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "/usr/bin/security",
+      ["find-generic-password", "-s", service, "-w"],
+      { encoding: "utf8", timeout: 1500, maxBuffer: 1024 * 1024 },
+    );
+    return nonEmptyText(stdout);
+  } catch {
+    return null;
+  }
+}
+
+async function readKeychainCredential(
+  options: ClaudeCredentialOptions,
+  now: Date,
+): Promise<Credential> {
+  const env = options.env ?? process.env;
+  const usesDefaultProfile = !nonEmptyText(env.CLAUDE_CONFIG_DIR);
+  if (!usesDefaultProfile || (options.platform ?? process.platform) !== "darwin") {
+    return { token: null, expired: false };
+  }
+  try {
+    const payload = await (options.keychainRead ?? readClaudeKeychain)(CLAUDE_KEYCHAIN_SERVICE);
+    return credentialFromPayload(payload, now);
+  } catch {
+    return { token: null, expired: false };
+  }
+}
+
+export async function resolveClaudeAnthropicToken(
+  options: ClaudeCredentialOptions = {},
+): Promise<string> {
+  const env = options.env ?? process.env;
+  const environmentToken = nonEmptyText(env.CLAUDE_CODE_OAUTH_TOKEN);
+  if (environmentToken) return environmentToken;
+
+  const now = options.now?.() ?? new Date();
+  const profileCredential = await readProfileCredential(options, now);
+  if (profileCredential.token) return profileCredential.token;
+
+  const keychainCredential = await readKeychainCredential(options, now);
+  if (keychainCredential.token) return keychainCredential.token;
+  if (profileCredential.expired || keychainCredential.expired) {
+    throw new Error("Claude OAuth credentials expired");
+  }
+  throw new Error("Claude OAuth credentials not found or malformed");
+}

package/src/harnesses/claude/readiness.ts

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import {
+  record,
+  registrationCheck,
+  scriptCheck,
+  worstReadinessStatus,
+} from "../readiness/checks.js";
+import type {
+  AuthReadinessCheck,
+  HarnessReadinessProfile,
+  IntegrationReadinessCheck,
+  ReadinessRuntime,
+} from "../readiness/types.js";
+
+async function authCheck(runtime: ReadinessRuntime): Promise<AuthReadinessCheck> {
+  try {
+    const result = await runtime.runCommand("claude", ["auth", "status", "--json"]);
+    const parsed = record(JSON.parse(result.stdout));
+    const authenticated = parsed?.loggedIn === true || parsed?.authenticated === true;
+    const unauthenticated = parsed?.loggedIn === false || parsed?.authenticated === false;
+    return {
+      state: authenticated ? "authenticated" : unauthenticated ? "unauthenticated" : "unknown",
+      source: "claude auth status --json",
+      provider: null,
+      availableProviders: [],
+      status: authenticated ? "pass" : unauthenticated ? "fail" : "warn",
+      errors: authenticated
+        ? []
+        : [unauthenticated ? "Claude is not authenticated" : "Claude authentication is unknown"],
+    };
+  } catch {
+    return {
+      state: "unknown",
+      source: "claude auth status --json",
+      provider: null,
+      availableProviders: [],
+      status: "warn",
+      errors: ["Claude authentication probe failed"],
+    };
+  }
+}
+
+async function integrationCheck(runtime: ReadinessRuntime): Promise<IntegrationReadinessCheck> {
+  const script = await scriptCheck(
+    join(runtime.homeDir, ".claude", "hooks", "claude-prompt-hook.js"),
+    join(runtime.assetRoot ?? "", "claude", "claude-prompt-hook.js"),
+    runtime,
+  );
+  const registration = await registrationCheck(
+    join(runtime.homeDir, ".claude", "settings.json"),
+    "PreToolUse",
+    "node ~/.claude/hooks/claude-prompt-hook.js",
+    runtime,
+  );
+  const installed = script.status === "pass" && registration.status === "pass";
+  return {
+    label: "ai-devkit hook",
+    installed,
+    status: worstReadinessStatus([script.status, registration.status]),
+    errors: [...script.errors, ...registration.errors],
+    details: { promptScript: script, registration },
+  };
+}
+
+export const claudeReadiness: HarnessReadinessProfile = {
+  configDir: ".claude",
+  auth: authCheck,
+  integration: integrationCheck,
+};

package/src/harnesses/codex/credentials.ts

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+type UnknownRecord = Record<string, unknown>;
+
+export type CodexCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+  now?: () => Date;
+};
+
+export type CodexCredentials = {
+  personalAccessToken: string | null;
+  oauth: { access: string; accountId: string } | null;
+};
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function resolveCodexAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  const root = env.CODEX_HOME || join(env.HOME || "", ".codex");
+  return join(root, "auth.json");
+}
+
+function jwtExpiry(token: string): number | null {
+  const part = token.split(".")[1];
+  if (!part) return null;
+  try {
+    return finiteNumber(record(JSON.parse(Buffer.from(part, "base64url").toString("utf8")))?.exp);
+  } catch {
+    return null;
+  }
+}
+
+function staleOAuth(tokens: UnknownRecord, token: string, now: Date): boolean {
+  const metadata = tokens.expires_at ?? tokens.expiresAt ?? tokens.expiry;
+  let expiry: number | null = finiteNumber(metadata);
+  if (typeof metadata === "string") {
+    const parsed = Date.parse(metadata);
+    expiry = Number.isNaN(parsed) ? null : parsed / 1000;
+  }
+  expiry ??= jwtExpiry(token);
+  return expiry !== null && expiry <= now.getTime() / 1000;
+}
+
+export async function resolveCodexCredentials(
+  options: CodexCredentialOptions = {},
+): Promise<CodexCredentials | null> {
+  let auth: UnknownRecord;
+  try {
+    const contents = await (options.readFile ?? readFile)(
+      resolveCodexAuthPath(options.env),
+      "utf8",
+    );
+    auth = record(JSON.parse(contents)) ?? {};
+  } catch {
+    return null;
+  }
+
+  const personalAccessToken = nonEmptyText(auth.personal_access_token);
+  const tokens = record(auth.tokens);
+  const access = nonEmptyText(tokens?.access_token);
+  const accountId = nonEmptyText(tokens?.account_id);
+  const now = options.now?.() ?? new Date();
+  const oauth =
+    tokens && access && accountId && !staleOAuth(tokens, access, now)
+      ? { access, accountId }
+      : null;
+  return { personalAccessToken, oauth };
+}

package/src/harnesses/codex/readiness.ts

@@ -0,0 +1,72 @@
+import { join } from "node:path";
+import {
+  displayHome,
+  mappingCheck,
+  registrationCheck,
+  scriptCheck,
+  worstReadinessStatus,
+} from "../readiness/checks.js";
+import type {
+  AuthReadinessCheck,
+  HarnessReadinessProfile,
+  IntegrationReadinessCheck,
+  ReadinessRuntime,
+} from "../readiness/types.js";
+
+async function authCheck(runtime: ReadinessRuntime): Promise<AuthReadinessCheck> {
+  try {
+    const value = await runtime.codexAuth();
+    return {
+      state: value === true ? "authenticated" : value === false ? "unauthenticated" : "unknown",
+      source: displayHome(join(runtime.homeDir, ".codex", "auth.json"), runtime.homeDir),
+      provider: null,
+      availableProviders: [],
+      status: value === true ? "pass" : value === false ? "fail" : "warn",
+      errors:
+        value === true
+          ? []
+          : [value === false ? "Codex is not authenticated" : "Codex authentication is unknown"],
+    };
+  } catch {
+    return {
+      state: "unknown",
+      source: "~/.codex/auth.json",
+      provider: null,
+      availableProviders: [],
+      status: "warn",
+      errors: ["Codex authentication probe failed"],
+    };
+  }
+}
+
+async function integrationCheck(runtime: ReadinessRuntime): Promise<IntegrationReadinessCheck> {
+  const script = await scriptCheck(
+    join(runtime.homeDir, ".codex", "hooks", "codex-session-mapping.cjs"),
+    join(runtime.assetRoot ?? "", "codex", "codex-session-mapping.cjs"),
+    runtime,
+  );
+  const registration = await registrationCheck(
+    join(runtime.homeDir, ".codex", "hooks.json"),
+    "SessionStart",
+    "node ~/.codex/hooks/codex-session-mapping.cjs",
+    runtime,
+  );
+  const mappingFile = await mappingCheck(
+    join(runtime.homeDir, ".codex", "ai-devkit", "sessions.json"),
+    runtime,
+  );
+  const installed = script.status === "pass" && registration.status === "pass";
+  return {
+    label: "ai-devkit hook",
+    installed,
+    status: worstReadinessStatus([script.status, registration.status, mappingFile.status]),
+    errors: [...script.errors, ...registration.errors, ...mappingFile.errors],
+    details: { sessionMappingScript: script, registration, mappingFile },
+  };
+}
+
+export const codexReadiness: HarnessReadinessProfile = {
+  configDir: ".codex",
+  auth: authCheck,
+  integration: integrationCheck,
+};

package/src/harnesses/copilot/readiness.ts

@@ -0,0 +1,33 @@
+import type {
+  AuthReadinessCheck,
+  HarnessReadinessProfile,
+  ReadinessRuntime,
+} from "../readiness/types.js";
+
+async function authCheck(runtime: ReadinessRuntime): Promise<AuthReadinessCheck> {
+  try {
+    await runtime.runCommand("gh", ["auth", "status", "--hostname", "github.com"]);
+    return {
+      state: "authenticated",
+      source: "gh auth status --hostname github.com",
+      provider: "github",
+      availableProviders: ["GitHub"],
+      status: "pass",
+      errors: [],
+    };
+  } catch {
+    return {
+      state: "unknown",
+      source: "gh auth status --hostname github.com",
+      provider: null,
+      availableProviders: ["GitHub"],
+      status: "warn",
+      errors: ["Copilot authentication could not be verified through GitHub CLI"],
+    };
+  }
+}
+
+export const copilotReadiness: HarnessReadinessProfile = {
+  configDir: ".copilot",
+  auth: authCheck,
+};

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;
+  }
+}