agy-pilot 0.1.0__tar.gz

agy_pilot-0.1.0/.env.example

@@ -0,0 +1,20 @@
+# ==============================================================================
+# Antigravity Pilot (agy-pilot) Configuration Template
+# Copy this file to .env or ~/.config/agy-pilot/config.env
+# ==============================================================================
+
+# IM Adapter to activate (default: telegram)
+AGY_ADAPTER=telegram
+
+# Telegram Bot API Token obtained from @BotFather
+# Example: 123456789:ABCdef-ghijklm_nopqrstuvwxyz
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+
+# Whitelist of Telegram User IDs allowed to access Antigravity Pilot.
+# Get your numeric User ID by messaging @userinfobot on Telegram.
+# Supports a single ID or comma-separated list of multiple IDs.
+# Example: 12345678,87654321
+TELEGRAM_ALLOWED_USER_IDS=12345678
+
+# Logging verbosity level (DEBUG, INFO, WARNING, ERROR)
+LOG_LEVEL=INFO

agy_pilot-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: 🐛 Bug Report
+description: Create a report to help us fix an unexpected error or issue
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this bug!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Describe what bug or unexpected behavior occurred.
+      placeholder: Tell us what you see...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this issue?
+      placeholder: |
+        1. Run '...'
+        2. Send message '...'
+        3. See error '...'
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment Info
+      description: Operating System, Python version, Antigravity version, etc.
+      placeholder: |
+        - OS: macOS 15.0 / Ubuntu 24.04
+        - Python: 3.12.x
+        - Adapter: Telegram
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Log Output
+      description: Please copy and paste any relevant logs from `agy-pilot service logs` or terminal.
+      render: shell

agy_pilot-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: 💡 Feature Request
+description: Suggest an idea or enhancement for Antigravity Pilot
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a new feature or improvement!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Pain Point
+      description: Is your feature request related to a problem or limitation?
+      placeholder: I am always frustrated when...
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution / Ideal Experience
+      description: Describe what you would like to happen or how the feature should behave.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?

agy_pilot-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- Briefly explain the goal of this pull request and the changes made. -->
+
+## Motivation / Context
+
+<!-- Why is this change required? What issue does it fix? Link issue using #123. -->
+
+## Changes Checklist
+
+- [ ] Code follows project standards and clean code guidelines
+- [ ] Added or updated unit tests for the changes
+- [ ] All tests pass locally (`make test` / `make test-cov`)
+- [ ] No secrets, API tokens, or personal paths committed
+- [ ] Documentation updated if relevant (README, GLOSSARY, or docs)
+
+## How Has This Been Tested?
+
+<!-- Describe tests you ran to verify your changes. -->

agy_pilot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run test suite with coverage
+        run: uv run pytest --cov=agy_pilot --cov-report=term-missing
+
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install ruff and run lint
+        run: |
+          uv tool run ruff check .
+          uv tool run ruff format --check .

agy_pilot-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    name: Build package and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+        continue-on-error: true

agy_pilot-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+/target
+*.db
+downloads/
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env

agy_pilot-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,60 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Contact
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at `doni.leong@gmail.com`. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

agy_pilot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to Antigravity Pilot
+
+Thank you for your interest in contributing to **Antigravity Pilot (`agy-pilot`)**! We welcome bug reports, feature requests, adapter extensions, and pull requests.
+
+---
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Development Setup
+
+We use [uv](https://github.com/astral-sh/uv) as the single, fast Python package and environment manager.
+
+### Prerequisites
+* Python 3.12+
+* [uv](https://github.com/astral-sh/uv) (`curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv`)
+* Google Antigravity 2 installed locally
+
+### Setup Steps
+```bash
+# 1. Clone the repository
+git clone https://github.com/donileong/agy-pilot.git
+cd agy-pilot
+
+# 2. Synchronize virtual environment and dependencies
+uv sync
+
+# 3. Copy configuration template
+cp .env.example .env
+# Edit .env with your Telegram Bot Token & User ID
+```
+
+---
+
+## Testing & Quality Assurance
+
+Before submitting any code changes, ensure all tests pass:
+
+```bash
+# Run test suite
+make test
+
+# Run tests with coverage report
+make test-cov
+
+# Run linting with Ruff
+make lint
+```
+
+---
+
+## Implementing a New IM Adapter
+
+One of the best ways to contribute is by adding support for new Instant Messaging platforms (e.g. Discord, Slack, Feishu/Lark, DingTalk, Matrix):
+
+1. **Subclass `BaseIMAdapter`**:
+   Create a new directory in `src/agy_pilot/adapters/<platform>/` and implement `start()` and `stop()` methods:
+   ```python
+   from agy_pilot.adapters.base import BaseIMAdapter
+
+   class DiscordAdapter(BaseIMAdapter):
+       async def start(self) -> None:
+           # Initialize client, register command handlers, and begin event loop
+           ...
+
+       async def stop(self) -> None:
+           # Clean up connections
+           ...
+   ```
+2. **Register the Adapter**:
+   Add it to `src/agy_pilot/adapters/registry.py`:
+   ```python
+   from agy_pilot.adapters.registry import register_adapter
+   register_adapter("discord", DiscordAdapter)
+   ```
+3. **Write Unit Tests**:
+   Add test coverage in `tests/test_adapters.py`.
+
+---
+
+## Pull Request Guidelines
+
+1. **Branch Naming**: Use descriptive branch names:
+   - `feat/add-discord-adapter`
+   - `fix/voice-download-timeout`
+   - `docs/update-quickstart`
+2. **Commit Messages**: Follow Conventional Commits format:
+   - `feat: add Discord IM adapter support`
+   - `fix: handle reconnection gracefully on network loss`
+   - `docs: improve onboarding wizard instructions`
+3. **Keep PRs Focused**: A single PR should address a single concern.
+4. **Never Commit Secrets**: Do not commit tokens, keys, passwords, or personal absolute directory paths.

agy_pilot-0.1.0/GLOSSARY.md

@@ -0,0 +1,37 @@
+# Antigravity Pilot (agy-pilot) Glossary
+
+A headless remote controller and bridge service allowing interaction and control of local Google Antigravity 2 AI sessions via Instant Messaging platforms.
+
+## Domain Terms
+
+**Antigravity Pilot (`agy-pilot`)**:
+The headless background daemon and multi-platform bridge providing remote control of Google Antigravity 2.
+_Avoid_: Bot, proxy
+
+**Hub**:
+The local background language server instance running as `subclient_type hub` that manages IDE workspaces and session state.
+_Avoid_: Core, backend, server
+
+**Host Bridge**:
+The internal IPC URL and port pair exposed by the Hub, used to infer gRPC and agent API communication endpoints.
+_Avoid_: Gateway, proxy
+
+**AgentAPI**:
+The command-line interface subcommand of `language_server` executed to query workspaces, conversations, and send prompt steps.
+_Avoid_: API, CLI, RPC
+
+**Transcript**:
+The JSON-lines event log (`transcript.jsonl`) generated per conversation containing incremental execution steps, model thinking, and tool invocations.
+_Avoid_: History, event log, audit log
+
+**Step Tracker**:
+The state machine responsible for tailing transcript deltas, tracking tool execution progress, and debouncing status messages.
+_Avoid_: Event listener, stream handler
+
+**IM Adapter**:
+The pluggable interface and protocol adapter (e.g. Telegram, Discord, Slack) responsible for translating chat events and user commands to and from the remote controller.
+_Avoid_: Bot, connector, frontend
+
+**Session**:
+The persistent mapping between an authorized user/chat and an active Antigravity project or conversation.
+_Avoid_: Thread, connection

agy_pilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doni Leong
+
+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.

agy_pilot-0.1.0/Makefile

@@ -0,0 +1,66 @@
+.PHONY: help init run restart status logs test test-cov lint format sync update clean clean-all install-service uninstall-service
+
+help:
+	@echo "🛠️  agy-pilot (Antigravity Pilot) Management Commands:"
+	@echo ""
+	@echo "  make init              - 🧙 Interactive onboarding setup wizard"
+	@echo "  make update            - 🔄 Self-update agy-pilot to latest version & restart"
+	@echo "  make status            - 📌 Inspect daemon service status (PID, health)"
+	@echo "  make restart           - 🚀 Restart background daemon service"
+	@echo "  make logs              - 📜 Follow runtime logs"
+	@echo "  make clean             - 🧹 Clean service and logs"
+	@echo "  make clean-all         - 🗑️  Clean service, logs, database, and config"
+	@echo "  make run               - 💻 Run directly in foreground (for debugging)"
+	@echo "  make test              - 🧪 Run complete test suite"
+	@echo "  make test-cov          - 📊 Run tests with code coverage report"
+	@echo "  make lint              - 🔍 Check code quality and style with Ruff"
+	@echo "  make format            - 🎨 Auto-format code with Ruff"
+	@echo "  make sync              - 📦 Sync dependencies with uv"
+	@echo "  make install-service   - ⚙️  Install and load background daemon"
+	@echo "  make uninstall-service - 🗑️  Stop and remove background daemon"
+	@echo ""
+
+init:
+	uv run agy-pilot init
+
+clean:
+	uv run agy-pilot clean
+
+clean-all:
+	uv run agy-pilot clean --all
+
+run:
+	uv run agy-pilot
+
+restart:
+	uv run agy-pilot service restart
+
+update:
+	uv run agy-pilot update
+
+status:
+	uv run agy-pilot service status
+
+logs:
+	uv run agy-pilot service logs -f
+
+test:
+	uv run pytest
+
+test-cov:
+	uv run pytest --cov=agy_pilot
+
+lint:
+	uv tool run ruff check .
+
+format:
+	uv tool run ruff format .
+
+sync:
+	uv sync
+
+install-service:
+	uv run agy-pilot service install
+
+uninstall-service:
+	uv run agy-pilot service uninstall