@ai-devkit/agent-manager 0.39.0 → 0.41.0

package/src/__tests__/readiness-fixtures.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Readiness fixture replay: each committed bundle under
+ * `fixtures/readiness/` provides the injectable seams (files,
+ * executables, command outputs, codexAuth) plus `expected` — the
+ * byte-identical reports the readiness probes must produce replaying
+ * the same bundle through their injectable seams.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  getAgentReadinessReports,
+  type AgentReadinessOptions,
+} from "../harnesses/readiness/AgentReadiness.js";
+
+interface ReadinessBundle {
+  options: {
+    homeDir: string;
+    path: string;
+    assetRoot?: string;
+    builtInSkillNames?: string[];
+    skillRoots?: Record<string, string>;
+  };
+  /** Absolute path → contents, or "<dir>" for a directory entry. */
+  files: Record<string, string>;
+  /** Paths that answer X_OK access. */
+  executables: string[];
+  /** `"command arg1 arg2"` → output; `ok: false` rejects like execFile. */
+  commands: Record<string, { stdout: string; stderr?: string; ok?: boolean }>;
+  codexAuth?: boolean | null;
+  expected: Record<string, unknown>;
+}
+
+const READINESS_ROOT = path.resolve(__dirname, "../../../..", "fixtures", "readiness");
+
+const bundlePaths = fs.existsSync(READINESS_ROOT)
+  ? fs
+      .readdirSync(READINESS_ROOT)
+      .filter((f) => f.endsWith(".json") && !f.startsWith("live"))
+      .sort()
+      .map((f) => path.join(READINESS_ROOT, f))
+  : [];
+
+function replay(bundle: ReadinessBundle): Promise<Record<string, unknown>> {
+  const executableSet = new Set(bundle.executables);
+  const options: AgentReadinessOptions = {
+    homeDir: bundle.options.homeDir,
+    path: bundle.options.path,
+    assetRoot: bundle.options.assetRoot,
+    builtInSkillNames: bundle.options.builtInSkillNames ?? [],
+    skillRoots: bundle.options.skillRoots ?? {},
+    readFile: async (target) => {
+      if (!(target in bundle.files)) throw new Error("missing");
+      return bundle.files[target];
+    },
+    access: async (target) => {
+      if (executableSet.has(target) || target in bundle.files) return;
+      throw new Error("missing");
+    },
+    runCommand: async (command, args) => {
+      const key = [command, ...args].join(" ");
+      const stub = bundle.commands[key];
+      if (!stub) throw new Error(`unexpected command ${key}`);
+      if (stub.ok === false) throw new Error(`command failed: ${key}`);
+      return { stdout: stub.stdout, stderr: stub.stderr ?? "" };
+    },
+    codexAuth: async () => bundle.codexAuth ?? null,
+  };
+  return getAgentReadinessReports(options);
+}
+
+describe("readiness fixture replay", () => {
+  it.each(bundlePaths)("%s", async (bundlePath) => {
+    const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8")) as ReadinessBundle;
+    const reports = await replay(bundle);
+    expect(reports).toEqual(bundle.expected);
+  });
+});

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/fixtures/bundle.ts

@@ -0,0 +1,130 @@
+/**
+ * Golden-fixture bundles: the parity oracle for the devkit-harness Rust port.
+ * A bundle records everything `detectAgents` consumed and produced so both
+ * the TS adapter and its Rust port can be run against identical inputs.
+ *
+ * Format (committed under fixtures/harness/<type>/<case>.json):
+ * {
+ *   adapter, capturedAt, frozenNow,
+ *   processes: ProcessInfo[],
+ *   home: { "<relpath under $FIXTURE_HOME>": "<content with $FIXTURE_HOME refs>" },
+ *   expected: AgentInfo[] (dates as ISO strings)
+ * }
+ */
+
+import type { AgentInfo, ProcessInfo } from "../adapters/AgentAdapter.js";
+
+export const HOME_PLACEHOLDER = "$FIXTURE_HOME";
+/** Resolves to the instant home files were written (birthtime matching). */
+export const NOW_PLACEHOLDER = "$NOW";
+/** Resolves to the local `YYYY/MM/DD` day dir at replay (Codex sessions). */
+export const TODAY_PLACEHOLDER = "$TODAY";
+
+export interface FixtureBundle {
+  adapter: string;
+  capturedAt: string;
+  /** Epoch ms the clock was frozen at; `"$NOW"` = materialization instant. */
+  frozenNow: number | string;
+  processes: ProcessInfo[];
+  /** Files under the fixture HOME; content may embed HOME_PLACEHOLDER. */
+  home: Record<string, string>;
+  /**
+   * mtime overrides keyed by `home` relpath — epoch ms, or "$NOW" for the
+   * materialization instant. Adapters whose output derives from file mtimes
+   * (Grok's lastActive / latest-session pick) need deterministic mtimes.
+   */
+  mtimes?: Record<string, number | string>;
+  /**
+   * AgentRegistry rows (pid→sessionFilePath etc.) visible at capture time,
+   * restricted to captured process pids — adapters' registry caches read
+   * this state, so replay seeds an isolated registry with it.
+   */
+  registry?: Record<string, unknown>[];
+  /**
+   * SQLite stores adapters consult (OpenCode's opencode.db), keyed by
+   * relpath under $FIXTURE_HOME: SQL statements (DDL + INSERTs) executed
+   * in order to materialize each db. Statements may embed HOME_PLACEHOLDER.
+   */
+  sqlite?: Record<string, string[]>;
+  expected: Record<string, unknown>[];
+}
+
+/**
+ * Rewrite harness dot-dir paths (`<home>/.claude`, `<home>/.codex`, …) to the
+ * placeholder — nothing else. Project cwds share the home prefix
+ * (`<home>/Code/proj`) and MUST stay literal: harnesses encode them into
+ * session-dir names (`-Users-foo-proj`), so rewriting them breaks
+ * cwd↔session matching on replay.
+ */
+export function sanitize<T>(value: T, realHome: string): T {
+  const homeDot = `${realHome}/.`;
+  if (typeof value === "string") {
+    return value.split(homeDot).join(`${HOME_PLACEHOLDER}/.`) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => sanitize(v, realHome)) as T;
+  if (value && typeof value === "object") {
+    if (value instanceof Date) return value.toISOString() as T;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = sanitize(v, realHome);
+    return out as T;
+  }
+  return value;
+}
+
+/** Inverse of sanitize: expand the placeholder to a concrete dir. */
+export function expand<T>(value: T, fixtureHome: string): T {
+  if (typeof value === "string") {
+    return value.split(HOME_PLACEHOLDER).join(fixtureHome) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => expand(v, fixtureHome)) as T;
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = expand(v, fixtureHome);
+    return out as T;
+  }
+  return value;
+}
+
+/** Replace NOW_PLACEHOLDER strings with a resolved ISO instant. */
+export function expandNow<T>(value: T, isoInstant: string): T {
+  if (typeof value === "string") {
+    return value.split(NOW_PLACEHOLDER).join(isoInstant) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => expandNow(v, isoInstant)) as T;
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = expandNow(v, isoInstant);
+    return out as T;
+  }
+  return value;
+}
+
+/** Agents normalized the way the wire carries them (Date → ISO string). */
+export function normalizeAgents(agents: AgentInfo[], realHome: string) {
+  return sanitize(JSON.parse(JSON.stringify(agents)), realHome);
+}
+
+/**
+ * Freeze `Date` at `epochMs` for the duration of `fn`. Adapters stamp
+ * `new Date()` in several places; parity requires a fixed clock.
+ */
+export async function withFrozenClock<T>(epochMs: number, fn: () => Promise<T>): Promise<T> {
+  const RealDate = Date;
+  class FrozenDate extends RealDate {
+    constructor(...args: unknown[]) {
+      if (args.length === 0) super(epochMs);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      else super(...(args as [any]));
+    }
+    static override now() {
+      return epochMs;
+    }
+  }
+  const g = globalThis as { Date: DateConstructor };
+  g.Date = FrozenDate as DateConstructor;
+  try {
+    return await fn();
+  } finally {
+    g.Date = RealDate;
+  }
+}