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.
This commit is contained in:
31
docs/oss/adr/0001-no-monetization.md
Normal file
31
docs/oss/adr/0001-no-monetization.md
Normal file
@@ -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.
|
||||
38
docs/oss/adr/0002-memory-contract-local-mem0.md
Normal file
38
docs/oss/adr/0002-memory-contract-local-mem0.md
Normal file
@@ -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).
|
||||
23
docs/oss/adr/0003-team-mode-postponed.md
Normal file
23
docs/oss/adr/0003-team-mode-postponed.md
Normal file
@@ -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.
|
||||
26
docs/oss/adr/0004-cost-tracking-in-self-learning-out.md
Normal file
26
docs/oss/adr/0004-cost-tracking-in-self-learning-out.md
Normal file
@@ -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`.
|
||||
34
docs/oss/adr/0005-whatsapp-web-js.md
Normal file
34
docs/oss/adr/0005-whatsapp-web-js.md
Normal file
@@ -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.
|
||||
25
docs/oss/adr/0006-opt-in-analytics.md
Normal file
25
docs/oss/adr/0006-opt-in-analytics.md
Normal file
@@ -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.
|
||||
30
docs/oss/adr/README.md
Normal file
30
docs/oss/adr/README.md
Normal file
@@ -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 |
|
||||
56
docs/oss/baseline.md
Normal file
56
docs/oss/baseline.md
Normal file
@@ -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 <temp dir>` | 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.
|
||||
Reference in New Issue
Block a user