@mrclrchtr/supi-antigravity 6.4.0

package/src/process/hooks.ts

@@ -0,0 +1,219 @@
+import type { IsolatedAntigravityPaths } from "../isolated-home.ts";
+import { PROJECT_HOOK_PROBE_ARGUMENTS, runAntigravityProbe } from "./runner.ts";
+
+/** Reduced state of project-local Antigravity hooks. */
+export type ProjectHookState = "active" | "inactive" | "unknown";
+
+/** Result of the bounded `/hooks` inspection. */
+export interface ProjectHookProbeResult {
+  state: ProjectHookState;
+  warning?: string;
+}
+
+/** Inspect project-local hooks without retaining commands or hook configuration. */
+export async function probeProjectHooks(options: {
+  paths: IsolatedAntigravityPaths;
+  cwd: string;
+  signal?: AbortSignal;
+  onProcessStart?: () => void;
+}): Promise<ProjectHookProbeResult> {
+  try {
+    const result = await runAntigravityProbe({
+      paths: options.paths,
+      cwd: options.cwd,
+      args: [...PROJECT_HOOK_PROBE_ARGUMENTS],
+      signal: options.signal,
+      timeoutMs: 15_000,
+      onProcessStart: options.onProcessStart,
+    });
+    return classifyHookOutput(result.stdout, result.exitCode);
+  } catch {
+    return unknownHookResult();
+  }
+}
+
+/** Classify bounded JSON output from the Antigravity hook command. */
+export function classifyHookOutput(
+  output: string,
+  exitCode: number | null,
+): ProjectHookProbeResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(output);
+    if (typeof parsed === "string") parsed = JSON.parse(parsed);
+  } catch {
+    return unknownHookResult();
+  }
+  const observation = inspectHookValue(parsed, { scope: "unknown", insideHookValue: false }, 0);
+  if (observation.active) return activeHookResult();
+  if (observation.inactive && exitCode === 0) return { state: "inactive" };
+  return unknownHookResult();
+}
+
+type HookScope = "project" | "global" | "unknown";
+
+interface HookContext {
+  scope: HookScope;
+  insideHookValue: boolean;
+}
+
+function inspectHookValue(
+  value: unknown,
+  context: HookContext,
+  depth: number,
+): { active: boolean; inactive: boolean } {
+  if (depth > 8 || value === null || typeof value !== "object") {
+    return { active: false, inactive: false };
+  }
+  if (Array.isArray(value)) return inspectHookArray(value, context, depth);
+  if (!isRecord(value)) return { active: false, inactive: false };
+  return inspectHookObject(value, context, depth);
+}
+
+function inspectHookArray(
+  value: unknown[],
+  context: HookContext,
+  depth: number,
+): { active: boolean; inactive: boolean } {
+  const itemScopes = value.map(scopeOfValue);
+  if (
+    context.insideHookValue &&
+    value.length > 0 &&
+    itemScopes.every((scope) => scope === "global")
+  ) {
+    return { active: false, inactive: true };
+  }
+  const result = value.reduce<{ active: boolean; inactive: boolean }>(
+    (current, item) => mergeHookObservation(current, inspectHookValue(item, context, depth + 1)),
+    { active: false, inactive: false },
+  );
+  if (result.active || result.inactive || !context.insideHookValue) return result;
+  if (value.length === 0 || context.scope === "global") {
+    return { active: false, inactive: true };
+  }
+  return { active: true, inactive: false };
+}
+
+function inspectHookObject(
+  value: Record<string, unknown>,
+  context: HookContext,
+  depth: number,
+): { active: boolean; inactive: boolean } {
+  const objectScope = scopeFromObject(value, context.scope);
+  const objectContext = { ...context, scope: objectScope };
+  return Object.entries(value).reduce<{ active: boolean; inactive: boolean }>(
+    (result, [key, child]) =>
+      mergeHookObservation(result, inspectHookProperty(key, child, objectContext, depth)),
+    { active: false, inactive: false },
+  );
+}
+
+function inspectHookProperty(
+  key: string,
+  child: unknown,
+  context: HookContext,
+  depth: number,
+): { active: boolean; inactive: boolean } {
+  const normalizedKey = key.toLowerCase().replace(/[-_]/g, "");
+  const childContext: HookContext = {
+    scope: scopeFromKey(normalizedKey, context.scope),
+    insideHookValue:
+      context.insideHookValue || normalizedKey.includes("hook") || normalizedKey === "projecthooks",
+  };
+  if (childContext.insideHookValue && typeof child === "boolean") {
+    return booleanHookState(normalizedKey, child, childContext.scope);
+  }
+  if (childContext.insideHookValue && typeof child === "string") {
+    return stringHookState(child, childContext.scope);
+  }
+  if (typeof child === "string" && ["result", "output", "data", "value"].includes(normalizedKey)) {
+    return inspectNestedJson(child, childContext, depth);
+  }
+  return inspectHookValue(child, childContext, depth + 1);
+}
+
+function inspectNestedJson(
+  value: string,
+  context: HookContext,
+  depth: number,
+): { active: boolean; inactive: boolean } {
+  try {
+    return inspectHookValue(JSON.parse(value), context, depth + 1);
+  } catch {
+    return { active: false, inactive: false };
+  }
+}
+
+function scopeOfValue(value: unknown): HookScope | undefined {
+  if (!isRecord(value)) return scopeFromValue(value);
+  return scopeFromObject(value, "unknown");
+}
+
+function scopeFromObject(value: Record<string, unknown>, fallback: HookScope): HookScope {
+  for (const key of ["scope", "source", "location"]) {
+    const scope = scopeFromValue(value[key]);
+    if (scope) return scope;
+  }
+  return fallback;
+}
+
+function scopeFromKey(key: string, fallback: HookScope): HookScope {
+  if (key.includes("global")) return "global";
+  if (key.includes("project") || key.includes("local")) return "project";
+  return fallback;
+}
+
+function scopeFromValue(value: unknown): HookScope | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.toLowerCase();
+  if (normalized.includes("global")) return "global";
+  if (normalized.includes("project") || normalized.includes("local")) return "project";
+  return undefined;
+}
+
+function booleanHookState(
+  key: string,
+  value: boolean,
+  scope: HookScope,
+): { active: boolean; inactive: boolean } {
+  if (!["active", "enabled", "loaded", "running"].includes(key)) {
+    return { active: false, inactive: false };
+  }
+  return scope === "global"
+    ? { active: false, inactive: !value }
+    : { active: value, inactive: !value };
+}
+
+function stringHookState(value: string, scope: HookScope): { active: boolean; inactive: boolean } {
+  const normalized = value.toLowerCase();
+  const active = ["active", "enabled", "running", "loaded"].includes(normalized);
+  const inactive = ["inactive", "disabled", "none", "notfound"].includes(normalized);
+  return scope === "global" ? { active: false, inactive } : { active, inactive };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function mergeHookObservation(
+  left: { active: boolean; inactive: boolean },
+  right: { active: boolean; inactive: boolean },
+): { active: boolean; inactive: boolean } {
+  return { active: left.active || right.active, inactive: left.inactive || right.inactive };
+}
+
+function activeHookResult(): ProjectHookProbeResult {
+  return {
+    state: "active",
+    warning:
+      "Project-local Antigravity hooks are active. They can run commands, read the Antigravity transcript, and cause side effects outside the Inspection Permission Set.",
+  };
+}
+
+function unknownHookResult(): ProjectHookProbeResult {
+  return {
+    state: "unknown",
+    warning:
+      "Project-local Antigravity hook state could not be determined. Hooks may run commands, read the Antigravity transcript, and cause side effects outside the Inspection Permission Set.",
+  };
+}

package/src/process/ndjson.ts

@@ -0,0 +1,120 @@
+/** Limits for streamed Antigravity output. */
+export const MAX_STDOUT_LINE_BYTES = 128 * 1024;
+export const MAX_STDOUT_BYTES = 5 * 1024 * 1024;
+export const MAX_STREAM_EVENTS = 512;
+export const MAX_RETAINED_STDERR_BYTES = 8 * 1024;
+
+/** Error raised when a process stream exceeds a package-owned bound. */
+export class StreamLimitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StreamLimitError";
+  }
+}
+
+/**
+ * Incrementally parses newline-delimited text without buffering an oversized line.
+ * The callback runs as soon as each complete line arrives.
+ */
+export class BoundedLineParser {
+  readonly #maxLineBytes: number;
+  readonly #maxTotalBytes: number;
+  #lineParts: Buffer[] = [];
+  #lineBytes = 0;
+  #totalBytes = 0;
+
+  constructor(
+    options: {
+      maxLineBytes?: number;
+      maxTotalBytes?: number;
+    } = {},
+  ) {
+    this.#maxLineBytes = options.maxLineBytes ?? MAX_STDOUT_LINE_BYTES;
+    this.#maxTotalBytes = options.maxTotalBytes ?? MAX_STDOUT_BYTES;
+  }
+
+  get totalBytes(): number {
+    return this.#totalBytes;
+  }
+
+  feed(chunk: Uint8Array, onLine: (line: string) => void): void {
+    this.#totalBytes += chunk.byteLength;
+    if (this.#totalBytes > this.#maxTotalBytes) {
+      throw new StreamLimitError("Antigravity stdout exceeded its byte limit.");
+    }
+
+    let start = 0;
+    for (let index = 0; index < chunk.byteLength; index += 1) {
+      if (chunk[index] !== 10) continue;
+      this.#append(chunk.subarray(start, index));
+      onLine(this.#takeLine());
+      start = index + 1;
+    }
+    this.#append(chunk.subarray(start));
+  }
+
+  finish(onLine: (line: string) => void): void {
+    if (this.#lineBytes === 0) return;
+    onLine(this.#takeLine());
+  }
+
+  #append(part: Uint8Array): void {
+    if (part.byteLength === 0) return;
+    this.#lineBytes += part.byteLength;
+    if (this.#lineBytes > this.#maxLineBytes) {
+      throw new StreamLimitError("An Antigravity stdout line exceeded its byte limit.");
+    }
+    this.#lineParts.push(Buffer.from(part));
+  }
+
+  #takeLine(): string {
+    const line = Buffer.concat(this.#lineParts, this.#lineBytes).toString("utf8");
+    this.#lineParts = [];
+    this.#lineBytes = 0;
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+  }
+}
+
+/** A bounded stderr collector used only to explain process failures. */
+export class BoundedStderrCapture {
+  readonly #maxBytes: number;
+  #parts: Buffer[] = [];
+  #bytes = 0;
+  #truncated = false;
+
+  constructor(maxBytes = MAX_RETAINED_STDERR_BYTES) {
+    this.#maxBytes = maxBytes;
+  }
+
+  feed(chunk: Uint8Array): void {
+    if (this.#bytes >= this.#maxBytes) {
+      this.#truncated = true;
+      return;
+    }
+    const remaining = this.#maxBytes - this.#bytes;
+    const part = Buffer.from(chunk.subarray(0, remaining));
+    this.#parts.push(part);
+    this.#bytes += part.byteLength;
+    if (part.byteLength < chunk.byteLength) this.#truncated = true;
+  }
+
+  text(): string {
+    const value = Buffer.concat(this.#parts).toString("utf8").trim();
+    return this.#truncated ? `${value}\n[stderr truncated]`.trim() : value;
+  }
+}
+
+/** Parse one bounded NDJSON line and reject malformed JSON. */
+export function parseNdjsonLine(line: string): Record<string, unknown> | undefined {
+  if (!line.trim()) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch (error) {
+    throw new Error("Antigravity returned malformed NDJSON.", { cause: error });
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("Antigravity returned a non-object NDJSON event.");
+  }
+  return parsed as Record<string, unknown>;
+}

package/src/process/protocol.ts

@@ -0,0 +1,69 @@
+import { ERROR_STATES, eventType, isRecord, SUCCESS_STATES, safeString } from "./event-values.ts";
+
+/** Adapt an agy event envelope to the small event vocabulary used by the reducer. */
+export function normalizeProtocolEvent(event: Record<string, unknown>): Record<string, unknown> {
+  const envelopeType = eventType(event);
+  if (envelopeType === "result") return normalizeResultEnvelope(event);
+  if (envelopeType === "step_update") return normalizeStepUpdateEnvelope(event);
+  return event;
+}
+
+function normalizeResultEnvelope(event: Record<string, unknown>): Record<string, unknown> {
+  return isRecord(event.result)
+    ? { ...event, ...event.result, type: "result" }
+    : { ...event, type: "result" };
+}
+
+function normalizeStepUpdateEnvelope(event: Record<string, unknown>): Record<string, unknown> {
+  if (!isRecord(event.step_update)) return event;
+  const update = event.step_update;
+  const stepType = lowerBoundedText(update.step_type ?? update.stepType);
+  const toolShaped =
+    update.tool_name !== undefined ||
+    update.toolName !== undefined ||
+    isRecord(update.tool_info) ||
+    isRecord(update.toolInfo);
+  if (stepType !== "tool" && !(stepType === "" && toolShaped)) {
+    return { ...update, type: stepType === "agent_response" ? "assistant" : "step_update" };
+  }
+  return normalizeToolStep(update);
+}
+
+function normalizeToolStep(update: Record<string, unknown>): Record<string, unknown> {
+  const state = lowerBoundedText(update.state);
+  const toolInfo = getToolInfo(update);
+  const parameters = toolInfo?.parameters ?? toolInfo?.input;
+  const toolNameValue = update.tool_name ?? update.toolName ?? toolInfo?.name;
+  const stepIndex = update.step_index ?? update.stepIndex;
+  const active = state === "active" || state === "running";
+  const terminal = SUCCESS_STATES.has(state) || ERROR_STATES.has(state);
+  return {
+    ...update,
+    type: active ? "tool_use" : terminal ? "tool_result" : "step_update",
+    ...(stepIndex === undefined ? {} : { id: stepIndex }),
+    ...(toolNameValue === undefined ? {} : { tool_name: toolNameValue }),
+    ...(isRecord(parameters) ? { input: parameters } : {}),
+    ...(terminal ? toolStateFields(state, toolInfo) : {}),
+  };
+}
+
+function getToolInfo(update: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (isRecord(update.tool_info)) return update.tool_info;
+  return isRecord(update.toolInfo) ? update.toolInfo : undefined;
+}
+
+function toolStateFields(
+  state: string,
+  toolInfo: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (SUCCESS_STATES.has(state)) return { status: "success" };
+  return {
+    status: "error",
+    is_error: true,
+    ...(toolInfo?.error === undefined ? {} : { error: toolInfo.error }),
+  };
+}
+
+function lowerBoundedText(value: unknown): string {
+  return (safeString(value, 40) ?? "").toLowerCase();
+}

package/src/process/runner.ts

@@ -0,0 +1,147 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type IsolatedAntigravityPaths, prepareIsolatedAntigravityHome } from "../isolated-home.ts";
+import type { AntigravityExecutionFacts, AntigravityProgressCallback } from "../types.ts";
+import { eventType, toolName } from "./event-values.ts";
+import { AntigravityEventAccumulator } from "./events.ts";
+import { MAX_STREAM_EVENTS, parseNdjsonLine, StreamLimitError } from "./ndjson.ts";
+import type { AntigravityProbeResult } from "./subprocess.ts";
+import { AntigravityProcessError, runBoundedChildProcess } from "./subprocess.ts";
+
+const DEFAULT_RUN_TIMEOUT_MS = 5 * 60 * 1_000;
+const DEFAULT_PROBE_TIMEOUT_MS = 15 * 1_000;
+
+export type { AntigravityProbeResult } from "./subprocess.ts";
+export { AntigravityProcessError } from "./subprocess.ts";
+
+/** Build the fixed paid-run argument list. */
+export function buildAntigravityRunArguments(
+  schemaPath: string,
+  model: string,
+  conversationId?: string,
+  workspaceDirectory?: string,
+): string[] {
+  return [
+    "--input-format",
+    "stream-json",
+    "--output-format",
+    "stream-json",
+    "--json-schema",
+    schemaPath,
+    "--model",
+    model,
+    "--print-timeout",
+    "5m",
+    "--sandbox",
+    ...(workspaceDirectory ? ["--add-dir", workspaceDirectory] : []),
+    "--disable-slash-commands",
+    ...(conversationId ? ["--conversation", conversationId] : []),
+  ];
+}
+
+/** Fixed arguments for the pre-run project hook probe. */
+export const PROJECT_HOOK_PROBE_ARGUMENTS = Object.freeze([
+  "-p",
+  "/hooks",
+  "--output-format",
+  "json",
+  "--print-timeout",
+  "15s",
+]);
+
+/** Run a bounded structured Antigravity conversation. */
+export async function runAntigravityConversation(options: {
+  paths: IsolatedAntigravityPaths;
+  cwd: string;
+  prompt: string;
+  model: string;
+  conversationId?: string;
+  /** Add the selected project directory to agy's sandbox workspace. */
+  workspaceDirectory?: string;
+  schema: Record<string, unknown>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Override the temporary schema parent for isolated integration tests. */
+  schemaDirectoryParent?: string;
+  onActivity?: AntigravityProgressCallback;
+  onProcessStart?: () => void;
+}): Promise<AntigravityExecutionFacts> {
+  await prepareIsolatedAntigravityHome(options.paths);
+  const schemaDirectory = await mkdtemp(
+    join(options.schemaDirectoryParent ?? tmpdir(), "supi-antigravity-schema-"),
+  );
+  const schemaPath = join(schemaDirectory, "answer.json");
+  try {
+    await writeFile(schemaPath, `${JSON.stringify(options.schema)}\n`, { mode: 0o600 });
+    const args = buildAntigravityRunArguments(
+      schemaPath,
+      options.model,
+      options.conversationId,
+      options.workspaceDirectory,
+    );
+    const accumulator = new AntigravityEventAccumulator({ workspaceDirectory: options.cwd });
+    let eventCount = 0;
+    await runBoundedChildProcess({
+      args,
+      cwd: options.cwd,
+      homeDir: options.paths.homeDir,
+      prompt: options.prompt,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS,
+      onLine: (line) => {
+        const event = parseNdjsonLine(line);
+        if (!event) return;
+        eventCount += 1;
+        if (eventCount > MAX_STREAM_EVENTS) {
+          throw new StreamLimitError("Antigravity returned too many stream events.");
+        }
+        options.onActivity?.(safeActivityLabel(event));
+        accumulator.consume(event);
+      },
+      onProcessStart: options.onProcessStart,
+    });
+    return accumulator.finish();
+  } catch (error) {
+    if (error instanceof AntigravityProcessError) throw error;
+    // biome-ignore lint/style/useErrorCause: the custom process error preserves the protocol cause.
+    throw new AntigravityProcessError("Antigravity returned an invalid stream.", "protocol", {
+      cause: error,
+    });
+  } finally {
+    await rm(schemaDirectory, { recursive: true, force: true });
+  }
+}
+
+/** Run one bounded agy command and retain only bounded text for its caller. */
+export async function runAntigravityProbe(options: {
+  paths: IsolatedAntigravityPaths;
+  cwd: string;
+  args: string[];
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxStdoutBytes?: number;
+  onProcessStart?: () => void;
+}): Promise<AntigravityProbeResult> {
+  await prepareIsolatedAntigravityHome(options.paths);
+  const lines: string[] = [];
+  const result = await runBoundedChildProcess({
+    args: options.args,
+    cwd: options.cwd,
+    homeDir: options.paths.homeDir,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    maxStdoutBytes: options.maxStdoutBytes,
+    allowNonZero: true,
+    onLine: (line) => lines.push(line),
+    onProcessStart: options.onProcessStart,
+  });
+  return { ...result, stdout: lines.join("\n") };
+}
+
+function safeActivityLabel(event: Record<string, unknown>): string {
+  const name = toolName(event);
+  if (name) return `activity: ${name}`;
+  const type = eventType(event);
+  return type ? `activity: ${type}` : "activity: processing";
+}