pi-agy-acp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 lili-luo
+Copyright (c) 2026 fdkevin0
+
+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/NOTICE

@@ -0,0 +1,10 @@
+This project adapts dsh-llm-antigravity-acp from:
+https://github.com/lili-luo/dsh-plugin-bundle
+Upstream snapshot: f0499138aa4f39531f258bcbdcebfeecbf17fbbc
+Copyright (c) 2026 lili-luo. MIT license, reproduced in LICENSE.
+
+The ACP runtime, JSON-RPC transport, MCP bridge, history projection, model
+catalog, preflight, quota reader, and runtime test fixtures derive
+from that project. Pi entry point, host process integration, local protocol
+contracts and Pi stream translation are adaptations in this repository.
+Internal bridge identifiers are renamed to pi; upstream licensing and attribution are retained.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# pi-agy-acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use Google Antigravity in Pi through the official, locally installed `agy` CLI.
+This extension registers the `antigravity-acp` provider and lets Pi execute the
+model's tool calls. It supports streaming text and reasoning, images, and
+parallel tool calls.
+
+## Prerequisites
+
+- Node.js >= 22.18.0.
+- Pi (`@earendil-works/pi-coding-agent`) 1.5.x.
+- The official `agy` CLI >= 1.4.12, signed in with your Google account.
+  Run `agy` in your terminal to complete sign-in before using the extension.
+
+## Install
+
+From GitHub (recommended):
+
+```sh
+pi install git:github.com/fdkevin0/pi-agy-acp
+```
+
+From npm:
+
+```sh
+pi install npm:pi-agy-acp
+```
+
+To install only for the current project, writing to `.pi/settings.json`:
+
+```sh
+pi install -l git:github.com/fdkevin0/pi-agy-acp
+```
+
+To try it for one invocation without saving an installation to settings:
+
+```sh
+pi -e git:github.com/fdkevin0/pi-agy-acp
+```
+
+To install a local clone for development:
+
+```sh
+git clone https://github.com/fdkevin0/pi-agy-acp.git
+pi install ./pi-agy-acp
+```
+
+See [development setup](docs/development.md) for dependencies and local testing.
+
+## Usage
+
+Start `pi`, then use `/model` to select a model under `antigravity-acp`.
+Examples include `gemini-4-argon`, `gemini-3.8-flash`, `claude-opus-5-5`,
+`claude-sonnet-5-5`, and `gpt-oss-120b-medium`. The available list refreshes
+automatically from your account.
+
+| Command | Purpose |
+| --- | --- |
+| `/agy-acp` or `/agy-acp status` | Show runtime state, account details, models, sessions, and the last turn. |
+| `/agy-acp quota` | Show a loading animation in the TUI, then account email, subscription plan, grouped 5h/weekly quota bars, and reset countdowns when available. |
+| `/agy-acp reset` | Close ACP sessions; the next request rebuilds the connection. |
+
+Update installed extensions:
+
+```sh
+pi update --extensions
+```
+
+Remove a GitHub installation:
+
+```sh
+pi remove git:github.com/fdkevin0/pi-agy-acp
+```
+
+For an npm installation, use `pi remove npm:pi-agy-acp`. Add `-l` when removing
+a project-local installation.
+
+Default prices are zero, not a promise of free calls. Pi pricing overrides are
+used when configured.
+
+## More information
+
+- [Reference](docs/reference.md): commands, configuration, stored data, model discovery, and limitations.
+- [Development](docs/development.md): setup, request flow, source layout, and verification.
+- [Attribution](NOTICE) and [MIT license](LICENSE).

package/docs/development.md

@@ -0,0 +1,104 @@
+# Development
+
+Start with the [installation guide](../README.md#install) to use the extension.
+For settings and user-visible limits, see the [reference](reference.md).
+
+For development, run these commands from your clone:
+
+```sh
+npm install
+pi -e ./index.ts
+```
+
+## Request flow
+
+1. The extension registers `antigravity-acp` with Pi. The first request starts
+   `agy acp --process-per-session` and a loopback MCP bridge.
+2. Pi messages and tool definitions are converted into an ACP prompt. The runtime
+   reuses a session when its history prefix still matches; otherwise it replays
+   the available history into a new session.
+3. Model tool calls reach the bridge and remain pending while Pi executes them.
+   Pi receives a `toolUse` result, then supplies tool results on its next request.
+4. Those results resolve the pending MCP requests, allowing the same ACP turn to
+   continue. Long-running tools use a relay to keep the agent waiting.
+5. The adapter drains the runtime's generator before publishing completion, so
+   session cleanup finishes before Pi can start its next step.
+
+Provider registration and cache-only refresh do not start processes, sockets, or
+timers. Successful session replacement is cleaned up through `session_shutdown`;
+pre-switch and pre-fork interception hooks do not reset the runtime.
+
+The bridge binds to `127.0.0.1`, uses per-session bearer credentials, and checks
+structured tool identity before granting permissions. Session changes and
+compaction trigger cleanup and rebuilding; shutdown closes processes and the bridge.
+
+## Source layout
+
+| File or group | Responsibility |
+| --- | --- |
+| `index.ts` | Provider registration, commands, and Pi lifecycle hooks. |
+| `src/pi-stream.ts`, `src/protocol.ts` | Pi message conversion and bridge event contracts. |
+| `src/runtime.ts`, `src/conversation.ts`, `src/history.ts` | Sessions, pending tool calls, streaming, and history replay. |
+| `src/acp-process.ts`, `src/jsonrpc.ts`, `src/mcp-bridge.ts` | ACP transport and local MCP server. |
+| `src/host.ts`, `src/preflight.ts`, `src/config.ts` | Process execution, executable discovery, and isolated home setup. |
+| `src/catalog.ts`, `src/quota.ts`, `src/format.ts`, `src/util.ts` | Model catalog, quota queries, TUI notice formatting, and shared utilities. |
+| `tests/` | Scripted agy fixture, runtime tests, and Pi integration tests. |
+
+Upstream provenance and licensing are recorded in [NOTICE](../NOTICE) and
+[LICENSE](../LICENSE).
+
+## Verification
+
+```sh
+npm run check
+npm test
+pi --no-extensions -e ./index.ts --list-models antigravity-acp
+```
+
+Tests run directly with Node's native TypeScript support; `tsx` is not required.
+Automated tests use a scripted local `agy` substitute so `npm test` runs offline
+without consuming account quota. They need permission to listen on `127.0.0.1`.
+
+Coverage includes tool suspension and resumption, parallel calls, permission
+checks, cancellation, history rewrites, images, quota errors, model discovery,
+account metadata caching, bounded login-log reads, and Pi stream completion.
+Listing models verifies extension loading, not access to the real service.
+
+To inspect the package contents without publishing:
+
+```sh
+npm pack --dry-run
+```
+
+## CI and releases
+
+`ci.yml` checks pull requests and pushes to `main`. `release.yml` runs only for
+version-tag pushes or manual runs on an existing tag, so ordinary commits do not
+run a second test suite or trigger publication. Both use Node.js 24. There is no
+committed lockfile, so dependency installation uses `npm install`.
+
+To release, bump `package.json`, commit the change, and push its matching
+`vX.Y.Z` tag. The workflow accepts stable versions only; publish one version at
+a time and never move a published tag. It validates the tag and version, then
+checks, tests, and packs before publishing. Only a registry 404 means the version
+is absent; network, authentication, and server errors stop the job.
+
+Configure npm [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+for owner `fdkevin0`, repository `pi-agy-acp`, and workflow filename `release.yml`.
+The workflow grants OIDC permission to the publish job and uses npm >= 11.5.1.
+An optional `NPM_TOKEN` repository secret supports token authentication through
+`NODE_AUTH_TOKEN`; use a granular write token with the required 2FA bypass.
+
+If npm publication succeeds but GitHub Release creation fails, rerun that tagged
+workflow, or use `gh workflow run release.yml --ref vX.Y.Z`. Branch-based manual
+runs are rejected. Existing npm versions are not republished, and GitHub Releases
+are created only for existing tags with `gh release create --verify-tag`.
+
+## Documentation conventions
+
+Keep all project documentation in English. Use progressive disclosure:
+
+- Keep the README focused on the first successful run and essential limitations.
+- Put operational details in the reference and implementation details in this guide.
+- Link to the relevant section instead of duplicating detailed explanations.
+- Include linked documentation in the package's `files` list.

package/docs/reference.md

@@ -0,0 +1,167 @@
+# Reference
+
+For installation and your first request, start with the [installation guide](../README.md#install).
+
+## Commands
+
+| Command | Behavior |
+| --- | --- |
+| `/agy-acp` or `/agy-acp status` | Show a status panel with runtime state, paths, sessions, model reasoning levels, and the last turn. |
+| `/agy-acp quota` | Show account details, grouped quota bars, and reset countdowns. |
+| `/agy-acp reset` | Close ACP sessions; the next request rebuilds a session from Pi's history. |
+
+Subcommands support completion with Tab. Unknown arguments display
+`Usage: /agy-acp [status|quota|reset]` as a warning.
+
+### Status panel
+
+The panel marks the runtime as idle, starting, ready, or in error. Before the first
+turn, it shows the isolated home and notes that agy has not been probed yet;
+viewing status does not start it. Models list their supported reasoning levels,
+including a fixed level where applicable.
+
+Once a turn finishes, its summary shows the model, effort, outcome (`completed`,
+`aborted`, or `error`), duration, and retry notice count when nonzero. Duration
+covers the ACP turn, including time waiting for Pi tools, but excludes startup.
+A parked tool call is still part of an active turn, not a completed turn.
+Runtime errors use an error notification; a failed last turn with an otherwise
+healthy runtime uses a warning.
+
+### Quota panel
+
+In interactive TUI mode, a bordered loader displays `Fetching Antigravity quota...`
+while the request is pending. Press Escape to cancel waiting and return to the
+editor. The underlying quota query may finish and update the cache, but its result
+will not appear after cancellation. Non-TUI modes query directly without a loader.
+
+Quota is read through `agy -p /usage --output-format json`. Each model group has
+one row per quota window, with a 12-cell bar showing the remaining fraction,
+a rounded percentage, and a relative reset time. For example:
+
+```text
+Antigravity Quota
+  Account:  user@example.com · Google AI Ultra
+
+  Gemini Models
+    Gemini Flash, Gemini Pro
+    5h      [████████████] 100% · resets in 4h 59m
+    weekly  [███████████░]  91% · resets in 6d 7h
+```
+
+Missing values display `n/a`; an elapsed reset time displays `resetting soon`.
+Severity uses the actual remaining fraction rather than the rounded percentage:
+
+| Condition | Notification |
+| --- | --- |
+| All known windows above 20% | Info |
+| Any window at or below 20%, with none at or below 5% | Warning |
+| Any window at or below 5%, or a failed quota query | Error |
+
+Errors include the reason. If cached groups are available after a failed query,
+the title marks them as `(stale)` and still displays their bars. An empty successful
+response displays `No quota data available.`.
+
+### Account details
+
+Both panels show the email and subscription plan when known. The plan comes from
+ACP session metadata and is saved in `catalog.json`. If no plan is cached, the
+first quota check also tries a tool-less ACP discovery session in parallel with
+the quota query. This starts ACP but sends no model prompt. Discovery is attempted
+once per runtime; failure still allows the quota result to appear. Use
+`/agy-acp reset` to allow another attempt. Viewing status never starts discovery.
+
+The email is read from the latest login entry in the last 64 KiB of the isolated
+home's `acp.log`; it is not saved in the model cache. With the default home only,
+the reader also checks `~/.gemini/antigravity-cli/cli.log` if needed. A custom
+`PI_AGY_HOME` never falls back to that global log. Either field appears on its own
+when the other is unavailable; the account line is omitted when neither is known.
+These details are best-effort: cached plans and login logs can be stale after an
+account change.
+
+## Configuration
+
+Set these environment variables before starting Pi:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `PI_AGY_COMMAND` | Absolute path to the `agy` executable. | Automatic discovery. |
+| `PI_AGY_HOME` | Dedicated directory for this extension's agy state. | `~/.pi/agent/cache/antigravity-acp` |
+
+For example:
+
+```sh
+PI_AGY_COMMAND=/absolute/path/to/agy pi -e ./index.ts
+```
+
+### Stored data and authentication
+
+The dedicated directory isolates the bridge agent from your normal agy tools and
+plugins. It contains agy-managed session data, logs, and the extension's model cache.
+
+Closed temporary ACP sessions have their database files and brain directories
+removed automatically. Before starting ACP, the extension also removes leftover
+session files, summary indexes, and numeric `acp.log.<pid>` backups. It retains
+the current `acp.log`, model cache, and authentication files; Pi owns the history
+used to rebuild sessions. Cleanup is best-effort if files are locked. Use a
+different `PI_AGY_HOME` for each concurrently running Pi instance, since startup
+cleanup assumes exclusive use of the directory.
+
+With file-backed authentication, the extension copies the existing OAuth token
+from your normal agy directory and sets its permissions to `0600`. Do not commit
+or share this directory. Authentication and token refresh remain agy's responsibility.
+
+## Models and context
+
+Loading the extension reads the cached model catalog, or falls back to five model
+families, without starting agy. Pi's model refresh queries ACP for the account's
+catalog once per runtime. Concurrent refreshes share one discovery session;
+after a refresh or normal session observes the live catalog, later refreshes
+reuse it. The first request also discovers models and validates the selection.
+Cache-only refreshes and refreshes already cancelled before startup do not launch
+ACP. Server-advertised models are not hidden, and live catalog changes update
+Pi's model selector. The selector exposes only the ACP reasoning levels offered
+for each model. Direct requests map `minimal` to `low` and `xhigh` or `max` to
+`high`; `off` leaves the ACP effort unspecified, using the runtime default.
+
+The fallback families are:
+
+- `gemini-4-argon`
+- `gemini-3.8-flash`
+- `claude-opus-5-5`
+- `claude-sonnet-5-5`
+- `gpt-oss-120b-medium`
+
+These entries are defaults, not a guarantee of account access. Context declarations
+are 256,000 tokens, or 131,072 for GPT-OSS. The history replay budget is 160,000 bytes;
+older history can be omitted to fit, and historical images become text placeholders.
+
+## Usage and costs
+
+Usage comes only from the ACP `session/prompt` result. Parked tool steps have no
+separate usage report; statistics arrive when the full ACP turn finishes.
+For turns spanning multiple model steps, input token buckets use the upstream
+implementation's averaging method. They are not an exact per-step measurement.
+
+Default model prices are zero because pricing is unavailable. If you configure
+Pi model pricing overrides, reported usage is priced using those rates. These
+estimates are not an invoice amount or a promise of free access.
+
+The extension does not inspect agy's private databases or invoke or distribute
+binary patch scripts.
+
+## Compatibility limits
+
+This version targets the `@earendil-works/*` Pi packages at version 1.5.x.
+Host peer dependencies use `*` as required by Pi package conventions; validation
+has been performed against version 1.5.0. Compatibility with older
+`@mariozechner/*` interfaces is not claimed.
+
+The bridge supports `onPayload` request replacement and `onProviderStreamEvent`
+observation before conversion to Pi events. At the first ACP stream event, it
+invokes `onResponse` with synthetic status `200` and empty headers before
+normalizing that event. This is a Pi instrumentation notification, not an HTTP
+response from agy. Startup errors before the first event do not emit it.
+
+Sampling parameters, output limits, forced `toolChoice`, and provider-scoped
+environment overrides are not mapped to ACP. See
+[development checks](development.md#verification) for the scope of automated validation.

package/index.ts

@@ -0,0 +1,129 @@
+import {
+  BorderedLoader,
+  type ExtensionAPI,
+  type ProviderModelConfig,
+} from '@earendil-works/pi-coding-agent'
+import { AntigravityRuntime } from './src/runtime.ts'
+import { defaults } from './src/config.ts'
+import { spawnAcp, runCommand } from './src/host.ts'
+import { streamPi } from './src/pi-stream.ts'
+import { formatQuota, formatStatus } from './src/format.ts'
+import type { QuotaSnapshot } from './src/quota.ts'
+
+export default function (pi: ExtensionAPI) {
+  const config = {
+    ...defaults,
+    command: process.env.PI_AGY_COMMAND || '',
+    home: process.env.PI_AGY_HOME || '',
+  }
+  const createRuntime = () =>
+    new AntigravityRuntime({
+      config,
+      spawnAcp,
+      runCommand,
+      log: { info: () => {}, warn: (message) => console.error(message) },
+      onModelsChanged: () => register(),
+    })
+  let runtime = createRuntime()
+  const models = (): ProviderModelConfig[] =>
+    runtime.catalog.list().map((m) => {
+      const efforts = runtime.catalog.effortsFor(m.id)
+      return {
+        id: m.id,
+        name: m.name,
+        input: ['text', 'image'],
+        reasoning: efforts.length > 0,
+        thinkingLevelMap:
+          efforts.length > 0
+            ? {
+                off: null,
+                minimal: null,
+                low: efforts.includes('low') ? 'low' : null,
+                medium: efforts.includes('medium') ? 'medium' : null,
+                high: efforts.includes('high') ? 'high' : null,
+                xhigh: null,
+                max: null,
+              }
+            : undefined,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: runtime.contextWindowFor(m.id),
+        maxTokens: 65536,
+      }
+    })
+  const register = () =>
+    pi.registerProvider(config.provider, {
+      name: config.displayName,
+      api: 'antigravity-acp',
+      baseUrl: 'acp://local',
+      apiKey: 'local-agy',
+      models: models(),
+      streamSimple: (model, context, options) =>
+        streamPi(runtime, model, context, options),
+      refreshModels: async (context) => {
+        if (context?.allowNetwork !== false && !context?.signal?.aborted) {
+          await runtime.warmup()
+        }
+        return models()
+      },
+    })
+  register()
+  const reset = async () => {
+    await runtime.dispose()
+    runtime = createRuntime()
+  }
+  pi.on('session_tree', reset)
+  pi.on('session_compact', reset)
+  pi.on('session_shutdown', async () => {
+    await runtime.dispose()
+  })
+  pi.registerCommand('agy-acp', {
+    description: 'Antigravity ACP status, quota, or reset',
+    getArgumentCompletions: (prefix) => {
+      const items = ['status', 'quota', 'reset']
+        .filter((command) => command.startsWith(prefix.trim()))
+        .map((value) => ({ value, label: value }))
+      return items.length > 0 ? items : null
+    },
+    handler: async (args, ctx) => {
+      const command = args.trim()
+      if (command === 'reset') {
+        await reset()
+        ctx.ui.notify('Antigravity ACP sessions reset', 'info')
+        return
+      }
+      if (command !== '' && command !== 'status' && command !== 'quota') {
+        ctx.ui.notify('Usage: /agy-acp [status|quota|reset]', 'warning')
+        return
+      }
+      let snapshot: QuotaSnapshot | null = null
+      if (command === 'quota') {
+        snapshot =
+          ctx.mode === 'tui' && typeof ctx.ui.custom === 'function'
+            ? await ctx.ui.custom<QuotaSnapshot | null>(
+                (tui, theme, _kb, done) => {
+                  const loader = new BorderedLoader(
+                    tui,
+                    theme,
+                    'Fetching Antigravity quota...',
+                  )
+                  loader.onAbort = () => done(null)
+                  // QuotaReader returns error snapshots, so failures also close the loader.
+                  void runtime.readQuota(true).then((result) => {
+                    if (!loader.signal.aborted) done(result)
+                  })
+                  return loader
+                },
+              )
+            : await runtime.readQuota(true)
+        if (snapshot === null) {
+          ctx.ui.notify('Quota check cancelled', 'info')
+          return
+        }
+      }
+      const notice = snapshot
+        ? formatQuota(snapshot)
+        : formatStatus(runtime.status())
+      ctx.ui.notify(notice.text, notice.level)
+    },
+  })
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "pi-agy-acp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "Google Antigravity ACP provider extension for Pi Coding Agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fdkevin0/pi-agy-acp.git"
+  },
+  "homepage": "https://github.com/fdkevin0/pi-agy-acp#readme",
+  "bugs": {
+    "url": "https://github.com/fdkevin0/pi-agy-acp/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "docs",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "antigravity",
+    "agy",
+    "acp"
+  ]
+}