paseo-acp-agy 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Melo
+
+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/PROTOCOL.md

@@ -0,0 +1,149 @@
+# Protocol Specification & Mapping: Antigravity stream-json ↔ ACP
+
+`agy-acp` exposes the official Google Antigravity CLI (`agy`) to Paseo through ACP while keeping authentication and model execution inside the official CLI.
+
+## Antigravity process
+
+Each Paseo ACP session owns one persistent `agy` process:
+
+```bash
+agy --input-format stream-json --output-format stream-json --print=""
+```
+
+Optional session flags are applied when the process starts or is restarted:
+
+- `--model <model-id>`
+- `--effort <low|medium|high>` when supported by the selected model
+- `--mode <mode-id>`
+- `--conversation <conversation-id>` when resuming
+- `--sandbox`
+- `--dangerously-skip-permissions` only when explicitly configured
+
+Configuration changes schedule a controlled restart before the next prompt. On POSIX systems `agy` is launched as a process-group leader; shutdown, restart and turn cancellation signal the process group so tool subprocesses are not left orphaned.
+
+## Antigravity stream-json
+
+### Input
+
+One NDJSON object per user turn:
+
+```json
+{"event":"user","message":{"content":"User prompt"}}
+```
+
+### Output
+
+`agy` emits NDJSON events:
+
+- `init` — process/session metadata and `conversation_id`
+- `step_update` — streaming assistant text, thoughts, tool calls and usage
+- `result` — terminal result for a prompt turn
+
+One open stdin/stdout stream is reused for multiple turns.
+
+## ACP wire methods
+
+The ACP wire protocol uses snake_case method names. `agy-acp` accepts these methods:
+
+| ACP method | agy-acp behavior |
+|---|---|
+| `initialize` | Advertise provider/session capabilities |
+| `session/new` | Create a new isolated session |
+| `session/resume` | Restore and validate a persisted ACP session without history replay |
+| `session/prompt` | Send a prompt to the persistent `agy` process |
+| `session/cancel` | Cancel the reserved/running turn; signal the `agy` process group when running |
+| `session/close` | Persist state and terminate the process tree |
+| `session/set_mode` | Change mode; restart before the next turn if needed |
+| `session/set_model` | Change base model; restart before the next turn if needed |
+| `session/set_config_option` | Change `thought_level` / reasoning effort |
+| `session/update` | Stream messages, thoughts, tool calls, usage and commands to Paseo |
+| `provider/usage` | Return current Antigravity quota and credit state |
+
+For backwards compatibility, the server also accepts the exact pre-hardening aliases:
+
+- `setSessionMode`
+- `unstable_setSessionModel`
+- `setSessionConfigOption`
+
+### `session/load`
+
+`agy-acp` currently advertises `loadSession: false`. ACP `session/load` requires the agent to replay prior conversation history through `session/update` notifications. The adapter intentionally does not claim that capability until replay is implemented. Paseo persistence uses `session/resume`, which restores model context without replaying already-rendered history.
+
+## Turn concurrency and cancellation
+
+A session-level prompt operation is reserved synchronously before any slash-command or process startup/restart `await`. Therefore:
+
+- a second `session/prompt` cannot enter while `/resume`, `/usage`, or another asynchronous slash command is running;
+- a second prompt cannot enter during first-turn startup;
+- cancellation received during startup prevents the user prompt from ever being written to `agy` stdin;
+- stale child events cannot resolve or reject a newer turn;
+- each active process turn tracks the exact child process that owns it;
+- the session prompt reservation is always released in `finally`, for both slash-command and ordinary prompt paths.
+
+## Models and thinking effort
+
+`agy-acp` discovers models through `agy models`. Model variants ending in `-high`, `-medium` or `-low` are exposed as a base model plus a separate ACP `thought_level` config option. Discovery is cached for one minute per `agy` binary path, with a fallback list if discovery fails.
+
+## Session persistence and resume validation
+
+ACP session metadata is stored outside the repository under:
+
+```text
+${XDG_STATE_HOME:-~/.local/state}/agy-acp/sessions/
+```
+
+Each session is stored in its own `0600` JSON file inside a `0700` directory. Persisted state contains only:
+
+- ACP `sessionId`
+- Antigravity `conversation_id`
+- cwd
+- model
+- effort
+- mode
+- accumulated token/cost/context usage
+- update timestamp
+
+No Google credentials or OAuth tokens are read or persisted by the adapter.
+
+When Paseo requests `session/resume`, the adapter starts `agy --conversation <id>`, waits for its `init` event, and verifies that Antigravity actually opened the requested conversation before returning success.
+
+## Token usage, context window, cost and quota
+
+- Cumulative `inputTokens`, `outputTokens`, `cachedInputTokens` and `totalTokens` are persisted per ACP session.
+- Usage from a completed Antigravity `result` is recorded even when the turn ends with `status: ERROR`, because model/tool work may already have consumed billable tokens.
+- The model used for cost calculation is snapshotted at the beginning of the prompt operation. A `session/set_model` received mid-turn applies to the next Antigravity process, without repricing the current turn.
+- Raw session cost is accumulated without per-turn rounding. Rounding occurs only in UI-facing ACP payloads, preserving micro-costs across many small turns.
+- Context-window limits are attached to model definitions and streaming usage updates.
+- `fetchAntigravityUsage()` treats `/usage` as the primary availability probe. A failed, timed-out or missing `agy` command returns `status: unavailable` with an error instead of a false zero-usage `available` result.
+- `/credits` failure is treated as partial data loss when `/usage` succeeds: quota remains available, balances are omitted and the error explains the missing credit data.
+
+## Child-process lifecycle
+
+- One ACP session = one `agy` process tree.
+- On POSIX, the child is a process-group leader and signals target the whole group.
+- A child being replaced is terminated and awaited before a replacement is spawned.
+- `SIGTERM` is used first; `SIGKILL` follows a bounded timeout.
+- Child event handlers are identity-checked so an old process cannot alter a newer process.
+
+## Attachments
+
+Inline base64 images are written under the adapter state directory with `0600` permissions and a content-addressed file name. The adapter:
+
+- accepts only known image MIME types;
+- validates base64 by decode/re-encode equivalence;
+- enforces a default 20 MiB decoded-size limit (`AGY_ACP_MAX_ATTACHMENT_BYTES` can override it);
+- converts valid `file://` URIs with Node's URL parser.
+
+## Slash commands
+
+The adapter intercepts selected local commands such as `/resume`, `/usage`, `/credits`, `/skills`, `/agents`, `/changelog` and `/help`.
+
+- Resume identifiers are validated before filesystem lookup.
+- Paseo session IDs resolve through the persisted session store rather than by scraping logs.
+- `/resume` stats all conversation candidates first and reads transcript contents only for the newest requested entries.
+- `/resume <id>` validates the Antigravity conversation before reporting success.
+- Subprocess-based slash commands use bounded timeouts and output buffers.
+
+## CI
+
+`.github/workflows/agy-acp.yml` runs `npm ci`, `npm audit --omit=dev --audit-level=high`, `npm run typecheck` and `npm test` for changes under `tools/agy-acp`.

package/README.md

@@ -0,0 +1,137 @@
+# paseo-acp-agy
+
+> **Agent Client Protocol (ACP)** provider adapter connecting **Google Antigravity (`agy`)** to **[Paseo](https://paseo.sh)**, **Zed**, and any ACP-compliant agent client over stdio.
+
+[![CI](https://github.com/tucomel/paseo-acp-agy/actions/workflows/ci.yml/badge.svg)](https://github.com/tucomel/paseo-acp-agy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Overview
+
+`paseo-acp-agy` allows you to use Google Antigravity as a first-class agent provider inside Paseo. It implements the JSON-RPC [Agent Client Protocol](https://agentclientprotocol.com) over standard input/output (`stdio`), dynamically exposing supported models, tracking session token usage, calculating real-time cost, displaying context window usage, and supporting slash commands.
+
+### Features
+- **Zero-Downtime Daemon Compatibility**: Conforms to the [Paseo Server & CLI specification](https://paseo.sh/docs#server--cli). Updates to this adapter apply to future agent launches without restarting the Paseo daemon.
+- **Dynamic Model Catalog**: Exposes Google Gemini (Flash, Pro) and Anthropic Claude models configured in your Antigravity CLI environment.
+- **Usage & Quota Telemetry**: Real-time context window meters, prompt/output token tracking, pricing windows, and quota limit notifications.
+- **Session Management**: Native support for session modes (Default / Plan mode), session cancellation, and resume.
+- **Slash Commands**: In-session support for `/help`, `/usage`, and `/resume`.
+
+---
+
+## Quick Start in Paseo
+
+### 1. Configure Provider in Paseo
+
+Add `antigravity` under `agents.providers` in your `~/.paseo/config.json`:
+
+```json
+{
+  "agents": {
+    "providers": {
+      "antigravity": {
+        "extends": "acp",
+        "label": "Antigravity",
+        "command": ["npx", "-y", "paseo-acp-agy", "--acp"],
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+> **Local / Development Setup:**
+> If you cloned this repository locally, you can compile and point directly to the binary:
+> ```json
+> "command": ["node", "/path/to/paseo-acp-agy/dist/index.js"]
+> ```
+> Or install globally:
+> ```bash
+> npm install -g paseo-acp-agy
+> ```
+> And configure `"command": ["paseo-acp-agy"]`.
+
+### 2. Reload Paseo Configuration
+
+Apply changes immediately without restarting the daemon:
+
+```bash
+paseo reload
+```
+
+### 3. Verify with Diagnostics
+
+Run the official Paseo provider diagnostic command:
+
+```bash
+paseo provider diagnostic antigravity
+```
+
+List detected models:
+
+```bash
+paseo provider models antigravity
+```
+
+### 4. Run an Agent
+
+Launch a task directly from your terminal:
+
+```bash
+paseo run --provider antigravity "Analyze the repository architecture"
+```
+
+Or select **Antigravity** from the provider dropdown in the Paseo Desktop App or Web UI (`https://app.paseo.sh`).
+
+### 5. Official Paseo Catalog Entry
+
+To include `paseo-acp-agy` in Paseo's built-in provider store (`ACP_PROVIDER_CATALOG`), see the [Paseo Catalog Specification](docs/paseo-catalog-entry.md).
+
+---
+
+## Requirements
+
+- **Node.js**: >= 20.0.0 (Node.js 22 recommended)
+- **Google Antigravity CLI (`agy`)**: Installed and authenticated in your `PATH` (or specified via `AGY_BIN_PATH`).
+- **Paseo**: [Paseo CLI / Daemon](https://paseo.sh/docs#server--cli) (`@getpaseo/cli`) >= 0.7.0.
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `AGY_BIN_PATH` | Path to the Google Antigravity binary | Auto-detected from `PATH` or `~/.local/bin/agy` |
+| `AGY_ACP_LOG_FILE` | Enable debug file logging | Disabled |
+
+---
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/tucomel/paseo-acp-agy.git
+cd paseo-acp-agy
+
+# Install dependencies
+npm install
+
+# Typecheck
+npm run typecheck
+
+# Run test suite (56+ unit & protocol tests)
+npm test
+
+# Build distribution
+npm run build
+
+# Test ACP initialization via stdio
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}\n' | node dist/index.js
+```
+
+---
+
+## License
+
+MIT © [Arthur Melo](https://github.com/tucomel)

package/dist/acp-server.d.ts

@@ -0,0 +1,28 @@
+import { Readable, Writable } from "node:stream";
+import { SessionManager } from "./session.js";
+export declare class ACPServer {
+    private sessionManager;
+    private input;
+    private output;
+    private binaryPath;
+    private rl;
+    private isRunning;
+    constructor(options?: {
+        input?: Readable;
+        output?: Writable;
+        sessionManager?: SessionManager;
+        binaryPath?: string;
+    });
+    start(): void;
+    private send;
+    private sendNotification;
+    private sendSuccess;
+    private sendError;
+    private publishCommands;
+    private sessionState;
+    private requireSession;
+    private validateModel;
+    private turnUsagePayload;
+    private handleLine;
+    stop(): Promise<void>;
+}