@ai-devkit/agent-manager 0.37.0 → 0.38.0

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

package/src/{utils/agents.ts → harnesses/runtimeProfiles.ts}

@@ -1,44 +1,46 @@
-import path from "path";
-import type { AGENT_TYPES } from "../adapters/AgentAdapter.js";
-import { executablePath } from "./process.js";
+import path from "node:path";
+import { AGENT_TYPES, type AgentType } from "../adapters/AgentAdapter.js";
+import { executablePath } from "../utils/process.js";
 
-/** 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`). */
+export interface HarnessRuntimeProfile {
   command: string;
-  /** Returns true if the given `ps` command line belongs to this agent. */
+  runtimeKind: string;
+  discoveryAliases: readonly string[];
   matches: (psCommand: string) => boolean;
 }
 
-/**
- * Per-agent configuration: launch command plus a matcher that recognizes the
- * agent's process in `ps` output. Each matcher knows that agent's distribution
- * quirks (e.g. gemini ships as a Node script so its real binary is in argv[1..]).
- */
-export const AGENTS: Record<StartableAgentType, AgentConfig> = {
-  claude: { command: "claude", matches: matchArgv0("claude") },
-  codex: { command: "codex", matches: matchArgv0("codex") },
-  copilot: { command: "copilot", matches: matchArgv0Name("copilot-cli") },
-  gemini_cli: { command: "gemini", matches: matchAnyToken("gemini") },
-  grok_cli: { command: "grok", matches: matchArgv0("grok") },
-  antigravity_cli: { command: "agy", matches: matchArgv0("agy") },
-  opencode: { command: "opencode", matches: matchArgv0("opencode") },
-  pi: { command: "pi", matches: matchAnyBasename(["pi"]) },
-  kiro: { command: "kiro-cli", matches: matchAnyBasename(["kiro-cli", "kiro"]) },
+export const HARNESS_RUNTIME_PROFILES: Record<StartableAgentType, HarnessRuntimeProfile> = {
+  claude: profile("claude", matchArgv0("claude")),
+  codex: profile("codex", matchArgv0("codex")),
+  copilot: profile("copilot", matchArgv0Name("copilot-cli")),
+  gemini_cli: profile("gemini", matchAnyBasename(["gemini"]), ["gemini_cli"]),
+  grok_cli: profile("grok", matchArgv0("grok"), ["grok_cli"]),
+  antigravity_cli: profile("agy", matchArgv0("agy"), ["antigravity", "antigravity_cli"]),
+  opencode: profile("opencode", matchArgv0("opencode")),
+  pi: profile("pi", matchAnyBasename(["pi"])),
+  kiro: profile("kiro", matchAnyBasename(["kiro-cli", "kiro"]), ["kiro_cli", "kiro-cli"]),
 };
 
-/**
- * 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.
- */
+export function runtimeAgentMatchesHarness(runtimeAgent: string, type: AgentType): boolean {
+  if (type === "other") return runtimeAgent.toLowerCase() === "other";
+  return HARNESS_RUNTIME_PROFILES[type].discoveryAliases.includes(runtimeAgent.toLowerCase());
+}
+
+function profile(
+  runtimeKind: string,
+  matches: (psCommand: string) => boolean,
+  extraAliases: readonly string[] = [],
+): HarnessRuntimeProfile {
+  return {
+    command: runtimeKind === "kiro" ? "kiro-cli" : runtimeKind,
+    runtimeKind,
+    discoveryAliases: [runtimeKind, ...extraAliases],
+    matches,
+  };
+}
+
 const ABSOLUTE_PATH = /^(?:\/|[a-zA-Z]:[\\/])/;
 const PATH_SEPARATOR = /[\\/]/;
 
@@ -50,14 +52,12 @@ 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]) &&
@@ -87,10 +87,6 @@ function matchArgv0Name(name: string): (psCommand: string) => boolean {
   };
 }
 
-function matchAnyToken(name: string): (psCommand: string) => boolean {
-  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));