Astra — Persistent AI Entity Runtime

Astra is a persistent intelligent entity living inside a capability-driven runtime: an agent with identity, memory, goals, and a body that survives restarts, spans surfaces (browser widget, desktop companion, phone, headless home server), and acts only through declared, typed, permissioned capabilities. The unit of the system is not a conversation but the entity — one mind, many bodies, local-first by constraint, with every deliberation reconstructable from a typed event journal.

• Version: 0.0.1 — single source platform/shared/src/version.ts:1 (ASTRA_VERSION) → package.json:3 / apps/desktop/src-tauri/tauri.conf.json:4 / apps/desktop/src-tauri/Cargo.toml:3
• Status: Production Release v0.0.1 — Phases 1–4 CLOSED (122/122 + 31/31, tsc 0×6, vite 68 modules, verify-packaged-runtime READY)

Read this first

• Architecture overview — layers, principles P1–P10, normative schemas, module ownership.
• AIRI structural analysis — the evidence corpus this clean-sheet design is built against (what to keep, what to make structurally impossible).
• Foundational ADR — the seven decisions everything else cites.
• Production Release v0.0.1 completion — Phases 1–4 verification matrix + probed links
• Licenses — third-party NOTICES (better-sqlite3, three, three-vrm, sqlite-vec, onnxruntime)

Quick start

pnpm install        # workspace install (pnpm required, 23 allowBuilds incl. better-sqlite3/sqlite-vec/onnxruntime)
pnpm check          # tsc --noEmit over all kernel sources (0×6 incl. mobile + studio)
pnpm test           # vitest 122/122 (unit + integration + packaged-runtime + oracle-realness + bench-smoke)
npx vitest run --config tests/simulation/vitest.config.ts  # simulation 31/31 seeded, byte-stable
pnpm dev            # vitest watch

build and lint fan out per-package via pnpm -r --if-present; bundler and eslint configs land with the first real packages (ADR-0001 keeps the stack TypeScript end-to-end).

Release install (Tauri)

pnpm install
pnpm deploy:runtime          # deterministic pnpm deploy → dist/runtime (better-sqlite3 13.0.3 + sqlite-vec 0.1.9)
node scripts/generate-native-inventory.mjs   # manifest probe
node scripts/verify-packaged-runtime.mjs     # SQLite READY · vector library READY · vector ops READY · hybrid READY
node apps/desktop/scripts/make-sidecar.mjs   # stage natives → apps/desktop/src-tauri/resources/
cargo build --manifest-path apps/desktop/src-tauri/Cargo.toml  # or: tauri build (msi/dmg/deb per OS, updater deferred)

CI proves the same on ubuntu-latest + windows-latest — see .github/workflows/ci.yml packaging gate (deploy → inventory → verify → sidecar → cargo build → upload-artifact) + docs/development/ci.md.

Layout

Path	Contents
runtime/core	@entity/runtime-core — entity principal, lifecycle, logger
runtime/events	@entity/spine — event envelopes, topic registry, bus
runtime/scheduler	@entity/scheduler — jobs-as-data time service
runtime/persistence	@entity/storage — SQLite (better-sqlite3 WAL/FTS5 + sqlite-vec vec0) + checkpoint/journal
platform/shared	@entity/platform-shared — ASTRA_VERSION, RuntimePaths jail (getDataDir/getModelsDir/getDatabasePath via isInside)
platform/audio	@entity/platform-audio — WebCapture → Vad → Stt/Tts (Whisper/Kokoro injectable, 4-state health)
presentation/vrm	@entity/presentation-vrm — three@0.162 + @pixiv/three-vrm@3.5.5 (VRMUtils, springBone)
apps/desktop	@astra/desktop-tauri — Tauri shell (vite 68 modules, catppuccin glass stage-centric)
apps/web	@astra/web-client — web thin client (vite 68 modules, same shell-layout)
apps/mobile	@astra/mobile-capacitor — Capacitor shell (5175, capacitor bridge shim)
apps/studio	@astra/studio — dev studio (5176, entity/trace/memory/plugin inspectors)
plugins/minecraft	@entity/minecraft — observer→bot MinecraftBackend injectable (Mineflayer wiring note)
plugins/browser	@entity/browser — Playwright-like BrowserBackend injectable (capability browser.read/navigate/interact)
plugins/computer-use	@entity/computer-use — DesktopInteraction (desktop.observe/interact) composable
engines/astra-godot-bridge	deferred Godot VRM bridge — README placeholder with getModelsDir() contract (OFL font vendoring deferred)
tools	@astra/tools — real CLI (astra daemon/dev/doctor/entity/memory/plugin/runtime/trace)
docs/	architecture, decisions, research, roadmap (incl. production-release-v0.0.1-completion.md)

Kernel code imports downward only (spine at the bottom); no presentation concepts, provider/vendor types, or renderer parameters appear in any kernel module (runtime.md §9). See CONTRIBUTING.md for governance + release flow.