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

docs: agent platform architecture plan — augmentation + task breakdown (#173)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source 
Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>
This commit was merged in pull request #173.
This commit is contained in:
Jason Woltje
2026-03-16 01:28:29 +00:00
committed by jason.woltje
parent bd81c12071
commit d5a1791dc5
7 changed files with 1866 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/MISSION-MANIFEST.md
View File

@@ -39,7 +39,7 @@
| 5 | ms-162 | Phase 5: Remote Control (v0.0.6) | done | — | #99 | 2026-03-14 | 2026-03-14 |
| 6 | ms-163 | Phase 6: CLI & Tools (v0.0.7) | done | — | #104 | 2026-03-14 | 2026-03-14 |
| 7 | ms-164 | Phase 7: Feature Completion (v0.0.8) | done | — | — | 2026-03-15 | 2026-03-15 |
| 8 | ms-165 | Phase 8: Polish & Beta (v0.1.0) | not-started | — | — | — | — |
| 8 | ms-165 | Phase 8: Polish & Beta (v0.1.0) | in-progress | — | — | 2026-03-15 | — |
## Deployment

171
docs/TASKS.md
View File

@@ -2,82 +2,95 @@
> Single-writer: orchestrator only. Workers read but never modify.
| id | status | milestone | description | pr | notes |
| ------ | ----------- | --------- | --------------------------------------------------------------------- | ---- | ------------- |
| P0-001 | done | Phase 0 | Scaffold monorepo | #60 | #1 |
| P0-002 | done | Phase 0 | @mosaic/types — migrate and extend shared types | #65 | #2 |
| P0-003 | done | Phase 0 | @mosaic/db — Drizzle schema and PG connection | #67 | #3 |
| P0-004 | done | Phase 0 | @mosaic/auth — BetterAuth email/password setup | #68 | #4 |
| P0-005 | done | Phase 0 | Docker Compose — PG 17, Valkey 8, SigNoz | #65 | #5 |
| P0-006 | done | Phase 0 | OTEL foundation — OpenTelemetry SDK setup | #65 | #6 |
| P0-007 | done | Phase 0 | CI pipeline — Woodpecker config | #69 | #7 |
| P0-008 | done | Phase 0 | Project docs — AGENTS.md, CLAUDE.md, README | #69 | #8 |
| P0-009 | done | Phase 0 | Verify Phase 0 — CI green, all packages build | #70 | #9 |
| P1-001 | done | Phase 1 | apps/gateway scaffold — NestJS + Fastify adapter | #61 | #10 |
| P1-002 | done | Phase 1 | Auth middleware — BetterAuth session validation | #71 | #11 |
| P1-003 | done | Phase 1 | @mosaic/brain — migrate from v0, PG backend | #71 | #12 |
| P1-004 | done | Phase 1 | @mosaic/queue — migrate from v0 | #71 | #13 |
| P1-005 | done | Phase 1 | Gateway routes — conversations CRUD + messages | #72 | #14 |
| P1-006 | done | Phase 1 | Gateway routes — tasks, projects, missions CRUD | #72 | #15 |
| P1-007 | done | Phase 1 | WebSocket server — chat streaming | #61 | #16 |
| P1-008 | done | Phase 1 | Basic agent dispatch — single provider | #61 | #17 |
| P1-009 | done | Phase 1 | Verify Phase 1 — gateway functional, API tested | #73 | #18 |
| P2-001 | done | Phase 2 | @mosaic/agent — Pi SDK integration + agent pool | #61 | #19 |
| P2-002 | done | Phase 2 | Multi-provider support — Anthropic + Ollama | #74 | #20 |
| P2-003 | done | Phase 2 | Agent routing engine — cost/capability matrix | #75 | #21 |
| P2-004 | done | Phase 2 | Tool registration — brain, queue, memory tools | #76 | #22 |
| P2-005 | done | Phase 2 | @mosaic/coord — migrate from v0, gateway integration | #77 | #23 |
| P2-006 | done | Phase 2 | Agent session management — tmux + monitoring | #78 | #24 |
| P2-007 | done | Phase 2 | Verify Phase 2 — multi-provider routing works | #79 | #25 |
| P3-001 | done | Phase 3 | apps/web scaffold — Next.js 16 + BetterAuth + Tailwind | #82 | #26 |
| P3-002 | done | Phase 3 | Auth pages — login, registration, SSO redirect | #83 | #27 |
| P3-003 | done | Phase 3 | Chat UI — conversations, messages, streaming | #84 | #28 |
| P3-004 | done | Phase 3 | Task management — list view + kanban board | #86 | #29 |
| P3-005 | done | Phase 3 | Project & mission views — dashboard + PRD viewer | #87 | #30 |
| P3-006 | done | Phase 3 | Settings — provider config, profile, integrations | #88 | #31 |
| P3-007 | done | Phase 3 | Admin panel — user management, RBAC | #89 | #32 |
| P3-008 | done | Phase 3 | Verify Phase 3 — web dashboard functional E2E | — | #33 |
| P4-001 | done | Phase 4 | @mosaic/memory — preference + insight stores | — | #34 |
| P4-002 | done | Phase 4 | Semantic search — pgvector embeddings + search API | — | #35 |
| P4-003 | done | Phase 4 | @mosaic/log — log ingest, parsing, tiered storage | — | #36 |
| P4-004 | done | Phase 4 | Summarization pipeline — Haiku-tier LLM + cron | — | #37 |
| P4-005 | done | Phase 4 | Memory integration — inject into agent sessions | — | #38 |
| P4-006 | done | Phase 4 | Skill management — catalog, install, config | — | #39 |
| P4-007 | done | Phase 4 | Verify Phase 4 — memory + log pipeline working | — | #40 |
| P5-001 | done | Phase 5 | Plugin host — gateway plugin loading + channel interface | — | #41 |
| P5-002 | done | Phase 5 | @mosaic/discord-plugin — Discord bot + channel plugin | #61 | #42 |
| P5-003 | done | Phase 5 | @mosaic/telegram-plugin — Telegraf bot + channel plugin | — | #43 |
| P5-004 | done | Phase 5 | SSO — Authentik OIDC adapter end-to-end | — | #44 |
| P5-005 | done | Phase 5 | Verify Phase 5 — Discord + Telegram + SSO working | #99 | #45 |
| P6-001 | done | Phase 6 | @mosaic/cli — unified CLI binary + subcommands | #104 | #46 |
| P6-002 | done | Phase 6 | @mosaic/prdy — migrate PRD wizard from v0 | #101 | #47 |
| P6-003 | done | Phase 6 | @mosaic/quality-rails — migrate scaffolder from v0 | #100 | #48 |
| P6-004 | done | Phase 6 | @mosaic/mosaic — install wizard for v1 | #103 | #49 |
| P6-005 | done | Phase 6 | Pi TUI integration — mosaic tui | #61 | #50 |
| P6-006 | done | Phase 6 | Verify Phase 6 — CLI functional, all subcommands | — | #51 |
| P7-009 | done | Phase 7 | Web chat — WebSocket integration, streaming, conversation switching | #136 | #120 W1 done |
| P7-001 | done | Phase 7 | MCP endpoint hardening — streamable HTTP transport | #137 | #52 W1 done |
| P7-010 | done | Phase 7 | Web conversation management — list, search, rename, delete, archive | #139 | #121 W2 done |
| P7-015 | done | Phase 7 | Agent tool expansion — file ops, git, shell exec, web fetch | #138 | #126 W2 done |
| P7-011 | done | Phase 7 | Web project detail views — missions, tasks, PRDs, dashboards | #140 | #122 W3 done |
| P7-016 | done | Phase 7 | MCP client — gateway connects to external MCP servers as tools | #141 | #127 W3 done |
| P7-012 | done | Phase 7 | Web provider management UI — add, configure, test LLM providers | #142 | #123 W4 done |
| P7-017 | done | Phase 7 | Agent skill invocation — load and execute skills from catalog | #143 | #128 W4 done |
| P7-013 | done | Phase 7 | Web settings persistence — profile, preferences save to DB | #145 | #124 W5 done |
| P7-018 | done | Phase 7 | CLI model/provider switching — --model, --provider, /model in TUI | #144 | #129 W5 done |
| P7-014 | done | Phase 7 | Web admin panel — user CRUD, role assignment, system health | #150 | #125 W6 done |
| P7-019 | done | Phase 7 | CLI session management — list, resume, destroy sessions | #146 | #130 W6 done |
| P7-020 | done | Phase 7 | Coord DB migration — project-scoped missions, multi-tenant RBAC | #149 | #131 W7 done |
| FIX-02 | done | Backlog | TUI agent:end — fix React state updater side-effect | #147 | #133 W8 done |
| FIX-03 | done | Backlog | Agent session — cwd sandbox, system prompt, tool restrictions | #148 | #134 W8 done |
| P7-004 | done | Phase 7 | E2E test suite — Playwright critical paths | #152 | #55 W9 done |
| P7-006 | done | Phase 7 | Documentation — user guide, admin guide, dev guide | #151 | #57 W9 done |
| P7-007 | done | Phase 7 | Bare-metal deployment docs + .env.example | #153 | #58 W9 done |
| P7-021 | done | Phase 7 | Verify Phase 7 — feature-complete platform E2E | — | #132 W10 done |
| P8-005 | done | Phase 8 | CLI command architecture — DB schema + brain repo + gateway endpoints | #158 | |
| P8-006 | done | Phase 8 | CLI command architecture — agent, mission, prdy commands + TUI mods | #158 | |
| P8-001 | not-started | Phase 8 | Additional SSO providers — WorkOS + Keycloak | — | #53 |
| P8-002 | not-started | Phase 8 | Additional LLM providers — Codex, Z.ai, LM Studio, llama.cpp | — | #54 |
| P8-003 | not-started | Phase 8 | Performance optimization | — | #56 |
| P8-004 | not-started | Phase 8 | Beta release gate — v0.1.0 tag | — | #59 |
| FIX-01 | done | Backlog | Call piSession.dispose() in AgentService.destroySession | #78 | #62 |
| id | status | milestone | description | pr | notes |
| ------ | ----------- | --------- | -------------------------------------------------------------------------------------------------- | ---- | ------------- |
| P0-001 | done | Phase 0 | Scaffold monorepo | #60 | #1 |
| P0-002 | done | Phase 0 | @mosaic/types — migrate and extend shared types | #65 | #2 |
| P0-003 | done | Phase 0 | @mosaic/db — Drizzle schema and PG connection | #67 | #3 |
| P0-004 | done | Phase 0 | @mosaic/auth — BetterAuth email/password setup | #68 | #4 |
| P0-005 | done | Phase 0 | Docker Compose — PG 17, Valkey 8, SigNoz | #65 | #5 |
| P0-006 | done | Phase 0 | OTEL foundation — OpenTelemetry SDK setup | #65 | #6 |
| P0-007 | done | Phase 0 | CI pipeline — Woodpecker config | #69 | #7 |
| P0-008 | done | Phase 0 | Project docs — AGENTS.md, CLAUDE.md, README | #69 | #8 |
| P0-009 | done | Phase 0 | Verify Phase 0 — CI green, all packages build | #70 | #9 |
| P1-001 | done | Phase 1 | apps/gateway scaffold — NestJS + Fastify adapter | #61 | #10 |
| P1-002 | done | Phase 1 | Auth middleware — BetterAuth session validation | #71 | #11 |
| P1-003 | done | Phase 1 | @mosaic/brain — migrate from v0, PG backend | #71 | #12 |
| P1-004 | done | Phase 1 | @mosaic/queue — migrate from v0 | #71 | #13 |
| P1-005 | done | Phase 1 | Gateway routes — conversations CRUD + messages | #72 | #14 |
| P1-006 | done | Phase 1 | Gateway routes — tasks, projects, missions CRUD | #72 | #15 |
| P1-007 | done | Phase 1 | WebSocket server — chat streaming | #61 | #16 |
| P1-008 | done | Phase 1 | Basic agent dispatch — single provider | #61 | #17 |
| P1-009 | done | Phase 1 | Verify Phase 1 — gateway functional, API tested | #73 | #18 |
| P2-001 | done | Phase 2 | @mosaic/agent — Pi SDK integration + agent pool | #61 | #19 |
| P2-002 | done | Phase 2 | Multi-provider support — Anthropic + Ollama | #74 | #20 |
| P2-003 | done | Phase 2 | Agent routing engine — cost/capability matrix | #75 | #21 |
| P2-004 | done | Phase 2 | Tool registration — brain, queue, memory tools | #76 | #22 |
| P2-005 | done | Phase 2 | @mosaic/coord — migrate from v0, gateway integration | #77 | #23 |
| P2-006 | done | Phase 2 | Agent session management — tmux + monitoring | #78 | #24 |
| P2-007 | done | Phase 2 | Verify Phase 2 — multi-provider routing works | #79 | #25 |
| P3-001 | done | Phase 3 | apps/web scaffold — Next.js 16 + BetterAuth + Tailwind | #82 | #26 |
| P3-002 | done | Phase 3 | Auth pages — login, registration, SSO redirect | #83 | #27 |
| P3-003 | done | Phase 3 | Chat UI — conversations, messages, streaming | #84 | #28 |
| P3-004 | done | Phase 3 | Task management — list view + kanban board | #86 | #29 |
| P3-005 | done | Phase 3 | Project & mission views — dashboard + PRD viewer | #87 | #30 |
| P3-006 | done | Phase 3 | Settings — provider config, profile, integrations | #88 | #31 |
| P3-007 | done | Phase 3 | Admin panel — user management, RBAC | #89 | #32 |
| P3-008 | done | Phase 3 | Verify Phase 3 — web dashboard functional E2E | — | #33 |
| P4-001 | done | Phase 4 | @mosaic/memory — preference + insight stores | — | #34 |
| P4-002 | done | Phase 4 | Semantic search — pgvector embeddings + search API | — | #35 |
| P4-003 | done | Phase 4 | @mosaic/log — log ingest, parsing, tiered storage | — | #36 |
| P4-004 | done | Phase 4 | Summarization pipeline — Haiku-tier LLM + cron | — | #37 |
| P4-005 | done | Phase 4 | Memory integration — inject into agent sessions | — | #38 |
| P4-006 | done | Phase 4 | Skill management — catalog, install, config | — | #39 |
| P4-007 | done | Phase 4 | Verify Phase 4 — memory + log pipeline working | — | #40 |
| P5-001 | done | Phase 5 | Plugin host — gateway plugin loading + channel interface | — | #41 |
| P5-002 | done | Phase 5 | @mosaic/discord-plugin — Discord bot + channel plugin | #61 | #42 |
| P5-003 | done | Phase 5 | @mosaic/telegram-plugin — Telegraf bot + channel plugin | — | #43 |
| P5-004 | done | Phase 5 | SSO — Authentik OIDC adapter end-to-end | — | #44 |
| P5-005 | done | Phase 5 | Verify Phase 5 — Discord + Telegram + SSO working | #99 | #45 |
| P6-001 | done | Phase 6 | @mosaic/cli — unified CLI binary + subcommands | #104 | #46 |
| P6-002 | done | Phase 6 | @mosaic/prdy — migrate PRD wizard from v0 | #101 | #47 |
| P6-003 | done | Phase 6 | @mosaic/quality-rails — migrate scaffolder from v0 | #100 | #48 |
| P6-004 | done | Phase 6 | @mosaic/mosaic — install wizard for v1 | #103 | #49 |
| P6-005 | done | Phase 6 | Pi TUI integration — mosaic tui | #61 | #50 |
| P6-006 | done | Phase 6 | Verify Phase 6 — CLI functional, all subcommands | — | #51 |
| P7-009 | done | Phase 7 | Web chat — WebSocket integration, streaming, conversation switching | #136 | #120 W1 done |
| P7-001 | done | Phase 7 | MCP endpoint hardening — streamable HTTP transport | #137 | #52 W1 done |
| P7-010 | done | Phase 7 | Web conversation management — list, search, rename, delete, archive | #139 | #121 W2 done |
| P7-015 | done | Phase 7 | Agent tool expansion — file ops, git, shell exec, web fetch | #138 | #126 W2 done |
| P7-011 | done | Phase 7 | Web project detail views — missions, tasks, PRDs, dashboards | #140 | #122 W3 done |
| P7-016 | done | Phase 7 | MCP client — gateway connects to external MCP servers as tools | #141 | #127 W3 done |
| P7-012 | done | Phase 7 | Web provider management UI — add, configure, test LLM providers | #142 | #123 W4 done |
| P7-017 | done | Phase 7 | Agent skill invocation — load and execute skills from catalog | #143 | #128 W4 done |
| P7-013 | done | Phase 7 | Web settings persistence — profile, preferences save to DB | #145 | #124 W5 done |
| P7-018 | done | Phase 7 | CLI model/provider switching — --model, --provider, /model in TUI | #144 | #129 W5 done |
| P7-014 | done | Phase 7 | Web admin panel — user CRUD, role assignment, system health | #150 | #125 W6 done |
| P7-019 | done | Phase 7 | CLI session management — list, resume, destroy sessions | #146 | #130 W6 done |
| P7-020 | done | Phase 7 | Coord DB migration — project-scoped missions, multi-tenant RBAC | #149 | #131 W7 done |
| FIX-02 | done | Backlog | TUI agent:end — fix React state updater side-effect | #147 | #133 W8 done |
| FIX-03 | done | Backlog | Agent session — cwd sandbox, system prompt, tool restrictions | #148 | #134 W8 done |
| P7-004 | done | Phase 7 | E2E test suite — Playwright critical paths | #152 | #55 W9 done |
| P7-006 | done | Phase 7 | Documentation — user guide, admin guide, dev guide | #151 | #57 W9 done |
| P7-007 | done | Phase 7 | Bare-metal deployment docs + .env.example | #153 | #58 W9 done |
| P7-021 | done | Phase 7 | Verify Phase 7 — feature-complete platform E2E | — | #132 W10 done |
| P8-005 | done | Phase 8 | CLI command architecture — DB schema + brain repo + gateway endpoints | #158 | |
| P8-006 | done | Phase 8 | CLI command architecture — agent, mission, prdy commands + TUI mods | #158 | |
| P8-007 | not-started | Phase 8 | DB migrations — preferences.mutable + teams + team_members + projects.teamId | — | #160 |
| P8-008 | not-started | Phase 8 | @mosaic/types — CommandDef, CommandManifest, new socket events | — | #161 |
| P8-009 | not-started | Phase 8 | TUI Phase 1 — slash command parsing, local commands, system message rendering, InputBar wiring | — | #162 |
| P8-010 | not-started | Phase 8 | Gateway Phase 2 — CommandRegistryService, CommandExecutorService, socket + REST commands | — | #163 |
| P8-011 | not-started | Phase 8 | Gateway Phase 3 — PreferencesService, /preferences REST, /system Valkey override, prompt injection | — | #164 |
| P8-012 | not-started | Phase 8 | Gateway Phase 4 — /agent, /provider (URL+clipboard), /mission, /prdy, /tools commands | — | #165 |
| P8-013 | not-started | Phase 8 | Gateway Phase 5 — MosaicPlugin lifecycle, ReloadService, hot reload, system:reload TUI | — | #166 |
| P8-014 | not-started | Phase 8 | Gateway Phase 6 — SessionGCService (all tiers), /gc command, cron integration | — | #167 |
| P8-015 | not-started | Phase 8 | Gateway Phase 7 — WorkspaceService, ProjectBootstrapService, teams project ownership | — | #168 |
| P8-016 | not-started | Phase 8 | Security — file/git/shell tool strict path hardening, sandbox escape prevention | — | #169 |
| P8-017 | not-started | Phase 8 | TUI Phase 8 — autocomplete sidebar, fuzzy match, arg hints, up-arrow history | — | #170 |
| P8-018 | done | Phase 8 | Spin-off plan stubs — Gatekeeper, Task Queue Unification, Chroot Sandboxing | — | #171 |
| P8-019 | not-started | Phase 8 | Verify Platform Architecture — integration + E2E verification | — | #172 |
| P8-001 | not-started | Phase 8 | Additional SSO providers — WorkOS + Keycloak | — | #53 |
| P8-002 | not-started | Phase 8 | Additional LLM providers — Codex, Z.ai, LM Studio, llama.cpp | — | #54 |
| P8-003 | not-started | Phase 8 | Performance optimization | — | #56 |
| P8-004 | not-started | Phase 8 | Beta release gate — v0.1.0 tag | — | #59 |
| FIX-01 | done | Backlog | Call piSession.dispose() in AgentService.destroySession | #78 | #62 |

1572
docs/plans/2026-03-15-agent-platform-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

60
docs/plans/chroot-sandboxing.md Normal file
View File

@@ -0,0 +1,60 @@
# Chroot Agent Sandboxing — Process Isolation for Agent Tool Execution
> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces → Chroot Agent Sandboxing).
> Implement after Workspaces (P8-015) is complete. Requires workspace directory structure and `WorkspaceService` to be operational.
**Date:** 2026-03-15
**Packages:** `apps/gateway`
---
## Problem Statement
Agent sessions can use file, git, and shell tools. Path validation in tools is defense-in-depth but insufficient alone — an agent with shell access can run `cat /opt/mosaic/.workspaces/other_user/...` and bypass gateway RBAC.
Chroot provides OS-level enforcement: tool processes literally cannot see outside their workspace directory.
---
## Design (Sweet Spot)
Chroot strikes the balance between full container isolation (too heavy per session) and path validation only (escape-prone):
- Gateway spawns tool processes inside a chroot rooted at the session's `sandboxDir`
- Requires `CAP_SYS_CHROOT` capability on the gateway process (not full root)
- Chroot environment provisioned by `WorkspaceService` on workspace creation (minimal deps: git, shell utils, language runtimes as needed)
- Alternative for Docker deployments: Linux `unshare` namespaces (lighter, no chroot env setup)
---
## Scope (To Be Designed)
- [ ] Chroot environment provisioning — `WorkspaceService.provisionChroot(workspacePath)` on project creation
- [ ] Minimal chroot deps — identify required binaries/libs per tool type (file: none; git: git binary; shell: bash, common utils)
- [ ] Gateway capability — document `CAP_SYS_CHROOT` requirement; Dockerfile and docker-compose.yml changes
- [ ] Tool process spawning — modify `createShellTools`, `createFileTools`, `createGitTools` to spawn via chroot wrapper
- [ ] Docker alternative — `unshare --mount --pid --user` namespace wrapper as fallback for environments without chroot capability
- [ ] Defense-in-depth layering — chroot + path validation both active; neither alone is sufficient
- [ ] Chroot cleanup — integrate with `SessionGCService` / workspace deletion
- [ ] AppArmor/SELinux profiles (v2) — restrict gateway process file access patterns for multi-tenant hardening
---
## Security Constraints
- What lives **inside** the chroot (agent-accessible): workspace files, git repo, language runtimes
- What lives **outside** the chroot (gateway-only, never agent-accessible): Valkey connection, PG connection, other users' workspaces, gateway config, OTEL endpoint, credentials
---
## Dependencies
- Workspaces (P8-015) — chroot is rooted at workspace directory; workspace must exist first
- Tool hardening (P8-016) — path validation stays active as defense-in-depth alongside chroot
---
## References
- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Chroot Agent Sandboxing" section
- Current tool implementations: `apps/gateway/src/agent/tools/`

53
docs/plans/gatekeeper-service.md Normal file
View File

@@ -0,0 +1,53 @@
# Gatekeeper Service — PR Review, Quality Gates & Merge Authority
> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces).
> Implement after Workspaces (P8-015) is complete and the workspace/git infrastructure is operational.
**Date:** 2026-03-15
**Packages:** `apps/gateway`, `packages/types`, `packages/agent`
---
## Problem Statement
Project agents create PRs but cannot review or merge their own work. A separate, isolated agent service with read-only code access and quality gate enforcement is needed to act as the authoritative merge authority.
The Gatekeeper existed in the old Mosaic codebase and must be ported/redesigned for mosaic-mono-v1.
---
## Key Design Constraints
- **Isolated trust boundary** — project agents cannot invoke Gatekeeper directly; it listens for PR events from the git provider
- **`isSystem: true`** — system agent, not editable by users
- **Read-only code access** — reads diffs and runs checks; cannot commit or push
- **Quality gates required before merge** — lint, typecheck, test results must pass
- **Cannot self-approve** — the agent that authored the PR cannot be the Gatekeeper for that PR
---
## Scope (To Be Designed)
- [ ] Gatekeeper agent bootstrap — system agent config, tool set, prompt engineering
- [ ] PR event listener — Gitea/GitHub webhook integration (PR opened/updated/ready)
- [ ] Quality gate runner — trigger CI checks, poll for results, enforce pass criteria
- [ ] Review generation — LLM-driven code review comment generation
- [ ] Merge execution — approve + merge when gates pass; reject with comments when they fail
- [ ] Configurable strictness — per-project required checks, review depth
- [ ] Trust boundary enforcement — gateway rejects Gatekeeper tool calls that exceed read-only scope
- [ ] Audit trail — OTEL spans for all Gatekeeper decisions (approve/reject/merge)
---
## Dependencies
- Workspaces (P8-015) — Gatekeeper needs project workspace layout to locate code
- Git provider API tools — PR creation/review/merge API (Gitea/GitHub/GitLab)
- CI/CD tool integration — Woodpecker pipeline status polling
---
## References
- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Gatekeeper Service" section
- Workspace RBAC and agent trust model: same document → "RBAC & Filesystem Security"

60
docs/plans/task-queue-unification.md Normal file
View File

@@ -0,0 +1,60 @@
# Task Queue Unification — @mosaic/queue as Unified Orchestration Layer
> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Task Queue & Orchestration section).
> Implement after Workspaces (P8-015) is complete. Requires workspace file structure to be in place.
**Date:** 2026-03-15
**Packages:** `packages/queue`, `packages/coord`, `packages/db`, `apps/gateway`
---
## Problem Statement
Two disconnected task systems exist:
1. **`@mosaic/coord`** — file-based missions (`mission.json`, `TASKS.md`), file locks, subprocess spawning. Single-machine orchestrator pattern.
2. **PG tables** (`tasks`, `mission_tasks`, `missions`) — DB-backed CRUD, REST API, Brain repos.
An agent using `coord_mission_status` gets file data. The dashboard shows DB data. They are never in sync.
---
## Vision
`@mosaic/queue` becomes the unified task orchestration service bridging PG, workspace files, and Valkey:
- DB is source of truth for structured state (status, assignees, timestamps)
- Workspace files (`TASKS.md`, PRDs) are working copies for agent interaction
- Valkey handles real-time assignment queues and agent claim locks
- Flatfile fallback for no-DB single-machine deployments (preserves `@mosaic/coord` pattern)
---
## Scope (To Be Designed)
- [ ] `@mosaic/queue` refactor — elevate from ioredis primitive to task orchestration service
- [ ] DB ↔ file sync layer — writes to PG propagate to `TASKS.md`; file edits by agents sync back
- [ ] Task assignment queue — Valkey-backed RPUSH/BLPOP for agent task claiming
- [ ] Agent claim locks — `mosaic:queue:project:{id}:lock:{taskId}` with TTL
- [ ] `@mosaic/coord` consolidation — file-based ops ported into queue service; `@mosaic/coord` becomes thin adapter or deprecated
- [ ] Flatfile fallback — queue service writes JSON manifests when PG unavailable
- [ ] Status pub/sub — real-time task status updates via Valkey pub/sub
- [ ] Dependency resolution — block task assignment until dependencies are met
- [ ] Orchestrator monitor — gateway process watches task queue, assigns next based on dependency graph
- [ ] API surface — queue service exposes typed interface used by agents, gateway, and CLI
---
## Dependencies
- Workspaces (P8-015) — file sync targets the workspace directory structure
- Teams architecture (P8-007) — project ownership determines queue namespacing
- DB schema stable — task/mission tables must not change mid-unification
---
## References
- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Task Queue & Orchestration" section
- Current `@mosaic/coord` implementation: `packages/coord/src/`
- Current `@mosaic/queue` implementation: `packages/queue/src/`

28
docs/scratchpads/mvp-20260312.md
View File

@@ -238,3 +238,31 @@ Issues closed: #52, #55, #57, #58, #120-#134
- TUI: --agent and --project flags, agent name display in top bar, agentId in socket payload.
- Types: agentId added to ChatMessagePayload.
- Tests: 23/23 gateway tests pass (updated ownership test for user-scoped missions).
### Session 14 — Platform Architecture Plan Augmentation + Task Breakdown
| Session | Date | Milestone | Tasks Done | Outcome |
| ------- | ---------- | --------- | ---------- | ------------------------------------------------------------- |
| 14 | 2026-03-15 | Phase 8 | P8-018 | Augmented plan, created 13 issues, created Phase 8 milestone. |
**Decisions made:**
- This plan is Phase 7 feature extension work, not Phase 8 beta scope. P8-001–P8-004 (SSO, LLM, perf, release gate) are deferred to far future.
- `/provider` OAuth in TUI: URL-to-clipboard + Valkey poll token pattern (same as Pi agent)
- Add `mutable` column to preferences now (P8-007 DB migration)
- Teams architecture: `teams` + `team_members` tables, `teamId`/`ownerType` on projects. Workspace path branches on owner type: `users/<uid>/` vs `teams/<tid>/`.
- Phase dependency chain decided: Wave 1 (DB+Types) → Wave 2 (TUI+toolhardening) → Wave 3 (gateway registry, gating) → Wave 4 (prefs+commands) → Wave 5 (reload+GC) → Wave 6 (workspaces) → Wave 7 (autocomplete) → Wave 8 (verify).
**Plan augmentations added:**
- Teams Architecture section (DB schema, workspace paths, RBAC)
- REST Route Specifications table
- `/provider` OAuth flow (URL+clipboard+polling)
- Preferences `mutable` migration spec
- Test Strategy (per-task test files + key test cases)
- Phase Execution Order (dependency graph + wave plan)
**Issues created:** #160–#172 (Gitea milestone ms-165)
**P8-018 closed:** Spin-off stubs created (gatekeeper-service.md, task-queue-unification.md, chroot-sandboxing.md)
**Next:** Begin execution at Wave 1 — P8-007 (DB migrations) + P8-008 (Types) in parallel.