@mrclrchtr/supi-antigravity 6.4.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@mrclrchtr/supi-antigravity",
+  "version": "6.4.0",
+  "description": "Bounded Antigravity tasks with isolated workspace access and evidence",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-antigravity"
+  },
+  "homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-antigravity#readme",
+  "bugs": {
+    "url": "https://github.com/mrclrchtr/supi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "supi",
+    "antigravity",
+    "agent",
+    "web",
+    "workspace"
+  ],
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "scripts/live-probe.ts",
+    "README.md",
+    "CLAUDE.md",
+    "CONTEXT.md",
+    "docs/adr/*.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mrclrchtr/supi-test-utils": "workspace:*",
+    "@types/node": "25.9.5",
+    "vitest": "4.1.11"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-antigravity/assets/social-preview.png"
+  },
+  "exports": {
+    "./extension": "./src/extension.ts",
+    "./package.json": "./package.json"
+  }
+}

package/scripts/live-probe.ts

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdtemp, readdir, readFile, readlink, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { isWebToolName, isWorkspaceToolName } from "../src/activity.ts";
+import { discoverAntigravityAvailability } from "../src/availability.ts";
+import { ConversationHandleStore } from "../src/conversation/handles.ts";
+import { getIsolatedAntigravityPaths } from "../src/isolated-home.ts";
+import { runAntigravityConversation } from "../src/process/runner.ts";
+import { ANTIGRAVITY_ANSWER_SCHEMA } from "../src/structured-output.ts";
+import { isHttpUrl, isSafeWorkspacePath } from "../src/tool/antigravity_run/evidence.ts";
+import type { CuratedModel } from "../src/types.ts";
+
+const LIVE_ENVIRONMENT = "SUPI_ANTIGRAVITY_LIVE";
+const MODEL: CuratedModel = "gemini-3.8-flash-low";
+const CONTEXT_TOKEN = "supi-antigravity-context-token";
+
+async function main(): Promise<void> {
+  if (process.env[LIVE_ENVIRONMENT] !== "1") {
+    throw new Error(`Set ${LIVE_ENVIRONMENT}=1 to run the Antigravity live probe.`);
+  }
+  const availability = await discoverAntigravityAvailability();
+  if (availability.status !== "available" || !availability.catalogue.includes(MODEL)) {
+    throw new Error("Gemini 3.8 Flash Low is not available in the isolated Antigravity account.");
+  }
+
+  const paths = getIsolatedAntigravityPaths();
+  const handles = new ConversationHandleStore();
+  const first = await runAntigravityConversation({
+    paths,
+    cwd: paths.consultationWorkspace,
+    prompt: `Remember the exact token ${CONTEXT_TOKEN}. Name one current official Node.js documentation page about subprocess cancellation and cite it.`,
+    model: MODEL,
+    schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+  });
+  requireWebEvidence(first);
+  const record = handles.create({
+    rawAntigravityId: first.conversationId,
+    model: MODEL,
+    canonicalWorkingDirectory: paths.consultationWorkspace,
+    workspaceAccess: false,
+    cliVersion: availability.cliVersion,
+  });
+  const second = await runAntigravityConversation({
+    paths,
+    cwd: paths.consultationWorkspace,
+    prompt: `What exact context token did I give you? Answer in one sentence and include ${CONTEXT_TOKEN}.`,
+    model: MODEL,
+    conversationId: record.rawAntigravityId,
+    schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+  });
+  if (
+    second.conversationId !== record.rawAntigravityId ||
+    !second.answer.answer.includes(CONTEXT_TOKEN)
+  ) {
+    throw new Error("Antigravity follow-up did not retain the Conversation Handle context.");
+  }
+
+  const fixture = await realpath(await mkdtemp(join(tmpdir(), "supi-antigravity-live-")));
+  try {
+    await cp(join(import.meta.dirname, "../__tests__/fixtures/subprocess-cancellation"), fixture, {
+      recursive: true,
+    });
+    const before = await digestTree(fixture);
+    const workspace = await runAntigravityConversation({
+      paths,
+      cwd: fixture,
+      prompt:
+        "Inspect the TypeScript subprocess-cancellation fixture. Consult official Node.js documentation and explain the cancellation risk. Return relative file paths within the fixture and source URLs. Do not return absolute file paths.",
+      model: MODEL,
+      workspaceDirectory: fixture,
+      schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+    });
+    requireWebEvidence(workspace);
+    requireWorkspaceEvidence(workspace, fixture);
+    if (!workspace.successfulToolNames.some(isWorkspaceToolName)) {
+      throw new Error("The workspace probe did not observe workspace activity.");
+    }
+    const after = await digestTree(fixture);
+    if (before !== after) throw new Error("The live probe changed the fixture.");
+  } finally {
+    await rm(fixture, { recursive: true, force: true });
+  }
+}
+
+function requireWebEvidence(result: {
+  successfulToolNames: string[];
+  answer: { sources: unknown[] };
+}): void {
+  const web = result.successfulToolNames.some(isWebToolName);
+  if (!web || result.answer.sources.length === 0) {
+    throw new Error("The live probe did not observe web evidence.");
+  }
+  if (
+    !result.answer.sources.every(
+      (source) => isRecord(source) && typeof source.url === "string" && isHttpUrl(source.url),
+    )
+  ) {
+    throw new Error("The live probe returned an invalid source URL.");
+  }
+}
+
+function requireWorkspaceEvidence(
+  result: { answer: { workspaceEvidence: unknown[] } },
+  workspace: string,
+): void {
+  if (
+    result.answer.workspaceEvidence.length === 0 ||
+    !result.answer.workspaceEvidence.every(
+      (item) =>
+        isRecord(item) &&
+        typeof item.path === "string" &&
+        isSafeWorkspacePath(item.path, workspace),
+    )
+  ) {
+    throw new Error("The live probe did not return valid workspace evidence.");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function digestTree(directory: string): Promise<string> {
+  const hash = createHash("sha256");
+  await digestDirectory(directory, directory, hash);
+  return hash.digest("hex");
+}
+
+async function digestDirectory(
+  directory: string,
+  root: string,
+  hash: ReturnType<typeof createHash>,
+): Promise<void> {
+  const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+    left.name.localeCompare(right.name),
+  );
+  for (const entry of entries) {
+    const file = join(directory, entry.name);
+    hash.update(relative(root, file));
+    if (entry.isDirectory()) {
+      hash.update("directory");
+      await digestDirectory(file, root, hash);
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      hash.update("link");
+      hash.update(await readlink(file));
+      continue;
+    }
+    if (entry.isFile()) {
+      hash.update("file");
+      hash.update(await readFile(file));
+      continue;
+    }
+    const info = await lstat(file);
+    hash.update(`${info.mode}:${info.size}`);
+  }
+}
+
+await main();

package/src/activity.ts

@@ -0,0 +1,22 @@
+import { normalizeToolName } from "./process/event-values.ts";
+
+/** Return whether a successful Antigravity tool name represents web activity. */
+export function isWebToolName(name: string): boolean {
+  const normalized = normalizeToolName(name);
+  return ["search_web", "read_url_content", "read_url", "web_search"].includes(normalized);
+}
+
+/** Return whether a successful Antigravity tool name represents workspace activity. */
+export function isWorkspaceToolName(name: string): boolean {
+  const normalized = normalizeToolName(name);
+  return (
+    normalized.includes("file") ||
+    normalized.includes("directory") ||
+    normalized.includes("code_search") ||
+    normalized.includes("search_code") ||
+    normalized.includes("grep") ||
+    normalized.includes("find") ||
+    normalized.includes("glob") ||
+    ["list_files", "list_dir", "read_file"].includes(normalized)
+  );
+}

package/src/availability.ts

@@ -0,0 +1,231 @@
+import {
+  formatAntigravityLoginCommand,
+  getIsolatedAntigravityPaths,
+  type IsolatedAntigravityPaths,
+} from "./isolated-home.ts";
+import type { AntigravityProbeResult } from "./process/runner.ts";
+import { AntigravityProcessError, runAntigravityProbe } from "./process/runner.ts";
+import { CURATED_MODELS, type CuratedModel, isCuratedModel } from "./types.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/catalogue.ts

@@ -0,0 +1,21 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { TSchema } from "typebox";
+import type { CuratedModel } from "./types.ts";
+
+/** Build the provider-facing enum from one discovered Model Catalogue. */
+export function buildModelCatalogueEnum(catalogue: readonly CuratedModel[]): TSchema {
+  if (catalogue.length === 0) {
+    throw new Error("Cannot build an Antigravity model enum from an empty catalogue.");
+  }
+  return StringEnum([...catalogue] as [string, ...string[]], {
+    description: "Curated Antigravity model available to the current account.",
+  });
+}
+
+/** Check runtime model input against the same discovered catalogue. */
+export function isAvailableCuratedModel(
+  value: unknown,
+  catalogue: readonly CuratedModel[],
+): value is CuratedModel {
+  return typeof value === "string" && catalogue.includes(value as CuratedModel);
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+
+/** The persisted SuPi configuration section owned by this package. */
+export const ANTIGRAVITY_CONFIG_SECTION = "antigravity";
+
+/** Configuration for the Antigravity Run tool. */
+export interface AntigravityConfig extends Record<string, unknown> {
+  /** Enable availability discovery and the antigravity_run tool. */
+  agentToolEnabled: boolean;
+}
+
+/** Default Antigravity configuration. */
+export const ANTIGRAVITY_DEFAULTS: AntigravityConfig = Object.freeze({
+  agentToolEnabled: true,
+});
+
+/** Load the effective Antigravity configuration for a workspace. */
+export function loadAntigravityConfig(cwd: string, homeDir?: string): AntigravityConfig {
+  const raw = loadSupiConfig(ANTIGRAVITY_CONFIG_SECTION, cwd, ANTIGRAVITY_DEFAULTS, { homeDir });
+  return {
+    agentToolEnabled:
+      typeof raw.agentToolEnabled === "boolean"
+        ? raw.agentToolEnabled
+        : ANTIGRAVITY_DEFAULTS.agentToolEnabled,
+  };
+}