@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/src/harnesses/pi/readiness.ts

@@ -0,0 +1,104 @@
+import { join } from "node:path";
+import {
+  displayHome,
+  mappingCheck,
+  nonEmpty,
+  record,
+  worstReadinessStatus,
+} from "../readiness/checks.js";
+import type {
+  AuthReadinessCheck,
+  HarnessReadinessProfile,
+  IntegrationReadinessCheck,
+  ReadinessRuntime,
+} from "../readiness/types.js";
+
+function providerNames(parsed: Record<string, unknown>): string[] {
+  const names = new Set<string>();
+  if (nonEmpty(parsed.provider)) names.add((parsed.provider as string).trim());
+  const providers = record(parsed.providers);
+  if (providers) {
+    for (const name of Object.keys(providers)) {
+      if (name.trim()) names.add(name);
+    }
+  }
+  for (const [name, value] of Object.entries(parsed)) {
+    if (name === "provider" || name === "providers") continue;
+    if (record(value) && name.trim()) names.add(name);
+  }
+  return [...names].sort();
+}
+
+async function authCheck(runtime: ReadinessRuntime): Promise<AuthReadinessCheck> {
+  const sourcePath = join(runtime.homeDir, ".pi", "agent", "auth.json");
+  try {
+    const parsed = record(JSON.parse(await runtime.readFile(sourcePath)));
+    if (!parsed) throw new Error("invalid");
+    const availableProviders = providerNames(parsed);
+    const provider = nonEmpty(parsed.provider) ? (parsed.provider as string).trim() : null;
+    const authenticated = availableProviders.length > 0;
+    return {
+      state: authenticated ? "authenticated" : "unauthenticated",
+      source: displayHome(sourcePath, runtime.homeDir),
+      provider,
+      availableProviders,
+      status: authenticated ? "pass" : "fail",
+      errors: authenticated ? [] : ["Pi credential file has no configured model provider"],
+    };
+  } catch {
+    return {
+      state: "unauthenticated",
+      source: displayHome(sourcePath, runtime.homeDir),
+      provider: null,
+      availableProviders: [],
+      status: "fail",
+      errors: ["Pi credential file is missing or invalid"],
+    };
+  }
+}
+
+function isSessionTrackerListed(output: string): boolean {
+  const normalized = output.toLowerCase();
+  return (
+    normalized.includes("@ai-devkit/pi-session-tracker") ||
+    /\bsession[\s-]+tracker\b/.test(normalized)
+  );
+}
+
+async function integrationCheck(runtime: ReadinessRuntime): Promise<IntegrationReadinessCheck> {
+  let installed = false;
+  try {
+    const result = await runtime.runCommand("pi", ["list"]);
+    installed = isSessionTrackerListed(result.stdout);
+  } catch {
+    // Safe fixed result below.
+  }
+  const mapping = await mappingCheck(
+    join(runtime.homeDir, ".pi", "agent", "sessions.json"),
+    runtime,
+  );
+  const mappingStatus = mapping.valid || !mapping.present ? "pass" : "fail";
+  const status = worstReadinessStatus([installed ? "pass" : "fail", mappingStatus]);
+  return {
+    label: "ai-devkit plugin",
+    installed,
+    status,
+    errors: [
+      ...(!installed ? ["Pi session tracker is not registered"] : []),
+      ...(mappingStatus === "fail" ? mapping.errors : []),
+    ],
+    details: {
+      package: "@ai-devkit/pi-session-tracker",
+      registryPath: mapping.path,
+      registryValid: mapping.valid,
+      invalidEntries: mapping.invalidEntries,
+      staleEntries: mapping.staleEntries,
+    },
+  };
+}
+
+export const piReadiness: HarnessReadinessProfile = {
+  configDir: ".pi",
+  auth: authCheck,
+  integration: integrationCheck,
+};

package/src/harnesses/readiness/AgentReadiness.ts

@@ -0,0 +1,87 @@
+import { claudeReadiness } from "../claude/readiness.js";
+import { codexReadiness } from "../codex/readiness.js";
+import { copilotReadiness } from "../copilot/readiness.js";
+import { openCodeReadiness } from "../opencode/readiness.js";
+import { piReadiness } from "../pi/readiness.js";
+import {
+  builtInSkillsCheck,
+  createReadinessRuntime,
+  directoryCheck,
+  executableCheck,
+  worstReadinessStatus,
+} from "./checks.js";
+import {
+  READINESS_AGENT_TYPES,
+  type AgentReadinessOptions,
+  type AgentReadinessReport,
+  type HarnessReadinessProfile,
+  type ReadinessAgentType,
+  type ReadinessRuntime,
+} from "./types.js";
+
+const READINESS_PROFILES: Record<ReadinessAgentType, HarnessReadinessProfile> = {
+  claude: claudeReadiness,
+  codex: codexReadiness,
+  gemini_cli: { configDir: ".gemini" },
+  grok_cli: { configDir: ".grok" },
+  kiro: { configDir: ".kiro" },
+  antigravity_cli: { configDir: ".gemini/antigravity-cli" },
+  opencode: openCodeReadiness,
+  copilot: copilotReadiness,
+  pi: piReadiness,
+};
+
+export async function getAgentReadinessReport(
+  agent: ReadinessAgentType,
+  options: AgentReadinessOptions = {},
+): Promise<AgentReadinessReport> {
+  return agentReadiness(agent, createReadinessRuntime(options));
+}
+
+async function agentReadiness(
+  agent: ReadinessAgentType,
+  runtime: ReadinessRuntime,
+): Promise<AgentReadinessReport> {
+  const profile = READINESS_PROFILES[agent];
+  const [executable, globalConfig, builtInSkills, auth, integration] = await Promise.all([
+    executableCheck(agent, runtime),
+    directoryCheck(profile.configDir, runtime),
+    builtInSkillsCheck(agent, runtime),
+    profile.auth?.(runtime),
+    profile.integration?.(runtime),
+  ]);
+  return {
+    type: agent,
+    executable,
+    globalConfig,
+    builtInSkills,
+    auth,
+    integration,
+    status: worstReadinessStatus([
+      executable.status,
+      globalConfig.status,
+      ...(auth ? [auth.status] : []),
+      ...(integration ? [integration.status] : []),
+    ]),
+  };
+}
+
+export async function getAgentReadinessReports(
+  options: AgentReadinessOptions = {},
+): Promise<Record<ReadinessAgentType, AgentReadinessReport>> {
+  const runtime = createReadinessRuntime(options);
+  const entries = await Promise.all(
+    READINESS_AGENT_TYPES.map(
+      async (agent) => [agent, await agentReadiness(agent, runtime)] as const,
+    ),
+  );
+  return Object.fromEntries(entries) as Record<ReadinessAgentType, AgentReadinessReport>;
+}
+
+export { worstReadinessStatus } from "./checks.js";
+export type {
+  AgentReadinessOptions,
+  AgentReadinessReport,
+  ReadinessAgentType,
+  ReadinessStatus,
+} from "./types.js";

package/src/harnesses/readiness/checks.ts

@@ -0,0 +1,336 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access as fsAccess, readFile as fsReadFile } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import { promisify } from "node:util";
+import { getCodexCapacityReport } from "../../capacity/index.js";
+import { HARNESS_RUNTIME_PROFILES } from "../runtimeProfiles.js";
+import type {
+  AgentReadinessOptions,
+  BuiltInSkillsReadinessCheck,
+  DirectoryReadinessCheck,
+  ExecutableReadinessCheck,
+  ReadinessAgentType,
+  ReadinessCheck,
+  ReadinessRuntime,
+  ReadinessStatus,
+} from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+export function createReadinessRuntime(options: AgentReadinessOptions): ReadinessRuntime {
+  return {
+    homeDir: options.homeDir ?? process.env.HOME ?? "",
+    path: options.path ?? process.env.PATH ?? "",
+    assetRoot: options.assetRoot ?? null,
+    builtInSkillNames: options.builtInSkillNames ?? [],
+    skillRoots: options.skillRoots ?? {},
+    readFile: options.readFile ?? ((target) => fsReadFile(target, "utf8")),
+    access: options.access ?? ((target, mode = constants.R_OK) => fsAccess(target, mode)),
+    runCommand: options.runCommand ?? defaultRunCommand,
+    codexAuth: options.codexAuth ?? (async () => (await getCodexCapacityReport()).authenticated),
+  };
+}
+
+async function defaultRunCommand(command: string, args: string[]) {
+  const result = await execFileAsync(command, args, {
+    encoding: "utf8",
+    timeout: 5000,
+    maxBuffer: 1024 * 1024,
+  });
+  return { stdout: result.stdout, stderr: result.stderr };
+}
+
+function statusRank(status: ReadinessStatus): number {
+  return status === "fail" ? 2 : status === "warn" ? 1 : 0;
+}
+
+export function worstReadinessStatus(statuses: ReadinessStatus[]): ReadinessStatus {
+  return statuses.reduce<ReadinessStatus>(
+    (worst, current) => (statusRank(current) > statusRank(worst) ? current : worst),
+    "pass",
+  );
+}
+
+export function displayHome(target: string, homeDir: string): string {
+  return target === homeDir
+    ? "~"
+    : target.startsWith(`${homeDir}/`)
+      ? `~${target.slice(homeDir.length)}`
+      : target;
+}
+
+export function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export function nonEmpty(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export async function accessible(
+  target: string,
+  runtime: ReadinessRuntime,
+  mode = constants.R_OK,
+): Promise<boolean> {
+  try {
+    await runtime.access(target, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveExecutable(
+  command: string,
+  runtime: ReadinessRuntime,
+): Promise<string | null> {
+  const candidates = runtime.path
+    .split(delimiter)
+    .filter(Boolean)
+    .map((directory) => join(directory, command));
+  const checks = await Promise.all(
+    candidates.map(async (target) => ({
+      target,
+      available: await accessible(target, runtime, constants.X_OK),
+    })),
+  );
+  return checks.find((check) => check.available)?.target ?? null;
+}
+
+export async function executableCheck(
+  agent: ReadinessAgentType,
+  runtime: ReadinessRuntime,
+): Promise<ExecutableReadinessCheck> {
+  const command = HARNESS_RUNTIME_PROFILES[agent].command;
+  const resolvedPath = await resolveExecutable(command, runtime);
+  return {
+    command,
+    path: resolvedPath,
+    status: resolvedPath ? "pass" : "fail",
+    errors: resolvedPath ? [] : [`${command} was not found on PATH`],
+  };
+}
+
+export async function directoryCheck(
+  configDir: string,
+  runtime: ReadinessRuntime,
+): Promise<DirectoryReadinessCheck> {
+  const target = join(runtime.homeDir, configDir);
+  const readable = await accessible(target, runtime);
+  return {
+    path: displayHome(target, runtime.homeDir),
+    present: readable,
+    readable,
+    status: readable ? "pass" : "fail",
+    errors: readable ? [] : ["global configuration directory is unavailable"],
+  };
+}
+
+export async function builtInSkillsCheck(
+  agent: ReadinessAgentType,
+  runtime: ReadinessRuntime,
+): Promise<BuiltInSkillsReadinessCheck> {
+  const relativeRoot = runtime.skillRoots[agent];
+  if (!relativeRoot) {
+    return {
+      path: null,
+      required: runtime.builtInSkillNames.length,
+      present: 0,
+      missing: [...runtime.builtInSkillNames],
+      status: "info",
+      errors: [],
+    };
+  }
+  const root = join(runtime.homeDir, relativeRoot);
+  const checks = await Promise.all(
+    runtime.builtInSkillNames.map(async (name) => ({
+      name,
+      present: await accessible(join(root, name, "SKILL.md"), runtime),
+    })),
+  );
+  const present = checks.filter((check) => check.present).map((check) => check.name);
+  const missing = runtime.builtInSkillNames.filter((name) => !present.includes(name));
+  return {
+    path: displayHome(root, runtime.homeDir),
+    required: runtime.builtInSkillNames.length,
+    present: present.length,
+    missing: [...missing],
+    status: "info",
+    errors: [],
+  };
+}
+
+export async function scriptCheck(
+  installed: string,
+  bundled: string,
+  runtime: ReadinessRuntime,
+): Promise<
+  ReadinessCheck & {
+    path: string;
+    present: boolean;
+    readable: boolean;
+    matchesBundledAsset: boolean;
+  }
+> {
+  let installedText: string;
+  try {
+    installedText = await runtime.readFile(installed);
+  } catch {
+    return {
+      path: displayHome(installed, runtime.homeDir),
+      present: false,
+      readable: false,
+      matchesBundledAsset: false,
+      status: "fail",
+      errors: ["hook script is unavailable"],
+    };
+  }
+  try {
+    const bundledText = await runtime.readFile(bundled);
+    const matches = installedText === bundledText;
+    return {
+      path: displayHome(installed, runtime.homeDir),
+      present: true,
+      readable: true,
+      matchesBundledAsset: matches,
+      status: matches ? "pass" : "fail",
+      errors: matches ? [] : ["hook script differs from the bundled AI DevKit asset"],
+    };
+  } catch {
+    return {
+      path: displayHome(installed, runtime.homeDir),
+      present: true,
+      readable: true,
+      matchesBundledAsset: false,
+      status: "fail",
+      errors: ["bundled hook asset is unavailable"],
+    };
+  }
+}
+
+function containsHook(root: unknown, event: string, command: string): boolean {
+  const hooks = record(record(root)?.hooks);
+  const entries = hooks?.[event];
+  if (!Array.isArray(entries)) return false;
+  return entries.some((entry) => {
+    const commands = record(entry)?.hooks;
+    return (
+      Array.isArray(commands) &&
+      commands.some((hook) => {
+        const item = record(hook);
+        return item?.type === "command" && item.command === command;
+      })
+    );
+  });
+}
+
+export async function registrationCheck(
+  target: string,
+  event: string,
+  command: string,
+  runtime: ReadinessRuntime,
+): Promise<
+  ReadinessCheck & {
+    path: string;
+    event: string;
+    command: string;
+    present: boolean;
+    valid: boolean;
+  }
+> {
+  try {
+    const parsed = JSON.parse(await runtime.readFile(target));
+    const valid = containsHook(parsed, event, command);
+    return {
+      path: displayHome(target, runtime.homeDir),
+      event,
+      command,
+      present: true,
+      valid,
+      status: valid ? "pass" : "fail",
+      errors: valid ? [] : ["required hook registration is missing"],
+    };
+  } catch {
+    return {
+      path: displayHome(target, runtime.homeDir),
+      event,
+      command,
+      present: false,
+      valid: false,
+      status: "fail",
+      errors: ["hook configuration is missing or invalid"],
+    };
+  }
+}
+
+export async function mappingCheck(
+  target: string,
+  runtime: ReadinessRuntime,
+): Promise<
+  ReadinessCheck & {
+    path: string;
+    present: boolean;
+    valid: boolean;
+    invalidEntries: number;
+    staleEntries: number;
+  }
+> {
+  let text: string;
+  try {
+    text = await runtime.readFile(target);
+  } catch {
+    return {
+      path: displayHome(target, runtime.homeDir),
+      present: false,
+      valid: false,
+      invalidEntries: 0,
+      staleEntries: 0,
+      status: "warn",
+      errors: ["session mapping has not been created"],
+    };
+  }
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    parsed = record(JSON.parse(text));
+  } catch {
+    // Fixed safe error below.
+  }
+  if (!parsed) {
+    return {
+      path: displayHome(target, runtime.homeDir),
+      present: true,
+      valid: false,
+      invalidEntries: 0,
+      staleEntries: 0,
+      status: "fail",
+      errors: ["session mapping is invalid"],
+    };
+  }
+  const entries = await Promise.all(
+    Object.entries(parsed).map(async ([pid, sessionPath]) => {
+      if (!/^\d+$/.test(pid) || typeof sessionPath !== "string" || !sessionPath) {
+        return { valid: false, stale: false };
+      }
+      return { valid: true, stale: !(await accessible(sessionPath, runtime)) };
+    }),
+  );
+  const invalidEntries = entries.filter((entry) => !entry.valid).length;
+  const staleEntries = entries.filter((entry) => entry.stale).length;
+  const valid = invalidEntries === 0;
+  return {
+    path: displayHome(target, runtime.homeDir),
+    present: true,
+    valid,
+    invalidEntries,
+    staleEntries,
+    status: !valid ? "fail" : staleEntries ? "warn" : "pass",
+    errors: !valid
+      ? ["session mapping contains invalid entries"]
+      : staleEntries
+        ? ["session mapping contains stale entries"]
+        : [],
+  };
+}

package/src/harnesses/readiness/types.ts

@@ -0,0 +1,90 @@
+import { AGENT_TYPES } from "../../adapters/AgentAdapter.js";
+
+export const READINESS_AGENT_TYPES = AGENT_TYPES;
+
+export type ReadinessStatus = "pass" | "warn" | "fail";
+export type ReadinessAuthState = "authenticated" | "unauthenticated" | "unknown";
+export type ReadinessAgentType = (typeof READINESS_AGENT_TYPES)[number];
+type ReadinessInfoStatus = ReadinessStatus | "info";
+
+export type CommandResult = { stdout: string; stderr: string };
+export type ReadFile = (target: string) => Promise<string>;
+export type Access = (target: string, mode?: number) => Promise<void>;
+export type RunCommand = (command: string, args: string[]) => Promise<CommandResult>;
+
+export interface ReadinessCheck<S extends ReadinessInfoStatus = ReadinessStatus> {
+  status: S;
+  errors: string[];
+}
+
+export interface ExecutableReadinessCheck extends ReadinessCheck {
+  command: string;
+  path: string | null;
+}
+
+export interface DirectoryReadinessCheck extends ReadinessCheck {
+  path: string;
+  present: boolean;
+  readable: boolean;
+}
+
+export interface BuiltInSkillsReadinessCheck extends ReadinessCheck<"info"> {
+  path: string | null;
+  required: number;
+  present: number;
+  missing: string[];
+}
+
+export interface AuthReadinessCheck extends ReadinessCheck {
+  state: ReadinessAuthState;
+  source: string;
+  provider: string | null;
+  availableProviders: string[];
+}
+
+export interface IntegrationReadinessCheck extends ReadinessCheck {
+  label: string;
+  installed: boolean;
+  details?: Record<string, unknown>;
+}
+
+export interface AgentReadinessReport {
+  type: ReadinessAgentType;
+  executable: ExecutableReadinessCheck;
+  globalConfig: DirectoryReadinessCheck;
+  builtInSkills: BuiltInSkillsReadinessCheck;
+  auth?: AuthReadinessCheck;
+  integration?: IntegrationReadinessCheck;
+  status: ReadinessStatus;
+}
+
+export interface AgentReadinessOptions {
+  homeDir?: string;
+  path?: string;
+  assetRoot?: string;
+  builtInSkillNames?: readonly string[];
+  skillRoots?: Partial<Record<ReadinessAgentType, string>>;
+  readFile?: ReadFile;
+  access?: Access;
+  runCommand?: RunCommand;
+  codexAuth?: () => Promise<boolean | null>;
+}
+
+export type ReadinessRuntime = Required<
+  Omit<AgentReadinessOptions, "assetRoot" | "builtInSkillNames" | "skillRoots">
+> & {
+  assetRoot: string | null;
+  builtInSkillNames: readonly string[];
+  skillRoots: Partial<Record<ReadinessAgentType, string>>;
+};
+
+export type AuthReadinessProbe = (runtime: ReadinessRuntime) => Promise<AuthReadinessCheck>;
+export type IntegrationReadinessProbe = (
+  runtime: ReadinessRuntime,
+) => Promise<IntegrationReadinessCheck>;
+
+export interface HarnessReadinessProfile {
+  configDir: string;
+  auth?: AuthReadinessProbe;
+  integration?: IntegrationReadinessProbe;
+}