xonecas.io
60255
Zn

Zoea-Nova / commit e6b9436

chore(config): drop default_myses and align docs

Remove the unused swarm default and update design and rate-limiting docs to match current provider config and auto-start behavior.

xonecas2026-02-04 e6b9436c06e732d7c7ebc73204723a86c717946a parent 1e2b81b

3 files changed

config.toml+0−1
@@ -1,5 +1,4 @@
11 [swarm]
2-default_myses = 4
32 max_myses = 16
43
54 [providers.ollama]
documentation/INITIAL_IMPLEMENTATION_DESIGN.md+18−26
@@ -47,30 +47,35 @@ Scrollable conversation viewport showing full message history with role-based st
4747 - **TUI Framework:** `bubbletea` (The Elm Architecture for Go).
4848 - **Styling & Components:** `lipgloss` for layouts/colors and `bubbles` for UI elements.
4949 - **LLM Integration:** `go-openai` (OpenAI-compatible client for Ollama and OpenCode Zen).
50-- **MCP Protocol:** Researching `mcp-golang` or similar for robust Model Context Protocol support.
50+- **MCP Protocol:** Custom MCP proxy and tool registry using Streamable HTTP.
5151 - **Configuration:** `github.com/BurntSushi/toml` for TOML parsing.
52-- **Database:** `modernc.org/sqlite` (pure Go, no CGO) or `github.com/mattn/go-sqlite3` (CGO).
52+- **Database:** `modernc.org/sqlite` (pure Go, no CGO).
5353 - **Logging:** `zerolog` for structured, non-blocking logs.
5454
5555 ## Configuration
5656
57-- **Environment Variables:** Primary mechanism for runtime overrides (e.g., `ZOEA_LOG_LEVEL`, `ZOEA_MCP_ENDPOINT`).
57+- **Environment Variables:** Runtime overrides (`ZOEA_MAX_MYSES`, `ZOEA_MCP_ENDPOINT`, `ZOEA_OLLAMA_ENDPOINT`, `ZOEA_OLLAMA_MODEL`, `ZOEA_OLLAMA_TEMPERATURE`, `ZOEA_OLLAMA_RATE_LIMIT`, `ZOEA_OLLAMA_RATE_BURST`, `ZOEA_OPENCODE_ENDPOINT`, `ZOEA_OPENCODE_MODEL`, `ZOEA_OPENCODE_TEMPERATURE`, `ZOEA_OPENCODE_RATE_LIMIT`, `ZOEA_OPENCODE_RATE_BURST`).
5858 - **Config File:** `config.toml` in project root for defaults and structure. Parsed via `github.com/BurntSushi/toml`.
5959 - **Credentials:** Stored in `$HOME/.zoea-nova/credentials.json`. Contains API keys for LLM providers. File permissions should be `0600`.
6060
6161 Example `config.toml`:
6262 ```toml
6363 [swarm]
64-default_myses = 4
6564 max_myses = 16
6665
6766 [providers.ollama]
6867 endpoint = "http://localhost:11434"
69-model = "llama3"
68+model = "qwen3:4b"
69+temperature = 0.7
70+rate_limit = 2.0
71+rate_burst = 3
7072
7173 [providers.opencode_zen]
72-endpoint = "https://api.opencode.ai/v1" # confirm from Zen dashboard
73-model = "zen-default"
74+endpoint = "https://api.opencode.ai/v1"
75+model = "glm-4.7-free"
76+temperature = 0.7
77+rate_limit = 10.0
78+rate_burst = 5
7479
7580 [mcp]
7681 upstream = "https://game.spacemolt.com/mcp"
@@ -121,23 +126,15 @@ CREATE TABLE accounts (
121126 ```
122127
123128 **Schema v6 → v7 Migration:**
124-Requires fresh database. Reset with:
125-```bash
126-make db-reset-accounts
127-```
128-This exports usernames/passwords to `accounts-backup.sql` before recreating the DB.
129+Requires fresh database. See `AGENTS.md` for the reset command and backup details.
129130
130131 **Memory Sources:**
131-- `direct` — Message sent directly to a specific Mysis
132-- `broadcast` — Message broadcast to all Myses (swarm command)
133-- `system` — System prompts
134-- `llm` — LLM-generated responses
135-- `tool` — Tool call results
132+See `AGENTS.md` for the canonical terminology.
136133
137134 ## Mysis Lifecycle
138135
139136 - **Ownership:** The Commander (orchestrator) owns all Mysis lifecycles.
140-- **Creation:** User creates Myses via TUI controls. Default swarm size: **4 Myses**.
137+- **Creation:** User creates Myses via TUI controls.
141138 - **Limits:** Configurable `max_myses` (default 16). Enforced at Commander level, but user controls count from TUI.
142139 - **States:** `idle` → `running` → `stopped` / `errored`.
143140 - **TUI Controls:**
@@ -148,7 +145,7 @@ This exports usernames/passwords to `accounts-backup.sql` before recreating the
148145 - **Broadcast Message:** Send a message/objective to all Myses.
149146 - **Direct Message:** Send a message to a specific Mysis.
150147 - **Configure Mysis:** Set model/provider per Mysis (Ollama or OpenCode Zen).
151-- **Recovery:** On application restart, Myses are rehydrated from SQLite in `stopped` state; user must explicitly relaunch.
148+- **Recovery:** On application restart, Myses are rehydrated from SQLite and auto-started.
152149
153150 ## Keyboard Shortcuts
154151
@@ -166,13 +163,8 @@ Minimal set matching TUI controls:
166163
167164 ## Build & Operations
168165
169-- **Task Runner:** `Makefile` for standard commands.
170-- **Commands:**
171- - `make fmt` — Format code (`go fmt ./...`)
172- - `make build` — Compile binary
173- - `make run` — Build and start
174- - `make test` — Run tests
175-- **Versioning:** Semver. Version injected at build time via `-ldflags`.
166+Use `Makefile` targets documented in `AGENTS.md`.
167+Versioning follows the rules in `AGENTS.md`.
176168
177169 ## Logging
178170
documentation/RATE_LIMITING_PLAN.md+21−88
@@ -1,45 +1,18 @@
1-# Provider Rate Limiting Plan
1+# Provider Rate Limiting
22
3-## Goal
3+## Overview
44
5-Prevent provider overload and external API rate limiting by enforcing a shared request rate per provider. All myses using the same provider should share a single limiter.
5+Zoea Nova enforces shared request limits per provider to prevent GPU overload (Ollama) and reduce the risk of upstream throttling (OpenCode Zen). Every mysis created with the same provider shares a single limiter.
66
7-## Research Findings
7+## Implementation
88
9-### Ollama (local)
9+- Each provider factory owns a `golang.org/x/time/rate` limiter created at startup.
10+- Providers created by the factory reuse that limiter, so the rate is shared across all myses for that provider.
11+- Requests in `Chat`, `ChatWithTools`, and `Stream` call `limiter.Wait(ctx)` before executing.
1012
11-- No built-in API rate limits for local deployments.
12-- Bottleneck is hardware throughput and concurrency.
13-- We should cap request rate to avoid GPU overload and reduce tail latency.
13+## Configuration
1414
15-### OpenCode Zen (remote)
16-
17-- Public documentation does not specify explicit request rate limits.
18-- Users report stalled requests that are consistent with server-side rate limiting.
19-- We should enforce a conservative request rate and handle 429 responses.
20-
21-### Implementation Approach
22-
23-Use `golang.org/x/time/rate` token buckets. The provider factory owns the limiter and injects it into each provider instance. This makes rate limiting shared per provider rather than per mysis.
24-
25-## Proposed Design
26-
27-### Shared Limiter Per Provider Factory
28-
29-- Each provider factory is instantiated once at startup.
30-- Each factory owns a `rate.Limiter` configured from `config.toml`.
31-- Providers created by a factory share the same limiter reference.
32-
33-### Request Flow
34-
35-1. Mysis prepares a request.
36-2. Provider waits on limiter (`limiter.Wait(ctx)`).
37-3. Provider executes the request.
38-4. If the request fails with 429, emit a rate limit event and return error.
39-
40-## Configuration Changes
41-
42-Add two optional fields to `ProviderConfig`:
15+Rate limits are configured per provider in `config.toml`.
4316
4417 ```toml
4518 [providers.ollama]
@@ -57,60 +30,20 @@ rate_limit = 10.0
5730 rate_burst = 5
5831 ```
5932
60-Defaults if omitted:
61-
62-- `rate_limit`: 2.0 for Ollama, 10.0 for OpenCode Zen
63-- `rate_burst`: 3 for Ollama, 5 for OpenCode Zen
33+## Environment Overrides
6434
65-## Implementation Steps
35+- `ZOEA_OLLAMA_RATE_LIMIT`
36+- `ZOEA_OLLAMA_RATE_BURST`
37+- `ZOEA_OPENCODE_RATE_LIMIT`
38+- `ZOEA_OPENCODE_RATE_BURST`
6639
67-### Phase 1: Config Layer
40+## Request Flow
6841
69-- Add `RateLimit` and `RateBurst` fields to `ProviderConfig`.
70-- Add environment overrides:
71- - `ZOEA_OLLAMA_RATE_LIMIT`
72- - `ZOEA_OLLAMA_RATE_BURST`
73- - `ZOEA_OPENCODE_RATE_LIMIT`
74- - `ZOEA_OPENCODE_RATE_BURST`
75-
76-### Phase 2: Provider Factory
77-
78-- Update `OllamaFactory` and `OpenCodeFactory` to own a limiter.
79-- Add constructors that accept `rate_limit` and `rate_burst`.
80-- Factory `Create()` injects the limiter into the provider instance.
81-
82-### Phase 3: Provider Calls
83-
84-- Add limiter field to `OllamaProvider` and `OpenCodeProvider`.
85-- Wrap all `Chat`, `ChatWithTools`, and `Stream` entry points with `limiter.Wait(ctx)`.
86-- If `Wait` returns an error, return immediately to caller.
87-
88-### Phase 4: Error Reporting
89-
90-- Add a dedicated event type (for UI/telemetry) when rate limit triggers.
91-- On HTTP 429, emit that event with provider name and model.
92-
93-### Phase 5: Tests
94-
95-- Config tests: verify parsing of `rate_limit` and `rate_burst`.
96-- Provider tests: ensure limiter blocks or delays requests.
97-- Commander tests: ensure myses sharing a provider are rate limited together.
98-
99-## Files To Change
100-
101-- `internal/config/config.go`
102-- `config.toml`
103-- `internal/provider/factory.go`
104-- `internal/provider/ollama.go`
105-- `internal/provider/opencode.go`
106-- `internal/provider/provider.go`
107-- `internal/core/events.go`
108-- `internal/core/commander.go`
109-- `documentation/KNOWN_ISSUES.md`
110-- Tests: `internal/config/config_test.go`, `internal/provider/*_test.go`, `internal/core/commander_test.go`
42+1. Mysis prepares a request.
43+2. Provider waits on the shared limiter with `limiter.Wait(ctx)`.
44+3. Provider executes the request if the limiter allows it.
11145
112-## Verification
46+## Behavior Notes
11347
114-1. `make test`
115-2. `make build`
116-3. Manual test: start two myses on the same provider, send rapid messages, observe throttling
48+- When the limiter blocks, the call waits until tokens are available or the context is canceled.
49+- Limiter errors are returned to the caller without additional event emission.