mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

fix: rename all packages from @mosaic/* to @mosaicstack/*
Some checks failed
ci/woodpecker/pr/ci Pipeline failed
Details
ci/woodpecker/push/ci Pipeline failed
Details

Browse Source 
- Updated all package.json name fields and dependency references
- Updated all TypeScript/JavaScript imports
- Updated .woodpecker/publish.yml filters and registry paths
- Updated tools/install.sh scope default
- Updated .npmrc registry paths (worktree + host)
- Enhanced update-checker.ts with checkForAllUpdates() multi-package support
- Updated CLI update command to show table of all packages
- Added KNOWN_PACKAGES, formatAllPackagesTable, getInstallAllCommand
- Marked checkForUpdate() with @deprecated JSDoc

Closes #391
This commit is contained in:
Jarvis
2026-04-04 21:43:23 -05:00
parent 80994bdc8e
commit 774b76447d
200 changed files with 828 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
docs/PRD.md
View File

@@ -8,7 +8,7 @@
- **Best-Guess Mode:** true
- Repo (target): `git.mosaicstack.dev/mosaic/mosaic-stack`
- Baseline: `~/src/jarvis-old` (jarvis v0.2.0)
- Package source: `~/src/mosaic-mono-v0` (@mosaic/\* packages)
- Package source: `~/src/mosaic-mono-v0` (@mosaicstack/\* packages)
- Agent harness: [pi](https://github.com/badlogic/pi-mono) (v0.57.1)
- Remote control reference: [OpenClaw](https://github.com/openclaw/openclaw) (upstream, canonical)
@@ -16,7 +16,7 @@
## Problem Statement
Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and Next.js frontend. It handles chat, projects, tasks, and LLM routing but lacks orchestration depth, agent coordination, shared memory, and remote access. The Mosaic framework (`~/.config/mosaic`) provides agent guides, shell-based orchestration tools, and quality rails — but these are loose scripts, not an integrated platform. The `@mosaic/*` packages in mosaic-mono-v0 began consolidating these into TypeScript packages (brain, queue, coord, cli, prdy, quality-rails) but have no UI, no auth, and no agent runtime integration.
Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and Next.js frontend. It handles chat, projects, tasks, and LLM routing but lacks orchestration depth, agent coordination, shared memory, and remote access. The Mosaic framework (`~/.config/mosaic`) provides agent guides, shell-based orchestration tools, and quality rails — but these are loose scripts, not an integrated platform. The `@mosaicstack/*` packages in mosaic-mono-v0 began consolidating these into TypeScript packages (brain, queue, coord, cli, prdy, quality-rails) but have no UI, no auth, and no agent runtime integration.
**The gap:** Three codebases with overlapping concerns, no unified runtime, no remote control surface (Discord/Telegram), no gateway orchestrator, and a Python backend that doesn't align with the target TypeScript-everywhere stack.
@@ -32,7 +32,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
4. **Gateway orchestrator** — Central routing layer that dispatches tasks to appropriate agents based on capability, cost, and context
5. **Shared memory** — PostgreSQL canonical store + vector DB for semantic search + tiered log summarization to prevent context creep
6. **Multi-user with SSO** — BetterAuth with Authentik/WorkOS/Keycloak SSO, RBAC for family/team/business use
7. **Full @mosaic/\* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
7. **Full @mosaicstack/\* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
8. **Extensible** — MCP capability, skill import interface, plugin architecture for LLM providers and remote channels
---
@@ -44,7 +44,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
1. Chat/conversation UI (web) — carry forward from jarvis-old, rewrite frontend to work with new backend
2. Pi TUI integration — terminal-based agent interaction using Pi SDK
3. Web dashboard — settings, task management, projects, PRDs, missions, agent status
4. Gateway orchestrator (`@mosaic/gateway`) — central dispatch for agent tasks with routing logic
4. Gateway orchestrator (`@mosaicstack/gateway`) — central dispatch for agent tasks with routing logic
5. Task management — CRUD, kanban, mission-scoped tasks, dependency tracking
6. Project management — projects, milestones, PRDs linked to missions
7. Shared memory system — learned preferences, behaviors, defaults; tiered storage with summarization
@@ -55,13 +55,13 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
12. Agent routing — task-based model/provider selection (cost/capability matrix)
13. MCP capability — server and client, tool registration
14. Skill import interface — browse, install, manage agent skills
15. `@mosaic/brain` — structured data layer (migrated to PG + vector DB backend)
16. `@mosaic/queue` — Valkey-backed task queue with MCP tools
17. `@mosaic/coord` — mission coordination engine
18. `@mosaic/mosaic` — install wizard / bootstrap
19. `@mosaic/prdy` — PRD wizard
20. `@mosaic/quality-rails` — code quality scaffolder
21. `@mosaic/cli` — unified `mosaic` CLI
15. `@mosaicstack/brain` — structured data layer (migrated to PG + vector DB backend)
16. `@mosaicstack/queue` — Valkey-backed task queue with MCP tools
17. `@mosaicstack/coord` — mission coordination engine
18. `@mosaicstack/mosaic` — install wizard / bootstrap
19. `@mosaicstack/prdy` — PRD wizard
20. `@mosaicstack/quality-rails` — code quality scaffolder
21. `@mosaicstack/cli` — unified `mosaic` CLI
22. Docker Compose deployment + bare-metal capability
23. Agent log service — ingest, parse, tier, summarize agent interaction logs
@@ -94,14 +94,14 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
│ └──────────────┴───────┬───────┴────────────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ @mosaic/gateway │ ← Central Orchestrator│
│ │ @mosaicstack/gateway │ ← Central Orchestrator│
│ │ (NestJS+Fastify) │ │
│ └────┬────┬────┬─────┘ │
│ │ │ │ │
│ ┌──────────────┤ │ ├──────────────┐ │
│ │ │ │ │ │ │
│ ┌───────▼──────┐ ┌────▼────▼──┐ │ ┌───────────▼────────┐ │
│ │ @mosaic/brain│ │ @mosaic/ │ │ │ Agent Pool │ │
│ │ @mosaicstack/brain│ │ @mosaicstack/ │ │ │ Agent Pool │ │
│ │ (Data Layer) │ │ queue │ │ │ (Pi SDK sessions) │ │
│ └───────┬──────┘ └────────────┘ │ │ - Anthropic │ │
│ │ │ │ - Codex │ │
@@ -111,12 +111,12 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
│ └──────────────┴───────────┘ │ │ - llama.cpp │ │
│ │ └────────────────────┘ │
│ ┌─────────────▼──────┐ │
│ │ @mosaic/coord │ │
│ │ @mosaicstack/coord │ │
│ │ Mission lifecycle │ │
│ └────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ @mosaic/cli │ │ @mosaic/prdy │ │ @mosaic/ │ │
│ │ @mosaicstack/cli │ │ @mosaicstack/prdy │ │ @mosaicstack/ │ │
│ │ │ │ │ │ quality-rails │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
@@ -130,20 +130,20 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
| Layer | Technology | Rationale |
| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Web Frontend** | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaic/design-tokens (mosaic-stack-website) |
| **Web Frontend** | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaicstack/design-tokens (mosaic-stack-website) |
| **API / Gateway** | NestJS + Fastify adapter | Module system, DI, guards/interceptors for complex gateway; Fastify performance underneath |
| **Agent Runtime** | Pi SDK (embedded) | Extensible harness with tools, skills, session management |
| **TUI** | Pi interactive mode | Native terminal agent interaction |
| **Auth** | BetterAuth + SSO adapters | Multi-user RBAC with Authentik/WorkOS/Keycloak |
| **Database** | PostgreSQL 17 + pgvector | Canonical store; pgvector for embedding search |
| **Vector DB** | pgvector + VectorStore interface | pgvector for v0.1.0; `VectorStore` abstraction in @mosaic/memory makes Qdrant a drop-in later |
| **Cache / Queue** | Valkey 8 | Redis-compatible; proven in @mosaic/queue |
| **Vector DB** | pgvector + VectorStore interface | pgvector for v0.1.0; `VectorStore` abstraction in @mosaicstack/memory makes Qdrant a drop-in later |
| **Cache / Queue** | Valkey 8 | Redis-compatible; proven in @mosaicstack/queue |
| **ORM** | Drizzle ORM | TypeScript-native, lightweight, good migration story |
| **Validation** | Zod | Already used across @mosaic/\* packages |
| **Validation** | Zod | Already used across @mosaicstack/\* packages |
| **Build** | pnpm workspaces + Turborepo | Proven in both jarvis-old and mosaic-mono-v0 |
| **Testing** | Vitest + Playwright | Unit/integration via Vitest, E2E via Playwright |
| **Remote Control** | Discord.js + Telegraf | Inspired by OpenClaw plugin architecture |
| **MCP** | @modelcontextprotocol/sdk | Already used in @mosaic/brain and @mosaic/queue |
| **MCP** | @modelcontextprotocol/sdk | Already used in @mosaicstack/brain and @mosaicstack/queue |
| **Container** | Docker Compose | Self-hosted; bare-metal also supported |
| **CI** | Woodpecker CI | Existing infrastructure at git.mosaicstack.dev |
| **Observability** | OpenTelemetry + SigNoz | Wide-event logging from day one; OTEL auto-instrumentation for NestJS/PG/HTTP; SigNoz as all-in-one backend |
@@ -158,12 +158,12 @@ The jarvis-old FastAPI backend is not carried forward as code. Its domain logic
Instead of a custom LLM provider abstraction (jarvis-old's `BaseLLMProvider`), Pi SDK manages agent sessions. Pi handles model selection, tool calling, context management, and compaction. The gateway dispatches work to Pi sessions configured with appropriate providers.
**AD-3: Gateway as the central nervous system (NestJS + Fastify adapter)**
`@mosaic/gateway` is the single API surface. The web app, TUI, Discord, and Telegram all talk to the gateway. The gateway routes to brain (data), queue (coordination), agent pool (LLM work), and coord (mission lifecycle). This replaces the direct FastAPI-to-DB pattern from jarvis-old.
`@mosaicstack/gateway` is the single API surface. The web app, TUI, Discord, and Telegram all talk to the gateway. The gateway routes to brain (data), queue (coordination), agent pool (LLM work), and coord (mission lifecycle). This replaces the direct FastAPI-to-DB pattern from jarvis-old.
NestJS was chosen over raw Fastify because the gateway is inherently complex — it hosts channel plugins, agent pool management, routing engine, WebSocket hub, MCP server, auth middleware, and integrates brain, queue, memory, and log services. NestJS provides the module system, dependency injection, guards, and interceptors needed to organize this cleanly. NestJS uses Fastify as its HTTP adapter, so Fastify's performance is preserved. This also aligns with the stated stack preference in USER.md ("NestJS API + Next.js web"). @mosaic/brain's existing Fastify code migrates naturally into a NestJS module with Fastify adapter.
NestJS was chosen over raw Fastify because the gateway is inherently complex — it hosts channel plugins, agent pool management, routing engine, WebSocket hub, MCP server, auth middleware, and integrates brain, queue, memory, and log services. NestJS provides the module system, dependency injection, guards, and interceptors needed to organize this cleanly. NestJS uses Fastify as its HTTP adapter, so Fastify's performance is preserved. This also aligns with the stated stack preference in USER.md ("NestJS API + Next.js web"). @mosaicstack/brain's existing Fastify code migrates naturally into a NestJS module with Fastify adapter.
**AD-4: Brain migrates from JSON files to PostgreSQL**
`@mosaic/brain` currently uses a JSON file store. For Mosaic Stack, brain's data model (tasks, projects, events, agents, missions, tickets) moves to PostgreSQL via Drizzle ORM. Brain's REST + MCP interface is preserved — only the storage backend changes.
`@mosaicstack/brain` currently uses a JSON file store. For Mosaic Stack, brain's data model (tasks, projects, events, agents, missions, tickets) moves to PostgreSQL via Drizzle ORM. Brain's REST + MCP interface is preserved — only the storage backend changes.
**AD-5: Tiered memory with summarization**
Agent interaction logs are ingested into a log service. Raw logs are stored short-term. A summarization pipeline (using a cheap LLM) periodically compresses logs into structured insights stored in the vector DB. This prevents unbounded log growth while preserving searchable context.
@@ -189,8 +189,8 @@ The gateway includes a cron scheduler for recurring tasks: log summarization run
**AD-12: Web search tool (DuckDuckGo MCP)**
Agent sessions include a web search tool for information retrieval. DuckDuckGo via MCP server is the primary option (privacy-respecting, no API key required). Falls back to other search MCP providers if configured. Registered as a standard MCP tool available to all agent sessions.
**AD-13: Design system from @mosaic/design-tokens**
The web dashboard uses the Mosaic Stack design system established in `mosaic-stack-website`. The `@mosaic/design-tokens` package provides CSS custom properties, Tailwind preset, and TS color/font/radius exports. Dark theme default with light theme support. Fonts: Outfit (sans), Fira Code (mono). Color palette: deep blue-grays with blue/purple/teal accents.
**AD-13: Design system from @mosaicstack/design-tokens**
The web dashboard uses the Mosaic Stack design system established in `mosaic-stack-website`. The `@mosaicstack/design-tokens` package provides CSS custom properties, Tailwind preset, and TS color/font/radius exports. Dark theme default with light theme support. Fonts: Outfit (sans), Fira Code (mono). Color palette: deep blue-grays with blue/purple/teal accents.
**AD-14: Multi-tier deployment readiness**
Code is structured assuming eventual multi-node deployment with dedicated roles (gateway nodes, agent worker nodes, brain/DB nodes). Packages communicate via well-defined APIs (HTTP/WS/MCP), not in-process calls where avoidable. Service boundaries are clean: gateway is stateless (state in PG/Valkey), agent pool can scale independently, brain is a separate service. v0.1.0 runs single-node; the architecture doesn't fight horizontal scaling later.
@@ -205,25 +205,25 @@ Code is structured assuming eventual multi-node deployment with dedicated roles
mosaic-mono-v1/
├── apps/
│ ├── web/ Next.js 16 web dashboard
│ └── gateway/ @mosaic/gateway — NestJS API + WebSocket
│ └── gateway/ @mosaicstack/gateway — NestJS API + WebSocket
├── packages/
│ ├── types/ @mosaic/types — shared type contracts
│ ├── brain/ @mosaic/brain — data layer (PG-backed)
│ ├── queue/ @mosaic/queue — Valkey task queue + MCP
│ ├── coord/ @mosaic/coord — mission coordination
│ ├── mosaic/ @mosaic/mosaic — install wizard
│ ├── prdy/ @mosaic/prdy — PRD wizard
│ ├── quality-rails/ @mosaic/quality-rails — code quality scaffolder
│ ├── cli/ @mosaic/cli — unified CLI
│ ├── auth/ @mosaic/auth — BetterAuth config + SSO adapters
│ ├── db/ @mosaic/db — Drizzle schema, migrations, connection
│ ├── agent/ @mosaic/agent — Pi SDK integration, agent pool manager
│ ├── memory/ @mosaic/memory — tiered memory + summarization service
│ ├── log/ @mosaic/log — agent log ingest + processing
│ └── design-tokens/ @mosaic/design-tokens — CSS vars, Tailwind preset, colors
│ ├── types/ @mosaicstack/types — shared type contracts
│ ├── brain/ @mosaicstack/brain — data layer (PG-backed)
│ ├── queue/ @mosaicstack/queue — Valkey task queue + MCP
│ ├── coord/ @mosaicstack/coord — mission coordination
│ ├── mosaic/ @mosaicstack/mosaic — install wizard
│ ├── prdy/ @mosaicstack/prdy — PRD wizard
│ ├── quality-rails/ @mosaicstack/quality-rails — code quality scaffolder
│ ├── cli/ @mosaicstack/cli — unified CLI
│ ├── auth/ @mosaicstack/auth — BetterAuth config + SSO adapters
│ ├── db/ @mosaicstack/db — Drizzle schema, migrations, connection
│ ├── agent/ @mosaicstack/agent — Pi SDK integration, agent pool manager
│ ├── memory/ @mosaicstack/memory — tiered memory + summarization service
│ ├── log/ @mosaicstack/log — agent log ingest + processing
│ └── design-tokens/ @mosaicstack/design-tokens — CSS vars, Tailwind preset, colors
├── plugins/
│ ├── discord/ @mosaic/discord-plugin — Discord channel
│ └── telegram/ @mosaic/telegram-plugin — Telegram channel
│ ├── discord/ @mosaicstack/discord-plugin — Discord channel
│ └── telegram/ @mosaicstack/telegram-plugin — Telegram channel
├── docker/
│ ├── gateway.Dockerfile
│ ├── web.Dockerfile
@@ -244,7 +244,7 @@ mosaic-mono-v1/
### Package Responsibilities
#### `apps/gateway` — @mosaic/gateway (NEW — critical path)
#### `apps/gateway` — @mosaicstack/gateway (NEW — critical path)
The central nervous system. All clients connect here. Built with NestJS (Fastify adapter).
@@ -303,7 +303,7 @@ Carried forward from jarvis-old with significant refactoring.
- User management (admin RBAC panel)
- Auth pages (login, SSO redirect, registration)
#### `packages/types` — @mosaic/types
#### `packages/types` — @mosaicstack/types
Migrated from mosaic-mono-v0. Extended with:
@@ -313,7 +313,7 @@ Migrated from mosaic-mono-v0. Extended with:
- Memory types (preference, insight, summary)
- Plugin channel types (Discord, Telegram message mapping)
#### `packages/brain` — @mosaic/brain
#### `packages/brain` — @mosaicstack/brain
Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.**
@@ -324,7 +324,7 @@ Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.
- New: computed endpoints (today, stale, stats, search, audit) run against PG
- New: appreciation collection preserved for family use
#### `packages/queue` — @mosaic/queue
#### `packages/queue` — @mosaicstack/queue
Migrated from mosaic-mono-v0 with minimal changes.
@@ -332,7 +332,7 @@ Migrated from mosaic-mono-v0 with minimal changes.
- MCP server with 8 tools
- Used by gateway for agent task dispatch and coordination
#### `packages/coord` — @mosaic/coord
#### `packages/coord` — @mosaicstack/coord
Migrated from mosaic-mono-v0.
@@ -342,7 +342,7 @@ Migrated from mosaic-mono-v0.
- Continuation prompt generation
- Integration with gateway for mission-driven orchestration
#### `packages/db` — @mosaic/db (NEW)
#### `packages/db` — @mosaicstack/db (NEW)
Shared database package.
@@ -351,7 +351,7 @@ Shared database package.
- Connection pool configuration
- Shared by gateway, brain, auth, memory
#### `packages/auth` — @mosaic/auth (NEW)
#### `packages/auth` — @mosaicstack/auth (NEW)
Authentication and authorization.
@@ -361,7 +361,7 @@ Authentication and authorization.
- API key generation for brain/MCP access
- Session management middleware
#### `packages/agent` — @mosaic/agent (NEW — critical path)
#### `packages/agent` — @mosaicstack/agent (NEW — critical path)
Pi SDK integration layer.
@@ -372,7 +372,7 @@ Pi SDK integration layer.
- Skill management — loads and configures Pi skills for agent sessions
- Session lifecycle — create, monitor, complete, fail, timeout
#### `packages/memory` — @mosaic/memory (NEW)
#### `packages/memory` — @mosaicstack/memory (NEW)
Tiered memory system.
@@ -382,7 +382,7 @@ Tiered memory system.
- Summarization pipeline — compress raw logs into structured insights
- Memory API — used by gateway and agent sessions
#### `packages/log` — @mosaic/log (NEW)
#### `packages/log` — @mosaicstack/log (NEW)
Agent log service.
@@ -392,7 +392,7 @@ Agent log service.
- Summarization trigger — invokes cheap LLM to compress aging logs
- Retention policy — configurable TTLs per tier
#### `packages/mosaic` — @mosaic/mosaic
#### `packages/mosaic` — @mosaicstack/mosaic
Migrated from mosaic-mono-v0, updated for v1.
@@ -400,7 +400,7 @@ Migrated from mosaic-mono-v0, updated for v1.
- Detects existing installations, offers upgrade path
- Configures `~/.config/mosaic/` with guides, tools, runtime configs
#### `packages/prdy` — @mosaic/prdy
#### `packages/prdy` — @mosaicstack/prdy
Migrated from mosaic-mono-v0.
@@ -408,7 +408,7 @@ Migrated from mosaic-mono-v0.
- Template-based PRD creation with Zod validation
- CLI integration via `mosaic prdy`
#### `packages/quality-rails` — @mosaic/quality-rails
#### `packages/quality-rails` — @mosaicstack/quality-rails
Migrated from mosaic-mono-v0.
@@ -416,15 +416,15 @@ Migrated from mosaic-mono-v0.
- Generates ESLint, tsconfig, Woodpecker, husky, lint-staged configs
- Supports project types: monorepo, typescript-node, nextjs
#### `packages/cli` — @mosaic/cli
#### `packages/cli` — @mosaicstack/cli
Migrated from mosaic-mono-v0, extended.
- Unified `mosaic` binary
- Subcommands: `mosaic coord`, `mosaic prdy`, `mosaic queue`, `mosaic quality`, `mosaic gateway`, `mosaic brain`
- Plugin discovery for installed @mosaic/\* packages
- Plugin discovery for installed @mosaicstack/\* packages
#### `plugins/discord` — @mosaic/discord-plugin (NEW — high priority)
#### `plugins/discord` — @mosaicstack/discord-plugin (NEW — high priority)
Discord remote control channel. Architecture inspired by OpenClaw (https://github.com/openclaw/openclaw).
@@ -436,7 +436,7 @@ Discord remote control channel. Architecture inspired by OpenClaw (https://githu
- Bot pairing and permission management (Discord user → Mosaic user mapping)
- DM support for private conversations
#### `plugins/telegram` — @mosaic/telegram-plugin (NEW)
#### `plugins/telegram` — @mosaicstack/telegram-plugin (NEW)
Telegram remote control channel.
@@ -547,7 +547,7 @@ Telegram remote control channel.
- WebSocket hub — real-time updates for chat, agent status, notifications
- Rate limiting and request validation
### FR-3: Agent Pool (@mosaic/agent)
### FR-3: Agent Pool (@mosaicstack/agent)
- Manage concurrent Pi SDK sessions
- Provider configuration: API key management, endpoint URLs, model lists
@@ -582,7 +582,7 @@ Telegram remote control channel.
- Mission CRUD (linked to project and PRD)
- Mission tasks with phases, dependencies, ordering
- Mission summary with computed progress
- Mission coordination via @mosaic/coord
- Mission coordination via @mosaicstack/coord
- Active mission dashboard in web UI
### FR-7: Memory System
@@ -844,7 +844,7 @@ Telegram remote control channel.
- [ ] Database migrations run automatically on first start
- [ ] `.env.example` documents all required configuration
### AC-11: @mosaic/\* Packages
### AC-11: @mosaicstack/\* Packages
- [ ] All 7 migrated packages build, pass tests, and integrate with gateway
- [ ] `mosaic` CLI provides subcommands for each package
@@ -870,7 +870,7 @@ Telegram remote control channel.
| Risk | Likelihood | Impact | Mitigation |
| -------------------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------------------------- |
| Pi SDK API instability (pre-1.0) | Medium | High | Pin version, abstract behind @mosaic/agent interface |
| Pi SDK API instability (pre-1.0) | Medium | High | Pin version, abstract behind @mosaicstack/agent interface |
| Brain PG migration complexity | Medium | Medium | Preserve Brain REST/MCP API contract; only storage changes |
| Discord plugin complexity (OpenClaw has ~60 files) | Medium | Medium | Start minimal (DM + mention in channel), single-guild only; expand iteratively post-beta |
| LLM provider subscription auth varies by provider | Medium | Medium | Abstract behind provider interface; implement per-provider adapters |
@@ -882,7 +882,7 @@ Telegram remote control channel.
| # | Question | Priority | Status |
| --- | ------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | Pi SDK version to pin for v0.1.0? | High | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaic/agent` interface to insulate from breaking changes. Bump deliberately after testing. |
| 1 | Pi SDK version to pin for v0.1.0? | High | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaicstack/agent` interface to insulate from breaking changes. Bump deliberately after testing. |
| 2 | Authentik vs WorkOS vs Keycloak — which SSO provider to implement first? | Medium | ✅ Resolved — Authentik first (already in Jason's infrastructure) |
| 3 | Vector DB: pgvector sufficient or need Qdrant from the start? | Medium | ✅ Resolved — pgvector with VectorStore interface abstraction. Qdrant drops in later if needed. |
| 4 | Summarization LLM: which model for log compression? | Medium | ✅ Resolved — Haiku-tier default with structured output guardrails, configurable via routing engine. |
@@ -910,9 +910,9 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
### Phase 0: Foundation (v0.0.1)
- Scaffold monorepo (pnpm + turbo + tsconfig + eslint + vitest)
- `@mosaic/types` — migrate and extend from v0
- `@mosaic/db` — Drizzle schema, PG connection, migrations
- `@mosaic/auth` — BetterAuth setup with email/password
- `@mosaicstack/types` — migrate and extend from v0
- `@mosaicstack/db` — Drizzle schema, PG connection, migrations
- `@mosaicstack/auth` — BetterAuth setup with email/password
- OTEL foundation — `@opentelemetry/sdk-node` setup, SigNoz in docker-compose, trace propagation wired
- Docker Compose (PG 17 + Valkey + SigNoz)
- CI pipeline (Woodpecker)
@@ -921,19 +921,19 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
### Phase 1: Core API (v0.0.2)
- `apps/gateway` — NestJS server (Fastify adapter), auth middleware, health endpoints
- `@mosaic/brain` — migrate from v0, swap JSON store for PG via @mosaic/db
- `@mosaic/queue` — migrate from v0 (minimal changes)
- `@mosaicstack/brain` — migrate from v0, swap JSON store for PG via @mosaicstack/db
- `@mosaicstack/queue` — migrate from v0 (minimal changes)
- Gateway routes: conversations, tasks, projects, missions
- WebSocket server for chat streaming
- Basic agent dispatch (single provider, no routing)
### Phase 2: Agent Layer (v0.0.3)
- `@mosaic/agent` — Pi SDK integration, agent pool manager
- `@mosaicstack/agent` — Pi SDK integration, agent pool manager
- Multi-provider support (Anthropic + Ollama minimum)
- Agent routing engine (cost/capability matrix)
- Tool registration (brain, queue, memory tools injected into agent sessions)
- `@mosaic/coord` — migrate from v0, integrate with gateway
- `@mosaicstack/coord` — migrate from v0, integrate with gateway
### Phase 3: Web Dashboard (v0.0.4)
@@ -946,25 +946,25 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
### Phase 4: Memory & Intelligence (v0.0.5)
- `@mosaic/memory` — preference store, insight store, semantic search
- `@mosaic/log` — log ingest, parsing, tiered storage
- `@mosaicstack/memory` — preference store, insight store, semantic search
- `@mosaicstack/log` — log ingest, parsing, tiered storage
- Summarization pipeline
- Memory integration into agent sessions
- Skill management interface (web UI + CLI)
### Phase 5: Remote Control (v0.0.6)
- `@mosaic/discord-plugin` — Discord channel plugin
- `@mosaic/telegram-plugin` — Telegram channel plugin
- `@mosaicstack/discord-plugin` — Discord channel plugin
- `@mosaicstack/telegram-plugin` — Telegram channel plugin
- Plugin host in gateway
- SSO configuration (Authentik)
### Phase 6: CLI & Tools (v0.0.7)
- `@mosaic/cli` — unified CLI with all subcommands
- `@mosaic/prdy` — migrate from v0
- `@mosaic/quality-rails` — migrate from v0
- `@mosaic/mosaic` — install wizard updated for v1
- `@mosaicstack/cli` — unified CLI with all subcommands
- `@mosaicstack/prdy` — migrate from v0
- `@mosaicstack/quality-rails` — migrate from v0
- `@mosaicstack/mosaic` — install wizard updated for v1
- Pi TUI integration (`mosaic tui`)
### Phase 7: Polish & Beta (v0.0.8 → v0.1.0)
@@ -982,11 +982,11 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
## Assumptions
1. RESOLVED: **pgvector is sufficient** for semantic search at v0.1.0 scale (personal/family/team = thousands to low hundreds-of-thousands of vectors). `@mosaic/memory` defines a `VectorStore` interface with pgvector as the default adapter. The interface boundary makes Qdrant a drop-in migration if PG resource contention or scale demands it later. Zero additional infrastructure for v0.1.0. Rationale: Reduces ops burden; pgvector HNSW indexes are fast at this scale; interface abstraction costs almost nothing now.
1. RESOLVED: **pgvector is sufficient** for semantic search at v0.1.0 scale (personal/family/team = thousands to low hundreds-of-thousands of vectors). `@mosaicstack/memory` defines a `VectorStore` interface with pgvector as the default adapter. The interface boundary makes Qdrant a drop-in migration if PG resource contention or scale demands it later. Zero additional infrastructure for v0.1.0. Rationale: Reduces ops burden; pgvector HNSW indexes are fast at this scale; interface abstraction costs almost nothing now.
2. RESOLVED: **Authentik is the first SSO provider** — confirmed, already running in Jason's infrastructure. WorkOS and Keycloak adapters follow in Phase 7.
3. RESOLVED: **NestJS with Fastify adapter for the gateway.** The gateway's complexity (plugin host, agent pool, routing engine, WebSocket hub, MCP server, auth, brain/queue/memory/log integration) warrants NestJS's module system, DI, and guards. Fastify performance preserved via adapter. Aligns with USER.md stated stack ("NestJS API + Next.js web"). @mosaic/brain's Fastify code migrates into a NestJS module.
3. RESOLVED: **NestJS with Fastify adapter for the gateway.** The gateway's complexity (plugin host, agent pool, routing engine, WebSocket hub, MCP server, auth, brain/queue/memory/log integration) warrants NestJS's module system, DI, and guards. Fastify performance preserved via adapter. Aligns with USER.md stated stack ("NestJS API + Next.js web"). @mosaicstack/brain's Fastify code migrates into a NestJS module.
4. RESOLVED: **OpenTelemetry from Phase 0.** Wide-event logging is required from the start. OTEL auto-instrumentation for NestJS/PG/HTTP via `@opentelemetry/sdk-node`. SigNoz as the all-in-one OTEL backend (single Docker service). Every significant operation emits structured events with rich context. Custom spans for agent dispatch, routing decisions, memory writes. Rationale: Retrofitting observability is painful; baking it in from day one means consistent instrumentation across all services.
@@ -1002,4 +1002,4 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
10. ASSUMPTION: **Conversations and messages get their own PG tables** (not stored in brain's entity model). They follow a chat-specific schema with proper foreign keys to users and projects. Rationale: Chat has different access patterns (streaming, pagination, search) than brain entities.
11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaic/agent — only configuration management.
11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaicstack/agent — only configuration management.