@mrclrchtr/supi-consulting 0.0.0-stage → 9.0.0

package/src/agents/antigravity/availability.ts

@@ -0,0 +1,231 @@
+import {
+  formatAntigravityLoginCommand,
+  getIsolatedAntigravityPaths,
+  type IsolatedAntigravityPaths,
+} from "./isolated-home.ts";
+import { CURATED_MODELS, type CuratedModel, isCuratedModel } from "./models.ts";
+import type { AntigravityProbeResult } from "./process/runner.ts";
+import { AntigravityProcessError, runAntigravityProbe } from "./process/runner.ts";
+
+/** Minimum supported Antigravity CLI version. */
+export const MINIMUM_ANTIGRAVITY_VERSION = Object.freeze({ major: 1, minor: 1, patch: 24 });
+const MAX_DISCOVERY_OUTPUT_BYTES = 128 * 1024;
+
+/** Parsed Antigravity CLI version. */
+export interface AntigravityVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string;
+}
+
+/** A successful immutable availability snapshot. */
+export interface AvailableAntigravity {
+  status: "available";
+  cliVersion: string;
+  catalogue: readonly CuratedModel[];
+}
+
+/** A bounded reason why the tool cannot be registered. */
+export interface UnavailableAntigravity {
+  status: "unavailable";
+  reason: "missing" | "old-version" | "authentication" | "discovery" | "no-curated-model";
+  warning: string;
+  cliVersion?: string;
+}
+
+/** Result of one immutable Antigravity availability discovery. */
+export type AntigravityAvailability = AvailableAntigravity | UnavailableAntigravity;
+
+/** Parse the first semantic version in CLI output. */
+export function parseAntigravityVersion(output: string): AntigravityVersion | undefined {
+  const match = output.match(/\b(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?\b/);
+  if (!match) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    ...(match[4] ? { prerelease: match[4] } : {}),
+  };
+}
+
+/** Return whether a parsed version meets the supported minimum. */
+export function isSupportedAntigravityVersion(version: AntigravityVersion): boolean {
+  const minimum = MINIMUM_ANTIGRAVITY_VERSION;
+  if (version.major !== minimum.major) return version.major > minimum.major;
+  if (version.minor !== minimum.minor) return version.minor > minimum.minor;
+  if (version.patch !== minimum.patch) return version.patch > minimum.patch;
+  return version.prerelease === undefined;
+}
+
+/** Format a version without retaining the CLI's complete output. */
+export function formatAntigravityVersion(version: AntigravityVersion): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+/** Parse bounded tab-separated `agy models` output. */
+export function parseAvailableModels(output: string): string[] {
+  if (Buffer.byteLength(output, "utf8") > MAX_DISCOVERY_OUTPUT_BYTES) {
+    throw new Error("Antigravity model output exceeded its limit.");
+  }
+  const found = new Set<string>();
+  for (const line of output.split(/\r?\n/)) {
+    for (const field of line.split("\t")) {
+      const model = field.trim();
+      if (isCuratedModel(model)) found.add(model);
+    }
+  }
+  return [...found];
+}
+
+/** Intersect discovered IDs with the immutable curated model order. */
+export function intersectCuratedModels(discovered: Iterable<string>): readonly CuratedModel[] {
+  const available = new Set(discovered);
+  return Object.freeze(CURATED_MODELS.filter((model) => available.has(model)));
+}
+
+/** Discover the supported Antigravity models in the Isolated Antigravity Home. */
+export async function discoverAntigravityAvailability(
+  options: {
+    paths?: IsolatedAntigravityPaths;
+    signal?: AbortSignal;
+    runProbe?: typeof runAntigravityProbe;
+  } = {},
+): Promise<AntigravityAvailability> {
+  const paths = options.paths ?? getIsolatedAntigravityPaths();
+  const runProbe = options.runProbe ?? runAntigravityProbe;
+  let versionResult: AntigravityProbeResult;
+  try {
+    versionResult = await runProbe({
+      paths,
+      cwd: paths.consultationWorkspace,
+      args: ["--version"],
+      signal: options.signal,
+      timeoutMs: 15_000,
+      maxStdoutBytes: MAX_DISCOVERY_OUTPUT_BYTES,
+    });
+  } catch (error) {
+    return unavailableFromError(error, paths);
+  }
+
+  const version = parseAntigravityVersion(`${versionResult.stdout}\n${versionResult.stderr}`);
+  if (!version || versionResult.exitCode !== 0 || versionResult.signal) {
+    return {
+      status: "unavailable",
+      reason: "discovery",
+      warning:
+        "Antigravity CLI version could not be read. Install or update Antigravity, then reload PI.",
+    };
+  }
+  const cliVersion = formatAntigravityVersion(version);
+  if (!isSupportedAntigravityVersion(version)) {
+    return {
+      status: "unavailable",
+      reason: "old-version",
+      cliVersion,
+      warning: `Antigravity CLI ${cliVersion} is too old; version ${formatAntigravityVersion(MINIMUM_ANTIGRAVITY_VERSION)} or newer is required.`,
+    };
+  }
+
+  let modelsResult: AntigravityProbeResult;
+  try {
+    modelsResult = await runProbe({
+      paths,
+      cwd: paths.consultationWorkspace,
+      args: ["models"],
+      signal: options.signal,
+      timeoutMs: 30_000,
+      maxStdoutBytes: MAX_DISCOVERY_OUTPUT_BYTES,
+    });
+  } catch (error) {
+    return unavailableFromError(error, paths, cliVersion);
+  }
+  const modelOutput = `${modelsResult.stdout}\n${modelsResult.stderr}`;
+  if (looksUnauthenticated(modelOutput)) return authenticationUnavailable(paths, cliVersion);
+  if (modelsResult.exitCode !== 0 || modelsResult.signal) {
+    return {
+      status: "unavailable",
+      reason: "discovery",
+      cliVersion,
+      warning:
+        "Antigravity model discovery failed. Check the isolated Antigravity sign-in, then reload PI.",
+    };
+  }
+
+  let catalogue: readonly CuratedModel[];
+  try {
+    catalogue = intersectCuratedModels(parseAvailableModels(modelsResult.stdout));
+  } catch {
+    return {
+      status: "unavailable",
+      reason: "discovery",
+      cliVersion,
+      warning: "Antigravity model discovery output exceeded its limit.",
+    };
+  }
+  if (catalogue.length === 0) {
+    return {
+      status: "unavailable",
+      reason: "no-curated-model",
+      cliVersion,
+      warning: "No supported curated Antigravity model is available to this account.",
+    };
+  }
+  return { status: "available", cliVersion, catalogue };
+}
+
+function unavailableFromError(
+  error: unknown,
+  paths: IsolatedAntigravityPaths,
+  cliVersion?: string,
+): UnavailableAntigravity {
+  if (error instanceof AntigravityProcessError && error.kind === "missing") {
+    return {
+      status: "unavailable",
+      reason: "missing",
+      warning: "Antigravity CLI `agy` was not found on PATH. Install it, then reload PI.",
+    };
+  }
+  if (
+    looksUnauthenticated(
+      error instanceof AntigravityProcessError
+        ? `${error.message}\n${error.stderr ?? ""}`
+        : error instanceof Error
+          ? error.message
+          : "",
+    )
+  ) {
+    return authenticationUnavailable(paths, cliVersion);
+  }
+  return {
+    status: "unavailable",
+    reason: "discovery",
+    ...(cliVersion ? { cliVersion } : {}),
+    warning: "Antigravity availability discovery failed. Check the installation, then reload PI.",
+  };
+}
+
+function authenticationUnavailable(
+  paths: IsolatedAntigravityPaths,
+  cliVersion?: string,
+): UnavailableAntigravity {
+  return {
+    status: "unavailable",
+    reason: "authentication",
+    ...(cliVersion ? { cliVersion } : {}),
+    warning: `Antigravity needs sign-in in its Isolated Antigravity Home. Run:\n${formatAntigravityLoginCommand(paths)}\nThen exit Antigravity and reload PI.`,
+  };
+}
+
+function looksUnauthenticated(value: string): boolean {
+  const normalized = value.toLowerCase();
+  return [
+    "please sign in",
+    "not authenticated",
+    "authentication required",
+    "unauthorized",
+    "sign-in required",
+    "login required",
+    "log in",
+  ].some((marker) => normalized.includes(marker));
+}

package/src/agents/antigravity/isolated-home.ts

@@ -0,0 +1,346 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readlink,
+  rename,
+  rm,
+  stat,
+  symlink,
+} from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const execFileAsync = promisify(execFile);
+const ANTIGRAVITY_BASE_DIR = join("supi", "consulting", "antigravity");
+const SETTINGS_RELATIVE_PATH = join(".gemini", "antigravity-cli", "settings.json");
+// macOS uses this conventional filename as the default keychain for an alternate HOME.
+const KEYCHAIN_RELATIVE_PATH = join("Library", "Keychains", "login.keychain-db");
+// A keychain with the special login name gets a user-password-managed password. Use a
+// package-owned keychain with an empty password, then expose it through the conventional name.
+const PRIVATE_KEYCHAIN_FILE_NAME = "antigravity.keychain-db";
+const EMPTY_TEMPLATE_NAME = "empty-git-template";
+const SECURITY_COMMAND = "/usr/bin/security";
+
+/** The package-owned paths used by Antigravity. */
+export interface IsolatedAntigravityPaths {
+  agentDir: string;
+  baseDir: string;
+  homeDir: string;
+  consultationWorkspace: string;
+  settingsPath: string;
+  gitTemplateDir: string;
+  /** The conventional macOS keychain path backed by the private isolated keychain. */
+  keychainPath: string;
+}
+
+/** Return package-owned Antigravity paths for one Pi agent directory. */
+export function getIsolatedAntigravityPaths(
+  agentDir = resolveAgentDirectory(),
+): IsolatedAntigravityPaths {
+  const baseDir = join(agentDir, ANTIGRAVITY_BASE_DIR);
+  const homeDir = join(baseDir, "home");
+  const consultationWorkspace = join(baseDir, "consultation-workspace");
+  return {
+    agentDir,
+    baseDir,
+    homeDir,
+    consultationWorkspace,
+    settingsPath: join(homeDir, SETTINGS_RELATIVE_PATH),
+    gitTemplateDir: join(baseDir, EMPTY_TEMPLATE_NAME),
+    keychainPath: join(homeDir, KEYCHAIN_RELATIVE_PATH),
+  };
+}
+
+/** Return the agent state directory used by the current Pi installation. */
+export function resolveAgentDirectory(): string {
+  return process.env.PI_CODING_AGENT_DIR || getAgentDir();
+}
+
+/** The exact Inspection Permission Set enforced in the Isolated Antigravity Home. */
+export const INSPECTION_PERMISSION_SET = Object.freeze({
+  allowNonWorkspaceAccess: false,
+  permissions: Object.freeze({
+    allow: Object.freeze(["read_url(*)"]),
+    deny: Object.freeze([
+      "write_file(*)",
+      "command(*)",
+      "unsandboxed(*)",
+      "mcp(*)",
+      "execute_url(*)",
+    ]),
+  }),
+});
+
+const consultationInitializations = new Map<string, Promise<void>>();
+const keychainInitializations = new Map<string, Promise<void>>();
+
+/** Options for preparing an isolated profile. */
+export interface IsolatedAntigravityPreparationOptions {
+  /** Override the host platform for tests. */
+  platform?: NodeJS.Platform;
+  /** Run one macOS Security command. */
+  runSecurityCommand?: (args: readonly string[], homeDir: string) => Promise<void>;
+}
+
+/** Create the stable empty Consultation Workspace without user Git templates. */
+export async function initializeConsultationWorkspace(
+  paths: IsolatedAntigravityPaths,
+): Promise<void> {
+  const existing = consultationInitializations.get(paths.consultationWorkspace);
+  if (existing !== undefined) {
+    await existing;
+    return;
+  }
+  const initialization = initializeConsultationWorkspaceOnce(paths).finally(() => {
+    consultationInitializations.delete(paths.consultationWorkspace);
+  });
+  consultationInitializations.set(paths.consultationWorkspace, initialization);
+  await initialization;
+}
+
+async function initializeConsultationWorkspaceOnce(paths: IsolatedAntigravityPaths): Promise<void> {
+  await mkdir(paths.baseDir, { recursive: true, mode: 0o700 });
+  await mkdir(paths.gitTemplateDir, { recursive: true, mode: 0o700 });
+  await mkdir(paths.consultationWorkspace, { recursive: true, mode: 0o700 });
+  await chmod(paths.baseDir, 0o700);
+  await chmod(paths.gitTemplateDir, 0o700);
+  await chmod(paths.consultationWorkspace, 0o700);
+
+  if (await isGitRepository(paths.consultationWorkspace)) return;
+
+  try {
+    await execFileAsync(
+      "git",
+      ["init", "--quiet", `--template=${paths.gitTemplateDir}`, paths.consultationWorkspace],
+      {
+        env: {
+          ...process.env,
+          GIT_CONFIG_NOSYSTEM: "1",
+        },
+        maxBuffer: 64 * 1024,
+      },
+    );
+  } catch (error) {
+    throw new Error("Could not initialize the Antigravity Consultation Workspace.", {
+      cause: error,
+    });
+  }
+}
+
+async function isGitRepository(directory: string): Promise<boolean> {
+  try {
+    await stat(join(directory, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Prepare both package-owned directories and atomically enforce permissions. */
+export async function prepareIsolatedAntigravityHome(
+  paths = getIsolatedAntigravityPaths(),
+  options: IsolatedAntigravityPreparationOptions = {},
+): Promise<IsolatedAntigravityPaths> {
+  const keychainDirectory = dirname(paths.keychainPath);
+  const libraryDirectory = dirname(keychainDirectory);
+  const isMacOS = (options.platform ?? process.platform) === "darwin";
+  await mkdir(paths.homeDir, { recursive: true, mode: 0o700 });
+  await mkdir(dirname(paths.settingsPath), { recursive: true, mode: 0o700 });
+  if (isMacOS) await mkdir(keychainDirectory, { recursive: true, mode: 0o700 });
+  await chmod(paths.homeDir, 0o700);
+  await chmod(dirname(paths.settingsPath), 0o700);
+  if (isMacOS) {
+    await chmod(libraryDirectory, 0o700);
+    await chmod(keychainDirectory, 0o700);
+  }
+  await Promise.all([
+    initializeConsultationWorkspace(paths),
+    mergeInspectionSettings(paths.settingsPath),
+    prepareIsolatedMacOSKeychain(paths, options),
+  ]);
+  return paths;
+}
+
+async function prepareIsolatedMacOSKeychain(
+  paths: IsolatedAntigravityPaths,
+  options: IsolatedAntigravityPreparationOptions,
+): Promise<void> {
+  if ((options.platform ?? process.platform) !== "darwin") return;
+  const existing = keychainInitializations.get(paths.keychainPath);
+  if (existing !== undefined) {
+    await existing;
+    return;
+  }
+  const runSecurityCommand = options.runSecurityCommand ?? runMacOSSecurityCommand;
+  const initialization = prepareIsolatedMacOSKeychainOnce(paths, runSecurityCommand).finally(() => {
+    keychainInitializations.delete(paths.keychainPath);
+  });
+  keychainInitializations.set(paths.keychainPath, initialization);
+  await initialization;
+}
+
+async function prepareIsolatedMacOSKeychainOnce(
+  paths: IsolatedAntigravityPaths,
+  runSecurityCommand: (args: readonly string[], homeDir: string) => Promise<void>,
+): Promise<void> {
+  const keychainDirectory = dirname(paths.keychainPath);
+  const privateKeychainPath = join(keychainDirectory, PRIVATE_KEYCHAIN_FILE_NAME);
+  await replaceLegacyKeychainEntry(paths.keychainPath, privateKeychainPath);
+  if (!(await pathExists(privateKeychainPath))) {
+    await runSecurityCommand(["create-keychain", "-p", "", privateKeychainPath], paths.homeDir);
+  }
+  if (!(await isSymlinkTo(paths.keychainPath, PRIVATE_KEYCHAIN_FILE_NAME))) {
+    await rm(paths.keychainPath, { force: true });
+    await symlink(PRIVATE_KEYCHAIN_FILE_NAME, paths.keychainPath);
+  }
+  // The private keychain has an empty password. Unlocking it with that known password is
+  // non-interactive and prevents a locked keychain from starting SecurityAgent.
+  await runSecurityCommand(["unlock-keychain", "-p", "", privateKeychainPath], paths.homeDir);
+  await chmod(privateKeychainPath, 0o600);
+}
+
+async function replaceLegacyKeychainEntry(
+  keychainPath: string,
+  privateKeychainPath: string,
+): Promise<void> {
+  const entry = await readFileEntry(keychainPath);
+  if (!entry) return;
+  if (entry.isSymbolicLink()) {
+    if (await isSymlinkTo(keychainPath, PRIVATE_KEYCHAIN_FILE_NAME)) return;
+    await rm(keychainPath, { force: true });
+    return;
+  }
+  if (keychainPath === privateKeychainPath) return;
+  await rm(keychainPath, { force: true });
+}
+
+async function isSymlinkTo(filePath: string, target: string): Promise<boolean> {
+  const entry = await readFileEntry(filePath);
+  if (!entry?.isSymbolicLink()) return false;
+  try {
+    return (await readlink(filePath)) === target;
+  } catch (error) {
+    if (isMissingFile(error)) return false;
+    throw error;
+  }
+}
+
+async function readFileEntry(
+  filePath: string,
+): Promise<Awaited<ReturnType<typeof lstat>> | undefined> {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (isMissingFile(error)) return undefined;
+    throw error;
+  }
+}
+
+async function runMacOSSecurityCommand(args: readonly string[], homeDir: string): Promise<void> {
+  try {
+    await execFileAsync(SECURITY_COMMAND, [...args], {
+      env: { HOME: homeDir },
+      maxBuffer: 64 * 1024,
+    });
+  } catch (error) {
+    throw new Error("Could not prepare the isolated Antigravity macOS keychain.", {
+      cause: error,
+    });
+  }
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (isMissingFile(error)) return false;
+    throw error;
+  }
+}
+
+/** Merge and atomically write the Inspection Permission Set. */
+export async function mergeInspectionSettings(settingsPath: string): Promise<void> {
+  const existing = await readSettingsObject(settingsPath);
+  const existingPermissions = isRecord(existing.permissions) ? existing.permissions : {};
+  const merged = {
+    ...existing,
+    allowNonWorkspaceAccess: INSPECTION_PERMISSION_SET.allowNonWorkspaceAccess,
+    permissions: {
+      ...existingPermissions,
+      allow: [...INSPECTION_PERMISSION_SET.permissions.allow],
+      deny: [...INSPECTION_PERMISSION_SET.permissions.deny],
+    },
+  };
+  await writeJsonAtomically(settingsPath, merged);
+}
+
+async function readSettingsObject(settingsPath: string): Promise<Record<string, unknown>> {
+  let content: string;
+  try {
+    content = await readFile(settingsPath, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) return {};
+    throw new Error("Could not read the isolated Antigravity settings.", { cause: error });
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(content);
+    if (!isRecord(parsed)) throw new Error("settings root is not an object");
+    return parsed;
+  } catch (error) {
+    throw new Error("The isolated Antigravity settings file is not valid JSON.", { cause: error });
+  }
+}
+
+/** Write JSON by replacing a same-directory temporary file. */
+export async function writeJsonAtomically(
+  filePath: string,
+  value: Record<string, unknown>,
+): Promise<void> {
+  const directory = dirname(filePath);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const temporaryPath = join(directory, `.${basename(filePath)}.${randomUUID()}.tmp`);
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(temporaryPath, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, filePath);
+  } catch (error) {
+    if (handle) await handle.close().catch(() => undefined);
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw new Error("Could not atomically write the isolated Antigravity settings.", {
+      cause: error,
+    });
+  }
+}
+
+/** Build the resolved command a user can run to authenticate Antigravity. */
+export function formatAntigravityLoginCommand(paths: IsolatedAntigravityPaths): string {
+  return [
+    `cd ${shellQuote(paths.consultationWorkspace)} &&`,
+    `HOME=${shellQuote(paths.homeDir)} AGY_CLI_DISABLE_AUTO_UPDATE=true agy`,
+  ].join("\n");
+}
+
+function shellQuote(value: string): string {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`")}"`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isMissingFile(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/src/agents/antigravity/models.ts

@@ -0,0 +1,15 @@
+/** Model choices that Antigravity can expose to a new Consultation. */
+export const CURATED_MODELS = Object.freeze([
+  "gemini-3.8-flash-low",
+  "gemini-3.8-flash-medium",
+  "gemini-3.8-flash-high",
+  "gemini-3.1-pro-high",
+] as const);
+
+/** A model in Antigravity's discovered catalogue. */
+export type CuratedModel = (typeof CURATED_MODELS)[number];
+
+/** Check whether an ID belongs to Antigravity's curated catalogue. */
+export function isCuratedModel(value: unknown): value is CuratedModel {
+  return typeof value === "string" && CURATED_MODELS.includes(value as CuratedModel);
+}

package/src/agents/antigravity/process/environment.ts

@@ -0,0 +1,33 @@
+/** Environment variables that are safe and useful for a non-interactive agy process. */
+export const APPROVED_ENVIRONMENT_KEYS = Object.freeze([
+  "PATH",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "LC_COLLATE",
+  "TERM",
+  "TERM_PROGRAM",
+  "COLORTERM",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "NO_COLOR",
+] as const);
+
+/** Build the restricted environment used by every Antigravity process. */
+export function buildAntigravityEnvironment(
+  homeDir: string,
+  source: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const environment: NodeJS.ProcessEnv = {};
+  for (const key of APPROVED_ENVIRONMENT_KEYS) {
+    const value = source[key];
+    if (value !== undefined) environment[key] = value;
+  }
+  environment.HOME = homeDir;
+  environment.AGY_CLI_DISABLE_AUTO_UPDATE = "true";
+  return environment;
+}