@ai-devkit/agent-manager 0.37.0 → 0.38.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/opencode/readiness.ts

@@ -0,0 +1,48 @@
+import type {
+  AuthReadinessCheck,
+  HarnessReadinessProfile,
+  ReadinessRuntime,
+} from "../readiness/types.js";
+
+const ANSI_ESCAPE_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
+
+function authProviderNames(output: string): string[] {
+  const names = new Set<string>();
+  for (const line of output.replace(ANSI_ESCAPE_PATTERN, "").split(/\r?\n/)) {
+    const match = /^\s*[●*+-]\s+(.+?)\s*$/.exec(line);
+    if (!match) continue;
+    const name = match[1].replace(/\s+(?:api|oauth|[\w-]*token|[A-Z][A-Z0-9_]+)$/i, "").trim();
+    if (name && !/^\d+\s+(?:credentials?|environment variables?)$/i.test(name)) names.add(name);
+  }
+  return [...names].sort();
+}
+
+async function authCheck(runtime: ReadinessRuntime): Promise<AuthReadinessCheck> {
+  try {
+    const result = await runtime.runCommand("opencode", ["auth", "list"]);
+    const availableProviders = authProviderNames(result.stdout);
+    const authenticated = availableProviders.length > 0;
+    return {
+      state: authenticated ? "authenticated" : "unauthenticated",
+      source: "opencode auth list",
+      provider: null,
+      availableProviders,
+      status: authenticated ? "pass" : "fail",
+      errors: authenticated ? [] : ["OpenCode has no configured credentials"],
+    };
+  } catch {
+    return {
+      state: "unknown",
+      source: "opencode auth list",
+      provider: null,
+      availableProviders: [],
+      status: "warn",
+      errors: ["OpenCode authentication probe failed"],
+    };
+  }
+}
+
+export const openCodeReadiness: HarnessReadinessProfile = {
+  configDir: ".config/opencode",
+  auth: authCheck,
+};

package/src/harnesses/pi/credentials.ts

@@ -0,0 +1,129 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type UnknownRecord = Record<string, unknown>;
+
+export type PiCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+};
+
+export type PiAnthropicCredential = {
+  kind: "oauth";
+  access: string;
+  expiresMs: number | null;
+};
+
+export type PiOpenAiCredential =
+  | { kind: "platform"; key: string }
+  | { kind: "oauth"; access: string; accountId: string; expiresMs: number | null };
+
+const OPENAI_CREDENTIALS_MISSING =
+  "OpenAI credentials not found; set OPENAI_API_KEY, configure the Pi openai provider, or log in to OpenAI via Pi";
+const ZAI_CREDENTIAL_MISSING =
+  "z.ai API key not found; set Z_AI_API_KEY or configure Pi provider zai";
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function epochMilliseconds(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+  return value > 1e12 ? value : value * 1000;
+}
+
+async function readPiAuthRoot(options: PiCredentialOptions): Promise<UnknownRecord> {
+  const env = options.env ?? process.env;
+  const authPath = join(env.HOME || homedir(), ".pi", "agent", "auth.json");
+  const contents = await (options.readFile ?? readFile)(authPath, "utf8");
+  const parsed = record(JSON.parse(contents));
+  if (!parsed) throw new Error("Pi auth file is malformed");
+  return parsed;
+}
+
+export async function resolvePiAnthropicCredential(
+  options: PiCredentialOptions = {},
+): Promise<PiAnthropicCredential> {
+  let root: UnknownRecord;
+  try {
+    root = await readPiAuthRoot(options);
+  } catch (error) {
+    if (record(error)?.code === "ENOENT") {
+      throw new Error("Pi Anthropic OAuth credentials not found");
+    }
+    throw new Error("Pi Anthropic auth file is malformed");
+  }
+
+  const credential = record(root.anthropic);
+  if (!credential) throw new Error("Pi Anthropic OAuth credentials not found");
+  const access = credential.type === "oauth" ? nonEmptyText(credential.access) : null;
+  if (!access) throw new Error("Pi Anthropic OAuth credential is malformed");
+  return {
+    kind: "oauth",
+    access,
+    expiresMs: epochMilliseconds(credential.expires),
+  };
+}
+
+export async function resolvePiOpenAiCredential(
+  options: PiCredentialOptions = {},
+): Promise<PiOpenAiCredential> {
+  const env = options.env ?? process.env;
+  const environmentKey = nonEmptyText(env.OPENAI_API_KEY);
+  if (environmentKey) return { kind: "platform", key: environmentKey };
+
+  let root: UnknownRecord;
+  try {
+    root = await readPiAuthRoot(options);
+  } catch (error) {
+    if (record(error)?.code === "ENOENT") throw new Error(OPENAI_CREDENTIALS_MISSING);
+    throw new Error("OpenAI Pi auth file is malformed");
+  }
+
+  const platform = record(root.openai);
+  if (platform) {
+    const key = platform.type === "api_key" ? nonEmptyText(platform.key) : null;
+    if (!key) throw new Error("OpenAI Pi auth file has a malformed openai credential");
+    return { kind: "platform", key };
+  }
+
+  const oauth = record(root["openai-codex"]);
+  const access = oauth?.type === "oauth" ? nonEmptyText(oauth.access) : null;
+  const accountId = nonEmptyText(oauth?.accountId);
+  if (oauth && access && accountId) {
+    return {
+      kind: "oauth",
+      access,
+      accountId,
+      expiresMs: epochMilliseconds(oauth.expires),
+    };
+  }
+  throw new Error(OPENAI_CREDENTIALS_MISSING);
+}
+
+export async function resolvePiZaiApiKey(options: PiCredentialOptions = {}): Promise<string> {
+  const env = options.env ?? process.env;
+  const environmentKey = nonEmptyText(env.Z_AI_API_KEY);
+  if (environmentKey) return environmentKey;
+
+  let root: UnknownRecord;
+  try {
+    root = await readPiAuthRoot(options);
+  } catch (error) {
+    if (record(error)?.code === "ENOENT") throw new Error(ZAI_CREDENTIAL_MISSING);
+    throw new Error("z.ai Pi auth file is malformed");
+  }
+
+  const credential = record(root.zai);
+  if (!credential) throw new Error(ZAI_CREDENTIAL_MISSING);
+  const key = credential.type === "api_key" ? nonEmptyText(credential.key) : null;
+  if (!key) throw new Error("z.ai Pi auth file has a malformed zai credential");
+  return key;
+}

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