I maintain paseo-agy-acp, an Apache-2.0 product adapter between Paseo and Google's official Antigravity ACP kernel. Version 2.3.0 is now on npm and can be launched with npx.

Maintainer disclosure: this is a community project, not official Paseo or Google support. This post was drafted by an AI agent from the project's v2.3.0 documentation on behalf of the maintainer.

The adapter does not reimplement Antigravity. Google's local kernel remains responsible for OAuth, model discovery, inference, streaming, tools, MCP execution, quotas, and provider errors. The npm package installs only the open-source proxy; it neither contains nor downloads Google's proprietary kernel.

The useful engineering question is narrower: what contracts are still missing after two products agree on ACP?

Contract 1: ownership must stay explicit

The execution chain is intentionally small:

Paseo / Generic ACP client
  -> paseo-agy-acp
       context | mode map | MCP rewrite | skill hints
       blank-turn guard | optional Admission fence
  -> official agy_acp_server
       OAuth | models | tools | MCP | inference

Paseo owns agent lifecycle, workspaces, and delegation. The adapter owns Paseo-specific normalization. The official kernel owns the provider. If a model is unavailable, quota is exhausted, or a tool behaves differently, the adapter surfaces that result instead of pretending it can repair the backend.

That boundary also defines distribution: the adapter is Apache-2.0, while the official kernel remains a separate local proprietary dependency.

Contract 2: controller context must reach the session

A session can be protocol-correct and still be operationally wrong.

Paseo launches agents with daemon-side context, a workspace cwd, and agent identity. A raw bridge can successfully forward session/prompt while silently dropping the instructions that tell an agent how to operate in that workspace.

paseo-agy-acp injects the daemon context when PASEO_AGENT_ID is present. The goal is preserving the controller's execution contract across the provider boundary.

This is a recurring integration lesson: transport success says nothing about whether product context survived.

Contract 3: modes and MCP shapes need deterministic normalization

Mode identifiers differ between products. The adapter currently maps:

The official live kernel does not expose a plan mode. Mapping it to default is explicit and testable; claiming an unsupported capability would be worse.

MCP configuration has a similar mismatch. Paseo commonly supplies an HTTP-style declaration with headers in a map. The official kernel expects SSE and header entries shaped as name/value pairs. The adapter rewrites that data during session/new so each caller does not need its own Antigravity-specific conversion.

Contract 4: empty output is an error, not success

An output-free end_turn is valid protocol data, but it is a poor product result.

Without additional tracking, the controller may store a blank assistant message as a successful turn. That makes failure statistics inaccurate and leaves operators guessing whether the model produced nothing, streaming was lost, or the provider failed internally.

The adapter tracks visible assistant and tool activity. If the official kernel ends the turn with none, it returns an explicit JSON-RPC error. Turning ambiguity into a typed failure improves retry behavior and observability without changing the kernel.

Contract 5: multi-agent bursts need account-wide Admission

Paseo can delegate to several agents at once. Each agent may have its own connector process and official-kernel child. If all of them write prompts against one signed-in Antigravity account at the same moment, process-local throttling is insufficient.

paseo-agy-acp places a durable Admission queue immediately before the official session/prompt write. Each turn:

1. joins the account-wide queue,
2. acquires a seat,
3. writes the prompt to the official kernel,
4. releases the seat on completion, failure, or cancellation.

Extra turns wait instead of striking the account concurrently.

The tested defaults are 8 active turns, 8 concurrent starts, and 2 seconds minimum start spacing. These are operating defaults validated under Paseo bursts, not a Google product limit.

Admission state is shared by every connector process using the same owner-only state directory. Invalid policy, missing identity, or permissive filesystem state fails closed when the fence is enabled. Silently switching from fenced to unfenced execution would make incidents difficult to reproduce.

Contract 6: local commands must remain workspace-scoped

Version 2.3.0 adds discovery of user-invocable SKILL.md metadata across configured and default Gemini, Agents, Codex, and workspace roots.

The adapter merges those skills into standard ACP slash-command hints while preserving native commands from the official kernel. The precedence rules are:

• native commands win name collisions,
• workspace skills override global skills,
• user-invocable: false entries remain hidden,
• discovery runs against each session cwd,
• concurrent session/new setup is serialized.

The cwd boundary matters. Without it, two agents starting in different workspaces could observe each other's command metadata. Version 2.3.0 treats command discovery as session state, not connector-global state.

The release validation covered 37 test files with 216 passing and one skipped. Architecture and secret checks passed. A live official-kernel canary preserved native commands, exposed a visible workspace skill, and kept a non-invocable skill hidden.

Running v2.3.0 with npx

Requirements:

• Paseo with Generic ACP provider support
• Node.js 22 or newer
• a locally installed official Antigravity ACP kernel wrapper or .par
• an Antigravity account able to complete oauth-personal
• Linux ownership and mode support when Admission is enabled

Authenticate through the official kernel:

export PASEO_AGY_ACP_OFFICIAL_BIN="/absolute/path/to/agy-acp-server-wrapper-or.par"
npx -y paseo-agy-acp@2.3.0 --login

For multi-agent operation, prepare one state directory per account:

export AGY_ACP_STATE_DIR="$HOME/.local/state/paseo-agy-acp/account-name"
install -d -m 700 "$AGY_ACP_STATE_DIR"

npx -y --package=paseo-agy-acp@2.3.0   agy-acp-prepare-state "$AGY_ACP_STATE_DIR"

Then point a Paseo provider at the package:

{
  "providers": {
    "antigravity": {
      "type": "acp",
      "command": ["npx", "-y", "paseo-agy-acp@2.3.0"],
      "env": {
        "PASEO_AGY_ACP_OFFICIAL_BIN": "/absolute/path/to/agy-acp-server-wrapper-or.par",
        "AGY_ACP_ADMISSION_ENABLED": "true",
        "AGY_ACP_STATE_DIR": "/home/YOU/.local/state/paseo-agy-acp/account-name"
      }
    }
  }
}

Restart Paseo after changing the provider command or environment. npx starts the stdio adapter consumed by Paseo; it is not a standalone chat application. The official kernel must already be installed and authenticated. The first npm run may compile better-sqlite3 and require a local C++ toolchain.

What remains provider-owned

The default official ACP path follows the Gemini-family model set available to the signed-in account. Entitled accounts can use the repository's explicit local compatibility runbook for Claude 4.6 and GPT-OSS 120B, but inference still runs through the same official kernel and Google backend.

That distinction matters when debugging. The adapter can preserve context, normalize requests, pace account access, and make failures visible. It cannot manufacture entitlement or redefine provider capacity.

The broader lesson

Protocol adapters become production integrations when their contracts are explicit.

For this project, the critical contracts are ownership, context propagation, deterministic normalization, visible failure semantics, account-wide Admission, and workspace-scoped command discovery. None requires replacing the official provider. Each removes a class of ambiguity at the boundary.

Project: github.com/tiezbro/paseo-agy-acp

npm: paseo-agy-acp@2.3.0

I would especially value reports on Admission settings under real multi-agent bursts and skill isolation across concurrent workspaces.