oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moving

Browse Source
This commit is contained in:
Oleg Maslov
2026-09-02 10:14:22 +02:00
parent 0c3e2ead3b
commit b20b138fe4
771 changed files with 161561 additions and 9027 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
AGENTS.md
View File

@@ -16,8 +16,9 @@ If you're about to write code, **Section 3** is the most important thing you'll
## 1. What Waggle OS Actually Is
**Waggle OS** is a workspace-native AI agent platform with persistent memory. It ships as a
Tauri 2.0 desktop binary for Windows and macOS, with a Vite-bundled web app and a Node.js sidecar.
**Waggle OS** is a workspace-native AI agent platform with persistent memory. The active release
candidate is a Windows-first Tauri 2.0 desktop app with a Vite-bundled web UI and a bundled Node.js
sidecar. macOS packaging, signing, notarization, and runtime certification are roadmap work.
**Strategic function:** Waggle is the demand-creation and qualification engine for KVARK —
Egzakta Group's sovereign enterprise AI platform.
@@ -38,23 +39,52 @@ Egzakta Group's sovereign enterprise AI platform.
and connectors are all free (they generate memory). Team collaboration (shared memory,
WaggleDance, governance) is the upgrade trigger.
### Key Technology Facts (Verified April 2026)
### Current Release Qualification Contract (2026-08-22)
- Launch gate: **Windows Solo only**.
- In-scope external-agent release cohort: **Claude Code, Codex, and Hermes**. Each integration
uses the user's own installed client and its official user authentication.
- **Cursor and OpenClaw are roadmap-only**: detection metadata may remain, but production launch,
hooks, Fleet/task dispatch, and direct run routes must fail closed for them.
- Claude Desktop, Codex Desktop, and Hermes Desktop may remain as detected convenience launch
surfaces; they are not separate memory-hook or agent-acceptance targets in this release gate.
- ChatGPT/OpenAI is a model/provider and memory-import surface, not a separate launcher target.
- The Windows Solo qualification receipt must prove the bundled Node sidecar, no-Python
OpenAI-compatible proxy, Waggle-managed local runtime/model, default in-process embedding path,
and freedom from developer Node, Docker, Python, external LiteLLM, or a separately installed
Ollama. A separate revision-bound receipt must prove smart-router primary, compact-tool-context,
budget, and fallback paths and may carry forward only under the launch recommendation's bounded
no-impact rule; user-installed Ollama remains optional.
- Persona release evidence requires a complete 10-persona x 3-run collection with every result
at or above 95/100 after any explicitly documented independent semantic adjudication, plus a
final-HEAD no-impact attestation or a fresh 30/30 rerun when intervening behavior changed. Never
relabel a non-gating collection as a canonical deterministic seal.
- Do not claim release approval until the current launch recommendation's exact-HEAD gates pass.
- Exact candidate revisions, installer hashes, local receipt hashes, carry-forward limits, and the
current verdict live only in `docs/production-readiness/09-LAUNCH_RECOMMENDATION.md`. Do not copy
an old candidate's evidence forward merely because a later branch contains its commits.
- Public GO still requires a publicly trusted Authenticode artifact and a sealed managed Deep
Security report for the exact approved release-tag commit, with no unresolved Critical/High.
- The repository remains private until an explicit open-source and licensing decision is made.
### Key Technology Facts (Verified August 2026)
| Layer | Stack |
|---|---|
| Frontend | React **19** + TypeScript + Vite + Tailwind 4 + base-ui/react |
| Desktop | Tauri 2.0 (Rust shell) |
| Backend | Fastify sidecar (Node.js, bundled into Tauri) |
| LLM routing | LiteLLM (see `litellm-config.yaml`) |
| LLM routing | Bundled no-Python OpenAI-compatible proxy for Windows Solo; optional LiteLLM deployment config |
| Database | SQLite via @waggle/core (better-sqlite3 + sqlite-vec-windows-x64) |
| Memory | FrameStore + HybridSearch + KnowledgeGraph + IdentityLayer + AwarenessLayer |
| Agent runtime | `packages/agent/src/agent-loop.ts` |
| Billing | Stripe (installed; `stripe@^21.0.1`) |
| Design | Hive DS — honey #e5a000 / hive-950 #08090c / accent #a78bfa |
| Tests | Vitest (unit) + Playwright (E2E) |
| Deploy | Dockerfile + docker-compose.production.yml + render.yaml |
| Deploy | Windows Tauri installer; optional Dockerfile + docker-compose.production.yml + render.yaml |
Package manager: npm (root) with `bun.lock` also present. Node >= 20.
Package manager: npm with the root `package-lock.json`. Source development requires Node
`^20.19.0 || >=22.12.0`; the packaged Windows desktop runtime is pinned to Node `22.23.2`.
---
@@ -67,7 +97,7 @@ waggle-os/
├── apps/
│ ├── web/ # <-- MAIN web app UI (this is where most components live)
│ └── www/ # Landing page (waggle-os.ai)
├── packages/ # 16 workspace packages (see below)
├── packages/ # 28 workspace packages (see below)
├── sidecar/ # Node.js sidecar bundled into Tauri
├── scripts/ # build-sidecar, bundle-native-deps, bundle-node
├── tests/ # Cross-cutting integration tests
@@ -81,7 +111,7 @@ waggle-os/
└── package.json (workspaces: apps/*, packages/*)
```
### Packages (`packages/`, 27 workspaces — verified 2026-05-28)
### Packages (`packages/`, 28 workspaces — verified 2026-08-02)
```
Core (15):
admin-web cli launcher marketplace
@@ -89,15 +119,15 @@ agent core memory-mcp optimizer
sdk server shared waggle-dance
weaver wiki-compiler worker
hive-mind OSS split (12 — synced to marolinik/hive-mind, see §7.5):
hive-mind OSS source set (13 — curated forward-port target is marolinik/hive-mind; see §7.5):
hive-mind-core hive-mind-cli hive-mind-shim-core hive-mind-mcp-server
hive-mind-wiki-compiler
hive-mind-hooks-{Codex, Codex-desktop, codex, codex-desktop,
hive-mind-wiki-compiler hive-mind-hooks-core
hive-mind-hooks-{claude-code, claude-desktop, codex, codex-desktop,
cursor, hermes, openclaw}
```
> Note: the prior list said "16" and included `ui`, which has no `package.json`
> (not a workspace). Real count is 27. The 12 `hive-mind-*` packages were added
> since the April verification.
> (not a workspace). The live count is 28: 15 product packages and 13
> `hive-mind-*` packages.
### `packages/agent/src/` — MOST ACTIVE (94 .ts files + 4 subdirs)
@@ -152,10 +182,11 @@ Subdirs:
MOVED (2026-04-30 monorepo migration): the memory substrate `mind/` (db/schema/
identity/awareness/frames/sessions/search/knowledge/scoring/reconcile/ontology/
concept-tracker/entity-normalizer/evolution-runs/execution-traces/
improvement-signals/embedding-provider/*-embedder) and `harvest/` (chatgpt/Codex/
Codex/gemini/perplexity/pdf/plaintext/markdown/url/universal adapters +
improvement-signals/embedding-provider/*-embedder) and `harvest/` (chatgpt/claude/
claude-code/gemini/perplexity/pdf/plaintext/markdown/url/universal adapters +
pipeline.ts + dedup.ts) now live at **packages/hive-mind-core/src/{mind,harvest}/**,
NOT under packages/core/. The OSS mirror is generated from there via subtree-split (§7.5).
NOT under packages/core/. The OSS mirror is curated from there through a maintainer-reviewed
forward-port (§7.5); raw subtree branches are never publish sources.
```
For the deep-dive on what the mind/ substrate does, see [`docs/memory-architecture.md`](docs/memory-architecture.md).
@@ -219,6 +250,35 @@ npm run lint
> run the `packages/server` tsc above. (A real type error slipped through this
> way on 2026-05-28; see `docs/addictiveness-audit-2026-05-28/REDUNDANCY-AUDIT.md`.)
### Windows Solo release commands (PowerShell 7; frozen clean checkout)
```powershell
# Local build-host preparation (the installed desktop has none of these prerequisites).
npm ci
npm ci --prefix app --ignore-scripts
npm run build:packages
# Local unsigned smoke build only; this is not a releasable artifact.
npm --prefix app run tauri:build:win
# Optional internal-pilot build. Its private test root is not public trust.
npm --prefix app run tauri:build:win:pilot-signed
# Certify an internal candidate under a disposable Windows profile.
pwsh -NoProfile -File scripts/certify-windows-installer.ps1 `
-InstallerPath "<absolute-path-to-Waggle-setup.exe>" `
-ExpectedSourceRevision "<40-character-final-HEAD>" `
-VerifyManagedModel
```
Production signing is hosted-only. Do not use a local thumbprint, client secret, or
`sign-windows-artifact.ps1` substitute to create a release artifact. The exact-tag
`.github/workflows/release.yml` Azure OIDC chain is authoritative for production signing,
certification, attestation, and publication. Never treat an unsigned or internal-pilot build
as publicly trusted.
The certified installed desktop must not depend on developer Node.js, Python,
Docker, external LiteLLM, or a separately installed Ollama.
---
## 3. Behavioral Rules — How You Must Work
@@ -379,7 +439,7 @@ interface AgentPersona {
// guardrails + picker metadata (all optional, all shipped)
disallowedTools?: string[] // denylist — overrides tools[] on conflict
failurePatterns?: string[] // documented failure modes — shown in hover tooltip
isReadOnly?: boolean // true = no write tools ever (enforced in assembleToolPool)
isReadOnly?: boolean // true = no write tools after applyPersonaToolFilter/filterMcpToolsForPersona
tagline?: string // one sentence for picker hover
bestFor?: string[] // 3 example tasks in user-facing language
wontDo?: string // hard boundary statement
@@ -418,7 +478,7 @@ shows tagline + bestFor + wontDo. "Create Custom Persona" inline form POSTs to
## 7. Security Constraints (Non-Negotiable)
1. **Vault-only secrets.** API keys in Vault or `.env` (never committed). `.env.example` has key names only.
1. **Vault-only secrets.** API keys belong in Vault or an untracked local `.env`, never in Git. `.env.example` may contain non-secret development defaults, but never usable credentials or secrets.
2. **Injection defense.** `scanForInjection()` from `injection-scanner.ts` MUST be called on all connector/external input.
3. **No eval, no dynamic require.** Tauri WebView is restricted.
4. **Tauri IPC allowlist.** Explicit in `app/src-tauri/capabilities/`. Never `allowlist: all: true`.
@@ -428,7 +488,7 @@ shows tagline + bestFor + wontDo. "Create Custom Persona" inline form POSTs to
---
## 7.5. Memory Substrate Sync (waggle-os → hive-mind, subtree-split)
## 7.5. Memory Substrate Sync (waggle-os → hive-mind, curated forward-port)
The memory substrate lives at **`packages/hive-mind-core/src/{mind,harvest}/`** (moved from
`packages/core/src/` in the 2026-04-30 monorepo migration). The public OSS mirror at
@@ -443,14 +503,16 @@ directly on the OSS mirror.** Parity is NOT automatic — it broke once: the cro
(`inprocess-reranker.ts` + HybridSearch options) was written directly on `marolinik/hive-mind`
during the LoCoMo benchmark arc and existed ONLY there, discovered by the W4 recon and
reverse-ported in W4.2 (`f47ee8f`). Rules:
1. Substrate changes land in `packages/hive-mind-core/` here FIRST; the mirror is regenerated
via subtree-split afterward.
1. Substrate changes land in `packages/hive-mind-core/` here FIRST; the mirror is updated
through a reviewed, maintainer-curated forward-port afterward.
2. Benchmark/experiment work in a `D:/Projects/hive-mind` checkout is throwaway unless
reverse-ported here — port it the same arc, don't let it sit.
3. Run **`scripts/oss-drift-check.sh`** (file-level diff of the mapped src trees) before every
OSS release push and after any arc that touched a hive-mind checkout.
4. External PRs on the OSS repo are fine — the maintainer merges them back here via
subtree-pull, then re-splits.
3. Run **`node scripts/oss-drift-check.mjs D:/Projects/hive-mind`** before every OSS release
push and after any arc that touched a hive-mind checkout. The checker compares the live
mapped trees with an immutable reviewed baseline: parity and reviewed adaptations are
allowed, while known blockers, unreviewed differences, or forbidden exports keep exit 1.
4. External PRs on the OSS repo are fine — the maintainer intentionally ports accepted changes
back here first, then prepares the next curated forward-port.
=== END CRITICAL ===
=== CORRECTION — how the sync ACTUALLY works (2026-06-12 drift analysis) ===
@@ -481,8 +543,10 @@ The prior text here claimed the mirror is produced by `scripts/oss-subtree-split
**To work on the substrate or publish the OSS mirror:** see
[`packages/hive-mind-core/CONTRIBUTING.md`](./packages/hive-mind-core/CONTRIBUTING.md),
[`scripts/oss-subtree-split.sh`](./scripts/oss-subtree-split.sh) (inspection/guard only), and
[`scripts/oss-drift-check.sh`](./scripts/oss-drift-check.sh) (run before every release; note its
~50 "DIFFERS" are mostly OSS-adaptation noise — layout + import rewrites — not true drift).
[`scripts/oss-drift-check.mjs`](./scripts/oss-drift-check.mjs) (run before every release; its
immutable baseline distinguishes parity, reviewed adaptations, known blockers, unreviewed
differences, and forbidden exports; every blocker or unreviewed entry must be resolved or
explicitly re-baselined through maintainer review before an OSS release).
**Deprecated (do not rely on; do not delete):** the old dual-repo bidirectional-sync workflows
`.github/workflows/{mind-parity-check,sync-mind}.yml` and the `.github/sync.md` manual are **preserved
@@ -517,7 +581,7 @@ Grep before creating. These exist and are functional:
| `packages/core/src/telemetry.ts` | Telemetry pipeline |
| `packages/hive-mind-core/src/harvest/pipeline.ts` | Harvest adapters + dedup |
| `packages/core/src/compliance/` | Compliance + audit |
| `app/src/components/cockpit/` | Tauri cockpit UI |
| `apps/web/src/components/os/` | Main desktop cockpit UI loaded by Tauri |
---
@@ -556,7 +620,7 @@ Do not recreate or expose outside gating.
- **Premium harness reached HONEST 21/21** (May 2026 S1) — every pillar regression-locked + composing. Full agent suite 2657/2657. See `memory/project_session_handoff_0519_s1.md`.
**AI-OS arc (May 2026 S1/S2, 14 commits on origin):**
- Phase 0 — Tool detection PoC (`packages/agent/src/tool-detection.ts`) for all 7 supported AI tools, hermetic + cross-platform.
- Phase 0 — Tool detection PoC (`packages/agent/src/tool-detection.ts`) for eight registered AI-tool surfaces, hermetic + cross-platform. Registration is broader than release support.
- Phase 1A — WaggleDance v2 dispatcher branches wired (discovery/routed_share/model_recipe/knowledge_match/task_claim/model_recommendation).
- Phase 1B — Local sidecar surface (`/api/waggle-dance/signal` + `/signals`), SignalBus ring buffer, personal-tier-eligible.
- Phase 1C — Bridge: v2 bus → existing `/api/waggle/signals` UI stream (zero frontend changes).
@@ -565,7 +629,7 @@ Do not recreate or expose outside gating.
- Phase 2A — Launcher backend (`/api/tools/launch`, `/api/tools/hooks`).
- Phase 2B — LauncherApp dock surface (`apps/web/src/components/os/apps/LauncherApp.tsx`).
- Phase 3 — Skill diffusion (D1 fire → `skill_share` broadcast via `onSkillDistillationFire` callback).
- Phase 4 — Full 7-tool launch cohort + Mission Control inventory tile + Memory provenance badge + launch-with-prompt textarea + process tracker / 'Running' badge.
- Phase 4 — Eight-tool inventory/detection surface + Mission Control tile + Memory provenance badge + launch-with-prompt textarea + process tracker / 'Running' badge. The in-scope agent-integration release cohort is Claude Code, Codex, and Hermes; Cursor and OpenClaw are roadmap-only.
End-to-end: detect → install hooks (reversible) → launch with `WAGGLE_WORKSPACE_ID` env → hook captures → shim emitter → bus → bridge → UI. Rollback tag: `checkpoint/pre-ai-os-2026-05-20`. AI-OS exploration doc: `docs/plans/AI-OS-EXPLORATION-2026-05-19.md`.
@@ -574,7 +638,7 @@ End-to-end: detect → install hooks (reversible) → launch with `WAGGLE_WORKSP
|---|---|---|
| 1 | Spawn Agent + Dock wiring | P36 already wired in `Dock.tsx`+`Desktop.tsx`; P35 third-tier fallback (LiteLLM → runtime model → provider catalogs) landed `14942be`. Residual: runtime verification on a clean install. |
| 2 | Light mode finish | P40/P41 + CR-2 — semantic-token migration is done (no hive-950 references except a comment); remaining issues are render-time fine-tuning (BootScreen visual polish + a few header-styling judgments) that need a binary build to validate. |
| 3 | Wave 2/3 hook implementations | **Mostly DONE (corrected 2026-06-29).** 6 of 7 hook packages ship real bins: Codex + the 2026-06-01 Wave 2/3 port (codex, codex-desktop, cursor, hermes, openclaw). Only `hive-mind-hooks-Codex-desktop` remains a binless `export {}` stub (deferred MCP-bridge category). The dock (`LauncherApp.tsx`) now exposes hook install/verify/uninstall for all 6 via the corrected `HOOKS_COHORT` (was hardcoded `['Codex']`). Residual: Codex-desktop MCP-bridge hook only. |
| 3 | External-tool release cohort | **Windows Solo scope fixed 2026-08-02.** Claude Code, Codex, and Hermes are the in-scope agent-integration cohort. Cursor and OpenClaw implementations remain in-tree as roadmap work and are fail-closed in production surfaces. Claude Desktop, Codex Desktop, and Hermes Desktop are convenience launch surfaces, not separate agent-acceptance targets. |
**Closed during May 2026 backlog sweep:**
- ✅ OW-6 PersonaSwitcher two-tier — shipped via M-01 (`PersonaSwitcher.tsx` + `lib/persona-tier.ts` + `lib/persona-tooltip.ts`); 26/26 tests passing
@@ -623,17 +687,13 @@ For the full polish+launch backlog see `docs/plans/BACKLOG-CONSOLIDATED-2026-04-
| BEHAVIORAL_SPEC | Core agent rules (`packages/agent/src/behavioral-spec.ts`) |
| Sidecar | Node.js Fastify server bundled into Tauri (`/sidecar`) |
| KVARK | Egzakta sovereign enterprise AI — top of the Waggle funnel |
| LiteLLM | LLM routing layer (`litellm-config.yaml`) |
| LiteLLM | Optional server/team deployment proxy config (`litellm-config.yaml`); Windows Solo uses the bundled no-Python proxy and smart router |
| WaggleDance | Multi-agent coordination package (`packages/waggle-dance`) |
| Weaver | `packages/weaver` — (check source for current role) |
| Weaver | Memory consolidation and session-skill extraction engine (`packages/weaver`) |
| Evolution | Self-improvement subsystem (`evolution-*.ts`, `judge.ts`, `iterative-optimizer.ts`) |
| assembleToolPool | Per-persona tool filtering from allowlist + denylist (to implement) |
| applyPersonaToolFilter / filterMcpToolsForPersona | Enforced local and MCP per-persona allowlist/denylist filtering (`packages/server/src/local/persona-tool-filter.ts`) |
---
Maintained by Marko Markovic · Egzakta Group · April 2026
waggle-os.ai · www.kvark.ai
## Imported Claude Cowork project instructions
This is my app repo... use it for exploring and working. What ever you produce, you will put in a new folder cowork and store all there dont change the reo itself.