Skip to content

feat(v2): runtime-neutral multi-runtime operating layer - #124

Draft
vudovn wants to merge 334 commits into
mainfrom
feat/lean-multiruntime-v2
Draft

vudovn wants to merge 334 commits into
mainfrom
feat/lean-multiruntime-v2

Conversation

@vudovn

@vudovn vudovn commented Sep 26, 2026 •

Copy link
Copy Markdown
Owner

Summary

This PR turns AG Kit v2 into a genuinely runtime-neutral operating layer. shared/ is canonical, runtimes/<runtime>/ owns host-specific behavior, and generated host trees are projections rather than competing sources of truth.

The architectural goal is IJFW-class multi-runtime discipline and useful feature-class parity through AG Kit's own implementation — not source-code duplication and not a single-runtime fork.

Core architecture

  • 1 resident core (ag-core)
  • 18 hot-loaded top-level skills
  • 4 permanent agents: scout, architect, builder, reviewer
  • 1 development spine with QUICK / STANDARD / DEEP modes
  • canonical runtime-neutral behavior under shared/
  • domain reference knowledge under packs/
  • runtime-specific source under runtimes/<runtime>/
  • generated host trees such as .agents/, .claude/, .gemini/, managed instruction files, and plugin folders are projections
  • no primary runtime

Runtime-neutrality cleanup

This branch removes the old assumption that AG Kit == Antigravity Kit while retaining Antigravity as a supported first-class adapter.

Removed/moved old repository-wide Antigravity source/tooling assumptions, including:

  • .agents/antigravity.json
  • Antigravity doctor / source schemas / plugin builder / adapter regression tests from generated .agents/
  • .github/workflows/antigravity.yml
  • legacy scripts/check-platform-drift.mjs
  • runtime-specific root npm validation commands and release gates

Antigravity-specific source now lives under runtimes/antigravity/; only the host projection belongs under .agents/.

The root runtime contract now rejects:

  • primary_runtime / primaryRuntime declarations;
  • runtime-specific root npm scripts;
  • runtime-specific GitHub workflow names/gates;
  • return of removed Antigravity-era source tooling into generated .agents/;
  • capability drift between platform-capabilities.json and adapter contracts;
  • public docs that instruct obsolete runtime-specific root commands.

16 runtime targets

First-class: Antigravity, Claude, Codex, Gemini, Qwen, Kimi, Cline.

Connected: Cursor, Windsurf, GitHub Copilot.

Bridge: OpenCode, OpenClaw, Aider, Wayland, Hermes, Pi.

Capabilities are declared in platform-capabilities.json; AG Kit does not claim native surfaces that an adapter cannot independently verify.

Runtime lifecycle

  • ag-kit runtime detect
  • ag-kit runtime install-present
  • explicit runtime install / doctor / uninstall
  • project-scoped installation where verified
  • pre-install backup + ownership manifests
  • doctor states: live / standing-by / degraded / untouched
  • surgical uninstall that preserves user drift and .ag-kit/memory/
  • filesystem root and user home are rejected as project roots
  • global-only configuration is staged for explicit activation instead of silently mutating home config
  • published runtime source defaults to the repository tag matching v<CLI_VERSION>; --branch is an explicit dev/ref override

Packaged lifecycle smoke

The Linux CLI job installs the real npm tarball and exercises multiple ownership/projection shapes:

  1. legacy managed-tree init → update → status, preserving a user-owned file;
  2. Antigravity install → doctor(live) → uninstall → doctor(untouched);
  3. Claude install → doctor(live) → uninstall → doctor(untouched);
  4. Codex install → doctor(live) → uninstall → doctor(untouched).

Each runtime smoke verifies ownership metadata, restoration/preservation of pre-existing user state, and persistence of project memory.

Runtime artifacts

build:runtime-artifacts is adapter-neutral. It discovers adapters that expose a real native artifact builder, validates each returned runtime/output, and emits a generic dist/runtime-artifacts/ARTIFACTS.json inventory.

No root workflow hard-codes Antigravity artifact paths. If only one runtime currently has a native package/plugin artifact, that remains an adapter capability rather than a product-wide assumption.

Engine parity

  • Markdown-first evolving memory with optional rebuildable SQLite/FTS5 index
  • temporal facts, supersession, candidate→durable promotion, dream/archive cycle
  • opt-in read-only cross-project brain
  • project-specific team assembly
  • explicit workflow artifacts, user approval gates, DEEP wave tables
  • independent read-only cross-model audit with lineage exclusion and consensus/contested findings
  • runtime-neutral preflight gates
  • MCP SDK v2 stdio bridge
  • runtime-neutral routing
  • bounded command sandbox
  • deterministic context compression with measured byte reduction
  • structured session handoff artifacts
  • bounded local observability + localhost dashboard
  • evidence-backed personalization, egress/forget controls, hard kill switch
  • portable DESIGN.md contract with 12 templates and validation

Adapter-specific native features

Richer host-native features stay behind their adapter boundary.

Examples:

  • Antigravity may project native rules, skills, agents, hooks, MCP, and plugin metadata;
  • Claude may project its native skills/agents plus project-scoped configuration;
  • Codex may project managed AGENTS.md, shared skills, and plugin/MCP surfaces;
  • lower-capability targets receive only the portable or staged surfaces AG Kit has verified.

A richer adapter does not become the product's primary runtime.

Security / integrity

  • no writable repo mount for external cross-audit reviewers
  • cross-project brain never crawls $HOME automatically
  • project-state writers reject filesystem root and user home
  • context artifact writes are realpath-contained and block symlink-parent escapes
  • runtime uninstall is ownership-aware and preserves drift/memory
  • host-native safety/observability hooks remain supplemental to host permissions and sandboxing
  • production dependency audit remains blocking
  • GitHub Actions remain pinned to immutable commit SHAs
  • public/release docs describe runtime-neutral gates and capability-aware adapters

Documentation cleanup

Updated to the v2 runtime-neutral model:

  • README.md / README-VI.md
  • AGENTS.md / CLAUDE.md
  • AGENT_FLOW.md
  • MIGRATION.md
  • SECURITY.md
  • PRODUCTION_CHECKLIST.md
  • .github/RELEASE_SETUP.md
  • docs/ARCHITECTURE_V2.md
  • docs/RUNTIMES.md
  • docs/PARITY_IJFW.md
  • cli/README.md
  • web/README.md
  • landing-page copy/testimonials

Historical Antigravity references remain only where they describe migration history or the Antigravity adapter itself.

IJFW parity posture

“Like IJFW” here means matching useful feature classes and multi-runtime operational discipline while preserving AG Kit's own code, names, lifecycle model, capability matrix, and privacy posture.

Intentional differences include:

  • no copied third-party framework source;
  • no primary runtime;
  • no silent user-global writes;
  • no automatic home-directory memory crawl;
  • no fabricated token-savings multiplier;
  • no writable cross-audit mount;
  • no capability-by-marketing-badge.

Validation

Current head validation is rerunning after the final documentation inventory fix. The PR remains Draft until the final head has complete repository evidence.

No version bump, release tag, npm publish, merge, or production deployment is performed by this refactor checkpoint.

@vercel

vercel Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ag-kit Error Error Oct 18, 2026 11:53am UTC

vudovn and others added 30 commits September 28, 2026 00:30
- Bump next and eslint-config-next 16.3.3 -> 16.4.2 (RCE, SSRF, cache
  poisoning advisories affecting <=16.3.7)
- Pin sharp override 0.35.4 -> 0.35.5 (libheif/librsvg advisories)
- Override source-map-js to 1.2.2 (indexed source-map DoS)
- Rewrite useIsMobile with useSyncExternalStore to satisfy the
  react-hooks/set-state-in-effect rule in the new eslint-config-next

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KKzPb9c4k6xHyHPWC61n1x
…, symlinks

The engine wrappers detected direct execution with
`import.meta.url === \`file://${process.argv[1]}\``, which never matches
when the path is percent-encoded (spaces, non-ASCII), on Windows drive
paths, or through a symlink, so `node engine/memory.mjs ...` exited 0
without doing anything. Add a shared realpath + pathToFileURL helper
(the same approach the Antigravity build/check scripts use) and cover it
with a regression test that runs the entrypoints from such a path.

Also align @next/mdx with next 16.4.2 and correct the [Unreleased]
security entry, which still named Next.js 16.3.3 and sharp 0.35.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KKzPb9c4k6xHyHPWC61n1x

This branch had an error being deployed

1 failed deployment
Preview — 4f43f530 Deployed Oct 18, 2026 by vercel[bot]
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.

2 participants