@mrclrchtr/supi-antigravity 6.4.0

package/src/process/subprocess.ts

@@ -0,0 +1,278 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { buildAntigravityEnvironment } from "./environment.ts";
+import {
+  BoundedLineParser,
+  BoundedStderrCapture,
+  MAX_STDOUT_BYTES,
+  MAX_STDOUT_LINE_BYTES,
+} from "./ndjson.ts";
+
+const COMMAND = "agy";
+const TERMINATION_GRACE_MS = 500;
+
+/** Safe outcomes from a bounded non-stream Antigravity probe. */
+export interface AntigravityProbeResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Error raised for a failed Antigravity process or protocol. */
+export class AntigravityProcessError extends Error {
+  readonly kind: "missing" | "timeout" | "cancelled" | "stream" | "process" | "protocol";
+  readonly exitCode: number | null | undefined;
+  /** Bounded stderr retained for an in-memory caller, never put in result details. */
+  readonly stderr: string | undefined;
+
+  constructor(
+    message: string,
+    kind: AntigravityProcessError["kind"],
+    options: { cause?: unknown; exitCode?: number | null; stderr?: string } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "AntigravityProcessError";
+    this.kind = kind;
+    this.exitCode = options.exitCode;
+    this.stderr = options.stderr;
+  }
+}
+
+/** Options for one directly spawned, bounded agy process. */
+export interface BoundedChildProcessOptions {
+  args: string[];
+  cwd: string;
+  homeDir: string;
+  prompt?: string;
+  signal?: AbortSignal;
+  timeoutMs: number;
+  onLine: (line: string) => void;
+  maxStdoutBytes?: number;
+  allowNonZero?: boolean;
+  onProcessStart?: () => void;
+}
+
+/** Spawn agy without a shell and apply stream, timeout, and process-group limits. */
+export function runBoundedChildProcess(
+  options: BoundedChildProcessOptions,
+): Promise<AntigravityProbeResult> {
+  if (process.platform !== "darwin" && process.platform !== "linux") {
+    return Promise.reject(
+      new AntigravityProcessError("Antigravity is supported on macOS and Linux only.", "process"),
+    );
+  }
+  if (options.signal?.aborted) {
+    return Promise.reject(
+      new AntigravityProcessError("Antigravity run was canceled.", "cancelled"),
+    );
+  }
+
+  return new Promise((resolve, reject) => {
+    const parser = new BoundedLineParser({
+      maxLineBytes: MAX_STDOUT_LINE_BYTES,
+      maxTotalBytes: options.maxStdoutBytes ?? MAX_STDOUT_BYTES,
+    });
+    const stderr = new BoundedStderrCapture();
+    let child: ChildProcess | undefined;
+    let closed = false;
+    let settled = false;
+    let failure: Error | undefined;
+    let closeResolve: (() => void) | undefined;
+    const closePromise = new Promise<void>((resolveClose) => {
+      closeResolve = resolveClose;
+    });
+
+    const finishReject = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    const terminateAndReject = (error: Error): void => {
+      if (settled || failure) return;
+      failure = error;
+      void terminateProcess(child, closePromise, () => closed).then(() => {
+        finishReject(error);
+      });
+    };
+
+    const timer = setTimeout(() => {
+      terminateAndReject(new AntigravityProcessError("Antigravity process timed out.", "timeout"));
+    }, options.timeoutMs);
+    const onAbort = (): void => {
+      terminateAndReject(new AntigravityProcessError("Antigravity run was canceled.", "cancelled"));
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      child = spawn(COMMAND, options.args, {
+        cwd: options.cwd,
+        env: buildAntigravityEnvironment(options.homeDir),
+        detached: true,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      terminateAndReject(classifySpawnError(error));
+      return;
+    }
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      try {
+        parser.feed(toBuffer(chunk), options.onLine);
+      } catch (error) {
+        terminateAndReject(
+          error instanceof Error
+            ? new AntigravityProcessError(error.message, "stream", { cause: error })
+            : new AntigravityProcessError("Antigravity stdout exceeded its limits.", "stream"),
+        );
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => stderr.feed(toBuffer(chunk)));
+    child.stdin?.on("error", (error) => terminateAndReject(classifySpawnError(error)));
+    child.on("error", (error) => terminateAndReject(classifySpawnError(error)));
+    child.on("close", (exitCode, signal) => {
+      handleChildClose(exitCode, signal, {
+        parser,
+        options,
+        stderr,
+        setClosed: () => {
+          closed = true;
+          closeResolve?.();
+        },
+        clearTimer: () => clearTimeout(timer),
+        removeAbortListener: () => options.signal?.removeEventListener("abort", onAbort),
+        getFailure: () => failure,
+        isSettled: () => settled,
+        resolve: (result) => {
+          settled = true;
+          resolve(result);
+        },
+        fail: terminateAndReject,
+      });
+    });
+
+    try {
+      options.onProcessStart?.();
+      if (options.prompt !== undefined) {
+        const userEvent = JSON.stringify({
+          event: "user",
+          message: { role: "user", content: options.prompt },
+        });
+        child.stdin?.end(`${userEvent}\n`);
+      } else {
+        child.stdin?.end();
+      }
+    } catch (error) {
+      terminateAndReject(classifySpawnError(error));
+    }
+  });
+}
+
+interface ChildCloseState {
+  parser: BoundedLineParser;
+  options: BoundedChildProcessOptions;
+  stderr: BoundedStderrCapture;
+  setClosed: () => void;
+  clearTimer: () => void;
+  removeAbortListener: () => void;
+  getFailure: () => Error | undefined;
+  isSettled: () => boolean;
+  resolve: (result: AntigravityProbeResult) => void;
+  fail: (error: Error) => void;
+}
+
+function handleChildClose(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  state: ChildCloseState,
+): void {
+  state.setClosed();
+  state.clearTimer();
+  state.removeAbortListener();
+  if (state.getFailure()) return;
+  try {
+    state.parser.finish(state.options.onLine);
+    ensureSuccessfulExit(exitCode, signal, state.options.allowNonZero, state.stderr.text());
+    if (!state.isSettled()) {
+      state.resolve({ exitCode, signal, stdout: "", stderr: state.stderr.text() });
+    }
+  } catch (error) {
+    state.fail(toProtocolOrProcessError(error));
+  }
+}
+
+function ensureSuccessfulExit(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  allowNonZero: boolean | undefined,
+  stderr: string,
+): void {
+  if (allowNonZero || (exitCode === 0 && !signal)) return;
+  throw new AntigravityProcessError(processFailureMessage(exitCode, signal), "process", {
+    exitCode,
+    stderr,
+  });
+}
+
+function toProtocolOrProcessError(error: unknown): AntigravityProcessError {
+  if (error instanceof AntigravityProcessError) return error;
+  return new AntigravityProcessError("Antigravity returned an invalid stream.", "protocol", {
+    cause: error,
+  });
+}
+
+async function terminateProcess(
+  child: ChildProcess | undefined,
+  closePromise: Promise<void>,
+  isClosed: () => boolean,
+): Promise<void> {
+  if (!child || isClosed()) return;
+  sendProcessGroupSignal(child, "SIGTERM");
+  await waitForClose(closePromise, TERMINATION_GRACE_MS);
+  if (!isClosed()) {
+    sendProcessGroupSignal(child, "SIGKILL");
+    await waitForClose(closePromise, TERMINATION_GRACE_MS);
+  }
+}
+
+function sendProcessGroupSignal(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (typeof child.pid !== "number") return;
+  try {
+    process.kill(-child.pid, signal);
+    return;
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // The process may have exited between the two kill attempts.
+    }
+  }
+}
+
+async function waitForClose(closePromise: Promise<void>, timeoutMs: number): Promise<void> {
+  await Promise.race([
+    closePromise,
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
+function toBuffer(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+}
+
+function classifySpawnError(error: unknown): AntigravityProcessError {
+  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  return new AntigravityProcessError(
+    code === "ENOENT" ? "Antigravity CLI was not found." : "Could not start Antigravity CLI.",
+    code === "ENOENT" ? "missing" : "process",
+    { cause: error },
+  );
+}
+
+function processFailureMessage(exitCode: number | null, signal: NodeJS.Signals | null): string {
+  if (signal) return `Antigravity process stopped with ${signal}.`;
+  return `Antigravity process exited with code ${String(exitCode)}.`;
+}

package/src/process/usage.ts

@@ -0,0 +1,50 @@
+import type { AntigravityUsage } from "../types.ts";
+import { isRecord } from "./event-values.ts";
+
+/** Read bounded token usage from one normalized Antigravity event. */
+export function readUsage(event: Record<string, unknown>): AntigravityUsage | undefined {
+  const value = isRecord(event.usage)
+    ? event.usage
+    : isRecord(event.token_usage)
+      ? event.token_usage
+      : isRecord(event.tokenUsage)
+        ? event.tokenUsage
+        : undefined;
+  if (!value) return undefined;
+  const inputTokens = finiteToken(value.input_tokens ?? value.inputTokens ?? value.prompt_tokens);
+  const outputTokens = finiteToken(
+    value.output_tokens ?? value.outputTokens ?? value.completion_tokens,
+  );
+  const totalTokens = finiteToken(value.total_tokens ?? value.totalTokens ?? value.total);
+  if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined)
+    return undefined;
+  return {
+    ...(inputTokens === undefined ? {} : { inputTokens }),
+    ...(outputTokens === undefined ? {} : { outputTokens }),
+    ...(totalTokens === undefined ? {} : { totalTokens }),
+  };
+}
+
+/** Merge usage fields without retaining any provider event payload. */
+export function mergeUsage(
+  left: AntigravityUsage | undefined,
+  right: AntigravityUsage | undefined,
+): AntigravityUsage | undefined {
+  if (!left) return right;
+  if (!right) return left;
+  return {
+    ...(left.inputTokens === undefined && right.inputTokens === undefined
+      ? {}
+      : { inputTokens: right.inputTokens ?? left.inputTokens }),
+    ...(left.outputTokens === undefined && right.outputTokens === undefined
+      ? {}
+      : { outputTokens: right.outputTokens ?? left.outputTokens }),
+    ...(left.totalTokens === undefined && right.totalTokens === undefined
+      ? {}
+      : { totalTokens: right.totalTokens ?? left.totalTokens }),
+  };
+}
+
+function finiteToken(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}

package/src/runtime.ts

@@ -0,0 +1,118 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AntigravityAvailability, discoverAntigravityAvailability } from "./availability.ts";
+import { loadAntigravityConfig } from "./config.ts";
+import { ConversationHandleStore } from "./conversation/handles.ts";
+import { getIsolatedAntigravityPaths, type IsolatedAntigravityPaths } from "./isolated-home.ts";
+import { registerAntigravityRunTool } from "./tool/antigravity_run/register.ts";
+import { ANTIGRAVITY_RUN_TOOL_NAME } from "./tool/antigravity_run/spec.ts";
+import type { CuratedModel } from "./types.ts";
+
+/** Context needed to show an availability warning. */
+export type AntigravityRefreshContext = { ui: Pick<ExtensionContext["ui"], "notify"> } | undefined;
+
+/** Session runtime for immutable availability and Conversation Handle state. */
+export class AntigravityRuntime {
+  readonly paths: IsolatedAntigravityPaths;
+  readonly handles = new ConversationHandleStore();
+  #pi: ExtensionAPI;
+  #homeDir: string | undefined;
+  #discover: typeof discoverAntigravityAvailability;
+  #availability: AntigravityAvailability | undefined;
+  #refreshGeneration = 0;
+  #refreshAbort: AbortController | undefined;
+  #toolRegistered = false;
+
+  constructor(options: {
+    pi: ExtensionAPI;
+    paths?: IsolatedAntigravityPaths;
+    homeDir?: string;
+    discover?: typeof discoverAntigravityAvailability;
+  }) {
+    this.#pi = options.pi;
+    this.paths = options.paths ?? getIsolatedAntigravityPaths();
+    this.#homeDir = options.homeDir;
+    this.#discover = options.discover ?? discoverAntigravityAvailability;
+  }
+
+  /** The immutable discovery result, if session discovery has completed. */
+  get availability(): AntigravityAvailability | undefined {
+    return this.#availability;
+  }
+
+  /** Rebuild handles from the current PI branch. */
+  rebuildHandles(branch: readonly unknown[]): void {
+    this.handles.rebuild(branch);
+  }
+
+  /** Discover or reuse availability and synchronize the active tool. */
+  async refresh(cwd: string, context?: AntigravityRefreshContext): Promise<void> {
+    const generation = ++this.#refreshGeneration;
+    this.#refreshAbort?.abort();
+    const abortController = new AbortController();
+    this.#refreshAbort = abortController;
+    const config = loadAntigravityConfig(cwd, this.#homeDir);
+    if (!config.agentToolEnabled) {
+      this.#deactivateTool();
+      return;
+    }
+
+    let availability = this.#availability;
+    if (!availability) {
+      try {
+        availability = await this.#discover({
+          paths: this.paths,
+          signal: abortController.signal,
+        });
+      } catch {
+        availability = {
+          status: "unavailable",
+          reason: "discovery",
+          warning:
+            "Antigravity availability discovery failed. Check the installation, then reload PI.",
+        };
+      }
+    }
+    if (generation !== this.#refreshGeneration || abortController.signal.aborted) return;
+    this.#availability = availability;
+    if (availability.status === "available") {
+      this.#activateTool(availability.catalogue, availability.cliVersion);
+      return;
+    }
+    this.#deactivateTool();
+    context?.ui.notify(availability.warning, "warning");
+  }
+
+  /** Stop in-flight discovery and clear session-local state. */
+  async shutdown(): Promise<void> {
+    this.#refreshGeneration += 1;
+    this.#refreshAbort?.abort();
+    this.#refreshAbort = undefined;
+    this.#deactivateTool();
+    this.handles.clear();
+    await Promise.resolve();
+  }
+
+  #activateTool(catalogue: readonly CuratedModel[], cliVersion: string): void {
+    if (!this.#toolRegistered) {
+      registerAntigravityRunTool({
+        pi: this.#pi,
+        paths: this.paths,
+        catalogue,
+        cliVersion,
+        handles: this.handles,
+      });
+      this.#toolRegistered = true;
+    }
+    const activeTools = this.#pi.getActiveTools();
+    if (!activeTools.includes(ANTIGRAVITY_RUN_TOOL_NAME)) {
+      this.#pi.setActiveTools([...activeTools, ANTIGRAVITY_RUN_TOOL_NAME]);
+    }
+  }
+
+  #deactivateTool(): void {
+    const activeTools = this.#pi.getActiveTools();
+    if (activeTools.includes(ANTIGRAVITY_RUN_TOOL_NAME)) {
+      this.#pi.setActiveTools(activeTools.filter((name) => name !== ANTIGRAVITY_RUN_TOOL_NAME));
+    }
+  }
+}

package/src/settings.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
+import { ANTIGRAVITY_CONFIG_SECTION, ANTIGRAVITY_DEFAULTS } from "./config.ts";
+import type { AntigravityRuntime } from "./runtime.ts";
+
+/** Register the Antigravity setting with an awaited availability refresh. */
+export function registerAntigravitySettings(
+  pi: ExtensionAPI,
+  runtime: AntigravityRuntime,
+  homeDir?: string,
+): void {
+  const fixedSettings = defineConfigSettings({
+    id: ANTIGRAVITY_CONFIG_SECTION,
+    label: "Antigravity",
+    section: ANTIGRAVITY_CONFIG_SECTION,
+    defaults: ANTIGRAVITY_DEFAULTS,
+    fields: [
+      {
+        kind: "boolean" as const,
+        key: "agentToolEnabled",
+        label: "Antigravity Run tool",
+        description: "Enable antigravity_run and its availability checks.",
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+
+  registerSettings(pi, {
+    ...fixedSettings,
+    apply: async (request) => {
+      const result = await fixedSettings.apply(request);
+      if (request.fieldKey === "agentToolEnabled") {
+        await runtime.refresh(request.cwd, request.ctx ? { ui: request.ctx.ui } : undefined);
+      }
+      return result;
+    },
+  });
+}

package/src/structured-output.ts

@@ -0,0 +1,58 @@
+import { type TSchema, Type } from "typebox";
+import { Value } from "typebox/value";
+import type { AntigravityAnswer } from "./types.ts";
+
+/** Maximum length of Antigravity's final answer text. */
+export const MAX_ANSWER_CHARS = 16_000;
+/** Maximum source references accepted from one answer. */
+export const MAX_SOURCES = 8;
+/** Maximum workspace references accepted from one answer. */
+export const MAX_WORKSPACE_EVIDENCE = 8;
+/** Maximum source title length. */
+export const MAX_SOURCE_TITLE_CHARS = 240;
+/** Maximum source URL length. */
+export const MAX_SOURCE_URL_CHARS = 1_024;
+/** Maximum workspace evidence path length. */
+export const MAX_WORKSPACE_PATH_CHARS = 512;
+/** Maximum workspace evidence summary length. */
+export const MAX_EVIDENCE_SUMMARY_CHARS = 1_000;
+
+/** JSON Schema passed to agy for every paid Antigravity Run. */
+export const ANTIGRAVITY_ANSWER_SCHEMA: TSchema = Type.Object(
+  {
+    answer: Type.String({
+      minLength: 1,
+      maxLength: MAX_ANSWER_CHARS,
+      description: "The answer to the user's request.",
+    }),
+    sources: Type.Array(
+      Type.Object(
+        {
+          title: Type.String({ minLength: 1, maxLength: MAX_SOURCE_TITLE_CHARS }),
+          url: Type.String({ minLength: 1, maxLength: MAX_SOURCE_URL_CHARS }),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: MAX_SOURCES },
+    ),
+    workspaceEvidence: Type.Array(
+      Type.Object(
+        {
+          path: Type.String({ minLength: 1, maxLength: MAX_WORKSPACE_PATH_CHARS }),
+          summary: Type.String({ minLength: 1, maxLength: MAX_EVIDENCE_SUMMARY_CHARS }),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: MAX_WORKSPACE_EVIDENCE },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** Validate and return the exact structured answer shape. */
+export function validateAntigravityAnswer(value: unknown): AntigravityAnswer {
+  if (!Value.Check(ANTIGRAVITY_ANSWER_SCHEMA, value)) {
+    throw new Error("Antigravity returned invalid structured output.");
+  }
+  return value as AntigravityAnswer;
+}