Skip to content

feat(agy): Persistent single-process driver, stream-json protocol, auto-retry & dual-engine architecture - #1709

Open
prophetw wants to merge 12 commits into
slopus:mainfrom
prophetw:feat/agy-stream-json-adapter
Open

feat(agy): Persistent single-process driver, stream-json protocol, auto-retry & dual-engine architecture#1709
prophetw wants to merge 12 commits into
slopus:mainfrom
prophetw:feat/agy-stream-json-adapter

Conversation

@prophetw

Copy link
Copy Markdown

Summary

This PR overhauls the Antigravity (`agy`) adapter in Happy CLI, upgrading it from a per-turn spawned CLI runner to a **native, long-lived persistent single-process architecture** with full **Stream-JSON** protocol support, **automatic network error

recovery**, session title extraction, and a dual-engine backend (Persistent CLI + Python SDK).

---

## Key Improvements & Features

### 1. 🚀 Native Persistent Single-Process Driver (`AgyBackend`)
- **Zero Cold Start**: Uses `agy --input-format stream-json --output-format stream-json` with native stdin event dispatch (`{"event":"user","message":{"content":"..."}}`).
- The `agy` subprocess is spawned **once** during `startSession` and kept alive throughout multi-turn conversations (PID remains unchanged).
- Multi-turn turn latency drops from **4~6s** (due to keyring re-reading and eligibility checks) to **~1.0s**.
- Automatic recovery: if the subprocess exits unexpectedly between turns, it is automatically respawned and seamlessly resumes via `--conversation <id>`.

### 2. ⚡ Full Stream-JSON Protocol & Deterministic Context Binding
- Replaced fragile filesystem scanning (`last_conversations.json`) with deterministic extraction of `conversation_id` directly from `agy`'s first `init` event.
- Binds `agyConversationId` to Happy's Session metadata and ACP envelopes.
- Full streaming support for:
  - Text token deltas (`model-output`)
  - Extended thinking / reasoning logs (`event: thinking`)
  - Tool calls & tool execution results (`tool-call`, `tool-result`)
  - Token counts and usage stats (`token_count`, `result`)

### 3. 🛡️ Auto-Retry on Transient Startup / Eligibility EOF Errors
- Built-in exponential backoff retry for transient network errors during startup (e.g., `Eligibility check failed: ... EOF`, TLS timeouts, rate limits).
- Completely eliminates transient startup error banners on mobile/web UI.

### 4. 🏷️ Automatic Session Title & Summary Generation
- Extracts clean summaries from the initial user prompt and persists them to session metadata (`metadata.summary`), ensuring named sessions in the conversation drawer.

### 5. 🔌 Dual-Engine Architecture (`createAgyBackend` & `AgySdkBackend`)
- **CLI Engine (Default / Google OAuth Subscription)**: Zero configuration required for Google subscription accounts via `agy` CLI binary.
- **SDK Engine (`google-antigravity` Python SDK)**: Persistent WebSocket bridge (`bridge/server.py`) activated automatically when `GEMINI_API_KEY` is provided or `HAPPY_AGY_ENGINE=sdk`.

---

## Architecture Overview

```text
┌─────────────────────────────────────────────────────────────┐
│ Happy Session Runner (Persistent)                           │
│                                                             │
│   createAgyBackend Factory                                  │
│     ├── AgyBackend (Persistent Stream-JSON CLI Engine)      │
│     └── AgySdkBackend (Persistent WebSocket Python SDK)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ stdin / stdout NDJSON
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ agy CLI / Python Bridge (Single Process, PID unchanged)     │
│   • Turn 1: Handshake & generate                            │
│   • Turn 2: Stdin dispatch -> 1s instantaneous streaming   │
│   • Turn N: Full context preserved in memory                │
└─────────────────────────────────────────────────────────────┘

──────

Testing & Verification

[✓] Unit Tests:
• src/agy/AgyBackend.test.ts (persistent multi-turn lifecycle & auto-retry)
• src/agy/AgySdkBackend.test.ts (Python bridge streaming & tool calls)
• src/agy/createAgyBackend.test.ts (engine resolution logic)
• src/agy/streamJson.test.ts (NDJSON event parser)
• src/agy/discoverModels.test.ts (model catalog discovery)
• src/agy/title.test.ts (summary extraction)
[✓] Full CLI Suite: All 88 test files (819+ unit tests) passed 100%.
[✓] End-to-End Live Testing:
• Verified multi-turn live conversation with Google subscription account over stdio NDJSON.
• Verified instant token generation on consecutive turns in a single PID.
• Tested daemon startup and remote mode synchronization with Happy Web/Mobile.

@prophetw prophetw changed the title Feat/agy stream json adapter feat(agy): Persistent single-process driver, stream-json protocol, auto-retry & dual-engine architecture Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant