> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase22-session01-antigravity-detection-data-contract/spec.md). # Session Specification **Session ID**: `phase22-session01-antigravity-detection-data-contract` **Phase**: 22 - Non-Hermes Multi-Agent Detection And Home Surfaces **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session extends AI OS local app detection so Antigravity becomes a real dual-surface local-agent signal instead of a single desktop-app boolean. The new contract must distinguish IDE and CLI availability, expose browser-safe conversation usage metadata, and provide a bounded saved-equivalent value for later usage and home ROI consumers. The work fits at the start of Phase 22 because Sessions 02 and 03 depend on a validated `detection.apps.antigravity` shape. Session 02 consumes `usage.savedEquivalent` in the usage panel and home ROI strip, while Session 03 uses Antigravity state in the Dream source-status strip. The implementation remains read-only and local-first. It must scan only safe filesystem facts from `~/.gemini/antigravity/conversations/*.pb` and `*.json`, avoid raw prompts, transcripts, paths, credential payloads, or protobuf contents, and degrade cleanly when Antigravity is absent or malformed. *** ## 2. Objectives 1. Add a typed Antigravity app-detection contract with independent IDE and CLI surfaces. 2. Scan conversation files for bounded count and last-active metadata without exposing private file paths or contents. 3. Emit `usage.savedEquivalent` in validated browser-safe live data for Phase 22 Session 02 consumers. 4. Update script/client types, validator defaults, examples, fixtures, and focused tests for absent, installed, malformed, and privacy cases. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-pricing-daily-activity-accuracy` - Provides stable pricing, daily activity, and ROI base contracts. * [x] `phase21-session02-project-windows-skill-roi-defaults` - Provides stable home and skill ROI defaults. * [x] `phase21-session03-authoritative-claude-usage-oauth` - Confirms additive usage-contract and validator patterns for browser-safe local usage data. ### Required Tools/Knowledge * Bun 1.3.14 scripts and Vitest test conventions. * Existing app detection helpers in `scripts/lib/app-detection.ts`. * Live-data type and validation contracts in `src/lib/live-data-types.ts` and `src/lib/validate-live-data.ts`. * v2.3 Antigravity reference around `scripts/aggregate.ts` lines 1833-2140. ### Environment Requirements * No local Antigravity install is required for tests. * Filesystem probes must be read-only, timeout-bounded where shell probing is used, and resilient to missing or unreadable paths. * Generated private `src/data/live-data.json` remains out of scope for committed updates. *** ## 4. Scope ### In Scope (MVP) * AI OS detects Antigravity IDE and CLI independently - Add `surfaces.ide` and `surfaces.cli` while preserving top-level `detected` and `path` compatibility. * AI OS scans Antigravity conversation usage safely - Count bounded `.pb` and `.json` files and emit last-active metadata from file mtimes only. * AI OS emits saved-equivalent value for Antigravity - Add `usage.savedEquivalent` as a bounded numeric field for Session 02. * AI OS validates additive Antigravity data - Backfill safe defaults and reject malformed or private-looking fields in browser-visible data. * AI OS examples and fixtures represent the new contract - Update committed fallback/demo data so downstream consumers can rely on the shape. * AI OS tests prove absence, IDE-only, CLI-only, both surfaces, malformed files, and privacy boundaries. ### Out of Scope (Deferred) * Usage panel Antigravity row - *Reason: Session 02 owns UI usage consumers.* * Home ROI chip and saved-equivalent math - *Reason: Session 02 owns ROI integration.* * Dream source-status strip - *Reason: Session 03 owns home surface UI.* * Raw prompt, transcript, protobuf, credential, or message-body parsing - *Reason: violates local-agent privacy boundary.* * Launching Antigravity or invoking mutating CLI behavior - *Reason: this session is read-only detection only.* *** ## 5. Technical Approach ### Architecture Add an additive Antigravity-specific contract to the existing app-detection shape. `scripts/lib/app-detection.ts` remains the scanner boundary and emits sanitized, browser-safe data under `detection.apps.antigravity`. Client-facing types in `src/lib/live-data-types.ts` mirror the additive shape, while `src/lib/validate-live-data.ts` normalizes absent and malformed payloads back to safe defaults. The detector should reuse existing helper patterns: `findMacApp` for the IDE, `resolveCliPath` plus common fallback paths for the CLI, `sanitize` for emitted paths, and fail-closed `try/catch` blocks around filesystem reads. Conversation usage should inspect only filename extensions and stat mtimes, then cap counts and values before they reach live data. ### Design Patterns * Additive live-data contract: Preserve old consumers by keeping top-level `detected` and optional `path` while adding nested `surfaces` and `usage`. * Read-only scanner boundary: Read local metadata only and never parse message contents or credentials. * Typed degradation over throws: Missing, unreadable, malformed, or unexpected Antigravity data returns safe absent/default values. * Pure validation helpers: Validate nested detection values through focused helpers so example data and generated data share the same browser contract. ### Technology Stack * Bun 1.3.14 for scripts and test execution. * TypeScript 6.0.3 for app and script contracts. * Vitest 4.1.6 for focused script and validator tests. * React 19/TanStack Start live-data consumers remain unchanged in this session. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------- | ------------------------------------------------------------------- | ---------- | | `src/lib/__tests__/antigravity-live-data.test.ts` | Focused client validation tests for Antigravity surfaces and usage. | \~120 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------- | ----------------------------------------------------------------------------------- | ---------- | | `scripts/lib/app-detection.ts` | Add Antigravity surface, conversation, and saved-equivalent scanning. | \~120 | | `scripts/lib/__tests__/app-detection.test.ts` | Cover absent, IDE-only, CLI-only, both surfaces, malformed files, and path privacy. | \~170 | | `src/lib/live-data-types.ts` | Add shared Antigravity app surface and usage types. | \~45 | | `src/lib/validate-live-data.ts` | Normalize nested Antigravity detection data and defaults. | \~90 | | `src/lib/__tests__/validate-live-data.test.ts` | Cover validator defaults and malformed Antigravity payloads. | \~80 | | `src/data/live-data.example.json` | Add safe example Antigravity contract shape. | \~20 | | `tests/e2e/fixtures/live-data.ts` | Keep browser-test fixtures aligned with the new fallback shape. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] IDE and CLI detection can be true or false independently. * [ ] Top-level `antigravity.detected` remains true when either surface exists. * [ ] Conversation count and last-active metadata are derived only from safe file stats. * [ ] `usage.savedEquivalent` is bounded and available for downstream consumers when usage data exists. * [ ] Missing or unreadable Antigravity data degrades to a safe absent state. ### Testing Requirements * [ ] Unit tests cover no install, IDE-only, CLI-only, both surfaces, conversation usage, malformed files, and privacy cases. * [ ] Client validation tests cover absent, valid, and malformed Antigravity payloads. * [ ] Focused script and app tests pass. * [ ] Manual inspection confirms no raw Antigravity paths, prompt text, transcript content, protobuf bodies, tokens, or auth payloads are emitted. ### Non-Functional Requirements * [ ] Detection remains read-only and resilient when filesystem access fails. * [ ] Browser-visible Antigravity output exposes only sanitized paths, safe counts, statuses, timestamps, and numeric saved-equivalent values. * [ ] Additive contract changes do not break existing detection consumers. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run typecheck:scripts` passes. * [ ] `bun run typecheck` passes. * [ ] Focused Vitest tests pass. *** ## 8. Implementation Notes ### Key Considerations * Keep `AppDetection` additive because setup and existing route consumers already rely on `detected`, `path`, `configPath`, `version`, and `variants`. * Use sanitized display paths only; do not expose conversation filenames or absolute conversation directory paths. * Treat the v2.3 source as reference behavior, not as code to copy wholesale. AI OS already has `resolveCliPath`, `sanitize`, and test mocks that should be preferred. * Prefer capped counts and finite numeric guards for `savedEquivalent`. ### Potential Challenges * CLI detection may vary by platform: Use `resolveCliPath("antigravity")` plus common local paths and keep absence non-fatal. * Conversation file access can be partial or unreadable: Catch per-file stat failures and still return the valid aggregate. * Validator changes can accidentally allow unsafe nested strings: Keep Antigravity-specific normalization narrow and test token/path rejection. * Example data drift can break tests: Update fallback JSON and e2e fixture data together. ### Relevant Considerations * \[P08] **Local agent privacy boundary**: Browser output may expose sanitized metadata only. This session limits Antigravity output to surfaces, counts, timestamps, and bounded value data. * \[P09] **Provider-neutral helpers stay the UI projection layer**: The contract should be usable by later home and usage selectors without route-specific parsing. * \[P02] **Typed degradation over throws**: Missing, malformed, or unreadable Antigravity inputs must normalize to safe optional states. * \[P21] **Additive live-data changes stay safest when scanner, validator, example payload, and transforms move together**: This session changes those layers in one small vertical slice. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Filesystem and CLI probes can fail or hang if not bounded. * Browser data can accidentally leak local paths, filenames, prompts, or credential-shaped strings. * Downstream consumers can break if optional Antigravity data is absent or malformed. *** ## 9. Testing Strategy ### Unit Tests * Extend `scripts/lib/__tests__/app-detection.test.ts` to mock `findMacApp`, `resolveCliPath`, `existsSync`, `readdirSync`, `statSync`, and `sanitize`. * Add/extend client validation tests for `detection.apps.antigravity.surfaces` and `usage`. * Assert malformed input drops unsafe or invalid nested values instead of throwing. ### Integration Tests * Run focused Vitest targets for script detection and live-data validation. * Run TypeScript checks for both app and script projects after contract changes. ### Manual Testing * Inspect `src/data/live-data.example.json` and `tests/e2e/fixtures/live-data.ts` for browser-safe Antigravity fields only. * Optionally run `bun run aggregate` locally and verify Antigravity absence does not fail the aggregate path. ### Edge Cases * No `.app`, no CLI, no conversation directory. * IDE installed without CLI. * CLI available without IDE. * Both surfaces installed. * Conversation directory exists but is empty. * Conversation files exist with mixed valid and unreadable stats. * Malformed live-data payload contains negative counts, invalid timestamps, raw filenames, home paths, or credential-shaped strings. *** ## 10. Dependencies ### External Libraries * No new dependencies. ### Other Sessions * **Depends on**: `phase21-session01-pricing-daily-activity-accuracy`, `phase21-session02-project-windows-skill-roi-defaults`, `phase21-session03-authoritative-claude-usage-oauth` * **Depended by**: `phase22-session02-antigravity-usage-consumers`, `phase22-session03-setup-wizard-dream-sources-strip` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase22-session01-antigravity-detection-data-contract/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.