Building a Paseo product adapter for Google's official Antigravity ACP kernel

I maintain paseo-agy-acp, a community adapter that lets Paseo use Google's official Antigravity ACP kernel as a real multi-agent provider.

Version 2.3.0 is now on npm, so the open-source adapter can be launched directly with npx:

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

That one command is useful, but the interesting part of the project is the boundary behind it.

Important disclosure: I maintain this project. It is not official Paseo support and not official Google support. The npm package contains only the Apache-2.0 proxy. It does not contain or download Google's proprietary Antigravity kernel. You still need Paseo, Node.js 22+, a locally installed official kernel, and an Antigravity account that can complete the kernel's OAuth flow.

Why a product adapter exists when both sides already speak ACP

ACP gives us the wire protocol: initialize a connection, create a session, send prompts, cancel work, stream assistant output, report tool calls, and expose modes or configuration.

That is necessary, but a generic protocol connection does not automatically define product behavior.

Paseo is a controller that can create and delegate to several agents across different workspaces. The official Antigravity kernel owns authentication, inference, models, tools, and MCP behavior. Connecting those two systems exposes questions that do not belong in either raw JSON-RPC message shape:

• How does Paseo's daemon and workspace context reach the provider session?
• What happens when Paseo and the kernel use different mode identifiers?
• How should HTTP-style MCP declarations be normalized for the official kernel?
• How do multiple connector processes avoid overloading one Antigravity account?
• How should an output-free end turn be represented?
• How can local SKILL.md commands appear beside native ACP commands without leaking between workspaces?

paseo-agy-acp is deliberately a thin NDJSON proxy that answers those product questions while leaving provider responsibilities in the official kernel.

The ownership boundary

The execution path is:

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

The official kernel remains responsible for:

• the supported oauth-personal authentication flow
• session lifecycle and assistant streaming
• tool calls and tool updates
• the signed-in account's available model catalog
• MCP client execution
• inference, quota, capacity, and backend errors

The adapter is responsible only for the Paseo-facing integration layer. That keeps the open-source surface inspectable and avoids reimplementing or redistributing a proprietary provider.

1. Daemon and workspace context

Paseo supplies agent identity and working-directory information to provider processes. It can also append daemon-side instructions that agents need in order to operate correctly inside a workspace.

The adapter carries that context into the official session prompt when PASEO_AGENT_ID is present. Without this bridge, a session may technically run while missing the controller's operating context.

This is a small transformation with a large behavioral impact: protocol success is not the same as a correctly contextualized agent.

2. Explicit mode mapping

Product mode names do not line up automatically. The current mapping is:

Paseo or legacy id	Official live mode
default	default
accept-edits	auto_edit
dangerously-skip-permissions	yolo
plan	default

The official live kernel has no plan mode, so the adapter maps plan to default rather than claiming a capability that is not there. Legacy kernel selection also fails closed; the official kernel is the only execution path.

3. MCP shape normalization

Paseo commonly describes an MCP endpoint as an HTTP server with a header map. The official Antigravity kernel expects the equivalent declaration as SSE with headers represented as name/value entries.

The adapter rewrites that structure during session/new. This keeps product-specific conversion in one place instead of requiring every Paseo configuration or MCP server to understand the kernel's exact representation.

4. Making silent turns visible

An official end_turn with no visible assistant output or tool activity should not look like a successful answer in Paseo.

The adapter tracks visible activity during the turn. If the kernel ends without any, the proxy returns an explicit JSON-RPC error. A visible failure is much easier to diagnose, retry, and monitor than a blank assistant message recorded as success.

5. Admission for multi-agent bursts

This was the largest operational issue.

Paseo can delegate several agents at once. If every connector immediately writes a prompt to the same account, neighboring starts can produce empty turns, hangs, or internal ACP failures. Serializing the whole controller would throw away useful concurrency, so the adapter instead fences only the provider-facing prompt write.

Admission is a durable, account-wide queue. Each turn takes a seat before its official session/prompt write and releases it on completion, failure, or cancellation. Extra turns wait rather than striking the kernel simultaneously.

The tested defaults are:

• 8 active turns
• 8 concurrent starts
• 2 seconds minimum start spacing

These are tested operating defaults, not a Google product limit. Operators can tune them. When Admission is enabled, invalid configuration, missing identity, or unsafe state-directory permissions fail closed instead of silently running without the fence.

The state is shared across connector processes, so starting more local processes does not accidentally multiply account concurrency.

6. v2.3.0 adds workspace-safe skill discovery

The newest release adds a second integration layer: local slash-command hints from SKILL.md metadata.

The adapter discovers user-invocable skills from configured and default Gemini, Agents, Codex, and workspace roots, then merges them with native command updates from the official kernel.

The merge rules matter:

• native commands win name collisions
• workspace skills override global skills
• entries marked user-invocable: false stay hidden
• discovery is scoped to the ACP session cwd
• concurrent session/new setup is serialized

That last pair prevents command metadata from one workspace appearing in another session. Version 2.3.0 also parses common quoted and multiline frontmatter forms.

The release was validated with 37 test files: 216 passed and 1 skipped. Architecture and secret checks passed, and a live official-kernel canary confirmed that native commands remained present, a visible workspace skill appeared, and a non-invocable skill stayed hidden.

Running it with npx

For a single-agent smoke test:

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 use, prepare one owner-only Admission state directory per Antigravity 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 configure a Paseo Generic ACP provider:

{
  "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, create an agent with the antigravity provider, and send a simple prompt.

npx starts the stdio ACP adapter for Paseo. It is not a standalone chat app, and it installs only the proxy. The official kernel must already exist locally. The first npm run may also need a C++ toolchain to compile better-sqlite3.

A note on additional models

The unmodified official ACP path uses the Gemini-family models exposed through the signed-in account. Accounts entitled to Claude 4.6 or GPT-OSS 120B can use the project's explicit local compatibility runbook.

That remains the same official kernel and Google backend. The repository does not vendor or replace either one.

What I would like to learn from other operators

I am looking for concrete reports from people running real multi-agent workloads:

• Which account-wide Admission settings stay reliable for your workload?
• Does skill discovery behave correctly across several simultaneous workspaces?
• Are MCP declarations normalized correctly for your servers?
• Do quota and capacity errors remain clear enough through the proxy?
• Which integration behavior belongs in a product adapter, and which should remain generic ACP behavior?

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

npm: paseo-agy-acp@2.3.0

The design goal is narrow: keep Google's official kernel responsible for provider behavior, keep Paseo responsible for orchestration, and make the boundary between them explicit, observable, and stable under multi-agent load.