owlen/AGENTS.md

AGENTS.md — Owlen v0.2 Execution Plan

Focus: Ollama (local) ✅, Ollama Cloud (with API key) ✅, context/limits UI ✅, seamless web-search tool ✅ Style: Medium-sized conventional commits, each with acceptance criteria & test notes. Definition of Done (DoD):

• Local Ollama works out-of-the-box (no key required).
• Ollama Cloud is available only when an API key is present; no more 401 loops; clear fallback to local.
• Chat header shows context used / context window and %.
• Cloud usage shows hourly / weekly token usage (tracked locally; limits configurable).
• “Internet?” → the model/tooling performs web search automatically; no “I can’t access the internet” replies.

---

Release Assumptions

• Provider config has separate entries for local (“ollama”) and cloud (“ollama-cloud”), both optional.
• Cloud base URL is config-driven (default [Inference] https://api.ollama.com), local default http://localhost:11434.
• Cloud requests include Authorization: Bearer <API_KEY>.
• Token counts (prompt_eval_count, eval_count) are read from provider responses if available; else fallback to local estimation.
• Rate-limit quotas unknown → user-configurable (hourly_quota_tokens, weekly_quota_tokens); we still track actual usage.

---

Commit Plan (Conventional Commits)

1) feat(provider/ollama): health checks, resilient model listing, friendly errors

• Why: Local should “just work”; no brittle failures if model not pulled or daemon is down.

• Implement:

  • GET /api/tags with timeout & retry; on failure → user-friendly banner (“Ollama not reachable on localhost:11434”).
  • If chat hits “model not found” → suggest ollama pull <model> (do not auto-pull).
  • Pre-chat healthcheck endpoint with short timeout.

• AC: With no Ollama, UI shows actionable error, app stays usable. With Ollama up, models list renders within TTL.

• Tests: Mock 200/500/timeout; simulate missing model.

2) feat(provider/ollama-cloud): separate provider with auth header & key-gating

• Why: Prevent 401s; enable cloud only when key is present.

• Implement:

  • New provider “ollama-cloud”.
  • Build reqwest::Client with default headers incl. Authorization: Bearer <API_KEY>.
  • Base URL from config (default [Inference] https://api.ollama.com).
  • If no key: provider not registered; cloud models hidden.

• AC: With key → cloud models list & chat work; without key → no cloud provider listed.

• Tests: No key (hidden), invalid key (401 handled), valid key (happy path).

3) fix(provider/ollama-cloud): handle 401/429 gracefully, auto-degrade

• Why: Avoid dead UX where cloud is selectable but unusable.

• Implement:

  • Intercept 401/403 → mark provider “unauthorized”, show toast “Cloud key invalid; using local”.
  • Intercept 429 → toast “Cloud rate limit hit; retry later”; keep provider enabled.
  • Auto-fallback to last good local provider for the active chat (don’t lose message).

• AC: Selecting cloud with bad key never traps the user; one click recovers to local.

• Tests: Simulated 401/429 mid-stream & at start.

4) feat(models/registry): multi-provider registry + aggregated model list

• Why: Show local & cloud side-by-side, clearly labeled.

• Implement:

  • Registry holds N providers (local, cloud).
  • Aggregate lists with provider_tag = ollama / ollama-cloud.
  • De-dupe identical names by appending provider tag in UI (“qwen3:8b · local”, “qwen3:8b-cloud · cloud”).

• AC: Model picker groups by provider; switching respects selection.

• Tests: Only local; only cloud; both; de-dup checks.

5) refactor(session): message pipeline to support tool-calls & partial updates

• Why: Prepare for search tool loop and robust streaming.

• Implement:

  • Centralize stream parser → yields either assistant_text chunks or tool_call messages.
  • Buffer + flush on done or on explicit tool boundary.

• AC: No regressions in normal chat; tool call boundary events visible to controller.

• Tests: Stream with mixed content, malformed frames, newline-split JSON.

6) fix(streaming): tolerant JSON lines parser & end-of-stream semantics

• Why: Avoid UI stalls on minor protocol hiccups.

• Implement:

  • Accept \n/\r\n delimiters; ignore empty lines; robust done: true handling; final metrics extraction.

• AC: Long completions never hang; final token counts captured.

• Tests: Fuzz malformed frames.

7) feat(ui/header): context usage indicator (value + %), colorized thresholds

• Why: Transparency: “2560 / 8192 (31%)”.

• Implement:

  • Track last prompt_eval_count (or estimate) as “context used”.
  • Context window: from model metadata (if available) else config default per provider/model family.
  • Header shows: Model · Context 2.6k / 8k (33%). Colors: <60% normal, 60–85% warn, >85% danger.

• AC: Live updates after each assistant turn.

• Tests: Various windows & counts; edge 0%/100%.

8) feat(usage): token usage tracker (hourly/weekly), local store

• Why: Cloud limits visibility even without official API.

• Implement:

  • Append per-provider token use after each response: prompt+completion.
  • Rolling sums: last 60m, last 7d.
  • Persist to JSON/SQLite in app data dir; prune daily.
  • Configurable quotas: providers.ollama_cloud.hourly_quota_tokens, weekly_quota_tokens.

• AC: :limits shows totals & percentages; survives restart.

• Tests: Time-travel tests; persistence.

9) feat(ui/usage): surface hourly/weekly usage + threshold toasts

• Why: Prevent surprises; act before you hit the wall.

• Implement:

  • Header second line (when cloud active): Cloud usage · 12k/50k (hour) · 90k/250k (week) with % colors.
  • Toast at 80% & 95% thresholds.

• AC: Visuals match tracker; toasts fire once per threshold band.

• Tests: Threshold crossings; reset behavior.

10) feat(tools): generic tool-calling loop (function-call adapter)

• Why: “Use the web” without whining.

• Implement:

  • Internal tool schema: { name, parameters(JSONSchema), invoke(args)->ToolResult }.
  • Provider adapter: if model emits a tool call → pause stream, invoke tool, append tool message, resume.
  • Guardrails: max tool hops (e.g., 3), max tokens per hop.

• AC: Model can call tools mid-answer; transcript shows tool result context to model (not necessarily to user).

• Tests: Single & chained tool calls; loop cutoff.

11) feat(tool/web.search): HTTP search wrapper for cloud mode; fallback stub

• Why: Default “internet” capability.

• Implement:

  • Tool name: web.search with params { query: string }.
  • Cloud path: call provider’s search endpoint (configurable path); include API key.
  • Fallback (no cloud): disabled; model will not see the tool (prevents “I can’t” messaging).

• AC: Asking “what happened today in Rust X?” triggers one search call and integrates snippets into the answer.

• Tests: Happy path, 401/key missing (tool hidden), network failure (tool error surfaced to model).

12) feat(commands): :provider, :model, :limits, :web on|off

• Why: Fast control for power users.

• Implement:

  • :provider lists/switches active provider.
  • :model lists/switches models under active provider.
  • :limits shows tracked usage.
  • :web on|off toggles exposing web.search to the model.

• AC: Commands work in both TUI and CLI modes.

• Tests: Command parsing & side-effects.

13) feat(config): explicit sections & env fallbacks

• Why: Clear separation + easy secrets management.

• Implement (example):

  [providers.ollama]
  base_url = "http://localhost:11434"
  list_ttl_secs = 60
  default_context_window = 8192
  
  [providers.ollama_cloud]
  enabled = true
  base_url = "https://api.ollama.com"        # [Inference] default
  api_key = ""                                # read from env OLLEN_OLLAMA_CLOUD_API_KEY if empty
  hourly_quota_tokens = 50000                 # configurable; visual only
  weekly_quota_tokens = 250000                # configurable; visual only
  list_ttl_secs = 60
  

• AC: Empty key → cloud disabled; env overrides work.

• Tests: Env vs file precedence.

14) docs(readme): setup & troubleshooting for local + cloud

• Why: Reduce support pings.

• Include:

  • Local prerequisites; healthcheck tips; “model not found” guidance.
  • Cloud key setup; common 401/429 causes; privacy note.
  • Context/limits UI explainer; tool behavior & toggles.
  • Upgrade notes from v0.1 → v0.2.

• AC: New users can configure both in <5 min.

15) test(integration): local-only, cloud-only, mixed; auth & rate-limit sims

• Why: Prevent regressions.

• Implement:

  • Wiremock stubs for cloud: /tags, /chat, search endpoint, 401/429 cases.
  • Snapshot test for tool-call transcript roundtrip.

• AC: Green suite in CI; reproducible.

16) refactor(errors): typed provider errors + UI toasts

• Why: Replace generic “something broke”.
• Implement: Error enum: Unavailable, Unauthorized, RateLimited, Timeout, Protocol. Map to toasts/banners.
• AC: Each known failure surfaces a precise message; logs redact secrets.

17) perf(models): cache model lists with TTL; invalidate on user action

• Why: Reduce network churn.
• AC: Re-open picker doesn’t re-fetch until TTL or manual refresh.

18) chore(release): bump to v0.2; changelog; package metadata

• AC: --version shows v0.2; changelog includes above bullets.

---

Missing Features vs. Codex / Claude-Code (Queued for v0.3+)

• Multi-vendor providers: OpenAI & Anthropic provider crates with function-calling parity and structured outputs.
• Agentic coding ops: Safe file edits, git ops, shell exec with approval queue.
• “Thinking/Plan” pane: First-class rendering of plan/reflect steps; optional auto-approve.
• Plugin system: Tool discovery & permissions; marketplace later.
• IDE integration: Minimal LSP/bridge (VS Code/JetBrains) to run Owlen as backend.
• Retrieval/RAG: Local project indexing; selective context injection with token budgeter.

---

Acceptance Checklist (Release Gate)

• Local Ollama: healthcheck OK, models list OK, chat OK.
• Cloud appears only with valid key; no 401 loops; 429 shows toast.
• Header shows context value and %; updates after each turn.
• :limits shows hourly/weekly tallies; persists across restarts.
• Asking for current info triggers web.search (cloud on) and returns an answer without “I can’t access the internet”.
• Docs updated; sample config included; tests green.

---

Notes & Caveats

• Base URLs & endpoints: Kept config-driven. Defaults are [Inference]. If your cloud endpoint differs, set it in config.toml.
• Quotas: No official token quota API assumed; we track locally and let you configure limits for UI display.
• Tooling: If a given model doesn’t emit tool calls, web.search won’t be visible to it. You can force exposure via :web on.

---

Lightly Opinionated Guidance (aka sparring stance)

• Don’t auto-pull models on errors—teach users where control lives.
• Keep cloud totally opt-in; hide it on misconfig to reduce paper cuts.
• Treat tool-calling like sudo: short leash, clear logs, obvious toggles.
• Make the header a cockpit, not a billboard: model · context · usage; that’s it.

If you want, I can turn this into a series of codex apply-ready prompts with one commit per run.