agentleFS
Omni-CraftOmni-Craft/OmniCraft/.claude/skills/antigravity-sdk-e2e-dev/SKILL.md

antigravity-sdk-e2e-dev

Skill1 starsChanged 4 months agoApache-2.0View on GitHub

Spin up a live local OmniCraft server and exercise the Antigravity (Gemini) SDK harness end-to-end — build antigravity agents, run real turns, smoke-test, and bug-bash. Load when developing, testing, or debugging the antigravity harness (omnicraft/inner/antigravity_executor.py, antigravity_harness.py, omnicraft/onboarding/antigravity_auth.py) or its auth / model / tool-bridge behavior.

  • Reads credentials
  • Deletes or force-pushes
  • Installs packages

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If both are False, run omni setup → Antigravity and paste a key, or export GEMINI_API_KEY=AIza….

    line 28
  2. Very specific:

    Use the printed URL below as $SERVER.

    line 54
  3. Very specific:

    Shell / file tools: add --tools coding.

    line 95
  4. Very specific:

    Specific model: add --model gemini-2.5-flash (or another Gemini id).

    line 96
  5. Very specific:

    Model ids are Gemini ids: Default gemini-3.5-flash. gemini-3-pro

    line 129
  6. Very specific:

    Native/built-in tools bypass the TOOL_CALL policy: Only a PostToolCallHook (post-execution, can't block) was installed at merge, so a …

    line 177

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Antigravity SDK harness: end-to-end dev & testing

The antigravity harness drives Google's Antigravity Python SDK (google-antigravity, an in-process Agent/Conversation) and bridges OmniCraft's sys_* tools into the SDK as custom_tools. It is Gemini-native: it authenticates with a Gemini / Antigravity API key (or Vertex AI) and has no OpenAI-compatible gateway / Databricks path. This skill is the proven recipe for running it for real against a live local server — not just the unit tests.

The harness runs as a local runner from your current checkout, so omni run <bundle> --server <url> exercises exactly the code you're on.

Prerequisites (check these first)

  1. You're on the branch you want to test. The antigravity harness merged to main (#194). Test on main unless validating a specific branch.
  2. A Gemini API key is configured. The SDK requires one (AIza…); there is no login flow. Verify (booleans only — never print the key):
    .venv/bin/python -c "from omnicraft.onboarding.antigravity_auth import antigravity_api_key_configured as c; import os; print('config:', c(), 'env:', bool(os.environ.get('GEMINI_API_KEY') or os.environ.get('ANTIGRAVITY_API_KEY')))"
    If both are False, run omni setup → Antigravity and paste a key, or export GEMINI_API_KEY=AIza….
  3. google-antigravity is installed (the antigravity extra — pip install "omnicraft[antigravity]"): .venv/bin/python -c "import google.antigravity as a; print(a.__file__)".
  4. glibc ≥ ~2.36. The SDK spawns a native localharness binary that needs a recent glibc (GLIBC_ABI_DT_RELR). Check ldd --version | head -1. On an older host the turn fails at setup with RuntimeError: … localharness: … version 'GLIBC_ABI_DT_RELR' not found. Dev workaround on a glibc-2.31 box: point the SDK at a loader-shim via ANTIGRAVITY_HARNESS_PATH=/path/to/shim that runs the untouched bundled binary through a newer glibc's loader (see the auto-memory note antigravity-harness-glibc-native-binary.md). The shim is dev-only — the real fix is a glibc-≥2.36 host.
  5. Network egress to the Gemini backend. The native binary talks to Google's API; a turn that hangs or fails to connect on a locked-down host is usually an egress problem, not a harness bug.

Step 1 — start a local server

cd /path/to/omnicraft
.venv/bin/omni server start          # spawns a detached server on a free loopback port
.venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767

Use the printed URL below as $SERVER. (You can also run a foreground server on a fixed port with omnicraft server --port 7777 --no-open.)

Step 2 — build an antigravity agent bundle

A spec with spec_version must be a directory containing config.yaml — not a single .yaml file. Minimal antigravity agent (no auth: block → it resolves the key from the antigravity: config / ambient env):

mkdir -p /tmp/agy-dev
cat > /tmp/agy-dev/config.yaml <<'YAML'
spec_version: 1
name: agy-dev
description: Antigravity SDK dev/test agent.
executor:
  type: omnicraft
  config:
    harness: antigravity
    model: gemini-3.5-flash      # default; gemini-3-pro 404s on a plain AI-Studio key
prompt: |
  You are a terse test agent. Answer in as few words as possible.
YAML

For sub-agents, tools, guardrails/policies, copy the field shapes from examples/fucho/config.yaml and examples/lilo/config.yaml.

Step 3 — run a turn (and smoke-test)

SERVER=http://127.0.0.1:6767   # the URL from `omni server status`
timeout 280 .venv/bin/omni run /tmp/agy-dev \
  -p "Reply with exactly the single word: PONG" \
  --server "$SERVER" 2>&1

A healthy run prints connection lines then the assistant reply (PONG). If that works, the full stack is good: Gemini key, glibc/native binary, egress, streaming, harness.

  • Shell / file tools: add --tools coding.
  • Specific model: add --model gemini-2.5-flash (or another Gemini id).

Targeted scenarios

GoalHow
Native tools (shell/edit/read)--tools coding, prompt to create→read→edit a file and run a shell command; confirm it actually touches disk
Bridged sys_* / sub-agent dispatchdeclare a sub-agent (tools.agents/spawn), prompt the agent to delegate — exercises the custom_tools bridge + PostToolCallHook
Model routingrun the same bundle with several --model Gemini ids; note which actually runs
Vertex AI authset executor.config.vertex: true + project/location and use GCP application-default creds instead of an API key
Policy / guardrailadd a guardrail that denies a keyword; confirm it blocks (see the sharp edges below — LLM-phase + tool-call enforcement was incomplete at merge)
Per-session brain overriderun a bundle agent (fucho/lilo) and select antigravity as the brain harness (it's in BRAIN_HARNESS_LABELS)
Concurrency / leaksfire several omni run … & at once; then pgrep -af localharness to check for orphaned native subprocesses

Gotchas (these cost real time)

  1. config.yaml's server: defaults to a remote server. Omitting --server sends your turn to that remote deploy — which may be stale and reject the antigravity harness with executor.config.harness: must be one of […], got 'antigravity'. Always pass --server http://127.0.0.1:<port> for local testing. (That allowlist is omnicraft/spec/_omnicraft_compat.py; if a local server rejects antigravity, it's running stale code — restart it from your checkout.)
  2. A spec with spec_version must be a directory + config.yaml, never a single .yaml file.
  3. Antigravity needs a Gemini key (no login). Resolution precedence: spec executor.auth (api_key) > stored antigravity: config block (omni setup)

    ambient GEMINI_API_KEY / ANTIGRAVITY_API_KEY. Vertex AI is opt-in via executor.config vertex/project/location.

  4. No OpenAI gateway / Databricks. The SDK has no base_url; a databricks or generic-provider auth is warned and ignored, and the run falls back to ambient Gemini creds. Don't expect databricks-* models to route through the AI Gateway like claude-sdk/codex/pi.
  5. Model ids are Gemini ids. Default gemini-3.5-flash. gemini-3-pro 404s on a plain AI-Studio key — use gemini-2.5-flash / gemini-3.5-flash unless your key has Pro access.
  6. The native binary needs glibc ≥ ~2.36 (see Prereq 4). This is the most common "it won't even start" cause; check it before assuming a harness bug.
  7. Turns take ~10–60s — always wrap in timeout 280.
  8. Local-runner topology: omni run <bundle> --server <url> runs the harness from your current checkout; the server only holds state. The managed omni server start server runs from whatever venv launched it.
  9. Never print/echo the Gemini key in logs or commands.

Code & tests

  • Executor (SDK driver): omnicraft/inner/antigravity_executor.py
  • Wrap (HARNESS_ANTIGRAVITY_ env → executor):* omnicraft/inner/antigravity_harness.py
  • Auth / key resolution: omnicraft/onboarding/antigravity_auth.py
  • Spawn env: _build_antigravity_spawn_env in omnicraft/runtime/workflow.py
# Unit tests (use --frozen; the cwsandbox extra is unsatisfiable on public PyPI here)
uv run --frozen --extra dev python -m pytest \
  tests/inner/test_antigravity_executor.py \
  tests/inner/test_antigravity_harness.py \
  tests/runtime/test_antigravity_spawn_env.py \
  tests/onboarding/test_antigravity_auth.py -q
# (or, if uv re-resolve is blocked on your host: .venv/bin/python -m pytest <same paths> -q)

There is no gated per-harness antigravity e2e test yet (it is deliberately excluded from the live no-AGENT harness matrix in tests/e2e/omnicraft/test_run_harness_without_agent_e2e.py, because that matrix authenticates through the Databricks gateway and antigravity is Gemini-native). This skill IS the live coverage.

Bug-bash (fan out)

To stress the harness, run several scenario probes in parallel — each builds a bundle and runs real turns against the same $SERVER, then reports what broke. Highest-value targets: the custom_tools bridge (hangs / lost tool results / errors reported as success), model routing, policy enforcement, streamed-output rendering, history retention across turns, and orphaned localharness processes after teardown.

Known sharp edges (found via the merge review — "as of this writing")

Several were merged as-is and have fix PRs in flight (#276–#281) — verify against your checkout:

  • Native/built-in tools bypass the TOOL_CALL policy. Only a PostToolCallHook (post-execution, can't block) was installed at merge, so a DENY/ASK guardrail doesn't gate the SDK's native shell/file tools before they run. Bridged sys_* tools route through the server. (Fix: policy-enforcement PR.)
  • LLM_REQUEST / LLM_RESPONSE policies aren't evaluated in run_turn (prompt- deny / output-block silently ignored). (Fix: policy-enforcement PR.)
  • History on a fresh/rebuilt session. The SDK has no history-injection API, so prior turns are replayed as a plain-text "Conversation so far: …" prefix (user/assistant text only; tool calls aren't reconstructed). (PR #278.)
  • sys_list_models can over-report OpenAI-family models for antigravity (it was mapped to the openai family for shared lookups); the worker only runs Gemini. (Fix: openai-family-cleanup PR.)
  • Per-session /model override was rejected with a false "no plumbing" error. (PR #276.) Global auth: (an OpenAI key) could be adopted as a Gemini key. (PR #277.) Tool parameter schemas were dropped (model flew blind on arg shapes). (PR #279.)
  • A failed turn (e.g. the glibc error, a bad model) surfaces as a failed session + an error item — if a turn returns little, check GET /v1/sessions/{id} status and …/items rather than assuming success.

Cleanup

.venv/bin/omni server stop      # stop the managed background server
rm -rf /tmp/agy-dev             # remove scratch bundles
pgrep -af "localharness"        # confirm no orphaned native subprocesses linger

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.