From ea21721d2a0ad35af00718d678f91b67a8f57d0f Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Thu, 15 Oct 2026 18:35:58 +0200 Subject: [PATCH] docs(oss): record owner decisions as ADRs and the starting baseline ADR-0001..0006 capture the scope decisions: no monetization, memory through a contract backed by local mem0 (knowledge graph deferred), team mode postponed, cost tracking open and self-learning out, whatsapp-web.js for WhatsApp, opt-in analytics. baseline.md records build, typecheck, lint and unit test results on macOS before scope work starts. --- docs/oss/adr/0001-no-monetization.md | 31 ++++++++++ .../adr/0002-memory-contract-local-mem0.md | 38 +++++++++++++ docs/oss/adr/0003-team-mode-postponed.md | 23 ++++++++ ...0004-cost-tracking-in-self-learning-out.md | 26 +++++++++ docs/oss/adr/0005-whatsapp-web-js.md | 34 +++++++++++ docs/oss/adr/0006-opt-in-analytics.md | 25 +++++++++ docs/oss/adr/README.md | 30 ++++++++++ docs/oss/baseline.md | 56 +++++++++++++++++++ 8 files changed, 263 insertions(+) create mode 100644 docs/oss/adr/0001-no-monetization.md create mode 100644 docs/oss/adr/0002-memory-contract-local-mem0.md create mode 100644 docs/oss/adr/0003-team-mode-postponed.md create mode 100644 docs/oss/adr/0004-cost-tracking-in-self-learning-out.md create mode 100644 docs/oss/adr/0005-whatsapp-web-js.md create mode 100644 docs/oss/adr/0006-opt-in-analytics.md create mode 100644 docs/oss/adr/README.md create mode 100644 docs/oss/baseline.md diff --git a/docs/oss/adr/0001-no-monetization.md b/docs/oss/adr/0001-no-monetization.md new file mode 100644 index 0000000..2dc7f11 --- /dev/null +++ b/docs/oss/adr/0001-no-monetization.md @@ -0,0 +1,31 @@ +# ADR-0001: The community edition has no monetization + +- Status: Accepted +- Date: 2026-10-14 +- Source: Waggle OSS Agreed Scope Annex + +## Context + +The commercial product sells tiers (Trial, Solo, Teams, Enterprise) through Stripe. The +server gates routes with `requireTier`, caps sessions per tier and blocks some embedding +providers; the web UI keeps its own copy of the tier model and shows plan cards, trial +banners, upgrade modals and KVARK and Team calls to action. + +## Decision + +The community edition is free and has no monetization. We remove the tier model, trial +logic, the Stripe integration, license checks, KVARK tools and nudges, and upgrade or Team +calls to action. Everything a tier used to gate becomes available. The per-tier session cap +becomes a fixed constant. + +## Consequences + +- P0.1 removes `packages/shared/src/tiers.ts`, the `assert-tier` middleware and the routes + that call `requireTier`, `/api/tier` and `/api/tier/start-trial`, and the trial auto-start + after onboarding. +- P1.1 removes `packages/server/src/stripe/` and `packages/server/src/kvark/`; P1.4 removes + `packages/agent/src/kvark-tools.ts`; P1.3a removes the billing UI. +- On startup the sidecar drops the `tier`, `trialStartedAt` and `stripe_customer_id` keys from + `config.json`. +- UserTier (UI complexity), ModelTier, persona tiers, CLI levels and memory health levels are + unrelated to billing and stay. diff --git a/docs/oss/adr/0002-memory-contract-local-mem0.md b/docs/oss/adr/0002-memory-contract-local-mem0.md new file mode 100644 index 0000000..f60d28c --- /dev/null +++ b/docs/oss/adr/0002-memory-contract-local-mem0.md @@ -0,0 +1,38 @@ +# ADR-0002: Memory goes through a contract backed by local mem0 + +- Status: Accepted +- Date: 2026-10-14, amended 2026-10-15 (knowledge graph deferred) + +## Context + +Memory today is the hive-mind substrate in `packages/hive-mind-core` (FrameStore, +HybridSearch, KnowledgeGraph, identity and awareness layers). About 250 imports across agent, +server, weaver and cli depend on it, and around 20 files query the memory database with SQL. +The agreed scope takes the memory packages out of the community edition. + +## Decision + +- Waggle reaches memory only through a memory contract package (P0.3): remember, search, get, + update, delete and history, plus a capability map that the UI uses to hide unsupported + features. +- The backend is the open-source mem0 library (`mem0ai`, Apache-2.0) running inside the + sidecar. Data stays in a SQLite file in the Waggle data directory. The hosted Mem0 Platform + is not used. +- Fact extraction and embeddings use the Waggle-managed Ollama runtime or the user's own + provider key. +- Memory features in v1: facts, search and the user profile. Hidden in v1: history import, + wiki, Claude Code and Codex hooks, Waggle Room and the memory MCP server. +- The knowledge graph is deferred to a later release, because open-source mem0 has no graph + memory since version 3. The capability map marks it unavailable, so it can be added later + without changing the contract. +- No code outside the adapter queries the memory store with SQL. + +## Consequences + +- Tables that belong to Waggle rather than to memory (cron, notifications, pending actions, + skill hashes, file index, cost tracking) move to a separate `waggle.db` (P1.5). +- Non-memory code in `hive-mind-core` (WorkspaceManager, logger, injection scanner, ingress + guard) moves to `@waggle/core` (P1.5). +- Search quality is compared with the current engine on a reference question set, with a + local model and with a provider key, before release. +- `hive-mind-*`, `memory-mcp` and `wiki-compiler` are removed once nothing imports them (P2.2). diff --git a/docs/oss/adr/0003-team-mode-postponed.md b/docs/oss/adr/0003-team-mode-postponed.md new file mode 100644 index 0000000..48471fd --- /dev/null +++ b/docs/oss/adr/0003-team-mode-postponed.md @@ -0,0 +1,23 @@ +# ADR-0003: Team mode stays in the repository but is not built or shipped + +- Status: Accepted +- Date: 2026-10-14 + +## Context + +Team mode spans the team server runtime (`packages/server/src/index.ts` with its routes, +services, database, scheduler and WebSocket layer), WaggleDance, the worker and the team +screens in the web UI. The local sidecar loads the team server dynamically, which pulls Clerk, +BullMQ, ioredis, postgres and drizzle into every build. + +## Decision + +Team mode code stays in the repository as a separate package. It is not built, bundled or +shipped in v1, and the team screens are removed from the UI. + +## Consequences + +- P1.1 separates the team runtime from the local sidecar and removes the dynamic team server + start, so the sidecar bundle no longer carries Clerk, BullMQ, ioredis, postgres or drizzle. +- P1.3a removes the team screens. +- Team code receives no new features until a later decision. diff --git a/docs/oss/adr/0004-cost-tracking-in-self-learning-out.md b/docs/oss/adr/0004-cost-tracking-in-self-learning-out.md new file mode 100644 index 0000000..52328c5 --- /dev/null +++ b/docs/oss/adr/0004-cost-tracking-in-self-learning-out.md @@ -0,0 +1,26 @@ +# ADR-0004: Cost tracking is open; self-learning and optimizer are excluded + +- Status: Accepted +- Date: 2026-10-14, amended 2026-10-15 (`optimizer` classified as self-learning) + +## Context + +Waggle tracks model costs and budget limits (execution traces, cost reservation, the +`CostTracker` in the agent). It also has a self-learning subsystem: behaviour evolution, +improvement signals, learning from user corrections, judge and eval loops, and the +`packages/optimizer` package for GEPA prompt optimization, called from the chat route through +`packages/server/src/local/services/optimizer-service.ts`. + +## Decision + +- Cost tracking and budget limits are part of the community edition, under MIT. +- Self-learning is excluded, including `packages/optimizer`. The project owner reworks it + separately. + +## Consequences + +- P1.2 and P1.5 move cost tracking to `waggle.db`. +- P1.4 removes the self-learning modules, `packages/optimizer` and the optimizer service. The + tables `evolution_runs` and `improvement_signals` are not carried into `waggle.db`. +- P1.4 decides whether the optimization log (`optimization_log`) is still needed without + `optimizer`. diff --git a/docs/oss/adr/0005-whatsapp-web-js.md b/docs/oss/adr/0005-whatsapp-web-js.md new file mode 100644 index 0000000..728282b --- /dev/null +++ b/docs/oss/adr/0005-whatsapp-web-js.md @@ -0,0 +1,34 @@ +# ADR-0005: The WhatsApp channel uses whatsapp-web.js + +- Status: Accepted, one open item (browser source) +- Date: 2026-10-14 + +## Context + +The WhatsApp channel (`packages/server/src/local/channels/whatsapp-adapter.ts`) uses Baileys. +Baileys itself is MIT, but it depends on `libsignal`, which is GPL-3.0. The sidecar build +bundles both, which would put GPL code into the shipped community edition. + +## Decision + +Replace Baileys with `whatsapp-web.js` (Apache-2.0) and remove Baileys from the dependencies +of `server` and `launcher`. + +## Consequences + +- `whatsapp-web.js` drives a Chrome browser through Puppeteer. The installer does not bundle a + browser, and installing dependencies does not download one. +- Open item, proposed and awaiting the owner: use an installed Edge or Chrome, and download a + browser (about 170 MB) only if none is found when the user enables WhatsApp. +- Voice and video messages go through ffmpeg, which is not bundled because ffmpeg builds carry + their own LGPL or GPL terms. Use an installed ffmpeg or download it on demand. +- The client is unofficial. The UI warns that WhatsApp may block the account. + +## Alternatives considered + +- whatsmeow (Go, MPL-2.0): no browser, but needs a separate Go binary per platform. +- WPPConnect (LGPL-3.0): also browser-based, stricter license. +- venom-bot: no npm release since November 2024. +- open-wa: Hippocratic license, not an open-source license in the OSI sense. +- WhatsApp Business Cloud API: needs a business account and a public webhook, so it does not + fit a local app. diff --git a/docs/oss/adr/0006-opt-in-analytics.md b/docs/oss/adr/0006-opt-in-analytics.md new file mode 100644 index 0000000..8cb111a --- /dev/null +++ b/docs/oss/adr/0006-opt-in-analytics.md @@ -0,0 +1,25 @@ +# ADR-0006: Analytics are opt-in + +- Status: Accepted, one open item (PostHog project) +- Date: 2026-10-14 + +## Context + +The web UI initializes PostHog on startup when a project key was present at build time, and +only an opt-out marker in local storage stops it. Local telemetry +(`packages/core/src/telemetry.ts`) stays on the machine. + +## Decision + +- Analytics are opt-in. On first launch a dialog asks for consent. Until the user chooses + "Allow", PostHog is not initialized and nothing is sent. +- Settings have a toggle to change the choice later. +- The PostHog project key is injected at build time (`VITE_POSTHOG_KEY`) from the build + environment and is never committed. Builds from source without the key send nothing. + +## Consequences + +- P1.3a adds the consent dialog and the settings toggle and moves PostHog initialization + behind consent. +- Open item, proposed and awaiting the owner: a separate PostHog project for the community + edition, so its events never mix with the commercial product. diff --git a/docs/oss/adr/README.md b/docs/oss/adr/README.md new file mode 100644 index 0000000..1e5d944 --- /dev/null +++ b/docs/oss/adr/README.md @@ -0,0 +1,30 @@ +# Decision records: Waggle community edition + +Each record captures one decision that shapes the community edition: the context, what was +decided and what follows from it. Records are numbered and never renumbered. To change a +decision, add a new record that supersedes the old one. + +| ADR | Decision | Status | +|---|---|---| +| [0001](0001-no-monetization.md) | The community edition has no monetization | Accepted | +| [0002](0002-memory-contract-local-mem0.md) | Memory goes through a contract backed by local mem0 | Accepted | +| [0003](0003-team-mode-postponed.md) | Team mode stays in the repository but is not built or shipped | Accepted | +| [0004](0004-cost-tracking-in-self-learning-out.md) | Cost tracking is open; self-learning and `optimizer` are excluded | Accepted | +| [0005](0005-whatsapp-web-js.md) | The WhatsApp channel uses `whatsapp-web.js` | Accepted, one open item | +| [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item | + +## Pending decisions + +These are open with the project owner. Work continues on temporary choices and the affected +work packages wait for the answer. + +| Topic | Temporary choice | Blocks | +|---|---|---| +| Licensing review | Technical license checks continue | P2.3, P2.6 | +| Product name and system identifiers | Temporary names | P1.3d, P2.6 | +| Location of the public repository | Manual builds on each OS | P1.3d, P2.6 | +| Supported platforms for v1 | Windows x64, macOS arm64 and x64, Linux x64 (glibc) | P1.3b, P1.3d | +| Installer signing | First release may ship unsigned with launch instructions | P2.5 | +| Separate data directory from the commercial edition | Not separated yet | P1.3c | +| Browser source for WhatsApp | See ADR-0005 | P1.7 | +| PostHog project for the community edition | See ADR-0006 | P1.3a | diff --git a/docs/oss/baseline.md b/docs/oss/baseline.md new file mode 100644 index 0000000..cebf32e --- /dev/null +++ b/docs/oss/baseline.md @@ -0,0 +1,56 @@ +# Baseline at the start of the conversion + +The state of build, typecheck, lint and tests before any scope work. Every later change is +compared against this record: a check that passes here must not start failing. + +- Date: 2026-10-15 +- Commit: `2346cf3` on `oss/community-edition` (the commercial code at `b20b138` plus the fixes + UF-001, UF-007, UF-008, UF-021 and UF-022) +- Machine: macOS 26.6.2, Apple silicon (arm64), Node 22.23.2, npm 10.9.8 +- CI: not set up yet. The location of the public repository is still open, so this record + stands in for a CI baseline until the pipeline exists (work package 0.2). + +## Results + +| Check | Command | Result | +|---|---|---| +| Package build | `npm run build:packages` | Pass | +| Typecheck, agent | `npx tsc --noEmit --project packages/agent/tsconfig.json` | Pass | +| Typecheck, server | `npx tsc --noEmit --project packages/server/tsconfig.json` | Pass | +| Typecheck, app tooling | `npx tsc --noEmit --project app/tsconfig.json` | Pass | +| Typecheck, web | `cd apps/web && npx tsc --noEmit -p tsconfig.app.json` | Pass | +| Web build | `cd apps/web && npx vite build --outDir ` | Pass | +| Lint | `npx eslint .` | 1,516 files, 0 errors, 0 warnings | +| Unit tests, root | `npm run test` | 719 files, 12,012 tests: 11,915 passed, 41 failed, 56 skipped (8.6 min) | +| Unit tests, web | `cd apps/web && npx vitest run` | 221 files, 1,979 tests, all passed (2.4 min) | +| E2E | `npm run test:e2e` | Not run, see below | +| Visual regression | `npm run test:visual` | Not run, see below | + +The web build went to a temporary directory instead of the root `dist/`, because a running +sidecar serves that directory. + +In the full root run `packages/hive-mind-cli/tests/cli-help.test.ts` also failed once: the +isolated home made npm print an update notice into the CLI output. The setup now turns that +notice off and the file passes (3 of 3), so the totals above count it as passing. + +## Known failures (macOS) + +All 41 failing root tests are in four files and fail the same way when run alone. They are +logged as UF-023. + +| File | Failing | Symptom | +|---|---|---| +| `packages/server/tests/local/managed-ollama-runtime.test.ts` | 38 of 45 | "Official runtime archive did not contain ollama.exe" | +| `packages/hive-mind-hooks-openclaw/tests/handler.test.ts` | 1 of 16 | Expects `/var/folders/...`, receives `/private/var/folders/...` | +| `packages/server/tests/local/files.test.ts` | 1 of 48 | "escapes workspace root through symlink" in a move test | +| `packages/server/tests/local/external-tool-runs.test.ts` | 1 of 17 | "OpenClaw run did not settle" (timeout, not investigated) | + +## Not run yet + +- **E2E and visual regression.** By default the Playwright web server reuses any sidecar on + `:3333` with its data directory, and it rebuilds the root `dist/`. A baseline run needs a + free port and an isolated data directory (`WAGGLE_E2E_REUSE_EXISTING_SERVER=0`, + `WAGGLE_E2E_PORT`) at a time when restarting the local sidecar is acceptable. +- **Infrastructure suites** (`npm run test:infra`) need Postgres and Redis and cover team + mode, which is not part of the community edition. +- **Windows and Linux.** This record covers macOS only.