@cavi-ai/antigravity 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.2.0
+
+- Add provider-owned guided setup that validates the external `agy` session
+  without storing an OpenClaw credential.
+- Persist the provider connection on reconnect: guided and interactive reconnect
+  preserve existing provider options and return a non-secret `configPatch`
+  recording the Antigravity endpoint and model catalog.
+- Refresh the static catalog for the models reported by `agy` 1.1.25.
+- Accept model listings written to stdout or stderr and separated by tabs or
+  spaces.
+- Give Antigravity provider requests focused guidance for using the local
+  `openclaw` CLI and MCP servers managed by `mcporter`, using a stable hook id.
+
+## 0.1.0
+
+- First public release under `@cavi-ai/antigravity` (the unscoped npm name
+  `openclaw-antigravity` is a different package).
+- OpenClaw provider/cli-backend ownership metadata, package-root setup entry,
+  doctor contract, and CLI-owned auth recovery hints.
+- Models via `antigravity-cli/<model>` using Google's Antigravity CLI (`agy`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sasan Sotoodehfar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @cavi-ai/antigravity
+
+Use Google's Antigravity CLI (`agy`) as an [OpenClaw](https://github.com/openclaw/openclaw) model provider.
+
+The plugin uses the Antigravity login already available to `agy`. It does not ask for or store an Antigravity API key.
+
+**Documentation:** [Online docs](https://cavi-ai.xyz/docs/antigravity) ·
+[Overview](docs/antigravity/source/pages/introduction/overview.md) ·
+[Quickstart](docs/antigravity/source/pages/introduction/quickstart.md) ·
+[Configuration](docs/antigravity/source/pages/guides/configuration.md) ·
+[Contributing](CONTRIBUTING.md)
+
+The pages under `docs/antigravity/source/` are the release source. A published
+GitHub Release builds them into an immutable versioned artifact that cavi-home
+ingests and serves at [cavi-ai.xyz/docs/antigravity](https://cavi-ai.xyz/docs/antigravity).
+
+## Requirements
+
+- OpenClaw 2026.7 or newer
+- Node.js 20 or newer
+- Antigravity CLI installed and signed in
+
+Confirm that Antigravity is ready:
+
+```bash
+agy models
+```
+
+## Install
+
+```bash
+openclaw plugins install @cavi-ai/antigravity
+openclaw config set plugins.entries.antigravity.enabled true
+```
+
+Restart the OpenClaw Gateway after installation.
+
+## Connect
+
+In OpenClaw, select **Antigravity CLI** and choose **Reconnect**. The plugin validates the existing `agy` session and makes its models available without creating a separate credential.
+
+## Use
+
+Models use the `antigravity-cli/<model>` format:
+
+```bash
+openclaw agent --model antigravity-cli/gemini-3.1-pro-high -m "hello"
+```
+
+If your OpenClaw configuration uses `agents.defaults.modelPolicy.allow`, add the models you want to use or allow `antigravity-cli/*`.
+
+### Models
+
+Run `agy models` for the live list. The plugin includes this catalog from `agy` 1.1.25:
+
+| Model | Alias |
+| --- | --- |
+| `gemini-3.8-flash-high` | |
+| `gemini-3.8-flash-medium` | |
+| `gemini-3.8-flash-low` | |
+| `gemini-3.7-flash-high` | |
+| `gemini-3.7-flash-medium` | |
+| `gemini-3.7-flash-low` | |
+| `gemini-3.6-flash-high` | |
+| `gemini-3.6-flash-medium` | `flash` |
+| `gemini-3.6-flash-low` | `flash-lite` |
+| `gemini-3.1-pro-high` | `pro` (default) |
+| `gemini-3.1-pro-low` | |
+| `claude-sonnet-4-6` | `sonnet` |
+| `claude-opus-4-6-thinking` | `opus` |
+| `gpt-oss-120b-medium` | `gpt-oss` |
+
+New model IDs that are not yet in the catalog are passed through to `agy`.
+
+## OpenClaw and MCP commands
+
+When a request runs through this provider, Antigravity is told to:
+
+- use the installed `openclaw` CLI for OpenClaw operations;
+- use `mcporter` for external MCP servers it manages; and
+- check each CLI's help before assuming command syntax.
+
+This guidance is limited to Antigravity requests and does not change either tool's global configuration.
+
+## Configuration
+
+All settings are optional and live under `plugins.entries.antigravity.config`.
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `command` | `agy` | Path to the `agy` executable. |
+| `mode` | `accept-edits` | Value passed to `agy --mode`, or `none` to omit it. |
+| `skipPermissions` | `false` | Pass `--dangerously-skip-permissions`. Enable only if you accept tool runs without permission prompts. |
+
+Example:
+
+```bash
+openclaw config set plugins.entries.antigravity.config.command /absolute/path/to/agy
+```
+
+## Troubleshooting
+
+- Run `agy models` to confirm that the CLI is installed and signed in.
+- If the provider is missing, confirm the plugin is enabled and restart the Gateway.
+- If OpenClaw rejects a model before it runs, check `agents.defaults.modelPolicy.allow`.
+
+## Limitations
+
+- Responses are returned after `agy` finishes; token streaming is not available.
+- Inline image input is not supported by `agy --print`.
+- Per-token cost is reported as zero because Antigravity is subscription-backed.
+- Context-window values are conservative because the CLI does not publish per-model limits.
+
+## Development
+
+```bash
+npm test          # plugin behaviour
+npm run docs:test # documentation build/verify/release tooling
+```
+
+Releasing docs is automated: publish a GitHub Release `vX.Y.Z` (matching
+`package.json`) and the `Publish release documentation` workflow builds the
+versioned artifact, attaches it to the release, and dispatches cavi-home to
+ingest it. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/doctor-contract-api.js

@@ -0,0 +1,13 @@
+// Doctor contract auto-loaded from the plugin package root (or dist/).
+// See OpenClaw doctor-contract-registry load paths.
+
+export const sessionRouteStateOwners = [
+  {
+    id: "antigravity",
+    label: "Antigravity CLI",
+    providerIds: ["antigravity-cli"],
+    runtimeIds: ["antigravity-cli"],
+    cliSessionKeys: ["antigravity-cli", "antigravity", "agy"],
+    authProfilePrefixes: ["antigravity-cli:", "antigravity:", "agy:"],
+  },
+];

package/openclaw.plugin.json

@@ -0,0 +1,72 @@
+{
+  "id": "antigravity",
+  "name": "Antigravity CLI",
+  "version": "0.2.0",
+  "description": "Runs Google's Antigravity CLI (agy) as a subscription-backed model provider.",
+  "enabledByDefault": false,
+  "activation": {
+    "onStartup": true,
+    "onProviders": ["antigravity-cli"]
+  },
+  "providers": ["antigravity-cli"],
+  "cliBackends": ["antigravity-cli"],
+  "autoEnableWhenConfiguredProviders": ["antigravity-cli"],
+  "syntheticAuthRefs": ["antigravity-cli"],
+  "setup": {
+    "providers": [
+      {
+        "id": "antigravity-cli"
+      }
+    ],
+    "cliBackends": ["antigravity-cli"]
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "antigravity-cli",
+      "method": "cli",
+      "choiceId": "antigravity-cli",
+      "appGuidedDiscovery": true,
+      "appGuidedActionLabel": "Reconnect",
+      "choiceLabel": "Antigravity CLI",
+      "choiceHint": "Use an existing Antigravity CLI (agy) login on this host. Run `agy models` to confirm.",
+      "groupId": "antigravity",
+      "groupLabel": "Antigravity",
+      "groupHint": "Subscription-backed models via agy",
+      "onboardingFeatured": true
+    }
+  ],
+  "uiHints": {
+    "command": {
+      "label": "agy binary",
+      "help": "Path to the agy executable. Prefer an absolute path after install; default `agy` resolves via PATH.",
+      "placeholder": "agy"
+    },
+    "mode": {
+      "label": "agy mode",
+      "help": "Value for `agy --mode` on print-mode runs, or `none` to omit the flag."
+    },
+    "skipPermissions": {
+      "label": "Skip permissions",
+      "help": "Passes --dangerously-skip-permissions to agy. Off by default. Only enable if you accept tool runs without agy permission prompts."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "command": {
+        "type": "string",
+        "description": "Path to the agy binary. Defaults to `agy` on PATH. Prefer an absolute path; do not pass shell metacharacters."
+      },
+      "mode": {
+        "type": "string",
+        "description": "agy --mode value for print-mode runs, or \"none\" to omit the flag.",
+        "enum": ["accept-edits", "plan", "none"]
+      },
+      "skipPermissions": {
+        "type": "boolean",
+        "description": "Pass --dangerously-skip-permissions. Off by default."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@cavi-ai/antigravity",
+  "version": "0.2.0",
+  "description": "Runs Google's Antigravity CLI (agy) as a subscription-backed OpenClaw model provider.",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "antigravity",
+    "agy",
+    "gemini",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cavi-ai/openclaw-antigravity.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cavi-ai/openclaw-antigravity/issues"
+  },
+  "homepage": "https://github.com/cavi-ai/openclaw-antigravity#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "setup-api.js",
+    "doctor-contract-api.js",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.7.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": ["./src/index.js"],
+    "runtimeExtensions": ["./src/index.js"],
+    "install": {
+      "npmSpec": "@cavi-ai/antigravity",
+      "minHostVersion": ">=2026.7.0"
+    },
+    "compat": {
+      "pluginApi": ">=2026.7",
+      "minGatewayVersion": "2026.7.0"
+    },
+    "build": {
+      "openclawVersion": "2026.7.0",
+      "pluginSdkVersion": "2026.7.0"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "docs:test": "node --test scripts/docs/*.test.mjs",
+    "docs:build": "node scripts/docs/build.mjs",
+    "docs:verify": "node scripts/docs/verify.mjs",
+    "docs:release": "node scripts/docs/release-artifact.mjs"
+  }
+}

package/setup-api.js

@@ -0,0 +1,10 @@
+// Lightweight setup entry. OpenClaw discovers package-root `setup-api.js`
+// for descriptor-backed setup without loading the full runtime entry.
+import { registerAntigravity } from "./src/register.js";
+
+export default {
+  id: "antigravity",
+  name: "Antigravity CLI Setup",
+  description: "Setup hooks for the Antigravity CLI provider.",
+  register: registerAntigravity,
+};

package/src/cli-backend.js

@@ -0,0 +1,71 @@
+// CLI backend that drives Google's Antigravity CLI (`agy`) in print mode.
+//
+// This is the `claude -p` pattern: OpenClaw owns the conversation, agy owns
+// inference and auth. agy authenticates itself against the user's Antigravity
+// subscription, so this backend carries no API key and no auth methods.
+//
+// `agy --print --output-format json` emits a single flat object:
+//   {"conversation_id":"…","status":"SUCCESS","response":"…","duration_seconds":…,
+//    "num_turns":1,"usage":{input_tokens,output_tokens,…}}
+// Core's generic JSON reader already takes `response` as the assistant text and
+// `sessionIdFields` for the resume handle, so no stream dialect is needed. agy's
+// `--output-format stream-json` is its own dialect (event/step_update/result) and
+// matches neither claude-stream-json nor gemini-stream-json; adopting it would
+// require a core dialect, so print+json is used instead.
+import { ANTIGRAVITY_MODEL_ALIASES } from "./models.js";
+
+export const ANTIGRAVITY_BACKEND_ID = "antigravity-cli";
+
+/** agy print mode cannot prompt a human, so tool calls need a non-review mode. */
+export const DEFAULT_MODE = "accept-edits";
+
+/**
+ * Builds the args every invocation shares.
+ *
+ * @param {{mode?: string, skipPermissions?: boolean}} [options]
+ */
+export function buildBaseArgs(options = {}) {
+  const args = ["--print", "{prompt}", "--output-format", "json"];
+  const mode = options.mode ?? DEFAULT_MODE;
+  if (mode !== "none") {
+    args.push("--mode", mode);
+  }
+  if (options.skipPermissions === true) {
+    args.push("--dangerously-skip-permissions");
+  }
+  return args;
+}
+
+/**
+ * @param {{command?: string, mode?: string, skipPermissions?: boolean}} [options]
+ *   Plugin config from `plugins.entries.antigravity.config`.
+ */
+export function buildAntigravityCliBackend(options = {}) {
+  const base = buildBaseArgs(options);
+  return {
+    id: ANTIGRAVITY_BACKEND_ID,
+    // Standalone backend: agy's catalog (Gemini + Claude + GPT-OSS behind one
+    // subscription) belongs to no existing provider, so it owns direct
+    // `antigravity-cli/<model>` refs rather than aliasing a canonical provider.
+    modelProvider: ANTIGRAVITY_BACKEND_ID,
+    config: {
+      command: options.command?.trim() || "agy",
+      args: [...base],
+      // agy resumes by conversation id; there is no separate session concept.
+      resumeArgs: [...base, "--conversation", "{sessionId}"],
+      output: "json",
+      resumeOutput: "json",
+      input: "arg",
+      // agy takes the prompt as an argv value. Very long prompts blow the argv
+      // limit, so hand those to stdin instead.
+      maxPromptArgChars: 96_000,
+      modelArg: "--model",
+      modelAliases: { ...ANTIGRAVITY_MODEL_ALIASES },
+      sessionMode: "existing",
+      sessionIdFields: ["conversation_id"],
+      // One agy process at a time: concurrent print-mode runs against the same
+      // conversation interleave writes to its history.
+      serialize: true,
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,19 @@
+// Antigravity CLI plugin — registers `agy` as an OpenClaw model provider backed
+// by the Antigravity subscription, the slot gemini-cli used to fill.
+import { registerAntigravity } from "./register.js";
+
+export const PLUGIN_ID = "antigravity";
+
+export const plugin = {
+  id: PLUGIN_ID,
+  name: "Antigravity CLI",
+  version: "0.2.0",
+  description: "Runs Google's Antigravity CLI (agy) as a subscription-backed model provider.",
+  register: registerAntigravity,
+};
+
+export function register(api) {
+  plugin.register(api);
+}
+
+export default plugin;

package/src/models.js

@@ -0,0 +1,105 @@
+// Model catalog for Google's Antigravity CLI (`agy`).
+//
+// The list mirrors `agy models` as of agy 1.1.25. agy publishes no machine-readable
+// catalog, so ids are refreshed by hand — run `agy models` after an `agy update`
+// and reconcile. Unknown ids still work: they are passed through to `--model`
+// verbatim, so a new agy model is usable before it is listed here.
+
+/** agy's own model ids, from `agy models`. */
+export const ANTIGRAVITY_MODEL_IDS = [
+  "gemini-3.8-flash-high",
+  "gemini-3.8-flash-medium",
+  "gemini-3.8-flash-low",
+  "gemini-3.7-flash-high",
+  "gemini-3.7-flash-medium",
+  "gemini-3.7-flash-low",
+  "gemini-3.6-flash-high",
+  "gemini-3.6-flash-medium",
+  "gemini-3.6-flash-low",
+  "gemini-3.1-pro-high",
+  "gemini-3.1-pro-low",
+  "claude-sonnet-4-6",
+  "claude-opus-4-6-thinking",
+  "gpt-oss-120b-medium",
+];
+
+export const ANTIGRAVITY_DEFAULT_MODEL = "gemini-3.1-pro-high";
+
+/**
+ * Placeholder endpoint for the catalog row. `agy` owns the transport, so this is
+ * never dialed; it exists because `baseUrl` is a required provider field and a
+ * row without it breaks catalog assembly. Loopback keeps it classified as a
+ * local endpoint rather than an unresolvable public host.
+ */
+export const ANTIGRAVITY_BASE_URL = "http://127.0.0.1/antigravity-cli";
+
+/** Adapter recorded on catalog rows. Unused at runtime for the same reason. */
+export const ANTIGRAVITY_MODEL_API = "openai-completions";
+
+/**
+ * Short names for the ids above. `agy` itself accepts only the full id, so these
+ * are expanded by the CLI backend before launch.
+ */
+export const ANTIGRAVITY_MODEL_ALIASES = {
+  pro: "gemini-3.1-pro-high",
+  flash: "gemini-3.6-flash-medium",
+  "flash-lite": "gemini-3.6-flash-low",
+  sonnet: "claude-sonnet-4-6",
+  opus: "claude-opus-4-6-thinking",
+  "gpt-oss": "gpt-oss-120b-medium",
+};
+
+// Context windows are conservative floors, not published figures — Antigravity
+// documents no per-model limits for the CLI. They exist so OpenClaw budgets and
+// compacts sanely; raise them if agy is observed accepting more.
+const CONTEXT_WINDOW_FLOOR = {
+  gemini: 1_000_000,
+  claude: 200_000,
+  other: 128_000,
+};
+
+function contextWindowFor(modelId) {
+  if (modelId.startsWith("gemini-")) {
+    return CONTEXT_WINDOW_FLOOR.gemini;
+  }
+  if (modelId.startsWith("claude-")) {
+    return CONTEXT_WINDOW_FLOOR.claude;
+  }
+  return CONTEXT_WINDOW_FLOOR.other;
+}
+
+/** Turns an agy model id into a human label, e.g. `gemini-3.1-pro-high` → `Gemini 3.1 Pro (high)`. */
+export function labelForModelId(modelId) {
+  const match = /^(.*)-(high|medium|low|thinking)$/.exec(modelId);
+  const base = match ? match[1] : modelId;
+  const suffix = match ? match[2] : undefined;
+  const words = base
+    .split("-")
+    .map((part) => {
+      if (part === "gpt") return "GPT";
+      if (part === "oss") return "OSS";
+      if (/^\d/.test(part)) return part;
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join(" ");
+  return suffix ? `${words} (${suffix})` : words;
+}
+
+/** Builds the catalog entries OpenClaw shows in model pickers. */
+export function buildAntigravityModelCatalog() {
+  return ANTIGRAVITY_MODEL_IDS.map((id) => ({
+    id,
+    name: labelForModelId(id),
+    api: ANTIGRAVITY_MODEL_API,
+    // Thinking-tier ids and the pro tiers reason; the flash-low tiers do not
+    // advertise it. Treat everything except the explicit `-low` tiers as reasoning.
+    reasoning: !id.endsWith("-low"),
+    input: ["text"],
+    contextWindow: contextWindowFor(id),
+    maxTokens: 64_000,
+    // Antigravity is subscription-billed, not metered per token, so there is no
+    // per-token price to report. Zero here means "not separately billed", and
+    // keeps OpenClaw's cost accounting from inventing charges.
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  }));
+}

package/src/provider.js

@@ -0,0 +1,215 @@
+// Provider registration for Antigravity (`agy`).
+//
+// agy owns the user's Antigravity OAuth session. The custom auth method below
+// validates that CLI-owned session and records the provider's non-secret
+// connection (models, endpoint) in config; OpenClaw stores no key for this provider.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ANTIGRAVITY_BACKEND_ID } from "./cli-backend.js";
+import {
+  ANTIGRAVITY_BASE_URL,
+  ANTIGRAVITY_DEFAULT_MODEL,
+  ANTIGRAVITY_MODEL_ALIASES,
+  ANTIGRAVITY_MODEL_API,
+  buildAntigravityModelCatalog,
+} from "./models.js";
+
+export const ANTIGRAVITY_PROVIDER_ID = ANTIGRAVITY_BACKEND_ID;
+const execFileAsync = promisify(execFile);
+const COMMAND_TIMEOUT_MS = 15_000;
+const COMMAND_MAX_BUFFER_BYTES = 1_048_576;
+
+const MISSING_AUTH_MESSAGE =
+  "Antigravity CLI is not ready. Install Google's Antigravity CLI (`agy`), sign in with your Google subscription, then confirm with `agy models`. This provider stores no API key in OpenClaw.";
+const RECONNECT_ERROR_MESSAGE =
+  "Antigravity CLI could not list models. Run `agy` in a terminal to sign in, then choose Reconnect again. OpenClaw stores no Antigravity credential.";
+
+async function runCommand(command, args, context = {}) {
+  const result = await execFileAsync(command, args, {
+    env: context.env,
+    signal: context.signal,
+    timeout: COMMAND_TIMEOUT_MS,
+    maxBuffer: COMMAND_MAX_BUFFER_BYTES,
+  });
+  return [result.stdout, result.stderr].filter(Boolean).join("\n");
+}
+
+function throwIfAborted(signal) {
+  signal?.throwIfAborted?.();
+}
+
+function isAbortError(error, signal) {
+  return signal?.aborted === true || error?.name === "AbortError" || error?.code === "ABORT_ERR";
+}
+
+/** Extracts model ids from the human-readable `agy models` table. */
+export function parseAntigravityModelIds(output) {
+  const ids = [];
+  for (const line of String(output ?? "").split(/\r?\n/)) {
+    const match = /^\s*([a-z0-9][a-z0-9._-]*-[a-z0-9][a-z0-9._-]*)\s+\S.*$/u.exec(line);
+    const id = match?.[1];
+    if (!id || ids.includes(id)) {
+      continue;
+    }
+    ids.push(id);
+  }
+  return ids;
+}
+
+function chooseDetectedModel(modelIds) {
+  return modelIds.includes(ANTIGRAVITY_DEFAULT_MODEL)
+    ? ANTIGRAVITY_DEFAULT_MODEL
+    : modelIds[0];
+}
+
+/**
+ * @param {{command?: string}} [options]
+ * @param {{runCommand?: typeof runCommand}} [dependencies]
+ */
+export function buildAntigravityProvider(options = {}, dependencies = {}) {
+  const command = options.command?.trim() || "agy";
+  const execute = dependencies.runCommand ?? runCommand;
+
+  const listModels = async (context) => {
+    throwIfAborted(context.signal);
+    const output = await execute(command, ["models"], context);
+    throwIfAborted(context.signal);
+    return parseAntigravityModelIds(output);
+  };
+
+  const detect = async (context) => {
+    try {
+      const modelId = chooseDetectedModel(await listModels(context));
+      return modelId
+        ? {
+            modelRef: `${ANTIGRAVITY_PROVIDER_ID}/${modelId}`,
+            detail: `${modelId} via agy`,
+          }
+        : null;
+    } catch (error) {
+      if (isAbortError(error, context.signal)) {
+        throw error;
+      }
+      return null;
+    }
+  };
+
+  // On a successful reconnect, hand OpenClaw a non-secret config patch so the
+  // provider's endpoint and model catalog persist. Shape matches the provider
+  // connection contract other CLI backends use (`configPatch.models.providers`).
+  const buildConnectionPatch = (config = {}) => {
+    const existing = config.models?.providers?.[ANTIGRAVITY_PROVIDER_ID] ?? {};
+    return {
+      models: {
+        mode: config.models?.mode ?? "merge",
+        providers: {
+          [ANTIGRAVITY_PROVIDER_ID]: {
+            ...existing,
+            baseUrl: ANTIGRAVITY_BASE_URL,
+            api: ANTIGRAVITY_MODEL_API,
+            models:
+              Array.isArray(existing.models) && existing.models.length > 0
+                ? existing.models
+                : buildAntigravityModelCatalog(),
+          },
+        },
+      },
+    };
+  };
+
+  const validatedResult = (modelRef, config) => ({
+    profiles: [],
+    defaultModel: modelRef,
+    configPatch: buildConnectionPatch(config),
+  });
+
+  return {
+    id: ANTIGRAVITY_PROVIDER_ID,
+    label: "Antigravity CLI",
+    aliases: ["antigravity", "agy"],
+    envVars: [],
+    auth: [
+      {
+        id: "cli",
+        label: "Antigravity CLI",
+        hint: "Reconnect the CLI-owned Antigravity session and refresh available models",
+        kind: "custom",
+        appGuidedSetup: {
+          detectAvailability: async (context) => {
+            try {
+              throwIfAborted(context.signal);
+              await execute(command, ["--version"], context);
+              throwIfAborted(context.signal);
+              return true;
+            } catch (error) {
+              if (isAbortError(error, context.signal)) {
+                throw error;
+              }
+              return false;
+            }
+          },
+          detect,
+          prepare: async (context) => {
+            const prefix = `${ANTIGRAVITY_PROVIDER_ID}/`;
+            if (!context.modelRef.startsWith(prefix)) {
+              return null;
+            }
+            const modelId = context.modelRef.slice(prefix.length);
+            try {
+              const available = await listModels(context);
+              return available.includes(modelId)
+                ? validatedResult(context.modelRef, context.config)
+                : null;
+            } catch (error) {
+              if (isAbortError(error, context.signal)) {
+                throw error;
+              }
+              return null;
+            }
+          },
+        },
+        run: async (context) => {
+          const detected = await detect(context);
+          if (!detected) {
+            throw new Error(RECONNECT_ERROR_MESSAGE);
+          }
+          return validatedResult(detected.modelRef, context.config);
+        },
+      },
+    ],
+    buildMissingAuthMessage: () => MISSING_AUTH_MESSAGE,
+    buildAuthDoctorHint: () => MISSING_AUTH_MESSAGE,
+    staticCatalog: {
+      order: "simple",
+      run: async () => ({
+        provider: {
+          // `agy` is the transport, so nothing here is ever dialed. Both fields
+          // are still required shape: a provider row without `baseUrl` fails
+          // catalog assembly, which takes down prepared-runtime publication for
+          // every agent, not just this provider.
+          baseUrl: ANTIGRAVITY_BASE_URL,
+          api: ANTIGRAVITY_MODEL_API,
+          defaultModel: ANTIGRAVITY_DEFAULT_MODEL,
+          models: buildAntigravityModelCatalog(),
+        },
+      }),
+    },
+    // agy accepts model ids this catalog has not caught up with. Rather than
+    // fail the run, pass an unknown id straight through to `--model`.
+    resolveDynamicModel: (ctx) => {
+      const modelId = typeof ctx?.modelId === "string" ? ctx.modelId.trim() : "";
+      if (!modelId) {
+        return null;
+      }
+      const resolved = ANTIGRAVITY_MODEL_ALIASES[modelId] ?? modelId;
+      return {
+        id: resolved,
+        provider: ANTIGRAVITY_PROVIDER_ID,
+        name: resolved,
+        api: ANTIGRAVITY_MODEL_API,
+        baseUrl: ANTIGRAVITY_BASE_URL,
+        input: ["text"],
+      };
+    },
+  };
+}

package/src/register.js

@@ -0,0 +1,24 @@
+import { buildAntigravityCliBackend } from "./cli-backend.js";
+import { buildAntigravityProvider } from "./provider.js";
+
+const ANTIGRAVITY_OPENCLAW_CONTEXT = [
+  "You are running through OpenClaw's Antigravity CLI model provider.",
+  "Use the installed `openclaw` CLI for OpenClaw operations and check its help before assuming command syntax.",
+  "Use `mcporter` for external MCP servers it manages and check its help before assuming command syntax.",
+  "Do not change global OpenClaw or mcporter configuration unless the user explicitly asks.",
+].join(" ");
+
+/** Shared by runtime entry and package-root setup-api. */
+export function registerAntigravity(api) {
+  const config = api?.pluginConfig ?? {};
+  api.registerProvider(buildAntigravityProvider(config));
+  api.registerCliBackend(buildAntigravityCliBackend(config));
+  api.registerHook?.(
+    "before_prompt_build",
+    (_event, context) =>
+      context?.modelProviderId === "antigravity-cli"
+        ? { prependContext: ANTIGRAVITY_OPENCLAW_CONTEXT }
+        : undefined,
+    { registrationId: "antigravity-openclaw-cli-guidance" },
+  );
+}