@mrclrchtr/supi-antigravity 6.4.0

package/src/tool/antigravity_run/evidence.ts

@@ -0,0 +1,169 @@
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, normalize as normalizePath, relative, resolve } from "node:path";
+import { hashEvidence } from "../../process/event-values.ts";
+import type {
+  AntigravityAnswer,
+  AntigravityExecutionFacts,
+  ClassifiedSource,
+  ClassifiedWorkspaceEvidence,
+} from "../../types.ts";
+
+/** Evidence split and safe warnings produced from one Antigravity answer. */
+export interface ClassifiedEvidence {
+  observedSources: ClassifiedSource[];
+  claimedSources: ClassifiedSource[];
+  observedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  claimedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  warnings: string[];
+}
+
+/** Validate references, classify observed facts, and omit unsafe references. */
+export function classifyAnswerEvidence(
+  answer: AntigravityAnswer,
+  facts: Pick<AntigravityExecutionFacts, "observedSourceHashes" | "observedWorkspacePathHashes">,
+  workspaceDirectory: string,
+): ClassifiedEvidence {
+  const sources = classifySources(answer.sources, new Set(facts.observedSourceHashes));
+  const workspace = classifyWorkspaceEvidence(
+    answer.workspaceEvidence,
+    new Set(facts.observedWorkspacePathHashes),
+    workspaceDirectory,
+  );
+  return {
+    observedSources: sources.observed,
+    claimedSources: sources.claimed,
+    observedWorkspaceEvidence: workspace.observed,
+    claimedWorkspaceEvidence: workspace.claimed,
+    warnings: [...new Set([...sources.warnings, ...workspace.warnings])],
+  };
+}
+
+interface ClassifiedSourceLists {
+  observed: ClassifiedSource[];
+  claimed: ClassifiedSource[];
+  warnings: string[];
+}
+
+function classifySources(
+  sources: readonly AntigravityAnswer["sources"][number][],
+  observedHashes: ReadonlySet<string>,
+): ClassifiedSourceLists {
+  const result: ClassifiedSourceLists = { observed: [], claimed: [], warnings: [] };
+  for (const source of sources) {
+    const url = source.url.trim();
+    if (!isHttpUrl(url) || !source.title.trim()) {
+      result.warnings.push("Some source references were omitted because they were invalid.");
+      continue;
+    }
+    const classified: ClassifiedSource = {
+      title: source.title.trim(),
+      url,
+      evidence: observedHashes.has(hashEvidence(url)) ? "observed" : "claimed",
+    };
+    addClassified(result, classified);
+  }
+  return result;
+}
+
+function classifyWorkspaceEvidence(
+  evidence: readonly AntigravityAnswer["workspaceEvidence"][number][],
+  observedHashes: ReadonlySet<string>,
+  workspaceDirectory: string,
+): {
+  observed: ClassifiedWorkspaceEvidence[];
+  claimed: ClassifiedWorkspaceEvidence[];
+  warnings: string[];
+} {
+  const result = { observed: [], claimed: [], warnings: [] } as {
+    observed: ClassifiedWorkspaceEvidence[];
+    claimed: ClassifiedWorkspaceEvidence[];
+    warnings: string[];
+  };
+  for (const item of evidence) {
+    if (!isSafeWorkspacePath(item.path, workspaceDirectory) || !item.summary.trim()) {
+      result.warnings.push(
+        "Some workspace references were omitted because they were outside the selected workspace.",
+      );
+      continue;
+    }
+    const normalizedPath = normalizeWorkspacePath(item.path);
+    const classified: ClassifiedWorkspaceEvidence = {
+      path: normalizedPath,
+      summary: item.summary.trim(),
+      evidence: observedHashes.has(hashEvidence(normalizedPath)) ? "observed" : "claimed",
+    };
+    if (classified.evidence === "observed") result.observed.push(classified);
+    else result.claimed.push(classified);
+  }
+  return result;
+}
+
+function addClassified(result: ClassifiedSourceLists, source: ClassifiedSource): void {
+  if (source.evidence === "observed") result.observed.push(source);
+  else result.claimed.push(source);
+}
+
+/** Accept only HTTP and HTTPS source URLs. */
+export function isHttpUrl(value: string): boolean {
+  if (hasControlCharacters(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** Check that a returned path is relative and contained by a workspace. */
+export function isSafeWorkspacePath(value: string, workspaceDirectory: string): boolean {
+  if (
+    !value ||
+    hasControlCharacters(value) ||
+    value.startsWith("~") ||
+    isAbsolute(value) ||
+    /^[A-Za-z]:[\\/]/.test(value)
+  ) {
+    return false;
+  }
+  const candidate = normalizeWorkspacePath(value);
+  if (candidate === "." || candidate === ".." || candidate.startsWith("../")) return false;
+  const resolvedWorkspace = safeRealpath(workspaceDirectory);
+  const resolvedCandidate = resolve(resolvedWorkspace, candidate);
+  if (!isContainedPath(resolvedWorkspace, resolvedCandidate)) return false;
+  const existingAncestor = findExistingAncestor(resolvedCandidate);
+  return isContainedPath(resolvedWorkspace, safeRealpath(existingAncestor));
+}
+
+function hasControlCharacters(value: string): boolean {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+
+function normalizeWorkspacePath(value: string): string {
+  return normalizePath(value.replaceAll("\\", "/")).replace(/^\.\//, "");
+}
+
+function safeRealpath(value: string): string {
+  try {
+    return realpathSync(value);
+  } catch {
+    return resolve(value);
+  }
+}
+
+function findExistingAncestor(value: string): string {
+  let candidate = value;
+  while (!existsSync(candidate)) {
+    const parent = dirname(candidate);
+    if (parent === candidate) return value;
+    candidate = parent;
+  }
+  return candidate;
+}
+
+function isContainedPath(workspace: string, candidate: string): boolean {
+  const distance = relative(workspace, candidate);
+  return distance !== ".." && !distance.startsWith("../") && !isAbsolute(distance);
+}

package/src/tool/antigravity_run/execute.ts

@@ -0,0 +1,225 @@
+import { realpath } from "node:fs/promises";
+import type {
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  appendHandleCreated,
+  appendHandleRetired,
+  type ConversationHandleStore,
+} from "../../conversation/handles.ts";
+import {
+  type IsolatedAntigravityPaths,
+  prepareIsolatedAntigravityHome,
+} from "../../isolated-home.ts";
+import { probeProjectHooks } from "../../process/hooks.ts";
+import { AntigravityProcessError, runAntigravityConversation } from "../../process/runner.ts";
+import { ANTIGRAVITY_ANSWER_SCHEMA } from "../../structured-output.ts";
+import type { CuratedModel } from "../../types.ts";
+import {
+  type AntigravityRunInput,
+  type ContinueAntigravityInput,
+  parseAntigravityRunInput,
+} from "./input.ts";
+import { buildAntigravityResult } from "./result.ts";
+
+/** Dependencies captured by one dynamically registered Antigravity tool. */
+export interface AntigravityRunDependencies {
+  pi: ExtensionAPI;
+  paths: IsolatedAntigravityPaths;
+  catalogue: readonly CuratedModel[];
+  cliVersion: string;
+  handles: ConversationHandleStore;
+}
+
+type AntigravityExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
+
+/** Build the execute function for one immutable availability snapshot. */
+export function makeAntigravityRunExecute(
+  dependencies: AntigravityRunDependencies,
+): AntigravityExecute {
+  // biome-ignore lint/complexity/useMaxParams: Pi execute contract requires five parameters.
+  return async (_toolCallId, params, signal, onUpdate, ctx) => {
+    const input = parseAntigravityRunInput(params, dependencies.catalogue);
+    const startedAt = Date.now();
+    if (input.new) {
+      return runNew({ input, dependencies, signal, onUpdate, ctx, startedAt });
+    }
+    if (!input.continue)
+      throw new Error("antigravity_run requires exactly one of new or continue.");
+    return runContinue({
+      continuation: input.continue,
+      prompt: input.prompt,
+      dependencies,
+      signal,
+      onUpdate,
+      ctx,
+      startedAt,
+    });
+  };
+}
+
+interface CommonRunOptions {
+  dependencies: AntigravityRunDependencies;
+  signal: AbortSignal | undefined;
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined;
+  ctx: ExtensionContext;
+  startedAt: number;
+}
+
+interface NewRunOptions extends CommonRunOptions {
+  input: Extract<AntigravityRunInput, { new: object }>;
+}
+
+async function runNew(options: NewRunOptions): Promise<ReturnType<typeof buildAntigravityResult>> {
+  const { input, dependencies, signal, onUpdate, ctx, startedAt } = options;
+  const workspaceAccess = input.new.workspace;
+  await prepareIsolatedAntigravityHome(dependencies.paths);
+  const cwd = await resolveWorkingDirectory(workspaceAccess, ctx.cwd, dependencies.paths);
+  const hookWarning = await prepareWorkspaceRun({
+    workspaceAccess,
+    cwd,
+    paths: dependencies.paths,
+    signal,
+    ctx,
+  });
+  const progress = createProgressReporter(onUpdate, input.new.model, workspaceAccess);
+  progress("starting Antigravity");
+
+  const facts = await runAntigravityConversation({
+    paths: dependencies.paths,
+    cwd,
+    prompt: input.prompt,
+    model: input.new.model,
+    workspaceDirectory: workspaceAccess ? cwd : undefined,
+    schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+    signal,
+    onActivity: progress,
+  });
+  const record = dependencies.handles.create({
+    rawAntigravityId: facts.conversationId,
+    model: input.new.model,
+    canonicalWorkingDirectory: cwd,
+    workspaceAccess,
+    cliVersion: dependencies.cliVersion,
+  });
+  appendHandleCreated(dependencies.pi, record);
+  return buildAntigravityResult({
+    facts,
+    handle: record,
+    durationMs: Date.now() - startedAt,
+    ...(hookWarning ? { hookWarning } : {}),
+  });
+}
+
+interface ContinueRunOptions extends CommonRunOptions {
+  continuation: ContinueAntigravityInput;
+  prompt: string;
+}
+
+async function runContinue(
+  options: ContinueRunOptions,
+): Promise<ReturnType<typeof buildAntigravityResult>> {
+  const { continuation, prompt, dependencies, signal, onUpdate, ctx, startedAt } = options;
+  const record = dependencies.handles.acquire(continuation.handle);
+  let processStarted = false;
+  try {
+    const cwd = record.canonicalWorkingDirectory;
+    const hookWarning = await prepareWorkspaceRun({
+      workspaceAccess: record.workspaceAccess,
+      cwd,
+      paths: dependencies.paths,
+      signal,
+      ctx,
+      onProcessStart: () => {
+        processStarted = true;
+      },
+    });
+    const progress = createProgressReporter(onUpdate, record.model, record.workspaceAccess);
+    await prepareIsolatedAntigravityHome(dependencies.paths);
+    progress("starting Antigravity follow-up");
+    const facts = await runAntigravityConversation({
+      paths: dependencies.paths,
+      cwd,
+      prompt,
+      model: record.model,
+      conversationId: record.rawAntigravityId,
+      workspaceDirectory: record.workspaceAccess ? cwd : undefined,
+      schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+      signal,
+      onActivity: progress,
+      onProcessStart: () => {
+        processStarted = true;
+      },
+    });
+    if (facts.conversationId !== record.rawAntigravityId) {
+      throw new Error("Antigravity returned a different conversation for this handle.");
+    }
+    return buildAntigravityResult({
+      facts,
+      handle: record,
+      durationMs: Date.now() - startedAt,
+      ...(hookWarning ? { hookWarning } : {}),
+    });
+  } catch (error) {
+    if (processStarted) {
+      const retired = dependencies.handles.retire(record.handle);
+      if (retired) appendHandleRetired(dependencies.pi, retired, errorMessage(error));
+    }
+    throw error;
+  } finally {
+    dependencies.handles.release(record.handle);
+  }
+}
+
+async function resolveWorkingDirectory(
+  workspaceAccess: boolean,
+  currentDirectory: string,
+  paths: IsolatedAntigravityPaths,
+): Promise<string> {
+  return realpath(workspaceAccess ? currentDirectory : paths.consultationWorkspace);
+}
+
+async function prepareWorkspaceRun(options: {
+  workspaceAccess: boolean;
+  cwd: string;
+  paths: IsolatedAntigravityPaths;
+  signal: AbortSignal | undefined;
+  ctx: ExtensionContext;
+  onProcessStart?: () => void;
+}): Promise<string | undefined> {
+  if (!options.workspaceAccess) return undefined;
+  const hookProbe = await probeProjectHooks({
+    paths: options.paths,
+    cwd: options.cwd,
+    signal: options.signal,
+    onProcessStart: options.onProcessStart,
+  });
+  if (!hookProbe.warning) return undefined;
+  options.ctx.ui.notify(hookProbe.warning, "warning");
+  return hookProbe.warning;
+}
+
+function createProgressReporter(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  model: CuratedModel,
+  workspaceAccess: boolean,
+): (activity: string) => void {
+  return (activity: string) => {
+    onUpdate?.({
+      content: [{ type: "text", text: "Antigravity is working…" }],
+      details: {
+        model,
+        workingDirectoryKind: workspaceAccess ? "workspace" : "consultation",
+        workspaceAccess,
+        latestActivity: activity,
+      },
+    });
+  };
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof AntigravityProcessError) return `Antigravity ${error.kind} failure`;
+  return "Antigravity follow-up failed";
+}

package/src/tool/antigravity_run/guidance.ts

@@ -0,0 +1,3 @@
+/** Selection guidance for the dynamically activated antigravity_run tool. */
+export const toolDescription =
+  "Consult an external model for focused web research, workspace analysis, or an independent second opinion.";

package/src/tool/antigravity_run/input.ts

@@ -0,0 +1,106 @@
+import { type TSchema, Type } from "typebox";
+import { Value } from "typebox/value";
+import { buildModelCatalogueEnum, isAvailableCuratedModel } from "../../catalogue.ts";
+import type { CuratedModel } from "../../types.ts";
+
+/** Maximum prompt length accepted by one Antigravity Run. */
+const MAX_PROMPT_CHARS = 32_000;
+/** Maximum opaque handle length accepted from a follow-up. */
+const MAX_HANDLE_CHARS = 128;
+
+/** Input for a new Antigravity Run. */
+export interface NewAntigravityInput {
+  workspace: boolean;
+  model: CuratedModel;
+}
+
+/** Input for a Conversation Handle follow-up. */
+export interface ContinueAntigravityInput {
+  handle: string;
+}
+
+/** The exact public antigravity_run input contract. */
+export type AntigravityRunInput =
+  | { prompt: string; new: NewAntigravityInput; continue?: never }
+  | { prompt: string; new?: never; continue: ContinueAntigravityInput };
+
+/** Build the dynamic tool schema from the immutable Model Catalogue. */
+export function buildAntigravityRunSchema(catalogue: readonly CuratedModel[]): TSchema {
+  if (catalogue.length === 0) {
+    throw new Error("Cannot register antigravity_run without an available model.");
+  }
+  const prompt = Type.String({
+    minLength: 1,
+    maxLength: MAX_PROMPT_CHARS,
+    description: "The bounded request to send to Antigravity.",
+  });
+  const newInput = Type.Object(
+    {
+      prompt,
+      new: Type.Object(
+        {
+          workspace: Type.Boolean({
+            description:
+              "Expose the current PI workspace, or use the empty Consultation Workspace.",
+          }),
+          model: buildModelCatalogueEnum(catalogue),
+        },
+        { additionalProperties: false },
+      ),
+    },
+    { additionalProperties: false },
+  );
+  const continueInput = Type.Object(
+    {
+      prompt,
+      continue: Type.Object(
+        {
+          handle: Type.String({ minLength: 1, maxLength: MAX_HANDLE_CHARS }),
+        },
+        { additionalProperties: false },
+      ),
+    },
+    { additionalProperties: false },
+  );
+  return Type.Union([newInput, continueInput]);
+}
+
+/** Validate exact-one input and the model against the same catalogue. */
+export function parseAntigravityRunInput(
+  value: unknown,
+  catalogue: readonly CuratedModel[],
+): AntigravityRunInput {
+  if (!isRecord(value)) throw new Error("Invalid antigravity_run input.");
+  const hasNew = value.new !== undefined;
+  const hasContinue = value.continue !== undefined;
+  if (hasNew === hasContinue) {
+    throw new Error("antigravity_run requires exactly one of new or continue.");
+  }
+  const schema = buildAntigravityRunSchema(catalogue);
+  if (!Value.Check(schema, value)) throw new Error("Invalid antigravity_run input.");
+  const newInput = isRecord(value.new) ? value.new : undefined;
+  const continueInput = isRecord(value.continue) ? value.continue : undefined;
+  if (newInput) {
+    if (
+      typeof newInput.workspace !== "boolean" ||
+      !isAvailableCuratedModel(newInput.model, catalogue)
+    ) {
+      throw new Error("The selected Antigravity model is not available in the Model Catalogue.");
+    }
+    return {
+      prompt: value.prompt as string,
+      new: { workspace: newInput.workspace, model: newInput.model },
+    };
+  }
+  if (!continueInput || typeof continueInput.handle !== "string") {
+    throw new Error("Invalid Antigravity Conversation Handle.");
+  }
+  return {
+    prompt: value.prompt as string,
+    continue: { handle: continueInput.handle },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tool/antigravity_run/register.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ConversationHandleStore } from "../../conversation/handles.ts";
+import type { IsolatedAntigravityPaths } from "../../isolated-home.ts";
+import type { CuratedModel } from "../../types.ts";
+import { makeAntigravityRunExecute } from "./execute.ts";
+import { toolDescription } from "./guidance.ts";
+import { renderAntigravityCall, renderAntigravityResult } from "./render.ts";
+import { antigravityRunSpec, buildAntigravityRunParameters } from "./spec.ts";
+
+/** Dependencies needed by the dynamically registered tool. */
+export interface RegisterAntigravityRunOptions {
+  pi: ExtensionAPI;
+  paths: IsolatedAntigravityPaths;
+  catalogue: readonly CuratedModel[];
+  cliVersion: string;
+  handles: ConversationHandleStore;
+}
+
+/** Register antigravity_run from one immutable Model Catalogue. */
+export function registerAntigravityRunTool(options: RegisterAntigravityRunOptions): void {
+  const parameters = buildAntigravityRunParameters(options.catalogue);
+  options.pi.registerTool({
+    ...antigravityRunSpec,
+    description: toolDescription,
+    parameters,
+    renderCall: renderAntigravityCall,
+    renderResult: renderAntigravityResult,
+    execute: makeAntigravityRunExecute({
+      pi: options.pi,
+      paths: options.paths,
+      catalogue: options.catalogue,
+      cliVersion: options.cliVersion,
+      handles: options.handles,
+    }),
+  });
+}