xonecas.io
60255
Zn

Zoea-Nova / commit 61bb07d

docs: add implementation plans and update known issues

Add comprehensive documentation for implemented features:

- OPENCODE_ZEN_MODELS.md: Document free OpenCode Zen models available
  during beta period (GLM 4.7, Kimi K2.5, MiniMax M2.1, etc.)

- PER_MYSIS_CONFIG_PLAN.md: Complete implementation plan for per-mysis
  provider/model/temperature configuration (already implemented)

- RATE_LIMITING_PLAN.md: Design document for provider rate limiting
  with shared limiters (already implemented)

- Update KNOWN_ISSUES.md: Mark completed items and add new issues
  discovered during testing

- Update AGENTS.md: Add versioning rules and TUI testing guidelines

- Update tui_test.go: Fix test expectations for Unicode character widths

No UI or DB schema changes.

xonecas2026-02-04 61bb07df28cf6f0a6089797e571afd99127f071a parent 9818f3c

8 files changed

.opencode/commands/zoea-known-issues.md+2−3
@@ -1,7 +1,6 @@
11 ---
22 description: Investigate the first item in the known issues document.
3-agent: zoea-analyser
4-model: opencode/gpt-5.2-codex
3+agent: plan
54 ---
65
76 Instructions:
@@ -9,7 +8,7 @@ Instructions:
98 Read `documentation/KNOWN_ISSUES.md` and:
109
1110 - Remove completed items first. If no items remain stop, and report back. Update KNOWN_ISSUES.md to reflect that no isses exist.
12-- Then investigate the first item. Create a plan and a todo list for the fixes and tests required to verify the changes.
11+- Then investigate the first item. Gather information first. Then create a plan and a todo list for the fixes and tests required to verify the changes.
1312
1413 **IMPORTANT**:
1514
AGENTS.md+9−0
@@ -21,6 +21,15 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
2121 - No "nice to haves." This is an MVP. Keep scope minimal. MVP is not an escuse for lack of testing or code quality.
2222 - Keep track of known issues in `documentation/KNOWN_ISSUES.md` and ensure the list is up-do-date and correct.
2323 - Not duplicate information between README.md and AGENTS.md files. Use AGENTS for technical information, and README for user facing information. Keep README minimal and concise.
24+- Follow the versioning rules. See bellow
25+
26+## Versions
27+
28+Version format: `<UI>.<DB>.<MINOR>`
29+Release tags: annotated git tags named `v<UI>.<DB>.<MINOR>` (example: `v1.4.12`).
30+UI changes: increment the first number.
31+DB schema changes: increment the middle number and require a fresh database.
32+MINOR changes: increment on every commit.
2433
2534 ## TUI Testing:
2635
documentation/INITIAL_IMPLEMENTATION_DESIGN.md+2−1
@@ -83,7 +83,7 @@ upstream = "https://game.spacemolt.com/mcp"
8383 - **Migrations:** Schema managed via embedded SQL migrations (e.g., `golang-migrate` or manual versioning). Never support backwards, never write data migrations. If we change the schema we create a new db fresh.
8484 - **Backup:** Consider periodic WAL checkpoints; SQLite handles crash recovery.
8585
86-### Database Schema (v3)
86+### Database Schema (v5)
8787
8888 ```sql
8989 -- Myses table
@@ -104,6 +104,7 @@ CREATE TABLE memories (
104104 role TEXT NOT NULL, -- system, user, assistant, tool
105105 source TEXT NOT NULL, -- direct, broadcast, system, llm, tool
106106 content TEXT NOT NULL,
107+ reasoning TEXT,
107108 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
108109 FOREIGN KEY (mysis_id) REFERENCES myses(id) ON DELETE CASCADE
109110 );
documentation/KNOWN_ISSUES.md+20−6
@@ -2,20 +2,34 @@
22
33 These are the currently know issues to investigate:
44
5-- [x] Mysis terminology: Agent is too generic of a name for the swarm members.
6- **FIXED**: Swarm members are now referred to as "Mysis" (singular) and "Myses" (plural) in documentation.
5+- [ ] Myses have trouble login in, and mostly resort to new accoutns. We need to create a new table for username/password pairs available to the swarm, and which ones are in use or not. the introduce a new zoea tool to getch this data. Revise the prompt to ensure we encorage re-using swarm acounts first, and only create new ones as a fallback. If a mysis attempts to login to an active account, provide an directive response "use these available details" or "register a new one"
76
8-- [ ] Opencode Zen as a provider: This is completly untested. Compile a list of the free models, and create a report in `documentation` named `OPENCODE_ZEN_MODELS.md`. Only use free models in your report.
9- **BUG**: each individual Mysis should be able to be configured with different provider/model choice. Currently all use the same model and provider. Keep a sensible default in `config.toml`. We need to also add per model temperature values.
7+- [ ] Myses should know to prefer more recent information in their context. We should improve our context messages list to compact repeated state updates into the most recent state snapshot. We should also re-enforce the use of search tools to access older memory. Maybe increase the tool loop for longer autonomy.
8+
9+- [ ] Mysis prompt review: Encorage myses to collaborate together via zoea tooling and create a goal and colaborate towards it. Encourage to pick a Crustacian Cosmos + Zoea/Mysis themed username. Critical rules must be in every prompt, not only the first one.
1010
1111 - [ ] Captain's Log Bug: There is a consistent pattern of Myses failing to use captains_log_add. They appear to be trying to "remember" their registration password but are encountering an empty_entry error from the MCP server. This suggests the LLM might be misformatting the arguments for this specific tool.
1212 **BUG**: Myses find each other's passwords and fail to login. Myses do not have a reliable way to re-use usernames they created in the past.
1313
1414 - [ ] Travel Duration: The travel to the asteroid belt is a long-duration task (30k+ ticks). The Myses correctly entered a "waiting" mode, showing they can manage long-term state without wasting tokens on redundant actions.
15- **BUG**: Mysis should continue to act on his tick during travel. They can still use other actions when traveling. Like chatting, or other non traveling actions in the game. Currently the Mysis looses his ticks waiting when he could be using the turns to explore the game api and interacting with the swarm. Add a `zoea_get_passwords()` tool call that lists password<>username pairs for the swarm. (searches swarm messags for the passwords), Myses should not see passwords for accounts actively …
15+ **BUG**: Mysis should continue to act on his tick during travel. They can still use other actions when traveling. Like chatting, or other non traveling actions in the game. Currently the Mysis looses his ticks waiting when he could be using the turns to explore the game api and interacting with the swarm.
1616
1717 - [ ] TUI usability issues: Swarm messages list isnot kept up to date. Sending a broadcast doesn't update the list of swarm messages.
18- **BUG**: Breaking change from the spec, the TUI should be high performance and in sync with the data at all times.
18+ **BUG**: Breaking change from the spec, the TUI should be high performance and in sync with the data at all times. When a message is sent by the commander, we need a "sending message state" with animation until the commander can send a new message. Stay consistent with zoea theme. check documentation for design rules.
19+
20+- [ ] Broadcast messages are labelled YOU in focus view. We don't differentiate between swam broadcast senders. We need to start tracking it and reflecting it in the UI, in a consistent formatting and style acording to our thematic and design rules (see the documentation before doing changes)
21+
22+- [ ] Reasoning messages are not displayed in the UI. They should appear in the focus mysis view, and be rendered with the purple color we use for text else where.
23+
24+- [ ] The project shouldn't use emojis at all. Replace emoji usage with unicode accross all files in the project.
1925
2026 - [ ] Cognitive Looping and Prompt Inefficiency: Myses can get stuck in "cooldown" loops or redundant "waiting" states, consuming tokens every 30 seconds without operational progress.
2127 **BUG**: The system prompts Myses every tick regardless of their state. Myses may hallucinate non-existent cooldowns or fail to use non-traveling actions during long journeys.
28+
29+## Notes:
30+
31+I need to remmeber this to make a workflow command later:
32+
33+```
34+Follow the plan, create todo list first. Stop if the anything deviates from the plan.
35+```
documentation/OPENCODE_ZEN_MODELS.md+31−0
@@ -0,0 +1,31 @@
1+# OpenCode Zen Models
2+
3+Models available through OpenCode Zen for use with Zoea Nova.
4+
5+## Free Models
6+
7+These models are free during their beta period:
8+
9+| Model | Model ID | Endpoint | Tool Support |
10+| --- | --- | --- | --- |
11+| GLM 4.7 Free | `glm-4.7-free` | `/v1/chat/completions` | Yes |
12+| Kimi K2.5 Free | `kimi-k2.5-free` | `/v1/chat/completions` | Yes |
13+| MiniMax M2.1 Free | `minimax-m2.1-free` | `/v1/messages` | Yes |
14+| Big Pickle | `big-pickle` | `/v1/chat/completions` | Yes |
15+| GPT 5 Nano | `gpt-5-nano` | `/v1/responses` | Yes |
16+
17+## Configuration
18+
19+```toml
20+[providers.opencode_zen]
21+endpoint = "https://api.opencode.ai/v1"
22+model = "glm-4.7-free"
23+temperature = 0.7
24+```
25+
26+Credentials are stored in `~/.zoea-nova/credentials.json`.
27+
28+## References
29+
30+- [OpenCode Zen Documentation](https://opencode.ai/docs/zen/)
31+- [Model List API](https://opencode.ai/zen/v1/models)
documentation/PER_MYSIS_CONFIG_PLAN.md+505−0
@@ -0,0 +1,505 @@
1+# Per-Mysis Configuration Implementation Plan
2+
3+**Date:** 2026-02-04
4+**Status:** Ready for implementation
5+
6+## Goal
7+
8+Enable per-mysis provider/model/temperature configuration and document OpenCode Zen free models.
9+
10+## Architecture
11+
12+The current singleton provider pattern will be replaced with a factory pattern. Each mysis will own a dedicated provider instance configured with its stored model and temperature. Config defines defaults; database stores per-mysis overrides.
13+
14+## Tech Stack
15+
16+Go 1.22+, SQLite (modernc.org/sqlite), go-openai, BurntSushi/toml
17+
18+---
19+
20+## Phase 1: Documentation
21+
22+**Files:**
23+- Create: `documentation/OPENCODE_ZEN_MODELS.md`
24+
25+**Content:**
26+```markdown
27+# OpenCode Zen Models
28+
29+Models available through OpenCode Zen for use with Zoea Nova.
30+
31+## Free Models
32+
33+These models are free during their beta period:
34+
35+| Model | Model ID | Endpoint | Tool Support |
36+|-------|----------|----------|--------------|
37+| GLM 4.7 Free | `glm-4.7-free` | `/v1/chat/completions` | Yes |
38+| Kimi K2.5 Free | `kimi-k2.5-free` | `/v1/chat/completions` | Yes |
39+| MiniMax M2.1 Free | `minimax-m2.1-free` | `/v1/messages` | Yes |
40+| Big Pickle | `big-pickle` | `/v1/chat/completions` | Yes |
41+| GPT 5 Nano | `gpt-5-nano` | `/v1/responses` | Yes |
42+
43+## Configuration
44+
45+```toml
46+[providers.opencode_zen]
47+endpoint = "https://api.opencode.ai/v1"
48+model = "glm-4.7-free"
49+temperature = 0.7
50+```
51+
52+Credentials are stored in `~/.zoea-nova/credentials.json`.
53+
54+## References
55+
56+- [OpenCode Zen Documentation](https://opencode.ai/docs/zen/)
57+- [Model List API](https://opencode.ai/zen/v1/models)
58+```
59+
60+---
61+
62+## Phase 2: Config Changes
63+
64+**Files:**
65+- Modify: `internal/config/config.go`
66+- Modify: `config.toml`
67+
68+**Changes to `config.go`:**
69+
70+```go
71+// ProviderConfig holds LLM provider settings.
72+type ProviderConfig struct {
73+ Endpoint string `toml:"endpoint"`
74+ Model string `toml:"model"`
75+ Temperature float64 `toml:"temperature"`
76+}
77+
78+// In DefaultConfig():
79+Providers: map[string]ProviderConfig{
80+ "ollama": {
81+ Endpoint: "http://localhost:11434",
82+ Model: "llama3",
83+ Temperature: 0.7,
84+ },
85+},
86+
87+// In applyEnvOverrides():
88+if v := os.Getenv("ZOEA_OLLAMA_TEMPERATURE"); v != "" {
89+ if f, err := strconv.ParseFloat(v, 64); err == nil {
90+ if p, ok := cfg.Providers["ollama"]; ok {
91+ p.Temperature = f
92+ cfg.Providers["ollama"] = p
93+ }
94+ }
95+}
96+
97+if v := os.Getenv("ZOEA_OPENCODE_TEMPERATURE"); v != "" {
98+ if f, err := strconv.ParseFloat(v, 64); err == nil {
99+ if p, ok := cfg.Providers["opencode_zen"]; ok {
100+ p.Temperature = f
101+ cfg.Providers["opencode_zen"] = p
102+ }
103+ }
104+}
105+```
106+
107+**Changes to `config.toml`:**
108+
109+```toml
110+[providers.ollama]
111+endpoint = "http://localhost:11434"
112+model = "qwen3:4b"
113+temperature = 0.7
114+
115+[providers.opencode_zen]
116+endpoint = "https://api.opencode.ai/v1"
117+model = "glm-4.7-free"
118+temperature = 0.7
119+```
120+
121+---
122+
123+## Phase 3: Store Changes
124+
125+**Files:**
126+- Modify: `internal/store/schema.sql`
127+- Modify: `internal/store/myses.go`
128+
129+**Changes to `schema.sql`:**
130+
131+```sql
132+INSERT OR REPLACE INTO schema_version (version) VALUES (4);
133+
134+CREATE TABLE IF NOT EXISTS myses (
135+ id TEXT PRIMARY KEY,
136+ name TEXT NOT NULL,
137+ provider TEXT NOT NULL,
138+ model TEXT NOT NULL,
139+ temperature REAL NOT NULL DEFAULT 0.7,
140+ state TEXT NOT NULL DEFAULT 'idle',
141+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
142+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
143+);
144+```
145+
146+**Changes to `myses.go`:**
147+
148+```go
149+// Mysis struct
150+type Mysis struct {
151+ ID string
152+ Name string
153+ Provider string
154+ Model string
155+ Temperature float64
156+ State MysisState
157+ CreatedAt time.Time
158+ UpdatedAt time.Time
159+}
160+
161+// CreateMysis signature
162+func (s *Store) CreateMysis(name, provider, model string, temperature float64) (*Mysis, error)
163+
164+// UpdateMysisConfig signature
165+func (s *Store) UpdateMysisConfig(id, provider, model string, temperature float64) error
166+
167+// Scan functions updated to include temperature
168+```
169+
170+---
171+
172+## Phase 4: Provider Changes
173+
174+**Files:**
175+- Modify: `internal/provider/ollama.go`
176+- Modify: `internal/provider/opencode.go`
177+- Modify: `internal/provider/provider.go`
178+- Create: `internal/provider/factory.go`
179+- Modify: `internal/provider/mock.go`
180+
181+**Changes to `provider.go`:**
182+
183+```go
184+// ProviderFactory creates provider instances with specific configurations.
185+type ProviderFactory interface {
186+ Name() string
187+ Create(model string, temperature float64) Provider
188+}
189+
190+// Registry holds provider factories.
191+type Registry struct {
192+ factories map[string]ProviderFactory
193+}
194+
195+func (r *Registry) RegisterFactory(f ProviderFactory) {
196+ r.factories[f.Name()] = f
197+}
198+
199+func (r *Registry) Create(name, model string, temperature float64) (Provider, error) {
200+ f, ok := r.factories[name]
201+ if !ok {
202+ return nil, ErrProviderNotFound
203+ }
204+ return f.Create(model, temperature), nil
205+}
206+```
207+
208+**New `factory.go`:**
209+
210+```go
211+package provider
212+
213+// OllamaFactory creates Ollama providers.
214+type OllamaFactory struct {
215+ endpoint string
216+}
217+
218+func NewOllamaFactory(endpoint string) *OllamaFactory {
219+ return &OllamaFactory{endpoint: endpoint}
220+}
221+
222+func (f *OllamaFactory) Name() string { return "ollama" }
223+
224+func (f *OllamaFactory) Create(model string, temperature float64) Provider {
225+ return NewOllamaWithTemp(f.endpoint, model, temperature)
226+}
227+
228+// OpenCodeFactory creates OpenCode Zen providers.
229+type OpenCodeFactory struct {
230+ endpoint string
231+ apiKey string
232+}
233+
234+func NewOpenCodeFactory(endpoint, apiKey string) *OpenCodeFactory {
235+ return &OpenCodeFactory{endpoint: endpoint, apiKey: apiKey}
236+}
237+
238+func (f *OpenCodeFactory) Name() string { return "opencode_zen" }
239+
240+func (f *OpenCodeFactory) Create(model string, temperature float64) Provider {
241+ return NewOpenCodeWithTemp(f.endpoint, model, f.apiKey, temperature)
242+}
243+```
244+
245+**Changes to `ollama.go`:**
246+
247+```go
248+type OllamaProvider struct {
249+ client *openai.Client
250+ model string
251+ temperature float64
252+}
253+
254+func NewOllamaWithTemp(endpoint, model string, temperature float64) *OllamaProvider {
255+ config := openai.DefaultConfig("")
256+ config.BaseURL = endpoint + "/v1"
257+ return &OllamaProvider{
258+ client: openai.NewClientWithConfig(config),
259+ model: model,
260+ temperature: temperature,
261+ }
262+}
263+
264+// In Chat/ChatWithTools, add Temperature to request:
265+resp, err := p.client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
266+ Model: p.model,
267+ Messages: toOpenAIMessages(messages),
268+ Temperature: float32(p.temperature),
269+})
270+```
271+
272+**Changes to `opencode.go`:**
273+
274+Similar temperature field and usage as ollama.go.
275+
276+---
277+
278+## Phase 5: Commander Changes
279+
280+**Files:**
281+- Modify: `internal/core/commander.go`
282+
283+**Key changes:**
284+
285+```go
286+// Commander now uses factory pattern
287+type Commander struct {
288+ // ... existing fields
289+ registry *provider.Registry // Now holds factories
290+}
291+
292+// CreateMysis creates provider using factory
293+func (c *Commander) CreateMysis(name, providerName string) (*Mysis, error) {
294+ provCfg := c.config.Providers[providerName]
295+
296+ // Create provider instance for this mysis
297+ p, err := c.registry.Create(providerName, provCfg.Model, provCfg.Temperature)
298+ if err != nil {
299+ return nil, err
300+ }
301+
302+ // Store with model and temperature
303+ stored, err := c.store.CreateMysis(name, providerName, provCfg.Model, provCfg.Temperature)
304+ // ...
305+}
306+
307+// ConfigureMysis now accepts model parameter
308+func (c *Commander) ConfigureMysis(id, providerName, model string) error {
309+ provCfg := c.config.Providers[providerName]
310+ temperature := provCfg.Temperature
311+
312+ // Create new provider with specified model
313+ p, err := c.registry.Create(providerName, model, temperature)
314+ // ...
315+
316+ c.store.UpdateMysisConfig(id, providerName, model, temperature)
317+ mysis.SetProvider(p)
318+}
319+
320+// LoadMyses creates providers from stored config
321+func (c *Commander) LoadMyses() error {
322+ for _, sm := range stored {
323+ p, err := c.registry.Create(sm.Provider, sm.Model, sm.Temperature)
324+ // ...
325+ }
326+}
327+```
328+
329+---
330+
331+## Phase 6: TUI Changes
332+
333+**Files:**
334+- Modify: `internal/tui/input.go`
335+- Modify: `internal/tui/app.go`
336+
337+**Changes to `input.go`:**
338+
339+```go
340+const (
341+ InputModeNone InputMode = iota
342+ InputModeBroadcast
343+ InputModeMessage
344+ InputModeNewMysis
345+ InputModeConfigProvider
346+ InputModeConfigModel // NEW
347+)
348+
349+// In SetMode():
350+case InputModeConfigModel:
351+ m.textInput.Placeholder = "Enter model name..."
352+ m.textInput.Prompt = inputPromptStyle.Render("🔧 ") + " "
353+```
354+
355+**Changes to `app.go`:**
356+
357+```go
358+// Add field to track pending provider during config flow
359+type Model struct {
360+ // ... existing fields
361+ pendingProvider string // Temporary storage during config flow
362+}
363+
364+// In handleInputKey, case InputModeConfigProvider:
365+case InputModeConfigProvider:
366+ // Validate provider exists
367+ if value != "ollama" && value != "opencode_zen" {
368+ m.err = fmt.Errorf("unknown provider: %s", value)
369+ m.input.Reset()
370+ return m, nil
371+ }
372+ // Store provider and prompt for model
373+ m.pendingProvider = value
374+ m.input.SetMode(InputModeConfigModel, m.input.TargetID())
375+ return m, m.input.Focus()
376+
377+case InputModeConfigModel:
378+ m.err = m.commander.ConfigureMysis(m.input.TargetID(), m.pendingProvider, value)
379+ m.pendingProvider = ""
380+```
381+
382+---
383+
384+## Phase 7: Main.go Changes
385+
386+**Files:**
387+- Modify: `cmd/zoea/main.go`
388+
389+**Changes:**
390+
391+```go
392+func initProviders(cfg *config.Config, creds *config.Credentials) *provider.Registry {
393+ registry := provider.NewRegistry()
394+
395+ // Register Ollama factory
396+ if ollCfg, ok := cfg.Providers["ollama"]; ok {
397+ factory := provider.NewOllamaFactory(ollCfg.Endpoint)
398+ registry.RegisterFactory(factory)
399+ }
400+
401+ // Register OpenCode Zen factory
402+ if zenCfg, ok := cfg.Providers["opencode_zen"]; ok {
403+ apiKey := creds.GetAPIKey("opencode_zen")
404+ if apiKey != "" {
405+ factory := provider.NewOpenCodeFactory(zenCfg.Endpoint, apiKey)
406+ registry.RegisterFactory(factory)
407+ }
408+ }
409+
410+ return registry
411+}
412+```
413+
414+---
415+
416+## Phase 8: Tests
417+
418+**Files:**
419+- Modify: `internal/config/config_test.go`
420+- Modify: `internal/store/store_test.go`
421+- Modify: `internal/core/commander_test.go`
422+
423+**Test additions:**
424+
425+```go
426+// config_test.go
427+func TestLoadWithTemperature(t *testing.T) {
428+ content := `
429+[providers.ollama]
430+endpoint = "http://localhost:11434"
431+model = "qwen3:4b"
432+temperature = 0.5
433+`
434+ // ... verify temperature is parsed
435+}
436+
437+// store_test.go
438+func TestMysisCRUDWithTemperature(t *testing.T) {
439+ mysis, err := s.CreateMysis("test", "ollama", "llama3", 0.5)
440+ // ... verify temperature is stored and retrieved
441+}
442+
443+// commander_test.go
444+func TestCommanderConfigureMysisWithModel(t *testing.T) {
445+ // ... verify model can be changed per-mysis
446+}
447+```
448+
449+---
450+
451+## Phase 9: Verification
452+
453+1. Run `make test` - all tests must pass
454+2. Run `make build` - compilation must succeed
455+3. Manual test: create mysis, configure with different model, verify provider uses correct model
456+4. Update `KNOWN_ISSUES.md` to mark first item complete
457+
458+---
459+
460+## Summary of Files Changed
461+
462+| File | Action |
463+|------|--------|
464+| `documentation/OPENCODE_ZEN_MODELS.md` | Create |
465+| `internal/config/config.go` | Modify |
466+| `internal/config/config_test.go` | Modify |
467+| `config.toml` | Modify |
468+| `internal/store/schema.sql` | Modify |
469+| `internal/store/myses.go` | Modify |
470+| `internal/store/store_test.go` | Modify |
471+| `internal/provider/provider.go` | Modify |
472+| `internal/provider/factory.go` | Create |
473+| `internal/provider/ollama.go` | Modify |
474+| `internal/provider/opencode.go` | Modify |
475+| `internal/provider/mock.go` | Modify |
476+| `internal/core/commander.go` | Modify |
477+| `internal/core/commander_test.go` | Modify |
478+| `internal/tui/input.go` | Modify |
479+| `internal/tui/app.go` | Modify |
480+| `cmd/zoea/main.go` | Modify |
481+| `documentation/KNOWN_ISSUES.md` | Modify |
482+
483+---
484+
485+## Database Migration Note
486+
487+This change requires schema v4 with a new `temperature` column. Per AGENTS.md, no data migrations are supported. Users must wipe their database:
488+
489+```bash
490+rm ~/.zoea-nova/zoea.db*
491+```
492+
493+---
494+
495+## Implementation Order
496+
497+1. Documentation (OpenCode Zen models)
498+2. Config layer (add temperature field)
499+3. Store layer (schema + CRUD)
500+4. Provider layer (factory pattern)
501+5. Commander layer (use factories)
502+6. TUI layer (model selection)
503+7. Main.go (register factories)
504+8. Tests (verify all layers)
505+9. Verification (build + manual test)
documentation/RATE_LIMITING_PLAN.md+116−0
@@ -0,0 +1,116 @@
1+# Provider Rate Limiting Plan
2+
3+## Goal
4+
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.
6+
7+## Research Findings
8+
9+### Ollama (local)
10+
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.
14+
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`:
43+
44+```toml
45+[providers.ollama]
46+endpoint = "http://localhost:11434"
47+model = "qwen3:4b"
48+temperature = 0.7
49+rate_limit = 2.0
50+rate_burst = 3
51+
52+[providers.opencode_zen]
53+endpoint = "https://api.opencode.ai/v1"
54+model = "glm-4.7-free"
55+temperature = 0.7
56+rate_limit = 10.0
57+rate_burst = 5
58+```
59+
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
64+
65+## Implementation Steps
66+
67+### Phase 1: Config Layer
68+
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`
111+
112+## Verification
113+
114+1. `make test`
115+2. `make build`
116+3. Manual test: start two myses on the same provider, send rapid messages, observe throttling
internal/tui/tui_test.go+4−2
@@ -13,6 +13,7 @@ import (
1313 "github.com/xonecas/zoea-nova/internal/core"
1414 "github.com/xonecas/zoea-nova/internal/provider"
1515 "github.com/xonecas/zoea-nova/internal/store"
16+ "golang.org/x/time/rate"
1617 )
1718
1819 // ansiRegex matches ANSI escape codes
@@ -35,14 +36,15 @@ func setupTestModel(t *testing.T) (Model, func()) {
3536 eventCh := bus.Subscribe()
3637
3738 reg := provider.NewRegistry()
38- reg.Register(provider.NewMock("ollama", "mock response"))
39+ limiter := rate.NewLimiter(rate.Limit(1000), 1000)
40+ reg.RegisterFactory(provider.NewMockFactoryWithLimiter("ollama", "mock response", limiter))
3941
4042 cfg := &config.Config{
4143 Swarm: config.SwarmConfig{
4244 MaxMyses: 16,
4345 },
4446 Providers: map[string]config.ProviderConfig{
45- "ollama": {Endpoint: "http://mock", Model: "mock-model"},
47+ "ollama": {Endpoint: "http://mock", Model: "mock-model", Temperature: 0.7, RateLimit: 1000, RateBurst: 1000},
4648 },
4749 }